@c4a/extract 0.6.0-beta.4 → 0.6.0-beta.6

package/README.md

@@ -131,7 +131,7 @@ When `snapshot` input is provided, the runner builds these files:
 During projection, code-owned Sections receive code `source_ref` values derived from these rows:
 
 - package rows: `src-N#package:<package>@<hash>`
-- symbol rows: `src-N#symbol:<locator>:<kind>@<hash>`
+- symbol rows: `src-N#symbol:<file>:<symbol>:<kind>@<hash>`
 
 These refs are verified against the raw code snapshot JSONL indexes. They are
 separate from prose evidence refs, because code snapshots use
@@ -212,6 +212,11 @@ project flow: better symbols/relations produce better draft candidates, stable
 `repo:<source>#symbol:...` source refs, review evidence, approved Markdown, and
 package output.
 
+Approved codegraph Markdown localizes canonical refs as
+`src-N#symbol:<file>:<symbol>:<kind>@<digest>`. The file segment is part of the
+deterministic evidence identity used by verification; agents copy the complete
+ref as an opaque token.
+
 ## Development
 
 ```bash

package/bin/c4a-extract-code.js

@@ -14298,9 +14298,77 @@ var detectModuleAt = async (repoPath, modulePath, ref, pathFilter2) => {
   return buildModule(repoRoot, moduleDir, name, nestedSet, ref, pathFilter2, gitFiles);
 };
 
+// src/errors.ts
+var NO_ENTRY_DETECTED = "NO_ENTRY_DETECTED";
+
+class ExtractionInputError extends Error {
+  code;
+  detail;
+  constructor(code, message, detail) {
+    super(message);
+    this.name = "ExtractionInputError";
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
 // src/repository.ts
 var PACKAGE_JSON = "package.json";
 var toPosixPath2 = (value) => value.split(path2.sep).join("/");
+function safeSourceRelativePath(value) {
+  const slashPath = value.trim().replace(/\\/gu, "/");
+  const normalized = path2.posix.normalize(slashPath).replace(/^\.\//u, "");
+  if (normalized.length === 0 || normalized === "." || normalized === ".." || normalized.startsWith("../") || normalized.startsWith("/") || /^[A-Za-z]:\//u.test(normalized)) {
+    throw new Error(`Extraction entry must be a source-relative file path: ${value}`);
+  }
+  return normalized;
+}
+function moduleRelativeEntryPath(modulePath, sourcePath) {
+  if (modulePath === ".")
+    return sourcePath;
+  const prefix = `${normalizeRelativePath(modulePath)}/`;
+  if (!sourcePath.startsWith(prefix)) {
+    throw new Error(`Extraction entry is outside the selected module ${modulePath}: ${sourcePath}`);
+  }
+  return sourcePath.slice(prefix.length);
+}
+function entrySubpath(filePath, index) {
+  if (index === 0)
+    return ".";
+  const withoutExtension = filePath.replace(/\.(?:d\.)?(?:ts|tsx|mts|cts)$/u, "");
+  return `./${withoutExtension}`;
+}
+function selectedEntryFiles(input) {
+  const selection = input.selection ?? { mode: "auto" };
+  const includedSourceFiles = new Set(input.module.files.map(safeSourceRelativePath));
+  if (selection.mode === "auto") {
+    if (input.detected.entries.length === 0) {
+      throw new ExtractionInputError(NO_ENTRY_DETECTED, 'No TypeScript entry files were detected from package.json. Configure extractTs entries in the Context project, or use mode: "scan"; do not modify the source repository solely for Context.', { mode: "auto", module: input.module.path });
+    }
+    for (const entry of input.detected.entries) {
+      const sourcePath = input.module.path === "." ? safeSourceRelativePath(entry.path) : safeSourceRelativePath(`${input.module.path}/${entry.path}`);
+      if (!includedSourceFiles.has(sourcePath)) {
+        throw new Error(`Auto-detected entry is outside extractTs include: ${sourcePath}. Update include or configure entries in the Context project.`);
+      }
+    }
+    return input.detected.entries;
+  }
+  const sourceEntries = selection.mode === "scan" ? [...includedSourceFiles].sort() : [...new Set(selection.entries.map(safeSourceRelativePath))];
+  if (sourceEntries.length === 0) {
+    throw new ExtractionInputError(NO_ENTRY_DETECTED, selection.mode === "scan" ? "No TypeScript files match extractTs include for scan mode." : "extractTs entries must contain at least one source-relative file path.", { mode: selection.mode, module: input.module.path });
+  }
+  return sourceEntries.map((sourcePath, index) => {
+    if (!includedSourceFiles.has(sourcePath)) {
+      throw new Error(`Configured extraction entry is missing or outside extractTs include: ${sourcePath}. Update entries or include in the Context project.`);
+    }
+    const modulePath = moduleRelativeEntryPath(input.module.path, sourcePath);
+    return {
+      path: modulePath,
+      subpath: entrySubpath(modulePath, index),
+      type: "library"
+    };
+  });
+}
 var normalizeRelativePath = (value) => {
   const normalized = toPosixPath2(value).replace(/^\.\/+/, "").replace(/\/+/g, "/");
   return normalized || ".";
@@ -14468,7 +14536,15 @@ var runRepositoryExtraction = async (input) => {
       module_name: module.name,
       module_path: module.path
     });
-    const entryDetection = await plugin.detectEntries(manifest, fs);
+    const detectedEntries = await plugin.detectEntries(manifest, fs);
+    const entryDetection = {
+      ...detectedEntries,
+      entries: selectedEntryFiles({
+        module,
+        detected: detectedEntries,
+        ...input.entrySelection !== undefined ? { selection: input.entrySelection } : {}
+      })
+    };
     input.onProgress?.({ phase: "parsing", progress: 20, module_name: module.name, module_path: module.path });
     const moduleDoc = await extractModuleDoc(entryDetection, fs);
     const rawExtraction = await plugin.extractSymbols(entryDetection.entries, fs);
@@ -14491,6 +14567,11 @@ var pluginSpecSchema = exports_external.object({
   package: exports_external.string().min(1),
   exportName: exports_external.string().min(1).optional()
 });
+var entrySelectionSchema = exports_external.discriminatedUnion("mode", [
+  exports_external.object({ mode: exports_external.literal("auto") }),
+  exports_external.object({ mode: exports_external.literal("configured"), entries: exports_external.array(exports_external.string().min(1)) }),
+  exports_external.object({ mode: exports_external.literal("scan") })
+]);
 var codeExtractRunnerInputSchema = exports_external.object({
   repoPath: exports_external.string().min(1),
   modules: exports_external.array(exports_external.string().min(1)).optional(),
@@ -14498,6 +14579,7 @@ var codeExtractRunnerInputSchema = exports_external.object({
   commitHash: exports_external.string().min(1).nullable().optional(),
   moduleCommits: exports_external.record(exports_external.string().nullable()).optional(),
   pathFilter: PathFilterConfigSchema.optional(),
+  entrySelection: entrySelectionSchema.optional(),
   plugins: exports_external.array(pluginSpecSchema).min(1),
   snapshot: exports_external.object({
     sourceId: exports_external.string().min(1),
@@ -14552,6 +14634,9 @@ var loadRunnerPlugins = async (pluginSpecs, cwd = process.cwd()) => {
 };
 var runCodeExtractRunner = async (rawInput, cwd = process.cwd()) => {
   const input = codeExtractRunnerInputSchema.parse(rawInput);
+  if (input.entrySelection?.mode === "configured" && input.entrySelection.entries.length === 0) {
+    throw new ExtractionInputError(NO_ENTRY_DETECTED, "Configured extraction entries must contain at least one source-relative file path.", { mode: "configured" });
+  }
   const events = [];
   const plugins = await loadRunnerPlugins(input.plugins, cwd);
   const extraction = await runRepositoryExtraction({
@@ -14561,6 +14646,7 @@ var runCodeExtractRunner = async (rawInput, cwd = process.cwd()) => {
     ...input.commitHash !== undefined ? { commitHash: input.commitHash } : {},
     ...input.moduleCommits ? { moduleCommits: input.moduleCommits } : {},
     ...input.pathFilter ? { pathFilter: input.pathFilter } : {},
+    ...input.entrySelection ? { entrySelection: input.entrySelection } : {},
     plugins,
     onProgress: (event) => events.push({ type: "progress", ...event })
   });

package/index.js

@@ -15474,7 +15474,8 @@ var DEFAULT_SOURCE_SPAN_HASH_LENGTH = 12;
 var BOM = "\uFEFF";
 var HASH_ID_RE = /^(?:sha256:)?[a-f0-9]{64}$/u;
 var SOURCE_SPAN_HASH_RE = /^[a-f0-9]{8,64}$/u;
-var DOCUMENT_SOURCE_NAME_RE = /^[a-z0-9][a-z0-9._-]*$/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) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -15499,8 +15500,20 @@ function assertDocumentSourceType(value) {
 }
 function normalizeDocumentSourceName(name) {
   const value = name.trim();
-  if (!DOCUMENT_SOURCE_NAME_RE.test(value)) {
-    throw new TypeError(`document source name must be a lowercase path-safe slug: ${name}`);
+  if (!DOCUMENT_SOURCE_SLUG_RE.test(value) && !DOCUMENT_SOURCE_BATCH_RE.test(value)) {
+    throw new TypeError(`document source name must be a lowercase path-safe slug or YYYYMMDD/module identity: ${name}`);
+  }
+  if (DOCUMENT_SOURCE_BATCH_RE.test(value)) {
+    const dateName = value.slice(0, 8);
+    const year = Number(dateName.slice(0, 4));
+    const month = Number(dateName.slice(4, 6));
+    const day = Number(dateName.slice(6, 8));
+    const date = new Date(0);
+    date.setUTCHours(0, 0, 0, 0);
+    date.setUTCFullYear(year, month - 1, day);
+    if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) {
+      throw new TypeError(`document source batch must be a valid calendar date: ${name}`);
+    }
   }
   return value;
 }
@@ -15530,14 +15543,20 @@ function decodeSnapshotLocatorPath(path2) {
   }
 }
 function parseDocumentSourceLocator(source2) {
-  const match = /^(file|lark):([^/]+)\/(.+)$/u.exec(source2);
-  if (match?.[1] === undefined || match[2] === undefined || match[3] === undefined)
+  const match = /^(file|lark):(.+)$/u.exec(source2);
+  if (match?.[1] === undefined || match[2] === undefined)
+    return null;
+  const segments = match[2].split("/");
+  const batched = /^\d{8}$/u.test(segments[0] ?? "") && segments.length >= 3;
+  const sourceName = batched ? `${segments[0]}/${segments[1]}` : segments[0];
+  const documentPath = segments.slice(batched ? 2 : 1).join("/");
+  if (sourceName === undefined || documentPath.length === 0)
     return null;
   try {
     return {
       sourceType: match[1],
-      sourceName: normalizeDocumentSourceName(match[2]),
-      documentPath: decodeSnapshotLocatorPath(match[3])
+      sourceName: normalizeDocumentSourceName(sourceName),
+      documentPath: decodeSnapshotLocatorPath(documentPath)
     };
   } catch {
     return null;
@@ -16405,9 +16424,77 @@ var detectModuleAt = async (repoPath, modulePath, ref, pathFilter2) => {
   return buildModule(repoRoot, moduleDir, name, nestedSet, ref, pathFilter2, gitFiles);
 };
 
+// src/errors.ts
+var NO_ENTRY_DETECTED = "NO_ENTRY_DETECTED";
+
+class ExtractionInputError extends Error {
+  code;
+  detail;
+  constructor(code, message, detail) {
+    super(message);
+    this.name = "ExtractionInputError";
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
 // src/repository.ts
 var PACKAGE_JSON = "package.json";
 var toPosixPath2 = (value) => value.split(path2.sep).join("/");
+function safeSourceRelativePath(value) {
+  const slashPath = value.trim().replace(/\\/gu, "/");
+  const normalized = path2.posix.normalize(slashPath).replace(/^\.\//u, "");
+  if (normalized.length === 0 || normalized === "." || normalized === ".." || normalized.startsWith("../") || normalized.startsWith("/") || /^[A-Za-z]:\//u.test(normalized)) {
+    throw new Error(`Extraction entry must be a source-relative file path: ${value}`);
+  }
+  return normalized;
+}
+function moduleRelativeEntryPath(modulePath, sourcePath) {
+  if (modulePath === ".")
+    return sourcePath;
+  const prefix = `${normalizeRelativePath(modulePath)}/`;
+  if (!sourcePath.startsWith(prefix)) {
+    throw new Error(`Extraction entry is outside the selected module ${modulePath}: ${sourcePath}`);
+  }
+  return sourcePath.slice(prefix.length);
+}
+function entrySubpath(filePath, index) {
+  if (index === 0)
+    return ".";
+  const withoutExtension = filePath.replace(/\.(?:d\.)?(?:ts|tsx|mts|cts)$/u, "");
+  return `./${withoutExtension}`;
+}
+function selectedEntryFiles(input) {
+  const selection = input.selection ?? { mode: "auto" };
+  const includedSourceFiles = new Set(input.module.files.map(safeSourceRelativePath));
+  if (selection.mode === "auto") {
+    if (input.detected.entries.length === 0) {
+      throw new ExtractionInputError(NO_ENTRY_DETECTED, 'No TypeScript entry files were detected from package.json. Configure extractTs entries in the Context project, or use mode: "scan"; do not modify the source repository solely for Context.', { mode: "auto", module: input.module.path });
+    }
+    for (const entry of input.detected.entries) {
+      const sourcePath = input.module.path === "." ? safeSourceRelativePath(entry.path) : safeSourceRelativePath(`${input.module.path}/${entry.path}`);
+      if (!includedSourceFiles.has(sourcePath)) {
+        throw new Error(`Auto-detected entry is outside extractTs include: ${sourcePath}. Update include or configure entries in the Context project.`);
+      }
+    }
+    return input.detected.entries;
+  }
+  const sourceEntries = selection.mode === "scan" ? [...includedSourceFiles].sort() : [...new Set(selection.entries.map(safeSourceRelativePath))];
+  if (sourceEntries.length === 0) {
+    throw new ExtractionInputError(NO_ENTRY_DETECTED, selection.mode === "scan" ? "No TypeScript files match extractTs include for scan mode." : "extractTs entries must contain at least one source-relative file path.", { mode: selection.mode, module: input.module.path });
+  }
+  return sourceEntries.map((sourcePath, index) => {
+    if (!includedSourceFiles.has(sourcePath)) {
+      throw new Error(`Configured extraction entry is missing or outside extractTs include: ${sourcePath}. Update entries or include in the Context project.`);
+    }
+    const modulePath = moduleRelativeEntryPath(input.module.path, sourcePath);
+    return {
+      path: modulePath,
+      subpath: entrySubpath(modulePath, index),
+      type: "library"
+    };
+  });
+}
 var normalizeRelativePath = (value) => {
   const normalized = toPosixPath2(value).replace(/^\.\/+/, "").replace(/\/+/g, "/");
   return normalized || ".";
@@ -16575,7 +16662,15 @@ var runRepositoryExtraction = async (input) => {
       module_name: module2.name,
       module_path: module2.path
     });
-    const entryDetection = await plugin.detectEntries(manifest, fs2);
+    const detectedEntries = await plugin.detectEntries(manifest, fs2);
+    const entryDetection = {
+      ...detectedEntries,
+      entries: selectedEntryFiles({
+        module: module2,
+        detected: detectedEntries,
+        ...input.entrySelection !== undefined ? { selection: input.entrySelection } : {}
+      })
+    };
     input.onProgress?.({ phase: "parsing", progress: 20, module_name: module2.name, module_path: module2.path });
     const moduleDoc = await extractModuleDoc(entryDetection, fs2);
     const rawExtraction = await plugin.extractSymbols(entryDetection.entries, fs2);
@@ -16920,6 +17015,11 @@ var pluginSpecSchema = exports_external.object({
   package: exports_external.string().min(1),
   exportName: exports_external.string().min(1).optional()
 });
+var entrySelectionSchema = exports_external.discriminatedUnion("mode", [
+  exports_external.object({ mode: exports_external.literal("auto") }),
+  exports_external.object({ mode: exports_external.literal("configured"), entries: exports_external.array(exports_external.string().min(1)) }),
+  exports_external.object({ mode: exports_external.literal("scan") })
+]);
 var codeExtractRunnerInputSchema = exports_external.object({
   repoPath: exports_external.string().min(1),
   modules: exports_external.array(exports_external.string().min(1)).optional(),
@@ -16927,6 +17027,7 @@ var codeExtractRunnerInputSchema = exports_external.object({
   commitHash: exports_external.string().min(1).nullable().optional(),
   moduleCommits: exports_external.record(exports_external.string().nullable()).optional(),
   pathFilter: PathFilterConfigSchema.optional(),
+  entrySelection: entrySelectionSchema.optional(),
   plugins: exports_external.array(pluginSpecSchema).min(1),
   snapshot: exports_external.object({
     sourceId: exports_external.string().min(1),
@@ -16981,6 +17082,9 @@ var loadRunnerPlugins = async (pluginSpecs, cwd = process.cwd()) => {
 };
 var runCodeExtractRunner = async (rawInput, cwd = process.cwd()) => {
   const input = codeExtractRunnerInputSchema.parse(rawInput);
+  if (input.entrySelection?.mode === "configured" && input.entrySelection.entries.length === 0) {
+    throw new ExtractionInputError(NO_ENTRY_DETECTED, "Configured extraction entries must contain at least one source-relative file path.", { mode: "configured" });
+  }
   const events = [];
   const plugins = await loadRunnerPlugins(input.plugins, cwd);
   const extraction = await runRepositoryExtraction({
@@ -16990,6 +17094,7 @@ var runCodeExtractRunner = async (rawInput, cwd = process.cwd()) => {
     ...input.commitHash !== undefined ? { commitHash: input.commitHash } : {},
     ...input.moduleCommits ? { moduleCommits: input.moduleCommits } : {},
     ...input.pathFilter ? { pathFilter: input.pathFilter } : {},
+    ...input.entrySelection ? { entrySelection: input.entrySelection } : {},
     plugins,
     onProgress: (event) => events.push({ type: "progress", ...event })
   });
@@ -17237,7 +17342,9 @@ export {
   buildCodeSnapshot,
   SCAN_EXCLUDED_DIRS,
   PACKAGE_JSON,
+  NO_ENTRY_DETECTED,
   ExtractionPluginRegistry,
+  ExtractionInputError,
   DOCUMENT_SNAPSHOT_MANIFEST_SCHEMA_VERSION,
   DOCUMENT_EVIDENCE_NORMALIZER_VERSION,
   DEFAULT_SOURCE_SPAN_HASH_LENGTH,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/extract",
-  "version": "0.6.0-beta.4",
+  "version": "0.6.0-beta.6",
   "type": "module",
   "bin": {
     "c4a-extract-code": "./bin/c4a-extract-code.js"