tempest-react-sdk 0.31.0 → 0.32.0

package/README.md

@@ -278,6 +278,8 @@ Every module is re-exported from the package root — `import { Button, useDebou
 | `sw` _(also subpath `tempest-react-sdk/sw`)_                                                      | `registerServiceWorker` (opt-in `autoUpdate` poll + reload, no `vite-plugin-pwa`), `skipWaiting`, `unregisterAllServiceWorkers`, `installPushHandler`, `installNotificationClickHandler`, `installSkipWaitingListener`, `installPrecache` (app-shell offline + Navigation Preload), `installRuntimeCache` (per-route caching, incl. `rangeRequests`), `createPartialResponse` (206 range slicing), `installBackgroundSync` (offline mutation queue + `periodicsync`), `registerPeriodicSync` (main-thread periodic sync), `inspectCaches`/`clearCaches` (cache observability) — the React-free `tempest-react-sdk/sw` subpath is ideal for bundling into your own `sw.ts`                                                                                                                                    |
 | `editor` _(subpath `tempest-react-sdk/editor`, opt. peers `@tiptap/react`+`@tiptap/starter-kit`)_ | `RichTextEditor` — themed tiptap v3 rich-text editor with toolbar (tiptap externalized; install it only if you use the editor)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `vision` _(subpath `tempest-react-sdk/vision`, opt. peer `onnxruntime-web`)_                      | `Classifier`, `Detector`, `Segmenter` + results/labels/preprocess — on-device ONNX vision inference, vendored from `@mauriciobenjamin700/ort-vision-sdk-web` (onnxruntime-web externalized; install it only if you use vision). Plus browser capture primitives: `useCameraStream` (rear-camera `getUserMedia` + classified errors + `retry()`), `computeImageLuminance`/`isLuminanceAcceptable`/`LowLuminanceError`/`LUMINANCE_SAMPLE_MAX_EDGE` (BT.709 brightness), `useLiveLuminance` (live rAF sampling)                                                                                                                                                                                                                                                                                                 |
+| `tabular` _(subpath `tempest-react-sdk/tabular`, opt. peer `onnxruntime-web`)_                    | `TabularPredictor`, `useTabularPredictor` — scikit-learn models exported by `tempest-fastapi-sdk`'s `export_sklearn_to_onnx`, running in the browser with no inference server. Offline by design: `fetchModelBytes`/`isModelCached`/`cacheModelBytes`/`clearModelCache` (Cache Storage, cache-first) plus `configureOrtAssets`/`ortAssetUrls`/`ORT_WASM_ASSETS` for the runtime's WebAssembly binaries, which ONNX Runtime Web fetches at session creation. Import the default `onnxruntime-web` entry — the WebGPU build has no `ai.onnx.ml` kernels                                                                                                                                                                                                                                                        |
+| `imaging` _(subpath `tempest-react-sdk/imaging`, no deps)_                                        | `resizeImage`, `cropImage`, `rotateImage`, `flipImage`, `compressToTarget` (binary-searches quality into a byte budget), `createThumbnails` (several sizes from one decode), `decodeImage`/`readImageInfo`, `encodeImage`, `supportsImageType`/`bestSupportedType`, plus `useImagePreview`/`useImageProcessing`. Canvas only — decodes with EXIF orientation applied (phone photos arrive upright), reports the format actually produced (asking for AVIF where there is no encoder silently returns PNG), and re-encoding drops EXIF, which is the privacy step as much as the bandwidth one                                                                                                                                                                                                                |
 | `audio`                                                                                           | `createAudioPlayer`, `playAudio`, `stopAudio`, `useAudio`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `offline` _(peer: `dexie`)_                                                                       | `createOfflineStore`, `createOfflineSync` (outbox + delta-pull + watermark engine, now with `subscribe`/`getState`/`dispose` + cross-tab `crossTab`), `useOfflineSync`/`useSyncStatus` (reactive hooks), `lastWriteWins`/`higherVersionWins` (conflict resolvers), types: `OfflineStore`, `OfflineStoreConfig`, `ListOptions`, `OfflineSync`, `OfflineSyncConfig`, `OutboxEntry`, `PullPage`, `SyncPhase`, `SyncState`, `SyncRunSummary`, `SyncTrigger`, `SyncStatus`, `SyncTone`, `WatermarkStore`                                                                                                                                                                                                                                                                                                          |
 | `error-boundary`                                                                                  | `ErrorBoundary`, `useErrorHandler`, types: `ErrorBoundaryProps`, `ErrorBoundaryRenderProps`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

package/bin/lib/design/collect.mjs

@@ -0,0 +1,103 @@
+// Which source files the design analysis is allowed to judge. Generated code and
+// type declarations are the author's output, not the author's writing: reporting
+// a 4000-line `icons.generated.ts` as "too big to read" buries the one component
+// that really is.
+import { readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const SKIP_DIRS = new Set([
+    "node_modules",
+    "dist",
+    "build",
+    "out",
+    "coverage",
+    "public",
+    "vendor",
+    ".git",
+    ".vite",
+    ".next",
+    ".turbo",
+    ".cache",
+]);
+
+const EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs"];
+
+/** Above this size a file is treated as generated, not authored. */
+const MAX_BYTES = 256 * 1024;
+
+/** Cap on files opened, so `tempest doctor` stays fast on a huge tree. */
+const MAX_FILES = 1200;
+
+/** True for a path the analysis must not judge. */
+export function isExcluded(path) {
+    return (
+        path.endsWith(".d.ts") ||
+        /\.generated\.[jt]sx?$/.test(path) ||
+        /[/\\]generated[/\\]/.test(path)
+    );
+}
+
+/**
+ * Collect the project's own source files.
+ *
+ * @param {object} params
+ * @param {string} params.root - Project root; relative targets resolve against it.
+ * @param {string[]} [params.targets] - Positional paths from the command line.
+ * @param {number} [params.maxFiles]
+ * @returns {{ files: string[], skipped: Array<{ path: string, reason: string }>, truncated: boolean }}
+ */
+export function collectSources({ root, targets = ["src", "app"], maxFiles = MAX_FILES }) {
+    const files = new Set();
+    const skipped = [];
+    let truncated = false;
+
+    const consider = (path) => {
+        if (!EXTENSIONS.some((ext) => path.endsWith(ext)) || files.has(path)) return;
+        if (isExcluded(path)) return;
+        if (files.size >= maxFiles) {
+            truncated = true;
+            return;
+        }
+        let size;
+        try {
+            size = statSync(path).size;
+        } catch {
+            return;
+        }
+        if (size > MAX_BYTES) {
+            skipped.push({ path, reason: "larger than 256 KB — treated as generated" });
+            return;
+        }
+        files.add(path);
+    };
+
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (SKIP_DIRS.has(entry.name)) continue;
+            if (entry.name.startsWith(".") && entry.isDirectory()) continue;
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) walk(full);
+            else if (entry.isFile()) consider(full);
+        }
+    };
+
+    for (const target of targets) {
+        const full = resolve(root, target);
+        let stat;
+        try {
+            stat = statSync(full);
+        } catch {
+            continue;
+        }
+        if (stat.isDirectory()) walk(full);
+        else if (stat.isFile()) consider(full);
+    }
+
+    return { files: [...files].sort((a, b) => a.localeCompare(b)), skipped, truncated };
+}

package/bin/lib/design/findings.mjs

@@ -0,0 +1,70 @@
+// The finding vocabulary of the design analysis, and how loud each one is.
+//
+// Nothing here is `error`, and that is deliberate. A size limit is a heuristic:
+// `Calendar` and `ImageCropper` in this very SDK exceed 150 lines for a reason
+// written in their JSDoc. Failing `tempest doctor`'s exit code on a heuristic
+// would make the command unusable in CI for any existing project, and the first
+// fix people reach for is silencing the tool. `warn` shows up, someone decides.
+//
+// The hard gates stay where they belong: `no-explicit-any` as an ESLint `error`
+// and `tsc --noEmit` in CI.
+
+/** Severity of each finding code. */
+export const SEVERITY = {
+    "file-lines": "warn",
+    "function-lines": "warn",
+    "hook-lines": "warn",
+    "props-count": "warn",
+    "param-count": "warn",
+    "explicit-any": "warn",
+    "ts-ignore": "warn",
+    "fetch-in-component": "warn",
+    "empty-catch": "warn",
+    "inline-style-literal": "warn",
+    "marker-without-reason": "warn",
+    acknowledged: "info",
+};
+
+/** Default thresholds — the numbers documented in docs/design/limits.md. */
+export const LIMITS = {
+    componentFileLines: 150,
+    moduleFileLines: 200,
+    functionLines: 80,
+    hookLines: 100,
+    props: 7,
+    params: 3,
+};
+
+/**
+ * Build a finding.
+ *
+ * @param {string} code - A key of {@link SEVERITY}.
+ * @param {object} params
+ * @param {string} params.file - Path as it should be reported (project-relative).
+ * @param {number} params.line - 1-based line.
+ * @param {string} params.message - What is over the line, and what to do about it.
+ * @param {object} [params.extra] - Extra fields carried through to the reporter.
+ * @returns {{ code: string, severity: string, file: string, line: number, message: string }}
+ */
+export function finding(code, { file, line, message, extra = {} }) {
+    return { code, severity: SEVERITY[code] ?? "warn", file, line, message, ...extra };
+}
+
+/** Sort findings by severity, then file, then line — the reporting order. */
+export function sortFindings(findings) {
+    const rank = { error: 0, warn: 1, info: 2 };
+    return [...findings].sort(
+        (a, b) =>
+            (rank[a.severity] ?? 3) - (rank[b.severity] ?? 3) ||
+            a.file.localeCompare(b.file) ||
+            a.line - b.line ||
+            a.code.localeCompare(b.code),
+    );
+}
+
+/** Count findings per severity. */
+export function countBySeverity(findings) {
+    const counts = { warn: 0, info: 0 };
+    for (const f of findings) counts[f.severity] = (counts[f.severity] ?? 0) + 1;
+    return counts;
+}

package/bin/lib/design/functions.mjs

@@ -0,0 +1,188 @@
+// Locate the functions in a masked source file and measure them. No TypeScript
+// parser on purpose: `doctor` must run in a project that has not installed
+// anything yet, and the numbers it reports (body length, parameter count, prop
+// count) are exactly the ones a brace scan can get right.
+import { countCodeLines, lineAt, matchPair } from "./mask.mjs";
+
+const DECLARATIONS = [
+    /\b(export\s+(?:default\s+)?)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*(?:<[^(){}]*>)?\s*\(/g,
+    /\b(export\s+)?(?:const|let)\s+([A-Za-z_$][\w$]*)\s*(?::[^=;()]*)?=\s*(?:async\s+)?(?:function\s*(?:<[^(){}]*>)?\s*)?\(/g,
+];
+
+// Destructured keys that are plumbing, not decisions: they forward the caller's
+// DOM attributes instead of adding a case to the component. Counting them made
+// every SDK primitive that spreads `...rest` look like two components — the
+// loudest false positive in the first run of this rule.
+const PLUMBING_KEYS = new Set(["className", "children", "style", "id", "ref", "key"]);
+
+/**
+ * Split a parameter or member list at top-level separators, ignoring nested
+ * groups.
+ *
+ * Angle brackets count as a group so `Record<string, number>` stays one item, but
+ * the `>` of an arrow (`=>`) does not — a default value like `onPick = () => {}`
+ * otherwise drove the depth negative and every later comma read as a new
+ * parameter. The depth is clamped at zero for the same reason: one unbalanced
+ * `>` must not turn the rest of the list into phantom items.
+ *
+ * @param {string} text
+ * @param {string} [separator]
+ * @returns {string[]}
+ */
+export function splitTopLevel(text, separator = ",") {
+    const parts = [];
+    let depth = 0;
+    let current = "";
+    let previous = "";
+    for (const ch of text) {
+        const isArrowTail = ch === ">" && previous === "=";
+        if ("([{<".includes(ch)) depth += 1;
+        else if (")]}>".includes(ch) && !isArrowTail) depth = Math.max(0, depth - 1);
+        if (ch === separator && depth === 0) {
+            parts.push(current);
+            current = "";
+            previous = ch;
+            continue;
+        }
+        current += ch;
+        previous = ch;
+    }
+    if (current.trim()) parts.push(current);
+    return parts.map((part) => part.trim()).filter(Boolean);
+}
+
+/**
+ * Keys of an inline destructured object pattern that represent a real choice.
+ *
+ * `{ variant, size, className, children, ...rest }` counts 2: the rest element
+ * and the DOM plumbing forward the caller's attributes rather than adding a case
+ * the component has to handle.
+ *
+ * @param {string} param - First parameter text.
+ * @returns {number} Key count, or 0 when the parameter is not a pattern.
+ */
+export function destructuredKeyCount(param) {
+    const open = param.indexOf("{");
+    if (open !== 0) return 0;
+    const close = matchPair(param, open, "{", "}");
+    if (close === -1) return 0;
+    return splitTopLevel(param.slice(open + 1, close)).filter((key) => {
+        if (key.startsWith("...")) return false;
+        const name = key.split(/[:=]/)[0].trim();
+        return !PLUMBING_KEYS.has(name);
+    }).length;
+}
+
+/**
+ * Find the body of a callable whose parameter list closes at `closeParen`.
+ *
+ * Returns null for an expression-bodied arrow (`const f = (a) => a + 1`): it has
+ * no block to measure, and any such function is already below every limit.
+ *
+ * @param {string} masked
+ * @param {number} closeParen
+ * @returns {{ start: number, end: number } | null}
+ */
+function findBody(masked, closeParen) {
+    for (let i = closeParen + 1; i < masked.length; i += 1) {
+        const ch = masked[i];
+        if (ch === "{") {
+            const end = matchPair(masked, i, "{", "}");
+            return end === -1 ? null : { start: i, end };
+        }
+        if (ch === ";" || ch === "\n") {
+            if (ch === ";") return null;
+            continue;
+        }
+        if (!/[\s=>:|&?[\]<>(),."'`\w$]/.test(ch)) return null;
+    }
+    return null;
+}
+
+/**
+ * Classify a declaration by name and file kind.
+ *
+ * @param {string} name
+ * @param {boolean} isTsx
+ * @returns {"hook" | "component" | "function"}
+ */
+export function classify(name, isTsx) {
+    if (/^use[A-Z]/.test(name)) return "hook";
+    if (isTsx && /^[A-Z]/.test(name)) return "component";
+    return "function";
+}
+
+/**
+ * Measure every function in a masked file.
+ *
+ * `bodyLines` spans the opening brace through the closing one, blank and
+ * comment-only lines excluded — the same thing `max-lines-per-function` with
+ * `skipBlankLines` + `skipComments` counts, minus the signature line.
+ *
+ * @param {string} masked - Output of `maskSource`.
+ * @param {object} [options]
+ * @param {boolean} [options.isTsx] - Whether components may be detected.
+ * @returns {Array<{ name: string, kind: string, line: number, bodyLines: number,
+ *   params: string[], destructuredProps: number, exported: boolean }>}
+ */
+export function findFunctions(masked, { isTsx = false } = {}) {
+    const found = new Map();
+
+    for (const pattern of DECLARATIONS) {
+        const re = new RegExp(pattern.source, "g");
+        let match;
+        while ((match = re.exec(masked))) {
+            const name = match[2];
+            const exported = Boolean(match[1]);
+            const openParen = masked.indexOf("(", match.index + match[0].length - 1);
+            if (openParen === -1) continue;
+            const closeParen = matchPair(masked, openParen, "(", ")");
+            if (closeParen === -1) continue;
+            const body = findBody(masked, closeParen);
+            if (!body) continue;
+            if (found.has(body.start)) continue;
+
+            const params = splitTopLevel(masked.slice(openParen + 1, closeParen));
+            found.set(body.start, {
+                name,
+                kind: classify(name, isTsx),
+                exported,
+                line: lineAt(masked, match.index),
+                bodyLines: countCodeLines(masked.slice(body.start, body.end + 1)),
+                params,
+                destructuredProps: params.length === 1 ? destructuredKeyCount(params[0]) : 0,
+            });
+        }
+    }
+
+    return [...found.values()].sort((a, b) => a.line - b.line);
+}
+
+/**
+ * Member count of every `…Props` type/interface in the file, keyed by the type
+ * name.
+ *
+ * A union (`type XProps = { as: "a" } | { as: "b"; href: string }`) is skipped:
+ * its member count belongs to the branches, not to the alias — and a union is the
+ * shape the docs recommend precisely to keep each branch small.
+ *
+ * @param {string} masked
+ * @returns {Map<string, { count: number, line: number }>}
+ */
+export function findPropsTypes(masked) {
+    const out = new Map();
+    const re = /\b(?:interface|type)\s+([A-Za-z_$][\w$]*Props)\b([^{;]*)/g;
+    let match;
+    while ((match = re.exec(masked))) {
+        const open = masked.indexOf("{", match.index + match[0].length - 1);
+        if (open === -1) continue;
+        const close = matchPair(masked, open, "{", "}");
+        if (close === -1) continue;
+        if (/^\s*[|&]/.test(masked.slice(close + 1))) continue;
+        const members = splitTopLevel(masked.slice(open + 1, close), ";").filter((member) =>
+            /^(readonly\s+)?\[?["']?[\w$]+["']?\]?\??\s*[:(]/.test(member),
+        );
+        out.set(match[1], { count: members.length, line: lineAt(masked, match.index) });
+    }
+    return out;
+}

package/bin/lib/design/functions.test.mjs

@@ -0,0 +1,127 @@
+import { describe, expect, it } from "vitest";
+
+import {
+    classify,
+    destructuredKeyCount,
+    findFunctions,
+    findPropsTypes,
+    splitTopLevel,
+} from "./functions.mjs";
+import { maskSource } from "./mask.mjs";
+
+const scan = (source) => findFunctions(maskSource(source).masked, { isTsx: true });
+
+describe("splitTopLevel", () => {
+    it("keeps a generic type argument as one item", () => {
+        expect(splitTopLevel("a: Record<string, number>, b: string")).toEqual([
+            "a: Record<string, number>",
+            "b: string",
+        ]);
+    });
+
+    it("does not count the > of an arrow default as a closing bracket", () => {
+        expect(splitTopLevel("onPick = () => {}, other, third")).toEqual([
+            "onPick = () => {}",
+            "other",
+            "third",
+        ]);
+    });
+
+    it("splits members on a custom separator", () => {
+        expect(splitTopLevel("a: string; b: number;", ";")).toEqual(["a: string", "b: number"]);
+    });
+});
+
+describe("destructuredKeyCount", () => {
+    it("ignores the rest element and DOM plumbing", () => {
+        expect(destructuredKeyCount("{ variant, size, className, children, ...rest }")).toBe(2);
+    });
+
+    it("counts keys carrying defaults once", () => {
+        expect(destructuredKeyCount('{ variant = "info", size = "md" }')).toBe(2);
+    });
+
+    it("returns 0 for a non-pattern parameter", () => {
+        expect(destructuredKeyCount("props: CardProps")).toBe(0);
+    });
+});
+
+describe("classify", () => {
+    it("recognises hooks, components and plain functions", () => {
+        expect(classify("useOrders", false)).toBe("hook");
+        expect(classify("OrderTable", true)).toBe("component");
+        expect(classify("OrderTable", false)).toBe("function");
+        expect(classify("sortBy", true)).toBe("function");
+    });
+});
+
+describe("findFunctions", () => {
+    it("measures a declaration body in code lines, blank lines excluded", () => {
+        const [fn] = scan(
+            ["export function a() {", "  const x = 1;", "", "  return x;", "}"].join("\n"),
+        );
+        expect(fn.name).toBe("a");
+        expect(fn.exported).toBe(true);
+        expect(fn.bodyLines).toBe(4);
+    });
+
+    it("measures an arrow assigned to a const", () => {
+        const [fn] = scan("const helper = (a, b) => {\n  return a + b;\n};");
+        expect(fn.name).toBe("helper");
+        expect(fn.exported).toBe(false);
+        expect(fn.params).toEqual(["a", "b"]);
+    });
+
+    it("skips an expression-bodied arrow", () => {
+        expect(scan("const double = (n) => n * 2;")).toEqual([]);
+    });
+
+    it("counts one destructured parameter as one parameter", () => {
+        const [fn] = scan("export function Card({ a, b, c }: CardProps) {\n  return null;\n}");
+        expect(fn.params).toHaveLength(1);
+        expect(fn.destructuredProps).toBe(3);
+    });
+
+    it("handles a generic component signature", () => {
+        const [fn] = scan(
+            "export function List<T>({ items, render }: ListProps<T>) {\n  return null;\n}",
+        );
+        expect(fn.name).toBe("List");
+        expect(fn.params).toHaveLength(1);
+        expect(fn.destructuredProps).toBe(2);
+    });
+
+    it("reports each function once", () => {
+        const found = scan("export function a() {\n  return 1;\n}\nfunction b() {\n  return 2;\n}");
+        expect(found.map((f) => f.name)).toEqual(["a", "b"]);
+    });
+});
+
+describe("findPropsTypes", () => {
+    it("counts members of an interface", () => {
+        const types = findPropsTypes(
+            maskSource("interface CardProps {\n  a: string;\n  b?: number;\n}").masked,
+        );
+        expect(types.get("CardProps").count).toBe(2);
+    });
+
+    it("counts members of a type literal", () => {
+        const types = findPropsTypes(maskSource("type CardProps = {\n  a: string;\n};").masked);
+        expect(types.get("CardProps").count).toBe(1);
+    });
+
+    it("skips a union alias", () => {
+        const types = findPropsTypes(
+            maskSource('type CardProps = { as: "a" } | { as: "b"; href: string };').masked,
+        );
+        expect(types.has("CardProps")).toBe(false);
+    });
+
+    it("does not count a nested object as a separate member", () => {
+        const types = findPropsTypes(
+            maskSource("interface CardProps {\n  meta: { a: string; b: string };\n  c: number;\n}")
+                .masked,
+        );
+        expect(types.get("CardProps").count).toBe(2);
+    });
+});

package/bin/lib/design/index.mjs

@@ -0,0 +1,80 @@
+// Public surface of the design analysis: read the project's sources, run the
+// rules over each one, and report the numbers the caller needs to say something
+// useful — how big the median file is, what went over a limit, and which limits
+// were waived on purpose.
+import { readFileSync } from "node:fs";
+import { relative } from "node:path";
+
+import { collectSources } from "./collect.mjs";
+import { countBySeverity, LIMITS, sortFindings } from "./findings.mjs";
+import { scanFile } from "./scan.mjs";
+
+export { LIMITS, SEVERITY } from "./findings.mjs";
+export { scanFile } from "./scan.mjs";
+
+/** Median of a numeric list, or 0 when empty. */
+function median(values) {
+    if (values.length === 0) return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0 ? Math.round((sorted[mid - 1] + sorted[mid]) / 2) : sorted[mid];
+}
+
+/**
+ * Run the design analysis over a project.
+ *
+ * @param {object} params
+ * @param {string} params.root - Project root.
+ * @param {string[]} [params.targets] - Paths to analyze (default: `src`, `app`).
+ * @param {object} [params.limits] - Overrides for {@link LIMITS}.
+ * @param {number} [params.maxFiles]
+ * @returns {{
+ *   findings: object[],
+ *   waivers: Array<{ file: string, code: string, reason: string }>,
+ *   counts: { warn: number, info: number },
+ *   stats: { files: number, codeLines: number, medianLines: number, largest: { file: string, lines: number } | null },
+ *   skipped: Array<{ file: string, reason: string }>,
+ *   truncated: boolean
+ * }}
+ */
+export function analyzeDesign({ root, targets, limits = {}, maxFiles } = {}) {
+    const collected = collectSources({ root, targets, maxFiles });
+    const findings = [];
+    const waivers = [];
+    const lineCounts = [];
+    let largest = null;
+    let codeLines = 0;
+
+    for (const path of collected.files) {
+        const file = relative(root, path) || path;
+        let source;
+        try {
+            source = readFileSync(path, "utf8");
+        } catch {
+            continue;
+        }
+        const result = scanFile({ file, source, limits });
+        findings.push(...result.findings);
+        waivers.push(...result.waivers.map((w) => ({ file, ...w })));
+        lineCounts.push(result.codeLines);
+        codeLines += result.codeLines;
+        if (!largest || result.codeLines > largest.lines) {
+            largest = { file, lines: result.codeLines };
+        }
+    }
+
+    const sorted = sortFindings(findings);
+    return {
+        findings: sorted,
+        waivers,
+        counts: countBySeverity(sorted),
+        stats: {
+            files: collected.files.length,
+            codeLines,
+            medianLines: median(lineCounts),
+            largest,
+        },
+        skipped: collected.skipped.map((s) => ({ file: relative(root, s.path), reason: s.reason })),
+        truncated: collected.truncated,
+    };
+}