@codependix/cli 0.0.3

package/dist/src/index.d.ts

@@ -0,0 +1,511 @@
+import { BoundaryCheckService } from '@codependix/boundaries';
+import { CombinedOutputService } from '@codependix/output';
+import { CommandRunner } from 'nest-commander';
+import { ConfigurationService } from '@codependix/configuration';
+import { ConsoleLogger } from '@nestjs/common';
+import { GraphRunService } from '@codependix/output';
+import { MapCommandOptions } from '@codependix/configuration';
+import pino from 'pino';
+import { ReportingService } from '@codependix/output';
+import { RunContextService } from '@codependix/boundaries';
+
+/**
+ * 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 codependix dependency graph workflow.
+ *
+ * `--write` publishes every configured export; `--check` names which finding
+ * fails the run — `boundaries` for an edge breaking a declared rule, `reports`
+ * for a configured destination that has gone stale. No per-graph-type
+ * subcommand: which graphs run, where each project's export lands, and which
+ * rules judge them is entirely a function of `codependix.config.ts`, read by
+ * `@codependix/configuration`.
+ *
+ * The two findings are named apart because they belong on opposite sides of a
+ * pull request. An export moves with the workspace it describes, so gating
+ * staleness on a branch fails every branch that touched a project graph; a
+ * broken boundary is caused by the branch and fixed by it. This is the split
+ * `callidescope` already made between `--check depth` and `--check reports`,
+ * copied wholesale down to the spelling of `reports`.
+ */
+export declare class MapCommand extends CommandRunner {
+    private readonly graphRunService;
+    private readonly boundaryCheckService;
+    private readonly combinedOutputService;
+    private readonly configurationService;
+    private readonly logger;
+    private readonly reportingService;
+    private readonly runContextService;
+    constructor(graphRunService: GraphRunService, boundaryCheckService: BoundaryCheckService, combinedOutputService: CombinedOutputService, configurationService: ConfigurationService, logger: LoggerService, reportingService: ReportingService, runContextService: RunContextService);
+    /**
+     * Prints and writes every active graph type's combined output, when the
+     * export pass ran at all.
+     *
+     * A `--check boundaries`-only run never reaches this: nothing was built to
+     * combine, so `--format`/`--json-output`/`--markdown-output` are silently
+     * inert on a run that touched no export at all — the same way `--write`
+     * and `--check reports` are inert on one that never named a destination.
+     */
+    private runCombinedOutput;
+    /**
+     * Runs the export pass, warning when nothing was selected.
+     *
+     * Returns both the usual delivery outcome and every active graph type's
+     * whole-workspace data, so `runMode` can hand the latter to
+     * `CombinedOutputService` without running the export pass a second time.
+     */
+    private runExports;
+    /**
+     * Runs the passes a resolved mode selected, and reports what they found.
+     *
+     * Split from `run` so the command line's own rejection path stays a
+     * handful of lines: everything below here has a mode to act on. Both
+     * passes are run directly here, rather than through a further-nested
+     * helper, to keep `MapCommand.run`'s own call stack inside this project's
+     * callidescope depth limit — see `packages/codependix-cli/callidescope.config.ts`.
+     */
+    private runMode;
+    /**
+     * Parses the set of findings the run fails on.
+     *
+     * 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 and is
+     * refused later: a set with nothing in it is indistinguishable from the flag
+     * having been left off, which is how one flag came to gate two findings.
+     */
+    parseCheck(value: string): string;
+    /** Parses the optional configuration path from command-line input. */
+    parseConfig(value: string | undefined): string | undefined;
+    /** Parses the directory whose Nx workspace this run reads. */
+    parseDirectory(value: string | undefined): string;
+    /**
+     * Parses `--exclude`, a comma-separated list of globs overriding the
+     * configured `exclude`.
+     *
+     * Refused later, by `ConfigurationService.loadConfiguration`, when the
+     * configuration this run reads never declared `exclude` in the first
+     * place — matching callidescope's `--exclude` refusal exactly.
+     */
+    parseExclude(value: string | undefined): string[];
+    /** Enables the `fileImports` graph type for this run. */
+    parseFileImports(): true;
+    /**
+     * Parses what `--format` prints to standard output.
+     *
+     * Defaults to Markdown when the flag was left off entirely — see
+     * `MapCommand.resolveFormat`, which validates the value this returns.
+     */
+    parseFormat(value: string | undefined): string | undefined;
+    /**
+     * Parses `--include`, a comma-separated list of globs overriding the
+     * configured `include`.
+     *
+     * Refused later, alongside `--exclude`, when the configuration this run
+     * reads never declared `include`.
+     */
+    parseInclude(value: string | undefined): string[];
+    /**
+     * Parses `--json-output`, the path to write every active graph type's
+     * combined JSON data to, keyed by graph type name.
+     */
+    parseJsonOutput(value: string | undefined): string | undefined;
+    /**
+     * Parses `--markdown-output`, the path to write every active graph type's
+     * combined, anchor-spliced Markdown diagram to.
+     */
+    parseMarkdownOutput(value: string | undefined): string | undefined;
+    /** Enables the `nestjsModules` graph type for this run. */
+    parseNestjsModules(): true;
+    /** Disables the `fileImports` graph type for this run. */
+    parseNoFileImports(): false;
+    /** Disables the `nestjsModules` graph type for this run. */
+    parseNoNestjsModules(): false;
+    /** Disables the `nxProjects` graph type for this run. */
+    parseNoNxProjects(): false;
+    /** Enables the `nxProjects` graph type for this run. */
+    parseNxProjects(): true;
+    /**
+     * Parses the projects a run exports for beyond `include`.
+     *
+     * **Widening, and narrowing.** A named project is added to whatever
+     * `include` already selected, and `exclude` still wins over it. It also
+     * narrows what a run draws and judges: the Workspace Graph's node set and
+     * every level `--check boundaries` judges become the named set. A narrowed
+     * gate sees fewer edges than a whole-workspace one — fine for a local run,
+     * and worth thinking twice about in CI.
+     */
+    parseProjects(value: string | undefined): string | undefined;
+    /**
+     * Parses the Nx tags a run exports for, matched exactly against a project's
+     * own tags. Widens and narrows exactly as `--projects` does.
+     */
+    parseTags(value: string | undefined): string | undefined;
+    /** Parses the `--write` flag from command-line input. */
+    parseWrite(value: boolean | undefined): boolean;
+    /**
+     * Runs whatever the command line asked for: exports, boundaries, or both.
+     *
+     * Every project is attempted regardless of whether an earlier one failed —
+     * both passes isolate a project's failure to itself — so this only decides
+     * the exit code from what came back. The two passes are also weighed
+     * independently rather than the first failure short-circuiting the second:
+     * a run gating both should report both, not the one that happened to run
+     * first.
+     */
+    run(_passedParameters: string[], options?: MapCommandOptions): Promise<void>;
+}
+
+/** Wires the codependix CLI command together with its collaborators. */
+export declare class MapModule {
+}
+
+/** A message split into the emoji the console shows and the prose telemetry stores. */
+declare interface ParsedLogMessage {
+    emoji: string | undefined;
+    text: string;
+}
+
+export { }

