@intentius/chant 0.1.17 → 0.1.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/build.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect, beforeEach, afterEach } from "vitest";
-import { build, partitionByLexicon, detectCrossLexiconRefs, collectLexiconOutputs } from "./build";
+import { build, partitionByLexicon, detectCrossLexiconRefs, collectLexiconOutputs, computeStackGraph } from "./build";
 import { output } from "./lexicon-output";
 import { AttrRef } from "./attrref";
 import { INTRINSIC_MARKER } from "./intrinsic";
@@ -462,3 +462,50 @@ describe("detectCrossLexiconRefs", () => {
     expect(detected[0].outputName).toBe("dataBucket_Endpoint");
   });
 });
+
+describe("computeStackGraph (#200 — cross-stack apply ordering)", () => {
+  const ent = (lexicon: string, props: Record<string, unknown> = {}): Declarable =>
+    ({ lexicon, entityType: `${lexicon}::X`, [DECLARABLE_MARKER]: true, props }) as unknown as Declarable;
+
+  test("infers a consumer→producer edge from a cross-lexicon AttrRef", () => {
+    const vpc = ent("aws");
+    const svc = ent("k8s", { vpcId: new AttrRef(vpc, "id") });
+    const g = computeStackGraph(new Map([["vpc", vpc], ["svc", svc]]), ["aws", "k8s"]);
+
+    expect(g.edges).toEqual([{ from: "k8s", to: "aws" }]);
+    expect(g.order).toEqual(["aws", "k8s"]); // producer before consumer
+    expect(g.waves).toEqual([["aws"], ["k8s"]]); // separate waves — ordered
+    expect(g.cycles).toEqual([]);
+  });
+
+  test("independent stacks share a wave (parallel-safe)", () => {
+    const g = computeStackGraph(new Map([["a", ent("aws")], ["b", ent("gcp")]]), ["aws", "gcp"]);
+    expect(g.edges).toEqual([]);
+    expect(g.waves).toEqual([["aws", "gcp"]]); // one wave — no inter-dependency
+  });
+
+  test("reports a dependency cycle", () => {
+    const a = ent("x");
+    const b = ent("y", { ref: new AttrRef(a, "out") });
+    // close the loop: a references b
+    (a as unknown as { props: Record<string, unknown> }).props = { ref: new AttrRef(b, "out") };
+    const g = computeStackGraph(new Map([["a", a], ["b", b]]), ["x", "y"]);
+
+    expect(g.edges).toEqual(expect.arrayContaining([{ from: "x", to: "y" }, { from: "y", to: "x" }]));
+    expect(g.cycles).toEqual([["x", "y"]]);
+    expect(g.order).toEqual([]); // nothing is orderable inside a cycle
+  });
+
+  test("a diamond resolves into three waves", () => {
+    // base ← (left, right) ← top
+    const base = ent("base");
+    const left = ent("left", { b: new AttrRef(base, "id") });
+    const right = ent("right", { b: new AttrRef(base, "id") });
+    const top = ent("top", { l: new AttrRef(left, "id"), r: new AttrRef(right, "id") });
+    const g = computeStackGraph(
+      new Map([["base", base], ["left", left], ["right", right], ["top", top]]),
+      ["base", "left", "right", "top"],
+    );
+    expect(g.waves).toEqual([["base"], ["left", "right"], ["top"]]);
+  });
+});

package/src/build.ts

