@intentius/chant 0.72.2 → 0.72.4

package/src/meta/source-is-text.test.ts

@@ -0,0 +1,72 @@
+import { describe, test, expect } from "vitest";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Every shipped source file is text a text tool can read.
+ *
+ * chant#2280 — `graph-ir.ts` carried three literal NUL bytes inside a template
+ * literal, used as separators in a composite key. The value was right and the
+ * code worked; what broke was everything that reads the file as text. ripgrep
+ * classifies a file containing NUL as binary, so it answers `binary file
+ * matches (found a NUL byte around offset 32631)` instead of the matching
+ * lines, and a repo-wide search does not list the file at all. 911 lines were
+ * invisible to every grep-driven search of this repository for as long as the
+ * bytes were there.
+ *
+ * That is worse than a silent bug, because it is a silent bug in the tool you
+ * would use to find bugs. Any audit, any "I searched the codebase", any
+ * refactor that greps for a symbol defined in that file quietly skipped it and
+ * reported success.
+ *
+ * The fix is not to stop using NUL as a separator — it is a good one, being the
+ * character that cannot appear in an identifier or an attribute name. It is to
+ * write it as an escape, four ASCII characters in the file and the same single
+ * code unit at runtime.
+ */
+const SRC = fileURLToPath(new URL("../", import.meta.url));
+
+/** Every TypeScript file under core's src, tests and fixtures included. */
+function sourceFiles(dir: string): string[] {
+  return readdirSync(dir).flatMap((entry) => {
+    const path = join(dir, entry);
+    if (statSync(path).isDirectory()) return entry === "node_modules" ? [] : sourceFiles(path);
+    return /\.(ts|mts|cts)$/.test(entry) ? [path] : [];
+  });
+}
+
+describe("source files are text, not binary (chant#2280)", () => {
+  test("no shipped source file contains a NUL byte", () => {
+    const offenders: string[] = [];
+    for (const file of sourceFiles(SRC)) {
+      const buf = readFileSync(file);
+      const at = buf.indexOf(0);
+      if (at !== -1) offenders.push(`${relative(SRC, file)} (first at byte ${at})`);
+    }
+
+    expect(
+      offenders,
+      "a NUL byte makes ripgrep treat the file as binary, so it reports a " +
+        "binary-file-matches line instead of the matches and a repo-wide search omits " +
+        "the file entirely. Write the character as a unicode escape instead — same " +
+        "value at runtime, plain ASCII in the file.",
+    ).toEqual([]);
+  });
+
+  test("the composite edge key still separates on NUL, which is the point of using it", () => {
+    // Guards the fix rather than the file: the escape must denote the same
+    // character the literal byte did, or the separator silently becomes
+    // something that CAN occur in an identifier and distinct edges collide.
+    const source = readFileSync(join(SRC, "graph-ir.ts"), "utf8");
+    const key = source.split("\n").find((l) => l.includes("const key = `${edge.from}"));
+    expect(key, "the composite edge key moved; check its separator is still NUL").toBeDefined();
+    expect(key).toContain("\\u0000");
+
+    // And the escape really is the NUL character, not a look-alike. Built with
+    // fromCharCode so this file stays plain ASCII and does not fail its own gate.
+    const nul = String.fromCharCode(0);
+    expect(`a${nul}b`.charCodeAt(1)).toBe(0);
+    expect(`a${nul}b`.split(nul)).toEqual(["a", "b"]);
+  });
+});

package/src/observation.ts

@@ -57,14 +57,33 @@ export type UnobservedReason =
   | "unsupported-kind"
   | "filtered";
 
