@codependix/nestjs-modules 0.0.3

package/dist/src/index.d.ts

@@ -0,0 +1,666 @@
+import { ConsoleLogger } from '@nestjs/common';
+import pino from 'pino';
+
+/**
+ * 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,
+        );
+    }
+}
+
+/** Legend explaining the rounded-node convention for an ambient module. */
+export declare const MODULE_GRAPH_AMBIENT_LEGEND = "_Rounded modules are global: every module can inject them, so their edges are left out._";
+
+/**
+ * Smallest graph the ambient-module rule is allowed to fire on.
+ *
+ * Below this a module imported by everything else is just a small graph, not
+ * a global one: in a two-module project the only import there is would
+ * qualify.
+ */
+export declare const MODULE_GRAPH_AMBIENT_MINIMUM_MODULES = 4;
+
+/** Mermaid diagram type and direction the graph is rendered as. */
+export declare const MODULE_GRAPH_MERMAID_HEADER = "flowchart LR";
+
+/** Rendered in place of a diagram for a project with no modules to graph. */
+export declare const MODULE_GRAPH_UNCONNECTED = "_This project defines no NestJS modules to graph._";
+
+/** Provides the NestJS module import Graph builder and renderer. */
+export declare class ModuleGraphModule {
+}
+
+/**
+ * Reduces an explored NestJS container into a Graph and renders it.
+ *
+ * Ported from `tools/synchronization`'s `nestjs-module-graphs` command (see
+ * issue #242), which this package replaces: the ambient-module heuristic and
+ * mermaid rendering are unchanged, but the cross-project ownership and
+ * grouping that command layers on top are not — codependix's Graph describes
+ * one project's own container, not the workspace's opinion of who else's
+ * modules it touches. `NestjsProjectService.exploreProject` is what supplies
+ * the explored tree this service turns into a Graph.
+ *
+ * `NestjsProjectService.exploreProject` reports the container's view rather than the
+ * decorators', which means every `@Global()` module is listed as an import of
+ * every other module. Drawn literally, one global module contributes an edge
+ * per module in the project and buries the structure worth reading, so those
+ * edges are left out and the module is drawn as a rounded node on its own.
+ */
+export declare class ModuleGraphService {
+    constructor();
+    /** Walks the tree into the edges worth drawing and the nodes they touch. */
+    private collectEdgesAndNodes;
+    /** Sorts edges by source then target so the rendered diagram never churns. */
+    private compareEdges;
+    /** Sorts nodes by name then declaring file so the graph is stable. */
+    private compareNodes;
+    /** Counts how many modules import each module. */
+    private countInboundEdges;
+    /**
+     * Names the modules every other module imports.
+     *
+     * A global module is registered into every module in the container, so it
+     * arrives with one inbound edge short of the module count.
+     */
+    private findAmbientModuleNames;
+    /** Renders a module as a plain node, or a rounded one when it is ambient. */
+    private renderNode;
+    /** Sorts names into a stable order. */
+    private sortNames;
+    /** Reduces an explored container to a Graph of its module imports. */
+    buildGraph(tree: NestjsExploredModule[], projectName: string): NestjsModuleGraph;
+    /** Derives the project-relative folder a module belongs to from its declaring file. */
+    deriveModuleFolder(node: NestjsModuleGraphNode): string;
+    /** Renders a module graph as a fenced mermaid diagram. */
+    renderMermaid(graph: NestjsModuleGraph): string;
+}
+
+/** Header declaring the mermaid diagram type and its default layout direction. */
+export declare const NESTJS_MODULES_WORKSPACE_GRAPH_MERMAID_HEADER = "graph LR";
+
+/** Rendered in place of a diagram for a workspace with no NestJS modules at all. */
+export declare const NESTJS_MODULES_WORKSPACE_GRAPH_UNCONNECTED = "_This workspace has no NestJS modules, in any project._";
+
+/**
+ * Modules NestJS creates to host a dynamic module's providers.
+ *
+ * These are implementation details of `forRoot`/`forRootAsync` rather than
+ * anything a project declares — `TypeOrmModule` is in a project's design and
+ * stays in the graph, while the `TypeOrmCoreModule` it builds underneath is
+ * not. The synthetic root belongs here for the same reason: this package
+ * created it, so it is not part of the project. So does `InternalCoreModule`,
+ * which NestJS adds to every container and imports into every module. It is
+ * matched by name because NestJS 11 and 12 export it from different paths.
+ */
+export declare const NESTJS_PROJECT_IGNORED_MODULES: RegExp[];
+
+/** File suffix that marks a NestJS module definition. */
+export declare const NESTJS_PROJECT_MODULE_FILE_SUFFIX = ".module.ts";
+
+/** Export a root module file is expected to provide. */
+export declare const NESTJS_PROJECT_ROOT_MODULE_EXPORT = "MainModule";
+
+/**
+ * Path, relative to a project root, of the module a project bootstraps.
+ *
+ * A project without one is a library rather than an application, and gets a
+ * synthetic root built from every module it defines instead.
+ */
+export declare const NESTJS_PROJECT_ROOT_MODULE_FILE = "src/main.module.ts";
+
+/**
+ * Additionally ignored when the root is synthetic.
+ *
+ * The synthetic root supplies a global `ConfigModule` so that a package whose
+ * modules read configuration in a `useFactory` can be scanned at all. That
+ * scaffolding is this package's, not the project's, so it stays out of the
+ * graph.
+ */
+export declare const NESTJS_PROJECT_SYNTHETIC_IGNORED_MODULES: RegExp[];
+
+/** Nx project tag that marks a project as one this package graphs. */
+export declare const NESTJS_PROJECT_TAG = "framework:nestjs";
+
+/** A module in an explored NestJS container. */
+export declare interface NestjsExploredModule {
+    /**
+     * Path to the file declaring the module class, relative to the project
+     * root. Undefined for a module the project imports rather than declares.
+     */
+    readonly declaringFile?: string | undefined;
+    /** Class names of the modules this one imports, in the container's order. */
+    readonly imports: string[];
+    /** The module class name. */
+    readonly name: string;
+}
+
+/**
+ * A NestJS project's module import graph, reduced to what an export needs.
+ *
+ * Built from the exploration of a project's container in
+ * preview mode — see `NestjsProjectService.exploreProject` — and kept to the
+ * plain module-name and edge shape a diagram or a JSON export can render
+ * directly, without carrying the container's own provider or controller
+ * metadata.
+ */
+export declare interface NestjsModuleGraph {
+    /**
+     * Modules every other module imports, and whose edges are therefore left
+     * out. Reported so a caller can say why the diagram looks sparser than the
+     * container does.
+     */
+    readonly ambientModuleNames: string[];
+    /** Every drawn import relationship, sorted so the diagram is stable. */
+    readonly edges: NestjsModuleGraphEdge[];
+    /** Modules left with no drawn edge in either direction. */
+    readonly isolatedModuleNames: string[];
+    /** Every module node in the graph, sorted. */
+    readonly nodes: NestjsModuleGraphNode[];
+    /** The project the graph was built from. */
+    readonly projectName: string;
+}
+
+/** One module importing another. */
+export declare interface NestjsModuleGraphEdge {
+    readonly source: string;
+    readonly target: string;
+}
+
+/** One module in a NestJS project's module import graph. */
+export declare interface NestjsModuleGraphNode {
+    /** Path to the file declaring the module class, relative to the project root. */
+    readonly declaringFile: string;
+    /** The module class name. */
+    readonly name: string;
+}
+
+/**
+ * The whole-workspace NestJS module graph: every NestJS project's own module
+ * graph, combined into one.
+ *
+ * Exported once at the workspace root rather than once per project — see
+ * `codependix-nx-projects`'s `WorkspaceGraph`, which this mirrors. A module's
+ * class name alone is not unique across the workspace — two different
+ * projects can each declare their own `AppModule` — so every node here is
+ * qualified with the project it belongs to (see
+ * `WorkspaceGraphService.qualifyModuleName`) rather than reused as-is from a
+ * single project's `NestjsModuleGraph`.
+ */
+export declare interface NestjsModulesWorkspaceGraph {
+    /** Every drawn import relationship, sorted so the diagram never churns. */
+    readonly edges: NestjsModulesWorkspaceGraphEdge[];
+    /** Every module in the graph, qualified by project and sorted. */
+    readonly moduleNames: string[];
+}
+
+/** One module importing another, both qualified by the project they belong to. */
+export declare interface NestjsModulesWorkspaceGraphEdge {
+    readonly source: string;
+    readonly target: string;
+}
+
+/** Provides the whole-workspace NestJS module graph builder. */
+export declare class NestjsModulesWorkspaceGraphModule {
+}
+
+/**
+ * Builds the whole-workspace NestJS module graph — every NestJS project's
+ * own module graph, combined into one — exported once at the workspace root
+ * rather than once per project.
+ *
+ * A module's class name alone is only unique within its own project — two
+ * different projects each declare their own `AppModule`, and even within one
+ * project `ModuleGraphService` already collapses two same-named modules into
+ * one node — so every node is qualified with the project it belongs to before
+ * the projects' graphs are combined, mirroring
+ * `codependix-nx-projects`'s `WorkspaceGraphService` without reusing its
+ * code, since the two build genuinely different kinds of graph from
+ * genuinely different sources. `ModuleGraphService.buildGraph` has already
+ * dropped ambient-module edges per project by the time a graph reaches here,
+ * so nothing further needs deciding about ambience at workspace scope.
+ */
+export declare class NestjsModulesWorkspaceGraphService {
+    constructor();
+    /** Sorts edges by source then target so a rendered diagram never churns. */
+    private compareEdges;
+    /** Qualifies a module's class name with the project it belongs to. */
+    private qualifyModuleName;
+    /** Renders one qualified module name as a mermaid node. */
+    private renderNode;
+    /** Sorts names into a stable order. */
+    private sortNames;
+    /** Turns a qualified module name into an identifier mermaid accepts. */
+    private toNodeIdentifier;
+    /**
+     * Builds the whole-workspace NestJS module graph from every discovered
+     * NestJS project's own already-built module graph.
+     */
+    buildWorkspaceGraph(graphs: NestjsModuleGraph[]): NestjsModulesWorkspaceGraph;
+    /** Renders the whole-workspace NestJS module graph as a mermaid diagram. */
+    renderMermaid(workspaceGraph: NestjsModulesWorkspaceGraph): string;
+}
+
+/** A workspace project tagged `framework:nestjs`. */
+export declare interface NestjsProject {
+    /** Absolute path of the project directory. */
+    readonly absoluteRoot: string;
+    /** Project directory name, which is also the Nx project name. */
+    readonly name: string;
+    /**
+     * Absolute path of the project's root module file, when it has one.
+     *
+     * Undefined for a library package, whose container is rooted in a
+     * synthetic module built from every module the package defines.
+     */
+    readonly rootModuleFile: string | undefined;
+}
+
+/** Provides NestJS project discovery and container exploration. */
+export declare class NestjsProjectModule {
+}
+
+/**
+ * Discovers the workspace's `framework:nestjs` projects and explores each
+ * one's container.
+ *
+ * Ported from `tools/synchronization`'s `nestjs-module-graphs` command (see
+ * issue #242), which this package replaces: exploration still runs the
+ * container in NestJS preview mode, which registers every module and
+ * provider without instantiating any of them. That is what makes a project
+ * safe to graph from a workstation or from CI: a project building a
+ * `TypeOrmModule.forRootAsync` options factory never has a database
+ * contacted. Project discovery reads the tags each project already carries
+ * rather than walking the filesystem for a `project.json`, since whoever
+ * read the Nx project graph for the Nx exports has already collected them.
+ */
+export declare class NestjsProjectService {
+    private readonly logger;
+    constructor(logger: LoggerService);
+    /** Roots a package that bootstraps nothing in every module it defines. */
+    private buildSyntheticRootModule;
+    /**
+     * Discovers declaring files for every module in a project, relative to its
+     * root.
+     */
+    private discoverModuleDeclaringFiles;
+    /**
+     * Lists every module in a container with the modules it imports, both by
+     * class name and in the container's registration order, leaving the ignored
+     * modules out of the list and out of every import.
+     *
+     * Reads the container through its public `ModulesContainer` provider, which
+     * a preview-mode container still hands out because NestJS registers it as a
+     * value. The container's view is what `import` edges report, so a global
+     * module appears as an import of every module rather than only of those
+     * that name it.
+     */
+    private exploreContainer;
+    /** Finds every module definition file beneath a directory. */
+    private findModuleFiles;
+    /** Imports a module file and returns every module class it exports. */
+    private loadModuleClasses;
+    /** Imports a root module file and returns the module class it exports. */
+    private loadRootModule;
+    /** Describes a project, noting whether it bootstraps a root module. */
+    describeProject(absoluteRoot: string, name: string): NestjsProject;
+    /**
+     * Filters an already-read list of Nx projects down to the ones tagged
+     * `framework:nestjs`, and describes each one.
+     *
+     * Projects are returned in the order they were given, which callers keep
+     * sorted by name — the same order `codependix-nx-projects`'s `NeighborhoodService`
+     * reads the Nx project graph's own projects in.
+     */
+    discoverProjects(projects: {
+        absoluteRoot: string;
+        name: string;
+        tags: string[];
+    }[]): NestjsProject[];
+    /** Explores a project's container in preview mode and returns its tree. */
+    exploreProject(project: NestjsProject): Promise<NestjsExploredModule[]>;
+    /** Reports whether a project's Nx tags mark it as a NestJS project. */
+    isNestjsProject(project: {
+        tags: string[];
+    }): boolean;
+}
+
+/** A message split into the emoji the console shows and the prose telemetry stores. */
+declare interface ParsedLogMessage {
+    emoji: string | undefined;
+    text: string;
+}
+
+export { }