mirror of
https://github.com/garrytan/gstack.git
synced 2026-11-16 21:31:58 +01:00
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
241 lines
12 KiB
TypeScript
241 lines
12 KiB
TypeScript
/**
|
|
* review-scope — the finding scope of /ship's pre-landing review loop
|
|
* (ship/sections/review-army.md, Step 9.4; docs/ship-policy.md#review-scope).
|
|
*
|
|
* Five Captains hit the same loop: every pass re-read the whole diff, found
|
|
* new neighbours in pre-existing code, fixed them, and the fixes drew another
|
|
* pass until the cycle cap. Under `review_scope: frozen` (the default) the
|
|
* scope is fixed after pass 1: findings in the diff are fixed, findings in
|
|
* code the PR did not change are filed as issues (deferred), and later passes
|
|
* read only the range since the previous pass and fix only blocking findings.
|
|
* Everything below the blocking floor is a named note in the PR body and never
|
|
* triggers a pass. `review_scope: all` keeps the old behaviour.
|
|
*
|
|
* Pure functions here; bin/gstack-review-scope runs git and gh.
|
|
*/
|
|
|
|
export type Locus = 'diff' | 'fix-range' | 'outside';
|
|
export type Kind = 'defect' | 'test-gap' | 'advisory';
|
|
export type ReviewScopePolicy = 'frozen' | 'diff-plus-blocking' | 'all';
|
|
export const REVIEW_SCOPE_POLICIES: readonly ReviewScopePolicy[] = ['frozen', 'diff-plus-blocking', 'all'];
|
|
export type ScopeAction = 'fix' | 'defer' | 'note';
|
|
|
|
/** Lines around a changed hunk that still count as the diff (a missing check right after an added line is the diff's fault). */
|
|
export const HUNK_CONTEXT_LINES = 3;
|
|
|
|
export interface ScopeFinding {
|
|
fingerprint?: string; path?: string; line?: number; severity?: string; category?: string; summary?: string;
|
|
problem?: string; fix?: string; specialist?: string; advisory?: boolean; test_stub?: string;
|
|
[key: string]: unknown;
|
|
}
|
|
export interface ScopedFinding extends ScopeFinding { locus: Locus; kind: Kind; blocking: boolean; scope: ScopeAction }
|
|
|
|
/** Per path, the new-side line ranges a diff touched; `'whole'` for an added or untracked file. */
|
|
export type HunkMap = Record<string, Array<[number, number]> | 'whole'>;
|
|
|
|
/** Parse `git diff -U0` output (plus untracked paths as whole files) into a hunk map. */
|
|
export function parseHunks(diff: string, untracked: readonly string[] = []): HunkMap {
|
|
const map: HunkMap = {};
|
|
let current: string | null = null;
|
|
let added = false;
|
|
for (const raw of diff.split('\n')) {
|
|
const line = raw.replace(/\r$/, '');
|
|
if (line.startsWith('diff --git ')) { current = null; added = false; continue; }
|
|
if (line.startsWith('--- ')) { added = line === '--- /dev/null'; continue; }
|
|
if (line.startsWith('+++ ')) {
|
|
if (line === '+++ /dev/null') { current = null; continue; }
|
|
current = line.replace(/^\+\+\+ (?:b\/)?/, '').replace(/\t.*$/, '');
|
|
if (added) map[current] = 'whole';
|
|
else if (!(current in map)) map[current] = [];
|
|
continue;
|
|
}
|
|
if (!current || map[current] === 'whole') continue;
|
|
const m = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/.exec(line);
|
|
if (!m) continue;
|
|
const start = Number(m[1]);
|
|
const count = m[2] === undefined ? 1 : Number(m[2]);
|
|
// A pure deletion (+N,0) still marks the line where the code used to be.
|
|
(map[current] as Array<[number, number]>).push([start, count === 0 ? start : start + count - 1]);
|
|
}
|
|
for (const p of untracked) if (p) map[normalizePath(p)] = 'whole';
|
|
return map;
|
|
}
|
|
|
|
function normalizePath(p: string): string {
|
|
return p.replace(/\\/g, '/').replace(/^\.\//, '');
|
|
}
|
|
|
|
function inHunks(hunks: HunkMap, path: string, line: number | undefined, context: number): boolean {
|
|
const ranges = hunks[normalizePath(path)];
|
|
if (ranges === undefined) return false;
|
|
if (ranges === 'whole' || line === undefined || !Number.isFinite(line)) return true;
|
|
return ranges.some(([a, b]) => line >= a - context && line <= b + context);
|
|
}
|
|
|
|
/** Where a finding sits: in the range since the previous pass, in the branch diff, or in code the PR did not change. */
|
|
export function locusOf(finding: ScopeFinding, diffHunks: HunkMap, rangeHunks: HunkMap | null, context = HUNK_CONTEXT_LINES): Locus {
|
|
const path = typeof finding.path === 'string' ? finding.path : fingerprintPath(finding.fingerprint);
|
|
if (!path) return 'outside';
|
|
const line = typeof finding.line === 'number' ? finding.line : fingerprintLine(finding.fingerprint);
|
|
if (rangeHunks && inHunks(rangeHunks, path, line, context)) return 'fix-range';
|
|
if (inHunks(diffHunks, path, line, context)) return 'diff';
|
|
return 'outside';
|
|
}
|
|
|
|
function fingerprintPath(fp: unknown): string | undefined {
|
|
if (typeof fp !== 'string' || fp.startsWith('shared-libs:')) return undefined;
|
|
const [path] = fp.split(':');
|
|
return path || undefined;
|
|
}
|
|
function fingerprintLine(fp: unknown): number | undefined {
|
|
if (typeof fp !== 'string') return undefined;
|
|
const n = Number(fp.split(':')[1]);
|
|
return Number.isInteger(n) && n > 0 ? n : undefined;
|
|
}
|
|
|
|
/** A finding's kind: optional advice, a missing test, or a defect. */
|
|
export function kindOf(finding: ScopeFinding): Kind {
|
|
if (finding.advisory === true) return 'advisory';
|
|
const category = String(finding.category ?? '').toLowerCase();
|
|
if (/^(test-gap|test-coverage|coverage|missing-test|untested)$/.test(category)) return 'test-gap';
|
|
return 'defect';
|
|
}
|
|
|
|
/**
|
|
* The blocking floor: a CRITICAL defect (a test that would fail, a production
|
|
* break, a security or data-loss defect). Advisories, test gaps, wording and
|
|
* INFORMATIONAL items are below it and never trigger another pass.
|
|
*/
|
|
export function isBlocking(finding: ScopeFinding, kind = kindOf(finding)): boolean {
|
|
return kind === 'defect' && String(finding.severity ?? '').toUpperCase() === 'CRITICAL';
|
|
}
|
|
|
|
export interface ScopeInput { policy: ReviewScopePolicy; pass: number; diffHunks: HunkMap; rangeHunks: HunkMap | null; context?: number }
|
|
|
|
/**
|
|
* The scope decision per finding. `all`: fix everything (today's loop).
|
|
* `frozen` pass 1: fix the diff, defer blocking findings in unchanged code,
|
|
* note the rest. `frozen` pass 2+: fix blocking findings in the range since
|
|
* the previous pass or in the diff; defer blocking findings outside; note
|
|
* everything else.
|
|
*/
|
|
export function scopeFindings(findings: readonly ScopeFinding[], input: ScopeInput): ScopedFinding[] {
|
|
return findings.map(finding => {
|
|
const kind = kindOf(finding);
|
|
const blocking = isBlocking(finding, kind);
|
|
const locus = locusOf(finding, input.diffHunks, input.pass > 1 ? input.rangeHunks : null, input.context);
|
|
let scope: ScopeAction;
|
|
if (input.policy === 'all') scope = 'fix';
|
|
else if (locus === 'outside') scope = !blocking ? 'note' : input.policy === 'diff-plus-blocking' ? 'fix' : 'defer';
|
|
else if (input.pass <= 1) scope = 'fix';
|
|
else scope = blocking ? 'fix' : 'note';
|
|
return { ...finding, locus, kind, blocking, scope };
|
|
});
|
|
}
|
|
|
|
export function scopeCounts(scoped: readonly ScopedFinding[]): { fix: number; defer: number; note: number; blocking: number } {
|
|
return {
|
|
fix: scoped.filter(f => f.scope === 'fix').length, defer: scoped.filter(f => f.scope === 'defer').length,
|
|
note: scoped.filter(f => f.scope === 'note').length, blocking: scoped.filter(f => f.blocking).length,
|
|
};
|
|
}
|
|
|
|
export function scopeLine(policy: ReviewScopePolicy, pass: number, scoped: readonly ScopedFinding[]): string {
|
|
const c = scopeCounts(scoped);
|
|
return `REVIEW_SCOPE: policy=${policy} pass=${pass} findings=${scoped.length} fix=${c.fix} defer=${c.defer} note=${c.note} blocking=${c.blocking}`;
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// deferral: one issue per blocking finding in code the PR did not change
|
|
// ---------------------------------------------------------------------------
|
|
export const DEFERRED_MARKER = 'gstack-deferred-finding';
|
|
const oneLine = (s: unknown) => String(s ?? '').replace(/[\x00-\x1f\x7f\u2028\u2029]+/g, ' ').trim();
|
|
|
|
export function findingIdentity(f: ScopeFinding): string {
|
|
if (typeof f.fingerprint === 'string' && f.fingerprint) return f.fingerprint;
|
|
return [f.path ?? '?', f.line ?? '', f.category ?? ''].join(':');
|
|
}
|
|
export function findingWhere(f: ScopeFinding): string {
|
|
return f.path ? `${f.path}${typeof f.line === 'number' ? `:${f.line}` : ''}` : fingerprintPath(f.fingerprint) ?? '(no path)';
|
|
}
|
|
function findingText(f: ScopeFinding): string {
|
|
return oneLine(f.summary ?? f.problem ?? f.category ?? 'review finding');
|
|
}
|
|
|
|
export interface DeferContext { repo?: string; pr?: number; branch?: string; head?: string }
|
|
|
|
/** Issue title and body for a deferred finding; the marker keeps a rerun from filing it twice. */
|
|
export function renderDeferredIssue(f: ScopedFinding, ctx: DeferContext): { title: string; body: string; marker: string } {
|
|
const text = findingText(f);
|
|
const title = `Deferred review finding: ${findingWhere(f)} — ${text}`.slice(0, 120);
|
|
const origin = ctx.pr ? `${ctx.repo ? `${ctx.repo}#${ctx.pr}` : `PR #${ctx.pr}`}` : ctx.branch ? `branch \`${ctx.branch}\`` : 'a /ship run';
|
|
const marker = `<!-- ${DEFERRED_MARKER}: ${oneLine(findingIdentity(f))} -->`;
|
|
const body = [
|
|
`Filed by /ship's pre-landing review of ${origin}${ctx.head ? ` (head ${ctx.head.slice(0, 12)})` : ''}. The finding is in code that PR did not change, so it was deferred here instead of being fixed there (review scope frozen after pass 1).`,
|
|
'',
|
|
`- **Severity:** ${oneLine(f.severity ?? 'unrated')}`,
|
|
`- **Where:** \`${findingWhere(f)}\``,
|
|
`- **Finding:** ${text}`,
|
|
...(f.fix ? [`- **Suggested fix:** ${oneLine(f.fix)}`] : []),
|
|
...(f.specialist ? [`- **Found by:** ${oneLine(f.specialist)}`] : []),
|
|
'',
|
|
marker,
|
|
'',
|
|
].join('\n');
|
|
return { title, body, marker };
|
|
}
|
|
|
|
export interface DeferredRecord { fingerprint: string; path: string; severity: string; summary: string; issue: number | null; url?: string; reason?: string }
|
|
|
|
/** The PR-body section for deferred findings: references, never closing keywords, so a merge closes nothing. */
|
|
export function renderDeferredSection(deferred: readonly DeferredRecord[], noted: readonly ScopeFinding[] = [], policy: ReviewScopePolicy = 'frozen'): string {
|
|
const out: string[] = [];
|
|
if (deferred.length) {
|
|
out.push('## Deferred findings', '', `Blocking findings in code this PR did not change (review scope: ${policy}); filed as issues and not closed by this PR.`, '');
|
|
for (const d of deferred) {
|
|
const ref = d.issue ? `#${d.issue}` : `unfiled${d.reason ? ` (${oneLine(d.reason)})` : ''}`;
|
|
out.push(`- Deferred: ${ref} — ${oneLine(d.severity)} \`${oneLine(d.path)}\` ${oneLine(d.summary)}`);
|
|
}
|
|
out.push('');
|
|
}
|
|
if (noted.length) {
|
|
out.push('## Review notes', '', 'Below the blocking floor (advisory, informational, test-gap or wording items); recorded here and not fixed in this PR.', '');
|
|
for (const n of noted) out.push(`- ${oneLine(n.severity ?? 'INFORMATIONAL')}${n.advisory ? ' [ADVISORY]' : ''} \`${findingWhere(n)}\` ${findingText(n)}`);
|
|
out.push('');
|
|
}
|
|
return out.join('\n');
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// loop summary: what the ship receipt carries for the factory scorecard
|
|
// ---------------------------------------------------------------------------
|
|
export interface ReviewLoopSummary { passes: number; blocking_found: number; deferred: number; noted: number; fixed: number; scope: ReviewScopePolicy | 'unknown' }
|
|
|
|
/** Review-log rows of one /ship invocation (skill review, via ship, at or after `since`) → the loop summary. */
|
|
export function summarizeReviewLoop(rows: readonly Record<string, any>[], since: string): ReviewLoopSummary {
|
|
const sinceMs = Date.parse(since);
|
|
const passes = rows.filter(r => r && r.skill === 'review' && r.via === 'ship' && typeof r.timestamp === 'string'
|
|
&& Number.isFinite(Date.parse(r.timestamp)) && (!Number.isFinite(sinceMs) || Date.parse(r.timestamp) >= sinceMs));
|
|
const blocking = new Set<string>();
|
|
const deferred = new Set<string>();
|
|
const noted = new Set<string>();
|
|
const fixed = new Set<string>();
|
|
let scope: ReviewLoopSummary['scope'] = 'unknown';
|
|
for (const row of passes) {
|
|
if (REVIEW_SCOPE_POLICIES.includes(row.review_scope)) scope = row.review_scope;
|
|
for (const f of Array.isArray(row.findings) ? row.findings : []) {
|
|
if (!f || typeof f !== 'object') continue;
|
|
const id = findingIdentity(f);
|
|
if (f.blocking === true) blocking.add(id);
|
|
if (f.action === 'deferred') deferred.add(id);
|
|
if (f.action === 'noted') noted.add(id);
|
|
if (f.action === 'fixed' || f.action === 'auto-fixed') fixed.add(id);
|
|
}
|
|
}
|
|
return { passes: passes.length, blocking_found: blocking.size, deferred: deferred.size, noted: noted.size, fixed: fixed.size, scope };
|
|
}
|
|
|
|
export function reviewLoopLine(s: ReviewLoopSummary): string {
|
|
return `REVIEW_LOOP: passes=${s.passes} blocking_found=${s.blocking_found} deferred=${s.deferred} noted=${s.noted} fixed=${s.fixed} scope=${s.scope}`;
|
|
}
|