@0xcraft/powershot 1.1.2 → 1.1.3

package/README.md

@@ -206,8 +206,9 @@ flowchart LR
 | `2` | Command or Git input was invalid |
 | `3` | Review is incomplete; findings may be missing |
 
-“No findings in portable coverage”, “No findings”, and “PowerShot could not look” are
-intentionally different outcomes. Use `--format manifest` to inspect `coverage`, file
+A clean report names its effective severity threshold, deterministic/model mode, file
+and check counts, and coverage level. A partial or failed review instead says it is not
+a verdict and keeps the missing work visible. Use `--format manifest` to inspect file
 dispositions, executed and unavailable checks, failures, judge units, and
 `notLookedAt`.
 

package/dist/cli/reports.js

@@ -1,10 +1,10 @@
 import { writeFileSync } from 'node:fs';
-import { unavailableCoverage } from '#app/manifest.js';
 import { dim } from '#app/report/ansi.js';
 import { codeQuality } from '#app/report/codequality.js';
 import { compact } from '#app/report/compact.js';
 import { markdown } from '#app/report/markdown.js';
 import { sarif } from '#app/report/sarif.js';
+import { summarizeRun } from '#app/report/summary.js';
 import { terminal } from '#app/report/terminal.js';
 export const REPORT_FORMATS = ['text', 'compact', 'markdown', 'json', 'sarif', 'codequality', 'manifest'];
 export function isReportFormat(value) {
@@ -38,15 +38,13 @@ export function renderReport(format, result, manifest, target) {
         return sarif(result.findings);
     if (format === 'json')
         return jsonResult(result);
+    const summary = summarizeRun(manifest);
     if (format === 'markdown')
-        return markdown(result.findings, manifest);
+        return markdown(result.findings, summary);
     return terminal(result.findings, {
         subtitle: target,
         ...result.stats,
-        state: manifest.state,
-        notLookedAt: manifest.notLookedAt,
-        coverage: manifest.coverage,
-        unavailableCoverage: unavailableCoverage(manifest),
+        ...summary,
     });
 }
 export function publishReports(options) {

package/dist/cli/review-command.js

@@ -5,11 +5,12 @@ import { loadConfig, policyChanged } from '#app/config.js';
 import { absorbDelegated, delegateBrief } from '#app/delegate.js';
 import { baseRefOf, checkRange, headSha, repoRoot, shaOf } from '#app/git.js';
 import { JUDGES } from '#app/judges/prompts.js';
-import { RunManifest, coverageProblems, hashOf, unavailableCoverage, writeManifest } from '#app/manifest.js';
+import { RunManifest, coverageProblems, hashOf, writeManifest } from '#app/manifest.js';
 import { Trace } from '#app/otel.js';
 import { PACKAGE_VERSION } from '#app/package-meta.js';
 import { dim, yellow } from '#app/report/ansi.js';
 import { progress, stage } from '#app/report/terminal.js';
+import { summarizeRun } from '#app/report/summary.js';
 import { review } from '#app/review.js';
 import { scanPaths } from '#app/scan.js';
 import { Session } from '#app/session.js';
@@ -222,6 +223,7 @@ export async function runReviewCommand(command, values, positionals) {
             model: config.model,
             tools: values.tools,
             verifyOnly: values['verify-only'],
+            minSeverity: config.minSeverity,
         },
         files: result.plan?.items() ?? [],
         skippedChecks: result.skippedChecks ?? [],
@@ -247,12 +249,7 @@ export async function runReviewCommand(command, values, positionals) {
         record.notLookedAt.push(failure);
         process.stderr.write(yellow(' ◇ manifest') + dim(' ' + gaps.join('; ')) + '\n');
     }
-    session?.saveReport(result.findings, {
-        state: record.state,
-        notLookedAt: record.notLookedAt,
-        coverage: record.coverage,
-        unavailableCoverage: unavailableCoverage(record),
-    });
+    session?.saveReport(result.findings, summarizeRun(record));
     writeManifest(root, record);
     publishReports({
         format: values.format,

package/dist/cli/session-command.js

@@ -43,7 +43,11 @@ export function runSessionCommand(positionals) {
             state: session.report.state ?? 'unknown',
             notLookedAt: session.report.notLookedAt ?? ['session predates verdict recording'],
             coverage: session.report.coverage,
-            unavailableCoverage: session.report.unavailableCoverage,
+            verifyOnly: session.report.verifyOnly,
+            minSeverity: session.report.minSeverity,
+            filesReviewed: session.report.filesReviewed,
+            deterministicChecks: session.report.deterministicChecks,
+            scopeDetails: session.report.scopeDetails,
         }));
         process.stdout.write(output + '\n');
         return 0;

package/dist/github/api.js

@@ -0,0 +1,198 @@
+import { stripControl } from '#app/text.js';
+const API_VERSION = '2022-11-28';
+const API_TIMEOUT_MS = 20_000;
+const MAX_API_PAGES = 100;
+export function createReviewPayload(commitId, comments) {
+    return {
+        commit_id: commitId,
+        body: `PowerShot posted ${comments.length} proven verified finding(s) on changed lines.`,
+        event: 'COMMENT',
+        comments,
+    };
+}
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function requiredString(value, name) {
+    if (typeof value !== 'string' || value.length === 0)
+        throw new Error(`GitHub API returned no ${name}`);
+    return value;
+}
+function nextLink(value) {
+    if (value === null)
+        return undefined;
+    for (const part of value.split(',')) {
+        const match = /^\s*<([^>]+)>;\s*rel="([^"]+)"\s*$/.exec(part);
+        if (match?.[2] === 'next')
+            return match[1];
+    }
+    return undefined;
+}
+function errorDetail(value) {
+    return stripControl(value).replace(/\r?\n/g, ' ').slice(0, 500);
+}
+function issueComment(value, index) {
+    if (!record(value) ||
+        !Number.isSafeInteger(value.id) ||
+        (value.body !== null && typeof value.body !== 'string')) {
+        throw new Error(`GitHub API issue comment ${index + 1} has an invalid contract`);
+    }
+    const user = record(value.user) && typeof value.user.login === 'string'
+        ? { login: value.user.login }
+        : undefined;
+    return { id: Number(value.id), body: value.body ?? '', user };
+}
+/** Shared REST transport for the two pull-request publication adapters. */
+export class GitHubPullRequestApi {
+    token;
+    pullNumber;
+    base;
+    pullPath;
+    issuePath;
+    issueCommentPath;
+    constructor(apiUrl, token, owner, repository, pullNumber) {
+        this.token = token;
+        this.pullNumber = pullNumber;
+        this.base = apiUrl.replace(/\/$/, '');
+        const repositoryPath = `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repository)}`;
+        this.pullPath = `${repositoryPath}/pulls`;
+        this.issuePath = `${repositoryPath}/issues/${pullNumber}`;
+        this.issueCommentPath = `${repositoryPath}/issues/comments`;
+    }
+    url(endpoint) {
+        if (!endpoint.startsWith('http://') && !endpoint.startsWith('https://'))
+            return this.base + endpoint;
+        if (endpoint !== this.base && !endpoint.startsWith(this.base + '/')) {
+            throw new Error('GitHub pagination left the configured API origin');
+        }
+        return endpoint;
+    }
+    async request(method, endpoint, body, acceptedStatuses = []) {
+        const response = await fetch(this.url(endpoint), {
+            method,
+            headers: {
+                Accept: 'application/vnd.github+json',
+                Authorization: `Bearer ${this.token}`,
+                'User-Agent': 'PowerShot',
+                'X-GitHub-Api-Version': API_VERSION,
+                ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+            signal: AbortSignal.timeout(API_TIMEOUT_MS),
+        });
+        const source = await response.text();
+        if (!response.ok) {
+            if (acceptedStatuses.includes(response.status))
+                return { data: undefined };
+            throw new Error(`GitHub API ${method} failed with ${response.status}: ${errorDetail(source)}`);
+        }
+        const data = source.length === 0 ? undefined : JSON.parse(source);
+        return { data, next: nextLink(response.headers.get('link')) };
+    }
+    async all(endpoint) {
+        const out = [];
+        const seen = new Set();
+        let next = endpoint + (endpoint.includes('?') ? '&' : '?') + 'per_page=100';
+        for (let page = 0; next !== undefined; page++) {
+            if (page >= MAX_API_PAGES)
+                throw new Error('GitHub API pagination exceeded its safety limit');
+            if (seen.has(next))
+                throw new Error('GitHub API returned a pagination cycle');
+            seen.add(next);
+            const response = await this.request('GET', next);
+            if (!Array.isArray(response.data))
+                throw new Error('GitHub API returned a non-array page');
+            out.push(...response.data);
+            next = response.next;
+        }
+        return out;
+    }
+    async headSha() {
+        const { data } = await this.request('GET', `${this.pullPath}/${this.pullNumber}`);
+        if (!record(data) || !record(data.head))
+            throw new Error('GitHub API returned no pull request head');
+        return requiredString(data.head.sha, 'pull request head SHA');
+    }
+    async listFiles() {
+        const values = await this.all(`${this.pullPath}/${this.pullNumber}/files`);
+        return values.map((value, index) => {
+            if (!record(value) || typeof value.filename !== 'string') {
+                throw new Error(`GitHub API pull file ${index + 1} has an invalid contract`);
+            }
+            if (value.patch !== undefined && typeof value.patch !== 'string') {
+                throw new Error(`GitHub API pull file ${index + 1} has an invalid patch`);
+            }
+            return { filename: value.filename, patch: value.patch };
+        });
+    }
+    async listReviewComments() {
+        const values = await this.all(`${this.pullPath}/${this.pullNumber}/comments`);
+        return values.map((value, index) => {
+            if (!record(value) ||
+                !Number.isSafeInteger(value.id) ||
+                typeof value.path !== 'string' ||
+                (value.line !== null && !Number.isSafeInteger(value.line)) ||
+                (value.body !== null && typeof value.body !== 'string') ||
+                (value.in_reply_to_id !== undefined && value.in_reply_to_id !== null && !Number.isSafeInteger(value.in_reply_to_id))) {
+                throw new Error(`GitHub API review comment ${index + 1} has an invalid contract`);
+            }
+            const user = record(value.user) && typeof value.user.login === 'string'
+                ? { login: value.user.login }
+                : undefined;
+            return {
+                id: Number(value.id),
+                path: value.path,
+                line: value.line === null ? null : Number(value.line),
+                body: value.body ?? '',
+                user,
+                inReplyToId: value.in_reply_to_id === undefined || value.in_reply_to_id === null
+                    ? undefined
+                    : Number(value.in_reply_to_id),
+            };
+        });
+    }
+    async createReview(commitId, comments) {
+        await this.request('POST', `${this.pullPath}/${this.pullNumber}/reviews`, createReviewPayload(commitId, comments));
+    }
+    async deleteReviewComment(id) {
+        await this.request('DELETE', `${this.pullPath}/comments/${id}`, undefined, [404]);
+    }
+    async listIssueComments() {
+        const values = await this.all(`${this.issuePath}/comments`);
+        return values.map(issueComment);
+    }
+    async createIssueComment(body) {
+        const { data } = await this.request('POST', `${this.issuePath}/comments`, { body });
+        return issueComment(data, 0);
+    }
+    async updateIssueComment(id, body) {
+        await this.request('PATCH', `${this.issueCommentPath}/${id}`, { body });
+    }
+    async deleteIssueComment(id) {
+        await this.request('DELETE', `${this.issueCommentPath}/${id}`, undefined, [404]);
+    }
+}
+export function requiredEnvironment(name) {
+    const value = process.env[name];
+    if (value === undefined || value.length === 0)
+        throw new Error(`${name} is required`);
+    return value;
+}
+export function expectedHeadShaFromEnvironment() {
+    const value = requiredEnvironment('POWERSHOT_HEAD_SHA');
+    if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/i.test(value))
+        throw new Error('POWERSHOT_HEAD_SHA is invalid');
+    return value;
+}
+export function githubPullRequestApiFromEnvironment() {
+    const repository = requiredEnvironment('GITHUB_REPOSITORY').split('/');
+    if (repository.length !== 2 || !repository[0] || !repository[1]) {
+        throw new Error('GITHUB_REPOSITORY must be owner/repository');
+    }
+    const pullNumber = Number(requiredEnvironment('POWERSHOT_PR_NUMBER'));
+    if (!Number.isSafeInteger(pullNumber) || pullNumber < 1) {
+        throw new Error('POWERSHOT_PR_NUMBER must be positive');
+    }
+    return new GitHubPullRequestApi(requiredEnvironment('GITHUB_API_URL'), requiredEnvironment('GITHUB_TOKEN'), repository[0], repository[1], pullNumber);
+}
+//# sourceMappingURL=api.js.map

