@intentius/chant 0.108.1 → 0.110.0

package/src/discovery/param-deps.test.ts

@@ -1,14 +1,21 @@
 import * as ts from "typescript";
 import { describe, expect, test } from "vitest";
 import { collectConsts } from "../fold/fold";
-import { collectCompositeOrigins, collectParamDependencies, collectTagOrigins } from "./param-deps";
+import {
+  argumentLocation,
+  collectCompositeOrigins,
+  collectParamDependencies,
+  collectTagOrigins,
+  type CompositeCallSite,
+  type HostBindings,
+} from "./param-deps";
 import type { PathOrigin } from "../provenance";
 
 /**
  * Collect dependencies for the props of the file's single
  * `export const x = new Type({...})`, which is the shape every case here uses.
  */
-function depsOf(source: string, paramLocals = ["params"]): Record<string, PathOrigin> {
+function depsOf(source: string, paramLocals = ["params"], host?: HostBindings): Record<string, PathOrigin> {
   const file = ts.createSourceFile("fixture.ts", source, ts.ScriptTarget.Latest, true);
   const consts = collectConsts(file);
   let props: ts.ObjectLiteralExpression | undefined;
@@ -26,7 +33,7 @@ function depsOf(source: string, paramLocals = ["params"]): Record<string, PathOr
     }
   }
   if (!props) throw new Error("fixture has no `const x = new Type({...})`");
-  return collectParamDependencies(props, consts, new Set(paramLocals));
+  return collectParamDependencies(props, consts, new Set(paramLocals), host);
 }
 
 const param = (...names: string[]): PathOrigin => ({ kind: "build-param", params: names });
@@ -292,3 +299,156 @@ describe("collectTagOrigins", () => {
     ).toEqual({ "engine.args": fromParam("version"), engine: fixed });
   });
 });
