Skip to content

compose primitives: 'codemap check <file>' should answer AND say whether to believe the answer #133

Description

@JordanCoin

codemap's primitives are good and its composites don't exist. Every genuinely useful thing I do with it is a hand-assembled combo of 2-3 commands plus knowledge that isn't in any output. Those combos should be first-class.

This issue proposes the highest-value one. I validated it as a script before filing.

The combo

Answering "who imports X" is only actionable alongside "did the scanner drop anything for X's language". Today those are two commands, and the second is the one people skip — which is exactly how #132 stays invisible.

Prototype composing --json --importers with the coverage block from --json --deps:

FILE      src/types.ts
IMPORTERS 0
COVERAGE  scan=complete  dropped_total=2  dropped_in_.ts=2
TRUST     LOW  - "no importers" is NOT evidence of unused;
          the scan dropped 2 reference(s) from .ts files.

Compare that to what codemap says today for the same file, which is imported by src/index.ts:

$ codemap --importers src/types.ts
No files import src/types.ts.

Same underlying data. One is a wrong answer stated plainly; the other is a wrong answer that tells you it might be wrong and why.

The finding that matters more than the feature

I ran the same prototype twice — once against shipped codemap, once against a build where coverage.issues is populated:

shipped codemap issues populated
verdict TRUST HIGH - nothing dropped TRUST LOW - dropped 2 refs from .ts
reality confidently wrong correct

A composite inherits its primitives' dishonesty and states it with more authority. Built on today's always-empty issues[], this feature would make #132's silent failure louder — a confident "TRUST HIGH" on a file that is in fact imported.

So the ordering is not negotiable: #111 (per-query coverage) and honest issues[] land first, then the composite. Shipping the composite on top of a lying primitive is strictly worse than shipping nothing.

Suggested shape

codemap check <file> returning, in one call:

  • importer count and hub status (already have it)
  • coverage scoped to this file's language, not the whole scan — that is coverage is reported at scan granularity but consumed at query granularity #111, and this is its most concrete consumer
  • an explicit trust verdict, so the caller does not have to know that "0 importers" and "0 importers, 515 edges dropped" are different facts
  • for a hub, the reason it matters (importer count, top dependents)

Text for humans, --json for agents, same content.

Why this earns its place

The agent-facing failure is not "codemap lacks a feature", it is "codemap gives an answer that reads as complete when it is not". A wrong --importers result is acted on: files get deleted, signatures get changed, blast radius gets underestimated. Attaching trust to the answer is the smallest change that makes the primitive safe to act on.

Related: #111 (coverage granularity — the blocking dependency), #132 (the failure this would have surfaced), #130.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions