@intentius/chant 0.100.0 → 0.102.0

package/src/workspace/kinds.test.ts

@@ -61,10 +61,10 @@ function pkg(name: string, version: string, kinds: unknown[] | null, extra: Reco
 }
 
 describe("the built-in kinds (#2535)", () => {
-  test("are chant, workspace and other, and the group kind examples", () => {
-    expect(BUILTIN_KINDS.map((k) => `${k.name}:${k.shape}`)).toEqual(["chant:member", "workspace:member", "other:member", "examples:group"]);
+  test("are chant, workspace, design and other, and the group kind examples", () => {
+    expect(BUILTIN_KINDS.map((k) => `${k.name}:${k.shape}`)).toEqual(["chant:member", "workspace:member", "other:member", "design:member", "examples:group"]);
     const registry = builtinKindRegistry();
-    expect(registry.names()).toEqual(["chant", "other", "workspace"]);
+    expect(registry.names()).toEqual(["chant", "design", "other", "workspace"]);
     expect(registry.get(EXAMPLES_KIND)?.shape).toBe("group");
   });
 
@@ -203,7 +203,7 @@ describe("loadKindRegistry: kinds from the pins", () => {
     const { registry, problems } = loadKindRegistry([{ package: "@acme/chant-lexicon-tf", version: "1.2.3", path: null }], root);
     expect(problems).toEqual([]);
     expect(registry.get("terraform")).toMatchObject({ source: "@acme/chant-lexicon-tf", precedence: 400 });
-    expect(registry.names()).toEqual(["chant", "other", "terraform", "workspace"]);
+    expect(registry.names()).toEqual(["chant", "design", "other", "terraform", "workspace"]);
     expect(existsSync(join(root, "node_modules/@acme/chant-lexicon-tf/IMPORTED"))).toBe(false);
     expect((globalThis as { __chantKindsImported?: boolean }).__chantKindsImported).toBeUndefined();
   });
@@ -223,7 +223,7 @@ describe("loadKindRegistry: kinds from the pins", () => {
       ],
       root,
     );
-    expect(registry.names()).toEqual(["chant", "other", "workspace"]);
+    expect(registry.names()).toEqual(["chant", "design", "other", "workspace"]);
     expect(problems).toEqual([
       { pin: 1, message: "pinned package absent is not installed; install it to read the kinds it supplies" },
       { pin: 2, message: "tf-kinds is pinned at 1.0.0, and 2.0.0 is installed" },

package/src/workspace/kinds.ts

@@ -3,8 +3,8 @@
  * `examples`).
  *
  * A kind is data: a name, a precedence and a probe that says what its
- * directory holds. Probes run no code (K3). Four kinds are built in: the
- * member kinds `chant`, `workspace` and `other`, and the group kind
+ * directory holds. Probes run no code (K3). Five kinds are built in: the
+ * member kinds `chant`, `workspace`, `design` and `other`, and the group kind
  * `examples`. Every other kind comes from a pinned package, which publishes
  * its kinds as a JSON file at a `./workspace-kinds` subpath, the way a
  * lexicon publishes a slim `./detect` entry (#426). chant finds that file
@@ -23,6 +23,7 @@ import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import schema from "./workspace-kinds.schema.json";
 import type { WorkspaceTree } from "./tree";
 import { joinPath, skippedDir } from "./tree";
+import { checkPinIntegrity } from "./pin-integrity";
 
 export const KINDS_SCHEMA_ID = schema.$id;
 
@@ -111,6 +112,9 @@ export interface KindRegistry {
 /** The group kind (ws-051). An entry of this kind is a group, not a member. */
 export const EXAMPLES_KIND = "examples";
 
+/** The data member kind that holds design artifacts (#2549, ws-062). */
+export const DESIGN_KIND = "design";
+
 export const BUILTIN_KINDS: readonly MemberKind[] = [
   {
     name: "chant",
@@ -123,7 +127,7 @@ export const BUILTIN_KINDS: readonly MemberKind[] = [
   },
   {
     name: "workspace",
-    description: "a nested workspace, with its own chant.workspace.json; opaque to the outer one",
+    description: "a nested workspace, with its own chant.workspace.json; the outer one reads it through its own chant workspace graph and never writes inside it",
     probe: { anyFile: ["chant.workspace.json", "chant.workspace.jsonc"] },
     precedence: 1000,
     shape: "member",
@@ -139,6 +143,15 @@ export const BUILTIN_KINDS: readonly MemberKind[] = [
     outputs: { from: "declared", names: [] },
     source: "builtin",
   },
+  {
+    name: DESIGN_KIND,
+    description: "a data member holding the design artifacts the workspace owns; chant reads its files for record pins and builds nothing",
+    probe: { directory: true },
+    precedence: 0,
+    shape: "member",
+    outputs: { from: "declared", names: [] },
+    source: "builtin",
+  },
   {
     name: EXAMPLES_KIND,
     description: "an example group: every directory its glob matches that holds a chant project is built and linted",
@@ -357,14 +370,15 @@ export interface PackageKinds extends KindData {
 }
 
 /**
- * Where a package's `exports` send `./workspace-kinds`, or undefined when
- * the package doesn't export that subpath. Only the literal key counts: a
- * `./*` pattern maps the subpath to code, which chant never runs for kinds.
+ * Where a package's `exports` send `./workspace-kinds` (or another data
+ * subpath, such as `./workspace-principals`), or undefined when the package
+ * doesn't export it. Only the literal key counts: a `./*` pattern maps the
+ * subpath to code, which chant never runs for plugin data.
  */
-export function kindsExportTarget(pkg: Record<string, unknown>): string | undefined | { problem: string } {
+export function kindsExportTarget(pkg: Record<string, unknown>, subpath: string = KINDS_SUBPATH): string | undefined | { problem: string } {
   const exports = pkg.exports;
   if (!exports || typeof exports !== "object" || Array.isArray(exports)) return undefined;
-  const entry = (exports as Record<string, unknown>)[KINDS_SUBPATH];
+  const entry = (exports as Record<string, unknown>)[subpath];
   if (entry === undefined) return undefined;
   let target: unknown = entry;
   if (target && typeof target === "object" && !Array.isArray(target)) {
@@ -372,10 +386,10 @@ export function kindsExportTarget(pkg: Record<string, unknown>): string | undefi
     target = conditions.default ?? conditions.import ?? conditions.require;
   }
   if (typeof target !== "string") {
-    return { problem: `exports["${KINDS_SUBPATH}"] must name one file, as a string or a "default" condition` };
+    return { problem: `exports["${subpath}"] must name one file, as a string or a "default" condition` };
   }
   if (!target.startsWith("./") || !target.endsWith(".json")) {
-    return { problem: `exports["${KINDS_SUBPATH}"] is ${target}; it must name a .json file inside the package, since chant reads kinds as data and never runs a package's code` };
+    return { problem: `exports["${subpath}"] is ${target}; it must name a .json file inside the package, since chant reads plugin data as data and never runs a package's code` };
   }
   return target;
 }
@@ -471,6 +485,8 @@ export interface PinLike {
   package: string | null;
   version: string | null;
   path: string | null;
+  /** A path pin's content hash (#2547). Checked before anything is read from the directory. */
+  integrity?: string | null;
 }
 
 export interface KindLoadProblem {
@@ -484,6 +500,37 @@ export interface LoadedKinds {
   problems: KindLoadProblem[];
 }
 
+/**
+ * The directory a pin's plugin data is read from: an installed package at
+ * the pinned version, looked up from `workspaceRoot`, or a path pin's
+ * directory, checked against its integrity digest when it has one. Null for
+ * a pin that names neither. Shared by the kinds and the principal classes
+ * (#3080), so both read a pin the same way.
+ */
+export function pinnedPackageDir(pin: PinLike, workspaceRoot: string): { dir: string; source: string } | { problem: string } | null {
+  if (pin.package) {
+    const dir = findInstalledPackage(pin.package, workspaceRoot);
+    if (!dir) return { problem: `pinned package ${pin.package} is not installed; install it to read the kinds it supplies` };
+    let installed: unknown;
+    try {
+      installed = (JSON.parse(readFileSync(join(dir, "package.json"), "utf-8")) as { version?: unknown }).version;
+    } catch {
+      installed = undefined;
+    }
+    if (pin.version && installed !== pin.version) return { problem: `${pin.package} is pinned at ${pin.version}, and ${String(installed ?? "an unknown version")} is installed` };
+    return { dir, source: pin.package };
+  }
+  if (pin.path) {
+    const dir = join(workspaceRoot, ...pin.path.split("/"));
+    if (pin.integrity) {
+      const checked = checkPinIntegrity(dir, pin.integrity, pin.path);
+      if (!checked.ok) return { problem: checked.message };
+    }
+    return { dir, source: pin.path };
+  }
+  return null;
+}
+
 /**
  * Build the registry for a workspace: the built-in kinds plus the kinds
  * every pin publishes. `workspaceRoot` is the absolute workspace root; a
@@ -499,31 +546,13 @@ export function loadKindRegistry(pins: readonly PinLike[], workspaceRoot: string
   const owner = new Map<string, string>();
   const clashing = new Set<string>();
   pins.forEach((pin, i) => {
-    let dir: string | undefined;
-    let source: string;
-    if (pin.package) {
-      source = pin.package;
-      dir = findInstalledPackage(pin.package, workspaceRoot);
-      if (!dir) {
-        problems.push({ pin: i, message: `pinned package ${pin.package} is not installed; install it to read the kinds it supplies` });
-        return;
-      }
-      let installed: unknown;
-      try {
-        installed = (JSON.parse(readFileSync(join(dir, "package.json"), "utf-8")) as { version?: unknown }).version;
-      } catch {
-        installed = undefined;
-      }
-      if (pin.version && installed !== pin.version) {
-        problems.push({ pin: i, message: `${pin.package} is pinned at ${pin.version}, and ${String(installed ?? "an unknown version")} is installed` });
-        return;
-      }
-    } else if (pin.path) {
-      source = pin.path;
-      dir = join(workspaceRoot, ...pin.path.split("/"));
-    } else {
+    const found = pinnedPackageDir(pin, workspaceRoot);
+    if (found === null) return;
+    if ("problem" in found) {
+      problems.push({ pin: i, message: found.problem });
       return;
     }
+    const { dir, source } = found;
     const read = readPackageKinds(dir, source);
     for (const p of read.problems) problems.push({ pin: i, message: p });
     for (const k of read.kinds) {

package/src/workspace/lineage-adopt-cli.ts

@@ -0,0 +1,103 @@
+/**
+ * `chant workspace adopt-lineage [<scope>] --from <repo>[@<ref>][#<member>]
+ * [--tags <glob>] [--index <file>] [--param k=v] [--dry-run] [--json]` and
+ * `chant workspace hash-index --from <repo>[#<member>] [--tags <glob>]
+ * [--output <file>]` (#2551).
+ *
+ * The first gives a scope a git lineage (see ./lineage-adopt.ts). The second
+ * computes the hash index a template's tags give, for the template's CI to
+ * publish as a cache that adopters pass with `--index`. Neither needs a
+ * `chant.workspace.json`.
+ */
+
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { formatError, formatInfo, formatSuccess, formatWarning } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import { adoptLineage, describeAdoption } from "./lineage-adopt";
+import { computeHashIndex, readHashIndex, renderHashIndex, TemplateTags } from "./lineage-hash-index";
+import { parseTemplateSource } from "./lineage-init";
+import { LOCK_FILE, LockError } from "./lineage-lock";
+import { parseParamArgs } from "./template-manifest";
+
+const ADOPT_USAGE =
+  "chant workspace adopt-lineage [<scope>] --from <repo>[@<ref>][#<member>] [--tags <glob>] [--index <file>] [--param name=value] [--dry-run] [--json]";
+const INDEX_USAGE = "chant workspace hash-index --from <repo>[#<member>] [--tags <glob>] [--output <file>]";
+
+export async function runWorkspaceAdoptLineage(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  if (args.extraPositional2) {
+    console.error(formatError({ message: `unexpected argument: ${args.extraPositional2}`, hint: ADOPT_USAGE }));
+    return 1;
+  }
+  if (!args.migrateFrom) {
+    console.error(formatError({ message: "adopt-lineage needs the template: --from <repo>[@<ref>][#<member>]", hint: ADOPT_USAGE }));
+    return 1;
+  }
+  try {
+    const result = adoptLineage({
+      root: process.cwd(),
+      scope: args.extraPositional,
+      from: args.migrateFrom,
+      tags: args.tags,
+      cache: args.index ? readHashIndex(resolve(args.index)) : undefined,
+      params: args.param?.length ? parseParamArgs(args.param) : undefined,
+      dryRun: args.dryRun,
+    });
+    if (args.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return 0;
+    }
+    console.log(describeAdoption(result).join("\n"));
+    if (result.lockIgnored) {
+      console.error(formatWarning({ message: `${LOCK_FILE} is covered by a .gitignore. Commit it with \`git add -f\` so the lineage travels with the project.` }));
+    }
+    if (!result.written) {
+      console.error(formatInfo("--dry-run: nothing written"));
+    } else if (result.by === "lineage") {
+      console.error(formatSuccess(`moved the lineage of "${result.scope}" onto ${result.template}@${result.chosen.tag} in ${LOCK_FILE}. Review and commit it; chant workspace upgrade --to <ref> now reads that repository.`));
+    } else {
+      console.error(
+        formatSuccess(
+          `recorded the lineage of "${result.scope}" in ${LOCK_FILE}${result.trust ? ` and the adopted range in ${result.trust.path}` : ""}. Review and commit both; the range counts once an admin merges it.`,
+        ),
+      );
+    }
+    return 0;
+  } catch (err) {
+    if (!(err instanceof LockError)) throw err;
+    console.error(formatError({ message: err.message, hint: ADOPT_USAGE }));
+    return 1;
+  }
+}
+
+export async function runWorkspaceHashIndex(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const from = args.migrateFrom ?? args.extraPositional;
+  if (!from || (args.migrateFrom && args.extraPositional)) {
+    console.error(formatError({ message: "hash-index needs one template: --from <repo>[#<member>]", hint: INDEX_USAGE }));
+    return 1;
+  }
+  try {
+    const spec = parseTemplateSource(from, process.cwd(), "--from");
+    if (spec.ref !== undefined) throw new LockError(`--from ${from}: the index covers every version tag; leave out "@${spec.ref}" and narrow with --tags`);
+    const tags = new TemplateTags(spec.url, spec.member, spec.member ? `${spec.repo}#${spec.member}` : spec.repo);
+    try {
+      const { index } = computeHashIndex(tags, spec.id, { pattern: args.tags });
+      const text = renderHashIndex(index);
+      if (args.output) {
+        writeFileSync(resolve(args.output), text);
+        console.error(formatSuccess(`wrote the hash index of ${spec.id} (${index.tags.length} version(s)) to ${args.output}`));
+      } else {
+        process.stdout.write(text);
+      }
+      return 0;
+    } finally {
+      tags.dispose();
+    }
+  } catch (err) {
+    if (!(err instanceof LockError)) throw err;
+    console.error(formatError({ message: err.message, hint: INDEX_USAGE }));
+    return 1;
+  }
+}