@tiangong-lca/pcr 0.3.0 → 0.4.0

package/packages/pcr-core/src/languages.mjs

@@ -1,86 +0,0 @@
-/** Shared language identities. Website route aliases never become PCR identities. */
-export const CANONICAL_PCR_LANGUAGE = "en-US";
-export const REQUIRED_PCR_LANGUAGES = Object.freeze(["en-US", "zh-CN"]);
-export const LEGACY_PCR_ARTIFACT_HASH_FIELDS = Object.freeze({
-  pcr_en_us_sha256: "pcr.en-US.md",
-  pcr_zh_cn_sha256: "pcr.zh-CN.md",
-  structured_sha256: "structured.yaml",
-});
-
-export function assertPcrLanguageCode(language) {
-  if (typeof language !== "string" || !/^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/u.test(language)) {
-    throw new Error(`Invalid PCR language code: ${String(language)}`);
-  }
-  let canonical;
-  try {
-    canonical = Intl.getCanonicalLocales(language)[0];
-  } catch {
-    throw new Error(`Invalid PCR language code: ${language}`);
-  }
-  if (canonical !== language || language === "und") {
-    throw new Error(`PCR language code must use its canonical BCP 47 spelling: ${language}`);
-  }
-  return language;
-}
-
-export function pcrMarkdownFile(language) {
-  return `pcr.${assertPcrLanguageCode(language)}.md`;
-}
-
-export function declaredPcrLanguages(manifest, { strict = true } = {}) {
-  const available = manifest?.languages?.available;
-  // Preserve the legacy reader's fixed-file inspection of incomplete metadata.
-  // Authoring and documentation export always use the strict contract.
-  if (!strict && available === undefined) return [...REQUIRED_PCR_LANGUAGES];
-  if (!Array.isArray(available) || available.length === 0) {
-    throw new Error("PCR manifest requires languages.available.");
-  }
-  const languages = available.map(assertPcrLanguageCode);
-  if (new Set(languages).size !== languages.length) {
-    throw new Error("PCR manifest languages.available must be unique.");
-  }
-  if (strict) {
-    if (manifest.languages.canonical !== CANONICAL_PCR_LANGUAGE) {
-      throw new Error(`PCR canonical language must be ${CANONICAL_PCR_LANGUAGE}.`);
-    }
-    for (const required of REQUIRED_PCR_LANGUAGES) {
-      if (!languages.includes(required)) throw new Error(`PCR requires language ${required}.`);
-    }
-  }
-  return languages;
-}
-
-export function pcrArtifactFiles(manifest, options = {}) {
-  return [...declaredPcrLanguages(manifest, options).map(pcrMarkdownFile), "structured.yaml"];
-}
-
-/** Current release artifacts, with v1 fixed hashes and v2 per-language hashes. */
-export function expectedPcrArtifactHashes(manifest) {
-  const artifacts = manifest?.release_artifacts;
-  if (!artifacts || typeof artifacts !== "object" || Array.isArray(artifacts)) {
-    throw new Error("Managed PCR requires release_artifacts.");
-  }
-  const languages = declaredPcrLanguages(manifest);
-  if (manifest.schema_version === 2) {
-    const hashes = artifacts.markdown_sha256;
-    if (!hashes || typeof hashes !== "object" || Array.isArray(hashes)) {
-      throw new Error("PCR schema v2 requires release_artifacts.markdown_sha256.");
-    }
-    if (Object.keys(hashes).sort().join("\n") !== [...languages].sort().join("\n")) {
-      throw new Error("Release Markdown hashes must match the declared languages exactly.");
-    }
-    return {
-      ...Object.fromEntries(languages.map((language) => [pcrMarkdownFile(language), hashes[language]])),
-      "structured.yaml": artifacts.structured_sha256,
-    };
-  }
-  if (manifest.schema_version !== undefined && manifest.schema_version !== 1) {
-    throw new Error(`Unsupported PCR manifest schema version: ${manifest.schema_version}`);
-  }
-  if (languages.some((language) => !REQUIRED_PCR_LANGUAGES.includes(language))) {
-    throw new Error("A released PCR with optional languages requires schema v2 artifact hashes.");
-  }
-  return Object.fromEntries(
-    Object.entries(LEGACY_PCR_ARTIFACT_HASH_FIELDS).map(([field, file]) => [file, artifacts[field]]),
-  );
-}

