@githolon/dsl 0.114.0 → 0.116.2

package/src/birth_key_rule.ts

@@ -0,0 +1,472 @@
+// NOMOS — the birth-key write check (CAP-804 / CO2-1687). A field-keyed birth names its workspace from the
+// key at birth, forever; the framework enforces that at runtime with a write-once invariant on the key field
+// (aggregate.ts, BIRTH_KEY_WRITE_ONCE_CODE). This compile-lane pass reads the package's TypeScript SOURCE
+// and WARNS — never refuses — at the exact line of a directive that writes a key field outside the birth in
+// a way the runtime rule will refuse or that means something other than the author thinks:
+//
+//   - `create(Born).set(key, …)` / `ensure(Born, <dynamic id>).set(key, …)` — ANOTHER instance of the born
+//     aggregate carrying a key that names a workspace it is not (the todo profiler's `createList`);
+//   - `existing(Born, id).set(key, …)` / `set(instance(Born, id), key, …)` — an edit of the key, refused
+//     whenever the value differs;
+//   - `ensure(Born, <constant id>).set(key, <constant>)` — a singleton seed that writes a CONSTANT key, which
+//     can equal the born key for at most one workspace.
+//
+// NOT warned: the birth's own recipe (`birth(X, { initialise })` and the framework-generated seed), and a
+// genesis SEED of the identity singleton — `ensure(Born, <constant id>).set(key, <payload value>)` — which
+// is exactly what the write-once rule admits when it re-states the born key.
+//
+// Static and syntactic: no plan is executed, so nothing is skipped because a probe could not run. It runs
+// only in the compile lane (it imports `typescript` and `node:fs`); the sealed engine never loads it.
+
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+import type { AggregateHandle } from "./aggregate.js";
+import { BIRTH_KEY_WRITE_ONCE_CODE } from "./aggregate.js";
+import { CHOOSING_A_BIRTH_KEY_DOC, type BusinessBirthDecl } from "./births.js";
+
+type Mod = Record<string, unknown>;
+
+/** One package source file the check reads. */
+export interface BirthKeySource {
+  readonly fileName: string;
+  readonly text: string;
+}
+
+/** What kind of out-of-birth key write was found. */
+export type BirthKeyWriteKind = "creates-another" | "edits-key" | "constant-seed";
+
+/** A compile WARNING: a directive (or helper) writes a birth key field outside the birth recipe. */
+export interface BirthKeyWriteWarning {
+  readonly rule: "birth-key-write";
+  readonly kind: BirthKeyWriteKind;
+  readonly aggregate: string;
+  readonly field: string;
+  /** The directive whose plan contains the write, or `undefined` for a shared helper function. */
+  readonly directive: string | undefined;
+  /** The enclosing helper function's name when the write is not lexically inside a directive. */
+  readonly enclosing: string | undefined;
+  readonly file: string;
+  /** 1-based. */
+  readonly line: number;
+  /** 1-based. */
+  readonly column: number;
+  readonly message: string;
+}
+
+function isBirthDecl(value: unknown): value is BusinessBirthDecl {
+  return !!value && typeof value === "object" && (value as { __isBusinessBirth?: unknown }).__isBusinessBirth === true;
+}
+
+function isAggregateHandle(value: unknown): value is AggregateHandle {
+  return !!value && typeof value === "object" && (value as { __isAggregateHandle?: unknown }).__isAggregateHandle === true;
+}
+
+interface KeyedBirth {
+  readonly aggregate: string;
+  readonly field: string;
+  readonly namespace: string | undefined;
+}
+
+/** The source-reading verbs that address an aggregate instance, and how a write through each is judged. */
+const ORIGIN_VERBS = new Set(["create", "ensure", "existing", "instance"]);
+
+interface Origin {
+  readonly verb: "create" | "ensure" | "existing" | "instance";
+  readonly aggregateName: string;
+  /** The instance-id argument (`ensure(X, id)`, `existing(X, id)`, `instance(X, id)`). */
+  readonly idArg: ts.Expression | undefined;
+}
+
+function unwrap(expr: ts.Expression): ts.Expression {
+  let current = expr;
+  while (
+    ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isNonNullExpression(current) ||
+    ts.isTypeAssertionExpression(current) || ts.isSatisfiesExpression(current)
+  ) {
+    current = current.expression;
+  }
+  return current;
+}
+
+function stringLiteralText(node: ts.Node | undefined): string | undefined {
+  if (node === undefined) return undefined;
+  return ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node) ? node.text : undefined;
+}
+
+function isFunctionLike(node: ts.Node): node is ts.SignatureDeclaration & { body?: ts.Node } {
+  return ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node) ||
+    ts.isMethodDeclaration(node) || ts.isConstructorDeclaration(node) || ts.isGetAccessorDeclaration(node) ||
+    ts.isSetAccessorDeclaration(node);
+}
+
+function bindingNames(name: ts.BindingName): string[] {
+  if (ts.isIdentifier(name)) return [name.text];
+  return name.elements.flatMap((element) => (ts.isOmittedExpression(element) ? [] : bindingNames(element.name)));
+}
+
+type Binding =
+  | { readonly where: "parameter" }
+  | { readonly where: "local"; readonly initializer: ts.Expression | undefined; readonly isConst: boolean }
+  | { readonly where: "module"; readonly initializer: ts.Expression | undefined; readonly isConst: boolean }
+  | { readonly where: "import" };
+
+function variableIn(statements: readonly ts.Statement[], name: string):
+  { initializer: ts.Expression | undefined; isConst: boolean } | undefined {
+  for (const statement of statements) {
+    if (!ts.isVariableStatement(statement)) continue;
+    const isConst = (statement.declarationList.flags & ts.NodeFlags.Const) !== 0;
+    for (const declaration of statement.declarationList.declarations) {
+      if (ts.isIdentifier(declaration.name) && declaration.name.text === name) {
+        return { initializer: declaration.initializer, isConst };
+      }
+      if (!ts.isIdentifier(declaration.name) && bindingNames(declaration.name).includes(name)) {
+        return { initializer: undefined, isConst };
+      }
+    }
+  }
+  return undefined;
+}
+
+/** Resolve an identifier to its lexical binding by walking the enclosing blocks and functions. */
+function resolveBinding(identifier: ts.Identifier): Binding | undefined {
+  const name = identifier.text;
+  let node: ts.Node | undefined = identifier.parent;
+  while (node !== undefined) {
+    if (isFunctionLike(node)) {
+      for (const parameter of node.parameters) {
+        if (bindingNames(parameter.name).includes(name)) return { where: "parameter" };
+      }
+    }
+    if (ts.isBlock(node) || ts.isModuleBlock(node) || ts.isCaseClause(node) || ts.isDefaultClause(node)) {
+      const found = variableIn(node.statements, name);
+      if (found !== undefined) return { where: "local", ...found };
+    }
+    if (ts.isForOfStatement(node) || ts.isForInStatement(node) || ts.isForStatement(node)) {
+      const init = node.initializer;
+      if (init !== undefined && ts.isVariableDeclarationList(init) &&
+        init.declarations.some((declaration) => bindingNames(declaration.name).includes(name))) {
+        return { where: "local", initializer: undefined, isConst: false };
+      }
+    }
+    if (ts.isCatchClause(node) && node.variableDeclaration !== undefined &&
+      bindingNames(node.variableDeclaration.name).includes(name)) {
+      return { where: "local", initializer: undefined, isConst: false };
+    }
+    if (ts.isSourceFile(node)) {
+      const found = variableIn(node.statements, name);
+      if (found !== undefined) return { where: "module", ...found };
+      for (const statement of node.statements) {
+        if (!ts.isImportDeclaration(statement)) continue;
+        const clause = statement.importClause;
+        if (clause === undefined) continue;
+        if (clause.name?.text === name) return { where: "import" };
+        const bindings = clause.namedBindings;
+        if (bindings === undefined) continue;
+        if (ts.isNamespaceImport(bindings) && bindings.name.text === name) return { where: "import" };
+        if (ts.isNamedImports(bindings) && bindings.elements.some((element) => element.name.text === name)) {
+          return { where: "import" };
+        }
+      }
+      return undefined;
+    }
+    node = node.parent;
+  }
+  return undefined;
+}
+
+/** A value fixed when the law module loads — a literal, an imported binding or a module-level `const`
+ *  (or a property of one) — never anything drawn from a plan's payload, reads or context. */
+function isConstantExpression(expr: ts.Expression, depth = 0): boolean {
+  if (depth > 8) return false;
+  const node = unwrap(expr);
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node) || ts.isNumericLiteral(node)) return true;
+  if (ts.isTemplateExpression(node)) {
+    return node.templateSpans.every((span) => isConstantExpression(span.expression, depth + 1));
+  }
+  if (ts.isPropertyAccessExpression(node)) return isConstantExpression(node.expression, depth + 1);
+  if (ts.isIdentifier(node)) {
+    const binding = resolveBinding(node);
+    if (binding === undefined) return false;
+    if (binding.where === "import") return true;
+    if (binding.where === "module") {
+      return binding.isConst && (binding.initializer === undefined || isConstantExpression(binding.initializer, depth + 1));
+    }
+    if (binding.where === "local" && binding.isConst && binding.initializer !== undefined) {
+      return isConstantExpression(binding.initializer, depth + 1);
+    }
+    return false;
+  }
+  return false;
+}
+
+/** Follow a receiver back to the `create/ensure/existing/instance(<Aggregate>, …)` that addressed it. */
+function resolveOrigin(expr: ts.Expression, depth = 0): Origin | undefined {
+  if (depth > 16) return undefined;
+  const node = unwrap(expr);
+  if (ts.isCallExpression(node)) {
+    const callee = unwrap(node.expression);
+    if (ts.isIdentifier(callee) && ORIGIN_VERBS.has(callee.text)) {
+      const target = node.arguments[0] !== undefined ? unwrap(node.arguments[0]) : undefined;
+      if (target !== undefined && ts.isIdentifier(target)) {
+        return {
+          verb: callee.text as Origin["verb"],
+          aggregateName: target.text,
+          idArg: node.arguments[1],
+        };
+      }
+      return undefined;
+    }
+    // `withMarker(set(instance(X, id), …), "ensures")` and the fluent chain `.set(…).set(…)`.
+    if (ts.isIdentifier(callee) && callee.text === "withMarker" && node.arguments[0] !== undefined) {
+      const inner = resolveOrigin(node.arguments[0], depth + 1);
+      const marker = stringLiteralText(node.arguments[1]);
+      return inner !== undefined && marker === "ensures" ? { ...inner, verb: "ensure" } : inner;
+    }
+    if (ts.isPropertyAccessExpression(callee)) return resolveOrigin(callee.expression, depth + 1);
+    return undefined;
+  }
+  if (ts.isIdentifier(node)) {
+    const binding = resolveBinding(node);
+    if ((binding?.where === "local" || binding?.where === "module") && binding.initializer !== undefined) {
+      return resolveOrigin(binding.initializer, depth + 1);
+    }
+  }
+  return undefined;
+}
+
+/** Is this node inside the arguments of a `birth(...)` declaration (its recipe / `initialise`)? */
+function insideBirthDeclaration(node: ts.Node): boolean {
+  let current: ts.Node | undefined = node.parent;
+  while (current !== undefined) {
+    if (ts.isCallExpression(current)) {
+      const callee = unwrap(current.expression);
+      if (ts.isIdentifier(callee) && callee.text === "birth") return true;
+    }
+    current = current.parent;
+  }
+  return false;
+}
+
+/** The `directive("<id>")` / `intent("<id>")` whose builder chain lexically encloses `node`, if any. */
+function enclosingDirective(node: ts.Node): { id?: string; enclosing?: string } {
+  let current: ts.Node | undefined = node.parent;
+  let helper: string | undefined;
+  while (current !== undefined) {
+    if (ts.isCallExpression(current) && ts.isPropertyAccessExpression(current.expression)) {
+      // Descend the builder chain to its root call.
+      let root: ts.Expression = current.expression.expression;
+      for (let hops = 0; hops < 64; hops++) {
+        const unwrapped = unwrap(root);
+        if (ts.isCallExpression(unwrapped)) {
+          const callee = unwrap(unwrapped.expression);
+          if (ts.isIdentifier(callee) && (callee.text === "directive" || callee.text === "intent")) {
+            const id = stringLiteralText(unwrapped.arguments[0]);
+            if (id !== undefined) return { id };
+            break;
+          }
+          if (ts.isPropertyAccessExpression(callee)) {
+            root = callee.expression;
+            continue;
+          }
+        }
+        break;
+      }
+    }
+    if (helper === undefined) {
+      if (ts.isFunctionDeclaration(current) && current.name !== undefined) helper = current.name.text;
+      else if ((ts.isArrowFunction(current) || ts.isFunctionExpression(current)) &&
+        ts.isVariableDeclaration(current.parent) && ts.isIdentifier(current.parent.name)) {
+        helper = current.parent.name.text;
+      } else if (ts.isMethodDeclaration(current) && ts.isIdentifier(current.name)) helper = current.name.text;
+    }
+    current = current.parent;
+  }
+  return helper !== undefined ? { enclosing: helper } : {};
+}
+
+function warningMessage(
+  kind: BirthKeyWriteKind,
+  birth: KeyedBirth,
+  where: string,
+): string {
+  const ref = `${birth.aggregate}.${birth.field}`;
+  const rule =
+    `'${birth.field}' is the birth key of ${birth.aggregate}${birth.namespace !== undefined ? ` (namespace '${birth.namespace}')` : ""}: ` +
+    `the born workspace's name was derived from it at birth and is fixed forever. Nomos enforces that at the ` +
+    `kernel — a write that CHANGES ${ref} is refused (\`${ref}:${BIRTH_KEY_WRITE_ONCE_CODE}\`); re-stating the ` +
+    `same value is admitted.`;
+  switch (kind) {
+    case "creates-another":
+      return `${where} writes ${ref} on ANOTHER ${birth.aggregate} instance. ${rule} That other record's ` +
+        `'${birth.field}' names a workspace it is not, and two records can carry one key. Give it its own id ` +
+        `field, or omit \`key\` on the birth so Nomos mints the workspace name. See ${CHOOSING_A_BIRTH_KEY_DOC}.`;
+    case "edits-key":
+      return `${where} writes ${ref} on an existing ${birth.aggregate}. ${rule} This write will be refused ` +
+        `whenever the value differs; if the business needs an editable label, keep it in a separate field. ` +
+        `See ${CHOOSING_A_BIRTH_KEY_DOC}.`;
+    case "constant-seed":
+      return `${where} seeds ${ref} with a CONSTANT. ${rule} A constant can equal the born key for at most ` +
+        `one workspace; on every workspace born with a different key this write is refused (and the record ` +
+        `would otherwise disagree with its own workspace name). Seed it from the birth's key value instead. ` +
+        `See ${CHOOSING_A_BIRTH_KEY_DOC}.`;
+  }
+}
+
+/** Gather the field-keyed births and, per born aggregate id, the export names its handle is bound to. */
+function keyedBirthsOf(modules: readonly Mod[]): { births: KeyedBirth[]; namesByAggregate: Map<string, Set<string>> } {
+  const births: KeyedBirth[] = [];
+  const seen = new Set<BusinessBirthDecl>();
+  for (const mod of modules) {
+    for (const value of Object.values(mod)) {
+      if (!isBirthDecl(value) || seen.has(value)) continue;
+      seen.add(value);
+      if (value.keyMode !== "field" || value.keyField === undefined) continue;
+      births.push({
+        aggregate: value.aggregate.id,
+        field: value.keyField,
+        namespace: (value as { namespace?: string }).namespace,
+      });
+    }
+  }
+  const born = new Set(births.map((birth) => birth.aggregate));
+  const namesByAggregate = new Map<string, Set<string>>();
+  for (const mod of modules) {
+    for (const [name, value] of Object.entries(mod)) {
+      if (!isAggregateHandle(value) || !born.has(value.id)) continue;
+      const names = namesByAggregate.get(value.id) ?? new Set<string>();
+      names.add(name);
+      namesByAggregate.set(value.id, names);
+    }
+  }
+  return { births, namesByAggregate };
+}
+
+/**
+ * Find every write of a field-keyed birth's key field outside the birth recipe that the runtime write-once
+ * rule will refuse or that addresses another instance (see the module header). `sources` are the package's
+ * own TypeScript files; aggregate handles are matched by the export names they are bound to.
+ */
+export function findBirthKeyWrites(
+  modules: readonly Mod[],
+  sources: readonly BirthKeySource[],
+  opts: { readonly root?: string } = {},
+): BirthKeyWriteWarning[] {
+  const { births, namesByAggregate } = keyedBirthsOf(modules);
+  if (births.length === 0) return [];
+  // aggregate export name → the births keyed on it (by field).
+  const byName = new Map<string, KeyedBirth[]>();
+  for (const birth of births) {
+    for (const name of namesByAggregate.get(birth.aggregate) ?? []) {
+      byName.set(name, [...(byName.get(name) ?? []), birth]);
+    }
+  }
+  const keyFields = new Set(births.map((birth) => birth.field));
+  const warnings: BirthKeyWriteWarning[] = [];
+  for (const source of sources) {
+    if (![...keyFields].some((field) => source.text.includes(field))) continue;
+    const file = ts.createSourceFile(source.fileName, source.text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const report = (call: ts.CallExpression, fieldNode: ts.Expression, receiver: ts.Expression, value: ts.Expression | undefined) => {
+      const field = stringLiteralText(fieldNode);
+      if (field === undefined || !keyFields.has(field)) return;
+      let origin = resolveOrigin(receiver);
+      if (origin === undefined) return;
+      // `withMarker(set(instance(X, id), …), "ensures")` — the functional spelling of `ensure(X, id)`.
+      const wrapper = call.parent;
+      if (origin.verb === "instance" && wrapper !== undefined && ts.isCallExpression(wrapper) &&
+        wrapper.arguments[0] === call && ts.isIdentifier(unwrap(wrapper.expression)) &&
+        (unwrap(wrapper.expression) as ts.Identifier).text === "withMarker" &&
+        stringLiteralText(wrapper.arguments[1]) === "ensures") {
+        origin = { ...origin, verb: "ensure" };
+      }
+      const birth = byName.get(origin.aggregateName)?.find((candidate) => candidate.field === field);
+      if (birth === undefined) return;
+      if (insideBirthDeclaration(call)) return;
+      let kind: BirthKeyWriteKind | undefined;
+      if (origin.verb === "create") kind = "creates-another";
+      else if (origin.verb === "ensure") {
+        const singleton = origin.idArg !== undefined && isConstantExpression(origin.idArg);
+        if (!singleton) kind = "creates-another";
+        else if (value !== undefined && isConstantExpression(value)) kind = "constant-seed";
+      } else kind = "edits-key";
+      if (kind === undefined) return;
+      const { line, character } = file.getLineAndCharacterOfPosition(fieldNode.getStart(file));
+      const context = enclosingDirective(call);
+      const shownFile = opts.root !== undefined ? path.relative(opts.root, source.fileName) : source.fileName;
+      const where = context.id !== undefined
+        ? `directive '${context.id}' (${shownFile}:${line + 1})`
+        : `${context.enclosing !== undefined ? `function '${context.enclosing}'` : "code"} (${shownFile}:${line + 1})`;
+      warnings.push({
+        rule: "birth-key-write",
+        kind,
+        aggregate: birth.aggregate,
+        field,
+        directive: context.id,
+        enclosing: context.enclosing,
+        file: shownFile,
+        line: line + 1,
+        column: character + 1,
+        message: warningMessage(kind, birth, where),
+      });
+    };
+    const visit = (node: ts.Node): void => {
+      if (ts.isCallExpression(node)) {
+        const callee = unwrap(node.expression);
+        // Fluent: `<ref>.set("<key>", value)` / `.relate("<key>", target)`.
+        if (ts.isPropertyAccessExpression(callee) && (callee.name.text === "set" || callee.name.text === "relate") &&
+          node.arguments.length >= 2) {
+          report(node, node.arguments[0]!, callee.expression, node.arguments[1]);
+        }
+        // Functional: `set(<ref>, "<key>", value)`.
+        if (ts.isIdentifier(callee) && callee.text === "set" && node.arguments.length >= 3) {
+          report(node, node.arguments[1]!, node.arguments[0]!, node.arguments[2]);
+        }
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(file);
+  }
+  return warnings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column);
+}
+
+const SOURCE_EXTENSIONS = [".ts", ".mts", ".tsx"];
+
+function resolveLocal(fromFile: string, specifier: string): string | undefined {
+  if (!specifier.startsWith(".")) return undefined;
+  const base = path.resolve(path.dirname(fromFile), specifier);
+  const candidates = [
+    base.replace(/\.js$/, ".ts").replace(/\.mjs$/, ".mts").replace(/\.jsx$/, ".tsx"),
+    base,
+    ...SOURCE_EXTENSIONS.map((extension) => base + extension),
+    ...SOURCE_EXTENSIONS.map((extension) => path.join(base, `index${extension}`)),
+  ];
+  return candidates.find((candidate) =>
+    SOURCE_EXTENSIONS.some((extension) => candidate.endsWith(extension)) && existsSync(candidate));
+}
+
+/** The package-local TypeScript sources reachable from `entries` by relative imports, inside `root`. */
+export function collectPackageSources(entries: readonly string[], root: string): BirthKeySource[] {
+  const inside = path.resolve(root) + path.sep;
+  const seen = new Set<string>();
+  const out: BirthKeySource[] = [];
+  const queue = entries.map((entry) => path.resolve(entry));
+  while (queue.length > 0) {
+    const file = queue.pop()!;
+    if (seen.has(file)) continue;
+    seen.add(file);
+    if (!file.startsWith(inside) || file.includes(`${path.sep}node_modules${path.sep}`) || file.endsWith(".d.ts")) continue;
+    if (!existsSync(file)) continue;
+    const text = readFileSync(file, "utf8");
+    out.push({ fileName: file, text });
+    for (const imported of ts.preProcessFile(text, true, true).importedFiles) {
+      const resolved = resolveLocal(file, imported.fileName);
+      if (resolved !== undefined && !seen.has(resolved)) queue.push(resolved);
+    }
+  }
+  return out.sort((a, b) => a.fileName.localeCompare(b.fileName));
+}
+
+/** Render warnings for the compiler's console. */
+export function formatBirthKeyWriteWarnings(warnings: readonly BirthKeyWriteWarning[]): string[] {
+  return warnings.map((warning) => `  ⚠ [${warning.rule}] ${warning.file}:${warning.line}:${warning.column} ${warning.message}`);
+}