@intentius/chant 0.19.0 → 0.20.0

package/src/fold/subset-doc-parity.test.ts

@@ -0,0 +1,183 @@
+import { describe, test, expect } from "vitest";
+import * as ts from "typescript";
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { join } from "path";
+import { collectConsts } from "./fold";
+import { findSubsetViolation } from "./subset";
+
+/**
+ * subset-doc-parity.test.ts — chant #1062 (epic #1019).
+ *
+ * `docs/.../concepts/typescript-as-data.mdx`'s "Supported Patterns" and
+ * "Unsupported Patterns" sections are prose over `findSubsetViolation`
+ * (./subset.ts), the real, code-defined classifier. #1062 exists because
+ * that prose already drifted from the code once (see subset.ts's own
+ * module doc, and #1061's fix) and nothing stopped it.
+ *
+ * Full generation was considered and rejected: `findSubsetViolation` is a
+ * recursive-descent classifier over `ts.Node` kinds, not a flat table — its
+ * value is precisely the nuance a table would lose (flow-insensitive
+ * short-circuit handling, opaque tagged-template interiors, which EVL rule
+ * id a rejection maps to, …). Mechanically reverse-engineering that nuance
+ * from the function body would mean either emitting a bare list of
+ * `ts.SyntaxKind` names (useless to a reader) or writing a second, brittle
+ * introspector that breaks on any harmless refactor of subset.ts — a worse
+ * failure mode than the one this issue exists to fix.
+ *
+ * Instead: this test pulls each pattern's example STRAIGHT OUT of the doc's
+ * own fenced code block (by heading, via {@link extractFencedBlock}) — no
+ * second copy of the snippet lives in this file — and runs it through
+ * `findSubsetViolation` for real. A heading that's renamed or removed fails
+ * loudly (`heading not found`); a snippet whose real verdict no longer
+ * matches what the doc claims for it fails just as loudly. That is the
+ * concrete failure mode from the day this issue was filed, closed for good.
+ *
+ * Scope: only patterns `findSubsetViolation` itself decides (EVL001/EVL003 —
+ * see subset.ts's module doc for why those are the two it owns). Left out,
+ * deliberately:
+ *   - "Control flow around resources" (EVL002) and the `let`/`var`, `class`,
+ *     `require()`, top-level `await`, decorator bullets under "Other
+ *     unsupported patterns" — these are rejected at `foldModule`'s top-level
+ *     statement scan, before any expression ever reaches
+ *     `findSubsetViolation`. Not this module's concern, and not real,
+ *     parseable TypeScript in the doc's own illustrative snippet (a bare
+ *     `export` inside an `if` block isn't valid syntax to begin with).
+ *   - "Import and re-export" / "Cross-file resource references" / "Typed
+ *     property-kind constructors" are exercised below, but only prove the
+ *     trivial case: `findSubsetViolation` treats every identifier as
+ *     shape-valid regardless of whether it resolves locally, across a
+ *     module boundary, or not at all (subset.ts's module doc, point 1) — a
+ *     documented, intentional asymmetry, not something this guard can
+ *     usefully narrow further without a binding resolver of its own.
+ */
+
+const repoRoot = fileURLToPath(new URL("../../../../", import.meta.url));
+const docPath = join(repoRoot, "docs", "src", "content", "docs", "concepts", "typescript-as-data.mdx");
+const doc = readFileSync(docPath, "utf-8");
+
+/** Pull the first ```typescript fenced block following `### {heading}`. */
+function extractFencedBlock(heading: string): string {
+  const headingMarker = `### ${heading}`;
+  const headingIdx = doc.indexOf(headingMarker);
+  if (headingIdx === -1) {
+    throw new Error(
+      `subset-doc-parity: heading "${headingMarker}" not found in ${docPath} — was it renamed or removed? Update this test to match.`,
+    );
+  }
+  const fenceStart = doc.indexOf("```typescript", headingIdx);
+  if (fenceStart === -1) {
+    throw new Error(`subset-doc-parity: no \`\`\`typescript block found after "${headingMarker}"`);
+  }
+  const codeStart = doc.indexOf("\n", fenceStart) + 1;
+  const fenceEnd = doc.indexOf("```", codeStart);
+  if (fenceEnd === -1) {
+    throw new Error(`subset-doc-parity: unterminated code fence after "${headingMarker}"`);
+  }
+  return doc.slice(codeStart, fenceEnd);
+}
+
+/** Parse `source` and return its top-level `const` bindings, keyed by name. */
+function parseConsts(source: string): Map<string, ts.Expression> {
+  const sourceFile = ts.createSourceFile("doc-example.ts", source, ts.ScriptTarget.Latest, /* setParentNodes */ true);
+  return collectConsts(sourceFile);
+}
+
+/** The object-literal argument of `const <name> = new Type({...})`. */
+function resourceArg(consts: Map<string, ts.Expression>, name: string): ts.Expression {
+  const init = consts.get(name);
+  if (!init || !ts.isNewExpression(init) || !init.arguments?.[0]) {
+    throw new Error(`subset-doc-parity: "${name}" did not parse as a resource declaration with an object-literal arg`);
+  }
+  return init.arguments[0];
+}
+
+describe("subset-doc-parity — supported patterns in typescript-as-data.mdx classify as fold-clean", () => {
+  test("Resource declarations", () => {
+    const consts = parseConsts(extractFencedBlock("Resource declarations"));
+    expect(findSubsetViolation(resourceArg(consts, "store"))).toBeUndefined();
+  });
+
+  test("Literal values", () => {
+    const consts = parseConsts(extractFencedBlock("Literal values"));
+    expect(findSubsetViolation(resourceArg(consts, "service"))).toBeUndefined();
+  });
+
+  test("Const variable references", () => {
+    const consts = parseConsts(extractFencedBlock("Const variable references"));
+    expect(findSubsetViolation(resourceArg(consts, "store"))).toBeUndefined();
+  });
+
+  test("Spread from const sources", () => {
+    const consts = parseConsts(extractFencedBlock("Spread from const sources"));
+    expect(findSubsetViolation(resourceArg(consts, "service"))).toBeUndefined();
+  });
+
+  test("Import and re-export", () => {
+    // Trivial by construction — see this file's module doc.
+    const consts = parseConsts(extractFencedBlock("Import and re-export"));
+    expect(findSubsetViolation(resourceArg(consts, "store"))).toBeUndefined();
+  });
+
+  test("Cross-file resource references", () => {
+    // Trivial by construction — see this file's module doc.
+    const consts = parseConsts(extractFencedBlock("Cross-file resource references"));
+    expect(findSubsetViolation(resourceArg(consts, "service"))).toBeUndefined();
+  });
+
+  test("Intrinsic tagged templates", () => {
+    // subset.ts treats any tagged template's TAG as shape-valid regardless
+    // of lexicon registration (that check is fold()'s job, not subset.ts's —
+    // see subset.ts's module doc, point 2) — only the interpolated values
+    // are classified, and this example's interpolation is a plain property
+    // access chain.
+    const consts = parseConsts(extractFencedBlock("Intrinsic tagged templates"));
+    expect(findSubsetViolation(resourceArg(consts, "store"))).toBeUndefined();
+  });
+
+  test("Typed property-kind constructors", () => {
+    const consts = parseConsts(extractFencedBlock("Typed property-kind constructors"));
+    expect(findSubsetViolation(resourceArg(consts, "config"))).toBeUndefined();
+    expect(findSubsetViolation(resourceArg(consts, "access"))).toBeUndefined();
+  });
+
+  test("Nullish coalescing for defaults", () => {
+    // Not a standalone statement in the doc (a single object-literal
+    // property, deliberately shown as a fragment) — wrapped in an object
+    // literal to parse, which also happens to be exactly the shape
+    // `findSubsetViolation` classifies a resource prop through.
+    const fragment = extractFencedBlock("Nullish coalescing for defaults").trim();
+    const consts = parseConsts(`const _wrapped = { ${fragment} };`);
+    const wrapped = consts.get("_wrapped");
+    if (!wrapped) throw new Error("subset-doc-parity: nullish-coalescing fragment failed to parse");
+    expect(findSubsetViolation(wrapped)).toBeUndefined();
+  });
+});
+
+describe("subset-doc-parity — unsupported patterns in typescript-as-data.mdx classify as rejected", () => {
+  test("Function calls as values", () => {
+    const consts = parseConsts(extractFencedBlock("Function calls as values"));
+    expect(findSubsetViolation(resourceArg(consts, "store"))).toBeDefined();
+  });
+
+  test("Dynamic property access", () => {
+    // A bare `const`, not a resource declaration — check the initializer
+    // directly rather than through `resourceArg`.
+    const consts = parseConsts(extractFencedBlock("Dynamic property access"));
+    const init = consts.get("name");
+    if (!init) throw new Error(`subset-doc-parity: "name" did not parse as a const declaration`);
+    expect(findSubsetViolation(init)).toBeDefined();
+  });
+
+  test("Spread from dynamic sources", () => {
+    // Documented as EVL004 (a stricter, value-level narrowing rule subset.ts
+    // doesn't model — see subset.ts's module doc, item 3) but this
+    // particular example — spreading a CALL's result — is also rejected by
+    // subset.ts's shape classifier on its own terms: a call expression
+    // nested inside a spread is still a call expression. Asserting only
+    // "rejected", not a specific rule id, since attributing a rule id here
+    // is EVL004's job, not subset.ts's.
+    const consts = parseConsts(extractFencedBlock("Spread from dynamic sources"));
+    expect(findSubsetViolation(resourceArg(consts, "store"))).toBeDefined();
+  });
+});

