@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/lib/diagnostics/trace.test.mjs

@@ -1,251 +0,0 @@
-/**
- * trace.test.mjs — node:test coverage for the trace/correlation spine.
- *
- * Hermetic: the clock and RNG are injected so minted ids are deterministic, and
- * AsyncLocalStorage propagation is exercised across real awaits.
- */
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-
-import {
-  mintTraceId,
-  isTraceId,
-  toContext,
-  withTrace,
-  currentTrace,
-  currentTraceId,
-  childSpan,
-  traceHeaders,
-  traceFromHeaders,
-  TRACE_ID_LENGTH,
-} from "./trace.mjs";
-
-// A deterministic 10-byte RNG.
-function fixedRng(byte) {
-  return () => Buffer.alloc(10, byte);
-}
-
-// ---------------------------------------------------------------------------
-// mintTraceId
-// ---------------------------------------------------------------------------
-
-test("mintTraceId returns a 26-char ULID-shaped id", () => {
-  const id = mintTraceId();
-  assert.equal(id.length, TRACE_ID_LENGTH);
-  assert.equal(id.length, 26);
-  assert.ok(isTraceId(id), `expected ${id} to be a valid trace id`);
-});
-
-test("mintTraceId is deterministic under injected clock + rng", () => {
-  const deps = { now: () => 1_700_000_000_000, rng: fixedRng(0x00) };
-  const a = mintTraceId(deps);
-  const b = mintTraceId(deps);
-  assert.equal(a, b, "same clock + rng must yield the same id");
-});
-
-test("mintTraceId is time-sortable: later timestamp sorts after earlier", () => {
-  const early = mintTraceId({ now: () => 1_000_000_000_000, rng: fixedRng(0xff) });
-  const late = mintTraceId({ now: () => 2_000_000_000_000, rng: fixedRng(0x00) });
-  assert.ok(early < late, "earlier-minted id should sort lexicographically first");
-});
-
-test("mintTraceId randomness varies the tail for the same clock", () => {
-  const now = () => 1_700_000_000_000;
-  const a = mintTraceId({ now, rng: fixedRng(0x01) });
-  const b = mintTraceId({ now, rng: fixedRng(0x02) });
-  assert.notEqual(a, b);
-  // Same timestamp head, different random tail.
-  assert.equal(a.slice(0, 10), b.slice(0, 10));
-  assert.notEqual(a.slice(10), b.slice(10));
-});
-
-test("two real mints are unique", () => {
-  const ids = new Set();
-  for (let i = 0; i < 1000; i++) ids.add(mintTraceId());
-  assert.equal(ids.size, 1000);
-});
-
-// ---------------------------------------------------------------------------
-// isTraceId
-// ---------------------------------------------------------------------------
-
-test("isTraceId rejects malformed inputs", () => {
-  assert.equal(isTraceId(""), false);
-  assert.equal(isTraceId(null), false);
-  assert.equal(isTraceId(undefined), false);
-  assert.equal(isTraceId(123), false);
-  assert.equal(isTraceId("short"), false);
-  assert.equal(isTraceId("a".repeat(26)), false); // lowercase not in alphabet
-  assert.equal(isTraceId("I".repeat(26)), false); // I is excluded from Crockford
-  assert.equal(isTraceId(mintTraceId()), true);
-});
-
-// ---------------------------------------------------------------------------
-// toContext
-// ---------------------------------------------------------------------------
-
-test("toContext normalizes a bare id string into {trace_id, span}", () => {
-  const id = mintTraceId();
-  const ctx = toContext(id);
-  assert.equal(ctx.trace_id, id);
-  assert.equal(ctx.span, "root");
-});
-
-test("toContext mints a fresh trace when given null/undefined", () => {
-  const a = toContext(null);
-  const b = toContext(undefined);
-  assert.ok(isTraceId(a.trace_id));
-  assert.ok(isTraceId(b.trace_id));
-  assert.notEqual(a.trace_id, b.trace_id);
-});
-
-test("toContext preserves a provided span", () => {
-  const ctx = toContext({ trace_id: "X", span: "root.classify" });
-  assert.equal(ctx.trace_id, "X");
-  assert.equal(ctx.span, "root.classify");
-});
-
-// ---------------------------------------------------------------------------
-// withTrace / currentTrace propagation
-// ---------------------------------------------------------------------------
-
-test("currentTrace is null outside any withTrace", () => {
-  assert.equal(currentTrace(), null);
-  assert.equal(currentTraceId(), null);
-});
-
-test("withTrace exposes the context to synchronous code", () => {
-  const id = mintTraceId();
-  const seen = withTrace(id, () => currentTraceId());
-  assert.equal(seen, id);
-});
-
-test("withTrace passes the normalized context to fn", () => {
-  const id = mintTraceId();
-  const ctx = withTrace(id, (c) => c);
-  assert.deepEqual(ctx, { trace_id: id, span: "root" });
-});
-
-test("withTrace propagates across awaits (async hooks)", async () => {
-  const id = mintTraceId();
-  const seen = await withTrace(id, async () => {
-    await new Promise((r) => setTimeout(r, 1));
-    await Promise.resolve();
-    return currentTraceId();
-  });
-  assert.equal(seen, id);
-  // Context does not leak after the run.
-  assert.equal(currentTrace(), null);
-});
-
-test("withTrace nests: inner context restores to outer on exit", () => {
-  const outer = mintTraceId();
-  const inner = mintTraceId();
-  withTrace(outer, () => {
-    assert.equal(currentTraceId(), outer);
-    withTrace(inner, () => {
-      assert.equal(currentTraceId(), inner);
-    });
-    assert.equal(currentTraceId(), outer);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// childSpan
-// ---------------------------------------------------------------------------
-
-test("childSpan extends the span path and keeps the trace_id", () => {
-  const id = mintTraceId();
-  withTrace(id, () => {
-    const c = childSpan("classify");
-    assert.equal(c.trace_id, id);
-    assert.equal(c.span, "root.classify");
-    const cc = childSpan("send", c);
-    assert.equal(cc.trace_id, id);
-    assert.equal(cc.span, "root.classify.send");
-  });
-});
-
-test("childSpan sanitizes unsafe segment chars", () => {
-  const c = childSpan("a/b c.d", { trace_id: "T", span: "root" });
-  assert.equal(c.span, "root.a_b_c_d");
-});
-
-test("childSpan with no ambient context mints a fresh trace", () => {
-  const c = childSpan("dispatch");
-  assert.ok(isTraceId(c.trace_id));
-  assert.equal(c.span, "root.dispatch");
-});
-
-// ---------------------------------------------------------------------------
-// traceHeaders / traceFromHeaders — boundary crossing
-// ---------------------------------------------------------------------------
-
-test("traceHeaders serializes the ambient context", () => {
-  const id = mintTraceId();
-  const headers = withTrace({ trace_id: id, span: "root.dispatch" }, () =>
-    traceHeaders()
-  );
-  assert.deepEqual(headers, { trace_id: id, span: "root.dispatch" });
-});
-
-test("traceHeaders returns {} when there is no context", () => {
-  assert.deepEqual(traceHeaders(), {});
-  assert.deepEqual(traceHeaders(null), {});
-});
-
-test("traceFromHeaders round-trips a serialized context", () => {
-  const id = mintTraceId();
-  const headers = { trace_id: id, span: "root.session" };
-  const ctx = traceFromHeaders(headers);
-  assert.deepEqual(ctx, { trace_id: id, span: "root.session" });
-});
-
-test("traceFromHeaders returns null on missing/garbage input", () => {
-  assert.equal(traceFromHeaders(null), null);
-  assert.equal(traceFromHeaders(undefined), null);
-  assert.equal(traceFromHeaders({}), null);
-  assert.equal(traceFromHeaders({ span: "root" }), null);
-  assert.equal(traceFromHeaders("nope"), null);
-});
-
-test("traceFromHeaders defaults span to root when absent", () => {
-  const id = mintTraceId();
-  const ctx = traceFromHeaders({ trace_id: id });
-  assert.equal(ctx.span, "root");
-});
-
-// ---------------------------------------------------------------------------
-// End-to-end: one trace_id carried item -> classify -> dispatch -> send
-// ---------------------------------------------------------------------------
-
-test("a single trace_id correlates a full interaction across hops", async () => {
-  const traceId = mintTraceId();
-  const spansSeen = [];
-
-  // item/tick mints the trace and opens the root context.
-  await withTrace(traceId, async () => {
-    spansSeen.push(currentTrace().span); // root
-
-    // classify (sync hop)
-    const classifyCtx = childSpan("classify");
-    await withTrace(classifyCtx, async () => {
-      spansSeen.push(currentTrace().span);
-      assert.equal(currentTraceId(), traceId);
-    });
-
-    // dispatch -> serialize across a (simulated) process boundary
-    const dispatchCtx = childSpan("dispatch");
-    const headers = traceHeaders(dispatchCtx);
-
-    // session: reconstruct from headers in the "child process"
-    const sessionCtx = traceFromHeaders(headers);
-    await withTrace(childSpan("send", sessionCtx), async () => {
-      spansSeen.push(currentTrace().span);
-      assert.equal(currentTraceId(), traceId);
-    });
-  });
-
-  assert.deepEqual(spansSeen, ["root", "root.classify", "root.dispatch.send"]);
-});

package/lib/env-compat.test.mjs

@@ -1,104 +0,0 @@
-/**
- * env-compat.test.mjs — NEOLITH_* ⇄ COHORT_* bridge: both directions,
- * no-clobber (presence beats aliasing, even for ""), non-brand keys
- * untouched, idempotency, and the default process.env path. Uses injected
- * plain-object envs everywhere except the one save/restore process.env test.
- * Run: node --test lib/env-compat.test.mjs
- */
-"use strict";
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-
-import { applyBrandEnvCompat, LEGACY_PREFIX, CANONICAL_PREFIX } from "./env-compat.mjs";
-
-test("legacy → canonical: NEOLITH_* is mirrored to COHORT_*", () => {
-  const env = { NEOLITH_API_KEY: "nlk_123", NEOLITH_ORG_ID: "acme" };
-  const created = applyBrandEnvCompat(env);
-  assert.equal(env.COHORT_API_KEY, "nlk_123");
-  assert.equal(env.COHORT_ORG_ID, "acme");
-  assert.equal(env.NEOLITH_API_KEY, "nlk_123"); // source untouched
-  assert.deepEqual(
-    created.sort((a, b) => a.from.localeCompare(b.from)),
-    [
-      { from: "NEOLITH_API_KEY", to: "COHORT_API_KEY" },
-      { from: "NEOLITH_ORG_ID", to: "COHORT_ORG_ID" },
-    ],
-  );
-});
-
-test("canonical → legacy: COHORT_* is mirrored to NEOLITH_*", () => {
-  const env = { COHORT_DB: "/var/db/cohort.sqlite", COHORT_ADMIN_TOKEN: "adm_1" };
-  applyBrandEnvCompat(env);
-  assert.equal(env.NEOLITH_DB, "/var/db/cohort.sqlite");
-  assert.equal(env.NEOLITH_ADMIN_TOKEN, "adm_1");
-});
-
-test("never clobbers: a present twin is left byte-for-byte untouched", () => {
-  const env = {
-    NEOLITH_API_KEY: "old-value",
-    COHORT_API_KEY: "new-value", // both set, deliberately different
-    NEOLITH_BASE: "https://legacy.example",
-    COHORT_BASE: "", // present-but-empty still wins over the alias
-  };
-  const created = applyBrandEnvCompat(env);
-  assert.equal(env.COHORT_API_KEY, "new-value");
-  assert.equal(env.NEOLITH_API_KEY, "old-value");
-  assert.equal(env.COHORT_BASE, ""); // NOT overwritten by NEOLITH_BASE
-  assert.deepEqual(created, []); // every twin existed — nothing bridged
-});
-
-test("presence propagates: an empty-string source mirrors as empty string", () => {
-  const env = { NEOLITH_AGENT_ID: "" };
-  applyBrandEnvCompat(env);
-  assert.equal(env.COHORT_AGENT_ID, "");
-});
-
-test("non-brand keys and non-string values are ignored", () => {
-  const env = {
-    PATH: "/usr/bin",
-    NEOLITHIC_ERA: "not-a-brand-var", // prefix must match exactly
-    COHORTS: "plural, not the prefix",
-    NEOLITH_BROKEN: undefined, // never minted into "undefined"
-  };
-  const created = applyBrandEnvCompat(env);
-  assert.deepEqual(created, []);
-  assert.ok(!("COHORT_BROKEN" in env));
-  assert.ok(!("COHORTIC_ERA" in env));
-  assert.equal(Object.keys(env).length, 4);
-});
-
-test("idempotent: a second pass is a no-op that reports []", () => {
-  const env = { NEOLITH_API_TOKEN: "t1", COHORT_REPO: "/path/to/hq" };
-  const first = applyBrandEnvCompat(env);
-  assert.equal(first.length, 2);
-  const snapshot = { ...env };
-  const second = applyBrandEnvCompat(env);
-  assert.deepEqual(second, []);
-  assert.deepEqual(env, snapshot);
-});
-
-test("defaults to process.env and bridges the real environment", () => {
-  // Unique suffix so a concurrent test file can never collide.
-  const suffix = `ENV_COMPAT_TEST_${process.pid}`;
-  const legacyKey = `${LEGACY_PREFIX}${suffix}`;
-  const canonicalKey = `${CANONICAL_PREFIX}${suffix}`;
-  const prevLegacy = process.env[legacyKey];
-  const prevCanonical = process.env[canonicalKey];
-  try {
-    delete process.env[canonicalKey];
-    process.env[legacyKey] = "bridged";
-    applyBrandEnvCompat();
-    assert.equal(process.env[canonicalKey], "bridged");
-  } finally {
-    if (prevLegacy == null) delete process.env[legacyKey];
-    else process.env[legacyKey] = prevLegacy;
-    if (prevCanonical == null) delete process.env[canonicalKey];
-    else process.env[canonicalKey] = prevCanonical;
-  }
-});
-
-test("tolerates a missing/foreign env argument without throwing", () => {
-  assert.deepEqual(applyBrandEnvCompat(null), []);
-  assert.deepEqual(applyBrandEnvCompat("not-an-object"), []);
-});