+
+// ─────────────────────────────────────────────────────────────────────────
+// chant #3597 — where the argument behind a parameter was written.
+// ─────────────────────────────────────────────────────────────────────────
+
+/** The first call expression in `source`, as a call site in `/p/src/app.ts`. */
+function callSiteOf(source: string): CompositeCallSite {
+  const file = ts.createSourceFile("/p/src/app.ts", source, ts.ScriptTarget.Latest, true);
+  let node: ts.CallExpression | undefined;
+  const visit = (n: ts.Node): void => {
+    if (!node && ts.isCallExpression(n)) node = n;
+    ts.forEachChild(n, visit);
+  };
+  visit(file);
+  if (!node) throw new Error("fixture has no call");
+  return { file: "/p/src/app.ts", node };
+}
+
+describe("argumentLocation (#3597)", () => {
+  const source = [
+    'import { WebApp } from "./web-app";',
+    "",
+    "export const web = WebApp({",
+    '  name: "web-app",',
+    "  replicas: 3,",
+    '  iam: { path: "/service/" },',
+    "  port,",
+    "});",
+  ].join("\n");
+
+  test("a top-level argument is the property as written, on its own line", () => {
+    expect(argumentLocation(callSiteOf(source), "replicas")).toEqual({
+      parameter: "replicas",
+      file: "/p/src/app.ts",
+      line: 5,
+      column: 3,
+      text: "replicas: 3",
+    });
+  });
+
+  test("a nested parameter path descends the argument's object literals", () => {
+    expect(argumentLocation(callSiteOf(source), "iam.path")).toEqual({
+      parameter: "iam.path",
+      file: "/p/src/app.ts",
+      line: 6,
+      column: 10,
+      text: 'path: "/service/"',
+    });
+  });
+
+  test("a shorthand property is written as its name", () => {
+    expect(argumentLocation(callSiteOf(source), "port")).toMatchObject({ line: 7, column: 3, text: "port" });
+  });
+
+  test("a parameter the call leaves out falls back to the call, and claims no text", () => {
+    expect(argumentLocation(callSiteOf(source), "image")).toEqual({
+      parameter: "image",
+      file: "/p/src/app.ts",
+      line: 3,
+      column: 20,
+    });
+    expect(argumentLocation(callSiteOf(source), "iam.role")).not.toHaveProperty("text");
+  });
+
+  test("an argument that is not an object literal falls back to the call", () => {
+    const location = argumentLocation(callSiteOf("export const web = WebApp(shared);"), "replicas");
+    expect(location).toEqual({ parameter: "replicas", file: "/p/src/app.ts", line: 1, column: 20 });
+  });
+
+  test("collectCompositeOrigins records the locations in the same pass, in parameter order", () => {
+    const call = callSiteOf(source);
+    const body = ts.createSourceFile(
+      "factory.ts",
+      "const f = (props) => new Thing({ spec: { replicas: props.replicas }, label: `${props.name}-${props.iam.path}`, kind: \"web\" });",
+      ts.ScriptTarget.Latest,
+      true,
+    );
+    let props: ts.ObjectLiteralExpression | undefined;
+    const visit = (n: ts.Node): void => {
+      if (!props && ts.isNewExpression(n)) props = n.arguments?.find(ts.isObjectLiteralExpression);
+      ts.forEachChild(n, visit);
+    };
+    visit(body);
+    const origins = collectCompositeOrigins(
+      props as ts.ObjectLiteralExpression,
+      new Map(),
+      { whole: new Set(["props"]), destructured: new Map() },
+      "WebApp",
+      call,
+    );
+    expect(origins["spec.replicas"]).toEqual({
+      kind: "composite-parameter",
+      composite: "WebApp",
+      parameters: ["replicas"],
+      arguments: [{ parameter: "replicas", file: "/p/src/app.ts", line: 5, column: 3, text: "replicas: 3" }],
+    });
+    expect(origins.label).toMatchObject({
+      parameters: ["iam.path", "name"],
+      arguments: [
+        { parameter: "iam.path", line: 6, text: 'path: "/service/"' },
+        { parameter: "name", line: 4, text: 'name: "web-app"' },
+      ],
+    });
+    // A literal carries no location: nothing at the call moves it.
+    expect(origins.kind).toEqual({ kind: "composite-literal", composite: "WebApp" });
+  });
+
+  test("without a call site the origins are what they were", () => {
+    expect(compositeOriginsOf("return new Thing({ replicas: props.replicas });")).toEqual({
+      replicas: { kind: "composite-parameter", composite: "WebService", parameters: ["replicas"] },
+    });
+  });
+});
+
+describe("collectParamDependencies with host bindings (typescript-as-data#248)", () => {
+  const host: HostBindings = { values: new Set(["AWS"]), eagerCalls: new Set(["matrix"]) };
+  const hostCall: PathOrigin = { kind: "host", reason: "host-call" };
+  const hostValue: PathOrigin = { kind: "host", reason: "host-value" };
+
+  test("a method call on a receiver is a host call, at its own path", () => {
+    const source = `export const x = new Thing({ name: "x".toUpperCase(), spec: { tag: [1, 2].join("-") }, fixed: "k" });`;
+    expect(depsOf(source, [], host)).toEqual({ name: hostCall, "spec.tag": hostCall });
+  });
+
+  test("an eager lexicon helper is a host call, and a project function is not", () => {
+    const source = `export const x = new Thing({ a: matrix("os"), b: helper("os") });`;
+    expect(depsOf(source, [], host)).toEqual({ a: hostCall });
+  });
+
+  test("a lexicon export is a host value, through a const and an operator", () => {
+    const source = [`const region = AWS.Region;`, "export const x = new Thing({ a: `${region}-x`, b: AWS });"].join("\n");
+    expect(depsOf(source, [], host)).toEqual({ a: hostValue, b: hostValue });
+  });
+
+  test("a host read outranks a build parameter the same expression reads", () => {
+    const source = `export const x = new Thing({ name: params.name.toUpperCase(), size: params.size });`;
+    expect(depsOf(source, ["params"], host)).toEqual({ name: hostCall, size: param("size") });
+  });
+
+  test("a sibling resource, a member name and a property key are not host reads", () => {
+    const source = [
+      `const logs = new Bucket({ name: "x".toUpperCase() });`,
+      `const AWS2 = 1;`,
+      `export const x = new Thing({ a: logs.Arn, b: { AWS: 1 }, c: thing.AWS });`,
+    ].join("\n");
+    expect(depsOf(source, [], host)).toEqual({});
+  });
+
+  test("a tag is not read, its interpolations are", () => {
+    const source = "export const x = new Thing({ a: Sub`${AWS.Region}`, b: Sub`plain` });";
+    expect(depsOf(source, [], { values: new Set(["AWS", "Sub"]), eagerCalls: new Set() })).toEqual({ a: hostValue });
+  });
+});

