@intentius/chant 0.28.0 → 0.30.0

package/src/cli/handlers/graph.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect, vi, beforeEach } from "vitest";
+import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
 import type { ParsedArgs } from "../registry";
 import { DECLARABLE_MARKER, type Declarable } from "../../declarable";
 import { AttrRef } from "../../attrref";
@@ -19,8 +19,10 @@ vi.mock("../commands/lint", () => ({
 }));
 
 const componentGraphMock = vi.fn();
+const generatePipelineMock = vi.fn();
 vi.mock("../../components/cli-support", () => ({
   computeComponentGraph: () => componentGraphMock(),
+  generateComponentsPipeline: (...a: unknown[]) => generatePipelineMock(...a),
 }));
 
 // Avoid running a real layout engine in tests; the format dispatch + size/engine
@@ -52,9 +54,14 @@ const discoverComponentsMock = vi.fn();
 vi.mock("../../components/discover", () => ({
   discoverComponents: (...a: unknown[]) => discoverComponentsMock(...a),
 }));
-vi.mock("../../config", () => ({
-  loadChantConfig: () => Promise.resolve({ config: {} }),
-}));
+const loadChantConfigMock = vi.fn();
+vi.mock("../../config", async () => {
+  const actual = await vi.importActual<typeof import("../../config")>("../../config");
+  return {
+    ...actual,
+    loadChantConfig: (...a: unknown[]) => loadChantConfigMock(...a),
+  };
+});
 vi.mock("../../build", () => ({
   build: () => Promise.resolve({ errors: [] }),
   partitionByLexicon: () => ({}),
@@ -101,12 +108,15 @@ describe("runGraph", () => {
     lintMock.mockReset();
     layoutMock.mockReset();
     componentGraphMock.mockReset();
+    generatePipelineMock.mockReset();
     discoverComponentsMock.mockReset();
     // Default: no components — the single-stack --live path most tests exercise.
     discoverComponentsMock.mockResolvedValue({ components: new Map(), sourceFiles: [], errors: [] });
     observeMock.mockReset();
     loadPluginsMock.mockReset();
     resolveLexMock.mockReset();
+    loadChantConfigMock.mockReset();
+    loadChantConfigMock.mockResolvedValue({ config: {} });
   });
 
   describe("Op graph (default)", () => {
@@ -318,6 +328,89 @@ describe("runGraph", () => {
       expect(exit).toBe(1);
       expect(stderrBuf.join("\n")).toContain("cycle: a ↔ b");
     });
+
+    describe("CI/pipeline projection (--projection, #989)", () => {
+      test("rejects --projection without --components --format ir", async () => {
+        const exit = await runGraph({ args: makeArgs({ projection: "gitlab" }), plugins: [], serializers: [] });
+        expect(exit).toBe(1);
+        expect(stderrBuf.join("\n")).toMatch(/--projection needs --components --format ir/);
+        expect(componentGraphMock).not.toHaveBeenCalled();
+      });
+
+      test("rejects --projection with --components --format mermaid", async () => {
+        const exit = await runGraph({
+          args: makeArgs({ projection: "gitlab", components: true, format: "mermaid" }),
+          plugins: [],
+          serializers: [],
+        });
+        expect(exit).toBe(1);
+        expect(stderrBuf.join("\n")).toMatch(/--projection needs --components --format ir/);
+      });
+
+      test("--components --format ir --projection gitlab adds ir.pipeline, reusing generateComponentsPipeline", async () => {
+        lintMock.mockResolvedValue({ success: true });
+        componentGraphClean();
+        generatePipelineMock.mockResolvedValue({
+          success: true,
+          stages: ["wave-1", "wave-2", "wave-3"],
+          jobs: [
+            { jobName: "shared-foundation", component: "shared-foundation", stage: "wave-1", needs: [] },
+            { jobName: "loom-db", component: "loom-db", stage: "wave-2", needs: ["shared-foundation"] },
+            { jobName: "loom-backend", component: "loom-backend", stage: "wave-3", needs: ["loom-db"] },
+          ],
+          yaml: "stages: [...]\n",
+        });
+
+        const exit = await runGraph({
+          args: makeArgs({ format: "ir", components: true, projection: "gitlab" }),
+          plugins: [],
+          serializers: [],
+        });
+        expect(exit).toBe(0);
+
+        // Reuses the same generator `build --components --generate` calls —
+        // never re-derives stages/jobs/needs itself.
+        expect(generatePipelineMock).toHaveBeenCalledWith(expect.any(String), "gitlab", undefined, undefined);
+
+        const ir = JSON.parse(stdoutBuf.join("\n"));
+        // The component graph itself is untouched by the projection.
+        expect(ir.nodes.map((n: { id: string }) => n.id)).toEqual(["shared-foundation", "loom-db", "loom-backend"]);
+        expect(ir.groups.byWave["wave-2"]).toEqual(["loom-db"]);
+
+        // The CI/pipeline projection sits alongside it as first-class IR nodes/edges.
+        expect(ir.pipeline.provider).toBe("gitlab");
+        expect(ir.pipeline.stages).toEqual(["wave-1", "wave-2", "wave-3"]);
+        expect(ir.pipeline.nodes).toEqual([
+          { id: "shared-foundation", kind: "CIJob", component: "shared-foundation", stage: "wave-1" },
+          { id: "loom-db", kind: "CIJob", component: "loom-db", stage: "wave-2" },
+          { id: "loom-backend", kind: "CIJob", component: "loom-backend", stage: "wave-3" },
+        ]);
+        // `needs:` edges, consumer job → producer job (mirrors the component
+        // graph's consumer → producer convention).
+        expect(ir.pipeline.edges).toEqual([
+          { from: "loom-db", to: "shared-foundation", kind: "needs" },
+          { from: "loom-backend", to: "loom-db", kind: "needs" },
+        ]);
+      });
+
+      test("an unsupported --projection lexicon fails the whole graph command", async () => {
+        lintMock.mockResolvedValue({ success: true });
+        componentGraphClean();
+        generatePipelineMock.mockResolvedValue({
+          success: false,
+          error: 'Lexicon "bogus" does not support generate mode (no generateComponentPipeline).',
+        });
+
+        const exit = await runGraph({
+          args: makeArgs({ format: "ir", components: true, projection: "bogus" }),
+          plugins: [],
+          serializers: [],
+        });
+        expect(exit).toBe(1);
+        expect(stderrBuf.join("\n")).toContain("does not support generate mode");
+        expect(stdoutBuf.join("\n")).toBe("");
+      });
+    });
   });
 
   describe("live graph (--live)", () => {
@@ -332,6 +425,7 @@ describe("runGraph", () => {
       observeMock.mockResolvedValue({
         observations: [{ lexicon: "aws", resources: { "web-vpc": { type: "AWS::EC2::VPC", status: "OK" } } }],
         errors: [],
+        warnings: [],
       });
       const exit = await runGraph({ args: makeArgs({ format: "ir", live: true, env: "prod" }), plugins: [], serializers: [] });
       expect(exit).toBe(0);
@@ -349,7 +443,7 @@ describe("runGraph", () => {
       loadPluginsMock.mockResolvedValue([
         { name: "aws", serializer: {}, describeResources: () => Promise.resolve({}) },
       ]);
-      observeMock.mockResolvedValue({ observations: [], errors: [] });
+      observeMock.mockResolvedValue({ observations: [], errors: [], warnings: [] });
       const exit = await runGraph({ args: makeArgs({ format: "ir", live: true, env: "prod" }), plugins: [], serializers: [] });
       expect(exit).toBe(0);
       expect(observeMock).toHaveBeenCalledWith("prod", expect.anything(), expect.anything(), {
@@ -390,6 +484,7 @@ describe("runGraph", () => {
       observeMock.mockResolvedValue({
         observations: [{ lexicon: "aws", resources: { "loom-db": { type: "AWS::RDS::DBInstance", status: "OK" } } }],
         errors: [],
+        warnings: [],
       });
       const exit = await runGraph({ args: makeArgs({ format: "ir", live: true, env: "local" }), plugins: [], serializers: [] });
       expect(exit).toBe(0);
@@ -409,7 +504,7 @@ describe("runGraph", () => {
         { name: "aws", serializer: {}, describeResources: () => Promise.resolve({}) },
       ]);
       discoverComponentsMock.mockResolvedValue({ errors: [{ message: "bad component" }], sourceFiles: [], components: new Map() });
-      observeMock.mockResolvedValue({ observations: [], errors: [] });
+      observeMock.mockResolvedValue({ observations: [], errors: [], warnings: [] });
       const exit = await runGraph({ args: makeArgs({ format: "ir", live: true, env: "prod" }), plugins: [], serializers: [] });
       expect(exit).toBe(0);
       expect(observeMock).toHaveBeenCalledWith("prod", expect.anything(), expect.anything(), {
@@ -418,5 +513,59 @@ describe("runGraph", () => {
       });
       expect(stderrBuf.join("\n")).toMatch(/component discovery failed/i);
     });
+
+    // #1166 — an environment can declare its own endpoint (a local emulator
+    // like Floci), so `--live --env floci` observes the right target even when
+    // the ambient shell never exported AWS_ENDPOINT_URL.
+    describe("declared endpoint (#1166)", () => {
+      const prevEndpoint = process.env.AWS_ENDPOINT_URL;
+
+      afterEach(() => {
+        if (prevEndpoint === undefined) delete process.env.AWS_ENDPOINT_URL;
+        else process.env.AWS_ENDPOINT_URL = prevEndpoint;
+      });
+
+      test("applies the declared endpoint to AWS_ENDPOINT_URL for the observe call, then restores it", async () => {
+        delete process.env.AWS_ENDPOINT_URL;
+        loadChantConfigMock.mockResolvedValue({
+          config: { environments: [{ name: "floci", endpoint: "http://localhost:4566" }] },
+        });
+        resolveLexMock.mockResolvedValue(["aws"]);
+        loadPluginsMock.mockResolvedValue([
+          { name: "aws", serializer: {}, describeResources: () => Promise.resolve({}) },
+        ]);
+        let seenDuringObserve: string | undefined;
+        observeMock.mockImplementation(async () => {
+          seenDuringObserve = process.env.AWS_ENDPOINT_URL;
+          return { observations: [], errors: [], warnings: [] };
+        });
+        const exit = await runGraph({ args: makeArgs({ format: "ir", live: true, env: "floci" }), plugins: [], serializers: [] });
+        expect(exit).toBe(0);
+        expect(seenDuringObserve).toBe("http://localhost:4566");
+        expect(process.env.AWS_ENDPOINT_URL).toBeUndefined(); // restored after the read
+        expect(stderrBuf.join("\n")).toMatch(/environment "floci" declares endpoint http:\/\/localhost:4566/);
+      });
+
+      test("ambient AWS_ENDPOINT_URL still wins when already set", async () => {
+        process.env.AWS_ENDPOINT_URL = "http://real-endpoint.example";
+        loadChantConfigMock.mockResolvedValue({
+          config: { environments: [{ name: "floci", endpoint: "http://localhost:4566" }] },
+        });
+        resolveLexMock.mockResolvedValue(["aws"]);
+        loadPluginsMock.mockResolvedValue([
+          { name: "aws", serializer: {}, describeResources: () => Promise.resolve({}) },
+        ]);
+        let seenDuringObserve: string | undefined;
+        observeMock.mockImplementation(async () => {
+          seenDuringObserve = process.env.AWS_ENDPOINT_URL;
+          return { observations: [], errors: [], warnings: [] };
+        });
+        const exit = await runGraph({ args: makeArgs({ format: "ir", live: true, env: "floci" }), plugins: [], serializers: [] });
+        expect(exit).toBe(0);
+        expect(seenDuringObserve).toBe("http://real-endpoint.example"); // ambient wins
+        expect(process.env.AWS_ENDPOINT_URL).toBe("http://real-endpoint.example"); // untouched
+        expect(stderrBuf.join("\n")).toMatch(/ambient AWS_ENDPOINT_URL already set/);
+      });
+    });
   });
 });

package/src/cli/handlers/graph.ts

@@ -2,10 +2,11 @@ import { resolve } from "node:path";
 import { discoverOps } from "../../op/discover";
 import { discover } from "../../discovery/index";
 import { partitionByLexicon, computeStackGraph, build } from "../../build";
-import { buildGraphIr, buildLiveGraphIr, overlayGraphs, sourceOverlayGraphs, type GraphIR } from "../../graph-ir";
+import { buildGraphIr, buildLiveGraphIr, collectUnobserved, overlayGraphs, sourceOverlayGraphs, type GraphIR, type IRPipeline, type LiveObservation } from "../../graph-ir";
 import { reconstructEdges, mergeCatalogs, containmentGroups, type ReferenceCatalog, type ContainmentPair } from "../../graph-refs";
 import { observeResources } from "../../lifecycle/observe";
-import { loadChantConfig } from "../../config";
+import { loadChantConfig, environmentNames } from "../../config";
+import { applyLiveEndpoint } from "../../live-endpoint";
 import { applyDetail, type DetailLevel } from "../../graph-detail";
 import { applyLens, parseLens } from "../../graph-lens";
 import { toMermaid } from "../../graph-mermaid";
@@ -16,7 +17,7 @@ import { loadPlugins, resolveProjectLexicons } from "../plugins";
 import { readFileSync } from "node:fs";
 import { formatError, formatWarning, formatBold } from "../format";
 import type { CommandContext } from "../registry";
-import { computeComponentGraph } from "../../components/cli-support";
+import { computeComponentGraph, generateComponentsPipeline } from "../../components/cli-support";
 import { discoverComponents } from "../../components/discover";
 import { cfnDeployStacks } from "./components";
 
@@ -33,6 +34,18 @@ import { cfnDeployStacks } from "./components";
 export async function runGraph(ctx: CommandContext): Promise<number> {
   const viewFormats = ["ir", "mermaid", "dot", "layout"] as const;
   const isViewFormat = (viewFormats as readonly string[]).includes(ctx.args.format);
+  // `--projection <lexicon>` (#989) only means anything for the component
+  // graph's IR — it adds the CI/pipeline shape to `GraphIR.pipeline`, a field
+  // the other view formats' emitters (mermaid/dot/layout) don't read, and the
+  // plain (non-`--format`) `--components` text/`--json` modes don't build an
+  // IR at all. Reject every other combination up front rather than silently
+  // ignoring the flag.
+  if (ctx.args.projection && !(ctx.args.components && ctx.args.format === "ir")) {
+    console.error(formatError({
+      message: "--projection needs --components --format ir — the CI/pipeline projection extends the component-graph IR, the only mode that carries it.",
+    }));
+    return 1;
+  }
   // `--live` graphs the provisioned (observed) infrastructure, not the declared
   // source (epic #776). It only makes sense as a view format; default to `ir`.
   if (ctx.args.live) {
@@ -76,10 +89,11 @@ async function runGraphLive(
   // lexicon), so `ctx.plugins` is empty. The live path needs the project's
   // observation plugins — load them here, mirroring the lifecycle handlers.
   const plugins = ctx.plugins.length > 0 ? ctx.plugins : await loadPlugins(await resolveProjectLexicons(projectPath));
-  if (config.environments && !config.environments.includes(environment)) {
+  const declaredEnvNames = environmentNames(config.environments);
+  if (declaredEnvNames && !declaredEnvNames.includes(environment)) {
     console.error(formatError({
       message: `Unknown environment "${environment}"`,
-      hint: `Defined environments: ${config.environments.join(", ")}`,
+      hint: `Defined environments: ${declaredEnvNames.join(", ")}`,
     }));
     return 1;
   }
@@ -121,30 +135,58 @@ async function runGraphLive(
     console.error(formatWarning({ message: "component discovery failed — observing the single-stack convention instead" }));
   }
 
-  const { observations, errors } = await observeResources(environment, observing, buildResult, {
-    owned: true,
-    stacks: [...stacks],
-  });
-  for (const e of errors) console.error(formatWarning({ message: e }));
+  // #1166 — an environment can declare its own endpoint (a local emulator like
+  // Floci), so this read is self-sufficient even when the ambient shell never
+  // exported e.g. AWS_ENDPOINT_URL. Ambient always wins when it's already set.
+  // Scoped to just this describe/enrich pass — restored in `finally` so it
+  // never leaks into a later invocation in the same process.
+  const endpointResult = applyLiveEndpoint(config.environments, environment, observing.map((p) => p.name));
+  if (endpointResult.notice) console.error(formatWarning({ message: endpointResult.notice }));
+
+  let ir: GraphIR;
+  let observations: LiveObservation[];
+  try {
+    const observeResult = await observeResources(environment, observing, buildResult, {
+      owned: true,
+      stacks: [...stacks],
+    });
+    observations = observeResult.observations;
+    const { errors, warnings } = observeResult;
+    for (const e of errors) console.error(formatWarning({ message: e }));
+    // Unobserved entities (#1089) arrive as warnings — a node missing from the
+    // live graph because nobody looked is a different fact from one that isn't
+    // deployed, and the diagram alone cannot say which. Capped: an estate with no
+    // ownership markers can produce one per declared entity, and a wall of them
+    // buries the graph output. The full list is `lifecycle diff --live`.
+    const WARN_CAP = 5;
+    for (const w of warnings.slice(0, WARN_CAP)) console.error(formatWarning({ message: w }));
+    if (warnings.length > WARN_CAP) {
+      console.error(formatWarning({
+        message: `... and ${warnings.length - WARN_CAP} more entity(ies) not observed — run \`chant lifecycle diff ${environment} --live\` for the full list`,
+      }));
+    }
 
-  let ir: GraphIR = buildLiveGraphIr(observations);
+    ir = buildLiveGraphIr(observations);
 
-  // Enrich node attrs from the fuller live config (#784) so references are
-  // present for edge reconstruction — describeResources metadata alone is often
-  // too thin (e.g. AWS returns stack outputs, not per-resource references).
-  for (const p of observing) {
-    if (!p.enrichLiveAttrs) continue;
-    try {
-      const enriched = await p.enrichLiveAttrs({ environment, owned: true });
-      ir = {
-        ...ir,
-        nodes: ir.nodes.map((n) =>
-          n.lexicon === p.name && enriched[n.id] ? { ...n, attrs: { ...n.attrs, ...enriched[n.id] } } : n,
-        ),
-      };
-    } catch (err) {
-      console.error(formatWarning({ message: `${p.name}: live attr enrichment failed — edges may be sparse (${err instanceof Error ? err.message : String(err)})` }));
+    // Enrich node attrs from the fuller live config (#784) so references are
+    // present for edge reconstruction — describeResources metadata alone is often
+    // too thin (e.g. AWS returns stack outputs, not per-resource references).
+    for (const p of observing) {
+      if (!p.enrichLiveAttrs) continue;
+      try {
+        const enriched = await p.enrichLiveAttrs({ environment, owned: true });
+        ir = {
+          ...ir,
+          nodes: ir.nodes.map((n) =>
+            n.lexicon === p.name && enriched[n.id] ? { ...n, attrs: { ...n.attrs, ...enriched[n.id] } } : n,
+          ),
+        };
+      } catch (err) {
+        console.error(formatWarning({ message: `${p.name}: live attr enrichment failed — edges may be sparse (${err instanceof Error ? err.message : String(err)})` }));
+      }
     }
+  } finally {
+    endpointResult.restore();
   }
 
   // Reconstruct edges + containment from live references (#778): merge the
@@ -166,10 +208,14 @@ async function runGraphLive(
     const declared = await discover(resolve(args.src ?? config.sourceDir ?? "."));
     if (declared.errors.length === 0) {
       const declaredIr = buildGraphIr(declared.entities, projectPath);
+      // Declared nodes chant could not read are painted `neutral`, not
+      // `accent`/pending (#1089) — a wrong-cluster or unsupported-kind read
+      // must not draw the estate as "not deployed yet".
+      const overlayOpts = { unobserved: collectUnobserved(observations) };
       ir =
         args.overlayAnchor === "live"
-          ? overlayGraphs(ir, declaredIr)
-          : sourceOverlayGraphs(declaredIr, ir);
+          ? overlayGraphs(ir, declaredIr, overlayOpts)
+          : sourceOverlayGraphs(declaredIr, ir, overlayOpts);
     } else {
       console.error(formatWarning({ message: "overlay: source has discovery errors — showing the provisioned graph without the declared overlay" }));
     }
@@ -247,6 +293,15 @@ async function runComponentGraph(ctx: CommandContext): Promise<number> {
  * the CI pipeline. Distinct from `runGraphView`, which emits the AWS *entity*
  * graph — the component projection has one node per component, not per resource.
  *
+ * `--projection <lexicon>` (#989, `--format ir` only — validated in `runGraph`)
+ * adds the **CI/pipeline projection** alongside this component graph:
+ * `ir.pipeline` carries the stages/jobs/`needs` `<lexicon>`'s
+ * `generateComponentPipeline` synthesizes for `chant build --components
+ * --generate <lexicon>` (`generateComponentsPipeline`, ../../components/cli-support.ts)
+ * — reused wholesale, not re-derived, so a consumer (e.g. behold, epic #492/
+ * INTENTIUS/behold#54) gets the pipeline shape as first-class IR nodes/edges
+ * instead of re-deriving it from `dependsOn` or parsing generated CI YAML.
+ *
  * Lint-gated like the entity view: the DAG stands for deployable source, so we
  * refuse to emit it for source that does not pass lint.
  */
@@ -278,7 +333,7 @@ async function runComponentGraphView(
   const waveOf = new Map<string, number>();
   graph.waves.forEach((wave, i) => wave.forEach((name) => waveOf.set(name, i + 1)));
 
-  const ir: GraphIR = {
+  let ir: GraphIR = {
     nodes: graph.order.map((name) => ({
       id: name,
       kind: "Component",
@@ -293,9 +348,49 @@ async function runComponentGraphView(
     },
   };
 
+  if (ctx.args.projection) {
+    const pipeline = await buildPipelineProjection(projectPath, ctx.args.projection, ctx.args.sandbox);
+    if (!pipeline.success) {
+      console.error(formatError({ message: pipeline.error ?? `Failed to generate ${ctx.args.projection} pipeline projection` }));
+      return 1;
+    }
+    ir = { ...ir, pipeline: pipeline.pipeline };
+  }
+
   return emitIr(ir, ctx, format);
 }
 
+/**
+ * Reshape `generateComponentsPipeline`'s result (../../components/cli-support.ts
+ * — the exact function `chant build --components --generate <lexicon>` calls)
+ * into the IR's `IRPipeline` vocabulary (#989): one `IRPipelineNode` per
+ * generated CI job, one `IRPipelineEdge` per `needs:` dependency (consumer job
+ * → producer job, mirroring the component edges' consumer → producer
+ * direction). Every shape decision — job naming, one stage per wave,
+ * dependency resolution — stays owned by `lexicon`'s `generateComponentPipeline`;
+ * this only relabels its `{ stages, jobs }` output as IR nodes/edges, it never
+ * re-derives the graph.
+ */
+async function buildPipelineProjection(
+  projectPath: string,
+  lexicon: string,
+  sandbox?: boolean,
+): Promise<{ success: true; pipeline: IRPipeline } | { success: false; error?: string }> {
+  const result = await generateComponentsPipeline(projectPath, lexicon, undefined, sandbox);
+  if (!result.success) return { success: false, error: result.error };
+
+  const jobs = result.jobs ?? [];
+  return {
+    success: true,
+    pipeline: {
+      provider: lexicon,
+      stages: result.stages ?? [],
+      nodes: jobs.map((j) => ({ id: j.jobName, kind: "CIJob" as const, component: j.component, stage: j.stage })),
+      edges: jobs.flatMap((j) => j.needs.map((dep) => ({ from: j.jobName, to: dep, kind: "needs" as const }))),
+    },
+  };
+}
+
 /**
  * `chant graph --format ir|mermaid|dot|layout` — build the graph IR (honouring
  * `--detail`) and emit it as JSON, a Mermaid flowchart, Graphviz DOT, or node