import { resolve } from 'node:path'; import { pathToFileURL } from 'node:url'; import { appendFileSync, readFileSync } from 'node:fs'; import type { QualityFindings } from './findings.mts'; import { COMMENT_LIMIT, DEFAULT_CRAP_THRESHOLD, DEFAULT_REFACTOR_HINTS, renderSections, resolveHints, resolveThreshold, } from './render.mts'; import { loadFindingsFile, validateFindings } from './findings.mts'; import { reportSelection } from './changes.mts'; export const GATE = 'Quality decision'; const PREFIX = '')) return; try { const value: Request = JSON.parse(line.slice(PREFIX.length, -4)); if ( ![value.request, value.pr, value.run, value.attempt].every(positive) || !SHA.test(value.head) || !SHA.test(value.base) || !/^[a-z\d-]+(?:\[bot\])?$/iu.test(value.actor) || !['queued', 'running', 'completed', 'ignored'].includes(value.phase) || typeof value.staticMutants !== 'boolean' || !Array.isArray(value.scopes) || !( value.conclusion === null || [ 'success', 'failure', 'cancelled', 'timed_out', 'action_required', 'neutral', 'skipped', 'stale', 'startup_failure', ].includes(value.conclusion) ) ) return; if (value.check === 'ignore') { if (value.scopes.length || value.phase !== 'ignored') return; } else { const selection = reportSelection(value.check, value.scopes.join(',')); if (JSON.stringify(selection.scopes) !== JSON.stringify(value.scopes)) return; } return value; } catch { return; } } export async function pages(api: API, path: string, key?: string): Promise { const all: T[] = []; for (let page = 1; ; page++) { const result = await api.request>( 'GET', `${path}${path.includes('?') ? '&' : '?'}per_page=100&page=${page}`, ); const items = key ? (result as Record)[key] : (result as T[]); all.push(...items); if (items.length < 100) return all; } } const comments = (api: API, pr: number) => pages(api, `issues/${pr}/comments`); const runURL = (context: Context, run: number) => `${context.server}/${context.repository}/actions/runs/${run}`; class GitHubError extends Error { readonly status: number; constructor(status: number, message: string) { super(message); this.status = status; } } function matchesRequest(run: Run, request: Request, context: Context) { return ( run.repository?.full_name.toLowerCase() === context.repository.toLowerCase() && run.id === request.run && run.event === 'issue_comment' && run.path === '.github/workflows/change-quality.yml' && run.display_title === `Quality PR #${request.pr} request ${request.request}` ); } function requests(items: Comment[], pr: number) { return items.flatMap((item) => { const request = readRequest(item); return request?.pr === pr ? [request] : []; }); } async function activeRequests(api: API, context: Context, records: Request[]) { const found = await Promise.all( records .filter((request) => request.check !== 'ignore') .map(async (request) => { try { const run = await api.request('GET', `actions/runs/${request.run}`); return matchesRequest(run, request, context) && run.status !== 'completed' ? { request, run } : undefined; } catch (error) { if (error instanceof GitHubError && error.status === 404) return; throw error; } }), ); return found.filter((item) => item !== undefined); } /** Force cancellation also stops jobs whose conditions use always(). */ async function cancelRequest(api: API, context: Context, request: Request, run: Run) { if (!matchesRequest(run, request, context) || run.status === 'completed') return; try { await api.request('POST', `actions/runs/${run.id}/force-cancel`); } catch (error) { // A run can finish between inspection and cancellation. const current = await api.request('GET', `actions/runs/${run.id}`); if (matchesRequest(current, request, context) && current.status === 'completed') return; throw error; } for (let attempt = 0; attempt < 30; attempt++) { const current = await api.request('GET', `actions/runs/${run.id}`); if (!matchesRequest(current, request, context)) throw new Error('Quality run identity changed'); if (current.status === 'completed') return; await new Promise((resolve) => setTimeout(resolve, 1000)); } throw new Error('Previous quality run has not stopped; retry the request'); } /** States exactly what `publishRun` and `gateDecision` treat as closing the gate. */ export const GATE_FOOTER = [ 'The gate opens only when the workflow, source selection, tooling verification, and every report', "job succeed. A report job fails on a failed test in its workspace's own Jest run, a tool error,", 'a job timeout, or an incomplete mutation report, including a mutation shard that reaches its', 'execution budget. A cancelled workflow keeps the gate closed. Scores are advisory. A change-risk', 'file marked incomplete or unavailable, for example by a failed `api/` source-alias suite, does', 'not close the gate.', ].join(' '); /** change-quality.yml's trusted job that bundles every report, and its upload steps. * `workflow.test.mts` asserts the workflow uses these exact names. */ export const REPORT_JOB = 'Quality report'; export const REPORT_ARTIFACT = 'quality-report'; export const REPORT_UPLOAD_STEP = 'Upload quality report'; export const FINDINGS_ARTIFACT = 'quality-internal-findings'; export const FINDINGS_UPLOAD_STEP = 'Upload report findings'; /** One line stating whether the gate is open, and exactly what keeps it closed. */ export function renderVerdict(request: Request, blockers: string[] = []): string { if (request.check === 'ignore') return '**Gate: open.** Quality checks explicitly ignored for this commit.'; if (request.phase !== 'completed') return `**Gate: pending.** Checks are ${request.phase === 'queued' ? 'queued' : 'running'}.`; if (request.conclusion === 'success') return '**Gate: open.** The selected checks completed. Scores and risk levels are advisory.'; const reasons = blockers.length ? blockers : [`the workflow (${request.conclusion ?? 'failure'})`]; return `**Gate: closed.** Blocked by: ${reasons.join(', ')}.`; } export function renderRequest( request: Request, context: Context, currentHead: string, details = '', blockers: string[] = [], ) { const scopes = request.scopes.join(', ') || 'none'; const url = runURL(context, request.run); const risk = request.check === 'risk' || request.check === 'both' ? scopes : 'none'; const mutation = request.check !== 'risk' && request.scopes.includes('data-schemas') ? 'data-schemas (four shards)' : 'none'; return [ `${PREFIX}${JSON.stringify(request)} -->`, HEADING, '', ...(currentHead !== request.head ? ['**Outdated: this request is for an earlier PR commit.**', ''] : []), renderVerdict(request, blockers), '', ...(request.check === 'ignore' ? [] : [ `Status: **${request.phase}${request.conclusion ? ` (${request.conclusion})` : ''}**. [Actions run](${url}), attempt ${request.attempt}.`, '', ]), `- Commit: \`${request.head}\``, `- Requested by: @${request.actor}`, `- Check: **${request.check === 'both' ? 'check-all' : request.check}**`, ...(request.check === 'ignore' ? [] : [ `- Scopes: **${scopes}**`, `- Static mutants: **${request.staticMutants ? 'on' : 'off'}**${request.check === 'risk' ? ' (not used by change risk)' : ''}`, `- Change risk: ${risk}`, `- Mutation testing (experimental, \`data-schemas\` only): ${mutation}`, ]), ...(details ? ['', details] : []), '', GATE_FOOTER, ].join('\n'); } export function gateDecision(records: Request[], head: string) { const latest = records .filter((item) => item.head === head) .sort((a, b) => b.request - a.request)[0]; if (!latest) return { state: 'pending', description: 'Comment /quality check-all to run checks, or /quality ignore if not needed', request: undefined, }; if (latest.check === 'ignore') return { state: 'success', description: `Explicitly ignored by ${latest.actor}`, request: latest, }; if (latest.phase !== 'completed') return { state: 'pending', description: 'Checks queued or running. Wait for results, or comment /quality ignore if not needed', request: latest, }; return latest.conclusion === 'success' ? { state: 'success', description: 'Selected quality checks completed; scores are advisory', request: latest, } : { state: 'failure', description: 'Checks failed or cancelled. Comment /quality check-all to retry, or /quality ignore if not needed', request: latest, }; } async function updateGate(api: API, context: Context, pr: number) { const pull = await api.request('GET', `pulls/${pr}`); const records = (await comments(api, pr)).flatMap((comment) => { const record = readRequest(comment); return record?.pr === pr ? [record] : []; }); const decision = gateDecision(records, pull.head.sha); await api.request('POST', `statuses/${pull.head.sha}`, { context: GATE, state: decision.state, description: decision.description, target_url: decision.request ? runURL(context, decision.request.run) : `${context.server}/${context.repository}/pull/${pr}`, }); } /** Authorization precedes parsing or any expensive work. No comment text is executed. */ export async function acceptRequest(api: API, context: Context, pr: number, comment: Comment) { if (!/^\/quality(?:\s|$)/u.test(comment.body.trim())) return; const trustedBot = comment.user.type === 'Bot' && TRUSTED_BOTS.some(({ login, id }) => comment.user.login === login && comment.user.id === id); if (!trustedBot) { if (comment.user.type !== 'User') return; const permission = await api.request<{ permission: string; user?: { permissions?: { push?: boolean } }; }>('GET', `collaborators/${encodeURIComponent(comment.user.login)}/permission`); if ( !permission.user?.permissions?.push && !['admin', 'maintain', 'write'].includes(permission.permission) ) return; } const pull = await api.request('GET', `pulls/${pr}`); if (pull.state !== 'open') return; let command: Command; try { command = parseCommand(comment.body)!; } catch (error) { await api.request('POST', `issues/${pr}/comments`, { body: `Quality request was not started.\n\n${error instanceof Error ? error.message : usage}`, }); return; } const items = await comments(api, pr); const records = requests(items, pr); const latest = records.toSorted((a, b) => b.request - a.request)[0]; const existing = items.find((item) => readRequest(item)?.request === comment.id); const previous = existing && readRequest(existing); if ((previous && previous.head !== pull.head.sha) || (latest && latest.request > comment.id)) { throw new Error('This quality request was superseded. Post a new /quality command.'); } try { await api.request('POST', `issues/comments/${comment.id}/reactions`, { content: 'eyes' }); } catch { console.warn('Could not add the quality request reaction. Continuing the request.'); } const active = await activeRequests(api, context, records); const duplicate = active.find( ({ request }) => request.request === latest?.request && request.run !== context.run && request.head === pull.head.sha && request.check === command.check && request.staticMutants === command.staticMutants && JSON.stringify(request.scopes) === JSON.stringify(command.scopes), ); if (duplicate) { await api.request('POST', `issues/${pr}/comments`, { body: `This quality request is already running for this commit. [Follow the existing run](${runURL(context, duplicate.run.id)}).`, }); return; } // Re-running Actions preserves the original request's commit and options. const request: Request = { ...(previous ?? { ...command, request: comment.id, pr, head: pull.head.sha, base: pull.base.sha, actor: comment.user.login, }), run: context.run, attempt: context.attempt, phase: (previous ?? command).check === 'ignore' ? 'ignored' : 'queued', conclusion: null, }; if (!SHA.test(request.head) || !SHA.test(request.base)) throw new Error('Invalid PR commit'); if (request.check === 'ignore') { for (const prior of active) { if (prior.run.id !== context.run) await cancelRequest(api, context, prior.request, prior.run); } } const body = renderRequest(request, context, pull.head.sha); const response = await api.request( existing ? 'PATCH' : 'POST', existing ? `issues/comments/${existing.id}` : `issues/${pr}/comments`, { body }, ); if (request.check !== 'ignore') await updateGate(api, context, pr); if (request.check !== 'ignore') { for (const prior of active) { if (prior.run.id !== context.run) await cancelRequest(api, context, prior.request, prior.run); } const current = await api.request('GET', `pulls/${pr}`); if (current.head.sha !== request.head) throw new Error('PR head changed. Post a new /quality command.'); } if (request.check === 'ignore') await updateGate(api, context, pr); return { request, comment: response.id }; } const WORKSPACES = ['data-schemas', 'api', 'server']; const REPORT_JOBS = /^(Change risk|Mutation testing ([1-4])\/4|Mutation report) \((data-schemas|api|server)\)$/u; const REQUIRED_JOBS = ['Select changed source', 'Verify quality tooling']; /** Room left for the request header, verdict, job table, links, and footer. */ const SHELL_MARGIN = 2_000; const compareOrder = (a: number[], b: number[]) => a.reduce((result, value, index) => result || value - b[index], 0); /** Sort key for a report job, or `undefined` for any other job. Change risk comes first, then * mutation shards in order, then the mutation report; one kind follows the scope order. */ function jobOrder(name: string): number[] | undefined { const match = REPORT_JOBS.exec(name); if (!match) return; const [, check, shard, workspace] = match; const kind = check === 'Change risk' ? 0 : check === 'Mutation report' ? 2 : 1; return [kind, WORKSPACES.indexOf(workspace), Number(shard ?? 0)]; } export interface PublishOptions { /** Directory the workflow downloaded the `quality-internal-findings` artifact into. Without it, * the comment carries the job table and links only. */ findingsDir?: string; hints?: number; threshold?: number; } const stepSucceeded = (job: Job | undefined, step: string) => job?.steps?.some((item) => item.name === step && item.conclusion === 'success') ?? false; /** Jobs and run state that keep the gate closed, in `GATE_FOOTER`'s terms. */ function gateBlockers(run: Run, latestJobs: Map, reports: Job[]): string[] { const blockers = REQUIRED_JOBS.flatMap((name) => { const job = latestJobs.get(name); return job?.conclusion === 'success' ? [] : [`${name} (${job?.conclusion ?? job?.status ?? 'did not run'})`]; }); for (const job of reports) if (job.conclusion !== 'success') blockers.push(`${job.name} (${job.conclusion ?? job.status})`); for (const job of latestJobs.values()) { if (REQUIRED_JOBS.includes(job.name) || jobOrder(job.name)) continue; if (['failure', 'cancelled', 'timed_out'].includes(job.conclusion ?? '')) blockers.push(`${job.name} (${job.conclusion})`); } if (run.conclusion !== 'success') blockers.push(`the workflow (${run.conclusion ?? run.status})`); return blockers; } /** The validated findings for this exact request, or a note saying why none are shown. The file * is trusted only when the trusted `Quality report` job's own upload step succeeded, so a * same-named artifact from a PR-code job cannot stand in for it. */ function loadReport( request: Request, context: Context, latestJobs: Map, findingsDir: string, ): { data: QualityFindings } | { note: string } { if (!stepSucceeded(latestJobs.get(REPORT_JOB), FINDINGS_UPLOAD_STEP)) return { note: 'No report data: the quality report job did not upload its findings.' }; const loaded = loadFindingsFile(findingsDir); if (!loaded.ok) { console.warn(`Findings artifact rejected: ${loaded.error}`); return { note: `Report data was rejected: ${loaded.error}.` }; } if (loaded.value === undefined) return { note: 'No report data was downloaded for this run.' }; const checked = validateFindings(loaded.value, { repository: context.repository, pr: request.pr, base: request.base, head: request.head, }); if (!checked.ok) { console.warn(`Findings artifact failed validation: ${checked.error}`); return { note: `Report data was rejected: ${checked.error}.` }; } return { data: checked.value }; } /** Refresh from GitHub's job metadata and the validated findings file. Artifact text is only ever * escaped into the comment, never executed. */ export async function publishRun( api: API, context: Context, run: Run, options: PublishOptions = {}, ) { const match = /^Quality PR #(\d+) request (\d+)$/u.exec(run.display_title); if ( run.event !== 'issue_comment' || run.path !== '.github/workflows/change-quality.yml' || !match ) return; const pr = Number(match[1]); const source = Number(match[2]); const comment = (await comments(api, pr)).find((item) => { const record = readRequest(item); return ( record?.request === source && record.pr === pr && record.run === run.id && record.attempt <= run.run_attempt ); }); if (!comment) return; const request = readRequest(comment)!; if (!matchesRequest(run, request, context)) return; // The record says this attempt already completed, so a delayed progress event for it must not // cancel, re-read or replace the full report. A new attempt or a new request still updates. if ( request.attempt === run.run_attempt && request.phase === 'completed' && run.status !== 'completed' ) return; const pull = await api.request('GET', `pulls/${pr}`); const latest = requests(await comments(api, pr), pr).toSorted((a, b) => b.request - a.request)[0]; if ( run.status !== 'completed' && (request.head !== pull.head.sha || latest.request > request.request) ) { await cancelRequest(api, context, request, run); run = await api.request('GET', `actions/runs/${run.id}`); } if (request.check === 'ignore') { await updateGate(api, context, pr); return; } const jobs = await pages(api, `actions/runs/${run.id}/jobs?filter=all`, 'jobs'); // Failed-job reruns reuse successful jobs from earlier attempts. const latestJobs = new Map(); for (const job of jobs) { if ((latestJobs.get(job.name)?.id ?? 0) < job.id) latestJobs.set(job.name, job); } const reports = [...latestJobs.values()] .flatMap((job) => { const order = jobOrder(job.name); return order ? [{ job, order }] : []; }) .sort((a, b) => compareOrder(a.order, b.order)) .map(({ job }) => job); const artifacts = await pages(api, `actions/runs/${run.id}/artifacts`, 'artifacts'); const reportArtifact = stepSucceeded(latestJobs.get(REPORT_JOB), REPORT_UPLOAD_STEP) ? artifacts.find((artifact) => artifact.name === REPORT_ARTIFACT && !artifact.expired) : undefined; request.attempt = run.run_attempt; request.phase = run.status === 'completed' ? 'completed' : 'running'; const checksSucceeded = REQUIRED_JOBS.every((name) => latestJobs.get(name)?.conclusion === 'success') && reports.every((job) => job.conclusion === 'success'); request.conclusion = run.status !== 'completed' ? null : run.conclusion === 'success' && !checksSucceeded ? 'failure' : run.conclusion; const blockers = request.conclusion === null || request.conclusion === 'success' ? [] : gateBlockers(run, latestJobs, reports); const runPage = runURL(context, run.id); const table = reports.length ? [ '| Check | Result |', '| --- | --- |', ...reports.map( (job) => `| [${job.name}](${runPage}/job/${job.id}) | ${job.conclusion ?? job.status} |`, ), ].join('\n') : 'No report jobs have started. A successful empty selection means no supported source changed.'; const jobsBlock = run.status === 'completed' && reports.length ? `
Jobs (${reports.length})\n\n${table}\n\n
` : table; const links = [ ...(reportArtifact ? [`[All data](${runPage}/artifacts/${reportArtifact.id}) (\`${REPORT_ARTIFACT}\` artifact)`] : []), `[Run page](${runPage})`, ].join(' ยท '); let report: { data: QualityFindings } | { note: string } | undefined; if (run.status === 'completed' && options.findingsDir !== undefined) { report = pull.head.sha !== request.head ? { note: 'The PR head moved after this run, so report details are omitted.' } : loadReport(request, context, latestJobs, options.findingsDir); } const compose = (sections: string) => renderRequest( request, context, pull.head.sha, [sections, jobsBlock, links].filter(Boolean).join('\n\n'), blockers, ); const shell = compose(report && 'note' in report ? report.note : ''); let body = shell; if (report && 'data' in report) { const sections = renderSections(report.data, { repositoryUrl: `${context.server}/${context.repository}`, head: request.head, budget: COMMENT_LIMIT - shell.length - SHELL_MARGIN, hints: options.hints ?? DEFAULT_REFACTOR_HINTS, threshold: options.threshold ?? DEFAULT_CRAP_THRESHOLD, }); body = compose(sections); if (body.length > COMMENT_LIMIT) body = compose('The report is too large for this comment; see All data.'); } await api.request('PATCH', `issues/comments/${comment.id}`, { body }); await updateGate(api, context, pr); } export async function refreshPull(api: API, context: Context, pr: number) { const pull = await api.request('GET', `pulls/${pr}`); const items = await comments(api, pr); for (const prior of await activeRequests(api, context, requests(items, pr))) { if (prior.request.head !== pull.head.sha) await cancelRequest(api, context, prior.request, prior.run); } for (const comment of items) { const request = readRequest(comment); if (!request || request.pr !== pr) continue; // Keep results and artifact links, including when a force push restores the same commit. const stale = '\n**Outdated: this request is for an earlier PR commit.**\n'; const clean = comment.body.replace(stale, ''); // Older request comments carry the `### Quality request` heading. const body = request.head === pull.head.sha ? clean : clean.replace(/^(### Quality (?:request|report)\n)/mu, `$1${stale}`); if (body === comment.body) continue; await api.request('PATCH', `issues/comments/${comment.id}`, { body }); } await updateGate(api, context, pr); } export function client(env: NodeJS.ProcessEnv): API { return { async request(method: string, path: string, body?: object): Promise { const response = await fetch( `${env.GITHUB_API_URL ?? 'https://api.github.com'}${path === '/graphql' ? path : `/repos/${env.GITHUB_REPOSITORY}/${path}`}`, { method, headers: { accept: 'application/vnd.github+json', authorization: `Bearer ${env.GH_TOKEN}`, 'content-type': 'application/json', 'x-github-api-version': '2022-11-28', }, body: body ? JSON.stringify(body) : undefined, signal: AbortSignal.timeout(30000), }, ); if (!response.ok) throw new GitHubError( response.status, `GitHub ${method} ${path.split('?')[0]} failed: HTTP ${response.status}`, ); const text = await response.text(); return (text ? JSON.parse(text) : undefined) as T; }, }; } if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) { const env = process.env; const api = client(env); const context = { repository: env.GITHUB_REPOSITORY!, server: env.GITHUB_SERVER_URL!, run: Number(env.GITHUB_RUN_ID), attempt: Number(env.GITHUB_RUN_ATTEMPT), }; const event = JSON.parse(readFileSync(env.GITHUB_EVENT_PATH!, 'utf8')); if (process.argv[2] === 'request' && event.issue?.pull_request) { const accepted = await acceptRequest(api, context, event.issue.number, event.comment); if (accepted && env.GITHUB_OUTPUT) { const { request } = accepted; appendFileSync( env.GITHUB_OUTPUT, Object.entries({ accepted: request.check !== 'ignore', head: request.head, base: request.base, scope: request.scopes.join(','), check: request.check, static: request.staticMutants ? 'on' : 'off', }) .map(([key, value]) => `${key}=${value}\n`) .join(''), ); } } else if (process.argv[2] === 'progress') { await publishRun(api, context, await api.request('GET', `actions/runs/${context.run}`)); } else if (env.GITHUB_EVENT_NAME === 'workflow_run') { // Read the current attempt so a late event cannot replace a newer rerun's result. await publishRun( api, context, await api.request('GET', `actions/runs/${event.workflow_run.id}`), { // The workflow downloads the findings only for a completed run's event. findingsDir: event.workflow_run.status === 'completed' ? 'findings' : undefined, hints: resolveHints(env.QUALITY_REFACTOR_HINTS), threshold: resolveThreshold(env.QUALITY_CRAP_THRESHOLD), }, ); } else if (env.GITHUB_EVENT_NAME === 'pull_request_target') { await refreshPull(api, context, event.pull_request.number); } }