codecartographer-pi 0.22.3 → 0.23.0

package/.codecarto/broadside/SKILL.md

@@ -86,6 +86,21 @@ Submits pre-flight the chosen model: pricing comes from the live catalog
 model that does not advertise structured-output support is refused outright,
 because every lens depends on `json_schema` response_format.
 
+Each lens reads a scope of the repository. Architecture reads the manifest,
+entry point, README, and file tree; defect, conventions, and porting read
+every source file; the **security** and **API** lenses target where the
+trust boundary usually lives — `server/**`, `**/auth*`, `**/middleware/**`,
+`SECURITY.md` (security) and `server/**`, `api/**`, `src/server/**`,
+`src/api/**`, `**/*routes*`, `**/*router*`, `**/*handler*`, `**/*endpoint*`
+(API). A repository whose server is `src/server.js` matches none of those, so
+when the targeted patterns find nothing those two lenses **fall back to every
+source file** — priced as such, chunked at the lens's slice size rather than
+truncated, and said so on the lens line of the estimate, the submit report,
+`status`, and the prompt the model receives. A lens whose targeted patterns
+and fallback both find nothing (only test files, say) is skipped with a line
+naming both. `max_cost` is the guard against a fallback scan on a large
+repository being more than you meant to spend.
+
 Collect runs two cross-lens post-passes by default: **synthesis** (the
 executive report) and **triage** (the prioritized work order). Pass
 `include_synthesis: false` or `include_triage: false` on collect to skip one.

package/.codecarto/workflow/scaffold-version.yaml

@@ -3,4 +3,4 @@
 # workspace's framework-owned files (GUIDE.md, templates/, workflow/ pipelines
 # and VALIDATE.md) predate the running release. Written at release time and
 # copied verbatim by init — never edit by hand.
-scaffold_version: 0.22.3
+scaffold_version: 0.23.0

package/README.md

