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

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

@@ -16405,9 +16405,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 +16643,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 +16996,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 +17008,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 +17063,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 +17075,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 +17323,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.5",
   "type": "module",
   "bin": {
     "c4a-extract-code": "./bin/c4a-extract-code.js"