@codometer/measurement 0.0.0-stage → 0.0.1

package/dist/src/index.d.ts

@@ -0,0 +1,1280 @@
+import { CodeStatisticsResult } from '@codometer/core';
+import { CodometerCompression } from '@codometer/configuration';
+import { CodometerSeverity } from '@codometer/core';
+import { CommentCounter } from '@codometer/languages';
+import { CommentMeasurement } from '@codometer/languages';
+import { ConsoleLogger } from '@nestjs/common';
+import { CustomStatisticResult } from '@codometer/core';
+import { CustomStatisticResultInstance } from '@codometer/core';
+import { Ignore } from 'ignore';
+import { LanguagesService } from '@codometer/languages';
+import pino from 'pino';
+import { ReportFailure } from '@codometer/core';
+import { ResolvedCodometerConfiguration } from '@codometer/configuration';
+import { ResolvedCodometerCustomStatistic } from '@codometer/configuration';
+import { ResolvedCodometerInput } from '@codometer/configuration';
+import { TypescriptSymbolCounter } from '@codometer/languages';
+
+/** Arguments accepted when measuring the size of a target's files. */
+export declare interface AnalyzeSizeArguments {
+    compression: CodometerCompression;
+    /** Paths relative to the working directory, as the target matched them. */
+    files: string[];
+    workingDirectory: string;
+}
+
+/** Arguments accepted when building a rule set from patterns already in hand. */
+declare interface CreateIgnoreScopeArguments {
+    directory: string;
+    patterns: string[];
+}
+
+/** Input to the custom statistics step. */
+export declare interface CustomizationInput {
+    /**
+     * Every `comment`-selector counter's own measurements, keyed by its
+     * statistic's label.
+     *
+     * Built by measuring the counters `buildCommentCounters` returns, then
+     * merging the two results back together by label — the languages package
+     * measures a counter naming a declaration kind and one naming a language
+     * through two different calls, but a label belongs to exactly one custom
+     * statistic either way.
+     */
+    commentCounts: Record<string, CommentMeasurement[]>;
+    /** Every file of the target being counted over. */
+    files: string[];
+    statistics: ResolvedCodometerCustomStatistic[];
+    /** What the TypeScript analyzer tallied, keyed by counter label. */
+    symbolCounts: Record<string, number>;
+}
+
+/**
+ * NestJS module that provides the configured file-name counters.
+ */
+export declare class CustomizationModule {
+}
+
+/**
+ * Counts the conventions a repository holds itself to.
+ *
+ * The languages a repository is written in are the same everywhere; what a
+ * `*.service.ts` means, or whether a static method is something to keep an
+ * eye on, is not — which is why these counters come from the configuration
+ * rather than from this package.
+ *
+ * A counter measures files by path, declarations by shape, or a comment
+ * budget by length. The file half is done here; the declaration half is
+ * tallied by the TypeScript analyzer during the walk it already makes, and
+ * the comment half by `@codometer/languages`' comment services — both arrive
+ * here as counts to be labelled.
+ */
+export declare class CustomizationService {
+    constructor();
+    /** Turn a `comment`-selector statistic's own breaches into its result. */
+    private buildCommentResult;
+    /**
+     * Counts the target's files that at least one of the globs claims.
+     *
+     * A file matching several globs of the same counter is one file, not
+     * several: the counter asks how many files there are, not how many times
+     * they matched.
+     */
+    private countMatches;
+    /** Count every configured statistic over the discovered files. */
+    analyze({ commentCounts, files, statistics, symbolCounts, }: CustomizationInput): CustomStatisticResult[];
+    /**
+     * Pick out the counters `@codometer/languages`' comment services have to
+     * measure.
+     *
+     * Handed to those services rather than measured again here: a `comment`
+     * selector names a language or a documentable kind, and turning that into a
+     * budget is this package's business, not the tokenizer's. One list, mirroring
+     * the selector field for field — which counter a given measurer takes is
+     * decided by each measurer, which selects from the list by reading `kind`.
+     */
+    buildCommentCounters(statistics: CustomizationInput["statistics"]): CommentCounter[];
+    /**
+     * Pick out the counters the TypeScript analyzer has to tally.
+     *
+     * Handed to that analyzer rather than parsed again here: it already walks
+     * every source file, and a second walk would double the slowest part of a
+     * run to learn what the first one passed straight over.
+     */
+    buildSymbolCounters(statistics: CustomizationInput["statistics"]): TypescriptSymbolCounter[];
+}
+
+/** Arguments accepted when discovering the files to measure. */
+export declare interface DiscoverFilesArguments {
+    exclude: string[];
+    excludeFrom: string[];
+    workingDirectory: string;
+}
+
+/**
+ * NestJS module that discovers and categorizes the files of a codebase.
+ */
+export declare class DiscoveryModule {
+}
+
+/** Categorized lists of file paths, relative to the working directory. */
+export declare interface DiscoveryResult {
+    cssFiles: string[];
+    /** Every file the target holds, before any category claims it. */
+    files: string[];
+    hclFiles: string[];
+    jsFiles: string[];
+    jsonFiles: string[];
+    markdownFiles: string[];
+    notebookFiles: string[];
+    pyFiles: string[];
+    shellFiles: string[];
+    sourceFiles: string[];
+    sqlFiles: string[];
+    testFiles: string[];
+    tomlFiles: string[];
+    tsFiles: string[];
+    yamlFiles: string[];
+}
+
+/** Discovers and categorizes the files of a codebase directory. */
+export declare class DiscoveryService {
+    private readonly ignoreRulesService;
+    private readonly logger;
+    constructor(ignoreRulesService: IgnoreRulesService, logger: LoggerService);
+    /**
+     * Folds a directory's own `.gitignore` into the rule sets already in force.
+     *
+     * Appended last so its patterns outrank the ones above it, which is how git
+     * resolves a nested ignore file: the closest one to the file wins.
+     */
+    private applyDirectoryIgnoreFile;
+    /** Selects the discovered files whose extension belongs to a category. */
+    private filterByExtension;
+    /**
+     * Whether any exclusion glob claims the given repository-relative path.
+     *
+     * Matched with `path.matchesGlob` rather than by substring, so a glob naming
+     * a `dist` directory removes build output and leaves a `redistribute`
+     * directory alone.
+     */
+    private isExcluded;
+    /**
+     * Whether every file beneath a directory is excluded by a glob already.
+     *
+     * A pattern ending in `/**` claims every descendant without exception, so a
+     * directory matching the pattern with that suffix removed cannot contribute
+     * a single file and never has to be read. This is a shortcut and not a rule
+     * of its own: the same files would be dropped one by one afterwards either
+     * way. It matters in a directory with no `.gitignore` to prune
+     * `node_modules`, where reading it dwarfs reading the codebase.
+     */
+    private isExhaustivelyExcluded;
+    /**
+     * Whether either set of ignore rules claims a path.
+     *
+     * The two sets are answered independently and the answers combined, rather
+     * than merged into one set. A configured ignore file subtracts from what the
+     * repository's own `.gitignore` files leave behind, exactly as the two git
+     * invocations this replaced did; a negation in one cannot resurrect a file
+     * the other removed.
+     */
+    private isIgnoredPath;
+    /**
+     * Lists every measurable file in the given directory, in sorted order.
+     *
+     * Sorted because the walk visits directories in whatever order the
+     * filesystem reports them, and every consumer downstream deserves the same
+     * list from the same tree on any machine.
+     */
+    private listDiscoveredFiles;
+    /**
+     * Reads a directory's entries, or none when the directory cannot be read.
+     *
+     * A directory can vanish or refuse to open partway through a walk — one
+     * being cleaned up by another process, a mount the caller has no permission
+     * on. Shelling out to git never failed for either reason, so letting one
+     * unreadable directory abort the whole measurement would be a regression:
+     * warn, skip it, and keep counting the rest.
+     */
+    private readDirectoryEntries;
+    /**
+     * Reads the configured ignore files into rule sets anchored at the root.
+     *
+     * A missing file is a warning rather than a failure: a repository that has
+     * renamed its ignore file should hear about it, but a report is still worth
+     * more than a crash.
+     */
+    private readExcludeFromScopes;
+    /**
+     * Collects every measurable file under one directory.
+     *
+     * Walked directory by directory rather than matched by a single recursive
+     * glob, because an ignored directory then costs one decision instead of an
+     * enumeration: `node_modules/` is pruned where it is named, not discovered
+     * in full and thrown away.
+     */
+    private walkDirectory;
+    /**
+     * Descends into one subdirectory, or skips it when nothing there counts.
+     *
+     * The trailing slash is what makes a `coverage/` pattern claim the directory
+     * itself: without it the pattern only ever matches a file of that name.
+     */
+    private walkSubdirectory;
+    /**
+     * Sorts a list of file paths into the categories the analyzers ask for.
+     *
+     * Separate from the walk so that any target's files can be categorized, not
+     * only the ones this service found itself: a target naming its files by glob
+     * is analyzed by the same language analyzers as the codebase around it.
+     */
+    categorize(files: string[]): DiscoveryResult;
+    /** Returns categorized file path lists for the given codebase root. */
+    discoverFiles(args: DiscoverFilesArguments): DiscoveryResult;
+}
+
+/** A target name that answered to more than one measured target. */
+declare interface DuplicateTargetFinding {
+    reason: string;
+    target: string;
+}
+
+/**
+ * Raised when a target carrying a limit matched no files at all.
+ *
+ * Writing a limit asserts the files exist, so nothing to measure means a glob
+ * that no longer matches or a build that never ran — either way a number that
+ * would pass every limit written against it. A target nobody limited is left
+ * alone: there it is simply zero, and unremarkable.
+ */
+export declare class EmptyTargetError extends Error {
+    constructor(target: string, metric: string);
+}
+
+/**
+ * What one limit found once it was pointed at its metric.
+ *
+ * A breach is one of these carrying `breached`, and it reports everything a
+ * breach has to: which metric, held to what, and what the metric actually
+ * measured. A limit that held is reported the same way, so a report can show
+ * the headroom rather than only the failures.
+ */
+export declare interface EvaluatedLimit {
+    /** Whether the measured value came out above the limit. */
+    breached: boolean;
+    /** Stays `undefined` when none was written; a report falls back to the path. */
+    label: string | undefined;
+    limit: number;
+    measured: number;
+    /** The metric's path within its target, with no target name on the front. */
+    metric: string;
+    severity: CodometerSeverity;
+    target: string;
+}
+
+/** Arguments accepted when evaluating every declared limit. */
+declare interface EvaluateLimitsArguments {
+    configuration: ResolvedCodometerConfiguration;
+    indexes: ReadonlyMap<string, TargetMetricIndex>;
+}
+
+/**
+ * Reads and applies gitignore-syntax rule sets without invoking git.
+ *
+ * Codometer used to hand this problem to `git ls-files`, which meant it could
+ * only measure a directory that was a git repository. Reading the syntax here
+ * is what lets it measure any directory at all, and it is the only reading of
+ * that syntax in the tool — there is no git fast path to disagree with.
+ */
+declare class IgnoreRulesService {
+    constructor();
+    /**
+     * The path a rule set sees, or nothing when the path lies outside it.
+     *
+     * A rule set anchored at `applications/affirmations` matches its patterns
+     * against `output/one.md`, not against the full path, because that is what
+     * the patterns in that directory's ignore file were written against.
+     */
+    private toScopedPath;
+    /**
+     * Builds a rule set from patterns already in hand.
+     *
+     * Case-sensitive on every platform, deliberately. Git decides that from the
+     * filesystem it happens to be on, so the same ignore file can claim a
+     * different set of files on a developer's Mac and on Linux CI. A measurement
+     * that disagrees with itself between machines is worse than a strict one.
+     */
+    createScope(args: CreateIgnoreScopeArguments): IgnoreScope;
+    /**
+     * Whether the rule sets ignore a path, the innermost one deciding.
+     *
+     * gitignore resolution is nested rather than additive: a rule set in a
+     * subdirectory overrides the one above it, which is what lets a `!pattern`
+     * re-include a file its parent excluded. Reading the scopes outermost first
+     * and keeping the last decision reproduces that ordering.
+     *
+     * A directory is passed with a trailing slash, so a `build/` pattern claims
+     * the directory rather than only a file that happens to be named `build`.
+     */
+    isIgnored(scopes: readonly IgnoreScope[], relativePath: string): boolean;
+    /**
+     * Reads a rule set out of a gitignore-syntax file.
+     *
+     * Returns nothing when the file is absent, so a configured ignore file that
+     * was renamed is reported by the caller rather than silently behaving as an
+     * empty one.
+     */
+    readScope(args: ReadIgnoreScopeArguments): IgnoreScope | undefined;
+}
+
+/**
+ * A gitignore-syntax rule set together with the directory it is anchored to.
+ *
+ * The directory matters because gitignore patterns are relative to the file
+ * they were written in: `/output` in a project's own ignore file claims that
+ * project's `output`, not the one at the repository root.
+ */
+declare interface IgnoreScope {
+    /** Directory the patterns are relative to, `/`-separated from the walk root. `""` is the root itself. */
+    directory: string;
+    matcher: Ignore;
+}
+
+/** What a directory entry counts as while an input's tree is walked. */
+export declare type InputEntryKind = "directory" | "file" | "other";
+
+/**
+ * What every analysis declared for one input reported over its files.
+ *
+ * An analysis an input did not ask for reports `undefined` rather than a zero,
+ * so an input nobody measured the size of is never mistaken for an empty one.
+ */
+export declare interface InputMeasurement {
+    /** How many files the input's globs claimed. */
+    files: number;
+    language: CodeStatisticsResult | undefined;
+    name: string;
+    size: SizeResult | undefined;
+}
+
+/**
+ * Raised when an input's directory reaches outside the repository.
+ *
+ * An input may name its way out of the folder being measured — that is how a
+ * project reaches build output written above it — but not out of the
+ * repository holding both. Beyond that boundary a configuration file could
+ * read any file on the machine and report its size, which is not a measurement
+ * anybody asked for and is exactly what a tool published as a shared action
+ * must not be able to do.
+ */
+export declare class InputOutsideRepositoryError extends Error {
+    constructor(input: string, directory: string, boundary: string);
+}
+
+/**
+ * NestJS module that lists the files each declared input holds.
+ */
+export declare class InputsModule {
+}
+
+/**
+ * Lists the files an input holds.
+ *
+ * Globs alone decide, with no ignore file consulted: an input exists to name a
+ * part of the tree outright, and the most useful part to name is compiled
+ * output, which every repository's ignore files claim.
+ */
+export declare class InputsService {
+    private readonly logger;
+    constructor(logger: LoggerService);
+    /**
+     * Whether a directory can hold anything the input's globs claim.
+     *
+     * A hidden directory is only entered when a glob spells it out. That is what
+     * every glob library means by excluding dot files, and it is also what stops
+     * an input over the whole tree from reading the repository's git database.
+     */
+    private canDescend;
+    /**
+     * The furthest out an input is allowed to reach, from where the run started.
+     *
+     * The repository holding the measured directory, or that directory itself
+     * when nothing above it looks like one. Found by marker rather than by
+     * asking git, which is never invoked here, and generic to every repository —
+     * it says where measuring stops, not how any tree beneath it is arranged.
+     */
+    private findBoundary;
+    /** Whether the last segment of a path starts with a dot. */
+    private isHidden;
+    /**
+     * Whether a symbolic link points at a file.
+     *
+     * Links are followed, as every glob library does. Only to files, though: a
+     * link pointing back at one of its own ancestors would otherwise be walked
+     * until the stack ran out.
+     */
+    private isLinkedFile;
+    /**
+     * Whether the input claims a file.
+     *
+     * Both lists are answered in full rather than in order, so where a pattern
+     * sits within either of them cannot change the answer.
+     */
+    private isMatched;
+    /** Whether the directory is on the way down to a glob's literal prefix. */
+    private leadsToBase;
+    /**
+     * Reads a directory's entries, or none when the directory cannot be read.
+     *
+     * An input naming a directory that was never built is an ordinary state
+     * rather than a failure — it holds no files, and what that means is decided
+     * by whoever asked for the measurement.
+     */
+    private readEntries;
+    /**
+     * The measured-directory-relative prefix every matched path carries.
+     *
+     * Empty when the input starts where the run does. Otherwise it is the walk
+     * root written relative to the measured directory — `../../dist` and the
+     * like — so that every path leaving this service is relative to the same
+     * directory whether or not the input reached outside it.
+     */
+    private readInputPrefix;
+    /** What a directory entry counts as, once any link has been followed. */
+    private resolveEntryKind;
+    /** Whether the directory sits inside a glob's literal prefix. */
+    private sitsInsideBase;
+    /** Whether a directory is the boundary or sits somewhere beneath it. */
+    private sitsInsideBoundary;
+    /**
+     * The literal path prefix of a glob, up to its first magic character.
+     *
+     * `dist/packages/logger/**` can only match inside `dist/packages/logger`, so
+     * that is the only branch of the tree worth reading — the difference between
+     * measuring one build directory and enumerating every dependency to find it.
+     */
+    private toIncludeBase;
+    /** Collects every file one directory of the input's tree contributes. */
+    private walk;
+    /**
+     * Lists the files an input holds, sorted, relative to the measured directory.
+     *
+     * The walk starts at the input's own directory, which is the measured one
+     * unless the input named a way out of it. Where a repository builds is a
+     * convention its configuration states and this service is told, never one
+     * inferred here from a project's position — but the reach is bounded: a
+     * directory landing outside the repository fails the input by name rather
+     * than measuring whatever it found there.
+     *
+     * Sorted because the walk visits directories in whatever order the
+     * filesystem reports them, and a size is a sum of every file either way —
+     * but a list nobody can predict is one nobody can compare.
+     */
+    matchFiles(args: MatchInputFilesArguments): string[];
+}
+
+/**
+ * One limit that could not be held against anything.
+ *
+ * Collected rather than thrown. A configuration carrying three limits that
+ * bind to nothing is three mistakes to fix, and reporting only the first turns
+ * one repair into three runs.
+ */
+declare interface LimitFailure {
+    /** The dotted path exactly as the limit was written. */
+    metric: string;
+    reason: string;
+}
+
+/**
+ * What every declared limit found, alongside the ones that bound to nothing.
+ *
+ * Both lists are always present. A limit that could not be bound is neither a
+ * breach nor a pass, and reporting it as either would be a gate whose verdict
+ * nobody could trust.
+ */
+declare interface LimitsEvaluation {
+    failures: LimitFailure[];
+    limits: EvaluatedLimit[];
+}
+
+/**
+ * NestJS module that holds measured metrics to their declared limits.
+ */
+export declare class LimitsModule {
+}
+
+/**
+ * Holds measured metrics to the limits declared against them.
+ *
+ * Every metric is addressable, whichever analysis produced it, by a dotted
+ * path of target name and metric path. Nothing here decides what a breach
+ * costs: it reports which limits were exceeded and how badly, and what that is
+ * worth is the caller's to say.
+ */
+export declare class LimitsService {
+    constructor();
+    /** Binds one metric path within one target, if that target measured it. */
+    private bind;
+    /** Names one binding the way an error message reads it out. */
+    private describeBinding;
+    /** Reads whatever a failed binding threw as the sentence a report prints. */
+    private describeFailure;
+    /** Names every measured target, for an error that has to list them. */
+    private describeTargets;
+    /**
+     * Every metric a written path could mean.
+     *
+     * Each target is asked whether the path starts with its name, rather than
+     * the path being split at its first dot: a target's name may hold a dot of
+     * its own, and so may the metric path that follows it. Whatever the shapes
+     * involved, every reading is collected and none of them is preferred.
+     */
+    private findCandidates;
+    /**
+     * What the path would mean read as the default target's, if one is set.
+     *
+     * A default target that was never measured is refused rather than ignored:
+     * ignoring it would turn every unqualified path in the configuration into an
+     * unresolvable one, and report the paths instead of the reason.
+     */
+    private findDefaultCandidate;
+    /**
+     * Points one written path at exactly one measured metric.
+     *
+     * Ambiguity is refused rather than settled by a rule about which reading
+     * wins. Any such rule would be invisible in the configuration file, and a
+     * limit holding a metric nobody meant to limit reads exactly like one that
+     * works.
+     */
+    private resolve;
+    /**
+     * Holds every declared limit against the metric it addresses.
+     *
+     * Returns what each limit found rather than a verdict. Severity is carried
+     * through untouched: whether a breach stops the run is a decision about the
+     * run, not about the measurement.
+     *
+     * A limit that binds to nothing joins `failures` and the rest are evaluated
+     * anyway, so one run names every path in a configuration that binds to
+     * nothing instead of the first one and nothing after it.
+     */
+    evaluate(args: EvaluateLimitsArguments): LimitsEvaluation;
+}
+
+/**
+ * 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,
+        );
+    }
+}
+
+/** Arguments accepted when listing the files an input holds. */
+export declare interface MatchInputFilesArguments {
+    input: ResolvedCodometerInput;
+    workingDirectory: string;
+}
+
+/**
+ * Arguments accepted by the measurement pipeline.
+ */
+export declare interface MeasureArguments {
+    configuration: ResolvedCodometerConfiguration;
+    /**
+     * Files codometer writes itself, relative to the measured directory.
+     *
+     * Never measured, whether or not this particular run writes them: a run that
+     * measured a different tree depending on its flags could not tell a stale
+     * report from a report written by a differently-flagged run.
+     */
+    outputPaths: readonly string[];
+    workingDirectory: string;
+}
+
+/**
+ * What one target measured, as the limits layer reads it.
+ *
+ * Declared here rather than imported from the measurement pipeline: gating a
+ * number needs the number and its target's name, and nothing about how either
+ * was produced.
+ */
+declare interface MeasuredTarget {
+    files: number;
+    language: CodeStatisticsResult | undefined;
+    name: string;
+    size: SizeResult | undefined;
+}
+
+/**
+ * Everything one run measured, input by input.
+ *
+ * `statistics` is the `codebase` input's own language metrics, which is the
+ * report every consumer renders today. It is the same object that input
+ * carries, held out separately so nothing downstream has to know which input
+ * it came from.
+ */
+export declare interface MeasurementResult {
+    /**
+     * Whatever the run could not do, collected rather than thrown.
+     *
+     * An input that will not measure and a limit that binds to nothing are both
+     * recorded here and stepped over, so one run names every one of them instead
+     * of stopping at the first and hiding the rest behind it.
+     */
+    failures: ReportFailure[];
+    /** Every metric each measured input counted, addressable by dotted path. */
+    indexes: Map<string, TargetMetricIndex>;
+    /** Every input measured, in the order `inputs` declared them. */
+    inputs: InputMeasurement[];
+    /**
+     * What every declared limit found, in the order they were declared.
+     *
+     * Empty when nothing declared one, which is the ordinary case: a metric with
+     * no limit is measured and reported like every other, and gated by nothing.
+     */
+    limits: EvaluatedLimit[];
+    statistics: CodeStatisticsResult;
+}
+
+/**
+ * Wires every analyzer a measurement run joins, and the service that joins
+ * them.
+ *
+ * The one module a host has to import to measure anything: discovery finds the
+ * files, the language and size analyzers count them, the custom counters add
+ * whatever a configuration declared, and the limits layer holds the result to
+ * what the configuration gates. None of the five imports another, which is why
+ * the join lives here rather than inside one of them.
+ */
+export declare class MeasureModule {
+}
+
+/**
+ * Aggregates every analyzer's report into a single set of statistics.
+ *
+ * The one place the discovery, language, size, and customization analyzers
+ * meet. None of the four imports another, so joining them has to happen
+ * somewhere, and a call-stack trace reports that join as module spread against
+ * `measureInput` and `analyzeFiles` — the two methods that personally name
+ * three of the four. That is the arrangement working, not drifting: pushing the
+ * join down into one of the analyzers is what would couple them to each other.
+ */
+export declare class MeasureService {
+    private readonly discoveryService;
+    private readonly languagesService;
+    private readonly customizationService;
+    private readonly inputsService;
+    private readonly sizeService;
+    private readonly limitsService;
+    private readonly metricIndexService;
+    constructor(discoveryService: DiscoveryService, languagesService: LanguagesService, customizationService: CustomizationService, inputsService: InputsService, sizeService: SizeService, limitsService: LimitsService, metricIndexService: MetricIndexService);
+    /**
+     * Run every analyzer over one set of files and shape the result.
+     *
+     * Three analyzers, not one: the language analyzers, the size analyzer that
+     * produces the headline byte total, and the custom counters a configuration
+     * declares. Named for the file set rather than for any of the three, because
+     * this sits directly above `LanguagesService.analyze` in every measurement
+     * stack — named for a language it reads there as a forwarding layer instead
+     * of as the place all three are joined.
+     *
+     * Takes the files it is given rather than finding them, so the codebase and
+     * an input naming compiled output are counted by exactly the same analyzers.
+     */
+    private analyzeFiles;
+    /** Project the TypeScript analyzer's counters onto the JavaScript group. */
+    private buildJavascriptStatistics;
+    /** Project the TypeScript analyzer's counters onto the TypeScript group. */
+    private buildTypescriptStatistics;
+    /** Reads whatever an input's measurement threw as a printable sentence. */
+    private describeFailure;
+    /**
+     * Discovers one input's files, minus the ones codometer writes itself.
+     *
+     * The built-in `codebase` input is discovered by whatever its ignore files
+     * leave behind rather than by matching its own `include`/`exclude` globs —
+     * those stay placeholders for that one input, exactly as
+     * `@codometer/configuration` documents. Every other input's files are
+     * whatever its globs claim.
+     */
+    private discoverInputFiles;
+    /**
+     * Drops the files codometer writes from a list of measured ones.
+     *
+     * Codometer's reports are made of what it measured, so measuring them makes
+     * every report an input to the next one: a badge block changes the markdown
+     * counters, which changes the badges. Removing them is what makes a second
+     * run over an untouched tree produce the same bytes as the first.
+     */
+    private excludeOutputPaths;
+    /**
+     * Count the unique folders the input's files sit in.
+     */
+    private getFolderCount;
+    /**
+     * Measure one declared input with whichever analyses it asked for.
+     *
+     * An analysis nobody asked for is not run at all. Compressing a source tree
+     * to answer a question nobody put costs more than every other analysis put
+     * together.
+     */
+    private measureInput;
+    /** Restates the limits layer's failures in the report's own vocabulary. */
+    private readLimitFailures;
+    /** Whether an input asked for one of the analyses. */
+    private runsAnalysis;
+    /**
+     * Measure every input the configuration declares.
+     *
+     * The built-in `codebase` input is not special-cased here — resolution
+     * already prepends it unless a configuration replaces it by name, so this
+     * simply measures whichever inputs it was handed, in the order given. An
+     * input that cannot be measured — a glob pointing at a directory that
+     * vanished, a file that will not open — is recorded and stepped over, so one
+     * unreadable file never takes the whole run with it.
+     */
+    measure(args: MeasureArguments): MeasurementResult;
+}
+
+/** Every measured target's metrics, and the names two targets fought over. */
+declare interface MetricIndexResult {
+    /** Collisions found while indexing, in the order they were found. */
+    duplicates: DuplicateTargetFinding[];
+    indexes: Map<string, TargetMetricIndex>;
+}
+
+/**
+ * Makes every measured number addressable by a dotted path.
+ *
+ * The same index answers two questions that used to be one layer's private
+ * business: which metric a limit is written against, and which metrics the
+ * report has to list. Both need every number a target measured, named the same
+ * way, so the naming lives here rather than in either caller.
+ */
+export declare class MetricIndexService {
+    constructor();
+    /**
+     * Records one metric, or marks its path as answered by more than one.
+     *
+     * Two counters sharing a path is a configuration mistake rather than a
+     * measurement one — two statistics with the same label — and it is caught
+     * here so that a limit addressing that path is refused instead of being
+     * given whichever counter was indexed first.
+     */
+    private addMetric;
+    /**
+     * Indexes every metric one target measured, by its path within that target.
+     *
+     * An analysis the target never ran contributes nothing, so a limit written
+     * against it is refused rather than being compared against a zero the target
+     * never reported.
+     */
+    private buildTargetIndex;
+    /**
+     * Explains a name two measured targets both answered to.
+     *
+     * Written where the collision is found rather than raised as an error: the
+     * run carries on with the first target of that name, and this is what the
+     * report says about the one it had to drop.
+     */
+    private describeDuplicate;
+    /** Indexes a group of counters, descending into the nested ones. */
+    private indexCounters;
+    /**
+     * Indexes everything language analysis counted.
+     *
+     * Configured counters are indexed under a prefix rather than beside the
+     * built-in ones, so a counter labelled `files` cannot take the path the file
+     * count already answers to.
+     */
+    private indexLanguage;
+    /** Whether a statistics entry holds counters of its own. */
+    private isCounterGroup;
+    /**
+     * Indexes every measured target, by name.
+     *
+     * A repeated name is collected rather than thrown, so a run reports every
+     * naming collision it found instead of the first one. The later target is
+     * dropped: a metric is addressed by its target's name, so a name answering
+     * to two targets can address neither.
+     */
+    index(targets: readonly MeasuredTarget[]): MetricIndexResult;
+}
+
+/** A message split into the emoji the console shows and the prose telemetry stores. */
+declare interface ParsedLogMessage {
+    emoji: string | undefined;
+    text: string;
+}
+
+/** Arguments accepted when reading a rule set out of a gitignore-syntax file. */
+declare interface ReadIgnoreScopeArguments {
+    directory: string;
+    filePath: string;
+}
+
+/**
+ * NestJS module that measures the compressed size of a target's files.
+ */
+export declare class SizeModule {
+}
+
+/** What size analysis reported over one target. */
+export declare interface SizeResult {
+    /**
+     * Total bytes the target's files occupy under the chosen compression.
+     *
+     * A sum of separately compressed files rather than one compression of all of
+     * them: a browser fetches each file on its own, so compressing them together
+     * would report a number no client ever receives.
+     */
+    bytes: number;
+    compression: CodometerCompression;
+    files: number;
+}
+
+/** Measures how many bytes a target's files occupy once compressed. */
+export declare class SizeService {
+    private readonly logger;
+    constructor(logger: LoggerService);
+    /**
+     * Compresses one file's contents and reports the resulting byte count.
+     *
+     * Written as a lookup rather than a switch so that a compression added to
+     * the configuration without an implementation here fails to compile, instead
+     * of falling through to whichever branch happened to be last.
+     */
+    private compress;
+    /**
+     * Measures one file, or fails the run.
+     *
+     * A file can vanish between being matched and being read — a build running
+     * beside the measurement is enough. Skipping it would report a total short
+     * by that file while still counting it, which is a number that looks
+     * consistent and lets a real breach through. Failing is the lesser harm.
+     */
+    private measureFile;
+    /**
+     * Measures every file of a target and sums the results.
+     *
+     * Each file is compressed on its own. Compressing them together would let
+     * one file's dictionary shrink the next, reporting a total smaller than
+     * anything that will ever be transferred.
+     */
+    analyze(args: AnalyzeSizeArguments): SizeResult;
+}
+
+/** Every metric one target measured, addressable by dotted path. */
+export declare interface TargetMetricIndex {
+    /**
+     * Paths more than one metric answers to, which no limit may address.
+     *
+     * Two configured counters sharing a label is the way this happens. Either
+     * metric would be a defensible binding, which is exactly why neither is.
+     */
+    ambiguous: Set<string>;
+    files: number;
+    /**
+     * Where each metric's per-instance measurements were found, keyed by the
+     * same dotted path `metrics` uses.
+     *
+     * Only a metric a per-instance selector produced has an entry here — a
+     * `comment` selector today, and any future selector that measures more
+     * than a count. A metric with no entry counted matches and nothing more,
+     * so a consumer reading this map can tell the two apart without reading
+     * the configuration that produced either.
+     */
+    instances: Map<string, CustomStatisticResultInstance[]>;
+    metrics: Map<string, number>;
+}
+
+/**
+ * Raised when a limit's dotted path does not name exactly one metric.
+ *
+ * Both halves of that are failures worth stopping for. A path naming nothing
+ * gates nothing while looking like a gate, and a path naming several would
+ * have to pick one — and a limit quietly holding the wrong metric is a limit
+ * nobody would ever discover was wrong.
+ */
+export declare class UnboundMetricError extends Error {
+    constructor(path: string, reason: string);
+}
+
+/**
+ * Raised when a file a target matched cannot be read.
+ *
+ * Louder than the unreadable *directory* discovery tolerates, and deliberately
+ * so: a directory nobody can read narrows what was measured, while a matched
+ * file nobody can read makes the reported total wrong by definition. Size
+ * analysis exists to gate, and a number quietly short by one file lets a real
+ * breach pass.
+ */
+export declare class UnreadableTargetFileError extends Error {
+    constructor(filePath: string, reason: string);
+}
+
+/** Arguments accepted when walking one directory of the measured tree. */
+export declare interface WalkDirectoryArguments {
+    absoluteDirectory: string;
+    exclude: string[];
+    /** Rule sets from the configured ignore files, all anchored at the walk root. */
+    excludeFromScopes: readonly IgnoreScope[];
+    /** Rule sets from the `.gitignore` files seen so far, outermost first. */
+    ignoreScopes: readonly IgnoreScope[];
+    relativeDirectory: string;
+}
+
+/** Arguments accepted when walking one directory of an input's tree. */
+export declare interface WalkInputArguments {
+    absoluteDirectory: string;
+    /**
+     * The literal path prefix of each include glob.
+     *
+     * A glob's prefix is where its matches can begin, so a directory neither
+     * leading to a prefix nor sitting inside one holds nothing the input wants.
+     */
+    includeBases: readonly string[];
+    input: ResolvedCodometerInput;
+    relativeDirectory: string;
+}
+
+/** Arguments accepted when descending into one subdirectory. */
+export declare interface WalkSubdirectoryArguments extends WalkDirectoryArguments {
+    absolutePath: string;
+    relativePath: string;
+}
+
+export { }