@intentius/chant 0.39.0 → 0.41.1

package/src/components/deploy-units.ts

@@ -0,0 +1,82 @@
+/**
+ * Deploy units — which live unit(s) a component's composition targets (#1495).
+ *
+ * `chant components status --live` (and `chant graph --live`) need to know
+ * what a component deployed in order to observe it. That answer used to be a
+ * string literal in the walk — `kind === "cfn-deploy"` — which made the whole
+ * chain CloudFormation-shaped: a component whose deploy phase is a server-side
+ * apply or a Helm upgrade contributed nothing and was skipped, not
+ * "unobserved", simply absent from the result.
+ *
+ * This module is the seam that fixes the walk (piece 1 of #1495's
+ * decomposition): a registry mapping a deploy-family step `kind` to the field
+ * naming its unit and the lexicon whose `describeStackStatus` can observe it.
+ * The registry is data, not a rule about what steps look like — a kind not
+ * listed here contributes no unit, exactly as before.
+ */
+import type { Phase } from "./component";
+
+/** A deploy-family step kind that names a live unit, and who observes it. */
+export interface DeployUnitRule {
+  /** The step `kind` (the capability's registered name). */
+  kind: string;
+  /** The step field carrying the unit's name (`stack`, `release`). */
+  field: string;
+  /** The lexicon whose `describeStackStatus` reads this kind of unit. */
+  lexicon: string;
+}
+
+/**
+ * The deploy-family kinds that name a unit. cfn-deploy's unit is its stack;
+ * kubectl-apply's is the ownership stack its labels carry (#1495 piece 2);
+ * helm-upgrade's is its release (#1495 piece 4). Listing a kind here is safe
+ * before its lexicon implements `describeStackStatus` — units whose lexicon
+ * has no observer are skipped by the caller, the same absent-observer path as
+ * before.
+ */
+export const DEPLOY_UNIT_RULES: readonly DeployUnitRule[] = [
+  { kind: "cfn-deploy", field: "stack", lexicon: "aws" },
+  { kind: "kubectl-apply", field: "stack", lexicon: "k8s" },
+  { kind: "helm-upgrade", field: "release", lexicon: "helm" },
+];
+
+/** One resolved unit a component's deploy composition targets. */
+export interface DeployUnit {
+  /** The unit's name — a stack, a release. */
+  unit: string;
+  /** The lexicon that observes this kind of unit. */
+  lexicon: string;
+}
+
+/**
+ * Every distinct deploy unit a component's phases target, in declaration
+ * order. A step may itself be a nested `Phase`, so the walk recurses; a
+ * resolved component carries the unit as a concrete string. Pure.
+ */
+export function deployUnits(deploy: Phase[]): DeployUnit[] {
+  const byKind = new Map(DEPLOY_UNIT_RULES.map((r) => [r.kind, r]));
+  const seen = new Set<string>();
+  const units: DeployUnit[] = [];
+  const walkSteps = (steps: Phase["steps"]): void => {
+    for (const step of steps) {
+      // A step may itself be a nested Phase (it carries its own `steps`). Step
+      // is open-typed (capability inputs), so discriminate structurally.
+      const nested = (step as { steps?: unknown }).steps;
+      if (Array.isArray(nested)) {
+        walkSteps(nested as Phase["steps"]);
+        continue;
+      }
+      const s = step as { kind?: string } & Record<string, unknown>;
+      const rule = s.kind ? byKind.get(s.kind) : undefined;
+      if (!rule) continue;
+      const unit = s[rule.field];
+      if (typeof unit !== "string" || unit.length === 0) continue;
+      const key = `${rule.lexicon}\0${unit}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      units.push({ unit, lexicon: rule.lexicon });
+    }
+  };
+  for (const phase of deploy) walkSteps(phase.steps);
+  return units;
+}

package/src/config.test.ts

@@ -1,6 +1,7 @@
 import { describe, test, expect, beforeEach, afterEach } from "vitest";
 import {
   loadChantConfig,
+  loadChantConfigUpward,
   DEFAULT_CHANT_CONFIG,
   resolveAutoReleaseDisabled,
   resolveFoldEnabled,
@@ -137,6 +138,58 @@ describe("loadChantConfig", () => {
   });
 });
 
+// #1502 — the upward walk skips lint-scoping fragments. A `src/chant.config.json`
+// holding only `extends`/`rules` (the examples/ convention) must not shadow the
+// project config above it, or `chant build src` silently loses `ownership`/
+// `buildParams` — the exact fallback #1117's walk exists to prevent.
+describe("loadChantConfigUpward (#1502 — lint fragments do not end the walk)", () => {
+  const SRC = join(TEST_DIR, "src");
+
+  test("walks past a lint-only src/chant.config.json to the project config", async () => {
+    mkdirSync(SRC, { recursive: true });
+    writeFileSync(
+      join(SRC, "chant.config.json"),
+      JSON.stringify({ extends: ["@intentius/chant/lint/presets/strict"], rules: { COR001: "off" } }),
+    );
+    writeFileSync(
+      join(TEST_DIR, "chant.config.json"),
+      JSON.stringify({ ownership: { stack: "billing", env: "prod" } }),
+    );
+
+    const result = await loadChantConfigUpward(SRC);
+    expect(result.config.ownership).toEqual({ stack: "billing", env: "prod" });
+    expect(result.configPath).toBe(join(TEST_DIR, "chant.config.json"));
+  });
+
+  test("a src/chant.config.json declaring any project-level key still wins in place", async () => {
+    mkdirSync(SRC, { recursive: true });
+    writeFileSync(
+      join(SRC, "chant.config.json"),
+      JSON.stringify({ ownership: { stack: "nested" }, rules: { COR001: "off" } }),
+    );
+    writeFileSync(
+      join(TEST_DIR, "chant.config.json"),
+      JSON.stringify({ ownership: { stack: "root" } }),
+    );
+
+    const result = await loadChantConfigUpward(SRC);
+    expect(result.config.ownership?.stack).toBe("nested");
+  });
+
+  test("a fragment-only project resolves to the default config at the boundary", async () => {
+    mkdirSync(SRC, { recursive: true });
+    writeFileSync(join(TEST_DIR, "package.json"), JSON.stringify({ name: "boundary" }));
+    writeFileSync(
+      join(SRC, "chant.config.json"),
+      JSON.stringify({ extends: ["@intentius/chant/lint/presets/strict"] }),
+    );
+
+    const result = await loadChantConfigUpward(SRC);
+    expect(result.config).toEqual(DEFAULT_CHANT_CONFIG);
+    expect(result.configPath).toBeUndefined();
+  });
+});
+
 // #1166 — `environments` accepts either a bare name (unchanged) or
 // `{ name, endpoint }`, so a declared environment can be self-sufficient for
 // `--live` reads without an ambient AWS_ENDPOINT_URL export.

package/src/config.ts

@@ -1,5 +1,5 @@
-import { existsSync } from "fs";
-import { join } from "path";
+import { existsSync, readFileSync } from "fs";
+import { dirname, join } from "path";
 import { z } from "zod";
 import type { LintConfig } from "./lint/config";
 import type { OwnershipMarker } from "./ownership";
@@ -384,12 +384,50 @@ export async function loadChantConfig(dir: string): Promise<ResolvedConfig> {
  * same walk `chant lint`/`chant graph` already used ({@link findProjectConfig},
  * shared with `./lint/config.ts`'s `findProjectRoot`) — one config-discovery
  * contract for the whole CLI.
+ *
+ * chant #1502 — a lint-scoping fragment does not end the walk. The convention
+ * of a `src/chant.config.json` holding only `extends`/`rules` (cc-aws-canonical
+ * and most of examples/) sits BETWEEN the build directory and the real
+ * `chant.config.ts`, and stopping there re-introduced the exact silent
+ * fallback this walk exists to prevent: `chant build src` resolved the
+ * fragment, found no `ownership`, and built unstamped manifests that every
+ * owned-scoped live read then withheld. A fragment is skipped, not merged —
+ * lint resolution keeps its own nearest-wins walk untouched, and a JSON
+ * config declaring any project-level key still wins where it stands.
  */
 export async function loadChantConfigUpward(startDir: string): Promise<ResolvedConfig> {
-  const { dir } = findProjectConfig(startDir);
+  let { dir, configPath } = findProjectConfig(startDir);
+  while (configPath && isLintOnlyFragment(configPath)) {
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    ({ dir, configPath } = findProjectConfig(parent));
+  }
   return loadChantConfig(dir);
 }
 
+/**
+ * The top-level keys of `./lint/config.ts`'s `LintConfigSchema` (plus the
+ * `$schema` editor convention). A `chant.config.json` whose keys all come from
+ * this set is a lint-scoping fragment, not a project config — see
+ * {@link loadChantConfigUpward}. `chant.config.ts` is never a fragment: it is
+ * project-authored code, and inspecting it would mean evaluating it.
+ */
+const LINT_FRAGMENT_KEYS = new Set(["$schema", "extends", "rules", "overrides", "plugins", "policies"]);
+
+function isLintOnlyFragment(configPath: string): boolean {
+  if (!configPath.endsWith("chant.config.json")) return false;
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, "utf-8")) as unknown;
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return false;
+    const keys = Object.keys(parsed);
+    return keys.length > 0 && keys.every((k) => LINT_FRAGMENT_KEYS.has(k));
+  } catch {
+    // Unreadable/unparseable JSON: let loadChantConfig surface the real error
+    // in place rather than silently walking past it.
+    return false;
+  }
+}
+
 /**
  * Resolve the ownership marker to stamp from project config, or undefined when
  * ownership marking is off (no `stack`, or `enabled: false`).

package/src/discovery/index.ts

@@ -11,6 +11,64 @@ import { getProvenance } from "../provenance";
 import type { BuildParamProvenance } from "../provenance";
 import { buildParamValues } from "../build-params";
 import { setBuildParams } from "../params";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, parse } from "node:path";
+
+/**
+ * Warn when resolved build parameters cannot reach project source (#1421).
+ *
+ * chant's core is ESM. When the project is CommonJS — `"type": "commonjs"`, or
+ * no `type` field — tsx loads project source through the CommonJS transform, so
+ * the project's `require` of `params.ts` and core's `import` of it produce two
+ * separate module records. {@link setBuildParams} mutates one object in place;
+ * project source reads the other, and sees `{}`.
+ *
+ * The failure is silence. chant prints `[param] tier = "prod" (cli)` and then
+ * emits the graph for the default branch. `chant graph` is always affected
+ * because it always takes the run path; `chant build --no-fold` likewise. Plain
+ * `chant build` usually escapes because folding substitutes parameters
+ * statically — but a file that falls back to run inside a folded build is wrong
+ * the same way, which is why this warns regardless of `fold`.
+ *
+ * Only fires when parameters were actually resolved, so a CJS project that uses
+ * none is never nagged. `chant doctor`'s `package-type-module` check is the
+ * ambient version of the same advice.
+ *
+ * Best-effort and never throws: a project whose `package.json` cannot be found
+ * or parsed gets no warning rather than a failed build.
+ */
+function warnIfParamsCannotReachProject(path: string, values: Record<string, unknown>): void {
+  if (Object.keys(values).length === 0) return;
+  try {
+    const pkgPath = findPackageJsonUpward(path);
+    if (!pkgPath) return;
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as { type?: string };
+    if (pkg.type === "module") return;
+    const found = pkg.type ? `"type": "${pkg.type}"` : "no `type` field";
+    const names = Object.keys(values).sort().join(", ");
+    console.error(
+      `warning: ${pkgPath} has ${found}, but chant is ESM — build parameters (${names}) ` +
+        `will read as empty in project source on the run path, so declarations conditioned ` +
+        `on them take their default branch. Set "type": "module". (chant #1421)`,
+    );
+  } catch {
+    // Unreadable or unparseable package.json — say nothing rather than fail.
+  }
+}
+
+/** Nearest `package.json` at or above `startDir`, or undefined. */
+function findPackageJsonUpward(startDir: string): string | undefined {
+  let dir = startDir;
+  const { root } = parse(dir);
+  for (;;) {
+    const candidate = join(dir, "package.json");
+    if (existsSync(candidate)) return candidate;
+    if (dir === root) return undefined;
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
 
 /**
  * Per-file fold-vs-run outcome (chant #1022, epic #1019), populated only
@@ -150,6 +208,7 @@ export async function discover(path: string, options?: DiscoveryOptions): Promis
   // `--watch`) never leaks into a build that supplied none.
   const buildParamValuesMap = buildParamValues(options?.buildParams ?? []);
   setBuildParams(buildParamValuesMap);
+  warnIfParamsCannotReachProject(path, buildParamValuesMap);
 
   // Step 1: Scan for TypeScript files
   const files = await findInfraFiles(path);

package/src/discovery/params-cjs-warning.test.ts

@@ -0,0 +1,75 @@
+import { describe, test, expect, vi, afterEach } from "vitest";
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { discover } from "./index";
+
+/**
+ * #1421 — chant's core is ESM. A CommonJS project's `require` of `params.ts`
+ * and core's `import` of it are two module records, so `setBuildParams`'s
+ * in-place mutation never reaches project source: it reads `{}` and every
+ * declaration conditioned on a parameter takes its default branch, silently.
+ *
+ * The fix is to stop it being silent. These assert the warning fires exactly
+ * when the hazard exists and stays quiet otherwise.
+ */
+describe("build params that cannot reach a CommonJS project (#1421)", () => {
+  const dirs: string[] = [];
+  const project = (type: string | undefined): string => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-1421-"));
+    dirs.push(dir);
+    writeFileSync(
+      join(dir, "package.json"),
+      JSON.stringify(type === undefined ? { name: "p" } : { name: "p", type }),
+    );
+    mkdirSync(join(dir, "src"));
+    writeFileSync(join(dir, "src", "main.ts"), "export const x = 1;\n");
+    return dir;
+  };
+
+  afterEach(() => {
+    for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  const warnings = async (dir: string, params: Array<{ name: string; value: unknown }>): Promise<string[]> => {
+    const seen: string[] = [];
+    vi.spyOn(console, "error").mockImplementation((...a: unknown[]) => void seen.push(a.join(" ")));
+    await discover(join(dir, "src"), {
+      buildParams: params as never,
+    });
+    return seen.filter((s) => s.includes("#1421"));
+  };
+
+  test('warns for "type": "commonjs" when parameters were resolved', async () => {
+    const out = await warnings(project("commonjs"), [{ name: "tier", value: "prod" }]);
+    expect(out).toHaveLength(1);
+    expect(out[0]).toMatch(/"type": "commonjs"/);
+    expect(out[0]).toMatch(/tier/);
+    expect(out[0]).toMatch(/Set "type": "module"/);
+  });
+
+  // The sneakier half: no `type` field at all is also CommonJS.
+  test("warns when package.json declares no type at all", async () => {
+    const out = await warnings(project(undefined), [{ name: "tier", value: "prod" }]);
+    expect(out).toHaveLength(1);
+    expect(out[0]).toMatch(/no `type` field/);
+  });
+
+  test('stays quiet for "type": "module"', async () => {
+    expect(await warnings(project("module"), [{ name: "tier", value: "prod" }])).toEqual([]);
+  });
+
+  // A CJS project using no parameters is not at risk, and must not be nagged.
+  test("stays quiet when no parameters were resolved", async () => {
+    expect(await warnings(project("commonjs"), [])).toEqual([]);
+  });
+
+  test("names every resolved parameter, sorted", async () => {
+    const out = await warnings(project("commonjs"), [
+      { name: "zone", value: "b" },
+      { name: "tier", value: "prod" },
+    ]);
+    expect(out[0]).toMatch(/\(tier, zone\)/);
+  });
+});

package/src/index.ts

@@ -49,6 +49,7 @@ export * from "./import/parser";
 export * from "./import/generator";
 export * from "./lexicon";
 export * from "./observation";
+export * from "./apply";
 export * from "./deep-observation";
 export * from "./owner-chain";
 export * from "./lexicon-integrity";