CLI & API Usage

@masumdev/tscheck can be used via the command-line interface (CLI) or imported as a library in your scripts.

CLI Commands & Flags

Run tscheck in the root of your project or monorepo:

tscheck

Command-Line Flags

Flag	Description	Default
`-c, --config <path>`	Path to custom configuration file (`.json`, `.yaml`, `.ts`)	Auto-detected
`-o, --output <dir>`	Custom directory to write audit reports	`.temp/tscheck`
`--staged`	Only scan files currently staged in Git (pre-commit mode)	`false`
`--since <ref>`	Only scan files changed since a specific git branch/commit
`--fix`	Automatically fix safe issues like prefixing unused identifiers with `_`	`false`
`-f, --format <format>`	Output format: `pretty` (default), `json`, or `github`	`pretty`
`-i, --interactive`	Launch interactive terminal search dashboard with live filtering	`false`
`--no-deprecated`	Disable deprecated API usages check	`false`
`--no-unused`	Disable unused variables and imports check	`false`
`--no-any`	Disable explicit any usages check	`false`
`--no-circular`	Disable circular module dependencies check	`false`
`--no-boundary`	Disable package boundary check	`false`
`--fail-on-warning`	Exit with non-zero exit code if violations are found	`false`
`--json`	Output pure JSON to stdout without Ink UI (shorthand for `--format json`)	`false`
`-V, --version`	Output version number
`-h, --help`	Display help screen

Practical Examples & Workflows

1. Git Staged Pre-Commit Hook (`--staged`)

Integrate tscheck into husky or lint-staged for sub-second pre-commit validations:

# In package.json scripts or .husky/pre-commit
npx tscheck --staged --fail-on-warning

2. CI Pull Request Audits with GitHub Actions (`--format github`)

Output native GitHub annotations so issues render directly on PR diffs:

# In your GitHub Actions workflow step (.github/workflows/ci.yml)
npx tscheck --format github --fail-on-warning

3. Auto-Fix Safe Issues (`--fix`)

Automatically rename unused parameters and variables with an underscore prefix _ to satisfy TypeScript standards without breaking runtime code:

npx tscheck --fix

4. Interactive Search Explorer Mode (`-i`)

Launch the interactive terminal UI with live search:

tscheck -i

Type any package name, rule, or symbol name in the interactive text input to instantly filter audit issues in real-time.

5. Rule-Specific Audits

# Audit only for circular dependencies and package boundaries
tscheck --no-deprecated --no-unused --no-any

# Audit only for deprecated APIs
tscheck --no-unused --no-any --no-circular --no-boundary

Programmatic API

You can import @masumdev/tscheck into your TypeScript or JavaScript scripts:

import {
  audit,
  writeAuditReports,
  emitGitHubAnnotations,
  applyAutoFixes,
  getStagedFiles,
} from "@masumdev/tscheck";

// 1. Run audit programmatically
const report = await audit({
  rootDir: process.cwd(),
  rules: {
    deprecated: true,
    unused: true,
    noExplicitAny: true,
    circular: true,
    packageBoundary: true,
  },
});

console.log(`Files scanned: ${report.summary.filesScanned}`);
console.log(`Deprecated usages: ${report.summary.totalDeprecatedUsages}`);
console.log(`Circular dependencies: ${report.summary.totalCircularDependencies}`);

// 2. Write JSON, Markdown & HTML reports to disk
const files = writeAuditReports(report, {
  reporters: {
    outputDir: ".temp/tscheck",
    json: true,
    markdown: true,
    html: true,
  },
});

console.log(`Generated: ${files.json}, ${files.markdown}, ${files.html}`);

// 3. Emit GitHub Annotations in CI environment
if (process.env.GITHUB_ACTIONS) {
  emitGitHubAnnotations(report, false);
}

Testing & Verification

@masumdev/tscheck includes 56 unit and end-to-end tests maintaining 100% function coverage across all rules, CLI commands, and UI components.

# Run test suite
bun test

# Run tests with code coverage report
bun test --coverage