@tiangong-lca/pcr 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,193 @@
+import { readFileSync } from "node:fs";
+
+import { createSchemaRegistry } from "./schema-validation.mjs";
+import {
+  readinessSemanticIssues,
+  validationReportSemanticIssues,
+} from "./output-semantics.mjs";
+
+const CORE_SCHEMA_DEPENDENCY_FILES = ["controlled-vocabulary.schema.json"];
+const CORE_SCHEMA_FILES = [
+  "classification-coverage.schema.json",
+  "dataset-validation-input.schema.json",
+  "feedback-draft-output.schema.json",
+  "feedback.schema.json",
+  "guidance-output.schema.json",
+  "model-validation-input.schema.json",
+  "pcr-id-aliases.schema.json",
+  "readiness.schema.json",
+  "structured-projection.schema.json",
+  "validation-output.schema.json",
+];
+
+const schemaEntries = CORE_SCHEMA_FILES.map((fileName) => ({
+  fileName,
+  schema: JSON.parse(readFileSync(new URL(`../schemas/${fileName}`, import.meta.url), "utf8")),
+}));
+const schemaDependencies = CORE_SCHEMA_DEPENDENCY_FILES.map((fileName) =>
+  JSON.parse(readFileSync(new URL(`../schemas/${fileName}`, import.meta.url), "utf8")),
+);
+const contractIds = new Map(schemaEntries.map(({ fileName, schema }) => [fileName, schema.$id]));
+const entityKindsByFile = {
+  "classification-coverage.schema.json": "classification_coverage",
+  "dataset-validation-input.schema.json": "dataset_validation_input",
+  "feedback-draft-output.schema.json": "feedback_draft_output",
+  "feedback.schema.json": "feedback_intake",
+  "guidance-output.schema.json": "guidance_output",
+  "model-validation-input.schema.json": "model_validation_input",
+  "pcr-id-aliases.schema.json": "pcr_id_aliases",
+  "readiness.schema.json": "readiness",
+  "structured-projection.schema.json": "structured_projection",
+  "validation-output.schema.json": "validation_report",
+};
+const registry = createSchemaRegistry(
+  [...schemaDependencies, ...schemaEntries.map(({ schema }) => schema)],
+  Object.fromEntries(
+    schemaEntries.map(({ fileName, schema }) => [schema.$id, entityKindsByFile[fileName]]),
+  ),
+);
+
+const semanticValidators = new Map([
+  [contractIds.get("readiness.schema.json"), readinessSemanticIssues],
+  [contractIds.get("validation-output.schema.json"), validationReportSemanticIssues],
+]);
+
+export class CoreContractSemanticError extends Error {
+  constructor({
+    code = "PCR_SEMANTIC_CONTRACT_INVALID",
+    contract,
+    entityKind,
+    source = null,
+    issues,
+  }) {
+    const location = source ? ` at ${source}` : "";
+    const details = issues.map((issue) => `${issue.instance_path}: ${issue.message}`).join("; ");
+    super(`${entityKind} semantic contract failed${location}: ${details}`);
+    this.name = "CoreContractSemanticError";
+    this.code = code;
+    this.contract = contract;
+    this.entity_kind = entityKind;
+    this.schema_id = contract;
+    this.source = source;
+    this.issues = structuredClone(issues);
+    this.errors = structuredClone(issues);
+  }
+
+  toJSON() {
+    return {
+      code: this.code,
+      entity_kind: this.entity_kind,
+      schema_id: this.schema_id,
+      source: this.source,
+      errors: structuredClone(this.errors),
+    };
+  }
+}
+
+export const CORE_SCHEMA_IDS = Object.freeze({
+  classificationCoverage: contractIds.get("classification-coverage.schema.json"),
+  structured: contractIds.get("structured-projection.schema.json"),
+  readiness: contractIds.get("readiness.schema.json"),
+  guidance: contractIds.get("guidance-output.schema.json"),
+  validationReport: contractIds.get("validation-output.schema.json"),
+  feedbackDraft: contractIds.get("feedback-draft-output.schema.json"),
+  feedbackIntake: contractIds.get("feedback.schema.json"),
+  modelInput: contractIds.get("model-validation-input.schema.json"),
+  datasetInput: contractIds.get("dataset-validation-input.schema.json"),
+  pcrIdAliases: contractIds.get("pcr-id-aliases.schema.json"),
+});
+
+export function assertCoreContract(contract, value, options = {}) {
+  const contractId = resolveContractId(contract);
+  registry.assert(contractId, value, options);
+  const issues = semanticValidators.get(contractId)?.(value) ?? [];
+  if (issues.length > 0) {
+    throw new CoreContractSemanticError({
+      code: options.code,
+      contract: contractId,
+      entityKind: options.entityKind ?? entityKindsByContract.get(contractId) ?? contractId,
+      source: options.source,
+      issues,
+    });
+  }
+  return value;
+}
+
+export function validateCoreContract(contract, value, options = {}) {
+  const contractId = resolveContractId(contract);
+  const result = registry.validate(contractId, value, options);
+  if (!result.valid) {
+    return result;
+  }
+  const errors = semanticValidators.get(contractId)?.(value) ?? [];
+  if (errors.length === 0) {
+    return result;
+  }
+  return {
+    ...result,
+    valid: false,
+    code: "PCR_SEMANTIC_CONTRACT_INVALID",
+    errors,
+    issues: errors,
+  };
+}
+
+export function coreContractId(fileName) {
+  return resolveContractId(fileName);
+}
+
+export const validateStructured = (value) =>
+  validateCoreContract("structured-projection.schema.json", value);
+export const assertStructured = (value, options = {}) =>
+  assertCoreContract("structured-projection.schema.json", value, options);
+export const validateReadiness = (value) => validateCoreContract("readiness.schema.json", value);
+export const assertReadiness = (value, options = {}) =>
+  assertCoreContract("readiness.schema.json", value, options);
+export const validateGuidance = (value) => validateCoreContract("guidance-output.schema.json", value);
+export const assertGuidance = (value, options = {}) =>
+  assertCoreContract("guidance-output.schema.json", value, options);
+export const validateValidationReport = (value) =>
+  validateCoreContract("validation-output.schema.json", value);
+export const assertValidationReport = (value, options = {}) =>
+  assertCoreContract("validation-output.schema.json", value, options);
+export const validateFeedbackDraft = (value) =>
+  validateCoreContract("feedback-draft-output.schema.json", value);
+export const assertFeedbackDraft = (value, options = {}) =>
+  assertCoreContract("feedback-draft-output.schema.json", value, options);
+export const validateFeedbackIntake = (value) =>
+  validateCoreContract("feedback.schema.json", value);
+export const assertFeedbackIntake = (value, options = {}) =>
+  assertCoreContract("feedback.schema.json", value, options);
+export const validateModelInput = (value) =>
+  validateCoreContract("model-validation-input.schema.json", value);
+export const assertModelInput = (value, options = {}) =>
+  assertCoreContract("model-validation-input.schema.json", value, options);
+export const validateDatasetInput = (value) =>
+  validateCoreContract("dataset-validation-input.schema.json", value);
+export const assertDatasetInput = (value, options = {}) =>
+  assertCoreContract("dataset-validation-input.schema.json", value, options);
+export const validateClassificationCoverage = (value) =>
+  validateCoreContract("classification-coverage.schema.json", value);
+export const assertClassificationCoverage = (value, options = {}) =>
+  assertCoreContract("classification-coverage.schema.json", value, options);
+export const validatePcrIdAliases = (value) =>
+  validateCoreContract("pcr-id-aliases.schema.json", value);
+export const assertPcrIdAliases = (value, options = {}) =>
+  assertCoreContract("pcr-id-aliases.schema.json", value, options);
+
+export const validateStructuredProjection = validateStructured;
+export const assertStructuredProjection = assertStructured;
+export const validateGuidanceOutput = validateGuidance;
+export const assertGuidanceOutput = assertGuidance;
+export const validateModelValidationInput = validateModelInput;
+export const assertModelValidationInput = assertModelInput;
+export const validateDatasetValidationInput = validateDatasetInput;
+export const assertDatasetValidationInput = assertDatasetInput;
+
+function resolveContractId(contract) {
+  return contractIds.get(contract) ?? contract;
+}
+
+const entityKindsByContract = new Map(
+  schemaEntries.map(({ fileName, schema }) => [schema.$id, entityKindsByFile[fileName]]),
+);

