vouchington-tooling 0.85.1 → 0.85.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/cli/commands/final-review.d.mts +8 -0
- package/dist/cli/commands/final-review.mjs +70 -0
- package/dist/cli/index.mjs +2 -0
- package/dist/cli/parse-forwarded-commands.d.mts +1 -1
- package/dist/cli/parse-forwarded-commands.mjs +1 -0
- package/dist/cli/parse.d.mts +3 -0
- package/dist/cli/usage-text-final-review.d.mts +2 -0
- package/dist/cli/usage-text-final-review.mjs +22 -0
- package/dist/cli/usage-text-policy.d.mts +2 -2
- package/dist/cli/usage-text-policy.mjs +3 -2
- package/dist/cli/usage-text.d.mts +1 -1
- package/dist/final-review/benchmark/cases.d.mts +23 -0
- package/dist/final-review/benchmark/cases.mjs +89 -0
- package/dist/final-review/benchmark/cli.d.mts +12 -0
- package/dist/final-review/benchmark/cli.mjs +144 -0
- package/dist/final-review/benchmark/judge-all.d.mts +32 -0
- package/dist/final-review/benchmark/judge-all.mjs +50 -0
- package/dist/final-review/benchmark/judge.d.mts +18 -0
- package/dist/final-review/benchmark/judge.mjs +86 -0
- package/dist/final-review/benchmark/runner.d.mts +60 -0
- package/dist/final-review/benchmark/runner.mjs +85 -0
- package/dist/final-review/benchmark/score.d.mts +33 -0
- package/dist/final-review/benchmark/score.mjs +84 -0
- package/dist/final-review/benchmark/snapshot.d.mts +20 -0
- package/dist/final-review/benchmark/snapshot.mjs +107 -0
- package/dist/final-review/benchmark/verifier-check.d.mts +21 -0
- package/dist/final-review/benchmark/verifier-check.mjs +93 -0
- package/dist/final-review/benchmark/verifier-cli.d.mts +6 -0
- package/dist/final-review/benchmark/verifier-cli.mjs +141 -0
- package/dist/final-review/benchmark/verifier-grade.d.mts +42 -0
- package/dist/final-review/benchmark/verifier-grade.mjs +76 -0
- package/dist/final-review/benchmark/verifier-input.d.mts +21 -0
- package/dist/final-review/benchmark/verifier-input.mjs +47 -0
- package/dist/final-review/benchmark/verifier-run.d.mts +23 -0
- package/dist/final-review/benchmark/verifier-run.mjs +108 -0
- package/dist/final-review/benchmark/verifier-score.d.mts +39 -0
- package/dist/final-review/benchmark/verifier-score.mjs +70 -0
- package/dist/final-review/build.d.mts +21 -0
- package/dist/final-review/build.mjs +91 -0
- package/dist/final-review/diff-files.d.mts +16 -0
- package/dist/final-review/diff-files.mjs +44 -0
- package/dist/final-review/finding.d.mts +32 -0
- package/dist/final-review/finding.mjs +101 -0
- package/dist/final-review/github.d.mts +21 -0
- package/dist/final-review/github.mjs +105 -0
- package/dist/final-review/index.d.mts +11 -0
- package/dist/final-review/index.mjs +6 -0
- package/dist/final-review/numbered-diff.d.mts +9 -0
- package/dist/final-review/numbered-diff.mjs +52 -0
- package/dist/final-review/post.d.mts +33 -0
- package/dist/final-review/post.mjs +63 -0
- package/dist/final-review/render.d.mts +17 -0
- package/dist/final-review/render.mjs +81 -0
- package/dist/gh-cli/exec.mjs +3 -1
- package/dist/gha-review-payload/index.d.mts +1 -1
- package/dist/gha-review-payload/index.mjs +1 -1
- package/dist/gha-review-payload/remap.d.mts +3 -1
- package/dist/gha-review-payload/remap.mjs +3 -2
- package/package.json +4 -4
- package/scripts/__pycache__/run_bounded_process.cpython-314.pyc +0 -0
- package/skills/bounded-iteration/SKILL.md +29 -14
- package/skills/final-review/SKILL.md +95 -0
- package/skills/final-review/references/dispatch.md +40 -0
- package/skills/final-review/references/orchestrator.md +39 -0
- package/skills/final-review/references/pillars/_contract.md +61 -0
- package/skills/final-review/references/pillars/blast-radius.md +33 -0
- package/skills/final-review/references/pillars/congruence.md +25 -0
- package/skills/final-review/references/pillars/correctness.md +52 -0
- package/skills/final-review/references/pillars/design.md +30 -0
- package/skills/final-review/references/pillars/history.md +26 -0
- package/skills/final-review/references/pillars/rules.md +34 -0
- package/skills/final-review/references/pillars/security.md +28 -0
- package/skills/final-review/references/verifier.md +62 -0
- package/skills/manifest.json +34 -28
- package/skills/postgres-node-performance-tuning/references/performance-patterns.md +5 -1
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
import { GITHUB_BODY_MAX_CHARACTERS } from "../gh-cli/body-length.mjs";
|
|
2
|
+
import { placeReviewComment, } from "../gha-review-payload/index.mjs";
|
|
3
|
+
import { renderBodyFinding, renderFindingBody, renderHeader, sortFindings } from "./render.mjs";
|
|
4
|
+
export const DEFAULT_LIMITS = {
|
|
5
|
+
maxComments: 50,
|
|
6
|
+
maxBodyChars: GITHUB_BODY_MAX_CHARACTERS - 1_536,
|
|
7
|
+
};
|
|
8
|
+
const TRUNCATED = '\n\n_(truncated to fit GitHub limits)_';
|
|
9
|
+
const OFF_DIFF_HEADING = '### Not on a diff line';
|
|
10
|
+
function toComment(finding) {
|
|
11
|
+
if (finding.path === undefined || finding.line === undefined)
|
|
12
|
+
return null;
|
|
13
|
+
const side = finding.side ?? 'RIGHT';
|
|
14
|
+
const comment = {
|
|
15
|
+
path: finding.path,
|
|
16
|
+
line: finding.line,
|
|
17
|
+
side,
|
|
18
|
+
body: renderFindingBody(finding),
|
|
19
|
+
};
|
|
20
|
+
if (finding.startLine === undefined)
|
|
21
|
+
return comment;
|
|
22
|
+
return { ...comment, start_line: finding.startLine, start_side: side };
|
|
23
|
+
}
|
|
24
|
+
/** Splits findings into placed inline comments and blocks for the review body. */
|
|
25
|
+
export function placeFindings(findings, index) {
|
|
26
|
+
const comments = [];
|
|
27
|
+
const offDiff = [];
|
|
28
|
+
for (const finding of sortFindings(findings)) {
|
|
29
|
+
const comment = toComment(finding);
|
|
30
|
+
const placed = comment === null ? null : placeReviewComment(comment, index);
|
|
31
|
+
if (placed === null)
|
|
32
|
+
offDiff.push(finding);
|
|
33
|
+
else
|
|
34
|
+
comments.push(placed);
|
|
35
|
+
}
|
|
36
|
+
return { comments, offDiff };
|
|
37
|
+
}
|
|
38
|
+
function fit(block, max) {
|
|
39
|
+
if (block.length <= max)
|
|
40
|
+
return block;
|
|
41
|
+
return `${block.slice(0, Math.max(0, max - TRUNCATED.length))}${TRUNCATED}`;
|
|
42
|
+
}
|
|
43
|
+
/** Greedily packs blocks into bodies; the first body starts with `first`. */
|
|
44
|
+
export function packBodies(first, blocks, max) {
|
|
45
|
+
const bodies = [fit(first, max)];
|
|
46
|
+
for (const raw of blocks) {
|
|
47
|
+
const block = fit(raw, max);
|
|
48
|
+
const last = bodies.length - 1;
|
|
49
|
+
const joined = `${bodies[last]}\n\n${block}`;
|
|
50
|
+
if (joined.length <= max)
|
|
51
|
+
bodies[last] = joined;
|
|
52
|
+
else
|
|
53
|
+
bodies.push(block);
|
|
54
|
+
}
|
|
55
|
+
return bodies;
|
|
56
|
+
}
|
|
57
|
+
function chunk(items, size) {
|
|
58
|
+
const chunks = [];
|
|
59
|
+
for (let start = 0; start < items.length; start += size) {
|
|
60
|
+
chunks.push(items.slice(start, start + size));
|
|
61
|
+
}
|
|
62
|
+
return chunks;
|
|
63
|
+
}
|
|
64
|
+
function partHeader(headSha, part, total) {
|
|
65
|
+
return `<!-- final-review-part sha=${headSha} part=${part} -->\n**Final review, part ${part} of ${total}** · \`${headSha.slice(0, 12)}\``;
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* Builds one or more COMMENT reviews for GitHub. Placeable findings become inline comments, the
|
|
69
|
+
* rest go in the body, and anything over the limits continues in additional review parts.
|
|
70
|
+
*/
|
|
71
|
+
export function buildFinalReviews(input, headSha, index, limits = DEFAULT_LIMITS) {
|
|
72
|
+
const { comments, offDiff } = placeFindings(input.findings, index);
|
|
73
|
+
const header = renderHeader(input, headSha);
|
|
74
|
+
const blocks = offDiff.length === 0 ? [] : [OFF_DIFF_HEADING, ...offDiff.map(renderBodyFinding)];
|
|
75
|
+
const bodyMax = limits.maxBodyChars - 200;
|
|
76
|
+
const bodies = packBodies(header, blocks, bodyMax);
|
|
77
|
+
const commentChunks = chunk(comments, limits.maxComments);
|
|
78
|
+
const total = Math.max(bodies.length, commentChunks.length);
|
|
79
|
+
const reviews = [];
|
|
80
|
+
for (let part = 0; part < total; part += 1) {
|
|
81
|
+
const body = bodies[part];
|
|
82
|
+
const prefix = part === 0 ? '' : `${partHeader(headSha, part + 1, total)}\n\n`;
|
|
83
|
+
reviews.push({
|
|
84
|
+
event: 'COMMENT',
|
|
85
|
+
commit_id: headSha,
|
|
86
|
+
body: `${prefix}${body ?? 'Inline findings continued.'}`,
|
|
87
|
+
comments: commentChunks[part] ?? [],
|
|
88
|
+
});
|
|
89
|
+
}
|
|
90
|
+
return reviews;
|
|
91
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/** One file's section of a (numbered) unified diff. */
|
|
2
|
+
export type DiffFile = {
|
|
3
|
+
path: string;
|
|
4
|
+
text: string;
|
|
5
|
+
added: number;
|
|
6
|
+
removed: number;
|
|
7
|
+
};
|
|
8
|
+
/**
|
|
9
|
+
* Splits a unified diff (plain or numbered) into per-file sections, so a reviewer of a large pull
|
|
10
|
+
* request can read one file's changes at a time. Text before the first file header is dropped.
|
|
11
|
+
*/
|
|
12
|
+
export declare function splitDiff(patch: string): DiffFile[];
|
|
13
|
+
/** Patch file name for the file at `index`; names never derive from pull request paths. */
|
|
14
|
+
export declare function diffFileName(index: number): string;
|
|
15
|
+
/** A markdown index of the per-file patches, largest change first. */
|
|
16
|
+
export declare function renderDiffIndex(files: readonly DiffFile[], dir: string): string;
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
// Git quotes a path holding a tab, quote, or non-ASCII byte; the index shows it as Git printed it.
|
|
2
|
+
const HEADER = /^diff --git (?:"a\/.*"|a\/.*) (?:"b\/(.*)"|b\/(.*))$/u;
|
|
3
|
+
/**
|
|
4
|
+
* Splits a unified diff (plain or numbered) into per-file sections, so a reviewer of a large pull
|
|
5
|
+
* request can read one file's changes at a time. Text before the first file header is dropped.
|
|
6
|
+
*/
|
|
7
|
+
export function splitDiff(patch) {
|
|
8
|
+
const files = [];
|
|
9
|
+
let current;
|
|
10
|
+
const flush = () => {
|
|
11
|
+
if (current === undefined)
|
|
12
|
+
return;
|
|
13
|
+
const hunks = current.lines.filter((line) => !line.startsWith('+++') && !line.startsWith('---'));
|
|
14
|
+
files.push({
|
|
15
|
+
path: current.path,
|
|
16
|
+
text: `${current.lines.join('\n')}\n`,
|
|
17
|
+
// Numbered lines put the marker after the two number columns; plain lines start with it.
|
|
18
|
+
added: hunks.filter((line) => /^(?:[ \d]{14})?\+/u.test(line)).length,
|
|
19
|
+
removed: hunks.filter((line) => /^(?:[ \d]{14})?-/u.test(line)).length,
|
|
20
|
+
});
|
|
21
|
+
};
|
|
22
|
+
for (const line of patch.split('\n')) {
|
|
23
|
+
const header = HEADER.exec(line);
|
|
24
|
+
if (header !== null) {
|
|
25
|
+
flush();
|
|
26
|
+
current = { path: (header[1] ?? header[2]), lines: [] };
|
|
27
|
+
}
|
|
28
|
+
current?.lines.push(line);
|
|
29
|
+
}
|
|
30
|
+
flush();
|
|
31
|
+
return files;
|
|
32
|
+
}
|
|
33
|
+
/** Patch file name for the file at `index`; names never derive from pull request paths. */
|
|
34
|
+
export function diffFileName(index) {
|
|
35
|
+
return `${String(index + 1).padStart(4, '0')}.patch`;
|
|
36
|
+
}
|
|
37
|
+
/** A markdown index of the per-file patches, largest change first. */
|
|
38
|
+
export function renderDiffIndex(files, dir) {
|
|
39
|
+
const rows = files
|
|
40
|
+
.map((file, index) => ({ file, name: diffFileName(index) }))
|
|
41
|
+
.sort((a, b) => b.file.added + b.file.removed - (a.file.added + a.file.removed))
|
|
42
|
+
.map(({ file, name }) => `- \`${dir}/${name}\` +${file.added} -${file.removed} ${file.path}`);
|
|
43
|
+
return [`# Changed files (${files.length})`, '', ...rows, ''].join('\n');
|
|
44
|
+
}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import type { ReviewSide } from '../gha-review-payload/index.mts';
|
|
2
|
+
export declare const PILLARS: readonly ["rules", "correctness", "design", "blast-radius", "security", "history", "congruence"];
|
|
3
|
+
export type Pillar = (typeof PILLARS)[number];
|
|
4
|
+
export declare const SEVERITIES: readonly ["blocking", "high", "medium", "low"];
|
|
5
|
+
export type Severity = (typeof SEVERITIES)[number];
|
|
6
|
+
export declare const EFFORTS: readonly ["low", "medium", "high"];
|
|
7
|
+
export type Effort = (typeof EFFORTS)[number];
|
|
8
|
+
export type Finding = {
|
|
9
|
+
pillar: Pillar;
|
|
10
|
+
severity: Severity;
|
|
11
|
+
title: string;
|
|
12
|
+
body: string;
|
|
13
|
+
path?: string;
|
|
14
|
+
line?: number;
|
|
15
|
+
side?: ReviewSide;
|
|
16
|
+
startLine?: number;
|
|
17
|
+
};
|
|
18
|
+
export type SkippedPillar = {
|
|
19
|
+
pillar: Pillar;
|
|
20
|
+
reason: string;
|
|
21
|
+
};
|
|
22
|
+
export type FinalReviewInput = {
|
|
23
|
+
effort: Effort;
|
|
24
|
+
summary: string;
|
|
25
|
+
skipped: SkippedPillar[];
|
|
26
|
+
findings: Finding[];
|
|
27
|
+
};
|
|
28
|
+
export declare class FinalReviewError extends Error {
|
|
29
|
+
constructor(message: string);
|
|
30
|
+
}
|
|
31
|
+
/** Validates the verifier's collected findings; malformed input fails closed. */
|
|
32
|
+
export declare function parseFinalReviewInput(raw: unknown): FinalReviewInput;
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
export const PILLARS = [
|
|
2
|
+
'rules',
|
|
3
|
+
'correctness',
|
|
4
|
+
'design',
|
|
5
|
+
'blast-radius',
|
|
6
|
+
'security',
|
|
7
|
+
'history',
|
|
8
|
+
'congruence',
|
|
9
|
+
];
|
|
10
|
+
export const SEVERITIES = ['blocking', 'high', 'medium', 'low'];
|
|
11
|
+
export const EFFORTS = ['low', 'medium', 'high'];
|
|
12
|
+
export class FinalReviewError extends Error {
|
|
13
|
+
constructor(message) {
|
|
14
|
+
super(message);
|
|
15
|
+
this.name = 'FinalReviewError';
|
|
16
|
+
}
|
|
17
|
+
}
|
|
18
|
+
function isRecord(value) {
|
|
19
|
+
return value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
20
|
+
}
|
|
21
|
+
function oneOf(values, value, field) {
|
|
22
|
+
const found = values.find((candidate) => candidate === value);
|
|
23
|
+
if (found === undefined) {
|
|
24
|
+
throw new FinalReviewError(`${field} must be one of ${values.join(', ')}.`);
|
|
25
|
+
}
|
|
26
|
+
return found;
|
|
27
|
+
}
|
|
28
|
+
function text(record, field, where) {
|
|
29
|
+
const value = record[field];
|
|
30
|
+
if (typeof value !== 'string' || value.trim().length === 0) {
|
|
31
|
+
throw new FinalReviewError(`${where}.${field} must be a non-empty string.`);
|
|
32
|
+
}
|
|
33
|
+
return value;
|
|
34
|
+
}
|
|
35
|
+
function positiveInt(value, field) {
|
|
36
|
+
if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0) {
|
|
37
|
+
throw new FinalReviewError(`${field} must be a positive integer.`);
|
|
38
|
+
}
|
|
39
|
+
return value;
|
|
40
|
+
}
|
|
41
|
+
function parseLocation(record, where) {
|
|
42
|
+
if (record.path === undefined) {
|
|
43
|
+
if (record.line !== undefined)
|
|
44
|
+
throw new FinalReviewError(`${where}.line needs a path.`);
|
|
45
|
+
return {};
|
|
46
|
+
}
|
|
47
|
+
const path = text(record, 'path', where);
|
|
48
|
+
if (path.includes('\0'))
|
|
49
|
+
throw new FinalReviewError(`${where}.path is invalid.`);
|
|
50
|
+
if (record.line === undefined)
|
|
51
|
+
return { path };
|
|
52
|
+
const line = positiveInt(record.line, `${where}.line`);
|
|
53
|
+
const side = record.side === undefined ? 'RIGHT' : oneOf(['LEFT', 'RIGHT'], record.side, `${where}.side`);
|
|
54
|
+
if (record.startLine === undefined)
|
|
55
|
+
return { path, line, side };
|
|
56
|
+
const startLine = positiveInt(record.startLine, `${where}.startLine`);
|
|
57
|
+
// Models often send a one-line range or reversed bounds; normalize instead of rejecting.
|
|
58
|
+
if (startLine === line)
|
|
59
|
+
return { path, line, side };
|
|
60
|
+
if (startLine > line)
|
|
61
|
+
return { path, line: startLine, side, startLine: line };
|
|
62
|
+
return { path, line, side, startLine };
|
|
63
|
+
}
|
|
64
|
+
function parseFinding(raw, index) {
|
|
65
|
+
const where = `findings[${index}]`;
|
|
66
|
+
if (!isRecord(raw))
|
|
67
|
+
throw new FinalReviewError(`${where} must be an object.`);
|
|
68
|
+
return {
|
|
69
|
+
pillar: oneOf(PILLARS, raw.pillar, `${where}.pillar`),
|
|
70
|
+
severity: oneOf(SEVERITIES, raw.severity, `${where}.severity`),
|
|
71
|
+
title: text(raw, 'title', where).trim(),
|
|
72
|
+
body: text(raw, 'body', where).trim(),
|
|
73
|
+
...parseLocation(raw, where),
|
|
74
|
+
};
|
|
75
|
+
}
|
|
76
|
+
function parseSkipped(raw, index) {
|
|
77
|
+
const where = `skipped[${index}]`;
|
|
78
|
+
if (!isRecord(raw))
|
|
79
|
+
throw new FinalReviewError(`${where} must be an object.`);
|
|
80
|
+
return {
|
|
81
|
+
pillar: oneOf(PILLARS, raw.pillar, `${where}.pillar`),
|
|
82
|
+
reason: text(raw, 'reason', where),
|
|
83
|
+
};
|
|
84
|
+
}
|
|
85
|
+
function list(record, field) {
|
|
86
|
+
const value = record[field] ?? [];
|
|
87
|
+
if (!Array.isArray(value))
|
|
88
|
+
throw new FinalReviewError(`${field} must be an array.`);
|
|
89
|
+
return value;
|
|
90
|
+
}
|
|
91
|
+
/** Validates the verifier's collected findings; malformed input fails closed. */
|
|
92
|
+
export function parseFinalReviewInput(raw) {
|
|
93
|
+
if (!isRecord(raw))
|
|
94
|
+
throw new FinalReviewError('Input must be a JSON object.');
|
|
95
|
+
return {
|
|
96
|
+
effort: raw.effort === undefined ? 'high' : oneOf(EFFORTS, raw.effort, 'effort'),
|
|
97
|
+
summary: typeof raw.summary === 'string' ? raw.summary.trim() : '',
|
|
98
|
+
skipped: list(raw, 'skipped').map(parseSkipped),
|
|
99
|
+
findings: list(raw, 'findings').map(parseFinding),
|
|
100
|
+
};
|
|
101
|
+
}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import { type RunTextCommand } from '../gh-cli/index.mts';
|
|
2
|
+
import { type ReviewFile, type SanitizedReview } from '../gha-review-payload/index.mts';
|
|
3
|
+
/** The GitHub reads and writes a final review needs, injectable for tests. */
|
|
4
|
+
export type FinalReviewIo = {
|
|
5
|
+
headSha(): Promise<string>;
|
|
6
|
+
/** The pull request's unified diff against its base. */
|
|
7
|
+
diff(): Promise<string>;
|
|
8
|
+
listFiles(): Promise<ReviewFile[]>;
|
|
9
|
+
listReviewBodies(): Promise<string[]>;
|
|
10
|
+
hasApprovalLabel(): Promise<boolean>;
|
|
11
|
+
postReview(review: SanitizedReview): Promise<string>;
|
|
12
|
+
addApprovalLabel(): Promise<void>;
|
|
13
|
+
removeApprovalLabel(): Promise<void>;
|
|
14
|
+
};
|
|
15
|
+
export type PullTarget = {
|
|
16
|
+
repo: string;
|
|
17
|
+
pr: number;
|
|
18
|
+
};
|
|
19
|
+
export declare function assertPullTarget(target: PullTarget): void;
|
|
20
|
+
/** Builds `FinalReviewIo` on top of the authenticated `gh` CLI. */
|
|
21
|
+
export declare function createGhFinalReviewIo(target: PullTarget, run?: RunTextCommand): FinalReviewIo;
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
|
|
2
|
+
import { tmpdir } from 'node:os';
|
|
3
|
+
import { join } from 'node:path';
|
|
4
|
+
import { runGh } from "../gh-cli/index.mjs";
|
|
5
|
+
import { parseReviewFilesJson, } from "../gha-review-payload/index.mjs";
|
|
6
|
+
import { FINAL_APPROVAL_LABEL } from "./render.mjs";
|
|
7
|
+
const REPO_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/u;
|
|
8
|
+
export function assertPullTarget(target) {
|
|
9
|
+
if (!REPO_RE.test(target.repo))
|
|
10
|
+
throw new Error('--repo must be owner/name.');
|
|
11
|
+
if (!Number.isInteger(target.pr) || target.pr <= 0)
|
|
12
|
+
throw new Error('--pr must be a positive integer.');
|
|
13
|
+
}
|
|
14
|
+
function lines(text) {
|
|
15
|
+
return text
|
|
16
|
+
.split('\n')
|
|
17
|
+
.map((line) => line.trim())
|
|
18
|
+
.filter((line) => line.length > 0);
|
|
19
|
+
}
|
|
20
|
+
/** Builds `FinalReviewIo` on top of the authenticated `gh` CLI. */
|
|
21
|
+
export function createGhFinalReviewIo(target, run = runGh) {
|
|
22
|
+
assertPullTarget(target);
|
|
23
|
+
const { repo, pr } = target;
|
|
24
|
+
const pull = `repos/${repo}/pulls/${pr}`;
|
|
25
|
+
return {
|
|
26
|
+
async headSha() {
|
|
27
|
+
return (await run([
|
|
28
|
+
'pr',
|
|
29
|
+
'view',
|
|
30
|
+
String(pr),
|
|
31
|
+
'-R',
|
|
32
|
+
repo,
|
|
33
|
+
'--json',
|
|
34
|
+
'headRefOid',
|
|
35
|
+
'-q',
|
|
36
|
+
'.headRefOid',
|
|
37
|
+
])).trim();
|
|
38
|
+
},
|
|
39
|
+
async diff() {
|
|
40
|
+
return run(['pr', 'diff', String(pr), '-R', repo, '--color', 'never']);
|
|
41
|
+
},
|
|
42
|
+
async listFiles() {
|
|
43
|
+
return parseReviewFilesJson(await run(['api', '--paginate', `${pull}/files?per_page=100`]));
|
|
44
|
+
},
|
|
45
|
+
async listReviewBodies() {
|
|
46
|
+
const out = await run([
|
|
47
|
+
'api',
|
|
48
|
+
'--paginate',
|
|
49
|
+
`${pull}/reviews?per_page=100`,
|
|
50
|
+
'-q',
|
|
51
|
+
'.[].body | @json',
|
|
52
|
+
]);
|
|
53
|
+
return lines(out).map((line) => JSON.parse(line));
|
|
54
|
+
},
|
|
55
|
+
async hasApprovalLabel() {
|
|
56
|
+
const out = await run([
|
|
57
|
+
'pr',
|
|
58
|
+
'view',
|
|
59
|
+
String(pr),
|
|
60
|
+
'-R',
|
|
61
|
+
repo,
|
|
62
|
+
'--json',
|
|
63
|
+
'labels',
|
|
64
|
+
'-q',
|
|
65
|
+
'.labels[].name',
|
|
66
|
+
]);
|
|
67
|
+
return lines(out).includes(FINAL_APPROVAL_LABEL);
|
|
68
|
+
},
|
|
69
|
+
async postReview(review) {
|
|
70
|
+
const dir = mkdtempSync(join(tmpdir(), 'final-review-'));
|
|
71
|
+
try {
|
|
72
|
+
const file = join(dir, 'review.json');
|
|
73
|
+
writeFileSync(file, JSON.stringify(review));
|
|
74
|
+
const out = await run([
|
|
75
|
+
'api',
|
|
76
|
+
'--method',
|
|
77
|
+
'POST',
|
|
78
|
+
`${pull}/reviews`,
|
|
79
|
+
'--input',
|
|
80
|
+
file,
|
|
81
|
+
'-q',
|
|
82
|
+
'.html_url',
|
|
83
|
+
]);
|
|
84
|
+
return out.trim();
|
|
85
|
+
}
|
|
86
|
+
finally {
|
|
87
|
+
rmSync(dir, { recursive: true, force: true });
|
|
88
|
+
}
|
|
89
|
+
},
|
|
90
|
+
async addApprovalLabel() {
|
|
91
|
+
// The issues labels endpoint creates a missing label, so no separate setup step is needed.
|
|
92
|
+
await run([
|
|
93
|
+
'api',
|
|
94
|
+
'--method',
|
|
95
|
+
'POST',
|
|
96
|
+
`repos/${repo}/issues/${pr}/labels`,
|
|
97
|
+
'-f',
|
|
98
|
+
`labels[]=${FINAL_APPROVAL_LABEL}`,
|
|
99
|
+
]);
|
|
100
|
+
},
|
|
101
|
+
async removeApprovalLabel() {
|
|
102
|
+
await run(['pr', 'edit', String(pr), '-R', repo, '--remove-label', FINAL_APPROVAL_LABEL]);
|
|
103
|
+
},
|
|
104
|
+
};
|
|
105
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
export { EFFORTS, FinalReviewError, PILLARS, SEVERITIES, parseFinalReviewInput, } from './finding.mts';
|
|
2
|
+
export type { Effort, FinalReviewInput, Finding, Pillar, Severity, SkippedPillar, } from './finding.mts';
|
|
3
|
+
export { FINAL_APPROVAL_LABEL, deriveVerdict, renderBodyFinding, renderFindingBody, renderHeader, reviewMarker, } from './render.mts';
|
|
4
|
+
export type { Verdict } from './render.mts';
|
|
5
|
+
export { DEFAULT_LIMITS, buildFinalReviews, packBodies, placeFindings } from './build.mts';
|
|
6
|
+
export type { BuildLimits } from './build.mts';
|
|
7
|
+
export { assertPullTarget, createGhFinalReviewIo } from './github.mts';
|
|
8
|
+
export type { FinalReviewIo, PullTarget } from './github.mts';
|
|
9
|
+
export { finalReviewStatus, postFinalReview, revokeFinalApproval } from './post.mts';
|
|
10
|
+
export type { PostOutcome, ReviewStatus } from './post.mts';
|
|
11
|
+
export { NUMBERED_DIFF_LEGEND, numberDiff } from './numbered-diff.mts';
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
export { EFFORTS, FinalReviewError, PILLARS, SEVERITIES, parseFinalReviewInput, } from "./finding.mjs";
|
|
2
|
+
export { FINAL_APPROVAL_LABEL, deriveVerdict, renderBodyFinding, renderFindingBody, renderHeader, reviewMarker, } from "./render.mjs";
|
|
3
|
+
export { DEFAULT_LIMITS, buildFinalReviews, packBodies, placeFindings } from "./build.mjs";
|
|
4
|
+
export { assertPullTarget, createGhFinalReviewIo } from "./github.mjs";
|
|
5
|
+
export { finalReviewStatus, postFinalReview, revokeFinalApproval } from "./post.mjs";
|
|
6
|
+
export { NUMBERED_DIFF_LEGEND, numberDiff } from "./numbered-diff.mjs";
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Prefixes every diff body line with its LEFT (base) and RIGHT (head) file line numbers, so a
|
|
3
|
+
* reviewer cites real file lines instead of counting from hunk headers or diff.patch offsets.
|
|
4
|
+
* Hunk lengths bound each hunk, so an empty context line (`diff.suppressBlankEmpty`) still
|
|
5
|
+
* advances both counters. Headers and lines outside hunks pass through unchanged.
|
|
6
|
+
*/
|
|
7
|
+
export declare function numberDiff(patch: string): string;
|
|
8
|
+
/** Explains the numbered diff format to a reviewer. */
|
|
9
|
+
export declare const NUMBERED_DIFF_LEGEND: string;
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
const HUNK = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/u;
|
|
2
|
+
function pad(value) {
|
|
3
|
+
return (value === null ? '' : String(value)).padStart(6);
|
|
4
|
+
}
|
|
5
|
+
/**
|
|
6
|
+
* Prefixes every diff body line with its LEFT (base) and RIGHT (head) file line numbers, so a
|
|
7
|
+
* reviewer cites real file lines instead of counting from hunk headers or diff.patch offsets.
|
|
8
|
+
* Hunk lengths bound each hunk, so an empty context line (`diff.suppressBlankEmpty`) still
|
|
9
|
+
* advances both counters. Headers and lines outside hunks pass through unchanged.
|
|
10
|
+
*/
|
|
11
|
+
export function numberDiff(patch) {
|
|
12
|
+
let left = 0;
|
|
13
|
+
let right = 0;
|
|
14
|
+
let oldLeft = 0;
|
|
15
|
+
let newLeft = 0;
|
|
16
|
+
return patch
|
|
17
|
+
.split('\n')
|
|
18
|
+
.map((line) => {
|
|
19
|
+
const hunk = HUNK.exec(line);
|
|
20
|
+
if (hunk !== null) {
|
|
21
|
+
left = Number(hunk[1]);
|
|
22
|
+
oldLeft = Number(hunk[2] ?? '1');
|
|
23
|
+
right = Number(hunk[3]);
|
|
24
|
+
newLeft = Number(hunk[4] ?? '1');
|
|
25
|
+
return line;
|
|
26
|
+
}
|
|
27
|
+
if (line.startsWith('diff --git ')) {
|
|
28
|
+
oldLeft = 0;
|
|
29
|
+
newLeft = 0;
|
|
30
|
+
}
|
|
31
|
+
if (oldLeft <= 0 && newLeft <= 0)
|
|
32
|
+
return line;
|
|
33
|
+
if (line.startsWith('+')) {
|
|
34
|
+
newLeft -= 1;
|
|
35
|
+
return `${pad(null)} ${pad(right++)} ${line}`;
|
|
36
|
+
}
|
|
37
|
+
if (line.startsWith('-')) {
|
|
38
|
+
oldLeft -= 1;
|
|
39
|
+
return `${pad(left++)} ${pad(null)} ${line}`;
|
|
40
|
+
}
|
|
41
|
+
if (line.startsWith(' ') || line === '') {
|
|
42
|
+
oldLeft -= 1;
|
|
43
|
+
newLeft -= 1;
|
|
44
|
+
return `${pad(left++)} ${pad(right++)} ${line}`;
|
|
45
|
+
}
|
|
46
|
+
return line;
|
|
47
|
+
})
|
|
48
|
+
.join('\n');
|
|
49
|
+
}
|
|
50
|
+
/** Explains the numbered diff format to a reviewer. */
|
|
51
|
+
export const NUMBERED_DIFF_LEGEND = 'Each diff line starts with two columns: the base (LEFT) line number and the head (RIGHT) line ' +
|
|
52
|
+
'number. Cite those numbers. Never cite a line number of the diff file itself.';
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import { type SanitizedReview } from '../gha-review-payload/index.mts';
|
|
2
|
+
import { type BuildLimits } from './build.mts';
|
|
3
|
+
import { type FinalReviewInput } from './finding.mts';
|
|
4
|
+
import type { FinalReviewIo } from './github.mts';
|
|
5
|
+
import { type Verdict } from './render.mts';
|
|
6
|
+
export type PostOutcome = {
|
|
7
|
+
verdict: Verdict;
|
|
8
|
+
reviews: SanitizedReview[];
|
|
9
|
+
urls: string[];
|
|
10
|
+
label: 'added' | 'removed' | 'unchanged';
|
|
11
|
+
};
|
|
12
|
+
/** Removes a stale `final approval` label; run before every re-review. */
|
|
13
|
+
export declare function revokeFinalApproval(io: FinalReviewIo): Promise<boolean>;
|
|
14
|
+
/**
|
|
15
|
+
* Renders the reviews for `headSha` and, unless `dryRun`, posts them and sets the label. Refuses
|
|
16
|
+
* when the pull request head moved, because the findings describe an older commit.
|
|
17
|
+
*/
|
|
18
|
+
export declare function postFinalReview(io: FinalReviewIo, input: FinalReviewInput, headSha: string, options?: {
|
|
19
|
+
dryRun?: boolean;
|
|
20
|
+
limits?: BuildLimits;
|
|
21
|
+
}): Promise<PostOutcome>;
|
|
22
|
+
export type ReviewStatus = {
|
|
23
|
+
headSha: string;
|
|
24
|
+
reviewedSha: string | null;
|
|
25
|
+
verdict: string | null;
|
|
26
|
+
effort: string | null;
|
|
27
|
+
current: boolean;
|
|
28
|
+
labeled: boolean;
|
|
29
|
+
/** True only when the newest final review approved the current head and the label is on. */
|
|
30
|
+
approved: boolean;
|
|
31
|
+
};
|
|
32
|
+
/** Reports whether the latest final review covers the current head, for merging agents. */
|
|
33
|
+
export declare function finalReviewStatus(io: FinalReviewIo): Promise<ReviewStatus>;
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
import { indexReviewFiles } from "../gha-review-payload/index.mjs";
|
|
2
|
+
import { buildFinalReviews, DEFAULT_LIMITS } from "./build.mjs";
|
|
3
|
+
import { FinalReviewError } from "./finding.mjs";
|
|
4
|
+
import { deriveVerdict } from "./render.mjs";
|
|
5
|
+
const SHA_RE = /^[0-9a-f]{40}$/u;
|
|
6
|
+
/** Removes a stale `final approval` label; run before every re-review. */
|
|
7
|
+
export async function revokeFinalApproval(io) {
|
|
8
|
+
if (!(await io.hasApprovalLabel()))
|
|
9
|
+
return false;
|
|
10
|
+
await io.removeApprovalLabel();
|
|
11
|
+
return true;
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Renders the reviews for `headSha` and, unless `dryRun`, posts them and sets the label. Refuses
|
|
15
|
+
* when the pull request head moved, because the findings describe an older commit.
|
|
16
|
+
*/
|
|
17
|
+
export async function postFinalReview(io, input, headSha, options = {}) {
|
|
18
|
+
if (!SHA_RE.test(headSha))
|
|
19
|
+
throw new FinalReviewError('--head-sha must be a full lowercase SHA.');
|
|
20
|
+
const current = await io.headSha();
|
|
21
|
+
if (current !== headSha) {
|
|
22
|
+
throw new FinalReviewError(`Pull request head is ${current}, not the reviewed ${headSha}; re-review the new head.`);
|
|
23
|
+
}
|
|
24
|
+
const index = indexReviewFiles(await io.listFiles());
|
|
25
|
+
const reviews = buildFinalReviews(input, headSha, index, options.limits ?? DEFAULT_LIMITS);
|
|
26
|
+
const verdict = deriveVerdict(input.findings);
|
|
27
|
+
if (options.dryRun === true)
|
|
28
|
+
return { verdict, reviews, urls: [], label: 'unchanged' };
|
|
29
|
+
const urls = [];
|
|
30
|
+
for (const review of reviews)
|
|
31
|
+
urls.push(await io.postReview(review));
|
|
32
|
+
if (verdict === 'Approve') {
|
|
33
|
+
await io.addApprovalLabel();
|
|
34
|
+
return { verdict, reviews, urls, label: 'added' };
|
|
35
|
+
}
|
|
36
|
+
const removed = await revokeFinalApproval(io);
|
|
37
|
+
return { verdict, reviews, urls, label: removed ? 'removed' : 'unchanged' };
|
|
38
|
+
}
|
|
39
|
+
const MARKER_RE = /<!-- final-review sha=([0-9a-f]{40}) verdict=([A-Za-z-]+) effort=([a-z]+) -->/u;
|
|
40
|
+
/** Reports whether the latest final review covers the current head, for merging agents. */
|
|
41
|
+
export async function finalReviewStatus(io) {
|
|
42
|
+
const [headSha, bodies, labeled] = await Promise.all([
|
|
43
|
+
io.headSha(),
|
|
44
|
+
io.listReviewBodies(),
|
|
45
|
+
io.hasApprovalLabel(),
|
|
46
|
+
]);
|
|
47
|
+
const latest = bodies
|
|
48
|
+
.map((body) => MARKER_RE.exec(body))
|
|
49
|
+
.filter((match) => match !== null)
|
|
50
|
+
.at(-1);
|
|
51
|
+
const reviewedSha = latest?.[1] ?? null;
|
|
52
|
+
const verdict = latest?.[2] ?? null;
|
|
53
|
+
const current = reviewedSha === headSha;
|
|
54
|
+
return {
|
|
55
|
+
headSha,
|
|
56
|
+
reviewedSha,
|
|
57
|
+
verdict,
|
|
58
|
+
effort: latest?.[3] ?? null,
|
|
59
|
+
current,
|
|
60
|
+
labeled,
|
|
61
|
+
approved: current && labeled && verdict === 'Approve',
|
|
62
|
+
};
|
|
63
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import type { Effort, FinalReviewInput, Finding, Severity } from './finding.mts';
|
|
2
|
+
export type Verdict = 'Approve' | 'Request Changes' | 'Comment';
|
|
3
|
+
/** Label a final approval carries; agents remove it before any re-review. */
|
|
4
|
+
export declare const FINAL_APPROVAL_LABEL = "final approval";
|
|
5
|
+
/** Any blocking finding requests changes, any high finding comments, otherwise approve. */
|
|
6
|
+
export declare function deriveVerdict(findings: readonly Finding[]): Verdict;
|
|
7
|
+
export declare function severityTag(severity: Severity): string;
|
|
8
|
+
export declare function locationText(finding: Finding): string;
|
|
9
|
+
/** Renders a finding: tag and title up front, short bodies inline, long bodies collapsed. */
|
|
10
|
+
export declare function renderFindingBody(finding: Finding): string;
|
|
11
|
+
/** Renders a finding that has no commentable diff line, for the review body. */
|
|
12
|
+
export declare function renderBodyFinding(finding: Finding): string;
|
|
13
|
+
export declare function sortFindings(findings: readonly Finding[]): Finding[];
|
|
14
|
+
/** Hidden marker other agents parse to tie a review and its label to one head SHA. */
|
|
15
|
+
export declare function reviewMarker(headSha: string, verdict: Verdict, effort: Effort): string;
|
|
16
|
+
/** Renders the review's top section: verdict, reviewed SHA, summary, and the finding index. */
|
|
17
|
+
export declare function renderHeader(input: FinalReviewInput, headSha: string): string;
|