@rdjperron/lint 0.1.0 → 0.2.0

package/docs/rules/no-conditional-empty-object-spread.md

@@ -0,0 +1,50 @@
+# rdj/no-conditional-empty-object-spread
+
+Rejects a spread inside an object literal whose argument is a conditional with `{}` on either
+branch.
+
+## Why
+
+`...(value !== undefined ? { value } : {})` is how a field becomes optional without anyone
+saying so. The object's keys can only be read by evaluating the conditional, so a reviewer
+counting the keys of the literal gets the wrong answer. The rule ships no autofix on purpose,
+and a test asserts that: any rewrite changes which keys the object ends up with.
+
+## Rejected
+
+```ts
+const result = { ...(value !== undefined ? { value } : {}) };
+```
+
+> This conditional spread hides property omission behind an empty object. Build the object in
+> separate statements and add the property only when present.
+
+```ts
+const result = { ...(condition ? {} : { value }) };
+```
+
+> This conditional spread hides property omission behind an empty object. Build the object in
+> separate statements and add the property only when present.
+
+## Accepted
+
+```ts
+const result = { value };
+```
+
+```ts
+const result = condition ? { value } : {};
+```
+
+## Options
+
+None.
+
+## When it is right to turn it off
+
+Nothing needs it off. Building the object in statements and adding the property inside an `if`
+produces the same object and states the omission where a reader looks for it.
+
+## Origin
+
+Vendored from dmmulroy/anti-slop, commit `c44ef22ca116d0ba62a3ff663a0bd13a3f3fa40b`.

package/docs/rules/no-hardcoded-jsx-text.md

@@ -0,0 +1,52 @@
+# rdj/no-hardcoded-jsx-text
+
+Rejects a word written straight into JSX children, whether as text or as a string literal child.
+
+## Why
+
+A string typed into a component is a string no translator will ever see, and it is found only
+when someone reads that file again. Sending every visible word through the dictionary makes the
+set of strings on screen countable. The rule looks at JSX text and at a string literal placed
+among an element's children. It never looks at attribute values, so `alt="Company logo"` is out
+of scope and needs a different check.
+
+## Rejected
+
+```tsx
+const a = <button>Save changes</button>;
+```
+
+> Do not write words straight into JSX. Every string on screen comes from the translation
+> dictionary.
+
+```tsx
+const a = <p>{"Hello world"}</p>;
+```
+
+> Do not write words straight into JSX. Every string on screen comes from the translation
+> dictionary.
+
+## Accepted
+
+```tsx
+const a = <p>{t("save")}</p>;
+```
+
+```tsx
+const a = <p>2026</p>;
+```
+
+## Options
+
+`pattern`, a regex source compiled with the `u` flag, default `\p{L}{3,}`. Three letters in a
+row is a word, so digits, separators and bullets are not. A project that only ships Latin
+script can narrow it, for example `[A-Za-zÀ-ÿ]{3,}`.
+
+## When it is right to turn it off
+
+A surface no user reads in their own language: a debug screen, a developer tools panel, a
+component gallery. Scope it to those files and keep it on everywhere a user can arrive.
+
+## Origin
+
+Written in this package.

package/docs/rules/no-known-value-widening.md

@@ -0,0 +1,62 @@
+# rdj/no-known-value-widening
+
+Rejects a value the file already describes flowing into an explicitly broad target type.
+
+## Why
+
+When a literal whose keys are right there is annotated `Record<string, Command>`, the compiler
+forgets which keys exist and `commands.strat` type checks. The annotation looks like extra
+rigour and is the opposite. The rule names what the target discarded: `unknown`, `object`,
+`open dictionary` (a broad-keyed `Record`, an index signature, a mapped type), `anonymous
+object` and `generic container`. It also fires on a call that hands a known value to a type
+guard whose parameter is `unknown`, because the guard then has nothing left to decide.
+
+## Rejected
+
+```ts
+type Command = () => void;
+const startCommand = () => {};
+const commands: Record<string, Command> = { start: startCommand };
+```
+
+> The explicit open dictionary type on binding `commands` discards known type evidence. Keep
+> inference, validate with `satisfies`, or use a named owner contract.
+
+```ts
+function isString(value: unknown): value is string {
+  return true;
+}
+isString("known");
+```
+
+> The explicit unknown type on argument for parameter `value` of `isString` discards known type
+> evidence. Keep inference, validate with `satisfies`, or use a named owner contract.
+
+## Accepted
+
+```ts
+const commands = { start: startCommand } satisfies Record<string, Command>;
+```
+
+```ts
+interface Commands {
+  readonly start: Command;
+}
+const commands: Commands = { start: startCommand };
+```
+
+An empty literal keeps its broad annotation: `const commands: Record<string, Command> = {}` is
+accepted, because an accumulator that starts empty has no evidence to discard.
+
+## Options
+
+None.
+
+## When it is right to turn it off
+
+Nothing measured needed it off. `satisfies` and a named interface cover the annotate-for-safety
+habit, and the empty accumulator is already exempt.
+
+## Origin
+
+Vendored from dmmulroy/anti-slop, commit `c44ef22ca116d0ba62a3ff663a0bd13a3f3fa40b`.

