Swift AST: cross-file IMPLEMENTS/REFERENCES edges are dropped (module-scope symbols need no import)

[Smilewithoutfalling]

Summary

On the AST track, symbols declared in a sibling file of the same Swift module cannot be resolved, so cross-file IMPLEMENTS and REFERENCES edges are dropped silently.

Swift imports are module-level, not file-level, and every file in one Swift target is one module — symbols declared in one file are visible in its siblings with no import statement at all. The AST resolver, however, resolves a relation target only through (a) a symbol declared in the same file, or (b) an imported binding:

• src/wiki-engine/code-knowledge/ast/index.ts — IMPLEMENTS sites: localInterfaces.find(…), then bindings.localToFile.get(ifaceName), otherwise continue (it never reaches a third fallback).
• src/wiki-engine/code-knowledge/ast/call-resolver.ts — resolveOneCall() for a bare callee: symbolsByFile.get(site.fromFile) first, then bindings.localToSymbolId / bindings.localToFile, otherwise returns the site unresolved.

That model is correct for TypeScript / TSX / Python / Go, where reaching a symbol in another file always requires an import or a relative path. It does not hold for Swift.

Minimal reproduction

Sources/P1/A.swift

import Foundation

public protocol LocalProto {
    func ping() -> String
}

public func helper() -> Int {
    return 42
}

Sources/P1/B.swift

import Foundation

public struct S: LocalProto {
    public func ping() -> String {
        return "s"
    }
}

public func caller() -> Int {
    return helper()
}

teamai codebase --extract <pkg> --project p1:

[AST: ast: 6 symbols, 3 imports (0 resolved), 2 calls (0 resolved), 0 edges]
[extract] p1 complete
  Files: 3
  Facts: 9 (relation:3, interface:1, component:5)
  Graph: 10 nodes, 4 edges

Neither struct S: LocalProto nor caller() → helper() yields a relation:

• facts-cache.json holds component facts for Sources/P1/B.swift:3 and Sources/P1/B.swift:9, but no IMPLEMENTS relation for line 3 and nothing resolving the call at line 9.
• gaps/detected.md reports high-orphan-ratio | 6/6 nodes have no graph connections, dependencies may not be fully extracted.
• The 4 graph edges are all CONTAINS edges generated by the heuristic track; every code-ast edge is absent.

The missing dimension is specifically "another file in the same module"

A fixture that declares one conformance per shape — protocol Refined: LocalProto, struct S: LocalProto, enum E: LocalProto, actor A: LocalProto, class C: LocalProto, extension ExtSite: LocalProto — resolves 8/8 IMPLEMENTS facts when all declarations live in one file. So struct, enum, actor, class, a protocol refinement and an extension conformance are all captured; the capture is not class-specific and is not the problem. Splitting the declaration and the conformance across two files drops it entirely.

Impact

Any Swift package with more than one source file that declares a conformance or calls across files — i.e. practically every real package. Because the edges are simply absent rather than recorded as a gap, a consumer cannot distinguish "there is no dependency" from "this was not resolved".

Relationship to #842

Not introduced by that PR: before it, .swift files were not collected on either track, so the resolver never received a Swift specifier. Registering Swift is what exposes the limitation — which is also why that PR registers Swift straight into the EXTERNAL_IMPORT gap path for module imports rather than attempting module resolution.

Possible direction

Swift Package Manager places each target's sources under Sources/<Target>/ (tests under Tests/<Target>/), and all files in one target form one module.

1. Derive the module root for a .swift file by walking up to the first directory under Sources/ or Tests/.
2. When resolving a call site or an IMPLEMENTS target from a .swift file, fall back to a symbol declared anywhere inside that module root before giving up.
3. Handle ambiguity explicitly — two targets in one package can declare the same symbol name. Pick deterministically or record a gap rather than emitting an arbitrary edge.
4. Gate the fallback on the importer being Swift so the TS / Go / Python semantics are untouched.

