@unifyplane/logsdk 1.0.0

package/tests/sinks_file_ndjson.test.ts

@@ -0,0 +1,53 @@
+import { test, expect } from "vitest";
+import path from "node:path";
+import os from "node:os";
+import fs from "node:fs/promises";
+import type { StepRecord } from "../src/core/types";
+import { assertStepRecord } from "../src/validate/schema_guard";
+
+class FileNdjsonSink {
+  constructor(private readonly filePath: string) {}
+
+  async emit(record: Readonly<StepRecord>): Promise<void> {
+    assertStepRecord(record);
+    const line = `${JSON.stringify(record)}\n`;
+    await fs.appendFile(this.filePath, line, "utf8");
+  }
+}
+
+function buildRecord(recordId: string): StepRecord {
+  return Object.freeze({
+    record_version: "log.step.v1",
+    record_id: recordId,
+    sequence: 1,
+    timestamp_utc: new Date().toISOString(),
+    monotonic_time: Date.now(),
+    institution: "UnifyPlane",
+    system_name: "LogSDK",
+    system_type: "service",
+    environment: "test",
+    system_version: "1.0.0",
+    instance_id: "unit-test",
+    message: "NDJSON check",
+    context_hash: "context_hash_001",
+    context_version: "log.context.v1",
+    record_hash: "hash_001",
+    hash_algorithm: "sha256",
+  });
+}
+
+test("file sink writes NDJSON", async () => {
+  const filePath = path.join(os.tmpdir(), `logsdk-${Date.now()}.ndjson`);
+  const sink = new FileNdjsonSink(filePath);
+
+  await sink.emit(buildRecord("rec_ndjson_001"));
+  await sink.emit(buildRecord("rec_ndjson_002"));
+
+  const content = await fs.readFile(filePath, "utf8");
+  const lines = content.split(/\r?\n/).filter(Boolean);
+
+  expect(lines.length).toBe(2);
+  const parsed = lines.map((line: string) => JSON.parse(line) as StepRecord);
+  expect(parsed[0].record_id).toBe("rec_ndjson_001");
+  expect(parsed[1].record_id).toBe("rec_ndjson_002");
+});

package/tests/step1_compliance.test.ts