package/docs/rules/no-module-mocking.md

@@ -0,0 +1,53 @@
+# rdj/no-module-mocking
+
+Rejects `vi.mock`, `vi.doMock`, `jest.mock` and `jest.unstable_mockModule`.
+
+## Why
+
+A module mock replaces a dependency by file path, so the test exercises the mock and proves
+nothing about the seam the code actually uses. When the real module's API changes the test
+keeps passing. It also makes a test unreadable in isolation, since the behaviour under test is
+defined in a factory somewhere above the assertions. The rule resolves the object rather than
+trusting the name: a global `vi` or `jest` counts, so does one imported from `vitest` or
+`@jest/globals` under any alias, and a local object of your own does not.
+
+## Rejected
+
+```ts
+import { vi } from "vitest";
+vi.mock("./user-store");
+```
+
+> Replace module mocking with dependency injection through a real interface, service layer, or
+> faithful test implementation.
+
+```ts
+jest.unstable_mockModule("./user-store");
+```
+
+> Replace module mocking with dependency injection through a real interface, service layer, or
+> faithful test implementation.
+
+## Accepted
+
+```ts
+const store = new InMemoryUserStore();
+```
+
+```ts
+vi.spyOn(store, "save");
+```
+
+## Options
+
+None.
+
+## When it is right to turn it off
+
+A third-party module with no injectable seam, where the only way to reach a branch is to
+replace the module itself. Scope the override to that test file and say which dependency has
+no seam, so the exception disappears when the seam is added.
+
+## Origin
+
+Vendored from dmmulroy/anti-slop, commit `c44ef22ca116d0ba62a3ff663a0bd13a3f3fa40b`.

package/docs/rules/no-object-parameters.md

@@ -0,0 +1,55 @@
+# rdj/no-object-parameters
+
+Rejects a function parameter annotated `object`, including through a local alias that resolves
+to `object`.
+
+## Why
+
+`object` tells a caller only that the value is not a primitive. Every field read inside the
+body then needs a cast, an index signature or `Reflect`, and the call site gets no help at all.
+The rule resolves aliases, so `type Bag = object` does not hide it, and it follows generic
+aliases such as `Identity<object>`. A type parameter constrained by `object` is a different
+claim and stays legal.
+
+## Rejected
+
+```ts
+type Bag = object;
+function consume(value: Bag): void {}
+```
+
+> Parameter `value` uses the broad `object` type. Accept a named owner type; parse external
+> input at its boundary before calling this function.
+
+```ts
+function consume({ value }: object = {}): void {}
+```
+
+> Parameter `{ value }` uses the broad `object` type. Accept a named owner type; parse external
+> input at its boundary before calling this function.
+
+## Accepted
+
+```ts
+interface Owner {
+  readonly id: string;
+}
+function consume(value: Owner): void {}
+```
+
+```ts
+function consume<Value extends object>(value: Value): void {}
+```
+
+## Options
+
+None.
+
+## When it is right to turn it off
+
+A declaration file that mirrors a third-party signature you do not own, where narrowing the
+parameter would misdescribe what the library accepts. Scope it to the declaration file.
+
+## Origin
+
+Vendored from dmmulroy/anti-slop, commit `c44ef22ca116d0ba62a3ff663a0bd13a3f3fa40b`.

