@intentius/chant 0.108.1 → 0.109.0

package/src/discovery/param-deps.ts

@@ -1,5 +1,5 @@
 import * as ts from "typescript";
-import type { PathOrigin } from "../provenance";
+import type { ArgumentLocation, PathOrigin, SourceLocation } from "../provenance";
 
 /**
  * Which build parameters an authored props expression READS, per path (chant
@@ -288,6 +288,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 +359,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 +386,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 +443,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 +455,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 +466,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.2, 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,14 @@ 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).
  *
  * `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 +239,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.2";
 
 /** The two EVL rule ids a shape violation can be attributed to. */
 export type SubsetRuleId = "EVL001" | "EVL003";

package/src/fold-provenance.test.ts

@@ -18,6 +18,7 @@ import {
   classifyFieldOrigin,
   emittedFieldPaths,
   foldProvenanceOfEntity,
+  describeCompositeArguments,
   describeFoldFieldOrigin,
   resolveDeepDrift,
   resolveDriftedField,
@@ -76,7 +77,7 @@ describe("classifyFieldOrigin", () => {
   });
 
   test("a recorded composite literal says which composite fixes it", () => {
-    expect(classifyFieldOrigin({ kind: "composite-literal", composite: "WebService" }, composite)).toEqual({
+    expect(classifyFieldOrigin({ kind: "composite-literal", composite: "WebService" }, composite)).toMatchObject({
       kind: "composite-literal",
       composite: "WebService",
       instance: "web",
@@ -244,6 +245,126 @@ describe("resolveDriftedField", () => {
   });
 });
 
+describe("the drift report's origin line (#3597)", () => {
+  const call = { file: "/p/src/app.ts", line: 10, column: 20 };
+  const compositeProv: EntityProvenance = {
+    sourceFile: "/p/src/app.ts",
+    composite: "WebApp",
+    compositeInstance: "web",
+    compositeCall: call,
+  };
+  const base = { entity: "webDeployment", entityType: "Deployment", root: "/p", declared: 3, live: 5 };
+
+  test("a composite parameter names the call, the argument as written, and its file and line", () => {
+    const resolved = resolveDriftedField({
+      ...base,
+      path: "spec.replicas",
+      origin: {
+        kind: "composite-parameter",
+        composite: "WebApp",
+        parameters: ["replicas"],
+        arguments: [{ parameter: "replicas", file: "/p/src/app.ts", line: 12, column: 3, text: "replicas: 3" }],
+      },
+      provenance: compositeProv,
+    });
+    expect(resolved.summary).toBe(
+      "spec.replicas on Deployment webDeployment comes from WebApp({ replicas: 3 }) at src/app.ts:12",
+    );
+    expect(resolved.resolution.description).toContain("the `web` call of composite WebApp at src/app.ts:12");
+    // The origin object carries the locations, for --json.
+    expect(resolved.origin).toEqual({
+      kind: "composite-parameter",
+      composite: "WebApp",
+      instance: "web",
+      parameters: ["replicas"],
+      call,
+      arguments: [{ parameter: "replicas", file: "/p/src/app.ts", line: 12, column: 3, text: "replicas: 3" }],
+    });
+  });
+
+  test("a nested parameter is shown nested, and a parameter the call does not write says so", () => {
+    expect(describeCompositeArguments("WebService", [
+      { parameter: "iam.path", file: "/p/a.ts", line: 4, column: 9, text: 'path: "/x/"' },
+    ])).toBe('WebService({ iam: { path: "/x/" } })');
+
+    const resolved = resolveDriftedField({
+      ...base,
+      path: "spec.template.spec.containers[#web].image",
+      origin: {
+        kind: "composite-parameter",
+        composite: "WebApp",
+        parameters: ["image"],
+        arguments: [{ parameter: "image", ...call }],
+      },
+      provenance: compositeProv,
+    });
+    expect(resolved.summary).toBe(
+      "spec.template.spec.containers[#web].image on Deployment webDeployment comes from WebApp(...) " +
+        "at src/app.ts:10 (parameter image, not written at the call)",
+    );
+  });
+
+  test("a composite literal says the composite fixes it, at the call", () => {
+    const resolved = resolveDriftedField({
+      ...base,
+      path: "spec.strategy.type",
+      origin: { kind: "composite-literal", composite: "WebApp" },
+      provenance: compositeProv,
+    });
+    expect(resolved.summary).toBe(
+      "spec.strategy.type on Deployment webDeployment is fixed inside composite WebApp; " +
+        "no argument to the call at src/app.ts:10 moves it",
+    );
+    expect(resolved.resolution.description).toContain("fixed by the `web` call of composite WebApp at src/app.ts:10");
+  });
+
+  test("a direct declaration says direct, and the resolution is today's", () => {
+    const resolved = resolveDriftedField({
+      ...base,
+      entity: "worker",
+      path: "spec.replicas",
+      provenance: { sourceFile: "/p/src/app.ts" },
+    });
+    expect(resolved.origin).toEqual({ kind: "direct" });
+    expect(resolved.summary).toBe("spec.replicas on Deployment worker is declared directly in src/app.ts");
+    expect(resolved.resolution).toEqual({
+      kind: "edit-declaration",
+      sourceFile: "/p/src/app.ts",
+      description: "change the declared value of `spec.replicas` in src/app.ts from 3 to 5.",
+    });
+  });
+
+  test("an unknown origin says unknown and why, and never reads as direct", () => {
+    for (const [provenance, why] of [
+      [{ sourceFile: "/p/src/app.ts", composite: "WebApp", compositeInstance: "web" }, "did not interpret"],
+      [undefined, "recorded no provenance"],
+    ] as const) {
+      const resolved = resolveDriftedField({ ...base, path: "spec.replicas", ...(provenance ? { provenance } : {}) });
+      expect(resolved.origin.kind).toBe("unknown");
+      expect(resolved.summary).toMatch(/^spec\.replicas on Deployment webDeployment has an unknown origin: /);
+      expect(resolved.summary).toContain(why);
+      expect(resolved.summary).not.toContain("direct");
+      expect(resolved.resolution.kind).toBe("fall-back");
+    }
+  });
+
+  test("a file outside the project root is printed as recorded", () => {
+    const resolved = resolveDriftedField({
+      ...base,
+      root: "/elsewhere",
+      path: "spec.replicas",
+      origin: {
+        kind: "composite-parameter",
+        composite: "WebApp",
+        parameters: ["replicas"],
+        arguments: [{ parameter: "replicas", file: "/p/src/app.ts", line: 12, column: 3, text: "replicas: 3" }],
+      },
+      provenance: compositeProv,
+    });
+    expect(resolved.summary).toContain("at /p/src/app.ts:12");
+  });
+});
+
 describe("resolveDeepDrift", () => {
   test("reads the drifted list and nothing else", () => {
     const verdicts = resolveDeepDrift(
@@ -399,25 +520,25 @@ describe("fold provenance over a real composite build (#2161)", () => {
     // 1. A field the composite PARAMETERIZES, including a nested parameter
     //    path, one read through a body `const`, and one read from inside an
     //    array literal.
-    expect(result.foldProvenance.webBucket.fields.BucketName).toEqual({
+    expect(result.foldProvenance.webBucket.fields.BucketName).toMatchObject({
       kind: "composite-parameter",
       composite: "WebService",
       instance: "web",
       parameters: ["name"],
     });
-    expect(result.foldProvenance.webBucket.fields.Tags).toEqual({
+    expect(result.foldProvenance.webBucket.fields.Tags).toMatchObject({
       kind: "composite-parameter",
       composite: "WebService",
       instance: "web",
       parameters: ["tier"],
     });
-    expect(result.foldProvenance.webRole.fields.RoleName).toEqual({
+    expect(result.foldProvenance.webRole.fields.RoleName).toMatchObject({
       kind: "composite-parameter",
       composite: "WebService",
       instance: "web",
       parameters: ["name"],
     });
-    expect(result.foldProvenance.webRole.fields.Path).toEqual({
+    expect(result.foldProvenance.webRole.fields.Path).toMatchObject({
       kind: "composite-parameter",
       composite: "WebService",
       instance: "web",
@@ -425,12 +546,12 @@ describe("fold provenance over a real composite build (#2161)", () => {
     });
 
     // 2. A field the composite FIXES.
-    expect(result.foldProvenance.webBucket.fields["VersioningConfiguration.Status"]).toEqual({
+    expect(result.foldProvenance.webBucket.fields["VersioningConfiguration.Status"]).toMatchObject({
       kind: "composite-literal",
       composite: "WebService",
       instance: "web",
     });
-    expect(result.foldProvenance.webRole.fields.Description).toEqual({
+    expect(result.foldProvenance.webRole.fields.Description).toMatchObject({
       kind: "composite-literal",
       composite: "WebService",
       instance: "web",
@@ -507,6 +628,43 @@ describe("fold provenance over a real composite build (#2161)", () => {
     // A direct declaration: today's behaviour, unchanged and unremarked.
     expect(verdicts[3].resolution.kind).toBe("edit-declaration");
   });
+
+  test("the build records where the composite call and each argument were written (#3597)", async () => {
+    const result = await build(srcDir, [namesSerializer], undefined, {
+      fold: true,
+      lexicons: [LEXICON_NAME],
+    });
+    expect(result.errors).toEqual([]);
+    const main = join(srcDir, "main.ts");
+    const lines = MAIN.split("\n");
+    const lineOf = (needle: string) => lines.findIndex((l) => l.includes(needle)) + 1;
+    const columnOf = (needle: string) => (lines.find((l) => l.includes(needle)) as string).indexOf(needle) + 1;
+    const call = { file: main, line: lineOf("WebService({"), column: columnOf("WebService({") };
+
+    expect(result.foldProvenance.webBucket.compositeCall).toEqual(call);
+    expect(result.foldProvenance.webRole.compositeCall).toEqual(call);
+    expect(result.foldProvenance.webBucket.fields.BucketName).toEqual({
+      kind: "composite-parameter",
+      composite: "WebService",
+      instance: "web",
+      parameters: ["name"],
+      call,
+      arguments: [{ parameter: "name", file: main, line: call.line, column: columnOf('name: "data"'), text: 'name: "data"' }],
+    });
+    expect(result.foldProvenance.webRole.fields.Path).toMatchObject({
+      arguments: [{ parameter: "iam.path", line: call.line, column: columnOf('path: "/service/"'), text: 'path: "/service/"' }],
+    });
+    expect(result.foldProvenance.webBucket.fields["VersioningConfiguration.Status"]).toEqual({
+      kind: "composite-literal",
+      composite: "WebService",
+      instance: "web",
+      call,
+    });
+
+    // A direct declaration and an uninterpreted composite record no call.
+    expect(result.foldProvenance.logs.compositeCall).toBeUndefined();
+    expect(result.foldProvenance.legacyBucket.compositeCall).toBeUndefined();
+  });
 });
 
 // ─────────────────────────────────────────────────────────────────────────
@@ -604,18 +762,23 @@ describe("fold provenance through a tagged template in a composite factory (#321
     const at = (parameters: string[]) => ({ kind: "composite-parameter", composite: "EventsTable", instance: "clicks", parameters });
     const fixed = { kind: "composite-literal", composite: "EventsTable", instance: "clicks" };
 
-    expect(events.fields.name).toEqual(at(["name"]));
-    expect(events.fields.ttl).toEqual(at(["ttlDays"]));
-    expect(events.fields.ddl).toEqual(at(["name", "ttlDays"]));
-    expect(events.fields.engine).toEqual(fixed);
-    expect(events.fields.orderBy).toEqual(fixed);
+    expect(events.fields.name).toMatchObject(at(["name"]));
+    expect(events.fields.ttl).toMatchObject(at(["ttlDays"]));
+    expect(events.fields.ddl).toMatchObject(at(["name", "ttlDays"]));
+    expect(events.fields.engine).toMatchObject(fixed);
+    expect(events.fields.orderBy).toMatchObject(fixed);
+    // #3597 — the argument behind a tag-fed field, where the call wrote it.
+    expect(events.fields.ttl).toMatchObject({ arguments: [{ parameter: "ttlDays", line: 6, text: "ttlDays: 30" }] });
+    expect(events.fields.ddl).toMatchObject({
+      arguments: [{ parameter: "name", text: 'name: "clicks"' }, { parameter: "ttlDays", text: "ttlDays: 30" }],
+    });
 
     // Through a body `const`; an interpolated literal string is fixed; an
     // interpolated sibling entity is wiring, so it governs nothing.
-    expect(rollup.fields.name).toEqual(at(["name"]));
-    expect(rollup.fields.engine).toEqual(fixed);
-    expect(rollup.fields.comment).toEqual(fixed);
-    expect(rollup.fields.ddl).toEqual(at(["name"]));
+    expect(rollup.fields.name).toMatchObject(at(["name"]));
+    expect(rollup.fields.engine).toMatchObject(fixed);
+    expect(rollup.fields.comment).toMatchObject(fixed);
+    expect(rollup.fields.ddl).toMatchObject(at(["name"]));
 
     expect(result.foldProvenance.audit.fields.ttl).toBeUndefined();
     expect(result.foldProvenance.audit.fields.name).toEqual({ kind: "direct" });