@c4a/extract 0.6.1 → 0.6.2

package/README.md

@@ -10,7 +10,7 @@ project extraction phases such as `extractTs({ source, collection: "codegraph" }
 - Language plugins implement `ExtractionPlugin` and return `ExtractionResult` v2.
 - The runner loads one or more plugins, scans repository modules, emits progress/module-error/summary events, and can build an optional low-level code snapshot payload.
 - `@c4a/context-cli` invokes the runner from `context run extract:<source>:codegraph` after the workspace declares an `extractTs` phase.
-- The project flow stages review candidates under `unapproved/entities.jsonl` and keeps runtime candidate artifacts under `.tmp/context-runtime/extract/`; approved Markdown is written only by review/apply.
+- The project flow stages review candidates under `.tmp/context-runtime/lifecycle/candidates.jsonl` and keeps runtime candidate artifacts under `.tmp/context-runtime/extract/`; approved Markdown is written only by review/apply.
 
 **Depends on:** `@c4a/core`, `web-tree-sitter`, `zod`
 

package/index.js

@@ -13721,7 +13721,115 @@ var generateSymbolDiff = (current, previous) => {
 // src/documentEvidence.ts
 import { Buffer as Buffer2 } from "node:buffer";
 import { createHash as createHash2 } from "node:crypto";
-var DOCUMENT_EVIDENCE_NORMALIZER_VERSION = "document-evidence-normalizer.v1";
+
+// src/documentCaptureFidelity.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requiredString(value, field) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new TypeError(`${field} must be a non-empty string`);
+  }
+  return value.trim();
+}
+function counts(value, field) {
+  if (!isRecord(value))
+    throw new TypeError(`${field} must be an object`);
+  const result = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (key.trim().length === 0 || !Number.isInteger(item) || item < 0) {
+      throw new TypeError(`${field}.${key} must be a non-negative integer`);
+    }
+    result[key] = item;
+  }
+  return result;
+}
+function skippedReasons(value, field) {
+  if (!Array.isArray(value))
+    throw new TypeError(`${field} must be an array`);
+  return value.map((item, index) => {
+    if (!isRecord(item))
+      throw new TypeError(`${field}[${index}] must be an object`);
+    if (!Number.isInteger(item.count) || item.count < 1) {
+      throw new TypeError(`${field}[${index}] must include block_type, positive count, and reason`);
+    }
+    return {
+      block_type: requiredString(item.block_type, `${field}[${index}].block_type`),
+      count: item.count,
+      reason: requiredString(item.reason, `${field}[${index}].reason`)
+    };
+  });
+}
+function fidelityIssues(value, field) {
+  if (!Array.isArray(value))
+    throw new TypeError(`${field} must be an array`);
+  return value.map((item, index) => {
+    if (!isRecord(item))
+      throw new TypeError(`${field}[${index}] must be an object`);
+    if (item.severity !== "warning" && item.severity !== "error" || !Number.isInteger(item.count) || item.count < 1) {
+      throw new TypeError(`${field}[${index}] must include severity, code, block_type, positive count, and reason`);
+    }
+    return {
+      severity: item.severity,
+      impact: item.impact === "evidence" || item.impact === "projection" ? item.impact : item.severity === "error" ? "evidence" : "projection",
+      code: requiredString(item.code, `${field}[${index}].code`),
+      block_type: requiredString(item.block_type, `${field}[${index}].block_type`),
+      count: item.count,
+      reason: requiredString(item.reason, `${field}[${index}].reason`)
+    };
+  });
+}
+function parseDocumentCaptureFidelity(value, field) {
+  if (value === undefined)
+    return;
+  if (!isRecord(value))
+    throw new TypeError(`${field} must be an object`);
+  if (value.status !== "complete" && value.status !== "warning" && value.status !== "error") {
+    throw new TypeError(`${field}.status must be complete, warning, or error`);
+  }
+  const discovered = counts(value.discovered, `${field}.discovered`);
+  const converted = counts(value.converted, `${field}.converted`);
+  const skipped = skippedReasons(value.skipped, `${field}.skipped`);
+  const issues = fidelityIssues(value.issues, `${field}.issues`);
+  const countedBlockTypes = new Set([
+    ...Object.keys(discovered),
+    ...Object.keys(converted),
+    ...skipped.map((item) => item.block_type)
+  ]);
+  for (const blockType of countedBlockTypes) {
+    const discoveredCount = discovered[blockType] ?? 0;
+    const skippedCount = skipped.filter((item) => item.block_type === blockType).reduce((sum, item) => sum + item.count, 0);
+    if ((converted[blockType] ?? 0) + skippedCount !== discoveredCount) {
+      throw new TypeError(`${field} does not close for ${blockType}: discovered ${discoveredCount}, converted ${converted[blockType] ?? 0}, skipped ${skippedCount}`);
+    }
+  }
+  const evidenceStatus = issues.some((issue) => issue.impact === "evidence" && issue.severity === "error") ? "error" : "complete";
+  const projectionIssues = issues.filter((issue) => issue.impact === "projection");
+  const inferredProjectionStatus = projectionIssues.some((issue) => issue.severity === "error") ? "error" : projectionIssues.some((issue) => issue.code === "lark.capture.generic-projection") ? "generic" : projectionIssues.length > 0 ? "warning" : "complete";
+  const projectionStatus = value.projection_status === "complete" || value.projection_status === "generic" || value.projection_status === "warning" || value.projection_status === "error" ? value.projection_status : inferredProjectionStatus;
+  const status = evidenceStatus === "error" || projectionStatus === "error" ? "error" : issues.length > 0 ? "warning" : "complete";
+  if (value.status !== status) {
+    throw new TypeError(`${field}.status must be ${status} for its issues`);
+  }
+  if (value.evidence_status !== undefined && value.evidence_status !== evidenceStatus) {
+    throw new TypeError(`${field}.evidence_status must be ${evidenceStatus} for its issues`);
+  }
+  if (value.projection_status !== undefined && value.projection_status !== inferredProjectionStatus) {
+    throw new TypeError(`${field}.projection_status must be ${inferredProjectionStatus} for its issues`);
+  }
+  return {
+    status,
+    evidence_status: evidenceStatus,
+    projection_status: projectionStatus,
+    discovered,
+    converted,
+    skipped,
+    issues
+  };
+}
+
+// src/documentEvidence.ts
+var DOCUMENT_EVIDENCE_NORMALIZER_VERSION = "document-evidence-normalizer.v2";
 var DOCUMENT_SNAPSHOT_MANIFEST_SCHEMA_VERSION = "document.snapshot.v2";
 var DEFAULT_SOURCE_SPAN_HASH_LENGTH = 12;
 var BOM = "\uFEFF";
@@ -13729,7 +13837,7 @@ var HASH_ID_RE = /^(?:sha256:)?[a-f0-9]{64}$/u;
 var SOURCE_SPAN_HASH_RE = /^[a-f0-9]{8,64}$/u;
 var DOCUMENT_SOURCE_SLUG_RE = /^[a-z0-9][a-z0-9._-]*$/u;
 var DOCUMENT_SOURCE_BATCH_RE = /^\d{8}\/[a-z0-9][a-z0-9._-]*$/u;
-function isRecord(value) {
+function isRecord2(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function bytesOf(value) {
@@ -14032,7 +14140,7 @@ function createDocumentSnapshotManifest(input) {
   });
 }
 function parseFileEntry(value, index) {
-  if (!isRecord(value)) {
+  if (!isRecord2(value)) {
     throw new TypeError(`snapshot manifest files[${index}] must be an object`);
   }
   if (typeof value.path !== "string") {
@@ -14060,7 +14168,7 @@ function parseFileEntry(value, index) {
   };
 }
 function parseAssetEntry(value, index) {
-  if (!isRecord(value)) {
+  if (!isRecord2(value)) {
     throw new TypeError(`snapshot manifest assets[${index}] must be an object`);
   }
   if (typeof value.path !== "string") {
@@ -14079,7 +14187,7 @@ function parseAssetEntry(value, index) {
 function parseStringRecord(value, field) {
   if (value === undefined)
     return;
-  if (!isRecord(value)) {
+  if (!isRecord2(value)) {
     throw new TypeError(`${field} must be an object`);
   }
   const result = {};
@@ -14126,7 +14234,7 @@ function optionalRouteFiles(value, field) {
     throw new TypeError(`${field} must be an array`);
   }
   const result = value.map((item, index) => {
-    if (!isRecord(item)) {
+    if (!isRecord2(item)) {
       throw new TypeError(`${field}[${index}] must be an object`);
     }
     const path2 = optionalMetadataString(item.path, `${field}[${index}].path`);
@@ -14148,7 +14256,7 @@ function optionalRouteHints(value, field) {
     throw new TypeError(`${field} must be an array`);
   }
   const result = value.map((item, index) => {
-    if (!isRecord(item)) {
+    if (!isRecord2(item)) {
       throw new TypeError(`${field}[${index}] must be an object`);
     }
     const documentPath = optionalMetadataString(item.documentPath, `${field}[${index}].documentPath`);
@@ -14168,12 +14276,12 @@ function optionalRouteHints(value, field) {
 function parseManifestMetadata(value) {
   if (value === undefined)
     return;
-  if (!isRecord(value)) {
+  if (!isRecord2(value)) {
     throw new TypeError("snapshot manifest metadata must be an object");
   }
   let source2;
   if (value.source !== undefined) {
-    if (!isRecord(value.source)) {
+    if (!isRecord2(value.source)) {
       throw new TypeError("snapshot manifest metadata.source must be an object");
     }
     const url = optionalMetadataString(value.source.url, "snapshot manifest metadata.source.url");
@@ -14193,18 +14301,20 @@ function parseManifestMetadata(value) {
   }
   let capture;
   if (value.capture !== undefined) {
-    if (!isRecord(value.capture)) {
+    if (!isRecord2(value.capture)) {
       throw new TypeError("snapshot manifest metadata.capture must be an object");
     }
     const include = optionalMetadataStringArray(value.capture.include, "snapshot manifest metadata.capture.include");
     const documentExtensions = optionalMetadataStringArray(value.capture.documentExtensions, "snapshot manifest metadata.capture.documentExtensions");
     const routeFiles = optionalRouteFiles(value.capture.routeFiles, "snapshot manifest metadata.capture.routeFiles");
     const routeHints = optionalRouteHints(value.capture.routeHints, "snapshot manifest metadata.capture.routeHints");
+    const fidelity = parseDocumentCaptureFidelity(value.capture.fidelity, "snapshot manifest metadata.capture.fidelity");
     capture = {
       ...include !== undefined ? { include } : {},
       ...documentExtensions !== undefined ? { documentExtensions } : {},
       ...routeFiles !== undefined ? { routeFiles } : {},
-      ...routeHints !== undefined ? { routeHints } : {}
+      ...routeHints !== undefined ? { routeHints } : {},
+      ...fidelity !== undefined ? { fidelity } : {}
     };
     if (Object.keys(capture).length === 0)
       capture = undefined;
@@ -14215,7 +14325,7 @@ function parseManifestMetadata(value) {
   } : {};
 }
 function parseDocumentSnapshotManifest(value) {
-  if (!isRecord(value)) {
+  if (!isRecord2(value)) {
     throw new TypeError("snapshot manifest must be an object");
   }
   if (value.schema_version !== DOCUMENT_SNAPSHOT_MANIFEST_SCHEMA_VERSION) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/extract",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "type": "module",
   "description": "Code extraction engine — Tree-sitter AST parsing and structural analysis",
   "license": "MIT",