package/packages/pcr-core/src/offline-library.mjs

@@ -1,121 +0,0 @@
-import { createHash } from "node:crypto";
-import { createRequire } from "node:module";
-import { closeSync, openSync, readSync, readFileSync, statSync } from "node:fs";
-import path from "node:path";
-import { inflateRawSync } from "node:zlib";
-import { parseYaml } from "./yaml-lite.mjs";
-import { expectedPcrArtifactHashes } from "./languages.mjs";
-import { PcrClassificationCoverageNotFoundError } from "./classification-coverage.mjs";
-
-export const LIBRARY_FORMAT_VERSION = 1;
-export const sha256 = (bytes) => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
-export function libraryError(code, message) {
-  return Object.assign(new Error(message), { code });
-}
-export function sqliteDatabase() {
-  const [major, minor] = process.versions.node.split(".").map(Number);
-  if (major < 24 || (major === 24 && minor < 19)) {
-    throw libraryError("PCR_LIBRARY_RUNTIME_UNSUPPORTED", "Offline libraries require Node.js 24.19 or newer.");
-  }
-  return createRequire(import.meta.url)("node:sqlite").DatabaseSync;
-}
-export function hashFile(filename) {
-  const hash = createHash("sha256");
-  const fd = openSync(filename, "r");
-  const buffer = Buffer.alloc(1024 * 1024);
-  try {
-    let count;
-    while ((count = readSync(fd, buffer, 0, buffer.length, null))) hash.update(buffer.subarray(0, count));
-    return `sha256:${hash.digest("hex")}`;
-  } finally { closeSync(fd); }
-}
-export function metadataDigest(db, table) {
-  if (!["records", "aliases", "coverage", "files"].includes(table)) throw new Error("Unknown snapshot table.");
-  const hash = createHash("sha256");
-  const columns = table === "files" ? "key, size, sha256" : "key, value, sha256";
-  for (const row of db.prepare(`SELECT ${columns} FROM ${table} ORDER BY key`).iterate()) {
-    hash.update(JSON.stringify(row)); hash.update("\n");
-  }
-  return `sha256:${hash.digest("hex")}`;
-}
-
-/** Read-only adapter; all original content remains compressed until selected. */
-export class OfflineLibrary {
-  constructor(filename, { expectedSha256 = null, verify = false, onArtifactRead = null } = {}) {
-    this.filename = path.resolve(filename);
-    this.root = path.dirname(this.filename);
-    this.onArtifactRead = onArtifactRead;
-    this.languages = ["en-US"];
-    try {
-      this.manifest = JSON.parse(readFileSync(`${this.filename}.json`, "utf8"));
-      if (this.manifest.format_version !== LIBRARY_FORMAT_VERSION) {
-        throw libraryError("PCR_LIBRARY_FORMAT_UNSUPPORTED", `Unsupported library format ${this.manifest.format_version}; supported: ${LIBRARY_FORMAT_VERSION}.`);
-      }
-      if (JSON.stringify(this.manifest.snapshot?.available_languages) !== JSON.stringify(this.languages)) throw new Error("Unsupported library language policy; expected English only.");
-      if (this.manifest.kind !== "tiangong-pcr-library" || !/^sha256:[a-f0-9]{64}$/u.test(this.manifest.sha256 ?? "")) throw new Error("Invalid library manifest.");
-      if (statSync(this.filename).size !== this.manifest.bytes) throw new Error("Library byte length differs from manifest.");
-      if (expectedSha256 !== null && !/^sha256:[a-f0-9]{64}$/u.test(expectedSha256)) throw new Error("Expected SHA-256 must use sha256:<64 lowercase hex digits>.");
-      if (verify || expectedSha256 !== null) {
-        const digest = hashFile(this.filename);
-        if (digest !== this.manifest.sha256 || (expectedSha256 !== null && digest !== expectedSha256)) throw new Error("Library SHA-256 mismatch.");
-      }
-      const DatabaseSync = sqliteDatabase();
-      this.db = new DatabaseSync(this.filename, { readOnly: true, allowExtension: false, defensive: true });
-      this.db.exec("PRAGMA query_only = ON; PRAGMA trusted_schema = OFF; BEGIN;");
-      if (this.db.prepare("PRAGMA user_version").get().user_version !== LIBRARY_FORMAT_VERSION) throw libraryError("PCR_LIBRARY_FORMAT_UNSUPPORTED", "SQLite format version does not match the reader.");
-      const metadata = JSON.parse(this.db.prepare("SELECT value FROM metadata WHERE key = 'snapshot'").get()?.value ?? "null");
-      if (JSON.stringify(metadata) !== JSON.stringify(this.manifest.snapshot)) throw new Error("Snapshot identity differs from manifest.");
-      for (const table of ["records", "aliases", "coverage", "files"]) {
-        if (metadataDigest(this.db, table) !== this.manifest.index_sha256?.[table]) throw new Error(`Library ${table} index checksum mismatch.`);
-      }
-      if (verify && this.db.prepare("PRAGMA integrity_check").get().integrity_check !== "ok") throw new Error("SQLite integrity check failed.");
-    } catch (error) {
-      this.close();
-      if (error.code?.startsWith("PCR_LIBRARY_")) throw error;
-      throw libraryError("PCR_LIBRARY_INVALID", `Cannot open offline library ${this.filename}: ${error.message}`);
-    }
-  }
-  close() { this.db?.close(); this.db = null; }
-  row(table, key) {
-    const row = this.db.prepare(`SELECT value, sha256 FROM ${table} WHERE key = ?`).get(key);
-    if (!row) return null;
-    if (sha256(row.value) !== row.sha256) throw libraryError("PCR_LIBRARY_INVALID", `Invalid ${table} row: ${key}`);
-    return JSON.parse(row.value);
-  }
-  listPcrs(scope) {
-    const where = scope === "all" ? "" : scope === "material" ? " WHERE kind = 'methodology'" : " WHERE kind = 'legacy_scaffold_reference'";
-    return this.db.prepare(`SELECT value FROM records${where} ORDER BY position`).all().map((row) => JSON.parse(row.value));
-  }
-  entry(id) {
-    const record = this.row("records", String(id));
-    return record ? { id: record.id, path: record.path, manifestPath: path.join(this.root, record.path, "manifest.yaml") } : null;
-  }
-  findAlias(id) { return this.row("aliases", String(id)); }
-  readFile(key) {
-    const row = this.db.prepare("SELECT data, size, sha256 FROM files WHERE key = ?").get(key);
-    if (!row) throw libraryError("PCR_LIBRARY_ARTIFACT_MISSING", `Missing library artifact: ${key}`);
-    try {
-      const bytes = inflateRawSync(row.data, { maxOutputLength: Math.max(1, row.size) });
-      if (bytes.length !== row.size || sha256(bytes) !== row.sha256) throw new Error("checksum mismatch");
-      this.onArtifactRead?.(key);
-      return bytes;
-    } catch (error) { throw libraryError("PCR_LIBRARY_ARTIFACT_INVALID", `Invalid library artifact ${key}: ${error.message}`); }
-  }
-  snapshotFiles(entry) {
-    const manifestBytes = this.readFile(`${entry.path}/manifest.yaml`);
-    const manifest = parseYaml(manifestBytes.toString("utf8"));
-    if (manifest.id !== entry.id) throw libraryError("PCR_LIBRARY_INVALID", "PCR manifest identity mismatch.");
-    const artifacts = Object.fromEntries(["pcr.en-US.md", "structured.yaml"].map((name) => [name, { bytes: this.readFile(`${entry.path}/${name}`) }]));
-    for (const [name, expected] of Object.entries(manifest.release_artifacts ? expectedPcrArtifactHashes(manifest) : {})) {
-      if (!Object.hasOwn(artifacts, name)) continue;
-      if (manifest.release_artifacts && sha256(artifacts[name]?.bytes ?? Buffer.alloc(0)) !== expected) throw libraryError("PCR_LIBRARY_ARTIFACT_INVALID", `Release artifact hash mismatch: ${entry.path}/${name}`);
-    }
-    return { manifest, manifestBytes, artifacts };
-  }
-  coverageSnapshot(system, version) {
-    const key = `${String(system).toLowerCase()}:${version}`;
-    const snapshot = this.row("coverage", key);
-    if (!snapshot) throw new PcrClassificationCoverageNotFoundError({ system, version, relativePath: `classifications/indexes/${system}-${version}-coverage.json` });
-    return snapshot;
-  }
-}