package/src/discovery/param-deps.ts

@@ -1,5 +1,5 @@
 import * as ts from "typescript";
-import type { PathOrigin } from "../provenance";
+import type { ArgumentLocation, HostOriginReason, PathOrigin, SourceLocation } from "../provenance";
 
 /**
  * Which build parameters an authored props expression READS, per path (chant
@@ -117,6 +117,94 @@ function readParams(
   visit(expr);
 }
 
+/**
+ * What a file binds to host code, for {@link hostReadOf} (INTENTIUS/typescript-as-data#248).
+ */
+export interface HostBindings {
+  /** Local names bound to a value a lexicon package exports. */
+  values: ReadonlySet<string>;
+  /** Local names of eager lexicon helpers: a call to one is evaluated by host code at fold time. */
+  eagerCalls: ReadonlySet<string>;
+}
+
+/**
+ * The first host read in `expr`, following this file's own top-level consts,
+ * or `undefined` when it reads none (INTENTIUS/typescript-as-data#248).
+ *
+ * A method called on a receiver is `host-call` whatever the receiver is, since
+ * fold calls the real method on it; so is a call to an eager lexicon helper. An
+ * identifier bound to a lexicon export is `host-value`. A call fold reduces to
+ * an envelope (an authoring helper, a call-form intrinsic) or evaluates itself
+ * (a project function) is not host code, and only its arguments are read.
+ *
+ * Syntactic, like {@link readParams}, so it over-reports in one place: both
+ * arms of a conditional are read although only one is taken. That errs toward
+ * `unknown`, which never licenses an edit `direct` would not.
+ */
+export function hostReadOf(
+  expr: ts.Expression,
+  consts: ReadonlyMap<string, ts.Expression>,
+  paramLocals: ReadonlySet<string>,
+  host: HostBindings,
+): HostOriginReason | undefined {
+  const followed = new Set<string>();
+  let found: HostOriginReason | undefined;
+
+  const visit = (node: ts.Node): void => {
+    if (found) return;
+    if (ts.isCallExpression(node)) {
+      const callee = unwrap(node.expression);
+      if (ts.isPropertyAccessExpression(callee) || ts.isElementAccessExpression(callee)) {
+        found = "host-call";
+        return;
+      }
+      if (ts.isIdentifier(callee) && !consts.has(callee.text) && host.eagerCalls.has(callee.text)) {
+        found = "host-call";
+        return;
+      }
+      for (const argument of node.arguments) visit(argument);
+      return;
+    }
+
+    if (ts.isPropertyAccessExpression(node)) {
+      // The member name is not a reference.
+      visit(node.expression);
+      return;
+    }
+
+    if (ts.isIdentifier(node)) {
+      if (paramLocals.has(node.text)) return;
+      const initializer = consts.get(node.text);
+      if (initializer) {
+        // A sibling resource is a reference to it, not a read of its props.
+        if (ts.isNewExpression(unwrap(initializer)) || followed.has(node.text)) return;
+        followed.add(node.text);
+        visit(initializer);
+        return;
+      }
+      if (host.values.has(node.text)) found = "host-value";
+      return;
+    }
+
+    if (ts.isPropertyAssignment(node)) {
+      visit(node.initializer);
+      return;
+    }
+
+    // A tag is an intrinsic the lexicon registered, and only its
+    // interpolations are read.
+    if (ts.isTaggedTemplateExpression(node)) {
+      visit(node.template);
+      return;
+    }
+
+    ts.forEachChild(node, visit);
+  };
+
+  visit(expr);
+  return found;
+}
+
 /**
  * Path → build-parameter origin for one resource's props object literal.
  *
@@ -129,16 +217,27 @@ function readParams(
  * A spread is attributed to the object it spreads INTO, at that object's own
  * path (the entity root for a top-level spread), since which keys it
  * contributes is not knowable here.
+ *
+ * With `host`, a path whose expression reads host code ({@link hostReadOf})
+ * is recorded `host` instead, and that outranks a build parameter it also
+ * reads: the value is what host code returned, whatever the parameter was.
  */
 export function collectParamDependencies(
   props: ts.ObjectLiteralExpression,
   consts: ReadonlyMap<string, ts.Expression>,
   paramLocals: ReadonlySet<string>,
+  host?: HostBindings,
 ): Record<string, PathOrigin> {
   const out: Record<string, PathOrigin> = {};
-  if (paramLocals.size === 0) return out;
+  if (paramLocals.size === 0 && !host) return out;
 
   const record = (path: string, expr: ts.Expression): void => {
+    if (out[path]?.kind === "host") return;
+    const reason = host ? hostReadOf(expr, consts, paramLocals, host) : undefined;
+    if (reason) {
+      out[path] = { kind: "host", reason };
+      return;
+    }
     const found = new Set<string>();
     readParams(expr, consts, paramLocals, found);
     if (found.size === 0) return;
@@ -288,6 +387,61 @@ function readCompositeParameters(
   visit(expr);
 }
 
+/**
+ * The composite call an interpreted factory body was reached from (chant
+ * #3597): the `WebApp({ replicas: 3 })` expression in the author's source and
+ * the absolute path of the file it is written in. The node must come from a
+ * source file parsed with parent pointers, which is how `fold-import.ts`
+ * parses every file it interprets.
+ */
+export interface CompositeCallSite {
+  file: string;
+  node: ts.CallExpression;
+}
+
+/** A node's start as a 1-based {@link SourceLocation}. */
+export function sourceLocationOf(file: string, node: ts.Node): SourceLocation {
+  const sourceFile = node.getSourceFile();
+  const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+  return { file, line: line + 1, column: character + 1 };
+}
+
+/**
+ * Where `parameter` was written at `call`: the property at that path in the
+ * call's object-literal argument, descending nested object literals segment by
+ * segment, or the call itself when there is no such property.
+ *
+ * The fallback covers a parameter the call leaves out, one that arrives through
+ * a spread, and an argument that is not an object literal. In each of those the
+ * call is the nearest place that governs the value, and no `text` is given,
+ * because no property at the call says what it is.
+ */
+export function argumentLocation(call: CompositeCallSite, parameter: string): ArgumentLocation {
+  const fallback: ArgumentLocation = { parameter, ...sourceLocationOf(call.file, call.node) };
+  const first = call.node.arguments[0];
+  if (!first) return fallback;
+  let object: ts.Expression = unwrap(first);
+  let found: ts.ObjectLiteralElementLike | undefined;
+  for (const segment of parameter.split(".")) {
+    if (!ts.isObjectLiteralExpression(object)) return fallback;
+    found = undefined;
+    // Last write wins, as it does when the object literal is evaluated.
+    for (const member of object.properties) {
+      if (ts.isShorthandPropertyAssignment(member) && member.name.text === segment) found = member;
+      else if (ts.isPropertyAssignment(member) && literalName(member.name) === segment) found = member;
+    }
+    if (!found) return fallback;
+    object = ts.isPropertyAssignment(found) ? unwrap(found.initializer) : found.name;
+  }
+  if (!found) return fallback;
+  return { parameter, ...sourceLocationOf(call.file, found), text: found.getText() };
+}
+
+/** {@link argumentLocation} for each of `parameters`, in order, or nothing when no call was seen. */
+function argumentLocations(call: CompositeCallSite | undefined, parameters: readonly string[]): ArgumentLocation[] | undefined {
+  return call ? parameters.map((parameter) => argumentLocation(call, parameter)) : undefined;
+}
+
 /**
  * Path → composite origin for one `new Type({...})` inside an interpreted
  * composite factory body (chant #2161).
@@ -304,12 +458,16 @@ function readCompositeParameters(
  * something under here", while `composite-literal` would be a claim that every
  * key it brings is fixed. That claim is left unmade, and those paths come back
  * `unknown` from ../fold-provenance.ts instead.
+ *
+ * `call` (chant #3597), when the fold saw the composite call, adds where each
+ * parameter's argument was written there, in the same pass.
  */
 export function collectCompositeOrigins(
   props: ts.ObjectLiteralExpression,
   consts: ReadonlyMap<string, ts.Expression>,
   scope: CompositeParamScope,
   composite: string,
+  call?: CompositeCallSite,
 ): Record<string, PathOrigin> {
   const out: Record<string, PathOrigin> = {};
 
@@ -327,7 +485,7 @@ export function collectCompositeOrigins(
         existing && existing.kind === "composite-parameter"
           ? [...new Set([...existing.parameters, ...parameters])].sort()
           : parameters;
-      out[path] = { kind: "composite-parameter", composite, parameters: merged };
+      out[path] = compositeParameterOrigin(composite, merged, call);
       return;
     }
     if (spread) return;
@@ -384,6 +542,7 @@ export function collectTagOrigins(
   consts: ReadonlyMap<string, ts.Expression>,
   scope: CompositeParamScope,
   composite: string,
+  call?: CompositeCallSite,
 ): Record<string, PathOrigin> {
   const out: Record<string, PathOrigin> = {};
 
@@ -395,7 +554,7 @@ export function collectTagOrigins(
       const existing = out[path];
       const merged = new Set(existing?.kind === "composite-parameter" ? existing.parameters : []);
       for (const parameter of found) merged.add(parameter);
-      out[path] = { kind: "composite-parameter", composite, parameters: [...merged].sort() };
+      out[path] = compositeParameterOrigin(composite, [...merged].sort(), call);
     }
   });
 
@@ -406,3 +565,13 @@ export function collectTagOrigins(
   }
   return out;
 }
+
+/** A `composite-parameter` origin, with its argument locations when the call was seen. */
+function compositeParameterOrigin(
+  composite: string,
+  parameters: string[],
+  call: CompositeCallSite | undefined,
+): PathOrigin {
+  const locations = argumentLocations(call, parameters);
+  return { kind: "composite-parameter", composite, parameters, ...(locations ? { arguments: locations } : {}) };
+}

package/src/fold/subset-public-export.test.ts

@@ -56,3 +56,41 @@ describe("SPEC_VERSION is declared on the package entry (chant#2424)", () => {
     expect(chant.SPEC_VERSION).toBe(SPEC_VERSION);
   });
 });
