@0xcraft/powershot 1.0.1 → 1.1.1

package/README.md

@@ -211,17 +211,39 @@ The composite action is the shortest setup for GitHub:
   with:
     fetch-depth: 0
 
+- run: npm ci --ignore-scripts
+
 - uses: xcrft/powershot@v1
   with:
     verify-only: 'true'
     upload-sarif: 'true'
     comment: 'true'
+    inline-comments: 'true'
     fail-on-findings: 'true'
 ```
 
+Install the checked-out project's dependencies before PowerShot so TypeScript can
+resolve its declared ambient types. The example disables lifecycle scripts because
+pull-request code is untrusted; use the equivalent safe install for another package
+manager. In a monorepo, install from the workspace root or add safe install steps for
+the affected package roots.
+
+PowerShot discovers `tsconfig.json` and `tsconfig.*.json` along the ancestor chain of
+each changed file. One review can use several independent package projects, skip
+empty solution configs in favour of their leaf configs, and type-check test files
+that a production config excludes. Discovery is change-scoped: unrelated packages
+and configless source trees are not crawled just to build the TypeScript ground.
+
 `@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