@conformetry/cli 0.0.1

package/dist/src/index.d.ts

@@ -0,0 +1,662 @@
+import { CommandRunner } from 'nest-commander';
+import { ConfigurationService } from '@conformetry/configuration';
+import { ConsoleLogger } from '@nestjs/common';
+import { GenerationService } from '@conformetry/generation';
+import { InventoryService } from '@conformetry/output';
+import pino from 'pino';
+import { ReportingService } from '@conformetry/output';
+import { ValidationService } from '@conformetry/validation';
+
+/**
+ * Renders a conformetry template from the configured registry.
+ *
+ * Unknown options are allowed through deliberately: a template's parameters
+ * are not known until the template is chosen, so they cannot be declared as
+ * flags ahead of time. They are matched against the template's own schema
+ * instead. This is also why the template is selected with `--template` rather
+ * than `--name` — nearly every template takes a `name` parameter, and
+ * reserving that flag made it impossible to supply.
+ *
+ * `--template` is optional at the parse layer so a bare `generate` reaches
+ * this command and can offer a picker instead of failing at argument parsing
+ * with a name the reader would have had to look up elsewhere.
+ */
+export declare class GenerateCommand extends CommandRunner {
+    private readonly configurationService;
+    private readonly generationService;
+    private readonly logger;
+    constructor(configurationService: ConfigurationService, generationService: GenerationService, logger: LoggerService);
+    /** Resolves the template's inputs and writes its files. */
+    private generate;
+    /**
+     * Logs a command line the input service refused, and fails the run.
+     *
+     * A required input that could not be asked for is the reader's own typing
+     * to fix, so it is reported as a rejected command line rather than as a
+     * crash. Nothing was generated, and the next move is to pass the flag it
+     * named, not to read a stack trace.
+     */
+    private rejectCommandLine;
+    /**
+     * Refuses the flag `--template` replaced, rather than ignoring it.
+     *
+     * Unknown options are allowed through so a template's own inputs can be
+     * passed as flags, which means commander does not reject `--generator` for
+     * this command the way it would for any other. Without this it would be
+     * read as an input nothing declares and quietly discarded, leaving a stale
+     * script to prompt or to fail for the wrong reason.
+     */
+    private rejectRemovedGeneratorOption;
+    /**
+     * Settles which template to render: the one named, the one picked, or none.
+     *
+     * The missing case and the unknown case are decided together here rather
+     * than split between argument parsing and the command body, which is what
+     * lets the picker sit between them. Whether anybody can be asked is read
+     * from the one predicate that knows — a non-terminal stdin is what once let
+     * a prompt hang a CI job until it timed out.
+     */
+    private resolveTemplateName;
+    /** Parses the optional configuration path. */
+    parseConfig(value: string | undefined): string | undefined;
+    /** Parses the output directory override. */
+    parseDirectory(value: string | undefined): string | undefined;
+    /**
+     * Parses the name of the template to render.
+     *
+     * Optional, so a bare `generate` is not rejected at argument parsing with a
+     * name the reader has not been shown yet.
+     */
+    parseTemplate(value: string | undefined): string | undefined;
+    /**
+     * Renders the template, reporting a refused command line as one.
+     *
+     * Only an `InputError` is caught: a required input nobody could be asked
+     * for is a flag the caller has to pass, where anything else is a genuine
+     * failure and keeps its stack.
+     */
+    run(passedParameters: string[], options: GenerateCommandOptions): Promise<void>;
+}
+
+/**
+ * Options accepted by the generate command.
+ *
+ * Keys are the camel-cased long flag names, which is how commander reports
+ * parsed options — `--directory` arrives as `directory`.
+ */
+export declare interface GenerateCommandOptions {
+    config?: string;
+    directory?: string;
+    /**
+     * Optional at the parse layer only. A bare `generate` has to reach the
+     * command body so the missing case and the unknown case can be decided
+     * together; the template itself is still required, and is either supplied
+     * here or chosen at the picker.
+     */
+    template?: string;
+}
+
+/**
+ * Provides the generate command.
+ */
+export declare class GenerateModule {
+}
+
+/**
+ * Lists every instance the configured globs find, and which templates explain
+ * each one.
+ *
+ * Each path printed is usable as the `--instances` argument to the templates
+ * command, so the two read as one pair: this side answers "what is generated
+ * code here", the other answers "what standard does this path answer to".
+ *
+ * Output goes to standard output rather than through the logger, which asserts
+ * every message opens with an emoji and a verb — right for a log line, wrong
+ * for a listing.
+ */
+export declare class InstancesCommand extends CommandRunner {
+    private readonly configurationService;
+    private readonly inventoryService;
+    private readonly logger;
+    constructor(configurationService: ConfigurationService, inventoryService: InventoryService, logger: LoggerService);
+    /** Parses the optional configuration path. */
+    parseConfig(value: string | undefined): string | undefined;
+    /** Selects the machine-readable listing. */
+    parseJson(): boolean;
+    /** Parses the optional template filter. */
+    parseTemplates(value: string | undefined): string[] | undefined;
+    /** Writes every instance found, filtered to the given templates. */
+    run(_passedParameters: string[], options: InstancesCommandOptions): Promise<void>;
+}
+
+/** Options accepted by the instances command. */
+export declare interface InstancesCommandOptions {
+    config?: string;
+    json?: boolean;
+    templates?: string[];
+}
+
+/**
+ * Provides the instances command.
+ */
+export declare class InstancesModule {
+}
+
+/**
+ * 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 {
+}
+
+/** A message split into the emoji the console shows and the prose telemetry stores. */
+declare interface ParsedLogMessage {
+    emoji: string | undefined;
+    text: string;
+}
+
+/**
+ * Names every template the configuration declares, and which instances each
+ * explains.
+ *
+ * With `--instances` it answers the other direction — which templates explain a
+ * given path. That is one command rather than two because a path can belong to
+ * several templates at once: nothing records where an instance came from, so
+ * attribution is inferred from file overlap and ties are real.
+ *
+ * Output goes to standard output rather than through the logger, which asserts
+ * every message opens with an emoji and a verb — right for a log line, wrong
+ * for a listing.
+ */
+export declare class TemplatesCommand extends CommandRunner {
+    private readonly configurationService;
+    private readonly inventoryService;
+    private readonly logger;
+    constructor(configurationService: ConfigurationService, inventoryService: InventoryService, logger: LoggerService);
+    /** Parses the optional configuration path. */
+    parseConfig(value: string | undefined): string | undefined;
+    /** Parses the optional instance filter. */
+    parseInstances(value: string | undefined): string[] | undefined;
+    /** Selects the machine-readable listing. */
+    parseJson(): boolean;
+    /** Writes every declared template, filtered to the given instances. */
+    run(_passedParameters: string[], options: TemplatesCommandOptions): Promise<void>;
+}
+
+/** Options accepted by the templates command. */
+export declare interface TemplatesCommandOptions {
+    config?: string;
+    instances?: string[];
+    json?: boolean;
+}
+
+/**
+ * Provides the templates command.
+ */
+export declare class TemplatesModule {
+}
+
+/**
+ * Validates instances against their conformetry templates.
+ *
+ * Which paths are instances comes from the configuration's `instances` globs,
+ * which `--instances` overrides for a one-off run, and `--templates` narrows
+ * the other half of the pairing. Neither flag overrides the other: each
+ * removes candidates from one side before templates and instances are paired,
+ * so a run is their intersection.
+ *
+ * `--templates` is the one option that is asked for when absent, because it
+ * is the one whose absence is genuinely a question rather than a default. It
+ * is asked only where somebody can answer: with no terminal the run falls
+ * back to every template, which is exactly what every invocation predating
+ * this flag already did.
+ */
+export declare class ValidateCommand extends CommandRunner {
+    private readonly configurationService;
+    private readonly reportingService;
+    private readonly validationService;
+    private readonly logger;
+    constructor(configurationService: ConfigurationService, reportingService: ReportingService, validationService: ValidationService, logger: LoggerService);
+    /**
+     * Describes why the run failed, naming the instances that fell short.
+     *
+     * A file count alone stopped being the whole story once thresholds existed:
+     * findings can be printed for an instance that still passed, so the message
+     * has to say which instances actually failed and by how much.
+     */
+    private describeFailure;
+    /**
+     * Expands every configured glob group into instances, or the single
+     * override group `--instances` supplies.
+     *
+     * Groups exist so that substitutions can differ per glob: `type` is
+     * `packages` for one set of paths and `applications` for another, and no
+     * generic rule can tell them apart.
+     */
+    private findInstances;
+    /**
+     * Offers a picker, or declines to ask where nobody could answer.
+     *
+     * Declining resolves to no selection rather than to a refusal, which is
+     * where this parts company with `generate`: a template that cannot be
+     * chosen leaves that command with nothing to render, where this one still
+     * has a whole workspace to validate.
+     *
+     * The loaded configuration is handed over as-is — a definition already
+     * carries the name and description a choice needs, so mapping it here would
+     * be a second source the picker could disagree with.
+     */
+    private promptForTemplateNames;
+    /**
+     * Reports a narrowing that matched nothing, as itself.
+     *
+     * A run with no instances produces no findings, and a report rendering no
+     * findings is indistinguishable from a clean one — which would turn naming
+     * a real template that happens to have nothing under it into a green
+     * result. The reader is told nothing matched instead.
+     */
+    private reportEmptySelection;
+    /**
+     * Writes the report and fails the run when anything fell short.
+     *
+     * The report is the command's product, not a log line: it is a multi-line
+     * document written for a reader, and routing it through the logger would
+     * both bury it in log framing and force prose no telemetry can group on.
+     */
+    private reportResult;
+    /**
+     * Pairs the two filters into the instances a run covers.
+     *
+     * With both flags supplied the globbed paths are intersected with the
+     * selected templates' own instances, rather than one flag winning: each
+     * simply removes candidates from one side.
+     */
+    private selectInstances;
+    /**
+     * Narrows the run to the selected templates, or leaves it whole.
+     *
+     * `undefined` means no narrowing, which is a different thing from an empty
+     * selection: it is what an absent flag, the `all` sentinel, and a cancelled
+     * picker all mean, and it reproduces the run this command made before the
+     * flag existed.
+     */
+    private selectTemplates;
+    /** Parses the optional configuration path. */
+    parseConfig(value: string | undefined): string | undefined;
+    /** Parses the optional instance glob override. */
+    parseInstances(value: string | undefined): string[] | undefined;
+    /** Parses the optional language filter. */
+    parseLanguages(value: string | undefined): string[] | undefined;
+    /**
+     * Parses the optional template filter.
+     *
+     * Comma-delimited like its `--instances` and `--languages` siblings, so all
+     * three read the same way on a command line.
+     */
+    parseTemplates(value: string | undefined): string[] | undefined;
+    /** Parses the optional run-level conformance threshold. */
+    parseThreshold(value: string | undefined): number | undefined;
+    /** Runs validation and reports every difference found. */
+    run(_passedParameters: string[], options: ValidateCommandOptions): Promise<void>;
+}
+
+/** Options accepted by the validate command. */
+export declare interface ValidateCommandOptions {
+    config?: string;
+    instances?: string[];
+    languages?: string[];
+    /**
+     * Template names to narrow the run to, or `["all"]` for every one.
+     *
+     * Absent means the caller has not decided, which is what the picker asks
+     * about; `["all"]` means they have, and nothing is asked.
+     */
+    templates?: string[];
+    threshold?: number;
+}
+
+/**
+ * Provides the validate command.
+ */
+export declare class ValidateModule {
+}
+
+export { }

package/dist/src/index.js

@@ -0,0 +1,2 @@
+import { a as e, c as t, i as n, l as r, n as i, o as a, r as o, s, t as c } from "../main.module-BIsov6qb.js";
+export { r as GenerateCommand, t as GenerateModule, s as InstancesCommand, a as InstancesModule, c as MainModule, e as TemplatesCommand, n as TemplatesModule, o as ValidateCommand, i as ValidateModule };

package/dist/src/main.d.ts

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

package/dist/src/main.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { t as e, u as t } from "../main.module-BIsov6qb.js";
+import { CommandFactory as n } from "nest-commander";
+import "reflect-metadata";
+//#region packages/ic-suite/conformetry/conformetry-cli/src/main.ts
+async function r() {
+	let r = new t();
+	r.setContext("CommandFactory"), await n.run(e, {
+		bufferLogs: !0,
+		errorHandler: (e) => {
+			process.exitCode = 1, r.error(e);
+		},
+		logger: r,
+		serviceErrorHandler: (e) => {
+			process.exitCode = 1, r.error(e);
+		}
+	});
+}
+r();
+//#endregion