callidescope-triage

Acting on a callidescope failure

Callidescope fails for a handful of distinct reasons, and reading which one occurred is most of the work. Separate them first:

The bottom five all mean the run never produced a verdict on the code. None of them writes a destination, so a checkout is unchanged by any of them — and no finding, or absence of one, should be believed from a run that printed one.

The limits command prints its own read failures under the same 🔭 Rejected a project configuration headline, fixed the same way — see A refused project configuration.

A depth gate that failed

A stack ran deeper than limits.maximumDepth. The change that made it longer is the change that fixes it — that is the whole reason depth is the gate and staleness is not.

A failed gate is about one project. Limits are written per project, in that project's own callidescope.config.ts, and a project's gate judges only the findings that project owns — a stack is charged to the project owning its root, and a dependency's breach belongs to that dependency's own gate. So there are exactly two places the fix can go: that project's code, or that project's own callidescope.config.ts. Read the second option with the whole of the section below in mind before taking it.

In an Nx workspace this arrives as a failing gate target rather than as a whole-workspace --check depth, and the task name says which project to open. Elsewhere, the finding's own limit says which number it was weighed against, and callidescope limits says which file that number is written in.

Read the printed stack before doing anything. The frames carry each callable's signature and the one-line summary of its documentation, and those summaries are how you tell the two cases apart:

• Every frame says something different. The layering is real: each stage does its own work. Question whether all the stages are needed, but do not start deleting one layer at a time — this case usually needs a design decision, not a trim.
• A run of frames all say roughly the same thing. Those are forwarding layers that exist only to pass arguments along. Collapse them. This is the common case and it is exactly what the tool was built to surface: the tools that would otherwise tell you are the ones reading a file at a time, so they see the forwarding and never the depth.

Raising maximumDepth is not a fix. The limit describes the shape the repository wants; moving it to fit today's worst stack means the gate stops gating, and every later stack gets a free pass to that new number. If the limit is genuinely wrong for the project, change it as its own decision, on its own, with the reasoning written down — not as the thing that unblocks a pull request. Raising a project's number is the smaller version of the same mistake, not an exemption from it: it is exactly the one number that was boundary-tested to sit one frame above what that project measured, so raising it by one converts a gate into headroom for the one project the finding is about.

The summary's depth is not the project's depth

The number to take is the one a verdict gives you, and never the one a summary line prints. A 🔭 Finished an analysis log line reports maximumDepthTraced, and the name is literal: it reduces over the whole of a run's measurement, the entire dependency-widened trace, so it is the deepest stack anywhere the run reached rather than anywhere it was pointed. The per-project scoping that decides a gate's verdict is a different code path entirely.

The two routinely disagree by several frames. tools/synchronization's scoped run prints maximumDepthTraced:13, while its gate passes at the declared 10 and fails at 9 — ten is the number that project owns, and thirteen belongs to a dependency it was traced alongside.

So do not set a project's limit from that line. Boundary-test instead: write a candidate, run the gate, and let a failure name the real number. A limit worth having passes at the number written and fails at one below it, and the only thing that can tell you where that boundary is, is a gate verdict.

≥ n rather than n

A depth printed with ≥ is a floor, not a measurement. Something on that path could not be followed — a callback invoked through a parameter, a computed member name like target[key](), or a structural expansion dropped for exceeding the implementation-candidate cap — and the run says so rather than quietly under-reporting.

This is not a defect to fix and not a number to distrust. It means the real depth is at least that, so a ≥ 10 against a limit of 6 is a genuine failure. Unfollowable calls in the summary counts how many such calls the run hit.

A stack headed orphan-root

Nothing in the repository calls the root. Either it is dead code, or an entry-point rule the configuration is missing — most often a framework decorator absent from entryPoints.decorators. Decide which before treating the depth as real: a stack under a root that a framework actually invokes is a finding, and one under genuinely dead code is a reason to delete the code.

Stacks through recursion above zero

A cycle, collapsed before depth was measured. A mutually recursive cluster of three contributes three frames once. The depth is a floor for the same reason as above, and the collapsing is what keeps the numbers from moving between runs — do not try to "fix" the recursion because callidescope mentioned it.

A breadth gate that failed

A callable calls more callables directly than limits.maximumBreadth. Unlike depth, this one has no default limit at all, so a breadth failure only ever happens in a project whose own callidescope.config.ts chose a number — a workspace-level maximumBreadth alone gates nothing, since every project must name its own to be judged by it.

The fix is to split the callable along the responsibilities its callees already group into, not to inline anything. Run the breadth command against the callable's address to see the direct callees and callers side by side before deciding where the seam goes — the callidescope-trace skill covers reading that.

A gate that read nothing of its own

## Read nothing of its own (0 files)

This run judged a project whose own code it never read:

