peer-ai-standards 1.0.0-next.0

package/dist/profiles/react-native.js

@@ -0,0 +1,133 @@
+// React Native, with or without Expo. It builds on React, whose web-only rules don't match native
+// components. Examples are from a made-up bicycle repair booking service.
+export const reactNative = {
+    id: "react-native",
+    name: "React Native",
+    prefix: "RN",
+    about: "Phone apps in React Native, with or without Expo: text that follows the person's size, nothing written to the device log, secrets in the platform's secure store, and the checks a phone app needs before it's trusted with people's data. It builds on the React profile.",
+    stacks: ["react-native", "expo"],
+    extends: ["react"],
+    rules: [
+        {
+            id: "RN-01",
+            title: "Text follows the person's text size",
+            rule: "Text isn't stopped from scaling with `allowFontScaling={false}`. A layout that breaks at large sizes is fixed, such as by wrapping or scrolling, not by ignoring the setting.",
+            why: "People who set a larger text size need it to read at all; an app that ignores it is unusable to them.",
+            ask: "Does this change stop any text from following the person's text size?",
+            stage: "mvp",
+            check: "auto",
+            severity: "medium",
+            carries: "DES-14",
+            enforcer: {
+                tool: "eslint",
+                rule: "no-restricted-syntax",
+                options: [
+                    {
+                        selector: "JSXAttribute[name.name='allowFontScaling'][value.expression.value=false]",
+                        message: "RN-01: text follows the person's text size. Fix the layout instead of turning scaling off.",
+                    },
+                ],
+            },
+            examples: {
+                file: "example.tsx",
+                fails: 'import { Text } from "react-native";\nexport function Price() {\n  return <Text allowFontScaling={false}>£45 service</Text>;\n}\n',
+                passes: 'import { Text } from "react-native";\nexport function Price() {\n  return <Text>£45 service</Text>;\n}\n',
+            },
+        },
+        {
+            id: "RN-02",
+            title: "Nothing is written to the device log",
+            rule: "The app doesn't call `console`. What needs recording goes through the project's logger, which drops personal data and sends nothing from release builds.",
+            why: "On a phone, the console goes to the device log, which crash tools collect and anyone with the phone on a cable can read.",
+            ask: "Does this change call console?",
+            stage: "mvp",
+            check: "auto",
+            severity: "medium",
+            carries: "MOB-02",
+            enforcer: { tool: "eslint", rule: "no-console" },
+            examples: {
+                file: "example.ts",
+                fails: "export function signIn(email: string): void {\n  console.log(`signing in ${email}`);\n}\n",
+                passes: 'export function signIn(email: string, log: (event: string) => void): void {\n  log(email.length > 0 ? "sign-in started" : "sign-in without an email");\n}\n',
+            },
+        },
+        {
+            id: "RN-03",
+            title: "Tokens and personal data are kept in secure storage",
+            rule: "Session tokens, keys and personal data are kept in the platform's secure store, such as `expo-secure-store` or the Keychain and Keystore, never in AsyncStorage or a plain file.",
+            why: "AsyncStorage is a plain file on the device, readable from a backup or a rooted phone.",
+            ask: "Does this change keep a token or personal data outside secure storage?",
+            stage: "mvp",
+            check: "ai-review",
+            severity: "high",
+            carries: "MOB-01",
+        },
+        {
+            id: "RN-04",
+            title: "A web view opens only your own pages",
+            rule: "A `WebView` loads only the project's own pages: `originWhitelist` lists them, links elsewhere open in the system browser, and JavaScript is on only where the page needs it.",
+            why: "A web view that follows any link runs someone else's page inside the app, with whatever the app gave the web view.",
+            ask: "Can any web view in this change load a page the project doesn't own?",
+            stage: "mvp",
+            check: "ai-review",
+            severity: "high",
+            carries: "MOB-03",
+        },
+        {
+            id: "RN-05",
+            title: "A link into the app is checked before it's used",
+            rule: "Every value a deep link carries, such as an id or a URL, is checked before the app acts on it, like any other input from outside.",
+            why: "Anyone can send a link that opens the app. A link that's trusted can open a page it shouldn't, or act as the person.",
+            ask: "Does this change act on a deep link's values without checking them?",
+            stage: "mvp",
+            check: "ai-review",
+            severity: "high",
+            carries: "MOB-04",
+        },
+        {
+            id: "RN-06",
+            title: "Long lists use a list component",
+            rule: "A list that can grow long is a `FlatList`, `SectionList` or another virtualised list, not a `ScrollView` of mapped items.",
+            why: "A ScrollView draws every item at once, so the screen gets slower and uses more memory with every item.",
+            ask: "Does this change draw a list that can grow long inside a ScrollView?",
+            stage: "mvp",
+            check: "ai-review",
+            severity: "low",
+            carries: "PERF-05",
+        },
+        {
+            id: "RN-07",
+            title: "Touch targets are at least {value} points",
+            rule: "Everything a person taps is at least {value} by {value} points, using `hitSlop` where the visible part is smaller.",
+            why: "A small target is missed by people with less precise hands, and by everyone on a moving bus.",
+            ask: "Is anything tappable in this change smaller than {value} points?",
+            stage: "mvp",
+            check: "ai-review",
+            severity: "low",
+            carries: "DES-15",
+            default: { value: 44, unit: "points" },
+        },
+        {
+            id: "RN-08",
+            title: "Permissions are asked for when they're needed",
+            rule: "The app asks for a permission, such as location or the camera, when the person starts the feature that needs it, and at the least level that works, such as while in use.",
+            why: "A permission asked for at launch is refused without being understood, and a wider one than needed is a risk the person didn't agree to.",
+            ask: "Does this change ask for a permission before it's needed, or at a wider level than it needs?",
+            stage: "mvp",
+            check: "ai-review",
+            severity: "medium",
+            carries: "MOB-05",
+        },
+        {
+            id: "RN-09",
+            title: "The app can require an update",
+            rule: "At start-up, the app asks the server for the lowest version it may run, and asks the person to update when it's below it, such as with Expo Updates or a store check.",
+            why: "An installed app can't be recalled. Without a way to require an update, a version with a security hole stays in use.",
+            ask: "Can the server require people to update this app?",
+            stage: "production",
+            check: "ai-review",
+            severity: "high",
+            carries: "MOB-06",
+        },
+    ],
+};

