@intentius/chant 0.80.0 → 0.81.0

package/src/workspace/behold-kinds.test.ts

@@ -0,0 +1,162 @@
+/**
+ * behold's two closed member kinds, read through chant's workspace (#2545).
+ *
+ * `terraform` ships from the terraform lexicon's `./workspace-kinds` subpath,
+ * and `choudoufu` from the kinds-only package
+ * `@intentius/workspace-kind-choudoufu`. A workspace that pins both lists
+ * members of either kind through `chant workspace ls --json`, with the kinds
+ * behold gave the same directories, and reading the kinds imports neither
+ * package.
+ *
+ * The installed packages are the repo's own: their package.json and kinds
+ * file are copied as they ship, and every code entry their `exports` name is
+ * replaced by a module that leaves a marker file when it is imported.
+ */
+
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { parseArgs } from "../cli/main";
+import { runDeclarationChecks } from "./checks";
+import { loadKindRegistry, resolveKind } from "./kinds";
+import { runWorkspaceLs, type LsDocument } from "./ls";
+import { workingTree } from "./tree";
+
+const REPO = join(import.meta.dirname, "..", "..", "..", "..");
+const TERRAFORM = join(REPO, "lexicons", "terraform");
+const CHOUDOUFU = join(REPO, "packages", "workspace-kind-choudoufu");
+const FIXTURES = join(TERRAFORM, "src", "__fixtures__");
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+
+const version = (dir: string): string => (JSON.parse(readFileSync(join(dir, "package.json"), "utf-8")) as { version: string }).version;
+
+const MARKER = `import { writeFileSync } from "node:fs";\nwriteFileSync(new URL("./IMPORTED", import.meta.url), "");\n(globalThis as { __chantKindsImported?: boolean }).__chantKindsImported = true;\n`;
+
+/**
+ * Install the package in `from` under `root/node_modules`: its package.json
+ * and kinds file as they are, and a marker module at every code target its
+ * exports name, the `./*` pattern's target for `workspace-kinds` included.
+ */
+function install(root: string, from: string): string {
+  const manifest = JSON.parse(readFileSync(join(from, "package.json"), "utf-8")) as { name: string; exports: Record<string, unknown> };
+  const dir = join(root, "node_modules", ...manifest.name.split("/"));
+  mkdirSync(dir, { recursive: true });
+  cpSync(join(from, "package.json"), join(dir, "package.json"));
+  cpSync(join(from, "workspace-kinds.json"), join(dir, "workspace-kinds.json"));
+  const targets = new Set<string>(["./index.js"]);
+  const collect = (entry: unknown): void => {
+    if (typeof entry === "string") targets.add(entry.replace("*", "workspace-kinds"));
+    else if (entry && typeof entry === "object") for (const v of Object.values(entry)) collect(v);
+  };
+  for (const [key, entry] of Object.entries(manifest.exports)) if (key !== "./workspace-kinds") collect(entry);
+  for (const t of targets) {
+    if (!/\.(ts|js|mjs)$/.test(t)) continue;
+    mkdirSync(dirname(join(dir, t)), { recursive: true });
+    writeFileSync(join(dir, t), MARKER);
+  }
+  return dir;
+}
+
+function workspace(): { root: string; installed: string[] } {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-behold-kinds-")));
+  scratch.push(root);
+  const installed = [install(root, TERRAFORM), install(root, CHOUDOUFU)];
+  // Estates in the shapes behold serves: a stock root, a choudoufu root with
+  // the sidecar, one with the live block, and a chant project beside .tf files.
+  cpSync(join(FIXTURES, "no-backend"), join(root, "estates", "stock"), { recursive: true });
+  cpSync(join(FIXTURES, "live-estate"), join(root, "estates", "sidecar"), { recursive: true });
+  cpSync(join(FIXTURES, "live"), join(root, "estates", "inline"), { recursive: true });
+  mkdirSync(join(root, "app"), { recursive: true });
+  writeFileSync(join(root, "app", "chant.config.ts"), "export default {};\n");
+  writeFileSync(join(root, "app", "main.tf"), 'resource "null_resource" "x" {}\n');
+  writeFileSync(
+    join(root, "chant.workspace.json"),
+    JSON.stringify(
+      {
+        name: "estate",
+        schema: 1,
+        pins: [
+          { package: "@intentius/chant-lexicon-terraform", version: version(TERRAFORM) },
+          { package: "@intentius/workspace-kind-choudoufu", version: version(CHOUDOUFU) },
+        ],
+        members: [
+          { name: "stock", dir: "estates/stock", kind: "terraform" },
+          { name: "sidecar", dir: "estates/sidecar", kind: "choudoufu" },
+          { name: "inline", dir: "estates/inline", kind: "choudoufu" },
+          { name: "app", dir: "app", kind: "chant" },
+        ],
+      },
+      null,
+      2,
+    ),
+  );
+  return { root, installed };
+}
+
+describe("behold's member kinds from their packages (#2545)", () => {
+  let out: string[];
+  beforeEach(() => {
+    out = [];
+    vi.spyOn(console, "log").mockImplementation((...a: unknown[]) => void out.push(a.join(" ")));
+  });
+  afterEach(() => vi.restoreAllMocks());
+
+  test("chant workspace ls --json lists terraform and choudoufu members, readable, and imports neither package", async () => {
+    const { root, installed } = workspace();
+    const code = await runWorkspaceLs({ args: parseArgs(["workspace", "ls", root, "--json"]), plugins: [] } as never);
+    expect(code).toBe(0);
+    const doc = JSON.parse(out.join("\n")) as Extract<LsDocument, { members: unknown }>;
+    expect(doc.members.map((m) => [m.name, m.kind, m.readable])).toEqual([
+      ["stock", "terraform", true],
+      ["sidecar", "choudoufu", true],
+      ["inline", "choudoufu", true],
+      ["app", "chant", true],
+    ]);
+    for (const dir of installed) expect(existsSync(join(dir, "IMPORTED")), dir).toBe(false);
+    expect(existsSync(join(installed[0], "src", "IMPORTED"))).toBe(false);
+    expect((globalThis as { __chantKindsImported?: boolean }).__chantKindsImported).toBeUndefined();
+  });
+
+  test("each directory's kind is the one behold gave it: chant over choudoufu over terraform", () => {
+    const { root } = workspace();
+    const pins = [
+      { package: "@intentius/chant-lexicon-terraform", version: version(TERRAFORM), path: null },
+      { package: "@intentius/workspace-kind-choudoufu", version: version(CHOUDOUFU), path: null },
+    ];
+    const { registry, problems } = loadKindRegistry(pins, root);
+    expect(problems).toEqual([]);
+    expect(registry.get("terraform")).toMatchObject({ source: "@intentius/chant-lexicon-terraform", precedence: 400 });
+    expect(registry.get("choudoufu")).toMatchObject({ source: "@intentius/workspace-kind-choudoufu", precedence: 450 });
+    const tree = workingTree(root);
+    const winner = (dir: string) => resolveKind(registry, tree, dir).winner?.name;
+    expect(winner("estates/stock")).toBe("terraform");
+    expect(winner("estates/sidecar")).toBe("choudoufu");
+    expect(winner("estates/inline")).toBe("choudoufu");
+    expect(winner("app")).toBe("chant");
+    expect(resolveKind(registry, tree, "estates/inline").claims.map((k) => k.name)).toEqual(["choudoufu", "terraform"]);
+  });
+
+  test("chant workspace check passes with no error: no member is outranked, and no probes tie", async () => {
+    const { root } = workspace();
+    const report = await runDeclarationChecks(root);
+    expect(report.diagnostics.filter((d) => d.severity === "error")).toEqual([]);
+    expect(report.ok).toBe(true);
+  });
+
+  test("without the pins, the same members are an unknown kind, and the message names the known ones", async () => {
+    const { root } = workspace();
+    const file = join(root, "chant.workspace.json");
+    const decl = JSON.parse(readFileSync(file, "utf-8")) as { pins?: unknown };
+    delete decl.pins;
+    writeFileSync(file, JSON.stringify(decl));
+    await runWorkspaceLs({ args: parseArgs(["workspace", "ls", root, "--json"]), plugins: [] } as never);
+    const doc = JSON.parse(out.join("\n")) as Extract<LsDocument, { members: unknown }>;
+    expect(doc.members.map((m) => m.reason?.code ?? null)).toEqual(["unknown-kind", "unknown-kind", "unknown-kind", null]);
+    expect(doc.members[0].reason?.message).toMatch(/known kinds: chant, other, workspace$/);
+  });
+});