- `packages/thing`

The run itself was not empty — the dependencies it traced were read — so this is narrower than 🔭 Traced nothing: only the judged project's own sources went missing. A gate fails on it and a trace prints it and passes, because a gate that never looked cannot tell a clean project from an unread one, where a trace decides nothing and is a report for a reader to open.

Two things to check, in this order:

1. An exclude that over-matched. The project's own exclude globs are anchored to its root, so one written workspace-relative matches nothing, and one written too broadly matches everything. Check the run's exclude and excludeFrom for a pattern covering the whole project as well.
2. A project that no longer holds sources its tsconfig.json includes. A moved or emptied source root reads exactly the same way.

Do not silence it by dropping the gate. A project the workspace configuration excludes is denied a gate deliberately and never reaches this message; a project that still has one is expected to have code, and a green verdict over nothing is the failure this exists to prevent.

A stale report

One or more configured destinations no longer hold what a fresh run would write. The run names every file that drifted rather than stopping at the first.

Re-run --write. That is the entire fix.

npx callidescope --write

Three things a stale report does not mean:

• It is not a defect. The call graph moves with the code, so a report goes stale whenever anything anywhere moves. That is exactly why --check reports belongs on the default branch and not on a pull request.
• It is not something to hand-edit. The next --write replaces the block between its markers wholesale, so an edited report is a diff that silently disappears on the following run.
• It is not a reason to add --check reports to the pull request gate. Doing that fails pull requests for drift they did not cause.

Lint before regenerating, never after. Every frame in every report carries a file:line, and a formatter that sorts class members moves the line numbers of everything after the one it inserted — so a report written before that sort is stale the moment it lands.

A rejected command line

Nothing was traced. The message lists the reasons; these are the ones to expect:

• --check needs a value. A valueless flag, an empty string, or a comma-only value are all the same mistake. A set with nothing in it is indistinguishable from the flag having been left off, and reading it as "gate nothing" would produce a gate that cannot fail — --check "$GATES" with the variable unset would pass forever over a stack twice as deep as anything allowed, which is worse than no gate because it looks like protection.
• --check does not accept that value. It takes a comma-separated set drawn from breadth, depth, and reports, and the message lists them.
• --write cannot be combined with --check reports. A report cannot be stale in the run that just wrote it, so the combination would pass whatever it was meant to catch. Run them separately, on the sides of the pull request they belong to.
• A destination flag with no verb. --json, --markdown, and --mermaid say where a report goes; --write and --check reports say whether one is written or compared. Given a destination and neither verb, the run is refused rather than obeyed silently. Add the verb the message names. --check reports counts as one: it compares a destination, so an override is meaningful there too.
• A destination flag overriding a destination nobody declared. --json, --markdown, and --mermaid change where a declared report goes; they cannot conjure one the configuration never asked for, or a requirement that configuration be complete would be circumventable from a terminal. Add the write.json, write.markdown, or write.mermaid the message names to the configuration this run reads, then point it elsewhere with the flag.
• --format does not accept that value. It takes markdown, mermaid, or json, and the message lists them. An unrecognized value is refused rather than rewritten to markdown, which is what it used to do — a run that printed a tree for --format mermiad exited 0 having taught its reader that the flag does nothing.
• --maximum-breadth overriding a limit nobody declared. It is refused the same way a destination flag is: against a configuration declaring no limits.maximumBreadth anywhere in scope, there is nothing for it to override, and supplying one from the command line would gate a workspace on a number no configuration ever chose.
• depth or breadth with no address. Those commands take <file>#<qualified-name>. At a real terminal outside CI they trace first and then complete the address against every callable they found, so the name can be picked rather than recalled; a name declared twice in one file arrives with its :<line> already attached. In a script or a CI job prompting is off, so a missing argument is a rejection rather than a hang.

A refused project configuration

A callidescope.config.ts sitting at one traced project's own root — or the absence of one — was refused. Nothing was printed and no destination was touched, so the checkout is exactly as the run found it. <project> is the workspace-relative project root; an address the workspace file declared is labelled the workspace configuration instead.

The project has no configuration file at all.

Every traced project's own callidescope.config.ts is required, not optional. A project with none is refused by name before anything is traced. The fix is to add one, spreading the workspace's projectDefaults export and overriding what it means to:

import { projectDefaults } from "../../configuration/callidescope.config.js";

That import path is illustrative rather than literal — write it relative to the project's own location. A file that overrides nothing is still a complete statement: it says outright that this project takes every default, which an absent file could never say.

The file could not be read, or leaves a required field out.