package/dist/profiles/react.d.ts

@@ -0,0 +1,2 @@
+import type { ProfileInput } from "../profile.ts";
+export declare const react: ProfileInput;

package/dist/profiles/react.js

@@ -0,0 +1,180 @@
+// React on the web, and the base for React Native and Next.js. Examples are from a made-up
+// bicycle repair booking service.
+/** A component file `lines` lines long, of one-line components. */
+function components(lines) {
+    return `${Array.from({ length: lines }, (_, i) => `export const Bay${String(i)} = () => <li>Bay ${String(i)}</li>;`).join("\n")}\n`;
+}
+export const react = {
+    id: "react",
+    name: "React",
+    prefix: "REACT",
+    about: "React components on the web: hooks that behave, state that isn't copied, components that stay small, no HTML from outside, and the accessibility checks a linter can make. React Native and Next.js build on it.",
+    stacks: ["react"],
+    extends: ["typescript"],
+    rules: [
+        {
+            id: "REACT-01",
+            title: "Hooks are called the same way on every render",
+            rule: "Hooks are called at the top of a component or another hook, never inside a condition, a loop or a callback.",
+            why: "React matches each hook to its state by the order of the calls. A hook called conditionally gets another hook's state, a bug that appears only on some renders.",
+            ask: "Is any hook in this change called conditionally, in a loop or in a callback?",
+            stage: "prototype",
+            check: "auto",
+            severity: "high",
+            carries: "CODE-16",
+            enforcer: { tool: "eslint", rule: "react-hooks/rules-of-hooks" },
+            examples: {
+                file: "example.tsx",
+                fails: 'import { useState } from "react";\nexport function Notes({ open }: { open: boolean }) {\n  if (open) {\n    const [note] = useState("");\n    return <p>{note}</p>;\n  }\n  return null;\n}\n',
+                passes: 'import { useState } from "react";\nexport function Notes({ open }: { open: boolean }) {\n  const [note] = useState("");\n  return open ? <p>{note}</p> : null;\n}\n',
+            },
+        },
+        {
+            id: "REACT-02",
+            title: "State isn't copied from other data by an effect",
+            rule: "A value that follows from props or state is worked out during render. An effect never copies it into state of its own.",
+            why: "A copy is out of date for a render, and wrong for good when the effect misses a change.",
+            ask: "Does any effect in this change set state from other props or state?",
+            stage: "prototype",
+            check: "auto",
+            severity: "medium",
+            carries: "FE-02",
+            enforcer: { tool: "eslint", rule: "react-hooks/no-deriving-state-in-effects" },
+            examples: {
+                file: "example.tsx",
+                fails: 'import { useEffect, useState } from "react";\nexport function Total({ labour, parts }: { labour: number; parts: number }) {\n  const [total, setTotal] = useState(0);\n  useEffect(() => {\n    setTotal(labour + parts);\n  }, [labour, parts]);\n  return <p>{total}</p>;\n}\n',
+                passes: "export function Total({ labour, parts }: { labour: number; parts: number }) {\n  const total = labour + parts;\n  return <p>{total}</p>;\n}\n",
+            },
+        },
+        {
+            id: "REACT-03",
+            title: "A component file longer than {value} lines prompts a question",
+            rule: "A component file over {value} lines, not counting blank lines and comments, fails the lint, so someone asks what could move out: a hook, a child component, or plain logic. Where nothing should, a disable comment at the top says why.",
+            why: "A component that keeps growing usually holds several jobs, and every change to one re-renders and re-tests the rest.",
+            ask: "Has any component file grown past {value} lines, and does each that stays say why?",
+            stage: "mvp",
+            check: "auto",
+            severity: "low",
+            carries: "CODE-10",
+            default: { value: 150, unit: "lines" },
+            enforcer: {
+                tool: "eslint",
+                rule: "max-lines",
+                options: [{ max: "$value", skipBlankLines: true, skipComments: true }],
+                files: ["**/*.tsx", "**/*.jsx"],
+                ignores: ["**/*.test.*", "**/*.spec.*", "**/*.stories.*"],
+            },
+            examples: {
+                file: "example.tsx",
+                fails: (value) => components(Number(value) + 1),
+                passes: (value) => components(Number(value)),
+            },
+        },
+        {
+            id: "REACT-04",
+            title: "No HTML from outside is put into the page",
+            rule: "`dangerouslySetInnerHTML` isn't used. Content from outside, such as a supplier's description, is shown as text, or through a sanitiser whose use a reviewer can see.",
+            why: "HTML from outside can carry a script, which then runs as the person viewing the page.",
+            ask: "Does this change use dangerouslySetInnerHTML?",
+            stage: "prototype",
+            check: "auto",
+            severity: "high",
+            carries: "SEC-08",
+            enforcer: { tool: "eslint", rule: "react-dom/no-dangerously-set-innerhtml" },
+            examples: {
+                file: "example.tsx",
+                fails: "export function PartNotes({ html }: { html: string }) {\n  return <div dangerouslySetInnerHTML={{ __html: html }} />;\n}\n",
+                passes: "export function PartNotes({ text }: { text: string }) {\n  return <div>{text}</div>;\n}\n",
+            },
+        },
+        {
+            id: "REACT-05",
+            title: "Every control has a name a screen reader can say",
+            rule: "Every button, link and other control has a name a screen reader can announce: its text, or an `aria-label` when it shows only an icon.",
+            why: 'A button that shows only an icon is announced as "button", with nothing to say what it does.',
+            ask: "Does every control in this change have a name, including those that show only an icon?",
+            stage: "prototype",
+            check: "auto",
+            severity: "medium",
+            carries: "DES-08",
+            // Form fields are REACT-06's: a field inside its label is named, which this rule can't see.
+            enforcer: {
+                tool: "eslint",
+                rule: "jsx-a11y/control-has-associated-label",
+                options: [{ ignoreElements: ["input", "select", "textarea"] }],
+            },
+            examples: {
+                file: "example.tsx",
+                fails: 'export function Close({ onClose }: { onClose: () => void }) {\n  return (\n    <button type="button" onClick={onClose}>\n      <svg aria-hidden="true" />\n    </button>\n  );\n}\n',
+                passes: 'export function Close({ onClose }: { onClose: () => void }) {\n  return (\n    <button type="button" aria-label="Close" onClick={onClose}>\n      <svg aria-hidden="true" />\n    </button>\n  );\n}\n',
+            },
+        },
+        {
+            id: "REACT-06",
+            title: "Every label is tied to its field",
+            rule: "Every `label` is tied to its field, by wrapping it or by `htmlFor`, so the field is named when it's reached.",
+            why: "A label that sits beside a field without being tied to it isn't read out when the field is reached, so a screen reader announces an unnamed field.",
+            ask: "Is every label in this change tied to its field?",
+            stage: "prototype",
+            check: "auto",
+            severity: "medium",
+            carries: "DES-09",
+            enforcer: { tool: "eslint", rule: "jsx-a11y/label-has-associated-control", options: [{ assert: "either" }] },
+            examples: {
+                file: "example.tsx",
+                fails: 'export function Serial() {\n  return (\n    <div>\n      <label>Frame number</label>\n      <input id="serial" />\n    </div>\n  );\n}\n',
+                passes: 'export function Serial() {\n  return (\n    <label>\n      Frame number\n      <input id="serial" />\n    </label>\n  );\n}\n',
+            },
+        },
+        {
+            id: "REACT-07",
+            title: "Anything clickable works with a keyboard",
+            rule: "An element with `onClick` also answers the keyboard. Better, it's a `button` or a link, which do both.",
+            why: "A clickable `div` can't be reached or used by someone who doesn't use a mouse.",
+            ask: "Does anything clickable in this change ignore the keyboard?",
+            stage: "mvp",
+            check: "auto",
+            severity: "medium",
+            carries: "DES-10",
+            enforcer: { tool: "eslint", rule: "jsx-a11y/click-events-have-key-events" },
+            examples: {
+                file: "example.tsx",
+                fails: 'export function Cancel({ onCancel }: { onCancel: () => void }) {\n  return <div role="button" tabIndex={0} onClick={onCancel}>Cancel booking</div>;\n}\n',
+                passes: 'export function Cancel({ onCancel }: { onCancel: () => void }) {\n  return <button type="button" onClick={onCancel}>Cancel booking</button>;\n}\n',
+            },
+        },
+        {
+            id: "REACT-08",
+            title: "Server data comes through a query cache, not an effect",
+            rule: "In a component that runs in the browser, data from the server is read through the project's query cache, such as TanStack Query or SWR, not fetched in `useEffect` and kept in `useState`. Components that render on the server fetch there instead.",
+            why: "Fetching in an effect repeats the same request in every component that needs it, races when inputs change, and leaves each copy stale in its own way.",
+            ask: "Does this change fetch server data in an effect and keep it in component state?",
+            stage: "mvp",
+            check: "ai-review",
+            severity: "medium",
+            carries: "FE-01",
+        },
+        {
+            id: "REACT-09",
+            title: "Long lists draw only what's on screen",
+            rule: "A list that can grow past a screenful, such as every past booking, is virtualised, so only the rows in view are drawn.",
+            why: "Drawing every row makes the screen slower with every row the business adds.",
+            ask: "Does this change draw a list that can grow long without virtualising it?",
+            stage: "mvp",
+            check: "ai-review",
+            severity: "low",
+            carries: "PERF-05",
+        },
+        {
+            id: "REACT-10",
+            title: "An effect stops what it starts",
+            rule: "An effect that starts something, such as a timer, a subscription or a request, returns a cleanup that stops it.",
+            why: "Without cleanup, work carries on after the component is gone, and sets state nobody will see or calls the server twice.",
+            ask: "Does every effect in this change stop what it starts?",
+            stage: "mvp",
+            check: "ai-review",
+            severity: "medium",
+            carries: "PERF-06",
+        },
+    ],
+};

