importMap edge recovery only considers file: nodes, so imports of config:/schema:/service: files are never recovered

[zorgy28]

Summary

recover_import_edges_from_import_map() in skills/understand/merge-batch-graphs.py builds its candidate node set from type == "file" only, then hardcodes the file: prefix for both edge endpoints. Whole-file nodes created under any other prefix — config:, schema:, service:, document: — are invisible to the recovery pass, so real importMap edges get reported as missing instead of recovered.

Version: 2.9.4

The code

# Build the set of file: node ids actually present in the assembled graph.
file_node_ids: set[str] = set()
for node in assembled["nodes"]:
    if node.get("type") == "file":
        file_node_ids.add(node.get("id", ""))
...
src_id = f"file:{src_path}"
if src_id not in file_node_ids: ...
    tgt_id = f"file:{tgt_path}"
    if tgt_id not in file_node_ids:
        skipped_no_tgt_node += 1

The file-analyzer agents legitimately model a whole file under a non-file: prefix — that is what the node-type table asks for. A JSON locale catalogue becomes config:messages/de.json, a Prisma schema becomes schema:prisma/schema.prisma, a compose file becomes service:docker-compose.prod.yml.

Symptom

Imports edge recovery:
  Recovered 0 `imports` edges from importMap (384 entries scanned)
  Skipped 3 importMap target paths with no `file:` node in graph

The message blames the graph for a missing node that exists — under a different prefix. On the project above, the three "missing" targets were all present as config: nodes:

• config:messages/de.json
• config:messages/en.json
• config:src/lib/validation/outcome-config.json

Reproducer

Any project where a code file imports a JSON/YAML/schema file that an analyzer typed as config: or schema:. Concretely: a Next.js app with next-intl where src/app/types/dictionary.ts imports messages/de.json and messages/en.json.

Suggested fix

Build a path -> node_id map across whole-file node types, preferring file: when a path carries more than one, and resolve through it:

WHOLE_FILE_NODE_TYPES: frozenset[str] = frozenset({
    "file", "config", "document", "service", "pipeline", "schema", "resource",
})

node_id_by_path: dict[str, str] = {}
for node in assembled["nodes"]:
    ntype = node.get("type")
    nid = node.get("id", "")
    fpath = node.get("filePath")
    # The id-shape check keeps whole-file nodes and excludes sub-file nodes
    # such as `table:<path>:<name>` or `endpoint:<path>:<method>`.
    if ntype in WHOLE_FILE_NODE_TYPES and fpath and nid == f"{ntype}:{fpath}":
        if fpath not in node_id_by_path or ntype == "file":
            node_id_by_path[fpath] = nid

Then src_id = node_id_by_path.get(src_path) / tgt_id = node_id_by_path.get(tgt_path).

table and endpoint are deliberately excluded — in this schema they are always sub-file constructs and never import endpoints. The two log lines should also change from "with no `file:` node in graph" to "with no whole-file node in graph".

Keep the existing if src_id == tgt_id: continue self-loop guard — it is a useful backstop (see the Python-resolver issue).

Verification

Replaying a real project's 44 batch fragments through the merge:

	before	after
Recovered … imports edges	0	3
Skipped … target paths	3	0
dangling edges	0	0
self-loops	0	0

Node and edge totals otherwise unchanged; the three recovered edges carry recoveredFromImportMap: true and point at the correct config: nodes.

---

Found while analysing a production TypeScript + Python repo with /understand. Happy to open a PR.

[nickssonfreitas]

Second reproduction on a different stack, same version (2.9.4), confirming the diagnosis and the line numbers.

Project. llm-wiki-compiler, a TypeScript CLI. 502 files scanned, 23 batches, importMap with 2103 pairs. Not a Next.js/next-intl app, so the failure is not specific to locale catalogues.

Symptom, verbatim from stderr:

Imports edge recovery:
  Recovered 0 `imports` edges from importMap (502 entries scanned)
  Skipped 9 importMap target paths with no `file:` node in graph

The 9 skipped occurrences, resolved against the assembled graph:

importMap target	Node actually in graph	Importers
package.json	config:package.json	8
src/profile/schema/profile.v1.schema.json	schema:src/profile/schema/profile.v1.schema.json	1

Both nodes are present and well-formed. Neither is reachable through f"file:{tgt_path}", so both are reported as absent.

One detail that sharpens the impact statement. On this project the recovery pass was not merely degraded, it was inverted: the graph was missing exactly 7 importMap edges before Phase 3, and all 7 had non-file: targets. So every edge the pass existed to recover was precisely an edge it could not see, and Recovered 0 reads like "nothing needed recovering" when it means "nothing recoverable was visible." Post-review the graph reaches 2103/2103; without the manual Phase 3 recovery it would have shipped at 2096/2103.

The proposed fix in the description resolves this case as written. With WHOLE_FILE_NODE_TYPES including both config and schema, and the id-shape guard nid == f"{ntype}:{fpath}", both nodes here match: their ids are exactly config:package.json and schema:src/profile/schema/profile.v1.schema.json, and neither is a sub-file construct. The file:-wins tie-break never triggers on this project, since no path carries two whole-file nodes.

Minor addition to the suggested patch. The two log lines are worth changing beyond the wording fix, because the counters currently conflate two different situations. skipped_no_tgt_node increments before the (src_id, tgt_id) in existing check, so a target counts as skipped even when the analyzer already emitted a correct edge to it. That is what happened to 2 of the 9 occurrences here (src/cli.ts and src/connectors/run.ts both emitted config:package.json correctly, having been given the prefix at dispatch — see #303). So "9 skipped" overstates the real gap of 7. Counting only targets that resolve to no whole-file node at all, after the dedup check, would make the number actionable.

Related, and arguably the same defect at earlier stages: #628 (the dangling dropper discards these instead of normalizing the prefix, which is where 6 of the 7 were actually lost) and #303 (the analyzer had to guess the prefix in the first place).