package/docs/rules/no-reduce-accumulator-copy.md

@@ -0,0 +1,57 @@
+# rdj/no-reduce-accumulator-copy
+
+Rejects a reducer callback that copies its own accumulator on every step.
+
+## Why
+
+`Object.assign({}, acc, item)` inside a `reduce` allocates a new object per element and copies
+everything collected so far, so the work grows with the square of the input. The pattern reads
+as careful immutability and is a performance bug at any real size. The rule covers
+`Object.assign` into a fresh literal, `Array.from(acc)`, and `concat`, `slice`, `toSpliced`,
+`toSorted`, `toReversed` and `with` on an accumulator whose initial value is a known array. It
+follows a `const` alias of the accumulator. The spread form, `[...acc, item]`, belongs to
+`oxc/no-accumulating-spread` and is deliberately left alone here.
+
+## Rejected
+
+```ts
+items.reduce((acc, item) => Object.assign({}, acc, { [item.id]: item }), {});
+```
+
+> Do not copy the reducer accumulator on every iteration; growing copies can cause quadratic
+> work. Mutate a fresh, locally owned accumulator and return it, or use an iterator
+> pipeline/flatMap.
+
+```ts
+items.reduce((acc, item) => acc.concat([item]), []);
+```
+
+> Do not copy the reducer accumulator on every iteration; growing copies can cause quadratic
+> work. Mutate a fresh, locally owned accumulator and return it, or use an iterator
+> pipeline/flatMap.
+
+## Accepted
+
+```ts
+items.reduce((acc, item) => {
+  acc.push(item);
+  return acc;
+}, []);
+```
+
+```ts
+items.reduce((acc, item) => Object.assign(acc, item), {});
+```
+
+## Options
+
+None.
+
+## When it is right to turn it off
+
+Nothing needs it off. The accumulator passed to `reduce` is owned by the reduction, so mutating
+it and returning it is safe and is what the message asks for.
+
+## Origin
+
+Vendored from dmmulroy/anti-slop, commit `c44ef22ca116d0ba62a3ff663a0bd13a3f3fa40b`.

package/docs/rules/no-reflect-apply.md

@@ -0,0 +1,56 @@
+# rdj/no-reflect-apply
+
+Rejects `Reflect.apply` on the global `Reflect`.
+
+## Why
+
+`Reflect.apply(operation, owner, args)` takes the arguments as an array, so the checker sees
+nothing about arity or argument types and every mistake surfaces at runtime. The call also
+hides who is being called, which is the one thing a reader wants from a dispatch site. The rule
+resolves the receiver, so a local object or parameter named `Reflect` is not reported. The
+computed spelling `Reflect["apply"]` is.
+
+## Rejected
+
+```ts
+const value = Reflect.apply(operation, owner, args);
+```
+
+> Replace `Reflect.apply` with a typed function call. Model dynamic dispatch behind a named
+> interface.
+
+```ts
+const value = Reflect["apply"](operation, owner, args);
+```
+
+> Replace `Reflect.apply` with a typed function call. Model dynamic dispatch behind a named
+> interface.
+
+## Accepted
+
+```ts
+const value = operation.apply(owner, args);
+```
+
+```ts
+const Reflect = {
+  apply() {
+    return 1;
+  },
+};
+Reflect.apply();
+```
+
+## Options
+
+None.
+
+## When it is right to turn it off
+
+A `Proxy` `apply` trap, where forwarding with `Reflect.apply(target, thisArg, args)` is the
+documented way to keep the original behaviour. Scope the override to the file that defines the
+proxy.
+
+## Origin
+
+Vendored from dmmulroy/anti-slop, commit `c44ef22ca116d0ba62a3ff663a0bd13a3f3fa40b`.

package/docs/rules/no-reflect-get.md

