@codependix/output 0.0.3

package/dist/src/index.d.ts

@@ -0,0 +1,1252 @@
+import { AnchorCheckResult } from '@codependix/core';
+import { BoundaryCheckOutcome } from '@codependix/boundaries';
+import { BoundaryReportService } from '@codependix/boundaries';
+import { CodependixGraphType } from '@codependix/configuration';
+import { CodependixRunMode } from '@codependix/core';
+import { ConfigurationService } from '@codependix/configuration';
+import { ConsoleLogger } from '@nestjs/common';
+import { FileImportsWorkspaceGraphService } from '@codependix/file-imports';
+import { GraphRunContext } from '@codependix/boundaries';
+import { GraphRunOutcome } from '@codependix/core';
+import { MarkdownSectionArguments } from '@codependix/core';
+import { ModuleGraphService } from '@codependix/nestjs-modules';
+import { Neighborhood } from '@codependix/nx-projects';
+import { NeighborhoodService } from '@codependix/nx-projects';
+import { NestjsModuleGraph } from '@codependix/nestjs-modules';
+import { NestjsModulesWorkspaceGraphService } from '@codependix/nestjs-modules';
+import { NestjsProjectService } from '@codependix/nestjs-modules';
+import pino from 'pino';
+import { ProjectRunResult } from '@codependix/core';
+import { PythonService } from '@codependix/file-imports';
+import { ResolvedCodependixGraphOutput } from '@codependix/configuration';
+import { TypescriptService } from '@codependix/file-imports';
+import { WorkspaceGraph } from '@codependix/nx-projects';
+import { WorkspaceGraphService } from '@codependix/nx-projects';
+
+/** Arguments shared by every method that reads or rewrites an anchor. */
+declare interface AnchorLocationArguments {
+    anchorName: string;
+    fileContent: string;
+    filePath: string;
+}
+
+/**
+ * Raised when a named anchor block is not present in a Markdown file.
+ *
+ * `AnchorsService.checkAnchor` and `replaceAnchorContent` still raise this for
+ * any missing anchor — they are low-level primitives that know nothing about
+ * auto-creation. `DeliveryService` is what decides whether this ever reaches a
+ * caller: it only lets it surface when the file itself does not exist at all
+ * (a project with no `README.md` is a genuinely more serious problem), and
+ * intercepts a missing-but-creatable anchor before calling into these
+ * primitives — auto-creating the `## 🕸️ Codependix` section on `--write` (see
+ * `AnchorsService.insertAnchorSection`) and reporting it as stale on
+ * `--check` instead.
+ */
+export declare class AnchorNotFoundError extends Error {
+    constructor(anchorName: string, filePath: string);
+}
+
+/** Arguments for auto-creating a missing anchor's section on write. */
+declare interface AnchorSectionInsertArguments {
+    anchorName: string;
+    content: string;
+    fileContent: string;
+    introLine: string;
+    /**
+     * The `### <Subheading>` placed immediately above the anchor block, or
+     * `undefined` when the anchor sits directly under the `## 🕸️ Codependix`
+     * heading with no subheading of its own — the workspace README's shape.
+     */
+    subheading: string | undefined;
+}
+
+/** Provides codependix's own Markdown anchor read/write mechanism. */
+export declare class AnchorsModule {
+}
+
+/**
+ * Reads and rewrites codependix's own named anchor blocks in a Markdown file.
+ *
+ * Owns its comment-marker syntax outright — a start marker and an end marker,
+ * each an HTML comment naming the anchor — with zero dependency on any
+ * `conformetry-*` package, per issue #242's decision that codependix must be
+ * able to evolve its export format without touching, or being constrained by,
+ * conformetry's template-conformance mechanism. See `anchors.constants.ts`
+ * for the exact marker text.
+ *
+ * `checkAnchor` and `replaceAnchorContent` still treat a missing anchor as an
+ * error — they are low-level primitives with no notion of where a new section
+ * would safely go. `insertAnchorSection` is the one place that risk is taken
+ * on deliberately: it only ever places a new section at one of two safe,
+ * well-defined spots — the end of the file, or the end of an existing
+ * `## 🕸️ Codependix` section — never anywhere else in a document someone else
+ * is authoring. `DeliveryService` is what decides when to reach for it.
+ */
+export declare class AnchorsService {
+    constructor();
+    /** Appends a brand-new `## 🕸️ Codependix` section to the end of a file. */
+    private appendCodependixSection;
+    /** Builds the pattern matching a named anchor block and its inner content. */
+    private buildAnchorPattern;
+    /** Escapes a string so it can be embedded literally in a regular expression. */
+    private escapeForPattern;
+    /**
+     * Inserts a new subsection at the end of an existing `## 🕸️ Codependix`
+     * section, before whatever heading comes next in the file (or at the end of
+     * the file, when the section is already the last thing in it).
+     */
+    private insertIntoCodependixSection;
+    /**
+     * Compares a Markdown file's anchor against a freshly computed export.
+     *
+     * `--check` reads this and reports drift without writing anything; `--write`
+     * is what acts on it. Throws `AnchorNotFoundError` when the anchor is
+     * missing, which is what fails a `--check` run against a project that never
+     * had the markers placed.
+     */
+    checkAnchor(args: AnchorLocationArguments & {
+        freshContent: string;
+    }): AnchorCheckResult;
+    /** Reads a named anchor's current content, or `undefined` when it is absent. */
+    extractAnchorContent(args: AnchorLocationArguments): string | undefined;
+    /** Whether a named anchor block is present in a file's content. */
+    hasAnchor(args: AnchorLocationArguments): boolean;
+    /**
+     * Auto-creates a missing anchor's `## 🕸️ Codependix` section.
+     *
+     * Called only when the caller has already confirmed the anchor is absent —
+     * this never checks that itself, and never touches an anchor that already
+     * exists. Two safe, well-defined outcomes only:
+     *
+     * - No `## 🕸️ Codependix` heading anywhere in the file: appends the heading,
+     *   `introLine`, the `### <subheading>` (when one is given), and the anchor
+     *   block to the end of the file.
+     * - A `## 🕸️ Codependix` heading already exists (from an earlier graph
+     *   type's write): inserts the new `### <subheading>` and anchor block at
+     *   the end of that section, before whatever heading comes next — never
+     *   duplicating the heading itself.
+     */
+    insertAnchorSection(args: AnchorSectionInsertArguments): string;
+    /**
+     * Replaces a named anchor's content in place, leaving the rest untouched.
+     *
+     * Idempotent: writing the same content twice produces byte-identical output,
+     * since the replacement is always rendered in the same canonical shape —
+     * marker, trimmed content, marker — regardless of what whitespace the
+     * anchor held before.
+     */
+    replaceAnchorContent(args: AnchorLocationArguments & {
+        newContent: string;
+    }): string;
+    /** Wraps content in a fresh pair of markers, for placing a new anchor by hand. */
+    wrapInAnchors(anchorName: string, content: string): string;
+}
+
+/** Builds the closing marker of a named anchor block. */
+export declare const buildEndMarker: (anchorName: string) => string;
+
+/**
+ * Message rendered when no connecting path exists between two nodes.
+ */
+export declare const buildNoPathMessage: (from: string, to: string) => string;
+
+/**
+ * Builds the opening marker of a named anchor block.
+ *
+ * codependix's own comment-marker syntax, independent of conformetry's marker
+ * mechanism by design — see issue #242. Named anchors let one Markdown file
+ * hold more than one block, such as an `nx` block today and an `nestjs` block
+ * once `codependix-nestjs-modules` ships, without the blocks colliding.
+ */
+export declare const buildStartMarker: (anchorName: string) => string;
+
+/**
+ * The single heading every project's (and the workspace's) auto-created
+ * Codependix section is placed under.
+ *
+ * Matched literally against a whole line, so a heading a human wrote by hand
+ * with this exact text is recognized and reused rather than duplicated — see
+ * `AnchorsService.insertAnchorSection`.
+ */
+export declare const CODEPENDIX_SECTION_HEADING = "## \uD83D\uDD78\uFE0F Codependix";
+
+/**
+ * One graph type's whole-workspace data, captured once per run for combined
+ * output — see `CombinedOutputService`.
+ *
+ * `json` is the same exported shape a workspace-level JSON destination would
+ * receive; `markdown` is the same rendered mermaid diagram a workspace-level
+ * Markdown destination would receive. Both are captured unconditionally,
+ * whether or not this run's configuration names a workspace destination for
+ * that graph type, so `--format`/`--json-output`/`--markdown-output` work
+ * even for a workspace that configured no destination of its own.
+ */
+export declare interface CombinedGraphEntry {
+    json: unknown;
+    markdown: string;
+}
+
+/**
+ * Every active graph type's whole-workspace data from one run, keyed by
+ * graph type — the structure `--json-output`/`--markdown-output`/`--format`
+ * read from. A type absent from this map was not active for the run — see
+ * `GraphRunContext.enabledGraphTypes`.
+ */
+export declare type CombinedGraphExports = Partial<Record<CodependixGraphType, CombinedGraphEntry>>;
+
+/**
+ * What `--format` prints, derived from the list it is validated against —
+ * see `FORMAT_NAMES`.
+ */
+export declare type CombinedOutputFormat = (typeof FORMAT_NAMES)[number];
+
+/** Provides the combined JSON/Markdown output and `--format` console pass. */
+export declare class CombinedOutputModule {
+}
+
+/** Arguments for producing every combined output a run asked for. */
+declare interface CombinedOutputRunArguments {
+    format: CombinedOutputFormat;
+    graphs: CombinedGraphExports;
+    jsonOutputPath: string | undefined;
+    markdownOutputPath: string | undefined;
+    workingDirectory: string;
+}
+
+/**
+ * Combines every active graph type's whole-workspace data into the single
+ * JSON object and single Markdown document `--json-output`,
+ * `--markdown-output`, and `--format` each read from, and delivers them.
+ *
+ * Kept apart from `DeliveryService`, which delivers one graph type's export
+ * to its own per-project or per-workspace destination: this service instead
+ * combines every active type's already-built data — see
+ * `GraphRunService.run` and `WorkspaceGraphsService` for where that data comes
+ * from — into one shared destination or one shared stdout write. Neither
+ * output is checked for staleness the way a per-project export is:
+ * `--json-output`/`--markdown-output` always write, matching
+ * `codometer-cli`'s own `--output-json`/`--output-markdown` precedent.
+ */
+export declare class CombinedOutputService {
+    private readonly anchorsService;
+    constructor(anchorsService: AnchorsService);
+    /** Prints whatever `--format` asked for. Never touches a file. */
+    private printConsole;
+    /** Builds the combined JSON object's content, keyed by graph type. */
+    private renderJson;
+    /** Builds the combined Markdown document's content from every active type. */
+    private renderMarkdown;
+    /** Writes a combined destination's content, creating its directory first. */
+    private writeFile;
+    /**
+     * Reads `--format` into what the run prints, falling back to
+     * `FORMAT_MARKDOWN` when the flag was left off entirely — codependix's
+     * configuration declares no `format` field of its own for this to read
+     * instead, unlike `codometer-cli`'s own `resolveFormat`.
+     */
+    resolveFormat(value: string | undefined): {
+        errors: string[];
+        format: CombinedOutputFormat;
+    };
+    /**
+     * Produces every combined output a run asked for: the console print
+     * `--format` always names, and the `--json-output`/`--markdown-output`
+     * files when their paths were given.
+     *
+     * A run naming no active graph type at all — every `--no-*` flag given —
+     * still prints and writes, with an empty object or an empty document: the
+     * flags are independent of which graph types are active, exactly as
+     * `--check`/`--write` are.
+     */
+    run(args: CombinedOutputRunArguments): void;
+}
+
+/** Every active graph type's path query outcome, keyed by type. */
+export declare type CombinedPathResults = Partial<Record<CodependixGraphType, PathQueryResult>>;
+
+/**
+ * Arguments for delivering one project's (or the workspace's) resolved
+ * export configuration.
+ *
+ * `jsonContent`/`markdownContent` are rendered by the caller — every graph
+ * type renders its own JSON shape and its own diagram — and are only read
+ * when the resolved output actually touches that destination, so a caller
+ * whose target is `"markdown"` never has to render JSON it will not deliver.
+ */
+declare interface DeliverGraphOutputArguments {
+    jsonContent: string | undefined;
+    markdownContent: string | undefined;
+    /**
+     * The heading text used to auto-create a missing anchor's section on write.
+     *
+     * `undefined` for a standalone (non-anchored) Markdown destination, which
+     * has no section to create. Required whenever the destination is anchored
+     * and might need auto-creation — see `DeliveryService.deliverAnchoredMarkdown`.
+     */
+    markdownSection: MarkdownSectionArguments | undefined;
+    mode: CodependixRunMode;
+    project: DeliveryProject;
+    resolvedOutput: ResolvedCodependixGraphOutput;
+}
+
+/** Provides the generic graph-export delivery mechanism every graph type uses. */
+export declare class DeliveryModule {
+}
+
+/** The project (or workspace) a graph export is delivered relative to. */
+declare interface DeliveryProject {
+    absoluteRoot: string;
+    name: string;
+}
+
+/**
+ * Delivers a resolved graph export to whichever destinations it names.
+ *
+ * Every codependix graph type — the Nx Neighborhood, the Nx Workspace Graph,
+ * and the NestJS module graph — resolves to the same
+ * `ResolvedCodependixGraphOutput` shape and is delivered the same way: a JSON
+ * file, an anchored or standalone Markdown file, or both. This service is
+ * the one place that shape is turned into file I/O, so `GraphRunService`
+ * only has to render each graph type's own JSON and diagram content and hand
+ * it over.
+ */
+export declare class DeliveryService {
+    private readonly anchorsService;
+    constructor(anchorsService: AnchorsService);
+    /**
+     * Checks whether a named anchor block is current against fresh content.
+     *
+     * A missing anchor is reported as stale rather than throwing, consistent
+     * with every other kind of drift this tool reports.
+     */
+    private checkAnchoredMarkdown;
+    /** Classifies whether a difference is formatting or graph structure. */
+    private classifyDifference;
+    /** Delivers a JSON destination, recording it as stale if needed. */
+    private deliverJson;
+    /** Delivers a Markdown destination, recording it as stale if needed. */
+    private deliverMarkdown;
+    /** Reads a file's content, or an empty string when it does not exist yet. */
+    private readFileOrEmpty;
+    /**
+     * Resolves the JSON destination a graph output should deliver to, or
+     * `undefined` when the target does not touch JSON, no destination was
+     * configured, or the caller rendered no JSON content for it.
+     */
+    private resolveJsonDelivery;
+    /**
+     * Resolves the Markdown destination a graph output should deliver to, or
+     * `undefined` when the target does not touch Markdown, no destination was
+     * configured, or the caller rendered no diagram content for it.
+     */
+    private resolveMarkdownDelivery;
+    /** Splices content into a named anchor block on write. */
+    private writeAnchoredMarkdown;
+    /**
+     * Auto-creates a missing anchor's `## 🕸️ Codependix` section and writes it.
+     *
+     * Falls back to the historical hard failure when the caller supplied no
+     * `markdownSection` — there is nothing safe to build without a heading and
+     * intro line, and `GraphRunService` always supplies one for every real
+     * anchored destination it delivers.
+     */
+    private writeAutoCreatedAnchorSection;
+    /**
+     * Delivers whichever destinations a resolved graph output names.
+     *
+     * `jsonContent`/`markdownContent` are read only when the resolved target
+     * actually touches that destination, mirroring how a project whose target
+     * is `"json"` never renders a diagram nobody configured.
+     */
+    deliverGraphOutput(args: DeliverGraphOutputArguments): ProjectRunResult;
+    /** Renders an export as JSON the same way every run of codependix would. */
+    renderJson(exportedGraph: unknown): string;
+}
+
+/** What `--format json` prints: every active graph type's data, keyed by type. */
+export declare const FORMAT_JSON = "json";
+
+/**
+ * What `--format markdown` prints: every active graph type's rendered
+ * diagram. Also what `--format` prints when the flag is left off entirely —
+ * unlike codometer, whose fallback reads a resolved configuration field,
+ * codependix's configuration declares no `format` field of its own, so the
+ * default is this same fixed constant instead of a second one aliasing it.
+ */
+export declare const FORMAT_MARKDOWN = "markdown";
+
+/** What `--format mermaid` prints: each active graph type rendered as a mermaid flowchart. */
+export declare const FORMAT_MERMAID = "mermaid";
+
+/**
+ * Everything `--format` accepts, in the order an error message lists them.
+ *
+ * A tuple rather than a bare union: `MapCommand.parseFormat` validates
+ * against this array directly, so a format added here is accepted everywhere
+ * the moment it is rendered — mirroring `codometer-cli`'s own `FORMAT_NAMES`.
+ */
+export declare const FORMAT_NAMES: readonly ["json", "markdown"];
+
+/** Wires every graph-type export pass together behind one orchestrator. */
+export declare class GraphRunModule {
+}
+
+/**
+ * Orchestrates every configured graph export, one pass per graph type.
+ *
+ * Owns none of the per-project or per-workspace rendering itself:
+ * `ProjectGraphsService` builds, renders, and delivers each included
+ * project's own graph, and `WorkspaceGraphsService` does the same for each
+ * type's whole-workspace graph. This service's own job is deciding which
+ * types are active, running both passes for each, combining their outcomes,
+ * and collecting each active type's whole-workspace data into a
+ * `CombinedGraphExports` map — for `CombinedOutputService` to print and
+ * write, see `MapCommand`.
+ *
+ * Every pass isolates one project's failure from the rest: a missing anchor
+ * or a NestJS project that fails to boot its container is collected as a
+ * `ProjectRunFailure` rather than aborting the loop.
+ */
+export declare class GraphRunService {
+    private readonly logger;
+    private readonly neighborhoodService;
+    private readonly projectGraphsService;
+    private readonly pythonImportsService;
+    private readonly workspaceGraphsService;
+    constructor(logger: LoggerService, neighborhoodService: NeighborhoodService, projectGraphsService: ProjectGraphsService, pythonImportsService: PythonImportsService, workspaceGraphsService: WorkspaceGraphsService);
+    /**
+     * Collects every active graph type's whole-workspace data into the map
+     * `CombinedOutputService` reads from, dropping a type this run built no
+     * whole-workspace graph for at all — see `GraphTypePassOutcome`.
+     */
+    private collectCombinedGraphs;
+    /** Turns a raised error into a `ProjectRunFailure` for the given project. */
+    private collectProjectFailure;
+    /**
+     * Runs one synchronous whole-workspace graph builder, pushes its delivery
+     * outcome when it produced one, and returns its combined-output entry.
+     *
+     * Shared by `runNxGraphs` and `runImportGraphs`, whose own
+     * `WorkspaceGraphsService` calls are both synchronous;
+     * `runNestjsGraphs`'s own call is asynchronous and keeps its own inline
+     * `try`/`catch` rather than sharing this one.
+     */
+    private collectWorkspaceOutcome;
+    /**
+     * Runs every configured graph export against an already-resolved context.
+     *
+     * Every pass is attempted regardless of an earlier failure: the four graph
+     * types are independent. A type `context.enabledGraphTypes` excludes is
+     * skipped entirely, so `--no-nestjs-modules` never boots a container. Also
+     * returns `combinedGraphs` — every active type's whole-workspace data,
+     * collected for `MapCommand` to hand to `CombinedOutputService`.
+     */
+    run(context: GraphRunContext): Promise<MapRunResult>;
+    /**
+     * Builds and delivers every configured file-level import graph export —
+     * each included project's own graph, from `ProjectGraphsService`, and the
+     * whole-workspace file-imports graph `WorkspaceGraphsService` combines
+     * from every TypeScript and Python project.
+     */
+    runImportGraphs(context: GraphRunContext): GraphTypePassOutcome;
+    /**
+     * Builds and delivers every configured NestJS module graph export — each
+     * included project's own graph, from `ProjectGraphsService`, and the
+     * whole-workspace NestJS module graph `WorkspaceGraphsService` combines
+     * from every NestJS project.
+     */
+    runNestjsGraphs(context: GraphRunContext): Promise<GraphTypePassOutcome>;
+    /**
+     * Builds and delivers every configured Nx graph export — each included
+     * project's Neighborhood, from `ProjectGraphsService`, and the
+     * whole-workspace Workspace Graph, from `WorkspaceGraphsService`.
+     */
+    runNxGraphs(context: GraphRunContext): GraphTypePassOutcome;
+    /**
+     * Builds and delivers every configured Python file-level import graph
+     * export.
+     *
+     * Delegates to `PythonImportsService`. Reports no whole-workspace data of
+     * its own: the Python graphs it builds are already folded into the
+     * `fileImports` combined entry `runImportGraphs` reports — see
+     * `WorkspaceGraphsService.runFileImportsWorkspaceGraph`.
+     */
+    runPythonImportGraphs(context: GraphRunContext): GraphRunOutcome;
+}
+
+/**
+ * One graph-type pass's outcome: the usual per-project delivery outcome,
+ * plus this type's whole-workspace data for combined output.
+ *
+ * `workspaceEntry` is `undefined` both when the pass built no whole-workspace
+ * graph of its own (`fileImports`'s Python pass, folded into the TypeScript
+ * pass's own `fileImports` entry — see `GraphRunService.runImportGraphs`) and
+ * when the one it owns resolved to a `"none"` target — see
+ * `WorkspaceGraphsService`.
+ */
+declare interface GraphTypePassOutcome extends GraphRunOutcome {
+    workspaceEntry: CombinedGraphEntry | undefined;
+}
+
+/**
+ * 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,
+        );
+    }
+}
+
+/**
+ * What `GraphRunService.run` resolves: the usual delivery outcome, and every
+ * active graph type's whole-workspace data for combined output — see
+ * `CombinedGraphExports`.
+ */
+export declare interface MapRunResult {
+    combinedGraphs: CombinedGraphExports;
+    outcome: GraphRunOutcome;
+}
+
+/**
+ * The intro line placed under a newly auto-created `## 🕸️ Codependix`
+ * heading — copied verbatim from the wording a human already placed by hand
+ * in `packages/logger/README.md`, so an auto-created section reads exactly
+ * like one a person wrote.
+ */
+export declare const MARKDOWN_SECTION_INTRO_LINE = "Dependency graphs exported by [codependix](https://github.com/Organizzolini/codebase/tree/main/packages/ic-suite/codependix/codependix-cli), regenerated by `nx run codebase:codependix:write`.";
+
+/**
+ * The JSON shape a single project's NestJS module graph export is written as.
+ *
+ * Identical in shape to `NestjsModuleGraph` itself — kept as its own named
+ * type so the export's JSON shape can evolve independently of
+ * `codependix-nestjs-modules`'s internal representation, the same reasoning
+ * `NxWorkspaceGraphExport` follows for the Nx Workspace Graph.
+ */
+export declare type NestjsModuleGraphExport = NestjsModuleGraph;
+
+/** The JSON shape a single project's Nx neighborhood export is written as. */
+export declare interface NxNeighborhoodExport {
+    dependencies: string[];
+    dependents: string[];
+    edges: Neighborhood["edges"];
+    projectName: string;
+}
+
+/**
+ * The JSON shape the whole-workspace Nx Workspace Graph export is written as.
+ *
+ * Identical in shape to `WorkspaceGraph` itself — no extra field is added the
+ * way `NxNeighborhoodExport` adds none beyond `Neighborhood` either — kept as
+ * its own named type so the export's JSON shape can evolve independently of
+ * `codependix-nx-projects`'s internal `WorkspaceGraph` representation.
+ */
+export declare type NxWorkspaceGraphExport = WorkspaceGraph;
+
+/** A message split into the emoji the console shows and the prose telemetry stores. */
+declare interface ParsedLogMessage {
+    emoji: string | undefined;
+    text: string;
+}
+
+/** Arrow connecting successive nodes in a Markdown path. */
+export declare const PATH_ARROW = " \u2192 ";
+
+/** Formats accepted by the path command's `--format` flag. */
+export declare const PATH_FORMAT_NAMES: readonly ["json", "markdown", "mermaid"];
+
+/** Header declaring the mermaid diagram type for path rendering. */
+export declare const PATH_MERMAID_HEADER = "graph LR";
+
+/** What `--format` prints for a path query. */
+export declare type PathFormat = (typeof PATH_FORMAT_NAMES)[number];
+
+/** Arguments for executing a path query. */
+export declare interface PathQueryArguments {
+    context: GraphRunContext;
+    from: string;
+    to: string;
+}
+
+/** Provides path query and rendering services across graph levels. */
+export declare class PathQueryModule {
+}
+
+/** The outcome of querying a connecting path for one graph type. */
+export declare interface PathQueryResult {
+    from: string;
+    path: null | string[];
+    to: string;
+}
+
+/**
+ * Searches for connecting paths between two nodes in codependix graphs and renders results.
+ */
+export declare class PathQueryService {
+    private readonly fileImportsWorkspaceGraphService;
+    private readonly moduleGraphService;
+    private readonly nestjsModulesWorkspaceGraphService;
+    private readonly nestjsProjectService;
+    private readonly pythonService;
+    private readonly typescriptService;
+    private readonly workspaceGraphService;
+    constructor(fileImportsWorkspaceGraphService: FileImportsWorkspaceGraphService, moduleGraphService: ModuleGraphService, nestjsModulesWorkspaceGraphService: NestjsModulesWorkspaceGraphService, nestjsProjectService: NestjsProjectService, pythonService: PythonService, typescriptService: TypescriptService, workspaceGraphService: WorkspaceGraphService);
+    /** Builds an adjacency map from directed edges with sorted targets. */
+    private buildAdjacency;
+    /**
+     * Explores and builds every discovered NestJS project's module graph.
+     */
+    private buildNestjsModuleGraphs;
+    /** Checks whether a node is present in the graph's node list or edges. */
+    private isKnownNode;
+    /** Queries the file-imports workspace graph for a path between two files. */
+    private queryFileImports;
+    /** Queries the NestJS modules workspace graph for a path between two modules. */
+    private queryNestjsModules;
+    /** Queries the Nx project graph for a path between two projects. */
+    private queryNxProjects;
+    /** Renders every active graph type's path as Markdown text. */
+    private renderMarkdown;
+    /** Renders every active graph type's path as a Mermaid diagram. */
+    private renderMermaid;
+    /** Renders a single path entry as a Mermaid diagram block or no-path message. */
+    private renderMermaidSection;
+    /** Runs deterministic breadth-first search to find the shortest path. */
+    private searchBfs;
+    /** Converts a node name to a safe Mermaid identifier. */
+    private toMermaidId;
+    /**
+     * Finds the shortest directed path between two nodes in a given edge set.
+     */
+    findShortestPath(args: {
+        edges: readonly {
+            source: string;
+            target: string;
+        }[];
+        from: string;
+        nodes?: readonly string[] | undefined;
+        to: string;
+    }): null | string[];
+    /**
+     * Queries every enabled graph type for a connecting path between two nodes.
+     */
+    query(args: PathQueryArguments): Promise<CombinedPathResults>;
+    /** Renders combined path query results according to the selected format. */
+    render(args: PathReportArguments): string;
+    /**
+     * Reads `--format` into what the run prints, falling back to
+     * `FORMAT_MARKDOWN` when the flag was left off entirely.
+     */
+    resolveFormat(value: string | undefined): {
+        errors: string[];
+        format: PathFormat;
+    };
+}
+
+/** Arguments for rendering path query results. */
+export declare interface PathReportArguments {
+    format: PathFormat;
+    results: CombinedPathResults;
+}
+
+/**
+ * Builds, renders, and delivers every included project's own graph, for
+ * each of the three graph types — the Nx Neighborhood, the TypeScript/Python
+ * file-level import graph, and the NestJS module graph.
+ *
+ * Split out of `GraphRunService`, which keeps only orchestration — resolving the
+ * context once, deciding which graph types are active, and combining this
+ * service's per-project outcome with `WorkspaceGraphsService`'s own
+ * whole-workspace one — purely to stay under this repository's per-file line
+ * limit. Every method here isolates one project's failure from the rest: a
+ * missing anchor or a NestJS project that fails to boot its container is
+ * collected as a `ProjectRunFailure` rather than aborting the loop.
+ */
+declare class ProjectGraphsService {
+    private readonly configurationService;
+    private readonly deliveryService;
+    private readonly moduleGraphService;
+    private readonly neighborhoodService;
+    private readonly nestjsProjectService;
+    private readonly typescriptService;
+    constructor(configurationService: ConfigurationService, deliveryService: DeliveryService, moduleGraphService: ModuleGraphService, neighborhoodService: NeighborhoodService, nestjsProjectService: NestjsProjectService, typescriptService: TypescriptService);
+    /**
+     * Builds the section heading a graph type's anchored Markdown destination
+     * auto-creates when it is missing.
+     */
+    private buildMarkdownSection;
+    /** Turns a neighborhood into the JSON shape it is exported as. */
+    private buildNeighborhoodJsonExport;
+    /** Turns a raised error into a `ProjectRunFailure` for the given project. */
+    private collectProjectFailure;
+    /** Resolves one project's export target for a graph type, carrying its root/tags. */
+    private resolveProjectOutput;
+    /** Builds, renders, and delivers one project's file-level import Graph. */
+    private runImportProject;
+    /** Explores, renders, and delivers one NestJS project's module graph. */
+    private runNestjsProject;
+    /** Renders and delivers one project's Nx Neighborhood. */
+    private runNxProject;
+    /** Builds, renders, and delivers every included TypeScript project's own file-level import graph. */
+    runFileImportsProjects(context: GraphRunContext): GraphRunOutcome;
+    /** Explores, builds, renders, and delivers every included NestJS project's own module graph. */
+    runNestjsModulesProjects(context: GraphRunContext): Promise<GraphRunOutcome>;
+    /** Renders and delivers every included project's own Nx Neighborhood. */
+    runNxProjectsGraphs(args: {
+        context: GraphRunContext;
+        neighborhoods: Map<string, Neighborhood>;
+    }): GraphRunOutcome;
+}
+
+/**
+ * Builds and delivers every configured Python file-level import graph
+ * export.
+ *
+ * Split out of `GraphRunService` — which owns the same pass for every
+ * other graph type — purely to keep that file under this repository's
+ * per-file line limit; the pass itself follows
+ * `GraphRunService.runImportGraphs` exactly, one collaborator per language
+ * instead of one compiler-backed `ts.Program` per project.
+ */
+declare class PythonImportsService {
+    private readonly configurationService;
+    private readonly deliveryService;
+    private readonly pythonService;
+    constructor(configurationService: ConfigurationService, deliveryService: DeliveryService, pythonService: PythonService);
+    /** Builds the section heading a missing anchor auto-creates. */
+    private buildMarkdownSection;
+    /** Turns a raised error into a `ProjectRunFailure` for the given project. */
+    private collectProjectFailure;
+    /**
+     * Resolves one project's export target for this graph type, including its
+     * workspace-relative root and its Nx tags, so `include`/`exclude` globs may
+     * match either and `--tags` reaches the tags — the same resolution
+     * `GraphRunService.resolveProjectOutput` performs for every other graph type.
+     */
+    private resolveProjectOutput;
+    /** Builds, renders, and delivers one project's Python import graph. */
+    private runProject;
+    /**
+     * Builds and delivers every configured Python file-level import graph
+     * export.
+     *
+     * Only `language:python`-tagged projects participate, discovered from the
+     * tags `context.projects` carry — see `PythonService`. A project that
+     * raises while its own export is being resolved is recorded as a failure
+     * rather than aborting the pass, the same rule `runImportGraphs` follows.
+     */
+    runGraphs(context: GraphRunContext): GraphRunOutcome;
+}
+
+/** Provides `MapCommand`'s findings-logging and pass/fail-weighing pass. */
+export declare class ReportingModule {
+}
+
+/**
+ * Logs what `MapCommand`'s passes found, and decides whether each pass
+ * should fail the run.
+ *
+ * Split out of `MapCommand` purely to keep that file under this
+ * repository's per-file line limit: reporting a pass's own findings is a
+ * concern of its own, separate from resolving the command line into a mode
+ * and orchestrating the passes themselves.
+ */
+export declare class ReportingService {
+    private readonly boundaryReportService;
+    private readonly logger;
+    constructor(boundaryReportService: BoundaryReportService, logger: LoggerService);
+    /**
+     * Logs a boundary pass's violations and failures, and reports whether the
+     * run as a whole should fail.
+     *
+     * Violations go to the console and the exit code and nowhere else: a list of
+     * things currently wrong is not a document worth publishing on the default
+     * branch, and not one worth checking for staleness either.
+     */
+    reportBoundaries(outcome: BoundaryCheckOutcome): boolean;
+    /**
+     * Warns when nothing in the configuration selects a single project.
+     *
+     * `include` defaults to nothing, so a configuration naming only `defaults`
+     * exports for no project at all — a run that writes nothing and still exits
+     * zero. Nothing else catches it: `--check boundaries` judges every project
+     * regardless of `include`, so a workspace whose exports have gone silent
+     * still has a green gate.
+     */
+    reportEmptySelection(projectCount: number): void;
+    /**
+     * Logs why a run ended before it started, and fails it.
+     *
+     * A command line the input service refused — two modes named, none named
+     * with no terminal to ask at, or a question walked away from — is reported
+     * as a rejected command line rather than as a crash. Nothing was
+     * attempted, and the reader's next move is to retype the flags, not to
+     * read a stack trace.
+     */
+    reportFailure(error: unknown): void;
+    /**
+     * Logs an outcome's failures and stale exports, and reports whether the run
+     * as a whole should fail.
+     *
+     * Both are reported together rather than the first one short-circuiting the
+     * other, since `GraphRunService.run` already attempted every project
+     * regardless of an earlier one's failure.
+     */
+    reportOutcome(outcome: GraphRunOutcome): boolean;
+    /**
+     * Weighs what each pass that ran found, reporting neither over the other.
+     *
+     * Both are weighed independently rather than the first failure
+     * short-circuiting the second: a run gating both should report both, not
+     * only the one that happened to run first.
+     */
+    reportPassOutcomes(args: {
+        boundaryOutcome: BoundaryCheckOutcome | undefined;
+        exportRun: MapRunResult | undefined;
+    }): boolean;
+    /** Logs what each pass that ran verified, and nothing for one that did not. */
+    reportSuccess(args: {
+        boundaryOutcome: BoundaryCheckOutcome | undefined;
+        exportOutcome: GraphRunOutcome | undefined;
+    }): void;
+}
+
+/** One whole-workspace graph pass's outcome. */
+declare interface WorkspaceGraphRunOutcome {
+    /**
+     * The graph's own data, for combined output — always populated when the
+     * resolved workspace target is not `"none"`, regardless of whether that
+     * target actually touches Markdown, so `--format`/`--json-output`/
+     * `--markdown-output` can read a rendered diagram this run never wrote to a
+     * configured destination.
+     */
+    entry: CombinedGraphEntry | undefined;
+    /** The delivery outcome, or `undefined` when nothing was configured to deliver. */
+    result: ProjectRunResult | undefined;
+}
+
+/**
+ * Builds and delivers every whole-workspace graph: the Nx Workspace Graph,
+ * the file-imports graph (every TypeScript and Python project's own import
+ * graph, combined), and the NestJS module graph (every NestJS project's own
+ * module graph, combined).
+ *
+ * Split out of `GraphRunService` purely to keep that file under this
+ * repository's per-file line limit — `GraphRunService` still owns every
+ * per-project pass, and hands the whole-workspace pass for each active
+ * graph type over to this service instead of building it inline.
+ *
+ * Each `run*WorkspaceGraph` method also hands back the graph's own rendered
+ * data alongside its delivery outcome — see `WorkspaceGraphRunOutcome` — so
+ * `GraphRunService.run` can collect it for combined output without building the
+ * same graph a second time.
+ */
+declare class WorkspaceGraphsService {
+    private readonly configurationService;
+    private readonly deliveryService;
+    private readonly fileImportsWorkspaceGraphService;
+    private readonly moduleGraphService;
+    private readonly nestjsModulesWorkspaceGraphService;
+    private readonly nestjsProjectService;
+    private readonly pythonService;
+    private readonly typescriptService;
+    private readonly workspaceGraphService;
+    constructor(configurationService: ConfigurationService, deliveryService: DeliveryService, fileImportsWorkspaceGraphService: FileImportsWorkspaceGraphService, moduleGraphService: ModuleGraphService, nestjsModulesWorkspaceGraphService: NestjsModulesWorkspaceGraphService, nestjsProjectService: NestjsProjectService, pythonService: PythonService, typescriptService: TypescriptService, workspaceGraphService: WorkspaceGraphService);
+    /** Builds the section heading a graph type's anchored Markdown destination auto-creates when it is missing. */
+    private buildMarkdownSection;
+    /**
+     * Explores and builds every discovered NestJS project's own module graph.
+     *
+     * Kept apart from `runNestjsModulesWorkspaceGraph` so that method's own
+     * direct callees stay under this repository's callidescope breadth limit.
+     */
+    private buildNestjsModuleGraphs;
+    /**
+     * Builds every discovered TypeScript project's own file-level import graph.
+     *
+     * Kept apart from `runFileImportsWorkspaceGraph` for the same breadth
+     * reason `buildNestjsModuleGraphs` is.
+     */
+    private buildTypescriptGraphs;
+    /**
+     * Delivers one already-built whole-workspace graph's configured
+     * destinations, at the workspace root.
+     *
+     * The one place both `runFileImportsWorkspaceGraph` and
+     * `runNestjsModulesWorkspaceGraph` hand off to `DeliveryService`, so
+     * neither of them carries `DeliveryService`'s own three-call shape as
+     * direct callees of its own.
+     */
+    private deliverWorkspaceGraph;
+    /**
+     * Builds, renders, and delivers the whole-workspace file-level import
+     * graph's configured destinations.
+     *
+     * Built from every discovered TypeScript and Python project's own import
+     * graph, combined by `FileImportsWorkspaceGraphService` — the same "read
+     * once, draw over the selected projects" shape `runNxWorkspaceGraph`
+     * follows for the Nx Workspace Graph, applied to the two file-level import
+     * builders instead of one Nx project graph read.
+     *
+     * The graph is not built at all when the resolved workspace target is
+     * `"none"` — a workspace that never configured this destination pays
+     * nothing for it, matching the target-gated shape every other pass here
+     * follows. Combined output is unavailable for this type in that case too.
+     */
+    runFileImportsWorkspaceGraph(context: GraphRunContext): WorkspaceGraphRunOutcome;
+    /**
+     * Explores, builds, renders, and delivers the whole-workspace NestJS
+     * module graph's configured destinations.
+     *
+     * Built from every discovered NestJS project's own module graph, combined
+     * by `NestjsModulesWorkspaceGraphService` — the same shape
+     * `runFileImportsWorkspaceGraph` follows, applied to booting every NestJS
+     * project's container instead of building a `ts.Program` or parsing
+     * Python source. Skipped entirely when the resolved target is `"none"`,
+     * for the same reason `runFileImportsWorkspaceGraph` skips its own build.
+     */
+    runNestjsModulesWorkspaceGraph(context: GraphRunContext): Promise<WorkspaceGraphRunOutcome>;
+    /**
+     * Renders and delivers the Nx Workspace Graph's configured destinations.
+     *
+     * Built from the already-read Nx project graph — no discovery pass of its
+     * own, unlike the other two whole-workspace graphs, since `GraphRunService`
+     * already read it once for the whole run. Skipped entirely when the
+     * resolved target is `"none"`, for the same reason
+     * `runFileImportsWorkspaceGraph` skips its own build.
+     */
+    runNxWorkspaceGraph(context: GraphRunContext): WorkspaceGraphRunOutcome;
+}
+
+export { }