@0xcraft/powershot 1.1.1 → 1.1.3

package/dist/github/summary-comment.js

@@ -0,0 +1,149 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+import { stripControl } from '#app/text.js';
+import { expectedHeadShaFromEnvironment, githubPullRequestApiFromEnvironment, requiredEnvironment, } from './api.js';
+export const LEGACY_SUMMARY_MARKER = '<!-- powershot:summary:v1 -->';
+const BOT_LOGIN = 'github-actions[bot]';
+const LEGACY_HEADING = /^## PowerShot(?:\r?\n|$)/;
+/** Scope ownership to one workflow job without exposing its repository path in the comment. */
+export function summaryMarker(scope) {
+    if (scope.length === 0)
+        throw new Error('PowerShot summary scope is required');
+    const digest = createHash('sha256').update(scope).digest('hex').slice(0, 24);
+    return `<!-- powershot:summary:v2:${digest} -->`;
+}
+/** Stable workflow identity: keep the repository/path, discard its moving ref. */
+export function workflowCommentScope(workflowRef, job) {
+    const structuralSeparator = workflowRef.indexOf('@refs/');
+    const separator = structuralSeparator === -1 ? workflowRef.lastIndexOf('@') : structuralSeparator;
+    if (separator < 1 || separator === workflowRef.length - 1) {
+        throw new Error('GITHUB_WORKFLOW_REF must contain a workflow path and ref');
+    }
+    if (job.length === 0)
+        throw new Error('GITHUB_JOB is required');
+    return `${workflowRef.slice(0, separator)}:${job}`;
+}
+function headMarker(headSha) {
+    return `<!-- powershot:head:${headSha.toLowerCase()} -->`;
+}
+export function summaryCommentBody(markdown, marker, headSha) {
+    const report = markdown.trimEnd();
+    const ownership = `${marker}\n${headMarker(headSha)}`;
+    return report.length === 0 ? ownership : `${ownership}\n\n${report}`;
+}
+function owns(body, marker) {
+    return body === marker || body.startsWith(marker + '\n') || body.startsWith(marker + '\r\n');
+}
+function ownsHead(body, marker, headSha) {
+    const ownership = `${marker}\n${headMarker(headSha)}`;
+    return body === ownership || body.startsWith(ownership + '\n') || body.startsWith(ownership + '\r\n');
+}
+function latest(comments) {
+    return comments.reduce((selected, comment) => selected === undefined || comment.id > selected.id ? comment : selected, undefined);
+}
+async function retireComments(api, comments, keepId) {
+    const staleIds = comments
+        .filter((comment) => comment.id !== keepId)
+        .map((comment) => comment.id)
+        .filter((id, index, ids) => ids.indexOf(id) === index)
+        .sort((left, right) => left - right);
+    for (const id of staleIds)
+        await api.deleteIssueComment(id);
+    return staleIds.length;
+}
+async function retireCreatedIfUnchanged(api, id, body) {
+    const created = (await api.listIssueComments())
+        .find((comment) => comment.id === id && comment.body === body);
+    if (created === undefined)
+        return 0;
+    await api.deleteIssueComment(id);
+    return 1;
+}
+async function reconcileCandidate(api, marker, body, expectedHeadSha, state, previousHeadComments, createdByThisRun, legacy) {
+    // REST has no atomic create-if-absent. Relisting makes same-head participants
+    // converge without allowing an old-head run to patch or retire a newer candidate.
+    const reconciled = (await api.listIssueComments()).filter((comment) => comment.user?.login === BOT_LOGIN &&
+        owns(comment.body, marker) &&
+        ownsHead(comment.body, marker, expectedHeadSha));
+    if (await api.headSha() !== expectedHeadSha) {
+        const retired = createdByThisRun === undefined
+            ? 0
+            : await retireCreatedIfUnchanged(api, createdByThisRun.id, body);
+        return { state: 'outdated', retired };
+    }
+    const keep = latest(reconciled);
+    if (keep === undefined)
+        throw new Error('GitHub API did not return the summary comment it created');
+    const retired = await retireComments(api, [...reconciled, ...previousHeadComments, ...(legacy === undefined ? [] : [legacy])], keep.id);
+    if (await api.headSha() !== expectedHeadSha) {
+        const createdRetired = createdByThisRun === undefined
+            ? 0
+            : await retireCreatedIfUnchanged(api, createdByThisRun.id, body);
+        return { state: 'outdated', retired: retired + createdRetired };
+    }
+    return { state, commentId: keep.id, retired };
+}
+async function createCandidate(api, marker, body, expectedHeadSha, state, previousHeadComments, legacy) {
+    const created = await api.createIssueComment(body);
+    if (await api.headSha() !== expectedHeadSha) {
+        const retired = await retireCreatedIfUnchanged(api, created.id, body);
+        return { state: 'outdated', retired };
+    }
+    return reconcileCandidate(api, marker, body, expectedHeadSha, state, previousHeadComments, created, legacy);
+}
+/** Reconcile only this workflow's PowerShot summary against the current pull-request head. */
+export async function syncSummaryComment(api, markdown, expectedHeadSha, scope) {
+    if (await api.headSha() !== expectedHeadSha)
+        return { state: 'outdated', retired: 0 };
+    const marker = summaryMarker(scope);
+    const body = summaryCommentBody(markdown, marker, expectedHeadSha);
+    const comments = await api.listIssueComments();
+    if (await api.headSha() !== expectedHeadSha)
+        return { state: 'outdated', retired: 0 };
+    const botComments = comments.filter((comment) => comment.user?.login === BOT_LOGIN);
+    const markedComments = botComments.filter((comment) => owns(comment.body, marker));
+    const currentHeadComments = markedComments.filter((comment) => ownsHead(comment.body, marker, expectedHeadSha));
+    const previousHeadComments = markedComments.filter((comment) => !ownsHead(comment.body, marker, expectedHeadSha));
+    const candidate = latest(currentHeadComments);
+    if (candidate !== undefined) {
+        const state = candidate.body === body ? 'unchanged' : 'updated';
+        if (state === 'updated') {
+            // A comment id never changes head ownership. This PATCH can race only with
+            // another run for the same head, never with a newer pull-request head.
+            await api.updateIssueComment(candidate.id, body);
+            if (await api.headSha() !== expectedHeadSha)
+                return { state: 'outdated', retired: 0 };
+        }
+        return reconcileCandidate(api, marker, body, expectedHeadSha, state, previousHeadComments);
+    }
+    // Legacy comments have no workflow or head identity, so claiming one with
+    // PATCH would let two workflows overwrite each other. Create the scoped,
+    // head-owned replacement first and retire only the legacy snapshot later.
+    const legacy = latest(botComments.filter((comment) => owns(comment.body, LEGACY_SUMMARY_MARKER) || LEGACY_HEADING.test(comment.body)));
+    if (legacy !== undefined) {
+        return createCandidate(api, marker, body, expectedHeadSha, 'migrated', previousHeadComments, legacy);
+    }
+    return createCandidate(api, marker, body, expectedHeadSha, 'created', previousHeadComments);
+}
+function oneLine(value, limit) {
+    return stripControl(value).replace(/\r?\n/g, ' ').slice(0, limit);
+}
+async function main() {
+    const result = await syncSummaryComment(githubPullRequestApiFromEnvironment(), await readFile('powershot.md', 'utf8'), expectedHeadShaFromEnvironment(), workflowCommentScope(requiredEnvironment('GITHUB_WORKFLOW_REF'), requiredEnvironment('GITHUB_JOB')));
+    if (result.state === 'outdated') {
+        process.stdout.write('PowerShot skipped the summary because the pull request head changed.\n');
+        return;
+    }
+    const retired = result.retired === 0 ? '' : ` ${result.retired} duplicate(s) retired.`;
+    process.stdout.write(`PowerShot summary comment: ${result.state}.${retired}\n`);
+}
+const entry = process.argv[1];
+if (entry !== undefined && import.meta.url === pathToFileURL(entry).href) {
+    main().catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write('PowerShot summary comment failed: ' + oneLine(message, 1_000) + '\n');
+        process.exitCode = 1;
+    });
+}
+//# sourceMappingURL=summary-comment.js.map

