TSUS diagnostic codes
Generated from packages/cli/src/rules/registry.js by npm run docs. Do not edit by hand; tsus explain <CODE> prints the same text.
| Code | Rule | Fix |
|---|---|---|
| TSUS000 | Syntax error | none |
| TSUS001 | Classes are banned | none |
| TSUS002 | null is banned | none |
| TSUS003 | undefined is banned | none |
| TSUS004 | var is banned | safe |
| TSUS005 | throw is banned | none |
| TSUS006 | Malformed match expression | none |
| TSUS100 | Non-exhaustive match (runtime) | none |
| TSUS401 | any is banned | safe |
| TSUS402 | as casts are banned outside boundary files | none |
| TSUS403 | Non-null assertions are banned | none |
| TSUS404 | enum is banned | unsafe |
| TSUS405 | == and != are banned | safe |
| TSUS406 | Default exports are banned outside boundary files | unsafe |
| TSUS407 | Reassigning a parameter is banned | none |
| TSUS408 | let that is never reassigned | safe |
| TSUS409 | Mutating a parameter is banned | unsafe |
| TSUS410 | Result error types must be tagged | none |
| TSUS411 | Floating promises are banned | unsafe |
| TSUS412 | Unused Result | none |
| TSUS413 | Type-check suppressions are banned | safe |
TSUS000 syntax-error
Syntax error. Every other rule runs on the parsed tree, so nothing else can be checked until the file parses.
Rejected:
const total = (a: number, b: number): number => a + ;Accepted:
const total = (a: number, b: number): number => a + b;Hint: The file does not parse as TypeScript after macro expansion.
Fix: No automatic fix: the right change depends on intent.
TSUS001 no-class
Classes are banned. Classes mix data, behavior, identity and mutable state, and this rebinding is a classic source of bugs. Plain data plus functions is easier to verify, serialize and test.
Rejected:
class Counter {
constructor(public count: number) {}
next(): Counter {
return new Counter(this.count + 1);
}
}Accepted:
type Counter = { readonly count: number };
const createCounter = (count: number): Counter => ({ count });
const next = (c: Counter): Counter => ({ count: c.count + 1 });Hint: Use plain object types and functions.
Fix: No automatic fix: the right change depends on intent.
TSUS002 no-null
null is banned. null is an absent value that the type system lets you forget to check. Option makes absence a value you have to match on.
Rejected:
const find = (id: number): string | null => (id === 1 ? "ada" : null);Accepted:
import { Some, None, type Option } from "@tsus/runtime";
const find = (id: number): Option<string> => (id === 1 ? Some("ada") : None);Hint: Use Option from @tsus/runtime, or fromNullable at the boundary.
Fix: No automatic fix: the right change depends on intent.
TSUS003 no-undefined
undefined is banned. undefined is the second absent value. Having two of them doubles the checks and neither is enforced. Option replaces both.
Rejected:
const nickname: string | undefined = undefined;Accepted:
import { None, type Option } from "@tsus/runtime";
const nickname: Option<string> = None;Hint: Use Option from @tsus/runtime, or fromNullable at the boundary.
Fix: No automatic fix: the right change depends on intent.
TSUS004 no-var
var is banned. var is function-scoped and hoisted, so a binding can be read before it is assigned and leaks out of blocks.
Rejected:
var count = 0;Accepted:
const count = 0;Hint: Use const (preferred) or let.
Fix: tsus fix applies it (behavior is kept).
TSUS005 no-throw
throw is banned. A throw is an invisible second return type. Callers cannot see it in the signature and the compiler cannot make them handle it. Result<T, E> puts the failure in the type.
Rejected:
const parsePort = (raw: string): number => {
const n = Number(raw);
if (Number.isNaN(n)) {
throw new Error("not a number");
}
return n;
};Accepted:
import { Ok, Err, type Result } from "@tsus/runtime";
const parsePort = (raw: string): Result<number, "not a number"> => {
const n = Number(raw);
return Number.isNaN(n) ? Err("not a number") : Ok(n);
};Hint: Return Result<T, E> from @tsus/runtime, or wrapSync/wrapAsync at the boundary.
Fix: No automatic fix: the right change depends on intent.
TSUS006 match-syntax
Malformed match expression. The match macro is expanded before TypeScript parses the file, so a malformed match has to be reported by the macro itself.
Rejected:
const label = match (opt) {
Some(x) -> x,
};Accepted:
const label = match (opt) {
Some(x) => x,
None => "none",
};Hint: Arms look like: Pattern(binding) => expression, separated by commas.
Fix: No automatic fix: the right change depends on intent.
TSUS100 non-exhaustive-match
Non-exhaustive match (runtime). A match that falls through has no value to return. Raised at runtime by __tsus_match until exhaustiveness is checked at compile time.
Rejected:
const name = (s: Shape): string =>
match (s) {
Circle(c) => "circle",
};Accepted:
const name = (s: Shape): string =>
match (s) {
Circle(c) => "circle",
_ => "other",
};Hint: Add an arm for every variant, or a _ arm.
Fix: No automatic fix: the right change depends on intent.
TSUS401 no-any
any is banned. any switches the type checker off for every value it touches, and it spreads: anything derived from an any is any too. unknown forces a check before use.
Rejected:
const parse = (raw: string): any => JSON.parse(raw);Accepted:
const parse = (raw: string): unknown => JSON.parse(raw);Hint: Use unknown and narrow it, or a precise type.
Fix: tsus fix applies it (behavior is kept).
TSUS402 no-as-cast
as casts are banned outside boundary files. A cast is a claim the compiler cannot check. Casts belong at the boundary, where outside data is validated once, not sprinkled through the program.
Rejected:
const user = JSON.parse(raw) as User;Accepted:
// user.boundary.tsus: the one place outside data is trusted
import { z } from "zod";
import { Ok, Err, type Result } from "@tsus/runtime";
const UserSchema = z.object({ name: z.string() });
export type User = z.infer<typeof UserSchema>;
export const parseUser = (input: unknown): Result<User, "invalid user"> => {
const out = UserSchema.safeParse(input);
return out.success ? Ok(out.data) : Err("invalid user");
};Hint: Validate the value (for example with zod) and return a Result, or move the cast into a *.boundary.tsus file.
Fix: No automatic fix: the right change depends on intent.
TSUS403 no-non-null-assertion
Non-null assertions are banned. x! tells the compiler a value cannot be absent without proving it. When the claim is wrong you get the crash Option exists to prevent.
Rejected:
const first = (xs: string[]): string => xs.find((x) => x.length > 0)!;Accepted:
import { fromNullable } from "@tsus/runtime/boundary";
const first = (xs: string[]): string =>
fromNullable(xs.find((x) => x.length > 0)).unwrapOr("");Hint: Model the value as Option and match on it, or use unwrapOr.
Fix: No automatic fix: the right change depends on intent.
TSUS404 no-enum
enum is banned. enums are the one TypeScript feature that emits runtime code, numeric enums accept any number, and they do not narrow like literal unions. A union of literals is erasable, exhaustive in match, and serializes as itself.
Rejected:
enum Color {
Red = "red",
Green = "green",
}
const paint = (c: Color): string => c;
paint(Color.Red);Accepted:
type Color = "red" | "green";
const paint = (c: Color): string => c;
paint("red");Hint: Use a union of string literals: type Color = "Red" | "Green".
Fix: tsus fix --unsafe applies it; review the change, it can alter behavior.
TSUS405 no-loose-equality
== and != are banned. == coerces its operands ("1" == 1, "" == 0), which is almost never intended. With null and undefined gone, the one idiom that needed it (x == null) is gone too.
Rejected:
const isAdmin = (role: string): boolean => role == "admin";Accepted:
const isAdmin = (role: string): boolean => role === "admin";Hint: Use === or !==.
Fix: tsus fix applies it (behavior is kept).
TSUS406 no-default-export
Default exports are banned outside boundary files. A default export has no name, so every importer invents one and grep, rename and auto-import all get weaker. Named exports keep one name for one thing.
Rejected:
export default function greet(name: string): string {
return `hi ${name}`;
}Accepted:
export function greet(name: string): string {
return `hi ${name}`;
}Hint: Use a named export. Hosts that require a default export (Workers, framework pages) get a *.boundary.tsus file.
Fix: tsus fix --unsafe applies it; review the change, it can alter behavior.
TSUS407 no-param-reassign
Reassigning a parameter is banned. After a parameter is reassigned, the name no longer means what the caller passed, and every reader has to track which assignment is live.
Rejected:
const clamp = (n: number, max: number): number => {
if (n > max) {
n = max;
}
return n;
};Accepted:
const clamp = (n: number, max: number): number => {
const clamped = n > max ? max : n;
return clamped;
};Hint: Introduce a new const with a descriptive name.
Fix: No automatic fix: the right change depends on intent.
TSUS408 prefer-const
let that is never reassigned. let tells the reader to expect reassignment. When none happens the keyword is a false signal, and const lets the compiler hold the line.
Rejected:
let total = 0;
console.log(total);Accepted:
const total = 0;
console.log(total);Hint: Replace let with const.
Fix: tsus fix applies it (behavior is kept).
TSUS409 no-param-mutation
Mutating a parameter is banned. A function that mutates its argument changes data the caller still holds, which is spooky action at a distance. Returning new values keeps every function's effect visible in its return type.
Rejected:
const addItem = (cart: string[], item: string): string[] => {
cart.push(item);
return cart;
};Accepted:
const addItem = (cart: string[], item: string): string[] => [...cart, item];Hint: Return a new value instead: spread objects ({ ...p, x }), and use toSorted/toReversed/toSpliced or [...xs, item] for arrays.
Fix: tsus fix --unsafe applies it; review the change, it can alter behavior.
TSUS410 tagged-errors
Result error types must be tagged. Result<T, string> or Result<T, Error> says that something failed but not what, so callers cannot match on the cases. A tagged error type is a closed set the caller can handle exhaustively.
Rejected:
const load = (id: string): Result<User, string> =>
id === "" ? Err("missing id") : Ok({ id });Accepted:
type LoadError = "missing id" | Tagged<"NotFound", string>;
const load = (id: string): Result<User, LoadError> =>
id === "" ? Err("missing id") : Ok({ id });Hint: Use literals (Result<T, "not found" | "timeout">) or variants with a literal tag (or kind/type) field: Tagged<"NotFound", string> | { tag: "Timeout"; ms: number }.
Fix: No automatic fix: the right change depends on intent.
TSUS411 no-floating-promise
Floating promises are banned. A promise nobody awaits loses its result and its rejection. The work races the rest of the program and failures vanish.
Rejected:
const save = async (row: Row): Promise<Result<true, SaveError>> => write(row);
const handler = async (row: Row): Promise<string> => {
save(row);
return "done";
};Accepted:
const handler = async (row: Row): Promise<string> =>
match (await save(row)) {
Ok(_) => "done",
Err(e) => `failed: ${e.tag}`,
};Hint: await it, return it, or hand it to something that owns it (for example ctx.waitUntil(promise)).
Fix: tsus fix --unsafe applies it; review the change, it can alter behavior.
TSUS412 no-unused-result
Unused Result. A Result carries the failure case. Calling a function that returns one and dropping it is the same bug as an empty catch block.
Rejected:
const run = (): string => {
saveConfig(config);
return "saved";
};Accepted:
const run = (): string =>
match (saveConfig(config)) {
Ok(_) => "saved",
Err(e) => `not saved: ${e}`,
};Hint: match on it, propagate it with ?, or return it.
Fix: No automatic fix: the right change depends on intent.
TSUS413 no-ts-suppression
Type-check suppressions are banned. A suppression comment switches checking off for a line or a file with no record of why, which reopens every hatch the other rules close.
Rejected:
// @ts-ignore
const port: number = process.env.PORT;Accepted:
import { fromNullable } from "@tsus/runtime/boundary";
const port: number = fromNullable(process.env.PORT).map(Number).unwrapOr(8080);Hint: Fix the type error. If outside data is the problem, validate it in a *.boundary.tsus file.
Fix: tsus fix applies it (behavior is kept).