Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
151 changes: 151 additions & 0 deletions i18n/.pending/es/docs/development/migrations.md

Large diffs are not rendered by default.

292 changes: 292 additions & 0 deletions i18n/.pending/es/docs/features/memory/retention-and-erasure.md

Large diffs are not rendered by default.

246 changes: 246 additions & 0 deletions i18n/.pending/es/docs/operations/postgres.md

Large diffs are not rendered by default.

261 changes: 261 additions & 0 deletions i18n/.pending/ja/docs/operations/backup-and-recovery.md

Large diffs are not rendered by default.

323 changes: 323 additions & 0 deletions i18n/.pending/ja/docs/operations/monitoring.md

Large diffs are not rendered by default.

302 changes: 302 additions & 0 deletions i18n/.pending/ja/docs/reference/cli.md

Large diffs are not rendered by default.

305 changes: 305 additions & 0 deletions i18n/.pending/ko/docs/reference/cli.md

Large diffs are not rendered by default.

494 changes: 494 additions & 0 deletions i18n/.pending/pt-BR/docs/architecture/system-overview.md

Large diffs are not rendered by default.

817 changes: 817 additions & 0 deletions i18n/.pending/pt-BR/docs/operations/code-index-operations.md

Large diffs are not rendered by default.

425 changes: 425 additions & 0 deletions i18n/.pending/zh-CN/docs/concepts/memory.md

Large diffs are not rendered by default.

271 changes: 271 additions & 0 deletions i18n/.pending/zh-CN/docs/features/namespaces-and-sharing.md

Large diffs are not rendered by default.

326 changes: 326 additions & 0 deletions i18n/.pending/zh-CN/docs/features/observability/telemetry.md

Large diffs are not rendered by default.

415 changes: 415 additions & 0 deletions i18n/.pending/zh-CN/docs/features/tasks-and-decisions.md

Large diffs are not rendered by default.

323 changes: 323 additions & 0 deletions i18n/.pending/zh-CN/docs/operations/monitoring.md

Large diffs are not rendered by default.

80 changes: 80 additions & 0 deletions i18n/es/docs/getting-started/whats-included.md

Large diffs are not rendered by default.

326 changes: 326 additions & 0 deletions i18n/ja/docs/features/observability/telemetry.md

Large diffs are not rendered by default.

422 changes: 422 additions & 0 deletions i18n/ja/docs/operations/code-index-operations.md

Large diffs are not rendered by default.

354 changes: 354 additions & 0 deletions i18n/ja/docs/operations/sso.md

Large diffs are not rendered by default.

354 changes: 354 additions & 0 deletions i18n/ko/docs/architecture/cells.md

Large diffs are not rendered by default.

348 changes: 348 additions & 0 deletions i18n/ko/docs/architecture/code-index-architecture.md

Large diffs are not rendered by default.

445 changes: 445 additions & 0 deletions i18n/ko/docs/architecture/failure-and-recovery.md

Large diffs are not rendered by default.

328 changes: 328 additions & 0 deletions i18n/ko/docs/operations/monitoring.md

Large diffs are not rendered by default.

34 changes: 17 additions & 17 deletions i18n/ko/docs/use-cases/code-intelligence-by-language.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,63 +6,63 @@

# C++, Python, TypeScript, Go, Rust, Java 및 인프라 코드를 위한 코드 인텔리전스

