@codependix/boundaries 0.0.10 → 0.0.11

package/dist/src/index.d.ts

@@ -42,7 +42,11 @@ 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. */
+    /**
+     * Turns one condemned edge into the violation reported for it, charged to
+     * the project owning the edge's source alone: the dependency is written in
+     * the source, so that is the project a fix belongs to.
+     */
     private buildAccessViolation;
     /**
      * The sentence a violation is reported as.
@@ -54,6 +58,15 @@ export declare class BoundariesService {
      * configured half says why it matters.
      */
     private buildMessage;
+    /**
+     * The projects owning the given nodes, sorted and deduplicated.
+     *
+     * A node's own `project` where it carries one — every node in an Nx-level
+     * graph is its own project — and the graph's `scope` otherwise, which is
+     * the project a file- or NestJS-level graph was built for. Never the
+     * workspace: a finding charged to no project could fail no project.
+     */
+    private chargeProjects;
     /**
      * Reports every edge an `allow` or `forbid` rule condemns.
      *
@@ -63,7 +76,11 @@ export declare class BoundariesService {
      * does not.
      */
     private evaluateAccessRule;
-    /** Reports every cycle an `acyclic` rule's selected nodes still form. */
+    /**
+     * Reports every cycle an `acyclic` rule's selected nodes still form, each
+     * charged to every project owning a node on it: no one project on a cycle
+     * can break it alone, so it fails every one of them.
+     */
     private evaluateAcyclicRule;
     /** Indexes a graph's nodes by identifier, so an edge can look its ends up. */
     private indexNodes;
