mirror of
https://github.com/garrytan/gstack.git
synced 2026-11-16 21:31:58 +01:00
fix: pre-landing review fixes (pass 1) and the review-loop budget wording
Two blocking findings from /ship's own pass 1, both reproduced in the QA smoke before the fix: gstack-ship-receipt carry hashed the product diff with git patch-id --stable, which strips whitespace, so a space moved in a reviewed shell line carried as "no product change"; and it classed package.json and every lockfile as release metadata, so a dependency swap carried too. The patch-id is now --verbatim, package.json and VERSION are metadata only while the change is a version stamp (lib/pregate/stamp-only.ts), lockfiles are product unless the policy names them, the test globs name code extensions, a dirty working tree refuses before anything is compared, and a receipt carried twice keeps the reviewed head as carry.from. gstack-review-scope: an unresolvable base is POLICY_SOURCE_UNAVAILABLE instead of a silent working-tree read; --range-base is validated; git runs with core.quotePath=false; range_base is null on pass 1; a blocking finding with no path is fix; category "testing" is a test finding below the floor; defer searches once, files nothing on a failed search and exits 0 unfiled; summary refuses zero matching passes and the receipt write is chained to it with &&; a finding the diff causes elsewhere names the changed line in `cause` and classify follows it. Review-loop budget wording (ideas from tstack's sol-loop and pstack's interrogate, rewritten; NOTICE.md): the blocker / should / nit glossary and two stop rules in Step 9.4, the checklist and docs/review-policy.md; a lead-judgment stage in the finding merge both /review and /ship render. The core read diffs $RANGE_BASE from pass 2 on. Caps and pins re-measured with reasons. Step 7 coverage audit: four tests added in existing files, the --review-loop case moved to its own test (the shared test tripped bun's 5 s default). Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
This commit is contained in:
1 parent
6f5782b5fd
commit
c3e27fc2b8
22 files changed
+807
-153
No files matched your search
+22
-10
@@ -26,6 +26,8 @@ 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;
|
||||
/** The changed line that causes a defect reported elsewhere (a broken caller, a consumer of a removed export); the locus follows it. */
|
||||
cause?: { path?: string; line?: number };
|
||||
[key: string]: unknown;
|
||||
}
|
||||
export interface ScopedFinding extends ScopeFinding { locus: Locus; kind: Kind; blocking: boolean; scope: ScopeAction }
|
||||
@@ -72,11 +74,17 @@ function inHunks(hunks: HunkMap, path: string, line: number | undefined, context
|
||||
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. */
|
||||
/**
|
||||
* Where a finding sits: in the range since the previous pass, in the branch
|
||||
* diff, or in code the PR did not change. A `cause` anchor wins over the
|
||||
* reported path, so a defect the diff causes in an unchanged caller is the
|
||||
* diff's.
|
||||
*/
|
||||
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);
|
||||
const anchor = finding.cause && typeof finding.cause === 'object' && typeof finding.cause.path === 'string' ? finding.cause : finding;
|
||||
const path = typeof anchor.path === 'string' ? anchor.path : fingerprintPath(finding.fingerprint);
|
||||
if (!path) return 'outside';
|
||||
const line = typeof finding.line === 'number' ? finding.line : fingerprintLine(finding.fingerprint);
|
||||
const line = typeof anchor.line === 'number' ? anchor.line : anchor === finding ? fingerprintLine(finding.fingerprint) : undefined;
|
||||
if (rangeHunks && inHunks(rangeHunks, path, line, context)) return 'fix-range';
|
||||
if (inHunks(diffHunks, path, line, context)) return 'diff';
|
||||
return 'outside';
|
||||
@@ -93,11 +101,13 @@ function fingerprintLine(fp: unknown): number | undefined {
|
||||
return Number.isInteger(n) && n > 0 ? n : undefined;
|
||||
}
|
||||
|
||||
/** A finding's kind: optional advice, a missing test, or a defect. */
|
||||
/** The categories a reviewer uses for a test finding; `testing` is what the Testing specialist's schema emits. */
|
||||
export const TEST_GAP_CATEGORIES: readonly string[] = ['testing', 'tests', 'test-gap', 'test-coverage', 'coverage', 'missing-test', 'untested'];
|
||||
|
||||
/** A finding's kind: optional advice, a test finding (a gap, a weak or flaky test), or a product 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';
|
||||
if (TEST_GAP_CATEGORIES.includes(String(finding.category ?? '').toLowerCase())) return 'test-gap';
|
||||
return 'defect';
|
||||
}
|
||||
|
||||
@@ -124,9 +134,11 @@ export function scopeFindings(findings: readonly ScopeFinding[], input: ScopeInp
|
||||
const kind = kindOf(finding);
|
||||
const blocking = isBlocking(finding, kind);
|
||||
const locus = locusOf(finding, input.diffHunks, input.pass > 1 ? input.rangeHunks : null, input.context);
|
||||
// A blocking finding nobody could place cannot be filed against a path; the diff's author resolves it now.
|
||||
const placed = typeof finding.path === 'string' || fingerprintPath(finding.fingerprint) !== undefined;
|
||||
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 (locus === 'outside') scope = !blocking ? 'note' : input.policy === 'diff-plus-blocking' || !placed ? 'fix' : 'defer';
|
||||
else if (input.pass <= 1) scope = 'fix';
|
||||
else scope = blocking ? 'fix' : 'note';
|
||||
return { ...finding, locus, kind, blocking, scope };
|
||||
@@ -187,11 +199,11 @@ export function renderDeferredIssue(f: ScopedFinding, ctx: DeferContext): { titl
|
||||
|
||||
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 {
|
||||
/** The PR-body section for deferred findings: references, never closing keywords, so a merge closes nothing. Only `frozen` defers. */
|
||||
export function renderDeferredSection(deferred: readonly DeferredRecord[], noted: readonly ScopeFinding[] = []): 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.`, '');
|
||||
out.push('## Deferred findings', '', 'Blocking findings in code this PR did not change (review scope: frozen); 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)}`);
|
||||
|
||||
+40
-17
@@ -10,6 +10,7 @@ import { ARTIFACT_SCHEMAS, checkSchema, type ShipReceipt, type ValidationError }
|
||||
import { approvalSummary } from './approval-citations';
|
||||
import { renderIssueLines } from './issue-links';
|
||||
import { matchesAny } from './ship-policy';
|
||||
import { stampFileKind, versionStampOnly } from './pregate/stamp-only';
|
||||
|
||||
export const RECEIPT_FENCE = 'gstack-ship-receipt';
|
||||
const KEY_ORDER: Array<keyof ShipReceipt> = [
|
||||
@@ -130,25 +131,25 @@ export function receiptSummaryLine(r: ShipReceipt): string {
|
||||
/**
|
||||
* Paths whose change never invalidates a /ship verdict on its own: tests (the
|
||||
* reviewed product code is what the verdict covers; CI at the new head reruns
|
||||
* them) and release metadata (stamps, lockfiles, the agents digest). A repo
|
||||
* extends the lists through its ship policy (`stamp_files`, `stamp_paths`,
|
||||
* `release_outputs`, `changelog`).
|
||||
* them, unreviewed) and release metadata (the version stamp, the changelog, the
|
||||
* agents digest). A repo extends the lists through its ship policy
|
||||
* (`stamp_files`, `stamp_paths`, `release_outputs`, `changelog`); lockfiles are
|
||||
* product unless the policy names them, because a dependency change is a
|
||||
* product change. The test globs name code extensions only: an API contract
|
||||
* such as `openapi.spec.yaml` is product.
|
||||
*/
|
||||
const TEST_CODE_EXTENSIONS = ['ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs', 'mts', 'cts', 'rb', 'py', 'go', 'rs', 'java', 'kt', 'swift', 'dart', 'php', 'cs'];
|
||||
export const CARRY_TEST_GLOBS: readonly string[] = [
|
||||
'test/**', 'tests/**', 'spec/**', '__tests__/**', 'e2e/**', 'cypress/**', '**/__tests__/**', '**/*.test.*', '**/*.spec.*',
|
||||
'test/**', 'tests/**', 'spec/**', '__tests__/**', 'e2e/**', 'cypress/**', '**/__tests__/**',
|
||||
...TEST_CODE_EXTENSIONS.flatMap(ext => [`**/*.test.${ext}`, `**/*.spec.${ext}`]),
|
||||
'**/*_test.go', '**/test_*.py', '**/*_test.py', '**/*_spec.rb', '**/*Test.java', '**/*Tests.swift',
|
||||
];
|
||||
export const CARRY_METADATA_GLOBS: readonly string[] = [
|
||||
'VERSION', 'CHANGELOG.md', 'package.json', 'package-lock.json', 'bun.lock', 'bun.lockb', 'yarn.lock', 'pnpm-lock.yaml',
|
||||
'Cargo.lock', 'Gemfile.lock', 'agents-digest/**',
|
||||
];
|
||||
export const CARRY_METADATA_GLOBS: readonly string[] = ['VERSION', 'CHANGELOG.md', 'package.json', 'agents-digest/**'];
|
||||
|
||||
export type CarryClass = 'product' | 'test' | 'metadata';
|
||||
export interface CarryPlanInput {
|
||||
/** The reviewed head the receipt names. */
|
||||
from: string; head: string;
|
||||
/** Merge base of origin/<base> with `from` and with `head`. */
|
||||
fromBase: string; headBase: string;
|
||||
/** Paths changed between from and head, classified. */
|
||||
changed: Array<{ path: string; class: CarryClass }>;
|
||||
/** Product patch-ids at both heads (empty string for no product diff). */
|
||||
@@ -162,9 +163,20 @@ export interface CarryPlanInput {
|
||||
export interface CarryRecord { from: string; reason: string; product_patch_id: string; changed_paths: string[]; merge_commits: number; range_diff: string; covers: string[]; reruns: string[] }
|
||||
export type CarryPlan = { ok: true; carry: CarryRecord } | { ok: false; code: 'RECEIPT_CARRY_PRODUCT_CHANGED' | 'RECEIPT_CARRY_REFUSED'; message: string };
|
||||
|
||||
export function classifyCarryPath(rel: string, extra: { tests?: readonly string[]; metadata?: readonly string[] } = {}): CarryClass {
|
||||
if (matchesAny([...CARRY_METADATA_GLOBS, ...(extra.metadata ?? [])], rel)) return 'metadata';
|
||||
if (matchesAny([...CARRY_TEST_GLOBS, ...(extra.tests ?? [])], rel)) return 'test';
|
||||
/**
|
||||
* One changed path's carry class. A default-metadata manifest (`package.json`,
|
||||
* `VERSION`) is metadata only while its from..head change is a version stamp
|
||||
* and nothing else (`versionStampOnly`): a dependency, a script or a new key is
|
||||
* product. `change` carries the file's text at both heads; without it the
|
||||
* default lists decide (the paths a policy names are the repo's own call).
|
||||
*/
|
||||
export function classifyCarryPath(rel: string, extra: { metadata?: readonly string[] } = {}, change?: { before: string | null; after: string | null }): CarryClass {
|
||||
if (matchesAny(extra.metadata ?? [], rel)) return 'metadata';
|
||||
if (matchesAny(CARRY_METADATA_GLOBS, rel)) {
|
||||
if (change && stampFileKind(rel) && !versionStampOnly(rel, change.before, change.after).stampOnly) return 'product';
|
||||
return 'metadata';
|
||||
}
|
||||
if (matchesAny(CARRY_TEST_GLOBS, rel)) return 'test';
|
||||
return 'product';
|
||||
}
|
||||
|
||||
@@ -190,18 +202,29 @@ export function planCarry(input: CarryPlanInput): CarryPlan {
|
||||
carry: {
|
||||
from: input.from, reason: reasons.join(' + '), product_patch_id: input.productPatchId.head || 'none',
|
||||
changed_paths: input.changed.slice(0, 50).map(c => `${c.class}:${c.path}`), merge_commits: input.mergeCommits, range_diff: input.rangeDiff,
|
||||
covers: ['pre-landing review', 'adversarial review', 'gate integrity', 'documentation audit'], reruns: ['CI at head (gstack-ship-queue ready requires it)'],
|
||||
covers: ['pre-landing review', 'adversarial review', 'gate integrity', 'documentation audit'],
|
||||
reruns: ['CI at head (gstack-ship-queue ready requires it); test and helper code changed since the reviewed head runs there unreviewed'],
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
/** The carried receipt: the same evidence, bound to the new head, with the carry recorded. */
|
||||
/**
|
||||
* The carried receipt: the same evidence, bound to the new head, with the carry
|
||||
* recorded. A receipt carried before keeps the reviewed head as `from` and adds
|
||||
* this hop's merges and paths, so the record always names the head a review saw.
|
||||
*/
|
||||
export function carryReceipt(receipt: ShipReceipt, head: string, carry: CarryRecord): ShipReceipt {
|
||||
return orderReceipt({ ...receipt, head, carry });
|
||||
const prior = receipt.carry;
|
||||
const merged: CarryRecord = !prior ? carry : {
|
||||
...carry, from: prior.from, reason: prior.reason === carry.reason ? carry.reason : `${prior.reason} + ${carry.reason}`,
|
||||
merge_commits: prior.merge_commits + carry.merge_commits,
|
||||
changed_paths: [...prior.changed_paths, ...carry.changed_paths.filter(p => !prior.changed_paths.includes(p))].slice(0, 50),
|
||||
};
|
||||
return orderReceipt({ ...receipt, head, carry: merged });
|
||||
}
|
||||
|
||||
/** The loop counters the factory scorecard reads (passes, blocking_found, deferred), as `write --review-loop` records them. */
|
||||
export interface ReviewLoopReceipt { passes: number; blocking_found: number; deferred: number; noted?: number; fixed?: number; scope?: string }
|
||||
export type ReviewLoopReceipt = NonNullable<ShipReceipt['review_loop']>;
|
||||
export function parseReviewLoop(value: unknown): ReviewLoopReceipt | undefined {
|
||||
if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
|
||||
const v = value as Record<string, unknown>;
|
||||
|
||||
Reference in new issue
Block a user