-/** Every legal {@link UnobservedReason}, for validation and conformance checks. */
-export const UNOBSERVED_REASONS: readonly UnobservedReason[] = [
-  "read-failed",
-  "no-credentials",
-  "no-binding",
-  "unsupported-kind",
-  "filtered",
-];
+/**
+ * Every legal {@link UnobservedReason}, for validation and conformance checks.
+ *
+ * Derived from a witness keyed off the union rather than written out beside it
+ * (chant#2366). A hand-maintained array is only ever checked for holding legal
+ * members, never for holding ALL of them, so a reason added to the type left
+ * the array silently short — `tsc` clean, every observation test green, and a
+ * value the type permits that `observation-conformance.ts` refuses. A lexicon
+ * could construct a value its own suite rejected.
+ *
+ * Keying a `Record` off the union makes the omission a compile error at the
+ * point of the omission. This is the construction #2365 applied to all four
+ * closed sets in `./behaviour.ts`; `BEHAVIOUR_UNPREDICTED_REASONS` derives from
+ * this very type, so that module was already protected against a change here
+ * while this module was not.
+ */
+const UNOBSERVED_REASON_WITNESS: Record<UnobservedReason, true> = {
+  "read-failed": true,
+  "no-credentials": true,
+  "no-binding": true,
+  "unsupported-kind": true,
+  filtered: true,
+};
+
+export const UNOBSERVED_REASONS: readonly UnobservedReason[] = Object.keys(
+  UNOBSERVED_REASON_WITNESS,
+) as UnobservedReason[];
 
 /** True when `value` is a legal {@link UnobservedReason}. */
 export function isUnobservedReason(value: unknown): value is UnobservedReason {

package/src/op/activities/converge-push.test.ts

@@ -0,0 +1,101 @@
+import { describe, test, expect, vi, beforeEach } from "vitest";
+
+/**
+ * chant#2337 — a converge tick says whether its record reached the remote.
+ *
+ * `convergeTick` ended with `await pushLifecycle().catch(() => undefined)`, the
+ * last instance of the idiom #2310 was filed about. The append is local-first
+ * and always lands, so the tick's own result was correct either way — what was
+ * missing is whether anyone else can see it.
+ *
+ * Softer than the gate's version of the same bug, which #2336 fixed: a lost
+ * tick record is an informational log rather than an approval, so nobody is
+ * left waiting on a fact they cannot see. It is still not success, and a
+ * converge loop reporting a clean tick while its ledger never leaves the
+ * machine is telling an operator something untrue.
+ */
+const execMock = vi.fn();
+vi.mock("node:child_process", () => ({
+  exec: (cmd: string, _opts: unknown, cb: (e: Error | null, r: { stdout: string; stderr: string }) => void) =>
+    cb(null, { stdout: execMock(cmd) as string, stderr: "" }),
+}));
+
+const pushLifecycle = vi.fn();
+vi.mock("../../lifecycle/git", () => ({
+  fetchLifecycle: vi.fn(async () => undefined),
+  pushLifecycle: (...args: unknown[]) => pushLifecycle(...args) as Promise<boolean>,
+}));
+
+vi.mock("../../lifecycle/converge-ledger", async (orig) => {
+  const actual = (await orig()) as Record<string, unknown>;
+  return {
+    ...actual,
+    readConvergeLedger: vi.fn(async () => ({ records: [] })),
+    appendConvergeRecord: vi.fn(async (record: Record<string, unknown>) => ({
+      record: { ...record, id: "tick-1" },
+    })),
+  };
+});
+
+const { convergeTick } = await import("./converge");
+
+/** A tick with nothing to do: no drift, no rules, so only the ledger write matters. */
+async function tick(): Promise<Awaited<ReturnType<typeof convergeTick>>> {
+  return convergeTick({ opName: "demo", env: "prod", rules: [], dial: "report" } as never);
+}
+
+describe("a converge tick reports its push outcome (chant#2337)", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    execMock.mockImplementation((cmd: string) =>
+      cmd.includes("lifecycle plan")
+        ? JSON.stringify({ env: "prod", entries: [] })
+        : JSON.stringify([]),
+    );
+  });
+
+  test("a push that lands reports pushed, with no warning", async () => {
+    pushLifecycle.mockResolvedValue(true);
+
+    const result = await tick();
+
+    expect(result.pushed).toBe(true);
+    expect(result.pushWarning).toBeUndefined();
+  });
+
+  test("a REJECTED push is reported, not swallowed", async () => {
+    // Red before chant#2337: `.catch(() => undefined)` meant the tick returned
+    // the same shape whether or not the record left the machine.
+    pushLifecycle.mockRejectedValue(new Error("remote rejected: chant/lifecycle has moved"));
+
+    const result = await tick();
+
+    expect(result.pushed).toBe(false);
+    expect(result.pushWarning).toContain("remote rejected");
+  });
+
+  test("no remote configured is reported too, and says which it is", async () => {
+    // `pushLifecycle` returns false rather than throwing when there is no
+    // remote. That is not an error, but it is not a push either, and the two
+    // reasons are worth telling apart in the warning.
+    pushLifecycle.mockResolvedValue(false);
+
+    const result = await tick();
+
+    expect(result.pushed).toBe(false);
+    expect(result.pushWarning).toMatch(/no remote/i);
+  });
+
+  test("the tick's own findings are unaffected by a failed push", async () => {
+    // The append is local-first and always lands. A push failure must not make
+    // the tick misreport what it observed, or the fix would have traded one
+    // wrong answer for another.
+    pushLifecycle.mockRejectedValue(new Error("nope"));
+
+    const result = await tick();
+
+    expect(result.id).toBe("tick-1");
+    expect(result.drifted).toBe(false);
+    expect(typeof result.log).toBe("string");
+  });
+});

package/src/op/activities/converge.ts

@@ -104,6 +104,22 @@ export interface ConvergeTickResult {
   gated: number;
   /** The one human-readable summary line this tick produced. */
   log: string;
+  /**
+   * Whether this tick's ledger record reached the remote (chant#2337).
+   *
+   * The append is local-first and always lands, so the tick's own result is
+   * correct either way — this says whether anyone else can see it. Before
+   * this, the push was `.catch(() => undefined)` and the tick reported success
+   * whether or not the record left the machine, which is the last instance of
+   * the idiom #2310 was filed about.
+   *
+   * Softer than the gate's version of the same bug (#2336): a lost tick record
+   * is an informational log rather than an approval, so nobody is stranded
+   * waiting on a fact they cannot see. It is still not success.
+   */
+  pushed: boolean;
+  /** Why the record did not reach the remote, when `pushed` is false. */
+  pushWarning?: string;
 }
 
 function shellQuote(s: string): string {
@@ -442,7 +458,19 @@ export async function convergeTick(args: ConvergeTickArgs, signal?: AbortSignal)
     },
     log,
   });
-  await pushLifecycle().catch(() => undefined);
+  // chant#2337 — reported rather than swallowed, the way #2336 does it for the
+  // gate. A push that did not land leaves a correct local record nobody else
+  // can read, and the caller is the only one positioned to say so.
+  let pushed = false;
+  let pushWarning: string | undefined;
+  try {
+    pushed = await pushLifecycle();
+    if (!pushed) {
+      pushWarning = "no remote is configured for chant/lifecycle — the tick record was recorded locally only";
+    }
+  } catch (err) {
+    pushWarning = err instanceof Error ? err.message : String(err);
+  }
 
   return {
     id: record.id,
@@ -455,5 +483,7 @@ export async function convergeTick(args: ConvergeTickArgs, signal?: AbortSignal)
     unobserved: record.summary.unobserved,
     adopted: record.summary.adopted,
     log: record.log,
+    pushed,
+    ...(pushWarning !== undefined ? { pushWarning } : {}),
   };
 }