prehello 0.0.0-stage → 1.0.0

package/dist/render/png.js

@@ -0,0 +1,162 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PNG_MAGIC = exports.PNG_UNAVAILABLE_MESSAGE = exports.FONT_DIR = exports.PNG_CHAR_EM = exports.PNG_FONT_FAMILY = exports.PngUnavailableError = void 0;
+exports.detectInstallKind = detectInstallKind;
+exports.pngUnavailableMessage = pngUnavailableMessage;
+exports.loadEngine = loadEngine;
+exports.toFontSafeText = toFontSafeText;
+exports.tagPng = tagPng;
+exports.svgToPng = svgToPng;
+/**
+ * PNG export of the share card. Pure JS + WebAssembly: no native binaries, no network, no child processes.
+ *
+ * Engine: `@resvg/resvg-wasm` (MPL-2.0), an OPTIONAL dependency. If it is not installed, prehello says so and SVG keeps working.
+ * Fonts: three subsetted static weights of Inter (SIL OFL 1.1, see assets/fonts/OFL.txt) are shipped in the package and handed to the
+ * renderer as buffers. System fonts are never used, so the PNG looks the same on every machine and can never show "tofu" boxes
+ * for the glyphs a card uses (ASCII, Latin-1, and a handful of punctuation marks).
+ */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+class PngUnavailableError extends Error {
+}
+exports.PngUnavailableError = PngUnavailableError;
+/** Family name the PNG variant of the SVG asks for; it matches the name inside the shipped font files. */
+exports.PNG_FONT_FAMILY = "Inter";
+const FONT_FILES = ["Inter-Regular.subset.ttf", "Inter-SemiBold.subset.ttf", "Inter-ExtraBold.subset.ttf"];
+/** Average advance of the shipped Inter weights is 0.46-0.50 em on card text and 0.58-0.61 on caps and digits; layout uses this (the system-font stack uses a wider 0.62). */
+exports.PNG_CHAR_EM = 0.58;
+exports.FONT_DIR = node_path_1.default.join(__dirname, "..", "..", "assets", "fonts");
+function detectInstallKind(dir = __dirname, hasPackageJson = (d) => node_fs_1.default.existsSync(node_path_1.default.join(d, "package.json"))) {
+    const hits = [...dir.matchAll(/[\\/]node_modules(?=[\\/]|$)/g)];
+    if (!hits.length)
+        return "source";
+    if (dir.split(/[\\/]+/).includes("_npx"))
+        return "npx";
+    // <something>/node_modules/prehello/dist/render -> <something> is a project (has package.json) for a local install,
+    // and a global prefix (<prefix>/lib or %APPDATA%\npm, no package.json) for `npm install -g`.
+    const holder = dir.slice(0, hits[hits.length - 1].index) || "/";
+    return hasPackageJson(holder) ? "local" : "global";
+}
+/**
+ * Printed (stderr) when PNG is asked for and the optional engine is missing. Same wording on Linux, macOS and Windows: npm commands
+ * are identical there. The detected install kind is marked, the other ways follow, and SVG is always offered.
+ */
+function pngUnavailableMessage(kind = "unknown") {
+    const here = (k) => (kind === k ? "   <- how this prehello was installed" : "");
+    return [
+        "PNG cards need the optional package @resvg/resvg-wasm, which is not installed here, so no card was written (everything else in this run completed normally).",
+        "Install it, then run the same command again:",
+        `  global install of prehello:  npm install -g @resvg/resvg-wasm${here("global")}`,
+        `  project install:             npm install @resvg/resvg-wasm   (run it in the project that has prehello in node_modules)${here("local")}`,
+        `  one-off with npx:            npx --package prehello --package @resvg/resvg-wasm -- prehello --card=card.png${here("npx")}`,
+        ...(kind === "source" ? ["  from a source checkout:      npm install   (in the prehello folder)   <- how this prehello is running"] : []),
+        "  if you installed with --omit=optional (or npm config optional=false), reinstall without it.",
+        "Or skip PNG: an SVG card needs no extra install, e.g. --card=card.svg (browsers and most image tools open it).",
+    ].join("\n");
+}
+/** Generic form of the message (install kind unknown). */
+exports.PNG_UNAVAILABLE_MESSAGE = pngUnavailableMessage();
+let engine;
+/** Loads the optional engine once. `resolver` exists so tests can simulate a missing dependency. */
+function loadEngine(resolver = require.resolve) {
+    if (engine)
+        return engine;
+    const p = (async () => {
+        let mod;
+        let wasmPath;
+        try {
+            wasmPath = resolver("@resvg/resvg-wasm/index_bg.wasm");
+            mod = require(resolver("@resvg/resvg-wasm"));
+        }
+        catch {
+            throw new PngUnavailableError(pngUnavailableMessage(detectInstallKind()));
+        }
+        try {
+            await mod.initWasm(node_fs_1.default.readFileSync(wasmPath));
+        }
+        catch (e) {
+            const msg = e.message;
+            // initWasm throws "Already initialized" when something else in the process initialised it: harmless.
+            if (!/already initialized/i.test(msg))
+                throw new PngUnavailableError(`PNG export could not start its WebAssembly renderer (${msg}). Reinstalling it may help: npm install @resvg/resvg-wasm. Or write an SVG instead: --card=card.svg`);
+        }
+        return mod;
+    })();
+    // a failed load is not cached when the caller injected a resolver (tests); the real one is cached either way
+    if (resolver === require.resolve)
+        engine = p;
+    return p;
+}
+/** Every glyph the card can print is in the font subset; anything else (never expected) becomes "?" rather than a tofu box. */
+function toFontSafeText(svg) {
+    return svg.replace(/[^\x09\x0a\x0d\x20-\x7e\u00a0-\u00ff\u2013\u2014\u2018\u2019\u201c\u201d\u2022\u2026\u2192\u2212\u2248\u2264\u2265]/gu, "?");
+}
+const CRC_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+function crc32(buf) {
+    let c = 0xffffffff;
+    for (let i = 0; i < buf.length; i++)
+        c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+function textChunk(keyword, text) {
+    const data = Buffer.concat([Buffer.from(keyword, "latin1"), Buffer.from([0]), Buffer.from(text, "latin1")]);
+    const body = Buffer.concat([Buffer.from("tEXt", "latin1"), data]);
+    const len = Buffer.alloc(4);
+    len.writeUInt32BE(data.length);
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(body));
+    return Buffer.concat([len, body, crc]);
+}
+/** Adds `Software` and `Description` tEXt chunks right after IHDR. This is how prehello recognises its own PNG before replacing it. */
+function tagPng(png, version) {
+    const ihdrEnd = 8 + 4 + 4 + 13 + 4; // signature + length + type + data + crc
+    return Buffer.concat([
+        png.subarray(0, ihdrEnd),
+        textChunk("Software", `prehello ${version}`),
+        textChunk("Description", "Share card generated locally by prehello. Token counts are estimates."),
+        png.subarray(ihdrEnd),
+    ]);
+}
+exports.PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+/** Rasterises a card SVG (made with `fontFamily: PNG_FONT_FAMILY`) to a PNG buffer. Throws PngUnavailableError when the engine is missing. */
+async function svgToPng(svg, o) {
+    const { Resvg } = await loadEngine(o.resolver);
+    let fontBuffers;
+    try {
+        fontBuffers = FONT_FILES.map((f) => new Uint8Array(node_fs_1.default.readFileSync(node_path_1.default.join(exports.FONT_DIR, f))));
+    }
+    catch {
+        throw new PngUnavailableError("PNG export could not read prehello's bundled fonts (assets/fonts is missing from this install). Reinstall prehello, or write an SVG instead: --card=card.svg");
+    }
+    const width = Number(/<svg[^>]*\swidth="(\d+)"/.exec(svg)?.[1] ?? 1200);
+    try {
+        const r = new Resvg(toFontSafeText(svg), {
+            font: { fontBuffers, defaultFontFamily: exports.PNG_FONT_FAMILY, sansSerifFamily: exports.PNG_FONT_FAMILY },
+            fitTo: { mode: "width", value: width * o.scale },
+            textRendering: 1,
+            shapeRendering: 2,
+        });
+        try {
+            return tagPng(Buffer.from(r.render().asPng()), o.version);
+        }
+        finally {
+            r.free();
+        }
+    }
+    catch (e) {
+        // never a stack trace: a renderer failure is reported like a missing engine, and SVG keeps working
+        throw new PngUnavailableError(`PNG rendering failed (${String(e?.message ?? e).slice(0, 200)}). Write an SVG instead: --card=card.svg`);
+    }
+}

