@intentius/chant 0.19.1 → 0.21.0

package/src/fold/foldable-helpers.ts

@@ -0,0 +1,171 @@
+/**
+ * foldable-helpers — the closed, declared allowlist of chant's OWN authoring
+ * helpers that a call expression may fold through (chant #1082, epic #1019).
+ *
+ * ## Why this exists
+ *
+ * `fold()` has no general case for a `CallExpression`: a function call as a
+ * value is structurally unrepresentable there, because folding it would mean
+ * executing code, which is the one thing the fold path exists to avoid. That
+ * rule is right for user code and stays right — a user's own function, an
+ * arrow function, a method call (`naming.name(...)`) all keep failing exactly
+ * as before.
+ *
+ * But it also blocks chant's own documented authoring API. `phase("Apply",
+ * [...])` is how the component contract says to write a component; `output(ref,
+ * "oX")` is how a lexicon output is authored. An application cannot avoid them
+ * and still use components or outputs, so every file that uses one falls back
+ * to run no matter how statically evaluable the rest of it is.
+ *
+ * #1044 already settled the shape of the answer one level down, for lexicon
+ * intrinsics: a call-shaped thing may fold ONLY when it is registered, opt-in,
+ * per-helper — never because it merely looks like a call. This module is the
+ * same decision applied one level up, to chant's own helpers, with the
+ * registration written here by hand instead of coming from a lexicon manifest.
+ *
+ * ## What "registered" buys, and what still has to be true
+ *
+ * A name in this list is NOT permission to invoke whatever it happens to be
+ * bound to. Folding a helper call is a two-key operation:
+ *
+ *   1. **Shape + name** (here, and in `fold()`/`findSubsetViolation`): the
+ *      callee is a bare identifier whose text is in {@link
+ *      FOLDABLE_AUTHORING_HELPERS} and which is not shadowed by a local
+ *      `const`. `fold()` reduces the call to a symbolic
+ *      `{ __helper, args }` envelope — it still executes nothing.
+ *   2. **Provenance + invocation** (`../discovery/fold-import.ts`): the
+ *      envelope is revived by resolving that name through the folding FILE'S
+ *      OWN `import` bindings and checking the import actually comes from chant
+ *      ({@link isChantOwnedSpecifier}, or a path inside chant-core's own tree
+ *      for in-repo/absolute-specifier callers). Only then is the real function
+ *      invoked, with the real folded arguments. A same-named helper imported
+ *      from somewhere else, or declared in the file itself, resolves to
+ *      nothing chant owns and the whole file falls back to run.
+ *
+ * So the function that runs is always the same function the run path would
+ * have called, from the same module the source itself imported — fold does not
+ * substitute its own reimplementation, which is why this list cannot drift
+ * from the helpers' real behavior.
+ *
+ * ## Admission criteria
+ *
+ * A helper belongs here only if all of these hold:
+ *
+ *   - chant owns and documents it as authoring surface;
+ *   - it is a pure function of its arguments — no I/O, no `process.env`, no
+ *     module-level mutable state, no observable side effect;
+ *   - calling it early (at fold time) is indistinguishable from calling it
+ *     during a real run of the file.
+ *
+ * Deliberately NOT admitted — see this module's tests and the #1082 PR body:
+ *
+ *   - `env()` (`../env.ts`) reads `process.env`. Folding it would bake one
+ *     run's environment into a statically-derived value. It is exactly the
+ *     kind of call fold must keep rejecting.
+ *   - `Op()` (`../op/builders.ts`) constructs an `OpResource` — a `Declarable`.
+ *     `fold()` already rejects a nested `new Type(...)` used as a value for a
+ *     real, differential-caught reason (the envelope leaks into
+ *     serialization); a factory that returns one is the same hazard wearing a
+ *     call.
+ *   - `propagate()`, `withDefaults()`, `resource()`, `mergeDefaults()`
+ *     (`../composite.ts`) are composite *definition* helpers, not value-position
+ *     helpers. `propagate()` in particular mutates its argument in place, and
+ *     the composite spine in fold-import.ts already resolves it live.
+ *   - `createResource()`/`createProperty()` (`../runtime.ts`) are used at a
+ *     lexicon module's top level to build classes, never as a value inside a
+ *     project file.
+ *   - Lexicon intrinsics in CALL form (`Ref(...)`, `Join(...)`) are lexicon
+ *     surface, not chant's own, and are #1044's registry (`IntrinsicDef`,
+ *     `../lexicon.ts`) to admit — not this one. Only their tagged-template
+ *     form folds today.
+ */
+
+/**
+ * One registered helper. `module` and `note` carry no runtime behavior — they
+ * are the audit trail for why this entry passed the admission criteria above,
+ * kept next to the name it justifies rather than in a comment that can drift
+ * away from the list.
+ */
+export interface FoldableHelperDef {
+  /** The exported name, matched against the callee identifier's text. */
+  readonly name: string;
+  /** Where chant defines it (a path under `packages/core/src`, for the audit trail). */
+  readonly module: string;
+  /** Why it qualifies — what it returns and why calling it at fold time is safe. */
+  readonly note: string;
+}
+
+/**
+ * The allowlist. Adding an entry is a deliberate act: it must satisfy every
+ * admission criterion in this module's doc, and it widens what `fold()` and
+ * `findSubsetViolation` accept for EVERY project, so it belongs in a PR that
+ * says so.
+ *
+ * Two names below are defined TWICE in chant, by different modules, with
+ * different return types (`phase`/`gate` by both the component contract and
+ * the Op builders; `stackOutput` by both the component contract and the
+ * cross-stack output primitive). That is fine and needs no disambiguation
+ * here: registration is by name, but the function actually invoked is the one
+ * the folding file itself imported (see step 2 in the module doc), so each
+ * file gets its own. Both definitions of each name independently satisfy the
+ * criteria, which is what makes registering the shared name safe.
+ */
+export const FOLDABLE_AUTHORING_HELPERS: readonly FoldableHelperDef[] = [
+  {
+    name: "phase",
+    module: "components/component.ts, op/builders.ts",
+    note: "Returns a plain `{ phase, steps, parallel? }` / `{ name, steps, parallel? }` object literal built from its arguments. No state, no I/O.",
+  },
+  {
+    name: "gate",
+    module: "components/component.ts, op/builders.ts",
+    note: "Returns a plain `{ kind: 'gate', signalName, ... }` object literal built from its arguments.",
+  },
+  {
+    name: "activity",
+    module: "op/builders.ts",
+    note: "Returns a plain `{ kind: 'activity', fn, args?, profile? }` object literal built from its arguments.",
+  },
+  {
+    name: "stackOutput",
+    module: "components/component.ts, stack-output.ts",
+    note: "Component form returns a plain `{ stackOutput: { stack, name } }` literal. Cross-stack form derives a `StackOutput` from a real `AttrRef`/`Intrinsic` and throws on anything else — so a fold that only has a symbolic reference fails loudly into run-fallback rather than producing a wrong output.",
+  },
+  {
+    name: "output",
+    module: "lexicon-output.ts",
+    note: "Constructs a `LexiconOutput` from a real `AttrRef`/`Intrinsic` and a name. Pure, but identity-sensitive: it reads through the ref's `WeakRef` to its parent entity. Only folds when the ref argument revives to a REAL live reference (see fold-import.ts's `requireLiveRefs`); a symbolic `{ __attrRef }` envelope is rejected, not silently wrapped.",
+  },
+];
+
+const HELPER_NAMES: ReadonlySet<string> = new Set(FOLDABLE_AUTHORING_HELPERS.map((h) => h.name));
+
+/**
+ * True when `name` is a registered foldable authoring helper. Name-only — this
+ * is the shape-level half of the check (step 1 in the module doc). It says
+ * nothing about where the name is bound; `../discovery/fold-import.ts` decides
+ * that before anything is invoked.
+ */
+export function isFoldableHelperName(name: string): boolean {
+  return HELPER_NAMES.has(name);
+}
+
+/**
+ * Package specifiers chant itself publishes. A registered helper name only
+ * folds when the folding file imported it from one of these — or, for in-repo
+ * and test callers that import chant-core by relative/absolute path, from
+ * inside chant-core's own tree (checked separately, in fold-import.ts, since
+ * only that module knows how to resolve a specifier to a path).
+ *
+ * Lexicon packages are included because several core helpers are re-exported
+ * through them and that is the documented import in real projects — e.g.
+ * `import { output } from "@intentius/chant-lexicon-aws"`.
+ */
+const CHANT_PACKAGE_SPECIFIERS: readonly string[] = ["@intentius/chant", "@intentius/chant-lexicon-"];
+
+/** True for a bare specifier that names a chant-published package (or one of its subpaths). */
+export function isChantOwnedSpecifier(specifier: string): boolean {
+  return CHANT_PACKAGE_SPECIFIERS.some(
+    (prefix) => specifier === prefix || specifier.startsWith(prefix.endsWith("-") ? prefix : `${prefix}/`),
+  );
+}

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

