Classification Rules
Diff Guardian classifies API changes using a set of structural rules. Each rule targets a specific symbol type (function, interface, enum, or type alias) and assigns a severity: breaking, warning, or safe. Click any rule to see its full documentation with before/after code examples.
Viewing rules in your terminal
Run npx dg rules to list all active rules with their IDs, names, and target types.
Severity levels
| Severity | Exit Code | Meaning |
|---|---|---|
BREAKING | 1 | Callers will fail. Blocks CI in strict mode. |
WARNING | 0 (or 1 if failOnWarnings) | Non-breaking but worth reviewing. |
SAFE | 0 | Harmless API expansion. |
Function rules
R01Parameter RemovedBREAKINGA parameter is removed from a function signature. Any caller that passes this argument will break.
processPayment(amount, currency) -> processPayment(amount)R02Parameter ReorderedBREAKINGThe order of parameters changes. Callers using positional arguments will receive wrong values.
createUser(name, age) -> createUser(age, name)R03Required Param AddedBREAKINGA new required parameter is added. All existing callers will be missing the new argument.
fetchUser(id) -> fetchUser(id, token)R04Param Type NarrowedBREAKINGA parameter type becomes more restrictive. Callers passing the previously-valid broader type will fail.
process(input: string | number) -> process(input: string)R05Optional Param AddedSAFEA new optional parameter is added. Existing callers are unaffected.
fetch(url) -> fetch(url, options?)R06Return NullableWARNINGThe return type now includes null or undefined. Callers not checking for null may crash.
getUser(): User -> getUser(): User | nullR07Return NarrowedSAFEThe return type becomes more specific. Callers expecting the broader type are safe.
getValue(): string | number -> getValue(): stringR08UnexportedBREAKINGA previously exported symbol is no longer exported. All external importers will break.
export function calc() -> function calc()R11Sync to AsyncBREAKINGA synchronous function becomes async. The return value changes from T to Promise<T>.
function getData(): Data -> async function getData(): Promise<Data>R12Param Type WidenedSAFEA parameter type becomes more permissive. All existing callers remain valid.
parse(input: string) -> parse(input: string | Buffer)R13Generic NarrowedBREAKINGA generic type parameter gains a stricter constraint. Callers using types that no longer satisfy the constraint will fail.
transform<T>(v: T) -> transform<T extends Serializable>(v: T)R14Rest ParameterWARNINGA rest parameter is added or removed, changing the argument collection behavior.
log(msg: string) -> log(...msgs: string[])R15Overload RemovedBREAKINGA function overload signature is removed. Callers invoking the removed overload will fail to compile.
function parse(s: string): T; (removed)R16Overload AddedSAFEA new overload signature is added. Existing callers are unaffected.
function parse(s: string): T; function parse(n: number): T; (added)R17Static ChangedBREAKINGA method changes between static and instance (or vice versa). All call sites change syntax.
static create() -> create() (or vice versa)R18Param Mutability NarrowedBREAKINGA parameter type gains a mutability constraint (e.g., readonly removed), breaking callers passing readonly data.
process(data: readonly T[]) -> process(data: T[])R19Param Mutability WidenedSAFEA parameter gains a readonly constraint. Callers passing mutable data automatically satisfy the new constraint.
process(data: T[]) -> process(data: readonly T[])R20Visibility NarrowedBREAKINGA class method's access modifier becomes more restrictive. External consumers or subclasses lose access.
public render() -> protected render()R21Async to SyncBREAKINGAn async function becomes synchronous. Callers using .then() or await will crash.
async function fetchData() -> function fetchData()R22Return NeverBREAKINGA return type transitions to 'never' (TS) or '!' (Rust), indicating the function now always throws or diverges.
process(): Result -> process(): neverR23Default Value ChangedWARNINGA parameter's default value is modified. Callers omitting this argument will silently receive different behavior.
retry(count = 3) -> retry(count = 1)R24Constructor ChangedBREAKINGA class constructor's parameters change structurally. All 'new ClassName()' instantiations may fail.
constructor(name: string) -> constructor(name: string, id: number)R28Visibility WidenedSAFEA previously internal symbol becomes exported. The API surface expands, but existing callers are unaffected.
function helper() -> export function helper()Interface rules
R25Interface Prop RequiredBREAKINGA new required property is added to an interface, or an optional property becomes required. Downstream implementations will fail.
{ name: string } -> { name: string; email: string }R26Interface Prop RemovedBREAKINGA property is completely deleted from an interface. Consumers relying on this property will fail.
{ name: string; age: number } -> { name: string }Enum rules
Related
- How It Works — understand the classifier engine
- Classifier Engine — bucketed rule routing
- Configuration — configure
failOnWarnings