dsh-plugin-compat-check 0.1.4 → 0.1.6

package/kernel/lib/author-ci-output.mjs

@@ -0,0 +1,188 @@
+/** Standard CI serializers; outputs describe a static gate, never business acceptance. */
+const relativeLocation = (location) => {
+  if (
+    !location ||
+    typeof location.file !== "string" ||
+    !Number.isSafeInteger(location.line) ||
+    location.line < 1
+  )
+    return null;
+  const file = location.file.replace(/\\/g, "/");
+  if (
+    file.startsWith("/") ||
+    /^[A-Za-z][A-Za-z\d+.-]*:/.test(file) ||
+    file.split("/").some((x) => x === ".." || x === "")
+  )
+    return null;
+  return {
+    uri: file.split("/").map(encodeURIComponent).join("/"),
+    line: location.line,
+    column: location.column,
+  };
+};
+const evidence = (m, c, p, f) => ({
+  dshVersion: c.dshVersion,
+  pluginName: p,
+  severity: f.severity,
+  certainty: f.certainty,
+  impactBasis: f.impactBasis,
+  impact: f.impact,
+  basis: f.basis,
+  identity: c.identity,
+  limitations: m.limitations,
+});
+export function renderSarif(matrix) {
+  const results = [],
+    notifications = [];
+  for (const c of matrix.cells || []) {
+    if (c.status !== "analyzed") {
+      notifications.push({
+        level: "error",
+        message: { text: c.error || c.status },
+        properties: { dshVersion: c.dshVersion, status: c.status },
+      });
+      continue;
+    }
+    for (const [name, p] of Object.entries(c.report.plugins))
+      for (const f of p.findings) {
+        const l = relativeLocation(f.location),
+          result = {
+            ruleId: f.category,
+            level: f.severity === "fatal" ? "error" : "warning",
+            message: {
+              text: f.impact + " (" + f.certainty + "; " + f.basis + ")",
+            },
+            properties: evidence(matrix, c, name, f),
+          };
+        if (l)
+          result.locations = [
+            {
+              physicalLocation: {
+                artifactLocation: { uri: l.uri },
+                region: {
+                  startLine: l.line,
+                  ...(Number.isSafeInteger(l.column) && l.column >= 0
+                    ? { startColumn: l.column + 1 }
+                    : {}),
+                },
+              },
+            },
+          ];
+        results.push(result);
+      }
+  }
+  // Gate-only blocks (coverage, unknown, invalid previous) must survive export too.
+  for (const r of matrix.gate.reasons || [])
+    if (r.code !== "finding")
+      notifications.push({
+        level: matrix.gate.exitCode === 3 ? "error" : "warning",
+        message: { text: r.message },
+        properties: r,
+      });
+  return {
+    $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+    version: "2.1.0",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: "dsh-plugin-compat-check",
+            version: matrix.toolVersion,
+          },
+        },
+        invocations: [
+          {
+            executionSuccessful: matrix.gate.status !== "error",
+            exitCode: matrix.gate.exitCode,
+            toolExecutionNotifications: notifications,
+          },
+        ],
+        results,
+        properties: {
+          identity: matrix.identity,
+          policy: matrix.policy,
+          gate: matrix.gate,
+          limitations: matrix.limitations,
+          scope: "Static compatibility evidence; no business acceptance.",
+        },
+      },
+    ],
+  };
+}
+const xml = (value) =>
+  String(value ?? "")
+    .replace(
+      /[^\u0009\u000A\u000D\u0020-\uD7FF\uE000-\uFFFD\u{10000}-\u{10FFFF}]/gu,
+      "",
+    )
+    .replace(
+      /[&<>"']/g,
+      (c) =>
+        ({
+          "&": "&amp;",
+          "<": "&lt;",
+          ">": "&gt;",
+          '"': "&quot;",
+          "'": "&apos;",
+        })[c],
+    );
+export function renderJUnit(matrix) {
+  const cases = [];
+  for (const c of matrix.cells || []) {
+    const reasons = (matrix.gate.reasons || []).filter(
+        (r) => r.dshVersion === c.dshVersion,
+      ),
+      error =
+        c.status !== "analyzed" ||
+        (matrix.gate.exitCode === 3 && reasons.length > 0),
+      failure = !error && reasons.length > 0;
+    const body = {
+      dshVersion: c.dshVersion,
+      status: c.status,
+      error: c.error,
+      identity: c.identity,
+      kernelExitCode: c.kernelExitCode,
+      gateReasons: reasons,
+      plugins: c.report?.plugins,
+      limitations: matrix.limitations,
+      scope: "Static evidence; no business acceptance.",
+    };
+    const message = c.error || reasons.map((r) => r.message).join("; ");
+    cases.push({
+      error,
+      failure,
+      xml: `<testcase classname="author-ci" name="${xml(matrix.identity?.package?.name || "selected-package")} @ ${xml(c.dshVersion)}">${error ? `<error type="ToolError" message="${xml(message)}">${xml(message)}</error>` : failure ? `<failure type="PolicyGate" message="${xml(message)}">${xml(message)}</failure>` : ""}<system-out>${xml(JSON.stringify(body))}</system-out></testcase>`,
+    });
+  }
+  const global = (matrix.gate.reasons || []).filter((r) => !r.dshVersion);
+  if (global.length || cases.length === 0) {
+    const error = matrix.gate.exitCode === 3,
+      failure = !error && matrix.gate.exitCode !== 0,
+      message = global.map((r) => r.message).join("; ");
+    cases.push({
+      error,
+      failure,
+      xml: `<testcase classname="author-ci" name="matrix gate">${error ? `<error message="${xml(message)}"/>` : failure ? `<failure message="${xml(message)}"/>` : ""}</testcase>`,
+    });
+  }
+  const failures = cases.filter((c) => c.failure).length,
+    errors = cases.filter((c) => c.error).length;
+  const properties = {
+    toolVersion: matrix.toolVersion,
+    identity: matrix.identity,
+    policy: matrix.policy,
+    gate: matrix.gate,
+    limitations: matrix.limitations,
+    scope: "Static evidence; no business acceptance.",
+  };
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<testsuites tests="${cases.length}" failures="${failures}" errors="${errors}"><testsuite name="author-ci" tests="${cases.length}" failures="${failures}" errors="${errors}" skipped="0"><properties>${Object.entries(
+    properties,
+  )
+    .map(
+      ([name, value]) =>
+        `<property name="${xml(name)}" value="${xml(typeof value === "string" ? value : JSON.stringify(value))}"/>`,
+    )
+    .join(
+      "",
+    )}</properties>${cases.map((c) => c.xml).join("")}</testsuite></testsuites>\n`;
+}

package/kernel/lib/author-ci-policy.mjs

@@ -0,0 +1,285 @@
+/** Pure author CI gate. Kernel reports remain unchanged and independently useful. */
+import { assertReportBody, CATALOG_REFERENCES } from "./contracts.mjs";
+const severities = ["fatal", "feature-dead", "degraded"];
+const certainties = ["certain", "suspected"];
+export const DEFAULT_POLICY = Object.freeze({
+  schemaVersion: 1,
+  mode: "all",
+  severities: Object.freeze([...severities]),
+  certainties: Object.freeze([...certainties]),
+  requireCompleteCoverage: true,
+  allowVacuous: false,
+});
+const record = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const hash = (v) => typeof v === "string" && /^[a-f0-9]{64}$/.test(v);
+const samePackage = (a, b) =>
+  a?.name === b?.name && a?.version === b?.version && a?.sha256 === b?.sha256;
+const text = (v) => typeof v === "string" && v.length > 0;
+const need = (condition, message) => {
+  if (!condition) throw Error(message);
+};
+export function validatePolicy(policy) {
+  need(record(policy), "Policy must be an object");
+  need(
+    Object.keys(policy).length === Object.keys(DEFAULT_POLICY).length &&
+      Object.keys(policy).every((k) => Object.hasOwn(DEFAULT_POLICY, k)),
+    "Policy has missing or unknown fields",
+  );
+  need(
+    policy.schemaVersion === 1 && ["all", "new"].includes(policy.mode),
+    "Invalid policy schemaVersion or mode",
+  );
+  for (const [key, allowed] of [
+    ["severities", severities],
+    ["certainties", certainties],
+  ])
+    need(
+      Array.isArray(policy[key]) &&
+        policy[key].every((v) => allowed.includes(v)) &&
+        new Set(policy[key]).size === policy[key].length,
+      "Invalid policy " + key,
+    );
+  need(
+    typeof policy.requireCompleteCoverage === "boolean" &&
+      typeof policy.allowVacuous === "boolean",
+    "Invalid policy coverage flags",
+  );
+  return policy;
+}
+function validIdentity(i) {
+  return (
+    record(i) &&
+    record(i.package) &&
+    text(i.package.name) &&
+    text(i.package.version) &&
+    hash(i.package.sha256) &&
+    hash(i.rulesSha256) &&
+    hash(i.catalogSha256) &&
+    text(i.toolVersion)
+  );
+}
+function validateCells(cells, { baseline = false } = {}) {
+  need(
+    Array.isArray(cells) && cells.length > 0,
+    "Matrix requires at least one version cell",
+  );
+  const seen = new Set();
+  let first;
+  for (const c of cells) {
+    need(
+      record(c) && text(c.dshVersion) && !seen.has(c.dshVersion),
+      "Missing or duplicate matrix version",
+    );
+    seen.add(c.dshVersion);
+    need(
+      ["analyzed", "unsupported", "error"].includes(c.status),
+      "Invalid matrix cell status",
+    );
+    if (c.status !== "analyzed") {
+      need(!baseline, "Previous matrix contains unavailable evidence");
+      need(c.report === null && text(c.error), "Invalid failed cell");
+      continue;
+    }
+    need(
+      c.error === null && validIdentity(c.identity),
+      "Invalid analyzed cell identity",
+    );
+    assertReportBody(c.report);
+    need(
+      c.kernelExitCode === c.report.exitCode,
+      "Cell kernel exit code mismatch",
+    );
+    const r = c.report,
+      i = c.identity,
+      cat = CATALOG_REFERENCES.find((x) => x.version === c.dshVersion);
+    need(
+      r.ok === true &&
+        r.dshVersion === c.dshVersion &&
+        r.toolVersion === i.toolVersion,
+      "Cell report identity mismatch",
+    );
+    need(
+      cat &&
+        i.catalogSha256 === cat.sha256 &&
+        r.catalog?.verified === true &&
+        r.catalog.sha256 === i.catalogSha256,
+      "Cell catalogue identity mismatch",
+    );
+    need(
+      Object.keys(r.plugins).length === 1 &&
+        r.plugins[i.package.name]?.version === i.package.version,
+      "Selected package/report mismatch",
+    );
+    if (first)
+      need(
+        samePackage(i.package, first.package) &&
+          i.rulesSha256 === first.rulesSha256 &&
+          i.toolVersion === first.toolVersion,
+        "Cross-cell identity mismatch",
+      );
+    else first = i;
+  }
+}
+function validatePrevious(previous, cells) {
+  need(
+    record(previous) &&
+      previous.schemaVersion === 1 &&
+      previous.kind === "plugin-compat-check/author-ci",
+    "Previous matrix schema mismatch",
+  );
+  validatePolicy(previous.policy);
+  validateCells(previous.cells, { baseline: true });
+  const current = cells.filter((c) => c.status === "analyzed");
+  need(
+    current.length === cells.length,
+    "Current matrix contains unavailable evidence",
+  );
+  need(
+    previous.cells.length === cells.length,
+    "Previous version matrix differs",
+  );
+  need(
+    record(previous.identity) && record(previous.identity.package),
+    "Previous matrix identity missing",
+  );
+  const head = previous.cells[0].identity;
+  need(
+    previous.toolVersion === head.toolVersion &&
+      samePackage(previous.identity.package, head.package) &&
+      previous.identity.rulesSha256 === head.rulesSha256,
+    "Previous matrix identity mismatch",
+  );
+  for (const c of current) {
+    const p = previous.cells.find((x) => x.dshVersion === c.dshVersion);
+    need(
+      p &&
+        p.identity.package.name === c.identity.package.name &&
+        p.identity.toolVersion === c.identity.toolVersion &&
+        p.identity.rulesSha256 === c.identity.rulesSha256 &&
+        p.identity.catalogSha256 === c.identity.catalogSha256,
+      "Previous evidence is not comparable",
+    );
+  }
+}
+function findingKey(f) {
+  return JSON.stringify([
+    f.category,
+    f.service ?? null,
+    f.method ?? null,
+    f.location?.file ?? null,
+    f.location?.line ?? null,
+    f.location?.column ?? null,
+    f.severity,
+    f.certainty,
+  ]);
+}
+export function evaluateMatrix(
+  cells,
+  policy = DEFAULT_POLICY,
+  previous = null,
+) {
+  const reasons = [],
+    counts = {
+      cells: Array.isArray(cells) ? cells.length : 0,
+      analyzed: 0,
+      findings: 0,
+      matched: 0,
+      suppressed: 0,
+      errors: 0,
+    };
+  const finish = (exitCode) => ({
+    status: exitCode === 0 ? "pass" : exitCode === 3 ? "error" : "blocked",
+    exitCode,
+    reasons,
+    counts,
+  });
+  try {
+    validatePolicy(policy);
+    validateCells(cells);
+    if (policy.mode === "new") validatePrevious(previous, cells);
+  } catch (error) {
+    reasons.push({
+      dshVersion: null,
+      code: "invalid-evidence",
+      message: error.message,
+    });
+    counts.errors++;
+    return finish(3);
+  }
+  let fatal = false,
+    risk = false,
+    tool = false;
+  for (const c of cells) {
+    if (c.status !== "analyzed") {
+      tool = true;
+      counts.errors++;
+      reasons.push({
+        dshVersion: c.dshVersion,
+        code: c.status === "unsupported" ? "unsupported-version" : "cell-error",
+        message: c.error,
+      });
+      continue;
+    }
+    counts.analyzed++;
+    const add = (code, message, pluginName) => {
+      risk = true;
+      reasons.push({
+        dshVersion: c.dshVersion,
+        ...(pluginName ? { pluginName } : {}),
+        code,
+        message,
+      });
+    };
+    if (c.report.extraction.scanComplete !== true)
+      add("incomplete-extraction", "Selected source extraction is incomplete");
+    for (const [pluginName, p] of Object.entries(c.report.plugins)) {
+      if (p.verdict === "unknown")
+        add("unknown-verdict", "Plugin verdict is unknown", pluginName);
+      if (policy.requireCompleteCoverage && p.coverage.status !== "complete")
+        add(
+          "incomplete-coverage",
+          p.coverage.limitations.join("; ") || "Coverage is limited",
+          pluginName,
+        );
+      if (!policy.allowVacuous && p.vacuous)
+        add(
+          "vacuous",
+          "No verified calls; this is not business acceptance",
+          pluginName,
+        );
+      const prev =
+        policy.mode === "new"
+          ? previous.cells.find((x) => x.dshVersion === c.dshVersion).report
+              .plugins[pluginName]
+          : null;
+      const old = new Map();
+      for (const f of prev?.findings || [])
+        old.set(findingKey(f), (old.get(findingKey(f)) || 0) + 1);
+      p.findings.forEach((f, findingIndex) => {
+        counts.findings++;
+        if (
+          !policy.severities.includes(f.severity) ||
+          !policy.certainties.includes(f.certainty)
+        )
+          return;
+        const key = findingKey(f);
+        if (old.get(key) > 0) {
+          old.set(key, old.get(key) - 1);
+          counts.suppressed++;
+          return;
+        }
+        counts.matched++;
+        risk = true;
+        if (f.severity === "fatal") fatal = true;
+        reasons.push({
+          dshVersion: c.dshVersion,
+          pluginName,
+          findingIndex,
+          code: "finding",
+          message: `${f.severity}/${f.certainty}: ${f.category}: ${f.impact}`,
+        });
+      });
+    }
+  }
+  return finish(tool ? 3 : fatal ? 2 : risk ? 1 : 0);
+}

package/kernel/lib/catalog.mjs

@@ -1,6 +1,9 @@
 /** Keep the frozen legacy catalogue available for older targets and overrides. */
 import path from "node:path";
 import semver from "semver";
+import fs from "node:fs";
+import { createHash } from "node:crypto";
+import { CATALOG_REFERENCES, describeCatalog } from "./contracts.mjs";
 
 export function catalogPathFor(root, version, override) {
   if (override) return override;
@@ -14,3 +17,38 @@ export function catalogPathFor(root, version, override) {
     modern ? "dsh-api-catalog-0.2.1-rc.2.json" : "dsh-api-catalog.json",
   );
 }
+
+/** Read once: the reported digest always describes the bytes used to judge. */
+export function loadCatalog(root, version, override) {
+  const file = catalogPathFor(root, version, override),
+    bytes = fs.readFileSync(file);
+  const sha256 = createHash("sha256").update(bytes).digest("hex");
+  const known = CATALOG_REFERENCES.find(
+    (c) => c.file === path.basename(file) && c.sha256 === sha256,
+  );
+  if (!override && !known)
+    throw new Error(
+      "内置 API 目录摘要与已验收记录不符，无法判定；请核对目录来源",
+    );
+  const catalog = JSON.parse(bytes);
+  if (
+    !catalog ||
+    typeof catalog !== "object" ||
+    Array.isArray(catalog) ||
+    !catalog.host ||
+    !catalog.client
+  )
+    throw new Error("API 目录格式无效");
+  return {
+    file,
+    catalog,
+    evidence: describeCatalog({
+      targetVersion: version || null,
+      referenceVersion:
+        known?.version ||
+        (typeof catalog._dshVersion === "string" ? catalog._dshVersion : null),
+      sha256,
+      override: Boolean(override),
+    }),
+  };
+}

package/kernel/lib/contracts.mjs

@@ -8,6 +8,61 @@
 export const REPORT_SCHEMA = 1;
 export const REPORT_KIND = "plugin-compat-check/result";
 export const ENVELOPE_KIND = "plugin-compat-check/report";
+/** Reviewed catalogue bytes, not a promise of plugin business compatibility.
+ * Adding a version requires source verification, rule review and integration
+ * evidence; extraction alone must never extend this list. */
+export const CATALOG_REFERENCES = Object.freeze([
+  Object.freeze({
+    version: "0.2.0-rc.2",
+    file: "dsh-api-catalog.json",
+    sha256: "1331bf3220c1e06cfe087237077118d002dc04c32d027ce01da74c6a0d1dc9ad",
+  }),
+  Object.freeze({
+    version: "0.2.1-rc.2",
+    file: "dsh-api-catalog-0.2.1-rc.2.json",
+    sha256: "90b4ae484ebc6660c53e5c9ad14ba657581534b30e8222c636c759e19587f743",
+  }),
+]);
+export function describeCatalog({
+  targetVersion = null,
+  referenceVersion = null,
+  sha256,
+  override = false,
+}) {
+  const known =
+    !override &&
+    CATALOG_REFERENCES.find(
+      (c) => c.version === referenceVersion && c.sha256 === sha256,
+    );
+  const verified = Boolean(known && targetVersion === referenceVersion);
+  return {
+    targetVersion,
+    referenceVersion,
+    sha256,
+    selection: override ? "override" : verified ? "exact" : "fallback",
+    verified,
+    certifiedVersions: known ? [known.version] : [],
+    scope:
+      "仅核验内置目录字节及对应精确版本的集成；不代表业务验收或运行时观测。",
+    warning: verified
+      ? null
+      : override
+        ? "自定义参考目录未认证；目录自报版本或相同字节不扩大已验收范围，请在实际目标宿主复核。"
+        : "目标 DSH 版本未知或未认证；普通体检使用参考目录回退，不能据此认定该版本已验收。",
+  };
+}
+export function catalogLines(c) {
+  if (!c) return ["API 目录身份未提供；版本范围未认证，请重新体检。"];
+  return [
+    "目标 DSH：" + (c.targetVersion || "未知"),
+    "参考目录：" + (c.referenceVersion || "未知") + " · SHA-256：" + c.sha256,
+    "目录认证范围：" +
+      (c.certifiedVersions.join("、") || "无") +
+      "；" +
+      c.scope,
+    ...(c.warning ? [c.warning] : []),
+  ];
+}
 const record = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 const text = (v) => typeof v === "string" && v.length > 0;
 const nullableText = (v) => v === null || typeof v === "string";
@@ -282,6 +337,37 @@ export function validateReportBody(body) {
   }
   need(e, body.error === null, "report.error");
   need(e, nullableText(body.dshVersion), "report.dshVersion");
+  // Older schema-1 reports remain readable, but consumers show missing identity.
+  if (body.catalog !== undefined) {
+    const c = body.catalog;
+    if (
+      !record(c) ||
+      !nullableText(c.referenceVersion) ||
+      !/^[a-f0-9]{64}$/.test(c.sha256)
+    )
+      e.push("report.catalog");
+    else {
+      const expected = describeCatalog({
+        targetVersion: body.dshVersion,
+        referenceVersion: c.referenceVersion,
+        sha256: c.sha256,
+        override: c.selection === "override",
+      });
+      if (
+        c.selection !== "override" &&
+        !CATALOG_REFERENCES.some(
+          (k) => k.version === c.referenceVersion && k.sha256 === c.sha256,
+        )
+      )
+        e.push("report.catalog.identity");
+      for (const [key, value] of Object.entries(expected))
+        need(
+          e,
+          JSON.stringify(c[key]) === JSON.stringify(value),
+          "report.catalog." + key,
+        );
+    }
+  }
   e.push(...validateObservation(body.observation));
   if (
     record(body.observation) &&
@@ -466,6 +552,8 @@ export function validateEnvelope(data) {
   )
     return ["envelope.schemaVersion/kind"];
   const e = validateReportBody(data.report);
+  if (Object.hasOwn(data, "issueReport"))
+    need(e, typeof data.issueReport === "string", "envelope.issueReport");
   need(
     e,
     typeof data.ok === "boolean" && data.ok === data.report?.ok,