diff --git a/.claude/settings.json b/.claude/settings.json index b7f9b0a6294..daa8e2e13ee 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -3,5 +3,29 @@ "commit": "", "pr": "", "sessionUrl": false + }, + "hooks": { + "PreToolUse": [ + { + "matcher": "Edit|Write|MultiEdit", + "hooks": [ + { + "type": "command", + "command": "cd \"$CLAUDE_PROJECT_DIR\" && node --import tsx scripts/hooks/server-fact-write-guard.ts", + "timeout": 20 + } + ] + }, + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "cd \"$CLAUDE_PROJECT_DIR\" && node --import tsx scripts/hooks/server-fact-approve-guard.ts", + "timeout": 120 + } + ] + } + ] } } diff --git a/scripts/hooks/server-fact-approve-guard.test.ts b/scripts/hooks/server-fact-approve-guard.test.ts new file mode 100644 index 00000000000..a9ffd2dd417 --- /dev/null +++ b/scripts/hooks/server-fact-approve-guard.test.ts @@ -0,0 +1,193 @@ +import { spawnSync } from 'node:child_process' +import path from 'node:path' + +import { describe, expect, it } from 'vitest' + +import type { Approval } from './server-fact-approve-guard' +import { + approvalDecision, + classifyApproval, + decideApproval +} from './server-fact-approve-guard' +import type { SnapshotLint } from './server-fact-hook' + +const SCRIPT = path.join(import.meta.dirname, 'server-fact-approve-guard.ts') +const PANEL = 'src/platform/workspace/composables/usePanel.ts' + +const inputFiles: Record = { + 'approve.json': '{ "event": "APPROVE", "body": "ok" }', + 'comment.json': '{ "event": "COMMENT", "body": "do not APPROVE yet" }' +} +const readInput = (file: string) => inputFiles[file] ?? '' + +describe('classifyApproval', () => { + it.for<[string, Approval | undefined]>([ + ['gh pr review 123 --approve', { pr: '123', repo: undefined }], + ['gh pr review 123 -a -b ok', { pr: '123', repo: undefined }], + [ + 'gh pr review --approve --repo Comfy-Org/ComfyUI_frontend 7', + { pr: '7', repo: 'Comfy-Org/ComfyUI_frontend' } + ], + [ + 'gh pr review https://github.com/Comfy-Org/ComfyUI_frontend/pull/9 --approve', + { + pr: 'https://github.com/Comfy-Org/ComfyUI_frontend/pull/9', + repo: 'Comfy-Org/ComfyUI_frontend' + } + ], + [ + 'cd app && GH_PAGER= gh pr review 5 --approve --body "a && b"', + { pr: '5', repo: undefined } + ], + ['gh pr review --approve', { pr: undefined, repo: undefined }], + ['gh pr review 123 --comment -b x', undefined], + ['gh pr review 123 --request-changes', undefined], + ['gh pr review 123 --comment -b "--approve"', undefined], + [ + 'gh api repos/Comfy-Org/ComfyUI_frontend/pulls/1/reviews -f event=APPROVE', + { pr: '1', repo: 'Comfy-Org/ComfyUI_frontend' } + ], + [ + 'gh api -X POST /repos/Comfy-Org/ComfyUI_frontend/pulls/2/reviews --input approve.json', + { pr: '2', repo: 'Comfy-Org/ComfyUI_frontend' } + ], + [ + 'gh api repos/{owner}/{repo}/pulls/3/reviews/44/events -F event=APPROVE', + { pr: '3', repo: undefined } + ], + [ + 'gh api repos/Comfy-Org/ComfyUI_frontend/pulls/2/reviews --input comment.json', + undefined + ], + [ + 'gh api repos/Comfy-Org/ComfyUI_frontend/pulls/2/reviews -f event=COMMENT -f body=APPROVE', + undefined + ], + [ + 'gh api repos/Comfy-Org/ComfyUI_frontend/pulls/2/comments -f event=APPROVE', + undefined + ], + ['gh pr view 1', undefined], + ['echo gh pr review 1 --approve', undefined], + ['gh pr review 1 --approve -R other/repo', { pr: '1', repo: 'other/repo' }] + ])('%s', ([command, expected]) => { + expect(classifyApproval(command, readInput)).toEqual(expected) + }) +}) + +describe('approvalDecision', () => { + const diff = [ + `diff --git a/${PANEL} b/${PANEL}`, + `--- a/${PANEL}`, + `+++ b/${PANEL}`, + '@@ -2 +2 @@', + 'diff --git a/src/a.test.ts b/src/a.test.ts', + '+++ b/src/a.test.ts', + '@@ -1 +1 @@' + ].join('\n') + const head = [ + "const isOwner = role === 'owner'", + 'const canInvite = canInviteMembers.value || isOwner', + '' + ].join('\n') + + function diagnosticOnLine(line: number, message: string) { + const offset = head + .split('\n') + .slice(0, line - 1) + .reduce((sum, text) => sum + text.length + 1, 0) + return { + filename: PANEL, + message, + labels: [{ span: { offset, length: 5, line } }] + } + } + + const lint: SnapshotLint = () => ({ + ok: true, + diagnostics: [ + diagnosticOnLine(1, 'role literal'), + diagnosticOnLine(2, 'combined') + ] + }) + + it('blocks on findings in changed lines of gated files only', () => { + const decision = approvalDecision(diff, () => head, lint) + + expect(decision).toEqual({ + kind: 'block', + report: expect.stringMatching( + new RegExp( + `^server-fact: ${PANEL}:2 combined\nApproval blocked until these are resolved.\n` + ) + ) + }) + }) + + it('lints only the gated files the PR changed', () => { + const linted: string[][] = [] + approvalDecision( + diff, + () => head, + (contents) => { + linted.push([...contents.keys()]) + return { ok: true, diagnostics: [] } + } + ) + + expect(linted).toEqual([[PANEL]]) + }) + + it('allows when no gated file changed, without linting', () => { + const decision = approvalDecision( + 'diff --git a/docs/x.md b/docs/x.md\n+++ b/docs/x.md\n@@ -1 +1 @@', + () => head, + () => ({ ok: false, detail: 'lint must not run' }) + ) + + expect(decision).toEqual({ kind: 'allow' }) + }) + + it('fails open when lint cannot run', () => { + expect( + approvalDecision( + diff, + () => head, + () => ({ ok: false, detail: 'boom' }) + ) + ).toEqual({ kind: 'warn', warning: 'boom' }) + }) +}) + +describe('decideApproval', () => { + it.for([ + 'gh pr review 1 --approve --repo someone/else', + 'gh pr review 1 --comment -b looks-good', + 'git status' + ])('allows %s without consulting GitHub', (command) => { + expect( + decideApproval({ tool_name: 'Bash', tool_input: { command } }, () => ({ + ok: false, + detail: 'lint must not run' + })) + ).toEqual({ kind: 'allow' }) + }) +}) + +describe('server-fact-approve-guard hook', () => { + it('exits 0 silently for an approval in another repository', () => { + const result = spawnSync(process.execPath, ['--import', 'tsx', SCRIPT], { + cwd: path.resolve(import.meta.dirname, '../..'), + input: JSON.stringify({ + tool_name: 'Bash', + tool_input: { command: 'gh pr review 1 --approve -R someone/else' } + }), + encoding: 'utf8' + }) + + expect({ status: result.status, stderr: result.stderr }).toEqual({ + status: 0, + stderr: '' + }) + }) +}) diff --git a/scripts/hooks/server-fact-approve-guard.ts b/scripts/hooks/server-fact-approve-guard.ts new file mode 100644 index 00000000000..c1d940c0fff --- /dev/null +++ b/scripts/hooks/server-fact-approve-guard.ts @@ -0,0 +1,296 @@ +import { execFileSync } from 'node:child_process' +import { readFileSync } from 'node:fs' +import path from 'node:path' + +import { z } from 'zod' + +import { isMainModule } from '../isMainModule' +import { changedRanges, isGatedPath } from '../server-fact-gate-core' +import { lintSnapshot } from '../server-fact-oxlint' +import type { HookDecision, HookEvent, SnapshotLint } from './server-fact-hook' +import { findingsReport, reviewSnapshot, runHook } from './server-fact-hook' + +const GUARDED_REPO = 'comfy-org/comfyui_frontend' +const GUARDED_REMOTE = 'https://github.com/Comfy-Org/ComfyUI_frontend.git' +const repoRoot = path.resolve(import.meta.dirname, '../..') + +export interface Approval { + pr: string | undefined + repo: string | undefined +} + +const SHELL_TOKEN = + /'[^']*'|"(?:[^"\\]|\\.)*"|&&|\|\||[;|&\n]|(?:[^\s'"\\;|&]|\\.)+|[ \t]+/g +const SHELL_OPERATOR = /^(?:&&|\|\||[;|&\n])$/ +const SHELL_SPACE = /^[ \t]+$/ +const INLINE_FLAG = /^(--[^=]+)=(.*)$/s +const PR_URL = /github\.com\/([^/]+\/[^/]+)\/pull\/(\d+)/ +const REVIEWS_ENDPOINT = + /^\/?repos\/([^/]+\/[^/]+)\/pulls\/(\d+)\/reviews(?:\/\d+\/events)?$/ +const APPROVE_PAYLOAD = /"event"\s*:\s*"APPROVE"/ +const REVIEW_VALUE_FLAGS = new Set([ + '-b', + '--body', + '-F', + '--body-file', + '-R', + '--repo' +]) +const API_VALUE_FLAGS = new Set([ + '-X', + '--method', + '-H', + '--header', + '-f', + '--raw-field', + '-F', + '--field', + '--input', + '-q', + '--jq', + '-t', + '--template', + '--hostname', + '-p', + '--preview', + '--cache' +]) +const API_FIELD_FLAGS = new Set(['-f', '--raw-field', '-F', '--field']) + +const unescape = (text: string) => text.replace(/\\(.)/gs, '$1') + +/** Splits a shell command into simple commands of unquoted words; enough to spot a gh call. */ +function shellSegments(command: string): string[][] { + const segments: string[][] = [] + let current: string[] = [] + let word: string | undefined + const endWord = () => { + if (word !== undefined) current.push(word) + word = undefined + } + for (const [token] of command.matchAll(SHELL_TOKEN)) { + if (SHELL_OPERATOR.test(token)) { + endWord() + segments.push(current) + current = [] + } else if (SHELL_SPACE.test(token)) { + endWord() + } else { + word = (word ?? '') + unquote(token) + } + } + endWord() + return [...segments, current] +} + +function unquote(token: string): string { + if (token.startsWith("'")) return token.slice(1, -1) + return unescape(token.startsWith('"') ? token.slice(1, -1) : token) +} + +function parseFlags( + tokens: readonly string[], + valueFlags: ReadonlySet +): { positionals: string[]; flags: [string, string | undefined][] } { + const positionals: string[] = [] + const flags: [string, string | undefined][] = [] + for (let i = 0; i < tokens.length; i++) { + const token = tokens[i] + const inline = INLINE_FLAG.exec(token) + if (!token.startsWith('-') || token === '-') positionals.push(token) + else if (inline) flags.push([inline[1], inline[2]]) + else if (valueFlags.has(token)) flags.push([token, tokens.at(++i)]) + else flags.push([token, undefined]) + } + return { positionals, flags } +} + +function flagValue( + flags: readonly [string, string | undefined][], + names: readonly string[] +): string | undefined { + return flags.find(([name]) => names.includes(name))?.[1] +} + +function reviewApproval(args: readonly string[]): Approval | undefined { + const { positionals, flags } = parseFlags(args, REVIEW_VALUE_FLAGS) + if (!flags.some(([name]) => name === '--approve' || name === '-a')) { + return undefined + } + const pr = positionals.at(0) + const url = pr === undefined ? null : PR_URL.exec(pr) + return { + pr, + repo: url?.[1] ?? flagValue(flags, ['-R', '--repo']) + } +} + +function apiApproval( + args: readonly string[], + command: string, + readInput: (file: string) => string +): Approval | undefined { + const { positionals, flags } = parseFlags(args, API_VALUE_FLAGS) + const endpoint = REVIEWS_ENDPOINT.exec(positionals.at(0) ?? '') + if (!endpoint) return undefined + const input = flagValue(flags, ['--input']) + const approves = + flags.some( + ([name, value]) => API_FIELD_FLAGS.has(name) && value === 'event=APPROVE' + ) || + (input !== undefined && + APPROVE_PAYLOAD.test(input === '-' ? command : readInput(input))) + if (!approves) return undefined + const repo = endpoint[1] + return { pr: endpoint[2], repo: repo === '{owner}/{repo}' ? undefined : repo } +} + +/** The PR a shell command approves, or undefined when it approves nothing. */ +export function classifyApproval( + command: string, + readInput: (file: string) => string +): Approval | undefined { + for (const tokens of shellSegments(command)) { + const start = tokens.findIndex((token) => !/^\w+=/.test(token)) + const [program, group, verb, ...rest] = tokens.slice(start) + if (program !== 'gh') continue + const approval = + group === 'pr' && verb === 'review' + ? reviewApproval(rest) + : group === 'api' + ? apiApproval([verb, ...rest], command, readInput) + : undefined + if (approval) return approval + } + return undefined +} + +const commandSchema = z.object({ command: z.string() }) +const pullRequestSchema = z.object({ + url: z.string(), + headRefOid: z.string(), + baseRefOid: z.string() +}) + +const ALLOW: HookDecision = { kind: 'allow' } + +const isGuardedRepo = (repo: string) => repo.toLowerCase() === GUARDED_REPO + +export function approvalDecision( + diff: string, + textAtHead: (file: string) => string, + lint: SnapshotLint = lintSnapshot +): HookDecision { + const rangesByFile = new Map( + [...changedRanges(diff)].filter(([file]) => isGatedPath(file)) + ) + if (rangesByFile.size === 0) return ALLOW + const review = reviewSnapshot(rangesByFile, textAtHead, lint) + if (!review.ok) return { kind: 'warn', warning: review.detail } + return review.findings.length === 0 + ? ALLOW + : { + kind: 'block', + report: findingsReport( + review.findings, + 'Approval blocked until these are resolved.' + ) + } +} + +function run(program: string, args: string[], cwd: string): string { + return execFileSync(program, args, { + cwd, + encoding: 'utf8', + maxBuffer: 256 * 1024 * 1024, + stdio: ['ignore', 'pipe', 'pipe'] + }) +} + +function hasCommit(oid: string): boolean { + try { + run('git', ['cat-file', '-e', `${oid}^{commit}`], repoRoot) + return true + } catch { + return false + } +} + +function pullRequestDiff(head: string, base: string): string { + const missing = [head, base].filter((oid) => !hasCommit(oid)) + if (missing.length > 0) { + run( + 'git', + [ + 'fetch', + '--quiet', + '--no-tags', + '--no-write-fetch-head', + GUARDED_REMOTE, + ...missing + ], + repoRoot + ) + } + const mergeBase = run('git', ['merge-base', base, head], repoRoot).trim() + return run( + 'git', + [ + '-c', + 'core.quotePath=false', + 'diff', + '-U0', + '--no-color', + '--no-ext-diff', + '--diff-filter=ACMR', + mergeBase, + head + ], + repoRoot + ) +} + +function viewPullRequest(approval: Approval, cwd: string) { + const json = run( + 'gh', + [ + 'pr', + 'view', + ...(approval.pr === undefined ? [] : [approval.pr]), + ...(approval.repo === undefined ? [] : ['--repo', approval.repo]), + '--json', + 'url,headRefOid,baseRefOid' + ], + cwd + ) + return pullRequestSchema.parse(JSON.parse(json)) +} + +/** Network and git failures throw; runHook turns them into an allow with a warning. */ +export function decideApproval( + event: HookEvent, + lint: SnapshotLint = lintSnapshot +): HookDecision { + const command = commandSchema.safeParse(event.tool_input).data?.command + if (command === undefined) return ALLOW + const cwd = event.cwd ?? process.cwd() + const approval = classifyApproval(command, (file) => + readFileSync(path.resolve(cwd, file), 'utf8') + ) + if (!approval) return ALLOW + if (approval.repo !== undefined && !isGuardedRepo(approval.repo)) return ALLOW + + const pr = viewPullRequest(approval, cwd) + const repo = PR_URL.exec(pr.url)?.[1] + if (repo === undefined || !isGuardedRepo(repo)) return ALLOW + + return approvalDecision( + pullRequestDiff(pr.headRefOid, pr.baseRefOid), + (file) => run('git', ['show', `${pr.headRefOid}:${file}`], repoRoot), + lint + ) +} + +if (isMainModule(import.meta.url)) { + await runHook('approve-guard', (event) => decideApproval(event)) +} diff --git a/scripts/hooks/server-fact-hook.test.ts b/scripts/hooks/server-fact-hook.test.ts new file mode 100644 index 00000000000..42510b165fb --- /dev/null +++ b/scripts/hooks/server-fact-hook.test.ts @@ -0,0 +1,100 @@ +import { execFileSync, spawnSync } from 'node:child_process' +import { + mkdirSync, + mkdtempSync, + readFileSync, + realpathSync, + rmSync, + writeFileSync +} from 'node:fs' +import { tmpdir } from 'node:os' +import path from 'node:path' + +import { describe, expect, it, onTestFinished } from 'vitest' + +import { recentSkipCount } from './server-fact-hook' + +const WRITE_GUARD = path.join(import.meta.dirname, 'server-fact-write-guard.ts') +const BROKEN_CONFIG = path.join(import.meta.dirname, 'missing.oxlintrc.json') +const PANEL = 'src/usePanel.ts' + +function tempRoot(): string { + const root = realpathSync(mkdtempSync(path.join(tmpdir(), 'skip-log-'))) + onTestFinished(() => rmSync(root, { recursive: true, force: true })) + mkdirSync(path.join(root, 'src')) + writeFileSync(path.join(root, PANEL), 'export const a = canTopUp.value\n') + return root +} + +function runBrokenGuard(root: string) { + const event = { + tool_name: 'Edit', + cwd: root, + tool_input: { + file_path: path.join(root, PANEL), + old_string: 'canTopUp.value', + new_string: 'canTopUp.value || isOwner.value' + } + } + const { GIT_DIR: _gitDir, ...env } = process.env + return spawnSync(process.execPath, ['--import', 'tsx', WRITE_GUARD], { + cwd: path.resolve(import.meta.dirname, '../..'), + input: JSON.stringify(event), + encoding: 'utf8', + env: { ...env, SERVER_FACT_OXLINT_CONFIG: BROKEN_CONFIG } + }) +} + +describe('server-fact hook skip log', () => { + it('records each fail-open skip in the git common dir and reports the weekly count', () => { + const root = tempRoot() + execFileSync('git', ['init', '-q'], { cwd: root }) + const logPath = path.join(root, '.git', 'server-fact-guard-skips.log') + + const first = runBrokenGuard(root) + const second = runBrokenGuard(root) + + expect([first.status, second.status]).toEqual([0, 0]) + expect(second.stderr).toContain( + `server-fact guard skipped (2 skips in the last 7 days, see ${logPath})` + ) + const entries = readFileSync(logPath, 'utf8') + .trim() + .split('\n') + .map((line) => JSON.parse(line)) + expect(entries).toEqual([ + expect.objectContaining({ + hook: 'write-guard', + reason: expect.stringContaining('oxlint did not produce a report') + }), + expect.objectContaining({ hook: 'write-guard' }) + ]) + }) + + it('still fails open when the skip cannot be logged', () => { + const root = tempRoot() + mkdirSync(path.join(root, '.git')) + + const result = runBrokenGuard(root) + + expect(result.status).toBe(0) + expect(result.stderr).toMatch( + /^server-fact guard skipped \(skip log unavailable\): / + ) + }) +}) + +describe('recentSkipCount', () => { + it('counts only well-formed entries from the last 7 days', () => { + const now = new Date('2026-10-09T12:00:00Z') + const log = [ + JSON.stringify({ ts: '2026-10-09T11:00:00Z', hook: 'write-guard' }), + JSON.stringify({ ts: '2026-10-03T12:00:01Z', hook: 'approve-guard' }), + JSON.stringify({ ts: '2026-10-02T11:59:59Z', hook: 'write-guard' }), + 'not json', + '' + ].join('\n') + + expect(recentSkipCount(log, now)).toBe(2) + }) +}) diff --git a/scripts/hooks/server-fact-hook.ts b/scripts/hooks/server-fact-hook.ts new file mode 100644 index 00000000000..082c9d85af7 --- /dev/null +++ b/scripts/hooks/server-fact-hook.ts @@ -0,0 +1,169 @@ +import { execFileSync } from 'node:child_process' +import { appendFileSync, readFileSync } from 'node:fs' +import path from 'node:path' + +import { z } from 'zod' + +import { GUIDANCE } from '../../tools/oxlint-plugins/serverFacts' +import type { ChangedRange, Finding } from '../server-fact-gate-core' +import { findingsInFiles } from '../server-fact-gate-core' +import type { LintOutcome } from '../server-fact-oxlint' +import { lintSnapshot } from '../server-fact-oxlint' + +const hookEventSchema = z.object({ + tool_name: z.string(), + tool_input: z.unknown(), + cwd: z.string().optional() +}) + +export type HookEvent = z.infer + +export type HookDecision = + | { kind: 'allow' } + | { kind: 'block'; report: string } + | { kind: 'warn'; warning: string } + +export type SnapshotLint = ( + contents: ReadonlyMap +) => LintOutcome + +export type SnapshotReview = + | { ok: true; findings: Finding[] } + | { ok: false; detail: string } + +const AGENT_GUIDANCE = [ + 'Render each server fact as received: no &&, ||, ??, ternary, comparison or helper around it, and do not choose which fact answers the question.', + 'Local UI state (loading, in-flight, validity) may only narrow it, as in canTopUp && !isLoading.', + "If the UI needs a fact the API does not emit, open a backend ticket and wrap the interim expression in pendingServerFact('BE-xxxx', ...).", + 'Never substitute another field: can_change_seats is not member management.', + 'See docs/adr/API-SERVER-FACTS-0042-server-facts-are-rendered-not-derived.md' +].join('\n') + +export function reviewSnapshot( + rangesByFile: ReadonlyMap, + textOf: (file: string) => string, + lint: SnapshotLint = lintSnapshot +): SnapshotReview { + const contents = new Map( + [...rangesByFile.keys()].map((file) => [file, textOf(file)]) + ) + const result = lint(contents) + if (!result.ok) return result + return { + ok: true, + findings: findingsInFiles( + rangesByFile, + result.diagnostics, + (file) => contents.get(file) ?? '' + ) + } +} + +export function findingsReport( + findings: readonly Finding[], + verdict?: string +): string { + const lines = findings.map( + ({ filename, line, message }) => + `server-fact: ${filename}:${line} ${message.replace(` ${GUIDANCE}`, '')}` + ) + return [...lines, ...(verdict ? [verdict] : []), AGENT_GUIDANCE].join('\n') +} + +async function readStdin(): Promise { + const chunks: Buffer[] = [] + for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk)) + return Buffer.concat(chunks).toString('utf8') +} + +const SKIP_LOG = 'server-fact-guard-skips.log' +const SKIP_WINDOW_MS = 7 * 24 * 60 * 60 * 1000 + +const skipEntrySchema = z.object({ ts: z.string() }) + +export function recentSkipCount(logText: string, now: Date): number { + return logText + .split('\n') + .map((line) => skipEntrySchema.safeParse(parseJson(line))) + .filter( + (entry) => + entry.success && + now.getTime() - Date.parse(entry.data.ts) < SKIP_WINDOW_MS + ).length +} + +function parseJson(text: string): unknown { + try { + return JSON.parse(text) + } catch { + return undefined + } +} + +function readOptional(file: string): string { + try { + return readFileSync(file, 'utf8') + } catch { + return '' + } +} + +/** Appends the skip to a log in the git common dir, shared by worktrees and never committed. */ +function recordSkip(hook: string, reason: string, cwd: string): string { + try { + const gitDir = execFileSync( + 'git', + ['rev-parse', '--path-format=absolute', '--git-common-dir'], + { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] } + ).trim() + const logPath = path.join(gitDir, SKIP_LOG) + const now = new Date() + appendFileSync( + logPath, + `${JSON.stringify({ ts: now.toISOString(), hook, reason })}\n` + ) + const count = recentSkipCount(readOptional(logPath), now) + return `${count} ${count === 1 ? 'skip' : 'skips'} in the last 7 days, see ${logPath}` + } catch { + return 'skip log unavailable' + } +} + +function exitWith(decision: HookDecision, hook: string, cwd: string): never { + if (decision.kind === 'block') { + process.stderr.write(`${decision.report}\n`) + process.exit(2) + } + if (decision.kind === 'warn') { + const record = recordSkip(hook, decision.warning, cwd) + process.stderr.write( + `server-fact guard skipped (${record}): ${decision.warning}\n` + ) + } + process.exit(0) +} + +/** + * A broken guard must never block the tool, so every internal failure allows + * it. Each skip is logged so a broken hook cannot become a silent bypass. + */ +export async function runHook( + hook: string, + decide: (event: HookEvent) => HookDecision +): Promise { + let cwd = process.cwd() + try { + const event = hookEventSchema.safeParse(parseJson(await readStdin())) + if (!event.success) { + return exitWith( + { kind: 'warn', warning: 'unreadable hook event' }, + hook, + cwd + ) + } + cwd = event.data.cwd ?? cwd + return exitWith(decide(event.data), hook, cwd) + } catch (error) { + return exitWith({ kind: 'warn', warning: String(error) }, hook, cwd) + } +} diff --git a/scripts/hooks/server-fact-write-guard.test.ts b/scripts/hooks/server-fact-write-guard.test.ts new file mode 100644 index 00000000000..831c18eb8ca --- /dev/null +++ b/scripts/hooks/server-fact-write-guard.test.ts @@ -0,0 +1,286 @@ +import { spawnSync } from 'node:child_process' +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs' +import { tmpdir } from 'node:os' +import path from 'node:path' + +import { describe, expect, it, onTestFinished } from 'vitest' + +import { + disableDirectiveFindings, + proposedContent +} from './server-fact-write-guard' + +const SCRIPT = path.join(import.meta.dirname, 'server-fact-write-guard.ts') +const PANEL = 'src/platform/workspace/composables/usePanel.ts' +const BROKEN_CONFIG = path.join(import.meta.dirname, 'missing.oxlintrc.json') + +const panelSource = [ + 'const { canInviteMembers } = useBillingCapabilities()', + 'const canInvite = computed(() => canInviteMembers.value)', + '' +].join('\n') + +const panelWithFinding = [ + 'const { canInviteMembers } = useBillingCapabilities()', + '// invite gate', + 'const canInvite = computed(() => canInviteMembers.value || isOwner.value)', + '' +].join('\n') + +function repoWith(files: Record): string { + const root = mkdtempSync(path.join(tmpdir(), 'write-guard-')) + onTestFinished(() => rmSync(root, { recursive: true, force: true })) + mkdirSync(path.join(root, '.git')) + for (const [file, text] of Object.entries(files)) { + mkdirSync(path.dirname(path.join(root, file)), { recursive: true }) + writeFileSync(path.join(root, file), text) + } + return root +} + +function runGuard( + root: string, + toolName: string, + toolInput: Record, + env: Record = {} +) { + const event = { + tool_name: toolName, + cwd: root, + tool_input: { + ...toolInput, + file_path: path.join(root, String(toolInput.file_path)) + } + } + return spawnSync(process.execPath, ['--import', 'tsx', SCRIPT], { + cwd: path.resolve(import.meta.dirname, '../..'), + input: JSON.stringify(event), + encoding: 'utf8', + env: { ...process.env, ...env } + }) +} + +describe('proposedContent', () => { + it.for< + [ + string, + string, + Record, + string | undefined, + string | undefined + ] + >([ + ['Write replaces the file', 'Write', { content: 'b' }, 'a', 'b'], + ['Write creates a file', 'Write', { content: 'b' }, undefined, 'b'], + [ + 'Edit replaces the single match', + 'Edit', + { old_string: 'x', new_string: '$&y' }, + 'a x b', + 'a $&y b' + ], + [ + 'Edit with replace_all replaces every match', + 'Edit', + { old_string: 'x', new_string: 'y', replace_all: true }, + 'x x', + 'y y' + ], + [ + 'Edit refuses an ambiguous match', + 'Edit', + { old_string: 'x', new_string: 'y' }, + 'x x', + undefined + ], + [ + 'Edit refuses a missing match', + 'Edit', + { old_string: 'z', new_string: 'y' }, + 'x', + undefined + ], + [ + 'Edit with an empty old_string creates a file', + 'Edit', + { old_string: '', new_string: 'new' }, + undefined, + 'new' + ], + [ + 'MultiEdit applies edits in order', + 'MultiEdit', + { + edits: [ + { old_string: 'a', new_string: 'b' }, + { old_string: 'b c', new_string: 'd' } + ] + }, + 'a c', + 'd' + ], + [ + 'MultiEdit refuses when any edit misses', + 'MultiEdit', + { + edits: [ + { old_string: 'a', new_string: 'b' }, + { old_string: 'a', new_string: 'c' } + ] + }, + 'a', + undefined + ] + ])('%s', ([, toolName, input, before, expected]) => { + expect(proposedContent(toolName, input, before)).toBe(expected) + }) +}) + +describe('disableDirectiveFindings', () => { + it.for<[string, string, number[]]>([ + [ + 'a next-line disable naming a server-fact rule', + '// oxlint-disable-next-line comfy/no-capability-recombination', + [1] + ], + [ + 'an eslint block disable naming a server-fact rule', + '/* eslint-disable comfy/no-server-fact-literals */', + [1] + ], + [ + 'a bare disable that turns off every rule', + '// eslint-disable-next-line', + [1] + ], + [ + 'a disable for an unrelated rule', + '// oxlint-disable-next-line no-console -- logging', + [] + ], + ['ordinary code', 'const a = 1', []] + ])('reports %s', ([, line, expected]) => { + const findings = disableDirectiveFindings(PANEL, `${line}\n`, [ + { kind: 'added', start: 1, end: 1 } + ]) + + expect(findings.map(({ line }) => line)).toEqual(expected) + }) + + it('ignores a directive on a line the change did not add', () => { + const text = + '// oxlint-disable-next-line comfy/no-server-fact-literals\nx\n' + + expect( + disableDirectiveFindings(PANEL, text, [ + { kind: 'added', start: 2, end: 2 } + ]) + ).toEqual([]) + }) +}) + +describe('server-fact-write-guard hook', () => { + it('blocks an edit that recombines a capability and names the line', () => { + const root = repoWith({ [PANEL]: panelSource }) + + const result = runGuard(root, 'Edit', { + file_path: PANEL, + old_string: 'canInviteMembers.value)', + new_string: 'canInviteMembers.value || isPlanEnded.value)' + }) + + expect(result.status).toBe(2) + expect(result.stderr).toContain( + `server-fact: ${PANEL}:2 A server capability is combined with other state through \`||\`.` + ) + expect(result.stderr).toContain("pendingServerFact('BE-xxxx', ...)") + }) + + it('blocks a newly added inline disable of a server-fact rule', () => { + const root = repoWith({ [PANEL]: panelSource }) + + const result = runGuard(root, 'Edit', { + file_path: PANEL, + old_string: 'const canInvite', + new_string: + '// oxlint-disable-next-line comfy/no-capability-recombination\nconst canInvite' + }) + + expect(result.status).toBe(2) + expect(result.stderr).toContain(`server-fact: ${PANEL}:2 An inline disable`) + }) + + it('allows a comment-only edit to a file that already has findings', () => { + const root = repoWith({ [PANEL]: panelWithFinding }) + + const result = runGuard(root, 'Edit', { + file_path: PANEL, + old_string: '// invite gate', + new_string: '// invite gate for the members panel' + }) + + expect({ status: result.status, stderr: result.stderr }).toEqual({ + status: 0, + stderr: '' + }) + }) + + it.for([ + ['a test file', 'src/platform/workspace/composables/usePanel.test.ts'], + ['a path outside src', 'browser_tests/fixtures/panel.ts'] + ])('allows %s without linting it', ([, file]) => { + const root = repoWith({ [file]: panelSource }) + + const result = runGuard( + root, + 'Edit', + { + file_path: file, + old_string: 'canInviteMembers.value)', + new_string: 'canInviteMembers.value || isPlanEnded.value)' + }, + { SERVER_FACT_OXLINT_CONFIG: BROKEN_CONFIG } + ) + + expect({ status: result.status, stderr: result.stderr }).toEqual({ + status: 0, + stderr: '' + }) + }) + + it('allows an edit the tool cannot apply without linting it', () => { + const root = repoWith({ [PANEL]: panelSource }) + + const result = runGuard( + root, + 'Edit', + { file_path: PANEL, old_string: 'not in file', new_string: 'x || y' }, + { SERVER_FACT_OXLINT_CONFIG: BROKEN_CONFIG } + ) + + expect({ status: result.status, stderr: result.stderr }).toEqual({ + status: 0, + stderr: '' + }) + }) + + it('fails open with a warning when oxlint cannot run', () => { + const root = repoWith({ [PANEL]: panelSource }) + + const result = runGuard( + root, + 'Edit', + { + file_path: PANEL, + old_string: 'canInviteMembers.value)', + new_string: 'canInviteMembers.value || isPlanEnded.value)' + }, + { SERVER_FACT_OXLINT_CONFIG: BROKEN_CONFIG } + ) + + expect(result.status).toBe(0) + expect(result.stderr).toMatch( + /^server-fact guard skipped \(.+\): oxlint did not produce a report/ + ) + }) +}) diff --git a/scripts/hooks/server-fact-write-guard.ts b/scripts/hooks/server-fact-write-guard.ts new file mode 100644 index 00000000000..e89c85c84c5 --- /dev/null +++ b/scripts/hooks/server-fact-write-guard.ts @@ -0,0 +1,211 @@ +import { spawnSync } from 'node:child_process' +import { + existsSync, + mkdirSync, + mkdtempSync, + readFileSync, + rmSync, + writeFileSync +} from 'node:fs' +import { tmpdir } from 'node:os' +import path from 'node:path' + +import { z } from 'zod' + +import { isMainModule } from '../isMainModule' +import type { ChangedRange, Finding } from '../server-fact-gate-core' +import { changedRanges, isGatedPath } from '../server-fact-gate-core' +import { SERVER_FACT_CONFIG, lintSnapshot } from '../server-fact-oxlint' +import type { HookDecision, HookEvent, SnapshotLint } from './server-fact-hook' +import { findingsReport, reviewSnapshot, runHook } from './server-fact-hook' + +const editSchema = z.object({ + old_string: z.string(), + new_string: z.string(), + replace_all: z.boolean().optional() +}) +const filePathSchema = z.object({ file_path: z.string() }) +const writeSchema = z.object({ content: z.string() }) +const multiEditSchema = z.object({ edits: z.array(editSchema) }) + +type Edit = z.infer + +const DISABLE_DIRECTIVE = + /\b(?:oxlint|eslint)-disable(?:-next-line|-line)?\b(.*)$/ +const SERVER_FACT_RULE = /no-capability-recombination|no-server-fact-literals/ + +function applyEdit(text: string | undefined, edit: Edit): string | undefined { + if (text === undefined) { + return edit.old_string === '' ? edit.new_string : undefined + } + if (edit.old_string === '') return undefined + const parts = text.split(edit.old_string) + if (parts.length === 1) return undefined + if (edit.replace_all) return parts.join(edit.new_string) + if (parts.length > 2) return undefined + return parts.join(edit.new_string) +} + +/** The file as the tool would leave it, or undefined when the tool will refuse the edit. */ +export function proposedContent( + toolName: string, + input: unknown, + before: string | undefined +): string | undefined { + switch (toolName) { + case 'Write': + return writeSchema.safeParse(input).data?.content + case 'Edit': { + const edit = editSchema.safeParse(input).data + return edit && applyEdit(before, edit) + } + case 'MultiEdit': { + const edits = multiEditSchema.safeParse(input).data?.edits + return edits?.reduce( + (text, edit) => + text === undefined ? undefined : applyEdit(text, edit), + before + ) + } + default: + return undefined + } +} + +function disablesServerFactRules(line: string): boolean { + const directive = DISABLE_DIRECTIVE.exec(line) + if (!directive) return false + const ruleList = directive[1].replace(/\*\/.*$|--.*$/, '').trim() + return ruleList === '' || SERVER_FACT_RULE.test(ruleList) +} + +export function disableDirectiveFindings( + file: string, + text: string, + ranges: readonly ChangedRange[] +): Finding[] { + const lines = text.split('\n') + return ranges.flatMap((range) => + range.kind === 'deleted' + ? [] + : lines.slice(range.start - 1, range.end).flatMap((line, index) => + disablesServerFactRules(line) + ? [ + { + filename: file, + line: range.start + index, + message: + 'An inline disable turns off the server-fact rules. Fix the gate instead of suppressing the check.' + } + ] + : [] + ) + ) +} + +function lineCount(text: string): number { + return text.split('\n').length - (text.endsWith('\n') ? 1 : 0) +} + +function proposedRanges( + file: string, + before: string | undefined, + after: string +): readonly ChangedRange[] | undefined { + if (before === undefined) { + const end = lineCount(after) + return end === 0 ? [] : [{ kind: 'added', start: 1, end }] + } + const dir = mkdtempSync(path.join(tmpdir(), 'server-fact-diff-')) + try { + for (const [side, text] of [ + ['a', before], + ['b', after] + ] as const) { + mkdirSync(path.dirname(path.join(dir, side, file)), { recursive: true }) + writeFileSync(path.join(dir, side, file), text) + } + const diff = spawnSync( + 'git', + [ + '-c', + 'core.quotePath=false', + 'diff', + '--no-index', + '--no-prefix', + '-U0', + '--no-color', + '--no-ext-diff', + `a/${file}`, + `b/${file}` + ], + { cwd: dir, encoding: 'utf8' } + ) + if (diff.status !== 0 && diff.status !== 1) return undefined + return changedRanges(diff.stdout).get(file) ?? [] + } finally { + rmSync(dir, { recursive: true, force: true }) + } +} + +function repoRootOf(file: string): string | undefined { + const parent = path.dirname(file) + if (existsSync(path.join(parent, '.git'))) return parent + return parent === file ? undefined : repoRootOf(parent) +} + +function readIfExists(file: string): string | undefined { + return existsSync(file) ? readFileSync(file, 'utf8') : undefined +} + +function gatedTarget( + event: HookEvent +): { absolute: string; file: string } | undefined { + const filePath = filePathSchema.safeParse(event.tool_input).data?.file_path + if (filePath === undefined) return undefined + const absolute = path.resolve(event.cwd ?? process.cwd(), filePath) + const root = repoRootOf(absolute) + if (root === undefined) return undefined + const file = path.relative(root, absolute).split(path.sep).join('/') + return isGatedPath(file) ? { absolute, file } : undefined +} + +function decideWrite(event: HookEvent, lint: SnapshotLint): HookDecision { + const target = gatedTarget(event) + if (!target) return { kind: 'allow' } + const before = readIfExists(target.absolute) + const after = proposedContent(event.tool_name, event.tool_input, before) + return after === undefined + ? { kind: 'allow' } + : reviewEdit(target.file, before, after, lint) +} + +function reviewEdit( + file: string, + before: string | undefined, + after: string, + lint: SnapshotLint +): HookDecision { + const ranges = proposedRanges(file, before, after) + if (ranges === undefined) { + return { kind: 'warn', warning: 'git diff --no-index failed' } + } + if (ranges.length === 0) return { kind: 'allow' } + const review = reviewSnapshot(new Map([[file, ranges]]), () => after, lint) + if (!review.ok) return { kind: 'warn', warning: review.detail } + + const findings = [ + ...review.findings, + ...disableDirectiveFindings(file, after, ranges) + ].sort((a, b) => a.line - b.line) + return findings.length === 0 + ? { kind: 'allow' } + : { kind: 'block', report: findingsReport(findings) } +} + +if (isMainModule(import.meta.url)) { + const config = process.env.SERVER_FACT_OXLINT_CONFIG ?? SERVER_FACT_CONFIG + await runHook('write-guard', (event) => + decideWrite(event, (contents) => lintSnapshot(contents, config)) + ) +} diff --git a/scripts/server-fact-gate-core.ts b/scripts/server-fact-gate-core.ts index cb5fec1a8a7..9340e98856e 100644 --- a/scripts/server-fact-gate-core.ts +++ b/scripts/server-fact-gate-core.ts @@ -22,7 +22,7 @@ export const oxlintReportSchema = z.object({ ) }) -type OxlintDiagnostic = z.infer< +export type OxlintDiagnostic = z.infer< typeof oxlintReportSchema >['diagnostics'][number] @@ -97,3 +97,17 @@ export function findingsOnChangedLines( : [] }) } + +export function findingsInFiles( + rangesByFile: ReadonlyMap, + diagnostics: readonly OxlintDiagnostic[], + textOf: (file: string) => string +): Finding[] { + return [...rangesByFile].flatMap(([file, ranges]) => + findingsOnChangedLines( + diagnostics.filter((diagnostic) => diagnostic.filename === file), + ranges, + textOf(file) + ) + ) +} diff --git a/scripts/server-fact-gate.ts b/scripts/server-fact-gate.ts index fd65feaba23..e0bdaa04f33 100644 --- a/scripts/server-fact-gate.ts +++ b/scripts/server-fact-gate.ts @@ -1,16 +1,12 @@ -import { execFileSync, spawnSync } from 'node:child_process' +import { execFileSync } from 'node:child_process' import { readFileSync } from 'node:fs' -import path from 'node:path' import { changedRanges, - findingsOnChangedLines, - isGatedPath, - oxlintReportSchema + findingsInFiles, + isGatedPath } from './server-fact-gate-core' - -const CONFIG = 'tools/oxlint-plugins/serverFacts.oxlintrc.json' -const oxlintEntry = path.resolve('node_modules/oxlint/bin/oxlint') +import { SERVER_FACT_CONFIG, lintServerFacts } from './server-fact-oxlint' function git(args: string[]): string { return execFileSync('git', args, { @@ -30,31 +26,6 @@ function diffArgs(argv: string[]): string[] { return [git(['merge-base', base, 'HEAD']).trim()] } -function lint(files: string[]) { - const result = spawnSync( - process.execPath, - [oxlintEntry, '-c', CONFIG, '--format', 'json', ...files], - { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, windowsHide: true } - ) - if (result.error) throw result.error - const parsed = oxlintReportSchema.safeParse(parseJson(result.stdout)) - if (!parsed.success) { - console.error( - `server-facts: oxlint did not produce a report (exit ${result.status}).\n${result.stderr}${result.stdout}` - ) - process.exit(2) - } - return parsed.data.diagnostics -} - -function parseJson(text: string): unknown { - try { - return JSON.parse(text) - } catch { - return undefined - } -} - const diff = git([ '-c', 'core.quotePath=false', @@ -68,15 +39,17 @@ const diff = git([ const rangesByFile = new Map( [...changedRanges(diff)].filter(([file]) => isGatedPath(file)) ) -const files = [...rangesByFile.keys()] -const diagnostics = files.length === 0 ? [] : lint(files) +const lint = lintServerFacts([...rangesByFile.keys()], { + cwd: process.cwd(), + config: SERVER_FACT_CONFIG +}) +if (!lint.ok) { + console.error(`server-facts: ${lint.detail}`) + process.exit(2) +} -const findings = files.flatMap((file) => - findingsOnChangedLines( - diagnostics.filter((diagnostic) => diagnostic.filename === file), - rangesByFile.get(file) ?? [], - readFileSync(file, 'utf8') - ) +const findings = findingsInFiles(rangesByFile, lint.diagnostics, (file) => + readFileSync(file, 'utf8') ) for (const { filename, line, message } of findings) { @@ -84,5 +57,5 @@ for (const { filename, line, message } of findings) { } if (findings.length > 0) process.exit(1) console.log( - `server-facts: no findings on changed lines in ${files.length} file(s)` + `server-facts: no findings on changed lines in ${rangesByFile.size} file(s)` ) diff --git a/scripts/server-fact-oxlint.ts b/scripts/server-fact-oxlint.ts new file mode 100644 index 00000000000..085c9a9fb98 --- /dev/null +++ b/scripts/server-fact-oxlint.ts @@ -0,0 +1,64 @@ +import { spawnSync } from 'node:child_process' +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs' +import { tmpdir } from 'node:os' +import path from 'node:path' + +import type { OxlintDiagnostic } from './server-fact-gate-core' +import { oxlintReportSchema } from './server-fact-gate-core' + +const repoRoot = path.resolve(import.meta.dirname, '..') +const oxlintEntry = path.join(repoRoot, 'node_modules/oxlint/bin/oxlint') + +export const SERVER_FACT_CONFIG = path.join( + repoRoot, + 'tools/oxlint-plugins/serverFacts.oxlintrc.json' +) + +export type LintOutcome = + | { ok: true; diagnostics: OxlintDiagnostic[] } + | { ok: false; detail: string } + +export function lintServerFacts( + files: readonly string[], + { cwd, config }: { cwd: string; config: string } +): LintOutcome { + if (files.length === 0) return { ok: true, diagnostics: [] } + const result = spawnSync( + process.execPath, + [oxlintEntry, '-c', config, '--format', 'json', ...files], + { cwd, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, windowsHide: true } + ) + const parsed = oxlintReportSchema.safeParse(parseJson(result.stdout)) + return parsed.success + ? { ok: true, diagnostics: parsed.data.diagnostics } + : { + ok: false, + detail: `oxlint did not produce a report (exit ${result.status}). ${result.error?.message ?? ''}${result.stderr}${result.stdout}` + } +} + +/** Lints file contents at their repo-relative paths without touching the checkout. */ +export function lintSnapshot( + contents: ReadonlyMap, + config: string = SERVER_FACT_CONFIG +): LintOutcome { + const mirror = mkdtempSync(path.join(tmpdir(), 'server-facts-')) + try { + for (const [file, text] of contents) { + const target = path.join(mirror, file) + mkdirSync(path.dirname(target), { recursive: true }) + writeFileSync(target, text) + } + return lintServerFacts([...contents.keys()], { cwd: mirror, config }) + } finally { + rmSync(mirror, { recursive: true, force: true }) + } +} + +function parseJson(text: string): unknown { + try { + return JSON.parse(text) + } catch { + return undefined + } +} diff --git a/tools/oxlint-plugins/serverFacts.ts b/tools/oxlint-plugins/serverFacts.ts index 671b7b2d8df..6398e12d6ef 100644 --- a/tools/oxlint-plugins/serverFacts.ts +++ b/tools/oxlint-plugins/serverFacts.ts @@ -58,7 +58,7 @@ const EQUALITY_OPERATORS: ReadonlySet = new Set([ const ROLE_FALLBACK_OPERATORS: ReadonlySet = new Set(['??', '||']) const SERVER_MESSAGE_NAME = /message$/i -const GUIDANCE = +export const GUIDANCE = "Render the server fact as received. If the UI needs a fact the API does not emit, open a backend ticket and wrap the interim expression in pendingServerFact('BE-xxxx', ...). See docs/adr/API-SERVER-FACTS-0042-server-facts-are-rendered-not-derived.md" function unwrap(node: AstNode): AstNode {