@@ -133,6 +150,12 @@ export declare const BOUNDARY_LEVEL_ORDER: readonly ["nxProjects", "nestjsModule
  * be repacked at the call site.
  */
 export declare interface BoundaryCheckContext {
+    /**
+     * The projects every level's graph is built over: `selectedProjects` and
+     * everything they depend on, or `selectedProjects` alone under
+     * `--no-dependencies` — see `RunContextService.resolveBuildProjects`.
+     */
+    readonly buildProjects: NxProject[];
     readonly configuration: ResolvedCodependixConfiguration;
     /**
      * The graph types this run judges.
@@ -148,7 +171,8 @@ export declare interface BoundaryCheckContext {
     /** 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.
+     * The projects the run was narrowed to: a finding fails the run only when
+     * it is charged to one of these.
      *
      * Identical to `projects` unless `--projects` or `--tags` named a
      * selection, so the gate judges the whole workspace by default and a
@@ -158,10 +182,26 @@ export declare interface BoundaryCheckContext {
     readonly workingDirectory: string;
 }
 
-/** One project whose graph could not be built, and why. */
+/**
+ * One graph that could not be built, charged to the project(s) it was being
+ * built for.
+ *
+ * A container that cannot boot fails its own project, since that container
+ * really cannot boot — but the class it failed on often lives in a
+ * dependency, so `ownerProject` names that dependency when the stack shows it.
+ */
 export declare interface BoundaryCheckFailure {
+    /** The raised error's message. */
     readonly error: string;
-    readonly projectName: string;
+    readonly level: CodependixBoundaryLevel;
+    /**
+     * The project owning the first stack frame inside the root of a project
+     * the charged ones depend on, when that is not a charged project. Absent when no frame resolves to a
+     * project: a guessed owner would blame a project that did nothing wrong.
+     */
+    readonly ownerProject?: string | undefined;
+    /** The projects this failure is charged to, sorted. */
+    readonly projects: readonly string[];
 }
 
 /** Wires rule evaluation together with the four graph builders it judges. */
@@ -169,7 +209,7 @@ export declare class BoundaryCheckModule {
 }
 
 /**
- * What one `--check boundaries` pass found.
+ * What one `--check boundaries` pass found, each finding judged.
  *
  * Failures are carried beside violations rather than thrown, for the same
  * reason every export pass carries them: a NestJS project that cannot boot
@@ -178,8 +218,8 @@ export declare class BoundaryCheckModule {
  * has.
  */
 export declare interface BoundaryCheckOutcome {
-    readonly failures: BoundaryCheckFailure[];
-    readonly violations: BoundaryViolation[];
+    readonly failures: JudgedBoundaryFinding<BoundaryCheckFailure>[];
+    readonly violations: JudgedBoundaryFinding<BoundaryViolation>[];
 }
 
 /**
@@ -198,15 +238,14 @@ export declare interface BoundaryCheckOutcome {
  */
 export declare class BoundaryCheckService {
     private readonly boundariesService;
+    private readonly boundaryFailureService;
     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;
+    constructor(boundariesService: BoundariesService, boundaryFailureService: BoundaryFailureService, boundaryGraphService: BoundaryGraphService, moduleGraphService: ModuleGraphService, nestjsProjectService: NestjsProjectService, pythonService: PythonService, typescriptService: TypescriptService, workspaceGraphService: WorkspaceGraphService);
     /**
      * The `CodependixGraphType` each boundary level is judged under.
      *
@@ -217,6 +256,13 @@ export declare class BoundaryCheckService {
      * both levels together.
      */
     private graphTypeForLevel;
+    /**
+     * Judges every charged finding: it fails the run when one of its projects
+     * is judged, and is a note against the dependency it lives in otherwise.
+     */
+    private judge;
+    /** `"fail"` when any charged project is judged, and `"note"` otherwise. */
+    private resolveVerdict;
     /**
      * Resolves one level's declared rules out of the nested boundaries shape.
      *
@@ -227,7 +273,7 @@ export declare class BoundaryCheckService {
      */
     private rulesForLevel;
     /**
-     * Judges one level, whichever of the four builders it needs.
+     * Builds one level's findings, 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
@@ -236,17 +282,24 @@ export declare class BoundaryCheckService {
     private runLevel;
     /** Judges every `framework:nestjs` project's module graph. */
     private runNestjsLevel;
-    /** Judges the whole-workspace Nx project graph. */
+    /**
+     * Judges the whole-workspace Nx project graph, drawn over the build set so
+     * no edge from a judged project into a dependency is dropped.
+     *
+     * A graph that cannot be built is charged to every judged project, since
+     * none of them could be judged at this level.
+     */
     private runNxLevel;
     /**
-     * Judges every project at one level, isolating each project's failure.
+     * Judges every project in the build set 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.
+     * project that raises is collected as a failure charged to it, 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. */
@@ -339,6 +392,64 @@ export declare interface BoundaryEdge {
     readonly target: string;
 }
 
+/**
+ * Turns an error a graph builder raised into the failure a run reports.
+ *
+ * The failure is charged to the project whose graph was being built — a
+ * container that cannot boot fails that project, whichever class broke it.
+ * What the message alone cannot say is whose class that was: NestJS
+ * containers are booted by `import()`, and a module that fails evaluation in
+ * a dependency rethrows the same error into every project importing it. The
+ * stack still holds the frame that threw, so the first frame inside the root
+ * of a project the charged ones depend on names the project that owns the
+ * failing code.
+ *
+ * Only their dependency closure: when codependix runs from source, its own
+ * packages are workspace projects too, and an error it raises itself would
+ * otherwise blame whichever of them threw.
+ */
+export declare class BoundaryFailureService {
+    private readonly neighborhoodService;
+    constructor(neighborhoodService: NeighborhoodService);
+    /**
+     * The project whose root holds a file, the innermost when roots nest — or
+     * nothing for a file no project holds, or one inside `node_modules`.
+     */
+    private findProjectHolding;
+    /**
+     * The location one stack line names, without its line and column — or
+     * nothing for a line that is not a frame, or a frame naming no position.
+     *
+     * String operations rather than a regular expression: a stack is library
+     * input, and every single-pattern reading of both frame shapes backtracks
+     * in polynomial time on a crafted line.
+     */
+    private readFrameLocation;
+    /**
+     * The absolute file path one stack line names, or nothing for a line that
+     * is not a frame or names no file — a `node:` internal, say.
+     */
+    private readFramePath;
+    /**
+     * The project owning the first stack frame inside the root of a project
+     * the charged ones transitively depend on, themselves included.
+     *
+     * The first such frame rather than any: frames below it are whatever was
+     * importing the failing module, which is every project that depends on it.
+     * A frame in any other project is skipped — that project is not something
+     * the charged ones are built from, so it cannot be what broke them.
+     */
+    private resolveOwnerProject;
+    /**
+     * Collects one graph's failure, charged to the projects it was built for.
+     *
+     * `ownerProject` is set only when the stack resolves to a project that is
+     * not already charged: naming the charged project a second time says
+     * nothing, and naming a guess would blame a project that did nothing wrong.
+     */
+    collect(args: CollectFailureArguments): BoundaryCheckFailure;
+}
+
 /**
  * One built graph, reduced to what rule evaluation needs.
  *
@@ -419,6 +530,12 @@ export declare class BoundaryGraphService {
     buildTypescriptImportGraph(graph: TypescriptImportGraph): BoundaryGraph;
 }
 
+/** What every level found, charged but not yet judged. */
+export declare interface BoundaryLevelOutcome {
+    readonly failures: BoundaryCheckFailure[];
+    readonly violations: BoundaryViolation[];
+}
+
 /**
  * One node in a graph, with whatever a level knows about it.
  *
@@ -438,6 +555,86 @@ export declare interface BoundaryNode {
     readonly tags?: readonly string[] | undefined;
 }
 
+/**
+ * Reports what a boundary pass found — as lines, as the JSON object under the
+ * `boundaries` key, and as the Markdown section of a combined document.
+ *
+ * Kept apart from `BoundaryReportService`, which renders rule violations
+ * alone: a pass's container failures and verdicts are only known to the check
+ * that judged them, and every wording that says whom a finding is charged to
+ * still comes from `BoundaryReportService.describeCharge`.
+ */
+export declare class BoundaryOutcomeReportService {
+    private readonly boundaryReportService;
+    constructor(boundaryReportService: BoundaryReportService);
+    /** One bullet: the verdict in bold, then the line the log prints. */
+    private renderBullet;
+    /** One failure as the line the log and the Markdown report both print. */
+    private renderFailure;
+    /** The bullets of every finding charged to one project, violations first. */
+    private renderProjectGroup;
+    /** One violation as the line the log and the Markdown report both print. */
+    private renderViolation;
+    /**
+     * Reduces a pass's judged findings to the object `--format json` prints.
+     *
+     * Maps field by field rather than spreading: a violation's `scope` is where
+     * it was found, not whose it is, and the report names the charged projects
+     * instead. A cycle absent from an access rule is `null` and an absent owner
+     * is left out, so the same key never means two things.
+     */
+    buildReport(args: BoundaryReportArguments): BoundaryReport;
+    /**
+     * One line per failure: its level, whom it is charged to, and the error —
+     * then the project owning the code it broke on, when that is another
+     * project. A note says which dependency it lives in instead.
+     */
+    renderFailures(failures: readonly JudgedBoundaryFinding<BoundaryCheckFailure>[]): string[];
+    /**
+     * Renders a report as the Markdown a combined document carries: the judged
+     * projects, then every finding listed under each project it is charged to,
+     * a note marked as not failing under the dependency it lives in.
+     *
+     * A run judging no project at all — a workspace holding nothing but its
+     * root, since an unmatched selection is refused before the run — says
+     * "none" rather than printing an empty list.
+     */
+    renderMarkdown(report: BoundaryReport): string;
+}
+
+/**
+ * One boundary pass's findings as `--format json` prints them, under the
+ * `boundaries` key.
+ *
+ * Every finding carries its verdict, so a reader can tell a finding that
+ * failed the run from a note about a dependency without re-deriving it from
+ * `judgedProjects`.
+ */
+export declare interface BoundaryReport {
+    /** Every container that could not boot, charged and judged. */
+    readonly failures: BoundaryReportFailure[];
+    /** The projects the run judged, sorted — what a finding must be charged to to fail. */
+    readonly judgedProjects: string[];
+    /** Every edge or cycle that broke a declared rule, charged and judged. */
+    readonly violations: BoundaryReportViolation[];
+}
+
+/** Arguments accepted when building a run's `BoundaryReport`. */
+export declare interface BoundaryReportArguments {
+    readonly judgedProjects: readonly string[];
+    readonly outcome: BoundaryCheckOutcome;
+}
+
+/** One container failure in a `BoundaryReport`. */
+export declare interface BoundaryReportFailure {
+    readonly error: string;
+    readonly level: CodependixBoundaryLevel;
+    /** Present only when the failing code belongs to another project. */
+    readonly ownerProject?: string;
+    readonly projects: readonly string[];
+    readonly verdict: BoundaryVerdict;
+}
+
 /**
  * Renders violations into the lines a run prints.
  *
@@ -450,6 +647,24 @@ export declare interface BoundaryNode {
  */
 export declare class BoundaryReportService {
     constructor();
+    /**
+     * Who a finding is charged to, as the lines and the Markdown report word it.
+     *
+     * The one place that wording lives: a violation and a failure are both
+     * reported as a note when they live only in a dependency, and a reader who
+     * sees the phrase in one report should find it unchanged in the other.
+     * Says "in dependency" because the finding is real, and inherited, but it is
+     * not theirs to fix and it did not fail their run.
+     */
+    describeCharge(args: {
+        isNote: boolean;
+        projects: readonly string[];
+    }): string;
+    /**
+     * One line per note — a violation charged only to a dependency of the
+     * projects a run judges — marked as not failing.
+     */
+    renderNotes(violations: readonly BoundaryViolation[]): string[];
     /**
      * One line summarizing what a run found.
      *
@@ -459,16 +674,31 @@ export declare class BoundaryReportService {
      */
     renderSummary(violations: readonly BoundaryViolation[]): string;
     /**
-     * One line per violation, each naming its level and scope before the rule's
-     * own sentence.
+     * One line per violation, each naming its level and the projects it is
+     * charged to 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.
+     * The level and projects 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. Charged projects rather
+     * than the graph's scope, so an Nx-level finding names the projects that
+     * own it rather than the workspace it was found in.
      */
     renderViolations(violations: readonly BoundaryViolation[]): string[];
 }
 
+/** One rule violation in a `BoundaryReport`. */
+export declare interface BoundaryReportViolation {
+    /** The whole cycle for an `acyclic` rule, and `null` for an access rule. */
+    readonly cycle: null | readonly string[];
+    readonly level: CodependixBoundaryLevel;
+    readonly message: string;
+    readonly projects: readonly string[];
+    readonly rule: string;
+    readonly source: string;
+    readonly target: string;
+    readonly verdict: BoundaryVerdict;
+}
+
 /**
  * Decides which nodes a rule's selector claims.
  *
@@ -517,6 +747,16 @@ export declare class BoundarySelectorService {
     selectIds(nodes: readonly BoundaryNode[], selector: CodependixBoundarySelector | undefined): Set<string>;
 }
 
+/**
+ * Whether a finding fails the run, or is reported as a note against the
+ * dependency it lives in.
+ *
+ * `"fail"` when a charged project is one the run judges; `"note"` when every
+ * charged project is only in the build set — a dependency the judged
+ * projects are built from, whose finding they inherit but cannot fix.
+ */
+export declare type BoundaryVerdict = "fail" | "note";
+
 /** One edge, or one cycle, breaking one declared rule. */
 export declare interface BoundaryViolation {
     /**
@@ -529,6 +769,14 @@ export declare interface BoundaryViolation {
     readonly level: CodependixBoundaryLevel;
     /** The sentence reported, whether the rule's own or the generated one. */
     readonly message: string;
+    /**
+     * The projects this violation is charged to, sorted: an access rule's
+     * edge source's project, or every project owning a node on a cycle.
+     *
+     * What decides whether it fails a run — it does when any of these is a
+     * project the run judges — see `BoundaryCheckService.run`.
+     */
+    readonly projects: readonly string[];
     /** The `name` of the rule that reported it. */
     readonly rule: string;
     readonly scope: string;
@@ -547,6 +795,21 @@ export declare interface BoundaryViolation {
  */
 declare type CodependixBoundaryLevel = "nestjsModules" | "nxProjects" | "python" | "typescript";
 
+/** Arguments accepted when collecting one graph's failure. */
+export declare interface CollectFailureArguments {
+    readonly error: unknown;
+    /**
+     * The whole Nx project graph, rather than the build set, so an owner is
+     * still found in a dependency `--no-dependencies` left out of the build.
+     */
+    readonly graph: NxProjectGraph;
+    readonly level: CodependixBoundaryLevel;
+    /** The projects the failing graph was being built for. */
+    readonly projects: readonly string[];
+    /** Every project the workspace knows, for resolving the failure's owner. */
+    readonly workspaceProjects: readonly NxProject[];
+}
+
 /** How a cycle's nodes are joined when one is reported. */
 export declare const CYCLE_SEPARATOR = " \u2192 ";
 
@@ -607,6 +870,16 @@ export declare interface FindCyclesArguments {
  * at the call site.
  */
 export declare interface GraphRunContext {
+    /**
+     * The projects every boundary graph is built over: `selectedProjects`'
+     * dependency closure in the Nx project graph, or `selectedProjects` alone
+     * under `--no-dependencies`.
+     *
+     * Wider than what is judged, so a finding a selected project inherits from
+     * a dependency is still found — and reported as a note against that
+     * dependency rather than failing the run. Exports never read this.
+     */
+    buildProjects: NxProject[];
     configuration: ResolvedCodependixConfiguration;
     /**
      * The graph types this run builds, checks, and writes.
@@ -633,7 +906,8 @@ export declare interface GraphRunContext {
     /** Every project the graph knows, apart from the workspace root. */
     projects: NxProject[];
     /**
-     * The projects `--projects` and `--tags` narrowed the run to.
+     * The projects `--projects` and `--tags` narrowed the run to — the set the
+     * boundary gate judges, and the set the Workspace Graph is drawn over.
      *
      * Identical to `projects` when a run named neither, which is what keeps the
      * Workspace Graph whole and the boundary gate judging every project by
@@ -644,6 +918,11 @@ export declare interface GraphRunContext {
     workingDirectory: string;
 }
 
+/** A violation or failure, with the verdict the run reached on it. */
+export declare type JudgedBoundaryFinding<Finding> = Finding & {
+    readonly verdict: BoundaryVerdict;
+};
+
 /** Arguments accepted when judging one graph level against its rules. */
 export declare interface LevelCheckArguments {
     readonly context: BoundaryCheckContext;
@@ -681,6 +960,18 @@ export declare class RunContextService {
      * `undefined` for the ones naming none.
      */
     private loadProjectConfigurations;
+    /**
+     * Widens the selected projects to the set every boundary graph is built
+     * over: their dependency closure, or the selection alone under
+     * `--no-dependencies`.
+     *
+     * Only the selection is judged. The rest of the closure is built so a
+     * finding the selected projects inherit from a dependency can be reported
+     * against it as a note, and so an Nx edge leaving the selection is still
+     * drawn. With no selection every project is selected, and the closure of
+     * every project is every project.
+     */
+    private resolveBuildProjects;
     /**
      * Reads the three graph-type toggle flags into the set of graph types this
      * run builds, checks, and writes.
@@ -699,6 +990,15 @@ export declare class RunContextService {
      * resolve underneath it too.
      */
     private resolveProjectGraphPath;
+    /**
+     * Resolves the two project sets a run acts on: the selection it judges,
+     * and the build set every boundary graph is drawn over.
+     *
+     * A `--projects`/`--tags` selection matching no project is refused here,
+     * before any pass runs — see `emptySelectionError`. No selection at all
+     * selects every project, so only a named one can come back empty.
+     */
+    private resolveProjectSets;
     /**
      * Narrows every project to the set `--projects` and `--tags` named.
      *
@@ -725,11 +1025,13 @@ export declare class RunContextService {
 }
 
 /**
- * The scope a violation found in the whole-workspace Nx graph is reported
- * under.
+ * The `scope` of the whole-workspace Nx graph — what the graph covers, not
+ * who a finding in it is charged to.
  *
- * The Nx level is judged once for the repository rather than once per
- * project, so it has no project name to report against.
+ * The Nx level is built once for the repository rather than once per
+ * project, so its graph has no one project to name. Each finding in it is
+ * charged to the projects owning its nodes instead — see
+ * `BoundariesService.chargeProjects`.
  */
 export declare const WORKSPACE_SCOPE = "workspace";