@@ -0,0 +1,192 @@
+import { beforeEach, test, expect, vi } from "vitest";
+import path from "node:path";
+import os from "node:os";
+import fs from "node:fs/promises";
+import { initLogSDK } from "../src/index";
+import { createFileNdjsonSink } from "../src/sinks/file_ndjson_sink";
+import { resetContextForTests } from "../src/core/context";
+import * as spool from "../src/core/spool";
+import {
+  AUTHORITATIVE_FAILURE_SWALLOWED,
+  CONTEXT_INJECTION_VIOLATION,
+  NO_AUTHORITATIVE_SINK,
+  PAYLOAD_EMBEDDING_VIOLATION,
+  NonComplianceError,
+} from "../src/validate/noncompliance";
+
+const baseSystem = {
+  institution: "UnifyPlane",
+  system_name: "LogSDK",
+  system_type: "service",
+  environment: "test",
+  system_version: "1.0.0",
+  instance_id: "unit-test",
+};
+
+async function expectNonCompliance(
+  action: Promise<void>,
+  code: string
+): Promise<void> {
+  await expect(action).rejects.toMatchObject({ code });
+}
+
+beforeEach(() => {
+  resetContextForTests();
+});
+
+test("fails when no authoritative sink configured", async () => {
+  const log = initLogSDK({
+    context: { build: "test" },
+    system: baseSystem,
+    sinks: [
+      {
+        sinkClass: "observability",
+        sink: {
+          emit() {
+            // no-op
+          },
+        },
+      },
+    ],
+  });
+
+  await expectNonCompliance(log.step("ok"), NO_AUTHORITATIVE_SINK);
+});
+
+test("fails when message contains JSON", async () => {
+  const log = initLogSDK({
+    context: { build: "test" },
+    system: baseSystem,
+    sinks: [
+      {
+        sinkClass: "authoritative",
+        sink: {
+          emit() {
+            // no-op
+          },
+        },
+      },
+    ],
+  });
+
+  await expectNonCompliance(
+    log.step('{"payload":true}'),
+    PAYLOAD_EMBEDDING_VIOLATION
+  );
+});
+
+test("fails on per-step context injection attempt", async () => {
+  const log = initLogSDK({
+    context: { build: "test" },
+    system: baseSystem,
+    sinks: [
+      {
+        sinkClass: "authoritative",
+        sink: {
+          emit() {
+            // no-op
+          },
+        },
+      },
+    ],
+  });
+
+  const unsafeStep = log.step as (message: unknown) => Promise<void>;
+  await expectNonCompliance(
+    unsafeStep({ message: "step", context: { injected: true } }),
+    CONTEXT_INJECTION_VIOLATION
+  );
+});
+
+test("degrades when authoritative sink emit throws", async () => {
+  const log = initLogSDK({
+    context: { build: "test" },
+    system: baseSystem,
+    sinks: [
+      {
+        sinkClass: "authoritative",
+        sink: {
+          emit() {
+            throw new Error("boom");
+          },
+        },
+      },
+    ],
+  });
+  const spoolPath = path.join(
+    os.tmpdir(),
+    `logsdk-step1-spool-${Date.now()}-${Math.random()}.ndjson`
+  );
+  const previousSpool = process.env.LOGSDK_EMERGENCY_SPOOL_PATH;
+  process.env.LOGSDK_EMERGENCY_SPOOL_PATH = spoolPath;
+
+  try {
+    await log.step("step");
+
+    const content = await fs.readFile(spoolPath, "utf8");
+    expect(content).toContain("step");
+  } finally {
+    await fs.rm(spoolPath, { force: true });
+    if (previousSpool === undefined) {
+      delete process.env.LOGSDK_EMERGENCY_SPOOL_PATH;
+    } else {
+      process.env.LOGSDK_EMERGENCY_SPOOL_PATH = previousSpool;
+    }
+  }
+});
+
+test("fails when emergency spool cannot persist authoritative record", async () => {
+  const log = initLogSDK({
+    context: { build: "test" },
+    system: baseSystem,
+    sinks: [
+      {
+        sinkClass: "authoritative",
+        sink: {
+          emit() {
+            throw new Error("boom");
+          },
+        },
+      },
+    ],
+  });
+
+  const spy = vi
+    .spyOn(spool, "writeEmergencySpool")
+    .mockRejectedValue(new Error("spool failure"));
+
+  try {
+    await expectNonCompliance(log.step("step"), AUTHORITATIVE_FAILURE_SWALLOWED);
+  } finally {
+    spy.mockRestore();
+  }
+});
+
+test("writes NDJSON for valid step", async () => {
+  const filePath = path.join(os.tmpdir(), `logsdk-step1-${Date.now()}.ndjson`);
+  const fileSink = createFileNdjsonSink(filePath);
+
+  const log = initLogSDK({
+    context: { build: "test" },
+    system: baseSystem,
+    sinks: [
+      {
+        sinkClass: "authoritative",
+        sink: fileSink,
+      },
+    ],
+  });
+
+  await log.step("First step");
+  await log.step("Second step");
+
+  const content = await fs.readFile(filePath, "utf8");
+  const lines = content.split(/\r?\n/).filter(Boolean);
+
+  expect(lines.length).toBe(2);
+  const records = lines.map((line: string) => JSON.parse(line) as { record_version: string; message: string });
+  expect(records[0].record_version).toBe("log.step.v1");
+  expect(records[1].record_version).toBe("log.step.v1");
+  expect(records[0].message).toBe("First step");
+  expect(records[1].message).toBe("Second step");
+});