package/src/fold/subset.test.ts

@@ -0,0 +1,241 @@
+import { describe, test, expect } from "vitest";
+import * as ts from "typescript";
+import { fold, foldResource, collectConsts, FoldError } from "./fold";
+import { evl001NonLiteralExpressionRule } from "../lint/rules/evl001-non-literal-expression";
+import { evl003DynamicPropertyAccessRule } from "../lint/rules/evl003-dynamic-property-access";
+import { evl004SpreadNonConstRule } from "../lint/rules/evl004-spread-non-const";
+import type { LintContext } from "../lint/rule";
+import type { IntrinsicDef } from "../lexicon";
+
+/**
+ * subset.test.ts — the equivalence property test for #1024: for a corpus of
+ * supported AND unsupported expression shapes, `fold()` and the EVL rules
+ * (EVL001 general, EVL003 for dynamic element-access keys) must agree —
+ * "EVL-flags <=> fold-rejects" — citing the same rule id and the same
+ * source position for every rejection.
+ *
+ * Every case here is a single-file, self-contained snippet (no imports, no
+ * unresolved cross-file symbols) so it stays inside the part of the subset
+ * that genuinely IS shared. A handful of real, environment/value-dependent
+ * exceptions are NOT unifiable through shape alone — see subset.ts's module
+ * doc for why — and are verified separately below, as documented
+ * divergences, rather than folded into the main equivalence loop.
+ */
+
+interface SubsetCase {
+  name: string;
+  /** The expression under test, plugged in as `new Thing({ x: <expr> })`. */
+  expr: string;
+  /** Extra top-level `const` declarations the expression may reference. */
+  preamble?: string;
+  intrinsics?: IntrinsicDef[];
+}
+
+const SUPPORTED_CASES: SubsetCase[] = [
+  { name: "string literal", expr: `"x"` },
+  { name: "numeric literal", expr: `42` },
+  { name: "boolean literal", expr: `true` },
+  { name: "null", expr: `null` },
+  { name: "undefined", expr: `undefined` },
+  { name: "template literal interpolating a const", preamble: `const name = "world";`, expr: "`hello-${name}`" },
+  { name: "nested object literal with shorthand", preamble: `const c = 2;`, expr: `{ a: 1, b: { c } }` },
+  { name: "object spread from a const object", preamble: `const base = { a: 1 };`, expr: `{ ...base, b: 2 }` },
+  { name: "array spread from a const array", preamble: `const arr = [2, 3];`, expr: `[1, ...arr, 4]` },
+  { name: "property access chain", preamble: `const config = { role: "arn" };`, expr: `config.role` },
+  { name: "element access with a literal key", preamble: `const config = { role: "arn" };`, expr: `config["role"]` },
+  { name: "logical-not unary", preamble: `const flag = true;`, expr: `!flag` },
+  { name: "numeric negation unary", preamble: `const n = 5;`, expr: `-n` },
+  { name: "whitelisted binary operator (+)", preamble: `const n = 5;`, expr: `n + 1` },
+  { name: "whitelisted binary operator (===)", preamble: `const n = 5;`, expr: `n === 5` },
+  { name: "conditional with both branches foldable", preamble: `const flag = true;`, expr: `flag ? "yes" : "no"` },
+  { name: "as cast", expr: `(1 + 1) as number` },
+  { name: "satisfies", expr: `"ok" satisfies string` },
+  { name: "parenthesized", expr: `(("nested"))` },
+  { name: "non-null assertion", preamble: `const n = 5;`, expr: `n!` },
+  {
+    name: "registered intrinsic tagged template with foldable interior",
+    preamble: `const name = "prefix";`,
+    expr: "Sub`${name}-data`",
+    intrinsics: [{ name: "Sub", isTag: true }],
+  },
+];
+
+const UNSUPPORTED_CASES: SubsetCase[] = [
+  { name: "function call as a value", expr: `getName()` },
+  { name: "method call as a value", expr: `config.getName()` },
+  { name: "computed/dynamic object-literal key", expr: `{ [dynKey]: 1 }` },
+  { name: "dynamic element-access key", expr: `config[dynKey]` },
+  { name: "non-whitelisted binary operator (%)", expr: `n % 2` },
+  { name: "non-whitelisted unary operator (~)", expr: `~n` },
+  { name: "unsupported object member (accessor)", expr: `{ get y() { return 1; } }` },
+  { name: "unsupported expression kind (arrow function)", expr: `() => 1` },
+  { name: "template literal with an unfoldable interpolation", expr: "`pre-${getName()}`" },
+];
+
+interface RunResult {
+  foldError: FoldError | undefined;
+  evl001Diags: ReturnType<typeof evl001NonLiteralExpressionRule.check>;
+  evl003Diags: ReturnType<typeof evl003DynamicPropertyAccessRule.check>;
+}
+
+function run(c: SubsetCase): RunResult {
+  const source = `${c.preamble ?? ""}\nconst bad = new Thing({ x: ${c.expr} });`;
+  const sourceFile = ts.createSourceFile("t.ts", source, ts.ScriptTarget.Latest, /* setParentNodes */ true);
+  const consts = collectConsts(sourceFile);
+  const badInit = consts.get("bad");
+  if (!badInit || !ts.isNewExpression(badInit)) {
+    throw new Error(`fixture error: "bad" did not parse as a NewExpression in case "${c.name}"`);
+  }
+
+  let foldError: FoldError | undefined;
+  try {
+    foldResource(badInit, consts, c.intrinsics ?? []);
+  } catch (e) {
+    if (e instanceof FoldError) {
+      foldError = e;
+    } else {
+      throw e;
+    }
+  }
+
+  const context: LintContext = { sourceFile, entities: [], filePath: "t.ts", lexicon: undefined };
+  return {
+    foldError,
+    evl001Diags: evl001NonLiteralExpressionRule.check(context),
+    evl003Diags: evl003DynamicPropertyAccessRule.check(context),
+  };
+}
+
+describe("subset equivalence — supported cases: fold succeeds AND EVL is clean", () => {
+  for (const c of SUPPORTED_CASES) {
+    test(c.name, () => {
+      const { foldError, evl001Diags, evl003Diags } = run(c);
+      expect(foldError, `fold() unexpectedly rejected: ${foldError?.message}`).toBeUndefined();
+      expect(evl001Diags, "EVL001 unexpectedly flagged a fold-supported construct").toHaveLength(0);
+      expect(evl003Diags, "EVL003 unexpectedly flagged a fold-supported construct").toHaveLength(0);
+    });
+  }
+});
+
+describe("subset equivalence — unsupported cases: fold rejects AND EVL flags the same rule id + position", () => {
+  for (const c of UNSUPPORTED_CASES) {
+    test(c.name, () => {
+      const { foldError, evl001Diags, evl003Diags } = run(c);
+      expect(foldError, "fold() unexpectedly accepted an unsupported construct").toBeInstanceOf(FoldError);
+      const err = foldError as FoldError;
+
+      const matching = err.ruleId === "EVL003" ? evl003Diags : evl001Diags;
+      expect(
+        matching.length,
+        `expected ${err.ruleId} to flag the same construct fold() rejected ("${err.message}")`,
+      ).toBeGreaterThan(0);
+      expect(matching[0].ruleId).toBe(err.ruleId);
+      expect(matching[0].line, "EVL diagnostic line must match FoldError.line").toBe(err.line);
+      expect(matching[0].column, "EVL diagnostic column must match FoldError.column").toBe(err.column);
+    });
+  }
+});
+
+/**
+ * Documented, out-of-scope divergences (see subset.ts's module doc). These
+ * are NOT bugs introduced by #1024 — they're inherent to a syntax-only
+ * lint rule vs. an evaluator, and are asserted here so a future change that
+ * accidentally "fixes" (or silently regresses) one of them gets caught.
+ */
+describe("documented divergences — NOT unified by design (see subset.ts module doc)", () => {
+  test("identifier resolution: fold rejects an unresolved bare identifier; EVL001 does not (shape-only)", () => {
+    const source = `const bad = new Thing({ x: missingVar });`;
+    const sourceFile = ts.createSourceFile("t.ts", source, ts.ScriptTarget.Latest, true);
+    const consts = collectConsts(sourceFile);
+    const badInit = consts.get("bad") as ts.NewExpression;
+
+    expect(() => foldResource(badInit, consts, [])).toThrow(FoldError);
+
+    const context: LintContext = { sourceFile, entities: [], filePath: "t.ts", lexicon: undefined };
+    expect(evl001NonLiteralExpressionRule.check(context)).toHaveLength(0);
+  });
+
+  test("intrinsic tag registration: fold rejects an unregistered tag; EVL001 does not (no lexicon manifest at lint time)", () => {
+    const source = "const bad = new Thing({ x: Unknown`plain` });";
+    const sourceFile = ts.createSourceFile("t.ts", source, ts.ScriptTarget.Latest, true);
+    const consts = collectConsts(sourceFile);
+    const badInit = consts.get("bad") as ts.NewExpression;
+
+    expect(() => foldResource(badInit, consts, [])).toThrow(FoldError);
+
+    const context: LintContext = { sourceFile, entities: [], filePath: "t.ts", lexicon: undefined };
+    expect(evl001NonLiteralExpressionRule.check(context)).toHaveLength(0);
+  });
+
+  test("spread-source runtime type: fold rejects spreading a const number; no EVL rule catches it (needs evaluation)", () => {
+    const source = `
+      const n = 5;
+      const bad = new Thing({ x: { ...n } });
+    `;
+    const sourceFile = ts.createSourceFile("t.ts", source, ts.ScriptTarget.Latest, true);
+    const consts = collectConsts(sourceFile);
+    const badInit = consts.get("bad") as ts.NewExpression;
+
+    expect(() => foldResource(badInit, consts, [])).toThrow(FoldError);
+
+    const context: LintContext = { sourceFile, entities: [], filePath: "t.ts", lexicon: undefined };
+    expect(evl001NonLiteralExpressionRule.check(context)).toHaveLength(0);
+    expect(evl004SpreadNonConstRule.check(context)).toHaveLength(0);
+  });
+
+  test("&&/||/?? short-circuit: fold folds only the taken side; EVL is flow-insensitive and flags the untaken side too", () => {
+    // fold(): the left side is falsy, so `sideEffect()` is never folded — succeeds.
+    const shortCircuitSrc = ts.createSourceFile(
+      "t.ts",
+      `const x = false && sideEffect();`,
+      ts.ScriptTarget.Latest,
+      true,
+    );
+    const shortCircuitConsts = collectConsts(shortCircuitSrc);
+    const foldedValue = fold(shortCircuitConsts.get("x") as ts.Expression, shortCircuitConsts);
+    expect(foldedValue).toBe(false);
+
+    // EVL001 has no evaluator — it requires every operand to be shape-valid,
+    // so it flags the untaken `sideEffect()` branch even though fold()
+    // never touches it.
+    const source = `const bad = new Thing({ x: false && sideEffect() });`;
+    const sourceFile = ts.createSourceFile("t.ts", source, ts.ScriptTarget.Latest, true);
+    const context: LintContext = { sourceFile, entities: [], filePath: "t.ts", lexicon: undefined };
+    expect(evl001NonLiteralExpressionRule.check(context).length).toBeGreaterThan(0);
+  });
+
+  test("tagged-template interior: fold rejects an unfoldable interpolation in a registered intrinsic tag; EVL is lenient (no registry, interiors opaque)", () => {
+    // `Sub`${getName()}`` — fold, with the intrinsic registry, folds the Sub
+    // tag's interior and rejects the getName() call. EVL has no registry and
+    // can't tell an intrinsic call (Ref, legit) from a plain one, so it treats
+    // tagged-template interiors as opaque and does not flag — otherwise it would
+    // false-flag `Sub`${Ref(env)}`` and break every intrinsic-using example.
+    const source = "const bad = new Thing({ x: Sub`${getName()}` });";
+    const sourceFile = ts.createSourceFile("t.ts", source, ts.ScriptTarget.Latest, true);
+    const consts = collectConsts(sourceFile);
+    const badInit = consts.get("bad") as ts.NewExpression;
+
+    expect(() => foldResource(badInit, consts, [{ name: "Sub", isTag: true }])).toThrow(FoldError);
+
+    const context: LintContext = { sourceFile, entities: [], filePath: "t.ts", lexicon: undefined };
+    expect(evl001NonLiteralExpressionRule.check(context)).toHaveLength(0);
+  });
+
+  test("nested resource construction: fold rejects a nested `new Type()` used as a value (falls back to run); EVL001 allows it statically", () => {
+    // A top-level `new Type()` folds (fold-import constructs a real Declarable),
+    // but a NESTED one as a property value can only fold to a {__resource,props}
+    // envelope that is never constructed, so it would serialize wrong (real
+    // fold-vs-run drift, caught by the #1025 differential on gitlab). fold()
+    // therefore rejects it, falling the file back to run; EVL allows it (a valid
+    // TS constructor call), so this is an inherent, out-of-scope divergence.
+    const source = `const bad = new Thing({ x: new Inner({ y: 1 }) });`;
+    const sourceFile = ts.createSourceFile("t.ts", source, ts.ScriptTarget.Latest, true);
+    const consts = collectConsts(sourceFile);
+    const badInit = consts.get("bad") as ts.NewExpression;
+
+    expect(() => foldResource(badInit, consts, [])).toThrow(FoldError);
+
+    const context: LintContext = { sourceFile, entities: [], filePath: "t.ts", lexicon: undefined };
+    expect(evl001NonLiteralExpressionRule.check(context)).toHaveLength(0);
+  });
+});