@intentius/chant 0.124.51 → 0.124.54

package/src/graph-schema/generate.ts

@@ -0,0 +1,263 @@
+/**
+ * Generates the graph JSON Schema set from chant core's TypeScript types
+ * (#4527; schema home ruled on INTENTIUS/behold#1025 Q5, 2026-10-26).
+ *
+ * One schema file, ./graph.schema.json, covers the documents a Go engine or
+ * a non-chant reader has to write or read without importing chant:
+ *
+ * - `EngineGraphDocument` (../engine-facts.ts): what `choudoufu live-graph
+ *   -json` and `plunge graph --json` print, a `GraphIR` at version 1 with
+ *   `meta.engineGraph`, node `facts` and edge `grain`;
+ * - `IndexDocument` (../lifecycle/index-document.ts): one index version;
+ * - `AdoptionFile` (../lifecycle/adoption-file.ts): the `adopt: "v1"` file
+ *   choudoufu, plunge and chant adopt indexed resources from (#4536).
+ *
+ * Each is a `$defs` entry, so a test validates against
+ * `<$id>#/$defs/EngineGraphDocument`, `<$id>#/$defs/IndexDocument` or
+ * `<$id>#/$defs/AdoptionFile`. The
+ * fixtures in ./fixtures are written from ./fixtures.ts, which the compiler
+ * checks against the same types.
+ *
+ * The emitter is a small walk over the TypeScript checker, not a dependency:
+ * the repo already ships `typescript`, and the types use only what JSON can
+ * hold (strings, numbers, booleans, literals, unions, arrays, records and
+ * interfaces). Anything else (a function, a class, a generic interface) is
+ * refused with its path, so a type that cannot be printed fails generation
+ * rather than printing a loose schema.
+ *
+ * Object schemas are closed (`additionalProperties: false`) unless the type
+ * has an index signature, so an engine's test catches a misspelled field.
+ * Readers still ignore fields they do not know (GRAPH_IR_VERSION's rule): the
+ * closed schema is for writers testing their output against the chant they
+ * target.
+ *
+ * `npm run generate:graph-schema` writes the files; `-- --check` exits 1 when
+ * the checked-in files differ, and ./graph-schema.test.ts asserts the same.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import * as ts from "typescript";
+import { GRAPH_SCHEMA_FIXTURES } from "./fixtures";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const coreSrc = resolve(here, "..");
+
+/** The schema's `$id`. */
+export const GRAPH_SCHEMA_ID = "https://intentius.io/chant/schemas/graph/v1/graph.schema.json";
+
+/** Where the generated schema is checked in. */
+export const GRAPH_SCHEMA_PATH = join(here, "graph.schema.json");
+
+/** Where the generated fixtures are checked in. */
+export const GRAPH_SCHEMA_FIXTURE_DIR = join(here, "fixtures");
+
+/** The root types, by the file that declares each. */
+const ROOTS: ReadonlyArray<{ file: string; name: string }> = [
+  { file: join(coreSrc, "engine-facts.ts"), name: "EngineGraphDocument" },
+  { file: join(coreSrc, "lifecycle", "index-document.ts"), name: "IndexDocument" },
+  { file: join(coreSrc, "lifecycle", "adoption-file.ts"), name: "AdoptionFile" },
+];
+
+type Schema = Record<string, unknown>;
+
+/** `{@link X}` and `{@link X text}` as plain text. */
+function plainDoc(text: string): string {
+  return text
+    .replace(/\{@link(?:code|plain)?\s+([^}\s|]+)(?:[\s|]+([^}]*))?\}/g, (_m, name: string, label?: string) => (label?.trim() ? label.trim() : name))
+    .replace(/\r\n/g, "\n")
+    // Unwrap hard-wrapped lines; keep paragraph breaks and list items.
+    .replace(/([^\n])\n(?!\n|\s*[-*] |\s*\d+\. )\s*/g, "$1 ")
+    .trim();
+}
+
+function docOf(symbol: ts.Symbol | undefined, checker: ts.TypeChecker): string | undefined {
+  if (!symbol) return undefined;
+  const text = plainDoc(ts.displayPartsToString(symbol.getDocumentationComment(checker)));
+  return text === "" ? undefined : text;
+}
+
+/** Declared under packages/core/src, so the name is chant's and not the standard library's. */
+function isCoreDeclaration(symbol: ts.Symbol | undefined): boolean {
+  const decl = symbol?.declarations?.[0];
+  if (!decl) return false;
+  const file = resolve(decl.getSourceFile().fileName);
+  return file.startsWith(coreSrc + sep) && !file.includes(`${sep}node_modules${sep}`);
+}
+
+function stableJson(value: unknown): string {
+  return JSON.stringify(value);
+}
+
+class Emitter {
+  readonly defs = new Map<string, Schema>();
+  private readonly defTypes = new Map<string, ts.Type>();
+
+  constructor(private readonly checker: ts.TypeChecker) {}
+
+  /** A `$ref` for a named chant type, else its structure inline. */
+  emit(type: ts.Type, path: string): Schema {
+    const name = this.defName(type, path);
+    if (name === undefined) return this.structure(type, path);
+    const seen = this.defTypes.get(name);
+    if (seen !== undefined && seen !== type) throw new Error(`graph schema: two types are named ${name} (at ${path})`);
+    if (seen === undefined) {
+      this.defTypes.set(name, type);
+      this.defs.set(name, {}); // placeholder, so a recursive type refers to itself
+      const symbol = type.aliasSymbol ?? type.getSymbol();
+      const description = docOf(symbol, this.checker);
+      this.defs.set(name, { ...(description ? { description } : {}), ...this.structure(type, name) });
+    }
+    return { $ref: `#/$defs/${name}` };
+  }
+
+  private defName(type: ts.Type, path: string): string | undefined {
+    if (type.aliasSymbol && !type.aliasTypeArguments?.length && isCoreDeclaration(type.aliasSymbol)) {
+      return type.aliasSymbol.getName();
+    }
+    const symbol = type.getSymbol();
+    if (
+      symbol &&
+      type.flags & ts.TypeFlags.Object &&
+      symbol.flags & ts.SymbolFlags.Interface &&
+      isCoreDeclaration(symbol)
+    ) {
+      if ((type as ts.TypeReference).typeArguments?.length) throw new Error(`graph schema: generic interface ${symbol.getName()} at ${path}`);
+      return symbol.getName();
+    }
+    return undefined;
+  }
+
+  private structure(type: ts.Type, path: string): Schema {
+    const f = type.flags;
+    if (f & (ts.TypeFlags.Any | ts.TypeFlags.Unknown)) return {};
+    if (f & ts.TypeFlags.String) return { type: "string" };
+    if (f & ts.TypeFlags.Number) return { type: "number" };
+    if (f & ts.TypeFlags.Boolean) return { type: "boolean" };
+    if (f & ts.TypeFlags.Null) return { type: "null" };
+    if (f & ts.TypeFlags.StringLiteral) return { const: (type as ts.StringLiteralType).value };
+    if (f & ts.TypeFlags.NumberLiteral) return { const: (type as ts.NumberLiteralType).value };
+    if (f & ts.TypeFlags.BooleanLiteral) return { const: (type as unknown as { intrinsicName: string }).intrinsicName === "true" };
+    if (type.isUnion()) return this.union(type, path);
+    if (this.checker.isTupleType(type)) {
+      const args = this.checker.getTypeArguments(type as ts.TypeReference);
+      return { type: "array", prefixItems: args.map((a, i) => this.emit(a, `${path}[${i}]`)), items: false };
+    }
+    if (this.checker.isArrayType(type)) {
+      const [item] = this.checker.getTypeArguments(type as ts.TypeReference);
+      return { type: "array", items: this.emit(item!, `${path}[]`) };
+    }
+    if (f & ts.TypeFlags.Object || type.isIntersection()) return this.object(type, path);
+    throw new Error(`graph schema: cannot print the type at ${path} (${this.checker.typeToString(type)})`);
+  }
+
+  private union(type: ts.UnionType, path: string): Schema {
+    let members = type.types.filter((t) => !(t.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Void)));
+    const bools = members.filter((t) => t.flags & ts.TypeFlags.BooleanLiteral);
+    const hasBoolean = bools.length === 2;
+    if (hasBoolean) members = members.filter((t) => !(t.flags & ts.TypeFlags.BooleanLiteral));
+    const strings = members.filter((t) => t.flags & ts.TypeFlags.StringLiteral).map((t) => (t as ts.StringLiteralType).value);
+    const rest = members.filter((t) => !(t.flags & ts.TypeFlags.StringLiteral));
+    const out: Schema[] = [];
+    if (strings.length > 0) out.push({ type: "string", enum: [...new Set(strings)].sort() });
+    if (hasBoolean) out.push({ type: "boolean" });
+    for (const t of rest) out.push(this.emit(t, path));
+    if (out.length === 1) return out[0]!;
+    if (out.length === 0) throw new Error(`graph schema: an empty union at ${path}`);
+    return { anyOf: out.sort((a, b) => (stableJson(a) < stableJson(b) ? -1 : stableJson(a) > stableJson(b) ? 1 : 0)) };
+  }
+
+  private object(type: ts.Type, path: string): Schema {
+    if (type.getCallSignatures().length > 0 || type.getConstructSignatures().length > 0) {
+      throw new Error(`graph schema: a function type at ${path}`);
+    }
+    const properties: Record<string, Schema> = {};
+    const required: string[] = [];
+    for (const prop of this.checker.getPropertiesOfType(type)) {
+      const name = prop.getName();
+      const propPath = `${path}.${name}`;
+      const decl = prop.valueDeclaration ?? prop.declarations?.[0];
+      if (decl && (ts.isMethodSignature(decl) || ts.isMethodDeclaration(decl))) throw new Error(`graph schema: a method at ${propPath}`);
+      // The declared type node keeps an alias (`EdgeGrain`) that the optional
+      // property's `T | undefined` loses.
+      const typeNode = decl && (ts.isPropertySignature(decl) || ts.isPropertyDeclaration(decl)) ? decl.type : undefined;
+      const propType = typeNode ? this.checker.getTypeFromTypeNode(typeNode) : this.checker.getTypeOfSymbol(prop);
+      const description = docOf(prop, this.checker);
+      const schema = this.emit(propType, propPath);
+      properties[name] = description ? { description, ...schema } : schema;
+      if (!(prop.flags & ts.SymbolFlags.Optional)) required.push(name);
+    }
+    const index = this.checker.getIndexInfoOfType(type, ts.IndexKind.String);
+    const out: Schema = { type: "object" };
+    if (Object.keys(properties).length > 0) out.properties = properties;
+    if (required.length > 0) out.required = required;
+    if (index) {
+      if (!(index.type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown))) out.additionalProperties = this.emit(index.type, `${path}[string]`);
+    } else {
+      out.additionalProperties = false;
+    }
+    return out;
+  }
+}
+
+function program(): ts.Program {
+  return ts.createProgram(
+    ROOTS.map((r) => r.file),
+    {
+      strict: true,
+      noEmit: true,
+      skipLibCheck: true,
+      target: ts.ScriptTarget.ES2022,
+      module: ts.ModuleKind.ESNext,
+      moduleResolution: ts.ModuleResolutionKind.Bundler,
+      allowImportingTsExtensions: true,
+      resolveJsonModule: true,
+      types: [],
+    },
+  );
+}
+
+/** The schema set, as an object. */
+export function generateGraphSchema(): Schema {
+  const prog = program();
+  const checker = prog.getTypeChecker();
+  const emitter = new Emitter(checker);
+  const roots: Schema[] = [];
+  for (const root of ROOTS) {
+    const source = prog.getSourceFile(root.file);
+    if (!source) throw new Error(`graph schema: ${root.file} is not in the program`);
+    const moduleSymbol = checker.getSymbolAtLocation(source);
+    const symbol = moduleSymbol && checker.getExportsOfModule(moduleSymbol).find((s) => s.getName() === root.name);
+    if (!symbol) throw new Error(`graph schema: ${root.file} exports no ${root.name}`);
+    roots.push(emitter.emit(checker.getDeclaredTypeOfSymbol(symbol), root.name));
+  }
+  const defs = Object.fromEntries([...emitter.defs.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: GRAPH_SCHEMA_ID,
+    title: "chant-graph/v1",
+    description:
+      "Generated from chant core's TypeScript types (packages/core/src/engine-facts.ts, packages/core/src/lifecycle/index-document.ts, packages/core/src/lifecycle/adoption-file.ts) by `npm run generate:graph-schema`; do not edit by hand. Three documents: an engine graph (`#/$defs/EngineGraphDocument`, what `choudoufu live-graph -json` and `plunge graph --json` print, chant#4520), an index version (`#/$defs/IndexDocument`, behold#1025) and an adoption file (`#/$defs/AdoptionFile`, the `adopt: v1` input choudoufu, plunge and chant adopt from, chant#4536). Objects are closed so a writer's test catches a misspelled field; a reader ignores fields it does not know.",
+    anyOf: roots,
+    $defs: defs,
+  };
+}
+
+/** Every generated file, by path, with its contents. */
+export function generatedGraphSchemaFiles(): Map<string, string> {
+  const files = new Map<string, string>();
+  files.set(GRAPH_SCHEMA_PATH, `${JSON.stringify(generateGraphSchema(), null, 2)}\n`);
+  for (const [name, doc] of Object.entries(GRAPH_SCHEMA_FIXTURES)) {
+    files.set(join(GRAPH_SCHEMA_FIXTURE_DIR, `${name}.json`), `${JSON.stringify(doc, null, 2)}\n`);
+  }
+  return files;
+}
+
+/** The generated files whose checked-in copy is missing or differs. */
+export function staleGraphSchemaFiles(): string[] {
+  const stale: string[] = [];
+  for (const [path, contents] of generatedGraphSchemaFiles()) {
+    if (!existsSync(path) || readFileSync(path, "utf-8") !== contents) stale.push(path);
+  }
+  return stale;
+}

package/src/graph-schema/graph-schema.test.ts

@@ -0,0 +1,153 @@
+// The graph JSON Schema set and its fixtures (#4527): generated from the
+// TypeScript types, checked in, and in sync. Engines (choudoufu#2285,
+// plunge#40) validate their output against the same files.
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import Ajv2020 from "ajv/dist/2020";
+import { GRAPH_SCHEMA_FIXTURES, GRAPH_SCHEMA_FIXTURE_DEFS } from "./fixtures";
+import { GRAPH_SCHEMA_FIXTURE_DIR, GRAPH_SCHEMA_ID, GRAPH_SCHEMA_PATH, generateGraphSchema, staleGraphSchemaFiles } from "./generate";
+import { validateIndexDocument, type IndexDocument } from "../lifecycle/index-document";
+import { adoptionFileProblemsAgainst, type AdoptionFile } from "../lifecycle/adoption-file";
+import { GRAPH_IR_VERSION } from "../graph-ir";
+
+const schema = JSON.parse(readFileSync(GRAPH_SCHEMA_PATH, "utf-8")) as { $id: string; $defs: Record<string, unknown> };
+const ajv = new Ajv2020({ allErrors: true, strict: true });
+ajv.addSchema(schema);
+const validator = (def: string) => ajv.getSchema(`${GRAPH_SCHEMA_ID}#/$defs/${def}`)!;
+const fixture = (name: string): Record<string, unknown> =>
+  JSON.parse(readFileSync(join(GRAPH_SCHEMA_FIXTURE_DIR, `${name}.json`), "utf-8")) as Record<string, unknown>;
+const clone = <T>(x: T): T => JSON.parse(JSON.stringify(x)) as T;
+
+describe("graph schema sync (#4527)", () => {
+  it("the checked-in schema and fixtures match the TypeScript types (npm run generate:graph-schema if this fails)", () => {
+    const stale = staleGraphSchemaFiles().map((p) => relative(GRAPH_SCHEMA_FIXTURE_DIR, p));
+    expect(stale).toEqual([]);
+  });
+
+  it("covers the three documents in one set, with the engine facts and edge grain", () => {
+    const generated = generateGraphSchema() as { $defs: Record<string, unknown> };
+    for (const def of ["EngineGraphDocument", "IndexDocument", "AdoptionFile", "AdoptionSelection", "AdoptionIndexRef", "GraphIR", "IRNode", "IREdge", "EngineFacts", "EngineGraphMeta", "EdgeGrain"]) {
+      expect(Object.keys(generated.$defs)).toContain(def);
+    }
+  });
+
+  it("keeps GraphIR at version 1", () => {
+    expect(GRAPH_IR_VERSION).toBe(1);
+    const doc = (schema.$defs.EngineGraphDocument as { properties: { version: unknown } }).properties.version;
+    expect(doc).toEqual({ const: 1 });
+  });
+});
+
+describe("graph schema fixtures (#4527)", () => {
+  for (const [name, def] of Object.entries(GRAPH_SCHEMA_FIXTURE_DEFS)) {
+    it(`${name}.json validates as ${def}`, () => {
+      const validate = validator(def);
+      const ok = validate(fixture(name));
+      expect(validate.errors ?? []).toEqual([]);
+      expect(ok).toBe(true);
+    });
+  }
+
+  it("the index fixture's stamp agrees with itself", () => {
+    expect(() => validateIndexDocument(GRAPH_SCHEMA_FIXTURES.index as IndexDocument)).not.toThrow();
+  });
+
+  it("the adoption fixture names the index fixture's version, digest and node (#4536)", () => {
+    expect(adoptionFileProblemsAgainst(fixture("adopt") as unknown as AdoptionFile, fixture("index") as unknown as IndexDocument)).toEqual([]);
+  });
+
+  it("each engine fixture names its engine and carries facts and grain", () => {
+    for (const [name, engine, grains] of [
+      ["choudoufu.engine-graph", "choudoufu", ["block"]],
+      ["plunge.engine-graph", "plunge", ["instance", "property"]],
+    ] as const) {
+      const doc = fixture(name) as { meta: { engineGraph: { engine: { name: string } } }; nodes: Array<{ facts?: unknown }>; edges: Array<{ grain?: string }> };
+      expect(doc.meta.engineGraph.engine.name).toBe(engine);
+      expect(doc.nodes.some((n) => n.facts !== undefined)).toBe(true);
+      expect([...new Set(doc.edges.map((e) => e.grain))].sort()).toEqual(grains);
+    }
+  });
+
+  it("plunge's markers come from the record and its ownership stops at bound or pending (#4520 Q5)", () => {
+    const doc = fixture("plunge.engine-graph") as { nodes: Array<{ facts?: { ownership?: string; markers?: { source: string } } }> };
+    for (const n of doc.nodes) {
+      if (n.facts?.markers) expect(n.facts.markers.source).toBe("record");
+      if (n.facts?.ownership) expect(["bound", "pending"]).toContain(n.facts.ownership);
+    }
+  });
+});
+
+describe("graph schema refusals (#4527)", () => {
+  const engine = validator("EngineGraphDocument");
+  const base = () => clone(fixture("choudoufu.engine-graph")) as {
+    version: unknown;
+    meta: Record<string, unknown> & { engineGraph: Record<string, unknown> };
+    nodes: Array<Record<string, unknown> & { facts?: Record<string, unknown> }>;
+    edges: Array<Record<string, unknown>>;
+  };
+
+  it("refuses a misspelled facts field", () => {
+    const doc = base();
+    doc.nodes[0]!.facts = { ...doc.nodes[0]!.facts, ownedby: "marker" };
+    expect(engine(doc)).toBe(false);
+  });
+
+  it("refuses an ownership value outside bound, unowned, pending and foreign", () => {
+    const doc = base();
+    doc.nodes[0]!.facts = { ...doc.nodes[0]!.facts, ownership: "owned" };
+    expect(engine(doc)).toBe(false);
+  });
+
+  it("refuses a grain outside block, instance and property", () => {
+    const doc = base();
+    doc.edges[0]!.grain = "module";
+    expect(engine(doc)).toBe(false);
+  });
+
+  it("refuses markers without encoding and source", () => {
+    const doc = base();
+    doc.nodes[0]!.facts = { markers: { owner: "web" } };
+    expect(engine(doc)).toBe(false);
+  });
+
+  it("refuses a document with no meta.engineGraph, or at another version", () => {
+    const noMeta = base();
+    delete (noMeta.meta as { engineGraph?: unknown }).engineGraph;
+    expect(engine(noMeta)).toBe(false);
+    const v2 = base();
+    v2.version = 2;
+    expect(engine(v2)).toBe(false);
+  });
+
+  it("lets other keys sit in meta beside engineGraph (meta is an open bag)", () => {
+    const doc = base();
+    doc.meta._behaviour = { engine: "x" };
+    expect(engine(doc)).toBe(true);
+  });
+
+  it("refuses an adoption file at another version, with no select, or with a misspelled field (#4536)", () => {
+    const adopt = validator("AdoptionFile");
+    const base = () => clone(fixture("adopt")) as Record<string, unknown> & { select: Array<Record<string, unknown>> };
+    expect(adopt(base())).toBe(true);
+    const v2 = base();
+    v2.adopt = "v2";
+    expect(adopt(v2)).toBe(false);
+    const noSelect = base();
+    delete (noSelect as { select?: unknown }).select;
+    expect(adopt(noSelect)).toBe(false);
+    const typo = base();
+    typo.select[0]!.address = "aws_s3_bucket.x";
+    expect(adopt(typo)).toBe(false);
+    const noType = base();
+    delete noType.select[0]!.type;
+    expect(adopt(noType)).toBe(true);
+  });
+
+  it("refuses an index coverage verdict outside listed and the unobserved reasons", () => {
+    const index = validator("IndexDocument");
+    const doc = clone(fixture("index")) as { coverage: Array<Record<string, unknown>> };
+    doc.coverage[0]!.verdict = "missing";
+    expect(index(doc)).toBe(false);
+  });
+});