@intentius/chant 0.124.44 → 0.124.46

package/dist/cli/handlers/declared-graph.js

@@ -0,0 +1,87 @@
+import { dirname } from "node:path";
+import { mergeBuildRootEntities } from "../../build.js";
+import { loadChantConfigUpward } from "../../config.js";
+import { applyLexiconGraphEdges } from "../../graph-ir.js";
+import { formatError, formatWarning } from "../format.js";
+import { collectBuildRootContributors, loadPlugins, resolveProjectLexicons } from "../plugins.js";
+/**
+ * The pieces of the declared graph that `chant graph` and `chant search` both
+ * read (#1626, #4365, #4368). They live here, once, so the two commands answer
+ * over the same entity set and the same edges: search drifted from graph once
+ * already, answering `(no matches)` over a `terraform.roots` project graph drew
+ * in full, because it never ran the build-root contributors.
+ */
+/**
+ * The build-root contributors this invocation's project configures (#1626):
+ * a `terraform.roots` root's blocks, a `k8s.kustomize.roots` root's rendered
+ * objects. The same closures `chant build` and the lifecycle handlers hand to
+ * `BuildOptions.buildRoots`, bound here for the discover-based paths, which
+ * never run `build()` and so never ran the hook.
+ *
+ * Neither command is `requiresPlugins` (Op/source-graph modes must work
+ * without a lexicon), so plugins are loaded here when `ctx.plugins` is empty.
+ * Rooted at the config's own directory, like `cli/commands/build.ts`: a
+ * relative root resolves against where it was declared, not against a
+ * sourceDir-scoped path. A project that fails to load plugins degrades to no
+ * contributors with a warning rather than failing modes that never needed
+ * plugins at all.
+ */
+export async function declaredBuildRootContributors(ctx, projectPath) {
+    const { config, configPath } = await loadChantConfigUpward(projectPath).catch(() => ({ config: {}, configPath: undefined }));
+    let plugins = ctx.plugins;
+    if (plugins.length === 0) {
+        try {
+            plugins = await loadPlugins(await resolveProjectLexicons(projectPath));
+        }
+        catch (err) {
+            console.error(formatWarning({
+                message: `could not load the project's lexicons — build-root entities (terraform and kustomize roots) will be missing from the graph (${err instanceof Error ? err.message : String(err)})`,
+            }));
+            return [];
+        }
+    }
+    return collectBuildRootContributors(plugins, config, configPath ? dirname(configPath) : projectPath);
+}
+/**
+ * Merge build-root contributions into a discovered entity set: the exact
+ * merge `build()` performs (one implementation: `mergeBuildRootEntities`,
+ * ../../build.ts), with its warnings and errors printed. Returns false when a
+ * contributor failed or a name collided; the caller stops, because a graph
+ * missing the entities the build would refuse over must not be answered from
+ * as if complete.
+ */
+export async function mergeDeclaredBuildRoots(entities, contributors) {
+    if (contributors.length === 0)
+        return true;
+    const merged = await mergeBuildRootEntities(entities, contributors);
+    for (const w of merged.warnings)
+        console.error(formatWarning({ message: w }));
+    if (merged.errors.length > 0) {
+        for (const message of merged.errors)
+            console.error(formatError({ message }));
+        return false;
+    }
+    return true;
+}
+/**
+ * Add the edges the lexicons' `graphEdges` hooks resolve (#3910): CI
+ * dependencies written as strings (`needs`, `uses:`, `trigger:`, `include:`,
+ * `extends`), which the AttrRef walk in `buildGraphIr` cannot see. A hook that
+ * throws costs its own edges and a warning, not the graph.
+ */
+export function withLexiconEdges(ir, plugins, entities) {
+    const reports = [];
+    for (const p of plugins) {
+        if (!p.graphEdges)
+            continue;
+        try {
+            const report = p.graphEdges(entities);
+            if (report)
+                reports.push(report);
+        }
+        catch (err) {
+            console.error(formatWarning({ message: `the ${p.name} lexicon's graphEdges failed (${err instanceof Error ? err.message : String(err)}); its edges are left out` }));
+        }
+    }
+    return reports.length === 0 ? ir : applyLexiconGraphEdges(ir, reports);
+}

package/dist/cli/handlers/graph.d.ts