package/packages/pcr-core/src/output-semantics.mjs

@@ -1,228 +0,0 @@
-function semanticIssue(code, instancePath, message, params = {}) {
-  return {
-    code: `semantic.${code}`,
-    instance_path: instancePath,
-    schema_path: `#/x-semantic/${code.replaceAll(".", "/")}`,
-    keyword: "semantic",
-    message,
-    params,
-  };
-}
-
-export function readinessSemanticIssues(readiness) {
-  const issues = [];
-  const blockers = readiness.blockers;
-  const fingerprint = readiness.projection_fingerprint;
-  const usable = readiness.usable_for_guidance && readiness.usable_for_validation;
-
-  if (readiness.usable_for_guidance !== readiness.usable_for_validation) {
-    issues.push(semanticIssue(
-      "readiness.usability_alignment",
-      "/usable_for_validation",
-      "guidance and validation usability must have the same value.",
-    ));
-  }
-
-  if (blockers.length > 0) {
-    if (readiness.status !== "unavailable") {
-      issues.push(semanticIssue(
-        "readiness.blocked_status",
-        "/status",
-        "readiness with blockers must be unavailable.",
-        { blocker_count: blockers.length },
-      ));
-    }
-    if (usable || readiness.usable_for_guidance || readiness.usable_for_validation) {
-      issues.push(semanticIssue(
-        "readiness.blocked_usability",
-        "/usable_for_guidance",
-        "readiness with blockers must not be usable for guidance or validation.",
-        { blocker_count: blockers.length },
-      ));
-    }
-  } else {
-    if (readiness.status === "unavailable") {
-      issues.push(semanticIssue(
-        "readiness.unavailable_without_blocker",
-        "/status",
-        "unavailable readiness must include at least one blocker.",
-      ));
-    }
-    if (!usable) {
-      issues.push(semanticIssue(
-        "readiness.unblocked_usability",
-        "/usable_for_guidance",
-        "readiness without blockers must be usable for guidance and validation.",
-      ));
-    }
-  }
-
-  if (!fingerprint.required) {
-    if (
-      fingerprint.status !== "not_required" ||
-      fingerprint.schema_valid !== null ||
-      fingerprint.issues.length > 0
-    ) {
-      issues.push(semanticIssue(
-        "readiness.fingerprint_not_required",
-        "/projection_fingerprint/status",
-        "a non-required projection fingerprint must be not_required with no schema result or issues.",
-      ));
-    }
-  }
-
-  if (fingerprint.status === "current") {
-    if (
-      fingerprint.schema_valid !== true ||
-      fingerprint.source_hash_valid !== true ||
-      fingerprint.content_hash_valid !== true ||
-      fingerprint.issues.length > 0
-    ) {
-      issues.push(semanticIssue(
-        "readiness.current_fingerprint",
-        "/projection_fingerprint/status",
-        "a current projection fingerprint requires valid schema, source hash, content hash, and no issues.",
-      ));
-    }
-  }
-
-  if (fingerprint.required && usable && fingerprint.status !== "current") {
-    issues.push(semanticIssue(
-      "readiness.usable_fingerprint",
-      "/projection_fingerprint/status",
-      "usable material PCR readiness requires a current projection fingerprint.",
-    ));
-  }
-
-  return issues.sort(compareIssues);
-}
-
-export function validationReportSemanticIssues(report) {
-  const issues = [];
-  const summary = countFindings(report.findings);
-  const performed = report.check_coverage.checks_performed;
-  const skipped = report.check_coverage.checks_skipped;
-  const checkedRequirementCount = performed.reduce(
-    (total, check) => total + check.requirement_count,
-    0,
-  );
-  const skippedRequirementCount = skipped.reduce(
-    (total, check) => total + check.requirement_count,
-    0,
-  );
-
-  if (report.finding_count !== report.findings.length) {
-    issues.push(semanticIssue(
-      "validation.finding_count",
-      "/finding_count",
-      "finding_count must equal findings.length.",
-      { expected: report.findings.length, actual: report.finding_count },
-    ));
-  }
-
-  for (const severity of ["error", "warning", "info"]) {
-    if (report.finding_summary[severity] !== summary[severity]) {
-      issues.push(semanticIssue(
-        `validation.finding_summary.${severity}`,
-        `/finding_summary/${severity}`,
-        `${severity} finding summary must equal the findings array count.`,
-        { expected: summary[severity], actual: report.finding_summary[severity] },
-      ));
-    }
-  }
-
-  for (const [index, check] of performed.entries()) {
-    if (check.evaluated_requirement_count !== check.requirement_count) {
-      issues.push(semanticIssue(
-        "validation.performed_check_coverage",
-        `/check_coverage/checks_performed/${index}/evaluated_requirement_count`,
-        "a performed check must evaluate every requirement it declares.",
-        {
-          requirement_count: check.requirement_count,
-          evaluated_requirement_count: check.evaluated_requirement_count,
-        },
-      ));
-    }
-  }
-
-  const coverage = report.check_coverage;
-  if (coverage.checked_requirement_count !== checkedRequirementCount) {
-    issues.push(semanticIssue(
-      "validation.checked_requirement_count",
-      "/check_coverage/checked_requirement_count",
-      "checked_requirement_count must equal the sum of performed requirement counts.",
-      { expected: checkedRequirementCount, actual: coverage.checked_requirement_count },
-    ));
-  }
-  if (coverage.skipped_requirement_count !== skippedRequirementCount) {
-    issues.push(semanticIssue(
-      "validation.skipped_requirement_count",
-      "/check_coverage/skipped_requirement_count",
-      "skipped_requirement_count must equal the sum of skipped requirement counts.",
-      { expected: skippedRequirementCount, actual: coverage.skipped_requirement_count },
-    ));
-  }
-  const totalRequirementCount = checkedRequirementCount + skippedRequirementCount;
-  if (coverage.total_requirement_count !== totalRequirementCount) {
-    issues.push(semanticIssue(
-      "validation.total_requirement_count",
-      "/check_coverage/total_requirement_count",
-      "total_requirement_count must equal checked plus skipped requirements.",
-      { expected: totalRequirementCount, actual: coverage.total_requirement_count },
-    ));
-  }
-
-  const expectedCompleteness = performed.length === 0
-    ? "none"
-    : skipped.length > 0
-      ? "partial"
-      : "complete";
-  if (report.completeness !== expectedCompleteness) {
-    issues.push(semanticIssue(
-      "validation.completeness",
-      "/completeness",
-      "completeness must reflect performed and skipped checks.",
-      { expected: expectedCompleteness, actual: report.completeness },
-    ));
-  }
-
-  const expectedStatus = summary.error > 0
-    ? "failed"
-    : performed.length === 0
-      ? "inconclusive"
-      : "passed";
-  if (report.validation_status !== expectedStatus) {
-    issues.push(semanticIssue(
-      "validation.status",
-      "/validation_status",
-      "validation_status must reflect error findings and performed coverage.",
-      { expected: expectedStatus, actual: report.validation_status },
-    ));
-  }
-
-  if (!report.input.accepted && performed.length > 0) {
-    issues.push(semanticIssue(
-      "validation.rejected_input_coverage",
-      "/check_coverage/checks_performed",
-      "rejected input must not report performed checks.",
-    ));
-  }
-
-  return issues.sort(compareIssues);
-}
-
-function countFindings(findings) {
-  const summary = { error: 0, warning: 0, info: 0 };
-  for (const finding of findings) {
-    summary[finding.severity] += 1;
-  }
-  return summary;
-}
-
-function compareIssues(left, right) {
-  return (
-    left.instance_path.localeCompare(right.instance_path) ||
-    left.code.localeCompare(right.code) ||
-    left.message.localeCompare(right.message)
-  );
-}