Adjacent but distinct from the above: import MyLib is unresolvable today for the same underlying reason (the resolver has no directory listing), which is why #842 reports it as an EXTERNAL_IMPORT gap.

[Smilewithoutfalling]

Thanks for merging #842, @jeff-r2026.

For context: I opened this issue myself right before the merge, so the gap is on record as a separate
item rather than buried in that PR. If nobody has picked it up yet, I would like to take it myself.
Codex Review flagged it as [P1 blocking] on #842 twice, and it was right that the gap is real — I just
argued (and you agreed by merging) that it should not block a PR that only opens the Swift door.

Here is the shape I am planning, so we do not end up with two people solving the same thing differently.

Root cause (reproduced, details in the issue body above): conformance and call resolution in the AST
track both run the same model — declared in this file, or reachable through a resolved import. That model
is correct for TS/Go/Python, where a cross-file symbol has to be imported. Swift is not built that way:
everything under one SPM target is in one module and is visible with no import at all. So a
struct S: LocalProto in B.swift, where LocalProto is declared in A.swift, currently emits nothing —
and the same applies to a cross-file call.

Proposed fix, scoped to Swift only.

1. Derive the module scope from the path: for an SPM layout, Sources/<Target>/**/*.swift is one module.
2. Add a Swift-only fallback after the existing same-file + import-bindings lookup: when the target symbol
   is not found there, look for a declaration of that name elsewhere in the same module and resolve to it.
3. Ambiguity: if the name is declared in more than one file of the module, I would rather emit nothing (and
   let it surface as a gap) than pick one arbitrarily. A genuine ambiguity is something Swift itself would
   reject, so a tie means the heuristic cannot tell — same reasoning as the module-import gap.

What I intend to verify: the two fixtures from this issue (cross-file conformance, cross-file call); a
negative fixture where the symbol exists only in a different target and must stay unresolved; and the full
existing suite on TS/Go/Python/Rust/Java to show nothing changes outside Swift.

If that matches how you would want it, I will start. If you would rather keep the resolution model untouched
and treat module-scope lookup as a separate layer, tell me and I will structure it that way instead.

[jeff-r2026]

Sounds good. Please take it with that shape: Swift-only fallback after the existing lookup, and emit nothing on a tie.

[Smilewithoutfalling]

Implementation is up: #847 — 4 files, +284/-7, on exactly the shape you approved (Swift-only
fallback after the existing lookup; nothing emitted on a tie).

Two gates I checked on this head that #842 never got, both against an unmodified main tree with the
same binary and flags:

• oxlint --deny-warnings → rc=0, 0 warnings, 0 errors on both trees.
  (feat(code-knowledge): add Swift support to the AST and heuristic tracks #842 merged about a minute after the lint gate landed, and its extractors/swift.ts tripped
  unicorn/prefer-string-starts-ends-with — fix(lint): use String#endsWith in the Swift extractor #846 cleaned that line up. That one was mine; measuring it
  locally this time is the least I can do.)
• tsc --noEmit → rc=0, 0 diagnostics on both trees, now that fast-check is installed locally.

Real-CLI single-variable control, one two-target package, only the source tree differing:

                       main          this branch
AST track       4 calls (1 resolved)   4 calls (3 resolved)
AST edges                1                      4
Facts                   25 (rel 8)             28 (rel 11)
Graph edges              5                      7
Models.swift -> Protocols.swift IMPLEMENTS   absent   present
Runner.swift -> Networking.swift REFERENCES  absent   present
Other/UseAux.swift -> SwiftDemo/*            absent   absent   (targets not bridged)

Heuristic track (TEAMAI_SKIP_AST=1) is byte-identical on both trees, so nothing leaked outside the AST track.

Also worth saying: the five implementation points are mutation-tested — removing any one of them (the
conformance fallback, the free-call fallback, the receiver-call fallback, the tie rejection, or the layout
restriction) fails exactly the matching test and nothing else. The known limitations are listed in the PR
description rather than left for a reviewer to find.