Unguard your code. Defend against overdefensive AI-generated code.

Type-aware static analysis powered by the TypeScript compiler itself.

If ?? is on a non-nullable type, you don't need it.

If ?. is on a guaranteed object, it's noise.

unguard proves it with types, and complains.

npx unguard

No config, no setup. unguard finds your tsconfig, builds a real TypeScript program, and reports only what the types prove. (npm install -g unguard if you prefer a global install.)

AI assistants pad code with guards against states the type system already rules out. Each one reads like caution, and in aggregate, they bury the real contracts. unguard reads the types and proves which guards need to be unguarded.

Dead fallbacks - the type says the value is always there:

const attempts = job.attempts ?? 1; // attempts: number

10:20  warning  Nullish coalescing (??) fallback on a non-nullable type is dead
                code; remove the fallback or fix the type upstream

Dead narrowing - the diagnostic cites the type that decides the condition:

if (typeof job.id !== "string") {   // id: string
  throw new Error("job is missing an id");
}

12:7   warning  typeof comparison is always false: `job.id` is `string`, and
                typeof always yields "string" for that type

Fabricated types - external data asserted into shape instead of validated:

const payload = JSON.parse(job.payload) as Payload;

17:21  error    Casting `any`/`unknown` to a concrete type without runtime
                validation fabricates structure; validate first or narrow with
                a type guard

Swallowed errors - failure silently becomes a normal-looking value:

try {
  return { id: job.id, attempts, payload };
} catch {
  return null;
}

19:5   warning  Catch swallows the error: it neither throws nor returns a value
                referencing the caught error. Propagate via throw, or model
                failure into the return type carrying the original error

Plus more type-system evasions (as any, x as unknown as T, @ts-ignore), cross-file analysis (exports nobody imports, optional parameters no call site ever passes, arguments that are the same literal everywhere, dead overloads, copy-pasted functions), and more - the full catalog is in Current Rules.

Keep typescript-eslint - unguard is a complement to it, not a replacement. Its no-unnecessary-condition overlaps with a slice of no-dead-narrowing, and that's roughly where the overlap ends. Unguard, on the other hand, provides more:

• Whole-project analysis. unguard indexes every call site, import, and export across your tsconfig groups (and is monorepo-aware). Lint rules see one file at a time while unguard can prove an optional parameter is never passed, an argument is always the same literal, an export is never imported.
• Defensive-pattern focus. Swallowed catches detected structurally (does any expression in the catch reference the error?), throw new Error(e.message) losing the cause, unvalidated casts of external data, defaults that widen interface contracts.
• Tiers split by certainty. scan runs finding-tier rules whose reports demand a fix because the checker or graph demonstrates them. Cases with a correct alternative reading live in smell for human review.
• Zero config. npx unguard on any TypeScript repo.

unguard is built for the verify loop. Findings are proofs with the evidence in the message, which is exactly what an agent needs to fix code instead of arguing with a style warning. Add to your CLAUDE.md / AGENTS.md / rules file:

After changing TypeScript, run `npx unguard` and fix every finding.
Diagnostics cite the type that proves the defect - fix the code (or the type),
don't add suppressions. If a guard is genuinely intentional, annotate it:
`// @unguard <rule-id> <reason>`.

And gate CI:

- name: unguard
  run: npx unguard --fail-on=error

unguard                                  # scan files/directories for findings
unguard smell                            # report smells for human review
unguard fix                              # apply certified fixes, report what remains
unguard --config ./unguard.config.json   # load config
unguard --ignore '**/*.gen.ts'           # add ignore globs
unguard --only no-any-cast               # run rules matching a selector
unguard --rule duplicate-*=warning       # override rule severity/policy
unguard --rule category:cross-file=warning
unguard --rule tag:safety=error
unguard --fail-on=error                  # fail only on errors
unguard --json                           # machine-readable report
unguard baseline                         # record current findings as the baseline
unguard --no-baseline                    # ignore unguard.baseline.json for this scan
unguard --concurrency 1                  # disable worker-thread parallelism, can be slow for large codebases
unguard --no-cache                       # bypass on-disk diagnostic cache

Every rule belongs to one tier:

• finding - the checker or graph demonstrates the report, so it demands a fix (or an explicit @unguard annotation). unguard scan runs finding-tier rules and is meant to gate CI or commits.
• smell - the analysis cannot see enough to choose between a likely problem and a correct alternative reading, such as deliberate duplication, an API surface for external consumers, or an intentionally optional parameter. unguard smell reports these for human review and exits 0 unless --fail-on is passed explicitly.

--only <selector> and explicit rules selections bypass the tiers - a matching rule runs in either command.

unguard automatically loads ./unguard.config.json (or ./.unguardrc.json). Use --config <path> to specify another file.