package/dist/profiles/typescript.d.ts

@@ -0,0 +1,2 @@
+import type { ProfileInput } from "../profile.ts";
+export declare const typescript: ProfileInput;

package/dist/profiles/typescript.js

@@ -0,0 +1,214 @@
+// TypeScript, in any runtime. Examples are from a made-up bicycle repair booking service.
+const count = (value) => Number(value);
+/** A function nested `depth` levels deep. */
+function nested(depth) {
+    const open = Array.from({ length: depth }, (_, i) => `${"  ".repeat(i + 1)}if (slots[${String(i)}] !== undefined) {`);
+    const close = Array.from({ length: depth }, (_, i) => `${"  ".repeat(depth - i)}}`);
+    return [
+        "export function firstFree(slots: (number | undefined)[]): number {",
+        ...open,
+        `${"  ".repeat(depth + 1)}return 1;`,
+        ...close,
+        "  return 0;",
+        "}",
+        "",
+    ].join("\n");
+}
+/** A function `lines` lines long, from its first line to its closing brace. */
+function longFunction(lines) {
+    const body = Array.from({ length: lines - 4 }, (_, i) => `  total += ${String(i)};`);
+    return ["export function repairTotal(): number {", "  let total = 0;", ...body, "  return total;", "}", ""].join("\n");
+}
+/** A module `lines` lines long. */
+function longModule(lines) {
+    return `${Array.from({ length: lines }, (_, i) => `export const bay${String(i)} = ${String(i)};`).join("\n")}\n`;
+}
+export const typescript = {
+    id: "typescript",
+    name: "TypeScript",
+    prefix: "TS",
+    about: "TypeScript in any runtime: the compiler at its strictest, no escape hatches from the types, and errors that can't disappear. The React, Node and backend profiles build on it.",
+    stacks: ["typescript"],
+    rules: [
+        {
+            id: "TS-01",
+            title: "The compiler is strict",
+            rule: 'Every tsconfig says `"strict": true`, so nothing is typed `any` without saying so, `null` is checked, and a caught error is `unknown` until it\'s narrowed. TypeScript 6 turns it on by default; saying so keeps it on with older compilers, and for anyone reading the file.',
+            why: "Each check strict mode turns off is a class of bug the compiler would have caught.",
+            ask: "Does every part's tsconfig say strict is on?",
+            stage: "prototype",
+            check: "auto",
+            severity: "medium",
+            carries: "CODE-14",
+            enforcer: { tool: "typescript", option: "strict", value: true },
+            examples: {
+                file: "example.ts",
+                fails: "export function deposit(price) {\n  return price / 5;\n}\n",
+                passes: "export function deposit(price: number): number {\n  return price / 5;\n}\n",
+            },
+        },
+        {
+            id: "TS-02",
+            title: "No `any` where a real type exists",
+            rule: "`any` isn't written. Data of unknown shape, such as a response from another service, is `unknown` and checked before use.",
+            why: "`any` turns the type checker off for everything it touches, and the error surfaces far from its cause.",
+            ask: "Does this change write `any`?",
+            stage: "prototype",
+            check: "auto",
+            severity: "medium",
+            carries: "CODE-14",
+            enforcer: { tool: "eslint", rule: "@typescript-eslint/no-explicit-any" },
+            examples: {
+                file: "example.ts",
+                fails: "export function bikeName(input: any): string {\n  return input.name;\n}\n",
+                passes: 'export function bikeName(input: unknown): string {\n  return typeof input === "object" && input !== null && "name" in input && typeof input.name === "string" ? input.name : "";\n}\n',
+            },
+        },
+        {
+            id: "TS-03",
+            title: "No `!` to tell the compiler a value is there",
+            rule: "A value that may be missing is checked, not asserted with `!`. Where it truly can't be missing, the types say so.",
+            why: "`!` is a promise the compiler can't check. When it's wrong, the crash comes at run time instead of a compile error.",
+            ask: "Does this change assert a value is present with `!`?",
+            stage: "mvp",
+            check: "auto",
+            severity: "low",
+            carries: "CODE-14",
+            enforcer: { tool: "eslint", rule: "@typescript-eslint/no-non-null-assertion" },
+            examples: {
+                file: "example.ts",
+                fails: "export function mechanic(names: Map<string, string>, id: string): string {\n  return names.get(id)!;\n}\n",
+                passes: 'export function mechanic(names: Map<string, string>, id: string): string {\n  return names.get(id) ?? "unassigned";\n}\n',
+            },
+        },
+        {
+            id: "TS-04",
+            title: "No empty catch",
+            rule: "A `catch` block is never empty. Where ignoring an error is right, the block logs it and says why.",
+            why: "An empty catch turns a failure into silence, and the bug report says only that something didn't happen.",
+            ask: "Does this change leave a catch block empty?",
+            stage: "prototype",
+            check: "auto",
+            severity: "high",
+            carries: "CODE-11",
+            enforcer: { tool: "eslint", rule: "no-empty", options: [{ allowEmptyCatch: false }] },
+            examples: {
+                file: "example.ts",
+                fails: "export function remind(send: () => void): void {\n  try {\n    send();\n  } catch {\n  }\n}\n",
+                passes: "export function remind(send: () => void, log: (message: string, error: unknown) => void): void {\n  try {\n    send();\n  } catch (error) {\n    // A reminder that fails mustn't cancel the booking; it's retried by the next run.\n    log(\"reminder not sent\", error);\n  }\n}\n",
+            },
+        },
+        {
+            id: "TS-05",
+            title: "Every promise is awaited or handled",
+            rule: "A promise is awaited, returned, or given a handler for its failure. One that's started and forgotten is marked with `void` and a comment saying why.",
+            why: "A forgotten promise's failure goes nowhere: the work silently doesn't happen, or crashes the process later.",
+            ask: "Does this change start a promise and not handle its failure?",
+            stage: "mvp",
+            check: "auto",
+            severity: "high",
+            carries: "CODE-11",
+            enforcer: { tool: "eslint", rule: "@typescript-eslint/no-floating-promises", typed: true },
+            examples: {
+                file: "example.ts",
+                fails: "export async function book(save: () => Promise<void>, notify: () => Promise<void>): Promise<void> {\n  await save();\n  notify();\n}\n",
+                passes: "export async function book(save: () => Promise<void>, notify: () => Promise<void>): Promise<void> {\n  await save();\n  await notify();\n}\n",
+            },
+        },
+        {
+            id: "TS-06",
+            title: "Nesting stays {value} levels deep or less",
+            rule: "Blocks nest at most {value} levels deep in a function. Deeper code handles the simple cases first and returns.",
+            why: "Each level is one more condition to hold in mind while reading the line inside it.",
+            ask: "Does any function in this change nest blocks more than {value} deep?",
+            stage: "mvp",
+            check: "auto",
+            severity: "low",
+            carries: "CODE-09",
+            default: { value: 3, unit: "levels" },
+            enforcer: { tool: "eslint", rule: "max-depth", options: [{ max: "$value" }] },
+            examples: {
+                file: "example.ts",
+                fails: (value) => nested(count(value) + 1),
+                passes: (value) => nested(count(value)),
+            },
+        },
+        {
+            id: "TS-07",
+            title: "A function longer than {value} lines prompts a question",
+            rule: "A function over {value} lines, not counting blank lines and comments, fails the lint, so someone asks whether it does two things. Where it doesn't, a disable comment beside it says why.",
+            why: "Long functions usually hide a second job, and the second job is what the next change breaks.",
+            ask: "Has any function grown past {value} lines, and does each that stays say why?",
+            stage: "mvp",
+            check: "auto",
+            severity: "low",
+            carries: "CODE-10",
+            default: { value: 60, unit: "lines" },
+            enforcer: {
+                tool: "eslint",
+                rule: "max-lines-per-function",
+                options: [{ max: "$value", skipBlankLines: true, skipComments: true }],
+            },
+            examples: {
+                file: "example.ts",
+                fails: (value) => longFunction(count(value) + 1),
+                passes: (value) => longFunction(count(value)),
+            },
+        },
+        {
+            id: "TS-08",
+            title: "A file longer than {value} lines prompts a question",
+            rule: "A file over {value} lines, not counting blank lines and comments, fails the lint, so someone asks what could move out. Where nothing should, a disable comment at the top says why.",
+            why: "A file that keeps growing is usually several modules sharing a name.",
+            ask: "Has any file grown past {value} lines, and does each that stays say why?",
+            stage: "mvp",
+            check: "auto",
+            severity: "low",
+            carries: "CODE-10",
+            default: { value: 400, unit: "lines" },
+            enforcer: {
+                tool: "eslint",
+                rule: "max-lines",
+                options: [{ max: "$value", skipBlankLines: true, skipComments: true }],
+            },
+            examples: {
+                file: "example.ts",
+                fails: (value) => longModule(count(value) + 1),
+                passes: (value) => longModule(count(value)),
+            },
+        },
+        {
+            id: "TS-09",
+            title: "A switch over a union handles every case",
+            rule: "A `switch` over a union of values handles each one, so adding a value to the union is a compile-time list of every place to change.",
+            why: "A new status that falls through to a default does whatever the default does, which is rarely right for it.",
+            ask: "Does every switch over a union in this change handle each of its values?",
+            stage: "mvp",
+            check: "auto",
+            severity: "medium",
+            carries: "CODE-15",
+            enforcer: {
+                tool: "eslint",
+                rule: "@typescript-eslint/switch-exhaustiveness-check",
+                options: [{ considerDefaultExhaustiveForUnions: false }],
+                typed: true,
+            },
+            examples: {
+                file: "example.ts",
+                fails: 'type Repair = "booked" | "in-progress" | "done";\nexport function label(repair: Repair): string {\n  switch (repair) {\n    case "booked":\n      return "Booked";\n    case "in-progress":\n      return "Being repaired";\n    default:\n      return "";\n  }\n}\n',
+                passes: 'type Repair = "booked" | "in-progress" | "done";\nexport function label(repair: Repair): string {\n  switch (repair) {\n    case "booked":\n      return "Booked";\n    case "in-progress":\n      return "Being repaired";\n    case "done":\n      return "Ready to collect";\n  }\n}\n',
+            },
+        },
+        {
+            id: "TS-10",
+            title: "A catch checks what it caught",
+            rule: "A `catch` that handles an error checks what it is, such as with `instanceof`, before using it. One that handles every kind alike says why that's safe.",
+            why: "In TypeScript every catch catches everything, so handling a network failure can also hide a bug in the code around it.",
+            ask: "Does every catch in this change check what it caught, or say why it handles all errors alike?",
+            stage: "mvp",
+            check: "ai-review",
+            severity: "medium",
+            carries: "CODE-12",
+        },
+    ],
+};

