@rdjperron/lint 0.2.0 → 0.5.0

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

@@ -1,61 +0,0 @@
-# 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`.

package/docs/rules/no-unknown-type-aliases.md

@@ -1,52 +0,0 @@
-# rdj/no-unknown-type-aliases
-
-Rejects a type alias whose resolved type is `unknown`.
-
-## Why
-
-`type Payload = unknown` gives a vague type a confident name. Every signature that uses it
-reads as if it were parsed, and none of them are. A union does the same thing quietly:
-`string | unknown` is `unknown`, so the `string` half is decoration. The rule resolves through
-chains and generic instantiations, so `Identity<unknown>` and an alias of an alias are caught,
-and a chain reports at each declaration that resolves to `unknown`.
-
-## Rejected
-
-```ts
-type Alias = unknown;
-```
-
-> Type alias `Alias` hides `unknown`. Keep `unknown` explicit at the parsing boundary or on an
-> allowed `cause` field; otherwise use the parsed owner type.
-
-```ts
-type Payload = string | unknown;
-```
-
-> Type alias `Payload` hides `unknown`. Keep `unknown` explicit at the parsing boundary or on an
-> allowed `cause` field; otherwise use the parsed owner type.
-
-## Accepted
-
-```ts
-type Box<T> = { readonly value: T };
-type Payload = Box<unknown>;
-```
-
-```ts
-type User = { readonly id: string };
-```
-
-## Options
-
-None.
-
-## When it is right to turn it off
-
-Nothing needs it off. Where `unknown` is genuinely the right type, at a parsing boundary or on
-an error's `cause`, writing `unknown` at that spot is both allowed and clearer than a name that
-conceals it.
-
-## Origin
-
-Vendored from dmmulroy/anti-slop, commit `c44ef22ca116d0ba62a3ff663a0bd13a3f3fa40b`.

package/docs/rules/no-unsafe-dictionary-type.md

@@ -1,56 +0,0 @@
-# rdj/no-unsafe-dictionary-type
-
-Rejects a dictionary contract whose value type is `unknown`, `any`, `object`, `{}`, or a union,
-alias or intersection that reaches one of those.
-
-## Why
-
-`Record<string, unknown>` promises a lookup and delivers nothing: every read needs a cast, and
-the cast is written at each call site by someone guessing. The type is usually a stand-in for a
-schema nobody wrote. The rule covers `Record` with a broad key, index signatures, mapped types
-and interface index members, resolves aliases and generic defaults, and reports the outermost
-type only, so one bad dictionary produces one finding. The value name in the message is one of
-`unknown`, `any`, `object`, `empty-object` or `union`.
-
-## Rejected
-
-```ts
-type Registry = Record<string, unknown>;
-```
-
-> This dictionary's unknown value type gives callers no concrete value contract. Use an
-> owner/schema-derived value type; parse external payloads before insertion.
-
-```ts
-type Registry = { [key: string]: any };
-```
-
-> This dictionary's any value type gives callers no concrete value contract. Use an
-> owner/schema-derived value type; parse external payloads before insertion.
-
-## Accepted
-
-```ts
-type Commands = Record<string, Command>;
-```
-
-```ts
-type Allowed = Record<string, { payload: unknown }>;
-```
-
-A finite key type is a different thing and passes: `Record<Permission, number>` is exhaustive,
-and a type parameter constrained by `Record<string, unknown>` is a constraint, not a contract.
-
-## Options
-
-None.
-
-## When it is right to turn it off
-
-The one module that holds a decoded JSON object before any field is read. There is no schema
-yet to name the values by, and the readers beside it are what give each field a type. Scope it
-to that module, not to the callers.
-
-## Origin
-
-Vendored from dmmulroy/anti-slop, commit `c44ef22ca116d0ba62a3ff663a0bd13a3f3fa40b`.

package/docs/rules/no-use-effect.md

@@ -1,55 +0,0 @@
-# rdj/no-use-effect
-
-Rejects every `useEffect` and `useLayoutEffect` call, and every value import of either.
-
-## Why
-
-An effect that computes state runs after the render that needed it, so the screen paints once
-with the old value and again with the new one, and the dependency array becomes the place bugs
-hide. Almost every use has a shorter form: derive the value during render, do the work in the
-event handler that caused it, or subscribe through a reactive query. Reporting the import as
-well as the call is deliberate, since an import is how the next one arrives. The rule matches
-by name, so `React.useEffect` and an aliased import both report.
-
-## Rejected
-
-```tsx
-useEffect(() => {
-  document.title = title;
-}, [title]);
-```
-
-> Do not call useEffect. Derive the value during render, do the work in the event handler, or
-> subscribe through a reactive query.
-
-```tsx
-import { useLayoutEffect } from "react";
-```
-
-> Do not call useLayoutEffect. Derive the value during render, do the work in the event handler,
-> or subscribe through a reactive query.
-
-## Accepted
-
-```tsx
-const value = useMemo(() => compute(input), [input]);
-```
-
-```tsx
-import type { useEffect } from "react";
-```
-
-## Options
-
-`hint`, a string, no default. It is appended to every message, which is how a project names its
-own sanctioned wrapper, for example "The one sanctioned wrapper is useMountEffect."
-
-## When it is right to turn it off
-
-The single file that wraps the hook. A genuine one-time external subscription needs a real
-effect somewhere, so it lives in one named wrapper and that file carries the only override.
-Every other file then has no reason to import the hook at all.
-
-## Origin
-
-Written in this package.

package/docs/rules/no-widen-then-assert.md

