@intentius/chant 0.49.0 → 0.50.0

package/src/provenance.ts

@@ -5,9 +5,11 @@
  * entity object, so it never serializes into the emitted YAML/JSON — it is build
  * metadata, not declared configuration. Read it back with {@link getProvenance}.
  *
- * This is entity-level provenance (which file declared it, and which composite
- * expanded it), not a YAML-line source map. It answers "where did this resource
- * come from?", which is the question an agent asks before changing it.
+ * Entity-level provenance (which file declared it, and which composite expanded
+ * it) answers "where did this resource come from?", which is the question an
+ * agent asks before changing it. {@link PathOrigin} (chant #1443) answers the
+ * follow-up — "what set THIS field" — for the paths a build can attribute
+ * without guessing. Neither is a YAML-line source map.
  *
  * {@link BuildParamProvenance} (chant #1064) is the other half: not "where did
  * this ENTITY come from" but "what INPUTS was this whole BUILD invoked with" —
@@ -30,6 +32,58 @@ export interface EntityProvenance {
    * collapse a composite to a single node at coarse diagram detail levels (#494).
    */
   compositeInstance?: string;
+  /**
+   * Per-path origins within the entity's `props` (chant #1443). Read with
+   * {@link originOfPath}, which does the prefix resolution these keys are
+   * written for.
+   *
+   * Keys are dotted property paths only — `spec.template.spec.containers` —
+   * with `""` for the whole entity. They never carry an array segment, because
+   * a producing mechanism attributes a whole array at once: the coarsest path
+   * it actually determines is the honest one to record, and a positional key
+   * would go stale the moment an element moved.
+   *
+   * Query paths come from #1441's diff addressing and may carry `[#key]` for an
+   * element of an associative list or `[n]` for a positional one. Resolution is
+   * longest segment-boundary prefix, so `spec.containers[#app].image` finds a
+   * key recorded at `spec.containers`, and a key recorded at
+   * `spec.containers.image` never matches it. The two grammars agree without
+   * the recorder needing the lexicon's ordering hook, which it has no access to.
+   *
+   * Absent means this build could not record path origins, not that nothing
+   * governs the entity's fields — the run path executes modules and has no
+   * expression to inspect, and a sandboxed child's provenance does not survive
+   * the wire (`discovery/entity-wire-codec.ts` drops build metadata).
+   */
+  paths?: Record<string, PathOrigin>;
+}
+
+/**
+ * What produced one path inside an entity's props.
+ *
+ * - `authored` — written in the source file that declared the entity.
+ * - `composite` — the entity was expanded by a composite, or the path was
+ *   supplied by `propagate()`'s shared props at the instance.
+ * - `build-param` — the build parameters the authored expression for this path
+ *   *reads*, which is a syntactic dependency, not a value taint. For
+ *   `replicas: params.tier === "prod" ? 5 : 1` a taint says the value came from
+ *   the literal `5`, which is true and useless; the dependency says the field
+ *   is governed by `tier`, which is what an editor needs to know. Under-reports
+ *   (a shape the collector does not follow drops a dependency) and never
+ *   over-reports a parameter the expression does not mention.
+ */
+export type PathOrigin =
+  | { kind: "authored" }
+  | { kind: "composite"; composite: string; instance: string }
+  | { kind: "build-param"; params: string[] };
+
+/** True when `prefix` addresses `path` or an ancestor of it, on a segment boundary. */
+function isPathPrefix(prefix: string, path: string): boolean {
+  if (prefix === "") return true;
+  if (!path.startsWith(prefix)) return false;
+  if (path.length === prefix.length) return true;
+  const next = path[prefix.length];
+  return next === "." || next === "[";
 }
 
 /**
@@ -44,10 +98,16 @@ export function setProvenance(entity: object, prov: EntityProvenance): void {
     existing.sourceFile ??= prov.sourceFile;
     existing.composite ??= prov.composite;
     existing.compositeInstance ??= prov.compositeInstance;
+    if (prov.paths) {
+      existing.paths ??= {};
+      for (const [path, origin] of Object.entries(prov.paths)) {
+        existing.paths[path] ??= origin;
+      }
+    }
     return;
   }
   Object.defineProperty(entity, PROVENANCE, {
-    value: { ...prov },
+    value: { ...prov, ...(prov.paths ? { paths: { ...prov.paths } } : {}) },
     enumerable: false,
     writable: true,
     configurable: true,
@@ -59,6 +119,60 @@ export function getProvenance(entity: object): EntityProvenance | undefined {
   return (entity as Record<symbol, unknown>)[PROVENANCE] as EntityProvenance | undefined;
 }
 
+/**
+ * Record one path's origin, first writer wins — the same rule
+ * {@link setProvenance} applies to entity-level fields, and for the same
+ * reason: expansion runs innermost-composite-first, so the earliest writer is
+ * the most specific one.
+ */
+export function setPathProvenance(entity: object, path: string, origin: PathOrigin): void {
+  setProvenance(entity, { paths: { [path]: origin } });
+}
+
+/**
+ * An entity's recorded path origins in sorted key order, or `undefined` when
+ * none were recorded. Sorted because a build's outputs are compared byte for
+ * byte and object key order is not something insertion should decide.
+ */
+export function getPathProvenance(entity: object): Record<string, PathOrigin> | undefined {
+  const paths = getProvenance(entity)?.paths;
+  if (!paths) return undefined;
+  const keys = Object.keys(paths).sort();
+  if (keys.length === 0) return undefined;
+  const out: Record<string, PathOrigin> = {};
+  for (const key of keys) out[key] = paths[key];
+  return out;
+}
+
+/**
+ * The origin governing `path` — the longest recorded key that addresses it or
+ * one of its ancestors. See {@link PROVENANCE_PATH_GRAMMAR}.
+ */
+export function originOfPath(
+  paths: Readonly<Record<string, PathOrigin>> | undefined,
+  path: string,
+): PathOrigin | undefined {
+  if (!paths) return undefined;
+  let best: string | undefined;
+  for (const key of Object.keys(paths)) {
+    if (!isPathPrefix(key, path)) continue;
+    if (best === undefined || key.length > best.length) best = key;
+  }
+  return best === undefined ? undefined : paths[best];
+}
+
+/** One-line rendering of an origin, for diff output. */
+export function describePathOrigin(origin: PathOrigin): string {
+  switch (origin.kind) {
+    case "authored":
+      return "authored";
+    case "composite":
+      return `composite ${origin.composite} (${origin.instance})`;
+    case "build-param":
+      return `param ${origin.params.join(", ")}`;
+  }
+}
+
 /**
  * One resolved build-time parameter (chant #1064, see ../build-params.ts): its
  * final value and which source won it, so a build's parameter inputs are

package/src/runtime-adapter.ts

@@ -34,8 +34,13 @@ export interface RuntimeAdapter {
   readonly hashAlgorithm: string;
   /** Test whether filePath matches a glob pattern */
   globMatch(pattern: string, filePath: string): boolean;
-  /** Spawn a child process and collect output */
-  spawn(cmd: string[], opts?: { cwd?: string }): Promise<SpawnResult>;
+  /**
+   * Spawn a child process and collect output. When `opts.stdin` is set, it is
+   * written to the child's stdin and the stream is closed — the caller never
+   * needs to round-trip content through a shell (`sh -c "echo … | cmd"`) just
+   * to feed a command that reads from stdin (e.g. `git hash-object --stdin`).
+   */
+  spawn(cmd: string[], opts?: { cwd?: string; stdin?: string }): Promise<SpawnResult>;
   /** Commands to use when spawning package manager / executor */
   readonly commands: RuntimeCommands;
 }
@@ -59,16 +64,32 @@ class NodeRuntimeAdapter implements RuntimeAdapter {
     return picomatch(pattern)(filePath);
   }
 
-  async spawn(cmd: string[], opts?: { cwd?: string }): Promise<SpawnResult> {
+  async spawn(cmd: string[], opts?: { cwd?: string; stdin?: string }): Promise<SpawnResult> {
     return new Promise((resolve) => {
-      execFile(cmd[0], cmd.slice(1), { cwd: opts?.cwd, maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
-        resolve({
-          stdout: stdout ?? "",
-          stderr: stderr ?? "",
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          exitCode: err ? (err as any).code ?? 1 : 0,
+      const child = execFile(
+        cmd[0],
+        cmd.slice(1),
+        { cwd: opts?.cwd, maxBuffer: 10 * 1024 * 1024 },
+        (err, stdout, stderr) => {
+          resolve({
+            stdout: stdout ?? "",
+            stderr: stderr ?? "",
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            exitCode: err ? (err as any).code ?? 1 : 0,
+          });
+        },
+      );
+      // Content is written verbatim (utf-8) — no shell involved, so nothing
+      // reinterprets backslash-escape sequences or needs quote-escaping.
+      // The error handler is load-bearing: a child that exits without reading
+      // stdin (any command that ignores it) makes this write race the pipe
+      // teardown, and an unhandled EPIPE 'error' event crashes the process.
+      if (child.stdin) {
+        child.stdin.on("error", () => {
+          /* EPIPE: child exited without consuming stdin — harmless */
         });
-      });
+        child.stdin.end(opts?.stdin ?? "");
+      }
     });
   }
 }

package/src/serializer.ts

@@ -42,6 +42,24 @@ export interface SerializerResult {
   primary: string;
   /** Additional files keyed by filename (e.g. "network.template.json" → content) */
   files?: Record<string, string>;
+  /**
+   * Basenames from `files` that must reach disk byte-for-byte — never
+   * `JSON.parse`d, key-sorted, or reformatted to YAML by the build's
+   * additional-file writer (chant#1937).
+   *
+   * A separate field rather than a per-file flag on `files` (e.g. widening
+   * its value to `string | { content: string; verbatim: boolean }`) so every
+   * existing lexicon serializer that returns `files: Record<string, string>`
+   * keeps compiling and behaving unchanged: this list defaults to empty, and
+   * only a serializer that actually carries opaque/pre-formatted bytes
+   * (committed ciphertext, a vendored file) needs to populate it.
+   *
+   * Before this field existed, "JSON.parse fails on this content" was the
+   * only way to opt out of round-tripping — true for YAML that happens not to
+   * parse as JSON, but never a structural guarantee (YAML is a JSON
+   * superset).
+   */
+  verbatimFiles?: string[];
   /**
    * Non-fatal diagnostics produced during serialization (e.g. a dialect
    * dropping keys the target platform ignores). The build pipeline collects