The read failed, or the object did not pass the schema. <reason> is the underlying failure and is kept as the error's cause. A schema complaint names the field: a missing entryPoints, exclude, limits, or write member, a limit that is not a positive integer, an addresses entry that is not a string. Every field is required now — entryPoints with all five members, limits with both, write with both, exclude — so a file that leaves one out is refused the same way a file with no configuration at all is, and spreading projectDefaults before overriding is what keeps that file from having to spell out every field itself.

A field only the workspace may set.

Move that field to the workspace file. <field> prints as limits.<name> for a limit, write.<name> for a destination, and as a bare name for any other top-level field, so the message says which of the three is wrong.

Two ways to arrive here, and the fix differs:

• A spread of the workspace's default export into the project's own file. Delete it and spread projectDefaults instead. The default export carries directories, excludeFrom, write.json, and the rest of what only the workspace may set; projectDefaults holds exactly the surface a project is entitled to, so spreading it cannot adopt one of those fields by accident.
• A genuinely workspace-level field — directories, excludeFrom, excludeCallees, or write.json. It belongs in the workspace file and there is no per-project form of it: each names what a run reads, where the run's own report lands, or how it partitions the workspace, which a project cannot answer differently from the run tracing it.

A declared address resolved to nothing.

The callable was renamed, moved, or excluded from this run. Correct the address or delete it. Do not silence it: this refusal exists because a rename that silently dropped a declared root would lower that project's measured depth with nothing in the output to say so, loosening a gate in the one commit nobody would think to check it in. If the address is right but the callable is outside what this run traced, the scope is the problem, not the address.

A declared address was ambiguous.

Every candidate is rendered as an address that would have picked it, so copy one into the configuration. Two declarations on one line cannot be told apart that way; those name their column instead and the advice changes to Two declarations on one line cannot be told apart by ":<line>" — rename one, or name a different callable.

A declared address was malformed.

Usually a bare file path, a bare qualified name, or a path separator where the # should be. The path is workspace-relative.

A run collects every unresolved address before it refuses, so fix them as a set: more than one arrives numbered, behind <count> declared entry points did not resolve. The depth and breadth commands report the same three problems about an address typed at a prompt, worded for that context and rendered by the same code.

A project configuration that is refused by nothing and does nothing

A misspelled key is not a refusal — the schema names every field it accepts, so limits: { maxDepth: 10 } alongside a correctly-spelled maximumDepth fails for the unrecognized key rather than silently keeping the typo around. If a project's limit still seems not to have taken effect after the schema passed, ask what it actually resolved to rather than re-reading the file:

The row for that project says the number and the file it came from.

A project's exclude goes quiet for a different reason. Its globs are anchored to that project's own root, so a workspace-relative one — packages/thing/src/generated/** written in packages/thing's own file — matches nothing and those files stay traced. Drop the project root from the front of it: src/generated/**. A glob that would reach into another project cannot be written here at all, and noise spanning several projects belongs in the run's own exclude instead.

A project it could not read

One project's tsconfig.json is missing or did not parse, and the run stopped there. The message carries the path and either the compiler's own diagnostic or that the directory holds no tsconfig.json at all. depth and breadth raise this too, under the same headline: a lookup traces before it matches, so it can reach the same unreadable project a whole-workspace trace always could.

Nothing was printed and no destination was written, which is the point of stopping rather than stepping over it: a caller writes its report before it weighs its findings, so a partial graph would publish depths measured through a workspace missing a project and only then fail. Stopping means there is nothing to un-commit.

Two ways out, and which one is right depends on why the file does not parse:

• The configuration is broken by accident. Fix it. The message carries the compiler's own diagnostic, which usually names the option.
• The configuration is broken on purpose. Some repositories commit a broken tsconfig.json as a fixture — this workspace has one in codependix-examples, and repairing it would delete the only place that failure is demonstrated. Exclude the project instead, by adding its directory to an excludeFrom ignore file or an exclude glob. Exclusions are applied to the tsconfig.json before it is opened, so this really does keep the run away from it. Excluding the project's files does not: opening its configuration is the step that fails, and that happens first.

A run that traced nothing

Every gate above passed for having nothing to judge, so the run fails on its own emptiness. It is never a clean result. Work down this list:

1. Is the code excluded? exclude globs are additive to the built-in defaults, and excludeFrom files are easy to forget. An exclusion broad enough to cover every project empties the run.
2. Is --directories pointed where you think? It takes paths holding their own tsconfig.json, not project names.

A run that found no stacks

Not a failure. A run that traced real code and reported no findings is the normal outcome: the summary carries the callable, file, and edge counts that say it looked, and a repository under its limits has no stacks to name.

Whose problem a finding is

A depth or breadth row is a statement about the code, not about the configuration that measured it. The fix belongs in the code. Turn to the configuration only when the measurement itself is wrong — an entry-point rule missing, a cross-cutting logger inflating everything's numbers — and the callidescope-configure skill covers each of those.