package/dist/rule.d.ts

@@ -0,0 +1,72 @@
+import { type Trait } from "peer-ai-workflow";
+import { z } from "zod";
+export declare const STAGES: readonly ["prototype", "mvp", "production"];
+export type Stage = (typeof STAGES)[number];
+export declare const SourceSchema: z.ZodObject<{
+    name: z.ZodString;
+    ref: z.ZodString;
+    url: z.ZodOptional<z.ZodURL>;
+}, z.core.$strict>;
+export declare const RuleSchema: z.ZodObject<{
+    id: z.ZodString;
+    domain: z.ZodEnum<{
+        requirements: "requirements";
+        architecture: "architecture";
+        "system-design": "system-design";
+        "api-design": "api-design";
+        frontend: "frontend";
+        mobile: "mobile";
+        "design-accessibility": "design-accessibility";
+        backend: "backend";
+        data: "data";
+        performance: "performance";
+        reliability: "reliability";
+        security: "security";
+        "privacy-compliance": "privacy-compliance";
+        testing: "testing";
+        delivery: "delivery";
+        operations: "operations";
+        "ai-features": "ai-features";
+        "code-quality": "code-quality";
+        money: "money";
+        "safety-critical": "safety-critical";
+    }>;
+    title: z.ZodString;
+    rule: z.ZodString;
+    why: z.ZodString;
+    ask: z.ZodString;
+    stage: z.ZodEnum<{
+        prototype: "prototype";
+        mvp: "mvp";
+        production: "production";
+    }>;
+    check: z.ZodEnum<{
+        auto: "auto";
+        "ai-review": "ai-review";
+        person: "person";
+    }>;
+    severity: z.ZodEnum<{
+        critical: "critical";
+        high: "high";
+        medium: "medium";
+        low: "low";
+    }>;
+    when: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        "ai-features": "ai-features";
+        money: "money";
+        "safety-critical": "safety-critical";
+        "several-audiences": "several-audiences";
+        offline: "offline";
+        "real-time": "real-time";
+        uploads: "uploads";
+    }>>>;
+    sources: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        ref: z.ZodString;
+        url: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type RuleInput = z.input<typeof RuleSchema>;
+export type Rule = z.output<typeof RuleSchema>;
+/** The traits a product needs for this rule to apply. */
+export declare function traitsNeeded(rule: Pick<Rule, "domain" | "when">): Trait[];