+
+/**
+ * chant#3598 — the conformance adapter reads fold provenance (spec 2.2) off
+ * `foldProject`'s verdicts, and maps or recomputes it with the functions
+ * below. All of them, and the types the verdict field is written in, have to
+ * be reachable from this namespace.
+ */
+describe("fold provenance is on the package entry (chant#3598)", () => {
+  test("the functions are exported", () => {
+    for (const name of [
+      "foldProject",
+      "foldProvenanceOfEntities",
+      "foldProvenanceOfEntity",
+      "classifyFieldOrigin",
+      "emittedFieldPaths",
+      "describeFoldFieldOrigin",
+      "getProvenance",
+    ] as const) {
+      expect(typeof chant[name]).toBe("function");
+    }
+  });
+
+  test("a verdict's foldProvenance is typed in the exported shapes", () => {
+    const origins: chant.FoldFieldOrigin[] = [
+      { kind: "composite-parameter", composite: "C", instance: "i", parameters: ["p"] },
+      { kind: "composite-literal", composite: "C" },
+      { kind: "direct" },
+      { kind: "unknown", reason: "no-provenance" satisfies chant.UnknownOriginReason },
+    ];
+    const record: chant.EntityFoldProvenance = { fields: Object.fromEntries(origins.map((o, i) => [`f${i}`, o])) };
+    const verdict: chant.FoldProjectVerdict = {
+      verdict: "fold",
+      tentative: "fold",
+      foldProvenance: { e: record } satisfies chant.FoldProvenance,
+    };
+    expect(Object.keys(verdict.foldProvenance!.e.fields)).toEqual(["f0", "f1", "f2", "f3"]);
+  });
+});

