@callidescope/output 0.0.0-stage → 0.0.4

package/dist/src/index.d.ts

@@ -0,0 +1,1434 @@
+import { BreadthMeasurement } from '@callidescope/graph';
+import { CallableDirectCalls } from '@callidescope/graph';
+import { CallableId } from '@callidescope/core';
+import { CallAddressTreeResult } from '@callidescope/graph';
+import { CallGraph } from '@callidescope/graph';
+import { CallGraphResult } from '@callidescope/core';
+import { CallidescopeOutputFormat } from '@callidescope/configuration';
+import { CallStack } from '@callidescope/core';
+import { CondensedGraph } from '@callidescope/graph';
+import { ConsoleLogger } from '@nestjs/common';
+import { DeepStackFinding } from '@callidescope/core';
+import { DepthMeasurement } from '@callidescope/graph';
+import { DiscoveredCallable } from '@callidescope/graph';
+import { EntryPointCollection } from '@callidescope/graph';
+import { MarkdownAnchorHelpers } from '@callidescope/configuration';
+import { PathsService } from '@callidescope/graph';
+import pino from 'pino';
+import { ProjectLimits } from '@callidescope/configuration';
+import { ProjectLimitsLookup } from '@callidescope/configuration';
+import { ProjectReport } from '@callidescope/core';
+import { ResolvedCallidescopeConfiguration } from '@callidescope/configuration';
+import { ResolvedCallidescopeJsonOutputConfiguration } from '@callidescope/configuration';
+import { ResolvedCallidescopeMarkdownOutputConfiguration } from '@callidescope/configuration';
+import { ResolvedCallidescopeWriteConfiguration } from '@callidescope/configuration';
+import { RunMode } from '@callidescope/configuration';
+import { SignaturesService } from '@callidescope/graph';
+import { SourceLocation } from '@callidescope/core';
+import { StackFrame } from '@callidescope/core';
+import { WideCallableFinding } from '@callidescope/core';
+
+/**
+ * NestJS module that wires `depth` and `breadth`'s terminal rendering.
+ */
+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.
+ */
+export declare class AddressReportService {
+    private readonly mermaidReportService;
+    private readonly reportService;
+    constructor(mermaidReportService: MermaidReportService, reportService: ReportService);
+    /** The JSON shape of one callable's direct calls. */
+    private buildBreadthPayload;
+    /** The JSON shape of one callable's traced paths. */
+    private buildDepthPayload;
+    /** Draws every callee and caller as one diagram, the target as a stadium. */
+    private renderBreadthDiagram;
+    /** Renders one direction's paths as headed, fenced trees. */
+    private renderDepthStacks;
+    /** Renders one list of direct callees or callers as a markdown table. */
+    private renderReferenceTable;
+    /** Turns a callable reference into a frame the diagram renderer can draw. */
+    private toFrame;
+    /** 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.
+     */
+    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.
+     */
+    renderDepthReports(args: RenderDepthReportsArguments): string;
+}
+
+/** One callable's direct callers and callees, without the run-level format. */
+export declare interface BreadthReport {
+    readonly address: string;
+    readonly directCalls: CallableDirectCalls;
+    readonly displayName: string;
+    readonly id: CallableId;
+    readonly location: SourceLocation;
+}
+
+/** Arguments for scoping a run's findings to each project that produced them. */
+export declare interface BuildProjectReportsArguments {
+    readonly breadthMeasurement: BreadthMeasurement;
+    readonly callablesById: ReadonlyMap<CallableId, DiscoveredCallable>;
+    readonly condensed: CondensedGraph;
+    readonly entryPoints: EntryPointCollection;
+    readonly fileCountByProject: ReadonlyMap<string, number>;
+    readonly graph: CallGraph;
+    readonly measurement: DepthMeasurement;
+    readonly projectNames: readonly string[];
+}
+
+/** Arguments for rendering the JSON report. */
+export declare interface BuildReportArguments {
+    readonly destination: ResolvedCallidescopeJsonOutputConfiguration;
+    readonly result: CallGraphResult;
+}
+
+/** Stands in for a parameter list too long to print. */
+export declare const COLLAPSED_PARAMETERS = "(\u2026)";
+
+/** Marks a frame whose callable is on its way out. */
+export declare const DEPRECATED_MARKER = "\u26A0 deprecated";
+
+/** One callable's traced paths, without the run-level format. */
+export declare interface DepthReport {
+    readonly address: string;
+    readonly downward: CallAddressTreeResult;
+    readonly upward: CallAddressTreeResult;
+}
+
+/** Prefix of every generated node identifier. */
+export declare const DIAGRAM_NODE_PREFIX = "n";
+
+/** Marks the first frame of a printed call stack. */
+export declare const ENTRY_FRAME_PREFIX = "\uD83D\uDE80";
+
+/** Arguments for picking the findings a named set of projects owns. */
+export declare interface FindOwnedFindingsArguments {
+    readonly limits: ProjectLimitsLookup;
+    /** The projects entitled to fail on what they own. */
+    readonly projectNames: readonly string[];
+    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.
+ */
+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.
+ */
+export declare interface FramedStack {
+    readonly frames: readonly StackFrame[];
+}
+
+/** Bucket holding the projects sitting exactly on their own limit. */
+export declare const HEADROOM_BUCKET_AT_LIMIT = "0 \u2014 at limit";
+
+/** Bucket holding the projects with room to spare. */
+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.
+ */
+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. */
+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.
+ */
+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.
+ */
+declare interface LogData {
+    [key: string]: unknown;
+    /** How many things the operation handled. */
+    count?: number;
+    /** Wall-clock milliseconds the operation took. */
+    durationMs?: number;
+    /** Completion between 0 and 100. */
+    percent?: number;
+    /** How many things the operation set out to handle. */
+    total?: number;
+}
+
+/**
+ * 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 });
+ * ```
+ */
+declare @Injectable({ scope: Scope.TRANSIENT })
+class LoggerService extends ConsoleLogger {
+    // 🏗 Dependency Injection
+
+    constructor() {
+        super();
+    }
+
+    // 🔐 Private Fields
+
+    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.
+     */
+    private static rootLogger: pino.Logger | undefined;
+
+    /** Whether lines go to standard error instead of standard output. */
+    private static writesToStandardError = false;
+
+    private child: pino.Logger = LoggerService.root;
+
+    // 🔑 Public Fields
+
+    // 🔏 Private Methods
+
+    /** Build the pino instance for production or local development output. */
+    private static createRootLogger(): pino.Logger {
+        const level = process.env["LOG_LEVEL"] ?? "info";
+
+        if (LoggerService.isProduction) {
+            return LoggerService.writesToStandardError
+            ? pino({ level }, pino.destination(STANDARD_ERROR_DESCRIPTOR))
+            : pino({ level });
+        }
+
+        return pino({
+            level,
+            transport: {
+                options: {
+                    colorize: true,
+                    destination: LoggerService.writesToStandardError
+                    ? STANDARD_ERROR_DESCRIPTOR
+                    : STANDARD_OUTPUT_DESCRIPTOR,
+                    // The emoji is a field, not part of the message, so the console can
+                    // show it while telemetry stores unadorned prose. `ignore` then keeps
+                    // it from being printed a second time in the trailing object.
+                    ignore: "pid,hostname,emoji",
+                    messageFormat: "{emoji} {msg}",
+                    singleLine: true,
+                },
+                target: "pino-pretty",
+            },
+        });
+    }
+
+    /**
+     * 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.
+     */
+    static logToStandardError(): void {
+        if (LoggerService.rootLogger !== undefined) {
+            process.emitWarning(
+            "LoggerService.logToStandardError() was called after the first log line, so log lines still go to standard output and anything piping that stream will read them as data. Call it as the first statement of the application's bootstrap.",
+            );
+            return;
+        }
+
+        LoggerService.writesToStandardError = true;
+    }
+
+    /**
+     * 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.
+     */
+    private assertConventionalMessage(args: {
+        context: string | undefined;
+        parsed: ParsedLogMessage;
+    }): void {
+        if (
+        LoggerService.isProduction ||
+        this.shouldSkipConventionalMessageValidation(args.context)
+        ) {
+            return;
+        }
+
+        const violation = this.getConventionalMessageViolation(args.parsed);
+
+        if (violation !== undefined) {
+            throw new Error(violation);
+        }
+    }
+
+    /** Assembles the object pino merges into the line. */
+    private buildBindings(args: {
+        context: string | undefined;
+        data: LogData | undefined;
+        parsed: ParsedLogMessage;
+    }): Record<string, unknown> {
+        this.assertConventionalMessage({
+            context: args.context,
+            parsed: args.parsed,
+        });
+
+        return {
+            ...args.data,
+            context: args.context,
+            // Telemetry gets prose; only the console-bound transport reads this.
+            ...(LoggerService.isProduction ? {} : { emoji: args.parsed.emoji }),
+        };
+    }
+
+    /** Returns a human-readable explanation when the message format is invalid. */
+    private getConventionalMessageViolation(
+    parsed: ParsedLogMessage,
+    ): string | undefined {
+        const emoji = parsed.emoji;
+        const text = parsed.text;
+
+        if (emoji === undefined) {
+            return `Log message must start with an emoji naming its subject, then a verb: "${text}"`;
+        }
+
+        const firstWord = FIRST_WORD_PATTERN.exec(text)?.[1];
+
+        if (firstWord === undefined || !this.isConventionalVerb(firstWord)) {
+            return `Log message must begin with a verb in present progressive or past tense, got "${firstWord ?? ""}": "${emoji} ${text}"`;
+        }
+
+        return undefined;
+    }
+
+    /**
+     * 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.
+     */
+    private isConventionalVerb(word: string): boolean {
+        const lowercased = word.toLowerCase();
+
+        return (
+        lowercased.endsWith("ing") ||
+        lowercased.endsWith("ed") ||
+        IRREGULAR_PAST_VERBS.has(lowercased)
+        );
+    }
+
+    /** Splits a leading emoji off a message, leaving prose behind. */
+    private parseMessage(message: unknown): ParsedLogMessage {
+        const text = String(message);
+        const match = LEADING_EMOJI_PATTERN.exec(text);
+        const emoji = match?.[1];
+
+        return emoji === undefined
+        ? { emoji: undefined, text }
+        : { emoji, text: text.slice(match?.[0].length) };
+    }
+
+    /** Whether a context is intentionally exempt from the validation rule. */
+    private shouldSkipConventionalMessageValidation(
+    context: string | undefined,
+    ): boolean {
+        return context !== undefined && UNVALIDATED_LOG_CONTEXTS.has(context);
+    }
+
+    // 🌎 Public Methods
+
+    /** The pino instance every logger's child is taken from. */
+    private static get root(): pino.Logger {
+        LoggerService.rootLogger ??= LoggerService.createRootLogger();
+
+        return LoggerService.rootLogger;
+    }
+
+    /** Normalizes unknown errors into a stable message and timestamped log line. */
+    buildErrorLogEntry(
+    context: string,
+    error: unknown,
+    ): { errorMessage: string; logLine: string } {
+        const errorMessage =
+        error instanceof Error ? error.stack || error.message : String(error);
+
+        return {
+            errorMessage,
+            logLine: `[${new Date().toISOString()}] ${context}: ${errorMessage}\n`,
+        };
+    }
+
+    /** Builds a timestamped output log file path and ensures the output directory exists. */
+    createTimestampedOutputLogFilePath(filePrefix: string): string {
+        const outputDirectory = path.join(process.cwd(), "output");
+        if (!existsSync(outputDirectory)) {
+            mkdirSync(outputDirectory, { recursive: true });
+        }
+
+        return path.join(
+        outputDirectory,
+        `${filePrefix}-${new Date().toISOString().replaceAll(/[:.]/g, "-")}.log`,
+        );
+    }
+
+    /** Logs a debug message at the `debug` level. */
+    override debug(message: unknown, context?: string, data?: LogData): void {
+        const parsed = this.parseMessage(message);
+        this.child.debug(
+        this.buildBindings({ context: context ?? this.context, data, parsed }),
+        parsed.text,
+        );
+    }
+
+    /**
+     * 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.
+     */
+    override error(
+    message: unknown,
+    stackOrContext?: string,
+    contextOrData?: LogData | string,
+    ): void {
+        const parsed = this.parseMessage(message);
+        const data = typeof contextOrData === "object" ? contextOrData : undefined;
+        const context =
+        typeof contextOrData === "string" ? contextOrData : this.context;
+
+        this.child.error(
+            {
+            ...this.buildBindings({ context, data, parsed }),
+            stack: stackOrContext,
+        },
+        parsed.text,
+        );
+    }
+
+    /** Logs an informational message at the `info` level. */
+    info(message: unknown, context?: string, data?: LogData): void {
+        const parsed = this.parseMessage(message);
+        this.child.info(
+        this.buildBindings({ context: context ?? this.context, data, parsed }),
+        parsed.text,
+        );
+    }
+
+    /**
+     * 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.
+     */
+    override log(message: unknown, context?: string, data?: LogData): void {
+        this.info(message, context, data);
+    }
+
+    /** Sets the context label included in every subsequent log line. */
+    override setContext(context: string): void {
+        super.setContext(context);
+        this.child = LoggerService.root.child({ context });
+    }
+
+    /** Logs a verbose message at the `trace` level. */
+    override verbose(message: unknown, context?: string, data?: LogData): void {
+        const parsed = this.parseMessage(message);
+        this.child.trace(
+        this.buildBindings({ context: context ?? this.context, data, parsed }),
+        parsed.text,
+        );
+    }
+
+    /** Logs a warning message at the `warn` level. */
+    override warn(message: unknown, context?: string, data?: LogData): void {
+        const parsed = this.parseMessage(message);
+        this.child.warn(
+        this.buildBindings({ context: context ?? this.context, data, parsed }),
+        parsed.text,
+        );
+    }
+}
+
+/**
+ * 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.
+ */
+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.
+ */
+export declare const MARKDOWN_DESTINATION_RENDERINGS: readonly [readonly ["markdown", "tree"], readonly ["mermaid", "diagram"]];
+
+/** Header of the depth-headroom scoreboard. */
+export declare const MARKDOWN_HEADROOM_HEADER = "| Headroom | Projects |\n| --- | --- |";
+
+/** Header of the per-project index table. */
+export declare const MARKDOWN_PROJECT_INDEX_HEADER = "| Project | Deepest | Limit | Headroom | Widest |\n| --- | --- | --- | --- | --- |";
+
+/** Header of the run or project summary table. */
+export declare const MARKDOWN_SUMMARY_HEADER = "| Measure | Value |\n| --- | --- |";
+
+/** Header of the breadth table. */
+export declare const MARKDOWN_WIDE_CALLABLES_HEADER = "| Callable | Breadth | Calls directly | Location |\n| --- | --- | --- | --- |";
+
+/** Heading over the callables that called more directly than allowed. */
+export declare const MARKDOWN_WIDE_CALLABLES_HEADING = "Callables over the breadth limit";
+
+/**
+ * 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.
+ */
+export declare class MarkdownReportService {
+    private readonly mermaidReportService;
+    private readonly reportService;
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    private renderProjectLimits;
+    /** Renders one stack: a labelled heading line and its tree in a fence. */
+    private renderStack;
+    /** Renders the stacks of one scope, drawn or printed as asked. */
+    private renderStacksAs;
+    /** Renders the counts describing what a run, or a project, produced. */
+    private renderSummaryTable;
+    /** 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.
+     */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    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.
+ */
+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.
+ */
+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.
+ */
+export declare interface MermaidDiagram {
+    readonly edges: Set<string>;
+    readonly identifiersByCallable: Map<CallableId, string>;
+    readonly nodes: string[];
+}
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+export declare class MermaidReportService {
+    constructor();
+    /** Draws one frame, or returns the identifier it already has. */
+    private addFrame;
+    /** Draws one stack into the diagram, reusing whatever it already holds. */
+    private addStack;
+    /** Counts the callables a stack would add that the diagram lacks. */
+    private countNewCallables;
+    /** Renders a frame's label, escaping what mermaid would read as syntax. */
+    private renderLabel;
+    /** Wraps a built diagram in its fence, or says why there is none. */
+    renderDiagram(args: {
+        diagram: MermaidDiagram;
+        omitted: number;
+    }): string;
+    /** Draws every stack that fits, deepest first, and says what did not. */
+    renderStacks(args: {
+        stacks: readonly FramedStack[];
+    }): 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.
+ */
+export declare const MINIMUM_STACK_FRAMES = 2;
+
+/** Raised when the anchor helper is asked to write a file nothing named. */
+export declare class MissingMarkdownPathError extends Error {
+    constructor();
+}
+
+/** Marks every frame below the first. */
+export declare const NESTED_FRAME_PREFIX = "\u2514\u2500>";
+
+/**
+ * Provides the machine-readable JSON report destination.
+ */
+export declare class OutputJsonModule {
+}
+
+/**
+ * Writes the traced findings to a JSON report file.
+ *
+ * The report holds the findings and nothing else — no timestamp, no tool
+ * version, no run duration. Anything that changed between two runs over the
+ * same tree would make check mode fail on a repository nobody touched.
+ */
+export declare class OutputJsonService {
+    private readonly logger;
+    constructor(logger: LoggerService);
+    /** 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.
+     */
+    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.
+     */
+    sync(args: SyncJsonArguments): boolean;
+}
+
+/**
+ * Provides the anchored markdown block destination.
+ */
+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.
+ */
+export declare class OutputMarkdownService {
+    private readonly logger;
+    constructor(logger: LoggerService);
+    /** Appends a generated block after a file's existing content. */
+    private appendBlock;
+    /** Builds the pattern matching everything between the two anchors. */
+    private buildBlockPattern;
+    /** Escapes a marker so it can sit inside a pattern. */
+    private escapePattern;
+    /** 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.
+     */
+    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.
+     */
+    private spliceBlock;
+    /** Builds the helpers a configured `writeBlock` function is handed. */
+    buildHelpers(args: SyncMarkdownArguments): MarkdownAnchorHelpers;
+    /** 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.
+     */
+    syncAnchoredBlock(args: SyncAnchoredBlockArguments): boolean;
+    /** Wraps content in the configured anchors. */
+    wrapInAnchors(args: WrapInAnchorsArguments): string;
+}
+
+/** The findings one set of projects owns, each judged by that project. */
+export declare interface OwnedFindings {
+    readonly deepStacks: readonly DeepStackFinding[];
+    readonly wideCallables: readonly WideCallableFinding[];
+}
+
+/** A message split into the emoji the console shows 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. */
+export declare interface ProjectIndexRow {
+    readonly deepest: number;
+    readonly headroom: number;
+    readonly limit: number;
+    readonly projectName: string;
+    readonly widest: number;
+}
+
+/**
+ * Provides the per-project view a project's own README is written from.
+ */
+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.
+ */
+export declare class ProjectReportsService {
+    private readonly pathsService;
+    private readonly signaturesService;
+    constructor(pathsService: PathsService, signaturesService: SignaturesService);
+    /** Builds every callable's breadth, grouped by project. */
+    private buildCallableBreadths;
+    /** Builds every stack that makes at least one call, deepest first. */
+    private buildStacks;
+    /** Counts what one project contributed to the graph. */
+    private buildSummary;
+    /** Picks the stacks one project's own depth limit fails on. */
+    private findProjectDeepStacks;
+    /** Picks the callables one project's own breadth limit fails on. */
+    private findProjectWideCallables;
+    /** 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.
+     */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    findUnreadProjects(args: {
+        /** The projects entitled to fail on what they own. */
+        projectNames: readonly string[];
+        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.
+     */
+    findWideCallables(args: {
+        limits: ProjectLimitsLookup;
+        reports: readonly ProjectReport[];
+    }): WideCallableFinding[];
+}
+
+/** Arguments for rendering one callable's direct callers and callees. */
+declare interface RenderBreadthArguments extends BreadthReport {
+    readonly format: CallidescopeOutputFormat;
+}
+
+/** Arguments for rendering several callables' direct calls as one document. */
+declare interface RenderBreadthReportsArguments {
+    readonly format: CallidescopeOutputFormat;
+    readonly reports: readonly BreadthReport[];
+}
+
+/** Arguments for rendering the paths traced above and below one callable. */
+declare interface RenderDepthArguments extends DepthReport {
+    readonly format: CallidescopeOutputFormat;
+}
+
+/** Arguments for rendering several callables' traced paths as one document. */
+declare interface RenderDepthReportsArguments {
+    readonly format: CallidescopeOutputFormat;
+    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.
+ */
+export declare interface RenderFindingsArguments extends OwnedFindings {
+    readonly previewCount: number;
+}
+
+/** Arguments for rendering the per-project index and its scoreboard. */
+export declare interface RenderProjectIndexArguments {
+    readonly limits: ProjectLimitsLookup;
+    readonly projects: readonly ProjectReport[];
+}
+
+/** 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.
+     */
+    readonly limits: ProjectLimitsLookup;
+    readonly previewCount: number;
+    readonly rendering: StackRendering;
+    readonly report: ProjectReport;
+}
+
+/** Arguments for rendering a whole run. */
+export declare interface RenderRunArguments {
+    /** Prose placed under the heading, from the destination that asked for it. */
+    readonly description: string | undefined;
+    readonly heading: string;
+    readonly limits: ProjectLimitsLookup;
+    readonly previewCount: number;
+    readonly rendering: StackRendering;
+    readonly result: CallGraphResult;
+}
+
+/** Arguments for rendering a run's stacks, preview then disclosure. */
+export declare interface RenderStacksArguments {
+    readonly previewCount: number;
+    readonly stacks: readonly CallStack[];
+}
+
+/** Arguments accepted when weighing what a run found. */
+export declare interface ReportFindingsArguments {
+    readonly mode: RunMode;
+    readonly result: CallGraphResult;
+    /**
+     * Destinations found not to hold the current report. Only ever non-empty
+     * when the run was comparing, since nothing else reads a destination.
+     */
+    readonly stalePaths: readonly string[];
+}
+
+/**
+ * NestJS module that wires the service weighing a trace's findings.
+ */
+export declare class ReportFindingsModule {
+}
+
+/**
+ * Weighs every finding a run can produce, and fails on the ones it was asked
+ * to gate.
+ *
+ * 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.
+ */
+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.
+     */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    reportFindings(args: ReportFindingsArguments): void;
+}
+
+/**
+ * Provides the terminal rendering of one run's findings.
+ */
+export declare class ReportModule {
+}
+
+/**
+ * Renders one call stack as an indented tree.
+ *
+ * Plain text rather than a markdown list, because the indentation is the thing
+ * that makes a stack readable and a list would have every renderer reflow it.
+ * Whatever embeds this is responsible for putting it in a fence.
+ */
+export declare class ReportService {
+    constructor();
+    /** Reads a summary's opening sentence, when it has more than one. */
+    private readFirstSentence;
+    /** Renders one frame at its indentation, with whatever it says about itself. */
+    private renderFrame;
+    /** 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.
+     */
+    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.
+     */
+    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.
+     */
+    renderStackTree(stack: {
+        frames: readonly StackFrame[];
+    }): string;
+}
+
+/** Stands in for the workspace root when it is itself 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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+export declare const SUMMARY_LIMIT = 120;
+
+/** Introduces the documentation line printed under a frame. */
+export declare const SUMMARY_PREFIX = "\u21B3";
+
+/** Arguments for splicing a block between its anchors. */
+export declare interface SyncAnchoredBlockArguments {
+    readonly check: boolean;
+    readonly content: string;
+    readonly destination: ResolvedCallidescopeMarkdownOutputConfiguration;
+    readonly path: string | undefined;
+}
+
+/** Arguments for writing every configured destination. */
+export declare interface SyncDestinationsArguments {
+    readonly check: boolean;
+    readonly configuration: ResolvedCallidescopeConfiguration;
+    /** 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.
+     */
+    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.
+     */
+    readonly writeByProject: ReadonlyMap<string, ResolvedCallidescopeWriteConfiguration>;
+}
+
+/** Arguments for syncing the configured JSON destination. */
+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.
+ */
+export declare interface SyncMarkdownArguments {
+    readonly check: boolean;
+    readonly content: string;
+    readonly destination: ResolvedCallidescopeMarkdownOutputConfiguration;
+    readonly result: CallGraphResult;
+}
+
+/** Arguments for writing the destinations one project declared for itself. */
+export declare interface SyncProjectSectionsArguments {
+    readonly check: boolean;
+    /** The depth and breadth limits each traced project is judged against. */
+    readonly projectLimits: ProjectLimitsLookup;
+    /** The findings for the one project these destinations belong to. */
+    readonly report: ProjectReport;
+    readonly result: CallGraphResult;
+    /** Workspace-relative root every declared path is read against. */
+    readonly root: string;
+    readonly write: ResolvedCallidescopeWriteConfiguration;
+}
+
+/** Appended to a summary cut mid-thought. */
+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.
+ *
+ * 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.
+ */
+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.
+     */
+    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.
+     */
+    buildRows(args: RenderProjectIndexArguments): ProjectIndexRow[];
+    /** The limits one project resolved to, or the workspace's when unlisted. */
+    limitsFor(args: {
+        limits: ProjectLimitsLookup;
+        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.
+     */
+    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.
+     */
+    renderProjectIndex(args: RenderProjectIndexArguments): string;
+}
+
+/** Arguments for wrapping content in the configured anchors. */
+export declare interface WrapInAnchorsArguments {
+    readonly content: string;
+    readonly destination: ResolvedCallidescopeMarkdownOutputConfiguration;
+}
+
+/**
+ * NestJS module that wires the service writing a run to its destinations.
+ */
+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.
+ */
+export declare class WriteDestinationsService {
+    private readonly markdownReportService;
+    private readonly outputJsonService;
+    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.
+     */
+    private syncProjectDestinations;
+    /** Writes one project's declared destinations, returning the stale ones. */
+    private syncProjectSections;
+    /** Writes every configured destination, returning the stale ones. */
+    syncDestinations(args: SyncDestinationsArguments): string[];
+}
+
+export { }