@callidescope/output 0.0.77 → 0.0.79

package/CHANGELOG.md

@@ -1,3 +1,27 @@
+## 0.0.79 (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-graph to 0.0.79
+- Updated callidescope-core to 0.0.79
+
+## 0.0.78 (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-graph to 0.0.78
+- Updated callidescope-core to 0.0.78
+
 ## 0.0.77 (2026-11-10)
 
 ### 🧱 Updated Dependencies

package/dist/src/index.d.ts

@@ -37,10 +37,9 @@ export declare class AddressReportModule {
 /**
  * Renders `depth` and `breadth`'s findings for a terminal.
  *
- * Markdown by default and mermaid on request, the same two renderings
- * `callidescope` itself prints — a diagram at a prompt is source someone can
- * paste somewhere that draws it, and markdown is what reads well as terminal
- * text. JSON carries the same data with nothing rendered.
+ * Markdown by default, mermaid on request, as `callidescope` prints them.
+ * Mermaid is paste-ready source; markdown reads well as terminal text.
+ * JSON carries the same data unrendered.
  */
 export declare class AddressReportService {
     private readonly mermaidReportService;
@@ -61,21 +60,15 @@ export declare class AddressReportService {
     /** Renders one callable's direct callers and callees. */
     renderBreadth(args: RenderBreadthArguments): string;
     /**
-     * Renders several callables' direct calls as one document.
-     *
-     * JSON is **always** an array, whatever the address count, so a script can
-     * `JSON.parse` a run's output without branching on how many addresses it
-     * asked about. Markdown and mermaid concatenate the per-callable renders,
-     * each of which already carries its own heading naming the address.
+     * Renders several callables' direct calls as one document. JSON is always an array,
+     * whatever the address count.
      */
     renderBreadthReports(args: RenderBreadthReportsArguments): string;
     /** Renders the paths traced above and below one callable. */
     renderDepth(args: RenderDepthArguments): string;
     /**
-     * Renders several callables' traced paths as one document.
-     *
-     * JSON is **always** an array, for the same reason `renderBreadthReports`
-     * does it: one run, one parseable document, regardless of address count.
+     * Renders several callables' traced paths as one document. JSON is always an array,
+     * whatever the address count.
      */
     renderDepthReports(args: RenderDepthReportsArguments): string;
 }
@@ -134,25 +127,10 @@ export declare interface FindOwnedFindingsArguments {
     readonly reports: readonly ProjectReport[];
 }
 
-/**
- * The start marker of any anchored block this convention recognizes, not
- * just the one a given destination owns.
- *
- * Used to find where a corrupted block — a start marker with no matching
- * end — has to stop being replaced: at another block's own territory,
- * never past it.
- */
+/** Start marker of an anchored block. Replacement stops at other blocks. */
 export declare const FOREIGN_ANCHOR_PATTERN: RegExp;
 
-/**
- * Anything holding a frame list, whether or not it is a full `CallStack`.
- *
- * `ReportService.renderStackTree` and `MermaidReportService.renderStacks`
- * only ever read `frames`, so this is what they accept: a full `CallStack`
- * satisfies it, and so does a path with no depth or entry-point kind of its
- * own, such as one traced from an arbitrary address rather than a recognized
- * entry point.
- */
+/** Anything holding a frame list, such as a `CallStack`. */
 export declare interface FramedStack {
     readonly frames: readonly StackFrame[];
 }
@@ -166,13 +144,7 @@ export declare const HEADROOM_BUCKET_FOUR_PLUS = "4+";
 /** Bucket holding the projects one frame from their own limit. */
 export declare const HEADROOM_BUCKET_ONE = "1";
 
-/**
- * The order the scoreboard prints its buckets in, tightest first.
- *
- * A fixed list rather than the keys a run happened to produce, so a bucket
- * nothing fell into is still printed as a zero. "Nothing is over its limit" is
- * the row a reader came for, and an absent row cannot say it.
- */
+/** Scoreboard bucket order, tightest first. Fixed, so empty ones still print. */
 export declare const HEADROOM_BUCKET_ORDER: readonly ["over limit", "0 — at limit", "1", "2–3", "4+", "no stacks"];
 
 /** Bucket holding the projects whose deepest stack broke their own limit. */
@@ -181,26 +153,10 @@ export declare const HEADROOM_BUCKET_OVER_LIMIT = "over limit";
 /** Bucket holding the projects two or three frames from their own limit. */
 export declare const HEADROOM_BUCKET_TWO_TO_THREE = "2\u20133";
 
-/**
- * Bucket holding the projects that measured no stack at all.
- *
- * Named rather than folded into the widest headroom bucket: a project whose
- * deepest stack is zero is not a project with room to spare, it is a project
- * whose limit gates nothing, and those are opposite findings.
- */
+/** Bucket for projects with no stack. Such a limit gates nothing. */
 export declare const HEADROOM_BUCKET_UNMEASURED = "no stacks";
 
-/**
- * Structured values that belong beside a log line rather than inside it.
- *
- * Counts, percentages, and durations are the values that change on every
- * occurrence, so they are carried as fields: the message stays constant and
- * groupable in telemetry, and the numbers stay queryable instead of having to
- * be parsed back out of prose.
- *
- * The named members are the recurring ones; the index signature keeps the
- * argument open for whatever a given call site needs to attach.
- */
+/** Values beside the log line, kept as queryable fields. */
 declare interface LogData {
     [key: string]: unknown;
     /** How many things the operation handled. */
@@ -214,20 +170,10 @@ declare interface LogData {
 }
 
 /**
- * Transient-scoped logger so each injecting class gets its own instance.
- * Each consumer calls `setContext(ClassName.name)` to tag every log line
- * with the originating class. Backed by pino for structured JSON output in
- * production and human-readable pretty-print in development.
- *
- * Messages follow one grammar: an emoji naming the subject, a verb in present
- * progressive or past tense, then the object. Values that vary per call —
- * counts, percentages, durations — go in the `data` argument rather than the
- * message, so the message stays constant enough for telemetry to group on.
- *
- * ```ts
- * this.logger.info("📥 Downloading CSEL sources", undefined, { total: 428 });
- * this.logger.info("📥 Downloaded CSEL sources", undefined, { count: 412 });
- * ```
+ * Transient logger, so each injecting class gets its own instance. Consumers
+ * call `setContext(ClassName.name)`. Backed by pino: JSON in production,
+ * pretty-printed in development. Messages start with an emoji naming the subject,
+ * then a present or past-tense verb. Varying values such as counts go in `data`.
  */
 declare @Injectable({ scope: Scope.TRANSIENT })
 class LoggerService
@@ -245,12 +191,7 @@ implements LoggerServiceContract
     private static readonly isProduction =
     process.env["NODE_ENV"] === "production";
 
-    /**
-     * Built on first use, not when this file is evaluated.
-     *
-     * A destination fixed at import time could only ever be chosen by this
-     * package, since every consumer's own code runs after its imports.
-     */
+    /** Built lazily, so `logToStandardError` can still set the destination. */
     private static rootLogger: pino.Logger | undefined;
 
     /** Whether lines go to standard error instead of standard output. */
@@ -293,18 +234,8 @@ implements LoggerServiceContract
     }
 
     /**
-     * Sends every subsequent line to standard error instead of standard output.
-     *
-     * For a command-line application whose standard output *is* its result. A log
-     * line sharing that stream is not a diagnostic beside the data, it is a
-     * corruption of it. Call it before anything logs — the first statement of the
-     * application's bootstrap.
-     *
-     * A call after the first line warns and changes nothing: the destination is
-     * fixed when the pino instance is built, and tearing down a transport
-     * somebody is writing through would be worse than refusing. The warning is
-     * the point — silently leaving the lines on standard output is how a caller
-     * would ship a corrupted pipe without ever being told.
+     * Sends later lines to standard error, for a command whose stdout is its
+     * result. Call it first; later calls warn and change nothing.
      */
     static logToStandardError(): void {
         if (LoggerService.rootLogger !== undefined) {
@@ -318,10 +249,8 @@ implements LoggerServiceContract
     }
 
     /**
-     * Fails a malformed message in development, and never in production.
-     *
-     * A logger that throws in production turns an observability call into an
-     * outage, so the check runs only where a developer is present to fix it.
+     * Fails a malformed message in development only, since a throw in production
+     * would turn logging into an outage.
      */
     private assertConventionalMessage(args: {
         context: string | undefined;
@@ -381,11 +310,8 @@ implements LoggerServiceContract
     }
 
     /**
-     * Whether a word is a verb in one of the two tenses the convention allows.
-     *
-     * Present progressive means the operation is under way; past means it
-     * finished. Regular morphology covers both, so a new verb needs no
-     * registration anywhere — only irregular pasts are enumerated.
+     * Whether a word is a present-progressive or past-tense verb. Only irregular
+     * pasts need listing; regular morphology covers the rest.
      */
     private isConventionalVerb(word: string): boolean {
         const lowercased = word.toLowerCase();
@@ -461,11 +387,8 @@ implements LoggerServiceContract
     }
 
     /**
-     * Logs an error message at the `error` level, optionally including a stack trace.
-     *
-     * `ConsoleLogger.error` spends a third slot on a context string that the
-     * other levels do not have, so this one accepts either: a string keeps
-     * NestJS's meaning, an object is structured data like everywhere else.
+     * Logs at the `error` level. The second argument is a stack, the third a
+     * context string or structured data.
      */
     override error(
     message: unknown,
@@ -496,12 +419,8 @@ implements LoggerServiceContract
     }
 
     /**
-     * Logs an informational message at the `info` level.
-     *
-     * NestJS and `nest-commander` call this method directly as part of the
-     * framework's own `LoggerService` contract, so it must keep working
-     * exactly as before. Application code should call `info` instead — the
-     * same behavior under a name that says what level it logs at.
+     * Logs at the `info` level, as NestJS and `nest-commander` call it.
+     * Application code should call `info` instead.
      */
     override log(message: unknown, context?: string, data?: LogData): void {
         this.info(message, context, data);
@@ -532,7 +451,7 @@ implements LoggerServiceContract
     }
 }
 
-/** The public logger shape used to type test doubles without importing its service. */
+/** Public logger shape, for test doubles without the service. */
 declare interface LoggerServiceContract extends ConsoleLogger {
     /** Normalizes unknown errors into a stable message and timestamped log line. */
     buildErrorLogEntry(
@@ -547,23 +466,10 @@ declare interface LoggerServiceContract extends ConsoleLogger {
     info(message: unknown, context?: string, data?: LogData): void;
 }
 
-/**
- * Heading over the call stacks that ran deeper than their project allows.
- *
- * A constant rather than a literal because two renderings write it — the
- * whole-run report, and the findings-only rendering a gate prints — and a
- * reader who greps a failed pipeline for one of them must find the other.
- */
+/** Heading for stacks deeper than allowed, identical in both renderings. */
 export declare const MARKDOWN_DEEP_STACKS_HEADING = "Call stacks over the depth limit";
 
-/**
- * How each anchored destination draws the stacks it carries.
- *
- * One list rather than the pair written out at each of the two places a run
- * writes anchored blocks — its own and every project's — because the pairing is
- * the same fact both times, and two copies of it are two places for `mermaid`
- * to start printing trees.
- */
+/** How each anchored destination draws stacks. Keeps `mermaid` from printing trees. */
 export declare const MARKDOWN_DESTINATION_RENDERINGS: readonly [readonly ["markdown", "tree"], readonly ["mermaid", "diagram"]];
 
 /** Header of the depth-headroom scoreboard. */
@@ -584,9 +490,8 @@ export declare const MARKDOWN_WIDE_CALLABLES_HEADING = "Callables over the bread
 /**
  * Renders a run, or one project's slice of it, as markdown.
  *
- * Markdown rather than a bespoke text format because the same rendering has to
- * serve three places — a terminal, a report file, and a section spliced into a
- * project's own README — and only one of those can read anything else.
+ * Markdown serves a terminal, a report file, and a section spliced into a
+ * project's README alike. Only markdown reads well in all three.
  */
 export declare class MarkdownReportService {
     private readonly mermaidReportService;
@@ -594,40 +499,18 @@ export declare class MarkdownReportService {
     private readonly workspaceReportService;
     constructor(mermaidReportService: MermaidReportService, reportService: ReportService, workspaceReportService: WorkspaceReportService);
     /**
-     * Renders each callable's breadth, the first few openly and the rest
-     * behind a disclosure — the same treatment `renderStacks` gives stacks.
-     *
-     * Shared by both scopes: a project section passes every callable with a
-     * direct callee, unfiltered by any limit, the same way its stacks are;
-     * a whole-run section passes only the `WideCallableFinding`s that broke
-     * the configured limit. `WideCallableFinding` is a `CallableBreadthReport`
-     * with a `limit` added, so one renderer covers both without caring which
-     * it was handed. Unfiltered, a project's breadth table is one row per
-     * non-leaf callable — every bit as unbounded as its stacks — so it earns
-     * the same truncation rather than a bare table.
+     * Renders each callable's breadth, the first few openly and the rest behind a disclosure, shared
+     * by project and run sections.
      */
     private renderCallableBreadths;
     /**
-     * Renders one limit's value cell.
-     *
-     * A limit the project does not declare prints `none` rather than a number,
-     * which is breadth's usual case: it has no default at any level, so a
-     * project writing `maximumBreadth: undefined` is gated on breadth by nothing
-     * at all, and printing some number there would say the opposite.
+     * Renders one limit's value cell, printing `none` for an undeclared limit rather than a number
+     * that implies a gate.
      */
     private renderLimitCell;
     /**
-     * Renders the two limits one project is judged against.
-     *
-     * A project's block already carried its deepest stack and its widest
-     * callable; what it could not say is what either number is measured against.
-     * That was inferable while one workspace number gated everything and is not
-     * inferable now — the limit is a fact about this project, and fifty projects
-     * hold fifty answers.
-     *
-     * There is no origin column, because there is no second origin left: every
-     * traced project's configuration is complete, so both numbers are written in
-     * the file beside this readme or the run refused to start.
+     * Renders the two limits one project is judged against, since a limit is a fact about that
+     * project alone.
      */
     private renderProjectLimits;
     /** Renders one stack: a labelled heading line and its tree in a fence. */
@@ -639,87 +522,44 @@ export declare class MarkdownReportService {
     /** Renders a table, or says plainly that there was nothing to put in one. */
     private renderTable;
     /**
-     * Names each callable that broke its breadth limit, a line each.
-     *
-     * A line rather than `renderCallableBreadths`' table, and deliberately not
-     * that method reused: the table's columns say what a callable calls, and a
-     * finding's product is the number it broke. `limit` is per project now, so a
-     * reader cannot infer it from the run the way a single workspace-wide number
-     * could be inferred — it has to be printed beside the breadth it failed.
+     * Names each callable that broke its breadth limit, one line each, printing the project's `limit`
+     * beside it.
      */
     private renderWideCallableLines;
     /**
-     * The heading prefix one level below the block's own.
-     *
-     * Derived rather than fixed, so a block spliced under an `##` heading writes
-     * `###` subsections and stays a well-formed subtree of the file it landed
-     * in. A heading carrying no leading `#` at all yields `##`, which is the
-     * level these sections had before the heading was configurable.
+     * The heading prefix one level below the block's own, so a spliced block stays a well-formed
+     * subtree.
      */
     private subsectionPrefix;
     /**
-     * Renders the two findings a gate weighs, and nothing else.
-     *
-     * A gate prints why it decided rather than what it read: the full report is
-     * what a trace is for, and burying two deep stacks in a listing of every
-     * stack in the project is how a failed pipeline stops being read.
-     *
-     * Here rather than in the caller because rendering is this package's job,
-     * and because the headings are `renderRun`'s headings — written once, so a
-     * reader who greps a pipeline log for one rendering finds the other.
+     * Renders the two findings a gate weighs, and nothing else, so a failed pipeline shows why it
+     * decided.
      */
     renderFindings(args: RenderFindingsArguments): string;
     /** Renders one project's section, for splicing into its own README. */
     renderProjectSection(args: RenderProjectSectionArguments): string;
     /**
-     * Renders a whole run, for a terminal or a report file.
-     *
-     * Opens with what the run adds up to rather than with its findings: the
-     * summary, the per-project index, and the headroom each project has left.
-     * A workspace holding fifty projects is not readable as a list of
-     * callables, and every section below these three is one — so a reader
-     * arriving at this block learns which project to look at before being
-     * handed the stacks.
+     * Renders a whole run, for a terminal or a report file. Opens with the summary, the project index,
+     * and the headroom.
      */
     renderRun(args: RenderRunArguments): string;
     /**
-     * Renders every stack, the first few openly and the rest behind a disclosure.
-     *
-     * A package with two hundred stacks is still worth publishing in full — an
-     * agent reading the file can expand it, and a person scrolling past should
-     * not have to.
+     * Renders every stack, the first few openly and the rest behind a disclosure, so a large package
+     * stays complete.
      */
     renderStacks(args: RenderStacksArguments): string;
 }
 
-/**
- * Callables a diagram draws before it stops accepting stacks.
- *
- * GitHub refuses a mermaid block past 50,000 characters, and at roughly fifty
- * characters per node and edge this leaves room to spare — the widest project
- * here draws 263. Whole stacks are dropped rather than trimmed, so the diagram
- * never shows an edge into a callable it does not draw.
- */
+/** Callables a diagram draws, since GitHub caps mermaid at 50,000 characters. */
 export declare const MAXIMUM_DIAGRAM_NODES = 300;
 
-/**
- * Opens every diagram.
- *
- * Left to right, because that is the direction a stack reads and the direction
- * a wide, shallow call graph fits a page.
- */
+/** Opens every diagram left to right, the way a stack reads. */
 export declare const MERMAID_FLOWCHART_HEADER = "flowchart LR";
 
 /** What mermaid would read as syntax inside a node label. */
 export declare const MERMAID_LABEL_ESCAPES: ReadonlyMap<string, string>;
 
-/**
- * A diagram under construction.
- *
- * Mutable, and deliberately so: nodes and edges accumulate across every stack
- * drawn, and threading an immutable accumulator through that would say nothing
- * the name does not.
- */
+/** A diagram under construction. Mutable, since stacks add nodes and edges. */
 export declare interface MermaidDiagram {
     readonly edges: Set<string>;
     readonly identifiersByCallable: Map<CallableId, string>;
@@ -729,15 +569,10 @@ export declare interface MermaidDiagram {
 /**
  * Draws a set of call stacks as one mermaid flowchart.
  *
- * One diagram for all of them rather than one apiece, because a single stack
- * is a straight line and a straight line is a list with extra steps. Drawn
- * together the shared tails converge — every resolver ending in the same
- * service, every command reaching the same repository — and that convergence
- * is the thing a picture shows and an indented tree cannot.
+ * One diagram for all stacks, because shared tails converge there and that convergence is what a
+ * picture shows and an indented tree cannot.
  *
- * Labels carry the callable's name and nothing else. What it takes, returns,
- * and documents belongs to the tree rendering, which has room for it; a
- * diagram trying to carry all of that is unreadable at any size.
+ * Labels carry only the callable's name. Signatures and docs belong to the tree rendering.
  */
 export declare class MermaidReportService {
     constructor();
@@ -760,13 +595,7 @@ export declare class MermaidReportService {
     }): string;
 }
 
-/**
- * Frames a stack needs before a report carries it.
- *
- * Two, because a single frame is a callable that calls nothing — accurate, but
- * not a call stack, and there are twice as many of those as there are real
- * ones.
- */
+/** Fewest frames a reported stack needs; one frame is a callable. */
 export declare const MINIMUM_STACK_FRAMES = 2;
 
 /** Raised when the anchor helper is asked to write a file nothing named. */
@@ -796,19 +625,13 @@ export declare class OutputJsonService {
     /** Reads an existing report, returning an empty string if absent. */
     private readExisting;
     /**
-     * Renders the JSON report for the traced findings.
-     *
-     * Ends with a newline so the file matches what a formatter would leave
-     * behind, and so check mode does not fail over the one byte every other tool
-     * in the repository adds.
+     * Renders the JSON report for the traced findings, ending with a newline so formatters and check
+     * mode agree.
      */
     buildReport(args: BuildReportArguments): string;
     /**
-     * Syncs the configured JSON file with the current findings.
-     *
-     * In write mode the report is written, creating parent directories as
-     * needed. In check mode nothing is written and the return value reports
-     * whether the file already holds the current report.
+     * Syncs the configured JSON file with the findings: writes in write mode, and in check mode
+     * reports whether it is current.
      */
     sync(args: SyncJsonArguments): boolean;
 }
@@ -822,10 +645,9 @@ export declare class OutputMarkdownModule {
 /**
  * Splices a generated block into a markdown file, between two anchors.
  *
- * Staleness is decided by comparing the extracted block against the
- * regenerated one, byte for byte. A file with no anchors, or no file at all,
- * counts as stale rather than as an error, so check mode reports the same thing
- * whether the block drifted or was never written.
+ * Staleness compares the extracted block with the regenerated one, byte for byte.
+ * A missing file or anchor counts as stale, not as an error, so check mode
+ * reports drift and absence alike.
  */
 export declare class OutputMarkdownService {
     private readonly logger;
@@ -839,25 +661,13 @@ export declare class OutputMarkdownService {
     /** Reads a file, treating an absent one as empty. */
     private readExisting;
     /**
-     * Cuts out a start marker's corrupted span and splices the fresh block in.
-     *
-     * Reached only when the start marker is present but the block's own end
-     * marker cannot be found anywhere after it — the same file this
-     * convention lets stack several anchored blocks back to back, so
-     * everything is fair game to have drifted except one thing: another
-     * block's own anchors. The span is cut at the next such anchor, or at the
-     * end of the file when none follows, so the fresh block replaces exactly
-     * what belonged to this one and nothing that belonged to another.
+     * Cuts a start marker's corrupted span, up to the next anchor or end of file, and splices the
+     * fresh block in.
      */
     private replaceOrphanedBlock;
     /**
-     * Places the generated block into the file's current content.
-     *
-     * A pattern match replaces cleanly. No start marker at all falls back to
-     * appending, the historical behavior for a file never written to before.
-     * A start marker with no matching end can never satisfy the pattern —
-     * silently leaving it in place is what let a run claim success while
-     * changing nothing — so that span is cut out and replaced instead.
+     * Places the generated block: replaces a match, appends when no marker exists, and cuts a
+     * dangling start marker.
      */
     private spliceBlock;
     /** Builds the helpers a configured `writeBlock` function is handed. */
@@ -865,11 +675,8 @@ export declare class OutputMarkdownService {
     /** Syncs the configured markdown destination with the current findings. */
     sync(args: SyncMarkdownArguments): boolean;
     /**
-     * Splices the anchored block into a file.
-     *
-     * Appends the block when the anchors are absent, creates the file when it
-     * does not exist, and in check mode writes nothing and reports whether the
-     * file already holds the current block.
+     * Splices the anchored block into a file, appending or creating it as needed, and in check mode
+     * only reports drift.
      */
     syncAnchoredBlock(args: SyncAnchoredBlockArguments): boolean;
     /** Wraps content in the configured anchors. */
@@ -882,13 +689,13 @@ export declare interface OwnedFindings {
     readonly wideCallables: readonly WideCallableFinding[];
 }
 
-/** A message split into the emoji the console shows and the prose telemetry stores. */
+/** Message split into emoji and the prose telemetry stores. */
 declare interface ParsedLogMessage {
     emoji: string | undefined;
     text: string;
 }
 
-/** One project's row in the index, and the numbers the scoreboard buckets it by. */
+/** One project's index row and the scoreboard's bucketing numbers. */
 export declare interface ProjectIndexRow {
     readonly deepest: number;
     readonly headroom: number;
@@ -906,9 +713,8 @@ export declare class ProjectReportsModule {
 /**
  * Scopes a run's findings to the project each one came from.
  *
- * A section embedded in a project's README should describe that project, not
- * the workspace it happens to sit in, so everything here is keyed on the
- * project the entry point — or the reported callable — belongs to.
+ * A project's README section should describe that project, not the workspace it
+ * sits in, so everything is keyed on the owning project of the entry point or callable.
  */
 export declare class ProjectReportsService {
     private readonly pathsService;
@@ -927,75 +733,28 @@ export declare class ProjectReportsService {
     /** Reads the depth measured for one callable, or nothing if unmeasured. */
     private readDepth;
     /**
-     * Reads the limits one project is judged against.
-     *
-     * A project the lookup does not name falls back to the workspace's, which is
-     * what a project declaring nothing is given anyway — so a report arriving
-     * from outside the resolved set is judged rather than silently exempted.
+     * Reads the limits one project is judged against, falling back to the workspace's for a project
+     * the lookup does not name.
      */
     private readProjectLimits;
     /** Builds one report per project, in the order the projects were traced. */
     build(args: BuildProjectReportsArguments): ProjectReport[];
     /**
-     * Picks the stacks a run should fail on, deepest first.
-     *
-     * A filter over the stacks the reports already hold rather than a second
-     * traversal: reconstructing the same paths twice would let the number the
-     * gate fails on drift from the number the README publishes.
-     *
-     * Each project is judged against its own limit rather than one number for
-     * the whole workspace, so a stack deeper than the project that roots it
-     * allows is reported even when a noisier project elsewhere allows more.
-     * The stack is judged by the project owning its entry point, which is the
-     * project `build` already filed it under.
-     *
-     * `maximumDepth` is a positive integer, so a stack past it is at least two
-     * deep and therefore survived the minimum-frame filter above.
+     * Picks the stacks a run should fail on, deepest first, each judged against its owning project's
+     * own limit.
      */
     findDeepStacks(args: {
         limits: ProjectLimitsLookup;
         reports: readonly ProjectReport[];
     }): DeepStackFinding[];
     /**
-     * Picks the findings a named set of projects owns, and nothing else.
-     *
-     * For a run whose verdict covers fewer projects than its measurement did. A
-     * finding's owner is already decided — `build` files a stack under the
-     * project owning its entry point and a breadth report under the project
-     * declaring the callable — so this selects among those reports rather than
-     * deciding ownership a second way.
-     *
-     * A named project the reports do not hold contributes nothing rather than
-     * being an error: a run may be pointed at a project whose files it then
-     * found nothing in, and having read nothing is a fact for the caller's own
-     * rules to judge.
+     * Picks the findings a named set of projects owns, and nothing else. A named project with no
+     * reports contributes nothing.
      */
     findOwnedFindings(args: FindOwnedFindingsArguments): OwnedFindings;
     /**
-     * Picks the named projects a run opened no file of its own from.
-     *
-     * The companion to `findOwnedFindings`, and the reason it needs one: owning
-     * no finding is what a clean project and an unread one look like from the
-     * outside, and a caller judging only the findings cannot tell them apart.
-     * The project's own `fileCount` is what separates them — `collect` counts a
-     * file per project once the run's exclusions and the per-project ones have
-     * had their say, so a project whose files were all filtered away reports
-     * zero however much the rest of the run read.
-     *
-     * **Files rather than callables**, which is the weaker of the two questions
-     * and the right one. A project can hold files that declare no callable at
-     * all — one whose `tsconfig.json` names only its own configuration files and
-     * its tests is the shape, and this repository has five — and those were
-     * read, so a verdict on them is a verdict on something. Asking for a
-     * callable would fail every one of them for containing no functions, which
-     * is not a finding about anything. The cost is stated plainly: a project
-     * whose sources are excluded while a configuration file of its own survives
-     * counts as read.
-     *
-     * A named project with no report at all counts as unread rather than as an
-     * error, the same way `findOwnedFindings` treats one: a run pointed at a
-     * project the workspace configuration excludes never discovers it, and that
-     * is exactly the case worth failing.
+     * Picks the named projects a run opened no file of its own from, judged by their file count
+     * rather than callables.
      */
     findUnreadProjects(args: {
         /** The projects entitled to fail on what they own. */
@@ -1003,17 +762,8 @@ export declare class ProjectReportsService {
         reports: readonly ProjectReport[];
     }): string[];
     /**
-     * Picks the callables a run should fail on, widest first.
-     *
-     * A filter over the breadth reports the reports already hold, mirroring
-     * `findDeepStacks`, so the number the gate fails on cannot drift from the
-     * number the README publishes. A callable is judged by the project that
-     * declares it, which is the project `build` already filed it under.
-     *
-     * No default exists for `maximumBreadth`: until a configuration sets one,
-     * nothing can exceed it, so a project with no limit anywhere in its
-     * inheritance reports nothing rather than being judged against a number
-     * nobody chose.
+     * Picks the callables a run should fail on, widest first, each judged by its declaring project.
+     * No breadth limit means none fails.
      */
     findWideCallables(args: {
         limits: ProjectLimitsLookup;
@@ -1043,17 +793,7 @@ declare interface RenderDepthReportsArguments {
     readonly reports: readonly DepthReport[];
 }
 
-/**
- * Arguments for rendering only the findings a gate weighs.
- *
- * No `rendering`, unlike `RenderRunArguments`: a gate's product is the list of
- * things to go and fix, and a diagram of them is not that list.
- *
- * The findings themselves rather than the run that produced them, also unlike
- * `RenderRunArguments`: a scoped gate judges fewer findings than its trace
- * measured, and a renderer handed the whole run would print the ones it was
- * not judged on.
- */
+/** Arguments for rendering only the findings a gate weighs. */
 export declare interface RenderFindingsArguments extends OwnedFindings {
     readonly previewCount: number;
 }
@@ -1067,13 +807,7 @@ export declare interface RenderProjectIndexArguments {
 /** Arguments for rendering one project's section. */
 export declare interface RenderProjectSectionArguments {
     readonly heading: string;
-    /**
-     * The lookup the whole run resolved, rather than this project's two numbers.
-     *
-     * The renderer reads its own row out of it through the same `limitsFor` the
-     * index and the gate read, so a project's block and the workspace's view of
-     * that project cannot come to disagree about which limit applied.
-     */
+    /** The lookup the whole run resolved, so a project's block and the workspace's view of it cannot disagree on the limit. */
     readonly limits: ProjectLimitsLookup;
     readonly previewCount: number;
     readonly rendering: StackRendering;
@@ -1115,57 +849,35 @@ export declare class ReportFindingsModule {
 }
 
 /**
- * Weighs every finding a run can produce, and fails on the ones it was asked
- * to gate.
+ * Weighs every finding a run produces, failing on the ones it gates.
  *
- * Kept away from `CallidescopeCommand` itself, the same reason `RunPlanService`
- * is: what a run does with what it found is a question this service answers on
- * its own — through `this.logger` alone — leaving the command to orchestrate
- * the trace rather than weigh its output.
+ * Kept apart from `CallidescopeCommand`, as `RunPlanService` is: this service
+ * decides on its own what a run does with its findings, through `this.logger`,
+ * leaving the command to orchestrate the trace.
  */
 export declare class ReportFindingsService {
     private readonly logger;
     constructor(logger: LoggerService);
     /**
-     * Names the stacks that ran deeper than callidescope allows.
-     *
-     * Reported whether or not the run gates on them — a stack this long is worth
-     * saying out loud even in a run that only wrote a report — but only a run
-     * asked to fail on depth fails on it.
+     * Names the stacks that ran deeper than allowed. Reported whether or not the run gates on them;
+     * only a depth gate fails.
      */
     private reportDeepStacks;
     /**
-     * Fails a run that traced nothing at all.
-     *
-     * Unconditional, and not something `--check` turns on. Every other finding
-     * is a verdict on code that was read; this one says no code was read, and a
-     * gate that passes because it never looked is worse than one that fails —
-     * it reports the workspace as clean and there is nothing in the output to
-     * say otherwise.
+     * Fails a run that traced nothing at all, unconditionally, since a gate that never looked must
+     * not pass.
      */
     private reportEmptyTrace;
     /** Names the destinations that no longer hold what a fresh run would write. */
     private reportStaleness;
     /**
-     * Names the callables that called more things directly than callidescope
-     * allows.
-     *
-     * Reported whether or not the run gates on them, mirroring
-     * `reportDeepStacks` — but only a run asked to fail on breadth fails on it.
+     * Names the callables that call more things directly than allowed. Reported always; only a breadth
+     * gate fails on them.
      */
     private reportWideCallables;
     /**
-     * Weighs every finding a run can produce, and fails on any of them.
-     *
-     * They are weighed separately and announced separately. A stack that is too
-     * deep is something the code does; a callable calling too many things is
-     * something else the code does; a stale report is something the checkout
-     * has not caught up with. Reading one as another sends the author to fix
-     * the wrong thing.
-     *
-     * A project that could not be read never reaches here: it ends the trace
-     * before anything is printed or written, and is reported by
-     * `CallidescopeCommand` itself.
+     * Weighs every finding a run can produce and fails on any of them, announcing each kind
+     * separately so its fix is clear.
      */
     reportFindings(args: ReportFindingsArguments): void;
 }
@@ -1192,82 +904,36 @@ export declare class ReportService {
     /** Renders what a frame warns about: that it recurses, that it is on its way out. */
     private renderMarkers;
     /**
-     * Renders a callable's signature, collapsing one that is too long.
-     *
-     * The return type survives the collapse. Which twelve services a constructor
-     * takes is noise at the point where someone is reading a stack; what it hands
-     * back is not.
+     * Renders a callable's signature, collapsing a long one while keeping the return type.
      */
     private renderSignature;
     /**
-     * Shortens a summary to what fits under an indented frame.
-     *
-     * The opening sentence first, because a comment that runs long here is a
-     * short statement of what the callable does followed by paragraphs of why —
-     * and the first half is the half that orients someone reading a stack. It is
-     * printed whole and unmarked: it is a complete thought, not an elision, and
-     * the frame's `file:line` is already the pointer to the rest.
-     *
-     * Cutting at the character instead throws away a sentence boundary that was
-     * usually right there. Across this repository that happens to a fifth of
-     * printed summaries, whose opening sentences run about 64 characters at the
-     * median and 113 at the very longest.
-     *
-     * A single sentence longer than the limit has no boundary to find, so it is
-     * cut on a word — half a word reads as a typo rather than as an elision —
-     * and marked as cut short.
+     * Shortens a summary to fit an indented frame, keeping the opening sentence whole, or
+     * cutting on a word and marking it.
      */
     private shortenSummary;
     /**
-     * Renders every frame of a stack, the entry point first.
-     *
-     * Takes anything holding a frame list rather than a full `CallStack`: a
-     * depth or entry-point kind is never read here, so a caller with a path
-     * that has neither — an address-centered lookup, for one — does not have to
-     * fabricate one to call this.
+     * Renders every frame of a stack, entry point first, from anything holding a frame list, not only
+     * a full `CallStack`.
      */
     renderStackTree(stack: {
         frames: readonly StackFrame[];
     }): string;
 }
 
-/** Stands in for the workspace root when it is itself a traced project. */
+/** Names the workspace root when it is a traced project. */
 export declare const ROOT_PROJECT_LABEL = ".";
 
-/**
- * Ends a sentence, when the next one starts.
- *
- * A capital after the space is what separates a sentence break from `e.g. the`
- * or a dotted identifier, neither of which ends anything.
- */
+/** Sentence break: a capital must follow, so `e.g.` does not split. */
 export declare const SENTENCE_END_PATTERN: RegExp;
 
-/**
- * Characters of signature a frame prints before it collapses the parameters.
- *
- * Most signatures here are short — the median is under twenty characters — but
- * a NestJS constructor taking a dozen injected services runs past four hundred,
- * and one of those inside an indented stack destroys the shape that makes the
- * stack readable at all.
- */
+/** Signature characters a frame prints before parameters collapse. */
 export declare const SIGNATURE_LIMIT = 80;
 
-/**
- * How a report draws the stacks it found.
- *
- * Narrower than `CallidescopeOutputFormat` on purpose: `json` is a different
- * report rather than a different drawing of this one, and a renderer that had
- * to accept it would carry a case it can never answer.
- */
+/** How a report draws stacks. Excludes `json`, which is no drawing. */
 export declare type StackRendering = "diagram" | "tree";
 
-/**
- * Characters of documentation prose a printed frame keeps.
- *
- * A summary is meant to orient a reader mid-stack, not to replace opening the
- * file, and a paragraph indented under ten frames is worse than a sentence.
- * Only the tree is bound by this — the JSON report carries the whole comment.
- */
+/** Documentation characters a printed frame keeps. JSON keeps all of it. */
 export declare const SUMMARY_LIMIT = 120;
 
 /** Introduces the documentation line printed under a frame. */
@@ -1288,19 +954,9 @@ export declare interface SyncDestinationsArguments {
     /** The depth and breadth limits each traced project is judged against. */
     readonly projectLimits: ProjectLimitsLookup;
     readonly result: CallGraphResult;
-    /**
-     * Workspace-relative root of each project the run was scoped to, keyed by
-     * name. Only these projects have a section published, so a scoped run never
-     * writes into a dependency it merely measured.
-     */
+    /** Root of each scoped project, keyed by name. Only these get a published section, never a measured-only dependency. */
     readonly startingProjectRoots: ReadonlyMap<string, string>;
-    /**
-     * The written destinations each project declared for itself, by name.
-     *
-     * Every traced project declares a complete configuration, so every one of
-     * them is named here — a project publishing nothing wrote `markdown:
-     * undefined` rather than being absent.
-     */
+    /** Destinations each project declared, by name. A project publishing nothing names `markdown: undefined`, never absence. */
     readonly writeByProject: ReadonlyMap<string, ResolvedCallidescopeWriteConfiguration>;
 }
 
@@ -1309,12 +965,7 @@ export declare interface SyncJsonArguments extends BuildReportArguments {
     readonly check: boolean;
 }
 
-/**
- * Arguments for syncing the configured markdown destination.
- *
- * The rendered markdown arrives already built: what a report says belongs to
- * the report module, and this one only decides where it lands.
- */
+/** Arguments for syncing the markdown destination, already rendered. */
 export declare interface SyncMarkdownArguments {
     readonly check: boolean;
     readonly content: string;
@@ -1339,44 +990,24 @@ export declare interface SyncProjectSectionsArguments {
 export declare const TRUNCATION_SUFFIX = "\u2026";
 
 /**
- * Renders what a whole run says about the projects in it, rather than about
- * one callable or one stack.
- *
- * Its own service because it answers a question the rest of the report cannot.
- * Every other section names callables — a stack, a spread, a wide callable —
- * and a workspace holding fifty projects is not readable as a list of
- * callables. These two sections are the index and the scoreboard: which
- * project holds what, and how much room each has left before its own limit
- * stops it.
+ * Renders what a whole run says about the projects in it.
  *
- * Both are keyed on a project's own resolved limit rather than one workspace
- * number. A limit pinned by the single worst stack anywhere in a repository
- * gates nothing for the projects nowhere near it, which is the whole reason
- * limits resolve per project — so a report that showed one number would be
- * describing a model the tool no longer has.
+ * Two sections: the index and the scoreboard, showing which project holds what
+ * and how much room each has before its own limit stops it. Both key on each
+ * project's resolved limit.
  */
 export declare class WorkspaceReportService {
     constructor();
     /**
-     * Sorts a project's headroom into the bucket the scoreboard counts it under.
-     *
-     * A project measuring nothing is its own bucket rather than a large
-     * headroom, and that distinction is the point of having the scoreboard at
-     * all: a project whose deepest stack is zero has every frame of its limit
-     * unused, which reads as the safest row in the table while actually being
-     * the one row where the limit gates nothing. Bucketing it by `limit - 0`
-     * would file the least-gated projects among the healthiest.
+     * Sorts a project's headroom into its scoreboard bucket. A project measuring nothing gets its own
+     * bucket, not a large headroom.
      */
     private bucketFor;
     /** The widest single callable a project declares, or zero when it has none. */
     private widestBreadth;
     /**
-     * Reads each project's report and its resolved limits into one row.
-     *
-     * Public so both sections render from the same rows rather than each
-     * deriving them: the scoreboard counts exactly the rows the index lists, and
-     * two derivations of "headroom" that could disagree would be worse than one
-     * that is merely wrong.
+     * Reads each project's report and resolved limits into one row, so both sections render from the
+     * same rows.
      */
     buildRows(args: RenderProjectIndexArguments): ProjectIndexRow[];
     /** The limits one project resolved to, or the workspace's when unlisted. */
@@ -1385,21 +1016,13 @@ export declare class WorkspaceReportService {
         projectName: string;
     }): ProjectLimits;
     /**
-     * Counts how many projects sit in each headroom bucket.
-     *
-     * The index says what every project holds; this says what the set of them
-     * adds up to, which is the number a ratchet is actually lowered against. A
-     * bucket nothing falls into is still printed, because "nothing is over its
-     * limit" is the row a reader is looking for and an absent row cannot say it.
+     * Counts how many projects sit in each headroom bucket. Empty buckets are still printed, since
+     * 'nothing over its limit' must show.
      */
     renderHeadroom(rows: readonly ProjectIndexRow[]): string;
     /**
-     * Renders one row per project: what it measured, and what it is held to.
-     *
-     * `Limit` is a bare number now. It used to carry `declared` or `inherited`
-     * beside it, and with every traced project's configuration complete only one
-     * of those two is reachable — a column with one value in every row is worse
-     * than no column.
+     * Renders one row per project: what it measured, and its limit as a bare number, since only one
+     * origin is reachable.
      */
     renderProjectIndex(args: RenderProjectIndexArguments): string;
 }
@@ -1419,11 +1042,8 @@ export declare class WriteDestinationsModule {
 /**
  * Writes a finished run to every destination it was configured with.
  *
- * Its own service rather than more of the command, because the two answer
- * different questions: the command decides whether a run may write at all, and
- * this decides where what it found lands. There are two answers to that second
- * question — the workspace's own declarations and each project's — and keeping
- * them side by side is what stops one writing over the other.
+ * Kept apart from the command: the command decides whether a run may write, and this decides where
+ * the findings land, for both the workspace and each project.
  */
 export declare class WriteDestinationsService {
     private readonly markdownReportService;
@@ -1431,16 +1051,8 @@ export declare class WriteDestinationsService {
     private readonly outputMarkdownService;
     constructor(markdownReportService: MarkdownReportService, outputJsonService: OutputJsonService, outputMarkdownService: OutputMarkdownService);
     /**
-     * Writes the destinations each project declared for itself, returning the
-     * stale ones.
-     *
-     * A path is read relative to that project's own root, which is what keeps a
-     * project's declaration about its own documents rather than about the
-     * repository's — a project cannot write into a sibling by declaring one.
-     *
-     * Only the projects a run was scoped to are published: a dependency measured
-     * through the closure has its own run to publish it, and this one was never
-     * pointed at it.
+     * Writes the destinations each project declared for itself, returning the stale ones.
+     * Paths are relative to each project's own root.
      */
     private syncProjectDestinations;
     /** Writes one project's declared destinations, returning the stale ones. */

package/package.json

@@ -4,9 +4,9 @@
     "url": "https://github.com/organizzolini/codebase/issues"
   },
   "dependencies": {
-    "@callidescope/configuration": "0.0.78",
-    "@callidescope/core": "0.0.77",
-    "@callidescope/graph": "0.0.77",
+    "@callidescope/configuration": "0.0.80",
+    "@callidescope/core": "0.0.79",
+    "@callidescope/graph": "0.0.79",
     "@nestjs/common": "^11.1.21 || ^12.0.1",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
@@ -63,5 +63,5 @@
     "strict": true
   },
   "types": "./dist/src/index.d.ts",
-  "version": "0.0.77"
+  "version": "0.0.79"
 }