package/dist/github/inline-comments.js

@@ -3,21 +3,11 @@ import { readFile } from 'node:fs/promises';
 import { pathToFileURL } from 'node:url';
 import { stripControl } from '#app/text.js';
 import { SEVERITIES } from '#app/types.js';
+import { githubPullRequestApiFromEnvironment, requiredEnvironment, } from './api.js';
 const INLINE_COMMENT_LIMIT = 10;
-const API_VERSION = '2022-11-28';
-const API_TIMEOUT_MS = 20_000;
-const MAX_API_PAGES = 100;
 const BOT_LOGIN = 'github-actions[bot]';
 const MARKER_PATTERN = /<!-- powershot:inline:v1:[a-f0-9]{24} -->/;
 const COMMONMARK_PUNCTUATION = new Set(`!"#$%&'()*+,-./:;<=>?@[\\]^_\`{|}~`);
-export function createReviewPayload(commitId, comments) {
-    return {
-        commit_id: commitId,
-        body: `PowerShot posted ${comments.length} proven verified finding(s) on changed lines.`,
-        event: 'COMMENT',
-        comments,
-    };
-}
 function oneLine(value, limit) {
     return stripControl(value).replace(/\r?\n/g, ' ').slice(0, limit);
 }
@@ -189,11 +179,6 @@ export async function syncInlineComments(api, findings, expectedHeadSha, limit =
 function record(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-function requiredString(value, name) {
-    if (typeof value !== 'string' || value.length === 0)
-        throw new Error(`GitHub API returned no ${name}`);
-    return value;
-}
 export function parseReviewFindings(source) {
     const document = JSON.parse(source);
     if (!record(document) || !Array.isArray(document.findings)) {
@@ -232,148 +217,12 @@ export function parseReviewFindings(source) {
         };
     });
 }
-function nextLink(value) {
-    if (value === null)
-        return undefined;
-    for (const part of value.split(',')) {
-        const match = /^\s*<([^>]+)>;\s*rel="([^"]+)"\s*$/.exec(part);
-        if (match?.[2] === 'next')
-            return match[1];
-    }
-    return undefined;
-}
-function errorDetail(value) {
-    return oneLine(value, 500);
-}
-export class GitHubPullRequestApi {
-    token;
-    pullNumber;
-    base;
-    pullPath;
-    constructor(apiUrl, token, owner, repository, pullNumber) {
-        this.token = token;
-        this.pullNumber = pullNumber;
-        this.base = apiUrl.replace(/\/$/, '');
-        this.pullPath = `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repository)}/pulls`;
-    }
-    url(endpoint) {
-        if (!endpoint.startsWith('http://') && !endpoint.startsWith('https://'))
-            return this.base + endpoint;
-        if (endpoint !== this.base && !endpoint.startsWith(this.base + '/')) {
-            throw new Error('GitHub pagination left the configured API origin');
-        }
-        return endpoint;
-    }
-    async request(method, endpoint, body, acceptedStatuses = []) {
-        const response = await fetch(this.url(endpoint), {
-            method,
-            headers: {
-                Accept: 'application/vnd.github+json',
-                Authorization: `Bearer ${this.token}`,
-                'User-Agent': 'PowerShot',
-                'X-GitHub-Api-Version': API_VERSION,
-                ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
-            },
-            body: body === undefined ? undefined : JSON.stringify(body),
-            signal: AbortSignal.timeout(API_TIMEOUT_MS),
-        });
-        const source = await response.text();
-        if (!response.ok) {
-            if (acceptedStatuses.includes(response.status))
-                return { data: undefined };
-            throw new Error(`GitHub API ${method} failed with ${response.status}: ${errorDetail(source)}`);
-        }
-        const data = source.length === 0 ? undefined : JSON.parse(source);
-        return { data, next: nextLink(response.headers.get('link')) };
-    }
-    async all(endpoint) {
-        const out = [];
-        const seen = new Set();
-        let next = endpoint + (endpoint.includes('?') ? '&' : '?') + 'per_page=100';
-        for (let page = 0; next !== undefined; page++) {
-            if (page >= MAX_API_PAGES)
-                throw new Error('GitHub API pagination exceeded its safety limit');
-            if (seen.has(next))
-                throw new Error('GitHub API returned a pagination cycle');
-            seen.add(next);
-            const response = await this.request('GET', next);
-            if (!Array.isArray(response.data))
-                throw new Error('GitHub API returned a non-array page');
-            out.push(...response.data);
-            next = response.next;
-        }
-        return out;
-    }
-    async headSha() {
-        const { data } = await this.request('GET', `${this.pullPath}/${this.pullNumber}`);
-        if (!record(data) || !record(data.head))
-            throw new Error('GitHub API returned no pull request head');
-        return requiredString(data.head.sha, 'pull request head SHA');
-    }
-    async listFiles() {
-        const values = await this.all(`${this.pullPath}/${this.pullNumber}/files`);
-        return values.map((value, index) => {
-            if (!record(value) || typeof value.filename !== 'string') {
-                throw new Error(`GitHub API pull file ${index + 1} has an invalid contract`);
-            }
-            if (value.patch !== undefined && typeof value.patch !== 'string') {
-                throw new Error(`GitHub API pull file ${index + 1} has an invalid patch`);
-            }
-            return { filename: value.filename, patch: value.patch };
-        });
-    }
-    async listReviewComments() {
-        const values = await this.all(`${this.pullPath}/${this.pullNumber}/comments`);
-        return values.map((value, index) => {
-            if (!record(value) ||
-                !Number.isSafeInteger(value.id) ||
-                typeof value.path !== 'string' ||
-                (value.line !== null && !Number.isSafeInteger(value.line)) ||
-                (value.body !== null && typeof value.body !== 'string') ||
-                (value.in_reply_to_id !== undefined && value.in_reply_to_id !== null && !Number.isSafeInteger(value.in_reply_to_id))) {
-                throw new Error(`GitHub API review comment ${index + 1} has an invalid contract`);
-            }
-            const user = record(value.user) && typeof value.user.login === 'string'
-                ? { login: value.user.login }
-                : undefined;
-            return {
-                id: Number(value.id),
-                path: value.path,
-                line: value.line === null ? null : Number(value.line),
-                body: value.body ?? '',
-                user,
-                inReplyToId: value.in_reply_to_id === undefined || value.in_reply_to_id === null
-                    ? undefined
-                    : Number(value.in_reply_to_id),
-            };
-        });
-    }
-    async createReview(commitId, comments) {
-        await this.request('POST', `${this.pullPath}/${this.pullNumber}/reviews`, createReviewPayload(commitId, comments));
-    }
-    async deleteReviewComment(id) {
-        await this.request('DELETE', `${this.pullPath}/comments/${id}`, undefined, [404]);
-    }
-}
-function environment(name) {
-    const value = process.env[name];
-    if (value === undefined || value.length === 0)
-        throw new Error(`${name} is required`);
-    return value;
-}
 async function main() {
-    const repository = environment('GITHUB_REPOSITORY').split('/');
-    if (repository.length !== 2 || !repository[0] || !repository[1]) {
-        throw new Error('GITHUB_REPOSITORY must be owner/repository');
-    }
-    const pullNumber = Number(environment('POWERSHOT_PR_NUMBER'));
-    if (!Number.isSafeInteger(pullNumber) || pullNumber < 1)
-        throw new Error('POWERSHOT_PR_NUMBER must be positive');
-    const expectedHeadSha = environment('POWERSHOT_HEAD_SHA');
+    const expectedHeadSha = requiredEnvironment('POWERSHOT_HEAD_SHA');
     if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/i.test(expectedHeadSha))
         throw new Error('POWERSHOT_HEAD_SHA is invalid');
     const findings = parseReviewFindings(await readFile('powershot.json', 'utf8'));
