@drkmttr/adhere 0.10.0 → 0.11.0

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;
+```

package/skills/adhere/SKILL.md

@@ -94,9 +94,10 @@ Rules for the rule:
 - Jev reads code without its comments, except comments that say `@adhere`. A
   rule about comments, such as doc comments on exports, needs
   `includeComments: true` in the config.
-- Rules skip tests: `.test.ts` and `.spec.ts` files, and files under `test/`,
-  `tests/`, `__tests__/`, or `fixtures/`. A rule about tests says `tests: only`
-  in its front matter, and one that holds in tests as well `tests: include`.
+- Rules skip tests: `.test` and `.spec` files, such as `a.test.ts` and
+  `Button.spec.tsx`, and files under `test/`, `tests/`, `__tests__/`, or
+  `fixtures/`. A rule about tests says `tests: only` in its front matter, and
+  one that holds in tests as well `tests: include`.
 - A nit, or a rule that tends to flag code wrongly, says `level: warning` in
   its front matter: its findings show in amber and do not fail CI.
 - `threshold` is optional. Start without it; set it in step 5 if needed.

package/skills/adhere-fix/SKILL.md

@@ -7,8 +7,8 @@ description: Verify and fix the findings `adhere lint` reports. Decide whether e
 
 adhere is a linter for rules a normal linter cannot check. Jev, TypeSafe AI's
 model, reads each file against each rule and answers with the probability that
-the file breaks it; adhere reports each rule above a threshold, at the line Jev
-points to. A finding is a judgment, not a proof. On one rule adhere's authors
+the file breaks it; adhere reports each rule above a threshold, in the section
+of the file Jev points to. A finding is a judgment, not a proof. On one rule adhere's authors
 checked against the live API, only 1 of its 20 findings was a real violation.
 Verify every finding before you change code for it: fix the real ones, and
 report the false ones with the evidence.
@@ -34,7 +34,13 @@ Each finding shows:
 - the rule id, a preset's with its preset first, as in
   `alchemy/providers/idempotent-delete`, Jev's probability, and the rule's
   description;
-- the line Jev points at, underlined, with the code around it;
+- the section of the file Jev points at, a run of whole statements of about 30
+  lines, with the lines it names underlined, or marked with a bar when they
+  are several: usually where the violation starts, which may run on past them;
+- sometimes `warning: this file may not show enough to check this rule`: the
+  rule may turn on another file, a library, or a service. Most of these are
+  false; read what the code relies on before fixing it. Its `help:` suggests
+  an `@adhere` note, which follows the same rule as a suppression (see below);
 - `hint:`, the code the rule wants, or `never:` for a rule that only shows code
   to avoid.
 
@@ -57,7 +63,7 @@ the code under `## Must` and `## Never`, and anything it puts out of scope.
 
 Read the code as a reviewer would, not only the excerpt:
 
-- **The whole unit.** Read the function, handler, or class the line is in,
+- **The whole unit.** Read the function, handler, or class the section holds,
   and what calls it.
 - **What it calls.** Follow helpers into other files. A helper can already do
   what the rule asks, such as a delete that looks unguarded calling a client

package/src/cli.ts

@@ -99,6 +99,13 @@ const threshold = Flag.float("threshold").pipe(
   ),
 );
 