@@ -20,6 +20,115 @@ export interface BuildManifest {
     { source: string; entity: string; attribute: string }
   >;
   deployOrder: string[];
+  /** Cross-stack apply-ordering graph (see {@link computeStackGraph}). */
+  stackGraph: StackGraph;
+}
+
+/**
+ * The cross-stack (cross-lexicon) apply-ordering graph chant already computes
+ * while resolving cross-lexicon references — surfaced as tool-agnostic data for
+ * an orchestrator to consume. chant exposes the order; it does not drive the
+ * apply.
+ */
+export interface StackGraph {
+  /** Stacks (lexicon partitions) in the build. */
+  nodes: string[];
+  /**
+   * Consumer→producer edges: `from` imports a value `to` exports, so `to` must
+   * apply before `from`. Inferred from cross-lexicon references.
+   */
+  edges: Array<{ from: string; to: string }>;
+  /** A flat applicable sequence — every producer before its consumers. */
+  order: string[];
+  /**
+   * Levels: stacks in the same wave have no inter-dependency and may apply
+   * concurrently. `order` flattened with parallelism made explicit.
+   */
+  waves: string[][];
+  /** Dependency cycles, if any (each a list of stacks). Normally empty. */
+  cycles: string[][];
+}
+
+/**
+ * Compute the cross-stack apply-ordering graph from resolved entities. Edges are
+ * inferred from cross-lexicon attribute references (a resource in lexicon A
+ * referencing an attribute of a resource in lexicon B ⇒ A depends on B). Returns
+ * the edge set plus a topological order, parallel-safe waves, and any cycles.
+ */
+export function computeStackGraph(
+  entities: Map<string, Declarable>,
+  lexiconNames: string[],
+): StackGraph {
+  const edges: Array<{ from: string; to: string }> = [];
+  const edgeSet = new Set<string>();
+  const addEdge = (from: string, to: string): void => {
+    if (from === to) return;
+    const key = `${from}\0${to}`;
+    if (edgeSet.has(key)) return;
+    edgeSet.add(key);
+    edges.push({ from, to });
+  };
+
+  const walk = (value: unknown, consumer: string, visited: Set<unknown>): void => {
+    if (value === null || value === undefined || typeof value !== "object") return;
+    if (visited.has(value)) return;
+    visited.add(value);
+    if (value instanceof AttrRef) {
+      const parent = value.parent.deref();
+      const producer = parent ? (parent as Record<string, unknown>).lexicon : undefined;
+      if (typeof producer === "string" && producer !== consumer) addEdge(consumer, producer);
+      return;
+    }
+    if (isLexiconOutput(value)) return;
+    if (Array.isArray(value)) {
+      for (const item of value) walk(item, consumer, visited);
+      return;
+    }
+    for (const val of Object.values(value as Record<string, unknown>)) walk(val, consumer, visited);
+  };
+
+  for (const [, entity] of entities) {
+    const consumer = entity.lexicon;
+    const visited = new Set<unknown>();
+    for (const val of Object.values(entity as unknown as Record<string, unknown>)) {
+      walk(val, consumer, visited);
+    }
+    if ("props" in entity && typeof entity.props === "object" && entity.props !== null) {
+      walk(entity.props, consumer, visited);
+    }
+  }
+
+  // Dependency map: node → producers it depends on.
+  const nodes = lexiconNames.length
+    ? [...lexiconNames]
+    : [...new Set([...entities.values()].map((e) => e.lexicon))];
+  const deps = new Map<string, Set<string>>();
+  for (const n of nodes) deps.set(n, new Set());
+  for (const { from, to } of edges) {
+    if (!deps.has(from)) deps.set(from, new Set());
+    if (!deps.has(to)) deps.set(to, new Set());
+    deps.get(from)!.add(to);
+  }
+
+  // Kahn layering: a node is ready once every producer it depends on is placed.
+  const remaining = new Set(deps.keys());
+  const waves: string[][] = [];
+  const order: string[] = [];
+  while (remaining.size > 0) {
+    const wave = [...remaining]
+      .filter((n) => [...deps.get(n)!].every((d) => !remaining.has(d)))
+      .sort();
+    if (wave.length === 0) break; // remaining nodes form a cycle
+    for (const n of wave) {
+      remaining.delete(n);
+      order.push(n);
+    }
+    waves.push(wave);
+  }
+  const cycles: string[][] = remaining.size > 0 ? [[...remaining].sort()] : [];
+
+  edges.sort((a, b) => `${a.from}\0${a.to}`.localeCompare(`${b.from}\0${b.to}`));
+  return { nodes: [...nodes].sort(), edges, order, waves, cycles };
 }
 
 /**
@@ -288,7 +397,8 @@ function computeDeployOrder(
  */
 function generateManifest(
   lexiconNames: string[],
-  lexiconOutputs: LexiconOutput[]
+  lexiconOutputs: LexiconOutput[],
+  entities: Map<string, Declarable>
 ): BuildManifest {
   const outputsRecord: Record<
     string,
@@ -307,6 +417,7 @@ function generateManifest(
     lexicons: lexiconNames,
     outputs: outputsRecord,
     deployOrder: computeDeployOrder(lexiconNames, lexiconOutputs),
+    stackGraph: computeStackGraph(entities, lexiconNames),
   };
 }
 
