@tiangong-lca/pcr 0.3.1 → 0.4.1

package/packages/pcr-core/src/projection-completeness.mjs

@@ -1,284 +0,0 @@
-const FUNCTIONAL_UNIT_FIELDS = [
-  "what",
-  "how_much",
-  "how_well",
-  "how_long_or_cycle",
-  "reference_flow_link",
-];
-
-const BOUNDARY_ABSTRACTION_FIELDS = [
-  "declared_starting_condition",
-  "starting_condition_role",
-  "product_classification_scope",
-  "recursive_input_rule",
-  "upstream_dataset_requirement",
-  "disclosure",
-];
-
-const PUBLISHED_DATASET_PROFILE_FIELDS = [
-  "dataset_role",
-  "downstream_use",
-  "allowed_use",
-  "excluded_use",
-  "required_metadata",
-  "required_quality_disclosure",
-  "update_trigger",
-];
-
-const REFERENCE_FLOW_FIELDS = [
-  ["reference_amount"],
-  ["product_flow_ref", "name"],
-  ["product_flow_ref", "uuid"],
-  ["flow_property_ref", "uuid"],
-  ["unit_group_ref", "uuid"],
-  ["reference_unit"],
-];
-
-function meaningfulScalar(value) {
-  return value !== undefined && value !== null && String(value).trim() !== "";
-}
-
-function valueAtPath(value, segments) {
-  return segments.reduce((current, segment) => current?.[segment], value);
-}
-
-function missingFieldIssue(codePath, displayPath, message) {
-  return {
-    code: `material_projection.${codePath}`,
-    message: message ?? `Material PCR projection requires non-empty ${displayPath}.`,
-  };
-}
-
-function inventoryFlowRowCount(processInventory) {
-  let count = 0;
-  for (const processEntry of Array.isArray(processInventory) ? processInventory : []) {
-    for (const direction of ["inputs", "outputs"]) {
-      for (const flowType of ["product", "waste", "elementary"]) {
-        count += Array.isArray(processEntry?.[direction]?.[flowType])
-          ? processEntry[direction][flowType].length
-          : 0;
-      }
-    }
-  }
-  return count;
-}
-
-/**
- * Checks content that must be present before a material projection can guide data production.
- * JSON Schema owns stable shape; this function owns state-sensitive methodology completeness.
- */
-export function hasDeclaredUnresolvedReferenceProductFlow(projection, manifest) {
-  if (
-    manifest?.status !== "candidate" ||
-    manifest?.content_maturity !== "authored_methodology"
-  ) {
-    return false;
-  }
-  const productName = String(
-    projection?.reference_flow_definition?.product_flow_ref?.name ?? "",
-  ).trim();
-  if (!productName) {
-    return false;
-  }
-  const reviewMetadata = manifest?.review_metadata ?? {};
-  const hasLegacyReferenceProductDeclaration =
-    (Array.isArray(reviewMetadata.unresolved) &&
-      reviewMetadata.unresolved.some((entry) =>
-        /reference[_ -]?product[_ -]?flow/iu.test(
-          String(entry?.code ?? entry?.issue_id ?? ""),
-        ),
-      )) ||
-    (reviewMetadata.reference_flow_identity?.status === "unresolved" &&
-      (reviewMetadata.reference_flow_identity?.unresolved_support_fields ?? []).some(
-        (field) => String(field) === "reference_product_flow_uuid",
-      ));
-  const unresolvedEntries = [
-    ...(Array.isArray(reviewMetadata.unresolved?.inventory_flow_uuids)
-      ? reviewMetadata.unresolved.inventory_flow_uuids
-      : []),
-    ...(Array.isArray(reviewMetadata.unresolved_flow_identities)
-      ? reviewMetadata.unresolved_flow_identities
-      : []),
-    ...(Array.isArray(reviewMetadata.unresolved)
-      ? reviewMetadata.unresolved
-          .filter((entry) =>
-            /reference[_ -]?product[_ -]?flow(?:[_ -]?uuid)?/iu.test(
-              String(entry?.code ?? entry?.issue_id ?? ""),
-            ),
-          )
-          .map(() => "reference product flow")
-      : []),
-    ...(reviewMetadata.reference_flow_identity?.status === "unresolved" &&
-    (reviewMetadata.reference_flow_identity?.unresolved_support_fields ?? []).some(
-      (field) => String(field) === "reference_product_flow_uuid",
-    )
-      ? ["reference product flow"]
-      : []),
-  ];
-  if (!Array.isArray(unresolvedEntries) || unresolvedEntries.length === 0) {
-    return false;
-  }
-  for (const processEntry of Array.isArray(projection?.process_inventory)
-    ? projection.process_inventory
-    : []) {
-    for (const row of Array.isArray(processEntry?.outputs?.product)
-      ? processEntry.outputs.product
-      : []) {
-      const rowId = String(row?.row_id ?? "").trim();
-      if (
-        hasLegacyReferenceProductDeclaration &&
-        /^reference_product(?:_|$)/u.test(rowId)
-      ) {
-        return true;
-      }
-      if (String(row?.name ?? "").trim() !== productName) {
-        continue;
-      }
-      const normalizedProductName = productName.toLocaleLowerCase("en-US");
-      const hasMatchingDeclaration = unresolvedEntries.some((entry) => {
-        if (typeof entry === "object" && entry !== null) {
-          return String(entry.row_id ?? "").trim() === rowId;
-        }
-        const declaration = String(entry ?? "").trim();
-        const normalizedDeclaration = declaration.toLocaleLowerCase("en-US");
-        return (
-          declaration === rowId ||
-          (rowId && declaration.includes(rowId)) ||
-          declaration.startsWith("reference_product_") ||
-          normalizedDeclaration.includes(normalizedProductName) ||
-          /\breference product(?: flow)?\b|参考产品(?:流)?/iu.test(declaration)
-        );
-      });
-      if (hasMatchingDeclaration) {
-        return true;
-      }
-    }
-  }
-  return false;
-}
-
-export function materialProjectionCompletenessIssues(
-  projection,
-  { expectedPcrId, allowUnresolvedProductFlowUuid = false } = {},
-) {
-  const issues = [];
-  const canonicalPcrId = projection?.product_category_identity?.canonical_pcr_id;
-  if (!meaningfulScalar(canonicalPcrId)) {
-    issues.push(
-      missingFieldIssue(
-        "product_category_identity.canonical_pcr_id",
-        "product_category_identity.canonical_pcr_id",
-        "Product Category Identity requires canonical_pcr_id.",
-      ),
-    );
-  } else if (meaningfulScalar(expectedPcrId) && canonicalPcrId !== expectedPcrId) {
-    issues.push({
-      code: "material_projection.product_category_identity.id_mismatch",
-      message: `canonical_pcr_id "${canonicalPcrId}" does not match manifest id "${expectedPcrId}".`,
-    });
-  }
-
-  for (const field of FUNCTIONAL_UNIT_FIELDS) {
-    if (!meaningfulScalar(projection?.functional_unit?.[field])) {
-      issues.push(
-        missingFieldIssue(
-          `functional_unit.${field}`,
-          `functional_unit.${field}`,
-          `Functional Unit is missing ${field}.`,
-        ),
-      );
-    }
-  }
-
-  for (const segments of REFERENCE_FLOW_FIELDS) {
-    if (
-      allowUnresolvedProductFlowUuid &&
-      segments.length === 2 &&
-      segments[0] === "product_flow_ref" &&
-      segments[1] === "uuid"
-    ) {
-      continue;
-    }
-    if (!meaningfulScalar(valueAtPath(projection?.reference_flow_definition, segments))) {
-      const field = segments.join(".");
-      issues.push(
-        missingFieldIssue(
-          `reference_flow_definition.${field}`,
-          `reference_flow_definition.${field}`,
-          `Reference Flow Definition is missing ${field}.`,
-        ),
-      );
-    }
-  }
-
-  if (!Array.isArray(projection?.measurement_rules) || projection.measurement_rules.length === 0) {
-    issues.push(
-      missingFieldIssue(
-        "measurement_rules",
-        "measurement_rules",
-        "material PCR requires at least one Measurement and Unit rule.",
-      ),
-    );
-  }
-
-  for (const [label, rules, code] of [
-    ["System Boundary", projection?.system_boundary?.rules, "system_boundary.rules"],
-    ["Allocation", projection?.allocation_rules, "allocation_rules"],
-    ["Validation", projection?.validation_rules, "validation_rules"],
-  ]) {
-    if (!Array.isArray(rules) || rules.length === 0) {
-      issues.push(
-        missingFieldIssue(
-          code,
-          code,
-          `material PCR requires at least one ${label} rule.`,
-        ),
-      );
-    }
-  }
-
-  for (const field of BOUNDARY_ABSTRACTION_FIELDS) {
-    if (!meaningfulScalar(projection?.boundary_abstraction?.[field])) {
-      issues.push(
-        missingFieldIssue(
-          `boundary_abstraction.${field}`,
-          `boundary_abstraction.${field}`,
-          `Boundary Abstraction is missing ${field}.`,
-        ),
-      );
-    }
-  }
-
-  if (!Array.isArray(projection?.process_map) || projection.process_map.length === 0) {
-    issues.push(
-      missingFieldIssue(
-        "process_map",
-        "process_map",
-        "material PCR is missing a Process Map.",
-      ),
-    );
-  }
-  if (inventoryFlowRowCount(projection?.process_inventory) === 0) {
-    issues.push(
-      missingFieldIssue(
-        "process_inventory.flow_rows",
-        "process_inventory",
-        "material PCR has no process inventory flow rows.",
-      ),
-    );
-  }
-
-  for (const field of PUBLISHED_DATASET_PROFILE_FIELDS) {
-    if (!meaningfulScalar(projection?.published_dataset_profile?.[field])) {
-      issues.push(
-        missingFieldIssue(
-          `published_dataset_profile.${field}`,
-          `published_dataset_profile.${field}`,
-          `Published Dataset Profile is missing ${field}.`,
-        ),
-      );
-    }
-  }
-
-  return issues;
-}

