Node IDs are context-dependent (_file_stem uses immediate parent of the passed path) → split & cross-repo-collided nodes

[cheema-yahya]

Summary

graphify.extract._file_stem() derives a node-ID prefix from path.parent.name of whatever Path it is handed, so node identity is not a pure function of the file's repo-relative location. The same entity can get two IDs (split nodes), and different entities can get one ID (collisions). Both corrupt degree/betweenness and community structure.

Two failure modes

1. Split nodes (when IDs come from more than one extractor)

The AST extractor receives absolute paths, so a repo-root file foo.py gets the repo folder name baked in: <repofolder>_foo_<entity>. Any other ID source that records a relative source_file / bare stem (an LLM/agent extraction step, a hand-authored fragment) produces foo_<entity>. They never join → the entity becomes two nodes with split degree. (_pick_winner in dedup.py already prefers the shorter, un-prefixed ID — i.e. the repo-prefixed form is effectively non-canonical.)

2. Cross-repo collisions (multi-repo workspace)

_file_stem qualifies with only the immediate parent dir. Running graphify extract . over a workspace of several repos collides same-named files: every service's app/models.py → one app_models_* node; tests/conftest.py from N services → shared tests_conftest_* nodes. Distinct entities silently merge, fabricating cross-service edges.

Real-world data point: a single extract . over a 7-repo workspace produced 29 such collisions (e.g. tests/conftest.py merged across 6 services, app/app.py across 5). merge-graphs/prefix_graph_for_global do namespace correctly via <repo>::<id> + the repo attribute — but a combined extract . does not, and that's a common usage.

Root cause

def _file_stem(path: Path) -> str:
    parent = path.parent.name          # immediate parent of the *passed* path
    if parent and parent not in (".", ""):
        return f"{parent}.{path.stem}"
    return path.stem

Identity depends on CWD / absolute-vs-relative path / repo folder name, and disambiguates only one directory level (partial #550 — still collides for same-named files 2+ dirs deep).

Invariant

A node's identity should be a pure function of (repo-relative path, entity) — stable across CWD, absolute-vs-relative paths, and the repo folder's name. The "which repo" dimension belongs in the repo attribute (which deduplicate_entities and prefix_graph_for_global already use), never in the ID.

Proposed fix

1. Thread the repo/scan root into _file_stem and qualify by the full repo-relative path (also fixes deep same-name collisions):

   def _file_stem(path, repo_root=None):
       if repo_root is not None:
           try:
               rel = path.resolve().relative_to(Path(repo_root).resolve())
               return ".".join(rel.with_suffix("").parts)
           except ValueError:
               pass
       parent = path.parent.name  # legacy fallback (unchanged)
       return f"{parent}.{path.stem}" if parent not in (".", "") else path.stem

2. Extract identity into one graphify/ids.py (node_id(repo_root, path, entity)) called by every ID-producing path, so non-AST sources can't drift.
3. Add a validate.py collision check (canonical_id -> [ids]) wired into validate_extraction / build_from_json so a regression fails loudly.
4. Backward-compat: this changes existing IDs → ship a one-time graphify migrate-ids. I have a working reference implementation (canonicalization + alias-assertion + selftest) and am happy to contribute it.

Tests to add

• canon idempotency; deep-nesting (a/b/c.py vs x/b/c.py distinct); rename-invariance (same repo under two folder names → identical IDs); collision-hook flags a split and passes a clean graph.

Filing as an issue first since it's a backward-incompatible change to node IDs — happy to open a PR if this direction looks right.

🤖 Generated with Claude Code

[pkudinov]

Here's a small monorepo-shaped repro for the false-positive side of this issue:

repo/
  packages/a/src/index.ts
  packages/a/src/feature/parser.ts
  packages/b/src/index.ts
  app/src/unrelated.spec.ts

packages/a/src/index.ts

export { Parser } from './feature/parser.js';

packages/b/src/index.ts

export const contract = {};

app/src/unrelated.spec.ts

import { contract } from '@scope/b';

If packages/a/src/feature/parser.ts changes, a reverse import traversal can incorrectly reach app/src/unrelated.spec.ts through the shared package-entrypoint alias:

feature_parser -> src_index -> unrelated_spec

There is no semantic dependency between package A's parser and the app test. The bridge exists because src/index.ts entrypoints can be represented by a non-repo-qualified ID or alias such as src_index. In a monorepo, many packages have src/index.ts, so package-entrypoint aliases become high-fanout collision points.

Using repo-relative file identity for these nodes and import targets, for example packages_a_src_index and packages_b_src_index, would prevent this class of false-positive traversal while still preserving stable IDs.

[safishamsi]

Fixed in 0.9.0. _file_stem no longer uses only the immediate parent — node IDs are now derived from the full repo-relative path, so files at the same relative path no longer collide and split/cross-repo collisions are resolved. This was the root cause behind #1504/#1509 too.