package/src/workspace/check-contract.test.ts

@@ -0,0 +1,127 @@
+/**
+ * The read contract for `chant workspace check --json` and `--format json`
+ * (#2536, #2524 D15): the output schema is a valid draft 2020-12 document, its
+ * closed code lists match the code, and real output validates against it, for
+ * the chant repo (#2557), for built workspaces, and for `--at <rev>`.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, commitAll, contract, declaration, git, REPO, repo, scratchDir, validSchema } from "./__fixtures__/contract-repo";
+import schema from "./check.schema.json";
+import { WORKSPACE_ERROR_CODES } from "./declaration";
+import { CHECK_CODES, CHECK_CONTRACT_VERSION, CHECK_ERROR_CODES, CHECK_OUTPUT_SCHEMA_ID, runChecks, type CheckDocument } from "./lineage-check";
+
+afterAll(cleanScratch);
+
+const { expectValid } = contract(schema);
+
+function result(doc: CheckDocument): Extract<CheckDocument, { findings: unknown }> {
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return doc;
+}
+
+const ruleIds = (doc: Extract<CheckDocument, { findings: unknown }>) => doc.declaration?.diagnostics.map((d) => d.ruleId) ?? [];
+
+describe("check output schema", () => {
+  test("is a valid draft 2020-12 document with the published $id", () => {
+    expect(schema.$schema).toBe("https://json-schema.org/draft/2020-12/schema");
+    expect(validSchema(schema)).toBe(true);
+    expect(schema.$id).toBe(CHECK_OUTPUT_SCHEMA_ID);
+    expect(CHECK_CONTRACT_VERSION).toBe(1);
+  });
+
+  test("lists exactly the codes the code can return", () => {
+    expect(schema.$defs.lockFinding.properties.code.enum).toEqual([...CHECK_CODES]);
+    expect(schema.$defs.failure.properties.error.properties.code.enum).toEqual([...CHECK_ERROR_CODES]);
+    expect(schema.$defs.diagnostic.properties.code.enum).toEqual([...WORKSPACE_ERROR_CODES]);
+  });
+});
+
+describe("chant workspace check on the chant repo (#2557)", () => {
+  test("validates in the working tree and at HEAD", async () => {
+    const now = result(await runChecks(REPO));
+    expectValid(now);
+    expect(now.workspace).toEqual({ name: "chant", root: "." });
+    expect(now.declaration?.file).toBe("chant.workspace.json");
+
+    const head = result(await runChecks(join(REPO, "packages", "core"), "HEAD"));
+    expectValid(head);
+    expect(head.at).toBe(git(REPO, "rev-parse", "HEAD"));
+    expect(head.workspace).toEqual({ name: "chant", root: "." });
+    expect(head.declaration?.file).toBe("../../chant.workspace.json");
+  });
+});
+
+describe("chant workspace check on built workspaces", () => {
+  test("a lock with no declaration: the lock findings carry their reason code", async () => {
+    const root = repo({ ".chant/workspace.lock.json": "{ not json" });
+    const doc = result(await runChecks(root));
+    expectValid(doc);
+    expect(doc.workspace).toBeNull();
+    expect(doc.declaration).toBeUndefined();
+    expect(doc.ok).toBe(false);
+    expect(doc.findings.map((f) => f.code)).toEqual(["lock-invalid"]);
+  });
+
+  test("declaration findings carry WSP ids, and an unreadable declaration is WSP001 with its reason code", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration([
+        { name: "gone", dir: "gone", kind: "chant" },
+        { name: "infra", dir: "infra", kind: "terraform" },
+      ]),
+      "infra/main.tf": "",
+    });
+    const doc = result(await runChecks(root));
+    expectValid(doc);
+    expect(doc.ok).toBe(false);
+    expect(doc.workspace).toEqual({ name: "acme", root: "." });
+    expect(ruleIds(doc)).toEqual(["WSP004", "WSP003"]);
+
+    const tooOld = repo({ "chant.workspace.json": declaration([], { minReader: "999.0.0" }) });
+    const pinned = repo({ "chant.workspace.json": declaration([], { pins: [{ package: "@intentius/chant", version: "0.0.1" }] }) });
+    for (const [dir, code] of [
+      [tooOld, "reader-too-old"],
+      [pinned, "root-chant-required"],
+    ] as const) {
+      const d = result(await runChecks(dir));
+      expectValid(d);
+      expect(d.workspace).toEqual({ name: null, root: "." });
+      expect(d.declaration?.diagnostics.map((x) => [x.ruleId, x.code])).toEqual([["WSP001", code]]);
+    }
+  });
+
+  test("--at <rev> checks the declaration and lock as they were at the revision", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration([{ name: "web", dir: "web", kind: "chant" }]),
+      "web/chant.config.ts": "",
+    });
+    const first = commitAll(root, "one");
+    // Break the working tree after the commit: the declaration, a member and the lock.
+    writeFileSync(join(root, "chant.workspace.json"), "{ broken");
+    mkdirSync(join(root, "web", ".chant"), { recursive: true });
+    writeFileSync(join(root, "web", ".chant", "workspace.lock.json"), "{ broken");
+
+    const at = result(await runChecks(join(root, "web"), first));
+    expectValid(at);
+    expect(at.at).toBe(first);
+    expect(at.ok).toBe(true);
+    expect(at.lock).toBeNull();
+    expect(at.declaration).toMatchObject({ file: "../chant.workspace.json", diagnostics: [], ok: true });
+
+    const now = result(await runChecks(join(root, "web")));
+    expectValid(now);
+    expect(now.ok).toBe(false);
+    expect(now.findings.map((f) => f.code)).toEqual(["lock-invalid"]);
+    expect(now.declaration?.diagnostics.map((d) => [d.ruleId, d.code])).toEqual([["WSP001", "declaration-unparseable"]]);
+  });
+
+  test("--at outside git or at an unknown revision is a failure document", async () => {
+    const outside = scratchDir("chant-check-nogit-");
+    const empty = repo({});
+    const docs = [await runChecks(outside, "HEAD"), await runChecks(empty, "no-such-rev")];
+    for (const d of docs) expectValid(d);
+    expect(docs.map((d) => ("error" in d ? d.error.code : "ok"))).toEqual(["not-a-git-repository", "revision-unknown"]);
+  });
+});

package/src/workspace/check.schema.json

@@ -0,0 +1,347 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/check/v1/check.schema.json",
+  "title": "chant workspace check output",
+  "description": "What `chant workspace check --format json` prints, version 1 of the read contract for checking a workspace (#2524 D9, D15, D16, #2535, #2536). The lineage lock findings carry reason codes; the declaration findings carry WSP ids from the check catalog, and WSP001, a declaration that can't be read, also carries the declaration's reason code. Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists: a new code is a new contract version. Contract version 1 is written by chant 0.81.0 and newer; a reader that needs it refuses output whose `contract` it doesn't know. Every code is in the one closed list of `reason-codes.ts`.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "description": "The checks ran. Exit code 0 when ok is true, 1 otherwise.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "at",
+        "workspace",
+        "ok",
+        "lock",
+        "findings"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/check/v1/check.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string",
+          "description": "The version of the chant that ran the checks."
+        },
+        "at": {
+          "description": "The full commit id the checks read (--at), or null for the working tree.",
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^[0-9a-f]{40,64}$"
+        },
+        "error": false,
+        "workspace": {
+          "description": "The workspace whose declaration was checked, or null when no declaration sits between the directory and the git root.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "name",
+                "root"
+              ],
+              "properties": {
+                "name": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "The declared name, or null when the declaration can't be read."
+                },
+                "root": {
+                  "type": "string",
+                  "description": "The workspace root relative to the git root, with / separators, \".\" for the git root itself. An absolute path outside a git repository."
+                }
+              }
+            }
+          ]
+        },
+        "ok": {
+          "type": "boolean",
+          "description": "No lock finding, and no declaration finding of error severity."
+        },
+        "lock": {
+          "description": "The lineage lock's path, or null when the directory has none.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "const": ".chant/workspace.lock.json"
+            }
+          ]
+        },
+        "findings": {
+          "description": "The lineage lock findings.",
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/lockFinding"
+          }
+        },
+        "declaration": {
+          "$ref": "#/$defs/declaration"
+        }
+      }
+    },
+    "lockFinding": {
+      "type": "object",
+      "required": [
+        "code",
+        "scope",
+        "message"
+      ],
+      "properties": {
+        "code": {
+          "enum": [
+            "lock-invalid",
+            "manual-step-open"
+          ]
+        },
+        "scope": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The lock scope, or null for the lock as a whole."
+        },
+        "path": {
+          "type": "string"
+        },
+        "message": {
+          "type": "string"
+        }
+      }
+    },
+    "declaration": {
+      "description": "Present when a declaration sits between the directory and the git root.",
+      "type": "object",
+      "required": [
+        "file",
+        "diagnostics",
+        "suppressed",
+        "ok"
+      ],
+      "properties": {
+        "file": {
+          "type": "string",
+          "description": "The declaration, relative to the directory the command ran in."
+        },
+        "ok": {
+          "type": "boolean"
+        },
+        "diagnostics": {
+          "description": "Active findings, in the shape `chant lint --format json` prints, sorted by position.",
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/diagnostic"
+          }
+        },
+        "suppressed": {
+          "description": "Findings an entry's suppress turned off, with its reason. They never fail the command.",
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/suppressed"
+          }
+        }
+      }
+    },
+    "diagnostic": {
+      "type": "object",
+      "required": [
+        "file",
+        "line",
+        "column",
+        "ruleId",
+        "severity",
+        "message"
+      ],
+      "properties": {
+        "file": {
+          "type": "string",
+          "description": "Relative to the directory the command ran in."
+        },
+        "line": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "column": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "endLine": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "endColumn": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "ruleId": {
+          "type": "string",
+          "pattern": "^WSP[0-9]{3}$",
+          "description": "The declaration check's id, from the catalog on the workspace check page."
+        },
+        "severity": {
+          "enum": [
+            "error",
+            "warning",
+            "info"
+          ]
+        },
+        "message": {
+          "type": "string"
+        },
+        "entity": {
+          "type": "string",
+          "description": "The member or group the finding is about."
+        },
+        "code": {
+          "enum": [
+            "declaration-missing",
+            "declaration-ambiguous",
+            "declaration-unparseable",
+            "declaration-invalid",
+            "placement-invalid",
+            "reader-too-old",
+            "root-chant-required",
+            "not-a-git-repository",
+            "revision-unknown"
+          ],
+          "description": "For WSP001: why the declaration can't be read."
+        }
+      }
+    },
+    "suppressed": {
+      "type": "object",
+      "required": [
+        "file",
+        "line",
+        "column",
+        "ruleId",
+        "severity",
+        "message",
+        "reason"
+      ],
+      "properties": {
+        "file": {
+          "type": "string",
+          "description": "Relative to the directory the command ran in."
+        },
+        "line": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "column": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "endLine": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "endColumn": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "ruleId": {
+          "type": "string",
+          "pattern": "^WSP[0-9]{3}$",
+          "description": "The declaration check's id, from the catalog on the workspace check page."
+        },
+        "severity": {
+          "enum": [
+            "error",
+            "warning",
+            "info"
+          ]
+        },
+        "message": {
+          "type": "string"
+        },
+        "entity": {
+          "type": "string",
+          "description": "The member or group the finding is about."
+        },
+        "code": {
+          "enum": [
+            "declaration-missing",
+            "declaration-ambiguous",
+            "declaration-unparseable",
+            "declaration-invalid",
+            "placement-invalid",
+            "reader-too-old",
+            "root-chant-required",
+            "not-a-git-repository",
+            "revision-unknown"
+          ],
+          "description": "For WSP001: why the declaration can't be read."
+        },
+        "reason": {
+          "type": "string"
+        }
+      }
+    },
+    "failure": {
+      "description": "The checks could not run: --at outside a git repository or at an unknown revision. Exit code 1.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/check/v1/check.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message",
+            "location"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "not-a-git-repository",
+                "revision-unknown"
+              ]
+            },
+            "message": {
+              "type": "string"
+            },
+            "location": {
+              "type": "null"
+            }
+          }
+        },
+        "findings": false,
+        "declaration": false
+      }
+    }
+  }
+}