@fuaran-ui/conformance 0.1.0

package/dist/cli.js

@@ -0,0 +1,612 @@
+#!/usr/bin/env node
+import { writeFileSync, readFileSync } from 'fs';
+import { resolve, join } from 'path';
+import { pathToFileURL, fileURLToPath } from 'url';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import { createHash } from 'crypto';
+
+// src/report.ts
+var computeVerdict = (legs) => {
+  if (legs.some((l) => l.status === "fail")) return "non-conformant";
+  if (legs.some((l) => l.mandatory && l.status === "skipped")) return "partially-conformant";
+  return "conformant";
+};
+var statusGlyph = { pass: "\u2713", fail: "\u2717", skipped: "\u2013" };
+var formatReport = (report2) => {
+  const lines = [];
+  const impl = report2.implementation.version === void 0 ? report2.implementation.name : `${report2.implementation.name} ${report2.implementation.version}`;
+  lines.push(`Fuaran wire-format conformance report`);
+  lines.push(`  kit            ${report2.kit.name}@${report2.kit.version}`);
+  lines.push(`  implementation ${impl}`);
+  lines.push(
+    `  corpus         v${report2.corpus.manifestVersion} (${report2.corpus.fixtureCount} fixtures, ${report2.corpus.source})`
+  );
+  lines.push(`  corpus digest  sha256:${report2.corpus.digest}`);
+  lines.push(`  generated      ${report2.generatedAt}`);
+  lines.push("");
+  for (const leg of report2.legs) {
+    const tier = leg.mandatory ? "mandatory" : "optional ";
+    const counts = leg.status === "skipped" ? leg.skipReason ?? "skipped" : `${leg.fixturesPassed}/${leg.fixturesTotal}`;
+    lines.push(`  ${statusGlyph[leg.status]} ${leg.leg.padEnd(20)} ${tier}  ${counts}`);
+    for (const f of leg.failures) {
+      lines.push(`      ${f.fixtureId}: ${f.summary}`);
+      if (f.detail !== void 0)
+        for (const detailLine of f.detail.split("\n")) lines.push(`        ${detailLine}`);
+    }
+  }
+  lines.push("");
+  lines.push(`  verdict: ${report2.verdict.toUpperCase()}`);
+  if (report2.verdict === "partially-conformant") {
+    const skipped = report2.legs.filter((l) => l.mandatory && l.status === "skipped").map((l) => l.leg);
+    lines.push(`  (mandatory legs not attempted: ${skipped.join(", ")})`);
+  }
+  lines.push(
+    `  Certification is per corpus version \u2014 re-certify when the corpus advances (WIRE_FORMAT.md \xA711).`
+  );
+  return lines.join("\n");
+};
+var bundledRoot = () => (
+  // dist/index.js → ../corpus (tsup `shims: true` provides import.meta.url under CJS).
+  fileURLToPath(new URL("../corpus/", import.meta.url))
+);
+var loadCorpus = (options) => {
+  const external = options?.corpusRoot;
+  const root = external ?? bundledRoot();
+  const read = (relPath) => readFileSync(join(root, relPath), "utf8");
+  const manifestText = read("manifest.json");
+  const manifest = JSON.parse(manifestText);
+  const hash = createHash("sha256");
+  hash.update(manifestText);
+  hash.update(read(manifest.schema));
+  for (const f of manifest.fixtures) {
+    hash.update(read(f.inputFile));
+    if (f.expectedFile !== void 0 && f.expectedFile !== f.inputFile)
+      hash.update(read(f.expectedFile));
+  }
+  return {
+    root,
+    source: external === void 0 ? "bundled" : "external",
+    manifestVersion: manifest.version,
+    fixtures: manifest.fixtures,
+    digest: hash.digest("hex"),
+    schema: JSON.parse(read(manifest.schema)),
+    read
+  };
+};
+
+// src/run.ts
+var KIT_NAME = "@fuaran-ui/conformance";
+var KIT_VERSION = "0.1.0";
+var canon = (s) => s.replace(/\r?\n$/, "");
+var firstDiff = (expected, actual) => {
+  const n = Math.min(expected.length, actual.length);
+  let i = 0;
+  while (i < n && expected[i] === actual[i]) i++;
+  const from = Math.max(0, i - 30);
+  const win = (s) => JSON.stringify(s.slice(from, i + 30));
+  return `byte offset ${i} (length canonical=${expected.length}, host=${actual.length})
+  canonical \u2026${win(expected)}\u2026
+  host      \u2026${win(actual)}\u2026`;
+};
+var messageOf = (err) => err instanceof Error ? err.message : String(err);
+var newAcc = () => ({ total: 0, passed: 0, failures: [] });
+var toLeg = (leg, mandatory, acc, skipReason) => acc === void 0 ? {
+  leg,
+  mandatory,
+  status: "skipped",
+  ...skipReason === void 0 ? {} : { skipReason },
+  fixturesTotal: 0,
+  fixturesPassed: 0,
+  failures: []
+} : {
+  leg,
+  mandatory,
+  status: acc.failures.length === 0 ? "pass" : "fail",
+  fixturesTotal: acc.total,
+  fixturesPassed: acc.passed,
+  failures: acc.failures
+};
+var runConformance = (adapter2, options) => {
+  const corpus = loadCorpus(
+    options.corpusRoot === void 0 ? void 0 : { corpusRoot: options.corpusRoot }
+  );
+  const ajv = new Ajv2020({ strict: false, allErrors: true });
+  const schemaValid = ajv.compile(corpus.schema);
+  const accepts = (decoder) => corpus.fixtures.filter(
+    (f) => f.decoder === decoder && (f.kind === "node-round-trip" || f.kind === "op-round-trip")
+  );
+  const rejects = (decoder) => corpus.fixtures.filter((f) => f.decoder === decoder && f.kind === "reject");
+  const lenients = (decoder) => corpus.fixtures.filter((f) => f.decoder === decoder && f.kind === "lenient-accept");
+  const accs = /* @__PURE__ */ new Map();
+  const acc = (leg) => {
+    let a = accs.get(leg);
+    if (a === void 0) {
+      a = newAcc();
+      accs.set(leg, a);
+    }
+    return a;
+  };
+  const runSide = (decoder, decode, encode) => {
+    const decodeLeg = decoder === "node" ? "node-decode" : "op-decode";
+    const byteLeg = decoder === "node" ? "node-byte-identity" : "op-byte-identity";
+    const rejectLeg = decoder === "node" ? "node-reject" : "op-reject";
+    if (decode === void 0) return;
+    for (const f of accepts(decoder)) {
+      const input = corpus.read(f.inputFile);
+      const d = acc(decodeLeg);
+      d.total++;
+      let decoded;
+      try {
+        decoded = decode(input);
+      } catch (err) {
+        d.failures.push({
+          fixtureId: f.id,
+          summary: "decoder THREW on an accept fixture (a conformant decoder never throws)",
+          detail: messageOf(err)
+        });
+        continue;
+      }
+      if (!decoded.ok) {
+        d.failures.push({
+          fixtureId: f.id,
+          summary: "decoder rejected an accept fixture",
+          detail: `${decoded.error.code} at ${decoded.error.path}${decoded.error.message === void 0 ? "" : ` \u2014 ${decoded.error.message}`}`
+        });
+        continue;
+      }
+      d.passed++;
+      if (encode === void 0) continue;
+      const b = acc(byteLeg);
+      b.total++;
+      const expected = canon(corpus.read(f.expectedFile ?? f.inputFile));
+      let actual;
+      try {
+        actual = encode(decoded.value);
+      } catch (err) {
+        b.failures.push({
+          fixtureId: f.id,
+          summary: "encoder THREW re-encoding a decoded accept fixture",
+          detail: messageOf(err)
+        });
+        continue;
+      }
+      if (actual !== expected) {
+        b.failures.push({
+          fixtureId: f.id,
+          summary: "encoder output diverges from the canonical form",
+          detail: firstDiff(expected, actual)
+        });
+        continue;
+      }
+      b.passed++;
+      const s = acc("schema-validation");
+      s.total++;
+      if (schemaValid(JSON.parse(actual))) {
+        s.passed++;
+      } else {
+        s.failures.push({
+          fixtureId: f.id,
+          summary: "encoder output fails the canonical JSON Schema (schema.json)",
+          detail: (schemaValid.errors ?? []).map((e) => `${e.instancePath === "" ? "$" : e.instancePath} ${e.message ?? ""}`).join("\n")
+        });
+      }
+    }
+    if (encode !== void 0) {
+      for (const f of lenients(decoder)) {
+        const input = corpus.read(f.inputFile);
+        const l = acc("lenient-accept");
+        l.total++;
+        let decoded;
+        try {
+          decoded = decode(input);
+        } catch (err) {
+          l.failures.push({
+            fixtureId: f.id,
+            summary: "decoder THREW on a \xA716 shorthand (a conformant decoder accepts it)",
+            detail: messageOf(err)
+          });
+          continue;
+        }
+        if (!decoded.ok) {
+          l.failures.push({
+            fixtureId: f.id,
+            summary: "decoder rejected a \xA716 shorthand (MUST accept \u2014 WIRE_FORMAT \xA716)",
+            detail: `${decoded.error.code} at ${decoded.error.path}${decoded.error.message === void 0 ? "" : ` \u2014 ${decoded.error.message}`}`
+          });
+          continue;
+        }
+        let actual;
+        try {
+          actual = encode(decoded.value);
+        } catch (err) {
+          l.failures.push({
+            fixtureId: f.id,
+            summary: "encoder THREW re-encoding a decoded \xA716 shorthand",
+            detail: messageOf(err)
+          });
+          continue;
+        }
+        const expected = canon(corpus.read(f.expectedFile ?? f.inputFile));
+        if (actual !== expected) {
+          l.failures.push({
+            fixtureId: f.id,
+            summary: "shorthand normalisation diverges from the verbose canonical form",
+            detail: firstDiff(expected, actual)
+          });
+          continue;
+        }
+        l.passed++;
+      }
+    }
+    for (const f of rejects(decoder)) {
+      const input = corpus.read(f.inputFile);
+      const r = acc(rejectLeg);
+      r.total++;
+      let decoded;
+      try {
+        decoded = decode(input);
+      } catch (err) {
+        r.failures.push({
+          fixtureId: f.id,
+          summary: "decoder THREW on a reject fixture (must return a structured error)",
+          detail: messageOf(err)
+        });
+        continue;
+      }
+      if (decoded.ok) {
+        r.failures.push({
+          fixtureId: f.id,
+          summary: "decoder ACCEPTED a reject fixture",
+          detail: `expected ${f.expectedErrorCode} at ${f.expectedPath}`
+        });
+        continue;
+      }
+      if (decoded.error.code !== f.expectedErrorCode) {
+        r.failures.push({
+          fixtureId: f.id,
+          summary: "decode-error CODE diverges from the canonical error",
+          detail: `expected ${f.expectedErrorCode}, got ${decoded.error.code} (path ${decoded.error.path})`
+        });
+        continue;
+      }
+      if (!decoded.error.path.startsWith(f.expectedPath ?? "$")) {
+        r.failures.push({
+          fixtureId: f.id,
+          summary: "decode-error PATH diverges from the canonical error",
+          detail: `expected prefix ${f.expectedPath}, got ${decoded.error.path} (code ${decoded.error.code})`
+        });
+        continue;
+      }
+      r.passed++;
+    }
+  };
+  runSide("node", adapter2.decodeNode, adapter2.encodeNode);
+  runSide("op", adapter2.decodeOp, adapter2.encodeOp);
+  const negotiateEnvelope = adapter2.negotiateEnvelope;
+  if (negotiateEnvelope !== void 0) {
+    const byKind = (kind) => corpus.fixtures.filter((f) => f.kind === kind);
+    for (const f of byKind("envelope-round-trip")) {
+      const a = acc("envelope-round-trip");
+      a.total++;
+      const input = corpus.read(f.inputFile);
+      let r;
+      try {
+        r = negotiateEnvelope(input);
+      } catch (err) {
+        a.failures.push({
+          fixtureId: f.id,
+          summary: "negotiateEnvelope THREW on a round-trip fixture (must return a structured result)",
+          detail: messageOf(err)
+        });
+        continue;
+      }
+      if (!r.ok) {
+        a.failures.push({
+          fixtureId: f.id,
+          summary: "negotiateEnvelope refused a round-trip fixture (Current/Behind must be tolerated)",
+          detail: `${r.error.code} at ${r.error.path}`
+        });
+        continue;
+      }
+      const expected = canon(corpus.read(f.expectedFile ?? f.inputFile));
+      if (typeof r.value !== "string" || r.value !== expected) {
+        a.failures.push({
+          fixtureId: f.id,
+          summary: "envelope re-encode diverges from the canonical form (must-ignore-but-preserve)",
+          detail: typeof r.value === "string" ? firstDiff(expected, r.value) : "value was not a string"
+        });
+        continue;
+      }
+      a.passed++;
+    }
+    for (const f of byKind("envelope-reject")) {
+      const a = acc("envelope-reject");
+      a.total++;
+      const input = corpus.read(f.inputFile);
+      let r;
+      try {
+        r = negotiateEnvelope(input);
+      } catch (err) {
+        a.failures.push({
+          fixtureId: f.id,
+          summary: "negotiateEnvelope THREW on a reject fixture (must return a structured error)",
+          detail: messageOf(err)
+        });
+        continue;
+      }
+      if (r.ok) {
+        a.failures.push({
+          fixtureId: f.id,
+          summary: "negotiateEnvelope ACCEPTED a Foreign artifact (must hard-refuse)",
+          detail: `expected ${f.expectedErrorCode} at ${f.expectedPath}`
+        });
+        continue;
+      }
+      if (r.error.code !== f.expectedErrorCode) {
+        a.failures.push({
+          fixtureId: f.id,
+          summary: "refusal CODE diverges from the canonical error",
+          detail: `expected ${f.expectedErrorCode}, got ${r.error.code} (path ${r.error.path})`
+        });
+        continue;
+      }
+      if (!r.error.path.startsWith(f.expectedPath ?? "$")) {
+        a.failures.push({
+          fixtureId: f.id,
+          summary: "refusal PATH diverges from the canonical error",
+          detail: `expected prefix ${f.expectedPath}, got ${r.error.path}`
+        });
+        continue;
+      }
+      a.passed++;
+    }
+  }
+  const roundTripElicitation = adapter2.roundTripElicitation;
+  if (roundTripElicitation !== void 0) {
+    const elDecoder = (f) => f.decoder === "elicitation-outcome" ? "elicitation-outcome" : "elicitation";
+    for (const f of corpus.fixtures.filter((x) => x.kind === "elicitation-round-trip")) {
+      const a = acc("elicitation-round-trip");
+      a.total++;
+      const input = corpus.read(f.inputFile);
+      let r;
+      try {
+        r = roundTripElicitation(elDecoder(f), input);
+      } catch (err) {
+        a.failures.push({
+          fixtureId: f.id,
+          summary: "roundTripElicitation THREW on a round-trip fixture (must return a structured result)",
+          detail: messageOf(err)
+        });
+        continue;
+      }
+      if (!r.ok) {
+        a.failures.push({
+          fixtureId: f.id,
+          summary: "roundTripElicitation refused a round-trip fixture",
+          detail: `${r.error.code} at ${r.error.path}`
+        });
+        continue;
+      }
+      const expected = canon(corpus.read(f.expectedFile ?? f.inputFile));
+      if (typeof r.value !== "string" || r.value !== expected) {
+        a.failures.push({
+          fixtureId: f.id,
+          summary: "elicitation re-encode diverges from the canonical form",
+          detail: typeof r.value === "string" ? firstDiff(expected, r.value) : "value was not a string"
+        });
+        continue;
+      }
+      a.passed++;
+    }
+    for (const f of corpus.fixtures.filter((x) => x.kind === "elicitation-reject")) {
+      const a = acc("elicitation-reject");
+      a.total++;
+      const input = corpus.read(f.inputFile);
+      let r;
+      try {
+        r = roundTripElicitation(elDecoder(f), input);
+      } catch (err) {
+        a.failures.push({
+          fixtureId: f.id,
+          summary: "roundTripElicitation THREW on a reject fixture (must return a structured error)",
+          detail: messageOf(err)
+        });
+        continue;
+      }
+      if (r.ok) {
+        a.failures.push({
+          fixtureId: f.id,
+          summary: "roundTripElicitation ACCEPTED a reject fixture",
+          detail: `expected ${f.expectedErrorCode} at ${f.expectedPath}`
+        });
+        continue;
+      }
+      if (r.error.code !== f.expectedErrorCode) {
+        a.failures.push({
+          fixtureId: f.id,
+          summary: "refusal CODE diverges from the canonical error",
+          detail: `expected ${f.expectedErrorCode}, got ${r.error.code} (path ${r.error.path})`
+        });
+        continue;
+      }
+      if (!r.error.path.startsWith(f.expectedPath ?? "$")) {
+        a.failures.push({
+          fixtureId: f.id,
+          summary: "refusal PATH diverges from the canonical error",
+          detail: `expected prefix ${f.expectedPath}, got ${r.error.path}`
+        });
+        continue;
+      }
+      a.passed++;
+    }
+  }
+  const validateAnswerDocument = adapter2.validateAnswerDocument;
+  if (validateAnswerDocument !== void 0) {
+    for (const f of corpus.fixtures.filter(
+      (x) => x.kind === "elicitation-answer-accept" || x.kind === "elicitation-answer-reject"
+    )) {
+      const a = acc("elicitation-answer");
+      a.total++;
+      const input = corpus.read(f.inputFile);
+      let r;
+      try {
+        r = validateAnswerDocument(input);
+      } catch (err) {
+        a.failures.push({
+          fixtureId: f.id,
+          summary: "validateAnswerDocument THREW (must return a structured result)",
+          detail: messageOf(err)
+        });
+        continue;
+      }
+      if (f.kind === "elicitation-answer-accept") {
+        if (!r.ok) {
+          a.failures.push({
+            fixtureId: f.id,
+            summary: "validateAnswerDocument refused a conforming answer",
+            detail: `${r.error.code} at ${r.error.path}`
+          });
+          continue;
+        }
+        a.passed++;
+        continue;
+      }
+      if (r.ok) {
+        a.failures.push({
+          fixtureId: f.id,
+          summary: "validateAnswerDocument ACCEPTED a nonconforming answer",
+          detail: `expected ${f.expectedErrorCode} at ${f.expectedPath}`
+        });
+        continue;
+      }
+      if (r.error.code !== f.expectedErrorCode) {
+        a.failures.push({
+          fixtureId: f.id,
+          summary: "refusal CODE diverges from the canonical error",
+          detail: `expected ${f.expectedErrorCode}, got ${r.error.code} (path ${r.error.path})`
+        });
+        continue;
+      }
+      if (!r.error.path.startsWith(f.expectedPath ?? "$")) {
+        a.failures.push({
+          fixtureId: f.id,
+          summary: "refusal PATH diverges from the canonical error",
+          detail: `expected prefix ${f.expectedPath}, got ${r.error.path}`
+        });
+        continue;
+      }
+      a.passed++;
+    }
+  }
+  const need = (hooks) => `adapter does not provide ${hooks.join(" + ")}`;
+  const hasSchemaInput = adapter2.encodeNode !== void 0 || adapter2.encodeOp !== void 0;
+  const legs = [
+    toLeg("node-decode", true, accs.get("node-decode"), need(["decodeNode"])),
+    toLeg(
+      "node-byte-identity",
+      true,
+      accs.get("node-byte-identity"),
+      need(["decodeNode", "encodeNode"])
+    ),
+    toLeg("node-reject", true, accs.get("node-reject"), need(["decodeNode"])),
+    toLeg("op-decode", true, accs.get("op-decode"), need(["decodeOp"])),
+    toLeg("op-byte-identity", true, accs.get("op-byte-identity"), need(["decodeOp", "encodeOp"])),
+    toLeg("op-reject", true, accs.get("op-reject"), need(["decodeOp"])),
+    toLeg(
+      "lenient-accept",
+      true,
+      accs.get("lenient-accept"),
+      need(["a decode + encode hook pair (node and/or op)"])
+    ),
+    toLeg(
+      "envelope-round-trip",
+      true,
+      accs.get("envelope-round-trip"),
+      need(["negotiateEnvelope"])
+    ),
+    toLeg("envelope-reject", true, accs.get("envelope-reject"), need(["negotiateEnvelope"])),
+    toLeg(
+      "elicitation-round-trip",
+      true,
+      accs.get("elicitation-round-trip"),
+      need(["roundTripElicitation"])
+    ),
+    toLeg(
+      "elicitation-reject",
+      true,
+      accs.get("elicitation-reject"),
+      need(["roundTripElicitation"])
+    ),
+    toLeg(
+      "elicitation-answer",
+      true,
+      accs.get("elicitation-answer"),
+      need(["validateAnswerDocument"])
+    ),
+    toLeg(
+      "schema-validation",
+      true,
+      accs.get("schema-validation"),
+      hasSchemaInput ? need(["a decode hook for the encode hooks provided"]) : need(["encodeNode and/or encodeOp"])
+    ),
+    toLeg("apply", false, void 0, "corpus v1 ships no apply fixtures \u2014 leg reserved")
+  ];
+  return {
+    kit: { name: KIT_NAME, version: KIT_VERSION },
+    implementation: options.implementation,
+    corpus: {
+      manifestVersion: corpus.manifestVersion,
+      digest: corpus.digest,
+      fixtureCount: corpus.fixtures.length,
+      source: corpus.source
+    },
+    legs,
+    verdict: computeVerdict(legs),
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+};
+
+// src/cli.ts
+var usage = () => {
+  console.error(
+    "Usage: fuaran-conformance <adapter-module> [--corpus <dir>] [--json <file>]\n\n  <adapter-module>  module exporting `adapter` (decode/encode hooks) and\n                    `implementation` ({ name, version? })\n  --corpus <dir>    certify against an external corpus checkout instead of\n                    the snapshot bundled with this package\n  --json <file>     also write the structured report as JSON\n"
+  );
+  process.exit(1);
+};
+var args = process.argv.slice(2);
+var modulePath;
+var corpusRoot;
+var jsonOut;
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (arg === "--corpus") corpusRoot = args[++i] ?? usage();
+  else if (arg === "--json") jsonOut = args[++i] ?? usage();
+  else if (modulePath === void 0 && arg !== void 0 && !arg.startsWith("--")) {
+    modulePath = arg;
+  } else usage();
+}
+if (modulePath === void 0) usage();
+var loaded = await import(pathToFileURL(resolve(modulePath)).href);
+var adapter = loaded.adapter ?? loaded.default?.adapter;
+var implementation = loaded.implementation ?? loaded.default?.implementation;
+if (adapter === void 0 || implementation === void 0) {
+  console.error(
+    `The adapter module must export \`adapter\` and \`implementation\` (named or on the default export). Loaded: ${modulePath}`
+  );
+  process.exit(1);
+}
+var report = runConformance(adapter, {
+  implementation,
+  ...corpusRoot === void 0 ? {} : { corpusRoot }
+});
+console.log(formatReport(report));
+if (jsonOut !== void 0) {
+  writeFileSync(jsonOut, JSON.stringify(report, null, 2) + "\n", "utf8");
+  console.log(`
+Structured report written to ${jsonOut}`);
+}
+process.exit(
+  report.verdict === "conformant" ? 0 : report.verdict === "partially-conformant" ? 2 : 1
+);
+//# sourceMappingURL=cli.js.map
+//# sourceMappingURL=cli.js.map