fix(resolution): constrain what an inheritance or import reference may resolve to (#1536, #1537)

[ctype-lab]

Fixes #1536. Fixes #1537.

Summary

Two reference kinds resolve to targets they could never legally name:

• impl Error for MapperError {}, where Error came from use std::error::Error,
  binds to MapperError's own enum variant — an implementation relationship
  absent from the source.
• import * as path from 'node:path' binds to some class's path property.

Both come from one place: matchByExactName applies no kind constraint to its
candidate pool, and scoreCandidate treats node kind as a bonus rather than a
requirement — awarding none at all for extends/implements/imports. With one
same-named node in the repo, the single-candidate shortcut adopts it outright at
confidence 0.9, never reaching findBestMatch.

They are one PR because they are one mechanism applied twice. Three commits, each
independently reviewable and green.

Why a kind filter alone would have been pointless

The obvious fix — drop candidates that cannot be a supertype — was implemented and
measured first. It does not remove the false edge. It moves it.

implements target	before	kind filter only	this PR
trait (correct)	52	52	52
enum_member	7	0	0
type_alias	4	11	0

The same 11 references simply landed on an unrelated local pub type Error = …
instead — and that is worse for a consumer, because type_alias is a legal
supertype in TypeScript (class X implements SomeAliasedObjectType) and so cannot be
rejected downstream, whereas enum_member could.

So kind is only half of it. The other half is locality: a name the file imports
from outside the repository has no in-repo referent at all, so no candidate of any
kind is correct.

The fix

1. Eligibility, applied before ranking

matchByExactName restricts its candidate pool by reference kind, so a legitimate
supertype wins instead of merely having its false rival's edge deleted:

.filter((n) => !isInheritanceRef(ref) || SUPERTYPE_TARGET_KINDS.has(n.kind))
.filter((n) => ref.referenceKind !== 'imports' || isImportableKind(n.kind));

SUPERTYPE_TARGET_KINDS is deliberately wide — type_alias (TS
implements SomeAliasedObjectType), component, and module/namespace, because
whole languages inherit from one: Ruby include Trackable targets a module,
Erlang -behaviour(gen_server) targets the behaviour module, which Erlang extraction
indexes as a namespace. Both were caught by existing tests during development, not
by inspection.

2. One gate at the resolveOne seam

Filtering inside the name-matcher covers matchByExactName only; the framework,
import, chain and CFML-component-path strategies all bypass it. resolveOne is
wrapped once so every strategy passes the same check:

resolveOne(ref) {
  return this.gateTargetKind(this.resolveOneInner(ref), ref);
}

It only ever removes an edge, never adds one. A dropped reference stays in
unresolved_refs as failed — the honest record for a supertype the repo does not
contain, and what the existing lifecycle already expects.

3. Locality, only where the oracle cannot be wrong

• Rust — a use path rooted at a standard-library crate (std/core/alloc/
  proc_macro), which by definition ships outside any repository. Guarded against
  2015-edition shadowing by requiring the path not resolve to a real module file.
• ES modules — isExternalImport, which already understands tsconfig path
  aliases and monorepo workspace packages.

Everything else returns "don't know" and resolves exactly as before. JVM and Python
imports notably do not go through resolveImportPath (they have dedicated
FQN/module matchers), so there is no trustworthy oracle to consult for them, and
asking anyway reported every Java import as external — caught by
frameworks-integration.test.ts.

A wider Rust oracle was tried and reverted. Treating "the module path does not
resolve to a file" as proof of out-of-repo deleted 13 real trait implementations
on the reference project: a crate re-exporting a sibling crate's modules
(pub use pupil_core::{ports, domain};) leaves crate::ports::CacheStore with no
src/ports/ directory to walk, yet it is entirely in-repo. That case is now a test,
so the generalization cannot be reintroduced silently.

4. Svelte / Vue / Astro (third commit)

isExternalImport listed typescript/tsx/javascript/jsx/arkts, so for the three SFC
languages it fell through every branch and answered "not external" for
import { Foo } from 'some-npm-pkg' — even though extractImportMappings already
routes all three through the same extractJSImports. The classifier disagreed with
the extractor about what those imports are, and commit 1's locality check therefore
did nothing for SFCs.

The language set is now one constant used by both, so they cannot drift apart again.
Relative and aliased specifiers are unaffected — the branch still answers "not
external" for ./…, workspace members, tsconfig alias prefixes, @/, ~/, src/.

Measurements

Both against main @ c6aaa20, re-indexed from scratch.

Rust/TypeScript application (Tauri desktop app, 149 files, 2,669 nodes):

	before	after
nodes	2,669	2,669 (unchanged)
edges	9,114	9,075 (−39)
implements/extends → trait	50	50 (none lost)
implements → enum_member	7	0
implements → type_alias	4	0
imports → method	28	0
synthesized (provenance='heuristic')	159	159 (unchanged)

−39 = 11 false inheritance edges + 28 false import edges. No correct edge is lost.

This repository as a control (571 files, 12,749 nodes): node count unchanged,
edges 44,983 → 44,962. The complete diff is 24 removals and 3 rebinds:

• 1 extends recording a Scala class Boot as extending a function named App
  (the real App is the out-of-repo Scala library trait)
• 19 imports → method and 4 imports → property, every one a coincidence:
  Walker::join ×15, Telemetry::events ×2, FetchCall::url ×2,
  Tables::default, Widget::fmt, Documented::target_cb,
  TortureService::helper
• 3 references fall through to a constant of that name instead of a member

The SFC commit changes no edge here (this repository has no .svelte/.vue/
.astro sources); it is covered by its own tests.

Tests

__tests__/reference-target-kind.test.ts, 12 cases, pinning both directions:

• the Rust enum-variant repro produces no edge and leaves a failed ref
• the false edge does not relocate onto a same-named type_alias
• an in-repo trait still resolves even when a same-named enum_member exists
• a trait reached through a re-exported sibling-crate module still resolves
  (the reverted-generalization guard)
• class extends class, class implements interface, TS object-type alias
• import → member produces nothing
• Svelte, Vue and Astro npm supertypes dropped; a relative-path SFC import kept

Full suite green: 3,082 passed / 9 skipped, kernel built and parity suites running.

Scope and risk

• src/resolution/ only. No extraction change, so no kernel mirror and no parity
  risk; NODE_KINDS/EDGE_KINDS and the kernel wire layout are untouched.
• The change is one-directional: it can only remove edges, never add them, which
  matches the "silent beats wrong" policy already stated for out-of-repo supertypes
  in the CFML component-path matcher.
• Node counts are unchanged in every measurement, so explore budgets and
  candidate-set sizes are unaffected.
• Re-index required to clear existing bad edges; noted in the CHANGELOG entries.

Not in this PR

An agent A/B run (scripts/agent-eval/ab-new-vs-baseline.sh) was not performed.
The deterministic gates were: full suite, kernel parity, node-explosion check,
synthesized-edge counts, and a control-repo diff. Happy to run the A/B if you want it
before merge.

[bompus]

Verified on a real TypeScript repo (Chrome MV3 extension, 582 files, TS/JS/Vue/markdown, Windows 11, tree-sitter wasm walker, kernel off). Branch: this PR merged onto current main (b9ca4b7) plus our fork's markdown/literal extras; control build indexed the same tree without the PR.

Merges onto main with a CHANGELOG-only conflict. On our tree: imports edges landing on a property/method node 19 → 0, total edges 39,337 → 39,330 (the other 12 were retargeted to the right symbol rather than dropped). No other metric moved. PR test file: 12/12 pass.

Also cancels the 19 → 61 growth of the same shape that #1686 causes on this tree once interface members exist, so the two are complementary.

[bompus]

Data point on the overlap with #1686, since the two interact and it affects merge order.

#1686 indexes TypeScript interface members, which makes every interface member a fresh candidate for the name-only import resolver — the #1537 shape this PR constrains. I measured on the codegraph repo itself, self-indexed three ways (fresh index -f each time, kernel path, plus the Rust mirror of #1686 so the kernel actually emits the members):

build	nodes / edges	imports edges targeting a property/method
#1686 alone	17,736 / 65,698	489 (459 property, 30 method)
#1686 + its kernel mirror	21,347 / 71,498	492 (461 property, 31 method)
the above + this PR	21,363 / 71,115	0

Two things worth separating, because they cut against each other:

This PR zeroes them outright — all 492, on a repo where the baseline is already 489. That is the result I care about and it is unambiguous.

But on this repo #1686 is barely the cause. I reported on #1686 that these edges went 19 → 61 on a Chrome-extension tree, and read that as #1686 creating them. Self-indexing codegraph shows a baseline of 489 before #1686's members exist at all — most of them are not TS interface members (Rust traits and the like reach the same interface/property kinds). #1686 adds 3. So the tripling I saw is a property of that repo's shape, not a general effect of #1686, and I would not want the earlier number read as a general claim.

The practical consequence is unchanged, and if anything simpler: this PR is worth landing on its own account rather than as a mitigation for #1686. It merges cleanly onto fix/1638-ts-interface-members (no conflicts, 4 files plus the new test).

[ctype-lab]

Thank you for the test and explanation.

[ctype-lab]

Hi @colbymchenry. I just wanted to leave a gentle check-in on this PR whenever you have a moment. Conflicts are resolved and all tests pass. Thanks for maintaining this project.