package/dist/src/index.js

@@ -0,0 +1,2 @@
+import { n as e, r as t, t as n } from "../main.module-B07sXqnE.js";
+export { n as MainModule, t as MapCommand, e as MapModule };

package/dist/src/main.d.ts

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

package/dist/src/main.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { i as e, t } from "../main.module-B07sXqnE.js";
+import { CommandFactory as n } from "nest-commander";
+import "reflect-metadata";
+//#region packages/ic-suite/codependix/codependix-cli/src/main.ts
+async function r() {
+	e.logToStandardError();
+	let r = new e();
+	r.setContext("CommandFactory"), await n.run(t, {
+		bufferLogs: !0,
+		logger: r
+	});
+}
+r();
+//#endregion

package/package.json

@@ -0,0 +1,77 @@
+{
+  "author": "Jimmy Paolini",
+  "bin": {
+    "codependix": "./dist/src/main.js"
+  },
+  "bugs": {
+    "url": "https://github.com/organizzolini/codebase/issues"
+  },
+  "dependencies": {
+    "@codependix/boundaries": "0.0.3",
+    "@codependix/configuration": "0.0.3",
+    "@codependix/core": "0.0.3",
+    "@codependix/output": "0.0.3",
+    "@nestjs/common": "^11.1.21 || ^12.0.1",
+    "@nestjs/config": "^12.0.0",
+    "@nestjs/core": "^11.1.21 || ^12.0.1",
+    "nest-commander": "^3.21.0",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "reflect-metadata": "^0.2.2",
+    "zod": "^4.4.3"
+  },
+  "description": "Command-line tool for exporting and validating Nx, NestJS, and file-level dependency graphs and boundaries",
+  "devDependencies": {
+    "@codebase/logger": "0.0.1",
+    "@golevelup/ts-vitest": "^4.0.0",
+    "@nestjs/testing": "^12.0.1",
+    "@nx/eslint-plugin": "^23.0.0",
+    "@swc-node/register": "^1.11.1",
+    "@swc/core": "^1.15.40",
+    "@swc/helpers": "^0.5.21",
+    "@types/node": "^26.5.1",
+    "@vitest/coverage-v8": "^5.0.0",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "homepage": "https://github.com/organizzolini/codebase/tree/main/packages/ic-suite/codependix/codependix-cli#readme",
+  "keywords": [
+    "architecture-linter",
+    "boundaries",
+    "cli",
+    "codependix",
+    "dependency-graph",
+    "mermaid"
+  ],
+  "license": "MIT",
+  "main": "./dist/src/index.js",
+  "name": "@codependix/cli",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "directory": "packages/ic-suite/codependix/codependix-cli",
+    "type": "git",
+    "url": "git+https://github.com/organizzolini/codebase.git"
+  },
+  "type": "module",
+  "typeCoverage": {
+    "atLeast": 100,
+    "strict": true
+  },
+  "types": "./dist/src/index.d.ts",
+  "version": "0.0.3"
+}