@@ -383,7 +383,7 @@ Each workflow tool accepts an absolute `cwd` for the target repository. `codecar
 
 ## Broad-Side (batch reconnaissance)
 
-Broad-Side is the cheap sweep you run *before* the expensive interactive run. It fires six analysis lenses — architecture, API surface, security, mechanical defect scan, convention extraction, porting — at a repository as single-turn prompts over the [OpenRouter Batch API](https://openrouter.ai/docs), then cross-references them into one executive report (`synthesis.md`) and a prioritized P0–P3 work order (`triage.md`).
+Broad-Side is the cheap sweep you run *before* the expensive interactive run. It fires six analysis lenses — architecture, API surface, security, mechanical defect scan, convention extraction, porting — at a repository as single-turn prompts over the [OpenRouter Batch API](https://openrouter.ai/docs), then cross-references them into one executive report (`synthesis.md`) and a prioritized P0–P3 work order (`triage.md`). The security and API lenses target the paths where a trust boundary usually lives (`server/`, `auth*`, `middleware/`, routers and handlers) and fall back to every source file when a repository has none of them — priced as such, and said so on the estimate — so a service whose server is `src/server.js` still gets its security review.
 
 **Broad-Side findings are unverified scouting leads, not evidence.** Each lens is one shot: no cross-file traversal, no runtime verification, no builds, no tests. Every finding is a `file:line` pointer that the interactive pipeline — or you — must confirm before it is a fact. That division of labor is the point: a sub-dollar unattended sweep that tells the expensive run where to look. Nothing downstream may cite a Broad-Side report as a source.
 

package/dist/core/broadside.d.ts

@@ -121,6 +121,12 @@ export type FileSlice = {
     redactedValues?: number;
     /** The files in this slice that had at least one value redacted. */
     redactedFiles?: string[];
+    /**
+     * Set when the lens's targeted globs matched nothing and the slice was
+     * built from its fallback globs instead (#319). The estimate, the batch
+     * entry, and the prompt all say so.
+     */
+    fallback?: string;
 };
 /**
  * OpenRouter's unified `reasoning` control, as sent on a lens request.
@@ -203,6 +209,12 @@ export type BroadsideBatchEntry = {
     error?: unknown;
     /** Why a `skipped` lens had nothing to submit: the globs that matched no file. */
     reason?: string;
+    /**
+     * Set when the lens scanned its fallback scope because its targeted globs
+     * matched nothing (#319): "no files matched …; scanned all javascript
+     * sources instead". Absent for a targeted scan.
+     */
+    fallback?: string;
     /** Set when this lens used a model other than the run default. */
     model?: string;
     /** The completion ceiling of this lens's model; bounds the truncation retry. */
@@ -348,6 +360,8 @@ export type BroadsideEstimate = {
         /** The model this lens would use — `model` unless a per-lens override applies. */
         model: string;
         pricing: ModelPricing;
+        /** Set when this lens is priced on its fallback scope (#319); see BroadsideBatchEntry.fallback. */
+        fallback?: string;
     }>;
     /** True when at least one lens uses a model other than the run default. */
     mixedModels: boolean;
@@ -490,6 +504,15 @@ type LensDefinition = {
     reasoning?: BroadsideReasoning;
     skipTestFiles?: boolean;
     globsFor: (info: RepoInfo) => string[];
+    /**
+     * Where to look when `globsFor` matches nothing (#319). The security and
+     * api lenses target server/, auth, and middleware paths because that is
+     * where the trust boundary usually lives; a service whose server is
+     * `src/server.js` matched none of them and got no security review at all.
+     * The fallback is the language's whole source set — priced as such, and
+     * said so in the estimate, the run record, and the prompt.
+     */
+    fallbackGlobsFor?: (info: RepoInfo) => string[];
     systemPrompt: (info: RepoInfo) => string;
     userPrompt: (info: RepoInfo, source: string, moduleName: string) => string;
 };
@@ -500,6 +523,20 @@ export declare const BROADSIDE_LANGUAGES: readonly ["go", "python", "rust", "typ
 export declare function collectRepoInfo(targetDir: string, opts?: {
     redact?: boolean;
 }): Promise<RepoInfo>;
+type CollectedFile = {
+    relPath: string;
+    moduleName: string;
+};
+/**
+ * The files a lens will read: its targeted globs, or — when those match
+ * nothing and the lens declares a fallback — the fallback globs, with a
+ * sentence saying so (#319). The sentence travels to the estimate, the
+ * batch entry, and the prompt, so a fallback scan is never a silent one.
+ */
+export declare function selectLensFiles(allFiles: string[], lens: LensDefinition, info: RepoInfo): {
+    files: CollectedFile[];
+    fallback?: string;
+};
 export declare function gatherSlices(targetDir: string, lens: LensDefinition, info: RepoInfo, opts?: {
     redact?: boolean;
 }): Promise<FileSlice[]>;

package/dist/core/broadside.js

@@ -698,6 +698,7 @@ const LENSES = {
                 "**/*handler*",
                 "**/*endpoint*",
             ],
+        fallbackGlobsFor: (info) => [info.sourceGlob],
         systemPrompt: () => "You are a senior API auditor. Given source files from an HTTP server, " +
             "extract every HTTP endpoint (method, path, handler function, auth requirement) " +
             "and every key request/response data type. Return a JSON object following the " +
@@ -718,6 +719,7 @@ const LENSES = {
         globsFor: (info) => info.language === "go"
             ? ["server/**/*.go", "server/*.go", "**/auth*.go", "**/middleware/**/*.go", "SECURITY.md"]
             : ["server/**", "**/auth*", "**/middleware/**", "SECURITY.md"],
+        fallbackGlobsFor: (info) => [info.sourceGlob],
         systemPrompt: () => "You are a security engineer performing a first-pass review of a codebase. " +
             "Given source files, identify potential security issues — focusing on " +
             "authentication, authorization, input validation, TLS, secrets handling, " +
@@ -1237,8 +1239,7 @@ function resolveSliceMode(lens, files, totalChars) {
         return lens.sliceBy;
     return totalChars > lens.maxChars ? "directory" : "none";
 }
-function collectLensFiles(allFiles, lens, info) {
-    const globs = lens.globsFor(info).filter(Boolean);
+function collectFilesMatching(allFiles, lens, globs) {
     if (globs.length === 0)
         return [];
     const out = [];
@@ -1253,6 +1254,30 @@ function collectLensFiles(allFiles, lens, info) {
     }
     return out;
 }
+/**
+ * The files a lens will read: its targeted globs, or — when those match
+ * nothing and the lens declares a fallback — the fallback globs, with a
+ * sentence saying so (#319). The sentence travels to the estimate, the
+ * batch entry, and the prompt, so a fallback scan is never a silent one.
+ */
+export function selectLensFiles(allFiles, lens, info) {
+    const globs = lens.globsFor(info).filter(Boolean);
+    const targeted = collectFilesMatching(allFiles, lens, globs);
+    if (targeted.length > 0 || globs.length === 0 || !lens.fallbackGlobsFor)
+        return { files: targeted };
+    const fallbackGlobs = lens.fallbackGlobsFor(info).filter(Boolean);
+    const files = collectFilesMatching(allFiles, lens, fallbackGlobs);
+    if (files.length === 0)
+        return { files };
+    return {
+        files,
+        fallback: `no files matched ${globs.join(", ")}${lens.skipTestFiles ? " (test files excluded)" : ""}; ` +
+            `scanned all ${info.language} sources (${fallbackGlobs.join(", ")}) instead`,
+    };
+}
+function collectLensFiles(allFiles, lens, info) {
+    return selectLensFiles(allFiles, lens, info).files;
+}
 async function slurpFileList(targetDir, files, maxChars, redact = true) {
     const slices = [];
     let currentModule = "";
@@ -1329,16 +1354,18 @@ export async function gatherSlices(targetDir, lens, info, opts = {}) {
         return [{ moduleName: "root", content: "", fileCount: 0, chars: 0, files: [] }];
     }
     const { files: allFiles } = await listRepoFiles(targetDir);
-    const files = collectLensFiles(allFiles, lens, info);
+    const { files, fallback } = selectLensFiles(allFiles, lens, info);
     const totalChars = await sumFileSizes(targetDir, files);
     const mode = resolveSliceMode(lens, files, totalChars);
-    if (mode === "none") {
+    const slices = mode === "none"
         // Whole-repo slice: one module named after the repo, so a small
         // repo produces a single request instead of one per directory.
-        const single = files.map((f) => ({ ...f, moduleName: info.name }));
-        return slurpFileList(targetDir, single, lens.maxChars, redact);
-    }
-    return slurpFileList(targetDir, files, lens.maxChars, redact);
+        ? await slurpFileList(targetDir, files.map((f) => ({ ...f, moduleName: info.name })), lens.maxChars, redact)
+        : await slurpFileList(targetDir, files, lens.maxChars, redact);
+    if (fallback)
+        for (const slice of slices)
+            slice.fallback = fallback;
+    return slices;
 }
 async function sumFileSizes(targetDir, files) {
     let total = 0;
@@ -1362,7 +1389,17 @@ export function buildBatchRequest(lens, info, slice, index, sliceCount, model =
             model,
             messages: [
                 { role: "system", content: lens.systemPrompt(info) },
-                { role: "user", content: lens.userPrompt(info, slice.content, slice.moduleName) },
+                {
+                    role: "user",
+                    content: 
+                    // A fallback scan is not "server source files": say what it is,
+                    // so the model judges the trust boundary wherever it appears
+                    // and does not report the missing server/ as a finding (#319).
+                    (slice.fallback
+                        ? `NOTE: this repository has no files under the paths this lens usually reads (${slice.fallback}). ` +
+                            "What follows is every source file it has; locate the trust boundary and the request-handling code wherever they live.\n\n"
+                        : "") + lens.userPrompt(info, slice.content, slice.moduleName),
+                },
             ],
             response_format: { type: "json_schema", json_schema: SCHEMAS[lens.schemaName] },
             max_tokens: maxTokensOverride ?? lens.maxTokens,
@@ -2320,11 +2357,14 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
         slicesByLens.set(lensId, slices);
         if (slices.length === 0) {
             const globs = lens.globsFor(info).filter(Boolean);
+            const fallbackGlobs = lens.fallbackGlobsFor?.(info).filter(Boolean) ?? [];
             skipReasons.set(lensId, globs.length === 0
                 ? "the lens has no file patterns for this language"
                 : matchedBeforeIncremental > 0
                     ? "incremental: none of this lens's files changed since the previous run"
-                    : `no files matched ${globs.join(", ")}${lens.skipTestFiles ? " (test files excluded)" : ""}`);
+                    : `no files matched ${globs.join(", ")}` +
+                        (fallbackGlobs.length > 0 ? ` or the fallback ${fallbackGlobs.join(", ")}` : "") +
+                        (lens.skipTestFiles ? " (test files excluded)" : ""));
         }
         const lensModel = modelForLens(lensId);
         const { pricing: lensPricing, outputCap: lensOutputCap } = resolved.get(lensModel);
@@ -2347,15 +2387,19 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
         const approved = await opts.confirm({
             model,
             pricing,
-            lenses: perLensEstimate.map(({ lens, cost, maxTokens, lensModel, lensPricing }) => ({
-                lensId: lens.id,
-                name: lens.name,
-                slices: (slicesByLens.get(lens.id) ?? []).length,
-                maxTokens,
-                cost,
-                model: lensModel,
-                pricing: lensPricing,
-            })),
+            lenses: perLensEstimate.map(({ lens, cost, maxTokens, lensModel, lensPricing }) => {
+                const fallback = (slicesByLens.get(lens.id) ?? []).find((slice) => slice.fallback)?.fallback;
+                return {
+                    lensId: lens.id,
+                    name: lens.name,
+                    slices: (slicesByLens.get(lens.id) ?? []).length,
+                    maxTokens,
+                    cost,
+                    model: lensModel,
+                    pricing: lensPricing,
+                    ...(fallback && { fallback }),
+                };
+            }),
             mixedModels: perLensEstimate.some(({ lensModel }) => lensModel !== model),
             totalCost: estimatedTotalCost,
             inputTokens: estimatedInputTokens,
@@ -2419,12 +2463,15 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
         const requests = slices.map((sl, i) => buildBatchRequest(lens, info, sl, i, slices.length, lensModel, maxTokens, config.reasoning ?? undefined));
         for (const request of requests)
             requestsByCustomId[request.custom_id] = request;
+        const fallback = slices.find((slice) => slice.fallback)?.fallback;
         const entry = {
             batchId: "",
             requests: requests.length,
             status: "submitting",
             submittedAt: new Date().toISOString(),
             estimatedCost: priced.cost,
+            // A scan of the fallback scope is recorded as such (#319).
+            ...(fallback && { fallback }),
             // Recorded per lens so collect's truncation retry re-submits against
             // the model and ceiling this lens actually used, not the run default.
             ...(lensModel !== model && { model: lensModel }),
@@ -3256,7 +3303,9 @@ export function estimateSubmitText(result, lenses) {
             ? ` — ${explainBatchError(entry.error)}`
             : !entry.batchId && entry.reason
                 ? ` — ${entry.reason}`
-                : "";
+                : entry.fallback
+                    ? ` — ${entry.fallback}`
+                    : "";
         lines.push(`  ${lens.name}: ${status} (${entry.requests} request(s), ~$${entry.estimatedCost.toFixed(4)})${override}${reason}`);
     }
     if (result.repo) {
@@ -3492,7 +3541,7 @@ export function statusText(state) {
             if (!entry)
                 continue;
             lines.push(`  ${lensId}: ${entry.status}${entry.batchId ? ` (${entry.batchId})` : ""}${entry.cost !== undefined ? `, $${entry.cost.toFixed(6)}` : ""}` +
-                (entry.status === "skipped" && entry.reason ? ` — ${entry.reason}` : ""));
+                (entry.status === "skipped" && entry.reason ? ` — ${entry.reason}` : entry.fallback ? ` — ${entry.fallback}` : ""));
         }
         lines.push(`  synthesis: ${run.synthesis.status}`);
         lines.push(`  triage: ${run.triage?.status ?? "pending"}`);

package/dist/extensions/codecarto/index.js

@@ -130,11 +130,14 @@ function describeBroadsideEstimate(estimate) {
         `Rates: $${estimate.pricing.inputPerM.toFixed(4)}/M in · $${estimate.pricing.outputPerM.toFixed(4)}/M out`,
         "",
         "Per lens:",
-        ...estimate.lenses.map(({ name, slices, cost, model }) => {
+        ...estimate.lenses.map(({ name, slices, cost, model, fallback }) => {
             // Naming the model only when it differs keeps the common case quiet
             // and makes a mixed-model run impossible to approve without noticing.
             const override = estimate.mixedModels && model !== estimate.model ? ` on ${model}` : "";
-            return `  ${name}: ${slices} slice${slices === 1 ? "" : "s"} — ~$${cost.toFixed(4)}${override}`;
+            // A lens priced on its fallback scope says so here, where the
+            // spend is approved — every source file, not a server directory (#319).
+            const scope = fallback ? `\n    ↳ ${fallback}` : "";
+            return `  ${name}: ${slices} slice${slices === 1 ? "" : "s"} — ~$${cost.toFixed(4)}${override}${scope}`;
         }),
         "",
         `Estimated total: ~$${estimate.totalCost.toFixed(4)} ` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.22.3",
+  "version": "0.23.0",
   "mcpName": "io.github.HuginnIndustries/codecartographer",
   "description": "Turn an unfamiliar codebase into a validated reimplementation spec, then synthesize confirmed specs and a product vision into a traceable plan.",
   "type": "module",