package/src/fold/subset.ts

@@ -179,7 +179,7 @@ import { intrinsicCallFolds, intrinsicCallFoldsEagerly, type IntrinsicDef } from
  * `spec/VERSION` in the specification repository carries the same string, and
  * the conformance adapter reads this one to fill its `specVersion` field.
  *
- * ## Why 1.6, and what each version since 1.0 asked for (chant#2445)
+ * ## Why 2.3, and what each version since 1.0 asked for (chant#2445)
  *
  * Raising this is the last step of adopting a rule set, so each version was
  * checked against what chant does rather than against whether the suite is
@@ -220,6 +220,21 @@ import { intrinsicCallFolds, intrinsicCallFoldsEagerly, type IntrinsicDef } from
  * - **1.8** added `ι = executing`, and chant carries it as of `0.72.3`
  *   (#2455) — `FoldProjectOptions.executing`, mutually exclusive with
  *   `sandbox`. `open` stays the default and stays strict (#2453).
+ * - **2.2** added obligations to `F-Obs-Provenance` for an implementation that
+ *   claims provenance: one origin per emitted path of four kinds, the
+ *   innermost writer wins, and an origin that cannot be determined is reported
+ *   as unknown, never as direct. chant claims provenance, so this is the
+ *   version whose obligations it takes on. 2.2 also widens two rules to what
+ *   chant already did: a call-bound local exported by name (`export { x }`)
+ *   resolves by F-Call as the single declarator does, and a same-file call's
+ *   result read inside an F-Call argument resolves once per file (#3329).
+ * - **2.3** says a value host code produced, written at an export or into a
+ *   field, has an unknown origin and never a direct one. chant reports
+ *   `host-call` and `host-value` for resource fields since
+ *   typescript-as-data#248. 2.3 also lets `F-Host-Composite` interpret a
+ *   composite an active package publishes as TypeScript source, which chant
+ *   has done since #3247, and adds fixtures for a call result read inside an
+ *   argument, which chant passes since #3610.
  *
  * `scripts/check-docs-citations.ts` refuses to run when this constant and the
  * rules it loads disagree, so this and the `@intentius/tsad-conformance`
@@ -231,7 +246,7 @@ import { intrinsicCallFolds, intrinsicCallFoldsEagerly, type IntrinsicDef } from
  * Until chant#2470 the rules came from a commit `docs-check.yml` checked out;
  * now they come from the published package, so bumping it is what moves this.
  */
-export const SPEC_VERSION = "2.1";
+export const SPEC_VERSION = "2.3";
 
 /** The two EVL rule ids a shape violation can be attributed to. */
 export type SubsetRuleId = "EVL001" | "EVL003";