javi-forge 1.26.0 → 1.27.0

package/dist/lib/context.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import fs from "fs-extra";
 import { STACK_CONTEXT_MAP } from "../constants.js";
+import { describeSafeReadFailure, safeReadFile } from "./safe-read.js";
 // =============================================================================
 // Internal helpers
 // =============================================================================
@@ -53,95 +54,135 @@ ${stack}-based project scaffolded with javi-forge.
 // =============================================================================
 // Dependency detection
 // =============================================================================
+const MAX_DEPS = 10;
 /**
- * Detect top-level dependencies from project manifest files.
- * Returns up to 10 dependency names (key deps only, not devDeps).
+ * Byte ceiling for a dependency manifest. A package.json or go.mod past this is
+ * not a manifest we can learn anything useful from — it is generated noise.
  */
-export async function detectDependencies(projectDir, stack) {
-    const MAX_DEPS = 10;
-    try {
-        switch (stack) {
-            case "node": {
-                const pkgPath = path.join(projectDir, "package.json");
-                if (!(await fs.pathExists(pkgPath)))
-                    return [];
-                const pkg = await fs.readJson(pkgPath).catch(() => ({}));
-                const deps = Object.keys(pkg.dependencies ?? {});
-                return deps.slice(0, MAX_DEPS);
+const MAX_MANIFEST_BYTES = 512 * 1024;
+/** Read a manifest under a byte budget; returns null and a warning on failure. */
+async function readManifest(manifestPath, warnings) {
+    const read = await safeReadFile(manifestPath, {
+        hardRejectOverBytes: MAX_MANIFEST_BYTES,
+    });
+    if (!read.ok) {
+        warnings.push(`${path.basename(manifestPath)}: ${describeSafeReadFailure(read)}`);
+        return null;
+    }
+    if (read.truncated) {
+        warnings.push(`${path.basename(manifestPath)}: truncated at ${read.bytesRead} of ${read.totalBytes} bytes`);
+    }
+    return read.content;
+}
+/**
+ * Detect top-level dependencies from project manifest files, reporting why a
+ * manifest was skipped. Returns up to 10 dependency names (key deps only).
+ */
+export async function detectDependenciesDetailed(projectDir, stack) {
+    const warnings = [];
+    switch (stack) {
+        case "node": {
+            const pkgPath = path.join(projectDir, "package.json");
+            if (!(await fs.pathExists(pkgPath)))
+                return { dependencies: [], warnings };
+            const content = await readManifest(pkgPath, warnings);
+            if (content === null)
+                return { dependencies: [], warnings };
+            let pkg;
+            try {
+                pkg = JSON.parse(content);
             }
-            case "python": {
-                const pyprojectPath = path.join(projectDir, "pyproject.toml");
-                if (await fs.pathExists(pyprojectPath)) {
-                    const content = await fs.readFile(pyprojectPath, "utf-8");
-                    const match = content.match(/dependencies\s*=\s*\[([\s\S]*?)\]/);
-                    if (match?.[1]) {
-                        const deps = match[1]
-                            .split("\n")
-                            .map((l) => l.replace(/[",]/g, "").trim())
-                            .filter((l) => l.length > 0 && !l.startsWith("#"))
-                            .map((l) => l.split(/[>=<~!]/)[0].trim())
-                            .filter(Boolean);
-                        return deps.slice(0, MAX_DEPS);
-                    }
-                }
-                const reqPath = path.join(projectDir, "requirements.txt");
-                if (await fs.pathExists(reqPath)) {
-                    const content = await fs.readFile(reqPath, "utf-8");
-                    const deps = content
+            catch (err) {
+                warnings.push(`package.json: invalid JSON (${err instanceof Error ? err.message : String(err)})`);
+                return { dependencies: [], warnings };
+            }
+            const deps = Object.keys(pkg?.dependencies ?? {});
+            return { dependencies: deps.slice(0, MAX_DEPS), warnings };
+        }
+        case "python": {
+            const pyprojectPath = path.join(projectDir, "pyproject.toml");
+            if (await fs.pathExists(pyprojectPath)) {
+                const content = await readManifest(pyprojectPath, warnings);
+                const match = content?.match(/dependencies\s*=\s*\[([\s\S]*?)\]/);
+                if (match?.[1]) {
+                    const deps = match[1]
                         .split("\n")
-                        .map((l) => l.trim())
-                        .filter((l) => l.length > 0 && !l.startsWith("#") && !l.startsWith("-"))
+                        .map((l) => l.replace(/[",]/g, "").trim())
+                        .filter((l) => l.length > 0 && !l.startsWith("#"))
                         .map((l) => l.split(/[>=<~!]/)[0].trim())
                         .filter(Boolean);
-                    return deps.slice(0, MAX_DEPS);
+                    return { dependencies: deps.slice(0, MAX_DEPS), warnings };
                 }
-                return [];
             }
-            case "go": {
-                const goModPath = path.join(projectDir, "go.mod");
-                if (!(await fs.pathExists(goModPath)))
-                    return [];
-                const content = await fs.readFile(goModPath, "utf-8");
-                const requireBlock = content.match(/require\s*\(([\s\S]*?)\)/);
-                if (requireBlock?.[1]) {
-                    const deps = requireBlock[1]
-                        .split("\n")
-                        .map((l) => l.trim())
-                        .filter((l) => l.length > 0 && !l.startsWith("//"))
-                        .map((l) => {
-                        const parts = l.split(/\s+/);
-                        const mod = parts[0] ?? "";
-                        return mod.split("/").pop() ?? mod;
-                    })
-                        .filter(Boolean);
-                    return deps.slice(0, MAX_DEPS);
-                }
-                return [];
+            const reqPath = path.join(projectDir, "requirements.txt");
+            if (await fs.pathExists(reqPath)) {
+                const content = await readManifest(reqPath, warnings);
+                if (content === null)
+                    return { dependencies: [], warnings };
+                const deps = content
+                    .split("\n")
+                    .map((l) => l.trim())
+                    .filter((l) => l.length > 0 && !l.startsWith("#") && !l.startsWith("-"))
+                    .map((l) => l.split(/[>=<~!]/)[0].trim())
+                    .filter(Boolean);
+                return { dependencies: deps.slice(0, MAX_DEPS), warnings };
             }
-            case "rust": {
-                const cargoPath = path.join(projectDir, "Cargo.toml");
-                if (!(await fs.pathExists(cargoPath)))
-                    return [];
-                const content = await fs.readFile(cargoPath, "utf-8");
-                const depsSection = content.match(/\[dependencies\]([\s\S]*?)(?=\n\[|$)/);
-                if (depsSection?.[1]) {
-                    const deps = depsSection[1]
-                        .split("\n")
-                        .map((l) => l.trim())
-                        .filter((l) => l.length > 0 && !l.startsWith("#"))
-                        .map((l) => l.split(/\s*=/)[0].trim())
-                        .filter(Boolean);
-                    return deps.slice(0, MAX_DEPS);
-                }
-                return [];
+            return { dependencies: [], warnings };
+        }
+        case "go": {
+            const goModPath = path.join(projectDir, "go.mod");
+            if (!(await fs.pathExists(goModPath)))
+                return { dependencies: [], warnings };
+            const content = await readManifest(goModPath, warnings);
+            const requireBlock = content?.match(/require\s*\(([\s\S]*?)\)/);
+            if (requireBlock?.[1]) {
+                const deps = requireBlock[1]
+                    .split("\n")
+                    .map((l) => l.trim())
+                    .filter((l) => l.length > 0 && !l.startsWith("//"))
+                    .map((l) => {
+                    const parts = l.split(/\s+/);
+                    const mod = parts[0] ?? "";
+                    return mod.split("/").pop() ?? mod;
+                })
+                    .filter(Boolean);
+                return { dependencies: deps.slice(0, MAX_DEPS), warnings };
             }
-            default:
-                return [];
+            return { dependencies: [], warnings };
         }
+        case "rust": {
+            const cargoPath = path.join(projectDir, "Cargo.toml");
+            if (!(await fs.pathExists(cargoPath)))
+                return { dependencies: [], warnings };
+            const content = await readManifest(cargoPath, warnings);
+            const depsSection = content?.match(/\[dependencies\]([\s\S]*?)(?=\n\[|$)/);
+            if (depsSection?.[1]) {
+                const deps = depsSection[1]
+                    .split("\n")
+                    .map((l) => l.trim())
+                    .filter((l) => l.length > 0 && !l.startsWith("#"))
+                    .map((l) => l.split(/\s*=/)[0].trim())
+                    .filter(Boolean);
+                return { dependencies: deps.slice(0, MAX_DEPS), warnings };
+            }
+            return { dependencies: [], warnings };
+        }
+        default:
+            return { dependencies: [], warnings };
     }
-    catch {
-        return [];
-    }
+}
+/**
+ * Detect top-level dependencies from project manifest files.
+ * Returns up to 10 dependency names (key deps only, not devDeps).
+ *
+ * List-returning convenience over `detectDependenciesDetailed`. It DISCARDS the
+ * read/parse warnings — an unreadable manifest is indistinguishable from an
+ * honest empty list through this function. Callers that must tell those two
+ * apart (like `refreshContextDir`) call `detectDependenciesDetailed` directly.
+ */
+export async function detectDependencies(projectDir, stack) {
+    const { dependencies } = await detectDependenciesDetailed(projectDir, stack);
+    return dependencies;
 }
 // =============================================================================
 // Public API
@@ -190,7 +231,7 @@ export async function refreshContextDir(projectDir) {
         return null;
     }
     const stackCtx = getStackContext(manifest.stack);
-    const dependencies = await detectDependencies(projectDir, manifest.stack);
+    const { dependencies, warnings } = await detectDependenciesDetailed(projectDir, manifest.stack);
     const index = buildIndexMd(manifest.projectName, stackCtx, manifest.ciProvider, manifest.memory);
     const summary = buildSummaryMd(manifest.projectName, manifest.stack, manifest.ciProvider, manifest.memory, manifest.modules, dependencies);
     // Write updated files
@@ -199,6 +240,6 @@ export async function refreshContextDir(projectDir) {
     // Update manifest timestamp
     manifest.updatedAt = new Date().toISOString();
     await fs.writeJson(manifestPath, manifest, { spaces: 2 });
-    return { index, summary, updated: true };
+    return { index, summary, updated: true, warnings };
 }
 //# sourceMappingURL=context.js.map

package/dist/lib/safe-read.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Bounded, non-throwing file reads.
+ *
+ * Every whole-file read in this CLI used to be an unguarded
+ * `fs.readFile(path, "utf-8")`: a 400 MB log, a minified bundle or a binary
+ * blob under a scanned directory could exhaust memory or stall a scan. This
+ * module is the single guarded entry point — it caps bytes during the read,
+ * rejects binaries by content sniffing, clamps pathological single lines, and
+ * returns a discriminated union instead of throwing for expected conditions.
+ *
+ * Deliberately NOT included: no path allow/block list. This is a local CLI
+ * operating on the user's own repository, so any path they can name they can
+ * already `cat`; a blocklist would add friction without adding a boundary.
+ */
+/** Default byte budget for a single read (1 MiB). */
+export declare const DEFAULT_MAX_BYTES: number;
+/** Default per-line character clamp — catches minified bundles and data URIs. */
+export declare const DEFAULT_MAX_LINE_LENGTH = 10000;
+export interface SafeReadOptions {
+    /** Maximum bytes kept. Anything beyond is dropped and `truncated` is set. */
+    maxBytes?: number;
+    /** Per-line character clamp. Use `0` or `Infinity` to disable. */
+    maxLineLength?: number;
+    /**
+     * If the file is larger than this, fail with `too-large` instead of
+     * truncating. Off by default — truncation is the normal behavior.
+     */
+    hardRejectOverBytes?: number;
+}
+export type SafeReadFailureReason = "not-found" | "not-a-file" | "binary" | "too-large" | "io-error";
+export interface SafeReadSuccess {
+    ok: true;
+    content: string;
+    /** True when the file had more bytes than the budget allowed. */
+    truncated: boolean;
+    /** Bytes actually decoded into `content` (before BOM stripping). */
+    bytesRead: number;
+    /** File size reported by `stat` at the time of the read. */
+    totalBytes: number;
+    /** True when at least one line hit the per-line clamp. */
+    longLinesClamped: boolean;
+}
+export interface SafeReadFailure {
+    ok: false;
+    reason: SafeReadFailureReason;
+    detail?: string;
+}
+export type SafeReadResult = SafeReadSuccess | SafeReadFailure;
+/**
+ * Read a text file with a byte budget, binary rejection and line clamping.
+ *
+ * Never throws for expected conditions (missing file, directory, binary,
+ * oversized, permission denied) — inspect `result.ok` and branch on `reason`.
+ *
+ * Newlines are returned verbatim: CRLF is NOT normalized, because the callers
+ * migrated to this helper already tolerate `\r` (they `trim()` split lines) and
+ * silently rewriting bytes would make reported offsets diverge from the file.
+ */
+export declare function safeReadFile(filePath: string, opts?: SafeReadOptions): Promise<SafeReadResult>;
+/** Human-readable one-liner for a failed read — for CLI notes and findings. */
+export declare function describeSafeReadFailure(failure: SafeReadFailure): string;
+//# sourceMappingURL=safe-read.d.ts.map

package/dist/lib/safe-read.js

@@ -0,0 +1,221 @@
+/**
+ * Bounded, non-throwing file reads.
+ *
+ * Every whole-file read in this CLI used to be an unguarded
+ * `fs.readFile(path, "utf-8")`: a 400 MB log, a minified bundle or a binary
+ * blob under a scanned directory could exhaust memory or stall a scan. This
+ * module is the single guarded entry point — it caps bytes during the read,
+ * rejects binaries by content sniffing, clamps pathological single lines, and
+ * returns a discriminated union instead of throwing for expected conditions.
+ *
+ * Deliberately NOT included: no path allow/block list. This is a local CLI
+ * operating on the user's own repository, so any path they can name they can
+ * already `cat`; a blocklist would add friction without adding a boundary.
+ */
+import { open, stat } from "node:fs/promises";
+// =============================================================================
+// Constants
+// =============================================================================
+/** Default byte budget for a single read (1 MiB). */
+export const DEFAULT_MAX_BYTES = 1024 * 1024;
+/** Default per-line character clamp — catches minified bundles and data URIs. */
+export const DEFAULT_MAX_LINE_LENGTH = 10_000;
+/** Size of each read from the file handle. */
+const READ_CHUNK_BYTES = 64 * 1024;
+/** Bytes of the first chunk sniffed for NUL when classifying binary content. */
+const BINARY_SNIFF_BYTES = 8 * 1024;
+const BOM = "\uFEFF";
+// =============================================================================
+// Internal helpers
+// =============================================================================
+function errnoOf(err) {
+    return typeof err === "object" && err !== null && "code" in err
+        ? String(err.code)
+        : undefined;
+}
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Drop a trailing partial UTF-8 sequence so a byte-capped buffer never decodes
+ * into a replacement character. Scans back at most 3 bytes (max lead distance
+ * for a 4-byte sequence) looking for a lead byte whose sequence would run past
+ * the end of the buffer.
+ */
+function trimPartialUtf8(buf) {
+    const maxLookback = Math.min(3, buf.length);
+    for (let back = 0; back < maxLookback; back++) {
+        const index = buf.length - 1 - back;
+        const byte = buf[index];
+        // Continuation byte (10xxxxxx): keep walking back to its lead byte.
+        if ((byte & 0xc0) === 0x80)
+            continue;
+        // ASCII byte: the buffer ends on a complete codepoint.
+        if ((byte & 0x80) === 0)
+            return buf;
+        // Lead byte: does its full sequence fit in what we kept?
+        let needed = 0;
+        if ((byte & 0xe0) === 0xc0)
+            needed = 2;
+        else if ((byte & 0xf0) === 0xe0)
+            needed = 3;
+        else if ((byte & 0xf8) === 0xf0)
+            needed = 4;
+        else
+            return buf; // invalid lead byte — leave it to the decoder
+        const available = buf.length - index;
+        return available >= needed ? buf : buf.subarray(0, index);
+    }
+    return buf;
+}
+/** Clamp lines longer than `maxLineLength`, marking how much was dropped. */
+function clampLongLines(content, maxLineLength) {
+    if (!Number.isFinite(maxLineLength) || maxLineLength <= 0) {
+        return { content, clamped: false };
+    }
+    if (content.length <= maxLineLength)
+        return { content, clamped: false };
+    const lines = content.split("\n");
+    let clamped = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.length <= maxLineLength)
+            continue;
+        const dropped = line.length - maxLineLength;
+        lines[i] = `${line.slice(0, maxLineLength)}…[clamped ${dropped} chars]`;
+        clamped = true;
+    }
+    return clamped
+        ? { content: lines.join("\n"), clamped }
+        : { content, clamped };
+}
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Read a text file with a byte budget, binary rejection and line clamping.
+ *
+ * Never throws for expected conditions (missing file, directory, binary,
+ * oversized, permission denied) — inspect `result.ok` and branch on `reason`.
+ *
+ * Newlines are returned verbatim: CRLF is NOT normalized, because the callers
+ * migrated to this helper already tolerate `\r` (they `trim()` split lines) and
+ * silently rewriting bytes would make reported offsets diverge from the file.
+ */
+export async function safeReadFile(filePath, opts = {}) {
+    const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+    const maxLineLength = opts.maxLineLength ?? DEFAULT_MAX_LINE_LENGTH;
+    const hardRejectOverBytes = opts.hardRejectOverBytes;
+    // -- Stat first: classify directories, sockets and missing paths cheaply ---
+    let totalBytes;
+    try {
+        const stats = await stat(filePath);
+        if (!stats.isFile()) {
+            return {
+                ok: false,
+                reason: "not-a-file",
+                detail: stats.isDirectory()
+                    ? "path is a directory"
+                    : "not a regular file",
+            };
+        }
+        totalBytes = stats.size;
+    }
+    catch (err) {
+        const code = errnoOf(err);
+        if (code === "ENOENT" || code === "ENOTDIR") {
+            return { ok: false, reason: "not-found", detail: filePath };
+        }
+        return { ok: false, reason: "io-error", detail: messageOf(err) };
+    }
+    if (hardRejectOverBytes !== undefined && totalBytes > hardRejectOverBytes) {
+        return {
+            ok: false,
+            reason: "too-large",
+            detail: `${totalBytes} bytes exceeds limit of ${hardRejectOverBytes}`,
+        };
+    }
+    if (maxBytes <= 0) {
+        return {
+            ok: true,
+            content: "",
+            truncated: totalBytes > 0,
+            bytesRead: 0,
+            totalBytes,
+            longLinesClamped: false,
+        };
+    }
+    // -- Read in chunks, enforcing the budget as we go (never buffer it all) ---
+    const chunks = [];
+    let collected = 0;
+    let truncated = false;
+    let handle;
+    try {
+        handle = await open(filePath, "r");
+        while (collected < maxBytes) {
+            const want = Math.min(READ_CHUNK_BYTES, maxBytes - collected);
+            const buf = Buffer.allocUnsafe(want);
+            const { bytesRead } = await handle.read(buf, 0, want, null);
+            if (bytesRead === 0)
+                break;
+            const chunk = buf.subarray(0, bytesRead);
+            // Binary sniff on the first chunk only — by content, never extension.
+            if (chunks.length === 0) {
+                const sniff = chunk.subarray(0, BINARY_SNIFF_BYTES);
+                if (sniff.includes(0)) {
+                    return {
+                        ok: false,
+                        reason: "binary",
+                        detail: "NUL byte in first chunk",
+                    };
+                }
+            }
+            chunks.push(chunk);
+            collected += bytesRead;
+        }
+        // One probe byte tells us whether the budget actually cut something off.
+        if (collected >= maxBytes) {
+            const probe = Buffer.allocUnsafe(1);
+            const { bytesRead } = await handle.read(probe, 0, 1, null);
+            truncated = bytesRead > 0;
+        }
+    }
+    catch (err) {
+        return { ok: false, reason: "io-error", detail: messageOf(err) };
+    }
+    finally {
+        await handle?.close().catch(() => { });
+    }
+    let buffer = Buffer.concat(chunks, collected);
+    if (truncated)
+        buffer = trimPartialUtf8(buffer);
+    const bytesRead = buffer.length;
+    let content = buffer.toString("utf-8");
+    if (content.startsWith(BOM))
+        content = content.slice(BOM.length);
+    const { content: clampedContent, clamped } = clampLongLines(content, maxLineLength);
+    return {
+        ok: true,
+        content: clampedContent,
+        truncated,
+        bytesRead,
+        totalBytes,
+        longLinesClamped: clamped,
+    };
+}
+/** Human-readable one-liner for a failed read — for CLI notes and findings. */
+export function describeSafeReadFailure(failure) {
+    switch (failure.reason) {
+        case "not-found":
+            return "file not found";
+        case "not-a-file":
+            return failure.detail ?? "not a regular file";
+        case "binary":
+            return "binary file";
+        case "too-large":
+            return failure.detail ? `too large (${failure.detail})` : "too large";
+        case "io-error":
+            return failure.detail ? `read error: ${failure.detail}` : "read error";
+    }
+}
+//# sourceMappingURL=safe-read.js.map

package/dist/lib/security-analysis.d.ts

@@ -25,12 +25,29 @@ export interface SecurityAnalysisReport {
     projectDir: string;
     findings: SecurityAnalysisFinding[];
     summary: SecurityAnalysisSummary;
+    /**
+     * Files the pattern pass never saw — binary, oversized or unreadable. A scan
+     * that silently skipped files is not a clean scan, so they are reported.
+     */
+    skipped?: SecurityAnalysisSkippedFile[];
+}
+export interface SecurityAnalysisSkippedFile {
+    /** Path relative to `projectDir`, matching the finding paths. */
+    file: string;
+    reason: string;
 }
 export interface SecurityAnalysisSummary {
     total: number;
     bySeverity: Record<SecuritySeverity, number>;
     byCategory: Record<string, number>;
     passed: boolean;
+    /**
+     * True when at least one file was skipped or only partially scanned (binary,
+     * oversized, I/O error, truncated, or clamped). The scan did not see the whole
+     * codebase, so `passed` is forced to `false` — a clean result over an
+     * incomplete scan would be a fail-open lie.
+     */
+    incomplete: boolean;
     failThreshold: SecuritySeverity;
 }
 export interface SecurityAnalysisOptions {
@@ -64,8 +81,8 @@ export declare function detectFileLanguage(filePath: string): string | null;
 export declare function matchRule(rule: SemgrepRule, content: string, filePath: string): SecurityAnalysisFinding[];
 export declare function collectFiles(dir: string): Promise<string[]>;
 export declare function severityAtOrAbove(severity: SecuritySeverity, threshold: SecuritySeverity): boolean;
-export declare function buildSummary(findings: SecurityAnalysisFinding[], failThreshold: SecuritySeverity): SecurityAnalysisSummary;
-export declare function buildReport(findings: SecurityAnalysisFinding[], projectDir: string, options?: SecurityAnalysisOptions): SecurityAnalysisReport;
+export declare function buildSummary(findings: SecurityAnalysisFinding[], failThreshold: SecuritySeverity, incomplete?: boolean): SecurityAnalysisSummary;
+export declare function buildReport(findings: SecurityAnalysisFinding[], projectDir: string, options?: SecurityAnalysisOptions, skipped?: SecurityAnalysisSkippedFile[]): SecurityAnalysisReport;
 export declare function filterRules(rules: SemgrepRule[], options?: SecurityAnalysisOptions): SemgrepRule[];
 export declare function loadCustomRules(rulesDir: string): Promise<SemgrepRule[]>;
 export declare function runSecurityAnalysis(projectDir: string, options?: SecurityAnalysisOptions): Promise<SecurityAnalysisReport>;