package/dist/rule.js

@@ -0,0 +1,39 @@
+import { CHECKS, DOMAIN_IDS, DOMAINS, SEVERITIES, TRAITS } from "peer-ai-workflow";
+import { z } from "zod";
+// What every rule has (RFC 0003): an id, the rule in plain words, why it matters, a question a
+// reviewer can answer, the stage it applies from, how it's checked, how serious breaking it
+// usually is, and where it comes from when an outside standard is the source.
+export const STAGES = ["prototype", "mvp", "production"];
+const Text = z.string().min(1);
+export const SourceSchema = z.strictObject({
+    name: Text.describe("The outside standard and its version, such as OWASP ASVS 5.0."),
+    ref: Text.describe("The requirement within it, such as 8.2.2."),
+    url: z.url().optional(),
+});
+export const RuleSchema = z
+    .strictObject({
+    id: z.string().regex(/^[A-Z][A-Z0-9]*-\d{2,}$/, "use the domain's prefix and a number, such as SEC-07"),
+    domain: z.enum(DOMAIN_IDS),
+    title: Text.max(100).describe("The rule in one short line."),
+    rule: Text.describe("The rule itself, in plain words."),
+    why: Text.describe("What goes wrong without it."),
+    ask: Text.regex(/\?$/, "the ask is a question").describe("The question a reviewer answers."),
+    stage: z.enum(STAGES).describe("The rule applies from this stage on."),
+    check: z.enum(CHECKS),
+    severity: z.enum(SEVERITIES).describe("How serious breaking it usually is, on RFC 0002's scale."),
+    when: z.array(z.enum(TRAITS)).min(1).optional().describe("The traits a product must have for the rule to apply."),
+    sources: z.array(SourceSchema).min(1).optional(),
+})
+    .superRefine((rule, ctx) => {
+    const prefix = DOMAINS[rule.domain];
+    if (!rule.id.startsWith(`${prefix}-`)) {
+        ctx.addIssue({ code: "custom", path: ["id"], message: `a ${rule.domain} rule's id starts with ${prefix}-` });
+    }
+});
+/** The sets that apply only to a product with the trait of the same name. */
+const SET_TRAITS = { money: "money", "safety-critical": "safety-critical" };
+/** The traits a product needs for this rule to apply. */
+export function traitsNeeded(rule) {
+    const set = SET_TRAITS[rule.domain];
+    return [...new Set([...(set === undefined ? [] : [set]), ...(rule.when ?? [])])];
+}