-    const api = new GitHubPullRequestApi(environment('GITHUB_API_URL'), environment('GITHUB_TOKEN'), repository[0], repository[1], pullNumber);
+    const api = githubPullRequestApiFromEnvironment();
     const result = await syncInlineComments(api, findings, expectedHeadSha);
     if (result.outdated) {
         process.stdout.write('PowerShot skipped inline comments because the pull request head changed.\n');

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/manifest.js

@@ -2,23 +2,6 @@ import { createHash } from 'node:crypto';
 import { mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 export const SCHEMA = 'powershot.run/v1';
-/** Human-readable optional depth, kept separate from verdict-blocking notLookedAt. */
-export function unavailableCoverage(record) {
-    const out = [];
-    const files = (record.files ?? []).filter((file) => file.unavailable?.length);
-    if (files.length > 0) {
-        out.push(files.length + ' file(s) without enriched semantic coverage: ' +
-            files.slice(0, 5).map((file) => file.path + ' (' + file.unavailable.join(', ') + ')').join(', ') +
-            (files.length > 5 ? ', …' : ''));
-    }
-    const checks = record.checks?.unavailable ?? [];
-    if (checks.length > 0) {
-        out.push(checks.length + ' enriched check(s) unavailable: ' +
-            checks.slice(0, 8).map((check) => check.check + ' (no ' + check.missing + ')').join(', ') +
-            (checks.length > 8 ? ', …' : ''));
-    }
-    return out;
-}
 /** The single state machine behind manifests, benches, renderers and exit codes. */
 export function completionOf(parts) {
     const waivedUnits = parts.units.filter((unit) => unit.outcome === 'waived').length;

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')))