@codometer/cli 0.0.1

package/dist/src/index.d.ts

@@ -0,0 +1,649 @@
+import { ChangesService } from '@codometer/output';
+import { CommandRunner } from 'nest-commander';
+import { ConfigurationListingService } from '@codometer/output';
+import { ConfigurationService } from '@codometer/configuration';
+import { ConsoleLogger } from '@nestjs/common';
+import { DeliveryService } from '@codometer/output';
+import { DestinationsService } from '@codometer/output';
+import { DocumentsService } from '@codometer/output';
+import { MeasureCommandOptions } from '@codometer/configuration';
+import { MeasureFormat } from '@codometer/configuration';
+import { MeasurementResult } from '@codometer/measurement';
+import { MeasureService } from '@codometer/measurement';
+import pino from 'pino';
+import { RenderConfigurationService } from '@codometer/output';
+import { RenderService } from '@codometer/output';
+import { ReportService } from '@codometer/output';
+import { ResolvedCodometerConfiguration } from '@codometer/configuration';
+import { ResolvedMarkdownDestination } from '@codometer/output';
+import { RunDestinations } from '@codometer/output';
+import { RunMode } from '@codometer/configuration';
+
+/**
+ * CLI entry point for the pull request change report.
+ *
+ * Diffs every project's codometer report against a baseline snapshot and
+ * puts the result wherever it was asked for. Only ever reads and writes a
+ * local markdown file — handing that file to a pull request, an issue, or a
+ * wiki is the caller's job, which keeps this command independent of any one
+ * forge's API.
+ */
+export declare class ChangesCommand extends CommandRunner {
+    private readonly configurationService;
+    private readonly changesService;
+    private readonly documentsService;
+    private readonly renderService;
+    private readonly logger;
+    constructor(configurationService: ConfigurationService, changesService: ChangesService, documentsService: DocumentsService, renderService: RenderService, logger: LoggerService);
+    /** Parse the baseline directory holding a snapshot of the reports. */
+    parseBaseline(value: unknown): string | undefined;
+    /** Parse the run URL the baseline came from, linked from the summary. */
+    parseBaselineUrl(value: unknown): string | undefined;
+    /** Parse the directory to look for codometer reports in. */
+    parseDirectory(value: unknown): string;
+    /** Parse the markdown document the report is spliced into. */
+    parseMarkdown(value: unknown): string | undefined;
+    /** Parse the file the report is written to on its own. */
+    parseOutput(value: unknown): string | undefined;
+    /** Diffs every project's report against the baseline, and emits the result. */
+    run(_passedParameters: string[], options: ChangesCommandOptions): Promise<void>;
+}
+
+/**
+ * Options accepted by the `changes` command.
+ *
+ * Typed loosely because commander skips an option's parser when the flag
+ * arrives without a value, handing the command `true` instead of text.
+ */
+declare interface ChangesCommandOptions {
+    baseline?: unknown;
+    baselineUrl?: unknown;
+    directory?: unknown;
+    markdown?: unknown;
+    output?: unknown;
+}
+
+/** Wires the `changes` command that reports codometer's diff against main. */
+export declare class ChangesModule {
+}
+
+/**
+ * CLI entry point for listing what a repository configures.
+ *
+ * Reports configuration and never measurement: no build is required, nothing
+ * is compressed, and no limit is evaluated. That separation is the point — a
+ * repository whose limits live one per project has no single place left to
+ * read them as a set, and this is that place, without waiting on the builds
+ * a measurement would need.
+ */
+export declare class ConfigurationCommand extends CommandRunner {
+    private readonly codometerConfigurationService;
+    private readonly configurationService;
+    private readonly renderConfigurationService;
+    private readonly logger;
+    constructor(codometerConfigurationService: ConfigurationService, configurationService: ConfigurationListingService, renderConfigurationService: RenderConfigurationService, logger: LoggerService);
+    /**
+     * Parse the configuration file answering for the walk root.
+     *
+     * The exclusions the walk uses come from whatever configuration answers for
+     * the directory being listed, and a workspace stating its shared object
+     * somewhere every project spreads it from has nothing at its own root for
+     * the upward search to find — so it names that file here, the same way its
+     * measurement target already does.
+     */
+    parseConfig(value: string | undefined): string | undefined;
+    /** Parse the directory to look for configuration files beneath. */
+    parseDirectory(value: unknown): string;
+    /** Parse the output format the listing is rendered in. */
+    parseFormat(value: unknown): string;
+    /** Parse whether to list only the limits. */
+    parseLimits(): boolean;
+    /**
+     * Lists what the tree beneath the given directory configures.
+     *
+     * Writes to standard output rather than a file: the listing is something a
+     * reader looks at or pipes onward, and unlike a measurement it has no report
+     * anything else consumes.
+     */
+    run(_passedParameters: string[], options?: ConfigurationCommandOptions): Promise<void>;
+}
+
+/** Options accepted by the configuration command. */
+declare interface ConfigurationCommandOptions {
+    config?: string | undefined;
+    directory?: string | undefined;
+    format?: string | undefined;
+    limits?: boolean | undefined;
+}
+
+/**
+ * Wires the command that lists what a repository configures.
+ *
+ * Nothing but wiring. Reading the tree and rendering what it found belong to
+ * `@codometer/output`, which is where every other render target already
+ * lives; this module hands the command the two it needs.
+ */
+export declare class ConfigurationModule {
+}
+
+/**
+ * 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,
+        );
+    }
+}
+
+/**
+ * Root NestJS application module.
+ */
+export declare class MainModule {
+}
+
+/**
+ * CLI entry point for the repository measurement workflow.
+ */
+export declare class MeasureCommand extends CommandRunner {
+    private readonly configurationService;
+    private readonly measureService;
+    private readonly deliveryService;
+    private readonly reportService;
+    private readonly destinationsService;
+    private readonly logger;
+    constructor(configurationService: ConfigurationService, measureService: MeasureService, deliveryService: DeliveryService, reportService: ReportService, destinationsService: DestinationsService, logger: LoggerService);
+    /**
+     * Say which files were left out because codometer writes them.
+     *
+     * Announced rather than left to be noticed. A file missing from the counts
+     * with no explanation reads as a measurement bug, and the last repository to
+     * hit this wrote the exclusion into its ignore file by hand.
+     */
+    private announceOutputPaths;
+    /**
+     * Replaces every configured input with the globs `--inputs` named, when it
+     * was passed.
+     *
+     * Not a filter over configured inputs: the run measures exactly the globs
+     * given, running the `language` analysis over them, with no other input —
+     * not even the built-in `codebase` one — active.
+     */
+    private applyInputsOverride;
+    /**
+     * Read the configuration, or say why it could not be read.
+     *
+     * A configuration nothing can parse fails the run rather than being taken as
+     * an empty one, and so does a directory with no configuration file anywhere
+     * above it: `format` is required with no code-level fallback, so an absent
+     * file 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
+     * `codometer.config.ts`, is what states it once for a workspace.
+     */
+    private readConfiguration;
+    /** Says the command line could not be made sense of, and fails the run. */
+    private rejectCommandLine;
+    /** Report every breached limit, and say whether one of them fails the run. */
+    private reportBreaches;
+    /**
+     * Report whatever the run could not do, and say whether it fails the run.
+     *
+     * A failure is neither staleness nor a breach: it is the run not having
+     * finished. It stops any run that produces or gates an output, because a
+     * report built from a partial measurement is not one to publish and a gate
+     * that could not be evaluated has not been passed. A run that does neither
+     * says so and exits clean, exactly as its flags promised.
+     */
+    private reportFailures;
+    /** Weigh every finding, set the exit code once, and say the run is done. */
+    private reportFindings;
+    /** Report every stale destination, and say whether that fails the run. */
+    private reportStaleness;
+    /**
+     * Reads the flags into everything the rest of the run needs: the mode, the
+     * resolved configuration, what to print, and where each output goes.
+     *
+     * `undefined` when the run cannot proceed at all — a rejected command line,
+     * or a configuration that failed to load — with the refusal and exit code
+     * already reported, so nothing after this has to check twice.
+     */
+    private resolveRunPlan;
+    /**
+     * Resolve the directory the run measures, and announce that it started.
+     *
+     * Always the process's working directory: unlike every other flag, there is
+     * no per-run override for it — a run measures where it was invoked.
+     */
+    private resolveWorkingDirectory;
+    /**
+     * Parse the set of things the run fails on from command-line input.
+     *
+     * The parser runs only when `--check` carries a value, so anything reaching
+     * it is a written set. A `--check` with no value never arrives here at all
+     * and is refused later, because a set with nothing in it is indistinguishable
+     * from the flag having been left off — which is how check mode once silently
+     * became write mode.
+     */
+    parseCheck(value: string): string;
+    /**
+     * Parse the optional configuration path from command-line input.
+     */
+    parseConfig(value: string | undefined): string | undefined;
+    /**
+     * Parse what the run prints from command-line input.
+     *
+     * Says nothing about which files are written — that is each `--output-*`
+     * flag's job. Omitted, it reads the resolved configuration's own required
+     * `format` field rather than inferring one from which other flags are
+     * present.
+     */
+    parseFormat(value: string): string;
+    /**
+     * Parse the glob array that replaces every configured input, from
+     * command-line input.
+     *
+     * Each value commander hands the parser is one glob; they accumulate into
+     * one array across the whole `--inputs` invocation.
+     */
+    parseInputs(value: string, previous?: string[]): string[];
+    /**
+     * Parse the report's destination from command-line input.
+     *
+     * `true` when the flag was passed with no value, asking this run to write
+     * wherever the resolved configuration's own JSON output says to; a string
+     * when a path was given, which is used for this destination alone.
+     */
+    parseOutputJson(value: string | true): string | true;
+    /**
+     * Parse the markdown badge block's destination from command-line input.
+     *
+     * `true` when the flag was passed with no value, asking this run to write
+     * wherever the resolved configuration's own markdown output says to; a
+     * string when a path was given, which is used for this destination alone.
+     */
+    parseOutputMarkdown(value: string | true): string | true;
+    /**
+     * Measure the repository and produce every resolved output.
+     *
+     * Flags are independent: `--output-json`/`--output-markdown` each write
+     * their own destination, `--check reports` fails on a stale report,
+     * `--check limits` fails on a breached limit, `--format` prints, and none of
+     * them turns another on. Every output is produced before any finding is
+     * weighed, so a run that writes and gates leaves the report behind even
+     * when the gate trips.
+     */
+    run(_passedParameters: string[], options: MeasureCommandOptions): Promise<void>;
+}
+
+/**
+ * NestJS module that wires the measure command to the layers it composes.
+ *
+ * Nothing but wiring: the configuration layer reads the command line and the
+ * configuration file, the measurement layer counts, and the output layer
+ * resolves destinations, builds the report, and delivers it. The command
+ * calls them in order and sets an exit code.
+ */
+export declare class MeasureModule {
+}
+
+/** A message split into the emoji the console shows and the prose telemetry stores. */
+declare interface ParsedLogMessage {
+    emoji: string | undefined;
+    text: string;
+}
+
+/** Arguments accepted when weighing what a run found. */
+export declare interface ReportFindingsArguments {
+    measurement: MeasurementResult;
+    mode: RunMode;
+    /** Destinations found not to hold the current output. Only ever non-empty
+     * when the run was comparing, since nothing else reads a destination. */
+    stalePaths: string[];
+}
+
+/**
+ * Everything a run needs once its command line has been made sense of: the
+ * resolved configuration, what to print, where each output goes, and what
+ * the run does with what it measures.
+ */
+export declare interface RunPlan {
+    configuration: ResolvedCodometerConfiguration;
+    /** Where the console's own badge block comes from, resolved independently
+     * of `destinations.markdown` so it never depends on which `--output-*` flag
+     * was passed. */
+    consoleMarkdown: ResolvedMarkdownDestination | undefined;
+    destinations: RunDestinations;
+    format: MeasureFormat | undefined;
+    mode: RunMode;
+}
+
+export { }