package/dist/ground.js

@@ -2,7 +2,7 @@ import { Project, SyntaxKind } from 'ts-morph';
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { decode } from './text.js';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
-import { packFor, parse } from './lang/packs.js';
+import { PACKS, packFor, parseIsolated } from './lang/packs.js';
 import { insideRepo, isSymlink, repoPath } from './fspolicy.js';
 const CODE_EXT = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;
 const TS_CONFIG = /^tsconfig(?:\..+)?\.json$/i;
@@ -360,7 +360,7 @@ export function readEnvManifest(root) {
     return undefined;
 }
 async function parseForeign(root, changed, signal) {
-    const out = [];
+    const byLanguage = new Map();
     for (const c of changed) {
         // parsing thousands of files is where a large scan spends its time, so a signal
         // has to be honoured here rather than only once the checks begin
@@ -376,13 +376,66 @@ async function parseForeign(root, changed, signal) {
         // costs seconds to produce findings nobody acts on
         if ((statSync(abs, { throwIfNoEntry: false })?.size ?? 0) > 512 * 1024)
             continue;
-        const tree = await parse(pack, decode(readFileSync(abs)));
-        if (!tree)
-            continue;
-        const beforeTree = c.before === undefined ? undefined : await parse(pack, c.before);
-        out.push({ path: c.path, pack, tree, beforeTree, changed: c });
+        const list = byLanguage.get(pack.name) ?? [];
+        list.push({
+            changed: c,
+            source: decode(readFileSync(abs)),
+            // A generated base can be arbitrarily larger than the reviewed result. Do not
+            // smuggle it past the current-file limit through the before/after channel.
+            beforeSource: c.before !== undefined && Buffer.byteLength(c.before) <= 512 * 1024
+                ? c.before
+                : undefined,
+        });
+        byLanguage.set(pack.name, list);
     }
-    return out;
+    const parsed = new Map();
+    // A worker holds one grammar and a bounded source batch. This keeps both WASM
+    // compilation and structured-clone payloads independent of monorepo size.
+    const MAX_BATCH_BYTES = 8 * 1024 * 1024;
+    const MAX_BATCH_FILES = 128;
+    for (const pack of PACKS) {
+        const candidates = byLanguage.get(pack.name) ?? [];
+        for (let start = 0; start < candidates.length;) {
+            let end = start;
+            let bytes = 0;
+            while (end < candidates.length && end - start < MAX_BATCH_FILES) {
+                const candidate = candidates[end];
+                const next = Buffer.byteLength(candidate.source) + Buffer.byteLength(candidate.beforeSource ?? '');
+                if (end > start && bytes + next > MAX_BATCH_BYTES)
+                    break;
+                bytes += next;
+                end++;
+            }
+            const batch = candidates.slice(start, end);
+            const sources = batch.flatMap((candidate) => candidate.beforeSource === undefined
+                ? [candidate.source]
+                : [candidate.source, candidate.beforeSource]);
+            const trees = await parseIsolated(pack, sources, signal);
+            let index = 0;
+            for (const candidate of batch) {
+                const tree = trees[index++];
+                const beforeTree = candidate.beforeSource === undefined ? undefined : trees[index++];
+                if (!tree)
+                    continue;
+                parsed.set(candidate.changed.path, {
+                    path: candidate.changed.path,
+                    pack,
+                    tree,
+                    beforeTree,
+                    changed: candidate.changed,
+                });
+            }
+            start = end;
+            if (signal?.aborted)
+                break;
+        }
+        if (signal?.aborted)
+            break;
+    }
+    return changed.flatMap((file) => {
+        const result = parsed.get(file.path);
+        return result ? [result] : [];
+    });
 }
 function buildSymbolIndex(sourceFiles, root) {
     const index = new Map();

package/dist/lang/packs.js

@@ -1,5 +1,6 @@
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
+import { Worker } from 'node:worker_threads';
 /** Shared defaults; a pack overrides only what its grammar spells differently. */
 const COMMON_NODES = {
     identifier: ['identifier'],
@@ -498,15 +499,6 @@ export function packFor(path) {
 }
 let ready;
 const parsers = new Map();
-/**
- * Measured, not guessed, and the measurement is worth writing down because the naive
- * one is misleading. Loading grammars is cheap — all eleven load for ~143MB. Parsing
- * with them is not: V8 tiers up each wasm module in the background, and RSS climbed
- * 63 → 690MB across eleven before the process died inside that compilation. Six
- * grammars sat at ~131MB and were comfortable.
- */
-const MAX_GRAMMARS = 6;
-export const skippedLanguages = [];
 /**
  * Grammars load lazily and once. A repository with no Python pays nothing for
  * Python, and the wasm runtime is only initialised when a foreign file appears.
@@ -515,11 +507,6 @@ async function parserFor(pack) {
     const cached = parsers.get(pack.name);
     if (cached)
         return cached;
-    if (parsers.size >= MAX_GRAMMARS) {
-        if (!skippedLanguages.includes(pack.name))
-            skippedLanguages.push(pack.name);
-        return undefined;
-    }
     try {
         if (!ready) {
             ready = (async () => {
@@ -554,4 +541,100 @@ export async function parse(pack, source) {
         return undefined;
     }
 }
+/** Turn a native WASM-backed tree into data that can cross a worker boundary. */
+export function serializeTree(tree) {
+    const copy = (raw, field) => {
+        const node = raw;
+        const children = [];
+        for (let i = 0; i < node.childCount; i++) {
+            const child = node.child(i);
+            if (child)
+                children.push(copy(child, node.fieldNameForChild(i) ?? undefined));
+        }
+        return {
+            type: node.type,
+            startIndex: node.startIndex,
+            endIndex: node.endIndex,
+            startPosition: { ...node.startPosition },
+            endPosition: { ...node.endPosition },
+            named: node.isNamed,
+            field,
+            children,
+        };
+    };
+    return { root: copy(tree.rootNode) };
+}
+/** Restore the small Node interface the language-independent verifiers consume. */
+function hydrateTree(source, tree) {
+    const hydrate = (data) => {
+        const children = data.children.map(hydrate);
+        return {
+            type: data.type,
+            get text() { return source.slice(data.startIndex, data.endIndex); },
+            startPosition: { ...data.startPosition },
+            endPosition: { ...data.endPosition },
+            childCount: children.length,
+            child: (index) => children[index] ?? null,
+            namedChildren: children.filter((_, index) => data.children[index]?.named),
+            childForFieldName: (name) => {
+                const index = data.children.findIndex((child) => child.field === name);
+                return index < 0 ? null : (children[index] ?? null);
+            },
+        };
+    };
+    return { rootNode: hydrate(tree.root) };
+}
+/**
+ * Parse one language in a disposable worker.
+ *
+ * V8 keeps compiled WASM grammars alive longer than their JS parsers. Eleven
+ * grammars in one process reached ~690MB and killed real mixed-language runs.
+ * One worker owns one grammar, returns plain trees, and is then terminated, so
+ * compiled-grammar memory is bounded by one language rather than by the monorepo's
+ * language count. Plain trees still scale with the selected diff.
+ */
+export function parseIsolated(pack, sources, signal) {
+    if (sources.length === 0)
+        return Promise.resolve([]);
+    if (signal?.aborted)
+        return Promise.resolve(sources.map(() => undefined));
+    return new Promise((resolve) => {
+        let worker;
+        let settled = false;
+        const empty = () => sources.map(() => undefined);
+        const finish = (trees) => {
+            if (settled)
+                return;
+            settled = true;
+            signal?.removeEventListener('abort', abort);
+            // Resolve only after V8 has released this worker's WASM grammar. Otherwise a
+            // fast next batch can overlap termination and recreate the memory spike this
+            // isolation boundary exists to prevent.
+            void worker.terminate().then(() => resolve(trees), () => resolve(trees));
+        };
+        const abort = () => finish(empty());
+        try {
+            worker = new Worker(new URL('./parse-worker.js', import.meta.url), {
+                workerData: { language: pack.name, sources },
+            });
+        }
+        catch {
+            resolve(empty());
+            return;
+        }
+        signal?.addEventListener('abort', abort, { once: true });
+        worker.once('message', (raw) => {
+            if (!Array.isArray(raw) || raw.length !== sources.length) {
+                finish(empty());
+                return;
+            }
+            finish(raw.map((tree, index) => tree ? hydrateTree(sources[index], tree) : undefined));
+        });
+        worker.once('error', () => finish(empty()));
+        worker.once('exit', () => finish(empty()));
+        // Close the narrow race between the early check and listener registration.
+        if (signal?.aborted)
+            abort();
+    });
+}
 //# sourceMappingURL=packs.js.map

package/dist/lang/parse-worker.js

@@ -0,0 +1,15 @@
+import { parentPort, workerData } from 'node:worker_threads';
+import { PACKS, parse, serializeTree } from './packs.js';
+async function run(input) {
+    const pack = PACKS.find((candidate) => candidate.name === input.language);
+    if (!pack || !Array.isArray(input.sources))
+        return [];
+    const trees = [];
+    for (const source of input.sources) {
+        const tree = await parse(pack, source);
+        trees.push(tree ? serializeTree(tree) : undefined);
+    }
+    return trees;
+}
+void run(workerData).then((trees) => parentPort?.postMessage(trees), () => parentPort?.postMessage([]));
+//# sourceMappingURL=parse-worker.js.map

package/dist/lang/python-deps.js

@@ -135,11 +135,20 @@ const SKIP_DIRS = new Set([
     'node_modules', '.git', '.venv', 'venv', 'env', '__pycache__', 'dist', 'build',
     '.mypy_cache', '.pytest_cache', '.tox', 'site-packages', 'target', '.next',
 ]);
-export function localModules(root) {
+/**
+ * Importable names near one changed Python file.
+ *
+ * Only direct entries in its ancestor chain and conventional source roots are read.
+ * That bounds work by path depth instead of repository size, while still covering
+ * `src/pkg` beside `tests/test_pkg.py` and namespace packages without __init__.py.
+ */
+export function localModules(root, from = root) {
     const local = new Set();
-    const walk = (dir, depth) => {
-        if (depth > 6 || local.size > 4000)
+    const scanned = new Set();
+    const inspect = (dir) => {
+        if (scanned.has(dir))
             return;
+        scanned.add(dir);
         let entries;
         try {
             entries = readdirSync(dir, { withFileTypes: true });
@@ -147,21 +156,25 @@ export function localModules(root) {
         catch {
             return;
         }
-        const isPackage = entries.some((e) => e.isFile() && e.name === '__init__.py');
         for (const entry of entries) {
             if (entry.name.startsWith('.') || SKIP_DIRS.has(entry.name))
                 continue;
             if (entry.isDirectory()) {
-                // a package directory is importable by name; so is a plain source folder
+                // Namespace packages are importable without __init__.py too.
                 local.add(entry.name);
-                walk(join(dir, entry.name), depth + 1);
             }
-            else if (entry.name.endsWith('.py') && (isPackage || depth <= 2)) {
+            else if (entry.isFile() && entry.name.endsWith('.py') && entry.name !== '__init__.py') {
                 local.add(entry.name.slice(0, -3));
             }
         }
     };
-    walk(root, 0);
+    for (let dir = from;; dir = dirname(dir)) {
+        inspect(dir);
+        for (const source of ['src', 'lib', 'python'])
+            inspect(join(dir, source));
+        if (dir === root || dirname(dir) === dir)
+            break;
+    }
     return local;
 }
 export function isPhantom(importName, manifest, local) {

package/dist/manifest.js

@@ -65,12 +65,20 @@ export class RunManifest {
                 ...file,
                 checks: [...file.checks],
                 missing: file.missing ? [...file.missing] : undefined,
+                unavailable: file.unavailable ? [...file.unavailable] : undefined,
             })),
             units: this.units.map((unit) => ({ ...unit })),
             checks: {
                 ran: [...this.ranChecks],
                 skipped: parts.skippedChecks.map((check) => ({ ...check })),
+                ...((parts.unavailableChecks?.length ?? 0) > 0
+                    ? { unavailable: parts.unavailableChecks.map((check) => ({ ...check })) }
+                    : {}),
             },
+            coverage: parts.files.some((file) => file.missing?.length || file.unavailable?.length) ||
+                parts.skippedChecks.length > 0 || (parts.unavailableChecks?.length ?? 0) > 0
+                ? 'portable'
+                : 'full',
             findings: { ...parts.findings },
             usage: { ...parts.usage },
             state: completion.state,
@@ -118,6 +126,15 @@ export function coverageProblems(m) {
         if (f.disposition !== 'selected' && f.checks.length > 0) {
             problems.push(f.path + ': ' + f.disposition + ' file received checks');
         }
+        if (f.disposition !== 'selected' && f.unavailable?.length) {
+            problems.push(f.path + ': ' + f.disposition + ' file has unavailable coverage');
+        }
+        const missingCaps = new Set(f.missing ?? []);
+        for (const capability of f.unavailable ?? []) {
+            if (missingCaps.has(capability)) {
+                problems.push(f.path + ': capability is both required and unavailable: ' + capability);
+            }
+        }
         const local = new Set();
         for (const check of f.checks) {
             if (local.has(check))
@@ -157,6 +174,21 @@ export function coverageProblems(m) {
         if (ran.has(check.check))
             problems.push('check counted as both ran and skipped: ' + check.check);
     }
+    const unavailable = new Set();
+    for (const check of m.checks.unavailable ?? []) {
+        if (unavailable.has(check.check))
+            problems.push('check counted twice as unavailable: ' + check.check);
+        unavailable.add(check.check);
+        if (skipped.has(check.check))
+            problems.push('check counted as both skipped and unavailable: ' + check.check);
+    }
+    const expectedCoverage = m.files.some((file) => file.missing?.length || file.unavailable?.length) ||
+        m.checks.skipped.length > 0 || (m.checks.unavailable?.length ?? 0) > 0
+        ? 'portable'
+        : 'full';
+    if (m.coverage !== undefined && m.coverage !== expectedCoverage) {
+        problems.push('coverage is ' + m.coverage + ' but accounting says ' + expectedCoverage);
+    }
     // a judged run that reports complete must have reached every unit it selected
     const unreached = m.units.filter((u) => u.outcome === 'failed' || u.outcome === 'waived');
     if (m.state === 'complete' && unreached.length > 0) {

package/dist/package-smoke.js

@@ -64,8 +64,12 @@ try {
             throw new Error('architecture guide is missing');
         if (!existsSync(join(installed, 'docs', 'ci.md')))
             throw new Error('CI guide is missing');
+        if (!existsSync(join(installed, 'dist', 'github', 'api.js')))
+            throw new Error('GitHub REST runtime is missing');
         if (!existsSync(join(installed, 'dist', 'github', 'inline-comments.js')))
             throw new Error('inline review runtime is missing');
+        if (!existsSync(join(installed, 'dist', 'github', 'summary-comment.js')))
+            throw new Error('summary comment runtime is missing');
         if (!existsSync(join(installed, 'examples', 'github-actions', 'cli.yml')))
             throw new Error('CI example is missing');
         if (!existsSync(join(installed, 'examples', 'gitlab', '.gitlab-ci.yml')))

package/dist/plan.js

@@ -67,6 +67,13 @@ export class SelectionPlan {
             row.missing = [...new Set([...(row.missing ?? []), ...missing])];
         }
     }
+    /** Record optional semantic depth that this environment could not provide. */
+    noteUnavailable(path, unavailable) {
+        const row = this.rows.get(path);
+        if (row && row.disposition === 'selected' && unavailable.length > 0) {
+            row.unavailable = [...new Set([...(row.unavailable ?? []), ...unavailable])];
+        }
+    }
     /** Record coverage at the same file granularity used to decide applicability. */
     checked(path, check) {
         const row = this.rows.get(path);

package/dist/report/markdown.js

@@ -1,3 +1,4 @@
+import { modeNote, noFindingsLabel, scopeLine, } from './summary.js';
 const MARK = { verified: '▣', judged: '▚' };
 /** Untrusted prose encoded as literal CommonMark text. */
 function text(s) {
@@ -50,6 +51,26 @@ function group(findings) {
         list.sort((a, b) => a.line - b.line);
     return out;
 }
+function runSummary(run) {
+    const out = [];
+    const scope = scopeLine(run);
+    const mode = modeNote(run, '`verify-only`');
+    const details = run.state === 'complete'
+        ? run.scopeDetails ?? []
+        : [...run.notLookedAt, ...(run.scopeDetails ?? [])];
+    if (scope)
+        out.push(scope, '');
+    if (mode)
+        out.push(mode, '');
+    if (details.length > 0) {
+        out.push('<details>', '<summary>' +
+            (run.state !== 'complete'
+                ? 'Why this is not a verdict'
+                : run.coverage === 'portable' ? 'Coverage details' : 'Review scope') +
+            '</summary>', '', ...details.map((detail) => '- ' + text(detail)), '', '</details>', '');
+    }
+    return out;
+}
 export function markdown(findings, run) {
     // "No findings" from a run that could not look is the one thing this must never
     // say on its own — the reader takes a comment at face value, and a red job beside
@@ -58,18 +79,25 @@ export function markdown(findings, run) {
     const banner = incomplete
         ? [
             '> [!WARNING]',
-            '> **This review is ' + text(run.state) + ' — not a verdict.** Something was not looked at:',
-            ...run.notLookedAt.slice(0, 8).map((f) => '> - ' + text(f)),
+            '> **This review is ' + text(run.state) + ' — not a verdict.** Some files or checks were not reviewed.',
             '',
         ]
         : [];
+    const summary = run ? runSummary(run) : [];
     if (findings.length === 0) {
-        return ['## PowerShot', '', ...banner, incomplete ? 'No findings *from what it managed to review*.' : 'No findings.', ''].join('\n');
+        return [
+            '## PowerShot', '', ...banner,
+            incomplete
+                ? 'No findings *from what it managed to review*.'
+                : run ? '✅ **' + noFindingsLabel(run) + '**' : 'No findings.',
+            '', ...summary,
+        ].join('\n');
     }
     const verified = findings.filter((f) => f.class === 'verified').length;
     const judged = findings.length - verified;
     const out = ['## PowerShot', '', ...banner];
     out.push('**' + verified + ' verified** (deterministic, 0 tokens) · **' + judged + ' judged** (agent)', '');
+    out.push(...summary);
     for (const [file, list] of group(findings)) {
         out.push('### `' + path(file) + '`', '');
         for (const f of list) {