package/tools/test_results/generate-test-traceability.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+/**
+ * Generates test-traceability.json from Jest JSON output
+ * Mode: READ-ONLY / AUDIT-SAFE
+ */
+
+import fs from "fs";
+import path from "path";
+
+const RESULTS_PATH = path.resolve("evidence/test_results/test-results.json");
+const MAP_PATH = path.resolve("tools/test_results/test-case-map.json");
+const OUTPUT_PATH = path.resolve("evidence/test_results/test-traceability.json");
+
+if (!fs.existsSync(RESULTS_PATH)) {
+  throw new Error(`Missing Jest results: ${RESULTS_PATH}`);
+}
+if (!fs.existsSync(MAP_PATH)) {
+  throw new Error(`Missing test case map: ${MAP_PATH}`);
+}
+
+const jestResults = JSON.parse(fs.readFileSync(RESULTS_PATH, "utf8"));
+const testCaseMap = JSON.parse(fs.readFileSync(MAP_PATH, "utf8"));
+
+const executedTests = new Map();
+
+/**
+ * Collect per-test-file pass/fail
+ */
+for (const suite of jestResults.testResults || []) {
+  const file = path.basename(suite.name);
+  const status = suite.status === "passed" ? "PASS" : "FAIL";
+  executedTests.set(file, status);
+}
+
+const runId = new Date().toISOString();
+
+const traceability = {};
+
+for (const [tcId, files] of Object.entries(testCaseMap)) {
+  const statuses = files.map(f => executedTests.get(f) || "NOT_RUN");
+
+  let overall = "PASS";
+  if (statuses.includes("FAIL")) overall = "FAIL";
+  else if (statuses.includes("NOT_RUN")) overall = "INCOMPLETE";
+
+  traceability[tcId] = {
+    tests: files,
+    status: overall,
+    run_id: runId
+  };
+}
+
+fs.writeFileSync(
+  OUTPUT_PATH,
+  JSON.stringify(traceability, null, 2),
+  "utf8"
+);
+
+console.log(`✔ Test traceability written to ${OUTPUT_PATH}`);

package/tools/test_results/normalize-test-results.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+
+import fs from "fs";
+import path from "path";
+
+const RESULTS_PATH = path.resolve("evidence/test_results/test-results.json");
+
+if (!fs.existsSync(RESULTS_PATH)) {
+  console.error(`Missing test results: ${RESULTS_PATH}`);
+  process.exit(1);
+}
+
+const raw = fs.readFileSync(RESULTS_PATH, "utf8");
+let data;
+try {
+  data = JSON.parse(raw);
+} catch (e) {
+  console.error("Invalid JSON in test-results.json");
+  process.exit(2);
+}
+
+const numTotalTestSuites = data.numTotalTestSuites ?? 0;
+const numPassedTestSuites = data.numPassedTestSuites ?? 0;
+const numFailedTestSuites = data.numFailedTestSuites ?? 0;
+const numPendingTestSuites = data.numPendingTestSuites ?? 0;
+
+const numTotalTests = data.numTotalTests ?? 0;
+const numPassedTests = data.numPassedTests ?? 0;
+const numFailedTests = data.numFailedTests ?? 0;
+const numPendingTests = data.numPendingTests ?? 0;
+const numTodoTests = data.numTodoTests ?? 0;
+
+const overall_status = (numFailedTestSuites > 0 || numFailedTests > 0) ? "FAILED" : "PASSED";
+
+const summary = {
+  overall_status,
+  totals: {
+    test_suites: {
+      total: numTotalTestSuites,
+      passed: numPassedTestSuites,
+      failed: numFailedTestSuites,
+      pending: numPendingTestSuites,
+    },
+    tests: {
+      total: numTotalTests,
+      passed: numPassedTests,
+      failed: numFailedTests,
+      pending: numPendingTests,
+      todo: numTodoTests,
+    },
+  },
+};
+
+data.summary = summary;
+
+fs.writeFileSync(RESULTS_PATH, JSON.stringify(data, null, 2) + "\n", "utf8");
+console.log(`✔ Normalized and updated ${RESULTS_PATH}`);

