@callidescope/nx 0.0.79 → 0.0.81

package/CHANGELOG.md

@@ -1,3 +1,31 @@
+## 0.0.81 (2026-11-11)
+
+### 🚀 Features
+
+- **codometer:** ✨ tighten the comment budgets and shorten every comment over them ([#2262](https://github.com/organizzolini/codebase/pull/2262), [#2261](https://github.com/organizzolini/codebase/issues/2261))
+
+### 🧱 Updated Dependencies
+
+- Updated callidescope-configuration to 0.0.80
+- Updated callidescope-output to 0.0.79
+- Updated callidescope-graph to 0.0.79
+- Updated callidescope-core to 0.0.79
+- Updated callidescope-cli to 0.0.80
+
+## 0.0.80 (2026-11-10)
+
+### 🚀 Features
+
+- **codometer:** ✨ gate JSDoc on every declaration kind and shorten long comments ([#2227](https://github.com/organizzolini/codebase/pull/2227), [#2226](https://github.com/organizzolini/codebase/issues/2226))
+
+### 🧱 Updated Dependencies
+
+- Updated callidescope-configuration to 0.0.79
+- Updated callidescope-output to 0.0.78
+- Updated callidescope-graph to 0.0.78
+- Updated callidescope-core to 0.0.78
+- Updated callidescope-cli to 0.0.79
+
 ## 0.0.79 (2026-11-10)
 
 ### 🧱 Updated Dependencies

package/dist/src/executors/breadth/executor.d.ts

@@ -2,12 +2,7 @@ import { ExecutorContext } from '@nx/devkit';
 
 /** Options the `depth` and `breadth` executors accept. */
 declare interface AddressExecutorOptions {
-    /**
-     * The callables to look up, each `<file>#<qualified-name>`.
-     *
-     * Plural to match the `--addresses` the command line takes, so one target
-     * run answers about a whole rename rather than one callable at a time.
-     */
+    /** The callables to look up, each `<file>#<qualified-name>`. Plural, so one run answers about a whole rename. */
     readonly addresses?: string[] | undefined;
     readonly configuration: string;
     readonly format?: string | undefined;
@@ -20,11 +15,7 @@ declare interface AddressExecutorOptions {
 }
 
 /**
- * Prints each named callable's direct callers and callees side by side — the two questions a rename or a refactor needs answered together.
- *
- * The addresses are resolved against the target's own project and its Nx
- * dependencies rather than the whole workspace, which is both faster than the
- * `callidescope breadth` command and the set the addresses actually belong to.
+ * Prints each named callable's direct callers and callees, resolved within the target's Nx scope.
  */
 declare function breadthExecutor(options: AddressExecutorOptions, context: ExecutorContext): Promise<{
     success: boolean;

package/dist/src/executors/depth/executor.d.ts

@@ -2,12 +2,7 @@ import { ExecutorContext } from '@nx/devkit';
 
 /** Options the `depth` and `breadth` executors accept. */
 declare interface AddressExecutorOptions {
-    /**
-     * The callables to look up, each `<file>#<qualified-name>`.
-     *
-     * Plural to match the `--addresses` the command line takes, so one target
-     * run answers about a whole rename rather than one callable at a time.
-     */
+    /** The callables to look up, each `<file>#<qualified-name>`. Plural, so one run answers about a whole rename. */
     readonly addresses?: string[] | undefined;
     readonly configuration: string;
     readonly format?: string | undefined;
@@ -20,11 +15,7 @@ declare interface AddressExecutorOptions {
 }
 
 /**
- * Prints every call stack above and below each named callable — every caller chain up to a root, every callee chain down to a leaf.
- *
- * The addresses are resolved against the target's own project and its Nx
- * dependencies rather than the whole workspace, which is both faster than the
- * `callidescope depth` command and the set the addresses actually belong to.
+ * Prints every call stack above and below each named callable, resolved within the target's Nx scope.
  */
 declare function depthExecutor(options: AddressExecutorOptions, context: ExecutorContext): Promise<{
     success: boolean;

package/dist/src/executors/gate/batch-executor.d.ts

@@ -2,25 +2,13 @@ import { ExecutorContext } from '@nx/devkit';
 import { TaskGraph } from '@nx/devkit';
 
 /**
- * Gates every task Nx batched for this executor from one trace.
- *
- * One `gate` task per project used to trace the whole workspace on its own, so
- * the cold run of a workspace of ~60 projects traced it ~60 times. A batch
- * traces the combined scope once and judges each task by its own project's
- * findings, so each still passes or fails alone and is still cached alone —
- * Nx hashes and replays batched tasks one by one. Tasks that name different
- * configuration files cannot share a trace, so they are batched per file.
+ * Gates every task Nx batched from one shared trace, judging each task by its own
+ * project's findings.
  */
 declare function gateBatchExecutor(...[taskGraph, options, overrides, context]: GateBatchExecutorArguments): Promise<Record<string, GateBatchTaskResult>>;
 export default gateBatchExecutor;
 
-/**
- * The four arguments Nx calls a batch executor with, in the order it passes them.
- *
- * A tuple rather than four parameters because Nx fixes that signature and the
- * workspace holds a function to three: the task graph, each task's resolved
- * options by task id, the overrides of the whole run, and the context.
- */
+/** Batch executor arguments: task graph, options, overrides, and context. */
 declare type GateBatchExecutorArguments = [
 taskGraph: TaskGraph,
 options: Record<string, GateExecutorOptions>,
@@ -28,13 +16,7 @@ overrides: GateExecutorOptions,
 context: ExecutorContext
 ];
 
-/**
- * What one task of a gate batch settled on.
- *
- * Nx's own type for a batch executor's result is not exported through
- * `@nx/devkit`, so this states the shape Nx reads back: whether the task
- * passed, and the output to show and to store with it in the cache.
- */
+/** One gate task's verdict and the output Nx caches. */
 declare interface GateBatchTaskResult {
     readonly success: boolean;
     readonly terminalOutput: string;

package/dist/src/executors/gate/executor.d.ts

@@ -1,22 +1,7 @@
 import { ExecutorContext } from '@nx/devkit';
 
 /**
- * Fails one project's task when its call stacks broke the limits it is held to.
- *
- * The gate rather than the trace: `trace` prints every stack in a project for
- * somebody reading it, and this prints only the stacks and callables that
- * decided the exit code, which is what a failed pipeline is asked to explain.
- *
- * Inferred onto every project holding a `tsconfig.json` that the workspace
- * configuration does not exclude, so `nx affected -t gate` gates a branch by
- * the projects it changed — and a project whose stacks got deeper is named by
- * the task that failed, which one workspace-wide task never could.
- *
- * With neither `projects` nor `tags` given, the selection is the project this
- * target belongs to, widened along the Nx dependency graph: a stack truncated
- * at a package boundary measures the wrong thing. The widening decides what is
- * traced and not what is judged — a dependency's breach fails the dependency's
- * own gate, which is the task named after the project that owns it.
+ * Fails one project's task when its call stacks break their limits. Prints only the deciding stacks.
  */
 declare function gateExecutor(options: GateExecutorOptions, context: ExecutorContext): Promise<{
     success: boolean;

package/dist/src/executors/trace/executor.d.ts

@@ -1,17 +1,7 @@
 import { ExecutorContext } from '@nx/devkit';
 
 /**
- * Traces one selection of Nx projects with callidescope.
- *
- * Inferred onto every project holding a `tsconfig.json`, so
- * `nx run-many -t callidescope-trace` covers the workspace,
- * `nx run-many -t callidescope-trace --projects=tag:type:package` covers a
- * category, and `nx affected -t callidescope-trace` covers only what changed
- * — none of which the workspace-wide command can do, and none of which needs
- * a flag of its own: selecting projects is what the task runner is for.
- *
- * With neither `projects` nor `tags` given, the selection is the project this
- * target belongs to.
+ * Traces one selection of Nx projects, defaulting to the target's own project when none are named.
  */
 declare function traceExecutor(options: TraceExecutorOptions, context: ExecutorContext): Promise<{
     success: boolean;

package/dist/src/index.d.ts

@@ -20,14 +20,11 @@ export declare class AddressModule {
 }
 
 /**
- * Answers `depth` and `breadth` about the callables it is named, inside a
- * resolved selection of Nx projects.
+ * Answers `depth` and `breadth` about the callables it is named, inside a resolved
+ * selection of Nx projects.
  *
- * The lookup itself is callidescope's — this only decides what it is asked
- * about. What the plugin adds is the scope: the CLI resolves an address
- * against the whole workspace, while here it is resolved against one project
- * and its Nx dependencies, which is both faster and the set the address
- * actually belongs to.
+ * The lookup is callidescope's. This adds the scope: the address resolves against one
+ * project and its Nx dependencies, which is faster and the set it belongs to.
  */
 export declare class AddressService {
     private readonly addressLookupService;
@@ -36,20 +33,13 @@ export declare class AddressService {
     private readonly breadthService;
     constructor(addressLookupService: AddressLookupService, addressReportService: AddressReportService, addressDepthService: AddressDepthService, breadthService: BreadthService);
     /**
-     * Matches one address against an already-traced selection, or explains why
-     * it could not be.
-     *
-     * The explanation is returned rather than logged: an executor's product is
-     * what it writes to stdout, and a reader looking at a failed task needs the
-     * reason in the same place the report would have been.
+     * Matches one address against a traced selection, or returns why it could not. Returned,
+     * not logged, so a failed task shows it.
      */
     private identify;
     /**
-     * Traces the selection, then matches every address against it.
-     *
-     * All or nothing, the way the command line is: a task that printed the
-     * addresses it understood and skipped the rest would report a partial
-     * answer under a `success` nobody asked it to qualify.
+     * Traces the selection, then matches every address against it. All or nothing,
+     * like the command line.
      */
     private locate;
     /** Prints each callable's direct callers and callees, side by side. */
@@ -87,25 +77,10 @@ export declare const DEFAULT_BREADTH_TARGET_NAME = "callidescope-breadth";
 /** Name of the inferred per-project depth-lookup target. */
 export declare const DEFAULT_DEPTH_TARGET_NAME = "callidescope-depth";
 
-/**
- * Name of the inferred per-project gate target.
- *
- * Named after what it decides rather than after what it measures. `trace`,
- * `depth`, and `breadth` all print something a reader asked for; this one is
- * the target here a pipeline is meant to read an exit code from, so it says
- * `gate`.
- */
+/** Inferred gate target, named for its verdict, which pipelines read. */
 export declare const DEFAULT_GATE_TARGET_NAME = "callidescope-restrict";
 
-/**
- * Names of the inferred per-project targets, when the registration names none.
- *
- * Prefixed defaults keep inferred tasks grouped and recognizable in Nx task
- * lists, and avoid collisions with generic names in workspaces carrying
- * several toolchains.
- *
- * Every one of them is overridable from the `nx.json` registration.
- */
+/** Default inferred target names; prefixed to group and avoid collisions. */
 export declare const DEFAULT_TRACE_TARGET_NAME = "callidescope-trace";
 
 /** A target this plugin infers onto a project. */
@@ -131,13 +106,7 @@ declare interface InferTargetsArguments {
 /** A loaded configuration, beside the path the loader settled on. */
 declare interface LoadedRunConfiguration {
     readonly configuration: ResolvedCallidescopeConfiguration;
-    /**
-     * Where the configuration was read from.
-     *
-     * The path the loader settled on rather than the one it was handed, since a
-     * relative path is resolved before it is read — and a run resolves a
-     * project's own configuration relative to it.
-     */
+    /** Where the configuration was read from: the path the loader settled on, since a relative one is resolved before reading. */
     readonly path: string;
 }
 
@@ -179,16 +148,7 @@ export declare interface LookupResult {
 export declare class MainModule {
 }
 
-/**
- * One Nx project, reduced to what a directory resolution needs of it.
- *
- * `codependix-nx-projects` declares a near-identical shape and reads it out of the
- * graph the same way. They are deliberately not shared: the two packages sit
- * in different toolchains, and `configuration/eslint.config.ts` lets this one
- * depend on nothing but `logging` precisely so `@nx/devkit` cannot spread. A
- * package extracted to hold both would have to be depended on by both, which
- * is the coupling that rule exists to prevent.
- */
+/** Nx project fields directory resolution needs; not shared, by design. */
 export declare interface NxProject {
     readonly name: string;
     /** Workspace-relative root, exactly as the Nx project graph states it. */
@@ -204,10 +164,7 @@ export declare class OptionsModule {
 /**
  * Narrows the untyped options object Nx hands a plugin.
  *
- * Nx passes whatever the consumer wrote in `nx.json` with no validation, so
- * every field is checked before use rather than cast. A bad value falls back
- * to its default: a typo in a target name should not stop the project graph
- * from being built.
+ * Nx passes unvalidated `nx.json` options, so every field is checked before use. A bad value falls back to its default, so a typo does not stop the project graph.
  */
 export declare class OptionsService {
     private readonly configurationService;
@@ -217,19 +174,13 @@ export declare class OptionsService {
     /** Reads a string field from an untrusted record, or `undefined`. */
     private readString;
     /**
-     * Reads the `configuration` option of an executor, refusing a missing one.
-     *
-     * Nx validates the option against `schema.json`, but a target written by hand
-     * reaches an executor unchecked, so the same refusal the plugin option gets —
-     * decided by the configuration layer — is applied here.
+     * Reads the `configuration` option of an executor, refusing a missing one, since
+     * hand-written targets skip `schema.json`.
      */
     readConfiguration(value: unknown): string;
     /**
-     * Narrows an untrusted output format to one callidescope renders.
-     *
-     * A target written by hand in a `project.json` bypasses the executor's
-     * `schema.json` enum, so an unrecognized value falls back to whatever the
-     * configuration chose rather than reaching the renderer.
+     * Narrows an untrusted output format to one callidescope renders, since hand-written targets
+     * bypass the `schema.json` enum.
      */
     readFormat(value: unknown): CallidescopeOutputFormat | undefined;
     /**
@@ -244,21 +195,13 @@ export declare class OptionsService {
         format: CallidescopeOutputFormat | undefined;
     };
     /**
-     * Reads a list of strings out of an executor's options.
-     *
-     * Nx validates an option against its `schema.json` before the executor sees
-     * it, but a target written by hand in a `project.json` reaches here
-     * unchecked, so a non-array or a list holding non-strings is narrowed rather
-     * than trusted. Entries are trimmed and the blanks dropped, so a trailing
-     * comma in `--projects a,b,` names two projects rather than three.
+     * Reads a list of strings from executor options, trimming entries and dropping blanks, so
+     * `a,b,` names two projects.
      */
     readStringList(value: unknown): string[];
     /**
-     * Resolves the effective plugin options from an untrusted value.
-     *
-     * Every field has a default except `configurationPath`: the workspace
-     * configuration is never searched for, so a registration that does not name
-     * it is refused rather than guessed at.
+     * Resolves the effective plugin options from an untrusted value. Only `configurationPath`
+     * has no default, and it is never searched for.
      */
     resolvePluginOptions(options: unknown): CallidescopePluginOptions;
 }
@@ -285,133 +228,54 @@ export declare class PluginService {
     private readonly verdictService;
     constructor(callidescopeService: CallidescopeService, configurationService: ConfigurationService, fileFilterService: FileFilterService, markdownReportService: MarkdownReportService, optionsService: OptionsService, projectsService: ProjectsService, runConfigurationService: RunConfigurationService, verdictService: VerdictService);
     /**
-     * Builds the predicate deciding which projects the workspace configuration
-     * keeps out of every trace.
-     *
-     * The run's own filter, built from the same two fields
-     * `WorkspaceService.discoverProjects` builds it from and asked the same
-     * question it asks — is this project's `tsconfig.json` excluded — so
-     * inference and discovery can never disagree about which projects a run
-     * covers.
-     *
-     * A configuration that cannot be loaded excludes nothing. This runs while Nx
-     * is building the project graph, where a thrown error stops every command in
-     * the workspace rather than one task; the executor loads the same file again
-     * and refuses there, where a refusal is about the run that asked for it.
+     * Builds the predicate for projects the workspace configuration excludes from every trace.
+     * A configuration that cannot load excludes nothing.
      */
     private buildExclusionFilter;
     /**
-     * Builds one project's targets, gate included unless it is excluded.
-     *
-     * An excluded project gets the three that print something and not the one
-     * that decides an exit code. Its own code is never traced — discovery drops
-     * it before its `tsconfig.json` is opened — so a gate there would own no
-     * finding at all and report green for a project it never read.
-     * `projects/ic-suite/callidescope/callidescope-examples` is the case: its fixtures exist to breach
-     * the limits, which is why `.callidescopeignore` names it.
-     *
-     * That sentence is what `runTrace`'s exemption from the unread rule keeps
-     * true: such a project reads nothing of its own by definition, so a trace
-     * failing on that would hand it a permanently red target.
+     * Builds one project's targets, with the gate only when the project is not excluded. An
+     * excluded gate would pass without reading anything.
      */
     private buildInferredTargets;
     /** Whether a project's directory holds a TypeScript program to trace. */
     private holdsProgram;
     /**
-     * Whether the workspace configuration excludes this project outright.
-     *
-     * The project's own `tsconfig.json` is the path asked about, because that is
-     * the path `WorkspaceService.discoverProjects` asks about — a project is
-     * excluded when the file that makes it a project is.
-     *
-     * Joined with `path.posix` rather than `path.join`, unlike `holdsProgram`
-     * beside it: a filter matches the workspace-relative POSIX paths git and the
-     * exclusion globs are written in, where `holdsProgram` hands `existsSync` a
-     * native absolute path.
+     * Whether the workspace configuration excludes this project, judged by its `tsconfig.json`
+     * path in POSIX form.
      */
     private isExcludedProject;
     /**
-     * Turns one traced outcome into the gate's result for the projects it judges.
-     *
-     * What to print comes from the verdict: the findings it judged, or, for a
-     * run that read nothing and so has none to show, the reason it failed. The
-     * one thing added to that verdict is the exit code for an unread judged
-     * project, which is the gate's alone — see `VerdictService.judge`.
+     * Turns one traced outcome into the gate's result, printing the verdict's findings or its
+     * reason. A gate alone fails unread projects.
      */
     private renderGateVerdict;
     /**
-     * States what a selection asked for that the workspace does not have.
-     *
-     * Both kinds of mistake are named at once, each beside the vocabulary it
-     * was drawn from, so a command line with two typos in it is two typos to
-     * fix rather than two runs.
+     * States what a selection asked for that the workspace does not have, naming every typo at once.
      */
     describeRefusedScope(scope: ResolvedTraceScope): string;
     /**
-     * Infers this plugin's targets onto every project holding a `tsconfig.json`.
-     *
-     * A project with no program of its own is skipped rather than given a target
-     * that would trace nothing — `callidescope` warns and moves on, so an
-     * inferred target there would be a permanently empty report. The
-     * workspace-root project is skipped for the opposite reason: it contains
-     * every other project, so its target would trace the whole workspace under
-     * one uncacheable task.
-     *
-     * Asynchronous because the gate is only inferred onto a project the
-     * workspace configuration does not exclude, and only that file can say which
-     * projects those are — see `buildExclusionFilter`, which is read once here
-     * rather than once per project for the same reason the plugin options are.
+     * Infers this plugin's targets onto every project holding a `tsconfig.json`, skipping the
+     * workspace root and projects without a program.
      */
     inferTargets(args: InferTargetsArguments): Promise<Map<string, InferredTargets>>;
     /**
-     * Resolves an executor's `projects`/`tags` selection into directories.
-     *
-     * The selection is widened along the Nx dependency graph unless asked not to
-     * be — see `ProjectsService.resolveDependencyClosure` for why a trace that
-     * stops at a project's own boundary measures the wrong thing. Two sets of
-     * directories come back for that reason: what the widened selection reads,
-     * and what the selection itself is answerable for.
+     * Resolves an executor's `projects`/`tags` selection into directories, widened along the Nx
+     * graph unless told not to.
      */
     resolveTraceScope(args: ResolveTraceScopeArguments): Promise<ResolvedTraceScope>;
     /**
-     * Traces the resolved directories and judges what it found against the
-     * limits every project in scope declared.
-     *
-     * The verdict is `judge`'s, which is where the rules are written; this
-     * chooses what to print for it — the findings it judged, or, for a run that
-     * read nothing and so has none to show, the reason it failed instead.
-     *
-     * The one thing it adds to that verdict is the exit code for an unread
-     * judged project, which is the gate's alone — see `judge`.
+     * Traces the resolved directories and judges the findings against each in-scope project's
+     * declared limits.
      */
     runGate(args: RunGateArguments): Promise<RunTraceResult>;
     /**
-     * Gates every task of a batch from one trace of their combined scope.
-     *
-     * Each gate used to trace the whole workspace on its own, so a run of ~60
-     * projects traced it ~60 times. The trace reads the union of the tasks'
-     * directories once, then every task is judged by `judge` on the projects it
-     * alone answers for, exactly as `runGate` judges one — a breach the shared
-     * trace found fails only the task whose project owns it, which is what keeps
-     * a batch's verdicts the same as the separate runs' would have been.
+     * Gates every task of a batch from one trace of their combined scope, judging each task by
+     * the projects it owns.
      */
     runGateBatch(args: RunGateBatchArguments): Promise<Record<string, RunTraceResult>>;
     /**
-     * Traces the resolved directories and renders the report.
-     *
-     * This is the whole of the "logic on top of core callidescope": the
-     * selection above is Nx's to resolve, and everything below this line is
-     * callidescope's own, reached through the same services the `callidescope`
-     * command uses rather than through a subprocess.
-     *
-     * Judged by the same predicate the gate is, so the two targets cannot come
-     * to disagree about what a passing run is. A run that read nothing keeps its
-     * report and gains the reason underneath it: a summary table of zeroes is
-     * what happened, not why it failed.
-     *
-     * The one rule the two act on differently: a judged project none of whose
-     * own files were read is **printed here and not failed on**, where a gate
-     * fails — see `judge` for why that is the one exemption.
+     * Traces the resolved directories and renders the report, judged by the gate's predicate.
+     * Unread projects print but do not fail.
      */
     runTrace(args: RunTraceArguments): Promise<RunTraceResult>;
 }
@@ -423,79 +287,35 @@ export declare class ProjectsModule {
 /**
  * Resolves Nx project names to the directories a callidescope run traces.
  *
- * This is the whole of callidescope's Nx awareness. `callidescope-cli` and
- * `callidescope-graph` know nothing about Nx and never read a project graph;
- * they take directories. What an Nx workspace has that plain paths do not is
- * a stable name for each of those directories, and turning one into the other
- * is the only thing this package is for.
- *
- * The project graph is passed in rather than read here, so every resolution
- * rule below is testable without a workspace to build a graph from —
- * `readProjectGraph` is the one method that touches Nx at run time.
+ * Only this part of callidescope knows about Nx. The project graph is passed in, so resolution is testable without a workspace.
  */
 export declare class ProjectsService {
     constructor();
     /** Every tag any project carries, sorted and deduplicated. */
     private readTags;
     /**
-     * Collects the names of every project carrying any of the given tags, and
-     * the tags nothing carries.
-     *
-     * Any of them rather than all of them. Nx tags come in families whose
-     * members are mutually exclusive on one project — nothing is both
-     * `type:application` and `type:package` — so requiring every tag would make
-     * the common selection resolve to nothing. Any is also the reading that
-     * composes: each tag widens the set, the way naming another project does.
+     * Collects projects carrying any of the given tags, and the tags nothing carries. Any, not all,
+     * since tag families exclude each other.
      */
     private resolveTaggedNames;
     /** Reads the workspace's Nx project graph. */
     readProjectGraph(): Promise<ProjectGraph>;
     /**
-     * Lists every project the graph knows, sorted by name.
-     *
-     * A project rooted at the workspace root is kept rather than filtered out.
-     * It resolves to `.`, which `--directories` accepts, and naming it is a
-     * caller saying they mean the root program — a different thing from
-     * omitting `--directories`, which walks the workspace for every
-     * `tsconfig.json` there is.
+     * Lists every project the graph knows, sorted by name, keeping the root project,
+     * which resolves to `.`.
      */
     readProjects(graph: ProjectGraph): NxProject[];
     /**
-     * Widens a set of project names to include everything they depend on.
-     *
-     * Dependencies, never dependents. A call stack runs downward — a command
-     * calls into the service it was injected with, which lives in a package it
-     * depends on — and those packages are what a trace of one project has to
-     * carry. Its dependents call *into* it and add no frames below it.
-     *
-     * This widens what the run is *scoped to*, not how far a stack runs:
-     * `WorkspaceService.walkImportedProjectClosure` already builds the program
-     * of every project the named directories transitively import. What the Nx
-     * graph adds is edges the compiler never read — an implicit dependency, or
-     * one that exists only at run time. Being scoped rather than merely reached
-     * costs nothing in this plugin, which writes nothing anywhere; it is the
-     * command-line host that acts on it, publishing a `README.md` section for a
-     * scoped project on a `--write` run.
-     *
-     * External `npm:` targets are dropped: they have no workspace directory to
-     * trace, and following them would mean tracing `node_modules`.
+     * Widens project names to their dependencies, not dependents, since stacks run downward.
+     * External `npm:` targets are dropped.
      */
     resolveDependencyClosure(args: {
         graph: ProjectGraph;
         projectNames: readonly string[];
     }): string[];
     /**
-     * Resolves Nx project names and tags to their workspace-relative roots.
-     *
-     * The two selections are unioned, not intersected: naming a project and
-     * naming a tag both widen what gets traced, and a project reached both ways
-     * is still one directory. Intersecting them would make `--tags` a filter on
-     * `--projects`, which would resolve to nothing whenever only one was given.
-     *
-     * Unknown names and unmatched tags are collected rather than dropped or
-     * thrown on, so one resolution reports every typo at once instead of one
-     * per run, and the caller decides whether a partial resolution is worth
-     * tracing.
+     * Resolves project names and tags to workspace-relative roots, merging them and collecting
+     * unknown names rather than throwing.
      */
     resolveDirectories(args: {
         graph: ProjectGraph;
@@ -503,12 +323,8 @@ export declare class ProjectsService {
         tags?: readonly string[] | undefined;
     }): ResolvedProjectDirectories;
     /**
-     * Resolves names and tags to the project names they stand for.
-     *
-     * Separate from `resolveDirectories` because a directory is the last step,
-     * not the only one: widening a selection along the Nx dependency graph
-     * happens between the two, and it happens in names, which is the only
-     * vocabulary the project graph speaks.
+     * Resolves names and tags to project names, kept separate from directories because widening
+     * happens in names.
      */
     resolveProjectNames(args: {
         graph: ProjectGraph;
@@ -534,7 +350,7 @@ export declare interface ResolvedProjectDirectories extends ResolvedProjectSelec
     readonly directories: string[];
 }
 
-/** What a set of Nx project names and tags resolved to, before directories. */
+/** Resolved project names and tags, before directories. */
 export declare interface ResolvedProjectSelection {
     /**
      * Every project name the graph knew, sorted — what a caller names back when
@@ -548,22 +364,9 @@ export declare interface ResolvedProjectSelection {
     readonly knownTags: string[];
     /** The projects the selection reached, sorted and deduplicated. */
     readonly projectNames: string[];
-    /**
-     * The names the project graph does not know, in the order they were given.
-     *
-     * Reported rather than dropped: a name nobody resolves is a trace that
-     * silently covers less than it was asked to, which is the one failure a
-     * report cannot show you.
-     */
+    /** Names the project graph does not know, in the order given. Reported, since a silently dropped name covers less than asked. */
     readonly unknownNames: string[];
-    /**
-     * The tags no project in the workspace carries, in the order they were
-     * given.
-     *
-     * Refused for the same reason an unknown name is: a tag matching nothing is
-     * far more often a typo than an empty category, and either way the run it
-     * would produce covers less than it was asked to without saying so.
-     */
+    /** Tags no project carries, in the order given. Refused like an unknown name, since a tag matching nothing is usually a typo. */
     readonly unmatchedTags: string[];
 }
 
@@ -577,14 +380,7 @@ export declare interface ResolvedTraceScope {
     readonly knownTags: string[];
     /** Every project the selection reached, including pulled-in dependencies. */
     readonly projectNames: string[];
-    /**
-     * Directories of the projects the selection itself named, before the
-     * dependency widening.
-     *
-     * What a verdict covers, where `directories` is what a trace reads: a
-     * dependency pulled in to keep a stack from stopping at a package boundary
-     * is measured by this run and judged by its own.
-     */
+    /** Directories of the projects the selection named, before dependency widening. What a verdict covers, not what a trace reads. */
     readonly selectedDirectories: string[];
     /** Names the workspace does not have. */
     readonly unknownNames: string[];
@@ -614,31 +410,20 @@ declare interface ResolveTraceScopeArguments {
 /**
  * Reads the callidescope configuration one run is judged by.
  *
- * Its own service rather than more of `PluginService`, because every target
- * here starts by reading the same file — the one its `configurationPath` names
- * — and none of them can be written until it is read. Keeping
- * it apart also keeps the verdict and the inference in `PluginService` beside
- * each other, which is where the rules a reader comes looking for are.
+ * Kept apart from `PluginService` because every target reads this file first. Keeping it
+ * separate leaves the verdict and inference together in `PluginService`.
  */
 declare class RunConfigurationService {
     private readonly configurationService;
     constructor(configurationService: ConfigurationService);
     /**
-     * Resolves and loads the configuration one run is judged by.
-     *
-     * The file-aware load rather than the plain one: a run resolves a
-     * configuration beside every project it reaches, and skips whichever file is
-     * already serving as this run's own.
+     * Resolves and loads the configuration one run is judged by, skipping whichever file is already
+     * this run's own.
      */
     load(args: LoadRunConfigurationArguments): Promise<LoadedRunConfiguration>;
 }
 
-/**
- * Arguments for gating one resolved selection against its limits.
- *
- * The trace's arguments without `format`: a gate's output is the findings that
- * decided its exit code, so there is no second rendering of it to ask for.
- */
+/** Trace arguments without `format`: a gate prints its findings. */
 declare type RunGateArguments = Omit<RunTraceArguments, "format">;
 
 /** Arguments for gating several tasks from one trace. */
@@ -649,7 +434,7 @@ declare interface RunGateBatchArguments {
     readonly workspaceRoot: string;
 }
 
-/** One task of a gate batch: the projects it reads and the ones it answers for. */
+/** Gate batch task: projects read, and projects answered for. */
 declare interface RunGateBatchTask {
     /** Workspace-relative directories the task's trace reads. */
     readonly directories: readonly string[];
@@ -666,18 +451,7 @@ declare interface RunTraceArguments {
     readonly directories: readonly string[];
     /** What the run prints. Defaults to markdown when omitted. */
     readonly format?: CallidescopeOutputFormat | undefined;
-    /**
-     * The projects whose findings decide the verdict.
-     *
-     * A subset of `directories`, which is what gets traced: a run reaches into
-     * the dependencies of what it was pointed at, and a finding there belongs
-     * to the task named after the project that owns it.
-     *
-     * Workspace-relative roots, because that is what callidescope calls a
-     * project name — `WorkspaceService.discoverProjects` names each project by
-     * the directory holding its `tsconfig.json`, and a report's `projectName`
-     * is that same string. An Nx project name would match nothing.
-     */
+    /** Projects whose findings decide the verdict: a subset of `directories`, named by callidescope's own project roots, not Nx names. */
     readonly judgedProjectNames: readonly string[];
     readonly workspaceRoot: string;
 }
@@ -688,94 +462,32 @@ export declare interface RunTraceResult {
     readonly report: string;
 }
 
-/**
- * What one predicate decided about a traced result.
- *
- * The findings come back with the verdict so the rendering shows what was
- * judged rather than what was measured — the two differ for every scoped run.
- *
- * `reason` carries the rendering a verdict owes the reader when the findings
- * cannot explain it themselves — a run that read nothing has no finding to
- * show, and a bare red task there is the guessing game this rule exists to
- * end.
- */
+/** One predicate's decision. `reason` explains what findings cannot. */
 declare interface RunVerdict {
     readonly findings: OwnedFindings;
     /** Whether every rule both targets share was cleared. */
     readonly ok: boolean;
     readonly reason: string | undefined;
-    /**
-     * Judged projects none of whose own files were read.
-     *
-     * Reported beside `ok` rather than folded into it, because this is the one
-     * rule the two targets act on differently: a `gate` fails on it, a `trace`
-     * prints it and passes. Every project the workspace configuration excludes
-     * reads nothing of its own and keeps its trace while losing its gate, so a
-     * trace failing here would be permanently red for being configured as asked.
-     * The rule itself still lives in one place — `PluginService.judge` — and only
-     * the consequence is the caller's.
-     */
+    /** Judged projects none of whose own files were read. A `gate` fails on this and a `trace` prints it and passes. */
     readonly unreadProjectNames: readonly string[];
 }
 
 /**
  * Decides whether a traced result passes, for every target that reads one.
  *
- * Its own service so one trace can be judged once per project: a batch of
- * gates traces the workspace a single time and asks this the same question of
- * each project, which is why a verdict takes the result and the projects to
- * judge rather than a trace to run.
+ * One trace serves a batch: this judges each project from the same result. A verdict takes the result and the projects to judge, not a trace to run.
  */
 declare class VerdictService {
     private readonly projectReportsService;
     constructor(projectReportsService: ProjectReportsService);
     /**
-     * The block a verdict owes the reader when its findings cannot explain it.
-     *
-     * Both targets print this and only one fails on it — see `judge` — because
-     * an unread project is a fact about the run either way. The unread projects
-     * come first when both apply: they name what went missing, where the
-     * whole-run reason can only say that something did.
+     * The block a verdict owes the reader when its findings cannot explain it. Unread projects come
+     * first, since they name what went missing.
      */
     explain(verdict: RunVerdict): string | undefined;
     /**
-     * Decides whether a traced result passes, for every target that reads one.
-     *
-     * One predicate rather than the same expression beside each caller, so a
-     * rule added here cannot reach one verdict and miss the other.
-     *
-     * **Only the projects the run was scoped to are judged.** A trace reaches
-     * into the dependencies of what it was pointed at, so judging the whole
-     * run's findings would fail `alpha`'s task for a breach in `beta`. The same
-     * line the publishing side already draws, one step further along:
-     * measurement reaches into dependencies, publishing does not, and judging
-     * does not either. A dependency's breach is its own gate's business, and
-     * `nx affected` selects it too when it changes, so nothing escapes a verdict.
-     *
-     * **A judged project none of whose own files were read is named back**, the
-     * case `callidescope`'s own `reportEmptyTrace` fails for the same reason: a
-     * gate that passes because it never looked reports the project as clean.
-     * Asked of each judged project rather than of the whole run, because
-     * narrowing made those two different questions — a project with dependencies
-     * has a non-empty run whatever became of its own sources, so its own
-     * `exclude` over-matching would otherwise leave it owning no finding and
-     * passing green. The whole run is asked too, for a run judging no project at
-     * all.
-     *
-     * It is the one rule whose **consequence** is the caller's rather than this
-     * predicate's, and so the one thing `unreadProjectNames` is returned beside
-     * `ok` for: a `gate` fails on it and a `trace` prints it and passes. Every
-     * project the workspace configuration excludes reads nothing of its own and
-     * is denied a gate while keeping its trace, so failing the trace too would
-     * make that project's target permanently red for being configured exactly as
-     * it was asked to be. Finding the projects stays here either way, so the
-     * rule cannot be applied to one verdict and forgotten by the other.
-     *
-     * **Depth is judged always, breadth wherever a limit exists** — not two
-     * modes to be selected between. `maximumDepth` has a default and
-     * `maximumBreadth` has none at any level, so a project declaring no breadth
-     * limit can produce no breadth finding to fail on. Reading the findings
-     * rather than naming a check is what keeps that true without a decision.
+     * Decides whether a traced result passes, judging only in-scope projects. Unread judged projects
+     * are named back to the caller.
      */
     judge(args: {
         judgedProjectNames: readonly string[];

package/package.json

@@ -4,11 +4,11 @@
     "url": "https://github.com/organizzolini/codebase/issues"
   },
   "dependencies": {
-    "@callidescope/cli": "0.0.78",
-    "@callidescope/configuration": "0.0.78",
-    "@callidescope/core": "0.0.77",
-    "@callidescope/graph": "0.0.77",
-    "@callidescope/output": "0.0.77",
+    "@callidescope/cli": "0.0.80",
+    "@callidescope/configuration": "0.0.80",
+    "@callidescope/core": "0.0.79",
+    "@callidescope/graph": "0.0.79",
+    "@callidescope/output": "0.0.79",
     "@nestjs/common": "^11.1.21 || ^12.0.1",
     "@nestjs/core": "^11.1.21 || ^12.0.1",
     "@nx/devkit": "^24.0.0",
@@ -80,5 +80,5 @@
     "strict": true
   },
   "types": "./dist/src/index.d.ts",
-  "version": "0.0.79"
+  "version": "0.0.81"
 }