package/dist/src/index.js

@@ -0,0 +1,2 @@
+import { a as e, i as t, n, o as r, r as i, s as a, t as o } from "../main.module-_z85wgY7.js";
+export { a as ChangesCommand, r as ChangesModule, e as ConfigurationCommand, t as ConfigurationModule, o as MainModule, i as MeasureCommand, n as MeasureModule };

package/dist/src/main.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/src/main.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { c as e, t } from "../main.module-_z85wgY7.js";
+import { CommandFactory as n } from "nest-commander";
+import "reflect-metadata";
+//#region packages/ic-suite/codometer/codometer-cli/src/main.utilities.ts
+function r(e) {
+	let t = /* @__PURE__ */ new Set([
+		"changes",
+		"configuration",
+		"help",
+		"measure"
+	]), n = /* @__PURE__ */ new Set(["--help", "-h"]), [r] = e;
+	return r !== void 0 && (t.has(r) || n.has(r)) ? [...e] : ["measure", ...e];
+}
+//#endregion
+//#region packages/ic-suite/codometer/codometer-cli/src/main.ts
+async function i() {
+	e.logToStandardError();
+	let i = new e();
+	i.setContext("CommandFactory"), process.argv = [...process.argv.slice(0, 2), ...r(process.argv.slice(2))], await n.run(t, {
+		bufferLogs: !0,
+		logger: i
+	});
+}
+i();
+//#endregion