@codometer/languages 0.0.1

package/dist/src/index.d.ts

@@ -0,0 +1,1697 @@
+import { CodometerCommentLanguage } from '@codometer/configuration';
+import { CodometerCommentMeasurement } from '@codometer/configuration';
+import { CodometerSeverity } from '@codometer/core';
+import { CodometerSymbolKind } from '@codometer/core';
+import { CodometerSymbolModifier } from '@codometer/core';
+import { ConsoleLogger } from '@nestjs/common';
+import { default as default_2 } from 'typescript';
+import pino from 'pino';
+import { ResolvedCodometerConfiguration } from '@codometer/configuration';
+import { SourceFile } from 'typescript';
+
+/** Arguments accepted by the Jupyter analyzer. */
+export declare interface AnalyzeJupyterArguments {
+    notebookFiles: string[];
+    pythonCommand: string;
+    workingDirectory: string;
+}
+
+/** Arguments accepted when running every language analyzer. */
+export declare interface AnalyzeLanguagesArguments {
+    /**
+     * One `comment`-selector custom statistic's budget, per declared statistic.
+     *
+     * Every counter arrives in one list, and every measurer is handed all of
+     * them: a counter naming a `kind` is measured by the TypeScript walk, and
+     * every other one by the comment readers, each selecting for itself.
+     */
+    commentCounters: CommentCounter[];
+    configuration: ResolvedCodometerConfiguration;
+    discoveredFiles: DiscoveredLanguageFiles;
+    /** Configured counters over declarations, tallied during the TypeScript walk. */
+    symbolCounters: TypescriptSymbolCounter[];
+    workingDirectory: string;
+}
+
+/** Arguments accepted by the Python analyzer. */
+export declare interface AnalyzePythonArguments {
+    command: string;
+    pythonFiles: string[];
+    workingDirectory: string;
+}
+
+/** Arguments accepted when analyzing Python source text without files. */
+export declare interface AnalyzePythonContentsArguments {
+    command: string;
+    contents: string[];
+    workingDirectory: string;
+}
+
+/** Arguments for analyzing a single source file. */
+export declare interface AnalyzeTypescriptFileArguments {
+    commentCounters: CommentCounter[];
+    counters: TypescriptSymbolCounter[];
+    filePath: string;
+    stats: TypescriptResult;
+    workingDirectory: string;
+}
+
+/** A run of comment lines a reader takes as one thought. */
+export declare interface CommentBlock {
+    tokens: CommentToken[];
+}
+
+/**
+ * How long one comment or JSDoc block may run, carried as an explicit
+ * argument rather than read off a resolved configuration object.
+ *
+ * Shaped to match the `comment` selector `@codometer/configuration` declares
+ * — a `language`, a `kind`, and this same set of optional maxima plus
+ * `severity` — so mapping one onto this is a direct field copy rather than a
+ * translation.
+ */
+export declare interface CommentBudget {
+    maximumCharacters: number | undefined;
+    maximumLines: number | undefined;
+    maximumWords: number | undefined;
+    severity: CodometerSeverity;
+}
+
+/**
+ * One `comment`-selector custom statistic's budget, and what it is over.
+ *
+ * Mirrors the selector field for field: `kind` names a documentable
+ * declaration whose JSDoc is measured, `language` names the language whose
+ * plain comment blocks are, and `undefined` on both means every language that
+ * has comments — exactly as `CodometerCommentSelector` documents. A counter
+ * naming both is measured as a `kind`: the whole list reaches both measurers,
+ * and each selects from it by reading `kind`.
+ *
+ * Kept apart per statistic rather than merged into one budget per language or
+ * kind, so two statistics naming the same one with different maxima each
+ * count only their own breaches back against their own label.
+ */
+export declare interface CommentCounter {
+    budget: CommentBudget;
+    kind: CodometerSymbolKind | undefined;
+    label: string;
+    language: CodometerCommentLanguage | undefined;
+}
+
+/** One comment block, measured against one declared maximum. */
+export declare type CommentMeasurement = CodometerCommentMeasurement;
+
+/**
+ * NestJS module that provides comment-length measurement.
+ *
+ * One measuring service and one reader per comment syntax, so a language that
+ * marks its comments differently is a new reader here rather than a second
+ * definition of what a word is.
+ */
+export declare class CommentsModule {
+}
+
+/**
+ * Measures comments against the maxima a configuration declares.
+ *
+ * Everything here is language-agnostic: it takes comments somebody else
+ * already found and says how long they are. What counts as a comment differs
+ * per language and lives with the reader that knows — `HashCommentsService`
+ * for the `#` languages, `YamlCommentsService` for YAML's tokenizer, and the
+ * TypeScript walk for a JSDoc block.
+ *
+ * That split is what keeps one definition of a word, a line, and a character
+ * across every language, rather than four analyzers each counting slightly
+ * differently.
+ */
+export declare class CommentsService {
+    constructor();
+    /**
+     * Counts the words in a comment's prose, markers already stripped.
+     *
+     * Splitting a trimmed string on whitespace runs never yields an empty
+     * token, so the empty case is the only one worth guarding — and guarding it
+     * rather than filtering keeps a callback frame off the deepest stack this
+     * package owns.
+     */
+    private countWords;
+    /**
+     * Every declared maximum, paired with what this comment measured.
+     *
+     * Written as three guarded pushes rather than a table walked by `flatMap`,
+     * because the callback would be one more frame on the deepest stack this
+     * package owns — the JSDoc walk reaches here through eleven of them, and
+     * `callidescope.config.ts` gates that at what it measures.
+     */
+    private declaredLimits;
+    /** The prose of a run of comment lines, markers already stripped. */
+    private readProse;
+    /** A run of comment lines exactly as the file carries them. */
+    private readSource;
+    /** Shortens a block's prose to something a breach line can carry. */
+    private toExcerpt;
+    /**
+     * Groups a file's comment lines into the blocks a reader perceives.
+     *
+     * A trailing comment never joins anything — it sits after a value and is
+     * read with that value, not with the prose above it — and neither does a
+     * comment separated from the previous one by a blank line, which is how a
+     * writer marks the end of a thought.
+     */
+    groupIntoBlocks(tokens: readonly CommentToken[]): CommentBlock[];
+    /**
+     * Measures every block a file's comment tokens form, breached or not.
+     *
+     * Every block is reported rather than only the breaches, so a length is
+     * visible in the JSON report before it ever becomes a problem — the same
+     * bargain the TypeScript declaration-comment measurement makes. A block is
+     * reported once per declared maximum, because the maxima are not
+     * alternatives: one can hold while another breaks.
+     */
+    measure(args: MeasureCommentsArguments): CommentMeasurement[];
+    /**
+     * Measures one comment's text against every maximum declared for it.
+     *
+     * The seam a JSDoc block enters through: it is one comment already, found by
+     * the TypeScript walk rather than grouped from lines, so it needs the
+     * counting and none of the grouping.
+     */
+    measureText(args: MeasureCommentTextArguments): CommentMeasurement[];
+}
+
+/** One comment line, with where it sits and what it says. */
+export declare interface CommentToken {
+    /** 1-indexed line the comment is written on. */
+    line: number;
+    /** Whether nothing but whitespace precedes it on its line. */
+    ownLine: boolean;
+    /** The comment's prose, with its marker already stripped. */
+    prose: string;
+    /** The comment exactly as the file carries it, marker and all. */
+    source: string;
+}
+
+/**
+ * Reads CSS's `/* ... *\/` comments from postcss's own parse.
+ *
+ * CSS has only the one comment syntax, and no line form at all, so a real
+ * parser costs nothing extra here: postcss already reads the repository's
+ * stylesheets for `CssService`, and its comment nodes carry a line and column
+ * a scanner would otherwise have to recompute by hand.
+ */
+export declare class CssCommentsService {
+    constructor();
+    /**
+     * A comment's text with the whitespace postcss split off restored.
+     *
+     * `raws.left`/`raws.right` are typed optional, but postcss's own parse
+     * always fills both in — with an empty string for an empty comment, never
+     * `undefined` — so the fallback is unreachable rather than untested.
+     */
+    private toBody;
+    /**
+     * Whether only whitespace precedes a comment's opening marker on its line.
+     *
+     * `comment.source` is typed optional because postcss also allows building a
+     * node by hand with none, which never happens here: every comment measured
+     * came from parsing real content, which always carries its position.
+     */
+    private toOwnLine;
+    /**
+     * Reads every comment postcss's parse finds, in document order.
+     *
+     * Empty for a stylesheet postcss cannot parse at all, the same way
+     * `CssService` skips a file it cannot parse rather than throwing out of the
+     * whole measurement run.
+     */
+    read(content: string): CommentToken[];
+}
+
+/** Input to the Css analysis step. */
+export declare interface CssInput {
+    cssFiles: string[];
+    workingDirectory: string;
+}
+
+/**
+ * NestJS module that provides Css source analysis.
+ */
+export declare class CssModule {
+}
+
+/** Aggregated metrics collected from parsing Css sources. */
+export declare interface CssResult {
+    atRules: number;
+    comments: number;
+    customProperties: number;
+    declarations: number;
+    files: number;
+    lines: number;
+    mediaQueries: number;
+    rules: number;
+    selectors: number;
+}
+
+/**
+ * Walks parsed stylesheets to collect structural metrics.
+ *
+ * Parsed with postcss, which the repository's stylelint already reads CSS
+ * through, so a selector split across lines counts once and a declaration
+ * inside a comment counts not at all.
+ */
+export declare class CssService {
+    private readonly logger;
+    constructor(logger: LoggerService);
+    /** Records one node against the running totals. */
+    private countNode;
+    /** Analyze the given stylesheets, resolved against the directory. */
+    analyze({ cssFiles, workingDirectory }: CssInput): CssResult;
+}
+
+/**
+ * Finds a documentable declaration's leading JSDoc comment and hands it to be
+ * measured.
+ *
+ * Only the finding is TypeScript's: which declarations can carry a limit,
+ * where the `/**` range sits, and what the declaration is called. How long the
+ * comment is comes from `CommentsService`, the same counting every other
+ * language's comments go through, so a word means one thing across the tool
+ * rather than one thing per analyzer.
+ */
+declare class DeclarationCommentsService {
+    private readonly comments;
+    constructor(comments: CommentsService);
+    /** Reads a declaration's own name, or `"(anonymous)"` when it has none. */
+    private getDeclarationName;
+    /** Finds the node's leading JSDoc comment range, the last one if several. */
+    private getJsDocRange;
+    /**
+     * Everything a measurement needs about one node, or `undefined` when there
+     * is nothing to measure.
+     *
+     * Split out of `measure` so that method stays inside this repository's
+     * statement budget without a helper on the measuring path itself — this one
+     * is called before the comment counting starts, so it adds no frame to the
+     * deepest stack the JSDoc walk reaches.
+     */
+    private prepare;
+    /**
+     * The comment's prose, with its delimiters and each line's `*` stripped.
+     *
+     * Stripped for the word count only. A character count stays the raw slice —
+     * it is the one unit a reader can check against their editor's own column
+     * count, and a marker is very much a character even though it is not a word.
+     */
+    private readProse;
+    /**
+     * Measures one declaration's leading JSDoc comment against every
+     * comment counter that names its kind, if it has one.
+     *
+     * Empty when the node's kind matches no configured counter, or when it
+     * carries no `/**` comment at all — neither is a measurement, and reporting
+     * one would name a declaration nothing documented. A declaration is
+     * measured once per counter that names its kind and once per maximum that
+     * counter declares, because neither is an alternative: one can hold while
+     * another breaks.
+     */
+    measure(node: default_2.Node, context: TypescriptWalkContext): LabeledCommentMeasurement[];
+}
+
+/** The categorized file lists every language analyzer reads from. */
+export declare interface DiscoveredLanguageFiles {
+    cssFiles: string[];
+    hclFiles: string[];
+    jsonFiles: string[];
+    markdownFiles: string[];
+    notebookFiles: string[];
+    pyFiles: string[];
+    shellFiles: string[];
+    sourceFiles: string[];
+    sqlFiles: string[];
+    tomlFiles: string[];
+    yamlFiles: string[];
+}
+
+/**
+ * Reads the comments of a language whose comments start with `#`.
+ *
+ * Shell, TOML, and Python all mark a comment the same way and all three
+ * already scan their sources line by line, which is why one reader serves
+ * them.
+ *
+ * It is a line scanner, not a tokenizer, and that is a real limitation rather
+ * than an oversight: a `#` inside a string literal is read as a comment here,
+ * exactly as those three analyzers' own `comments` counters already read it.
+ * YAML is measured by `YamlCommentsService` instead, whose tokenizer knows the
+ * difference, because YAML's `#` sits next to quoted scalars constantly.
+ */
+export declare class HashCommentsService {
+    constructor();
+    /**
+     * Whether this is the interpreter line rather than a comment.
+     *
+     * `#!` on the first line is an instruction to the kernel, not prose. Left in,
+     * it would be grouped with whatever comment follows it — every shell script
+     * opening with a shebang and a comment would measure one block carrying
+     * `!/bin/sh` as its first word.
+     */
+    private isShebang;
+    /** Reads every `#` comment in a file, with its line and its placement. */
+    read(content: string): CommentToken[];
+}
+
+/**
+ * Reads HCL's `#`, `//`, and `/* ... *\/` comments — the only language this
+ * tool measures that marks a comment three different ways.
+ *
+ * A line scanner for the two line forms, none of it string-aware:
+ * `HclService`'s own line-based counting already accepts the same
+ * limitation, checking only whether a trimmed line's first characters open a
+ * comment rather than parsing the language properly. The block form is found
+ * with `indexOf` rather than a regular expression: a pattern matching an
+ * unclosed `/*` through to end of input has to fail once per occurrence,
+ * which is quadratic on adversarial input, while two `indexOf` calls per
+ * comment never scan the same text twice.
+ */
+export declare class HclCommentsService {
+    constructor();
+    /** Every `/* *\/` comment's span, left to right and never overlapping. */
+    private findBlockComments;
+    /** Whether only whitespace precedes an offset on its own line. */
+    private isOwnLine;
+    /** The 1-indexed line an offset sits on. */
+    private lineOf;
+    /** Every block comment's span, as a positioned token. */
+    private readBlocks;
+    /** Every match of a comment pattern, as a positioned token. */
+    private readMatches;
+    /**
+     * Reads every `#`, `//`, and `/* *\/` comment, in the order they appear.
+     *
+     * Block spans are found first so a line marker found inside one — a `#`
+     * written as prose in a `/* *\/` block, say — can be dropped rather than
+     * measured a second time as a comment of its own.
+     */
+    read(content: string): CommentToken[];
+}
+
+/** Input to the Hcl analysis step. */
+export declare interface HclInput {
+    hclFiles: string[];
+    workingDirectory: string;
+}
+
+/**
+ * NestJS module that provides Hcl source analysis.
+ */
+export declare class HclModule {
+}
+
+/** Aggregated metrics collected from parsing Hcl sources. */
+export declare interface HclResult {
+    attributes: number;
+    blocks: number;
+    comments: number;
+    files: number;
+    interpolations: number;
+    lines: number;
+    outputs: number;
+    resources: number;
+    variables: number;
+}
+
+/**
+ * Counts the blocks and attributes an HCL configuration declares.
+ *
+ * Blocks are recognized by the header that opens them, which also names what
+ * kind they are: a `resource` block and an `output` block are both blocks, and
+ * knowing how many of each is what makes the count worth reading.
+ */
+export declare class HclService {
+    private readonly logger;
+    constructor(logger: LoggerService);
+    /** Records the block a header opens, by the kind it names. */
+    private countBlock;
+    /** Records what one line of HCL declares. */
+    private countLine;
+    /** Analyze the given HCL files, resolved against the directory. */
+    analyze({ hclFiles, workingDirectory }: HclInput): HclResult;
+}
+
+/** State used while stripping JSONC comments from a document. */
+export declare interface JsoncState {
+    isInBlockComment: boolean;
+    isInLineComment: boolean;
+    isInString: boolean;
+    sanitizedContent: string;
+    shouldAdvanceIndex: boolean;
+}
+
+/** Input to the JSON analysis step. */
+export declare interface JsonInput {
+    jsonFiles: string[];
+    workingDirectory: string;
+}
+
+/**
+ * TODO: Document the measureJson module.
+ */
+export declare class JsonModule {
+}
+
+/** Aggregated metrics collected from parsing JSON documents. */
+export declare interface JsonResult {
+    arrays: number;
+    booleans: number;
+    files: number;
+    items: number;
+    lines: number;
+    maxDepth: number;
+    nulls: number;
+    numbers: number;
+    objects: number;
+    properties: number;
+    strings: number;
+    totalNodes: number;
+}
+
+/** Walks parsed JSON values to collect structural metrics. */
+export declare class JsonService {
+    private readonly logger;
+    constructor(logger: LoggerService);
+    /** Consume a character that is not inside a comment or string. */
+    private consumeCharacterOutsideComments;
+    /** Consume one JSONC character and update the parser state. */
+    private consumeJsoncCharacter;
+    /** Count array nodes and their child values. */
+    private countArrayNode;
+    /** Recursively count JSON containers, primitives, and nesting depth. */
+    private countNode;
+    /** Count scalar values and update primitive stats. */
+    private countPrimitiveNode;
+    /** Increment stats for a scalar JSON value. */
+    private countPrimitiveValue;
+    /** Count object nodes and their child values. */
+    private countRecordNode;
+    /** Handle block comments while parsing JSONC content. */
+    private handleBlockCommentState;
+    /** Update the JSONC parser when it is inside a line comment. */
+    private handleLineCommentState;
+    /** Update the JSONC parser when it is inside a string literal. */
+    private handleStringState;
+    /** Return true when a value is a JSON array. */
+    private isArrayNode;
+    /** Return true when a value is a JSON object. */
+    private isRecordNode;
+    /** Parse a file into one or more JSON documents depending on the extension. */
+    private parseDocuments;
+    /** Remove comments from JSONC content while preserving string literals. */
+    private stripJsoncComments;
+    /** Analyze JSON files and return structural metrics for their contents. */
+    analyze(input: JsonInput): JsonResult;
+}
+
+/**
+ * NestJS module that measures notebooks through the JSON, Python, and
+ * markdown analyzers it composes.
+ */
+export declare class JupyterModule {
+}
+
+/** Aggregated metrics collected from Jupyter notebooks. */
+export declare interface JupyterResult {
+    cells: number;
+    classes: number;
+    codeBlocks: number;
+    codeCells: number;
+    codeLines: number;
+    decorators: number;
+    executedCells: number;
+    files: number;
+    functions: number;
+    headings: number;
+    images: number;
+    imports: number;
+    links: number;
+    markdownCells: number;
+    markdownLines: number;
+    maxDepth: number;
+    outputs: number;
+    properties: number;
+    rawCells: number;
+    totalNodes: number;
+}
+
+/**
+ * Measures Jupyter notebooks by handing their parts to the other analyzers.
+ *
+ * A notebook is three languages in one file, and this service owns none of
+ * them: the document is JSON, its code cells are Python, and its markdown
+ * cells are prose, so each is counted by the analyzer that already knows how.
+ * What is left — cells, outputs, execution — belongs to the notebook itself
+ * and is counted here.
+ */
+export declare class JupyterService {
+    private readonly jsonService;
+    private readonly markdownService;
+    private readonly pythonService;
+    private readonly logger;
+    constructor(jsonService: JsonService, markdownService: MarkdownService, pythonService: PythonService, logger: LoggerService);
+    /** Record one cell against the running notebook totals. */
+    private collectCell;
+    /** Read every notebook, collecting cell counts and cell sources. */
+    private collectParts;
+    /** Sum every heading level the markdown analyzer reports. */
+    private countHeadings;
+    /** Read and validate one notebook, returning its cells. */
+    private readNotebook;
+    /** Join a cell's source, which nbformat writes as a string or line array. */
+    private readSource;
+    /** Analyze the given notebooks, resolved against the directory. */
+    analyze(args: AnalyzeJupyterArguments): JupyterResult;
+}
+
+/** One measurement, tagged with the custom statistic label that produced it. */
+declare interface LabeledCommentMeasurement {
+    label: string;
+    measurement: CommentMeasurement;
+}
+
+/**
+ * The file lists comment measurement reads, one per language that has a
+ * budget.
+ *
+ * Named here rather than taken from `DiscoveredLanguageFiles`, which would
+ * point this module back at the one that depends on it. `languages` depends on
+ * `comments` and never the reverse; a cycle between the two crashes the Nest
+ * container outright rather than failing anything readable. The discovery
+ * result satisfies this structurally, so callers pass it unchanged.
+ */
+declare interface LanguageCommentFiles {
+    cssFiles: string[];
+    hclFiles: string[];
+    shellFiles: string[];
+    /** TypeScript and JavaScript sources, in every dialect the workspace holds. */
+    sourceFiles: string[];
+    sqlFiles: string[];
+    tomlFiles: string[];
+    yamlFiles: string[];
+}
+
+/**
+ * Measures the comment blocks every `comment`-selector custom statistic asks
+ * for, one counter at a time.
+ *
+ * Files are read here rather than inside each language analyzer, which is
+ * what lets Python be measured at all: its analysis runs in a subprocess and
+ * returns zeros when the interpreter is unreachable, so a gate that lived
+ * there would stop gating on any machine without `uv` and say nothing about
+ * it. Reading the sources directly makes the budget independent of that.
+ *
+ * A counter is measured on its own rather than merged with every other one
+ * that shares a language: two custom statistics can watch the same language
+ * with different maxima, and keeping them apart is what lets each one's own
+ * breaches be counted back against its own label.
+ */
+export declare class LanguageCommentsService {
+    private readonly comments;
+    private readonly cssComments;
+    private readonly hashComments;
+    private readonly hclComments;
+    private readonly logger;
+    private readonly sqlComments;
+    private readonly typescriptComments;
+    private readonly yamlComments;
+    constructor(comments: CommentsService, cssComments: CssCommentsService, hashComments: HashCommentsService, hclComments: HclCommentsService, logger: LoggerService, sqlComments: SqlCommentsService, typescriptComments: TypescriptCommentsService, yamlComments: YamlCommentsService);
+    /** Reads and measures one language's files against one counter's budget. */
+    private measureLanguage;
+    /** Measures one counter's budget against one language's discovered files. */
+    private measureOneLanguage;
+    /**
+     * Measures Python's comments, which its own analyzer already found.
+     *
+     * The tokens arrive grouped by nothing, so they are split per file before
+     * measuring — a block never spans two files, and `groupIntoBlocks` compares
+     * line numbers that would otherwise run together.
+     */
+    private measurePython;
+    /** Reads one file, or reports which one it gave up on. */
+    private readFile;
+    /**
+     * Measures every counter that names no declaration kind, keyed by the custom
+     * statistic's label.
+     *
+     * A counter naming no language measures every one of them; one naming a
+     * language measures only that one. Either way its results land under its
+     * own label, never merged with another counter's.
+     */
+    measure(args: MeasureLanguageCommentsArguments): Record<string, CommentMeasurement[]>;
+}
+
+/** What every language analyzer reported, keyed by language. */
+export declare interface LanguageResults {
+    /** One measurement list per configured comment counter, keyed by its label. */
+    commentCounts: Record<string, CommentMeasurement[]>;
+    css: CssResult;
+    hcl: HclResult;
+    json: JsonResult;
+    jupyter: JupyterResult;
+    markdown: MarkdownResult;
+    python: PythonResult;
+    shell: ShellResult;
+    sql: SqlResult;
+    toml: TomlResult;
+    typescript: TypescriptResult;
+    yaml: YamlResult;
+}
+
+/**
+ * NestJS module that gathers every language analyzer behind one service.
+ */
+export declare class LanguagesModule {
+}
+
+/**
+ * Runs every language analyzer over the discovered files.
+ *
+ * One collaborator for the measurement pipeline instead of eleven: which
+ * languages exist is this service's business, and adding a twelfth changes
+ * nothing above it.
+ */
+export declare class LanguagesService {
+    private readonly cssService;
+    private readonly languageComments;
+    private readonly hclService;
+    private readonly jsonService;
+    private readonly jupyterService;
+    private readonly markdownService;
+    private readonly pythonService;
+    private readonly shellService;
+    private readonly sqlService;
+    private readonly tomlService;
+    private readonly typescriptService;
+    private readonly yamlService;
+    constructor(cssService: CssService, languageComments: LanguageCommentsService, hclService: HclService, jsonService: JsonService, jupyterService: JupyterService, markdownService: MarkdownService, pythonService: PythonService, shellService: ShellService, sqlService: SqlService, tomlService: TomlService, typescriptService: TypescriptService, yamlService: YamlService);
+    /** Analyze every language present in the discovered files. */
+    analyze(args: AnalyzeLanguagesArguments): LanguageResults;
+}
+
+/** A comment token together with the file it was found in. */
+declare interface LocatedCommentToken extends CommentToken {
+    file: string;
+}
+
+/**
+ * Structured values that belong beside a log line rather than inside it.
+ *
+ * Counts, percentages, and durations are the values that change on every
+ * occurrence, so they are carried as fields: the message stays constant and
+ * groupable in telemetry, and the numbers stay queryable instead of having to
+ * be parsed back out of prose.
+ *
+ * The named members are the recurring ones; the index signature keeps the
+ * argument open for whatever a given call site needs to attach.
+ */
+declare interface LogData {
+    [key: string]: unknown;
+    /** How many things the operation handled. */
+    count?: number;
+    /** Wall-clock milliseconds the operation took. */
+    durationMs?: number;
+    /** Completion between 0 and 100. */
+    percent?: number;
+    /** How many things the operation set out to handle. */
+    total?: number;
+}
+
+/**
+ * Transient-scoped logger so each injecting class gets its own instance.
+ * Each consumer calls `setContext(ClassName.name)` to tag every log line
+ * with the originating class. Backed by pino for structured JSON output in
+ * production and human-readable pretty-print in development.
+ *
+ * Messages follow one grammar: an emoji naming the subject, a verb in present
+ * progressive or past tense, then the object. Values that vary per call —
+ * counts, percentages, durations — go in the `data` argument rather than the
+ * message, so the message stays constant enough for telemetry to group on.
+ *
+ * ```ts
+ * this.logger.info("📥 Downloading CSEL sources", undefined, { total: 428 });
+ * this.logger.info("📥 Downloaded CSEL sources", undefined, { count: 412 });
+ * ```
+ */
+declare @Injectable({ scope: Scope.TRANSIENT })
+class LoggerService extends ConsoleLogger {
+    // 🏗 Dependency Injection
+
+    constructor() {
+        super();
+    }
+
+    // 🔐 Private Fields
+
+    private static readonly isProduction =
+    process.env["NODE_ENV"] === "production";
+
+    /**
+     * Built on first use, not when this file is evaluated.
+     *
+     * A destination fixed at import time could only ever be chosen by this
+     * package, since every consumer's own code runs after its imports.
+     */
+    private static rootLogger: pino.Logger | undefined;
+
+    /** Whether lines go to standard error instead of standard output. */
+    private static writesToStandardError = false;
+
+    private child: pino.Logger = LoggerService.root;
+
+    // 🔑 Public Fields
+
+    // 🔏 Private Methods
+
+    /** Build the pino instance for production or local development output. */
+    private static createRootLogger(): pino.Logger {
+        const level = process.env["LOG_LEVEL"] ?? "info";
+
+        if (LoggerService.isProduction) {
+            return LoggerService.writesToStandardError
+            ? pino({ level }, pino.destination(STANDARD_ERROR_DESCRIPTOR))
+            : pino({ level });
+        }
+
+        return pino({
+            level,
+            transport: {
+                options: {
+                    colorize: true,
+                    destination: LoggerService.writesToStandardError
+                    ? STANDARD_ERROR_DESCRIPTOR
+                    : STANDARD_OUTPUT_DESCRIPTOR,
+                    // The emoji is a field, not part of the message, so the console can
+                    // show it while telemetry stores unadorned prose. `ignore` then keeps
+                    // it from being printed a second time in the trailing object.
+                    ignore: "pid,hostname,emoji",
+                    messageFormat: "{emoji} {msg}",
+                    singleLine: true,
+                },
+                target: "pino-pretty",
+            },
+        });
+    }
+
+    /**
+     * Sends every subsequent line to standard error instead of standard output.
+     *
+     * For a command-line application whose standard output *is* its result. A log
+     * line sharing that stream is not a diagnostic beside the data, it is a
+     * corruption of it. Call it before anything logs — the first statement of the
+     * application's bootstrap.
+     *
+     * A call after the first line warns and changes nothing: the destination is
+     * fixed when the pino instance is built, and tearing down a transport
+     * somebody is writing through would be worse than refusing. The warning is
+     * the point — silently leaving the lines on standard output is how a caller
+     * would ship a corrupted pipe without ever being told.
+     */
+    static logToStandardError(): void {
+        if (LoggerService.rootLogger !== undefined) {
+            process.emitWarning(
+            "LoggerService.logToStandardError() was called after the first log line, so log lines still go to standard output and anything piping that stream will read them as data. Call it as the first statement of the application's bootstrap.",
+            );
+            return;
+        }
+
+        LoggerService.writesToStandardError = true;
+    }
+
+    /**
+     * Fails a malformed message in development, and never in production.
+     *
+     * A logger that throws in production turns an observability call into an
+     * outage, so the check runs only where a developer is present to fix it.
+     */
+    private assertConventionalMessage(args: {
+        context: string | undefined;
+        parsed: ParsedLogMessage;
+    }): void {
+        if (
+        LoggerService.isProduction ||
+        this.shouldSkipConventionalMessageValidation(args.context)
+        ) {
+            return;
+        }
+
+        const violation = this.getConventionalMessageViolation(args.parsed);
+
+        if (violation !== undefined) {
+            throw new Error(violation);
+        }
+    }
+
+    /** Assembles the object pino merges into the line. */
+    private buildBindings(args: {
+        context: string | undefined;
+        data: LogData | undefined;
+        parsed: ParsedLogMessage;
+    }): Record<string, unknown> {
+        this.assertConventionalMessage({
+            context: args.context,
+            parsed: args.parsed,
+        });
+
+        return {
+            ...args.data,
+            context: args.context,
+            // Telemetry gets prose; only the console-bound transport reads this.
+            ...(LoggerService.isProduction ? {} : { emoji: args.parsed.emoji }),
+        };
+    }
+
+    /** Returns a human-readable explanation when the message format is invalid. */
+    private getConventionalMessageViolation(
+    parsed: ParsedLogMessage,
+    ): string | undefined {
+        const emoji = parsed.emoji;
+        const text = parsed.text;
+
+        if (emoji === undefined) {
+            return `Log message must start with an emoji naming its subject, then a verb: "${text}"`;
+        }
+
+        const firstWord = FIRST_WORD_PATTERN.exec(text)?.[1];
+
+        if (firstWord === undefined || !this.isConventionalVerb(firstWord)) {
+            return `Log message must begin with a verb in present progressive or past tense, got "${firstWord ?? ""}": "${emoji} ${text}"`;
+        }
+
+        return undefined;
+    }
+
+    /**
+     * Whether a word is a verb in one of the two tenses the convention allows.
+     *
+     * Present progressive means the operation is under way; past means it
+     * finished. Regular morphology covers both, so a new verb needs no
+     * registration anywhere — only irregular pasts are enumerated.
+     */
+    private isConventionalVerb(word: string): boolean {
+        const lowercased = word.toLowerCase();
+
+        return (
+        lowercased.endsWith("ing") ||
+        lowercased.endsWith("ed") ||
+        IRREGULAR_PAST_VERBS.has(lowercased)
+        );
+    }
+
+    /** Splits a leading emoji off a message, leaving prose behind. */
+    private parseMessage(message: unknown): ParsedLogMessage {
+        const text = String(message);
+        const match = LEADING_EMOJI_PATTERN.exec(text);
+        const emoji = match?.[1];
+
+        return emoji === undefined
+        ? { emoji: undefined, text }
+        : { emoji, text: text.slice(match?.[0].length) };
+    }
+
+    /** Whether a context is intentionally exempt from the validation rule. */
+    private shouldSkipConventionalMessageValidation(
+    context: string | undefined,
+    ): boolean {
+        return context !== undefined && UNVALIDATED_LOG_CONTEXTS.has(context);
+    }
+
+    // 🌎 Public Methods
+
+    /** The pino instance every logger's child is taken from. */
+    private static get root(): pino.Logger {
+        LoggerService.rootLogger ??= LoggerService.createRootLogger();
+
+        return LoggerService.rootLogger;
+    }
+
+    /** Normalizes unknown errors into a stable message and timestamped log line. */
+    buildErrorLogEntry(
+    context: string,
+    error: unknown,
+    ): { errorMessage: string; logLine: string } {
+        const errorMessage =
+        error instanceof Error ? error.stack || error.message : String(error);
+
+        return {
+            errorMessage,
+            logLine: `[${new Date().toISOString()}] ${context}: ${errorMessage}\n`,
+        };
+    }
+
+    /** Builds a timestamped output log file path and ensures the output directory exists. */
+    createTimestampedOutputLogFilePath(filePrefix: string): string {
+        const outputDirectory = path.join(process.cwd(), "output");
+        if (!existsSync(outputDirectory)) {
+            mkdirSync(outputDirectory, { recursive: true });
+        }
+
+        return path.join(
+        outputDirectory,
+        `${filePrefix}-${new Date().toISOString().replaceAll(/[:.]/g, "-")}.log`,
+        );
+    }
+
+    /** Logs a debug message at the `debug` level. */
+    override debug(message: unknown, context?: string, data?: LogData): void {
+        const parsed = this.parseMessage(message);
+        this.child.debug(
+        this.buildBindings({ context: context ?? this.context, data, parsed }),
+        parsed.text,
+        );
+    }
+
+    /**
+     * Logs an error message at the `error` level, optionally including a stack trace.
+     *
+     * `ConsoleLogger.error` spends a third slot on a context string that the
+     * other levels do not have, so this one accepts either: a string keeps
+     * NestJS's meaning, an object is structured data like everywhere else.
+     */
+    override error(
+    message: unknown,
+    stackOrContext?: string,
+    contextOrData?: LogData | string,
+    ): void {
+        const parsed = this.parseMessage(message);
+        const data = typeof contextOrData === "object" ? contextOrData : undefined;
+        const context =
+        typeof contextOrData === "string" ? contextOrData : this.context;
+
+        this.child.error(
+            {
+            ...this.buildBindings({ context, data, parsed }),
+            stack: stackOrContext,
+        },
+        parsed.text,
+        );
+    }
+
+    /** Logs an informational message at the `info` level. */
+    info(message: unknown, context?: string, data?: LogData): void {
+        const parsed = this.parseMessage(message);
+        this.child.info(
+        this.buildBindings({ context: context ?? this.context, data, parsed }),
+        parsed.text,
+        );
+    }
+
+    /**
+     * Logs an informational message at the `info` level.
+     *
+     * NestJS and `nest-commander` call this method directly as part of the
+     * framework's own `LoggerService` contract, so it must keep working
+     * exactly as before. Application code should call `info` instead — the
+     * same behavior under a name that says what level it logs at.
+     */
+    override log(message: unknown, context?: string, data?: LogData): void {
+        this.info(message, context, data);
+    }
+
+    /** Sets the context label included in every subsequent log line. */
+    override setContext(context: string): void {
+        super.setContext(context);
+        this.child = LoggerService.root.child({ context });
+    }
+
+    /** Logs a verbose message at the `trace` level. */
+    override verbose(message: unknown, context?: string, data?: LogData): void {
+        const parsed = this.parseMessage(message);
+        this.child.trace(
+        this.buildBindings({ context: context ?? this.context, data, parsed }),
+        parsed.text,
+        );
+    }
+
+    /** Logs a warning message at the `warn` level. */
+    override warn(message: unknown, context?: string, data?: LogData): void {
+        const parsed = this.parseMessage(message);
+        this.child.warn(
+        this.buildBindings({ context: context ?? this.context, data, parsed }),
+        parsed.text,
+        );
+    }
+}
+
+/** Input to the markdown analysis step. */
+export declare interface MarkdownInput {
+    markdownFiles: string[];
+    workingDirectory: string;
+}
+
+/**
+ * Provides structural measurement of markdown documents.
+ */
+export declare class MarkdownModule {
+}
+
+/** Aggregated metrics collected from parsing markdown documents. */
+export declare interface MarkdownResult {
+    blockQuotes: number;
+    codeBlocks: number;
+    files: number;
+    headingLevel1: number;
+    headingLevel2: number;
+    headingLevel3: number;
+    headingLevel4: number;
+    headingLevel5: number;
+    headingLevel6: number;
+    images: number;
+    inlineCode: number;
+    lines: number;
+    links: number;
+    listItems: number;
+    lists: number;
+    paragraphs: number;
+    tableRows: number;
+    tables: number;
+    taskListItems: number;
+    thematicBreaks: number;
+}
+
+/**
+ * Walks parsed markdown documents to collect structural metrics.
+ *
+ * Comparison is structural rather than textual, so a heading only counts when
+ * the parser agrees it is one. Frontmatter is parsed as its own node because
+ * a `---` delimited block is otherwise read as a setext heading, which would
+ * report a level-two heading at the top of every file that has frontmatter.
+ * GFM is enabled so tables and task list items exist as nodes at all.
+ */
+export declare class MarkdownService {
+    private readonly logger;
+    constructor(logger: LoggerService);
+    private readonly processor;
+    /** Records a heading against the field for its depth. */
+    private countHeading;
+    /** Records a list item, separating GFM checkboxes from plain bullets. */
+    private countListItem;
+    /** Records a single node against the running totals. */
+    private countNode;
+    /** Walks every node in a parsed document. */
+    private walk;
+    /** Analyze the given markdown files, resolved against the directory. */
+    analyze({ markdownFiles, workingDirectory }: MarkdownInput): MarkdownResult;
+    /**
+     * Analyze markdown source text that never came from a file of its own.
+     *
+     * The seam the jupyter analyzer reads through: a notebook's markdown cells
+     * are documents without paths, and re-parsing them anywhere else would be a
+     * second implementation of this counting.
+     */
+    analyzeContents(contents: string[]): MarkdownResult;
+}
+
+/** Arguments accepted when measuring one file's comment blocks. */
+declare interface MeasureCommentsArguments {
+    comments: CommentBudget;
+    filePath: string;
+    tokens: CommentToken[];
+}
+
+/** Arguments accepted when measuring one comment's text directly. */
+declare interface MeasureCommentTextArguments {
+    comments: CommentBudget;
+    declaration: string;
+    filePath: string;
+    kind: string;
+    line: number;
+    /** The comment's prose, with every marker stripped. */
+    prose: string;
+    /** The comment exactly as the file carries it, markers and all. */
+    source: string;
+}
+
+/** Arguments accepted when measuring every configured language's comments. */
+declare interface MeasureLanguageCommentsArguments {
+    /** One `comment`-selector custom statistic's budget, per declared statistic. */
+    counters: CommentCounter[];
+    files: LanguageCommentFiles;
+    /**
+     * Python's comments, already found by its own analyzer.
+     *
+     * Python is read in Python: its analysis runs `tokenize` in a subprocess,
+     * which knows a `#` inside a string literal from a real comment the way no
+     * line scanner can. The tokens arrive here rather than the measurements, so
+     * a word still means one thing across every language.
+     */
+    pythonComments: readonly LocatedCommentToken[];
+    workingDirectory: string;
+}
+
+/**
+ * What the notebooks themselves report, before any language analyzer runs.
+ *
+ * The two source lists are what the notebook contributes to the Python and
+ * markdown analyzers: cell bodies that exist in no file of their own.
+ */
+export declare interface NotebookParts {
+    cells: number;
+    codeCells: number;
+    codeSources: string[];
+    executedCells: number;
+    files: number;
+    markdownCells: number;
+    markdownSources: string[];
+    outputs: number;
+    rawCells: number;
+}
+
+/** A message split into the emoji the console shows and the prose telemetry stores. */
+declare interface ParsedLogMessage {
+    emoji: string | undefined;
+    text: string;
+}
+
+/**
+ * NestJS module that provides Python code analysis.
+ */
+export declare class PythonModule {
+}
+
+/**
+ * Aggregated statistics produced by the Python analyzer.
+ */
+export declare interface PythonResult {
+    classes: number;
+    commentLines: number;
+    comments: number;
+    /** Every comment `tokenize` found, with the file it was found in. */
+    commentTokens: LocatedCommentToken[];
+    constants: number;
+    decorators: number;
+    docstringLines: number;
+    docstrings: number;
+    files: number;
+    functions: number;
+    imports: number;
+    lines: number;
+    protocols: number;
+}
+
+/**
+ * Executes the Python analysis script and returns aggregated metrics.
+ */
+export declare class PythonService {
+    private readonly logger;
+    constructor(logger: LoggerService);
+    private readonly scriptPath;
+    /**
+     * Analyze the given Python files, resolved relative to the directory.
+     *
+     * The interpreter comes from the configuration because reaching Python is a
+     * property of the repository, not of the analysis: a managed environment is
+     * entered with `uv run python` or `poetry run python`, and a plain one with
+     * `python3`.
+     *
+     * The paths travel over stdin rather than argv so that a repository with
+     * thousands of Python files cannot overflow the command-line length limit.
+     */
+    analyze(args: AnalyzePythonArguments): PythonResult;
+    /**
+     * Analyze Python source text that never came from a file of its own.
+     *
+     * The seam the jupyter analyzer reads through. The interpreter reads files,
+     * so the sources are staged in a temporary directory first — but the
+     * analysis still runs from the measured directory, because a command like
+     * `uv run python` resolves its environment from the working directory and
+     * would find no project under the system temp directory.
+     */
+    analyzeContents(args: AnalyzePythonContentsArguments): PythonResult;
+}
+
+/** Input to the Shell analysis step. */
+export declare interface ShellInput {
+    shellFiles: string[];
+    workingDirectory: string;
+}
+
+/**
+ * NestJS module that provides Shell source analysis.
+ */
+export declare class ShellModule {
+}
+
+/** Aggregated metrics collected from parsing Shell sources. */
+export declare interface ShellResult {
+    commentLines: number;
+    comments: number;
+    conditionals: number;
+    exports: number;
+    files: number;
+    functions: number;
+    lines: number;
+    loops: number;
+    pipelines: number;
+    shebangs: number;
+    variables: number;
+}
+
+/**
+ * Counts the constructs a shell script is built from.
+ *
+ * Pattern-based rather than parsed: shell has no syntax tree available without
+ * a native dependency, and a heuristic that a reader would agree with is worth
+ * more here than no measurement at all. Comment lines are recognized before
+ * anything else so that a `#` opening a line never reads as code.
+ */
+export declare class ShellService {
+    private readonly logger;
+    constructor(logger: LoggerService);
+    /** Records the constructs one line of shell holds. */
+    private countLine;
+    /** Records the constructs a line of shell code holds. */
+    private countStatements;
+    /** Analyze the given shell scripts, resolved against the directory. */
+    analyze({ shellFiles, workingDirectory }: ShellInput): ShellResult;
+}
+
+/**
+ * Reads SQL's `--` and `/* ... *\/` comments.
+ *
+ * A line scanner rather than a tokenizer, so a `--` or `/*` inside a `'…'`
+ * string literal is read as a comment here exactly as it already is when
+ * `SqlService` counts keywords — the reading is the same, only the positions
+ * are new. The block form is found with `indexOf` rather than a regular
+ * expression: a pattern matching an unclosed `/*` through to end of input has
+ * to fail once per occurrence, which is quadratic on adversarial input, while
+ * two `indexOf` calls per comment never scan the same text twice.
+ */
+export declare class SqlCommentsService {
+    constructor();
+    /** Every `/* *\/` comment's span, left to right and never overlapping. */
+    private findBlockComments;
+    /** Whether only whitespace precedes an offset on its own line. */
+    private isOwnLine;
+    /** The 1-indexed line an offset sits on. */
+    private lineOf;
+    /** Every block comment's span, as a positioned token. */
+    private readBlocks;
+    /** Every match of a comment pattern, as a positioned token. */
+    private readMatches;
+    /**
+     * Reads every `--` and `/* *\/` comment, in the order they appear.
+     *
+     * Block spans are found first so a `--` matched inside one can be
+     * dropped — the block already spans the whole thing, and without dropping
+     * the overlap a `--` written as prose inside a block would be measured a
+     * second time as a comment of its own.
+     */
+    read(content: string): CommentToken[];
+}
+
+/** Input to the Sql analysis step. */
+export declare interface SqlInput {
+    sqlFiles: string[];
+    workingDirectory: string;
+}
+
+/**
+ * NestJS module that provides Sql source analysis.
+ */
+export declare class SqlModule {
+}
+
+/** Aggregated metrics collected from parsing Sql sources. */
+export declare interface SqlResult {
+    comments: number;
+    commonTableExpressions: number;
+    creates: number;
+    deletes: number;
+    files: number;
+    inserts: number;
+    joins: number;
+    lines: number;
+    selects: number;
+    statements: number;
+    updates: number;
+}
+
+/**
+ * Counts the statements and clauses a SQL script is built from.
+ *
+ * Comments are stripped before anything is counted, so a `SELECT` inside a
+ * `--` explanation is prose rather than a query. Statements are separated on
+ * semicolons, which is what the dialect-agnostic reading of a script is.
+ */
+export declare class SqlService {
+    private readonly logger;
+    constructor(logger: LoggerService);
+    /** Records every keyword occurrence in the comment-free source. */
+    private countKeywords;
+    /** Counts the comments in a script and returns the source without them. */
+    private stripComments;
+    /** Analyze the given SQL scripts, resolved against the directory. */
+    analyze({ sqlFiles, workingDirectory }: SqlInput): SqlResult;
+}
+
+/** Input to the Toml analysis step. */
+export declare interface TomlInput {
+    tomlFiles: string[];
+    workingDirectory: string;
+}
+
+/**
+ * NestJS module that provides Toml source analysis.
+ */
+export declare class TomlModule {
+}
+
+/** Aggregated metrics collected from parsing Toml sources. */
+export declare interface TomlResult {
+    arrays: number;
+    arrayTables: number;
+    comments: number;
+    files: number;
+    keys: number;
+    lines: number;
+    tables: number;
+}
+
+/**
+ * Counts the tables, keys, and arrays a TOML document declares.
+ *
+ * Read line by line while tracking whether a multi-line string is open, so a
+ * `#` or a `[heading]` inside one of those strings is content rather than
+ * syntax. That state is the whole reason this is not three regexes.
+ */
+export declare class TomlService {
+    private readonly logger;
+    constructor(logger: LoggerService);
+    /** Records a key assignment and whether its value opens an array. */
+    private countKey;
+    /** Records the declaration one line of TOML holds. */
+    private countLine;
+    /**
+     * Whether the line closes the multi-line string that was open, or opens one.
+     *
+     * An odd number of `"""` or `'''` delimiters flips the state; an even number
+     * opens and closes within the same line and leaves it as it was.
+     */
+    private isInsideMultilineString;
+    /** Analyze the given TOML documents, resolved against the directory. */
+    analyze({ tomlFiles, workingDirectory }: TomlInput): TomlResult;
+}
+
+/**
+ * Reads TypeScript and JavaScript's `//` and non-JSDoc `/* ... *\/` comments
+ * from the compiler's real parse, rather than its bare scanner.
+ *
+ * A bare `ts.createScanner` cannot tell a `/` that divides from one that opens
+ * a regular expression without the parser's context, and gets it wrong on real
+ * source — swallowing a long run of genuine comments as trivia inside a
+ * misread token. Parsing for real and walking every leaf token's leading and
+ * trailing trivia is what a full parse resolves correctly, at the cost of one
+ * parse per file instead of one scan.
+ *
+ * A JSDoc `/**` block is skipped here — `DeclarationCommentsService`
+ * already measures those — the same check it uses to find one: the
+ * delimiter's first three characters.
+ */
+export declare class TypescriptCommentsService {
+    constructor();
+    /**
+     * Walks every leaf token, collecting the comments around it.
+     *
+     * Both sides of every leaf, because a comment sharing its line with the
+     * token before it is that token's *trailing* trivia rather than the next
+     * token's *leading* trivia — `getLeadingCommentRanges` at a token's start
+     * never finds it, only `getTrailingCommentRanges` at the previous token's
+     * end does.
+     */
+    private collectComments;
+    /** Choose the dialect a file is parsed as, from its extension. */
+    private getScriptKind;
+    /** Whether this range is a JSDoc block, measured elsewhere. */
+    private isJsDoc;
+    /** Whether only whitespace precedes an offset on its own line. */
+    private isOwnLine;
+    /** The 1-indexed line an offset sits on. */
+    private lineOf;
+    /** Strips a comment's delimiters, leaving its prose. */
+    private toProse;
+    /** Turns one comment range into a token, unless it is a JSDoc block. */
+    private toToken;
+    /** Reads every non-JSDoc comment the parse finds, in source order. */
+    read(content: string, filePath: string): CommentToken[];
+}
+
+/** Input to the TypeScript/JavaScript AST analysis step. */
+export declare interface TypescriptInput {
+    /**
+     * Every `comment`-selector custom statistic's budget, per declared statistic.
+     *
+     * The whole list, not only the counters this walk measures: a counter naming
+     * a documentable `kind` is one of those and every other one is ignored here,
+     * which is what leaves a configuration declaring no such statistic measuring
+     * nothing rather than measuring against a limit nobody chose.
+     */
+    commentCounters: CommentCounter[];
+    sourceFiles: string[];
+    /** Configured counters over declarations, tallied during the same walk. */
+    symbolCounters: TypescriptSymbolCounter[];
+    workingDirectory: string;
+}
+
+/**
+ * NestJS module that provides TypeScript and JavaScript code analysis.
+ */
+export declare class TypescriptModule {
+}
+
+/** Aggregated metrics collected from walking TypeScript and JavaScript ASTs. */
+export declare interface TypescriptResult {
+    asyncFunctions: number;
+    blockComments: number;
+    classes: number;
+    commentLines: number;
+    comments: number;
+    constants: number;
+    /** One measurement list per configured declaration-comment counter, keyed by its label. */
+    declarationCommentCounts: Record<string, CommentMeasurement[]>;
+    decorators: number;
+    docComments: number;
+    docTags: Record<string, number>;
+    enums: number;
+    exported: number;
+    externalPackages: Set<string>;
+    functions: number;
+    genericDeclarations: number;
+    imports: number;
+    interfaces: number;
+    jsFiles: number;
+    lineComments: number;
+    lines: number;
+    methods: number;
+    /** One tally per configured symbol counter, keyed by its label. */
+    symbolCounts: Record<string, number>;
+    syncFunctions: number;
+    testFiles: number;
+    todos: number;
+    tsFiles: number;
+}
+
+/** Walks TypeScript and JavaScript ASTs to collect code metrics. */
+export declare class TypescriptService {
+    private readonly declarationComments;
+    /** Creates the TypescriptService. */
+    constructor(declarationComments: DeclarationCommentsService);
+    /**
+     * What to count for each syntax kind the walk cares about.
+     *
+     * Read by `dispatchNode`, which is the only caller: a kind absent from the
+     * table is a node this analyzer counts nothing for, so adding a statistic
+     * means adding a row here rather than another branch inside the walk.
+     *
+     * `dispatchNode` reaches a row by computed member access, which no call
+     * graph can follow — callidescope records the call as unfollowable and
+     * every row here as an entry point nothing calls. So a traced stack stops
+     * at `dispatchNode` and each `handle*` method appears again at the root of
+     * a stack of its own. That is the price of a table over a `switch`, and
+     * worth knowing before reading those roots as dead code.
+     */
+    private readonly kindDispatch;
+    /** Read one source file, count its lines and comments, and walk its AST. */
+    private analyzeFile;
+    /** Measure a documentable declaration's leading JSDoc comment, if it has one. */
+    private collectDeclarationComments;
+    /** Count a discovered comment and update the appropriate metrics. */
+    private countComment;
+    /**
+     * Tally every configured counter that claims this declaration.
+     *
+     * A declaration is claimed when its kind is one the counter asked for and
+     * it carries every modifier the counter requires; a counter naming no
+     * modifiers asks for the kind alone.
+     */
+    private countSymbols;
+    /**
+     * Build the zeroed result every file's counters accumulate into.
+     *
+     * Every configured counter is seeded, so one that matches nothing reports a
+     * zero rather than going missing from the report entirely.
+     */
+    private createEmptyResult;
+    /** Dispatches non-class AST nodes to the appropriate metric-collection handler. */
+    private dispatchNode;
+    /** Narrow the configured counters to the ones that search this file. */
+    private getCountersForFile;
+    /** Choose the dialect a file is parsed as, from its extension. */
+    private getScriptKind;
+    /** Collect the modifier keywords a node carries, by configured name. */
+    private getSymbolModifiers;
+    /** Increments class, exported, and generic counts for a class node. */
+    private handleClass;
+    /** Increments enum and exported counts for an enum declaration node. */
+    private handleEnum;
+    /** Increments function, method, async, sync, exported, and generic counts for a function node. */
+    private handleFunction;
+    /** Increments import count and tracks the external package name if applicable. */
+    private handleImport;
+    /** Increments interface, exported, and generic counts for an interface declaration node. */
+    private handleInterface;
+    /** Increments method and async or sync counts for a method or accessor node. */
+    private handleMethodOrAccessor;
+    /** Increments exported and generic counts for a type alias declaration node. */
+    private handleTypeAlias;
+    /** Increments constant and exported counts for a const variable statement. */
+    private handleVariable;
+    /** Returns true when the node has an async modifier keyword. */
+    private hasAsyncKeyword;
+    /** Returns true when the node has an export modifier keyword. */
+    private hasExportKeyword;
+    /** Returns true when the node declares one or more type parameters. */
+    private hasTypeParameters;
+    /** Scan the provided source text and collect comment-based metrics. */
+    private scanComments;
+    /**
+     * Seed one empty list per counter this walk is the measurer for.
+     *
+     * A counter naming a `kind` is one of those, and a counter naming only a
+     * `language` is not: `kind` takes precedence, so a counter naming both is
+     * measured here and its `language` never read, which is the same tie-break
+     * `LanguageCommentsService` makes by skipping it. Written as a guarded loop
+     * rather than a filtered `Object.fromEntries`, which would spend two of
+     * `createEmptyResult`'s direct calls instead of one.
+     */
+    private seedDeclarationCommentCounts;
+    /** Recursively visits each AST node and dispatches to the appropriate handler. */
+    private walkNode;
+    /** Analyzes TypeScript and JavaScript source files and returns aggregated AST metrics. */
+    analyze(input: TypescriptInput): TypescriptResult;
+}
+
+/** One configured counter over declarations, resolved for the analyzer. */
+export declare interface TypescriptSymbolCounter {
+    kinds: CodometerSymbolKind[];
+    label: string;
+    modifiers: CodometerSymbolModifier[];
+    /** Globs narrowing which files are searched; empty searches all of them. */
+    patterns: string[];
+}
+
+/**
+ * What one file's AST walk carries with it, node to node.
+ *
+ * Narrowed once per file rather than rebuilt per node: which counters search a
+ * file depends on its path, and the path does not change as the walk descends.
+ */
+export declare interface TypescriptWalkContext {
+    commentCounters: CommentCounter[];
+    /**
+     * The symbol counters that apply to the file being walked.
+     *
+     * Narrowed once per file rather than per node: which counters search a file
+     * depends on its path, which does not change as the walk descends.
+     */
+    counters: TypescriptSymbolCounter[];
+    filePath: string;
+    insideClass: boolean;
+    sourceFile: SourceFile;
+    stats: TypescriptResult;
+}
+
+/**
+ * Reads YAML's comments from the tokenizer rather than from the text.
+ *
+ * The CST is the only view carrying both facts a measurement needs: an offset,
+ * so a breach can name the line it sits on, and the tokenizer's judgement of
+ * what is a comment at all, so a `#` inside a quoted scalar stays a character
+ * in a string. The composed document has the second and not the first — it
+ * hangs a whole run of `#` lines on a node as one string with no position,
+ * blank lines and all.
+ *
+ * This is why YAML does not use `HashCommentsService`: a line scanner would
+ * read `key: "a # b"` as carrying a comment, and YAML puts quoted scalars next
+ * to `#` constantly.
+ */
+export declare class YamlCommentsService {
+    constructor();
+    /** Walks one parsed token, recording every comment beneath it. */
+    private collectComments;
+    /** Whether a parsed token is a comment carrying an offset. */
+    private isCommentToken;
+    /** Turns one tokenizer offset into a positioned, placed comment line. */
+    private toToken;
+    /** Reads every comment the tokenizer found, in the order they appear. */
+    read(content: string): CommentToken[];
+}
+
+/** Input to the YAML analysis step. */
+export declare interface YamlInput {
+    workingDirectory: string;
+    yamlFiles: string[];
+}
+
+/**
+ * NestJS module that provides YAML document analysis.
+ */
+export declare class YamlModule {
+}
+
+/** Aggregated metrics collected from parsing YAML documents. */
+export declare interface YamlResult {
+    aliases: number;
+    anchors: number;
+    comments: number;
+    documents: number;
+    files: number;
+    keys: number;
+    lines: number;
+    mappings: number;
+    maxDepth: number;
+    scalars: number;
+    sequences: number;
+}
+
+/**
+ * Walks parsed YAML documents to collect structural metrics.
+ *
+ * Counted from the parse tree rather than from the text, so a `#` inside a
+ * quoted scalar stays a character in a string and an indented block reports
+ * its real nesting instead of a column number. The `yaml` package keeps
+ * comments and anchors on the nodes, which is what makes both countable at all.
+ */
+export declare class YamlService {
+    private readonly logger;
+    constructor(logger: LoggerService);
+    /** Walks a mapping's pairs or a sequence's items. */
+    private countCollection;
+    /** Records the comments attached to one node or document. */
+    private countComments;
+    /** Records one document and everything under it. */
+    private countDocument;
+    /** Records one node against the running totals, then walks its children. */
+    private countNode;
+    /** Analyze the given YAML files, resolved against the directory. */
+    analyze({ workingDirectory, yamlFiles }: YamlInput): YamlResult;
+}
+
+export { }