resolver: a third-party package colliding with an internal directory classifies INTERNAL (alembic: 552 edges)

[zaebee]

Problem

classify_fqn decides a namespace from the root segment alone (indices.py:192). When a third-party package shares its name with an internal directory, its symbols classify INTERNAL — and, since #459, are then reported as unresolved internal rather than as the third-party calls they are.

Measured on owner-api (2026-09-17)

target shape	edges	what it really is
alembic.op.add_column, …drop_column, …get_bind, …	552	the alembic library, from alembic import op — internal only because app/alembic/ exists
app.add_middleware, app.include_router, app.mount	~9	FastAPI methods on an instance named app
app.models.User.is_deleted.is_ and similar	~16	SQLAlchemy on a model attribute

Together ~750 edges on one backend, reported as unresolved when EXTERNAL would be the truthful answer for the library half.

Why it matters

unresolved_ratio is the number the project advertises as its honesty measure (README, docs/CASE_STUDY.md). Counting a library call as "could not place" overstates the gap in the same way that counting it INTERNAL used to understate it. The import map already knows the answer: from alembic import op is recorded there as a third-party root.

Sketch

When the root segment is both an internal directory and a key in the file's import map pointing at a third-party root, prefer the import map. The file that owns the reference is the tiebreaker — the same shape as the source_file argument added in #454, which made stdlib names mean stdlib only in Python sources.

Acceptance

• from alembic import op; op.add_column(...) in a repository that also has app/alembic/ classifies EXTERNAL.
• A test pins the opposite direction: a genuine internal alembic.env.run_migrations still classifies INTERNAL.
• The owner-api unresolved share drops by the ~550 alembic edges; the number goes in the PR.

Found while reviewing #493.

[zaebee]

Tried it; the premise in the description is wrong

The import map already knows the answer: from alembic import op is recorded there as a third-party root.

It is not. On the owner-api graph the index sees the two colliding roots identically:

alembic   internal_root=True  external_root=True  first_party_prefix=False
scripts   internal_root=True  external_root=True  first_party_prefix=False

internal_root because both app/alembic/ and app/scripts/ exist; external_root because imports under both names fail to strip to a node. Nothing in the graph separates a library from our own code.

What a graph-only rule gets right, and what it gets wrong

I prototyped the sharpest rule the graph supports: an internal-root FQN is third-party when its second segment names nothing under that root, and that root.second appears in some import map. Our alembic holds env and versions; the library's references are all alembic.op.* and alembic.context.*.

Measured on owner-api (ownima-backend/app, same tree, two resolvers):

	before	after
unresolved edges	12,150 / 87,845 (13.83 %)	11,646 (13.26 %)
alembic.* counted unresolved	494	0
targets reclassified	—	27

21 of the 27 are the library (alembic.op.add_column, alembic.context.configure, …) — correct. The other 6 are the project's own code:

scripts.ci.openapi_snapshot{,.canonical,.current_schema,.summarize,.SNAPSHOT.exists,.SNAPSHOT.read_text}
  ← app/tests/api/test_openapi_contract.py:17
    from scripts.ci.openapi_snapshot import SNAPSHOT, canonical, current_schema, summarize

That module lives in ownima-backend/scripts/ci/, i.e. outside the ingest root (app/), while the graph's scripts.* nodes come from app/scripts/. The rule declares first-party code third-party — trading this issue's false "internal" for a false "external", which is the worse direction: it lowers unresolved_ratio by laundering code we simply did not ingest.

What would actually decide it

The only reliable signal is outside the graph: alembic>=1.12.1 is in ownima-backend/pyproject.toml's dependencies, scripts is not. Doing this properly means

1. finding the manifest from the ingest root (walking up — the root is often a subdirectory of the project, as app/ is here),
2. parsing [project] dependencies, optional-dependencies, tool.poetry.dependencies, and requirements*.txt,
3. mapping distribution names to import names (python-dateutil → dateutil), which is only approximate without the installed environment,
4. plumbing the result from IngestionPipeline into IndexBuilder, which today receives nodes and nothing else.

That is a feature with its own design questions (what if there is no manifest? a monorepo with several? a dependency that is vendored?), not a tweak to classify_fqn.

Status

Not doing it now — deferred deliberately, with the numbers above as the starting point. The current behaviour after #459 is UNKNOWN for these targets: pessimistic but honest, which is the right default for the figure the README leans on. A future PR should take the manifest route, and the acceptance test should include the scripts/-outside-the-root shape, not only alembic.