@codometer/output 0.0.1

package/dist/src/index.d.ts

@@ -0,0 +1,1571 @@
+import { CodeStatisticsResult } from '@codometer/core';
+import { CodometerCompression } from '@codometer/configuration';
+import { CodometerReport as CodometerReport_2 } from '@codometer/core';
+import { ConfigurationService } from '@codometer/configuration';
+import { ConsoleLogger } from '@nestjs/common';
+import { DiscoveryService } from '@codometer/measurement';
+import { EvaluatedLimit } from '@codometer/measurement';
+import { MeasureCommandOptions } from '@codometer/configuration';
+import { MeasureFormat } from '@codometer/configuration';
+import { MeasurementResult } from '@codometer/measurement';
+import { MetricUnit as MetricUnit_2 } from '@codometer/core';
+import pino from 'pino';
+import { ReportFailure as ReportFailure_2 } from '@codometer/core';
+import { ResolvedCodometerConfiguration } from '@codometer/configuration';
+import { ResolvedCodometerCustomStatistic } from '@codometer/configuration';
+import { ResolvedCodometerMarkdownOutput } from '@codometer/configuration';
+import { RunMode } from '@codometer/configuration';
+import { TargetMetricIndex } from '@codometer/measurement';
+import { WriteMarkdownOutput } from '@codometer/configuration';
+import { z } from 'zod';
+
+/** Stands in for a column a limit left empty, so the cell is never blank. */
+export declare const ABSENT_LABEL = "\u2014";
+
+/** Arguments accepted when building the report from one measurement. */
+declare interface BuildReportArguments {
+    failures: readonly ReportFailure_2[];
+    /** Every metric each measured target counted, target by target. */
+    indexes: ReadonlyMap<string, TargetMetricIndex>;
+    limits: readonly EvaluatedLimit[];
+}
+
+/**
+ * Diffs codometer reports and joins them to a baseline.
+ *
+ * Imports `LoggerModule` itself rather than relying on a consuming
+ * application to import it globally, since this package is a library with no
+ * root module of its own — `LoggerModule` is `@Global()`, so importing it
+ * here is enough for `LoggerService` to resolve wherever this module is used.
+ */
+export declare class ChangesModule {
+}
+
+/**
+ * Reads what each project's codometer run measured and joins it to a baseline.
+ *
+ * Codometer is stateless: it measures the tree in front of it and never looks
+ * at another branch. Comparing two runs is this package's job, because a
+ * baseline needs branches, workflow artifacts, and pull request context —
+ * exactly the knowledge a measurement tool has to stay free of.
+ *
+ * The baseline is a snapshot downloaded from the latest successful `main` run
+ * rather than a second build of the base branch, which used to cost a full
+ * extra checkout, install, and build on every pull request.
+ *
+ * Because CI runs `nx affected`, a pull request measures only the projects it
+ * touched. Metrics the baseline knows about but this run did not rebuild are
+ * still collected — flagged as unmeasured, carrying their baseline value — so
+ * a report can cover the whole workspace instead of only the change's blast
+ * radius.
+ *
+ * Every metric a target produced is joined, not only the ones denominated in
+ * bytes or the ones a limit was written against — a metric with no limit is
+ * measured and reported, never gated, and that includes whether it changed.
+ */
+export declare class ChangesService {
+    private readonly logger;
+    constructor(logger: LoggerService);
+    /**
+     * Builds the row for a metric only the baseline knows about.
+     *
+     * Its numbers come from the baseline, so its verdicts are dropped: `breach`
+     * and `empty` are cleared rather than spread through. A pull request that
+     * never rebuilt a project must not be marked by what that project was doing
+     * on `main` — otherwise a limit breached there marks every unrelated pull
+     * request, and the row explaining it is not even on screen, because an
+     * unmeasured row is easy to miss and a removed one needs to say so plainly.
+     *
+     * The same reasoning drops the baseline's failures in `readBaseline`. Both
+     * exist to keep this change's status derived from this change.
+     */
+    private buildBaselineRow;
+    /** Builds the row for a metric this run measured. */
+    private buildMeasuredRow;
+    /**
+     * Joins one project's current report to its baseline.
+     *
+     * A baseline metric with no current counterpart was removed when this run
+     * rebuilt the project, and merely skipped when it did not.
+     */
+    private collectProjectRows;
+    /** Parses the report's JSON body, tolerating an absent or malformed file. */
+    private parseReport;
+    /** Reads a baseline report into a name-to-metric lookup. */
+    private readBaseline;
+    /**
+     * The severity of the worst limit a metric breached, if it breached one.
+     *
+     * A failing breach outranks an advisory one, so a metric that went past
+     * its `fail` limit while also going past an advisory limit below it reads
+     * as failing rather than as merely advised.
+     */
+    private readBreach;
+    /**
+     * The limit a metric is actually held to.
+     *
+     * The lowest `fail` limit, because that is the one that stops a change, and
+     * the lowest of them when several are written because that is the one that
+     * binds first. A metric limited only by advice falls back to its lowest
+     * `warn` limit — the only limit it has — rather than reporting none.
+     */
+    private readGoverningLimit;
+    /** The first label any limit wrote, which names the row in the table. */
+    private readLabel;
+    /**
+     * Pulls every metric a target produced out of the report.
+     *
+     * A codometer report carries everything a project measures — files, symbols,
+     * lines, bytes — and every one of them is joined against its baseline, not
+     * only the ones denominated in bytes.
+     *
+     * The row is labelled with whatever the limit was written under, falling
+     * back to the metric's own dotted name rather than the target's — a target
+     * groups many metrics under one name, so labelling every one of them with
+     * that shared name would make them indistinguishable from each other.
+     */
+    private readMetrics;
+    /** Derives the Nx project name from a report path. */
+    private readProjectName;
+    /** Parses a codometer report, tolerating an absent or malformed file. */
+    private readReport;
+    /**
+     * Lists every report path either side knows about, so a project the baseline
+     * measured is still accounted for when this run skipped it.
+     */
+    private readReportPaths;
+    /** Joins every current report to the baseline snapshot. */
+    collect(args: CollectRowsArguments): MetricCollection;
+}
+
+/**
+ * The block this report claims inside a shared document. HTML comments are
+ * invisible once the markdown is rendered, and every other report claims its
+ * own pair, so several can sit in one document without collision.
+ */
+export declare const CODOMETER_MARKERS: {
+    end: string;
+    start: string;
+};
+
+/** One codometer report, as far as this diff reads it. */
+declare type CodometerReport = z.infer<typeof codometerReportSchema>;
+
+/**
+ * The shape of a codometer report, as far as this diff reads it.
+ *
+ * Validated rather than asserted: the file is output this package does not
+ * produce, and a malformed one should read as "nothing measured" instead of
+ * flowing through as untyped data.
+ *
+ * Nothing here is inferred from an absent field. A target says outright whether
+ * its globs matched anything, and a metric nobody limited carries an empty
+ * `limits` array rather than no limits key at all — so a target that matched
+ * no files reads differently from one that genuinely measured zero, and an
+ * unlimited metric differently from an unread report.
+ *
+ * `limits` is a list because a metric may carry more than one: the
+ * configuration accepts a `warn` short of a `fail` on purpose, and the gate
+ * enforces every one of them.
+ *
+ * `failures` is read for the same reason the rest of this is. A target the run
+ * could not measure contributes no row, and a table that silently holds fewer
+ * rows than the workspace has targets is a number that looks right only
+ * because whatever would have contradicted it is missing.
+ *
+ * `unit` is carried through on every row rather than filtered here, so a
+ * renderer can format a byte count differently from a plain count without this
+ * package needing to know what a renderer does with either.
+ */
+export declare const codometerReportSchema: z.ZodObject<{
+    failures: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            limit: "limit";
+            target: "target";
+        }>;
+        reason: z.ZodString;
+        subject: z.ZodString;
+    }, z.core.$strip>>>;
+    targets: z.ZodArray<z.ZodObject<{
+        empty: z.ZodBoolean;
+        metrics: z.ZodArray<z.ZodObject<{
+            limits: z.ZodArray<z.ZodObject<{
+                breached: z.ZodBoolean;
+                label: z.ZodNullable<z.ZodString>;
+                severity: z.ZodEnum<{
+                    fail: "fail";
+                    warn: "warn";
+                }>;
+                value: z.ZodNumber;
+            }, z.core.$strip>>;
+            name: z.ZodString;
+            unit: z.ZodNullable<z.ZodEnum<{
+                bytes: "bytes";
+            }>>;
+            value: z.ZodNumber;
+        }, z.core.$strip>>;
+        name: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+
+/** Arguments for reading one project's report and its baseline. */
+export declare interface CollectProjectRowsArguments extends CollectRowsArguments {
+    reportPath: string;
+}
+
+/** Arguments for joining measured reports to a baseline. */
+export declare interface CollectRowsArguments {
+    baselineDirectory: string | undefined;
+    workingDirectory: string;
+}
+
+/** Heading the whole listing is written under. */
+export declare const CONFIGURATION_HEADING = "# \uD83D\uDD27 Codometer Configuration";
+
+/**
+ * Renders what a repository configures, as a document rather than a command.
+ *
+ * Reading the configuration a tree declares is an analysis of configuration,
+ * and turning it into a markdown table or a JSON document is a render target
+ * like any other — so both live here, above the configuration layer they read
+ * and below the command that asks for them. Codometer's own configuration and
+ * discovery modules are imported rather than reimplemented: the listing must
+ * resolve a file exactly as a measurement would, and must skip the same
+ * ignored directories, or it would describe a repository nobody runs.
+ */
+export declare class ConfigurationListingModule {
+}
+
+/**
+ * Finds every codometer configuration in a tree and says what each one holds.
+ *
+ * Answers the question a repository gains once its limits stop living in one
+ * table: where is everything configured, and what does it add up to. It reads
+ * configuration and never measures anything, so it needs no build and runs in
+ * milliseconds — and no single unreadable file takes the listing down, because
+ * every failure is carried back on the result rather than thrown.
+ */
+export declare class ConfigurationListingService {
+    private readonly configurationService;
+    private readonly discoveryService;
+    constructor(configurationService: ConfigurationService, discoveryService: DiscoveryService);
+    /** Every name a configuration file may be written under, as a set. */
+    private readonly configurationFileNames;
+    /**
+     * Resolves one configuration file, reporting rather than throwing on failure.
+     *
+     * A file named like a configuration is not always one that loads: a
+     * generator template carries placeholders in its own path, and a
+     * work-in-progress file may not parse. One such file must not take the
+     * listing down with it, because the listing is most wanted precisely when
+     * something is wrong. The failure is carried on the entry so the reader sees
+     * which file could not be read instead of a shorter list than the tree holds.
+     */
+    private describeConfiguration;
+    /**
+     * Renders a limit's value with the unit its metric implies.
+     *
+     * A resolved limit carries a bare number, so `256000` alone cannot say
+     * whether it gates bytes or files. Only a size analysis produces a `.size`
+     * metric, which is what makes the suffix a sound test.
+     */
+    private formatLimitValue;
+    /**
+     * Resolves the exclusions the walk uses, reporting rather than throwing.
+     *
+     * The walk root is not guaranteed to have a configuration answering for it:
+     * a workspace states its `format` once in a shared object that each project
+     * spreads, so the root itself may carry no configuration file at all and the
+     * upward search then finds nothing to resolve. A workspace in that shape
+     * names its own file with `--config`; one that does neither must not take
+     * the listing down — the listing is most wanted precisely when the
+     * configuration is in a state somebody is trying to understand — so the
+     * built-in exclusions stand in and the failure is carried back to be
+     * reported and to fail the run's exit code.
+     */
+    private resolveWalkExclusions;
+    /**
+     * Resolves the configuration each file in a tree answers with.
+     *
+     * Every file is resolved for **its own directory** rather than for the walk
+     * root, which is what makes the result match what a per-project run of
+     * codometer actually sees: every configuration file is resolved against the
+     * directory it sits in, so resolving one anywhere else would report
+     * something no run would ever use.
+     */
+    describeConfigurations(args: DescribeConfigurationsArguments): Promise<ConfiguredTree>;
+    /**
+     * Finds every configuration file beneath a directory.
+     *
+     * Walks with the same gitignore-aware discovery a measurement uses, so a
+     * configuration inside `node_modules` or a build directory is never picked
+     * up, and one inside a folder the repository ignores is never reported as
+     * something the repository configures.
+     *
+     * The exclusions come from whatever configuration answers for the walk root,
+     * because that is what says which files this repository considers its own —
+     * walking without them would list every configuration in a vendored
+     * dependency or a generator template. A root nothing answers for falls back
+     * to the built-in exclusions and reports itself instead of failing.
+     */
+    findConfigurationFiles(args: DescribeConfigurationsArguments): Promise<DiscoveredConfigurationFiles>;
+    /** Flattens every configured limit into one row per limit, in walk order. */
+    toLimitRows(described: readonly ConfiguredDirectory[]): ConfiguredLimitRow[];
+}
+
+/** One configuration file, and everything it resolved to for its own folder. */
+export declare interface ConfiguredDirectory {
+    /** The configuration with every default applied, absent when it failed to load. */
+    configuration: ResolvedCodometerConfiguration | undefined;
+    /** Directory the configuration was resolved for, relative to the walk root. */
+    directory: string;
+    /** Why the file could not be read, and `undefined` when it was read. */
+    error: string | undefined;
+    /** Configuration file that answered, relative to the walk root. */
+    path: string;
+}
+
+/** One row of the limits listing. */
+export declare interface ConfiguredLimitRow {
+    /** Directory the limit gates, relative to the walk root. */
+    directory: string;
+    /** Written label, or a dash when none was written. */
+    label: string;
+    /** Metric path the limit is written against. */
+    metric: string;
+    /** Configuration file the limit is declared in, relative to the walk root. */
+    path: string;
+    severity: string;
+    /** Rendered with its unit, so a size reads as a size and a count as a count. */
+    value: string;
+}
+
+/** Everything a tree configures, plus whatever answered for its root. */
+export declare interface ConfiguredTree {
+    described: ConfiguredDirectory[];
+    /**
+     * Why nothing could be resolved for the walk root, and `undefined` when
+     * something was.
+     *
+     * Carried rather than thrown. The listing is most wanted precisely when the
+     * configuration is in a state somebody is trying to understand, so an
+     * unreadable root is reported and the walk goes on with the built-in
+     * exclusions — but it still fails the run's exit code.
+     */
+    rootError: string | undefined;
+}
+
+/** Arguments accepted when producing every one of a run's outputs. */
+export declare interface DeliverArguments {
+    /** Where the printed badge block's own configured counters come from,
+     * resolved independently of `destinations.markdown`. */
+    consoleMarkdown: ResolvedMarkdownDestination | undefined;
+    destinations: RunDestinations;
+    /** What goes to standard output, or nothing when the run prints nothing. */
+    format: MeasureFormat | undefined;
+    measurement: MeasurementResult;
+    mode: RunMode;
+    report: CodometerReport_2;
+    scope: MeasurementScope;
+}
+
+/**
+ * NestJS module that writes every resolved output a run produces.
+ */
+export declare class DeliveryModule {
+}
+
+/**
+ * Produces every resolved output — the report, the badge block, and whatever
+ * the run prints — and says which of the written ones are stale.
+ *
+ * Split out of `MeasureCommand` so delivering a report is a concern of its
+ * own, separate from measuring and from gating on what was measured. Every
+ * destination is produced before anything is reported, so a run that writes
+ * and gates writes all of its reports even when the gate then trips.
+ *
+ * Standard output has exactly one writer here, `deliverConsole`. A file sink
+ * never prints: two sinks that could each decide to print is how one run put
+ * two documents on the stream a pipeline was parsing.
+ *
+ * `renderBadges` and where a custom statistic's per-instance breaches are
+ * rendered are `@codometer/output`'s business, not this service's — it hands
+ * over the measured statistics and a destination and lets that package
+ * decide what the markdown says.
+ */
+export declare class DeliveryService {
+    private readonly jsonService;
+    private readonly markdownService;
+    constructor(jsonService: JsonService, markdownService: MarkdownService);
+    /** Print whatever the run asked for, and nothing when it asked for nothing. */
+    private deliverConsole;
+    /** Write the report to its file, if this run writes or compares one. */
+    private deliverJson;
+    /**
+     * Put the badge block into its markdown file, if this run writes or
+     * compares one.
+     *
+     * The one markdown sink. `MarkdownService.sync` splices the block between
+     * its markers when the file carries them, appends it when it does not, and
+     * creates the file when it is not there — so a README somebody else wrote
+     * and a file holding nothing but badges are the same case, and neither
+     * needs a flag of its own.
+     */
+    private deliverMarkdown;
+    /**
+     * The size of every input this run measured, in declaration order.
+     *
+     * Left out rather than reported as zero bytes: an input that ran no size
+     * analysis, and an input whose globs matched no file. Both would otherwise
+     * publish `0.00 kB` — a figure that is not merely missing but wrong, and
+     * wrong in a README a release commits. An input measured before its build
+     * lands is the ordinary way to reach the second case, and it is caught by a
+     * failing limit only for the inputs that happen to declare one.
+     *
+     * A run that declared no input beyond `codebase` produces an empty list and
+     * no size badges.
+     */
+    private readTargetSizes;
+    /**
+     * Whether the run does anything with a file at all.
+     *
+     * A run that neither writes nor compares leaves every file alone. What it
+     * shows instead is `--format`'s business, not a destination's.
+     */
+    private touchesFiles;
+    /** Produce every output, and name the ones found stale. */
+    deliver(args: DeliverArguments): string[];
+}
+
+/** Which tree to describe, and which configuration answers for its root. */
+export declare interface DescribeConfigurationsArguments {
+    /**
+     * Configuration file answering for the walk root, when one is named.
+     *
+     * `undefined` searches upward from the walk root instead. A workspace whose
+     * root carries no configuration file — because its shared object lives
+     * somewhere every project spreads it from — names that file here, exactly as
+     * the workspace-root measurement target already does.
+     */
+    configurationPath: string | undefined;
+    /** Directory the walk starts from, absolute. */
+    workingDirectory: string;
+}
+
+/**
+ * NestJS module that resolves where each of a run's outputs goes.
+ */
+export declare class DestinationsModule {
+}
+
+/**
+ * Resolves which file each of a run's outputs lands in.
+ *
+ * Kept away from the command itself so that a destination can be resolved and
+ * tested without a measurement: which file each output lands in, and whether
+ * a bare `--output-*` flag has anything to resolve from at all, are questions
+ * that have been got wrong by inferring them from whichever other flag
+ * happened to be on the command line.
+ *
+ * It sits in the output layer rather than beside the flag reading it starts
+ * from, because a destination is a render target: what it produces is the
+ * path `JsonService` and `MarkdownService` write to, and the exclusion list
+ * the measurement is told not to measure.
+ */
+export declare class DestinationsService {
+    constructor();
+    /** Finds the first output of the given type, if the configuration named one. */
+    private findConfiguredOutput;
+    /** Where the report goes, if this run resolves that destination at all. */
+    private resolveJson;
+    /**
+     * Which markdown file the badge block goes into, if any.
+     *
+     * One sink rather than two. The block is spliced between its markers when
+     * the file already carries them, and appended with them when it does not,
+     * so the same flag serves a README somebody else wrote the rest of and a
+     * file that holds nothing but badges.
+     *
+     * The path is never defaulted from nothing: it comes from the command line,
+     * or from a configured `markdown` output's own path or `write`. A
+     * configured `write` function is a destination in its own right — it picks
+     * the file itself — so it counts as "resolvable" even without a path.
+     */
+    private resolveMarkdown;
+    /** Turns a written destination path into an absolute one. */
+    private resolvePath;
+    /**
+     * Lists the files this run writes, relative to the measured directory.
+     *
+     * What codometer writes is what codometer must not measure, so this is also
+     * the exclusion list handed to the measurement.
+     */
+    listOutputPaths(args: ListOutputPathsArguments): string[];
+    /**
+     * Which markdown destination the console renders.
+     *
+     * Resolved from the configuration alone, never gated by whether
+     * `--output-markdown` — or any other `--output-*` flag — was passed: the
+     * printed badge block must carry every configured custom counter whether or
+     * not this run also writes a markdown file, so it is resolved as though no
+     * other output flag were on the command line. An explicit `--output-markdown
+     * <path>` is still honored, exactly as it would be for the write
+     * destination. Nothing here is written to disk; `resolveDestinations`
+     * decides that separately.
+     */
+    resolveConsoleMarkdown(args: ResolveDestinationsArguments): ResolvedMarkdownDestination | undefined;
+    /**
+     * Resolves which files the run writes, and refuses a destination this run
+     * has no way to have produced.
+     *
+     * `--output-json`/`--output-markdown` passed bare ask this run to write
+     * wherever the configuration says to; refused before anything is measured
+     * when the configuration names no such output at all, since there is then
+     * nowhere to write it.
+     */
+    resolveDestinations(args: ResolveDestinationsArguments): ResolveDestinationsResult;
+    /**
+     * Whether a run covers a whole repository or one project inside one.
+     *
+     * Decided from the measured directory alone, not by walking upward: a
+     * directory carrying a repository marker is a repository, and anything
+     * beneath one is a project. The first badge group is headed by this, so a
+     * project README saying `Repository` over figures that only ever covered
+     * that project is the thing it exists to prevent.
+     */
+    selectScope(workingDirectory: string): MeasurementScope;
+}
+
+/** Every configuration file a walk found, plus whatever the walk root said. */
+export declare interface DiscoveredConfigurationFiles {
+    /** Configuration file paths, relative to the walk root, in walk order. */
+    files: string[];
+    /** Why nothing answered for the walk root, and `undefined` when it did. */
+    rootError: string | undefined;
+}
+
+/** Where a rendered section should land. */
+export declare interface DocumentDestination {
+    /** Markdown file to splice the section into, between its markers. */
+    markdown: string | undefined;
+    /** File to write the section to on its own. */
+    output: string | undefined;
+}
+
+/** The HTML comments delimiting one report's section inside a document. */
+export declare interface DocumentMarkers {
+    end: string;
+    start: string;
+}
+
+/**
+ * Wraps a report body in markers and writes it wherever it was asked for.
+ *
+ * Imports `LoggerModule` itself rather than relying on a consuming
+ * application to import it globally, since this package is a library with no
+ * root module of its own — `LoggerModule` is `@Global()`, so importing it
+ * here is enough for `LoggerService` to resolve wherever this module is used.
+ */
+export declare class DocumentsModule {
+}
+
+/**
+ * Puts a rendered report body where it was asked for.
+ *
+ * Every report shares this: wrap the body in its markers, then write it to a
+ * file, splice it into a document, or print it. Nothing here knows what any
+ * report measures, and nothing here talks to a forge — handing the markdown to
+ * a pull request, an issue, or a wiki is the caller's job.
+ */
+export declare class DocumentsService {
+    private readonly logger;
+    constructor(logger: LoggerService);
+    /** Reads a document, treating an absent one as empty. */
+    private readDocument;
+    /**
+     * Wraps a rendered body in its markers, then writes it wherever the
+     * destination says.
+     *
+     * With neither a file nor a document the section goes to standard output,
+     * which is what makes any report inspectable before it is wired into
+     * anything.
+     */
+    emit(args: EmitArguments): Promise<void>;
+    /**
+     * Splices a section into a document, or appends it when the markers are
+     * absent, and leaves the author's prose either side of it alone.
+     */
+    splice(document: string, section: string, markers: DocumentMarkers): string;
+    /** Wraps a rendered body in its markers. */
+    wrap(body: string, markers: DocumentMarkers): string;
+}
+
+/** Arguments for wrapping a rendered body and putting it where it was asked for. */
+export declare interface EmitArguments {
+    /** The report's rendered body, without its markers. */
+    body: string;
+    destination: DocumentDestination;
+    /** Names the report in log messages, so several reports stay distinguishable. */
+    label: string;
+    markers: DocumentMarkers;
+}
+
+/**
+ * Formats a byte count, switching to megabytes once kilobytes get unwieldy.
+ *
+ * Kilobytes are decimal, matching what codometer parses out of a limit written
+ * as `"8 KB"`. Dividing by 1024 here would print a limit as a number the
+ * configuration never mentions.
+ */
+export declare function formatBytes(bytes: number): string;
+
+/** Formats a plain count, grouped with the reader's locale separators. */
+export declare function formatCount(value: number): string;
+
+/** Formats a signed delta, or an em dash when there is nothing to compare. */
+export declare function formatDelta(delta: number | undefined, unit: MetricUnit_2): string;
+
+/** Formats a value the way its unit calls for. */
+export declare function formatValue(value: number, unit: MetricUnit_2): string;
+
+/**
+ * Whether a metric changed since the baseline, or is breaching a limit right
+ * now regardless of whether it moved.
+ *
+ * A row that neither changed nor breaches anything has nothing to tell a
+ * reviewer, so it never reaches the table. A brand-new metric — one with no
+ * baseline at all — counts as changed only when it measured something or its
+ * target's globs matched nothing, because a zero-valued metric appearing for
+ * the first time (every project carries a metric for every language
+ * codometer knows, most of them zero) tells a reviewer nothing "appeared" —
+ * least of all on the first run this report ever makes against a project,
+ * where every metric is technically without a baseline at once.
+ */
+export declare function hasChanged(row: MetricRow): boolean;
+
+/** Heading the rendered section is filed under. */
+export declare const HEADING = "## \u23F2\uFE0F Codometer";
+
+/**
+ * NestJS module that provides JSON statistics report writing.
+ */
+export declare class JsonModule {
+}
+
+/**
+ * Writes the report to a JSON file.
+ *
+ * The file holds the report and nothing else — no timestamp, no tool version.
+ * Anything that changes between two runs over the same tree would report a
+ * repository nobody touched as stale.
+ */
+export declare class JsonService {
+    private readonly logger;
+    constructor(logger: LoggerService);
+    /**
+     * Read an existing report, returning an empty string if absent.
+     */
+    private readExisting;
+    /**
+     * Render the report as the JSON document that gets written.
+     *
+     * Ends with a newline so the file matches what a formatter would leave
+     * behind, and so a staleness comparison does not fail over the one byte
+     * every other tool in the repository adds.
+     */
+    render<Report>(args: RenderReportArguments<Report>): string;
+    /**
+     * Sync the JSON file with the current report.
+     *
+     * - **Writing**: writes the file, creating parent directories as needed.
+     * - **Checking**: returns `true` when the file already holds the current
+     *   report, `false` when it is missing or stale, and writes nothing.
+     */
+    sync<Report>(args: SyncJsonArguments<Report>): boolean;
+}
+
+/** Column headers of the limits table, in the order they are rendered. */
+export declare const LIMIT_TABLE_COLUMNS: readonly ["Directory", "Metric", "Label", "Severity", "Value", "Declared in"];
+
+/** Arguments accepted when listing the files a run writes. */
+export declare interface ListOutputPathsArguments {
+    destinations: RunDestinations;
+    workingDirectory: string;
+}
+
+/**
+ * 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,
+        );
+    }
+}
+
+/**
+ * NestJS module that provides markdown badge block writing.
+ */
+export declare class MarkdownModule {
+}
+
+/**
+ * Writes generated code statistics badges into a markdown file.
+ */
+export declare class MarkdownService {
+    private readonly logger;
+    constructor(logger: LoggerService);
+    /**
+     * Build the anchor helpers handed to a configured `write` function.
+     *
+     * Every helper is bound to this run's content, path, and mode, so a writer
+     * that only wants the ordinary splice calls one method with no arguments.
+     *
+     * Each helper keeps the name of the method it wraps, because those names are
+     * the `MarkdownAnchorHelpers` contract a configured writer is written
+     * against.
+     */
+    private buildAnchorHelpers;
+    /**
+     * Assemble the badge groups, in the order they are rendered.
+     *
+     * Every counter the measurement pipeline produces gets a badge, grouped
+     * under a heading naming the language it was measured from. Only the first
+     * group spans languages; the rest report one language each, so a number
+     * that moves can be traced to the analyzer that produced it rather than to
+     * a sum that silently mixes several. That first group is named for the
+     * run's scope — `Repository` for the whole tree, `Project` for one project.
+     *
+     * `Measured Targets` is the one group not counting anything the language analyzers
+     * produced: it reports the size of each declared target this run measured,
+     * which is how a project's README carries the compressed size of what it
+     * ships. It renders nothing when the run declared no target, so the
+     * whole-repository report is byte for byte what it was.
+     */
+    private buildBadgeGroups;
+    /**
+     * Build the matcher for a block delimited by the configured markers.
+     */
+    private buildBlockRegex;
+    /**
+     * Escape a configured marker so it can be searched for literally.
+     */
+    private escapeRegex;
+    /**
+     * Read an existing markdown file, returning an empty string if absent.
+     */
+    private readExisting;
+    /**
+     * Narrow the measured statistics to one destination's own selected
+     * counters.
+     *
+     * `statistics.custom` is every counter the configuration's top-level
+     * `custom` array declares, measured once for the whole run regardless of
+     * which output — if any — renders each one. Two destinations may select
+     * entirely different labels back out of it, so each has to pick its own
+     * subset before rendering, or one destination's badges would carry
+     * another's counters too.
+     */
+    private scopeCustomStatistics;
+    /**
+     * Splice the anchored block into a file, or report whether it is current.
+     *
+     * Replaces the block when the markers are found, appends it when they are
+     * absent, and creates the file when it does not exist. Check mode compares
+     * and writes nothing.
+     *
+     * Deliberately its own splice, not the `documents` module's
+     * `DocumentsService`: that service has no check mode, and its `wrap` omits
+     * the blank line after the opening marker that `wrapInAnchors` below adds
+     * for Prettier — sharing it as-is would either drop check-mode reports or
+     * reformat every README the badge block sits in. Only the byte formatting
+     * was shared; unifying the splice itself needs check mode added to
+     * `DocumentsService` first, which is unscoped work of its own.
+     */
+    private syncAnchoredBlock;
+    /**
+     * Wrap rendered markdown in the configured anchor markers.
+     */
+    private wrapInAnchors;
+    /**
+     * Write markdown to a file, and record that it happened.
+     *
+     * Creates the directory on the way. The block is appended to a file that
+     * does not exist yet as readily as it is spliced into one that does, so a
+     * destination naming a directory nothing has created is an ordinary command
+     * line rather than a mistake.
+     */
+    private writeMarkdownFile;
+    /**
+     * Render the badge block for a destination, description and all.
+     *
+     * The block a splice destination places between its markers, and the body of
+     * the document a whole-file destination writes. Both are the same markdown,
+     * which is why the two sinks never disagree about a number.
+     *
+     * `statistics.custom` carries every counter the top-level `custom` array
+     * declares; this destination's own `custom` list says which of them it
+     * selected, so it is scoped down before rendering.
+     */
+    renderBadges(args: RenderBadgesArguments): string;
+    /**
+     * Render the badge block wrapped in its destination's anchor markers.
+     *
+     * What a splice would place, without placing it — the form a run that writes
+     * nothing shows on the console.
+     */
+    renderBlock(args: RenderBadgesArguments): string;
+    /**
+     * Render the badges as a document of their own.
+     *
+     * No anchor markers: nothing else is in the file, so there is nothing to
+     * anchor the block against.
+     *
+     * Every run, whatever its scope, heads its figures with the same section
+     * heading, because the heading lives inside the markers now rather than
+     * being written by hand above them — one owner instead of one per
+     * document. The groups underneath still distinguish `Repository` from
+     * `Project` by scope, so only the top-level heading unifies.
+     *
+     * A per-instance custom statistic that breached this run gets one more
+     * section after the badges, naming the file and line of each breach —
+     * spec #749 user story 16. Nothing is appended when nothing breached, the
+     * same instinct the badge groups themselves follow.
+     */
+    renderDocument(args: RenderDocumentArguments): string;
+    /**
+     * Sync a splice destination with the current statistics.
+     *
+     * `write` is the whole of the customizable behavior now: it decides what
+     * the markdown says and which file it lands in, replacing what used to be
+     * two separate `render` and `write` callbacks. The built-in behavior — no
+     * `write` configured — renders badges and splices them between the
+     * configured anchor markers.
+     *
+     * Returns whatever a configured `write` returns; the built-in path returns
+     * `false` only when checking, and only when the destination is missing or
+     * stale.
+     */
+    sync(args: SyncMarkdownArguments): boolean;
+}
+
+/**
+ * What a run measured: one project, or the repository holding it.
+ *
+ * Carried into the rendering because the first badge group is named after it.
+ * A run scoped to `packages/logger` reporting a `Repository` heading names the
+ * whole workspace for figures that only ever covered one package.
+ */
+export declare type MeasurementScope = "project" | "repository";
+
+/**
+ * Everything one collection read: the rows, and what could not be measured.
+ *
+ * Both travel together because a table of rows alone cannot be read honestly.
+ * A target that failed contributes no row, and the reader would have to count
+ * rows against a list of projects to notice it was gone.
+ */
+export declare interface MetricCollection {
+    failures: ProjectFailure[];
+    rows: MetricRow[];
+}
+
+/** One metric joined to the project that measured it and to its baseline. */
+export declare interface MetricRow extends ReportMetric {
+    baseValue: number | undefined;
+    /** False when this run did not rebuild the project, so the baseline stands in. */
+    measured: boolean;
+    project: string;
+    /** True when the baseline had this metric and the current run does not. */
+    removed: boolean;
+}
+
+/** How hard a breached limit lands: advisory, or fatal. */
+export declare type MetricSeverity = "fail" | "warn";
+
+/** The denomination a metric's value is counted in. */
+declare type MetricUnit = "bytes" | null;
+
+/** Raised when the anchor helper is asked to write a file nothing named. */
+export declare class MissingMarkdownPathError extends Error {
+    constructor();
+}
+
+/** A message split into the emoji the console shows and the prose telemetry stores. */
+declare interface ParsedLogMessage {
+    emoji: string | undefined;
+    text: string;
+}
+
+/**
+ * Something one project's run could not do, and what it was trying to do it to.
+ *
+ * Neither a breach nor staleness: it is the run not having finished. A `target`
+ * failure means a set of files nobody measured, so the rows it would have
+ * produced are absent from the table entirely.
+ */
+export declare interface ProjectFailure extends ReportFailure {
+    project: string;
+}
+
+/** What one project's report yielded: its metrics, and what failed. */
+export declare interface ProjectReport {
+    failures: ReportFailure[];
+    metrics: ReportMetric[];
+}
+
+/** Arguments accepted when rendering the built-in badge report. */
+declare interface RenderBadgesArguments {
+    destination: ResolvedCodometerMarkdownOutput;
+    scope: MeasurementScope;
+    statistics: CodeStatisticsResult;
+    targets: readonly TargetSize[];
+}
+
+/** Arguments accepted when rendering the configuration listing. */
+export declare interface RenderConfigurationArguments {
+    described: readonly ConfiguredDirectory[];
+    format: string;
+    limitRows: readonly ConfiguredLimitRow[];
+    limitsOnly: boolean;
+    rootError: string | undefined;
+}
+
+/**
+ * Turns a resolved configuration listing into the document a reader gets.
+ *
+ * Markdown by default because the listing is a table and a repository already
+ * reads codometer's output as markdown; JSON when something downstream parses
+ * it. Kept apart from the command so the shape of the document is testable
+ * without a command line, and apart from the service so gathering the
+ * configuration never depends on how it will be shown.
+ */
+export declare class RenderConfigurationService {
+    constructor();
+    /** Renders everything one configuration file resolved to. */
+    private renderDirectory;
+    /** Renders the limits as a markdown table, or a line saying there are none. */
+    private renderLimitsTable;
+    /** Renders a list of names, or an em dash when the list is empty. */
+    private renderNames;
+    /**
+     * Renders why nothing answered for the walk root, when nothing did.
+     *
+     * Nothing at all otherwise, so the caller's line list is unchanged. Said at
+     * the top of the document rather than left out: every limit below is still
+     * real, but the walk that found them ran on the built-in exclusions rather
+     * than the ones this repository declares.
+     */
+    private renderRootError;
+    /** Renders one markdown table row, escaping nothing a path may not hold. */
+    private renderRow;
+    /** Renders the listing in the requested format. */
+    render(args: RenderConfigurationArguments): string;
+}
+
+/** Arguments accepted when rendering a whole document of badges. */
+declare interface RenderDocumentArguments {
+    /** Placed above the badges, exactly as a spliced block places it. */
+    description: string | undefined;
+    scope: MeasurementScope;
+    statistics: CodeStatisticsResult;
+    targets: readonly TargetSize[];
+}
+
+/** Renders a codometer change collection as the body of a report. */
+export declare class RenderModule {
+}
+
+/** Arguments accepted when rendering a report as JSON. */
+export declare interface RenderReportArguments<Report> {
+    indentation: number;
+    report: Report;
+}
+
+/** Arguments for rendering the whole section. */
+export declare interface RenderSectionArguments {
+    /** Run the baseline came from, linked from the comparison line. */
+    baselineUrl: string | undefined;
+    /** What this run could not measure, so an absent row is never silent. */
+    failures: readonly ProjectFailure[];
+    rows: readonly MetricRow[];
+}
+
+/** Renders codometer's measured changes as the body of the report. */
+export declare class RenderService {
+    constructor();
+    /** Groups items by whatever project name a case picks out of each one. */
+    private groupByProject;
+    /**
+     * Whether a project's block should open expanded.
+     *
+     * A breach or a measurement failure must never sit behind a click, so those
+     * two are the only reasons a block starts open. Everything else — a metric
+     * that merely changed — is exactly the kind of thing a collapsed block
+     * exists to keep off the screen by default.
+     */
+    private readIsOpen;
+    /** Every project name either a row or a failure mentions, in sorted order. */
+    private readProjects;
+    /**
+     * Picks the icon for one row, in priority order: a row that disappeared or
+     * matched nothing outranks a breach, and a breach outranks plain growth.
+     */
+    private readStatus;
+    /** Names the run the baseline came from, when there was one to compare against. */
+    private renderComparison;
+    /**
+     * Names everything the run could not do, above the table rather than below.
+     *
+     * A failed target produces no row at all, so without this a project's block
+     * can be empty of rows and still have something to say. A failure is
+     * neither a breach nor staleness — it is the run not having finished — so it
+     * is reported as its own thing and never folded into a metric's value.
+     */
+    private renderFailures;
+    /** Renders one project's block, or nothing if it has nothing to show. */
+    private renderProject;
+    /** Renders one table row. */
+    private renderRow;
+    /**
+     * Renders the report body: its heading, and one block per project with
+     * something to show.
+     */
+    renderSection(args: RenderSectionArguments): string;
+}
+
+/**
+ * Where a project's codometer run leaves its report.
+ *
+ * One glob per workspace directory rather than a single recursive sweep, so a
+ * stray report inside `node_modules` or a build output directory cannot be
+ * mistaken for a project's own measurement.
+ */
+export declare const REPORT_GLOBS: string[];
+
+/** One report's failure entry, as codometer writes it. */
+declare type ReportFailure = NonNullable<CodometerReport["failures"]>[number];
+
+/**
+ * One metric codometer measured, and whatever limits it.
+ *
+ * Everything a row needs from the report itself, before the project it belongs
+ * to and the baseline it is compared against are joined onto it. Carries every
+ * metric a target produced — a byte count, a symbol count, anything — never
+ * filtered by unit or by whether a limit was configured.
+ */
+declare interface ReportMetric {
+    /**
+     * The severity of the worst limit this metric breached, if it breached one.
+     *
+     * One field for three states rather than a flag beside a severity, because
+     * "breached, severity unknown" is not a state a metric can be in. `undefined`
+     * is no breach, `"warn"` is advisory, `"fail"` stops the change.
+     */
+    breach: MetricSeverity | undefined;
+    /**
+     * True when the target's globs matched no files.
+     *
+     * Read straight off the report rather than inferred from a zero, because a
+     * target that matched nothing clears every limit written against it while
+     * measuring nothing at all — and a target that genuinely measures zero is a
+     * different thing entirely.
+     */
+    empty: boolean;
+    /** What the row is called in the table: the written label, else its target. */
+    label: string;
+    /**
+     * The enforced limit, absent where nothing limits the metric.
+     *
+     * The lowest `fail` limit when there is one, else the lowest `warn` limit.
+     * An advisory limit sitting below it is carried by the row's breach severity
+     * instead.
+     */
+    limit: number | undefined;
+    /**
+     * The metric's name, which is the key it joins to its baseline on.
+     *
+     * Stable by construction — codometer builds it from the target's name and the
+     * metric's path within that target, both of which are written in the
+     * configuration — so a metric present on both sides never reads as one
+     * removal plus one addition.
+     */
+    name: string;
+    /** What `value` is denominated in, so a renderer can format it correctly. */
+    unit: MetricUnit;
+    value: number;
+}
+
+/**
+ * NestJS module that renders a measurement as codometer's own report.
+ */
+export declare class ReportModule {
+}
+
+/**
+ * Writes out what a run measured, in codometer's own shape.
+ *
+ * Every metric is listed whether or not anything limits it, and a limit is
+ * listed whether or not it was breached, so one document answers both "what is
+ * this repository" and "what is it held to". Nothing is signalled by a missing
+ * field: an empty match says so, and a metric nobody limited carries an
+ * explicit `null` rather than no limit key at all.
+ */
+export declare class ReportService {
+    constructor();
+    /** Writes out one limit as the report carries it. */
+    private buildLimit;
+    /** The name a metric answers to across runs. */
+    private buildMetricName;
+    /** Writes out every metric one target measured, in the order counted. */
+    private buildMetrics;
+    /**
+     * Indexes the evaluated limits by the metric each one landed on.
+     *
+     * Keyed by the joined name rather than by the written path, because two
+     * limits may be written differently — one qualified, one leaning on the
+     * default target — and still address the same metric.
+     *
+     * Collected rather than overwritten. Several limits may land on one metric,
+     * and keeping only the last would report a limit the gate is not the only
+     * one enforcing.
+     */
+    private indexLimits;
+    /** What a metric's number counts, where that is anything but things. */
+    private readUnit;
+    /**
+     * Builds the report for one measurement.
+     *
+     * Targets keep the order they were measured in and metrics the order they
+     * were counted in, so two runs over one tree produce byte-identical
+     * documents — which is the whole of what makes staleness meaningful.
+     */
+    build(args: BuildReportArguments): CodometerReport_2;
+}
+
+/** Arguments accepted when resolving where each output goes. */
+export declare interface ResolveDestinationsArguments {
+    configuration: ResolvedCodometerConfiguration;
+    options: MeasureCommandOptions;
+    workingDirectory: string;
+}
+
+/** Every file one run writes, and the destinations found along the way. */
+export declare interface ResolveDestinationsResult {
+    destinations: RunDestinations;
+    errors: string[];
+}
+
+/** A JSON output destination, resolved for this run. */
+export declare interface ResolvedJsonDestination {
+    custom: ResolvedCodometerCustomStatistic[];
+    indentation: number;
+    path: string;
+}
+
+/** A markdown output destination, resolved for this run. */
+export declare interface ResolvedMarkdownDestination {
+    custom: ResolvedCodometerCustomStatistic[];
+    description: string | undefined;
+    endMarker: string;
+    path: string | undefined;
+    startMarker: string;
+    type: "markdown";
+    write: undefined | WriteMarkdownOutput;
+}
+
+/**
+ * Every file one run writes.
+ *
+ * Two independent sinks: `json` is the report, and `markdown` is the badge
+ * block spliced between two markers in a file somebody else wrote the rest
+ * of. Neither says anything about standard output — that is `format`'s job
+ * alone, so no destination can print a second document over the one a
+ * pipeline was reading.
+ */
+export declare interface RunDestinations {
+    json: ResolvedJsonDestination | undefined;
+    markdown: ResolvedMarkdownDestination | undefined;
+}
+
+/**
+ * Metric suffix marking a limit whose value is a number of bytes.
+ *
+ * A limit's value is a bare number by the time it is resolved, so nothing left
+ * in the configuration says whether `256000` is a size or a count of files.
+ * The metric path is what still does: only a size analysis produces `.size`.
+ */
+export declare const SIZE_METRIC_SUFFIX = ".size";
+
+/** Arguments accepted when syncing a JSON file with a report. */
+export declare interface SyncJsonArguments<Report> {
+    check: boolean;
+    indentation: number;
+    path: string;
+    report: Report;
+}
+
+/** Arguments accepted when syncing a markdown destination with the statistics. */
+declare interface SyncMarkdownArguments {
+    check: boolean;
+    destination: ResolvedCodometerMarkdownOutput;
+    scope: MeasurementScope;
+    statistics: CodeStatisticsResult;
+    targets: readonly TargetSize[];
+}
+
+/** Column headers for a project's metrics table. */
+export declare const TABLE_HEADER: string[];
+
+/**
+ * One declared target's measured size, as the badge block reports it.
+ *
+ * Only the targets a run actually measured the size of reach this. A run that
+ * declared none — the whole-repository run, which measures source and has no
+ * build output of its own — renders no size badges at all, so the aggregate
+ * README keeps the single `Repository Size` figure it already carries.
+ */
+export declare interface TargetSize {
+    bytes: number;
+    compression: CodometerCompression;
+    name: string;
+}
+
+/** The exclusions a configuration walk uses, and why they may be the defaults. */
+export declare interface WalkExclusions {
+    /** Why the walk root's configuration could not be read, if it could not. */
+    error: string | undefined;
+    exclude: string[];
+    excludeFrom: string[];
+}
+
+export { }