package/packages/pcr-core/src/projection-integrity.mjs

@@ -1,208 +0,0 @@
-import { createHash } from "node:crypto";
-
-export const PROJECTION_CONTRACT_VERSION = "1";
-export const PROJECTION_GENERATOR = "tiangong-pcr-builder/markdown-projection";
-export const PROJECTION_SOURCE_PATH = "pcr.en-US.md";
-export const PROJECTION_SOURCE_NORMALIZATION = "utf8-lf-v1";
-export const PROJECTION_HASH_ALGORITHM = "sha256";
-
-const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/u;
-const METADATA_MARKER = "projection_metadata:";
-
-export function normalizeFingerprintText(value) {
-  return String(value ?? "")
-    .replace(/^\uFEFF/u, "")
-    .replace(/\r\n?/gu, "\n");
-}
-
-export function sha256Fingerprint(value) {
-  return `sha256:${createHash("sha256").update(normalizeFingerprintText(value), "utf8").digest("hex")}`;
-}
-
-export function buildProjectionMetadata({ sourceMarkdown, generatedContent }) {
-  return {
-    contract_version: PROJECTION_CONTRACT_VERSION,
-    generator: PROJECTION_GENERATOR,
-    canonical_markdown: {
-      path: PROJECTION_SOURCE_PATH,
-      normalization: PROJECTION_SOURCE_NORMALIZATION,
-      hash_algorithm: PROJECTION_HASH_ALGORITHM,
-      sha256: sha256Fingerprint(sourceMarkdown),
-    },
-    generated_content_sha256: sha256Fingerprint(generatedContent),
-  };
-}
-
-export function splitProjectionDocument(structuredText) {
-  const normalized = normalizeFingerprintText(structuredText);
-  const lines = normalized.split("\n");
-  const markerIndexes = [];
-  let offset = 0;
-
-  for (const [index, line] of lines.entries()) {
-    if (line === METADATA_MARKER) {
-      markerIndexes.push({ index, offset });
-    }
-    offset += line.length + 1;
-  }
-
-  if (markerIndexes.length !== 1) {
-    return {
-      valid: false,
-      generatedContent: null,
-      error: markerIndexes.length === 0
-        ? "projection_metadata must be present as the final top-level block"
-        : "projection_metadata must appear exactly once",
-    };
-  }
-
-  const marker = markerIndexes[0];
-  for (const line of lines.slice(marker.index + 1)) {
-    if (line.trim() && !/^ {2,}\S/u.test(line)) {
-      return {
-        valid: false,
-        generatedContent: null,
-        error: "projection_metadata must be the final top-level block",
-      };
-    }
-  }
-
-  const generatedContent = normalized.slice(0, marker.offset);
-  if (!generatedContent.endsWith("\n")) {
-    return {
-      valid: false,
-      generatedContent: null,
-      error: "generated projection content must end with a newline before projection_metadata",
-    };
-  }
-
-  return { valid: true, generatedContent, error: null };
-}
-
-export function inspectProjectionIntegrity({ sourceMarkdown, structuredText, metadata }) {
-  const issues = [];
-  const contractVersion = scalarOrNull(metadata?.contract_version);
-  const sourceHash = scalarOrNull(metadata?.canonical_markdown?.sha256);
-  const generatedContentHash = scalarOrNull(metadata?.generated_content_sha256);
-
-  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
-    issues.push(issue(
-      "projection_fingerprint_missing",
-      "structured.yaml is missing projection_metadata.",
-    ));
-  }
-  if (contractVersion !== PROJECTION_CONTRACT_VERSION) {
-    issues.push(issue(
-      "projection_contract_unsupported",
-      `Projection contract must be ${PROJECTION_CONTRACT_VERSION}; found ${contractVersion ?? "(missing)"}.`,
-    ));
-  }
-  if (metadata?.generator !== PROJECTION_GENERATOR) {
-    issues.push(issue(
-      "projection_fingerprint_invalid",
-      `Projection generator must be ${PROJECTION_GENERATOR}.`,
-    ));
-  }
-  if (metadata?.canonical_markdown?.path !== PROJECTION_SOURCE_PATH) {
-    issues.push(issue(
-      "projection_fingerprint_invalid",
-      `Canonical Markdown path must be ${PROJECTION_SOURCE_PATH}.`,
-    ));
-  }
-  if (metadata?.canonical_markdown?.normalization !== PROJECTION_SOURCE_NORMALIZATION) {
-    issues.push(issue(
-      "projection_fingerprint_invalid",
-      `Canonical Markdown normalization must be ${PROJECTION_SOURCE_NORMALIZATION}.`,
-    ));
-  }
-  if (metadata?.canonical_markdown?.hash_algorithm !== PROJECTION_HASH_ALGORITHM) {
-    issues.push(issue(
-      "projection_fingerprint_invalid",
-      `Canonical Markdown hash algorithm must be ${PROJECTION_HASH_ALGORITHM}.`,
-    ));
-  }
-  if (!SHA256_PATTERN.test(sourceHash ?? "") || !SHA256_PATTERN.test(generatedContentHash ?? "")) {
-    issues.push(issue(
-      "projection_fingerprint_invalid",
-      "Projection SHA-256 values must use sha256:<64 lowercase hex>.",
-    ));
-  }
-
-  const sourceHashValid = SHA256_PATTERN.test(sourceHash ?? "")
-    ? sourceHash === sha256Fingerprint(sourceMarkdown)
-    : null;
-  if (sourceHashValid === false) {
-    issues.push(issue(
-      "projection_source_mismatch",
-      "Canonical Markdown SHA-256 does not match projection metadata; regenerate structured.yaml.",
-    ));
-  }
-
-  const split = splitProjectionDocument(structuredText);
-  let contentHashValid = null;
-  if (!split.valid) {
-    issues.push(issue("projection_fingerprint_invalid", split.error));
-  } else if (SHA256_PATTERN.test(generatedContentHash ?? "")) {
-    contentHashValid = generatedContentHash === sha256Fingerprint(split.generatedContent);
-    if (!contentHashValid) {
-      issues.push(issue(
-        "projection_content_mismatch",
-        "Generated structured projection content SHA-256 does not match projection metadata.",
-      ));
-    }
-  }
-
-  return {
-    required: true,
-    status: integrityStatus(issues),
-    contract_version: contractVersion,
-    source_sha256: sourceHash,
-    generated_content_sha256: generatedContentHash,
-    source_hash_valid: sourceHashValid,
-    content_hash_valid: contentHashValid,
-    issues: deduplicateIssues(issues),
-  };
-}
-
-export function projectionNotRequiredState() {
-  return {
-    required: false,
-    status: "not_required",
-    contract_version: null,
-    source_sha256: null,
-    generated_content_sha256: null,
-    source_hash_valid: null,
-    content_hash_valid: null,
-    issues: [],
-  };
-}
-
-function scalarOrNull(value) {
-  return value === undefined || value === null || typeof value === "object"
-    ? null
-    : String(value);
-}
-
-function issue(code, message) {
-  return { code, message };
-}
-
-function deduplicateIssues(issues) {
-  return [...new Map(issues.map((entry) => [`${entry.code}\0${entry.message}`, entry])).values()];
-}
-
-function integrityStatus(issues) {
-  const codes = new Set(issues.map((entry) => entry.code));
-  for (const [code, status] of [
-    ["projection_fingerprint_missing", "missing"],
-    ["projection_contract_unsupported", "unsupported_contract"],
-    ["projection_source_mismatch", "source_mismatch"],
-    ["projection_content_mismatch", "content_mismatch"],
-    ["projection_fingerprint_invalid", "invalid"],
-  ]) {
-    if (codes.has(code)) {
-      return status;
-    }
-  }
-  return "current";
-}