@codometer/configuration 0.0.1

package/dist/src/index.d.ts

@@ -0,0 +1,1204 @@
+import { CodeStatisticsResult } from '@codometer/core';
+import { CodometerSeverity } from '@codometer/core';
+import { CodometerStatisticGroup } from '@codometer/core';
+import { CodometerSymbolKind } from '@codometer/core';
+import { CodometerSymbolModifier } from '@codometer/core';
+import { z } from 'zod';
+
+/** What `--check limits` asks the run to fail on: a breached failing limit. */
+export declare const CHECK_LIMITS = "limits";
+
+/**
+ * Everything `--check` accepts, in the order an error message lists them.
+ *
+ * Named here rather than spelled into each message, so the list a mistake is
+ * measured against and the list it is told about can never drift apart.
+ */
+export declare const CHECK_NAMES: string[];
+
+/** What `--check reports` asks the run to fail on: a stale written report. */
+export declare const CHECK_REPORTS = "reports";
+
+/** How a `--check` value is written: one comma-separated set, no spaces needed. */
+export declare const CHECK_SEPARATOR = ",";
+
+/** Analyses an input may ask to have run over it. */
+export declare const CODOMETER_ANALYSES: readonly ["language", "size"];
+
+/** Languages a `comment` selector may narrow itself to. */
+export declare const CODOMETER_COMMENT_LANGUAGES: readonly ["css", "hcl", "python", "shell", "sql", "toml", "typescript", "yaml"];
+
+/** Compressions an input may ask its size to be measured under. */
+export declare const CODOMETER_COMPRESSIONS: readonly ["brotli", "gzip", "none"];
+
+/** Units a documentation limit may measure a comment's length in. */
+export declare const CODOMETER_DOCUMENTATION_UNITS: readonly ["characters", "lines", "words"];
+
+/** Report shapes a run may produce. */
+export declare const CODOMETER_FORMATS: readonly ["json", "markdown"];
+
+/**
+ * An analysis codometer can run over an input.
+ *
+ * `language` parses the matched files and counts what they declare; `size`
+ * compresses them and counts bytes. Which of them an input runs is the only
+ * thing separating a source tree from build output.
+ */
+export declare type CodometerAnalysis = "language" | "size";
+
+/**
+ * A language a `comment` custom-statistic selector may narrow itself to.
+ *
+ * The same eight languages that used to carry their own `comments` override:
+ * every language this tool reads comments from except the JSDoc-style
+ * documentation a `kind` narrows to, which is not tied to one language.
+ */
+export declare type CodometerCommentLanguage = "css" | "hcl" | "python" | "shell" | "sql" | "toml" | "typescript" | "yaml";
+
+/**
+ * One comment measured against the limit its kind carries.
+ *
+ * Shared by every analyzer that measures comment length, so a JSDoc block and
+ * a YAML comment block reach the report through one channel and render with
+ * one line of markdown. `kind` is a plain string for that reason: a symbol
+ * kind and a comment kind are both written into it, and narrowing it here
+ * would make the union the property of whichever analyzer was added first.
+ */
+export declare interface CodometerCommentMeasurement {
+    breached: boolean;
+    /** What the comment documents: a declaration's name, or the comment itself. */
+    declaration: string;
+    file: string;
+    kind: string;
+    limit: number;
+    /** 1-indexed line the measured thing starts on. */
+    line: number;
+    measured: number;
+    severity: CodometerSeverity;
+    unit: CodometerDocumentationUnit;
+}
+
+/**
+ * Selects a comment budget for a `CodometerCustomStatistic` to measure.
+ *
+ * A matching custom statistic's `value` counts the blocks that broke this
+ * selector's own maxima, and its `instances` names each one's file and line.
+ * No selector inherits from another: a general budget and a narrower
+ * exception are both written out in full, rather than one merging over the
+ * other.
+ *
+ * Omitting `language` applies the budget to every language that has comments.
+ * Naming `kind` narrows the budget to a documented declaration's JSDoc-style
+ * comment for that kind, rather than a plain comment block.
+ */
+export declare interface CodometerCommentSelector {
+    kind?: CodometerSymbolKind | undefined;
+    language?: CodometerCommentLanguage | undefined;
+    /** How many characters a block may hold, markers and newlines and all. */
+    maximumCharacters?: number | undefined;
+    /** How many lines a block may span. */
+    maximumLines?: number | undefined;
+    /** How many words of prose a block may hold, once markers are stripped. */
+    maximumWords?: number | undefined;
+    /** How loudly a breach is reported. Defaults to `fail`, as limits do. */
+    severity?: CodometerSeverity | undefined;
+}
+
+/**
+ * How a target's files are compressed before size analysis counts them.
+ *
+ * `none` reports the bytes on disk. Named explicitly rather than inferred from
+ * which options are absent, because a compression nobody chose is a byte count
+ * nobody can explain.
+ */
+export declare type CodometerCompression = "brotli" | "gzip" | "none";
+
+/**
+ * Configuration authored in a `codometer.config.ts` file.
+ *
+ * Every field but `format` is optional, so a repository can leave its
+ * exclusions and output destinations unwritten until it has decided what they
+ * should be. `format` is the one thing every run must be told, and there is no
+ * built-in fallback for it — so a directory with no configuration file
+ * anywhere above it does not measure at all: it fails on the missing `format`
+ * exactly as a file that forgot to write one does. A shared default object,
+ * spread by each project's own file, is how a workspace states it once.
+ */
+export declare interface CodometerConfiguration {
+    /**
+     * Every counter this configuration measures, regardless of where — or
+     * whether — any of them is rendered.
+     *
+     * Declaring a counter here is what measures it; an `outputs[].custom` entry
+     * then only *selects* which of these labels that destination renders. A
+     * label an output selects that is not declared here is refused: selection
+     * cannot conjure a counter that was never measured.
+     */
+    custom?: CodometerCustomStatistic[] | undefined;
+    /**
+     * Input an unqualified limit's metric path belongs to.
+     *
+     * A limit addresses its metric by input name followed by metric path.
+     * Naming a default lets the input that dominates a repository's limits go
+     * unwritten, leaving `typescript.interfaces` where every line would
+     * otherwise repeat the same input name. A path that could be read either
+     * way is rejected rather than resolved, so the shorthand can never bind
+     * somewhere unintended.
+     */
+    defaultInput?: string | undefined;
+    exclude?: string[] | undefined;
+    /**
+     * Ignore files, in gitignore syntax, whose patterns also exclude files.
+     *
+     * For the committed-but-generated files no glob list should have to restate —
+     * lockfiles, vendored bundles, anything a repository already tells its other
+     * tools to skip. Files the repository's own `.gitignore` claims need no
+     * mention at all: discovery reads those files itself.
+     */
+    excludeFrom?: string[] | undefined;
+    /**
+     * Which report shape a run produces.
+     *
+     * Required, with no code-level fallback: a shared default object — spread
+     * by every project's own `codometer.config.ts` — is what sets it once for a
+     * workspace, and a configuration reaching neither it nor its own value
+     * fails to resolve rather than silently picking one.
+     */
+    format: CodometerFormat;
+    /**
+     * Named sets of files measured alongside — or instead of — the codebase.
+     *
+     * A built-in entry named `codebase` — the whole-tree scan, running the
+     * `language` analysis — is always present unless this array declares an
+     * entry of its own by that name, which replaces it outright. A
+     * configuration declaring no `inputs` at all gets exactly that built-in
+     * entry and nothing else, which is today's implicit whole-tree behavior.
+     */
+    inputs?: CodometerInput[] | undefined;
+    /**
+     * How high each measured metric may go.
+     *
+     * A metric nothing here names is measured and reported like every other one,
+     * and gated by nothing.
+     */
+    limits?: CodometerLimit[] | undefined;
+    /**
+     * Destinations the measured statistics are written to.
+     *
+     * An array of typed entries rather than a fixed-key object, so each entry
+     * carries its own `custom` counters independently of every other one.
+     *
+     * At most one entry per `type`: a second entry of a kind is refused rather
+     * than silently ignored, because `--output-json [path]` and
+     * `--output-markdown [path]` each name one path, so nothing on the command
+     * line could ever address a second destination of the same kind.
+     */
+    outputs?: CodometerOutput[] | undefined;
+    python?: CodometerPythonConfiguration | undefined;
+}
+
+/**
+ * Validates a configuration file's contents.
+ *
+ * Zod strips unknown keys rather than rejecting them, so a configuration
+ * written for a newer codometer still loads under an older one instead of
+ * failing on a field it has no opinion about. That is also what makes a
+ * removed field — `comments`, `documentation`, a per-language override —
+ * silently absent from the resolved configuration rather than a validation
+ * error.
+ */
+export declare const codometerConfigurationSchema: z.ZodObject<{
+    custom: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        color: z.ZodOptional<z.ZodString>;
+        comment: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodOptional<z.ZodEnum<{
+                function: "function";
+                class: "class";
+                enum: "enum";
+                getter: "getter";
+                interface: "interface";
+                method: "method";
+                property: "property";
+                setter: "setter";
+            }>>;
+            language: z.ZodOptional<z.ZodEnum<{
+                css: "css";
+                hcl: "hcl";
+                python: "python";
+                shell: "shell";
+                sql: "sql";
+                toml: "toml";
+                typescript: "typescript";
+                yaml: "yaml";
+            }>>;
+            maximumCharacters: z.ZodOptional<z.ZodNumber>;
+            maximumLines: z.ZodOptional<z.ZodNumber>;
+            maximumWords: z.ZodOptional<z.ZodNumber>;
+            severity: z.ZodOptional<z.ZodEnum<{
+                fail: "fail";
+                warn: "warn";
+            }>>;
+        }, z.core.$strip>>;
+        group: z.ZodOptional<z.ZodEnum<{
+            json: "json";
+            markdown: "markdown";
+            conventions: "conventions";
+            css: "css";
+            hcl: "hcl";
+            jupyter: "jupyter";
+            python: "python";
+            repository: "repository";
+            shell: "shell";
+            sql: "sql";
+            toml: "toml";
+            typescript: "typescript";
+            yaml: "yaml";
+        }>>;
+        label: z.ZodString;
+        patterns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        symbols: z.ZodOptional<z.ZodObject<{
+            kinds: z.ZodArray<z.ZodEnum<{
+                function: "function";
+                class: "class";
+                enum: "enum";
+                getter: "getter";
+                interface: "interface";
+                method: "method";
+                property: "property";
+                setter: "setter";
+            }>>;
+            modifiers: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                abstract: "abstract";
+                async: "async";
+                export: "export";
+                override: "override";
+                private: "private";
+                protected: "protected";
+                public: "public";
+                readonly: "readonly";
+                static: "static";
+            }>>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    defaultInput: z.ZodOptional<z.ZodString>;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    excludeFrom: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    format: z.ZodEnum<{
+        json: "json";
+        markdown: "markdown";
+    }>;
+    inputs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        analyses: z.ZodArray<z.ZodEnum<{
+            language: "language";
+            size: "size";
+        }>>;
+        compression: z.ZodOptional<z.ZodEnum<{
+            brotli: "brotli";
+            gzip: "gzip";
+            none: "none";
+        }>>;
+        directory: z.ZodOptional<z.ZodString>;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        include: z.ZodArray<z.ZodString>;
+        name: z.ZodString;
+    }, z.core.$strip>>>;
+    limits: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodOptional<z.ZodString>;
+        metric: z.ZodString;
+        severity: z.ZodOptional<z.ZodEnum<{
+            fail: "fail";
+            warn: "warn";
+        }>>;
+        value: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+    }, z.core.$strip>>>;
+    outputs: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        custom: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        indentation: z.ZodOptional<z.ZodNumber>;
+        path: z.ZodString;
+        type: z.ZodLiteral<"json">;
+    }, z.core.$strip>, z.ZodObject<{
+        custom: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        description: z.ZodOptional<z.ZodString>;
+        endMarker: z.ZodOptional<z.ZodString>;
+        path: z.ZodOptional<z.ZodString>;
+        startMarker: z.ZodOptional<z.ZodString>;
+        type: z.ZodLiteral<"markdown">;
+        write: z.ZodOptional<z.ZodType<WriteMarkdownOutput, unknown, z.core.$ZodTypeInternals<WriteMarkdownOutput, unknown>>>;
+    }, z.core.$strip>]>>>;
+    python: z.ZodOptional<z.ZodObject<{
+        command: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+
+/**
+ * One configured counter.
+ *
+ * A counter measures one of three things. With `patterns` alone it counts
+ * *files* whose repository-relative path matches at least one glob. With
+ * `symbols` it counts *declarations* in TypeScript and JavaScript sources
+ * matching the AST criteria, and `patterns` then narrows which files are
+ * searched rather than being what is counted. With `comment` it counts
+ * *comment blocks* that broke the selector's own budget, instead of files or
+ * declarations.
+ *
+ * Either way a match is counted once, however many patterns claim it.
+ */
+export declare interface CodometerCustomStatistic {
+    /** Badge color, as a shields.io hexadecimal triplet. */
+    color?: string | undefined;
+    comment?: CodometerCommentSelector | undefined;
+    /**
+     * Which badge group the counter is rendered into.
+     *
+     * Defaults to `conventions`, the group that exists for these counters and
+     * is omitted entirely when none are configured. Naming a language group
+     * instead puts the badge beside the built-in counters it belongs with.
+     */
+    group?: CodometerStatisticGroup | undefined;
+    label: string;
+    patterns?: string[] | undefined;
+    symbols?: CodometerSymbolMatcher | undefined;
+}
+
+/** Unit a documentation length is measured in. */
+export declare type CodometerDocumentationUnit = "characters" | "lines" | "words";
+
+/** Which report shape a run produces. */
+export declare type CodometerFormat = "json" | "markdown";
+
+/**
+ * A named set of files, declared by include and exclude globs.
+ *
+ * Globs are relative to `directory`, which itself is relative to the
+ * process's working directory — not to the configuration file's own
+ * directory — and a leading `!` on an include glob excludes instead of
+ * including. Negations are collected rather than applied in order, so moving
+ * one within the array cannot change which files the input holds.
+ *
+ * Ignore files are not consulted, except for the entry named `codebase`,
+ * whose files are every one the repository's ignore files leave behind
+ * rather than a glob match. An entry declared under that name replaces the
+ * built-in one, which is what lets a repository measure the whole tree under
+ * a compression or a different set of analyses — but only its `compression`
+ * and `analyses` are read. Its `include` and `exclude` globs are not
+ * consulted at all, because the whole-tree scan is discovered by ignore-file
+ * walking rather than by matching globs; to measure a subset of the tree,
+ * declare an input under some other name.
+ */
+export declare interface CodometerInput {
+    /** Which analyses run over the matched files. At least one. */
+    analyses: CodometerAnalysis[];
+    compression?: CodometerCompression | undefined;
+    /**
+     * Where the input's globs start, relative to the process's working
+     * directory.
+     *
+     * Defaults to the working directory itself. A repository that builds into
+     * one tree while measuring a project in another names the way out here —
+     * `"../.."` for a project two levels down from a workspace-level `dist` —
+     * so that codometer never has to know a build output convention to find the
+     * files an input claims.
+     */
+    directory?: string | undefined;
+    exclude?: string[] | undefined;
+    include: string[];
+    name: string;
+}
+
+/**
+ * Where and how the JSON statistics report is written.
+ *
+ * `custom` selects, by label, which of the top-level `custom` counters this
+ * destination renders — independently of any other output's own selection.
+ * Selecting a label the top level never declared is refused.
+ */
+export declare interface CodometerJsonOutput {
+    custom?: string[] | undefined;
+    indentation?: number | undefined;
+    path: string;
+    type: "json";
+}
+
+/**
+ * How high one measured metric may go.
+ *
+ * Limits are absolute: the metric is compared against `value` and nothing
+ * else, with no baseline and no floor. A metric that stays under its limit is
+ * reported the same way it would be without one.
+ */
+export declare interface CodometerLimit {
+    /** What to call the limit in a report, when the path itself reads poorly. */
+    label?: string | undefined;
+    /**
+     * The metric this limits, as a dotted path.
+     *
+     * Written as the input's name followed by the metric's path within it —
+     * `codebase.typescript.interfaces`, `codebase.markdown.files`, or
+     * `Compiled JavaScript.size`. With a `defaultInput` configured, a path
+     * naming no input is read as that input's. A path that resolves to more
+     * than one metric, or to none, fails the run rather than binding to
+     * whichever came first.
+     */
+    metric: string;
+    /**
+     * How loudly a breach is reported. Defaults to `fail`.
+     *
+     * Defaulted to the strict one on purpose: a limit exists to gate, and one
+     * that quietly warned because nobody said otherwise would be a gate in name
+     * only.
+     */
+    severity?: CodometerSeverity | undefined;
+    /**
+     * How high the metric may go, as a number or a string carrying a unit.
+     *
+     * Units are decimal and their trailing `b` is required: `"8 KB"` is 8000 and
+     * `"1 MB"` is 1000000, while `"8 K"` is not a size and is rejected. A value
+     * nothing can read fails the run rather than being taken as zero, which
+     * would gate every metric at nothing.
+     */
+    value: number | string;
+}
+
+/**
+ * Where and how the markdown report is written.
+ *
+ * `write` is the whole of the customizable behavior: it turns the measured
+ * statistics into markdown and decides which file that markdown lands in and
+ * how, replacing what used to be two separate callbacks. Leaving it unset
+ * keeps the built-in rendering and writing.
+ *
+ * `path` is optional because a `write` function may choose the file itself —
+ * but one of the two must be present, or there is no markdown output at all.
+ * `custom` selects, by label, which of the top-level `custom` counters this
+ * destination renders — independently of any other output's own selection.
+ * Selecting a label the top level never declared is refused.
+ */
+export declare interface CodometerMarkdownOutput {
+    custom?: string[] | undefined;
+    description?: string | undefined;
+    endMarker?: string | undefined;
+    path?: string | undefined;
+    startMarker?: string | undefined;
+    type: "markdown";
+    write?: undefined | WriteMarkdownOutput;
+}
+
+/** Destination the measured statistics are written to, one report shape each. */
+export declare type CodometerOutput = CodometerJsonOutput | CodometerMarkdownOutput;
+
+/** How Python sources are analyzed. */
+export declare interface CodometerPythonConfiguration {
+    command?: string | undefined;
+}
+
+/**
+ * Which TypeScript and JavaScript declarations a counter claims.
+ *
+ * A declaration counts when its kind is one of `kinds` and it carries every
+ * modifier in `modifiers`. An empty or absent `modifiers` asks for the kind
+ * alone.
+ */
+export declare interface CodometerSymbolMatcher {
+    kinds: CodometerSymbolKind[];
+    modifiers?: CodometerSymbolModifier[] | undefined;
+}
+
+/**
+ * File names searched for when no configuration path is given.
+ *
+ * Searched in order, so a repository carrying both a TypeScript and a JSON
+ * configuration file gets the TypeScript one — the richer format, and the one
+ * a type-checked configuration was written in.
+ */
+export declare const CONFIGURATION_FILE_NAMES: readonly ["codometer.config.ts", "codometer.config.mts", "codometer.config.cts", "codometer.config.js", "codometer.config.mjs", "codometer.config.cjs", "codometer.config.json", "codometer.config.jsonc"];
+
+/**
+ * Reads the command line `ConfigurationService` answers a run from.
+ *
+ * Not exported. The configuration layer has one public entry point, and this
+ * is the half of it that reads flags rather than files.
+ *
+ * `codometer`, `changes` and `configuration` share the rules for the flags
+ * they hold in common, and those rules are subtle enough to be worth stating
+ * once: commander hands a valueless flag through as `true` without ever
+ * calling its parser, so a command that narrows text and one that does not
+ * disagree about what `--flag "$UNSET"` meant. A flag only one command takes
+ * keeps its own parser.
+ */
+declare class ConfigurationFlagsService {
+    constructor();
+    /** States what `--check` accepts, in front of whatever went wrong. */
+    private describeAcceptedCheckNames;
+    /**
+     * Reads the `--check` value into the set of things the run fails on.
+     *
+     * A flag passed without a value arrives as `true` and is a mistake rather
+     * than a shorthand: it used to mean "check everything", and a set with
+     * nothing in it looks exactly like the flag having been left off.
+     */
+    private readCheckNames;
+    /** Keeps the names `--check` knows and complains about the rest. */
+    private validateCheckNames;
+    /**
+     * Reads an option that carries a default when it was left off.
+     *
+     * The fallback belongs to the command rather than here: two commands that
+     * share the parsing rule for `--format` need not share what they render
+     * when nobody said.
+     */
+    parseDefaultedOption(value: unknown, fallback: string): string;
+    /**
+     * Reads a directory option, falling back to the working directory.
+     *
+     * The fallback is the process's working directory as it stands when the
+     * option is read, which is what every command means by "here" — no command
+     * changes it mid-run, and one that did would want the new one.
+     */
+    parseDirectoryOption(value: unknown): string;
+    /**
+     * Reads an option that carries text, or nothing at all.
+     *
+     * A flag written `--baseline-url "$EMPTY"` can reach commander with no
+     * value at all, which it reports as `true` without calling the option's
+     * parser. So anything but a non-empty string counts as absent — passing
+     * that boolean through renders a link to the word `true`.
+     *
+     * Deliberately does not trim, unlike `callidescope`'s same-named method: a
+     * codometer option is a path, and a path whose surrounding spaces were
+     * silently dropped is a different path from the one that was asked for.
+     */
+    parseOptionalOption(value: unknown): string | undefined;
+    /**
+     * Reads `--format` into what the run prints, falling back to the resolved
+     * configuration's own `format` when the flag was left off.
+     *
+     * The fallback never infers from which other flags are present — omitting
+     * `--format` always reads the same value the configuration declares,
+     * whether or not this run also writes a file.
+     */
+    resolveFormat(value: string | undefined, configuredFormat: CodometerFormat, errors: string[]): MeasureFormat | undefined;
+    /**
+     * Reads the flags into what the run writes and what it fails on.
+     *
+     * Writing is answered per output, by whether that output's own
+     * `--output-*` flag was passed at all. `--output-json`/`--output-markdown`
+     * together with `--check reports` is refused rather than obeyed: nothing
+     * can be stale immediately after being written, so a run asking for both on
+     * the same output has misunderstood one of them and would silently compare
+     * instead of writing.
+     */
+    selectMode(options: MeasureCommandOptions): ModeSelection;
+}
+
+/**
+ * Finds and reads a codometer configuration file.
+ *
+ * Owns locating the file and turning whatever it exports into a plain,
+ * unvalidated configuration object — parsing JSON/JSONC by hand, everything
+ * else through `jiti`. What the object means is `ConfigurationService`'s to
+ * validate and resolve, kept apart so a file finding no configuration reads
+ * exactly like one that found an empty object.
+ */
+declare class ConfigurationLoaderService {
+    constructor();
+    /**
+     * Walks upward from a directory looking for a configuration file.
+     *
+     * Returns `undefined` when the search reaches the filesystem root without
+     * finding one: a repository that never wrote a configuration file is
+     * measured with the defaults rather than told to write one.
+     */
+    private findConfigurationFile;
+    /**
+     * Walks upward from the process cwd looking for the repository root.
+     *
+     * Used to resolve a configuration path given relative to that root even when
+     * the command was invoked from a nested directory, which is what a task
+     * runner does whenever it sets the cwd to the project rather than the
+     * workspace.
+     */
+    private findRepositoryRoot;
+    /** Loads a configuration module, choosing the reader by extension. */
+    private loadConfigurationModule;
+    /** Reads a JSON or JSONC configuration file. */
+    private loadJsonConfiguration;
+    /**
+     * Reads what a configuration module exported, through either interop shape.
+     *
+     * Anything that is not a plain object — including a function, since a
+     * configuration file authored as one is no longer supported — falls back to
+     * an empty object, the same way a configuration file exporting `42` does:
+     * the schema then applies to that empty object exactly as it would to a
+     * genuinely empty configuration file.
+     */
+    private readDefaultExport;
+    /**
+     * Resolves a configuration path against the cwd, then the repository root.
+     */
+    private resolveConfigurationPath;
+    /**
+     * Loads a configuration file's raw export, or `undefined` when none exists.
+     *
+     * Unvalidated on purpose: the caller runs the result through the schema
+     * before trusting any of it, so this service never has to know the shape a
+     * configuration is supposed to have.
+     */
+    load(args?: LoadConfigurationArguments): Promise<LoadedConfigurationModule | undefined>;
+}
+
+/**
+ * Provides the configuration layer's one public service.
+ *
+ * `ConfigurationLoaderService`, `ConfigurationResolverService` and
+ * `ConfigurationFlagsService` are providers rather than exports: they are how
+ * `ConfigurationService` finds a file, fills it in, and reads the command line
+ * beside it, and nothing outside this package injects any of them.
+ */
+export declare class ConfigurationModule {
+}
+
+/**
+ * Fills a validated configuration in, field by field, with what it left out.
+ *
+ * Not exported from this package. The configuration layer has exactly one
+ * public entry point, and this is the half of it that turns a file's contents
+ * into the resolved object every analyzer reads — held apart from
+ * `ConfigurationService` so that class states what the layer answers rather
+ * than how each default is arrived at.
+ */
+declare class ConfigurationResolverService {
+    constructor();
+    /**
+     * Validates a configuration object, refusing it in prose rather than in JSON.
+     *
+     * Every load goes through here — a file's contents and the empty object a
+     * directory with no configuration file stands in with alike — so the two
+     * fail identically and a reader gets the same sentence either way.
+     */
+    private parseConfigurationInternal;
+    /**
+     * Reads a limit's value, in decimal units when it was written as a string.
+     *
+     * Everything unreadable is refused: a negative number, a unit missing its
+     * `b`, a word, an empty string. The tool this replaces coerced an unreadable
+     * limit to nothing and then failed every target holding a single byte.
+     */
+    private parseLimitValue;
+    /**
+     * Reads a limit written as a string, unit and all.
+     *
+     * A unit multiplies and then rounds: `"1.5 KB"` is 1500, and the rounding is
+     * what keeps `"0.1 KB"` from arriving as the 100.00000000000001 floating
+     * point makes of it. A string carrying no unit at all is the plain number,
+     * which is what a limit on a count of interfaces or files is written as.
+     */
+    private parseLimitValueText;
+    /**
+     * Gives every configured counter a color and a group, and its `comment`
+     * selector a severity.
+     *
+     * Colors are handed out by position within a group rather than within the
+     * whole list, so adding a counter to one group does not recolor the badges
+     * of another — which would rewrite a report that had not otherwise changed.
+     * A `comment` selector's own defaulting is inlined here rather than given
+     * its own method: this list already runs one call deep inside
+     * `resolveConfiguration`, and a further call would push the whole chain
+     * past what this package's callidescope gate allows.
+     *
+     * Runs once, over the top-level `custom` declaration — never per output.
+     * An output only selects labels back out of what this resolves, so a
+     * counter is never resolved twice just because two outputs both render it.
+     */
+    private resolveCustomStatistics;
+    /**
+     * Fills in every input's compression and directory, and splits its globs
+     * into what they add and what they remove.
+     *
+     * A `!` prefix in `include` is what the tool this replaced used to subtract
+     * a file, and there it mattered where in the array it sat. Here the
+     * negations join the exclude globs in a single set, so an input holds the
+     * same files however its patterns are arranged.
+     */
+    private resolveInput;
+    /**
+     * Resolves every declared input, and the built-in `codebase` one.
+     *
+     * The built-in entry is prepended unless the configuration already declares
+     * one by that name, which replaces it outright — the only way a
+     * configuration reaches the built-in whole-tree scan under a compression or
+     * a different set of analyses.
+     */
+    private resolveInputs;
+    /** Applies defaults to one JSON output destination. */
+    private resolveJsonOutput;
+    /**
+     * Gives every limit its severity and a value read as a number.
+     *
+     * Which metric a limit lands on is decided where the measurement is, since
+     * nothing here knows what was measured — the only thing settled at this
+     * point is what the limit says.
+     */
+    private resolveLimits;
+    /** Applies defaults to one markdown output destination. */
+    private resolveMarkdownOutput;
+    /** Applies defaults to every declared output destination. */
+    private resolveOutputs;
+    /**
+     * Picks out the top-level custom statistics an output's own `custom` array
+     * selected, by label.
+     *
+     * The schema already refuses a label naming no top-level declaration, so a
+     * label failing to resolve here is dropped rather than treated as another
+     * way to fail: this method's job is the lookup, not re-validating what the
+     * schema already guarantees.
+     */
+    private selectCustomStatistics;
+    /** Validates a configuration object, refusing it in prose rather than in JSON. */
+    parseConfiguration(configuration: unknown): CodometerConfiguration;
+    /**
+     * Fills in every field a configuration file may leave out.
+     *
+     * Exposed so a host embedding codometer can hand over a configuration object
+     * it assembled itself and get the same shape a configuration file produces.
+     */
+    resolveConfiguration(configuration: CodometerConfiguration): ResolvedCodometerConfiguration;
+}
+
+/**
+ * Answers what a codometer run is configured to do.
+ *
+ * The configuration layer's one public entry point. The file says what to
+ * measure, and the flags beside it say what to do about what was measured;
+ * both are answered here, so a command injects this and nothing else from
+ * this package.
+ *
+ * It composes rather than implements. Finding and reading a file is
+ * `ConfigurationLoaderService`, filling one in is
+ * `ConfigurationResolverService`, and reading a command line is
+ * `ConfigurationFlagsService` — three package-internal collaborators, none of
+ * them reachable from outside. What the configuration *means* — which files an
+ * exclusion glob removes, where a badge block is spliced in — belongs to the
+ * analyzers that read it, so that reading a configuration stays free of any
+ * knowledge of the repository being measured.
+ */
+export declare class ConfigurationService {
+    private readonly configurationLoaderService;
+    private readonly configurationResolverService;
+    private readonly configurationFlagsService;
+    constructor(configurationLoaderService: ConfigurationLoaderService, configurationResolverService: ConfigurationResolverService, configurationFlagsService: ConfigurationFlagsService);
+    /**
+     * Loads and validates a codometer configuration file.
+     *
+     * A path that was named explicitly must exist — a typo in a task runner's
+     * arguments should fail rather than quietly measure the repository with
+     * defaults it never asked for. A path that was not named is searched for
+     * from the measured directory upward, and its absence is legal.
+     *
+     * The nearest configuration file wins outright: nothing from a further
+     * ancestor is folded into it. Merging the two would leave a limit that never
+     * applied looking exactly like one that did, and the only way to tell them
+     * apart would be to know which of several files each field came from.
+     */
+    loadConfiguration(args?: LoadConfigurationArguments): Promise<ResolvedCodometerConfiguration>;
+    /**
+     * Loads a configuration and says which file answered.
+     *
+     * The same work as `loadConfiguration`, keeping the path the upward walk
+     * settled on. A caller measuring one directory has no use for it — the
+     * configuration is the whole answer — but one listing what a repository
+     * configures has to attribute each answer to the file that gave it, and
+     * nothing downstream of the walk can still tell.
+     */
+    loadConfigurationFile(args?: LoadConfigurationArguments): Promise<LoadedConfiguration>;
+    /** Validates a configuration object, refusing it in prose rather than JSON. */
+    parseConfiguration(configuration: unknown): CodometerConfiguration;
+    /** Reads an option that carries a default when it was left off. */
+    parseDefaultedOption(value: unknown, fallback: string): string;
+    /** Reads a directory option, falling back to the working directory. */
+    parseDirectoryOption(value: unknown): string;
+    /** Reads an option that carries text, or nothing at all. */
+    parseOptionalOption(value: unknown): string | undefined;
+    /** Fills in every field a configuration file may leave out. */
+    resolveConfiguration(configuration: CodometerConfiguration): ResolvedCodometerConfiguration;
+    /** Reads `--format` into what the run prints, or the configured format. */
+    resolveFormat(value: string | undefined, configuredFormat: CodometerFormat, errors: string[]): MeasureFormat | undefined;
+    /** Reads the flags into what the run writes and what it fails on. */
+    selectMode(options: MeasureCommandOptions): ModeSelection;
+}
+
+/**
+ * The built-in `codebase` input, present unless a configuration's `inputs`
+ * names an entry of its own by that name.
+ */
+export declare const DEFAULT_CODEBASE_INPUT: CodometerInput;
+
+/**
+ * Badge colors handed to configured counters that name none, in order.
+ *
+ * Cycled rather than exhausted, so a repository can configure as many counters
+ * as it likes and each still gets a color that is stable between runs.
+ */
+export declare const DEFAULT_CUSTOM_STATISTIC_COLORS: readonly ["7c3aed", "0284c7", "16a34a", "ea580c", "db2777", "0ea5e9", "059669", "ca8a04"];
+
+/** Badge group a configured counter is rendered into when it names none. */
+export declare const DEFAULT_CUSTOM_STATISTIC_GROUP = "conventions";
+
+/**
+ * Path globs excluded from measurement when a configuration names none.
+ *
+ * Only the directories every ecosystem generates. Everything a specific
+ * repository considers noise — ingested corpora, generated documentation,
+ * scratch notes — belongs in that repository's own configuration file.
+ */
+export declare const DEFAULT_EXCLUDE_GLOBS: readonly ["**/.nx/**", "**/build/**", "**/coverage/**", "**/dist/**", "**/node_modules/**"];
+
+/**
+ * Compression applied to an input that names none.
+ *
+ * Gzip rather than the best available, because a compressed size is only worth
+ * measuring against what a server would actually send, and gzip is what every
+ * client understands. An input measuring bytes on disk asks for `none`.
+ */
+export declare const DEFAULT_INPUT_COMPRESSION = "gzip";
+
+/**
+ * Where an input's globs start when it names no directory of its own.
+ *
+ * The process's working directory. An input that means to reach outside it
+ * says so, which keeps "measure what I was pointed at" the thing that needs
+ * no writing down.
+ */
+export declare const DEFAULT_INPUT_DIRECTORY = ".";
+
+/**
+ * Name of the input every run measures unless a configuration replaces it:
+ * the codebase itself.
+ *
+ * Its files are every one the repository's ignore files leave behind rather
+ * than a glob match — `include` here is a placeholder a glob-based reader
+ * never consults for this one entry — which is what makes this input
+ * different from every other one a configuration declares.
+ */
+export declare const DEFAULT_INPUT_NAME = "codebase";
+
+/** Spaces used to indent the JSON report when a configuration names none. */
+export declare const DEFAULT_JSON_INDENTATION = 2;
+
+/**
+ * Severity a limit that names none carries.
+ *
+ * The strict one. A limit is written to gate, so one that quietly warned
+ * because nobody spelled out the severity would be a gate in name only —
+ * `warn` is the deliberate choice, not the accidental one.
+ */
+export declare const DEFAULT_LIMIT_SEVERITY = "fail";
+
+/** Closing marker of the generated badge block. */
+export declare const DEFAULT_MARKDOWN_END_MARKER = "<!-- codometer:end -->";
+
+/** Opening marker of the generated badge block. */
+export declare const DEFAULT_MARKDOWN_START_MARKER = "<!-- codometer:start -->";
+
+/**
+ * Interpreter used for Python analysis when a configuration names none.
+ *
+ * A repository whose Python lives in a managed environment overrides this with
+ * the command that enters it — `uv run python`, `poetry run python`, or the
+ * path to a virtual environment's interpreter.
+ */
+export declare const DEFAULT_PYTHON_COMMAND = "python3";
+
+/** What `--format json` prints: the report, as a document something can parse. */
+export declare const FORMAT_JSON = "json";
+
+/** What `--format markdown` prints: the rendered badge document. */
+export declare const FORMAT_MARKDOWN = "markdown";
+
+/**
+ * Everything `--format` accepts, in the order an error message lists them.
+ *
+ * Named here rather than spelled into each message, so the list a mistake is
+ * measured against and the list it is told about can never drift apart. A
+ * format added here is accepted everywhere the moment it is rendered.
+ */
+export declare const FORMAT_NAMES: readonly ["json", "markdown"];
+
+/** Arguments accepted when loading a configuration file. */
+export declare interface LoadConfigurationArguments {
+    configurationPath?: string | undefined;
+    searchDirectory?: string | undefined;
+}
+
+/**
+ * A resolved configuration and the file it was resolved from.
+ *
+ * `path` stays `undefined` when the upward walk reached the filesystem root
+ * without finding a file, which is legal and leaves every default in place.
+ */
+export declare interface LoadedConfiguration {
+    configuration: ResolvedCodometerConfiguration;
+    path: string | undefined;
+}
+
+/** What `ConfigurationLoaderService.load` found, unvalidated. */
+declare interface LoadedConfigurationModule {
+    configuration: unknown;
+    /**
+     * Absolute path of the file it came from.
+     *
+     * Carried because a caller listing what a repository configures has to say
+     * where each answer was written, and the upward walk is the only thing that
+     * knows: by the time a configuration is resolved, the file it came from is
+     * indistinguishable from one three directories higher.
+     */
+    path: string;
+}
+
+/**
+ * The anchor mechanics a `write` function would otherwise have to reimplement.
+ *
+ * Splicing a generated block between two HTML comments is the common case, so
+ * it is one call away even for a writer that picks its own file.
+ */
+export declare interface MarkdownAnchorHelpers {
+    endMarker: string;
+    startMarker: string;
+    /**
+     * Splices the anchored block into a file, appending it when the markers are
+     * absent, and creating the file when it does not exist.
+     *
+     * In check mode nothing is written and the return value reports whether the
+     * file already holds the current block. Defaults to the rendered content and
+     * the configured path; pass either to override.
+     */
+    syncAnchoredBlock: (overrides?: {
+        content?: string | undefined;
+        path?: string | undefined;
+    }) => boolean;
+    /** The content wrapped in the configured markers, ready to place anywhere. */
+    wrapInAnchors: (content?: string) => string;
+}
+
+/**
+ * Options accepted by the measure command.
+ *
+ * `--output-json` and `--output-markdown` are each independent: passing one
+ * never implicitly writes the other, and neither implies `--check reports`.
+ * There is no `--write` — passing an `--output-*` flag at all is what makes
+ * this run produce that destination.
+ */
+export declare interface MeasureCommandOptions {
+    /** The comma-separated set of things to fail on, as it was written. */
+    check?: string | true | undefined;
+    config?: string | undefined;
+    /** What to print to standard output, as it was written. */
+    format?: string | undefined;
+    /**
+     * The glob array that replaces every configured input for this run, as
+     * written. `undefined` when the flag was never passed at all.
+     */
+    inputs?: string[] | undefined;
+    /**
+     * The report's destination, as it was written.
+     *
+     * `true` for a bare flag naming no path, a string for an explicit one, and
+     * `undefined` when the flag was never passed.
+     */
+    outputJson?: string | true | undefined;
+    /**
+     * The markdown destination, as it was written.
+     *
+     * `true` for a bare flag naming no path, a string for an explicit one, and
+     * `undefined` when the flag was never passed.
+     */
+    outputMarkdown?: string | true | undefined;
+}
+
+/**
+ * What a run prints to standard output, when it prints anything.
+ *
+ * Derived from the list `--format` is validated against, so a format added
+ * there is one this accepts rather than two lists to keep in step.
+ */
+export declare type MeasureFormat = (typeof FORMAT_NAMES)[number];
+
+/**
+ * What a configuration reaching no `format` is told — written out rather than
+ * left as the schema's own "expected one of" line, because it is the first
+ * thing a newcomer to codometer sees.
+ */
+export declare const MISSING_FORMAT_MESSAGE = "A codometer configuration must name a `format` of \"json\" or \"markdown\", and nothing supplies one for it. Set it in this file, or spread a shared default object that sets it \u2014 every run has to be told which report shape it produces, and a directory with no configuration file anywhere above it fails here rather than measuring with a format nobody chose.";
+
+/**
+ * What the command line asked the run to do, and what it could not make sense
+ * of.
+ *
+ * Every complaint is collected before any of them is reported, so a command
+ * line with two mistakes in it is two mistakes to fix rather than two runs.
+ */
+export declare interface ModeSelection {
+    errors: string[];
+    mode: RunMode;
+}
+
+/**
+ * Marks the repository root during an upward search from the process cwd.
+ *
+ * A package manifest is deliberately not one of them: every package in a
+ * monorepo carries one, so the search would stop at the nearest project rather
+ * than the root a configuration path was written relative to.
+ */
+export declare const REPOSITORY_ROOT_MARKERS: readonly [".git", "pnpm-workspace.yaml"];
+
+/** A `comment` selector with its severity filled in. */
+export declare interface ResolvedCodometerCommentSelector {
+    kind: CodometerSymbolKind | undefined;
+    language: CodometerCommentLanguage | undefined;
+    maximumCharacters: number | undefined;
+    maximumLines: number | undefined;
+    maximumWords: number | undefined;
+    severity: CodometerSeverity;
+}
+
+/**
+ * Configuration with every default applied.
+ *
+ * Consumers read this shape rather than the authored one, so no analyzer has
+ * to know which fields a configuration file may omit.
+ */
+export declare interface ResolvedCodometerConfiguration {
+    /** Every counter this configuration measures, with defaults applied. */
+    custom: ResolvedCodometerCustomStatistic[];
+    /** Stays `undefined` when nothing named one, so every path must qualify. */
+    defaultInput: string | undefined;
+    exclude: string[];
+    excludeFrom: string[];
+    format: CodometerFormat;
+    inputs: ResolvedCodometerInput[];
+    limits: ResolvedCodometerLimit[];
+    outputs: ResolvedCodometerOutput[];
+    python: ResolvedCodometerPythonConfiguration;
+}
+
+/** A configured counter with its badge color and group filled in. */
+export declare interface ResolvedCodometerCustomStatistic {
+    color: string;
+    comment: ResolvedCodometerCommentSelector | undefined;
+    group: CodometerStatisticGroup;
+    label: string;
+    /** Empty for a symbol or comment counter naming none, which then searches every file. */
+    patterns: string[];
+    symbols?: CodometerSymbolMatcher | undefined;
+}
+
+/**
+ * A named set of files with its compression filled in and its negations
+ * collected.
+ *
+ * `include` holds only patterns that add files and `exclude` only patterns
+ * that remove them, whichever list they were authored in. Order carries no
+ * meaning in either: a file is in the input when some include glob claims it
+ * and no exclude glob does.
+ */
+export declare interface ResolvedCodometerInput {
+    analyses: CodometerAnalysis[];
+    compression: CodometerCompression;
+    /** `"."` when the input never named one, meaning the process's working directory. */
+    directory: string;
+    exclude: string[];
+    include: string[];
+    name: string;
+}
+
+/** JSON output destination with defaults applied. */
+export declare interface ResolvedCodometerJsonOutput {
+    custom: ResolvedCodometerCustomStatistic[];
+    indentation: number;
+    path: string;
+    type: "json";
+}
+
+/**
+ * A limit with its severity filled in and its value read as a number.
+ *
+ * The unit is gone by this point: a limit written `"8 KB"` arrives here as
+ * 8000, so nothing downstream has to know that limits can be written with
+ * units at all.
+ */
+export declare interface ResolvedCodometerLimit {
+    /** Stays `undefined` when none was written; a report falls back to the path. */
+    label: string | undefined;
+    metric: string;
+    severity: CodometerSeverity;
+    value: number;
+}
+
+/**
+ * Markdown output destination with defaults applied.
+ *
+ * `write` stays `undefined` when the configuration supplies none: the
+ * built-in rendering and writing live in the CLI that calls it, so "unset" is
+ * what selects it rather than a default named here.
+ */
+export declare interface ResolvedCodometerMarkdownOutput {
+    custom: ResolvedCodometerCustomStatistic[];
+    description: string | undefined;
+    endMarker: string;
+    path: string | undefined;
+    startMarker: string;
+    type: "markdown";
+    write: undefined | WriteMarkdownOutput;
+}
+
+/** Destination the measured statistics are written to, with defaults applied. */
+export declare type ResolvedCodometerOutput = ResolvedCodometerJsonOutput | ResolvedCodometerMarkdownOutput;
+
+/** Python analysis settings with defaults applied. */
+export declare interface ResolvedCodometerPythonConfiguration {
+    command: string;
+}
+
+/**
+ * What the run does with what it measures.
+ *
+ * Checking staleness gates on `checksReports` alone and a breach on
+ * `checksLimits` alone. Writing is answered per output: `writesJson` and
+ * `writesMarkdown` are each true only when that output's own `--output-*`
+ * flag was passed, so no flag ever quietly writes a destination the command
+ * line never named.
+ */
+export declare interface RunMode {
+    checksLimits: boolean;
+    checksReports: boolean;
+    writesJson: boolean;
+    writesMarkdown: boolean;
+}
+
+/**
+ * Decides what the markdown report says, which file it lands in, and how.
+ *
+ * Return `false` to report the destination as stale — in check mode that is
+ * what fails the command. Anything else counts as up to date.
+ */
+export declare type WriteMarkdownOutput = (args: WriteMarkdownOutputArguments) => boolean;
+
+/** What a `write` function is handed. */
+export declare interface WriteMarkdownOutputArguments {
+    anchors: MarkdownAnchorHelpers;
+    /** True when nothing may be written and the file is only being inspected. */
+    check: boolean;
+    /** The configured description, for a writer that wants to place it itself. */
+    description: string | undefined;
+    /** The configured path, resolved against the measured directory. */
+    path: string | undefined;
+    /**
+     * The built-in badge rendering of these same statistics.
+     *
+     * Call it to build the default report's content, or to add to it, rather
+     * than reimplementing it.
+     */
+    renderBadges: () => string;
+    statistics: CodeStatisticsResult;
+}
+
+export { }