package/dist/render/sarif.js

@@ -0,0 +1,472 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RULES = exports.WARN_WINDOW_PCT = exports.HEAVY_GROUP_TOKENS = exports.LARGE_ITEM_TOKENS = exports.SRCROOT = exports.SARIF_SCHEMA = void 0;
+exports.sarifText = sarifText;
+exports.toSarif = toSarif;
+exports.renderSarif = renderSarif;
+/**
+ * SARIF 2.1.0 report (--sarif): for GitHub code scanning, VS Code's SARIF viewer and other IDE / CI tools.
+ *
+ * Privacy by construction (same contract as the card and the Markdown report):
+ *  - No file contents, no finding or warning TEXTS (those name user-level paths); every message is built here from numbers and generic words.
+ *  - A physicalLocation is emitted ONLY for a file inside the scanned project folder, as a relative URI against %SRCROOT%. Never an absolute
+ *    path, never a home or user-config path (~/.claude, ~/.cursor, ...), never a path that looks like it holds a secret or has control characters.
+ *    User-level items (user, managed, plugin, built-in) get a logicalLocation with a generic label ("User CLAUDE.md") and no file location.
+ *  - `strict` (--redact): no physical locations at all, generic labels only. `anonymize`: plugin / MCP server names become "plugin 1" / "MCP server 1".
+ *  - Token numbers are ESTIMATES (`isEstimate: true`), an unmeasured item never carries a number (never 0), and a total that is a lower bound says "at least".
+ */
+const node_crypto_1 = require("node:crypto");
+const node_path_1 = __importDefault(require("node:path"));
+const savings_1 = require("../analyze/savings");
+const card_1 = require("./card");
+const fmt_1 = require("../util/fmt");
+const json_1 = require("./json");
+const fs_safe_1 = require("../fs-safe");
+const redact_1 = require("../redact");
+exports.SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json";
+exports.SRCROOT = "%SRCROOT%";
+/** An always-on file is reported (PH001) from this size on, or from 1% of the window. */
+exports.LARGE_ITEM_TOKENS = 2000;
+/** A plugin / skills folder / MCP server is reported (PH002) from this size on. */
+exports.HEAVY_GROUP_TOKENS = 1000;
+/** Warning instead of note from this share of the window (one item or group). */
+exports.WARN_WINDOW_PCT = 5;
+const MAX_GROUPS_PER_AGENT = 10;
+exports.RULES = [
+    {
+        id: "PH001",
+        name: "LargeAlwaysOnFile",
+        level: "note",
+        short: "A file that loads before the first message is large",
+        full: "An instruction, rule or memory file that the coding agent loads into context before the first message costs a lot of tokens. The count is an estimate (o200k BPE with a per-agent scaling prior).",
+        help: "Trim the file, split rarely needed material into scoped rules or skills, or move reference text out of always-loaded files. Token counts are estimates with an error band, not exact for any model.",
+        precision: "medium",
+    },
+    {
+        id: "PH002",
+        name: "HeavyAlwaysOnGroup",
+        level: "note",
+        short: "A plugin, skills folder or MCP server costs many tokens before the first message",
+        full: "The listing of a plugin's skills, a skills folder or an MCP server's tool definitions is part of the always-on context. This is what `prehello --fix` calls the cut list. The count is an estimate.",
+        help: "If you do not use it, disable or remove the plugin, skills folder or MCP server in the agent's own settings. prehello never edits agent configuration. The saving is an estimate, not a promise.",
+        precision: "medium",
+    },
+    {
+        id: "PH003",
+        name: "OverTokenBudget",
+        level: "warning",
+        short: "Always-on context is above the --max-tokens budget",
+        full: "The estimated always-on token count of an agent in use is above the budget given with --max-tokens. When some always-on items could not be measured, the total is a lower bound (at least).",
+        help: "Cut the biggest contributors (see PH001 and PH002), or raise the budget if the size is intentional. This result only exists when --max-tokens is given; the same condition makes prehello exit with code 2.",
+        precision: "medium",
+    },
+    {
+        id: "PH004",
+        name: "UnmeasuredAlwaysOnItems",
+        level: "note",
+        short: "Some always-loaded items could not be measured",
+        full: "Some items that load before the first message (typically MCP servers whose tools are only known at runtime) have no token count. Their cost is unknown, not zero, so every always-on total for this agent is a lower bound.",
+        help: "No action is required. Treat the totals as 'at least'. You can supply measured weights with --mcp-catalog.",
+        precision: "low",
+    },
+    {
+        id: "PH005",
+        name: "DuplicateContextFiles",
+        level: "warning",
+        short: "Two context files are near-duplicates",
+        full: "Two files that agents load share most of their text (60% or more). If one agent loads both, the text is paid for twice.",
+        help: "Keep one copy. Claude Code @imports do not reduce cost. If different agents read the two files, do not delete either; make one the source of truth (for example a CLAUDE.md that only contains @AGENTS.md, or a symlink).",
+        precision: "medium",
+    },
+    {
+        id: "PH006",
+        name: "LongInstructionFile",
+        level: "note",
+        short: "An always-loaded file is longer than the documented guideline",
+        full: "The file is longer than the length the agent's documentation recommends (Claude Code: 200 lines for CLAUDE.md, Cursor: 500 lines per rule). Longer files can reduce how well the agent follows them.",
+        help: "Split the file into scoped rules or move reference material out of the always-loaded file.",
+        precision: "medium",
+    },
+    {
+        id: "PH007",
+        name: "SilentTruncation",
+        level: "warning",
+        short: "Part of a context file is silently dropped by the agent",
+        full: "The agent cuts this content off at a documented limit (Codex 32 KiB project docs, Claude Code MEMORY.md 200 lines / 25 KB, the skill description cap), so the tail never reaches the model.",
+        help: "Shorten the file or the description, and put the important parts first.",
+        precision: "medium",
+    },
+    {
+        id: "PH008",
+        name: "IgnoredContextFile",
+        level: "warning",
+        short: "A context file is ignored by the agent",
+        full: "The agent does not load this file (for example AGENTS.md next to a CLAUDE.md for Claude Code, or a .md file in .cursor/rules for Cursor). Other agents may still read it.",
+        help: "Rename or restructure the file if you intend the agent to use it, or delete it if it is stale.",
+        precision: "medium",
+    },
+    {
+        id: "PH009",
+        name: "PossibleSecretInContextFile",
+        level: "warning",
+        short: "A context file contains something that looks like a secret",
+        full: "A line of this file matches a secret pattern (cloud keys, tokens, private key headers, key=value credentials). The value is never printed or stored by prehello. Agents send context files to a model provider.",
+        help: "Remove the secret from the file and rotate it. This is a pattern match and can be a false positive.",
+        precision: "low",
+    },
+    {
+        id: "PH010",
+        name: "SkillsListingOverBudget",
+        level: "note",
+        short: "A skills listing is above the agent's listing budget",
+        full: "The skills listing is estimated to be larger than the share of the window the agent reserves for it, so the agent shortens or drops descriptions of the least used skills.",
+        help: "Remove skills you do not use, or switch rarely used skills to name-only where the agent supports it.",
+        precision: "low",
+    },
+    {
+        id: "PH011",
+        name: "IncompleteScan",
+        level: "note",
+        short: "Some sources could not be read or the scan hit its budget",
+        full: "Some files were unreadable, too large, binary or skipped, or the scan stopped at its byte or time budget. Every total is then a lower bound.",
+        help: "Run prehello locally to see which sources were skipped, or raise --scan-budget-mb / --scan-budget-ms.",
+        precision: "low",
+    },
+];
+const RULE_INDEX = new Map(exports.RULES.map((r, i) => [r.id, i]));
+/** Finding id -> rule. F5 (unmeasured) is reported per agent as PH004 from the coverage numbers instead. */
+const FINDING_RULE = { F1: "PH006", F2: "PH005", F4: "PH007", F8: "PH007", F12: "PH007", F7: "PH008", F11: "PH008", F9: "PH009", F13: "PH010" };
+const ZERO_WIDTH = /[\u200b-\u200f\u2028\u2029\u2060\ufeff]/g;
+/** A user-controlled name inside SARIF message text: no control / bidi characters, no secrets, `[ ] \` escaped (SARIF reads `[text](n)` as a link). */
+function sarifText(s, max = 80) {
+    const t = (0, fmt_1.sanitize)(s.replace(/[\r\n\t\v\f]+/g, " "), 400).replace(ZERO_WIDTH, "").replace(/\s+/g, " ").trim();
+    const cut = t.length > max ? t.slice(0, max - 3) + "..." : t;
+    return (cut || "(unnamed)").replace(/[\\[\]]/g, (c) => "\\" + c);
+}
+const plural = (n, one, many = one + "s") => `${n} ${n === 1 ? one : many}`;
+function isHomeOrAncestor(cwd, home) {
+    const rel = node_path_1.default.relative(cwd, home);
+    return rel === "" || (!rel.startsWith("..") && !node_path_1.default.isAbsolute(rel));
+}
+function insideRel(base, p) {
+    const rel = node_path_1.default.relative(base, p);
+    if (rel === "" || rel === ".." || rel.startsWith(".." + node_path_1.default.sep) || node_path_1.default.isAbsolute(rel))
+        return null;
+    return rel;
+}
+/** Everything that turns SARIF input into output. Exported for tests. */
+function toSarif(r, o) {
+    const cwd = (0, fs_safe_1.realpathOrSelf)(o.cwd);
+    const home = (0, fs_safe_1.realpathOrSelf)(o.home);
+    const shown = r.agents.filter((a) => !a.presentInRepoOnly);
+    const noFiles = o.strict || isHomeOrAncestor(cwd, home);
+    // user-level, managed, plugin and built-in items never get a file location, even if a path looks like it is inside the project
+    const userLevel = new Set();
+    for (const a of r.agents)
+        for (const it of a.items)
+            if (!["project", "local", "nested"].includes(it.scope))
+                userLevel.add(it.path);
+    function locate(p, line = 1) {
+        if (noFiles || userLevel.has(p))
+            return undefined;
+        const rel = insideRel(cwd, p);
+        if (rel === null)
+            return undefined;
+        const real = insideRel(cwd, (0, fs_safe_1.realpathOrSelf)(p));
+        if (real === null)
+            return undefined; // a symlink pointing out of the project
+        // eslint-disable-next-line no-control-regex
+        if (/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/.test(rel) || (0, redact_1.scrubSecrets)(rel) !== rel)
+            return undefined;
+        const segs = rel.split(node_path_1.default.sep);
+        return { uri: segs.map((s) => encodeURIComponent(s)).join("/"), shown: sarifText(segs.join("/"), 120), line: Math.max(1, Math.floor(line)) };
+    }
+    const recs = new Map();
+    const add = (x) => {
+        const cur = recs.get(x.key);
+        if (!cur) {
+            recs.set(x.key, x);
+            return;
+        }
+        for (const a of x.agents)
+            if (!cur.agents.includes(a))
+                cur.agents.push(a);
+        if (x.level === "warning")
+            cur.level = "warning";
+        // merged agents: keep the biggest numbers; per-agent numbers stay in `props.perAgent`
+        const pa = cur.props.perAgent ?? [];
+        cur.props.perAgent = [...pa, ...(x.props.perAgent ?? [])];
+    };
+    const levelFor = (tokens, window) => ((tokens / window) * 100 >= exports.WARN_WINDOW_PCT ? "warning" : "note");
+    const W = r.scan.window;
+    const est = (t) => ({ estimateTokens: t.est, lowTokens: t.low, highTokens: t.high, isEstimate: true });
+    for (const a of shown) {
+        const labels = (0, json_1.numberedLabels)(a);
+        // PH001: big always-on single items
+        for (const it of a.items) {
+            if (it.loadMode !== "always" || !it.tokens || it.kind === "skills-listing" || it.kind === "mcp-server")
+                continue;
+            if (it.tokens.est < exports.LARGE_ITEM_TOKENS && (it.tokens.est / W) * 100 < 1)
+                continue;
+            const loc = locate(it.path);
+            const label = sarifText(labels.get(it.id) ?? it.cardLabel);
+            add({
+                rule: "PH001",
+                key: loc ? `PH001|${loc.uri}` : `PH001|${a.id}|${label}`,
+                level: levelFor(it.tokens.est, W),
+                agents: [a.name],
+                loc,
+                logical: loc ? undefined : { name: label, fq: `${a.id}/${label}` },
+                d: { label },
+                props: { perAgent: [{ agent: a.id, kind: it.kind, scope: it.scope, loadMode: it.loadMode, ...est(it.tokens), percentOfWindow: round1((it.tokens.est / W) * 100), tokens: it.tokens.est }] },
+                fp: loc ? loc.uri : `${a.id}/${label}`,
+            });
+        }
+        // PH002: heavy removable groups (same groups, order and names as the card and the cut list)
+        const cands = (0, savings_1.cutCandidatesWithSource)(a.items);
+        const tiles = (0, savings_1.cardTiles)(a.items, o.anonymize);
+        const byCut = new Map(tiles.filter((t) => t.cut !== undefined).map((t) => [t.cut, t]));
+        let emitted = 0;
+        cands.forEach((c, i) => {
+            if (c.tokens < exports.HEAVY_GROUP_TOKENS || emitted >= MAX_GROUPS_PER_AGENT)
+                return;
+            emitted++;
+            const t = byCut.get(i);
+            const name = sarifText(t ? t.label : c.label);
+            const loc = c.kind === "mcp" ? locate(c.source.path) : undefined;
+            add({
+                rule: "PH002",
+                key: `PH002|${a.id}|${c.kind}|${name}|${loc?.uri ?? ""}`,
+                level: levelFor(c.tokens, W),
+                agents: [a.name],
+                loc,
+                logical: { name, fq: `${a.id}/${name}` },
+                d: { name, kind: c.kind, count: c.count },
+                props: { perAgent: [{ agent: a.id, kind: c.kind === "mcp" ? "mcp-server" : "skills", scope: c.source.scope, estimateTokens: c.tokens, isEstimate: true, skills: c.kind === "skills" ? c.count : undefined, percentOfWindow: round1((c.tokens / W) * 100), tokens: c.tokens }] },
+                fp: `${a.id}/${c.kind}/${name}`,
+            });
+        });
+        // PH003: --max-tokens
+        if (o.maxTokens !== undefined && a.totals.always.est > o.maxTokens) {
+            add({
+                rule: "PH003",
+                key: `PH003|${a.id}`,
+                level: "warning",
+                agents: [a.name],
+                logical: { name: a.name, fq: a.id },
+                d: { est: a.totals.always.est, max: o.maxTokens, lower: a.lowerBound },
+                props: { perAgent: [{ agent: a.id, ...est(a.totals.always), isLowerBound: a.lowerBound, maxTokens: o.maxTokens, tokens: a.totals.always.est }] },
+                fp: a.id,
+            });
+        }
+        // PH004: unmeasured always-on items (counts and kinds only)
+        const un = a.totals.always.unmeasuredItems;
+        if (un > 0) {
+            add({
+                rule: "PH004",
+                key: `PH004|${a.id}`,
+                level: "note",
+                agents: [a.name],
+                logical: { name: a.name, fq: a.id },
+                d: { n: un, kinds: a.coverage.unmeasuredKinds, est: a.totals.always.est, measured: a.totals.always.measuredItems },
+                props: { perAgent: [{ agent: a.id, unmeasuredItems: un, unmeasuredKinds: a.coverage.unmeasuredKinds, measuredItems: a.totals.always.measuredItems, alwaysTokensAtLeast: a.totals.always.measuredItems ? a.totals.always.est : null, isLowerBound: true }] },
+                fp: a.id,
+            });
+        }
+    }
+    // findings -> PH005..PH010 (messages rebuilt from structured data; the finding's own text names user-level paths)
+    const visibleAgents = new Set(shown.map((a) => a.id));
+    const nameOf = (f) => (f.agent === "all" ? shown.map((a) => a.name) : [shown.find((a) => a.id === f.agent)?.name ?? String(f.agent)]);
+    r.findings.forEach((f, fi) => {
+        const rule = FINDING_RULE[f.id];
+        if (!rule || (f.agent !== "all" && !visibleAgents.has(f.agent)))
+            return;
+        if (f.data?.omittedPairs)
+            return; // a "N more not listed" summary has no file; the count goes into the run properties
+        const lvl = exports.RULES[RULE_INDEX.get(rule)].level;
+        const agents = f.id === "F2" || f.id === "F9" ? [] : nameOf(f);
+        const first = f.paths[0] ? locate(f.paths[0], f.data?.lines?.[0] ?? 1) : undefined;
+        const second = f.id === "F2" && f.paths[1] ? locate(f.paths[1]) : undefined;
+        const primary = first ?? second;
+        const other = first && second ? second : undefined;
+        const outside = f.id === "F2" ? f.paths.length - [first, second].filter(Boolean).length : 0;
+        const gen = f.agent === "all" ? "agents" : agents[0];
+        add({
+            rule,
+            key: primary ? `${rule}|${f.id}|${primary.uri}${other ? "|" + other.uri : ""}` : `${rule}|${f.id}|${f.agent}|#${fi}`,
+            level: lvl,
+            agents,
+            loc: primary,
+            related: other,
+            logical: primary ? undefined : { name: f.agent === "all" ? "context files" : agents[0], fq: `${f.agent}/${f.id}` },
+            d: { fid: f.id, gen, outside, ...f.data, secretLines: f.data?.lines },
+            props: { findingId: f.id, confidence: f.confidence, ...(f.savingsTokens !== undefined ? { savingsTokensEstimate: f.savingsTokens, savingsIsEstimate: true } : {}), ...(f.data?.lines ? { lines: f.data.lines } : {}), ...(f.data?.similarityPct !== undefined ? { similarityPercent: f.data.similarityPct } : {}), ...(f.data?.fileLines !== undefined ? { fileLines: f.data.fileLines, guidelineLines: f.data.guidelineLines } : {}) },
+            fp: `${f.id}/${primary?.uri ?? `${f.agent}#${fi}`}/${other?.uri ?? ""}`,
+        });
+    });
+    // PH011: partial / unreadable sources
+    if (r.partial || r.warnings.length) {
+        add({
+            rule: "PH011",
+            key: "PH011",
+            level: "note",
+            agents: [],
+            logical: { name: "scan", fq: "scan" },
+            d: {},
+            props: { warnings: r.warnings.length, ...(r.partial ? { budget: r.partial.reason, filesNotRead: r.partial.filesNotRead } : {}) },
+            fp: "scan",
+        });
+    }
+    const results = [...recs.values()].map((x) => finalize(x, r, o)).sort((a, b) => (0, fmt_1.cmp)(a.ruleId, b.ruleId) || (0, fmt_1.cmp)(a.sortKey, b.sortKey)).map(({ sortKey: _s, ...res }) => res);
+    return {
+        $schema: exports.SARIF_SCHEMA,
+        version: "2.1.0",
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: "prehello",
+                        version: r.tool.version,
+                        semanticVersion: r.tool.version,
+                        shortDescription: { text: "Shows what a coding agent loads into context before the first message. Token counts are estimates." },
+                        rules: exports.RULES.map((d) => ({
+                            id: d.id,
+                            name: d.name,
+                            shortDescription: { text: d.short },
+                            fullDescription: { text: d.full },
+                            help: { text: `${d.help}\nThe rule list is in docs/REFERENCE.md (SARIF) in the prehello repository.`, markdown: `${d.help}\n\nThe rule list is in docs/REFERENCE.md (SARIF) in the prehello repository.` },
+                            defaultConfiguration: { level: d.level },
+                            properties: { tags: ["context", "tokens", "coding-agents"], precision: d.precision },
+                        })),
+                    },
+                },
+                columnKind: "utf16CodeUnits",
+                originalUriBaseIds: { [exports.SRCROOT]: { description: { text: "The scanned project folder. Run prehello from the repository root so these paths match the repository." } } },
+                automationDetails: { id: "prehello/" },
+                invocations: [{ executionSuccessful: true, endTimeUtc: r.generatedAt, properties: { partial: !!r.partial } }],
+                results,
+                properties: runProps(r, shown, o, noFiles),
+            },
+        ],
+    };
+}
+const round1 = (x) => Math.round(x * 10) / 10;
+function runProps(r, shown, o, noFiles) {
+    return {
+        prehello: {
+            note: "All token numbers are estimates (o200k BPE with per-agent scaling factors), not exact for any model. An unmeasured item has no number, never 0. A total marked isLowerBound is 'at least'.",
+            tokenizer: r.scan.tokenizer.method,
+            claudeProfile: r.scan.claudeProfile,
+            windowTokens: r.scan.window,
+            redacted: o.strict,
+            namesAnonymized: o.anonymize,
+            fileLocations: !noFiles,
+            partial: r.partial ?? null,
+            ...(r.scan.fixturesSkipped ? { fixtureFoldersSkipped: r.scan.fixturesSkipped } : {}),
+            duplicatePairsNotListed: r.findings.reduce((n, f) => n + (f.data?.omittedPairs ?? 0), 0),
+            agents: shown.map((a) => ({
+                id: a.id,
+                profile: a.profile.id,
+                band: a.profile.band,
+                always: { ...{ estimateTokens: a.totals.always.measuredItems ? a.totals.always.est : null, lowTokens: a.totals.always.measuredItems ? a.totals.always.low : null, highTokens: a.totals.always.measuredItems ? a.totals.always.high : null }, isEstimate: true, isLowerBound: a.lowerBound, measuredItems: a.totals.always.measuredItems, unmeasuredItems: a.totals.always.unmeasuredItems },
+                percentOfWindow: a.percentOfWindowAlways === null ? null : round1(a.percentOfWindowAlways),
+                grade: a.grade ? { letter: a.grade.letter, provisional: a.grade.provisional, heuristic: true } : null,
+                savings: a.savings ? { topGroups: a.savings.n, estimateTokens: a.savings.topTokens, isEstimate: true } : null,
+            })),
+        },
+    };
+}
+function agentList(names) {
+    if (names.length <= 1)
+        return names[0] ?? "the agent";
+    return names.slice(0, -1).join(", ") + " and " + names[names.length - 1];
+}
+function finalize(x, r, o) {
+    const W = r.scan.window;
+    const per = x.props.perAgent ?? [];
+    const names = x.agents;
+    const d = x.d;
+    const fid = d.fid;
+    let text = "";
+    const sum = (k) => per.map((p) => p[k]).filter((v) => typeof v === "number");
+    switch (x.rule) {
+        case "PH001": {
+            const parts = per.map((p, i) => `${names[i] ?? "the agent"} ~${(0, fmt_1.fmtTok)(p.estimateTokens)}`);
+            const pct = Math.max(...sum("percentOfWindow"));
+            text = `This file is always loaded before the first message (${agentList(parts)} tokens, estimate; up to ${(0, fmt_1.fmtPct)(pct)} of a ${(0, fmt_1.fmtWindow)(W)} window).${x.loc ? "" : ` Item: ${d.label}.`}`;
+            break;
+        }
+        case "PH002": {
+            const p = per[0];
+            const cnt = d.kind === "skills" && d.count > 1 ? ` (${plural(d.count, "skill")})` : "";
+            text = `"${d.name}"${cnt} adds ~${(0, fmt_1.fmtTok)(p.estimateTokens)} tokens before the first message in ${names[0]} (estimate; ${(0, fmt_1.fmtPct)((p.estimateTokens / W) * 100)} of a ${(0, fmt_1.fmtWindow)(W)} window). Removing it would save about that much.`;
+            break;
+        }
+        case "PH003":
+            text = `${names[0]}: always-on context is ${d.lower ? card_1.AT_LEAST + " " : ""}~${(0, fmt_1.fmtTok)(d.est)} tokens (estimate), above --max-tokens ${(0, fmt_1.fmtTok)(d.max)}.${d.lower ? " Some items are unmeasured, so the real number is higher." : ""}`;
+            break;
+        case "PH004": {
+            const KIND_WORDS = { "mcp-server": ["MCP server", "MCP servers"], instructions: ["instruction file", "instruction files"], rule: ["rule", "rules"], memory: ["memory file", "memory files"] };
+            const kinds = Object.entries(d.kinds).map(([k, n]) => `${n} ${(KIND_WORDS[k] ?? [k, k])[n === 1 ? 0 : 1]}`).join(", ");
+            text = `${names[0]}: ${plural(d.n, "always-loaded item")} could not be measured (${kinds}). ${d.n === 1 ? "Its" : "Their"} token cost is unknown, not zero, so the always-on total${d.measured ? ` of ${card_1.AT_LEAST} ~${(0, fmt_1.fmtTok)(d.est)} tokens (estimate)` : ""} is a lower bound.`;
+            break;
+        }
+        case "PH005": {
+            const rel = x.related ? ` The other file: [${x.related.shown}](1).` : x.loc && d.outside > 0 ? " The other file is outside the project, so it is not shown." : "";
+            const where = x.loc ? "This file is" : "Two context files are";
+            text = `${where} about ${d.similarityPct}% the same text (estimated from shared 5-word sequences).${rel} Keep one copy, or make one the source of truth.`;
+            break;
+        }
+        case "PH006":
+            text = `This file is ${d.fileLines} lines, over the documented guideline of ${d.guidelineLines} for ${agentList(names)}; longer files can reduce adherence.`;
+            break;
+        case "PH007":
+            text = fid === "F8" ? `MEMORY.md is over the load cap (200 lines / 25 KB) for ${agentList(names)}; the rest is silently dropped.` : fid === "F12" ? `${agentList(names)} cuts this file off at project_doc_max_bytes; only the first part is loaded.` : `A skill description is over the length cap for ${agentList(names)}; its tail is dropped from the skills listing.`;
+            break;
+        case "PH008":
+            text = fid === "F11" ? `${agentList(names)} ignores this file: only .mdc files in .cursor/rules are loaded.` : `${agentList(names)} ignores this file: a CLAUDE.md exists in the directory tree and takes precedence. Other agents may still load it.`;
+            break;
+        case "PH009": {
+            const ls = d.secretLines ?? [];
+            text = `Possible secret on line${ls.length > 1 ? "s" : ""} ${ls.slice(0, 5).join(", ")}${ls.length > 5 ? ", ..." : ""} (value not shown; pattern match, may be a false positive). Agents send this file to a model provider: remove the secret and rotate it.`;
+            break;
+        }
+        case "PH010":
+            text = `The skills listing for ${agentList(names)} is estimated above its listing budget; descriptions of rarely used skills are shortened or dropped.`;
+            break;
+        default:
+            text = `Some sources could not be read or were skipped${r.partial ? `, or the scan hit its ${r.partial.reason} budget` : ""}. Every total is a lower bound.`;
+    }
+    const loc = x.loc;
+    const locations = [];
+    if (loc)
+        locations.push({ physicalLocation: { artifactLocation: { uri: loc.uri, uriBaseId: exports.SRCROOT }, region: { startLine: loc.line } } });
+    else if (x.logical)
+        locations.push({ logicalLocations: [{ name: x.logical.name, fullyQualifiedName: x.logical.fq, kind: "module" }] });
+    const props = { ...x.props };
+    if (per.length)
+        props.perAgent = per.map((p) => Object.fromEntries(Object.entries(p).filter(([k, v]) => v !== undefined && k !== "tokens")));
+    if (names.length)
+        props.agents = names;
+    props.anonymized = o.anonymize || o.strict;
+    const hash = (0, node_crypto_1.createHash)("sha256").update(`${x.rule}|${x.fp}`).digest("hex").slice(0, 32);
+    const ri = RULE_INDEX.get(x.rule);
+    const sortKey = `${loc?.uri ?? ""}|${x.logical?.fq ?? ""}|${String(1e9 - Math.max(0, ...per.map((p) => p.tokens ?? 0))).padStart(10, "0")}|${text}`;
+    return {
+        ruleId: x.rule,
+        ruleIndex: ri,
+        level: x.level,
+        message: { text },
+        locations,
+        ...(x.related ? { relatedLocations: [{ id: 1, physicalLocation: { artifactLocation: { uri: x.related.uri, uriBaseId: exports.SRCROOT }, region: { startLine: x.related.line } }, message: { text: "The other near-duplicate file" } }] } : {}),
+        partialFingerprints: { "prehello/v1": hash },
+        properties: props,
+        sortKey,
+    };
+}
+function renderSarif(r, o) {
+    return JSON.stringify(toSarif(r, o), null, 2) + "\n";
+}