@@ -0,0 +1,51 @@
+# rdj/no-reflect-get
+
+Rejects `Reflect.get` on the global `Reflect`.
+
+## Why
+
+`Reflect.get(owner, key)` returns `any` and asks the checker no questions, so a misspelled key
+and a renamed field both survive to runtime. It is usually reached for when the value was never
+parsed into a type that has the field. Plain property access says the same thing and gets
+checked. The rule resolves the receiver, so a local object or parameter named `Reflect` is not
+reported, and it catches the computed spelling `Reflect["get"]`.
+
+## Rejected
+
+```ts
+const value = Reflect.get(owner, key);
+```
+
+> Replace `Reflect.get` with typed property access. Parse dynamic input into a named domain type
+> before reading it.
+
+```ts
+const value = Reflect["get"](owner, key);
+```
+
+> Replace `Reflect.get` with typed property access. Parse dynamic input into a named domain type
+> before reading it.
+
+## Accepted
+
+```ts
+const value = owner.property;
+```
+
+```ts
+const value = owner[key];
+```
+
+## Options
+
+None.
+
+## When it is right to turn it off
+
+A `Proxy` `get` trap, where `Reflect.get(target, key, receiver)` forwards with the right
+receiver and writing `target[key]` would break getters on the prototype chain. Scope the
+override to the file that defines the proxy.
+
+## Origin
+
+Vendored from dmmulroy/anti-slop, commit `c44ef22ca116d0ba62a3ff663a0bd13a3f3fa40b`.

package/docs/rules/no-runtime-typeof.md

@@ -0,0 +1,61 @@
+# rdj/no-runtime-typeof
+
+Rejects every `typeof` operator except one compared against the string `"undefined"`.
+
+## Why
+
+`typeof value === "string"` tells you how the value is represented, not what it means or where
+it came from. Narrowing this way scatters half a parser across the branches that consume the
+value, and each branch has to guess again. The fix is to decode the value once, at the boundary
+where it arrives, and branch on the result. Probing whether a binding exists at all,
+`typeof document === "undefined"`, is a different question and stays allowed.
+
+## Rejected
+
+```ts
+if (typeof input === "string") use(input);
+```
+
+> A `typeof` check narrows a representation without establishing its contract. Parse input at
+> its I/O boundary, then branch on the domain value.
+
+```ts
+function parse(value: unknown): string {
+  if (typeof value !== "string") throw new Error();
+  return value;
+}
+```
+
+> A `typeof` check narrows a representation without establishing its contract. Parse input at
+> its I/O boundary, then branch on the domain value.
+
+## Accepted
+
+```ts
+const isServer = typeof document === "undefined";
+```
+
+```ts
+// with { allowInTypeGuards: true }
+function isString(value: unknown): value is string {
+  return typeof value === "string";
+}
+```
+
+## Options
+
+`allowInTypeGuards`, boolean, default `false`. When true, a `typeof` is allowed if the nearest
+enclosing function returns a type predicate, `value is T` or `asserts value is T`. Nearest is
+literal: a callback declared inside the guard is still reported, since its own return type is
+not a predicate.
+
+## When it is right to turn it off
+
+Decoder modules, the one place per kind of outside value where a route param, a stored blob or
+a token payload becomes a named type. There `typeof` is the parse the rule asks for, not a
+substitute for one. Tests are the other case: `expect(typeof api.run).toBe("function")` asserts
+the shape of your own public API, which the rule reads as unparsed input.
+
+## Origin
+
+Vendored from dmmulroy/anti-slop, commit `c44ef22ca116d0ba62a3ff663a0bd13a3f3fa40b`.

package/docs/rules/no-shape-in-symbol-names.md

@@ -0,0 +1,53 @@
+# rdj/no-shape-in-symbol-names
+
+Rejects the case-insensitive substring `shape` in any name you declare or reference, except a
+static member name owned by another value.
+
+## Why
+
+`PayloadShape` and `userShape` name the structure of a value instead of its role, which is the
+tell of a type that was written to satisfy the compiler rather than to describe the domain. A
+reader learns nothing from the suffix, and the name survives every refactor that changes what
+the value is for. The match is a plain substring on the lowered name, so `reshape` and
+`shapeOf` are reported too. Reading someone else's member, `schema.shape.id`, is not your name
+to choose and is allowed.
+
+## Rejected
+
+```ts
+type PayloadShape = { id: string };
+```
+
+> Rename symbol "PayloadShape" for its domain role; "shape" describes structure rather than
+> ownership.
+
+```ts
+type Payload = { shape: string };
+```
+
+> Rename symbol "shape" for its domain role; "shape" describes structure rather than ownership.
+
+## Accepted
+
+```ts
+declare const schema: ExternalSchema;
+const field = schema.shape.id;
+```
+
+```ts
+type Payload = { id: string };
+```
+
+## Options
+
+None. The term is fixed in the rule source.
+
+## When it is right to turn it off
+
+A domain where a shape is the thing itself, drawing, geometry, a layout engine. There `shape`
+is the domain role, which is exactly what the rule asks names to state. Scope the override to
+that module.
+
+## Origin
+
+Vendored from dmmulroy/anti-slop, commit `c44ef22ca116d0ba62a3ff663a0bd13a3f3fa40b`.

