Skip to content
Python
17.9 KB
Raw Blame
import { readdirSync, readFileSync } from "node:fs";
import path from "node:path";
import { describe, expect, it } from "vitest";

/** Guard the two halves of a traced write.
 *
 * A `ui.action` only forms a complete four-line chain when the same trace id
 * reaches Core on the request. It is easy to add a trace and forget the
 * argument, which yields a log with `ui.action -> ui.result` and no kernel
 * legs — exactly the failure the native verifier rejects. This check reads the
 * real sources so that mistake fails in the web suite instead of only in a
 * packaged-App run.
 */

const ROOT = path.resolve(__dirname, "..");

function source(file: string): string {
  return readFileSync(path.join(ROOT, "src", file), "utf8");
}

describe("ui trace write coverage", () => {
  it("passes a trace id on every traced memory write", () => {
    const api = source("api.ts");
    // The memory write functions accept a trace id and forward it.
    for (const fn of ["updateSdkMemory", "deleteSdkMemory"]) {
      const start = api.indexOf(`export async function ${fn}(`);
      expect(start, `${fn} not found`).toBeGreaterThan(-1);
      const body = api.slice(start, api.indexOf("\n}", start));
      expect(body, `${fn} must accept traceId`).toContain("traceId?: string");
      expect(body, `${fn} must send the trace header`).toContain(
        "X-One-Memory-Trace-Id",
      );
    }
  });

  it("threads the trace id from each discovering surface", () => {
    // SourcesView already carried the id; assert it stays.
    expect(source("SourcesView.tsx")).toMatch(
      /imports\.setSync\(source, enabled, trace\.traceId\)/,
    );
    // MemorySpace passes the id on both memory writes.
    const memory = source("MemorySpace.tsx");
    expect(memory).toMatch(/updateSdkMemory\([\s\S]{0,160}trace\.traceId/);
    expect(memory).toMatch(/deleteSdkMemory\([\s\S]{0,160}trace\.traceId/);
    // The composer's save is the native four-level sample.
    expect(source("MemoryAddComposer.tsx")).toMatch(
      /addMemory\([\s\S]{0,200}trace\.traceId/,
    );
  });

  it("traces the history-import and graph-width writes", () => {
    const history = source("HistoryImport.tsx");
    expect(history).toMatch(
      /uploadHistoryFile\(file, inputKind, trace\.traceId\)/,
    );
    expect(history).toMatch(
      /commitHistoryFile\(receipt\.upload_id, trace\.traceId\)/,
    );
    const graph = source("GraphWidthPrompt.tsx");
    expect(graph).toMatch(/decideGraphWidth\(decision, trace\.traceId\)/);
    const api = source("api.ts");
    for (const fn of [
      "uploadHistoryFile",
      "commitHistoryFile",
      "decideGraphWidth",
    ]) {
      const start = api.indexOf(`export async function ${fn}(`);
      expect(start, `${fn} not found`).toBeGreaterThan(-1);
      const body = api.slice(start, start + 900);
      expect(body, `${fn} must accept traceId`).toContain("traceId?: string");
    }
    // uploadHistoryFile threads the id through the recoverable transport.
    expect(api).toMatch(/recoverableFileUpload\(/);
    const uploadBody = api.slice(
      api.indexOf("export async function uploadHistoryFile("),
      api.indexOf("export async function uploadHistoryFile(") + 700,
    );
    expect(uploadBody).toMatch(/historyUploadTransport,\s*\n?\s*traceId/);
    // commit and graph forward the header directly.
    const commitBody = api.slice(
      api.indexOf("export async function commitHistoryFile("),
      api.indexOf("export async function commitHistoryFile(") + 700,
    );
    expect(commitBody).toContain("X-One-Memory-Trace-Id");
    const graphBody = api.slice(
      api.indexOf("export async function decideGraphWidth("),
      api.indexOf("export async function decideGraphWidth(") + 700,
    );
    expect(graphBody).toContain("X-One-Memory-Trace-Id");
  });

  it("traces the source-folder save", () => {
    // Choosing a source folder is a real Core write: `PUT
    // /api/v1/sources/{id}/candidate` is a non-GET under `/api/v1/sources`, so
    // Core logs kernel-call/kernel-return. This path had no trace at all, so
    // those legs were orphaned and the log showed a write with no matching user
    // action. The guard also pins the transport half: a trace that is opened but
    // never handed to `saveSourceDirectory` still produces a half chain.
    const picker = source("SourceDirectoryPicker.tsx");
    expect(picker).toMatch(/traceUiAction\("sources", "confirm"\)/);
    expect(picker).toMatch(/saveSourceRoot\(\[[\s\S]{0,400}?trace\.traceId,/);
    const api = source("api.ts");
    const start = api.indexOf("export async function saveSourceDirectory(");
    expect(start, "saveSourceDirectory not found").toBeGreaterThan(-1);
    const body = api.slice(start, api.indexOf("\n}", start));
    expect(body, "saveSourceDirectory must accept traceId").toContain(
      "traceId?: string",
    );
    expect(body, "saveSourceDirectory must send the trace header").toContain(
      "X-One-Memory-Trace-Id",
    );
  });

  it("does not reissue a leftover sync write after onboarding", () => {
    // Connecting a source already opens the one Harness processing switch.
    // Leaving onboarding must not submit a second sync write for the same
    // choice; Freeze/Thaw remains a later explicit user action.
    const onboarding = source("OnboardingFlow.tsx");
    expect(onboarding).not.toMatch(/setSourceSync\(/);
  });

  it("traces every remembered-preference sync write", () => {
    // The remembered-preference reconciler runs outside a click handler: the
    // app applies saved sync selections on entry and during onboarding. Each
    // write must still open a chain at the point of the request instead of
    // leaving kernel-only legs behind.
    const reconcile = source("connection-reconcile.ts");
    expect(reconcile).toMatch(/traceUiAction\("sources", "confirm"\)/);
    expect(reconcile).toMatch(/setSync\(source, true, trace\.traceId\)/);
  });

  it("gives every settle() guard exactly one finally close", () => {
    // The write paths that can return early between opening a trace and
    // finishing it use an idempotent `settle()` helper whose only guaranteed
    // call site is a `finally`. If that call is dropped, an early return leaves
    // a `ui.action` with no `ui.result` — an incomplete chain the native
    // verifier rejects. This ties each `const settle =` definition to exactly
    // one `finally { ... settle(` close in the same file.
    for (const file of ["HistoryImport.tsx"]) {
      const text = source(file);
      const definitions = (text.match(/const settle\s*=/g) ?? []).length;
      const finallyCloses = (
        text.match(/\}\s*finally\s*\{[^}]*\bsettle\(/g) ?? []
      ).length;
      expect(
        definitions,
        `${file} should define at least one settle`,
      ).toBeGreaterThan(0);
      expect(
        finallyCloses,
        `${file} has ${definitions} settle definition(s) but ${finallyCloses} finally close(s)`,
      ).toBe(definitions);
    }
  });

  it("traces the extraction and manual-extract writes", () => {
    // These are non-GET writes on the memory surface that previously ran
    // with no trace at all.
    const memory = source("MemorySpace.tsx");
    expect(memory).toMatch(/setExtractionWindow\([\s\S]{0,80}trace\.traceId/);
    expect(memory).toMatch(/manualExtract\(\[\], trace\.traceId\)/);
    const api = source("api.ts");
    for (const fn of ["setExtractionWindow", "manualExtract"]) {
      const start = api.indexOf(`export async function ${fn}(`);
      expect(start, `${fn} not found`).toBeGreaterThan(-1);
      const body = api.slice(start, start + 600);
      expect(body, `${fn} must accept traceId`).toContain("traceId?: string");
      expect(body, `${fn} must send the trace header`).toContain(
        "X-One-Memory-Trace-Id",
      );
    }
  });

  it("traces the destructive call-history clears", () => {
    // Clearing call records deletes retained history, so it is a real write and
    // must form a four-line chain like the other writes. It previously emitted
    // nothing: the api helpers did not even accept a trace id.
    const view = source("CallHistory.tsx");
    expect(view).toMatch(/traceUiAction\("calls", "confirm"\)/);
    expect(view).toMatch(/clearAllCallEvents\(trace\.traceId\)/);
    expect(view).toMatch(
      /clearCallEvents\(\[\.\.\.confirmation\.ids\], trace\.traceId\)/,
    );

    const client = source("call-history-client.ts");
    for (const fn of ["clearCallEvents", "clearAllCallEvents"]) {
      const start = client.indexOf(`export async function ${fn}(`);
      expect(start, `${fn} not found`).toBeGreaterThan(-1);
      const body = client.slice(start, client.indexOf("\n}", start));
      expect(body, `${fn} must accept traceId`).toContain("traceId");
      expect(body, `${fn} must forward traceId`).toMatch(/traceId\)/);
    }
    const api = source("api.ts");
    for (const fn of ["clearCallEventsRequest", "clearAllCallEventsRequest"]) {
      const start = api.indexOf(`export async function ${fn}(`);
      expect(start, `${fn} not found`).toBeGreaterThan(-1);
      const body = api.slice(start, start + 500);
      expect(body, `${fn} must accept traceId`).toContain("traceId?: string");
      expect(body, `${fn} must send the trace header`).toContain(
        "X-One-Memory-Trace-Id",
      );
    }
  });

  it("traces the streaming answer write", () => {
    // `askMemoriesStream` is a raw `fetch`, so it never passes through the axios
    // interceptor that stamps the trace header. If the caller does not open a
    // trace and hand the id down, Core still logs its kernel legs but under a
    // different id, and the interaction is a half-chain. Both halves are pinned:
    // the call site opens a trace and passes the id, and the stream forwards it.
    const view = source("MemorySpace.tsx");
    expect(view).toMatch(/traceUiAction\("memory", "submit"\)/);
    expect(view).toMatch(
      /askMemoriesStream\(\s*question,\s*scope,\s*undefined,\s*trace\.traceId,?\s*\)/,
    );
    const api = source("api.ts");
    const start = api.indexOf("export async function* askMemoriesStream(");
    expect(start, "askMemoriesStream not found").toBeGreaterThan(-1);
    const body = api.slice(start, api.indexOf("\n}", start));
    expect(body, "askMemoriesStream must accept traceId").toContain(
      "traceId?: string",
    );
    expect(body, "askMemoriesStream must send the trace header").toContain(
      "X-One-Memory-Trace-Id",
    );
  });

  it("traces the answer memory add", () => {
    // `saveAnswer` adds a memory, so it must form a four-line chain.
    const view = source("MemorySpace.tsx");
    expect(view).toMatch(
      /addMemory\(\s*\{[\s\S]{0,240}?scope: "all-apps",\s*\},?\s*trace\.traceId,?\s*\)/,
    );
  });

  it("traces the Harness Freeze/Thaw toggle", () => {
    const control = source("SourcesView.tsx");
    expect(control).toMatch(/traceUiAction\("sources", "toggle"\)/);
    expect(control).toMatch(
      /imports\.setSync\(source, enabled, trace\.traceId\)/,
    );

    const hook = source("use-import-sources.ts");
    expect(hook).toMatch(
      /syncWrite\.mutateAsync\(\{ source, enabled, traceId \}\)/,
    );

    const state = source("source-state.ts");
    expect(state).toMatch(/setSourceSync\(current, enabled, traceId\)/);

    const api = source("api.ts");
    const start = api.indexOf("export async function setSourceSync(");
    expect(start).toBeGreaterThan(-1);
    const body = api.slice(start, start + 600);
    expect(body).toContain("traceId?: string");
    expect(body).toContain("X-One-Memory-Trace-Id");
    expect(api).toContain("X-One-Memory-Trace-Id");
  });

  it("traces the onboarding completion write", () => {
    // Finishing first-run setup records durable onboarding state. It is a
    // non-GET and had no trace.
    const flow = source("OnboardingFlow.tsx");
    expect(flow).toMatch(/traceUiAction\("onboarding", "submit"\)/);
    expect(flow).toMatch(/completeOnboarding\(trace\.traceId\)/);
    const api = source("api.ts");
    const start = api.indexOf("export async function completeOnboarding(");
    expect(start).toBeGreaterThan(-1);
    const body = api.slice(start, start + 400);
    expect(body).toContain("traceId?: string");
    expect(body).toContain("X-One-Memory-Trace-Id");
  });

  it("has no separate memory-add process write", () => {
    // Processing an addition is not a client write: activating a model
    // readmits parked work. The composer must not grow a retry route again.
    const composer = source("MemoryAddComposer.tsx");
    expect(composer).not.toMatch(/traceUiAction\("memory", "retry"\)/);
    const api = source("api.ts");
    expect(api).not.toContain("/process`");
    expect(api).not.toContain("memory-notes");
  });

  it("traces every model-profile write through the hook's single choke point", () => {
    // create / activate / update / delete / probe are all non-GET writes. The
    // hook's `run` funnel starts one trace per write, so each must be handed
    // that trace id and the api functions must forward it.
    const hook = source("use-model-profiles.ts");
    expect(hook).toMatch(/traceUiAction\("settings", traceAction\(key\)\)/);
    // The failure reason must be a bounded code, not the raw key: `key` holds
    // `activate:<profile-id>`, and logging it verbatim would put a profile UUID
    // in the line and make every failure its own ungroupable value.
    // The outcome now depends on whether Core refused or the result is unknown,
    // so the call is `done(<status>, { reason: ... })` rather than a literal
    // `"failed"`. Both reason helpers must stay bounded codes tied to `key`.
    expect(hook).toMatch(
      /trace\.done\(isDefiniteRefusal\(reason\) \? "failed" : "unknown", \{/,
    );
    expect(hook).toMatch(
      /traceReason\(key\)[\s\S]{0,120}?traceReasonUnknown\(key\)/,
    );
    expect(hook).toMatch(
      /function traceReasonUnknown\(key: string\): string \{/,
    );
    expect(hook).not.toMatch(/trace\.done\("failed", \{ reason: key \}\)/);
    expect(hook).toMatch(
      /createModelProfile\(\s*\{[\s\S]{0,200}?traceId,\s*\)/,
    );
    expect(hook).toMatch(/activateModelProfile\(profileId, traceId\)/);
    expect(hook).toMatch(/updateModelProfile\(profileId, patch, traceId\)/);
    expect(hook).toMatch(/deleteModelProfile\(profileId, traceId\)/);
    expect(hook).toMatch(
      /probeModelProfile\(profileId, inputRevision, traceId\)/,
    );
    const api = source("api.ts");
    for (const fn of [
      "createModelProfile",
      "probeModelProfile",
      "activateModelProfile",
      "updateModelProfile",
      "deleteModelProfile",
    ]) {
      const start = api.indexOf(`export async function ${fn}(`);
      expect(start, `${fn} not found`).toBeGreaterThan(-1);
      // Slice to the function's real end, not a fixed window: a fixed window
      // silently stopped covering the header once a comment pushed it past the
      // boundary, which reports a missing header that is actually there.
      const end = api.indexOf("\n}", start);
      expect(end, `${fn} body end not found`).toBeGreaterThan(start);
      const body = api.slice(start, end);
      expect(body, `${fn} must accept traceId`).toContain("traceId?: string");
      expect(body, `${fn} must send the trace header`).toContain(
        "X-One-Memory-Trace-Id",
      );
    }
  });

  it("names one Core endpoint per poll key", () => {
    // A poll key is a *data plane* name. When two call sites name the same key
    // but lead to different Core endpoints, one is misnamed — the scheduler
    // runs every subscriber, so the key stops meaning "this surface". That is
    // Walk each `subscribePoll({...})` body and require the reachable
    // endpoints to agree per key.
    const files = readdirSync(path.join(ROOT, "src"))
      .filter((name) => /\.(ts|tsx)$/.test(name) && !/\.test\./.test(name))
      .map((name) => path.join(ROOT, "src", name));
    const allSources = files.map((file) => readFileSync(file, "utf8"));
    const values = files.map((file, i) => ({ file, text: allSources[i] }));

    /** Core reads reachable from a poll body, following named local thunks. */
    const endpointsOf = (body: string): string[] => {
      const found = new Set<string>();
      const scan = (fragment: string) => {
        for (const m of fragment.matchAll(/\b(get[A-Z][A-Za-z0-9]*)\s*\(/g))
          found.add(m[1]);
        for (const m of fragment.matchAll(
          /\b([a-z][A-Za-z0-9]*)\.(refresh|load)\s*\(/g,
        ))
          found.add(`${m[1]}.${m[2]}`);
      };
      scan(body);
      for (const m of body.matchAll(
        /\b(?:run|fetch):\s*([A-Za-z_$][\w$]*)\b/g,
      )) {
        for (const { text } of values) {
          const decl = new RegExp(
            `(?:async\\s+)?function\\s+${m[1]}\\s*\\(|const\\s+${m[1]}\\s*=`,
          ).exec(text);
          if (!decl) continue;
          scan(text.slice(decl.index, decl.index + 1200));
        }
      }
      return [...found].sort();
    };

    const readersByKey = new Map<string, Map<string, string>>();
    for (const { file, text } of values) {
      let index = text.indexOf("subscribePoll({");
      while (index >= 0) {
        const open = text.indexOf("{", index);
        let depth = 0;
        let end = open;
        for (let i = open; i < text.length; i += 1) {
          if (text[i] === "{") depth += 1;
          else if (text[i] === "}") {
            depth -= 1;
            if (depth === 0) {
              end = i;
              break;
            }
          }
        }
        const body = text.slice(open, end + 1);
        const key = /key:\s*"([a-z-]+)"/.exec(body)?.[1];
        if (key) {
          const endpoints = endpointsOf(body).join("+") || "unknown";
          const perKey = readersByKey.get(key) ?? new Map<string, string>();
          perKey.set(endpoints, path.basename(file));
          readersByKey.set(key, perKey);
        }
        index = text.indexOf("subscribePoll({", end);
      }
    }
    const conflicts = [...readersByKey.entries()]
      .filter(([, readers]) => readers.size > 1)
      .map(
        ([key, readers]) =>
          `${key}: ${[...readers.entries()]
            .map(([r, f]) => `${r} (${f})`)
            .join(" vs ")}`,
      );
    expect(conflicts).toEqual([]);
  });
});