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/.github/workflows/ci-lint-format-queue.yaml b/.github/workflows/ci-lint-format-queue.yaml index 139bfd403a0..f34e9800e29 100644 --- a/.github/workflows/ci-lint-format-queue.yaml +++ b/.github/workflows/ci-lint-format-queue.yaml @@ -61,6 +61,24 @@ jobs: cache-key: ${{ steps.lint-cache.outputs.cache-key }} path: ${{ env.LINT_CACHE_PATHS }} + server-facts: + runs-on: ubuntu-latest + steps: + - name: Checkout ref + uses: actions/checkout@v7 + with: + fetch-depth: 0 + + - name: Setup frontend + uses: ./.github/actions/setup-frontend + + # Push runs gate the pushed range; a branch-creation push has no base. + - name: Check server facts on changed lines + if: ${{ (github.event.merge_group.base_sha || github.event.before) != '0000000000000000000000000000000000000000' }} + env: + BASE_SHA: ${{ github.event.merge_group.base_sha || github.event.before }} + run: pnpm lint:server-facts --base "$BASE_SHA" + typecheck: runs-on: ubuntu-latest steps: @@ -132,7 +150,7 @@ jobs: # Single stable branch-protection context over the parallel jobs above. lint-and-format: - needs: [lint, typecheck, typecheck-aux, repo-checks] + needs: [lint, server-facts, typecheck, typecheck-aux, repo-checks] if: ${{ always() && github.event_name == 'push' }} runs-on: ubuntu-latest steps: diff --git a/.github/workflows/ci-lint-format.yaml b/.github/workflows/ci-lint-format.yaml index 6434861bbf6..5e437d62757 100644 --- a/.github/workflows/ci-lint-format.yaml +++ b/.github/workflows/ci-lint-format.yaml @@ -109,6 +109,24 @@ jobs: cache-key: ${{ steps.lint-cache.outputs.cache-key }} path: ${{ env.LINT_CACHE_PATHS }} + server-facts: + runs-on: ubuntu-latest + steps: + - name: Checkout PR + uses: actions/checkout@v7 + with: + ref: ${{ !github.event.pull_request.head.repo.fork && github.head_ref || github.ref }} + token: ${{ !github.event.pull_request.head.repo.fork && secrets.PR_GH_TOKEN || github.token }} + fetch-depth: 0 + + - name: Setup frontend + uses: ./.github/actions/setup-frontend + + - name: Check server facts on changed lines + env: + BASE_SHA: ${{ github.event.pull_request.base.sha }} + run: pnpm lint:server-facts --base "$BASE_SHA" + typecheck: runs-on: ubuntu-latest steps: diff --git a/AGENTS.md b/AGENTS.md index d7f351e5888..77a4a6eb56a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -234,6 +234,12 @@ When working from a TDD or design doc, record its tradeoffs, alternatives consid ## Common Pitfalls +- NEVER derive a server fact on the client: a gate renders one fact from the + API as received, without combining it with role, tier, plan state, seats or + `isCloud`. Local UI state (loading, in-flight, form validity) may only + disable the control, never grant it. A missing fact is a backend ticket plus + `pendingServerFact('BE-xxxx', expr)`, never another field. See + `docs/adr/API-SERVER-FACTS-0042-server-facts-are-rendered-not-derived.md` - NEVER use `any` type - use proper TypeScript types - NEVER use `as any` type assertions - fix the underlying type issue - NEVER add `@ts-ignore` or `@ts-nocheck`. Use `@ts-expect-error` only in a test diff --git a/docs/adr/API-SERVER-FACTS-0042-server-facts-are-rendered-not-derived.md b/docs/adr/API-SERVER-FACTS-0042-server-facts-are-rendered-not-derived.md new file mode 100644 index 00000000000..446d55016ea --- /dev/null +++ b/docs/adr/API-SERVER-FACTS-0042-server-facts-are-rendered-not-derived.md @@ -0,0 +1,124 @@ +# ADR-API-SERVER-FACTS-0042: Server Facts Are Rendered, Not Derived + +Date: 2026-10-09 + +## Status + +Proposed + +## Context + +The frontend keeps recombining facts the backend owns into decisions of its +own. The latest case shipped two billing P0s (BE-19903 Invite member, +BE-19904 Manage seats) through three PRs that agents wrote and agents +approved: + +- #15675 gated member management on `isCloud ? can_change_seats : role`. + `can_change_seats` answers "may this workspace change its seat quantity", + so Enterprise owners lost member management. +- #18662 OR'd `isPlanEnded && canManageSubscription` onto `can_invite_members`. +- #19455 added tier and plan-status checks so that gate survived the backend + collapsing `max_seats` to 1. + +This is not specific to billing. Since April, about 20 fixes moved a +decision back to the server after the client had derived it, including: + +- workspace creation (`can_create_workspace`) +- agent gating (server `/features`) +- the free-run offer (`free_tier_offer`) +- asset counts +- release notes keyed by the wrong version +- queue caps + +Each derivation is a second copy of backend policy. It drifts silently, +because a wrongly hidden or disabled control emits nothing. + +A rule written as prose did not stop it. A reviewer-side "never approve a +frontend-derived server fact" rule was in place before #18662 and #19455, +and both were approved. This guidance also pointed the other way: +`docs/guidance/state-and-effects.md` said "derive everything derivable", and +its first example was a `can*` flag. + +## Decision + +A **server fact** is anything the backend knows about an account, workspace, +subscription or resource that would stay true with no UI: + +- permissions and capabilities +- role, tier, plan status and seats +- readiness and versions +- server timestamps and error codes + +1. **The server fact alone decides entitlement.** A gate renders one server + fact as received. It does not combine that fact with another server fact + or a value derived from one (role, tier, plan state, seats, `isCloud`) + through `&&`, `||`, `??`, a ternary, arithmetic, a comparison or a helper. + It also does not choose which fact answers the question. Local, transient + UI state (loading, an in-flight request, form validity) may delay or + disable the control, as in `canTopUp && !isLoading`. It never grants + entitlement or stands in for a server field. +2. **`isCloud` decides which build ships, not what a user may do.** Off + Cloud, a local provider answers the same fact. +3. **A failed read uses the default its contract names.** Never fall back to + a role or a tier. +4. **A fact the API does not emit yet is a backend ticket.** Until the ticket + lands, wrap the interim expression in `pendingServerFact('', expr)`. + Never substitute another field. `can_change_seats` is not member + management. +5. **Choosing which server field answers a UI question needs review from + the backend team that owns the field.** + +Presentation stays on the client: formatting, translation, sorting, layout, +and local UI state such as loading, open panels and form validation. + +The rule is to be enforced by checks that fail, not by prose. None of +them ships with this ADR; each lands in its own change, tracked under +FE-3349 (TDD "Server-fact guardrails"): + +- oxlint rules gated on changed lines in the required lint check: the + authoritative block (FE-3351) +- a checked-in agent write hook and an approve hook: an advisory first line + that fails open (FE-3352, FE-3353) +- the `pendingServerFact` bridge and its expiry check (FE-3354) +- orthogonality tests on every gate a PR touches (FE-3355) + +Until those land, this ADR and the `AGENTS.md` line are the only guidance. + +### Alternatives considered + +- **More Markdown in reviewer skills.** Rejected: it was already in place + and failed twice. +- **An LLM reviewer prompt for this rule.** Rejected as a gate: that is what + approved the three PRs. It is not calibrated, and it shares the author's + framing. +- **Opaque `ServerFact` types now.** Deferred: it is the strongest + guarantee, but about 15 billing surfaces and other domains have to migrate + first. The planned lint gate (FE-3351) is meant to hold the line in the + meantime. +- **Server-driven UI.** Rejected for now: out of scope for the capabilities + API. + +## Consequences + +### Positive + +- One copy of each policy, in the backend, shared by every client (app, + billing-web, website, platform). +- A missing fact becomes a visible backend ticket instead of a silent client + proxy. +- Reviewers and agents get a mechanical test: is this gate one server fact, + as received? + +### Negative + +- Some UI waits on backend fields that the client could approximate today. + `pendingServerFact` is the escape hatch, and it expires with its ticket. +- Existing derivations need burning down domain by domain. Until then, new + code is held to the rule on changed lines only. + +## Notes + +- Capabilities TDD: "an API should emit facts about its own domain, and + clients should render those facts rather than recombine them into a + decision." +- Related: ADR-AUTH-SESSION-0037 (the server owns the AND for one flag). diff --git a/docs/adr/README.md b/docs/adr/README.md index a39c07929ea..b623c730698 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -16,6 +16,7 @@ An Architecture Decision Record captures an important architectural decision mad | [AGENT-OBSERVABILITY-0034](AGENT-OBSERVABILITY-0034-frontend-journey-effect-contract.md) | Frontend Journey Effect Contract | Proposed | 2026-09-17 | | [AGENT-SESSION-0028](AGENT-SESSION-0028-compose-turn-origin-and-account-generation.md) | Compose Turn Origin and Account Generation | Proposed | 2026-09-05 | | [AGENT-TARGET-0037](AGENT-TARGET-0037-commit-workflow-target-on-send-or-node-reference.md) | Commit Workflow Target on Explicit User Intent | Proposed | 2026-09-24 | +| [API-SERVER-FACTS-0042](API-SERVER-FACTS-0042-server-facts-are-rendered-not-derived.md) | Server Facts Are Rendered, Not Derived | Proposed | 2026-10-09 | | [ASSETS-DRAG-DROP-0035](ASSETS-DRAG-DROP-0035-asset-card-drag-uses-file-url.md) | Asset Card Drag-and-Drop Uses the File URL, Never the Preview URL | Proposed | 2026-09-19 | | [ASSETS-LIFECYCLE-0030](ASSETS-LIFECYCLE-0030-asset-record-and-content-lifecycles.md) | Asset Record and Content Lifecycles | Accepted | 2026-08-27 | | [AUTH-BILLING-0014](AUTH-BILLING-0014-billing-attempt-context-and-workspace-scope.md) | Billing Attempt Context and Workspace Scope | Proposed | 2026-07-28 | diff --git a/docs/guidance/state-and-effects.md b/docs/guidance/state-and-effects.md index 27ee47ad413..11a5799a3e1 100644 --- a/docs/guidance/state-and-effects.md +++ b/docs/guidance/state-and-effects.md @@ -85,9 +85,15 @@ async function startFlow(id: string) { ## 4. Derive everything derivable -Do not store `isOpening`, `canTransition`, `isLast`, or a second copy of data -that already exists. If a `computed` can name it, do not put it in a `ref` and -keep it in sync by hand — the sync is where the bugs live. +Do not store `isOpening`, `isLast`, or a second copy of data that already +exists. If a `computed` can name it, do not put it in a `ref` and keep it in +sync by hand — the sync is where the bugs live. + +This covers state the feature owns. A server fact (a permission, role, tier, +plan status, seat count, readiness or server timestamp) is not derivable here. +Render the field the API returns. If the API does not return it, ask the +backend for it. See +[ADR-API-SERVER-FACTS-0042](../adr/API-SERVER-FACTS-0042-server-facts-are-rendered-not-derived.md). ## 5. Reserve effects for synchronising with the outside diff --git a/lint-staged.config.ts b/lint-staged.config.ts index e679fcad0be..29c479ffac6 100644 --- a/lint-staged.config.ts +++ b/lint-staged.config.ts @@ -47,6 +47,9 @@ export default function lintStaged(stagedFiles: string[]) { 'pnpm exec oxfmt --write --no-error-on-unmatched-pattern' ), ...lintCommands(codeFiles, styleFiles, astroFiles), + ...(codeFiles.length > 0 + ? repoWide('pnpm lint:server-facts --staged') + : []), ...commandsWithFiles( astroFiles.map((fileName) => fileName.slice('apps/website/'.length)), 'pnpm --dir apps/website exec prettier --write' diff --git a/package.json b/package.json index b942742fbe4..7f27fd9457b 100644 --- a/package.json +++ b/package.json @@ -45,6 +45,7 @@ "lint:fix:ci": "pnpm lint:fix --cache-strategy content", "lint:fix": "pnpm oxlint --fix && eslint --cache --concurrency auto --fix", "lint:no-cache": "pnpm exec stylelint '{apps,packages,src}/**/*.{css,vue}' && pnpm oxlint && eslint --concurrency auto", + "lint:server-facts": "tsx scripts/server-fact-gate.ts", "lint:unstaged:fix": "tsx scripts/lint-unstaged.ts --fix", "lint:unstaged": "tsx scripts/lint-unstaged.ts", "lint:ci": "pnpm lint --cache-strategy content", 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/lint-staged-config.test.ts b/scripts/lint-staged-config.test.ts index 8cb1c869914..ac5f0fd053f 100644 --- a/scripts/lint-staged-config.test.ts +++ b/scripts/lint-staged-config.test.ts @@ -95,6 +95,24 @@ describe('lint-staged config', () => { expect(commands.some((command) => command.includes('eslint '))).toBe(false) }) + it.for([ + ['src/stores/appStore.ts', ['pnpm lint:server-facts --staged']], + ['src/styles.css', []] + ] as const)( + 'runs the server-fact gate only when code is staged: %s', + async ([fileName, expected]) => { + const lintStaged = await freshConfig() + + const commands = [lintStaged([fileName])].flat() + + expect( + commands.filter( + (command) => command === 'pnpm lint:server-facts --staged' + ) + ).toEqual(expected) + } + ) + it('keeps per-file commands scoped to their own chunk', async () => { const lintStaged = await freshConfig() diff --git a/scripts/server-fact-gate-core.ts b/scripts/server-fact-gate-core.ts new file mode 100644 index 00000000000..cfd48627f08 --- /dev/null +++ b/scripts/server-fact-gate-core.ts @@ -0,0 +1,118 @@ +import { z } from 'zod' + +export type ChangedRange = + | { kind: 'added'; start: number; end: number } + | { kind: 'deleted'; after: number } + +export const oxlintReportSchema = z.object({ + diagnostics: z.array( + z.object({ + message: z.string(), + filename: z.string(), + labels: z.array( + z.object({ + span: z.object({ + offset: z.number(), + length: z.number(), + line: z.number() + }) + }) + ) + }) + ) +}) + +export type OxlintDiagnostic = z.infer< + typeof oxlintReportSchema +>['diagnostics'][number] + +export interface Finding { + filename: string + line: number + message: string +} + +const GATED_PATH = /^(?:src|apps\/[^/]+\/src)\/.*\.(?:ts|vue)$/ +const UNGATED_PATH = + /\.(?:test|spec|stories)\.ts$|(?:^|\/)__mocks__\/|(?:^|\/)storybook\// +const ESCAPING_PATH = /^\/|(?:^|\/)\.\.(?:\/|$)/ +const NEW_FILE_HEADER = /^\+\+\+ (?:b\/(.+)|\/dev\/null)$/ +const HUNK_HEADER = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/ + +export function isGatedPath(path: string): boolean { + return ( + GATED_PATH.test(path) && + !UNGATED_PATH.test(path) && + !ESCAPING_PATH.test(path) + ) +} + +export function changedRanges(diffText: string): Map { + const ranges = new Map() + let current: ChangedRange[] | undefined + + for (const line of diffText.split('\n')) { + const file = NEW_FILE_HEADER.exec(line) + if (file) { + current = undefined + const path = file.at(1) + if (path !== undefined) { + current = [] + ranges.set(path, current) + } + continue + } + const hunk = HUNK_HEADER.exec(line) + if (!hunk || !current) continue + const start = Number(hunk[1]) + const count = Number(hunk.at(2) ?? 1) + current.push( + count === 0 + ? { kind: 'deleted', after: start } + : { kind: 'added', start, end: start + count - 1 } + ) + } + return ranges +} + +// A deletion sits between new lines `after` and `after + 1`. Unwrapping a +// pendingServerFact call deletes lines at the edges of the expression it +// wrapped, so a deletion on either boundary of a finding counts as touching it. +function touches(range: ChangedRange, first: number, last: number): boolean { + return range.kind === 'added' + ? first <= range.end && last >= range.start + : first <= range.after + 1 && last >= range.after +} + +export function findingsOnChangedLines( + diagnostics: readonly OxlintDiagnostic[], + ranges: readonly ChangedRange[], + fileText: string +): Finding[] { + const bytes = Buffer.from(fileText) + return diagnostics.flatMap(({ filename, message, labels }) => { + const span = labels.at(0)?.span + if (!span) return [] + const covered = bytes + .subarray(span.offset, span.offset + span.length) + .toString() + const lastLine = span.line + covered.split('\n').length - 1 + return ranges.some((range) => touches(range, span.line, lastLine)) + ? [{ filename, line: span.line, message }] + : [] + }) +} + +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.test.ts b/scripts/server-fact-gate.test.ts new file mode 100644 index 00000000000..1172823f0c7 --- /dev/null +++ b/scripts/server-fact-gate.test.ts @@ -0,0 +1,256 @@ +import { execFileSync, spawnSync } from 'node:child_process' +import { + existsSync, + mkdirSync, + mkdtempSync, + rmSync, + symlinkSync, + writeFileSync +} from 'node:fs' +import { tmpdir } from 'node:os' +import path from 'node:path' +import { afterEach, describe, expect, it } from 'vitest' + +import type { ChangedRange } from './server-fact-gate-core' +import { lintSnapshot } from './server-fact-oxlint' +import { + changedRanges, + findingsOnChangedLines, + isGatedPath +} from './server-fact-gate-core' + +const fileText = [ + "const label = '역할'", + 'const canInvite = computed(', + ' () =>', + ' canInviteMembers.value ||', + ' isPlanEnded.value', + ')', + "const isOwner = role === 'owner'" +].join('\n') + +function diagnosticCovering(snippet: string, line: number) { + const index = fileText.indexOf(snippet) + return { + filename: 'src/useInvite.ts', + message: 'server fact', + labels: [ + { + span: { + offset: Buffer.byteLength(fileText.slice(0, index)), + length: Buffer.byteLength(snippet), + line + } + } + ] + } +} + +const recombination = diagnosticCovering( + 'canInviteMembers.value ||\n isPlanEnded.value', + 4 +) +const roleLiteral = diagnosticCovering("role === 'owner'", 7) + +describe('changedRanges', () => { + it('maps each file to the new-side lines its hunks add or delete', () => { + const diff = [ + 'diff --git a/src/a.ts b/src/a.ts', + '--- a/src/a.ts', + '+++ b/src/a.ts', + '@@ -10,2 +10,3 @@ function a() {', + '@@ -20 +21 @@', + '@@ -30,2 +31,0 @@', + 'diff --git a/src/new.vue b/src/new.vue', + '--- /dev/null', + '+++ b/src/new.vue', + '@@ -0,0 +1,4 @@' + ].join('\n') + + expect(Object.fromEntries(changedRanges(diff))).toEqual({ + 'src/a.ts': [ + { kind: 'added', start: 10, end: 12 }, + { kind: 'added', start: 21, end: 21 }, + { kind: 'deleted', after: 31 } + ], + 'src/new.vue': [{ kind: 'added', start: 1, end: 4 }] + }) + }) +}) + +describe('findingsOnChangedLines', () => { + it.for<[string, ChangedRange[], number[]]>([ + [ + 'a finding that starts on an unchanged line but covers a changed one', + [{ kind: 'added', start: 5, end: 5 }], + [4] + ], + [ + 'a finding whose first line changed', + [{ kind: 'added', start: 7, end: 7 }], + [7] + ], + [ + 'findings entirely on unchanged lines', + [{ kind: 'added', start: 1, end: 3 }], + [] + ], + [ + 'a deletion inside a multi-line finding', + [{ kind: 'deleted', after: 4 }], + [4] + ], + [ + 'a deletion on the boundary just before a finding starts', + [{ kind: 'deleted', after: 3 }], + [4] + ], + [ + 'a deletion on the boundary just after a finding ends, even when the finding already existed', + [{ kind: 'deleted', after: 5 }], + [4] + ], + [ + 'no finding for a deletion one line away from either boundary', + [{ kind: 'deleted', after: 2 }], + [] + ] + ])('reports %s', ([, ranges, expectedLines]) => { + const findings = findingsOnChangedLines( + [recombination, roleLiteral], + ranges, + fileText + ) + + expect(findings.map(({ line }) => line)).toEqual(expectedLines) + }) +}) + +describe('isGatedPath', () => { + it.for([ + ['src/platform/workspace/composables/useMembersPanel.ts', true], + ['src/components/Dialog.vue', true], + ['apps/billing-web/src/main.ts', true], + ['src/components/Dialog.test.ts', false], + ['src/components/Dialog.stories.ts', false], + ['src/__mocks__/api.ts', false], + ['src/storybook/mocks/useBillingCapabilities.ts', false], + ['browser_tests/fixtures/billing.ts', false], + ['packages/account-core/src/index.ts', false], + ['src/locales/en/main.json', false], + ['src/../../outside.ts', false], + ['src/a/../../../outside.vue', false], + ['apps/website/src/../../../outside.ts', false], + ['/src/outside.ts', false] + ] as const)('gates %s: %s', ([file, gated]) => { + expect(isGatedPath(file)).toBe(gated) + }) +}) + +describe('lintSnapshot', () => { + let outsideDir: string | undefined + + afterEach(() => { + if (outsideDir) rmSync(outsideDir, { recursive: true, force: true }) + outsideDir = undefined + }) + + it.for([ + [ + 'a relative path that climbs out', + (dir: string) => `src/../../${path.basename(dir)}/escaped.ts` + ], + ['an absolute path', (dir: string) => path.join(dir, 'escaped.ts')] + ] as const)('refuses %s without writing it', ([, fileIn]) => { + const dir = mkdtempSync(path.join(tmpdir(), 'server-fact-outside-')) + outsideDir = dir + const file = fileIn(dir) + + const outcome = lintSnapshot(new Map([[file, 'export const a = 1']])) + + expect(outcome).toEqual({ + ok: false, + detail: `${file} resolves outside the snapshot` + }) + expect(existsSync(path.join(dir, 'escaped.ts'))).toBe(false) + }) +}) + +describe('server-fact gate on a real diff', () => { + const repoRoot = path.resolve(import.meta.dirname, '..') + const gatedFile = 'src/useInvite.ts' + let workDir: string | undefined + + afterEach(() => { + if (workDir) rmSync(workDir, { recursive: true, force: true }) + workDir = undefined + }) + + function runGateAfterEdit(before: string[], after: string[]) { + const dir = mkdtempSync(path.join(tmpdir(), 'server-fact-gate-')) + workDir = dir + const run = (...args: string[]) => + execFileSync('git', args, { cwd: dir, stdio: 'ignore' }) + run('init', '-q') + run('config', 'user.email', 'gate@test.invalid') + run('config', 'user.name', 'gate') + for (const linked of ['node_modules', 'tools']) { + symlinkSync(path.join(repoRoot, linked), path.join(dir, linked)) + } + writeFileSync(path.join(dir, '.git/info/exclude'), 'node_modules\ntools\n') + mkdirSync(path.join(dir, 'src')) + writeFileSync(path.join(dir, gatedFile), before.join('\n')) + run('add', '.') + run('commit', '-q', '-m', 'base') + writeFileSync(path.join(dir, gatedFile), after.join('\n')) + return spawnSync( + process.execPath, + [ + '--import', + 'tsx', + path.join(repoRoot, 'scripts/server-fact-gate.ts'), + '--base', + 'HEAD' + ], + { cwd: dir, encoding: 'utf8' } + ) + } + + it('reports a recombination exposed by deleting only its pendingServerFact wrapper lines', () => { + const wrapped = [ + 'const { canInviteMembers } = useBillingCapabilities()', + 'export const canInvite =', + ' pendingServerFact(', + " 'BE-1',", + ' canInviteMembers.value || isPlanEnded.value', + ' )', + 'export const ready = true', + '' + ] + const unwrapped = wrapped.filter( + (line) => !/pendingServerFact|BE-1|^ {2}\)$/.test(line) + ) + + const result = runGateAfterEdit(wrapped, unwrapped) + + expect(result.stderr).toContain(`${gatedFile}:3 `) + expect(result.status).toBe(1) + }) + + it('passes an existing finding when the only deletion is a line away from it', () => { + const before = [ + 'const { canInviteMembers } = useBillingCapabilities()', + 'export const canInvite =', + ' canInviteMembers.value || isPlanEnded.value', + 'export const ready = true', + 'export const unused = false', + '' + ] + const after = before.filter((line) => !line.includes('unused')) + + const result = runGateAfterEdit(before, after) + + expect(result.stderr).toBe('') + expect(result.status).toBe(0) + }) +}) diff --git a/scripts/server-fact-gate.ts b/scripts/server-fact-gate.ts new file mode 100644 index 00000000000..e0bdaa04f33 --- /dev/null +++ b/scripts/server-fact-gate.ts @@ -0,0 +1,61 @@ +import { execFileSync } from 'node:child_process' +import { readFileSync } from 'node:fs' + +import { + changedRanges, + findingsInFiles, + isGatedPath +} from './server-fact-gate-core' +import { SERVER_FACT_CONFIG, lintServerFacts } from './server-fact-oxlint' + +function git(args: string[]): string { + return execFileSync('git', args, { + encoding: 'utf8', + maxBuffer: 256 * 1024 * 1024 + }) +} + +function diffArgs(argv: string[]): string[] { + if (argv.includes('--staged')) return ['--cached'] + const baseIndex = argv.indexOf('--base') + const base = baseIndex === -1 ? undefined : argv.at(baseIndex + 1) + if (base === undefined) { + console.error('Usage: server-fact-gate (--base | --staged)') + process.exit(2) + } + return [git(['merge-base', base, 'HEAD']).trim()] +} + +const diff = git([ + '-c', + 'core.quotePath=false', + 'diff', + '-U0', + '--no-color', + '--no-ext-diff', + '--diff-filter=ACMR', + ...diffArgs(process.argv.slice(2)) +]) +const rangesByFile = new Map( + [...changedRanges(diff)].filter(([file]) => isGatedPath(file)) +) +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 = findingsInFiles(rangesByFile, lint.diagnostics, (file) => + readFileSync(file, 'utf8') +) + +for (const { filename, line, message } of findings) { + console.error(`${filename}:${line} ${message}`) +} +if (findings.length > 0) process.exit(1) +console.log( + `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..136c2b501be --- /dev/null +++ b/scripts/server-fact-oxlint.ts @@ -0,0 +1,79 @@ +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 { + const escaping = [...contents.keys()].find( + (file) => !isInside(mirror, path.resolve(mirror, file)) + ) + if (escaping !== undefined) { + return { ok: false, detail: `${escaping} resolves outside the snapshot` } + } + for (const [file, text] of contents) { + const target = path.resolve(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 isInside(root: string, target: string): boolean { + const relative = path.relative(root, target) + return ( + relative !== '' && + !path.isAbsolute(relative) && + relative.split(path.sep)[0] !== '..' + ) +} + +function parseJson(text: string): unknown { + try { + return JSON.parse(text) + } catch { + return undefined + } +} diff --git a/tools/oxlint-plugins/comfy.ts b/tools/oxlint-plugins/comfy.ts index ced5195cef2..6b40442d45d 100644 --- a/tools/oxlint-plugins/comfy.ts +++ b/tools/oxlint-plugins/comfy.ts @@ -28,6 +28,10 @@ import type { noUnitTestFilesInBrowserTests as NoUnitTestFilesInBrowserTests, noUnsafeErrorAssertion as NoUnsafeErrorAssertion } from './restrictedSyntax' +import type { + noCapabilityRecombination as NoCapabilityRecombination, + noServerFactLiterals as NoServerFactLiterals +} from './serverFacts' import type { noImportActual as NoImportActual, noModuleScopeVitestMocks as NoModuleScopeVitestMocks, @@ -93,6 +97,12 @@ const { noUnitTestFilesInBrowserTests: typeof NoUnitTestFilesInBrowserTests noUnsafeErrorAssertion: typeof NoUnsafeErrorAssertion } +const { noCapabilityRecombination, noServerFactLiterals } = requireFrom( + './serverFacts.ts' +) as { + noCapabilityRecombination: typeof NoCapabilityRecombination + noServerFactLiterals: typeof NoServerFactLiterals +} const { noImportActual, noModuleScopeVitestMocks, @@ -113,6 +123,7 @@ const { noRenderInWatchEffect } = requireFrom('./watchEffectRendering.ts') as { export default { meta: { name: 'comfy' }, rules: { + 'no-capability-recombination': noCapabilityRecombination, 'no-comfy-page-setup-call': noComfyPageSetupCall, 'no-deprecated-api-schema': noDeprecatedApiSchema, 'no-direct-selection-write': noDirectSelectionWrite, @@ -130,6 +141,7 @@ export default { 'no-playwright-imports-in-fixture-data': noPlaywrightImportsInFixtureData, 'no-primevue-imports': noPrimeVueImports, 'no-render-in-watch-effect': noRenderInWatchEffect, + 'no-server-fact-literals': noServerFactLiterals, 'no-statically-disabled-test': noStaticallyDisabledTest, 'no-redundant-litegraph-cleanup': noRedundantLiteGraphCleanup, 'no-redundant-vitest-cleanup': noRedundantVitestCleanup, diff --git a/tools/oxlint-plugins/serverFacts.oxlintrc.json b/tools/oxlint-plugins/serverFacts.oxlintrc.json new file mode 100644 index 00000000000..06341b876b8 --- /dev/null +++ b/tools/oxlint-plugins/serverFacts.oxlintrc.json @@ -0,0 +1,10 @@ +{ + "$schema": "../../node_modules/oxlint/configuration_schema.json", + "plugins": [], + "categories": { "correctness": "off" }, + "jsPlugins": ["./comfy.ts"], + "rules": { + "comfy/no-capability-recombination": "error", + "comfy/no-server-fact-literals": "error" + } +} diff --git a/tools/oxlint-plugins/serverFacts.test.ts b/tools/oxlint-plugins/serverFacts.test.ts new file mode 100644 index 00000000000..d92590aac75 --- /dev/null +++ b/tools/oxlint-plugins/serverFacts.test.ts @@ -0,0 +1,336 @@ +import { RuleTester } from 'oxlint/plugins-dev' +import { describe, it } from 'vitest' + +import { noCapabilityRecombination, noServerFactLiterals } from './serverFacts' + +RuleTester.describe = describe +RuleTester.it = it + +const ruleTester = new RuleTester({ + languageOptions: { parserOptions: { lang: 'ts' } } +}) + +ruleTester.run('no-capability-recombination', noCapabilityRecombination, { + valid: [ + { + name: 'a capability rendered alone', + code: ` +const { canTopUp } = useBillingCapabilities() +const showTopUp = computed(() => canTopUp.value) +` + }, + { + name: 'a capability defaulted with a literal', + code: `const canCancel = computed(() => capabilities.value?.can_cancel ?? false)` + }, + { + name: 'a recombination wrapped in pendingServerFact', + code: ` +const { canInviteMembers } = useBillingCapabilities() +const canInvite = computed(() => + pendingServerFact('BE-1', canInviteMembers.value || isPlanEnded.value) +) +` + }, + { + name: 'a pendingServerFact result combined later', + code: ` +const { canInviteMembers } = useBillingCapabilities() +const canInvite = pendingServerFact('BE-1', canInviteMembers.value && isOwner) +const showInvite = canInvite || isLoading.value +` + }, + { + name: 'a can-prefixed local that is not a capability', + code: ` +const canClose = computed(() => open.value && dirty.value) +const ready = canClose.value || isLoading.value +` + }, + { + name: 'client-only flags combined with each other', + code: ` +const a = isCloud && isNightly +const b = isLoading.value || isReady.value +` + }, + { + name: 'a capability narrowed by a negated loading flag', + code: ` +const { canInviteMembers } = useBillingCapabilities() +const enabled = canInviteMembers.value && !isLoading.value +` + }, + { + name: 'a disabled state from a negated capability or an in-flight submit', + code: ` +const { canTopUp } = useBillingCapabilities() +const disabled = !canTopUp.value || isSubmitting.value +` + }, + { + name: 'a capability narrowed by several local flags', + code: ` +const { canTopUp } = useBillingCapabilities() +const enabled = isValid.value && canTopUp.value && !inFlight +const disabled = !(canTopUp.value && !saving.value) || isDirty.value +const locked = isSaving.value || !isValid.value || !canTopUp.value +` + }, + { + name: 'a property that merely shares a capability name', + code: ` +const { canTopUp } = useBillingCapabilities() +const enabled = options.canTopUp || fallback +` + }, + { + name: 'a capability defaulted while loading', + code: ` +const { canTopUp } = useBillingCapabilities() +const enabled = isLoading.value ? false : canTopUp.value +` + }, + { + name: 'a capability defaulted by negated or positive local state', + code: ` +const { canTopUp } = useBillingCapabilities() +const a = !isSubmitting.value ? canTopUp.value : false +const b = isValid.value ? canTopUp.value : undefined +const c = isLoading.value ? null : canTopUp.value && !isSaving.value +` + }, + { + name: 'a disabled state forced while submitting', + code: ` +const { canTopUp } = useBillingCapabilities() +const disabled = isSubmitting.value ? true : !canTopUp.value +` + }, + { + name: 'a capability defaulted while its source is absent', + code: ` +const a = capabilities.value ? capabilities.value.can_top_up : false +const b = !capabilities.value ? false : capabilities.value.can_top_up +const c = capabilities.value?.can_top_up ?? false +` + } + ], + invalid: [ + { + name: '#15675 capability chosen by isCloud with a role fallback', + code: ` +const { canChangeSeats } = useBillingCapabilities() +const canManage = computed(() => + isCloud ? canChangeSeats.value : workspaceRole.value === 'owner' +) +`, + errors: [{ messageId: 'chosen' }] + }, + { + name: '#18662 capability or-ed with plan state and a permission', + code: ` +const { canInviteMembers } = useBillingCapabilities() +const canInvite = computed( + () => + canInviteMembers.value || + (isPlanEnded.value && permissions.value.canManageSubscription) +) +`, + errors: [{ messageId: 'combined', data: { operator: '||' } }] + }, + { + name: '#16967 capability object member chosen by isCloud', + code: ` +const capabilities = useBillingCapabilities() +const canChangeSeats = computed(() => + isCloud + ? capabilities.canChangeSeats.value + : permissions.value.canManageSubscription +) +`, + errors: [{ messageId: 'chosen' }] + }, + { + name: '#16967 proxy choice between two capabilities by plan tier', + code: ` +const { canChangeSeats, canSubscribeSelfServe } = useBillingCapabilities() +function canAct(tier) { + return hasActivePaidPlan(tier) + ? canChangeSeats.value + : canSubscribeSelfServe.value +} +`, + errors: [{ messageId: 'chosen' }] + }, + { + name: 'a raw capability field defaulted to a role check', + code: `const canTopUp = capabilities.value?.can_top_up ?? workspaceStore.activeWorkspace?.role === 'owner'`, + errors: [{ messageId: 'combined', data: { operator: '??' } }] + }, + { + name: 'two capabilities or-ed together', + code: ` +const { canTopUp, canSubscribeSelfServe } = useBillingCapabilities() +const showBuy = canTopUp.value || canSubscribeSelfServe.value +`, + errors: [{ messageId: 'combined', data: { operator: '||' } }] + }, + { + name: 'a capability narrowed by a server-derived seat fact', + code: ` +const { canInviteMembers } = useBillingCapabilities() +const enabled = canInviteMembers.value && hasMemberSeats.value +`, + errors: [{ messageId: 'combined', data: { operator: '&&' } }] + }, + { + name: 'a loading flag that grants a capability through ||', + code: ` +const { canTopUp } = useBillingCapabilities() +const enabled = canTopUp.value || isLoading.value +`, + errors: [{ messageId: 'combined', data: { operator: '||' } }] + }, + { + name: 'a local flag that grants when the capability is false', + code: ` +const { canTopUp } = useBillingCapabilities() +const enabled = !canTopUp.value && isOpen.value +`, + errors: [{ messageId: 'combined', data: { operator: '&&' } }] + }, + { + name: 'a narrowed capability or-ed with a local flag', + code: ` +const { canTopUp } = useBillingCapabilities() +const enabled = (canTopUp.value && !isLoading.value) || isSaving.value +`, + errors: [{ messageId: 'combined', data: { operator: '||' } }] + }, + { + name: 'server-derived plan and subscription flags next to a capability', + code: ` +const { canTopUp } = useBillingCapabilities() +const a = canTopUp.value && !isPlanEnded.value +const b = canTopUp.value && isTeamPlan.value +const c = !canTopUp.value || !isSubscribed.value +`, + errors: [ + { messageId: 'combined', data: { operator: '&&' } }, + { messageId: 'combined', data: { operator: '&&' } }, + { messageId: 'combined', data: { operator: '||' } } + ] + }, + { + name: 'an alias of a capability combined later', + code: ` +const { canTopUp } = useBillingCapabilities() +const topUpAllowed = computed(() => canTopUp.value) +const showTopUp = topUpAllowed.value && isPersonal.value +`, + errors: [{ messageId: 'combined', data: { operator: '&&' } }] + }, + { + name: 'a capability defaulted by server-derived plan state', + code: ` +const { canInviteMembers } = useBillingCapabilities() +const enabled = isPlanEnded.value ? false : canInviteMembers.value +`, + errors: [{ messageId: 'chosen' }] + }, + { + name: 'a local flag that grants through a ternary', + code: ` +const { canTopUp } = useBillingCapabilities() +const a = isLoading.value ? true : canTopUp.value +const b = isSubmitting.value ? false : !canTopUp.value +`, + errors: [{ messageId: 'chosen' }, { messageId: 'chosen' }] + }, + { + name: 'a capability chosen by another capability', + code: ` +const { canTopUp, canSubscribeSelfServe } = useBillingCapabilities() +const a = canTopUp.value ? canSubscribeSelfServe.value : false +const b = capabilities.value.can_a ? capabilities.value.can_b : false +`, + errors: [{ messageId: 'chosen' }, { messageId: 'chosen' }] + }, + { + name: 'a presence check of a different object or inverted polarity', + code: ` +const a = other.value ? capabilities.value.can_top_up : false +const b = capabilities.value ? false : capabilities.value.can_top_up +`, + errors: [{ messageId: 'chosen' }, { messageId: 'chosen' }] + } + ] +}) + +ruleTester.run('no-server-fact-literals', noServerFactLiterals, { + valid: [ + { + name: 'local result, chat and channel literals', + code: ` +const ok = result.status === 'ok' +const fromUser = msg.role === 'user' +const other = ch.role !== 'selection' +` + }, + { + name: 'a role comparison wrapped in pendingServerFact', + code: `const isOwner = pendingServerFact('BE-1', role.value === 'owner')` + }, + { + name: 'includes on a list of messages', + code: `const seen = messageIds.includes(id)` + } + ], + invalid: [ + { + name: 'a session role compared with a role value', + code: `const isPaid = session.value?.role !== 'member'`, + errors: [ + { messageId: 'compared', data: { field: 'role', literal: 'member' } } + ] + }, + { + name: 'a role literal on the left side', + code: `const isOwner = 'owner' === workspace.role`, + errors: [ + { messageId: 'compared', data: { field: 'role', literal: 'owner' } } + ] + }, + { + name: 'a subscription tier compared with a literal', + code: `const isEnterprise = subscription.value?.tier === 'ENTERPRISE'`, + errors: [ + { + messageId: 'compared', + data: { field: 'tier', literal: 'ENTERPRISE' } + } + ] + }, + { + name: 'a subscription status compared with a literal', + code: `const ended = subscriptionStatus.value === 'ended'`, + errors: [ + { + messageId: 'compared', + data: { field: 'subscriptionStatus', literal: 'ended' } + } + ] + }, + { + name: 'a missing role defaulted to owner', + code: `const effectiveRole = role ?? 'owner'`, + errors: [{ messageId: 'roleFallback', data: { literal: 'owner' } }] + }, + { + name: 'a server error message matched as text', + code: `const oom = error.message.includes('CUDA')`, + errors: [{ messageId: 'messageMatch' }] + } + ] +}) diff --git a/tools/oxlint-plugins/serverFacts.ts b/tools/oxlint-plugins/serverFacts.ts new file mode 100644 index 00000000000..1a83c6bd1dd --- /dev/null +++ b/tools/oxlint-plugins/serverFacts.ts @@ -0,0 +1,488 @@ +import type { RuleTester } from 'oxlint/plugins-dev' + +type Rule = Parameters[1] +type Create = NonNullable +type Visitor = ReturnType +type VisitedNode = Parameters< + NonNullable +>[0] +type Expression = VisitedNode<'LogicalExpression'>['left'] +type AstNode = Expression['parent'] +type Ternary = VisitedNode<'ConditionalExpression'> + +const CAPABILITY_SOURCES: ReadonlySet = new Set([ + 'useBillingCapabilities' +]) +const CAPABILITY_BINDING = /^can[A-Z]\w*$/ +const CAPABILITY_FIELD = /^can_[a-z_]+$/ +const PENDING_FACT_WRAPPER = 'pendingServerFact' +const LOCAL_UI_STATE: ReadonlySet = new Set([ + 'isLoading', + 'isPending', + 'isSubmitting', + 'isSaving', + 'isBusy', + 'isFetching', + 'isValidating', + 'isDirty', + 'isValid', + 'isInvalid', + 'isOpen', + 'isDisabled', + 'loading', + 'pending', + 'submitting', + 'saving', + 'busy', + 'inFlight' +]) + +const ROLE_VALUES: ReadonlySet = new Set(['owner', 'member', 'admin']) +const isRoleValue = (literal: string) => ROLE_VALUES.has(literal) +const anyString = () => true + +const COMPARED_FACTS: ReadonlyMap boolean> = + new Map([ + ['role', isRoleValue], + ['tier', anyString], + ['billingStatus', anyString], + ['subscriptionStatus', anyString], + ['billing_status', anyString], + ['subscription_status', anyString] + ]) +const EQUALITY_OPERATORS: ReadonlySet = new Set([ + '===', + '!==', + '==', + '!=' +]) +const ROLE_FALLBACK_OPERATORS: ReadonlySet = new Set(['??', '||']) +const SERVER_MESSAGE_NAME = /message$/i + +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 { + switch (node.type) { + case 'ChainExpression': + case 'TSNonNullExpression': + case 'ParenthesizedExpression': + return unwrap(node.expression) + default: + return node + } +} + +function factName(node: AstNode): string | undefined { + const expression = unwrap(node) + if (expression.type === 'Identifier') return expression.name + if (expression.type !== 'MemberExpression' || expression.computed) { + return undefined + } + return expression.property.name === 'value' + ? factName(expression.object) + : expression.property.name +} + +function isLiteral(node: AstNode): boolean { + const expression = unwrap(node) + return ( + expression.type === 'Literal' || + (expression.type === 'Identifier' && expression.name === 'undefined') + ) +} + +function literalTruthiness(node: AstNode): boolean | undefined { + if (!isLiteral(node)) return undefined + const expression = unwrap(node) + return expression.type === 'Literal' && Boolean(expression.value) +} + +function stringLiteral(node: AstNode): string | undefined { + const expression = unwrap(node) + return expression.type === 'Literal' && typeof expression.value === 'string' + ? expression.value + : undefined +} + +function isNode(value: unknown): value is AstNode { + return ( + typeof value === 'object' && + value !== null && + 'type' in value && + typeof value.type === 'string' + ) +} + +// Property names are not references, so a `foo.canTopUp` key must not match a +// destructured `canTopUp` binding. +function childNodes(node: AstNode): AstNode[] { + if (node.type === 'MemberExpression' && !node.computed) return [node.object] + if (node.type === 'Property' && !node.computed) return [node.value] + return Object.entries(node) + .filter(([key]) => key !== 'parent') + .flatMap(([, value]: [string, unknown]) => + Array.isArray(value) ? value.filter(isNode) : isNode(value) ? [value] : [] + ) +} + +function isPendingFactCall(node: AstNode): boolean { + return ( + node.type === 'CallExpression' && + factName(node.callee) === PENDING_FACT_WRAPPER + ) +} + +function isInsidePendingFact(node: AstNode): boolean { + const { parent } = node + return ( + parent !== null && + (isPendingFactCall(parent) || isInsidePendingFact(parent)) + ) +} + +function logicalOperands(node: AstNode): AstNode[] { + const expression = unwrap(node) + return expression.type === 'LogicalExpression' + ? [ + ...logicalOperands(expression.left), + ...logicalOperands(expression.right) + ] + : [expression] +} + +function isCapabilitySourceCall(node: AstNode | null): boolean { + if (!node) return false + const expression = unwrap(node) + return ( + expression.type === 'CallExpression' && + CAPABILITY_SOURCES.has(factName(expression.callee) ?? '') + ) +} + +type ObjectPattern = Extract< + VisitedNode<'VariableDeclarator'>['id'], + { type: 'ObjectPattern' } +> + +function destructuredCapabilities(pattern: ObjectPattern): string[] { + return pattern.properties.flatMap((property) => + property.type === 'Property' && + property.key.type === 'Identifier' && + CAPABILITY_BINDING.test(property.key.name) && + property.value.type === 'Identifier' + ? [property.value.name] + : [] + ) +} + +function referenceName(node: AstNode): string | undefined { + const expression = unwrap(node) + if (expression.type === 'Identifier') return expression.name + if ( + expression.type !== 'MemberExpression' || + expression.computed || + expression.property.name !== 'value' + ) { + return undefined + } + const object = unwrap(expression.object) + return object.type === 'Identifier' ? object.name : undefined +} + +function negated(node: AstNode): AstNode | undefined { + const expression = unwrap(node) + return expression.type === 'UnaryExpression' && expression.operator === '!' + ? expression.argument + : undefined +} + +function isLocalUiState(node: AstNode): boolean { + const inner = negated(node) + if (inner) return isLocalUiState(inner) + const expression = unwrap(node) + if (expression.type === 'LogicalExpression') { + return isLocalUiState(expression.left) && isLocalUiState(expression.right) + } + return LOCAL_UI_STATE.has(referenceName(expression) ?? '') +} + +type IsCapability = (node: AstNode) => boolean + +// Local UI state may only narrow a capability: `cap && !isLoading` is true only +// when `cap` is, and `!cap || isSubmitting` is true whenever `cap` is false. +function impliesCapability(node: AstNode, isCapability: IsCapability): boolean { + const inner = negated(node) + if (inner) return isDisabledWithoutCapability(inner, isCapability) + const expression = unwrap(node) + if (expression.type !== 'LogicalExpression') return isCapability(expression) + return ( + expression.operator === '&&' && + oneSideIsLocal(expression, (side) => impliesCapability(side, isCapability)) + ) +} + +function isDisabledWithoutCapability( + node: AstNode, + isCapability: IsCapability +): boolean { + const inner = negated(node) + if (inner) return impliesCapability(inner, isCapability) + const expression = unwrap(node) + return ( + expression.type === 'LogicalExpression' && + expression.operator === '||' && + oneSideIsLocal(expression, (side) => + isDisabledWithoutCapability(side, isCapability) + ) + ) +} + +function oneSideIsLocal( + { left, right }: Extract, + narrows: (side: AstNode) => boolean +): boolean { + return ( + (narrows(left) && isLocalUiState(right)) || + (isLocalUiState(left) && narrows(right)) + ) +} + +function memberPath(node: AstNode): string | undefined { + const expression = unwrap(node) + if (expression.type === 'Identifier') return expression.name + if (expression.type !== 'MemberExpression' || expression.computed) { + return undefined + } + const object = memberPath(expression.object) + return object === undefined + ? undefined + : `${object}.${expression.property.name}` +} + +interface LiteralDefault { + truthy: boolean + other: AstNode + isConsequent: boolean +} + +function literalDefault({ + consequent, + alternate +}: Ternary): LiteralDefault | undefined { + const consequentTruthy = literalTruthiness(consequent) + if (consequentTruthy !== undefined) { + return { truthy: consequentTruthy, other: alternate, isConsequent: true } + } + const alternateTruthy = literalTruthiness(alternate) + return alternateTruthy === undefined + ? undefined + : { truthy: alternateTruthy, other: consequent, isConsequent: false } +} + +// `isLoading ? false : cap` reads as `!isLoading && cap`, and +// `isSubmitting ? true : !cap` as `isSubmitting || !cap`. +function isNarrowedTernary(node: Ternary, isCapability: IsCapability): boolean { + const fallback = literalDefault(node) + if (!fallback || !isLocalUiState(node.test)) return false + return fallback.truthy + ? isDisabledWithoutCapability(fallback.other, isCapability) + : impliesCapability(fallback.other, isCapability) +} + +function capabilityOwner( + node: AstNode, + isCapability: IsCapability +): string | undefined { + const expression = unwrap(node) + if (expression.type !== 'MemberExpression' || expression.computed) { + return undefined + } + if (expression.property.name === 'value') { + return capabilityOwner(expression.object, isCapability) + } + return isCapability(expression) ? memberPath(expression.object) : undefined +} + +// `caps ? caps.can_top_up : false` is `caps?.can_top_up ?? false`. +function isPresenceDefault(node: Ternary, isCapability: IsCapability): boolean { + const fallback = literalDefault(node) + if (!fallback) return false + const negatedTest = negated(node.test) + const owner = capabilityOwner(fallback.other, isCapability) + return ( + owner !== undefined && + fallback.isConsequent === (negatedTest !== undefined) && + memberPath(negatedTest ?? node.test) === owner + ) +} + +export const noCapabilityRecombination: Rule = { + meta: { + type: 'problem', + docs: { + description: + 'Prevent combining a server capability with other client state' + }, + schema: [], + messages: { + combined: `A server capability is combined with other state through \`{{operator}}\`. Only local UI state may narrow it, as in \`canTopUp && !isLoading\`. ${GUIDANCE}`, + chosen: `A server capability is chosen by a client-side condition. ${GUIDANCE}` + } + }, + create(context) { + const capabilityBindings = new Set() + const capabilityObjects = new Set() + + const isCapabilityReference = (node: AstNode): boolean => { + if (node.type === 'Identifier') return capabilityBindings.has(node.name) + if (node.type !== 'MemberExpression' || node.computed) return false + const property = node.property.name + return ( + CAPABILITY_FIELD.test(property) || + (CAPABILITY_BINDING.test(property) && + capabilityObjects.has(factName(node.object) ?? '')) + ) + } + + const isCapabilitySource = (init: AstNode | null): boolean => + isCapabilitySourceCall(init) || + (init !== null && capabilityObjects.has(factName(init) ?? '')) + + const containsCapability = (node: AstNode): boolean => + !isPendingFactCall(node) && + (isCapabilityReference(node) || childNodes(node).some(containsCapability)) + + const isCapabilityValue = (node: AstNode): boolean => { + const expression = unwrap(node) + return expression.type === 'MemberExpression' && + !expression.computed && + expression.property.name === 'value' + ? isCapabilityValue(expression.object) + : isCapabilityReference(expression) + } + + const onlyNarrowedByLocalState = (node: AstNode): boolean => + impliesCapability(node, isCapabilityValue) || + isDisabledWithoutCapability(node, isCapabilityValue) + + const onlyDefaultsCapability = (node: Ternary): boolean => + isNarrowedTernary(node, isCapabilityValue) || + isPresenceDefault(node, isCapabilityReference) + + const isUnchosenCapability = (node: Ternary): boolean => + isLiteral(node.test) || + !( + containsCapability(node.consequent) || + containsCapability(node.alternate) + ) || + onlyDefaultsCapability(node) || + isInsidePendingFact(node) + + return { + VariableDeclarator({ id, init }) { + if (id.type === 'Identifier') { + if (isCapabilitySourceCall(init)) capabilityObjects.add(id.name) + else if (init && containsCapability(init)) { + capabilityBindings.add(id.name) + } + return + } + if (id.type !== 'ObjectPattern' || !isCapabilitySource(init)) return + for (const name of destructuredCapabilities(id)) { + capabilityBindings.add(name) + } + }, + LogicalExpression(node) { + if (unwrap(node.parent).type === 'LogicalExpression') return + const operands = logicalOperands(node) + const factOperands = operands.filter((operand) => !isLiteral(operand)) + if ( + factOperands.length < 2 || + !operands.some(containsCapability) || + onlyNarrowedByLocalState(node) || + isInsidePendingFact(node) + ) { + return + } + context.report({ + node, + messageId: 'combined', + data: { operator: node.operator } + }) + }, + ConditionalExpression(node) { + if (isUnchosenCapability(node)) return + context.report({ node, messageId: 'chosen' }) + } + } + } +} + +export const noServerFactLiterals: Rule = { + meta: { + type: 'problem', + docs: { + description: + 'Prevent deriving gates from server role, tier, status or message literals' + }, + schema: [], + messages: { + compared: `\`{{field}}\` is compared with the literal '{{literal}}'. ${GUIDANCE}`, + roleFallback: `A missing role falls back to '{{literal}}'. ${GUIDANCE}`, + messageMatch: `A server message is matched as text. ${GUIDANCE}` + } + }, + create(context) { + return { + BinaryExpression(node) { + if (!EQUALITY_OPERATORS.has(node.operator)) return + const leftLiteral = stringLiteral(node.left) + const [literal, compared] = + leftLiteral === undefined + ? [stringLiteral(node.right), node.left] + : [leftLiteral, node.right] + const field = factName(compared) + if ( + literal === undefined || + field === undefined || + !(COMPARED_FACTS.get(field)?.(literal) ?? false) || + isInsidePendingFact(node) + ) { + return + } + context.report({ + node, + messageId: 'compared', + data: { field, literal } + }) + }, + LogicalExpression(node) { + const literal = stringLiteral(node.right) + if ( + !ROLE_FALLBACK_OPERATORS.has(node.operator) || + literal === undefined || + !isRoleValue(literal) || + factName(node.left) !== 'role' || + isInsidePendingFact(node) + ) { + return + } + context.report({ node, messageId: 'roleFallback', data: { literal } }) + }, + CallExpression(node) { + const callee = unwrap(node.callee) + if ( + callee.type !== 'MemberExpression' || + callee.computed || + callee.property.name !== 'includes' || + !SERVER_MESSAGE_NAME.test(factName(callee.object) ?? '') || + isInsidePendingFact(node) + ) { + return + } + context.report({ node, messageId: 'messageMatch' }) + } + } + } +}