@kernlang/review 3.2.3 → 3.3.5

package/dist/public-api.js

@@ -0,0 +1,351 @@
+/**
+ * Public API resolver — decides whether an exported symbol is part of a package's
+ * intentional public API, so dead-export doesn't flag symbols consumed outside the
+ * analyzed graph.
+ *
+ * Sources of truth, in order:
+ *   1. package.json `exports` (string / object / conditional)
+ *   2. package.json `main` / `module` / `types`
+ *   3. package.json `bin`
+ *   4. Conservative barrel fallback: `src/index.ts(x)`, `index.ts(x)`
+ *   5. kern.config `review.publicApi` — explicit escape hatch
+ *
+ * A file listed as a package entry has ALL its named exports treated as public.
+ * Re-exports resolved through call-graph are already kept live by existing logic;
+ * this rule covers exports consumed by EXTERNAL callers who never show up in
+ * the graph (library consumers, dynamic loaders, platform entry points).
+ */
+import { existsSync, readFileSync } from 'fs';
+import { dirname, isAbsolute, join, resolve } from 'path';
+import { SyntaxKind } from 'ts-morph';
+const SRC_EXTS = ['.ts', '.tsx'];
+/** Characters that, when present in a pattern, trigger glob expansion. */
+const GLOB_CHARS = /[*?[]/;
+function hasGlobChars(pattern) {
+    return GLOB_CHARS.test(pattern);
+}
+/**
+ * Convert a POSIX-style glob pattern to a `RegExp` that matches full paths.
+ *
+ * Supported syntax:
+ *   - `*`  — any run of non-separator chars
+ *   - `**` — any path fragment, including separators (zero or more segments)
+ *   - `?`  — a single non-separator char
+ *   - `[abc]` / `[a-z]` — character class
+ *   - `[!abc]` — negated character class (POSIX-style; translated to regex `[^abc]`)
+ *
+ * All other regex metacharacters are escaped. Brace expansion (`{a,b}`) is
+ * NOT supported — keep config patterns simple; split into multiple entries.
+ *
+ * The pattern is expected to be POSIX-separated (forward slashes). The caller
+ * normalizes Windows backslashes to `/` before calling this. Consecutive `*`
+ * runs are collapsed first to prevent catastrophic backtracking on patterns
+ * like `**\/**\/**`.
+ */
+function globToRegex(pattern) {
+    const squashed = pattern.replace(/\*{2,}/g, '**').replace(/(?:\*\*\/)+/g, '**/');
+    let out = '';
+    let i = 0;
+    while (i < squashed.length) {
+        const c = squashed[i];
+        if (c === '*') {
+            if (squashed[i + 1] === '*') {
+                if (squashed[i + 2] === '/') {
+                    out += '(?:.*/)?';
+                    i += 3;
+                }
+                else {
+                    out += '.*';
+                    i += 2;
+                }
+            }
+            else {
+                out += '[^/]*';
+                i++;
+            }
+        }
+        else if (c === '?') {
+            out += '[^/]';
+            i++;
+        }
+        else if (c === '[') {
+            const end = squashed.indexOf(']', i + 1);
+            if (end === -1) {
+                out += '\\[';
+                i++;
+            }
+            else {
+                let inner = squashed.substring(i + 1, end);
+                if (inner.startsWith('!'))
+                    inner = `^${inner.slice(1)}`;
+                out += `[${inner}]`;
+                i = end + 1;
+            }
+        }
+        else if ('.+^$|(){}\\'.includes(c)) {
+            out += `\\${c}`;
+            i++;
+        }
+        else {
+            out += c;
+            i++;
+        }
+    }
+    return new RegExp(`^${out}$`);
+}
+/** Normalize path separators so glob matching works on Windows. */
+function toPosix(p) {
+    return p.replace(/\\/g, '/');
+}
+function collectSpecifiers(value) {
+    if (typeof value === 'string')
+        return [value];
+    if (!value || typeof value !== 'object')
+        return [];
+    if (Array.isArray(value))
+        return value.flatMap(collectSpecifiers);
+    const out = [];
+    for (const v of Object.values(value)) {
+        out.push(...collectSpecifiers(v));
+    }
+    return out;
+}
+/**
+ * Resolve a package.json specifier (e.g. `./dist/index.js`) to the source file
+ * the review operates on (e.g. `./src/index.ts`). Returns undefined if nothing
+ * plausible exists on disk.
+ */
+export function resolveSpecifierToSrc(packageRoot, specifier, fileExists = existsSync) {
+    if (typeof specifier !== 'string' || !specifier.startsWith('.'))
+        return undefined;
+    const abs = resolve(packageRoot, specifier);
+    const stemMatch = abs.match(/^(.+?)(\.d\.ts|\.js|\.cjs|\.mjs|\.ts|\.tsx)$/);
+    const stem = stemMatch ? stemMatch[1] : abs;
+    const candidates = [];
+    if (abs.endsWith('.ts') || abs.endsWith('.tsx'))
+        candidates.push(abs);
+    for (const ext of SRC_EXTS)
+        candidates.push(`${stem}${ext}`);
+    // dist → src swap
+    const withSrc = candidates.flatMap((c) => (c.includes('/dist/') ? [c.replace('/dist/', '/src/')] : []));
+    candidates.push(...withSrc);
+    // Directory entry — try index.{ts,tsx}
+    for (const base of [abs, stem]) {
+        for (const ext of SRC_EXTS)
+            candidates.push(join(base, `index${ext}`));
+    }
+    for (const c of candidates) {
+        if (fileExists(c))
+            return c;
+    }
+    return undefined;
+}
+/**
+ * For a parsed package.json at packageRoot, return all source files that act as
+ * public entry points. Missing files are silently dropped.
+ */
+export function resolvePackageEntryFiles(packageRoot, pkg, fileExists = existsSync) {
+    const specs = new Set();
+    if (pkg.exports !== undefined) {
+        for (const s of collectSpecifiers(pkg.exports))
+            specs.add(s);
+    }
+    if (typeof pkg.main === 'string')
+        specs.add(pkg.main);
+    if (typeof pkg.module === 'string')
+        specs.add(pkg.module);
+    if (typeof pkg.types === 'string')
+        specs.add(pkg.types);
+    if (typeof pkg.bin === 'string') {
+        specs.add(pkg.bin);
+    }
+    else if (pkg.bin && typeof pkg.bin === 'object') {
+        for (const v of Object.values(pkg.bin)) {
+            if (typeof v === 'string')
+                specs.add(v);
+        }
+    }
+    // Conservative barrel fallback — only contributes if the file actually exists.
+    for (const ext of SRC_EXTS) {
+        specs.add(`./src/index${ext}`);
+        specs.add(`./index${ext}`);
+    }
+    const resolved = new Set();
+    for (const s of specs) {
+        const p = resolveSpecifierToSrc(packageRoot, s, fileExists);
+        if (p)
+            resolved.add(p);
+    }
+    return [...resolved];
+}
+function findPackageRoot(startFile, cache) {
+    const startDir = dirname(startFile);
+    if (cache.has(startDir))
+        return cache.get(startDir) ?? null;
+    const visited = [];
+    let dir = startDir;
+    for (let i = 0; i < 30; i++) {
+        if (cache.has(dir)) {
+            const hit = cache.get(dir) ?? null;
+            for (const v of visited)
+                cache.set(v, hit);
+            return hit;
+        }
+        visited.push(dir);
+        if (existsSync(join(dir, 'package.json'))) {
+            for (const v of visited)
+                cache.set(v, dir);
+            return dir;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    for (const v of visited)
+        cache.set(v, null);
+    return null;
+}
+/**
+ * Build a public-API map by walking up from each file to its nearest package.json
+ * and collecting declared entry points. Applies config overrides on top.
+ */
+export function buildPublicApiMap(filePaths, overrides) {
+    const rootCache = new Map();
+    const roots = new Set();
+    for (const fp of filePaths) {
+        const r = findPackageRoot(fp, rootCache);
+        if (r)
+            roots.add(r);
+    }
+    const entryFiles = new Set();
+    for (const root of roots) {
+        const pkgPath = join(root, 'package.json');
+        let pkg;
+        try {
+            pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        }
+        catch {
+            continue;
+        }
+        for (const f of resolvePackageEntryFiles(root, pkg))
+            entryFiles.add(f);
+    }
+    const explicitSymbols = new Set();
+    const projectRoot = overrides?.projectRoot ?? process.cwd();
+    if (overrides?.files) {
+        for (const pattern of overrides.files) {
+            if (typeof pattern !== 'string' || pattern.length === 0)
+                continue;
+            const abs = isAbsolute(pattern) ? pattern : resolve(projectRoot, pattern);
+            // Always add the literal resolved path. This preserves the pre-glob
+            // behavior ("files listed here are public even if absent from the
+            // reviewed graph") AND gives the right answer for Next.js-style
+            // literal brackets like "src/app/[slug]/page.tsx" — the bracketed
+            // segment looks like a glob character class but is actually part of
+            // the filename. Glob expansion still runs below, so users who meant
+            // [...] as a class get that behavior too.
+            entryFiles.add(abs);
+            if (hasGlobChars(pattern)) {
+                const regex = globToRegex(toPosix(abs));
+                for (const fp of filePaths) {
+                    if (regex.test(toPosix(fp)))
+                        entryFiles.add(fp);
+                }
+            }
+        }
+    }
+    if (overrides?.symbols) {
+        for (const spec of overrides.symbols) {
+            if (typeof spec !== 'string')
+                continue;
+            const idx = spec.lastIndexOf('#');
+            if (idx <= 0 || idx === spec.length - 1)
+                continue;
+            const rawPath = spec.slice(0, idx);
+            const name = spec.slice(idx + 1);
+            const abs = isAbsolute(rawPath) ? rawPath : resolve(projectRoot, rawPath);
+            explicitSymbols.add(`${abs}#${name}`);
+        }
+    }
+    return { entryFiles, explicitSymbols };
+}
+export const EMPTY_PUBLIC_API = {
+    entryFiles: new Set(),
+    explicitSymbols: new Set(),
+};
+export function isPublicApi(map, filePath, exportName) {
+    if (map.entryFiles.has(filePath))
+        return true;
+    if (map.explicitSymbols.has(`${filePath}#${exportName}`))
+        return true;
+    return false;
+}
+// Re-export propagation.
+//
+// A curated barrel (`export { foo } from './worker.js'`) makes worker.ts#foo
+// part of the package's public API even if no file in the graph imports
+// worker.ts directly. Without this, dead-export would fire on every symbol
+// a package re-exports but never uses internally: the exact FP that Agon
+// hit before Phase 1, and which the single-file buildPublicApiMap cannot
+// catch on its own.
+function getDeclName(decl, fallback) {
+    const maybeNamed = decl;
+    if (typeof maybeNamed.getName === 'function') {
+        const name = maybeNamed.getName();
+        if (name)
+            return name;
+    }
+    if (decl.getKindName() === 'ExportAssignment') {
+        const expr = decl.getExpression?.();
+        if (expr?.getKind() === SyntaxKind.Identifier)
+            return expr.getText();
+    }
+    return fallback;
+}
+/**
+ * Expand `map.entryFiles` through re-export chains: for each public entry,
+ * walk `getExportedDeclarations()` and mark every upstream `(file, symbol)`
+ * that the entry re-exports as also public. Returns a new map; the input is
+ * not mutated.
+ *
+ * `sourceFileFor(path)` should return the ts-morph SourceFile for an
+ * absolute path (or undefined when the file is outside the analyzed graph).
+ */
+export function expandPublicApiThroughReExports(map, sourceFileFor) {
+    const entryFiles = new Set(map.entryFiles);
+    const explicitSymbols = new Set(map.explicitSymbols);
+    // BFS through re-export chains so a barrel-of-barrels propagates too.
+    const frontier = [...map.entryFiles];
+    const seen = new Set(map.entryFiles);
+    while (frontier.length > 0) {
+        const entry = frontier.shift();
+        const sf = sourceFileFor(entry);
+        if (!sf)
+            continue;
+        let exported;
+        try {
+            exported = sf.getExportedDeclarations();
+        }
+        catch {
+            continue;
+        }
+        for (const [exportName, decls] of exported) {
+            for (const decl of decls) {
+                const declFile = decl.getSourceFile().getFilePath();
+                if (declFile === entry)
+                    continue;
+                explicitSymbols.add(`${declFile}#${getDeclName(decl, exportName)}`);
+                if (!seen.has(declFile)) {
+                    seen.add(declFile);
+                    // An upstream barrel's own re-exports should also be followed;
+                    // don't mark it as an entry (only declared entries get that), but
+                    // do walk it so transitive symbols are captured.
+                    frontier.push(declFile);
+                }
+            }
+        }
+    }
+    return { entryFiles, explicitSymbols };
+}
+//# sourceMappingURL=public-api.js.map

package/dist/public-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-api.js","sourceRoot":"","sources":["../src/public-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAC1D,OAAO,EAA8B,UAAU,EAAE,MAAM,UAAU,CAAC;AA+BlE,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,MAAM,CAAU,CAAC;AAE1C,0EAA0E;AAC1E,MAAM,UAAU,GAAG,OAAO,CAAC;AAE3B,SAAS,YAAY,CAAC,OAAe;IACnC,OAAO,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAS,WAAW,CAAC,OAAe;IAClC,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACjF,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC;QAC3B,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAE,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;YACd,IAAI,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;gBAC5B,IAAI,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;oBAC5B,GAAG,IAAI,UAAU,CAAC;oBAClB,CAAC,IAAI,CAAC,CAAC;gBACT,CAAC;qBAAM,CAAC;oBACN,GAAG,IAAI,IAAI,CAAC;oBACZ,CAAC,IAAI,CAAC,CAAC;gBACT,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,GAAG,IAAI,OAAO,CAAC;gBACf,CAAC,EAAE,CAAC;YACN,CAAC;QACH,CAAC;aAAM,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;YACrB,GAAG,IAAI,MAAM,CAAC;YACd,CAAC,EAAE,CAAC;QACN,CAAC;aAAM,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;YACrB,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;YACzC,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;gBACf,GAAG,IAAI,KAAK,CAAC;gBACb,CAAC,EAAE,CAAC;YACN,CAAC;iBAAM,CAAC;gBACN,IAAI,KAAK,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;gBAC3C,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;oBAAE,KAAK,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;gBACxD,GAAG,IAAI,IAAI,KAAK,GAAG,CAAC;gBACpB,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC;YACd,CAAC;QACH,CAAC;aAAM,IAAI,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;YACrC,GAAG,IAAI,KAAK,CAAC,EAAE,CAAC;YAChB,CAAC,EAAE,CAAC;QACN,CAAC;aAAM,CAAC;YACN,GAAG,IAAI,CAAC,CAAC;YACT,CAAC,EAAE,CAAC;QACN,CAAC;IACH,CAAC;IACD,OAAO,IAAI,MAAM,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC;AAChC,CAAC;AAED,mEAAmE;AACnE,SAAS,OAAO,CAAC,CAAS;IACxB,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAc;IACvC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAC9C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IACnD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAClE,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,KAAgC,CAAC,EAAE,CAAC;QAChE,GAAG,CAAC,IAAI,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CACnC,WAAmB,EACnB,SAAiB,EACjB,aAAqC,UAAU;IAE/C,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAElF,MAAM,GAAG,GAAG,OAAO,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IAC5C,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAC5E,MAAM,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAE5C,MAAM,UAAU,GAAa,EAAE,CAAC;IAEhC,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtE,KAAK,MAAM,GAAG,IAAI,QAAQ;QAAE,UAAU,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,GAAG,EAAE,CAAC,CAAC;IAE7D,kBAAkB;IAClB,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACxG,UAAU,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC;IAE5B,uCAAuC;IACvC,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,CAAC;QAC/B,KAAK,MAAM,GAAG,IAAI,QAAQ;YAAE,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,EAAE,CAAC,CAAC,CAAC;IACzE,CAAC;IAED,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,IAAI,UAAU,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CACtC,WAAmB,EACnB,GAAoB,EACpB,aAAqC,UAAU;IAE/C,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAEhC,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAC9B,KAAK,MAAM,CAAC,IAAI,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC;YAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC/D,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ;QAAE,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACtD,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ;QAAE,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1D,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ;QAAE,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACxD,IAAI,OAAO,GAAG,CAAC,GAAG,KAAK,QAAQ,EAAE,CAAC;QAChC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;SAAM,IAAI,GAAG,CAAC,GAAG,IAAI,OAAO,GAAG,CAAC,GAAG,KAAK,QAAQ,EAAE,CAAC;QAClD,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACvC,IAAI,OAAO,CAAC,KAAK,QAAQ;gBAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;IAED,+EAA+E;IAC/E,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,KAAK,CAAC,GAAG,CAAC,cAAc,GAAG,EAAE,CAAC,CAAC;QAC/B,KAAK,CAAC,GAAG,CAAC,UAAU,GAAG,EAAE,CAAC,CAAC;IAC7B,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,MAAM,CAAC,GAAG,qBAAqB,CAAC,WAAW,EAAE,CAAC,EAAE,UAAU,CAAC,CAAC;QAC5D,IAAI,CAAC;YAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC;AACvB,CAAC;AAED,SAAS,eAAe,CAAC,SAAiB,EAAE,KAAiC;IAC3E,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IACpC,IAAI,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC;IAE5D,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,GAAG,GAAG,QAAQ,CAAC;IACnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACnB,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;YACnC,KAAK,MAAM,CAAC,IAAI,OAAO;gBAAE,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;YAC3C,OAAO,GAAG,CAAC;QACb,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAClB,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC;YAC1C,KAAK,MAAM,CAAC,IAAI,OAAO;gBAAE,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;YAC3C,OAAO,GAAG,CAAC;QACb,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG;YAAE,MAAM;QAC1B,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,OAAO;QAAE,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IAC5C,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAmB,EAAE,SAA8B;IACnF,MAAM,SAAS,GAAG,IAAI,GAAG,EAAyB,CAAC;IACnD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAEhC,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;QAC3B,MAAM,CAAC,GAAG,eAAe,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;QACzC,IAAI,CAAC;YAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACtB,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IACrC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;QAC3C,IAAI,GAAoB,CAAC;QACzB,IAAI,CAAC;YACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAoB,CAAC;QACtE,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,KAAK,MAAM,CAAC,IAAI,wBAAwB,CAAC,IAAI,EAAE,GAAG,CAAC;YAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACzE,CAAC;IAED,MAAM,eAAe,GAAG,IAAI,GAAG,EAAU,CAAC;IAC1C,MAAM,WAAW,GAAG,SAAS,EAAE,WAAW,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAE5D,IAAI,SAAS,EAAE,KAAK,EAAE,CAAC;QACrB,KAAK,MAAM,OAAO,IAAI,SAAS,CAAC,KAAK,EAAE,CAAC;YACtC,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS;YAClE,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;YAC1E,oEAAoE;YACpE,kEAAkE;YAClE,gEAAgE;YAChE,kEAAkE;YAClE,oEAAoE;YACpE,oEAAoE;YACpE,0CAA0C;YAC1C,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACpB,IAAI,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC1B,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;gBACxC,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;oBAC3B,IAAI,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;wBAAE,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBAClD,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IACD,IAAI,SAAS,EAAE,OAAO,EAAE,CAAC;QACvB,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,OAAO,EAAE,CAAC;YACrC,IAAI,OAAO,IAAI,KAAK,QAAQ;gBAAE,SAAS;YACvC,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;YAClC,IAAI,GAAG,IAAI,CAAC,IAAI,GAAG,KAAK,IAAI,CAAC,MAAM,GAAG,CAAC;gBAAE,SAAS;YAClD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;YACnC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;YACjC,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;YAC1E,eAAe,CAAC,GAAG,CAAC,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,CAAC;AACzC,CAAC;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAiB;IAC5C,UAAU,EAAE,IAAI,GAAG,EAAE;IACrB,eAAe,EAAE,IAAI,GAAG,EAAE;CAC3B,CAAC;AAEF,MAAM,UAAU,WAAW,CAAC,GAAiB,EAAE,QAAgB,EAAE,UAAkB;IACjF,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9C,IAAI,GAAG,CAAC,eAAe,CAAC,GAAG,CAAC,GAAG,QAAQ,IAAI,UAAU,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IACtE,OAAO,KAAK,CAAC;AACf,CAAC;AAED,yBAAyB;AACzB,EAAE;AACF,6EAA6E;AAC7E,wEAAwE;AACxE,2EAA2E;AAC3E,yEAAyE;AACzE,yEAAyE;AACzE,oBAAoB;AAEpB,SAAS,WAAW,CAAC,IAAU,EAAE,QAAgB;IAC/C,MAAM,UAAU,GAAG,IAAqD,CAAC;IACzE,IAAI,OAAO,UAAU,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;QAC7C,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,EAAE,CAAC;QAClC,IAAI,IAAI;YAAE,OAAO,IAAI,CAAC;IACxB,CAAC;IACD,IAAI,IAAI,CAAC,WAAW,EAAE,KAAK,kBAAkB,EAAE,CAAC;QAC9C,MAAM,IAAI,GAAI,IAA8C,CAAC,aAAa,EAAE,EAAE,CAAC;QAC/E,IAAI,IAAI,EAAE,OAAO,EAAE,KAAK,UAAU,CAAC,UAAU;YAAE,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC;IACvE,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,+BAA+B,CAC7C,GAAiB,EACjB,aAAuD;IAEvD,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAC3C,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAErD,sEAAsE;IACtE,MAAM,QAAQ,GAAG,CAAC,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG,IAAI,GAAG,CAAS,GAAG,CAAC,UAAU,CAAC,CAAC;IAE7C,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,EAAG,CAAC;QAChC,MAAM,EAAE,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;QAChC,IAAI,CAAC,EAAE;YAAE,SAAS;QAElB,IAAI,QAA2D,CAAC;QAChE,IAAI,CAAC;YACH,QAAQ,GAAG,EAAE,CAAC,uBAAuB,EAAE,CAAC;QAC1C,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QAED,KAAK,MAAM,CAAC,UAAU,EAAE,KAAK,CAAC,IAAI,QAAQ,EAAE,CAAC;YAC3C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC,WAAW,EAAE,CAAC;gBACpD,IAAI,QAAQ,KAAK,KAAK;oBAAE,SAAS;gBACjC,eAAe,CAAC,GAAG,CAAC,GAAG,QAAQ,IAAI,WAAW,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC;gBACpE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;oBACxB,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;oBACnB,+DAA+D;oBAC/D,kEAAkE;oBAClE,iDAAiD;oBACjD,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBAC1B,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,CAAC;AACzC,CAAC"}

package/dist/reporter.d.ts

@@ -28,6 +28,11 @@ export declare function formatReportJSON(report: ReviewReport, options?: {
     includeLLMPrompt?: boolean;
 }): string;
 export declare function formatSARIF(reports: ReviewReport[]): string;
+export interface SARIFMetadataOptions {
+    suppressedFindings?: ReviewFinding[];
+    getBaselineStatus?: (report: ReviewReport, finding: ReviewFinding) => 'new' | 'existing' | undefined;
+}
+export declare function formatSARIFWithMetadata(reports: ReviewReport[], options?: SARIFMetadataOptions): string;
 /**
  * Format SARIF with suppression metadata.
  * Suppressed findings appear with a `suppressions` array per SARIF v2.1.0 section 3.35.

package/dist/reporter.js

@@ -191,6 +191,17 @@ export function formatReport(report, config) {
     const lines = [];
     lines.push(`  @kernlang/review — analyzing ${report.filePath}`);
     lines.push('');
+    // Render health banner BEFORE findings. Users need to know which subsystems skipped/fell
+    // back before they interpret "0 findings" as "the file is clean" — a clean report and a
+    // report where half the checks didn't run used to look identical in the CLI.
+    if (report.health && report.health.entries.length > 0) {
+        const label = report.health.status === 'partial' ? 'PARTIAL' : 'DEGRADED';
+        lines.push(`  [${label}] Review ran in ${report.health.status} mode:`);
+        for (const entry of report.health.entries) {
+            lines.push(`    - ${entry.subsystem} (${entry.kind}): ${entry.message}`);
+        }
+        lines.push('');
+    }
     if (report.inferred.length > 0) {
         lines.push(`  KERN-expressible (${report.inferred.length} constructs):`);
         for (const r of report.inferred) {
@@ -308,6 +319,10 @@ export function formatReportJSON(report, options) {
 }
 // ── SARIF Format ─────────────────────────────────────────────────────────
 export function formatSARIF(reports) {
+    return formatSARIFWithMetadata(reports);
+}
+export function formatSARIFWithMetadata(reports, options = {}) {
+    const { suppressedFindings, getBaselineStatus } = options;
     const sarif = {
         $schema: 'https://schemastore.azurewebsites.net/schemas/json/sarif-2.1.0-rtm.5.json',
         version: '2.1.0',
@@ -321,118 +336,138 @@ export function formatSARIF(reports) {
                     },
                 },
                 results: [],
-            },
-        ],
-    };
-    const rules = new Set();
-    for (const report of reports) {
-        for (const f of report.findings) {
-            if (!rules.has(f.ruleId)) {
-                rules.add(f.ruleId);
-                sarif.runs[0].tool.driver.rules.push({
-                    id: f.ruleId,
-                    shortDescription: { text: f.ruleId },
-                    helpUri: `https://github.com/kern-lang/kern-lang/blob/main/docs/rules.md#${f.ruleId}`,
-                });
-            }
-            const sarifLevel = f.severity === 'error' ? 'error' : f.severity === 'warning' ? 'warning' : 'note';
-            const result = {
-                ruleId: f.ruleId,
-                level: sarifLevel,
-                message: { text: f.message },
-                locations: [
+                // SARIF spec 3.20: invocations describe tool-execution events. toolExecutionNotifications
+                // carries messages FROM the tool (not findings ABOUT the code), which is exactly where
+                // "ESLint skipped" / "call graph failed" belong. Without this, enterprise consumers of
+                // SARIF (GitHub code scanning, Azure DevOps) see 0 results and assume "clean" when the
+                // truth is "half the analyzers didn't run."
+                invocations: [
                     {
-                        physicalLocation: {
-                            artifactLocation: { uri: f.primarySpan.file },
-                            region: {
-                                startLine: f.primarySpan.startLine,
-                                startColumn: f.primarySpan.startCol,
-                                endLine: f.primarySpan.endLine,
-                                endColumn: f.primarySpan.endCol,
-                            },
-                        },
+                        executionSuccessful: true,
+                        toolExecutionNotifications: [],
                     },
                 ],
-            };
-            // SARIF result.rank is 0.0–100.0 per spec; kern/confidence stays 0–1
-            if (f.confidence !== undefined) {
-                result.rank = f.confidence * 100;
-                result.properties = { 'kern/confidence': f.confidence };
-            }
-            sarif.runs[0].results.push(result);
-        }
-    }
-    return JSON.stringify(sarif, null, 2);
-}
-/**
- * Format SARIF with suppression metadata.
- * Suppressed findings appear with a `suppressions` array per SARIF v2.1.0 section 3.35.
- */
-export function formatSARIFWithSuppressions(reports, suppressedFindings) {
-    const sarif = {
-        $schema: 'https://schemastore.azurewebsites.net/schemas/json/sarif-2.1.0-rtm.5.json',
-        version: '2.1.0',
-        runs: [
-            {
-                tool: {
-                    driver: {
-                        name: '@kernlang/review',
-                        version: '2.0.0',
-                        rules: [],
-                    },
-                },
-                results: [],
             },
         ],
     };
+    // Aggregate + dedupe health entries across every report. The in-process ReviewHealthBuilder
+    // already dedupes within one review, but reports from different reviewFile calls can each
+    // carry their own builders — dedupe again here by (subsystem, kind) so SARIF output emits one
+    // notification per distinct failure mode, not one per report.
+    const healthSeen = new Set();
+    let anyError = false;
+    for (const report of reports) {
+        for (const entry of report.health?.entries ?? []) {
+            const key = `${entry.subsystem}:${entry.kind}`;
+            if (healthSeen.has(key))
+                continue;
+            healthSeen.add(key);
+            // SARIF notification levels map to health kinds:
+            //   skipped  -> note     (optional subsystem absent — nothing wrong)
+            //   fallback -> warning  (analysis degraded but still ran)
+            //   error    -> error    (subsystem failed outright; findings may be missing)
+            const level = entry.kind === 'error' ? 'error' : entry.kind === 'fallback' ? 'warning' : 'note';
+            if (entry.kind === 'error')
+                anyError = true;
+            sarif.runs[0].invocations[0].toolExecutionNotifications.push({
+                descriptor: { id: `kern/health/${entry.subsystem}` },
+                level,
+                message: { text: entry.message },
+                properties: {
+                    'kern/subsystem': entry.subsystem,
+                    'kern/kind': entry.kind,
+                    ...(entry.detail !== undefined ? { 'kern/detail': entry.detail } : {}),
+                },
+            });
+        }
+    }
+    // Spec 3.20.6: executionSuccessful=false means the tool raised any error-level notification.
+    // Setting this correctly lets CI systems distinguish "tool ran cleanly, zero findings" from
+    // "tool errored on a subsystem, zero findings from that subsystem don't mean safe code."
+    if (anyError) {
+        sarif.runs[0].invocations[0].executionSuccessful = false;
+    }
     const rules = new Set();
-    // Include file path in suppression key to avoid cross-file fingerprint collisions
     const suppressedSet = new Set(suppressedFindings?.map((f) => `${f.primarySpan.file}:${f.fingerprint}`) ?? []);
-    const allFindings = [...reports.flatMap((r) => r.findings), ...(suppressedFindings ?? [])];
-    for (const f of allFindings) {
-        if (!rules.has(f.ruleId)) {
-            rules.add(f.ruleId);
+    function pushResult(finding, report, overrides = {}) {
+        if (!rules.has(finding.ruleId)) {
+            rules.add(finding.ruleId);
             sarif.runs[0].tool.driver.rules.push({
-                id: f.ruleId,
-                shortDescription: { text: f.ruleId },
-                helpUri: `https://github.com/kern-lang/kern-lang/blob/main/docs/rules.md#${f.ruleId}`,
+                id: finding.ruleId,
+                shortDescription: { text: finding.ruleId },
+                helpUri: `https://github.com/kern-lang/kern-lang/blob/main/docs/rules.md#${finding.ruleId}`,
             });
         }
-        const sarifLevel = f.severity === 'error' ? 'error' : f.severity === 'warning' ? 'warning' : 'note';
+        const sarifLevel = finding.severity === 'error' ? 'error' : finding.severity === 'warning' ? 'warning' : 'note';
+        const baselineStatus = report ? getBaselineStatus?.(report, finding) : undefined;
+        const properties = {};
         const result = {
-            ruleId: f.ruleId,
+            ruleId: finding.ruleId,
             level: sarifLevel,
-            message: { text: f.message },
+            message: { text: finding.message },
             locations: [
                 {
                     physicalLocation: {
-                        artifactLocation: { uri: f.primarySpan.file },
+                        artifactLocation: { uri: finding.primarySpan.file },
                         region: {
-                            startLine: f.primarySpan.startLine,
-                            startColumn: f.primarySpan.startCol,
-                            endLine: f.primarySpan.endLine,
-                            endColumn: f.primarySpan.endCol,
+                            startLine: finding.primarySpan.startLine,
+                            startColumn: finding.primarySpan.startCol,
+                            endLine: finding.primarySpan.endLine,
+                            endColumn: finding.primarySpan.endCol,
                         },
                     },
                 },
             ],
         };
-        if (f.confidence !== undefined) {
-            result.rank = f.confidence * 100;
-            result.properties = { 'kern/confidence': f.confidence };
+        // SARIF result.rank is 0.0–100.0 per spec; kern/confidence stays 0–1
+        if (finding.confidence !== undefined) {
+            result.rank = finding.confidence * 100;
+            properties['kern/confidence'] = finding.confidence;
         }
-        if (suppressedSet.has(`${f.primarySpan.file}:${f.fingerprint}`)) {
-            result.suppressions = [
-                {
-                    kind: 'inSource',
-                    justification: `kern-ignore directive`,
-                },
-            ];
+        if (baselineStatus) {
+            properties['kern/baselineStatus'] = baselineStatus;
+        }
+        if (Object.keys(properties).length > 0) {
+            result.properties = properties;
+        }
+        const suppressions = [];
+        if (overrides.isSuppressedInSource || suppressedSet.has(`${finding.primarySpan.file}:${finding.fingerprint}`)) {
+            suppressions.push({
+                kind: 'inSource',
+                justification: 'kern-ignore directive',
+            });
+        }
+        if (baselineStatus === 'existing') {
+            suppressions.push({
+                kind: 'external',
+                justification: 'Present in review baseline',
+            });
+        }
+        if (suppressions.length > 0) {
+            result.suppressions = suppressions;
         }
         sarif.runs[0].results.push(result);
     }
+    for (const report of reports) {
+        for (const finding of report.findings) {
+            pushResult(finding, report);
+        }
+        for (const finding of report.suppressedFindings ?? []) {
+            pushResult(finding, report, { isSuppressedInSource: true });
+        }
+    }
+    for (const finding of suppressedFindings ?? []) {
+        pushResult(finding, undefined, { isSuppressedInSource: true });
+    }
     return JSON.stringify(sarif, null, 2);
 }
+/**
+ * Format SARIF with suppression metadata.
+ * Suppressed findings appear with a `suppressions` array per SARIF v2.1.0 section 3.35.
+ */
+export function formatSARIFWithSuppressions(reports, suppressedFindings) {
+    return formatSARIFWithMetadata(reports, { suppressedFindings });
+}
 // ── Multi-file Summary ───────────────────────────────────────────────────
 export function formatSummary(reports) {
     const lines = [];