@codependix/boundaries 0.0.3

package/dist/src/index.d.ts

@@ -0,0 +1,736 @@
+import { CodependixBoundaryRule } from '@codependix/configuration';
+import { CodependixBoundarySelector } from '@codependix/configuration';
+import { CodependixGraphType } from '@codependix/configuration';
+import { CodependixProjectConfiguration } from '@codependix/configuration';
+import { CodependixRunMode } from '@codependix/core';
+import { ConfigurationService } from '@codependix/configuration';
+import { MapCommandOptions } from '@codependix/configuration';
+import { ModuleGraphService } from '@codependix/nestjs-modules';
+import { NeighborhoodService } from '@codependix/nx-projects';
+import { NestjsModuleGraph } from '@codependix/nestjs-modules';
+import { NestjsProjectService } from '@codependix/nestjs-modules';
+import { NxProject } from '@codependix/nx-projects';
+import { NxProjectGraph } from '@codependix/nx-projects';
+import { PythonImportGraph } from '@codependix/file-imports';
+import { PythonService } from '@codependix/file-imports';
+import { ResolvedCodependixConfiguration } from '@codependix/configuration';
+import { TypescriptImportGraph } from '@codependix/file-imports';
+import { TypescriptService } from '@codependix/file-imports';
+import { WorkspaceGraph } from '@codependix/nx-projects';
+import { WorkspaceGraphService } from '@codependix/nx-projects';
+
+/** Wires rule evaluation together with selection, cycle finding, and reporting. */
+export declare class BoundariesModule {
+}
+
+/**
+ * Judges a built graph against the rules declared for its level.
+ *
+ * The whole package's public act: a `BoundaryGraph` and a list of rules go in,
+ * and the edges and cycles that break them come out. Nothing here knows how a
+ * graph was built, where a rule was written, or what a caller will do with a
+ * violation — which is what keeps the package a leaf, depending on nothing but
+ * `@codependix/configuration` for the rule shapes it reads.
+ *
+ * A rule that matches nothing is not an error. It reports no violation, the
+ * same as a rule everything satisfies: a workspace that has not yet grown the
+ * code a rule was written for should not be failed for it, and a rule kept
+ * around after the code it covered was deleted is a cleanup rather than a
+ * breakage.
+ */
+export declare class BoundariesService {
+    private readonly cyclesService;
+    private readonly selectorService;
+    constructor(cyclesService: BoundaryCyclesService, selectorService: BoundarySelectorService);
+    /** Turns one condemned edge into the violation reported for it. */
+    private buildAccessViolation;
+    /**
+     * The sentence a violation is reported as.
+     *
+     * A rule's own `message` is appended to the generated one rather than
+     * replacing it, so no wording a configuration can choose ever costs the
+     * report the two things it must always carry: the rule that fired, and both
+     * ends of what it fired on. The generated half says what happened, and the
+     * configured half says why it matters.
+     */
+    private buildMessage;
+    /**
+     * Reports every edge an `allow` or `forbid` rule condemns.
+     *
+     * The two kinds differ only in which verdict the target's match produces,
+     * so they are one traversal rather than two: `forbid` condemns an edge
+     * reaching what `to` claims, and `allow` condemns one reaching anything it
+     * does not.
+     */
+    private evaluateAccessRule;
+    /** Reports every cycle an `acyclic` rule's selected nodes still form. */
+    private evaluateAcyclicRule;
+    /** Indexes a graph's nodes by identifier, so an edge can look its ends up. */
+    private indexNodes;
+    /**
+     * Whether a rule judges this edge at all, before either end is selected.
+     *
+     * A rule naming no `edges` judges every one, which is the stricter reading
+     * and the right default for a rule about what a project may _depend on_.
+     * Naming `implicit: false` narrows it to what an
+     * `@nx/enforce-module-boundaries` `depConstraint` actually sees — that rule
+     * reads import statements, so an `implicitDependencies` entry is invisible
+     * to it. An edge at a level that draws no implicit edges is read as
+     * explicit, since a file import is not "explicitly" anything.
+     */
+    private judgesEdge;
+    /**
+     * The node an edge names, or a bare one carrying only that identifier.
+     *
+     * An edge naming a node the graph does not list is judged on its identifier
+     * alone rather than skipped: silently dropping the edge would hide the rule
+     * rather than the mistake. The consequence is that a `path`, `project`, or
+     * `tags` selector cannot match such an endpoint, since a bare node carries
+     * none of them — so a `forbid` written against `path` reports nothing for
+     * it, which is the safer of the two wrong answers.
+     *
+     * Every real builder lists both ends of every edge it draws — an import
+     * graph only draws edges between files in its own `fileNames`, and the Nx
+     * and NestJS graphs both list every node they connect — so this is reached
+     * only by a hand-written graph.
+     */
+    private resolveNode;
+    /**
+     * Every violation one graph's rules report, in the order the rules were
+     * declared.
+     *
+     * Declaration order rather than severity or node order: a configuration's
+     * author reads their own file top to bottom, and a report ordered the same
+     * way needs no key.
+     */
+    evaluate(args: EvaluateBoundariesArguments): BoundaryViolation[];
+}
+
+/**
+ * The order the four graph levels are judged in.
+ *
+ * Cheapest first, and it is not a small difference: the Nx level reads a graph
+ * the run already holds, while the NestJS level boots every container in
+ * preview mode and the TypeScript level builds a `ts.Program` per project. A
+ * workspace declaring only Nx rules never pays for either, because a level
+ * with no rules is not built at all.
+ *
+ * Written as a list rather than left implicit in the order of four `if`
+ * blocks, so the order a report comes out in is stated once, in the place a
+ * reader looks for it. `typescript` and `python` are `boundaries.fileImports`'s
+ * two nested languages, judged as separate levels here even though
+ * `codependix-file-imports` builds and exports them as one merged graph type.
+ */
+export declare const BOUNDARY_LEVEL_ORDER: readonly ["nxProjects", "nestjsModules", "typescript", "python"];
+
+/**
+ * Everything a boundary check reads about the workspace it is judging.
+ *
+ * Stated apart from `GraphRunContext` — the wider run context this package
+ * also owns, which carries an export mode the gate never reads — so a caller
+ * that only judges boundaries never has to name an export mode it has none
+ * of. `GraphRunContext` is structurally assignable to this, so nothing has to
+ * be repacked at the call site.
+ */
+export declare interface BoundaryCheckContext {
+    readonly configuration: ResolvedCodependixConfiguration;
+    /**
+     * The graph types this run judges.
+     *
+     * Read by `BoundaryCheckService.run` to skip every level under a disabled
+     * graph type before a single graph is built — see
+     * `RunContextService.resolveEnabledGraphTypes`, which is where a run
+     * resolves this from `--no-file-imports`, `--no-nestjs-modules`, and
+     * `--no-nx-projects`.
+     */
+    readonly enabledGraphTypes: ReadonlySet<CodependixGraphType>;
+    readonly graph: NxProjectGraph;
+    /** Every project the graph knows, apart from the workspace root. */
+    readonly projects: NxProject[];
+    /**
+     * The projects the run was narrowed to, which is what every level judges.
+     *
+     * Identical to `projects` unless `--projects` or `--tags` named a
+     * selection, so the gate judges the whole workspace by default and a
+     * narrowed run is something the command line asked for explicitly.
+     */
+    readonly selectedProjects: NxProject[];
+    readonly workingDirectory: string;
+}
+
+/** One project whose graph could not be built, and why. */
+export declare interface BoundaryCheckFailure {
+    readonly error: string;
+    readonly projectName: string;
+}
+
+/** Wires rule evaluation together with the four graph builders it judges. */
+export declare class BoundaryCheckModule {
+}
+
+/**
+ * What one `--check boundaries` pass found.
+ *
+ * Failures are carried beside violations rather than thrown, for the same
+ * reason every export pass carries them: a NestJS project that cannot boot
+ * its container says nothing about whether the other thirty-six break a rule,
+ * and a run that abandoned the rest would report a smaller problem than it
+ * has.
+ */
+export declare interface BoundaryCheckOutcome {
+    readonly failures: BoundaryCheckFailure[];
+    readonly violations: BoundaryViolation[];
+}
+
+/**
+ * Judges every level's graph against the rules declared for it.
+ *
+ * A level whose rule list is empty is never built at all, which is what makes
+ * the gate affordable: judging the NestJS level means booting every
+ * `framework:nestjs` container in preview mode, and judging the TypeScript
+ * level means building a `ts.Program` per project. A workspace declaring only
+ * Nx rules pays for neither.
+ *
+ * Nothing here writes or reads a destination. A violation goes to the console
+ * and the exit code, so `--check boundaries` leaves every committed export
+ * exactly as it found it — the property that lets it gate a branch, where the
+ * exports are expected to be behind the workspace they describe.
+ */
+export declare class BoundaryCheckService {
+    private readonly boundariesService;
+    private readonly boundaryGraphService;
+    private readonly moduleGraphService;
+    private readonly nestjsProjectService;
+    private readonly pythonService;
+    private readonly typescriptService;
+    private readonly workspaceGraphService;
+    constructor(boundariesService: BoundariesService, boundaryGraphService: BoundaryGraphService, moduleGraphService: ModuleGraphService, nestjsProjectService: NestjsProjectService, pythonService: PythonService, typescriptService: TypescriptService, workspaceGraphService: WorkspaceGraphService);
+    /** Turns a raised error into a `BoundaryCheckFailure` for the given project. */
+    private collectProjectFailure;
+    /**
+     * The `CodependixGraphType` each boundary level is judged under.
+     *
+     * Finer-grained than `CodependixGraphType` itself: `python` and
+     * `typescript` both fall under `fileImports`, since `codependix-file-imports`
+     * builds and exports both as one graph type even though `boundaries`
+     * still nests their rules by language. `--no-file-imports` therefore skips
+     * both levels together.
+     */
+    private graphTypeForLevel;
+    /**
+     * Resolves one level's declared rules out of the nested boundaries shape.
+     *
+     * A record keyed by level rather than a switch, the same reason `runLevel`
+     * is one: every `CodependixBoundaryLevel` must have an entry, so a fifth
+     * level added to that union fails to compile here instead of silently
+     * resolving to nothing.
+     */
+    private rulesForLevel;
+    /**
+     * Judges one level, whichever of the four builders it needs.
+     *
+     * A record keyed by level rather than a switch: the record type requires
+     * every `CodependixBoundaryLevel` to have an entry, so a fifth level added
+     * to that union fails to compile here instead of silently going unchecked.
+     */
+    private runLevel;
+    /** Judges every `framework:nestjs` project's module graph. */
+    private runNestjsLevel;
+    /** Judges the whole-workspace Nx project graph. */
+    private runNxLevel;
+    /**
+     * Judges every project at one level, isolating each project's failure.
+     *
+     * The three per-project levels differ only in how a project is discovered
+     * and how its graph is built, so the loop around them is written once: a
+     * project that raises is collected as a failure and every other project is
+     * still judged. `buildGraph` may be asynchronous because the NestJS level's
+     * is — booting a container is the one graph this tool cannot build
+     * synchronously.
+     */
+    private runProjectLevel;
+    /** Judges every `language:python` project's file-level import graph. */
+    private runPythonImportsLevel;
+    /** Judges every TypeScript project's file-level import graph. */
+    private runTypescriptImportsLevel;
+    /**
+     * Judges every level that has a rule to judge it by and whose graph type
+     * this run enabled.
+     *
+     * The four levels are independent, so a NestJS project failing to boot has
+     * no bearing on whether the Nx or import graphs break a rule, and every
+     * level is attempted regardless of what an earlier one reported. A level
+     * declaring no rule is skipped before anything is built, which is what
+     * keeps the gate affordable — and a level whose graph type
+     * `context.enabledGraphTypes` excludes is skipped the same way, so
+     * `--no-nestjs-modules` never boots a single container to judge it.
+     */
+    run(context: BoundaryCheckContext): Promise<BoundaryCheckOutcome>;
+}
+
+/**
+ * One cycle found in a graph.
+ *
+ * `source` and `target` are the edge that closed it — the last node walked,
+ * and the node already on the path it returned to — so a cycle reports the
+ * same two endpoints every other violation does, without a caller having to
+ * index into `path` and prove to the compiler that it is non-empty.
+ */
+export declare interface BoundaryCycle {
+    /** The whole path, with the closing node repeated at the end. */
+    readonly path: readonly string[];
+    readonly source: string;
+    readonly target: string;
+}
+
+/**
+ * Finds the cycles in a graph, within a selected set of nodes.
+ *
+ * A cycle is the one finding no rule reading a single file can make, which is
+ * why it is a rule kind of its own rather than an access rule with a clever
+ * selector. Scoped to a node set rather than always the whole graph: a rule
+ * covering one directory should not fail because of a cycle running entirely
+ * through code it was never asked about.
+ *
+ * One cycle is reported per distinct set of nodes, keyed on the cycle rotated
+ * to start at its smallest node — so a three-node cycle is one finding rather
+ * than the same finding printed once per node it passes through.
+ */
+export declare class BoundaryCyclesService {
+    constructor();
+    /** Builds the outgoing-edge map, keeping only edges inside the node set. */
+    private buildAdjacency;
+    /**
+     * The key every cycle over the same nodes shares.
+     *
+     * The node set rather than the path: `a → b → a` and `b → a → b` are one
+     * finding written two ways, and so are the two directions round a
+     * three-node cycle. Reporting the first path found through a set of nodes
+     * and nothing else is what keeps one tangle from printing as six findings.
+     */
+    private buildCycleKey;
+    /** Records the cycle closed by walking back to a node already on the path. */
+    private recordCycle;
+    /** Walks one node's subtree depth-first, recording every cycle it closes. */
+    private walk;
+    /**
+     * Every cycle lying entirely inside the given node set.
+     *
+     * Nodes are walked in sorted order and each cycle is reported starting from
+     * the node the walk reached first, so the same graph always produces the
+     * same findings in the same order — a report that reshuffles itself between
+     * runs is one nobody can diff.
+     */
+    findCycles(args: FindCyclesArguments): BoundaryCycle[];
+}
+
+/**
+ * One node depending on another, at whatever level the graph is.
+ *
+ * `implicit` is carried rather than dropped because it is the one fact a lint
+ * rule reading import statements cannot reach: an Nx `implicitDependencies`
+ * entry creates a project-graph edge with no import statement to flag. Absent
+ * at every level that has no such notion, rather than defaulted to `false` —
+ * a file import is not "explicitly" anything, it is just an import.
+ */
+export declare interface BoundaryEdge {
+    readonly implicit?: boolean | undefined;
+    readonly source: string;
+    readonly target: string;
+}
+
+/**
+ * One built graph, reduced to what rule evaluation needs.
+ *
+ * Deliberately not `Neighborhood`, `NestjsModuleGraph`, `TypescriptImportGraph`
+ * or `PythonImportGraph`: reading any of those would drag `@nx/devkit`,
+ * `@nestjs/core` and `typescript` behind anything that wants only rule
+ * evaluation. The four already share an identical `{ source, target }` edge
+ * shape by construction, so the adapters that flatten them into this live in
+ * the host that already builds all four — see `codependix-cli`.
+ */
+export declare interface BoundaryGraph {
+    readonly edges: readonly BoundaryEdge[];
+    /** Which of codependix's four levels this graph was built at. */
+    readonly level: CodependixBoundaryLevel;
+    readonly nodes: readonly BoundaryNode[];
+    /**
+     * What the graph covers: an Nx project name, or the workspace itself.
+     *
+     * Reported beside every violation, because the same rule evaluated at file
+     * level fails once per project and a bare pair of file paths does not say
+     * which project's files they are.
+     */
+    readonly scope: string;
+}
+
+/**
+ * Flattens each of codependix's four graphs into the one shape rules read.
+ *
+ * The adapters live here, in the host that already builds all four, rather
+ * than in `@codependix/boundaries` — which would otherwise have to depend on
+ * `@nestjs/core` and `typescript` to name the types it translates, for a
+ * package whose whole job is evaluating rules. The four
+ * already share an identical `{ source, target }` edge shape by construction,
+ * so each adapter is only ever nodes, edges, and the attributes rules select
+ * on.
+ *
+ * What each level knows differs, and the node shape says so: an Nx project
+ * carries tags and a root, a file carries its project-relative path and the
+ * project it belongs to, and a NestJS module carries its class name, declaring
+ * file path, and project name.
+ */
+export declare class BoundaryGraphService {
+    constructor();
+    /** Builds one file-level graph's nodes, which both languages share. */
+    private buildFileNodes;
+    /**
+     * A project's workspace-relative root, or nothing when the graph knows of a
+     * project the discovered list does not carry.
+     */
+    private resolveProjectRoot;
+    /**
+     * Adapts one project's NestJS module graph.
+     *
+     * Nodes carry a name, their project-relative declaring file path, and the
+     * project name they belong to.
+     */
+    buildNestjsGraph(graph: NestjsModuleGraph): BoundaryGraph;
+    /**
+     * Adapts the whole-workspace Nx project graph.
+     *
+     * The workspace graph rather than each project's one-hop neighborhood: a
+     * rule is a statement about the shape of the graph, and a neighborhood is
+     * the same graph shown twice from either end of every edge.
+     *
+     * Tags come off the `NxProject`s themselves, because they are what makes
+     * this level worth having: a tag rule reaches nothing unless the nodes it
+     * judges carry them.
+     */
+    buildNxGraph(args: {
+        projects: readonly NxProject[];
+        scope: string;
+        workingDirectory: string;
+        workspaceGraph: WorkspaceGraph;
+    }): BoundaryGraph;
+    /** Adapts one project's Python file-level import graph. */
+    buildPythonImportGraph(graph: PythonImportGraph): BoundaryGraph;
+    /** Adapts one project's TypeScript file-level import graph. */
+    buildTypescriptImportGraph(graph: TypescriptImportGraph): BoundaryGraph;
+}
+
+/**
+ * One node in a graph, with whatever a level knows about it.
+ *
+ * One shape for three vocabularies: an Nx project has a name, a root, and
+ * tags; a file has a project-relative path and project; a NestJS module has a
+ * class name, declaring file path, and project. Every field beyond `id` is
+ * therefore optional, and a selector naming one a level does not carry
+ * matches nothing there rather than everything — see `BoundarySelectorService`.
+ *
+ * No `kind` field: the graph already states its `level`, and a second field
+ * saying the same thing is a second thing that can be wrong.
+ */
+export declare interface BoundaryNode {
+    readonly id: string;
+    readonly path?: string | undefined;
+    readonly project?: string | undefined;
+    readonly tags?: readonly string[] | undefined;
+}
+
+/**
+ * Renders violations into the lines a run prints.
+ *
+ * Rendering lives here rather than in the host for the same reason each graph
+ * package renders its own mermaid: the package that knows what a finding means
+ * is the one that should decide how it reads. There is no configured
+ * destination and no file — a violation report is a list of things currently
+ * wrong, which is not a document worth regenerating on the default branch or
+ * checking for staleness.
+ */
+export declare class BoundaryReportService {
+    constructor();
+    /**
+     * One line summarizing what a run found.
+     *
+     * Counts rules as well as violations, because the two answer different
+     * questions: one broken rule reporting forty edges is a single decision to
+     * revisit, and forty rules reporting one edge each is not.
+     */
+    renderSummary(violations: readonly BoundaryViolation[]): string;
+    /**
+     * One line per violation, each naming its level and scope before the rule's
+     * own sentence.
+     *
+     * The level and scope lead because the message cannot carry them: the same
+     * rule evaluated at file level fails once per project, and a bare pair of
+     * file paths does not say whose files they are.
+     */
+    renderViolations(violations: readonly BoundaryViolation[]): string[];
+}
+
+/**
+ * Decides which nodes a rule's selector claims.
+ *
+ * Split out from `BoundariesService` because it is the one part of rule
+ * evaluation with no opinion about rules at all: a selector and a node go in,
+ * and a yes or no comes out. Both rule kinds ask it the same question, and so
+ * does anything that later wants to know what a rule covers without running
+ * it.
+ */
+export declare class BoundarySelectorService {
+    constructor();
+    /**
+     * Whether one of a node's string attributes matches a list of globs.
+     *
+     * A selector naming an attribute the node's level does not carry matches
+     * nothing rather than everything — a `path` rule evaluated against a NestJS
+     * module graph, which carries no file paths, selects no module instead of
+     * silently selecting all of them.
+     */
+    private matchesGlobs;
+    /**
+     * Whether a node carries a tag matching one of a list of globs.
+     *
+     * One tag matching is enough, which is what makes `tags: ["type:package"]`
+     * read the way an Nx tag list does — a project carries several, and a rule
+     * naming one is asking whether that one is among them.
+     */
+    private matchesTags;
+    /**
+     * Whether a selector claims a node.
+     *
+     * Every field the selector states must match — the fields narrow each
+     * other, so `{ project: ["lexico"], path: ["src/**"] }` means a file in
+     * lexico's `src` rather than either of those. Within one field, one glob
+     * matching is enough.
+     */
+    matches(node: BoundaryNode, selector: CodependixBoundarySelector): boolean;
+    /**
+     * The ids of every node a selector claims.
+     *
+     * A selector of `undefined` claims every node, which is what an `acyclic`
+     * rule naming no scope means. An empty selector is a different thing and
+     * never reaches here: the configuration schema refuses one outright, since
+     * a selector stating nothing reads exactly like a typo.
+     */
+    selectIds(nodes: readonly BoundaryNode[], selector: CodependixBoundarySelector | undefined): Set<string>;
+}
+
+/** One edge, or one cycle, breaking one declared rule. */
+export declare interface BoundaryViolation {
+    /**
+     * The whole cycle, closing node repeated at the end, for an `acyclic` rule.
+     *
+     * Absent for an access rule, which is about one edge and has no path to
+     * report.
+     */
+    readonly cycle: readonly string[] | undefined;
+    readonly level: CodependixBoundaryLevel;
+    /** The sentence reported, whether the rule's own or the generated one. */
+    readonly message: string;
+    /** The `name` of the rule that reported it. */
+    readonly rule: string;
+    readonly scope: string;
+    readonly source: string;
+    readonly target: string;
+}
+
+/**
+ * The level a boundary graph was built at, or a violation was found at.
+ *
+ * Finer-grained than `CodependixGraphType`: `fileImports` builds one merged
+ * graph type per project, but `boundaries.fileImports` still nests rules by
+ * language, and a violation has to say which language's graph it came from.
+ * `nestjsModules` and `nxProjects` match `CodependixGraphType` one for one,
+ * since those two levels carry no such split.
+ */
+declare type CodependixBoundaryLevel = "nestjsModules" | "nxProjects" | "python" | "typescript";
+
+/** How a cycle's nodes are joined when one is reported. */
+export declare const CYCLE_SEPARATOR = " \u2192 ";
+
+/**
+ * The sentence an `acyclic` rule reports when it names none of its own.
+ *
+ * Names the whole path rather than only the edge that closed it: a cycle is a
+ * statement about a shape, and the two nodes of its closing edge are the
+ * least useful two to be handed.
+ */
+export declare const describeCycle: (args: {
+    cycle: readonly string[];
+    rule: string;
+}) => string;
+
+/**
+ * The sentence a violated `allow` rule reports when it names none of its own.
+ *
+ * Worded as a permitted surface rather than as a forbidden edge, because that
+ * is what distinguishes it from `forbid`: the reader's next question is what
+ * the rule does allow, and the rule's name is the only place this can point
+ * them at without restating the configuration.
+ */
+export declare const describeDisallowedEdge: (args: {
+    rule: string;
+    source: string;
+    target: string;
+}) => string;
+
+/** The sentence a violated `forbid` rule reports when it names none of its own. */
+export declare const describeForbiddenEdge: (args: {
+    rule: string;
+    source: string;
+    target: string;
+}) => string;
+
+/** Arguments accepted when judging one graph against one level's rules. */
+export declare interface EvaluateBoundariesArguments {
+    readonly graph: BoundaryGraph;
+    readonly rules: readonly CodependixBoundaryRule[];
+}
+
+/** Arguments accepted when finding the cycles in a graph. */
+export declare interface FindCyclesArguments {
+    readonly edges: readonly BoundaryEdge[];
+    /** The nodes a cycle must lie entirely within. */
+    readonly nodeIds: ReadonlySet<string>;
+}
+
+/**
+ * Everything every graph-type pass reads, resolved once per run rather than
+ * once per pass — see `GraphRunService.run`.
+ *
+ * Stated here, beside `BoundaryCheckContext`, because resolving it is the
+ * first thing every run does and the boundary gate is one of its readers:
+ * the wider context carries an export mode the gate never looks at, and is
+ * structurally assignable to `BoundaryCheckContext`, so nothing is repacked
+ * at the call site.
+ */
+export declare interface GraphRunContext {
+    configuration: ResolvedCodependixConfiguration;
+    /**
+     * The graph types this run builds, checks, and writes.
+     *
+     * All three unless `--no-file-imports`, `--no-nestjs-modules`, or
+     * `--no-nx-projects` narrowed it — see `RunContextService.build`. Read by
+     * `GraphRunService.run` to skip a whole pass, and by
+     * `BoundaryCheckService.run` to skip a boundary level, so a developer can
+     * run a narrower, faster check locally without editing configuration.
+     */
+    enabledGraphTypes: ReadonlySet<CodependixGraphType>;
+    graph: NxProjectGraph;
+    mode: CodependixRunMode;
+    /**
+     * Every project's own `codependix.config.ts`, keyed by project name — or
+     * `undefined` for a project naming none of its own.
+     *
+     * Loaded once per run, alongside `projects`, so every pass reads the same
+     * snapshot rather than each re-reading the filesystem for every graph type
+     * it resolves. Read as-is by `ConfigurationService.resolveForProject` — see
+     * that method for why no further merge happens here.
+     */
+    projectConfigurations: Map<string, CodependixProjectConfiguration | undefined>;
+    /** Every project the graph knows, apart from the workspace root. */
+    projects: NxProject[];
+    /**
+     * The projects `--projects` and `--tags` narrowed the run to.
+     *
+     * Identical to `projects` when a run named neither, which is what keeps the
+     * Workspace Graph whole and the boundary gate judging every project by
+     * default. `include`/`exclude` never reach this: they decide which projects
+     * have exports written, not which projects a graph is drawn over.
+     */
+    selectedProjects: NxProject[];
+    workingDirectory: string;
+}
+
+/** Arguments accepted when judging one graph level against its rules. */
+export declare interface LevelCheckArguments {
+    readonly context: BoundaryCheckContext;
+    readonly level: CodependixBoundaryLevel;
+    readonly rules: readonly CodependixBoundaryRule[];
+}
+
+/**
+ * Wires run-context resolution to the configuration and project graph it
+ * reads, which are the only two things a run has to resolve before any pass
+ * can run.
+ */
+export declare class RunContextModule {
+}
+
+/**
+ * Resolves everything one run reads, once, before any pass runs.
+ *
+ * Kept apart from the passes that read it because the two answer different
+ * questions: what this workspace is, versus what to do about it. Every pass —
+ * the four export passes, the Workspace Graph, and the boundary gate — is
+ * handed the same resolved context rather than resolving its own, so a run
+ * reads the project graph once and judges one workspace.
+ */
+export declare class RunContextService {
+    private readonly configurationService;
+    private readonly neighborhoodService;
+    constructor(configurationService: ConfigurationService, neighborhoodService: NeighborhoodService);
+    /**
+     * Loads every project's own `codependix.config.ts`, keyed by project name.
+     *
+     * Loaded once per run, up front, rather than once per graph-type pass: a
+     * project with no file of its own is a normal, expected outcome rather than
+     * a failure, so every project is attempted and the map simply holds
+     * `undefined` for the ones naming none.
+     */
+    private loadProjectConfigurations;
+    /**
+     * Reads the three graph-type toggle flags into the set of graph types this
+     * run builds, checks, and writes.
+     *
+     * A graph type is enabled unless its own `--no-*` flag disabled it —
+     * `--file-imports`/`--nestjs-modules`/`--nx-projects` exist only for
+     * symmetry with the negated form, matching every graph type's default of
+     * "on" when neither flag was given.
+     */
+    private resolveEnabledGraphTypes;
+    /**
+     * Resolves a supplied project graph's path against the workspace root.
+     *
+     * The same root every export path resolves against — `--directory` keeps
+     * its one meaning, and a supplied graph's workspace-relative node roots
+     * resolve underneath it too.
+     */
+    private resolveProjectGraphPath;
+    /**
+     * Narrows every project to the set `--projects` and `--tags` named.
+     *
+     * A run naming neither selects every project, which is what keeps the
+     * Workspace Graph whole and the boundary gate judging the whole workspace by
+     * default. `include`/`exclude` deliberately do not reach this: they decide
+     * which projects have exports written for them, not which projects a graph
+     * is drawn over.
+     */
+    private selectProjects;
+    /**
+     * Reads the configuration and the project graph a run is about to act on.
+     *
+     * Called once per run, by the command — every pass takes the context it
+     * returns. `--check boundaries` reads exactly the same one, which is what
+     * lets a single run both export and gate without reading the workspace
+     * twice.
+     */
+    build(args: {
+        mode: CodependixRunMode;
+        options: MapCommandOptions;
+        workingDirectory: string;
+    }): Promise<GraphRunContext>;
+}
+
+/**
+ * The scope a violation found in the whole-workspace Nx graph is reported
+ * under.
+ *
+ * The Nx level is judged once for the repository rather than once per
+ * project, so it has no project name to report against.
+ */
+export declare const WORKSPACE_SCOPE = "workspace";
+
+export { }