+const sufficiencyThreshold = Flag.float("sufficiency-threshold").pipe(
+  Flag.optional,
+  Flag.withDescription(
+    "Warn on a finding when Jev's probability that the file shows enough to decide it is below this value, 0 to 1. Replaces the config's sufficiencyThreshold; the default is 0.6.",
+  ),
+);
+
 const limit = Flag.integer("limit").pipe(
   Flag.filter(
     (checks) => checks >= 0,
@@ -219,7 +226,7 @@ export const auditLayer = (flags: Flags, filter: ReadonlyArray<string> = []) =>
 /** `adhere lint`: the audit. */
 export const lintCommand = Command.make(
   "lint",
-  { preset, threshold, yes, limit, rpm, filter, denyWarnings },
+  { preset, threshold, sufficiencyThreshold, yes, limit, rpm, filter, denyWarnings },
   (input) =>
     Effect.gen(function* () {
       const stdio = yield* Stdio.Stdio;
@@ -264,6 +271,7 @@ export const lintCommand = Command.make(
       {
         presets: input.preset,
         threshold: Option.getOrUndefined(input.threshold),
+        sufficiencyThreshold: Option.getOrUndefined(input.sufficiencyThreshold),
         rpm: Option.getOrUndefined(input.rpm),
       },
       input.filter,

package/src/config.ts

@@ -28,6 +28,17 @@ const RuleFields = Schema.Struct({
    * findings, which does not.
    */
   level: Schema.optionalKey(Schema.Literals(["error", "warning"])),
+  /**
+   * Where the rule applies, each a description of code that breaks it: Jev is
+   * asked of each whether any code that breaks the rule is as it describes,
+   * and a finding stands only when it says yes to every one.
+   */
+  appliesTo: Schema.optionalKey(Schema.Array(Schema.String)),
+  /**
+   * Where the rule does not apply: Jev is asked of each whether all the code
+   * that breaks the rule is as it describes, and a yes to any drops the finding.
+   */
+  excludeIf: Schema.optionalKey(Schema.Array(Schema.String)),
 });
 
 /** Before 0.7, a rule's examples were `reference` and `avoid`: read as `must` and `never`. */
@@ -112,6 +123,12 @@ export const AdhereConfig = Schema.Struct({
    * The minimum confidence threshold for a positive match. Defaults to 0.8
    */
   threshold: Schema.optionalKey(Schema.Finite),
+  /**
+   * Below this, Jev's probability that a file shows enough to decide a
+   * finding's rule adds a warning to the finding: check what the code relies
+   * on outside the file. Defaults to 0.6
+   */
+  sufficiencyThreshold: Schema.optionalKey(Schema.Finite),
   /**
    * The presets to use for rule matching. Defaults to an empty array. Current presets
    * include "effect" and "alchemy". Subcategories can be expanded by appending `/<subcategory>`.
@@ -175,13 +192,17 @@ export const SKIPPED_DIRECTORIES: ReadonlySet<string> = new Set([
 /**
  * Directories whose files are tests, matched as whole path segments below the
  * working directory, as skipped directories are. Only a rule that says `tests`
- * judges them, or a `.test.ts` or `.spec.ts` file anywhere.
+ * judges them, or a `.test` or `.spec` file, such as `a.test.tsx`, anywhere.
  */
 export const TEST_DIRECTORIES: ReadonlySet<string> = new Set([
   "test",
   "tests",
   "__tests__",
+  "testing",
   "fixtures",
+  "fixture",
+  "__fixtures__",
+  "__mocks__",
 ]);
 
 /** The shape a config file default-exports: the schema's input, where `presets` is optional. */
@@ -212,11 +233,14 @@ export type Loaded<T extends { readonly rules?: unknown }> = Omit<T, "rules"> &
 
 export const DEFAULT_MODEL = "jev-latest";
 export const DEFAULT_THRESHOLD = 0.8;
+export const DEFAULT_SUFFICIENCY_THRESHOLD = 0.6;
 
 /** A config with its presets folded in and every default applied. */
 export interface ResolvedConfig {
   readonly model: string;
   readonly threshold: number;
+  /** Below this, a finding's sufficiency adds a warning to it. */
+  readonly sufficiencyThreshold: number;
   readonly rules: Rules;
   readonly scopedRules?: RuleSet;
   /** Requests to Jev a minute, at most. Unset, requests go out as fast as they are made. */
@@ -232,6 +256,8 @@ export interface Flags {
   readonly presets?: ReadonlyArray<PresetName>;
   /** Replaces the config's global threshold. Per-rule thresholds still win. */
   readonly threshold?: number | undefined;
+  /** Replaces the config's sufficiency threshold. */
+  readonly sufficiencyThreshold?: number | undefined;
   /** Throttles requests to Jev to at most this many a minute. */
   readonly rpm?: number | undefined;
 }
@@ -271,6 +297,8 @@ export const resolveConfig = (
   return {
     model: config.model ?? last("model") ?? DEFAULT_MODEL,
     threshold: flags.threshold ?? config.threshold ?? last("threshold") ?? DEFAULT_THRESHOLD,
+    sufficiencyThreshold:
+      flags.sufficiencyThreshold ?? config.sufficiencyThreshold ?? DEFAULT_SUFFICIENCY_THRESHOLD,
     rules: Object.assign({}, ...applied.map((preset) => preset.rules), config.rules),
     ...(flags.rpm === undefined ? {} : { rpm: flags.rpm }),
     ...(config.exclude === undefined ? {} : { exclude: config.exclude }),