@@ -1,53 +0,0 @@
-# rdj/no-widen-then-assert
-
-Rejects a local `const` that is explicitly widened and then asserted back to a narrower type
-later in the same function.
-
-## Why
-
-The round trip costs the file its one piece of real evidence. The initializer showed what the
-value was, the annotation threw that away, and the assertion re-invents it by hand, so a typo
-in the asserted type is now unreachable by the checker. A reader has to compare two type
-expressions several lines apart to see whether they agree. The rule wants one precise type from
-initialization to use. It only fires on a `const` that is never reassigned, widened by its
-annotation or by an `as unknown` initializer, and asserted after its declaration within the
-same function.
-
-## Rejected
-
-```ts
-const source = { id: "second" };
-const widened: unknown = source;
-const parsed = widened as { readonly id: string };
-```
-
-> Binding "widened" discards type evidence and later recreates it with an assertion. Keep the
-> precise type from initialization through use; parse boundary input once.
-
-## Accepted
-
-```ts
-declare const input: unknown;
-const parsed = input as { readonly id: string };
-```
-
-```ts
-const source = { id: "first" };
-const widened: unknown = source;
-```
-
-The second one is accepted here because nothing asserts the binding back. The widening itself
-is what `rdj/no-known-value-widening` reports.
-
-## Options
-
-None.
-
-## When it is right to turn it off
-
-Nothing needs it off. Where the value genuinely arrives unknown, as a parameter or an import,
-there is no local widening and the rule stays silent.
-
-## Origin
-
-Vendored from dmmulroy/anti-slop, commit `c44ef22ca116d0ba62a3ff663a0bd13a3f3fa40b`.

package/docs/rules/require-safety-comment-for-type-assertion.md

@@ -1,59 +0,0 @@
-# rdj/require-safety-comment-for-type-assertion
-
-Requires a `SAFETY:` comment before every type assertion that is not `as const`.
-
-## Why
-
-An assertion is a claim the checker cannot verify, so the only thing that makes it reviewable
-is the sentence saying which check already ran. Without it a reviewer cannot tell a justified
-narrowing from a cast that silenced an error. The comment has to sit before the assertion or
-before the statement that contains it, which also means a trailing `// SAFETY:` at the end of
-the line does not count: it is read after the claim it was supposed to support. The marker must
-be followed by a colon and at least one non-space character, so an empty `// SAFETY:` still
-reports.
-
-## Rejected
-
-```ts
-const id = value as UserId;
-```
-
-> This type assertion has no `SAFETY:` justification. State the checked invariant immediately
-> before the assertion or its containing statement.
-
-```ts
-const id = value as UserId; // SAFETY: Too late.
-```
-
-> This type assertion has no `SAFETY:` justification. State the checked invariant immediately
-> before the assertion or its containing statement.
-
-## Accepted
-
-```ts
-// SAFETY: The parser established the UserId invariant.
-const id = value as UserId;
-```
-
-```ts
-const id = /* SAFETY: Validation established the invariant. */ value as UserId;
-```
-
-`as const` and `<const>` assertions are exempt, and a comment above an `export` covers the
-declaration it exports.
-
-## Options
-
-`markers`, an array of unique non-empty strings, default `["SAFETY"]`. Any one of them
-satisfies the rule; the first fills the `{{marker}}` in the message. A project that already
-writes `// INVARIANT:` can keep its own word.
-
-## When it is right to turn it off
-
-Test files. A fixture's assertions are all the same claim, that the fixture is what the test
-just built, and repeating it on each one is noise rather than review material. One consumer
-measured 53 such findings across its tests before scoping the rule off there.
-
-## Origin
-
-Vendored from dmmulroy/anti-slop, commit `c44ef22ca116d0ba62a3ff663a0bd13a3f3fa40b`.

package/docs/rules/static-public-env.md

@@ -1,55 +0,0 @@
-# rdj/static-public-env
-
-Rejects every use of `process.env` except a static `process.env.NAME` read.
-
-## Why
-
-Expo replaces each `process.env.EXPO_PUBLIC_*` read textually at bundle time. There is no
-`process.env` object on the device, so anything the substitution cannot see becomes `undefined`
-at runtime and nothing fails at build time. Destructuring, a computed key and passing
-`process.env` around as a value all read fine and all break silently on the phone. The rule has
-three messages, one per form, so the finding names which one it found.
-
-## Rejected
-
-```ts
-const { EXPO_PUBLIC_API_URL } = process.env;
-```
-
-> Expo replaces each `process.env.EXPO_PUBLIC_*` read textually at bundle time, so there is no
-> `process.env` object to destructure on the device. Read each variable as `process.env.NAME`.
-
-```ts
-const url = process.env[name];
-```
-
-> Expo replaces each `process.env.EXPO_PUBLIC_*` read textually at bundle time, so a computed
-> key is undefined on the device. Read the variable as `process.env.NAME` with the name spelled
-> out.
-
-Everything else, including `Object.keys(process.env)`, `"A" in process.env` and a spread,
-reports the third message: `process.env` passed around as a value is empty on the device.
-
-## Accepted
-
-```ts
-const url = process.env.EXPO_PUBLIC_API_URL ?? "http://localhost";
-```
-
-```ts
-const url = process.env?.EXPO_PUBLIC_API_URL;
-```
-
-## Options
-
-None.
-
-## When it is right to turn it off
-
-Code that never enters the app bundle: a build script, a config file, anything running under
-Node where `process.env` is a real object. Scope the override to those files, since the rule's
-whole value is that it fires on the side Metro bundles.
-
-## Origin
-
-Written in this package.