agent-rules-init 0.6.1 → 0.7.0

package/dist/core/llm-bridge.js

@@ -33,38 +33,59 @@ function printArgs(assistant, model) {
         "-",
     ];
 }
-// A hung assistant (expired session, dead network) must not hang the CLI forever;
-// 10 minutes comfortably covers real enrichment runs, and on expiry the rejection
-// lands in the normal fallback path that keeps the deterministic files.
-const EXEC_TIMEOUT_MS = 600_000;
+// A hung assistant (expired session, dead network) must not hang the CLI forever.
+// Five minutes covers the verified real runs while still placing a useful upper bound;
+// callers can lower or raise it explicitly.
+export const DEFAULT_EXEC_TIMEOUT_MS = 300_000;
+const MAX_ASSISTANT_OUTPUT_CHARS = 2_000_000;
 const SAFE_WINDOWS_SHELL_ARG = /^[A-Za-z0-9._:/@+,-]+$/;
-export const defaultExecFn = (command, args, stdin, cwd) => new Promise((resolve, reject) => {
-    if (process.platform === "win32" && args.some((arg) => !SAFE_WINDOWS_SHELL_ARG.test(arg))) {
-        reject(new Error(`refusing an unsafe shell argument for ${command}`));
-        return;
-    }
-    // shell:true is only needed on Windows, to resolve npm-installed .cmd/.ps1 shims.
-    // cwd matters for enrichment: the assistant explores the repo it runs in with its
-    // own read tools, so it must be spawned at the target repo root, not wherever the
-    // CLI process happens to live.
-    const child = spawn(command, args, { shell: process.platform === "win32", cwd, timeout: EXEC_TIMEOUT_MS });
-    let stdout = "";
-    child.stdout?.on("data", (chunk) => (stdout += chunk.toString()));
-    child.on("error", reject);
-    child.on("close", (exitCode) => {
-        if (exitCode === 0)
-            resolve({ stdout, exitCode });
-        else if (child.killed)
-            reject(new Error(`${command} timed out after ${EXEC_TIMEOUT_MS / 1000}s`));
-        else
-            reject(new Error(`${command} exited with code ${exitCode}`));
+export function createDefaultExecFn(timeoutMs = DEFAULT_EXEC_TIMEOUT_MS) {
+    return (command, args, stdin, cwd) => new Promise((resolve, reject) => {
+        if (process.platform === "win32" && args.some((arg) => !SAFE_WINDOWS_SHELL_ARG.test(arg))) {
+            reject(new Error(`refusing an unsafe shell argument for ${command}`));
+            return;
+        }
+        // shell:true is only needed on Windows, to resolve npm-installed .cmd/.ps1 shims.
+        // cwd matters for enrichment: the assistant explores the repo it runs in with its
+        // own read tools, so it must be spawned at the target repo root, not wherever the
+        // CLI process happens to live.
+        const child = spawn(command, args, { shell: process.platform === "win32", cwd, timeout: timeoutMs });
+        let stdout = "";
+        let stderr = "";
+        let outputLimitExceeded = false;
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk.toString();
+            if (stdout.length > MAX_ASSISTANT_OUTPUT_CHARS) {
+                outputLimitExceeded = true;
+                child.kill();
+            }
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString();
+            if (stderr.length > MAX_ASSISTANT_OUTPUT_CHARS)
+                stderr = stderr.slice(-MAX_ASSISTANT_OUTPUT_CHARS);
+        });
+        child.on("error", reject);
+        child.on("close", (exitCode) => {
+            if (outputLimitExceeded)
+                reject(new Error(`${command} exceeded the assistant output limit`));
+            else if (exitCode === 0)
+                resolve({ stdout, stderr, exitCode });
+            else if (child.killed)
+                reject(new Error(`${command} timed out after ${timeoutMs / 1000}s`));
+            else {
+                const detail = stderr.trim().slice(-2_000).replace(/[\r\n]+/g, " ");
+                reject(new Error(`${command} exited with code ${exitCode}${detail ? `: ${detail}` : ""}`));
+            }
+        });
+        // Content always goes through stdin, never as a CLI argument: on Windows, spawn's
+        // shell:true routes the command through cmd.exe, which cannot reliably carry a
+        // multi-line, multi-KB argument (embedded newlines truncate/corrupt it). Piping
+        // via stdin has no such limit and needs no shell-quoting at all.
+        child.stdin?.end(stdin ?? "");
     });
-    // Content always goes through stdin, never as a CLI argument: on Windows, spawn's
-    // shell:true routes the command through cmd.exe, which cannot reliably carry a
-    // multi-line, multi-KB argument (embedded newlines truncate/corrupt it). Piping
-    // via stdin has no such limit and needs no shell-quoting at all.
-    child.stdin?.end(stdin ?? "");
-});
+}
+export const defaultExecFn = createDefaultExecFn();
 export async function detectAvailableAssistants(execFn = defaultExecFn) {
     const candidates = ["claude", "codex"];
     const results = await Promise.all(candidates.map(async (id) => {
@@ -131,6 +152,35 @@ function parseAssistantBatch(stdout, originals) {
 export function estimateEnrichment(files) {
     return { characters: JSON.stringify(files).length, batches: makeBatches(files).length };
 }
+export function summarizeEnrichmentChanges(originals, enriched) {
+    let changedFiles = 0;
+    let addedLines = 0;
+    let removedLines = 0;
+    for (let index = 0; index < originals.length; index++) {
+        const before = originals[index].content.split("\n");
+        const after = enriched[index]?.content.split("\n") ?? [];
+        if (originals[index].content === enriched[index]?.content)
+            continue;
+        changedFiles++;
+        const beforeCounts = new Map();
+        const afterCounts = new Map();
+        for (const line of before)
+            beforeCounts.set(line, (beforeCounts.get(line) ?? 0) + 1);
+        for (const line of after)
+            afterCounts.set(line, (afterCounts.get(line) ?? 0) + 1);
+        for (const [line, count] of afterCounts)
+            addedLines += Math.max(0, count - (beforeCounts.get(line) ?? 0));
+        for (const [line, count] of beforeCounts)
+            removedLines += Math.max(0, count - (afterCounts.get(line) ?? 0));
+    }
+    return { changedFiles, addedLines, removedLines };
+}
+class SecurityValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SecurityValidationError";
+    }
+}
 // The assistant is free-form: it may drop the one command CI actually runs and invent a
 // plausible replacement. Any lost must-keep command invalidates the whole batch.
 function assertMustKeepSurvive(enriched, originals, mustKeep) {
@@ -138,7 +188,7 @@ function assertMustKeepSurvive(enriched, originals, mustKeep) {
     const enrichedText = enriched.map((f) => f.content).join("\n");
     for (const command of mustKeep) {
         if (originalText.includes(command) && !enrichedText.includes(command)) {
-            throw new Error(`assistant dropped a canonical command: ${command}`);
+            throw new SecurityValidationError(`assistant dropped a canonical command: ${command}`);
         }
     }
 }
@@ -149,7 +199,7 @@ function assertNoNewDangerousInstructions(enriched, originals) {
     for (const line of enriched.flatMap((file) => file.content.split("\n"))) {
         const dangerous = line.match(DANGEROUS_INSTRUCTION)?.[0];
         if (dangerous && !NEGATED_DANGER.test(line) && !originalText.includes(dangerous)) {
-            throw new Error(`assistant introduced a dangerous instruction: ${dangerous}`);
+            throw new SecurityValidationError(`assistant introduced a dangerous instruction: ${dangerous}`);
         }
     }
 }
@@ -158,8 +208,54 @@ function assertNewBulletClaimsCiteEvidence(enriched, originals) {
         const originalLines = new Set(originals[index].content.split("\n").map((line) => line.trim()));
         for (const line of enriched[index].content.split("\n")) {
             const trimmed = line.trim();
-            if (/^[-*] /.test(trimmed) && !originalLines.has(trimmed) && !HAS_EVIDENCE_GROUP.test(trimmed)) {
-                throw new Error("assistant introduced a bullet claim without cited evidence");
+            if (/^[-*] /.test(trimmed) && !originalLines.has(trimmed) && checkableCitedPaths(trimmed).length === 0) {
+                throw new SecurityValidationError("assistant introduced a bullet claim without a checkable evidence path");
+            }
+        }
+    }
+}
+const PROMPT_INJECTION_LANGUAGE = /(?:ignore (?:all )?(?:previous|prior) instructions|system prompt|developer message|bypass (?:the )?(?:sandbox|permissions|safety)|disable (?:the )?(?:guardrails|validation|security)|exfiltrat|upload (?:the )?(?:secret|credential|token)|lee (?:las )?(?:variables de entorno|credenciales)|ignora (?:todas )?(?:las )?instrucciones (?:anteriores|previas)|mensaje (?:del sistema|de desarrollador))/i;
+const COMMAND_TOKEN = /`((?:npm|pnpm|yarn|bun|go|cargo|python|pytest|ruff|mvn|gradle|\.\/gradlew|dotnet|mix|composer|bundle|phpunit|make|cmake|ctest|swift|dart|flutter|sbt|Rscript)\b[^`]*)`/gi;
+const PLAIN_COMMAND = /\b((?:npm|pnpm|yarn|bun)\s+(?:run|test|install|build|lint|exec)\b[^.;\n]*|go\s+(?:test|build|run|vet|fmt|generate|get)\b[^.;\n]*|cargo\s+(?:test|build|run|clippy|fmt)\b[^.;\n]*|python\s+-m\s+\S+[^.;\n]*|(?:pytest|ruff|mvn|gradle|dotnet|mix|composer|bundle|phpunit|make|cmake|ctest|swift|dart|flutter|sbt|Rscript)\s+[^.;\n]+)/i;
+function assertNoPromptInjectionLanguage(enriched, originals) {
+    for (let index = 0; index < enriched.length; index++) {
+        const originalLines = new Set(originals[index].content.split("\n").map((line) => line.trim()));
+        for (const line of enriched[index].content.split("\n")) {
+            if (!originalLines.has(line.trim()) && PROMPT_INJECTION_LANGUAGE.test(line)) {
+                throw new SecurityValidationError("assistant introduced prompt-injection or safety-bypass language");
+            }
+        }
+    }
+}
+function assertNoUnverifiedCommands(enriched, originals, allowedCommands) {
+    const originalText = originals.map((file) => file.content).join("\n");
+    const allowed = new Set(allowedCommands.map((command) => command.trim()));
+    for (const file of enriched) {
+        for (const match of file.content.matchAll(COMMAND_TOKEN)) {
+            const command = match[1].trim();
+            if (!originalText.includes(`\`${command}\``) && !allowed.has(command)) {
+                throw new SecurityValidationError(`assistant introduced an unverified command: ${command}`);
+            }
+        }
+    }
+    for (let index = 0; index < enriched.length; index++) {
+        const originalLines = new Set(originals[index].content.split("\n").map((line) => line.trim()));
+        for (const line of enriched[index].content.split("\n")) {
+            if (originalLines.has(line.trim()))
+                continue;
+            const command = line.replace(/`[^`]*`/g, "").match(PLAIN_COMMAND)?.[1]?.replace(/[*_]/g, "").trim();
+            if (!command)
+                continue;
+            throw new SecurityValidationError(`assistant introduced an unquoted command: ${command}`);
+        }
+    }
+}
+function assertNoNewHeadings(enriched, originals) {
+    for (let index = 0; index < enriched.length; index++) {
+        const originalHeadings = new Set(originals[index].content.split("\n").filter((line) => /^#{1,6}\s+/.test(line.trim())).map((line) => line.trim()));
+        for (const heading of enriched[index].content.split("\n").filter((line) => /^#{1,6}\s+/.test(line.trim()))) {
+            if (!originalHeadings.has(heading.trim())) {
+                throw new SecurityValidationError(`assistant introduced an unapproved section: ${heading.trim()}`);
             }
         }
     }
@@ -169,10 +265,15 @@ function assistantFailureDetail(assistant, error) {
     if (/unknown (?:option|argument)|unrecognized (?:option|argument)|unexpected argument/i.test(message)) {
         return `${assistant} does not support the required read-only safety flags; update the assistant CLI`;
     }
+    if (/not (?:logged|signed) in|unauthenticated|authentication|login required|401\b/i.test(message)) {
+        return `${assistant} is installed but not authenticated; sign in with the assistant CLI and retry`;
+    }
+    if (/enotfound|econnrefused|network|timed? out|connection/i.test(message)) {
+        return `${assistant} could not reach its service; check connectivity or lower the enrichment timeout`;
+    }
     return message;
 }
 const EVIDENCE_GROUP = /\((?:evidencia|evidence):([^)]*)\)/gi;
-const HAS_EVIDENCE_GROUP = /\((?:evidencia|evidence):[^)]*\)/i;
 // A checkable citation is a plain relative path; tokens with spaces, URLs or globs are
 // left alone rather than guessed at.
 const PATH_TOKEN = /^[\w.@~-]+(?:[\\/][\w.@~-]+)*[\\/]?$/;
@@ -193,12 +294,25 @@ function checkableCitedPaths(line) {
 // prose lines are kept (removing them would mangle paragraphs) but still reported.
 function dropUnverifiableClaims(files, rootPath) {
     const missing = new Set();
+    const root = path.resolve(rootPath);
+    const evidenceExists = (relativePath) => {
+        const absolutePath = path.resolve(root, relativePath);
+        if (absolutePath === root || !absolutePath.startsWith(`${root}${path.sep}`))
+            return false;
+        try {
+            const stat = fs.lstatSync(absolutePath);
+            return stat.isFile() && !stat.isSymbolicLink();
+        }
+        catch {
+            return false;
+        }
+    };
     const checked = files.map((file) => {
         const kept = file.content.split("\n").filter((line) => {
             const cited = checkableCitedPaths(line);
             if (cited.length === 0)
                 return true;
-            if (cited.some((p) => fs.existsSync(path.join(rootPath, p))))
+            if (cited.some(evidenceExists))
                 return true;
             for (const p of cited)
                 missing.add(p);
@@ -214,7 +328,7 @@ function dropUnverifiableClaims(files, rootPath) {
  * process; only very large outputs are split. Falls back to the originals per batch.
  */
 export async function enrichFilesWithAssistant(assistant, files, options = {}) {
-    const { execFn = defaultExecFn, lang = "es", cwd, mustKeep = [], existingDocs = [], model, onMetrics } = options;
+    const { execFn = defaultExecFn, lang = "es", cwd, mustKeep = [], existingDocs = [], model, maxAttempts = 2, onMetrics, } = options;
     const existingDocsJson = existingDocs.length > 0 ? JSON.stringify(existingDocs) : undefined;
     const enriched = [];
     const batches = makeBatches(files);
@@ -223,12 +337,13 @@ export async function enrichFilesWithAssistant(assistant, files, options = {}) {
     let fallbackBatches = 0;
     let inputChars = 0;
     let outputChars = 0;
+    let securityRejections = 0;
     for (const batch of batches) {
         const input = UI[lang].enrichPrompt(JSON.stringify(batch), mustKeep, existingDocsJson);
         let attemptInput = input;
         // Contract violations (invalid JSON, changed paths, dropped commands) are stochastic,
         // especially with smaller models; one bounded retry recovers most of them.
-        let attemptsLeft = 2;
+        let attemptsLeft = Math.max(1, Math.min(3, maxAttempts));
         while (attemptsLeft > 0) {
             attemptsLeft--;
             attempts++;
@@ -240,6 +355,9 @@ export async function enrichFilesWithAssistant(assistant, files, options = {}) {
                 assertMustKeepSurvive(parsed, batch, mustKeep);
                 assertNoNewDangerousInstructions(parsed, batch);
                 assertNewBulletClaimsCiteEvidence(parsed, batch);
+                assertNoPromptInjectionLanguage(parsed, batch);
+                assertNoUnverifiedCommands(parsed, batch, mustKeep);
+                assertNoNewHeadings(parsed, batch);
                 if (cwd) {
                     const verified = dropUnverifiableClaims(parsed, cwd);
                     if (verified.missing.length > 0)
@@ -250,6 +368,8 @@ export async function enrichFilesWithAssistant(assistant, files, options = {}) {
                 break;
             }
             catch (err) {
+                if (err instanceof SecurityValidationError)
+                    securityRejections++;
                 if (attemptsLeft > 0) {
                     const detail = assistantFailureDetail(assistant, err);
                     attemptInput = `${input}\n\nYour previous response was rejected: ${detail}. Correct that exact problem and return the required JSON array only.`;
@@ -263,6 +383,7 @@ export async function enrichFilesWithAssistant(assistant, files, options = {}) {
             }
         }
     }
+    const changes = summarizeEnrichmentChanges(files, enriched);
     onMetrics?.({
         assistant,
         model,
@@ -272,6 +393,9 @@ export async function enrichFilesWithAssistant(assistant, files, options = {}) {
         inputChars,
         outputChars,
         durationMs: Date.now() - startedAt,
+        cacheHit: false,
+        ...changes,
+        securityRejections,
     });
     return enriched;
 }

package/dist/core/project-units.js

@@ -57,7 +57,8 @@ export function applyProjectExcludes(signals, patterns) {
     };
 }
 function withoutLocation(manifest) {
-    const { path: _path, ...packageJson } = manifest;
+    const packageJson = { ...manifest };
+    delete packageJson.path;
     return packageJson;
 }
 /**

package/dist/core/prompt-engine.d.ts

@@ -1,15 +1,6 @@
-import { type Lang } from "./i18n.js";
-import type { DetectionResult } from "./types.js";
-export type QuestionField = "framework" | "testRunner" | "linter" | "packageManager";
-export interface Question {
-    packId: string;
-    field: QuestionField;
-    message: string;
-}
-export declare function collectLowConfidenceQuestions(detections: DetectionResult[], lang: Lang): Question[];
+/**
+ * Kept as a compatibility type for callers that supplied a custom clarification
+ * prompt before 0.6.2. Project metadata is no longer requested interactively.
+ */
 export type PromptFn = (message: string) => Promise<string>;
 export declare function hasInteractiveTty(): boolean;
-export declare function makeDefaultPromptFn(lang: Lang): PromptFn;
-export declare const defaultPromptFn: PromptFn;
-export declare function askQuestions(questions: Question[], promptFn?: PromptFn): Promise<Record<string, string>>;
-export declare function applyAnswers(detections: DetectionResult[], answers: Record<string, string>): DetectionResult[];

package/dist/core/prompt-engine.js

@@ -1,57 +1,3 @@
-import * as clack from "@clack/prompts";
-import { UI, detectLang } from "./i18n.js";
-const FIELDS = ["framework", "testRunner", "linter", "packageManager"];
-export function collectLowConfidenceQuestions(detections, lang) {
-    const ui = UI[lang];
-    const questions = [];
-    for (const detection of detections) {
-        for (const field of FIELDS) {
-            const detectionField = detection[field];
-            if (detectionField && detectionField.confidence === "low") {
-                questions.push({
-                    packId: detection.packId,
-                    field,
-                    message: ui.question(ui.fieldLabels[field], detection.language),
-                });
-            }
-        }
-    }
-    return questions;
-}
 export function hasInteractiveTty() {
     return Boolean(process.stdin.isTTY && process.stdout.isTTY);
 }
-export function makeDefaultPromptFn(lang) {
-    return async (message) => {
-        if (!hasInteractiveTty()) {
-            console.warn(UI[lang].skippedQuestion(message));
-            return "";
-        }
-        const answer = await clack.text({ message });
-        if (clack.isCancel(answer)) {
-            clack.cancel(UI[lang].cancelled);
-            process.exit(1);
-        }
-        return answer;
-    };
-}
-export const defaultPromptFn = (message) => makeDefaultPromptFn(detectLang())(message);
-export async function askQuestions(questions, promptFn = defaultPromptFn) {
-    const answers = {};
-    for (const question of questions) {
-        answers[`${question.packId}:${question.field}`] = await promptFn(question.message);
-    }
-    return answers;
-}
-export function applyAnswers(detections, answers) {
-    return detections.map((detection) => {
-        const updated = { ...detection };
-        for (const field of FIELDS) {
-            const answer = answers[`${detection.packId}:${field}`];
-            if (answer) {
-                updated[field] = { value: answer, confidence: "high" };
-            }
-        }
-        return updated;
-    });
-}

package/dist/core/scanner-async.d.ts

@@ -0,0 +1,4 @@
+import type { RepoSignals } from "./types.js";
+import type { ScanOptions } from "./scanner.js";
+/** Runs full repository discovery off the main event loop in the published CLI. */
+export declare function scanRepoInWorker(rootPath: string, options?: ScanOptions, timeoutMs?: number): Promise<RepoSignals>;

package/dist/core/scanner-async.js

@@ -0,0 +1,55 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Worker } from "node:worker_threads";
+function restoreSignals(signals) {
+    const normalizedFiles = new Set(signals.files.map((file) => file.split(path.sep).join("/")));
+    return {
+        ...signals,
+        hasFile: (relativePath) => normalizedFiles.has(relativePath.split(path.sep).join("/")),
+        hasDir: (relativeDir) => {
+            try {
+                return fs.statSync(path.join(signals.rootPath, relativeDir)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+/** Runs full repository discovery off the main event loop in the published CLI. */
+export function scanRepoInWorker(rootPath, options = {}, timeoutMs = 30_000) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const worker = new Worker(new URL("./scanner-worker.js", import.meta.url), {
+            workerData: { rootPath, options },
+        });
+        const finish = (action) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            action();
+        };
+        const timer = setTimeout(() => {
+            void worker.terminate();
+            finish(() => reject(new Error(`repository scanner worker timed out after ${timeoutMs / 1000}s`)));
+        }, timeoutMs);
+        worker.once("message", (message) => {
+            finish(() => {
+                if (message.ok) {
+                    const restored = restoreSignals(message.signals);
+                    if (restored.scanStats)
+                        restored.scanStats.mode = "worker";
+                    resolve(restored);
+                }
+                else
+                    reject(new Error(`repository scanner worker failed: ${message.error}`));
+            });
+        });
+        worker.once("error", (error) => finish(() => reject(error)));
+        worker.once("exit", (code) => {
+            if (code !== 0)
+                finish(() => reject(new Error(`repository scanner worker exited with code ${code}`)));
+        });
+    });
+}

package/dist/core/scanner-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/scanner-worker.js

@@ -0,0 +1,17 @@
+import { parentPort, workerData } from "node:worker_threads";
+import { scanRepo } from "./scanner.js";
+if (!parentPort)
+    throw new Error("scanner worker must run inside a worker thread");
+try {
+    const input = workerData;
+    const serializable = { ...scanRepo(input.rootPath, input.options) };
+    delete serializable.hasFile;
+    delete serializable.hasDir;
+    parentPort.postMessage({ ok: true, signals: serializable });
+}
+catch (error) {
+    parentPort.postMessage({
+        ok: false,
+        error: error instanceof Error ? error.message : String(error),
+    });
+}

package/dist/core/scanner.d.ts

@@ -1,2 +1,6 @@
 import type { RepoSignals } from "./types.js";
-export declare function scanRepo(rootPath: string): RepoSignals;
+export interface ScanOptions {
+    maxDepth?: number;
+    maxFiles?: number;
+}
+export declare function scanRepo(rootPath: string, options?: ScanOptions): RepoSignals;

package/dist/core/scanner.js

@@ -8,12 +8,20 @@ const IGNORED_DIRS = new Set([
     ".gradle", ".dart_tool",
     ".agent-rules-init",
 ]);
-const MAX_DEPTH = 4;
-function walk(rootPath) {
+const DEFAULT_MAX_DEPTH = 12;
+const DEFAULT_MAX_FILES = 100_000;
+function walk(rootPath, options) {
     const results = [];
+    const warnings = new Set();
+    const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES;
     function recurse(dir, depth) {
-        if (depth > MAX_DEPTH)
+        if (results.length >= maxFiles)
             return;
+        if (depth > maxDepth) {
+            warnings.add(`Repository scan reached maxDepth=${maxDepth}; some nested files were skipped.`);
+            return;
+        }
         let entries;
         try {
             entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -34,11 +42,15 @@ function walk(rootPath) {
                 if (entry.name.includes(".generated."))
                     continue;
                 results.push(path.relative(rootPath, path.join(dir, entry.name)));
+                if (results.length >= maxFiles) {
+                    warnings.add(`Repository scan reached maxFiles=${maxFiles}; remaining files were skipped.`);
+                    return;
+                }
             }
         }
     }
     recurse(rootPath, 0);
-    return results;
+    return { files: results, warnings: [...warnings] };
 }
 // Windows editors (Notepad, PowerShell's Set-Content, some IDE defaults) save UTF-8
 // with a leading BOM, which JSON.parse rejects and line-anchored regexes trip over.
@@ -58,15 +70,20 @@ function readJsonIfExists(filePath) {
 function toPackageJsonManifest(raw, relativePath) {
     return {
         path: relativePath.split(path.sep).join("/"),
-        name: raw.name,
+        name: typeof raw.name === "string" ? raw.name : undefined,
         main: typeof raw.main === "string" ? raw.main : undefined,
-        dependencies: raw.dependencies ?? {},
-        devDependencies: raw.devDependencies ?? {},
-        scripts: raw.scripts ?? {},
+        dependencies: stringRecord(raw.dependencies),
+        devDependencies: stringRecord(raw.devDependencies),
+        scripts: stringRecord(raw.scripts),
         moduleType: raw.type === "module" ? "module" : "commonjs",
         packageManager: parsePackageManager(raw.packageManager),
     };
 }
+function stringRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return {};
+    return Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === "string"));
+}
 function parsePackageManager(value) {
     if (typeof value !== "string")
         return undefined;
@@ -166,8 +183,10 @@ function readAllConcatenated(rootPath, relativePaths) {
 function pickShallowest(paths) {
     return shallowest(paths.filter((p) => p !== undefined));
 }
-export function scanRepo(rootPath) {
-    const files = walk(rootPath);
+export function scanRepo(rootPath, options = {}) {
+    const startedAt = performance.now();
+    const walked = walk(rootPath, options);
+    const files = walked.files;
     const fileSet = new Set(files.map((f) => f.split(path.sep).join("/")));
     // Keep every project package manifest, not only the root workspace manifest. Root
     // package.json files are often workspace glue and contain none of the dependencies
@@ -278,6 +297,12 @@ export function scanRepo(rootPath) {
         const normalized = file.split(path.sep).join("/");
         return guidanceNames.has(path.posix.basename(normalized));
     });
+    const scanStats = {
+        files: files.length,
+        durationMs: Math.round((performance.now() - startedAt) * 100) / 100,
+        truncated: walked.warnings.length > 0,
+        mode: "sync",
+    };
     return {
         rootPath,
         files,
@@ -318,5 +343,7 @@ export function scanRepo(rootPath) {
         guidanceFiles: guidancePaths
             .map((p) => ({ path: p.split(path.sep).join("/"), content: readTextIfExists(path.join(rootPath, p)) }))
             .filter((f) => f.content !== undefined),
+        scanWarnings: walked.warnings,
+        scanStats,
     };
 }

package/dist/core/types.d.ts

@@ -53,6 +53,14 @@ export interface RepoSignals {
         path: string;
         content: string;
     }[];
+    /** Non-fatal conditions that may make repository detection incomplete. */
+    scanWarnings?: string[];
+    scanStats?: {
+        files: number;
+        durationMs: number;
+        truncated: boolean;
+        mode?: "sync" | "worker" | "sync-fallback";
+    };
 }
 export type Confidence = "high" | "low";
 export interface DetectionField<T> {

package/dist/packs/index.d.ts

@@ -0,0 +1,3 @@
+import type { Pack } from "../core/types.js";
+export declare const ALL_PACKS: readonly Pack[];
+export declare function findPack(id: string): Pack;

package/dist/packs/index.js

@@ -0,0 +1,25 @@
+import { cppPack } from "./cpp.js";
+import { csharpPack } from "./csharp.js";
+import { dartPack } from "./dart.js";
+import { elixirPack } from "./elixir.js";
+import { goPack } from "./go.js";
+import { javaPack } from "./java.js";
+import { jsTsPack } from "./js-ts.js";
+import { kotlinPack } from "./kotlin.js";
+import { phpPack } from "./php.js";
+import { pythonPack } from "./python.js";
+import { rPack } from "./r.js";
+import { rubyPack } from "./ruby.js";
+import { rustPack } from "./rust.js";
+import { scalaPack } from "./scala.js";
+import { swiftPack } from "./swift.js";
+export const ALL_PACKS = [
+    jsTsPack, pythonPack, javaPack, phpPack, rubyPack, goPack, rustPack, csharpPack,
+    kotlinPack, swiftPack, dartPack, cppPack, elixirPack, scalaPack, rPack,
+];
+export function findPack(id) {
+    const pack = ALL_PACKS.find((candidate) => candidate.id === id);
+    if (!pack)
+        throw new Error(`Unknown pack: ${id}`);
+    return pack;
+}

package/dist/packs/java.js

@@ -17,7 +17,7 @@ function detect(signals) {
     if ((signals.buildGradle && /\bkotlin\b/i.test(signals.buildGradle)) ||
         (signals.pomXml && /\bkotlin\b/i.test(signals.pomXml)))
         return null;
-    const framework = /spring/i.test(source)
+    const framework = /(?:org\.springframework|spring-boot|springframework)/i.test(source)
         ? { value: "spring", confidence: "high" }
         : { value: "none", confidence: "low" };
     const packageManager = signals.pomXml