package/tools/test_results/run-tests-then-prebuild.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+
+function run(cmd) {
+  console.log(`→ ${cmd}`);
+  execSync(cmd, { stdio: "inherit", shell: true });
+}
+
+/* -----------------------------
+ * Paths
+ * --------------------------- */
+const STRUCTURE_AUDIT =
+  "evidence/validators/validate-repo-structure/repo-structure-audit.json";
+
+const TEST_RESULTS_DIR = "evidence/test_results";
+const TEST_RESULTS = `${TEST_RESULTS_DIR}/test-results.json`;
+
+/* -----------------------------
+ * Pipeline
+ * --------------------------- */
+try {
+  /* 0. Run repo-structure validator */
+  run("node validators/bootstrap/validate-repo-structure.ts --root .");
+
+  if (!fs.existsSync(STRUCTURE_AUDIT)) {
+    console.error("✖ Missing repo-structure-audit.json");
+    process.exit(2);
+  }
+
+  const structureAudit = JSON.parse(
+    fs.readFileSync(STRUCTURE_AUDIT, "utf8")
+  );
+  const summary = structureAudit?.summary;
+  const riskLevel = summary?.risk_level;
+
+  if (!summary || summary.overall_status !== "COMPLIANT") {
+    console.error(
+      "✖ Repo structure validation not COMPLIANT. Aborting."
+    );
+    process.exit(3);
+  }
+
+  if (riskLevel !== "LOW") {
+    console.error(
+      `✖ Repo structure risk_level=${riskLevel ?? "UNKNOWN"}. Aborting.`
+    );
+    process.exit(3);
+  }
+
+  console.log("✔ Repo structure validation PASSED (risk_level=LOW)");
+
+  /* 1. Ensure test evidence directory exists */
+  fs.mkdirSync(TEST_RESULTS_DIR, { recursive: true });
+
+  /* 2. Run tests */
+  run(
+    `npx vitest run --reporter=json --silent > ${TEST_RESULTS}`
+  );
+
+  if (!fs.existsSync(TEST_RESULTS)) {
+    console.error("✖ Missing test-results.json");
+    process.exit(4);
+  }
+
+  const testResults = JSON.parse(
+    fs.readFileSync(TEST_RESULTS, "utf8")
+  );
+
+  if (testResults.success !== true) {
+    console.error("✖ Tests did not pass (success=false).");
+    process.exit(5);
+  }
+
+  console.log("✔ Tests passed (success=true)");
+
+  /* 3. Normalize + traceability */
+  run("node tools/test_results/normalize-test-results.js");
+  run("node tools/test_results/generate-test-traceability.js");
+
+  /* 4. Run prebuild if defined */
+  let hasPrebuild = false;
+  try {
+    const pkg = JSON.parse(fs.readFileSync("package.json", "utf8"));
+    hasPrebuild = !!pkg?.scripts?.prebuild;
+  } catch {
+    console.warn("⚠ Unable to read package.json; skipping prebuild.");
+  }
+
+  if (hasPrebuild) {
+    run("npm run prebuild");
+    console.log("✔ Prebuild completed successfully");
+  } else {
+    console.log("ℹ No prebuild script found; skipping prebuild.");
+  }
+
+  console.log("✔ VERIFY → TEST → PREBUILD pipeline completed successfully");
+} catch (err) {
+  console.error("✖ Pipeline failed");
+  process.exit(1);
+}

package/tools/test_results/test-case-map.json

@@ -0,0 +1,9 @@
+{
+  "TC-SEQ-001": ["sequence_monotonic.test.ts"],
+  "TC-CLK-001": ["sequence_monotonic.test.ts"],
+  "TC-REC-001": ["record_builder.test.ts", "step1_compliance.test.ts"],
+  "TC-FAN-001": ["fanout.test.ts"],
+  "TC-SPL-001": ["fanout_spool.test.ts"],
+  "TC-MSG-001": ["message_constraints.test.ts"],
+  "TC-SNK-001": ["sinks_file_ndjson.test.ts"]
+}

package/tsconfig.json

@@ -0,0 +1,31 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "Node",
+    "strict": true,
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "noEmitOnError": true,
+    "types": [
+      "node"
+    ],
+    "lib": [
+      "ES2022"
+    ]
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "**/*.js"
+  ]
+}