@intentius/chant 0.97.0 → 0.99.0

package/src/cli/handlers/operator-steward-signal.e2e.test.ts

@@ -45,7 +45,7 @@ function sleep(ms: number): Promise<void> {
 }
 
 describe("chant operator --steward — a repeated SIGTERM (#2872)", () => {
-  test("a second and third SIGTERM sent in quick succession still release the steward's lease", async () => {
+  test("repeated SIGTERMs sent in quick succession still release the steward's lease and exit 0", async () => {
     const dir = repo(
       {
         "chant.config.ts": "export default { lexicons: [] };\n",
@@ -77,16 +77,24 @@ describe("chant operator --steward — a repeated SIGTERM (#2872)", () => {
       await sleep(50);
     }
 
-    // Three SIGTERMs, each given a moment to actually reach the child's event
-    // loop before the next: with `process.once`, the first one's auto-removal
-    // happens the instant it fires, so the second (or third) finds no
-    // listener left and the process exits right there, skipping the
-    // `finally` that releases the lease.
-    child.kill("SIGTERM");
-    await sleep(30);
-    child.kill("SIGTERM");
-    await sleep(30);
-    child.kill("SIGTERM");
+    // A SIGTERM, then more every few ms until the child is gone, each given
+    // a moment to reach the child's event loop before the next. With
+    // `process.once`, the first one's auto-removal happens the instant it
+    // fires, so the second finds no listener left and the process exits
+    // right there, skipping the `finally` that releases the lease. Firing
+    // until the child closes (not a fixed three) also covers the stretch
+    // after that `finally`, up to `process.exit`: when the handler removed
+    // its listeners there, a SIGTERM arriving in that stretch ended the
+    // process by signal (exit code null) though the lease was released. With
+    // three signals 30ms apart that failed CI now and then (runs
+    // 36357297831, 36358285603, 36368551353); signalling to the end hit it
+    // every time.
+    let closed = false;
+    child.on("close", () => (closed = true));
+    for (let sent = 0; !closed && sent < 1000; sent++) {
+      child.kill("SIGTERM");
+      await sleep(5);
+    }
 
     const code = await exited;
     expect(code, `chant operator --steward did not exit cleanly; stderr:\n${stderr}`).toBe(0);

package/src/cli/handlers/operator.ts

@@ -216,7 +216,12 @@ export async function runOperator(ctx: CommandContext): Promise<number> {
     });
     return 0;
   } finally {
-    process.removeListener("SIGINT", onSigint);
+    // Only when no signal started this shutdown. After one did, the process
+    // exits right after this returns, and removing the listener would put
+    // SIGINT back to its default disposition for that last stretch: a repeat
+    // signal arriving there ends the process by signal instead of the exit
+    // code (see the steward's `finally` below).
+    if (!stopping) process.removeListener("SIGINT", onSigint);
   }
 }
 
@@ -347,8 +352,17 @@ export async function runStewardOperator(ctx: CommandContext): Promise<number> {
     // A courtesy: the lease expires on its own if this never runs.
     const { record } = await readLease(stewardLeaseName(steward.name)).catch(() => ({ record: undefined }));
     if (record?.holder === holder) await releaseLease(stewardLeaseName(steward.name), holder, record.token).catch(() => false);
-    process.removeListener("SIGINT", onSigint);
-    process.removeListener("SIGTERM", onSigint);
+    // Removed only when no signal started this shutdown. After one did, the
+    // CLI goes on to `flushAndExit` (../main.ts) and `process.exit`, and
+    // removing the last SIGTERM listener hands the signal back to its
+    // default disposition for that stretch: a repeat SIGTERM arriving there
+    // ended the process by signal (exit code null) with the lease already
+    // released. That was the operator-steward-signal e2e test's intermittent
+    // failure; a SIGTERM every 2ms after the first hit it 8 runs of 8.
+    if (!stopping) {
+      process.removeListener("SIGINT", onSigint);
+      process.removeListener("SIGTERM", onSigint);
+    }
   }
 }
 

package/src/cli/main.ts

@@ -1091,7 +1091,8 @@ Options:
                         - build: json (default) or yaml
                         - list: text (default) or json
                         - lint: stylish (default), json, or sarif
-  -d, --lexicon <name>  Build only the specified lexicon (e.g. aws, gitlab)
+  -d, --lexicon <name>  Build only the specified lexicon (e.g. aws, gitlab);
+                        import: use this lexicon instead of detecting one
       --env <name>      Active environment: sets CHANT_ENV so env-aware source
                         re-evaluates for that environment (build + graph), and
                         drives organizational policy. Must be in chant.config
@@ -1201,6 +1202,7 @@ Examples:
   chant run --components all --env production
   chant components export prod --component search-service -o ./dist/search-service
   chant import template.json --output ./infra/
+  chant import manifest.yaml --lexicon k8s --output ./infra/
   chant import --from prod --name my-bucket --output src/
   chant lint ./infra/
   chant lint ./infra/ --format sarif

package/src/cli/mcp/tools/import.ts

@@ -17,6 +17,10 @@ export const importTool = {
         type: "string",
         description: "Output directory (default: ./infra/)",
       },
+      lexicon: {
+        type: "string",
+        description: "Lexicon to import with (e.g. k8s); skips template detection",
+      },
     },
     required: ["source"],
   },
@@ -28,11 +32,13 @@ export const importTool = {
 export async function handleImport(params: Record<string, unknown>): Promise<unknown> {
   const source = params.source as string;
   const output = params.output as string | undefined;
+  const lexicon = params.lexicon as string | undefined;
 
   const result = await importCommand({
     templatePath: source,
     output,
     force: true,
+    lexicon,
   });
 
   if (!result.success) {

package/src/cli/plugins.ts

@@ -2,8 +2,9 @@ import { importLexiconModule, importLexiconPackage, lexiconModulePath, lexiconNa
 import { readLexiconDeclarationsStatically, type StaticLexiconRead } from "../config-static";
 export { unknownPathLexiconsNotice } from "../config-static";
 import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
-import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync, readdirSync, readFileSync, type Dirent } from "node:fs";
 import { isLexiconPlugin, type LexiconPlugin } from "../lexicon";
 import { loadChantConfigUpward } from "../config";
 import { findInfraFiles, detectLexicons } from "../index";
@@ -80,6 +81,44 @@ export async function loadPlugin(lexiconName: string): Promise<LexiconPlugin> {
   throw new Error(`Package ${packageName} does not export a LexiconPlugin or Serializer`);
 }
 
+const LEXICON_PACKAGE_PREFIX = "chant-lexicon-";
+
+/**
+ * The names of the lexicon packages installed where {@link loadPlugin} can
+ * load them (#2965), sorted. `loadPlugin` imports
+ * `@intentius/chant-lexicon-<name>` from chant's own install and then from the
+ * project (`importLexiconPackage`), so this lists the `@intentius` scope of
+ * every `node_modules` directory Node would search from either place: each
+ * ancestor of chant's own module and each ancestor of `projectDir`. A name
+ * being listed does not promise it loads; the caller still handles a failure.
+ */
+export function listInstalledLexicons(projectDir: string = process.cwd()): string[] {
+  const names = new Set<string>();
+  const starts = [dirname(fileURLToPath(import.meta.url)), resolve(projectDir)];
+  for (const start of starts) {
+    let dir = start;
+    for (;;) {
+      const scope = join(dir, "node_modules", "@intentius");
+      let entries: Dirent[] = [];
+      try {
+        entries = readdirSync(scope, { withFileTypes: true });
+      } catch {
+        // No @intentius scope here.
+      }
+      for (const entry of entries) {
+        if (!entry.name.startsWith(LEXICON_PACKAGE_PREFIX)) continue;
+        if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+        const name = entry.name.slice(LEXICON_PACKAGE_PREFIX.length);
+        if (name !== "") names.add(name);
+      }
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  }
+  return [...names].sort();
+}
+
 /**
  * The installed version of each named lexicon package (chant #1442).
  *

package/src/deep-observation.test.ts

@@ -309,6 +309,27 @@ describe("deepPathSet", () => {
     const set = deepPathSet({ Tags: [{ Key: "a" }] });
     expect([...set].sort()).toEqual(["Tags", "Tags[0]", "Tags[0].Key", "Tags[]", "Tags[].Key"]);
   });
+
+  // #2946: the path set has to agree with the normalized tree, which inlines
+  // a property-kind declarable's props (#1314). Otherwise a live node under
+  // one reads `counterpart: "absent"` and is pruned as an undeclared default.
+  test("walks a property-kind declarable as its props, as normalization inlines it", () => {
+    class Panel {
+      readonly entityType = "Grafana::Panel::stat";
+      readonly kind = "property";
+      constructor(readonly props: Record<string, unknown>) {}
+    }
+    const set = deepPathSet({ panels: [new Panel({ gridPos: { w: 6 } })] });
+    expect(set.has("panels[0].gridPos.w")).toBe(true);
+    expect(set.has("panels[].gridPos.w")).toBe(true);
+
+    const hooks = { prune: (n: { side: string; counterpart: string }) => n.side === "live" && n.counterpart === "absent" };
+    const live = normalizeDeepProperties(
+      { panels: [{ gridPos: { w: 6, x: 0 } }] },
+      { entityType: "T", side: "live", hooks, counterpartPaths: set },
+    );
+    expect(live).toEqual({ panels: [{ gridPos: { w: 6 } }] });
+  });
 });
 
 describe("deepValueEqual", () => {

package/src/deep-observation.ts

@@ -363,6 +363,15 @@ export function deepPathSet(tree: Record<string, unknown>): Set<string> {
     // gives it, so this path set agrees with what the normalized tree
     // actually looks like a path down.
     if (isHeldElsewhere(value)) return;
+    // A property-kind declarable is walked as its props, exactly as
+    // `normalizeDeepProperties` inlines it (#1314). Stopping at it left every
+    // path under a typed nested property out of the set, so the other tree's
+    // nodes there read `counterpart: "absent"` and default subtraction fired
+    // on properties the author did declare.
+    if (isPropertyDeclarableValue(value)) {
+      walk((value as { props?: unknown }).props ?? {}, path, pattern);
+      return;
+    }
     if (Array.isArray(value)) {
       value.forEach((el, i) => walk(el, joinIndex(path, i), joinPattern(pattern)));
       return;

package/src/import/embedded.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, test } from "vitest";
+import {
+  EmbeddedImports,
+  EmbeddedImportScope,
+  embeddedDocument,
+  exportedNames,
+  isEmbeddedReference,
+  renderEmbeddedReference,
+  type EmbeddedContent,
+  type EmbeddedContentImporter,
+} from "./embedded";
+
+const site = (over: Partial<EmbeddedContent> = {}): EmbeddedContent => ({
+  host: "k8s",
+  hostType: "K8s::Core::ConfigMap",
+  location: 'ConfigMap agent data["config.yaml"]',
+  directory: "agent",
+  text: "kind: widget\nsize: 3\n",
+  ...over,
+});
+
+/** Imports any `kind: widget` document as `widgets.ts`, passed through `render`. */
+const widgets: EmbeddedContentImporter = {
+  what: "a widget",
+  matches: (c) => (c.document as { kind?: string } | undefined)?.kind === "widget",
+  import: () => ({
+    files: [{ path: "widgets.ts", content: "const w = 1;\n\nexport { w };\n" }],
+    value: { bindings: [{ from: "widgets.ts", name: "w" }], shape: "list", through: { from: "@acme/widgets", name: "render" } },
+    warnings: ["dropped the colour"],
+  }),
+};
+
+describe("EmbeddedImports", () => {
+  test("an importer that matches gets the content, with its document parsed from the text", () => {
+    const seen: EmbeddedContent[] = [];
+    const resolver = new EmbeddedImports([{ lexicon: "acme", importer: { ...widgets, import: (c) => (seen.push(c), widgets.import(c)) } }]);
+    const ref = resolver.resolve(site());
+    expect(seen[0].document).toEqual({ kind: "widget", size: 3 });
+    expect(isEmbeddedReference(ref)).toBe(true);
+    // Local modules are rebased under the content's directory; packages stay as they are.
+    expect(ref!.$embedded).toEqual({
+      lexicon: "acme",
+      what: "a widget",
+      location: 'ConfigMap agent data["config.yaml"]',
+      value: { bindings: [{ from: "agent/widgets.ts", name: "w" }], shape: "list", through: { from: "@acme/widgets", name: "render" } },
+    });
+    expect(resolver.files).toEqual([{ path: "agent/widgets.ts", content: "const w = 1;\n\nexport { w };\n" }]);
+    expect(resolver.warnings).toEqual(['ConfigMap agent data["config.yaml"]: dropped the colour']);
+    expect(resolver.offered).toHaveLength(1);
+  });
+
+  test("two pieces of content wanting one directory get two", () => {
+    const resolver = new EmbeddedImports([{ lexicon: "acme", importer: widgets }]);
+    resolver.resolve(site({ directory: "Agent Config" }));
+    resolver.resolve(site({ directory: "agent-config" }));
+    expect(resolver.files.map((f) => f.path)).toEqual(["agent-config/widgets.ts", "agent-config-2/widgets.ts"]);
+  });
+
+  test("content nobody claims is kept, with a warning only when the host names its expected owner", () => {
+    const resolver = new EmbeddedImports([{ lexicon: "acme", importer: widgets }]);
+    expect(resolver.resolve(site({ text: "kind: gadget\n" }))).toBeUndefined();
+    expect(resolver.warnings).toEqual([]);
+    expect(resolver.resolve(site({ text: "kind: gadget\n", expectedOwner: { lexicon: "gadgets", what: "a gadget" } }))).toBeUndefined();
+    expect(resolver.warnings).toHaveLength(1);
+    expect(resolver.warnings[0]).toContain("looks like a gadget");
+    expect(resolver.warnings[0]).toContain("@intentius/chant-lexicon-gadgets");
+  });
+
+  test("a quiet probe collects what is offered and warns about nothing", () => {
+    const probe = new EmbeddedImports([], { quiet: true });
+    expect(probe.resolve(site({ expectedOwner: { lexicon: "gadgets", what: "a gadget" } }))).toBeUndefined();
+    expect(probe.offered).toHaveLength(1);
+    expect(probe.warnings).toEqual([]);
+  });
+
+  test("a failing import keeps the content and says why; a throwing matcher is a non-match", () => {
+    const resolver = new EmbeddedImports([
+      { lexicon: "broken", importer: { what: "a widget", matches: () => { throw new Error("no"); }, import: widgets.import } },
+      { lexicon: "acme", importer: { ...widgets, import: () => { throw new Error("bad size"); } } },
+    ]);
+    expect(resolver.resolve(site())).toBeUndefined();
+    expect(resolver.files).toEqual([]);
+    expect(resolver.warnings).toEqual([
+      'ConfigMap agent data["config.yaml"] looks like a widget, but the acme import failed, so it is kept as written: bad size',
+    ]);
+  });
+
+  test("when two lexicons match, the first imports it and the other is named", () => {
+    const resolver = new EmbeddedImports([
+      { lexicon: "acme", importer: widgets },
+      { lexicon: "other", importer: widgets },
+    ]);
+    expect(resolver.resolve(site())!.$embedded.lexicon).toBe("acme");
+    expect(resolver.warnings[0]).toContain("also importable by other");
+  });
+});
+
+describe("renderEmbeddedReference", () => {
+  const ref = (bindings: Array<{ from: string; name: string; member?: string }>, shape: "list" | "single", through?: { from: string; name: string }) => ({
+    $embedded: { lexicon: "acme", what: "a widget", location: "here", value: { bindings, shape, ...(through ? { through } : {}) } },
+  });
+
+  test("imports each name once, relative to the module, and aliases a name already taken", () => {
+    const scope = new EmbeddedImportScope("", ["otlp"]);
+    const a = renderEmbeddedReference(
+      ref([{ from: "agent/receivers.ts", name: "otlp" }, { from: "agent/pipelines.ts", name: "traces" }], "list", { from: "@acme/otel", name: "collectorYaml" }),
+      scope,
+    );
+    const b = renderEmbeddedReference(ref([{ from: "gateway/receivers.ts", name: "otlp" }], "list"), scope);
+    expect(a).toBe("collectorYaml([otlp2, traces])");
+    expect(b).toBe("[otlp3]");
+    expect(scope.lines()).toEqual([
+      'import { collectorYaml } from "@acme/otel";',
+      'import { traces } from "./agent/pipelines";',
+      'import { otlp as otlp2 } from "./agent/receivers";',
+      'import { otlp as otlp3 } from "./gateway/receivers";',
+    ]);
+  });
+
+  test("a single binding, a member, and a module in a subdirectory", () => {
+    const scope = new EmbeddedImportScope("infra");
+    expect(renderEmbeddedReference(ref([{ from: "rules/slos.ts", name: "api", member: "rules" }], "single"), scope)).toBe("api.rules");
+    expect(scope.lines()).toEqual(['import { api } from "../rules/slos";']);
+  });
+
+  test("a long list is broken one binding per line", () => {
+    const names = Array.from({ length: 12 }, (_, i) => ({ from: "c/x.ts", name: `component${i}` }));
+    const out = renderEmbeddedReference(ref(names, "list"), new EmbeddedImportScope(""), 4);
+    expect(out.split("\n")).toHaveLength(14);
+    expect(out.split("\n")[1]).toBe("      component0,");
+    expect(out.endsWith("\n    ]")).toBe(true);
+  });
+});
+
+describe("helpers", () => {
+  test("embeddedDocument reads JSON or one YAML document", () => {
+    expect(embeddedDocument('{"a": 1}')).toEqual({ a: 1 });
+    expect(embeddedDocument("a: 1\n")).toEqual({ a: 1 });
+    expect(embeddedDocument("a: 1\n---\nb: 2\n")).toBeUndefined();
+  });
+
+  test("exportedNames reads one-line and multi-line export lists", () => {
+    expect(exportedNames("const a = 1;\n\nexport { a, b };\n")).toEqual(["a", "b"]);
+    expect(exportedNames("export {\n  one,\n  two as three,\n};\n")).toEqual(["one", "three"]);
+    expect(exportedNames("export const x = 1;\n")).toEqual([]);
+  });
+
+  test("isEmbeddedReference", () => {
+    expect(isEmbeddedReference({ $embedded: { value: { bindings: [] } } })).toBe(true);
+    expect(isEmbeddedReference({ $embedded: true })).toBe(false);
+    expect(isEmbeddedReference("x")).toBe(false);
+  });
+});