Inline suppression

Suppress specific findings with inline comments or JSDoc tags. Useful for false positives or intentional exceptions.

JSDoc visibility tags

Exports annotated with JSDoc visibility tags are never reported as unused. Fallow recognizes @public, @internal, @beta, and @alpha. Use these for library APIs consumed by external projects, or exports intentionally reserved for specific audiences. They have zero internal references but are intentionally part of your API surface.

/** @public */
export function createClient() {
  // Not imported anywhere in this repo, but consumed by users of the library
}

/**
 * Configuration options for the client.
 * @public
 */
export interface ClientOptions {
  baseUrl: string;
  timeout?: number;
}

/** @internal */
export function resetState() {
  // Used by sibling packages in the monorepo, not public API
}

/** @beta */
export function experimentalFeature() {
  // Available to early adopters, not yet stable
}

/** @alpha */
export function unstableApi() {
  // Early-stage API, subject to breaking changes
}

/** @api public */
export type UserId = string; // TSDoc @api convention also supported

The tags work with all export types: named, default, classes, interfaces, enums, type aliases, and multi-specifier exports (export { foo, bar }).

@expected-unused JSDoc tag

Mark exports as intentionally unused with /** @expected-unused */. Unlike visibility tags (@public, @internal), this tag is tracked for staleness. If the export later becomes imported by another module, fallow reports the tag as a stale suppression.

/** @expected-unused */
export const deprecatedHelper = () => {
  // Intentionally kept but not used anywhere
};

Use @expected-unused when you want to:

• Suppress an unused export finding
• Be notified if the export becomes used again (via the stale-suppressions rule)

The stale-suppressions rule (default: warn) controls the severity of stale @expected-unused tags. See dead code explained for details.

Comment syntax

// Suppress all issues on the next line
// fallow-ignore-next-line
export const keepThis = 1;

// Suppress a specific issue type
// fallow-ignore-next-line unused-export
export const keepThisToo = 2;

// Suppress all issues in the entire file
// fallow-ignore-file

// Suppress a specific issue type file-wide
// fallow-ignore-file unused-export

Suppressing complexity findings

Suppress individual functions from the health command's complexity report. Both cyclomatic and cognitive metrics are suppressed together.

// fallow-ignore-next-line complexity
function* parseCsv(text) {
  // intentionally complex parser, not worth refactoring
  // ...
}

function processRow(row) {
  // this function is NOT suppressed, still appears in health output
  // ...
}

File-level suppression excludes all functions in the file from complexity findings (file health scores are unaffected):

// fallow-ignore-file complexity

Reference

Multi-kind markers and typos

A marker can list more than one token. When one of the tokens does not match a known issue kind (typo, or a kind renamed in a newer fallow release), the recognized tokens still apply and each unknown token surfaces as a stale-suppression finding. fallow includes a "Did you mean ...?" Levenshtein hint when a known kind is within edit distance 2, so an upgrade across a rename never silently breaks the entire marker.

// Recognized + unknown on the same marker:
// fallow-ignore-next-line unused-export, complexity-typo
export const foo = 1;
// `unused-export` still suppresses `foo`; `complexity-typo` surfaces as a stale
// suppression so you can fix the typo or drop the unknown token.

JSON consumers can distinguish unknown-kind tokens from stale-but-known tokens via the additive origin.kind_known field on stale_suppressions[].origin (present and false only in the unknown-kind case; absent when the kind is recognized).

Documenting suppressions with a reason

Every suppression comment and @expected-unused tag can carry a trailing -- <reason> explaining why it is there:

// fallow-ignore-next-line unused-export -- public compatibility export
export const legacyHelper = () => {};

// fallow-ignore-file -- generated route map

/** @expected-unused -- kept for the v3 migration */
export const oldApi = () => {};

By default the reason is optional and recorded in suppression hygiene output. Enable the opt-in require-suppression-reason rule (default off) to enforce that every suppression documents itself:

{ "rules": { "require-suppression-reason": "warn" } }

With the rule at warn (or error to fail CI), any fallow-ignore-* comment or @expected-unused tag without a -- <reason> reports as a missing-suppression-reason finding, so you can find and backfill undocumented suppressions across the codebase. See Rules & Severity for the rule reference.

Issue type tokens

Use these tokens with suppression comments. The Scope column shows whether each type supports line-level (// fallow-ignore-next-line), file-level (// fallow-ignore-file), or both.

When to use suppression

Prefer config-level solutions (rules, ignoreExports) for broad patterns. Use inline suppression for:

• Individual false positives
• Temporary suppression during migration

Config-level vs inline suppression

// src/components/Button.tsx
// fallow-ignore-next-line unused-export
export const Button = () => { /* ... */ };

// src/components/Input.tsx
// fallow-ignore-next-line unused-export
export const Input = () => { /* ... */ };

// src/components/Modal.tsx
// fallow-ignore-next-line unused-export
export const Modal = () => { /* ... */ };

// Repeated across dozens of component files...

See also