victor-codegraph 0.1.0__tar.gz → 0.1.2__tar.gz

{victor_codegraph-0.1.0 → victor_codegraph-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: victor-codegraph
-Version: 0.1.0
+Version: 0.1.2
 Summary: Code->CPG chunker: tree-sitter symbol + relation extraction, size-capped chunks, ProximaRecord projection. Shared by Victor, ProximaDB SDK, and AnvaiOps.
 Author-email: Vijaykumar Singh <singhvjd@gmail.com>
 License: Apache-2.0

{victor_codegraph-0.1.0 → victor_codegraph-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "victor-codegraph"
-version = "0.1.0"
+version = "0.1.2"
 description = "Code->CPG chunker: tree-sitter symbol + relation extraction, size-capped chunks, ProximaRecord projection. Shared by Victor, ProximaDB SDK, and AnvaiOps."
 readme = "README.md"
 requires-python = ">=3.10"

{victor_codegraph-0.1.0 → victor_codegraph-0.1.2}/tests/test_adapter.py

@@ -37,6 +37,10 @@ def test_edge_records_reference_node_oids():
     assert e["edge"]["from_oid"].startswith("graph/repo1/node/")
     assert e["edge"]["to_oid"].startswith("graph/repo1/node/")
     assert e["edge"]["edge_type"] == "CALLS"
+    # edge props always carry a call-site line (0 when unknown; >0 once the parser
+    # preserves call_site through resolution — see the call-site-fidelity change).
+    assert "line" in e["props"]
+    assert isinstance(e["props"]["line"], int)
 
 
 def test_embedder_populates_embedding_cell():

victor_codegraph-0.1.2/tests/test_line_base_contract.py

@@ -0,0 +1,30 @@
+"""Pins the canonical 1-based line-number contract (see model.LINE_BASE).
+
+This is the cross-surface contract — Victor, the ProximaDB SDK, and AnvaiOps all
+consume this package and must agree on a symbol's (file, name, line) coordinate.
+If a refactor ever shifts line numbers, this test fails loudly.
+"""
+
+from __future__ import annotations
+
+from victor_codegraph import LINE_BASE, parse
+
+
+def test_line_base_is_one():
+    assert LINE_BASE == 1
+
+
+def test_parse_emits_1_based_lines():
+    # The def is on the FIRST line → start_line must be 1 (not 0).
+    parsed = parse("def first():\n    return second()\n\n\ndef second():\n    return 1\n", file_path="m.py")
+    by_name = {s.simple_name: s for s in parsed.symbols}
+    assert by_name["first"].location.start_line == 1
+    assert by_name["second"].location.start_line == 5  # 1-based line of the 2nd def
+
+
+def test_call_site_line_is_1_based():
+    parsed = parse("def a():\n    return b()\n\n\ndef b():\n    return 1\n", file_path="m.py")
+    calls = [r for r in parsed.relations if r.relation_type.name == "CALLS"]
+    assert calls
+    # the b() call is on line 2 (1-based), not 1
+    assert any(r.call_site is not None and r.call_site.start_line == 2 for r in calls)

victor_codegraph-0.1.2/tests/test_repo.py

@@ -0,0 +1,62 @@
+"""Repo-walk tests — fully offline (tmp tree + stdlib ast for the .py files)."""
+
+from __future__ import annotations
+
+from victor_codegraph import chunk_path, chunk_repo, iter_source_files, parse_path
+
+
+def _make_tree(root):
+    (root / "pkg").mkdir()
+    (root / "pkg" / "a.py").write_text("def a():\n    return b()\ndef b():\n    return 1\n")
+    (root / "pkg" / "notes.txt").write_text("not source")  # unknown extension
+    (root / "README.md").write_text("# docs")  # markdown is not in the language map
+    # noise dirs that must be skipped
+    (root / "node_modules").mkdir()
+    (root / "node_modules" / "dep.py").write_text("def vendored():\n    pass\n")
+    (root / ".git").mkdir()
+    (root / ".git" / "hook.py").write_text("def hook():\n    pass\n")
+    return root
+
+
+def test_iter_source_files_filters_and_skips_noise(tmp_path):
+    _make_tree(tmp_path)
+    found = {p.name for p in iter_source_files(tmp_path)}
+    assert found == {"a.py"}  # .txt/.md skipped; node_modules/.git pruned
+
+
+def test_iter_source_files_language_filter(tmp_path):
+    _make_tree(tmp_path)
+    assert {p.name for p in iter_source_files(tmp_path, languages=["python"])} == {"a.py"}
+    assert list(iter_source_files(tmp_path, languages=["rust"])) == []
+
+
+def test_iter_single_file(tmp_path):
+    f = tmp_path / "solo.py"
+    f.write_text("def f():\n    return 1\n")
+    assert [p.name for p in iter_source_files(f)] == ["solo.py"]
+
+
+def test_chunk_path(tmp_path):
+    f = tmp_path / "m.py"
+    f.write_text("def f():\n    return 1\n")
+    chunks = chunk_path(f)
+    assert chunks and any(c.metadata.get("simple_name") == "f" for c in chunks)
+
+
+def test_chunk_path_unreadable_returns_empty(tmp_path):
+    assert chunk_path(tmp_path / "does_not_exist.py") == []
+
+
+def test_parse_path(tmp_path):
+    f = tmp_path / "m.py"
+    f.write_text("def a():\n    return b()\ndef b():\n    return 1\n")
+    parsed = parse_path(f)
+    assert parsed is not None
+    assert {s.simple_name for s in parsed.symbols} == {"a", "b"}
+
+
+def test_chunk_repo_streams_all_files(tmp_path):
+    _make_tree(tmp_path)
+    chunks = list(chunk_repo(tmp_path))
+    names = {c.metadata.get("simple_name") for c in chunks}
+    assert {"a", "b"} <= names  # symbols from pkg/a.py, vendored dirs excluded

victor_codegraph-0.1.2/tests/test_symbol_oid_contract.py

@@ -0,0 +1,81 @@
+"""Pins the ADR-044 stable, line-independent symbol-oid contract.
+
+The correlated-CPG join key must survive edits that don't change *what a symbol is*:
+a line move keeps the oid; a rename / signature change mints a new one; a body edit
+bumps ``content_version`` but not the oid. Every cross-surface consumer (Victor, the
+ProximaDB SDK, the AnvaiOps connector) derives identity from this one function, so if it
+ever drifts this test fails loudly.
+"""
+
+from __future__ import annotations
+
+from victor_codegraph import parse, stable_symbol_oid, to_proxima_records
+
+
+def _node(records, name):
+    for r in records:
+        if "graph_node" in r.get("labels", []) and r["props"].get("name") == name:
+            return r
+    raise AssertionError(f"no node record for {name!r}")
+
+
+def _records(content, *, repo="repo1", stable=True):
+    return to_proxima_records(
+        parse(content, file_path="m.py"), repo_graph_id=repo, stable_oid=stable
+    )
+
+
+def _oid_of(content, name):
+    return _node(_records(content), name)["oid"]
+
+
+def test_stable_oid_unchanged_when_symbol_moves_lines():
+    base = "def first():\n    return second()\n\n\ndef second():\n    return 1\n"
+    moved = "\n\n\n" + base  # both symbols pushed down; identity must not churn
+    assert _oid_of(base, "second") == _oid_of(moved, "second"), "line move must not churn the oid"
+    assert _oid_of(base, "first") == _oid_of(moved, "first")
+
+
+def test_stable_oid_changes_on_rename():
+    a = "def alpha():\n    return 1\n"
+    b = "def beta():\n    return 1\n"
+    assert _oid_of(a, "alpha") != _oid_of(b, "beta"), "rename must mint a new identity"
+
+
+def test_stable_oid_changes_on_signature_change():
+    one = "def f(x):\n    return x\n"
+    two = "def f(x, y):\n    return x\n"
+    assert _oid_of(one, "f") != _oid_of(two, "f"), "signature change must mint a new identity"
+
+
+def test_body_edit_bumps_content_version_not_oid():
+    a = _node(_records("def f(x):\n    return x\n"), "f")
+    b = _node(_records("def f(x):\n    return x + 1  # changed body\n"), "f")
+    assert a["oid"] == b["oid"], "body edit must not churn the oid"
+    assert (
+        a["props"]["content_version"] != b["props"]["content_version"]
+    ), "body edit must bump content_version"
+
+
+def test_dual_emit_and_default_on_gate(monkeypatch):
+    monkeypatch.delenv("VICTOR_CODEGRAPH_STABLE_OID", raising=False)
+    parsed = parse("def f(x):\n    return x\n", file_path="m.py")
+    # P2 cutover — default ON: the record oid is the canonical stable id; BOTH ids are
+    # always emitted for mixed-read.
+    on = _node(to_proxima_records(parsed, repo_graph_id="r"), "f")
+    assert on["oid"] == on["props"]["stable_oid"]
+    assert on["props"]["stable_oid"] != on["props"]["legacy_oid"]
+    # Explicit opt-out → legacy line-coupled id (existing collections stay byte-identical).
+    off = _node(to_proxima_records(parsed, repo_graph_id="r", stable_oid=False), "f")
+    assert off["oid"] == off["props"]["legacy_oid"]
+    assert off["props"]["stable_oid"] == on["props"]["stable_oid"]
+
+
+def test_stable_symbol_oid_is_pure_and_structural():
+    # The pure derivation depends only on structural coordinates — never on line/col.
+    k = stable_symbol_oid("repo1", "python", "m.py::f", "(x)")
+    assert k == stable_symbol_oid("repo1", "python", "m.py::f", "(x)")  # deterministic
+    assert k != stable_symbol_oid("repo2", "python", "m.py::f", "(x)")  # repo
+    assert k != stable_symbol_oid("repo1", "rust", "m.py::f", "(x)")  # language
+    assert k != stable_symbol_oid("repo1", "python", "m.py::g", "(x)")  # name (FQN)
+    assert k != stable_symbol_oid("repo1", "python", "m.py::f", "(x, y)")  # overload

victor_codegraph-0.1.2/tests/test_symbol_oid_parity.py

@@ -0,0 +1,77 @@
+"""ADR-044 P2 cutover **parity ratchet**.
+
+The canonical oid becomes the default only if it is a SAFE, non-lossy replacement for the
+legacy one. This ratchet pins the invariants that gate the cutover, over a representative
+multi-symbol corpus:
+
+  1. **No collisions** — distinct symbols get distinct canonical oids (else the cutover
+     would merge two symbols into one record and lose data).
+  2. **Completeness** — every symbol gets a non-empty canonical oid + a legacy alias +
+     a content_version.
+  3. **Line-shift stability** — no symbol's canonical oid changes when lines move
+     (the incremental-re-index property the whole ADR exists for).
+  4. **Determinism** — re-parsing yields identical oids.
+
+If any of these regresses, the cutover is unsafe and CI fails.
+"""
+
+from __future__ import annotations
+
+from victor_codegraph import parse, to_proxima_records
+
+_CORPUS = """\
+import os
+
+
+class Auth:
+    def login(self, user):
+        return self._check(user)
+
+    def _check(self, user):
+        return bool(user)
+
+
+def helper(x):
+    return x + 1
+
+
+def helper2(x, y):
+    return x + y
+"""
+
+
+def _nodes(records):
+    return [r for r in records if "graph_node" in r["labels"]]
+
+
+def _canonical_nodes(src):
+    return _nodes(
+        to_proxima_records(parse(src, file_path="auth.py"), repo_graph_id="r", stable_oid=True)
+    )
+
+
+def test_no_collisions_distinct_symbols_distinct_oids():
+    recs = _canonical_nodes(_CORPUS)
+    oids = [r["oid"] for r in recs]
+    assert len(recs) >= 5, "Auth, login, _check, helper, helper2 expected"
+    assert len(oids) == len(set(oids)), "canonical oids must be unique per symbol (no merge)"
+
+
+def test_completeness_every_symbol_has_canonical_legacy_and_version():
+    for r in _canonical_nodes(_CORPUS):
+        assert r["props"]["stable_oid"], "missing canonical oid"
+        assert r["props"]["legacy_oid"], "missing legacy alias"
+        assert r["props"]["content_version"], "missing content_version"
+        assert r["oid"] == r["props"]["stable_oid"], "gated record oid must be the canonical one"
+
+
+def test_line_shift_stable_for_all_symbols():
+    base = {r["props"]["name"]: r["oid"] for r in _canonical_nodes(_CORPUS)}
+    moved = {r["props"]["name"]: r["oid"] for r in _canonical_nodes("\n\n\n" + _CORPUS)}
+    assert base == moved, "no symbol's canonical oid may change on a line shift"
+
+
+def test_deterministic_reparse():
+    a = {r["props"]["name"]: r["oid"] for r in _canonical_nodes(_CORPUS)}
+    b = {r["props"]["name"]: r["oid"] for r in _canonical_nodes(_CORPUS)}
+    assert a == b

{victor_codegraph-0.1.0 → victor_codegraph-0.1.2}/victor_codegraph/__init__.py

@@ -16,6 +16,7 @@ from .adapter import relation_to_record, symbol_to_record, to_proxima_records
 from .config import ChunkConfig
 from .languages import detect_language
 from .model import (
+    LINE_BASE,
     CodeChunk,
     CodeRelation,
     CodeRelationType,
@@ -23,16 +24,24 @@ from .model import (
     CodeSymbolType,
     ParsedCode,
     SourceLocation,
+    deterministic_symbol_id,
+    stable_symbol_oid,
 )
 from .parser import chunk, parse
+from .repo import chunk_path, chunk_repo, iter_source_files, parse_path
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"
 
 __all__ = [
     "__version__",
     "chunk",
     "parse",
+    "chunk_repo",
+    "chunk_path",
+    "parse_path",
+    "iter_source_files",
     "ChunkConfig",
+    "LINE_BASE",
     "detect_language",
     "to_proxima_records",
     "symbol_to_record",
@@ -44,4 +53,6 @@ __all__ = [
     "CodeRelationType",
     "ParsedCode",
     "SourceLocation",
+    "stable_symbol_oid",
+    "deterministic_symbol_id",
 ]

victor_codegraph-0.1.2/victor_codegraph/adapter.py

@@ -0,0 +1,182 @@
+"""Projection to the ProximaDB substrate-keystone ``ProximaRecord`` shape.
+
+Per ProximaDB ``CODE_GRAPH_CORRELATED_SUBSTRATE_2026_06_22.adoc`` a code symbol is *one*
+record addressable as a relational row, a graph node, and a vector at once. This adapter
+emits the **shape** as plain dicts — it does not import proximadb, embed, or write. The
+consumer (Victor embedded, AnvaiOps service) supplies the embedder and the DB write.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from typing import Any, Callable
+
+from .model import CodeRelation, CodeSymbol, ParsedCode, stable_symbol_oid
+
+Embedder = Callable[[str], list[float]]
+
+# ADR-044 mixed-read gate. **P2 cutover (2026-06-28): default ON** — the record `oid` is
+# the line-independent canonical form, gated behind the parity ratchet
+# (tests/test_symbol_oid_parity.py: no collisions / completeness / line-shift stability).
+# BOTH ids are always emitted in props so readers dual-read and legacy collections still
+# resolve. Opt out per-call (`stable_oid=False`) or per-process (`VICTOR_CODEGRAPH_STABLE_OID=0`).
+_STABLE_OID_ENV = "VICTOR_CODEGRAPH_STABLE_OID"
+
+
+def _stable_oid_enabled(override: bool | None = None) -> bool:
+    if override is not None:
+        return override
+    val = os.getenv(_STABLE_OID_ENV)
+    if val is None or val.strip() == "":
+        return True  # ADR-044 P2: canonical is the default (parity-ratchet-gated)
+    return val.strip().lower() in ("1", "true", "yes", "on")
+
+
+def _legacy_symbol_oid(repo_graph_id: str, symbol: CodeSymbol) -> str:
+    """Line-coupled alias (today's id) — retained for the mixed-read bake."""
+    return f"graph/{repo_graph_id}/node/{symbol.id}"
+
+
+def _canonical_symbol_oid(repo_graph_id: str, symbol: CodeSymbol) -> str:
+    """Line-independent canonical oid (ADR-044) — the correlation join key."""
+    key = stable_symbol_oid(
+        repo_graph_id, symbol.language, symbol.fully_qualified_name, symbol.signature
+    )
+    return f"graph/{repo_graph_id}/node/{key}"
+
+
+def _content_version(symbol: CodeSymbol) -> str:
+    """Body fingerprint for staleness/dedup — NOT identity (a body edit bumps this,
+    not the oid)."""
+    return hashlib.blake2b(symbol.source_code.encode("utf-8"), digest_size=8).hexdigest()
+
+
+def symbol_to_record(
+    symbol: CodeSymbol,
+    repo_graph_id: str,
+    branch_id: str = "main",
+    embedder: Embedder | None = None,
+    model_id: str = "bge-small-en-v1.5",
+    dim: int = 384,
+    *,
+    stable_oid: bool | None = None,
+) -> dict[str, Any]:
+    """Project one symbol to a node record (row + graph node + optional vector).
+
+    Always emits BOTH the canonical line-independent oid and the legacy line-coupled
+    one (ADR-044 dual-emit); the primary record ``oid`` is the canonical one only when
+    the stable-oid gate is on (``stable_oid`` arg or ``VICTOR_CODEGRAPH_STABLE_OID``),
+    else legacy — so existing collections are byte-identical until cutover. Consumers
+    read ``name`` / ``line`` / ``fully_qualified_name`` from props (never by parsing the
+    oid), so the oid can be opaque.
+    """
+
+    legacy = _legacy_symbol_oid(repo_graph_id, symbol)
+    canonical = _canonical_symbol_oid(repo_graph_id, symbol)
+    oid = canonical if _stable_oid_enabled(stable_oid) else legacy
+    record: dict[str, Any] = {
+        "oid": oid,
+        "labels": ["graph_node", "code_symbol"],
+        "branch_id": branch_id,
+        "props": {
+            "name": symbol.simple_name,
+            "fully_qualified_name": symbol.fully_qualified_name,
+            "file": symbol.location.file_path,
+            "line": symbol.location.start_line,
+            "end_line": symbol.location.end_line,
+            "lang": symbol.language,
+            "ast_kind": symbol.symbol_type.name,
+            "signature": symbol.signature,
+            "visibility": "private" if "private" in symbol.modifiers else "public",
+            "module_path": "::".join(symbol.scope_chain),
+            "snippet": symbol.source_code,
+            "documentation": symbol.documentation,
+            # ADR-044 dual-emit: both ids always present for mixed-read resolution,
+            # plus the body fingerprint (staleness/dedup, not identity).
+            "stable_oid": canonical,
+            "legacy_oid": legacy,
+            "content_version": _content_version(symbol),
+        },
+        "embeddings": [],
+    }
+    if embedder is not None:
+        record["embeddings"].append(
+            {
+                "model_id": model_id,
+                "modality": "code",
+                "dim": dim,
+                "values": embedder(symbol.source_code),
+            }
+        )
+    return record
+
+
+def relation_to_record(
+    relation: CodeRelation,
+    repo_graph_id: str,
+    branch_id: str = "main",
+    *,
+    id_map: dict[str, str] | None = None,
+    stable_oid: bool | None = None,
+) -> dict[str, Any]:
+    """Project one relation to an edge record.
+
+    Edge IDENTITY is ``(from_oid, to_oid, edge_type)`` — the call-site line is a prop,
+    not identity, so the edge is line-independent once its endpoints are. ``id_map``
+    (built by :func:`to_proxima_records`) maps a symbol's legacy id to its canonical
+    oid; when the gate is on, endpoints resolve through it so edges and nodes agree.
+    """
+
+    def _endpoint(symbol_id: str) -> str:
+        if id_map is not None and _stable_oid_enabled(stable_oid):
+            mapped = id_map.get(symbol_id)
+            if mapped is not None:
+                return mapped
+        return f"graph/{repo_graph_id}/node/{symbol_id}"
+
+    return {
+        "labels": ["graph_edge"],
+        "branch_id": branch_id,
+        "edge": {
+            "from_oid": _endpoint(relation.from_symbol_id),
+            "to_oid": _endpoint(relation.to_symbol_id),
+            "edge_type": relation.relation_type.name,
+        },
+        "props": {
+            "confidence": relation.confidence,
+            "context": relation.context,
+            # call-site line (0 when unknown) — a prop, NOT part of edge identity.
+            "line": relation.call_site.start_line if relation.call_site is not None else 0,
+            # legacy endpoints for mixed-read resolution.
+            "legacy_from_oid": f"graph/{repo_graph_id}/node/{relation.from_symbol_id}",
+            "legacy_to_oid": f"graph/{repo_graph_id}/node/{relation.to_symbol_id}",
+        },
+    }
+
+
+def to_proxima_records(
+    parsed: ParsedCode,
+    repo_graph_id: str,
+    branch_id: str = "main",
+    embedder: Embedder | None = None,
+    *,
+    stable_oid: bool | None = None,
+) -> list[dict[str, Any]]:
+    """Project an entire parsed file to node + edge records (shapes only).
+
+    Builds the legacy-id → canonical-oid map once so edges resolve to the same key the
+    nodes use under the gate (ADR-044). Pass ``stable_oid=True`` (or set
+    ``VICTOR_CODEGRAPH_STABLE_OID``) to emit canonical oids as primary.
+    """
+
+    id_map = {s.id: _canonical_symbol_oid(repo_graph_id, s) for s in parsed.symbols}
+    records = [
+        symbol_to_record(s, repo_graph_id, branch_id, embedder, stable_oid=stable_oid)
+        for s in parsed.symbols
+    ]
+    records.extend(
+        relation_to_record(r, repo_graph_id, branch_id, id_map=id_map, stable_oid=stable_oid)
+        for r in parsed.relations
+    )
+    return records

{victor_codegraph-0.1.0 → victor_codegraph-0.1.2}/victor_codegraph/model.py

@@ -13,6 +13,23 @@ from dataclasses import dataclass, field
 from enum import IntEnum
 from typing import Any
 
+# ─────────────────────────────────────────────────────────────────────────────
+# CANONICAL LINE-NUMBER CONTRACT
+#
+# Every line number this package emits (``SourceLocation.start_line`` / ``end_line``,
+# ``CodeChunk.metadata['start_line']``/``['end_line']``, the ``call_site`` line on a
+# ``CodeRelation``) is **1-based** — line 1 is the first line of the file. This matches
+# editors (Monaco/VS Code), pgwire, and how humans reference code.
+#
+# victor-codegraph is the SHARED parser across Victor, the ProximaDB SDK, and AnvaiOps,
+# so this convention is the cross-surface contract: a symbol's ``(file, name, line)``
+# coordinate must be identical in every consumer for the correlated code-graph to
+# reconcile. Consumers MUST pass these line numbers through unchanged — do NOT convert
+# to 0-based (a `- 1` shift) for an internal/tree-sitter-compat convention; that breaks
+# cross-surface reconciliation. Byte offsets (``byte_offset``/``start_pos``) are 0-based.
+LINE_BASE = 1
+# ─────────────────────────────────────────────────────────────────────────────
+
 
 class CodeSymbolType(IntEnum):
     """Kinds of code symbol that can be extracted (superset across languages)."""
@@ -62,7 +79,13 @@ class CodeRelationType(IntEnum):
 
 @dataclass
 class SourceLocation:
-    """Where a symbol lives in source. Lines are 1-based; bytes are 0-based."""
+    """Where a symbol lives in source.
+
+    Lines (``start_line``/``end_line``) are **1-based** (see ``LINE_BASE`` and the
+    canonical line-number contract at the top of this module); byte offsets
+    (``byte_offset``/``byte_length``) are 0-based. Pass line numbers through
+    unchanged — do not convert to 0-based.
+    """
 
     file_path: str
     start_line: int = 0
@@ -136,12 +159,42 @@ class CodeChunk:
 
 
 def deterministic_symbol_id(file_path: str, name: str, line: int, column: int = 0) -> str:
-    """Stable 16-hex id keyed on (file, name, line, col) — same input, same id."""
+    """Stable 16-hex id keyed on (file, name, line, col) — same input, same id.
+
+    LINE-COUPLED: editing code above a symbol moves its line and changes this id.
+    Retained as the *legacy* alias during the ADR-044 mixed-read bake; new identity
+    is :func:`stable_symbol_oid`.
+    """
 
     key = f"{file_path}:{name}:{line}:{column}"
     return hashlib.sha256(key.encode("utf-8")).hexdigest()[:16]
 
 
+def stable_symbol_oid(
+    repo_id: str,
+    language: str,
+    fully_qualified_name: str,
+    signature: str | None,
+) -> str:
+    """Line-independent stable symbol id (ADR-044) — the correlated-CPG join key.
+
+    Identity = the structural coordinates that survive edits which don't change *what
+    the symbol is*: ``repo ‖ language ‖ fully_qualified_name ‖ overload_discriminator``.
+    The FQN already encodes ``path::scope::name`` (no line), and ``signature`` (the
+    parameter list / arity) disambiguates same-name overloads. **Line, column, byte
+    offset and body text are NOT in identity** — they are metadata / a separate
+    ``content_version``. So a symbol that merely moves lines (or whose body is edited)
+    keeps this id; it changes only on rename / move / signature change.
+
+    Uses ``blake2b`` (stdlib, dependency-free) and the unit-separator ``\\x1f`` as the
+    field delimiter so a coordinate containing the delimiter can't forge a collision.
+    """
+
+    disc = signature or ""
+    key = "\x1f".join((repo_id, language, fully_qualified_name, disc))
+    return hashlib.blake2b(key.encode("utf-8"), digest_size=8).hexdigest()
+
+
 def content_hash(content: str) -> str:
     """SHA-256 of file content, for change detection on the re-index hot path."""
 

victor_codegraph-0.1.2/victor_codegraph/repo.py

@@ -0,0 +1,113 @@
+"""Repo-walking convenience — iterate source files and chunk/parse a whole tree.
+
+Every consumer (Victor codebase indexing, AnvaiOps code-graph-sync) needs the same
+loop: walk a repository, skip noise directories, and chunk/parse each source file
+whose extension maps to a known language. This puts that loop in one place.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator
+from pathlib import Path
+
+from .config import ChunkConfig
+from .languages import detect_language
+from .model import CodeChunk, ParsedCode
+from .parser import chunk as _chunk
+from .parser import parse as _parse
+
+# Directories never worth indexing (VCS, caches, vendored deps, build output).
+DEFAULT_EXCLUDE_DIRS: frozenset[str] = frozenset(
+    {
+        ".git",
+        ".hg",
+        ".svn",
+        "node_modules",
+        "__pycache__",
+        ".venv",
+        "venv",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".tox",
+        "dist",
+        "build",
+        "target",
+        ".idea",
+        ".gradle",
+        ".next",
+        "site-packages",
+        "vendor",
+    }
+)
+
+
+def iter_source_files(
+    root: str | os.PathLike[str],
+    *,
+    languages: list[str] | None = None,
+    exclude_dirs: frozenset[str] | set[str] = DEFAULT_EXCLUDE_DIRS,
+    follow_symlinks: bool = False,
+) -> Iterator[Path]:
+    """Yield files under ``root`` whose extension maps to a known language.
+
+    Skips ``exclude_dirs`` and dot-directories. If ``root`` is itself a file, yields it
+    (when its extension is recognized). ``languages`` restricts to those language names.
+    """
+    root_path = Path(root)
+    if root_path.is_file():
+        if detect_language(str(root_path)) is not None:
+            yield root_path
+        return
+    allowed = set(languages) if languages else None
+    excl = set(exclude_dirs)
+    for dirpath, dirnames, filenames in os.walk(root_path, followlinks=follow_symlinks):
+        # Prune in place so os.walk does not descend into excluded/hidden dirs.
+        dirnames[:] = [d for d in dirnames if d not in excl and not d.startswith(".")]
+        for fn in sorted(filenames):
+            p = Path(dirpath) / fn
+            lang = detect_language(str(p))
+            if lang is None:
+                continue
+            if allowed is not None and lang not in allowed:
+                continue
+            yield p
+
+
+def parse_path(
+    path: str | os.PathLike[str], *, encoding: str = "utf-8"
+) -> ParsedCode | None:
+    """Parse a single file into symbols + relations. Returns ``None`` if unreadable."""
+    p = Path(path)
+    try:
+        content = p.read_text(encoding=encoding)
+    except (OSError, UnicodeDecodeError):
+        return None
+    return _parse(content, file_path=str(p))
+
+
+def chunk_path(
+    path: str | os.PathLike[str],
+    config: ChunkConfig | None = None,
+    *,
+    encoding: str = "utf-8",
+) -> list[CodeChunk]:
+    """Read + chunk a single file. Returns an empty list if it can't be read."""
+    p = Path(path)
+    try:
+        content = p.read_text(encoding=encoding)
+    except (OSError, UnicodeDecodeError):
+        return []
+    return _chunk(content, file_path=str(p), config=config)
+
+
+def chunk_repo(
+    root: str | os.PathLike[str],
+    config: ChunkConfig | None = None,
+    *,
+    languages: list[str] | None = None,
+) -> Iterator[CodeChunk]:
+    """Walk ``root`` and yield chunks for every source file (streaming, low-memory)."""
+    for p in iter_source_files(root, languages=languages):
+        yield from chunk_path(p, config)

{victor_codegraph-0.1.0 → victor_codegraph-0.1.2}/victor_codegraph/treesitter_parser.py

@@ -116,7 +116,12 @@ def _name_of(node, src: bytes) -> str | None:
     if field is not None:
         return _text(field, src)
     for child in _children(node):
-        if child.type in ("identifier", "type_identifier", "field_identifier", "property_identifier"):
+        if child.type in (
+            "identifier",
+            "type_identifier",
+            "field_identifier",
+            "property_identifier",
+        ):
             return _text(child, src)
     return None
 
@@ -129,9 +134,7 @@ def _walk_collect(node, src, file_path, language, scope, symbols, relations):
             stype = (
                 CodeSymbolType.STRUCT
                 if t.startswith("struct")
-                else CodeSymbolType.INTERFACE
-                if "interface" in t
-                else CodeSymbolType.CLASS
+                else CodeSymbolType.INTERFACE if "interface" in t else CodeSymbolType.CLASS
             )
             sym = _mk(child, src, file_path, language, name, stype, scope)
             symbols.append(sym)
@@ -170,9 +173,33 @@ def _handle_const_arrow(node, src, file_path, language, symbols):
         value = decl.child_by_field_name("value")
         if name_node is not None and value is not None and value.type == "arrow_function":
             name = _text(name_node, src)
-            symbols.append(
-                _mk(decl, src, file_path, language, name, CodeSymbolType.FUNCTION, [])
-            )
+            symbols.append(_mk(decl, src, file_path, language, name, CodeSymbolType.FUNCTION, []))
+
+
+# Parameter-list node types across tree-sitter grammars (Python/JS-TS/Java/Go/Rust/C…).
+_PARAM_NODE_TYPES = frozenset(
+    {
+        "parameters",
+        "formal_parameters",
+        "parameter_list",
+        "argument_list",
+        "function_value_parameters",  # Kotlin/Rust-style
+    }
+)
+
+
+def _param_signature(node, src) -> str | None:
+    """The symbol's parameter-list text — the ADR-044 overload discriminator.
+
+    Stable under line moves (it's the params, not the position). ``None`` for symbols
+    with no parameter node (classes/structs), giving an empty discriminator there.
+    Python's AST parser supplies a richer ``signature``; this is the tree-sitter path.
+    """
+
+    for ch in _children(node):
+        if _attr(ch, "type") in _PARAM_NODE_TYPES:
+            return _text(ch, src)
+    return None
 
 
 def _mk(node, src, file_path, language, name, stype, scope) -> CodeSymbol:
@@ -184,6 +211,7 @@ def _mk(node, src, file_path, language, name, stype, scope) -> CodeSymbol:
         symbol_type=stype,
         fully_qualified_name=fqn,
         simple_name=name,
+        signature=_param_signature(node, src),
         location=SourceLocation(
             file_path=file_path,
             start_line=start_line,

{victor_codegraph-0.1.0 → victor_codegraph-0.1.2}/victor_codegraph.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: victor-codegraph
-Version: 0.1.0
+Version: 0.1.2
 Summary: Code->CPG chunker: tree-sitter symbol + relation extraction, size-capped chunks, ProximaRecord projection. Shared by Victor, ProximaDB SDK, and AnvaiOps.
 Author-email: Vijaykumar Singh <singhvjd@gmail.com>
 License: Apache-2.0

{victor_codegraph-0.1.0 → victor_codegraph-0.1.2}/victor_codegraph.egg-info/SOURCES.txt

@@ -1,8 +1,12 @@
 README.md
 pyproject.toml
 tests/test_adapter.py
+tests/test_line_base_contract.py
 tests/test_python_parser.py
+tests/test_repo.py
 tests/test_sizing_and_chunk.py
+tests/test_symbol_oid_contract.py
+tests/test_symbol_oid_parity.py
 tests/test_treesitter_jsts.py
 victor_codegraph/__init__.py
 victor_codegraph/adapter.py
@@ -11,6 +15,7 @@ victor_codegraph/languages.py
 victor_codegraph/model.py
 victor_codegraph/parser.py
 victor_codegraph/python_parser.py
+victor_codegraph/repo.py
 victor_codegraph/sizing.py
 victor_codegraph/treesitter_parser.py
 victor_codegraph.egg-info/PKG-INFO

victor_codegraph-0.1.0/victor_codegraph/adapter.py

@@ -1,94 +0,0 @@
-"""Projection to the ProximaDB substrate-keystone ``ProximaRecord`` shape.
-
-Per ProximaDB ``CODE_GRAPH_CORRELATED_SUBSTRATE_2026_06_22.adoc`` a code symbol is *one*
-record addressable as a relational row, a graph node, and a vector at once. This adapter
-emits the **shape** as plain dicts — it does not import proximadb, embed, or write. The
-consumer (Victor embedded, AnvaiOps service) supplies the embedder and the DB write.
-"""
-
-from __future__ import annotations
-
-from typing import Any, Callable
-
-from .model import CodeRelation, CodeSymbol, ParsedCode
-
-Embedder = Callable[[str], list[float]]
-
-
-def _symbol_oid(repo_graph_id: str, symbol: CodeSymbol) -> str:
-    return f"graph/{repo_graph_id}/node/{symbol.id}"
-
-
-def symbol_to_record(
-    symbol: CodeSymbol,
-    repo_graph_id: str,
-    branch_id: str = "main",
-    embedder: Embedder | None = None,
-    model_id: str = "bge-small-en-v1.5",
-    dim: int = 384,
-) -> dict[str, Any]:
-    """Project one symbol to a node record (row + graph node + optional vector)."""
-
-    oid = _symbol_oid(repo_graph_id, symbol)
-    record: dict[str, Any] = {
-        "oid": oid,
-        "labels": ["graph_node", "code_symbol"],
-        "branch_id": branch_id,
-        "props": {
-            "name": symbol.simple_name,
-            "fully_qualified_name": symbol.fully_qualified_name,
-            "file": symbol.location.file_path,
-            "line": symbol.location.start_line,
-            "end_line": symbol.location.end_line,
-            "lang": symbol.language,
-            "ast_kind": symbol.symbol_type.name,
-            "signature": symbol.signature,
-            "visibility": "private" if "private" in symbol.modifiers else "public",
-            "module_path": "::".join(symbol.scope_chain),
-            "snippet": symbol.source_code,
-            "documentation": symbol.documentation,
-        },
-        "embeddings": [],
-    }
-    if embedder is not None:
-        record["embeddings"].append(
-            {
-                "model_id": model_id,
-                "modality": "code",
-                "dim": dim,
-                "values": embedder(symbol.source_code),
-            }
-        )
-    return record
-
-
-def relation_to_record(relation: CodeRelation, repo_graph_id: str, branch_id: str = "main") -> dict[str, Any]:
-    """Project one relation to an edge record."""
-
-    return {
-        "labels": ["graph_edge"],
-        "branch_id": branch_id,
-        "edge": {
-            "from_oid": f"graph/{repo_graph_id}/node/{relation.from_symbol_id}",
-            "to_oid": f"graph/{repo_graph_id}/node/{relation.to_symbol_id}",
-            "edge_type": relation.relation_type.name,
-        },
-        "props": {"confidence": relation.confidence, "context": relation.context},
-    }
-
-
-def to_proxima_records(
-    parsed: ParsedCode,
-    repo_graph_id: str,
-    branch_id: str = "main",
-    embedder: Embedder | None = None,
-) -> list[dict[str, Any]]:
-    """Project an entire parsed file to node + edge records (shapes only)."""
-
-    records = [
-        symbol_to_record(s, repo_graph_id, branch_id, embedder) for s in parsed.symbols
-    ]
-    records.extend(
-        relation_to_record(r, repo_graph_id, branch_id) for r in parsed.relations
-    )
-    return records