@@ -453,7 +564,7 @@ export async function build(
 
   // Step 8: Generate manifest
   const lexiconNames = Array.from(partitions.keys());
-  const manifest = generateManifest(lexiconNames, lexiconOutputs);
+  const manifest = generateManifest(lexiconNames, lexiconOutputs, discoveryResult.entities);
 
   return {
     outputs,

package/src/cli/commands/build.ts

@@ -3,7 +3,7 @@ import { loadChantConfig, resolveOwnershipMarker } from "../../config";
 import type { Serializer, SerializerResult } from "../../serializer";
 import type { LexiconPlugin } from "../../lexicon";
 import { runPostSynthChecks } from "../../lint/post-synth";
-import type { PostSynthCheck } from "../../lint/post-synth";
+import { loadPolicyChecks } from "../../lint/policy";
 import { sortedJsonReplacer } from "../../utils";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
 import { writeFileSync, mkdirSync } from "fs";
@@ -26,8 +26,15 @@ export interface BuildOptions {
   plugins?: LexiconPlugin[];
   /** Print summary to stderr */
   verbose?: boolean;
+  /**
+   * Environment/stack to evaluate policy against (`--env`). Falls back to the
+   * project's `ownership.env`. Passed into post-synth checks so organizational
+   * policy can branch on environment.
+   */
+  env?: string;
 }
 
+
 /**
  * Build command result
  */
@@ -56,11 +63,21 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
 
   // Resolve opt-in ownership marking from project config (search the infra dir
   // and its parent, where chant.config.* usually lives).
-  const { config } = await loadChantConfig(infraPath).then((r) =>
+  const loaded = await loadChantConfig(infraPath).then((r) =>
     r.configPath ? r : loadChantConfig(dirname(infraPath)),
   );
+  const config = loaded.config;
   const ownership = resolveOwnershipMarker(config);
 
+  // Environment for policy evaluation: explicit --env wins, else ownership.env.
+  const env = options.env ?? config.ownership?.env;
+  // Project-authored organizational policy checks (lint.policies), run over the
+  // resolved resources during build. Resolve paths relative to the config dir.
+  const configDir = loaded.configPath ? dirname(loaded.configPath) : infraPath;
+  const policyChecks = config.lint?.policies?.length
+    ? await loadPolicyChecks(config.lint.policies, configDir)
+    : [];
+
   // Run the build
   const result = await build(infraPath, options.serializers, undefined, { ownership });
 
@@ -96,7 +113,7 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
       }
 
       const scopedResult = { ...result, outputs: scopedOutputs };
-      const postDiags = runPostSynthChecks(checks, scopedResult);
+      const postDiags = runPostSynthChecks(checks, scopedResult, env);
       for (const diag of postDiags) {
         const prefix = diag.entity ? `[${diag.entity}] ` : "";
         const lexiconSuffix = diag.lexicon ? ` (${diag.lexicon})` : "";
@@ -107,6 +124,19 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
         }
       }
     }
+
+    // Project-authored organizational policy — cross-cutting, so it sees every
+    // lexicon's output at once (not scoped per-plugin), with the current env.
+    if (policyChecks.length > 0) {
+      const policyDiags = runPostSynthChecks(policyChecks, result, env);
+      for (const diag of policyDiags) {
+        const prefix = diag.entity ? `[${diag.entity}] ` : "";
+        const where = diag.lexicon ? ` (${diag.lexicon})` : "";
+        const msg = `[policy:${diag.checkId}] ${prefix}${diag.message}${where}`;
+        if (diag.severity === "error") errors.push(formatError({ message: msg }));
+        else warnings.push(formatWarning({ message: msg }));
+      }
+    }
   }
 
   // Empty-output guard: source files were discovered but no lexicon produced

package/src/cli/commands/vendor.test.ts