@@ -1,3 +1,4 @@
+import { type LintResult } from "../commands/lint.js";
 import type { CommandContext } from "../registry.js";
 /**
  * `chant graph` — the Op dependency graph by default; `--stacks` renders the
@@ -16,4 +17,28 @@ import type { CommandContext } from "../registry.js";
  * is the read the other gets.
  */
 export declare function runGraph(ctx: CommandContext): Promise<number>;
+/** One lint finding as `meta.lint` carries it (INTENTIUS/behold#919). */
+export interface GraphLintFinding {
+    ruleId: string;
+    severity: string;
+    message: string;
+    /** Relative to the project when inside it, else as lint reported it. */
+    file: string;
+    line: number;
+    column: number;
+    /** The entity a post-synth check named, which is the graph node's id. Absent for a source-file rule. */
+    entity?: string;
+}
+/**
+ * What a `graph.lint: "report"` project's entity graph carries on `meta.lint`:
+ * the counts `chant lint` would print and every finding behind them, warnings
+ * included. Present on every graph such a project emits, findings or none, so
+ * a reader can tell "linted, clean" from "not looked" (no key).
+ */
+export interface GraphLintReport {
+    errors: number;
+    warnings: number;
+    findings: GraphLintFinding[];
+}
+export declare function graphLintReport(lint: LintResult, projectPath: string): GraphLintReport;
 //# sourceMappingURL=graph.d.ts.map

package/dist/cli/handlers/graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/graph.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,aAAa,CAAC;AA+H9D;;;;;;;;;GASG;AACH;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAE7D"}
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/graph.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAYhE,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,aAAa,CAAC;AAgE9D;;;;;;;;;GASG;AACH;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAE7D;AAoaD,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,wGAAwG;IACxG,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,gBAAgB,EAAE,CAAC;CAC9B;AAQD,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,eAAe,CAoBtF"}

package/dist/cli/handlers/graph.js

@@ -1,14 +1,14 @@
-import { dirname, resolve } from "node:path";
+import { isAbsolute, relative, resolve } from "node:path";
 import { discoverOps } from "../../op/discover.js";
 import { discover } from "../../discovery/index.js";
-import { partitionByLexicon, computeStackGraph, build, mergeBuildRootEntities } from "../../build.js";
-import { applyLexiconGraphEdges, applyLexiconOutputs, buildGraphIr, buildLiveGraphIr, collectUnobserved, overlayGraphs, sourceOverlayGraphs, GRAPH_IR_VERSION } from "../../graph-ir.js";
+import { partitionByLexicon, computeStackGraph, build } from "../../build.js";
+import { applyLexiconOutputs, buildGraphIr, buildLiveGraphIr, collectUnobserved, overlayGraphs, sourceOverlayGraphs, GRAPH_IR_VERSION } from "../../graph-ir.js";
 import { behaviourOverlay } from "../../behaviour-overlay.js";
 import { applyBehaviourOverlay, behaviourRequestFromIr } from "../../behaviour-graph.js";
 import { buildDeclaredPerStack } from "../../graph-declared.js";
 import { mergeProjectOps } from "../../graph-ops.js";
 import { reconstructEdges, mergeCatalogs, containmentGroups } from "../../graph-refs.js";
-import { observeResources } from "../../lifecycle/observe.js";
+import { carryAnnotations, observeResources } from "../../lifecycle/observe.js";
 import { withLiveReadSession } from "../../live-read-session.js";
 import { replaySnapshots, hasSnapshot } from "../../lifecycle/replay.js";
 import { loadChantConfig, environmentNames, matchesDeclaredEnvironment, loadChantConfigUpward } from "../../config.js";
@@ -21,6 +21,8 @@ import { getLayoutEngine, toLayoutInput } from "../../graph-layout.js";
 import { lintCommand } from "../commands/lint.js";
 import { reportUninstalledDependencies } from "../dependencies.js";
 import { loadPlugins, resolveProjectLexicons, collectBuildRootContributors } from "../plugins.js";
+// One copy for graph and search (#4365): the build-root join and the lexicon edges.
+import { declaredBuildRootContributors as graphBuildRootContributors, mergeDeclaredBuildRoots as mergeGraphBuildRoots, withLexiconEdges, } from "./declared-graph.js";
 import { isNoLexiconDetected } from "../../detectLexicon.js";
 import { readFileSync } from "node:fs";
 import { formatError, formatWarning, formatBold } from "../format.js";
@@ -71,59 +73,6 @@ async function graphBuildParams(ctx, projectPath) {
     }
     return resolution.provenance;
 }