@@ -0,0 +1,210 @@
+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("Registered intrinsic calls", () => {
+    // chant #1044 — the one doc snippet that needs the registry to classify:
+    // `Ref(...)` is only in the subset because a lexicon opted its call form
+    // in, and `findSubsetViolation` answers exactly that question when it is
+    // given the registry (subset.ts module doc, point 2c). Without one it
+    // would report a violation, which is the pre-#1044 answer EVL still gets.
+    const consts = parseConsts(extractFencedBlock("Registered intrinsic calls"));
+    const intrinsics = [
+      { name: "Sub", isTag: true },
+      { name: "Ref", isTag: false, foldsAsCall: true },
+    ];
+    expect(findSubsetViolation(resourceArg(consts, "store"), intrinsics)).toBeUndefined();
+    expect(findSubsetViolation(resourceArg(consts, "store"))).toBeDefined();
+  });
+
+  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("Registered authoring helpers", () => {
+    // chant #1082 — not a `new Type({...})` declaration, so classify the
+    // exported component object literal directly. `findSubsetViolation`
+    // checks the helper NAME only (subset.ts module doc, point 2b); the
+    // doc's own snippet imports them from chant, which is what the bridge
+    // additionally verifies at fold time.
+    const consts = parseConsts(extractFencedBlock("Registered authoring helpers"));
+    const web = consts.get("web");
+    if (!web) throw new Error(`subset-doc-parity: "web" did not parse as a const declaration`);
+    expect(findSubsetViolation(web)).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();
+  });
+});