package/docs/rules/no-unknown-parameters.md

@@ -0,0 +1,55 @@
+# rdj/no-unknown-parameters
+
+Rejects a parameter whose annotation is or contains `unknown`, except a parameter named `cause`
+and the subject of a type predicate.
+
+## Why
+
+An `unknown` parameter moves the parsing work from the caller, who knows what the value is, to
+the body, which does not. Every call site then passes whatever it has and the function decides
+at runtime. The two escapes are narrow: `cause` is the error-enrichment convention, and a type
+guard's subject is `unknown` by construction. Note that the first escape is matched by the
+parameter's name alone, not by anything about its type.
+
+## Rejected
+
+```ts
+function parse(value: unknown): void {}
+```
+
+> Parameter `value` leaves input unparsed. Accept a named domain type; run the expected schema
+> or parser at the I/O boundary before calling this function.
+
+```ts
+export function parse({ value }: unknown = {}): void {}
+```
+
+> Parameter `{ value }` leaves input unparsed. Accept a named domain type; run the expected
+> schema or parser at the I/O boundary before calling this function.
+
+## Accepted
+
+```ts
+function enrich(cause: unknown): void {}
+```
+
+```ts
+function isString(value: unknown): value is string {
+  return true;
+}
+```
+
+## Options
+
+None.
+
+## When it is right to turn it off
+
+The error decoder that turns a rejection into a domain failure. It is handed whatever was
+thrown, and TypeScript itself types a `catch` binding as `unknown`, so the contract is honest
+and the parameter is rarely called `cause`. Scope it to that one module and let every caller
+above it take the named failure type.
+
+## Origin
+
+Vendored from dmmulroy/anti-slop, commit `c44ef22ca116d0ba62a3ff663a0bd13a3f3fa40b`.

package/docs/rules/no-unknown-returns.md

@@ -0,0 +1,61 @@
+# rdj/no-unknown-returns
+
+Rejects an explicit return annotation that resolves to `unknown`, including `Promise<unknown>`
+and a union containing `unknown`.
+
+## Why
+
+A function that returns `unknown` hands its caller a value and no way to use it, so the caller
+either asserts or writes the parse the function should have done. Multiply that by the call
+sites and one missing decode becomes several. The rule resolves local aliases and generic
+instantiations, so `type UnknownValue = unknown` and `Identity<unknown>` are caught as well. An
+alias that is not visible in the file cannot be resolved and passes.
+
+## Rejected
+
+```ts
+function load(): unknown {
+  return input;
+}
+```
+
+> This function exposes `unknown` to its caller. Parse the value at its boundary and return a
+> named domain type.
+
+```ts
+type Loader = () => Promise<unknown>;
+```
+
+> This function exposes `unknown` to its caller. Parse the value at its boundary and return a
+> named domain type.
+
+## Accepted
+
+```ts
+function load(): Promise<User> {
+  return promise;
+}
+```
+
+```ts
+function cause(): { cause: unknown } {
+  return { cause: input };
+}
+```
+
+An unannotated function is not a contract and is never reported: `function infer() { return
+input; }` passes.
+
+## Options
+
+None.
+
+## When it is right to turn it off
+
+A declaration file that mirrors an external API whose real return type is `unknown`, `JSON.parse`
+being the obvious one. In your own code the boundary is the place to parse, which is what the
+message asks for.
+
+## Origin
+
+Vendored from dmmulroy/anti-slop, commit `c44ef22ca116d0ba62a3ff663a0bd13a3f3fa40b`.