-/**
- * The build-root contributors this invocation's project configures (#1626) —
- * the same closures `chant build` and the lifecycle handlers hand to
- * `BuildOptions.buildRoots`, bound here for the graph command's
- * discover-based paths, which never run `build()` and so never ran the hook:
- * a `k8s.kustomize.roots` estate graphed only its typed source while its
- * built (and deployed) output carried the rendered manifests too.
- *
- * `graph` is not `requiresPlugins` (Op/source-graph modes must work without a
- * lexicon), so plugins are loaded here when `ctx.plugins` is empty, mirroring
- * `runGraphLive`. Rooted at the config's own directory, like
- * `cli/commands/build.ts` — a relative kustomize root resolves against where
- * it was declared, not against a sourceDir-scoped graph path. A project that
- * fails to load plugins degrades to no contributors with a warning rather
- * than failing modes that never needed plugins at all.
- */
-async function graphBuildRootContributors(ctx, projectPath) {
-    const { config, configPath } = await loadChantConfigUpward(projectPath).catch(() => ({ config: {}, configPath: undefined }));
-    let plugins = ctx.plugins;
-    if (plugins.length === 0) {
-        try {
-            plugins = await loadPlugins(await resolveProjectLexicons(projectPath));
-        }
-        catch (err) {
-            console.error(formatWarning({
-                message: `could not load the project's lexicons — build-root entities (kustomize roots) will be missing from the graph (${err instanceof Error ? err.message : String(err)})`,
-            }));
-            return [];
-        }
-    }
-    return collectBuildRootContributors(plugins, config, configPath ? dirname(configPath) : projectPath);
-}
-/**
- * Merge build-root contributions into a discovered entity set — the exact
- * merge `build()` performs (one implementation: `mergeBuildRootEntities`,
- * ../../build.ts), surfaced in the graph command's error style. Returns false
- * when a contributor failed or a name collided; the caller stops, matching
- * how the discover-based paths treat discovery errors — a graph missing the
- * entities the build would refuse over must not be emitted as if complete.
- */
-async function mergeGraphBuildRoots(entities, contributors) {
-    if (contributors.length === 0)
-        return true;
-    const merged = await mergeBuildRootEntities(entities, contributors);
-    for (const w of merged.warnings)
-        console.error(formatWarning({ message: w }));
-    if (merged.errors.length > 0) {
-        for (const message of merged.errors)
-            console.error(formatError({ message }));
-        return false;
-    }
-    return true;
-}
 /** #1675 — join git-root ops into a discovered entity map; op-discovery
  * errors are warnings here (the lint gate never saw those files). */
 async function mergeGraphOps(entities, sourceFiles, projectPath) {
@@ -165,6 +114,15 @@ async function runGraphCommand(ctx) {
         }));
         return 1;
     }
+    // The capability view (#4378) is built from the declared entity graph's IR,
+    // the read `chant workspace graph --capability-view` asks each member for.
+    if (ctx.args.capabilityView && (ctx.args.format !== "ir" || ctx.args.components || ctx.args.live || ctx.args.at)) {
+        console.error(formatError({
+            message: "--capability-view adds the capability view to the declared graph's IR, so it needs --format ir and takes no --components, --live or --at",
+            hint: "chant graph --format ir --detail 3 --capability-view",
+        }));
+        return 1;
+    }
     // `--at` graphs a recorded observation instead of reading the estate (#1279).
     // Two different observations with no rule for which wins, so not both.
     if (ctx.args.at && ctx.args.live) {
@@ -300,6 +258,8 @@ async function runGraphLive(ctx, format) {
         console.error(formatWarning({ message: endpointResult.notice }));
     let ir;
     let observations;
+    // Facts about absent entities (#4372), carried onto the overlay's nodes.
+    let annotations;
     // A replay is a graph of what was recorded, so it must not reach the provider
     // at all — not for observation and not for enrichment. Anything that quietly
     // called out would make `--at` a live read with an older label on it.
@@ -329,6 +289,7 @@ async function runGraphLive(ctx, format) {
                 ...(args.namespace ? { namespace: args.namespace } : {}),
             });
             observations = observeResult.observations;
+            annotations = observeResult.annotations;
             const { errors, warnings, notes = [] } = observeResult;
             for (const e of errors)
                 console.error(formatWarning({ message: e }));
@@ -443,6 +404,10 @@ async function runGraphLive(ctx, format) {
                         : sourceOverlayGraphs(declaredIr, ir, overlayOpts);
             }
         }
