From a9f25be76f24bdf2ec163565fcfb99451246431d Mon Sep 17 00:00:00 2001 From: Dante Date: Sat, 10 Oct 2026 02:09:53 +0000 Subject: [PATCH] FE-3350 / FE-3351 / FE-3352 / FE-3353 feat: server-fact guardrails (ADR, changed-line lint gate, agent hooks) (#20679) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit > **This PR now carries the whole short-term stack.** The approved children were folded into this branch: #20681 (S2 server-fact oxlint rules + changed-line gate, FE-3351) and #20682 (S3/S4 write and approve hooks, FE-3352 / FE-3353). Each was reviewed and approved on its own PR. The reviewer-visible diff since the docs-only version is those two PRs plus two ADR wording commits: `83e85827ef` (rule 1 scoped to entitlement; local UI state may only narrow) and `2c6455a3bd` (enforcement described as planned per ticket, per CodeRabbit). Agents keep writing, and approving, frontend code that recombines server facts (capabilities, role, tier, plan status, seats, timestamps) into decisions the backend owns. The latest case shipped two billing P0s (BE-19903, BE-19904) through #15675, #18662 and #19455. About 20 fixes since April moved a decision back to the server. There is no repo-level rule for this. The one piece of guidance that touches it points the other way: `docs/guidance/state-and-effects.md` says "Derive everything derivable", and its first example is a `can*` flag. A reviewer-side prose rule existed, and #18662 and #19455 were approved anyway. - **`docs/adr/API-SERVER-FACTS-0042`** records the rule (R1–R5): a gate renders one server fact as received; `isCloud` picks the build, not the permission; failed reads use contract defaults, never role or tier fallbacks; a missing fact is a backend ticket plus `pendingServerFact`. It also records the rejected alternatives. - **`AGENTS.md`** gets one Common Pitfalls line linking the ADR, so every author's agent reads it. - **`state-and-effects.md` §4** now scopes "derive everything derivable" to state the feature owns, and sends server facts to the API. The `canTransition` example is dropped. Enforcement (lint rules, write and approve hooks, orthogonality tests, the `pendingServerFact` expiry check) follows in the sibling tickets below. This PR is the text those checks link to. Docs only. There is no UI change. | | AS IS | TO BE | |---|---|---| | Repo rule | none | ADR + `AGENTS.md` line | | `state-and-effects.md` §4 | "derive everything derivable", `canTransition` example | feature-owned state only; server facts render the API field | TDD: [Server-fact guardrails](https://app.notion.com/p/3f46d73d36508162ae1be360e6403b5b). Parent: FE-3349. | Item | Ticket | PR | Status | |---|---|---|---| | **S1 ADR + AGENTS.md + guidance** | **FE-3350** | **this PR** | **In review** | | S2 oxlint rules, diff-scoped gate | FE-3351 | — | Next | | S3 write hook | FE-3352 | — | Blocked by S2 | | S4 approve hook | FE-3353 | — | Blocked by S2 | | S5 `pendingServerFact` + expiry CI | FE-3354 | — | Needs `LINEAR_API_KEY` secret | | S6 orthogonality tests + CODEOWNERS | FE-3355 | — | After #20674 | | S7 cloud agent instructions | FE-3356 | — | Blocked by S1 | ```mermaid graph LR S1["S1 ADR (this PR)"]:::current --> S7["S7 cloud AGENTS.md"] S2["S2 oxlint rules"] --> S3["S3 write hook"] S2 --> S4["S4 approve hook"] S5["S5 pendingServerFact"] S6["S6 orthogonality tests"] P20674["PR 20674 member capabilities"] --> S6 classDef current fill:#f9d71c,stroke:#333,stroke-width:2px ``` (cherry picked from commit a67953153e68e04f172cfff175130804d4da50b0) --- .claude/settings.json | 24 + .github/workflows/ci-lint-format-queue.yaml | 20 +- .github/workflows/ci-lint-format.yaml | 18 + AGENTS.md | 6 + ...2-server-facts-are-rendered-not-derived.md | 124 +++++ docs/adr/README.md | 1 + docs/guidance/state-and-effects.md | 12 +- lint-staged.config.ts | 3 + package.json | 1 + .../hooks/server-fact-approve-guard.test.ts | 193 +++++++ scripts/hooks/server-fact-approve-guard.ts | 296 +++++++++++ scripts/hooks/server-fact-hook.test.ts | 100 ++++ scripts/hooks/server-fact-hook.ts | 169 ++++++ scripts/hooks/server-fact-write-guard.test.ts | 286 ++++++++++ scripts/hooks/server-fact-write-guard.ts | 211 ++++++++ scripts/lint-staged-config.test.ts | 18 + scripts/server-fact-gate-core.ts | 118 +++++ scripts/server-fact-gate.test.ts | 256 +++++++++ scripts/server-fact-gate.ts | 61 +++ scripts/server-fact-oxlint.ts | 79 +++ tools/oxlint-plugins/comfy.ts | 12 + .../oxlint-plugins/serverFacts.oxlintrc.json | 10 + tools/oxlint-plugins/serverFacts.test.ts | 336 ++++++++++++ tools/oxlint-plugins/serverFacts.ts | 488 ++++++++++++++++++ 24 files changed, 2838 insertions(+), 4 deletions(-) create mode 100644 docs/adr/API-SERVER-FACTS-0042-server-facts-are-rendered-not-derived.md create mode 100644 scripts/hooks/server-fact-approve-guard.test.ts create mode 100644 scripts/hooks/server-fact-approve-guard.ts create mode 100644 scripts/hooks/server-fact-hook.test.ts create mode 100644 scripts/hooks/server-fact-hook.ts create mode 100644 scripts/hooks/server-fact-write-guard.test.ts create mode 100644 scripts/hooks/server-fact-write-guard.ts create mode 100644 scripts/server-fact-gate-core.ts create mode 100644 scripts/server-fact-gate.test.ts create mode 100644 scripts/server-fact-gate.ts create mode 100644 scripts/server-fact-oxlint.ts create mode 100644 tools/oxlint-plugins/serverFacts.oxlintrc.json create mode 100644 tools/oxlint-plugins/serverFacts.test.ts create mode 100644 tools/oxlint-plugins/serverFacts.ts 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' }) + } + } + } +}