{
  "$schema": "./node_modules/unguard/schema.json",
  "paths": ["src", "apps/web/src"],
  "ignore": ["**/*.gen.ts", "**/routeTree.gen.ts"],
  "rules": {
    "duplicate-*": "warning",
    "category:cross-file": "warning",
    "tag:safety": "error",
    "no-ts-ignore": "error",
    "prefer-*": "off"
  },
  "overrides": [
    {
      "files": ["tests/**", "**/*.test.ts"],
      "rules": {
        "no-non-null-assertion": "off",
        "duplicate-*": "off"
      }
    }
  ],
  "failOn": "error",
  "concurrency": 4,
  "cache": true
}

rules values can be off, info, warning, or error. Selectors support:

• exact rule id: no-ts-ignore
• wildcard: duplicate-*
• category: category:cross-file
• tag: tag:safety
• tier: tier:finding, tier:smell

overrides entries apply a rule policy only to diagnostics in files matching the listed globs (gitignore syntax, relative to the working directory). Later entries win; off drops the diagnostic. Typical use: relaxing rules in test directories, where non-null assertions and duplication are often deliberate.

unguard ignores:

• built-in: node_modules, dist, .git, declaration files (*.d.ts, *.d.cts, *.d.mts)
• generated files: *.gen.*, *.generated.*
• project .gitignore
• anything passed via --ignore or config ignore

Use --fail-on=error in CI to fail only on errors while still showing all diagnostics:

unguard src --fail-on=error

unguard smell defaults to --fail-on=none and exits 0 regardless of smells. Pass --fail-on explicitly to make it gate.

Grouped text output is the default, with diagnostics grouped by file:

src/lib/probe.ts
  37:4       warning  Catch swallows the error...  no-swallowed-catch

Use --json for a machine-readable report. Scan and fix reports use findings; smell reports use smells:

{
  "findings": [
    {
      "file": "src/lib/probe.ts",
      "line": 37,
      "column": 4,
      "severity": "warning",
      "ruleId": "no-swallowed-catch",
      "message": "Catch swallows the error...",
      "fixable": false
    }
  ],
  "fileCount": 1,
  "exitCode": 1
}

unguard fix applies certified fixes for diagnostics with semantics-preserving replacements (dead ?? fallbacks, dead ?., no-op await, redundant casts, cond ? true : false, and similar), then reports what remains. The exit code reflects only the remaining findings.

Adopting unguard in an existing codebase? unguard baseline src records every current finding in unguard.baseline.json. Subsequent scans suppress a (file, rule) group as long as its count stays at or below the recorded number - new findings anywhere still fail, and fixing old ones ratchets the allowance down on the next unguard baseline. Use --no-baseline to see the full picture.

The Tier column says which command runs the rule: scan for a finding or smell for a smell.

These rules use the TypeScript type checker. Non-nullable types suppress the diagnostic; nullable types are flagged.

Nullability-driven rules require strictNullChecks (or strict). Without it the checker erases null/undefined from every type, so these rules are skipped with a warning rather than reporting every load-bearing guard as dead code.

Comments near flagged lines appear in the output as context:

// intentional escape hatch for untyped AST access
type AnyNode = Record<string, any>;

file.ts:2:31 error Explicit `any` annotation ... (intentional escape hatch for untyped AST access)

For warning and info diagnostics, you can explicitly mark a finding as intentional with @unguard <rule-id> on the same line or immediately above:

// @unguard no-nullish-coalescing intentional default for legacy callers
const port = config.port ?? 3000;

@unguard never suppresses error diagnostics.

import { executeScan, scan } from "unguard";

const result = await scan({ paths: ["src/"] }); // raw diagnostics
const execution = await executeScan({
  paths: ["src"],
  mode: "scan", // or "smell"
  ignore: ["**/*.gen.ts"],
  rulePolicy: {
    "duplicate-*": "warning",
    "category:cross-file": "warning",
    "tag:safety": "error",
    "prefer-*": "off",
  },
  overrides: [{ files: ["tests/**"], rules: { "no-non-null-assertion": "off" } }],
  failOn: "error",
});

console.log(execution.exitCode);
for (const d of execution.visibleDiagnostics) {
  console.log(`${d.file}:${d.line} [${d.ruleId}] ${d.message}`);
}

unguard caches scan results under node_modules/.cache/unguard/. Before reusing results, it refreshes project membership and module resolution, then checks reportable files, semantic dependency hashes, and scan policy. Cache hits skip type-checker and rule analysis, but still parse project inputs to resolve dependencies. The cache invalidates automatically on:

• content changes in scanned files, project-context files, and imported declarations (mtime-only changes are ignored)
• added or removed project inputs, including changes to inherited include patterns
• changes to tsconfig, extended configurations, or package-resolution metadata
• changes to active rules or rule severities
• changes to reportable files (including .gitignore effects), scan paths, ignore globs, or failOn
• unguard version upgrades

Disable with --no-cache (CLI), cache: false (config), or pass cache: false to executeScan({ cache: false }) programmatically.

MIT