+        // What a read learned about an entity it found absent (#4372), on the
+        // declared node beside the overlay's `_status`. A planned create keeps its
+        // pending paint and carries the plan's attributes.
+        ir = { ...ir, nodes: carryAnnotations(ir.nodes, annotations) };
     }
     // Behaviour overlay (#2377, epic #2355): carry a prediction on the graph.
     // After the drift overlay so it lands on the final node set beside `_status`,
@@ -544,6 +509,55 @@ function refuseLintGate(lint, projectPath) {
         message: "Refusing to emit graph: source has lint errors. Run `chant lint` and fix them first.",
     }));
 }
+/** The project's `graph.lint`: `"report"` only when it says so (#919). */
+async function graphLintMode(projectPath) {
+    const { config } = await loadChantConfigUpward(projectPath).catch(() => ({ config: {} }));
+    return config.graph?.lint === "report" ? "report" : "gate";
+}
+export function graphLintReport(lint, projectPath) {
+    const rel = (file) => {
+        if (!isAbsolute(file))
+            return file;
+        const r = relative(projectPath, file);
+        return r.startsWith("..") ? file : r;
+    };
+    const findings = (lint.diagnostics ?? []).map((d) => ({
+        ruleId: d.ruleId,
+        severity: d.severity,
+        message: d.message,
+        file: rel(d.file),
+        line: d.line,
+        column: d.column,
+        ...(d.entity ? { entity: d.entity } : {}),
+    }));
+    return {
+        errors: findings.filter((f) => f.severity === "error").length,
+        warnings: findings.filter((f) => f.severity === "warning").length,
+        findings,
+    };
+}
+/**
+ * The lint gate for the entity graph. Returns false when the graph must not be
+ * emitted, having printed why. A `graph.lint: "report"` project passes with
+ * lint errors and says so on stderr, unless an error is an uninstalled
+ * dependency: then there is no source to read, and it refuses as the gate does.
+ */
+function passLintGate(lint, projectPath, mode) {
+    if (lint.success)
+        return true;
+    if (mode === "gate") {
+        refuseLintGate(lint, projectPath);
+        return false;
+    }
+    const errors = (lint.diagnostics ?? []).filter((d) => d.severity === "error").map((d) => d.message);
+    if (reportUninstalledDependencies(errors, projectPath))
+        return false;
+    const n = errors.length;
+    console.error(formatWarning({
+        message: `Emitting the graph with ${n} lint error${n === 1 ? "" : "s"}: graph.lint is "report", so every finding is on the IR's meta.lint. Run \`chant lint\` to see them.`,
+    }));
+    return true;
+}
 /**
  * `chant graph --components --format ir|mermaid|dot|layout` — the component DAG
  * projected into the renderable IR (nodes = components, `groups.byWave` = the
@@ -673,7 +687,9 @@ async function buildPipelineProjection(projectPath, lexicon, sandbox) {
  * `--node-sizes` so spacing fits real node footprints, and defaults to the dagre
  * engine (no native dependency); `--layout-engine graphviz` opts into `dot`.
  * Lint-gated: the IR represents valid infra, so we refuse to emit for source that
- * does not pass lint. Non-zero on discovery errors or a layout-engine failure.
+ * does not pass lint, unless the project's config sets `graph.lint: "report"`
+ * (#919): then the graph is emitted and the findings ride on `meta.lint`.
+ * Non-zero on discovery errors or a layout-engine failure.
  */
 /**
  * Add what the lexicons' `graphMeta` hooks report to `ir.meta` (#2559). A
@@ -696,28 +712,6 @@ function withGraphMeta(ir, plugins, entities) {
     }
     return Object.keys(added).length === 0 ? ir : { ...ir, meta: { ...(ir.meta ?? {}), ...added } };
 }
-/**
- * Add the edges the lexicons' `graphEdges` hooks resolve (#3910): CI
- * dependencies written as strings (`needs`, `uses:`, `trigger:`, `include:`,
- * `extends`), which the AttrRef walk in `buildGraphIr` cannot see. A hook that
- * throws costs its own edges and a warning, not the graph.
- */
-function withLexiconEdges(ir, plugins, entities) {
-    const reports = [];
-    for (const p of plugins) {
-        if (!p.graphEdges)
-            continue;
-        try {
-            const report = p.graphEdges(entities);
-            if (report)
-                reports.push(report);
-        }
-        catch (err) {
-            console.error(formatWarning({ message: `the ${p.name} lexicon's graphEdges failed (${err instanceof Error ? err.message : String(err)}); its edges are left out` }));
-        }
-    }
-    return reports.length === 0 ? ir : applyLexiconGraphEdges(ir, reports);
-}
 /**
  * Add the outputs the lexicons' `workspaceOutputs` hooks report (#3931) to
  * the IR's `exports`: a sql table and each of its columns, which `chant
@@ -821,17 +815,17 @@ async function runGraphView(ctx, format) {
     const buildParams = await graphBuildParams(ctx, projectPath);
     if (!buildParams)
         return 1;
-    // Gate: only emit for lint-clean source.
+    // Gate: only emit for lint-clean source, unless the project reads source it
+    // did not author and asks for the findings instead (`graph.lint`, #919).
     const lint = await lintCommand({
         path: ctx.args.path,
         format: "stylish",
         sandbox: ctx.args.sandbox,
         buildParams,
     });
-    if (!lint.success) {
-        refuseLintGate(lint, projectPath);
+    const lintMode = await graphLintMode(projectPath);
+    if (!passLintGate(lint, projectPath, lintMode))
         return 1;
-    }
     const result = await discover(projectPath, { buildParams });
     if (result.errors.length > 0) {
         for (const e of result.errors)
@@ -854,10 +848,10 @@ async function runGraphView(ctx, format) {
     // The declared half of the epic's delta (#2355): this path predicts the
     // file, the live path predicts the account. Same helper, so the two shapes
     // reach the engine by one route and stay comparable.
+    const plugins = ctx.plugins.length > 0
+        ? ctx.plugins
+        : await loadPlugins(await projectLexiconsOrNone(projectPath));
     {
-        const plugins = ctx.plugins.length > 0
-            ? ctx.plugins
-            : await loadPlugins(await projectLexiconsOrNone(projectPath));
         ir = withLexiconEdges(ir, plugins, result.entities);
         ir = withLexiconOutputs(ir, plugins, result.entities);
         const predicted = await predictOntoIr(ir, plugins, ctx.args, {
@@ -894,6 +888,18 @@ async function runGraphView(ctx, format) {
                 console.error(formatWarning({ message: notice }));
         }
     }
+    // Last, so no lens or detail pass can drop it: the findings are about the
+    // whole source read, not about the nodes this view kept.
+    if (lintMode === "report")
+        ir = { ...ir, meta: { ...ir.meta, lint: graphLintReport(lint, projectPath) } };
+    // The view capability rules read (#4378), mapped by this project's own
+    // lexicons, so a workspace's rules read each member as its chant maps it.
+    if (ctx.args.capabilityView) {
+        const { buildView, serializeView } = await import("../../capabilities/view.js");
+        const { resolvePacks } = await import("../../capabilities/catalog.js");
+        const packs = plugins.map((p) => p.capabilityPack).filter((p) => !!p);
+        ir = { ...ir, capabilityView: serializeView(buildView(ir, resolvePacks(packs))) };
+    }
     return emitIr(ir, ctx, format);
 }
 /** Emit a built IR in the requested view format — shared by the source

package/dist/cli/handlers/pr-env.d.ts

@@ -25,8 +25,14 @@
  * `down` reads the environment's record on chant/lifecycle, checks it names
  * this pull request's environment, and tears down what `planTeardown` finds
  * under the record's marker, after dropping any entry whose marker is not
- * exactly that one. No gate holds it: closing the pull request is the
- * decision, as is the TTL the base set for `sweep`.
+ * exactly that one. The lexicons tear down what they own, and the command
+ * `ci.prEnvironment.teardown` names tears down the rest (#4330). No gate
+ * holds it: closing the pull request is the decision, as is the TTL the base
+ * set for `sweep`.
+ *
+ * The runs themselves are ../../components/pr-env-run.ts, which a product
+ * calls with an adapter of its own (#4330). This file supplies the
+ * components adapter and the CLI's ports.
  */
 import type { CommandContext } from "../registry.js";
 /** chant components pr-env <up|down|sweep> */

package/dist/cli/handlers/pr-env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pr-env.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/pr-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AA0CH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AASlD,8CAA8C;AAC9C,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAO7E"}
+{"version":3,"file":"pr-env.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/pr-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AA0CH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAUlD,8CAA8C;AAC9C,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAO7E"}