Niteo

---

Niteo is a standalone Rust CLI for structural linting in TypeScript projects.

It checks project shape, module boundaries, and source structure rather than formatting. Niteo ships 50+ opinionated rules, builds a full import graph, and runs as a single binary with no plugins to configure. It uses oxc for AST parsing.

Why Niteo?

Tool	Focus
ESLint	Code-level linting: style, correctness, and patterns within individual files.
Knip	Unused exports, files, and dependencies. Finds dead code.
dependency-cruiser	Dependency rules between modules. Validates import constraints.
Niteo	Opinionated architecture and structural conventions. Enforces how a project is shaped: file layout, export style, module boundaries, domain boundaries, and import hygiene — all in one fast standalone CLI.

Niteo complements ESLint and Knip rather than replacing them. Where ESLint checks what your code does and Knip checks what your code uses, Niteo checks how your project is organized.

Features

• 50+ structural rules covering exports, barrel files, directory shape, imports, hooks, components, and unsafe TypeScript patterns. See the full rule reference.
• Baselines — snapshot existing violations so CI only fails on new issues. Adopt Niteo incrementally without fixing every file first.
• Suppressions — inline niteo-ignore-file, niteo-ignore-next-line, and niteo-ignore-line directives for narrow exceptions. Stale directive detection keeps suppressions honest.
• Monorepo configs — cascading niteo.toml files. Set defaults at the workspace root and override per package. Rule options merge field-by-field.
• Import graph — niteo stats shows fan-out and most-imported files. niteo graph outputs DOT or JSON for visualization and tooling.
• SARIF output — --format sarif integrates with GitHub Code Scanning, Azure DevOps, and any SARIF-compatible dashboard.
• NDJSON output — --format ndjson produces one valid JSON object per line for streaming consumption.
• Watch mode — niteo lint --watch re-lints on every file change during development.
• Cache — niteo lint --cache caches import graph analysis, parsed AST results, and rule violations for faster repeated runs. Automatically invalidated when files, config, or Niteo version changes.
• Health score — every run produces a 0–100 score so you can track structural health over time.
• Git-aware scanning — --git limits analysis to changed files, with --git BASE..HEAD for revision ranges and --git-staged / --git-unstaged for pre-commit and working-tree workflows. Interactive mode auto-detects changed files with best-effort fallback.

Installation

With Homebrew:

brew install FrozenProductions/niteo/niteo

Or tap first:

brew tap FrozenProductions/niteo
brew install niteo

The Homebrew tap is published at https://github.com/FrozenProductions/homebrew-niteo.

Run directly with npx:

npx niteo-cli lint

Or install globally:

npm i -g niteo-cli
niteo lint

The npm package ships prebuilt binaries for common platforms. Rust is only required when building from source or using an unsupported platform.

Usage

niteo lint              # Scan for structural issues
niteo init              # Create niteo.toml
niteo baseline create   # Snapshot current violations
niteo rules             # List configured rules
niteo explain no-console

Examples:

niteo lint --root src
niteo lint --scope src/components
niteo lint --format json --output report.json
niteo lint --format sarif --output report.sarif
niteo lint --watch
niteo lint --git
niteo lint --git origin/main..HEAD
niteo lint --git-staged
niteo lint --fail-on error
niteo lint --history
niteo lint --cache
niteo lint --cache --watch
niteo stats
niteo stats --history
niteo graph

Monorepos

Niteo supports cascading configs. Place a niteo.toml at the workspace root and additional niteo.toml files inside individual packages. Child configs merge on top of the root config, overriding only the fields they declare.

Workspace packages are discovered from package.json workspaces and pnpm-workspace.yaml packages. Niteo supports nested globs (apps/*/packages/*), recursive globs (packages/**), and negative globs (!packages/excluded).

# niteo.toml (root)
[project]
root = "packages"

[rules.no-console]
severity = "warn"

# packages/admin/niteo.toml
[rules.no-console]
severity = "error"

See Configuration for merge semantics and examples.

Documentation

See the full documentation.