@drkmttr/adhere 0.9.5 → 0.11.0

package/presets/effect/testing/test-clock-for-time.md

@@ -1,8 +1,11 @@
 ---
 description: A test that depends on time must use TestClock, never a real sleep or it.live, unless the test needs real time.
+tests: only
 ---
 
-```ts must
+## Must
+
+```ts
 it.effect("time-based test", () =>
   Effect.gen(function* () {
     const fiber = yield* Effect.delay(Effect.succeed("done"), "10 seconds").pipe(Effect.forkChild);
@@ -13,7 +16,9 @@ it.effect("time-based test", () =>
 );
 ```
 
-```ts never
+## Never
+
+```ts
 it.live("retries after a delay", () =>
   Effect.gen(function* () {
     yield* Effect.sleep("2 seconds");

package/presets/react/effects/clean-up-what-they-start.md

@@ -0,0 +1,23 @@
+---
+description: An effect that subscribes to something, adds an event listener, starts a timer or an interval, or opens a connection must return a cleanup function that undoes it, never leave it running after the component unmounts or the effect runs again.
+appliesTo: ["a React effect"]
+---
+
+## Must
+
+```tsx
+useEffect(() => {
+  const onResize = () => setWidth(window.innerWidth);
+  window.addEventListener("resize", onResize);
+  return () => window.removeEventListener("resize", onResize);
+}, []);
+```
+
+## Never
+
+```tsx
+useEffect(() => {
+  const onResize = () => setWidth(window.innerWidth);
+  window.addEventListener("resize", onResize);
+}, []);
+```

package/presets/react/effects/event-logic-in-handlers.md

@@ -0,0 +1,29 @@
+---
+description: Code that runs because the user did something, such as submitting a form, clicking a button, or choosing an option, must run in that event's handler, never in an effect that watches state the handler set. An effect is for keeping a component in sync with something outside React while it is shown.
+appliesTo: ["a React component or hook"]
+---
+
+## Must
+
+```tsx
+function CheckoutForm({ cart }: { cart: Cart }) {
+  const handleSubmit = async (event: FormEvent) => {
+    event.preventDefault();
+    await placeOrder(cart);
+    showToast("Order placed");
+  };
+  return <form onSubmit={handleSubmit}>{/* fields */}</form>;
+}
+```
+
+## Never
+
+```tsx
+function CheckoutForm({ cart }: { cart: Cart }) {
+  const [submitted, setSubmitted] = useState(false);
+  useEffect(() => {
+    if (submitted) placeOrder(cart).then(() => showToast("Order placed"));
+  }, [submitted, cart]);
+  return <form onSubmit={() => setSubmitted(true)}>{/* fields */}</form>;
+}
+```

package/presets/react/effects/external-stores-use-sync-external-store.md

@@ -0,0 +1,38 @@
+---
+description: A component or hook that reads a value from a store outside React, such as a browser API like `navigator.onLine` or a store module, should subscribe to it with `useSyncExternalStore`, and should not copy the value into state from a subscription an effect sets up.
+appliesTo: ["a React component or hook"]
+---
+
+## Should
+
+```tsx
+const subscribe = (callback: () => void) => {
+  window.addEventListener("online", callback);
+  window.addEventListener("offline", callback);
+  return () => {
+    window.removeEventListener("online", callback);
+    window.removeEventListener("offline", callback);
+  };
+};
+
+export const useOnlineStatus = () =>
+  useSyncExternalStore(subscribe, () => navigator.onLine, () => true);
+```
+
+## Should not
+
+```tsx
+export function useOnlineStatus() {
+  const [isOnline, setIsOnline] = useState(true);
+  useEffect(() => {
+    const update = () => setIsOnline(navigator.onLine);
+    window.addEventListener("online", update);
+    window.addEventListener("offline", update);
+    return () => {
+      window.removeEventListener("online", update);
+      window.removeEventListener("offline", update);
+    };
+  }, []);
+  return isOnline;
+}
+```

package/presets/react/effects/fetches-ignore-stale-responses.md

@@ -0,0 +1,26 @@
+---
+description: An effect that requests data over the network must ignore or abort a response that arrives after its inputs changed or the component unmounted, such as with an `ignore` flag or an AbortController that its cleanup sets, never set state from every response in whatever order they arrive.
+appliesTo: ["a React effect"]
+---
+
+## Must
+
+```tsx
+useEffect(() => {
+  let ignore = false;
+  fetchResults(query).then((results) => {
+    if (!ignore) setResults(results);
+  });
+  return () => {
+    ignore = true;
+  };
+}, [query]);
+```
+
+## Never
+
+```tsx
+useEffect(() => {
+  fetchResults(query).then((results) => setResults(results));
+}, [query]);
+```

package/presets/react/effects/notify-parents-in-handlers.md

@@ -0,0 +1,29 @@
+---
+description: A component must tell its parent about a change, through a callback prop such as `onChange`, in the event handler that makes the change, never from an effect that watches the component's own state.
+appliesTo: ["a React component or hook"]
+---
+
+## Must
+
+```tsx
+function Toggle({ onChange }: { onChange: (isOn: boolean) => void }) {
+  const [isOn, setIsOn] = useState(false);
+  const toggle = () => {
+    setIsOn(!isOn);
+    onChange(!isOn);
+  };
+  return <button onClick={toggle}>{isOn ? "On" : "Off"}</button>;
+}
+```
+
+## Never
+
+```tsx
+function Toggle({ onChange }: { onChange: (isOn: boolean) => void }) {
+  const [isOn, setIsOn] = useState(false);
+  useEffect(() => {
+    onChange(isOn);
+  }, [isOn, onChange]);
+  return <button onClick={() => setIsOn(!isOn)}>{isOn ? "On" : "Off"}</button>;
+}
+```

package/presets/react/server/no-private-data-to-client.md

@@ -0,0 +1,23 @@
+---
+description: A Server Component must pass a Client Component only the fields it shows, never a whole database record, a secret, a token, or other data the user must not see, since every prop passed to a Client Component is sent to the browser.
+appliesTo: ["a React Server Component"]
+level: warning
+---
+
+## Must
+
+```tsx
+export default async function ProfilePage({ params }: { params: { id: string } }) {
+  const user = await db.user.findUniqueOrThrow({ where: { id: params.id } });
+  return <ProfileCard name={user.name} avatarUrl={user.avatarUrl} />;
+}
+```
+
+## Never
+
+```tsx
+export default async function ProfilePage({ params }: { params: { id: string } }) {
+  const user = await db.user.findUniqueOrThrow({ where: { id: params.id } });
+  return <ProfileCard user={user} />;
+}
+```

package/presets/react/server/server-functions-authorize-and-validate.md

@@ -0,0 +1,29 @@
+---
+description: A Server Function, one marked `"use server"`, is an endpoint any client can call with any arguments, so it must check that the caller is signed in and allowed to do what it does, and validate its arguments at runtime; it must never trust that only the app's own UI calls it.
+appliesTo: ["a Server Function, marked \"use server\""]
+---
+
+## Must
+
+```ts
+"use server";
+
+export async function deletePost(input: unknown) {
+  const session = await getSession();
+  if (!session) throw new Error("Not signed in");
+  const { postId } = DeletePostInput.parse(input);
+  const post = await db.post.findUnique({ where: { id: postId } });
+  if (post?.authorId !== session.userId) throw new Error("Not allowed");
+  await db.post.delete({ where: { id: postId } });
+}
+```
+
+## Never
+
+```ts
+"use server";
+
+export async function deletePost(postId: string) {
+  await db.post.delete({ where: { id: postId } });
+}
+```

package/presets/react/state/no-contradictory-state.md

@@ -0,0 +1,17 @@
+---
+description: State that describes one thing's status, such as whether a request is being sent, was sent, or failed, should be a single state that holds one status at a time, and should not be separate booleans that can say contradictory things at once.
+appliesTo: ["a React component or hook"]
+---
+
+## Should
+
+```tsx
+const [status, setStatus] = useState<"typing" | "sending" | "sent">("typing");
+```
+
+## Should not
+
+```tsx
+const [isSending, setIsSending] = useState(false);
+const [isSent, setIsSent] = useState(false);
+```

package/presets/react/state/no-props-copied-into-state.md

@@ -0,0 +1,23 @@
+---
+description: A component must read a prop, or compute from it, during render, never copy it into state, where the copy stops following the prop when the parent passes a new value.
+appliesTo: ["a React component or hook"]
+excludeIf: ["a prop meant only as the starting value and named for that, such as initialColor or defaultValue"]
+---
+
+## Must
+
+```tsx
+function Message({ messageColor }: { messageColor: string }) {
+  const color = messageColor;
+  return <p style={{ color }}>Hello</p>;
+}
+```
+
+## Never
+
+```tsx
+function Message({ messageColor }: { messageColor: string }) {
+  const [color, setColor] = useState(messageColor);
+  return <p style={{ color }}>Hello</p>;
+}
+```

package/presets/react/state/store-ids-not-copies.md

@@ -0,0 +1,20 @@
+---
+description: State that says which item of a list is selected, or otherwise points into data held elsewhere, should hold the item's id and look the item up during render, and should not hold a copy of the item, which goes stale when the list changes.
+appliesTo: ["a React component or hook"]
+level: warning
+---
+
+## Should
+
+```tsx
+const [items, setItems] = useState(initialItems);
+const [selectedId, setSelectedId] = useState(initialItems[0].id);
+const selectedItem = items.find((item) => item.id === selectedId);
+```
+
+## Should not
+
+```tsx
+const [items, setItems] = useState(initialItems);
+const [selectedItem, setSelectedItem] = useState(initialItems[0]);
+```

package/presets/security/constant-time-secret-compare.md

@@ -0,0 +1,22 @@
+---
+description: Code that checks a secret it received, such as a token, an API key, or an HMAC signature, must compare it in constant time, as `crypto.timingSafeEqual` or a library's verify function does, never with `===`, `!==`, or a string method.
+---
+
+## Must
+
+```ts
+const expected = createHmac("sha256", WEBHOOK_SECRET).update(body).digest();
+const received = Buffer.from(request.headers.get("x-signature") ?? "", "hex");
+if (received.length !== expected.length || !timingSafeEqual(received, expected)) {
+  return new Response("Invalid signature", { status: 401 });
+}
+```
+
+## Never
+
+```ts
+const expected = createHmac("sha256", WEBHOOK_SECRET).update(body).digest("hex");
+if (request.headers.get("x-signature") !== expected) {
+  return new Response("Invalid signature", { status: 401 });
+}
+```

package/presets/security/no-secrets-in-output.md

@@ -0,0 +1,19 @@
+---
+description: A secret, such as a password, an API key, a token, a private key, a session id, or a connection string with credentials, must never be written to a log, put in an error message, or returned in an HTTP response; code must refer to a secret only by its name, its presence, or a non-secret id.
+appliesTo: ["code that writes a log, builds an error message, or builds an HTTP response"]
+excludeIf: ["a masked secret that shows at most a few of its characters"]
+---
+
+## Must
+
+```ts
+logger.info("calling billing", { keyId: apiKey.id });
+throw new Error(`Could not connect to the database at ${dbHost}`);
+```
+
+## Never
+
+```ts
+logger.info(`calling billing with key ${apiKey.secret}`);
+throw new Error(`Could not connect to ${process.env.DATABASE_URL}`);
+```

package/presets/security/no-untrusted-input-in-commands-or-paths.md

@@ -0,0 +1,18 @@
+---
+description: Input from outside the program, such as a request's parameters or body, must reach a shell command only as a separate argument, and a file path only after the resolved path is checked to be inside the directory meant for it; it must never be interpolated into a command string, passed to `eval` or `new Function`, or joined into a path unchecked.
+---
+
+## Must
+
+```ts
+const file = resolve(UPLOADS, request.params.name);
+if (!file.startsWith(UPLOADS + sep)) return new Response("Not found", { status: 404 });
+const { stdout } = await execFile("ffprobe", ["-show_format", file]);
+```
+
+## Never
+
+```ts
+const file = join(UPLOADS, request.params.name);
+const { stdout } = await exec(`ffprobe -show_format ${file}`);
+```

package/presets/security/parameterized-queries.md

@@ -0,0 +1,16 @@
+---
+description: A SQL query that includes a value that comes from outside the code, such as user input or a function's argument, must pass it as a bound parameter, or through a query builder or tagged template that binds it, never concatenate or interpolate the value into the query string.
+excludeIf: ["an identifier, such as a table or column name, the code chose from a fixed list"]
+---
+
+## Must
+
+```ts
+const { rows } = await db.query("SELECT * FROM users WHERE email = $1", [email]);
+```
+
+## Never
+
+```ts
+const { rows } = await db.query(`SELECT * FROM users WHERE email = '${email}'`);
+```

package/presets/typescript/async/concurrent-independent-work.md

@@ -0,0 +1,23 @@
+---
+description: Awaited calls that do not depend on each other's results should run concurrently, with `Promise.all` or `Promise.allSettled`, and should not be awaited one after another or one per loop iteration.
+excludeIf: ["calls that must run in order, such as writes whose order matters", "calls spaced out on purpose, such as to respect a rate limit"]
+level: warning
+---
+
+## Should
+
+```ts
+const [user, orders, preferences] = await Promise.all([
+  getUser(userId),
+  getOrders(userId),
+  getPreferences(userId),
+]);
+```
+
+## Should not
+
+```ts
+const user = await getUser(userId);
+const orders = await getOrders(userId);
+const preferences = await getPreferences(userId);
+```

package/presets/typescript/async/network-calls-have-timeouts.md

@@ -0,0 +1,19 @@
+---
+description: An HTTP request, such as a `fetch` or a call through an HTTP client, should carry a timeout or an AbortSignal that ends it, and should not wait without limit.
+excludeIf: ["a call through a client configured with a default timeout", "a call whose signal the caller passes in", "a request from browser code to the app's own API"]
+level: warning
+---
+
+## Should
+
+```ts
+const response = await fetch(`${BILLING_URL}/invoices/${id}`, {
+  signal: AbortSignal.timeout(5_000),
+});
+```
+
+## Should not
+
+```ts
+const response = await fetch(`${BILLING_URL}/invoices/${id}`);
+```

package/presets/typescript/design/no-argument-mutation.md

@@ -0,0 +1,20 @@
+---
+description: A function must return a changed copy of an object or array it received as an argument, never mutate the argument, such as by sorting it in place, pushing to it, deleting a key, or assigning to a property, where its caller does not expect the change.
+excludeIf: ["a function whose name says it changes its argument, such as sortInPlace", "an accumulator the function builds, such as a reduce callback's"]
+---
+
+## Must
+
+```ts
+const byNewest = (posts: ReadonlyArray<Post>) =>
+  posts.toSorted((a, b) => b.publishedAt.getTime() - a.publishedAt.getTime());
+```
+
+## Never
+
+```ts
+const byNewest = (posts: Post[]) => {
+  posts.sort((a, b) => b.publishedAt.getTime() - a.publishedAt.getTime());
+  return posts;
+};
+```

package/presets/typescript/errors/no-swallowed-errors.md

@@ -0,0 +1,29 @@
+---
+description: A caught error must be handled, rethrown, or returned as a failure the caller can tell apart from success, never discarded or turned into a value that reads as a successful result, such as `null`, an empty array, or a default. Logging an error and carrying on as if nothing failed discards it. Recovering from one specific, expected error, such as a missing file that has a default, handles it.
+---
+
+## Must
+
+```ts
+async function loadSettings(path: string): Promise<Settings> {
+  try {
+    return parseSettings(await readFile(path, "utf8"));
+  } catch (error) {
+    if (isNotFound(error)) return DEFAULT_SETTINGS;
+    throw new Error(`Could not load settings from ${path}`, { cause: error });
+  }
+}
+```
+
+## Never
+
+```ts
+async function loadInvoices(customerId: string): Promise<Invoice[]> {
+  try {
+    return await api.invoices.list({ customerId });
+  } catch (error) {
+    console.error(error);
+    return [];
+  }
+}
+```

package/presets/typescript/errors/release-on-every-path.md

@@ -0,0 +1,29 @@
+---
+description: A resource the code acquires and must give back, such as a file handle, a lock, a database connection or transaction, a temporary file, or a child process, must be released on every path, including when an error is thrown between acquiring and releasing it, with `finally` or `using`; it must never be released only after the work succeeds. A resource whose owner releases it, such as a framework or a pool's query method, is out of scope.
+---
+
+## Must
+
+```ts
+const client = await pool.connect();
+try {
+  await client.query("BEGIN");
+  await client.query("UPDATE accounts SET balance = balance - $1 WHERE id = $2", [amount, from]);
+  await client.query("COMMIT");
+} catch (error) {
+  await client.query("ROLLBACK");
+  throw error;
+} finally {
+  client.release();
+}
+```
+
+## Never
+
+```ts
+const client = await pool.connect();
+await client.query("BEGIN");
+await client.query("UPDATE accounts SET balance = balance - $1 WHERE id = $2", [amount, from]);
+await client.query("COMMIT");
+client.release();
+```

package/presets/typescript/testing/assert-outcomes.md

@@ -0,0 +1,22 @@
+---
+description: A test must assert what the code under test returned or did, such as its result, what it rendered, or the state it left, never only that it ran without throwing or returned something defined.
+tests: only
+---
+
+## Must
+
+```ts
+it("applies the discount to each line", () => {
+  const total = checkout([{ price: 100, quantity: 2 }], { discount: 0.1 });
+  expect(total).toBe(180);
+});
+```
+
+## Never
+
+```ts
+it("applies the discount to each line", () => {
+  const total = checkout([{ price: 100, quantity: 2 }], { discount: 0.1 });
+  expect(total).toBeDefined();
+});
+```

package/presets/typescript/testing/independent-tests.md

@@ -0,0 +1,41 @@
+---
+description: A test must set up the state it needs itself, or in a `beforeEach`, and must never rely on state another test left behind, such as a module-level variable, a record another test inserted, or a mock another test configured.
+excludeIf: ["state a suite sets up once for all its tests, in beforeAll or its body, that no test changes"]
+tests: only
+---
+
+## Must
+
+```ts
+let cart: Cart;
+beforeEach(() => {
+  cart = new Cart();
+});
+
+it("adds an item", () => {
+  cart.add(book);
+  expect(cart.items).toEqual([book]);
+});
+
+it("totals its items", () => {
+  cart.add(book);
+  cart.add(pen);
+  expect(cart.total()).toBe(book.price + pen.price);
+});
+```
+
+## Never
+
+```ts
+const cart = new Cart();
+
+it("adds an item", () => {
+  cart.add(book);
+  expect(cart.items).toEqual([book]);
+});
+
+it("totals its items", () => {
+  cart.add(pen);
+  expect(cart.total()).toBe(book.price + pen.price);
+});
+```

package/presets/typescript/types/assertions-only-when-proven.md

@@ -0,0 +1,20 @@
+---
+description: A type assertion with `as`, or a non-null assertion with `!`, should claim only what the code around it has already established, and should not be used to make a type error go away. `as const` claims nothing and is out of scope.
+excludeIf: ["data read from outside the program, such as a parsed body or a fetch response"]
+level: warning
+---
+
+## Should
+
+```ts
+const input = document.querySelector("#email");
+if (!(input instanceof HTMLInputElement)) throw new Error("#email is not an input");
+input.value = email;
+```
+
+## Should not
+
+```ts
+const input = document.querySelector("#email") as HTMLInputElement;
+input.value = email;
+```

package/presets/typescript/types/derive-dont-restate.md

@@ -0,0 +1,24 @@
+---
+description: A type that describes the same data as another type, a schema, a function, or a constant should be derived from it, with a utility type such as `Pick`, with `typeof` or `keyof`, or as a schema's inferred type, and should not restate its fields or values by hand.
+level: warning
+---
+
+## Should
+
+```ts
+const ROLES = ["admin", "member", "guest"] as const;
+type Role = (typeof ROLES)[number];
+
+const User = z.object({ id: z.string(), email: z.string(), role: z.enum(ROLES) });
+type User = z.infer<typeof User>;
+```
+
+## Should not
+
+```ts
+const ROLES = ["admin", "member", "guest"];
+type Role = "admin" | "member" | "guest";
+
+const User = z.object({ id: z.string(), email: z.string(), role: z.enum(ROLES) });
+type User = { id: string; email: string; role: Role };
+```

package/presets/typescript/types/unrepresentable-invalid-states.md

@@ -0,0 +1,23 @@
+---
+description: A type whose fields are valid only in some combinations must be a union with one member per state, each carrying only the fields that state has, never one object type of optional fields and flags whose valid combinations only the code that reads them knows. A union of Schema.TaggedClass members is such a union.
+appliesTo: ["a declared type, interface, or schema"]
+---
+
+## Must
+
+```ts
+type Request<T> =
+  | { status: "loading" }
+  | { status: "ok"; data: T }
+  | { status: "error"; error: Error };
+```
+
+## Never
+
+```ts
+interface Request<T> {
+  loading: boolean;
+  data?: T;
+  error?: Error;
+}
+```

package/presets/typescript/types/validate-external-data.md

@@ -0,0 +1,21 @@
+---
+description: Data from outside the program, such as a parsed request body, a fetch response, a file's contents, a message, or an environment variable, must be checked at runtime before code gives it a type, never cast with `as` or assigned from `any` to a declared type. A schema's parse or decode, such as Zod's or Effect Schema's, or a type guard that checks each field it claims, is a runtime check.
+appliesTo: ["code that reads data from outside the program"]
+excludeIf: ["a value read through a typed client of the program's own database"]
+---
+
+## Must
+
+```ts
+const User = z.object({ id: z.string(), email: z.string().email() });
+
+const response = await fetch(`/api/users/${id}`);
+const user = User.parse(await response.json());
+```
+
+## Never
+
+```ts
+const response = await fetch(`/api/users/${id}`);
+const user = (await response.json()) as User;
+```