@0xcraft/powershot 1.0.1 → 1.1.0

package/README.md

@@ -216,12 +216,20 @@ The composite action is the shortest setup for GitHub:
     verify-only: 'true'
     upload-sarif: 'true'
     comment: 'true'
+    inline-comments: 'true'
     fail-on-findings: 'true'
 ```
 
 `@v1` follows compatible `1.x` releases. Pin the action to a full commit SHA in a
 protected required workflow when immutable dependencies are required.
 
+`inline-comments` is opt-in. It posts at most ten `verified` + `proven` findings of
+`medium` severity or higher as one GitHub review, and only when GitHub confirms the
+finding line was added by the pull request. Reruns keep matching bot comments and
+retire stale PowerShot copies that have no replies. Human comments and discussions
+are preserved. Every finding still stays in the full report and, when `comment` is
+enabled, the summary comment.
+
 The [CI guide](docs/ci.md) covers exit handling, Git history, one-run/many-report
 artifacts, GitLab Code Quality, local parity, and recommended gate policies.
 

package/dist/github/inline-comments.js

@@ -0,0 +1,392 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+import { stripControl } from '#app/text.js';
+import { SEVERITIES } from '#app/types.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);
+}
+/** Untrusted finding prose rendered as literal CommonMark without mentions or HTML. */
+function literal(value, limit = 1_200) {
+    let out = '';
+    for (const char of oneLine(value, limit)) {
+        if (char === '&')
+            out += '&amp;';
+        else if (char === '<')
+            out += '&lt;';
+        else if (char === '>')
+            out += '&gt;';
+        else if (char === '@')
+            out += '&#64;';
+        else
+            out += COMMONMARK_PUNCTUATION.has(char) ? '\\' + char : char;
+    }
+    return out;
+}
+function code(value) {
+    return oneLine(value, 160).replace(/`/g, '');
+}
+/** Stable across reruns; unlike the display id, it does not depend on finding order. */
+export function inlineMarker(finding) {
+    const key = JSON.stringify([finding.check, finding.file, finding.line, finding.title]);
+    const digest = createHash('sha256').update(key).digest('hex').slice(0, 24);
+    return `<!-- powershot:inline:v1:${digest} -->`;
+}
+function inlineBody(finding) {
+    const body = [
+        `**PowerShot · ${finding.severity.toUpperCase()} · \`${code(finding.check)}\` · verified/proven**`,
+        '',
+        literal(finding.title),
+    ];
+    if (finding.evidence) {
+        body.push('', `> _${literal(finding.evidence.oracle, 240)}_: ${literal(finding.evidence.detail)}`);
+    }
+    body.push('', inlineMarker(finding));
+    return body.join('\n');
+}
+/** Parse right-side line numbers from the unified patch returned by GitHub. */
+export function addedLinesFromPatch(patch) {
+    const added = new Set();
+    let rightLine;
+    for (const raw of patch.split('\n')) {
+        const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
+        const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(line);
+        if (hunk) {
+            rightLine = Number(hunk[1]);
+            continue;
+        }
+        if (rightLine === undefined || line === '\')
+            continue;
+        if (line.startsWith('+')) {
+            added.add(rightLine);
+            rightLine++;
+        }
+        else if (line.startsWith('-')) {
+            continue;
+        }
+        else if (line.startsWith(' ')) {
+            rightLine++;
+        }
+    }
+    return added;
+}
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+/**
+ * Select the small, high-confidence subset suitable for review comments.
+ *
+ * A missing or truncated GitHub patch is deliberately ineligible: the finding is
+ * still in the full report, but there is no proven right-side location to attach to.
+ */
+export function selectInlineComments(findings, files, limit = INLINE_COMMENT_LIMIT) {
+    const changed = new Map();
+    for (const file of files) {
+        if (file.patch === undefined)
+            continue;
+        const lines = changed.get(file.filename) ?? new Set();
+        for (const line of addedLinesFromPatch(file.patch))
+            lines.add(line);
+        changed.set(file.filename, lines);
+    }
+    const eligible = findings
+        .filter((finding) => finding.class === 'verified' &&
+        finding.confidence === 'proven' &&
+        SEVERITIES.indexOf(finding.severity) >= SEVERITIES.indexOf('medium') &&
+        changed.get(finding.file)?.has(finding.line) === true)
+        .sort((left, right) => SEVERITIES.indexOf(right.severity) - SEVERITIES.indexOf(left.severity) ||
+        compareText(left.file, right.file) ||
+        left.line - right.line ||
+        compareText(left.check, right.check) ||
+        compareText(left.title, right.title));
+    const out = [];
+    const seen = new Set();
+    const requested = Number.isFinite(limit) ? Math.floor(limit) : 0;
+    const bounded = Math.min(INLINE_COMMENT_LIMIT, Math.max(0, requested));
+    if (bounded === 0)
+        return out;
+    for (const finding of eligible) {
+        const marker = inlineMarker(finding);
+        if (seen.has(marker))
+            continue;
+        seen.add(marker);
+        out.push({ path: finding.file, line: finding.line, side: 'RIGHT', body: inlineBody(finding) });
+        if (out.length === bounded)
+            break;
+    }
+    return out;
+}
+function markerIn(body) {
+    return MARKER_PATTERN.exec(body)?.[0];
+}
+/** Plan an idempotent rerun without deleting any human-authored comment. */
+export function reconcileInlineComments(desired, existing) {
+    const managed = existing.filter((comment) => comment.user?.login === BOT_LOGIN && markerIn(comment.body) !== undefined);
+    const repliedTo = new Set(existing.flatMap((comment) => comment.inReplyToId === undefined ? [] : [comment.inReplyToId]));
+    const used = new Set();
+    const create = [];
+    let kept = 0;
+    for (const wanted of desired) {
+        const marker = markerIn(wanted.body);
+        const matches = managed.filter((comment) => !used.has(comment.id) &&
+            markerIn(comment.body) === marker &&
+            comment.path === wanted.path &&
+            comment.line === wanted.line &&
+            comment.body === wanted.body);
+        const match = matches.find((comment) => repliedTo.has(comment.id)) ?? matches[0];
+        if (match) {
+            used.add(match.id);
+            kept++;
+        }
+        else {
+            create.push(wanted);
+        }
+    }
+    const staleIds = [...new Set(managed
+            .filter((comment) => !used.has(comment.id) && !repliedTo.has(comment.id))
+            .map((comment) => comment.id))]
+        .sort((left, right) => left - right);
+    return { create, staleIds, kept };
+}
+/** Create missing comments as one review, then retire superseded bot comments. */
+export async function syncInlineComments(api, findings, expectedHeadSha, limit = INLINE_COMMENT_LIMIT) {
+    if (await api.headSha() !== expectedHeadSha) {
+        return { outdated: true, desired: 0, created: 0, kept: 0, retired: 0 };
+    }
+    const [files, existing] = await Promise.all([api.listFiles(), api.listReviewComments()]);
+    if (await api.headSha() !== expectedHeadSha) {
+        return { outdated: true, desired: 0, created: 0, kept: 0, retired: 0 };
+    }
+    const desired = selectInlineComments(findings, files, limit);
+    const plan = reconcileInlineComments(desired, existing);
+    if (plan.create.length > 0)
+        await api.createReview(expectedHeadSha, plan.create);
+    for (const id of plan.staleIds)
+        await api.deleteReviewComment(id);
+    return {
+        outdated: false,
+        desired: desired.length,
+        created: plan.create.length,
+        kept: plan.kept,
+        retired: plan.staleIds.length,
+    };
+}
+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)) {
+        throw new Error('powershot.json does not contain a findings array');
+    }
+    return document.findings.map((value, index) => {
+        if (!record(value))
+            throw new Error(`powershot.json finding ${index + 1} is not an object`);
+        if (typeof value.id !== 'string' ||
+            (value.class !== 'verified' && value.class !== 'judged') ||
+            typeof value.check !== 'string' ||
+            !SEVERITIES.includes(value.severity) ||
+            (value.confidence !== 'proven' && value.confidence !== 'firm' && value.confidence !== 'tentative') ||
+            typeof value.file !== 'string' ||
+            !Number.isSafeInteger(value.line) || Number(value.line) < 1 ||
+            typeof value.title !== 'string') {
+            throw new Error(`powershot.json finding ${index + 1} has an invalid contract`);
+        }
+        let evidence;
+        if (value.evidence !== undefined) {
+            if (!record(value.evidence) || typeof value.evidence.oracle !== 'string' || typeof value.evidence.detail !== 'string') {
+                throw new Error(`powershot.json finding ${index + 1} has invalid evidence`);
+            }
+            evidence = { oracle: value.evidence.oracle, detail: value.evidence.detail };
+        }
+        return {
+            id: value.id,
+            class: value.class,
+            check: value.check,
+            severity: value.severity,
+            confidence: value.confidence,
+            file: value.file,
+            line: Number(value.line),
+            title: value.title,
+            evidence,
+        };
+    });
+}
+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');
+    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 result = await syncInlineComments(api, findings, expectedHeadSha);
+    if (result.outdated) {
+        process.stdout.write('PowerShot skipped inline comments because the pull request head changed.\n');
+        return;
+    }
+    process.stdout.write(`PowerShot inline comments: ${result.created} created, ${result.kept} kept, ${result.retired} 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 inline comments failed: ' + oneLine(message, 1_000) + '\n');
+        process.exitCode = 1;
+    });
+}
+//# sourceMappingURL=inline-comments.js.map

package/dist/package-smoke.js

@@ -64,6 +64,8 @@ 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', 'inline-comments.js')))
+            throw new Error('inline review 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/selftest.js

@@ -53,6 +53,7 @@ import { highlight, isJsx } from './report/highlight.js';
 import { normalizeName, readEnvManifest, relPath } from './ground.js';
 import { incompleteReasons } from './bench.js';
 import { PACKAGE_NAME, PACKAGE_VERSION } from './package-meta.js';
+import { addedLinesFromPatch, createReviewPayload, GitHubPullRequestApi, inlineMarker, parseReviewFindings, reconcileInlineComments, selectInlineComments, syncInlineComments, } from './github/inline-comments.js';
 const root = '/repo';
 /** Build a Ground by hand so verifiers are testable without git or a real repo. */
 function ground(files, deps = []) {
@@ -653,6 +654,210 @@ const sample = [
     { id: 'F2', class: 'judged', check: 'plausible-logic', severity: 'low', confidence: 'tentative',
         file: 'src/b.ts', line: 9, title: 'off by one' },
 ];
+check('GitHub patches expose only added right-side lines for inline comments', () => {
+    const patch = [
+        '@@ -1,3 +1,4 @@',
+        ' context',
+        '-old',
+        '+new',
+        '+extra',
+        ' tail',
+        '@@ -20,0 +22,2 @@',
+        '+later',
+        '\',
+        '+latest',
+    ].join('\n');
+    assert.deepEqual([...addedLinesFromPatch(patch)], [2, 3, 22, 23]);
+});
+check('inline review selects only proven medium-or-higher verified findings on added lines', () => {
+    const finding = (overrides) => ({
+        id: 'F', class: 'verified', check: 'phantom-dep', severity: 'high', confidence: 'proven',
+        file: 'src/a.ts', line: 3, title: 'finding', ...overrides,
+    });
+    const findings = [
+        finding({ id: 'critical', severity: 'critical', line: 4, title: 'critical finding' }),
+        finding({ id: 'medium', severity: 'medium', line: 3, title: 'medium finding' }),
+        finding({ id: 'context', line: 2 }),
+        finding({ id: 'low', severity: 'low' }),
+        finding({ id: 'judged', class: 'judged' }),
+        finding({ id: 'firm', confidence: 'firm' }),
+        finding({ id: 'other-file', file: 'src/missing.ts' }),
+    ];
+    const files = [{ filename: 'src/a.ts', patch: '@@ -2,1 +2,3 @@\n context\n+first\n+second' }];
+    assert.deepEqual(selectInlineComments(findings, files).map((comment) => comment.line), [4, 3]);
+    assert.deepEqual(selectInlineComments(findings, files, 1).map((comment) => comment.line), [4]);
+    assert.deepEqual(selectInlineComments(findings, files, 0), []);
+    const many = Array.from({ length: 12 }, (_, index) => finding({ line: index + 3, title: `finding ${index}` }));
+    const manyPatch = '@@ -2,0 +3,12 @@\n' + many.map((_, index) => `+line ${index}`).join('\n');
+    assert.equal(selectInlineComments(many, [{ filename: 'src/a.ts', patch: manyPatch }], 100).length, 10);
+});
+check('inline comment markdown renders finding prose literally and carries a stable marker', () => {
+    const finding = {
+        id: 'F1', class: 'verified', check: 'check`id', severity: 'high', confidence: 'proven',
+        file: 'src/a.ts', line: 3, title: '@team <img src=x> [click](https://example.invalid)',
+        evidence: { oracle: 'manifest', detail: 'line one\n> forged quote' },
+    };
+    const [comment] = selectInlineComments([finding], [{ filename: finding.file, patch: '@@ -2,0 +3,1 @@\n+line' }]);
+    assert.ok(comment);
+    assert.equal(comment.body.includes('@team'), false);
+    assert.equal(comment.body.includes('<img'), false);
+    assert.equal(comment.body.includes('[click]('), false);
+    assert.equal(comment.body.endsWith(inlineMarker(finding)), true);
+    assert.equal(comment.body.match(/<!-- powershot:inline:/g)?.length, 1);
+});
+check('inline publishing rejects a malformed machine report instead of silently dropping it', () => {
+    assert.deepEqual(parseReviewFindings(JSON.stringify({ findings: [sample[0]] })), [sample[0]]);
+    assert.throws(() => parseReviewFindings(JSON.stringify({ findings: [{ ...sample[0], line: 0 }] })), /invalid contract/);
+    assert.throws(() => parseReviewFindings('{}'), /findings array/);
+});
+check('inline reruns keep exact bot comments, batch only missing ones, and retire stale bot copies', () => {
+    const findings = [
+        { id: 'F1', class: 'verified', check: 'a', severity: 'critical', confidence: 'proven', file: 'a.ts', line: 1, title: 'one' },
+        { id: 'F2', class: 'verified', check: 'b', severity: 'high', confidence: 'proven', file: 'b.ts', line: 2, title: 'two' },
+    ];
+    const desired = selectInlineComments(findings, [
+        { filename: 'a.ts', patch: '@@ -0,0 +1,1 @@\n+one' },
+        { filename: 'b.ts', patch: '@@ -1,0 +2,1 @@\n+two' },
+    ]);
+    const existing = [
+        { id: 1, path: desired[0].path, line: desired[0].line, body: desired[0].body, user: { login: 'github-actions[bot]' } },
+        { id: 2, path: desired[0].path, line: desired[0].line, body: desired[0].body, user: { login: 'github-actions[bot]' } },
+        { id: 3, path: desired[0].path, line: desired[0].line, body: 'old\n' + inlineMarker(findings[0]), user: { login: 'github-actions[bot]' } },
+        { id: 4, path: desired[1].path, line: desired[1].line, body: desired[1].body, user: { login: 'human' } },
+        { id: 5, path: desired[0].path, line: desired[0].line, body: 'discussion', user: { login: 'human' }, inReplyToId: 2 },
+        { id: 6, path: desired[0].path, line: desired[0].line, body: 'discussed old\n' + inlineMarker(findings[0]), user: { login: 'github-actions[bot]' } },
+        { id: 7, path: desired[0].path, line: desired[0].line, body: 'still investigating', user: { login: 'human' }, inReplyToId: 6 },
+    ];
+    const plan = reconcileInlineComments(desired, existing);
+    assert.equal(plan.kept, 1);
+    assert.deepEqual(plan.create, [desired[1]]);
+    assert.deepEqual(plan.staleIds, [1, 3]);
+    const settled = reconcileInlineComments(desired, desired.map((comment, index) => ({
+        id: index + 10, path: comment.path, line: comment.line, body: comment.body,
+        user: { login: 'github-actions[bot]' },
+    })));
+    assert.deepEqual(settled, { create: [], staleIds: [], kept: 2 });
+});
+check('the batched GitHub review carries the required comment body and current commit', () => {
+    const comment = { path: 'a.ts', line: 1, side: 'RIGHT', body: 'finding' };
+    const payload = createReviewPayload('a'.repeat(40), [comment]);
+    assert.equal(payload.commit_id, 'a'.repeat(40));
+    assert.equal(payload.event, 'COMMENT');
+    assert.match(payload.body, /1 proven verified finding/);
+    assert.deepEqual(payload.comments, [comment]);
+});
+await checkAsync('the GitHub client paginates files, submits the review contract, and treats delete 404 as settled', async () => {
+    const originalFetch = globalThis.fetch;
+    const calls = [];
+    const json = (value, init = {}) => new Response(JSON.stringify(value), { status: 200, ...init });
+    const fakeFetch = async (input, init) => {
+        const url = String(input);
+        const method = init?.method ?? 'GET';
+        const body = typeof init?.body === 'string' ? init.body : undefined;
+        calls.push({ url, method, body });
+        assert.equal(new Headers(init?.headers).get('authorization'), 'Bearer token');
+        if (url.endsWith('/pulls/7'))
+            return json({ head: { sha: 'a'.repeat(40) } });
+        if (url.includes('/pulls/7/files') && !url.includes('page=2')) {
+            return json([{ filename: 'a.ts', patch: '@@ -0,0 +1,1 @@\n+one' }], {
+                headers: { link: '<https://api.github.test/repos/acme/repo/pulls/7/files?per_page=100&page=2>; rel="next"' },
+            });
+        }
+        if (url.includes('/pulls/7/files') && url.includes('page=2')) {
+            return json([{ filename: 'b.bin' }]);
+        }
+        if (url.includes('/pulls/7/comments')) {
+            return json([
+                { id: 9, path: 'a.ts', line: 1, body: 'old', user: { login: 'github-actions[bot]' } },
+                { id: 10, path: 'a.ts', line: 1, body: 'reply', in_reply_to_id: 9, user: { login: 'human' } },
+            ]);
+        }
+        if (method === 'POST' && url.endsWith('/pulls/7/reviews'))
+            return json({ id: 1 });
+        if (method === 'DELETE' && url.endsWith('/pulls/comments/9'))
+            return json({ message: 'gone' }, { status: 404 });
+        return json({ message: 'unexpected request' }, { status: 500 });
+    };
+    globalThis.fetch = fakeFetch;
+    try {
+        const api = new GitHubPullRequestApi('https://api.github.test', 'token', 'acme', 'repo', 7);
+        assert.equal(await api.headSha(), 'a'.repeat(40));
+        assert.deepEqual(await api.listFiles(), [
+            { filename: 'a.ts', patch: '@@ -0,0 +1,1 @@\n+one' },
+            { filename: 'b.bin', patch: undefined },
+        ]);
+        const comments = await api.listReviewComments();
+        assert.equal(comments[0]?.id, 9);
+        assert.equal(comments[1]?.inReplyToId, 9);
+        await api.createReview('a'.repeat(40), [{ path: 'a.ts', line: 1, side: 'RIGHT', body: 'finding' }]);
+        await api.deleteReviewComment(9);
+    }
+    finally {
+        globalThis.fetch = originalFetch;
+    }
+    const submitted = calls.find((call) => call.method === 'POST');
+    assert.ok(submitted?.body);
+    assert.deepEqual(JSON.parse(submitted.body), {
+        commit_id: 'a'.repeat(40),
+        body: 'PowerShot posted 1 proven verified finding(s) on changed lines.',
+        event: 'COMMENT',
+        comments: [{ path: 'a.ts', line: 1, side: 'RIGHT', body: 'finding' }],
+    });
+    assert.equal(calls.filter((call) => call.url.includes('/files')).length, 2);
+});
+await checkAsync('inline synchronization creates one review before removing stale comments', async () => {
+    const finding = {
+        id: 'F1', class: 'verified', check: 'a', severity: 'high', confidence: 'proven',
+        file: 'a.ts', line: 1, title: 'one',
+    };
+    const events = [];
+    const api = {
+        headSha: async () => 'a'.repeat(40),
+        listFiles: async () => [{ filename: 'a.ts', patch: '@@ -0,0 +1,1 @@\n+one' }],
+        listReviewComments: async () => [{
+                id: 7, path: 'old.ts', line: 1,
+                body: 'old\n<!-- powershot:inline:v1:0123456789abcdef01234567 -->',
+                user: { login: 'github-actions[bot]' },
+            }],
+        createReview: async (commitId, comments) => {
+            events.push(`create:${commitId}:${comments.length}`);
+        },
+        deleteReviewComment: async (id) => {
+            events.push(`delete:${id}`);
+        },
+    };
+    const result = await syncInlineComments(api, [finding], 'a'.repeat(40));
+    assert.deepEqual(events, [`create:${'a'.repeat(40)}:1`, 'delete:7']);
+    assert.deepEqual(result, { outdated: false, desired: 1, created: 1, kept: 0, retired: 1 });
+});
+await checkAsync('inline synchronization makes no writes for an outdated pull request head', async () => {
+    let reads = 0;
+    const api = {
+        headSha: async () => 'b'.repeat(40),
+        listFiles: async () => { reads++; return []; },
+        listReviewComments: async () => { reads++; return []; },
+        createReview: async () => { throw new Error('must not create'); },
+        deleteReviewComment: async () => { throw new Error('must not delete'); },
+    };
+    const result = await syncInlineComments(api, [], 'a'.repeat(40));
+    assert.equal(reads, 0);
+    assert.deepEqual(result, { outdated: true, desired: 0, created: 0, kept: 0, retired: 0 });
+});
+await checkAsync('inline synchronization makes no writes when the pull request head changes during reads', async () => {
+    let headReads = 0;
+    let writes = 0;
+    const api = {
+        headSha: async () => ++headReads === 1 ? 'a'.repeat(40) : 'b'.repeat(40),
+        listFiles: async () => [{ filename: 'a.ts', patch: '@@ -0,0 +1,1 @@\n+one' }],
+        listReviewComments: async () => [],
+        createReview: async () => { writes++; },
+        deleteReviewComment: async () => { writes++; },
+    };
+    const result = await syncInlineComments(api, [sample[0]], 'a'.repeat(40));
+    assert.equal(headReads, 2);
+    assert.equal(writes, 0);
+    assert.deepEqual(result, { outdated: true, desired: 0, created: 0, kept: 0, retired: 0 });
+});
 check('nested modules use the native package import map', () => {
     const manifest = JSON.parse(readFileSync(join(process.cwd(), 'package.json'), 'utf8'));
     assert.equal(manifest.imports?.['#app/*.js'], './dist/*.js');
@@ -696,17 +901,22 @@ check('the public action persists judge answers and publishes only a verdict', (
     assert.match(action, /restore-keys:/);
     assert.match(action, /upload-sarif:\s*\n\s+description: [^\n]+\n\s+default: 'true'/);
     assert.match(action, /Upload SARIF[\s\S]+inputs\.upload-sarif == 'true'[\s\S]+steps\.review\.outputs\.complete == 'true'/);
+    assert.match(action, /inline-comments:\s*\n\s+description: [^\n]+\n\s+default: 'false'/);
+    assert.match(action, /Post inline comments[\s\S]+inputs\.inline-comments == 'true'[\s\S]+steps\.review\.outputs\.complete == 'true'/);
+    assert.match(action, /node "\$GITHUB_ACTION_PATH\/dist\/github\/inline-comments\.js"/);
 });
 check('published CI examples preserve one verdict and its exit status', () => {
     const action = readFileSync(join(process.cwd(), 'examples', 'github-actions', 'action.yml'), 'utf8');
     const github = readFileSync(join(process.cwd(), 'examples', 'github-actions', 'cli.yml'), 'utf8');
     const gitlab = readFileSync(join(process.cwd(), 'examples', 'gitlab', '.gitlab-ci.yml'), 'utf8');
     assert.match(action, /upload-sarif: 'true'/);
-    assert.match(github, /npm install --global --ignore-scripts @0xcraft\/powershot@1\.0\.1/);
+    assert.match(action, /inline-comments: 'true'/);
+    assert.match(action, /runs-on: ubuntu-24\.04/);
+    assert.match(github, /npm install --global --ignore-scripts @0xcraft\/powershot@1\.1\.0/);
     assert.equal(github.match(/psh review/g)?.length, 1);
     assert.match(github, /--report markdown=powershot\.md[\s\S]+--report sarif=powershot\.sarif/);
     assert.match(github, /\|\| STATUS=\$\?[\s\S]+case "\$STATUS"/);
-    assert.match(gitlab, /npm install --global --ignore-scripts @0xcraft\/powershot@1\.0\.1/);
+    assert.match(gitlab, /npm install --global --ignore-scripts @0xcraft\/powershot@1\.1\.0/);
     assert.equal(gitlab.match(/psh review/g)?.length, 1);
     assert.match(gitlab, /--format codequality > gl-code-quality-report\.json \|\| STATUS=\$\?/);
     assert.match(gitlab, /test "\$STATUS" -le 1 \|\| exit "\$STATUS"/);

package/docs/ci.md

@@ -27,7 +27,8 @@ There are two independent decisions:
 ## GitHub Action
 
 The action runs one review, adds a job summary, uploads SARIF when enabled, and can
-maintain one pull-request comment.
+maintain one pull-request comment. Its opt-in inline mode posts a bounded batched
+review on changed lines.
 
 ```yaml
 name: PowerShot
@@ -42,7 +43,7 @@ permissions:
 
 jobs:
   review:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v7
         with:
@@ -53,12 +54,21 @@ jobs:
           verify-only: 'true'
           upload-sarif: 'true'
           comment: 'true'
+          inline-comments: 'true'
           fail-on-findings: 'true'
 ```
 
 Set `upload-sarif: 'false'` and omit `security-events: write` when GitHub code scanning
 is unavailable or the workflow should not publish SARIF.
 
+`inline-comments: 'true'` requires `pull-requests: write`. It publishes at most ten
+findings as one review. Only deterministic `verified` findings with `proven`
+confidence, severity `medium` or higher, and a GitHub-confirmed added line qualify.
+Findings on context lines or files whose patch GitHub omitted stay in the full report.
+Reruns preserve exact bot comments, create only missing comments, and remove stale
+PowerShot inline copies without replies. Human comments and replied-to discussions
+are never modified.
+
 The major tag follows compatible `1.x` releases. Pin a full commit SHA in a protected
 required workflow when immutable dependencies are required. The copy-paste version
 lives at [`examples/github-actions/action.yml`](../examples/github-actions/action.yml).
@@ -73,6 +83,7 @@ lives at [`examples/github-actions/action.yml`](../examples/github-actions/actio
 | `checks` | empty | Select comma-separated check ids |
 | `upload-sarif` | `true` | Upload a complete SARIF report to GitHub code scanning |
 | `comment` | `true` | Maintain a pull-request comment |
+| `inline-comments` | `false` | Post up to ten proven verified findings as one inline review |
 | `fail-on-findings` | `false` | Turn a complete finding verdict into a failed job |
 | `approve` | `false` | Approve only a complete, clean review |
 
@@ -88,7 +99,7 @@ step inside a larger quality job. The complete example is
 The core pattern is:
 
 ```bash
-npm install --global --ignore-scripts @0xcraft/powershot@1.0.1
+npm install --global --ignore-scripts @0xcraft/powershot@1.1.0
 
 STATUS=0
 psh review --verify-only \

package/examples/github-actions/action.yml

@@ -10,7 +10,7 @@ permissions:
 
 jobs:
   review:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v7
         with:
@@ -21,4 +21,5 @@ jobs:
           verify-only: 'true'
           upload-sarif: 'true'
           comment: 'true'
+          inline-comments: 'true'
           fail-on-findings: 'true'

package/examples/github-actions/cli.yml

@@ -19,7 +19,7 @@ jobs:
           node-version: '24'
 
       - name: Install PowerShot
-        run: npm install --global --ignore-scripts @0xcraft/powershot@1.0.1
+        run: npm install --global --ignore-scripts @0xcraft/powershot@1.1.0
 
       - name: Review pull request
         env:

package/examples/gitlab/.gitlab-ci.yml

@@ -5,7 +5,7 @@ powershot:
   variables:
     GIT_DEPTH: "0"
   before_script:
-    - npm install --global --ignore-scripts @0xcraft/powershot@1.0.1
+    - npm install --global --ignore-scripts @0xcraft/powershot@1.1.0
   script:
     - |
       STATUS=0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xcraft/powershot",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Oracle-first code review for machine-written code, with deterministic verification and CI-ready reports.",
   "license": "Apache-2.0",
   "author": "aglumova <alina.glumova@gmail.com>",