@@ -0,0 +1,148 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  vendorPull,
+  vendorCheck,
+  contentHash,
+  scopeArchiveFiles,
+  loadManifest,
+  MANIFEST_FILE,
+} from "./vendor";
+
+let root: string;
+
+function write(rel: string, content: string): void {
+  const full = join(root, rel);
+  mkdirSync(join(full, ".."), { recursive: true });
+  writeFileSync(full, content);
+}
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "chant-vendor-"));
+  // A local "shared pattern" source.
+  write("shared/web-app/index.ts", "export const WebApp = () => ({});\n");
+  write("shared/web-app/README.md", "# pattern\n");
+  // A project that vendors it.
+  writeFileSync(
+    join(root, MANIFEST_FILE),
+    JSON.stringify({
+      vendored: [
+        { name: "web-app", source: { type: "local", path: "shared/web-app" }, target: "vendor/web-app", ref: "v1" },
+      ],
+    }, null, 2),
+  );
+});
+
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+describe("vendor pull", () => {
+  test("copies the source into target and records a checksum", async () => {
+    const result = await vendorPull(root);
+    expect(result.success).toBe(true);
+    expect(result.pulled[0].fileCount).toBe(2);
+
+    expect(existsSync(join(root, "vendor/web-app/index.ts"))).toBe(true);
+    expect(readFileSync(join(root, "vendor/web-app/README.md"), "utf-8")).toContain("# pattern");
+
+    // Checksum written back into the manifest.
+    const { manifest } = loadManifest(root);
+    expect(manifest.vendored[0].checksum).toMatch(/^sha256:[0-9a-f]{64}$/);
+  });
+
+  test("pull <name> filters to one entry; unknown name fails", async () => {
+    expect((await vendorPull(root, "web-app")).pulled).toHaveLength(1);
+    const miss = await vendorPull(root, "nope");
+    expect(miss.success).toBe(false);
+    expect(miss.output).toContain("nope");
+  });
+
+  test("fails clearly when the local source is missing", async () => {
+    writeFileSync(
+      join(root, MANIFEST_FILE),
+      JSON.stringify({ vendored: [{ name: "x", source: { type: "local", path: "missing" }, target: "vendor/x" }] }),
+    );
+    await expect(vendorPull(root)).rejects.toThrow(/local source not found/);
+  });
+});
+
+describe("vendor check", () => {
+  test("reports ok right after a pull", async () => {
+    await vendorPull(root);
+    const result = vendorCheck(root);
+    expect(result.drift).toBe(false);
+    expect(result.entries[0].status).toBe("ok");
+  });
+
+  test("detects drift when a vendored file is edited", async () => {
+    await vendorPull(root);
+    writeFileSync(join(root, "vendor/web-app/index.ts"), "// locally edited\n");
+    const result = vendorCheck(root);
+    expect(result.drift).toBe(true);
+    expect(result.entries[0].status).toBe("drifted");
+  });
+
+  test("flags a target deleted after pinning as missing", async () => {
+    await vendorPull(root);
+    rmSync(join(root, "vendor/web-app"), { recursive: true });
+    const result = vendorCheck(root);
+    expect(result.entries[0].status).toBe("missing");
+    expect(result.drift).toBe(true);
+  });
+
+  test("an entry with no checksum is unpinned, not drift", async () => {
+    // Manifest never pulled → no checksum recorded.
+    const result = vendorCheck(root);
+    expect(result.entries[0].status).toBe("unpinned");
+    expect(result.drift).toBe(false);
+  });
+});
+
+describe("manifest validation", () => {
+  test("rejects an invalid manifest", () => {
+    writeFileSync(join(root, MANIFEST_FILE), JSON.stringify({ vendored: [{ name: "x" }] }));
+    expect(() => loadManifest(root)).toThrow(/invalid vendor.json/);
+  });
+
+  test("rejects a floating updatePolicy (pins only)", () => {
+    writeFileSync(
+      join(root, MANIFEST_FILE),
+      JSON.stringify({ vendored: [{ name: "x", source: { type: "local", path: "shared/web-app" }, target: "v/x", updatePolicy: "latest" }] }),
+    );
+    expect(() => loadManifest(root)).toThrow(/invalid vendor.json/);
+  });
+});
+
+describe("contentHash", () => {
+  test("is order-independent and content-sensitive", () => {
+    const a = new Map([["a", Buffer.from("1")], ["b", Buffer.from("2")]]);
+    const b = new Map([["b", Buffer.from("2")], ["a", Buffer.from("1")]]);
+    expect(contentHash(a)).toBe(contentHash(b)); // order doesn't matter
+    const c = new Map([["a", Buffer.from("1")], ["b", Buffer.from("CHANGED")]]);
+    expect(contentHash(a)).not.toBe(contentHash(c));
+  });
+});
+
+describe("scopeArchiveFiles", () => {
+  test("strips the top-level wrapper dir and scopes to a subpath", () => {
+    const raw = new Map([
+      ["repo-main/composites/web-app/index.ts", Buffer.from("a")],
+      ["repo-main/composites/web-app/util.ts", Buffer.from("b")],
+      ["repo-main/ops/deploy.op.ts", Buffer.from("c")],
+      ["repo-main/README.md", Buffer.from("d")],
+    ]);
+    const scoped = scopeArchiveFiles(raw, "composites/web-app");
+    expect([...scoped.keys()].sort()).toEqual(["index.ts", "util.ts"]);
+  });
+
+  test("no subpath keeps everything below the wrapper dir", () => {
+    const raw = new Map([
+      ["repo-main/a.ts", Buffer.from("a")],
+      ["repo-main/sub/b.ts", Buffer.from("b")],
+    ]);
+    expect([...scopeArchiveFiles(raw).keys()].sort()).toEqual(["a.ts", "sub/b.ts"]);
+  });
+});