Loom의 코드 인덱스는 저장소에 있는 언어를 가리지 않고 코딩 에이전트의 구조 관련 질문에 답합니다. 심볼이 어디에 정의되어 있는지, 누가 호출하는지, 변경이 무엇에 영향을 주는지를 알려 줍니다.
저장소를 추가하고 `LOOM_CODE_INGEST_ENABLED=true`를 설정해야 합니다. 모든 언어는 빠른 티어를 사용하며, tree-sitter 문법이나 직접 작성한 스캐너로 파싱합니다. C/C++, Python, TypeScript, Go는 컴파일러처럼 이름을 해석하는 컴파일러 티어를 추가할 수 있습니다. 전체 확장자와 엣지 목록은
Loom의 코드 인덱스는 저장소에 담긴 언어 전반에서 코딩 에이전트의 구조 관련 질문에 답합니다. 심볼이 어디에 정의되어 있는지, 누가 호출하는지, 변경이 무엇에 영향을 주는지를 알려 줍니다.
저장소가 추가되어 있어야 하며 `LOOM_CODE_INGEST_ENABLED=true`가 필요합니다. 모든 언어는 빠른 티어를 사용하며, tree-sitter 문법 또는 직접 작성한 스캐너로 파싱합니다. C/C++, Python, TypeScript, Go는 컴파일러처럼 이름을 해석하는 컴파일러 티어를 추가할 수 있습니다. 확장자와 엣지의 전체 목록은
[언어 지원 표](https://github.com/ClickHouse/loom/blob/main/docs/features/code-index/overview.md#language-support)에 있고, 컴파일러 티어 설정은
[코드 인덱스 운영](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md#compiler-tier)에 있습니다.

답변에는 그 답을 만든 티어가 표시됩니다(컴파일러 티어는 `tier: "scip"`, 빠른 티어는 `"treesitter"`). `code.coverage`는 네임스페이스가 언어별, 티어별로 무엇을 담고 있는지 보고합니다. Loom을 써 본 적 없는 언어에서 `code.callers`나 `code.impact`의 답을 신뢰하기 전에 먼저 확인하세요.
응답에는 그 근거가 된 티어가 표시되며(컴파일러 티어는 `tier: "scip"`, 빠른 티어는 `"treesitter"`), `code.coverage`는 네임스페이스가 언어별, 티어별로 무엇을 담고 있는지 보고합니다. Loom을 사용해 본 적이 없는 언어에서 `code.callers` 또는 `code.impact`의 응답을 신뢰하기 전에 먼저 확인하세요.

<a id="c-and-c"></a>

## C와 C++
## C 및 C++

심볼, 호출, include, 상속, 오버라이드는 빠른 티어에서 얻습니다. 컴파일러 티어(`scip-clang`)는 프로젝트의 빌드를 바탕으로 오버로드, 템플릿, 네임스페이스를 해석합니다. 따라서 `DB::IMergeTreeDataPart::getBytesOnDisk` 같은 정규화된 이름에 `uses_brief: true`를 지정해 `code.symbol`을 호출하면 하나의 정의, 호출 지점 수, 그리고 이를 감싸는 함수와 함께 상위 호출 지점이 반환되며, 각각 `tier: "scip"`로 표시됩니다. 컴파일러 티어에는 프로젝트의 CMake 빌드 설정이 필요합니다.
심볼, 호출, include, 상속, 오버라이드는 빠른 티어에서 가져옵니다. 컴파일러 티어(`scip-clang`)는 프로젝트의 빌드를 바탕으로 오버로드, 템플릿, 네임스페이스를 해석합니다. 따라서 `DB::IMergeTreeDataPart::getBytesOnDisk`처럼 네임스페이스나 클래스 범위로 한정된 이름에 `uses_brief: true`를 지정해 `code.symbol`을 호출하면, 하나의 정의와 호출 지점 수, 그리고 이를 감싸는 함수와 함께 상위 호출 지점이 반환되며 각각 `tier: "scip"`로 표시됩니다. 컴파일러 티어에는 프로젝트의 CMake 빌드 설정이 필요합니다.

<a id="python"></a>

## Python

호출, import, 상속, 오버라이드는 빠른 티어에서 얻으며, 노트북의 코드 셀도 포함됩니다. 컴파일러 티어(`scip-python`)는 모듈 간 이름을 해석합니다. Loom 자체 저장소에서 `writer_actor`에 `code.symbol`을 호출하면 컴파일러 티어에서 `server/memory/app/provenance.py`의 정의와 함께 시그니처와 docstring을 반환하고, `uses_brief: true`를 지정하면 호출 지점이 추가됩니다.
호출, import, 상속, 오버라이드는 빠른 티어에서 가져오며 노트북의 코드 셀도 포함됩니다. 컴파일러 티어(`scip-python`)는 모듈 간의 이름을 해석합니다. Loom 자체 저장소에서 `writer_actor`에 `code.symbol`을 호출하면 `server/memory/app/provenance.py`에 있는 정의를 시그니처와 docstring과 함께 컴파일러 티어로 반환하며, `uses_brief: true`를 지정하면 호출 지점이 추가됩니다.

<a id="typescript-and-javascript"></a>

## TypeScript와 JavaScript
## TypeScript 및 JavaScript

호출(`new` 포함), import, 상속, 오버라이드는 빠른 티어에서 얻으며, Vue, Svelte, Astro 컴포넌트의 스크립트 블록도 마찬가지입니다. Angular `.component.html` 템플릿은 해당 컴포넌트와 함께 하나의 단위로 인덱싱됩니다. 컴파일러 티어(`scip-typescript`)는 프로젝트의 `tsconfig.json`, `jsconfig.json`, `package.json`을 통해 이름을 해석합니다.
호출(`new` 포함), import, 상속, 오버라이드는 빠른 티어에서 가져오며, Vue, Svelte, Astro 컴포넌트의 스크립트 블록도 마찬가지입니다. Angular `.component.html` 템플릿은 해당 컴포넌트와 함께 하나의 단위로 인덱싱됩니다. 컴파일러 티어(`scip-typescript`)는 프로젝트의 `tsconfig.json`, `jsconfig.json` 또는 `package.json`을 통해 이름을 해석합니다.

<a id="go"></a>

## Go

호출, 인터페이스 임베딩, 구조적 구현은 빠른 티어에서 얻고, Go 문자열 안의 SQL은 테이블 참조가 됩니다. 컴파일러 티어(`scip-go`)는 모노레포를 포함해 패키지 간 이름을 해석합니다.
호출, 인터페이스 임베딩, 구조적 구현은 빠른 티어에서 가져오며, Go 문자열 안의 SQL은 테이블 참조가 됩니다. 컴파일러 티어(`scip-go`)는 모노레포를 포함해 패키지 간의 이름을 해석합니다.

<a id="rust-and-java"></a>

## Rust와 Java
## Rust 및 Java

Rust는 호출, `use` import, 트레이트 구현을 얻고, Java는 import가 이름을 바인딩하는 호출과 Java 문자열 안의 SQL을 얻습니다. 둘 다 빠른 티어만 지원합니다. 같은 파일 안에서 바인딩된 호출의 신뢰도는 1.0, 감싸는 클래스를 통한 호출은 0.8, 저장소 전체 이름 매칭은 0.6이며, 바인딩할 수 없는 호출은 추측하지 않고 제외합니다. `code.impact`는 파일 수준에서 매핑된 테스트와 함께 변경되는 파트너를 추가합니다.
Rust에서는 호출, `use` import, 트레이트 구현을 얻고, Java에서는 이름을 바인딩하는 import가 있는 호출과 Java 문자열 안의 SQL을 얻습니다. 둘 다 빠른 티어만 지원합니다. 같은 파일 안에서 바인딩된 호출의 신뢰도는 1.0, 감싸는 클래스를 통한 경우는 0.8, 저장소 전체의 이름 일치로 바인딩된 경우는 0.6이며, 바인딩할 수 없는 호출은 추측하지 않고 제외됩니다. `code.impact`는 매핑된 테스트와 함께 변경되는 파트너를 파일 수준에서 추가합니다.

<a id="sql-and-migrations"></a>

## SQL과 마이그레이션
## SQL 및 마이그레이션

`.sql` 파일은 기본적으로 검색과 grep을 위해 인덱싱됩니다. `LOOM_CODE_SQL_STATEMENT_RECORDS`를 켜면 각 구문이 테이블 참조를 포함한 레코드가 되므로, 에이전트가 어떤 마이그레이션과 쿼리가 테이블을 읽거나 쓰는지 물을 수 있습니다. 이미 인덱싱된 네임스페이스에 이 기능을 켜려면 SQL 파일에 대해 `loom code backfill --paths-file`을 실행해야 합니다
`.sql` 파일은 기본적으로 검색과 grep용으로 인덱싱됩니다. `LOOM_CODE_SQL_STATEMENT_RECORDS`를 켜면 각 구문이 테이블 참조와 함께 레코드가 되므로, 에이전트는 어떤 마이그레이션과 쿼리가 테이블을 읽거나 쓰는지 물을 수 있습니다. 이미 인덱싱된 네임스페이스에 이를 켜려면 SQL 파일에 대한 `loom code backfill --paths-file`이 필요합니다
([스위치](https://github.com/ClickHouse/loom/blob/main/docs/features/code-index/overview.md#language-support)).

<a id="infrastructure-as-code"></a>

## 코드형 인프라

Terraform과 HCL, Kubernetes 매니페스트, Helm 차트와 Go 템플릿, Jsonnet, CMake, Protocol Buffers, 셸 스크립트는 참조, include, 호출과 함께 인덱싱됩니다. 따라서 에이전트는 Helm `include`를 해당 `define`까지, Terraform 참조를 그것이 가리키는 대상까지 따라갈 수 있습니다. Dockerfile, Makefile, Jenkinsfile, CI YAML 작업은 `LOOM_CODE_HOST_ISLANDS`를 켜면 심볼이 되며, 네임스페이스가 이미 인덱싱되어 있다면 해당 파일을 backfill한 후에 적용됩니다.
Terraform과 HCL, Kubernetes 매니페스트, Helm 차트와 Go 템플릿, Jsonnet, CMake, Protocol Buffers, 셸 스크립트는 참조, include, 호출과 함께 인덱싱되므로, 에이전트는 Helm `include`를 해당 `define`으로, 또는 Terraform 참조를 그것이 가리키는 대상으로 따라갈 수 있습니다. Dockerfile, Makefile, Jenkinsfile, CI YAML 잡은 `LOOM_CODE_HOST_ISLANDS`를 켜면 심볼이 되며, 네임스페이스가 이미 인덱싱되어 있다면 해당 파일을 백필한 뒤에 적용됩니다.

<a id="start"></a>

## 시작하기

1. [저장소를 인덱싱합니다](https://github.com/ClickHouse/loom/blob/main/docs/features/code-index/repositories.md). 어떤 컴파일러 티어가 실행되는지는 [코드 인덱스 운영](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md#compiler-tier)에 있습니다.
2. `coding` 툴셋으로 [코딩 에이전트를 연결합니다](https://github.com/ClickHouse/loom/blob/main/docs/getting-started/connect-a-coding-agent.md).
3. 구조 관련 질문을 하고, 사용하는 언어에 대해 `code.coverage`를 확인합니다.
1. [저장소를 인덱싱합니다](../features/code-index/repositories.md). 어떤 컴파일러 티어가 실행되는지는 [코드 인덱스 운영](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md#compiler-tier)에 있습니다.
2. `coding` 툴셋에서 [코딩 에이전트를 연결합니다](../getting-started/connect-a-coding-agent.md).
3. 구조 관련 질문을 하고, 의존하는 언어에 대해 `code.coverage`를 확인합니다.

<a id="related"></a>

Expand Down
24 changes: 20 additions & 4 deletions scripts/i18n/lifecycle.py
Original file line number Diff line number Diff line change
Expand Up @@ -149,10 +149,24 @@ def english_fallback(link: str) -> tuple[str, str] | None:
return (source, url.fragment) if source_path(source) else None


def english_live(source: str, anchor: str, inventory: frozenset[str]) -> bool:
def english_live(
source: str,
anchor: str,
inventory: frozenset[str],
*,
_bodies: dict[str, tuple[str, str]] | None = None,
) -> bool:
if source not in inventory or not regular(source):
return False
body = "\n".join(t.english_requests((t.ROOT / source).read_text()))
# Recheck the file and its bytes per link; reuse only the derived parse within a pass.
text = (t.ROOT / source).read_text()
cached = _bodies.get(source) if _bodies is not None else None
if cached is None or cached[0] != text:
body = "\n".join(t.english_requests(text))
if _bodies is not None:
_bodies[source] = (text, body)
else:
body = cached[1]
return not anchor or f'<a id="{unquote(anchor)}"></a>' in body


Expand All @@ -162,14 +176,15 @@ def link_failures(extra: dict[str, str] | None = None) -> list[tuple[str, str, s
}
pages.update(extra or {})
inventory = frozenset(t.sources())
english_bodies: dict[str, tuple[str, str]] = {}
problems = []
for path, text in pages.items():
for match in t.prose_links(text[body_start(path, text) :]):
link, _, anchor = match[2].partition("#")
fallback = english_fallback(match[2])
if fallback:
source, fragment = fallback
if not english_live(source, fragment, inventory):
if not english_live(source, fragment, inventory, _bodies=english_bodies):
problems.append(
(
path,
Expand Down Expand Up @@ -200,6 +215,7 @@ def link_failures(extra: dict[str, str] | None = None) -> list[tuple[str, str, s
def repair_english_fallbacks(codes: list[str] | None = None) -> None:
"""Keep deleted English body links on an owned published target that retains the anchor."""
inventory = frozenset(t.sources())
english_bodies: dict[str, tuple[str, str]] = {}
for path in output_files():
if not regular(path):
continue
Expand All @@ -212,7 +228,7 @@ def repair_english_fallbacks(codes: list[str] | None = None) -> None:
def fix(prose: str, path: str = path, language: str = owned[1].code) -> str:
def replace(match: re.Match[str]) -> str:
fallback = english_fallback(match[2])
if not fallback or english_live(*fallback, inventory):
if not fallback or english_live(*fallback, inventory, _bodies=english_bodies):
return match[0]
source, anchor = fallback
target = t.target_path(language, source)
Expand Down
121 changes: 121 additions & 0 deletions tests/unit/test_i18n_lifecycle.py
Original file line number Diff line number Diff line change
Expand Up @@ -917,3 +917,124 @@ def test_composed_lifecycle_stages_native_table_rows_without_changing_body(
assert lc.candidate_problems(path, candidate) == []
lc.stage(path, candidate)
assert (repo / lc.checkpoint_path(path)).read_text() == candidate


@pytest.mark.parametrize("repair", [False, True])
def test_fallback_pass_reuses_english_parse_for_different_anchors_only_within_call(
repo: pathlib.Path, monkeypatch: pytest.MonkeyPatch, repair: bool
) -> None:
put(repo, "docs/a.md", "# Alpha\n\n## Beta\n")
links = "\n".join(
f"[guide]({t.REPO_URL}/blob/main/docs/a.md{fragment})"
for fragment in ("#alpha", "#b%65ta", "", "#alpha")
)
put(
repo,
"i18n/ja/docs/b.md",
t.header("docs/b.md", JA, t.DEFAULT_MODEL, t.blob("docs/b.md")) + links,
)
original = t.english_requests
parsed = []

def requests(text: str) -> list[str]:
parsed.append(text)
return original(text)

monkeypatch.setattr(t, "english_requests", requests)
for _ in range(2):
if repair:
lc.repair_english_fallbacks()
else:
assert lc.link_failures() == []
assert parsed == ["# Alpha\n\n## Beta\n"] * 2


def test_fallback_pass_reparses_changed_source_and_rejects_removed_anchor(
repo: pathlib.Path, monkeypatch: pytest.MonkeyPatch
) -> None:
original = t.english_requests
parsed = []

def requests(text: str) -> list[str]:
parsed.append(text)
put(repo, "docs/a.md", "# Changed\n")
return original(text)

monkeypatch.setattr(t, "english_requests", requests)
link = f"[guide]({t.REPO_URL}/blob/main/docs/a.md#alpha)"
problems = lc.link_failures({"i18n/ja/docs/b.md": link + "\n" + link})
assert len(problems) == 1
assert problems[0][1] == "docs/a.md"
assert parsed == ["# Alpha\n", "# Changed\n"]


def test_fallback_repair_reparses_changed_source_before_retaining_owned_anchor(
repo: pathlib.Path, monkeypatch: pytest.MonkeyPatch
) -> None:
publish(repo, "docs/a.md")
link = f"[guide]({t.REPO_URL}/blob/main/docs/a.md#alpha)"
path = repo / "i18n/ja/docs/b.md"
header = t.header("docs/b.md", JA, t.DEFAULT_MODEL, t.blob("docs/b.md"))
put(repo, "i18n/ja/docs/b.md", header + link + "\n" + link)
original = t.english_requests
parsed = []

def requests(text: str) -> list[str]:
parsed.append(text)
put(repo, "docs/a.md", "# Changed\n")
return original(text)

monkeypatch.setattr(t, "english_requests", requests)
lc.repair_english_fallbacks()
assert path.read_text() == header + link + "\n[guide](a.md#alpha)"
assert parsed == ["# Alpha\n", "# Changed\n"]


@pytest.mark.parametrize("replacement", ["deleted", "symlink"])
@pytest.mark.parametrize("repair", [False, True])
def test_fallback_pass_rechecks_regular_source_after_first_parse(
repo: pathlib.Path, monkeypatch: pytest.MonkeyPatch, replacement: str, repair: bool
) -> None:
publish(repo, "docs/a.md")
link = f"[guide]({t.REPO_URL}/blob/main/docs/a.md#alpha)"
header = t.header("docs/b.md", JA, t.DEFAULT_MODEL, t.blob("docs/b.md"))
path = repo / "i18n/ja/docs/b.md"
put(repo, "i18n/ja/docs/b.md", header + link + "\n" + link)
original = t.english_requests
parsed = []

def requests(text: str) -> list[str]:
parsed.append(text)
(repo / "docs/a.md").unlink()
if replacement == "symlink":
(repo / "docs/a.md").symlink_to("b.md")
return original(text)

monkeypatch.setattr(t, "english_requests", requests)
if repair:
lc.repair_english_fallbacks()
assert path.read_text() == header + link + "\n[guide](a.md#alpha)"
else:
problems = lc.link_failures()
assert len(problems) == 1
assert problems[0][1] == "docs/a.md"
assert parsed == ["# Alpha\n"]


@pytest.mark.parametrize("fragment", ["", "#alpha"])
@pytest.mark.parametrize("repair", [False, True])
def test_fallback_pass_propagates_english_parser_errors_without_fragment_shortcut(
repo: pathlib.Path, fragment: str, repair: bool
) -> None:
put(repo, "docs/a.md", "# Alpha\n\n" + "x" * 20_000)
link = f"[guide]({t.REPO_URL}/blob/main/docs/a.md{fragment})"
put(
repo,
"i18n/ja/docs/b.md",
t.header("docs/b.md", JA, t.DEFAULT_MODEL, t.blob("docs/b.md")) + link,
)
with pytest.raises(t.TranslationDiffers, match="indivisible Markdown unit"):
if repair:
lc.repair_english_fallbacks()
else:
lc.link_failures()
Loading