@intentius/chant 0.71.1 → 0.72.1

package/src/fold/subset.test.ts

@@ -1,7 +1,7 @@
 import { describe, test, expect } from "vitest";
 import * as ts from "typescript";
 import { fold, foldResource, collectConsts, FoldError } from "./fold";
-import { briefNodeText, callExpressionMessage, findSubsetViolation } from "./subset";
+import { briefNodeText, callExpressionMessage, findSubsetViolation, collectLocalCallables } from "./subset";
 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";
@@ -137,6 +137,38 @@ describe("subset equivalence — supported cases: fold succeeds AND EVL is clean
   }
 });
 
+/**
+ * chant#2436 closed a divergence that used to live in the block below.
+ *
+ * `phase` is a registered authoring helper, but shadowed by the file's own
+ * arrow the local binding wins — which is what #1082 asserted, and still
+ * true. It used to win by making `fold()` reject, because `fold()` had no way
+ * to call a local function; a build folded the same file. Now both fold it, so
+ * the two agree rather than diverging by design.
+ */
+describe("authoring-helper shadowing — now unified (chant#2436)", () => {
+  const source = `
+      const phase = (n) => ({ phase: n });
+      const good = new Thing({ x: phase("Apply") });
+    `;
+
+  test("fold calls the local arrow, and does not apply the registered meaning", () => {
+    const sourceFile = ts.createSourceFile("t.ts", source, ts.ScriptTarget.Latest, true);
+    const consts = collectConsts(sourceFile);
+    const folded = foldResource(consts.get("good") as ts.NewExpression, consts, []);
+
+    // chant's own `phase(name, steps)` yields `{ phase, steps }`; no `steps`
+    // here is what proves the shadowing binding was the one called.
+    expect((folded.props as { x: unknown }).x).toEqual({ phase: "Apply" });
+  });
+
+  test("and EVL001 is clean, as it always was", () => {
+    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)).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, () => {
@@ -241,25 +273,6 @@ describe("documented divergences — NOT unified by design (see subset.ts module
     expect(evl001NonLiteralExpressionRule.check(context)).toHaveLength(0);
   });
 
-  test("authoring-helper shadowing: fold rejects a registered name bound to a local const; EVL001 does not (shape-only, no binding resolution)", () => {
-    // chant #1082 — `phase` is registered, but here it's the file's own local
-    // arrow function, so the local binding wins and fold() rejects. EVL has no
-    // binding resolver (subset.ts module doc, point 1) and stays permissive —
-    // the same direction as every other divergence here.
-    const source = `
-      const phase = (n) => ({ phase: n });
-      const bad = new Thing({ x: phase("Apply") });
-    `;
-    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("method call on an unresolved receiver: fold rejects; EVL001 accepts the shape (chant #1966, resolution-dependent)", () => {
     // `config.getName()` — chant #1966 widened `findSubsetViolation` to
     // accept a method call unconditionally (mirroring `.step` and a nested
@@ -550,3 +563,131 @@ describe("callExpressionMessage — one line regardless of the call's own argume
     expect(message).toBe("function call as a value is not foldable: GkeCluster(...)");
   });
 });
+
+/**
+ * chant#2435 — `S-CallLocal`.
+ *
+ * The classifier rejected every call to a project-local function while the
+ * build folds all of them, which is the one direction `F-Direction` forbids:
+ * this module may accept what the fold rejects, never the reverse. In practice
+ * it meant `chant lint` reported EVL001 on a file `chant build --fold` folds
+ * cleanly.
+ *
+ * The admission is by NAME and the names come from the node's own source file,
+ * so nothing a caller does changes the answer.
+ */
+describe("findSubsetViolation — project-local calls (chant#2435)", () => {
+  /** The initializer of `export const x = …` in `src`, with its file attached. */
+  const initializerOf = (src: string): ts.Expression => {
+    const sourceFile = ts.createSourceFile("m.ts", src, ts.ScriptTarget.Latest, true);
+    for (const statement of sourceFile.statements) {
+      if (!ts.isVariableStatement(statement)) continue;
+      for (const decl of statement.declarationList.declarations) {
+        if (ts.isIdentifier(decl.name) && decl.name.text === "x" && decl.initializer) return decl.initializer;
+      }
+    }
+    throw new Error("fixture has no `x`");
+  };
+  const accepts = (src: string) => findSubsetViolation(initializerOf(src)) === undefined;
+
+  describe("admitted, because a build folds them", () => {
+    test("a same-file function declaration, exported or not", () => {
+      expect(accepts("function twice(n: number) { return n * 2; }\nexport const x = twice(21);")).toBe(true);
+      expect(accepts("export function twice(n: number) { return n * 2; }\nexport const x = twice(21);")).toBe(true);
+    });
+
+    test("a same-file arrow const, through parentheses and `as`", () => {
+      expect(accepts('const label = (s: string) => ({ label: s });\nexport const x = label("k");')).toBe(true);
+      expect(accepts('const label = ((s: string) => s) as (s: string) => string;\nexport const x = label("k");')).toBe(true);
+    });
+
+    test("a name imported from a project specifier", () => {
+      expect(accepts('import { twice } from "./pure";\nexport const x = twice(21);')).toBe(true);
+      expect(accepts('import { twice } from "../lib/pure";\nexport const x = twice(21);')).toBe(true);
+    });
+
+    test("a default import from a project specifier", () => {
+      expect(accepts('import make from "./make";\nexport const x = make(1);')).toBe(true);
+    });
+  });
+
+  describe("still rejected, so the diagnostic keeps its value", () => {
+    test("a call to a name imported from a package", () => {
+      expect(accepts('import { v4 } from "uuid";\nexport const x = v4();')).toBe(false);
+    });
+
+    test("a call to a name the file never binds", () => {
+      expect(accepts("export const x = getId();")).toBe(false);
+    });
+
+    test("a local name that shadows nothing local — the specifier decides, not the name", () => {
+      expect(accepts('import { twice } from "some-package";\nexport const x = twice(1);')).toBe(false);
+    });
+
+    test("a type-only import, which is erased before anything can call it", () => {
+      expect(accepts('import type { T } from "./t";\nexport const x = T();')).toBe(false);
+      expect(accepts('import { type T } from "./t";\nexport const x = T();')).toBe(false);
+    });
+
+    test("a `let`-bound arrow, which `S-LocalFunction` does not admit", () => {
+      expect(accepts("let f = (n: number) => n;\nexport const x = f(1);")).toBe(false);
+    });
+
+    test("a function nested inside another, so not a top-level binding", () => {
+      expect(accepts("function outer() { function inner() { return 1; } return inner; }\nexport const x = inner();")).toBe(false);
+    });
+
+    test("an argument outside the subset, even when the callee is local", () => {
+      const violation = findSubsetViolation(
+        initializerOf("function twice(n: number) { return n; }\nexport const x = twice(getId());"),
+      );
+      expect(violation?.ruleId).toBe("EVL001");
+      // The rejection points at the argument, not at the admitted call.
+      expect(violation?.node.getText()).toBe("getId()");
+    });
+  });
+
+  describe("collectLocalCallables", () => {
+    test("collects each binding kind, and nothing else", () => {
+      const sourceFile = ts.createSourceFile(
+        "m.ts",
+        [
+          'import { fromProject } from "./p";',
+          'import fromProjectDefault from "./d";',
+          'import { fromPackage } from "pkg";',
+          'import type { TypeOnly } from "./t";',
+          "export function declared() { return 1; }",
+          "const arrowConst = () => 1;",
+          "let notConst = () => 1;",
+          "const notAFunction = 1;",
+        ].join("\n"),
+        ts.ScriptTarget.Latest,
+        true,
+      );
+
+      expect([...collectLocalCallables(sourceFile)].sort()).toEqual([
+        "arrowConst",
+        "declared",
+        "fromProject",
+        "fromProjectDefault",
+      ]);
+    });
+
+    test("is memoized per source file, so a large file is walked once", () => {
+      const sourceFile = ts.createSourceFile("m.ts", "function f() { return 1; }", ts.ScriptTarget.Latest, true);
+      expect(collectLocalCallables(sourceFile)).toBe(collectLocalCallables(sourceFile));
+    });
+  });
+
+  test("the local-callable lookup is not a new failure mode for a node with no file", () => {
+    // A synthetic node has no parent chain, so `getSourceFile()` throws. That
+    // is pre-existing: `violation()` renders the offending node with
+    // `getText()`, which throws for the same reason, so this shape was never
+    // supported. What is asserted here is narrower and is what chant#2435
+    // could have broken: the lookup added in front of that rejection swallows
+    // the throw instead of turning it into a different error.
+    const synthetic = ts.factory.createCallExpression(ts.factory.createIdentifier("twice"), undefined, []);
+    expect(() => collectLocalCallables(synthetic.getSourceFile())).toThrow();
+    expect(() => findSubsetViolation(synthetic)).toThrow(/Cannot read|undefined|getSourceFile|getText/i);
+  });
+});

package/src/fold/subset.ts

@@ -48,7 +48,16 @@ import { intrinsicCallFolds, intrinsicCallFoldsEagerly, type IntrinsicDef } from
  * expression, its operator, and (for keys) its literal-ness. It
  * deliberately does NOT resolve bindings or perform any evaluation, because
  * three things a full fold needs are inherently environment-dependent and
- * cannot be recovered from shape alone:
+ * cannot be recovered from shape alone.
+ *
+ * One thing it does read beyond the expression itself, since chant#2435: the
+ * enclosing file's top-level bindings, for `S-CallLocal`. A call to a
+ * project-local function is admitted by NAME (see
+ * {@link collectLocalCallables}), which is decidable from that file's syntax
+ * and needs no resolution. Before that, this module rejected all four shapes
+ * the build folds, which is the one direction `F-Direction` forbids, and it
+ * made `chant lint` report EVL001 on a file `chant build --fold` folds
+ * cleanly. The three genuinely environment-dependent cases are:
  *
  *   1. Identifier *resolution* — is a bare name actually a local `const`,
  *      vs. an unbound name? That needs the file's `consts` map. Both
@@ -237,6 +246,111 @@ export function briefNodeText(node: ts.Node, maxLength = 60): string {
   return collapsed.length > maxLength ? `${collapsed.slice(0, maxLength - 3)}...` : collapsed;
 }
 
+// ---------------------------------------------------------------------------
+// Project-local callables (chant#2435, spec `S-CallLocal`)
+// ---------------------------------------------------------------------------
+
+/**
+ * Every name a file binds to something a project-local call can reach.
+ *
+ * Two bindings, both of which the specification's `S-LocalFunction` names and
+ * both decidable from this file's own syntax, which is all a shape classifier
+ * has:
+ *
+ *   - a top-level `function f(...) {...}`, or a `const f = (...) => ...`
+ *     (a function expression counts, and parentheses / `as` / `satisfies`
+ *     wrappers are unwrapped), exported or not;
+ *   - a name imported from a *project* specifier, one starting `./` or `../`.
+ *     A bare specifier is a package, and a package's function is not
+ *     project-local.
+ *
+ * Deliberately syntax-only, and deliberately not a judgment about the callee's
+ * body. Whether the body is admissible is `S-FnBody`'s question and the fold's
+ * to answer, exactly as it already is for a call this classifier admits by
+ * name (a registered authoring helper, an opted-in intrinsic).
+ *
+ * Mirrors `collectLocalFunctions` in ../discovery/fold-import.ts, which builds
+ * the real `FoldableFunction` for each of these during a build. This one only
+ * needs the names.
+ */
+export function collectLocalCallables(sourceFile: ts.SourceFile): ReadonlySet<string> {
+  const cached = localCallableCache.get(sourceFile);
+  if (cached) return cached;
+
+  const names = new Set<string>();
+  const unwrap = (node: ts.Expression): ts.Expression => {
+    let current = node;
+    while (
+      ts.isParenthesizedExpression(current) ||
+      ts.isAsExpression(current) ||
+      ts.isSatisfiesExpression(current)
+    ) {
+      current = current.expression;
+    }
+    return current;
+  };
+
+  for (const statement of sourceFile.statements) {
+    if (ts.isFunctionDeclaration(statement)) {
+      if (statement.name && statement.body) names.add(statement.name.text);
+      continue;
+    }
+    if (ts.isImportDeclaration(statement)) {
+      const specifier = statement.moduleSpecifier;
+      if (!ts.isStringLiteral(specifier) || !/^\.\.?\//.test(specifier.text)) continue;
+      const clause = statement.importClause;
+      // `import type { T } from "./t"` is erased before anything runs, so `T`
+      // is not something a call can reach. Both spellings are skipped: the
+      // whole-clause one and the per-specifier `import { type T }`.
+      if (!clause || clause.isTypeOnly) continue;
+      if (clause.name) names.add(clause.name.text);
+      const bindings = clause.namedBindings;
+      if (bindings && ts.isNamedImports(bindings)) {
+        for (const element of bindings.elements) {
+          if (!element.isTypeOnly) names.add(element.name.text);
+        }
+      }
+      continue;
+    }
+    if (!ts.isVariableStatement(statement)) continue;
+    if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0) continue;
+    for (const decl of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(decl.name) || !decl.initializer) continue;
+      const initializer = unwrap(decl.initializer);
+      if (ts.isArrowFunction(initializer) || ts.isFunctionExpression(initializer)) {
+        names.add(decl.name.text);
+      }
+    }
+  }
+
+  localCallableCache.set(sourceFile, names);
+  return names;
+}
+
+/** Per-file memo: the classifier asks this once per call expression, and a big file has many. */
+const localCallableCache = new WeakMap<ts.SourceFile, ReadonlySet<string>>();
+
+/**
+ * The project-local callables in scope at `node`, or an empty set when the node
+ * has no file to read.
+ *
+ * The guard is not a claim that a file-less node is supported: the rejection
+ * this sits in front of renders the node with `getText()`, which needs the same
+ * parent chain. It is here so that looking the names up never becomes a *new*
+ * way for this function to fail, and so the answer for a node whose file cannot
+ * be read is the pre-#2435 one, that every call is a violation.
+ */
+function localCallablesAt(node: ts.Node): ReadonlySet<string> {
+  try {
+    const sourceFile = node.getSourceFile();
+    return sourceFile ? collectLocalCallables(sourceFile) : EMPTY_NAMES;
+  } catch {
+    return EMPTY_NAMES;
+  }
+}
+
+const EMPTY_NAMES: ReadonlySet<string> = new Set<string>();
+
 // ---------------------------------------------------------------------------
 // Shared message builders — `fold()` and `findSubsetViolation` both call
 // these so the diagnostic text for the same violation kind is the same
@@ -547,6 +661,27 @@ export function findSubsetViolation(
       return undefined;
     }
 
+    // chant#2435 — a call to a project-local function. `fold-import.ts` binds
+    // every top-level function a file declares (and every one it imports from
+    // a project file) before folding it, so a build folds all four shapes the
+    // issue tabulates; this classifier rejected all four. That is the one
+    // direction `F-Direction` forbids, and it made `chant lint` report EVL001
+    // on a file `chant build --fold` folds cleanly.
+    //
+    // Name-only, like the authoring-helper case above and for the same reason:
+    // this module classifies shape and never resolves bindings. Whether the
+    // callee's body is admissible is `S-FnBody`'s question, which the fold
+    // answers. The set comes from the node's own source file, so every caller
+    // gets the corrected answer without passing anything — a caller holding a
+    // synthetic node with no file keeps the old, stricter one.
+    if (ts.isIdentifier(node.expression) && localCallablesAt(node).has(node.expression.text)) {
+      for (const arg of node.arguments) {
+        const v = findSubsetViolation(arg, intrinsics);
+        if (v) return v;
+      }
+      return undefined;
+    }
+
     return violation(node, callExpressionMessage(node));
   }
 

package/src/index.ts

@@ -43,7 +43,7 @@ export * from "./fold/fold";
 // fold?" of without running a fold (subset.ts module doc, point 2c), and the
 // half of the fold subset a conformance adapter needs that `fold()` alone
 // does not expose. INTENTIUS/typescript-as-data#11.
-export { findSubsetViolation, checkObjectMember, type SubsetViolation, type SubsetRuleId } from "./fold/subset";
+export { findSubsetViolation, checkObjectMember, collectLocalCallables, type SubsetViolation, type SubsetRuleId } from "./fold/subset";
 // The version of the TypeScript-as-Data specification chant implements
 // (INTENTIUS/typescript-as-data#18, chant#2424). The specification's
 // conformance adapter reads this off the public entry; without it a suite