package/packages/pcr-core/src/generated/controlled-vocabulary.mjs

@@ -0,0 +1,41 @@
+// Generated by builder/scripts/generate-controlled-vocabulary.mjs.
+// Do not edit this file directly; edit builder/vocab/*.yaml and run npm run vocab:generate.
+
+export const AMOUNT_RANGE_ROLE_VALUES = Object.freeze(["qa_guardrail","typical_range","allowed_range","default_estimate","uncertainty_range"]);
+export const AMOUNT_SPECIFICITY_VALUES = Object.freeze(["generic","site_specific","product_specific","route_specific","scenario_specific","technology_specific","not_applicable"]);
+export const AMOUNT_VALUE_MODE_VALUES = Object.freeze(["fixed_value","foreground_record","calculated_value","modelled_estimate","not_applicable"]);
+export const BASIS_KIND_VALUES = Object.freeze(["reference_flow","process_output","n_input","fuel_inventory","transport_service","storage_duration","crop_cycle"]);
+export const CLASSIFICATION_COVERAGE_STATUS_VALUES = Object.freeze(["mapped","unmapped","candidate_suggestion","manual_review","unknown"]);
+export const CLASSIFICATION_MAPPING_RELATION_VALUES = Object.freeze(["exact","broader","narrower","proxy","manual_review"]);
+export const CONTENT_MATURITY_VALUES = Object.freeze(["empty_scaffold","draft_methodology","authored_methodology","reviewed_methodology","published_methodology","deprecated_methodology"]);
+export const EVIDENCE_KIND_VALUES = Object.freeze(["external_source","observed_dataset","method_formula","foreground_data","tiangong_default","collected_record","calculated_from_collection","identity_reference","source_rule","reasoned_estimate"]);
+export const FEEDBACK_CONFIDENCE_VALUES = Object.freeze(["high","medium","low","unknown"]);
+export const FEEDBACK_TYPE_VALUES = Object.freeze(["missing_pcr","classification_mapping_gap","unclear_reference_flow","wrong_or_missing_uuid","process_boundary_issue","inventory_flow_gap","range_evidence_update","unit_or_flow_property_issue","validation_rule_issue","translation_mismatch","source_update"]);
+export const FLOW_DIRECTION_VALUES = Object.freeze(["inputs","outputs"]);
+export const FLOW_TYPE_VALUES = Object.freeze(["product","waste","elementary"]);
+export const PCR_STATUS_VALUES = Object.freeze(["scaffold","candidate","active","published","deprecated"]);
+export const PROCESS_INCLUSION_VALUES = Object.freeze(["required","conditional","optional","excluded_by_default"]);
+export const SOURCE_TYPE_VALUES = Object.freeze(["official_guidance","literature","standard","dataset","method_factor","extension_guidance","handbook"]);
+export const TARGET_ENTITY_VALUES = Object.freeze(["flow","process","lifecyclemodel","dataset"]);
+export const TRANSLATION_STATUS_VALUES = Object.freeze(["not_available","scaffold","scaffold_pending_translation","draft_translation","aligned","reviewed","out_of_sync"]);
+
+export const CONTROLLED_VOCABULARY = Object.freeze({
+  amount_range_role: AMOUNT_RANGE_ROLE_VALUES,
+  amount_specificity: AMOUNT_SPECIFICITY_VALUES,
+  amount_value_mode: AMOUNT_VALUE_MODE_VALUES,
+  basis_kind: BASIS_KIND_VALUES,
+  classification_coverage_status: CLASSIFICATION_COVERAGE_STATUS_VALUES,
+  classification_mapping_relation: CLASSIFICATION_MAPPING_RELATION_VALUES,
+  content_maturity: CONTENT_MATURITY_VALUES,
+  evidence_kind: EVIDENCE_KIND_VALUES,
+  feedback_confidence: FEEDBACK_CONFIDENCE_VALUES,
+  feedback_type: FEEDBACK_TYPE_VALUES,
+  flow_direction: FLOW_DIRECTION_VALUES,
+  flow_type: FLOW_TYPE_VALUES,
+  pcr_status: PCR_STATUS_VALUES,
+  process_inclusion: PROCESS_INCLUSION_VALUES,
+  source_type: SOURCE_TYPE_VALUES,
+  target_entity: TARGET_ENTITY_VALUES,
+  translation_status: TRANSLATION_STATUS_VALUES,
+});
+