TScanner

• Code Editor: See issues in real-time while coding. Add to lint-staged to prevent committing errors.
• Before PR: Check all issues in your branch compared to origin/main and fix them before opening a PR.
• CI/CD: Every push to a PR is checked automatically. Get a single comment with clickable links to the exact lines.

• Go fast with confidence: Know exactly what issues to fix before committing or merging.
• Zero rejected PRs: Over time, eliminate PR rejections due to styling or poor code quality patterns.
• AI-powered quality: Use AI rules to detect patterns that traditional linters miss, and let AI help fix AI-generated code.
• Your job: Observe code patterns to enforce/avoid and add TScanner rules for that.

We use TScanner to maintain this very codebase. Here's our setup:

Built-in rules (34 enabled): Standard code quality checks like no-explicit-any, prefer-const, no-console, etc.

Regex rules (3):

• no-rust-deprecated: Block #[allow(deprecated)] in Rust code
• no-rust-dead-code: Block #[allow(dead_code)] - remove unused code instead
• no-process-env: Prevent direct process.env access

Script rules (8):

• types-parity-match: Ensure TypeScript and Rust shared types are in sync
• config-schema-match: Keep Rust config and TypeScript schema aligned
• cli-builder-match: CLI builder must cover all CLI check flags
• action-zod-match: GitHub Action inputs must match Zod validation
• readme-toc-match: README table of contents must match all headings
• rust-entry-simple: lib.rs and mod.rs should only contain module declarations
• no-long-files: Files cannot exceed 300 lines
• no-default-node-imports: Use named imports for Node.js modules

AI rules (2):

• no-dead-code: Detect dead code patterns in Rust executors
• find-enum-candidates: Find type unions that could be enums

TIP: Check the .tscanner/ folder to see the full config and script implementations.

I basically observe code patterns to enforce/avoid and add custom rules, here are my current rules:

regex rules:

"regex": {
  "no-nestjs-logger": {
    "pattern": "import\\s*\\{[^}]*Logger[^}]*\\}\\s*from\\s*['\"]@nestjs/common['\"]",
    "message": "Do not use NestJS Logger. Import from custom logger instead"
  },
  "no-typeorm-for-feature": {
    "pattern": "TypeOrmModule\\.forFeature\\(",
    "message": "Use api/src/way-type-orm.module.ts instead"
  },
  "avoid-typeorm-raw-queries": {
    "pattern": "await this\\.([^.]+)\\.manager\\.query\\(",
    "message": "Avoid using RawQueryBuilder. Use the repository instead",
    "severity": "error"
  },
  "no-static-zod-schema": {
    "pattern": "static\\s+zodSchema\\s*=",
    "message": "Remove 'static zodSchema' from class. The schema is already passed to createZodDto() and this property is redundant"
  }
}

script rules:

"script": {
  "entity-registered-in-typeorm-module": {
    "command": "npx tsx script-rules/entity-registered-in-typeorm-module.ts",
    "message": "Entity must be registered in way-type-orm.module.ts",
    "severity": "error",
    "include": ["api/src/**/*.entity.ts", "api/src/way-type-orm.module.ts"]
  },
  "entity-registered-in-setup-nest": {
    "command": "npx tsx script-rules/entity-registered-in-setup-nest.ts",
    "message": "Entity must be registered in setup-nest.ts for tests",
    "severity": "error",
    "include": ["api/src/**/*.entity.ts", "api/test/helpers/setup-nest.ts"]
  },
  "no-long-files": {
    "command": "npx tsx script-rules/no-long-files.ts",
    "message": "File exceeds 600 lines limit",
    "include": ["**/*.ts"]
  }
}

ai rules:

soon!

Note: my rules at work are not commited to the codebase, so I basically installed tscanner globally and move the .tscanner folder into the .gitignore file

# TScanner Issue Report

This is a report from TScanner, a CLI tool that detects code quality issues in TypeScript/JavaScript projects. Your task is to fix the issues listed below.

## Report Details

Filter: rule "no-console" | Mode: codebase mode | Issues: 3
CLI: tscanner check --rule no-console --group-by rule

Results:

Rules triggered:

  ● no-console: Unexpected call to console.error

Issues grouped by rule:

● no-console (3 issues, 2 files)

  assets/configs/example-no-long-files.ts (2 issues)
    ⚠ 46:3 → console.log(JSON.stringify({ issues }));
    ⚠ 50:3 → console.error(err);

  packages/cli/src/main.ts (1 issues)
    ⚠ 33:5 → console.error(err.message);

Scope:

  Rules: 1
  Files: 2 (0 cached, 2 scanned)


Results:

  Issues: 3 (⚠ 3)
  Triggered rules: 1 (● 1)
  Files with issues: 2
  Duration: 0ms

## Instructions

- Some fixes require changes in multiple files, not just where the issue is reported
- Consider fixing one issue at a time and verifying each fix
- The rule description explains what's wrong - understand it before fixing
- Line numbers are 1-indexed

# TScanner Issue Report

This is a report from TScanner, a CLI tool that detects code quality issues in TypeScript/JavaScript projects. Your task is to fix the issues listed below.

## Report Details

Filter: file "packages/github-action/src/core/input-validator.ts" | Mode: codebase mode | Issues: 6
CLI: tscanner check --glob packages/github-action/src/core/input-validator.ts --group-by file

Results:

Rules triggered:

  ● prefer-nullish-coalescing: Use nullish coalescing (??) instead of logical OR (||). The || operator treats 0, "", and false as falsy, while ?? only checks for null/undefined.

Issues grouped by file:

packages/github-action/src/core/input-validator.ts - 6 issues - 1 rules

  ● prefer-nullish-coalescing (6 issues)
    ⚠ 44:20 → const timezone = githubHelper.getInput('timezone') || DEFAULT_INPUTS.timezone;
    ⚠ 45:22 → const configPath = githubHelper.getInput('config-path') || DEFAULT_INPUTS.configPath;
    ⚠ 46:27 → const tscannerVersion = githubHelper.getInput('tscanner-version') || DEFAULT_INPUTS.tscannerVersion;
    ⚠ 48:24 → const groupByInput = githubHelper.getInput('group-by') || DEFAULT_INPUTS.groupBy;
    ⚠ 54:23 → const aiModeInput = githubHelper.getInput('ai-mode') || AiExecutionMode.Ignore;
    ⚠ 78:53 → ...(mode === ScanMode.Branch && { targetBranch: targetBranch || DEFAULT_INPUTS.targetBranch }),

Scope:

  Rules: 1
  Files: 1 (0 cached, 1 scanned)


Results:

  Issues: 6 (⚠ 6)
  Triggered rules: 1 (● 1)
  Files with issues: 1
  Duration: 0ms

## Instructions

- Some fixes require changes in multiple files, not just where the issue is reported
- Consider fixing one issue at a time and verifying each fix
- The rule description explains what's wrong - understand it before fixing
- Line numbers are 1-indexed

{
  "$schema": "https://unpkg.com/tscanner@latest/schema.json",
  "rules": {
    "builtin": {
      "consistent-return": {},
      "max-function-length": {},
      "max-params": {},
      "no-absolute-imports": {},
      "no-alias-imports": {},
      "no-async-without-await": {},
      "no-console": {},
      "no-constant-condition": {},
      "no-default-export": {},
      "no-duplicate-imports": {},
      "no-dynamic-import": {},
      "no-else-return": {},
      "no-empty-class": {},
      "no-empty-function": {},
      "no-empty-interface": {},
      "no-explicit-any": {},
      "no-floating-promises": {},
      "no-forwarded-exports": {},
      "no-implicit-any": {},
      "no-inferrable-types": {},
      "no-nested-require": {},
      "no-nested-ternary": {},
      "no-non-null-assertion": {},
      "no-relative-imports": {},
      "no-return-await": {},
      "no-shadow": {},
      "no-single-or-array-union": {},
      "no-todo-comments": {},
      "no-unnecessary-type-assertion": {},
      "no-unreachable-code": {},
      "no-unused-vars": {},
      "no-useless-catch": {},
      "no-var": {},
      "prefer-const": {},
      "prefer-interface-over-type": {},
      "prefer-nullish-coalescing": {},
      "prefer-optional-chain": {},
      "prefer-type-over-interface": {}
    },
    "regex": {
      "example-no-console-log": {
        "pattern": "console\\.log",
        "message": "Remove console.log before committing"
      }
    },
    "script": {
      "example-no-long-files": {
        "command": "npx tsx script-rules/example-no-long-files.ts",
        "message": "File exceeds 300 lines limit",
        "include": ["packages/**/*.ts", "packages/**/*.rs"]
      }
    }
  },
  "aiRules": {
    "example-find-enum-candidates": {
      "prompt": "example-find-enum-candidates.md",
      "mode": "agentic",
      "message": "Type union could be replaced with an enum for better type safety",
      "severity": "warning",
      "include": ["**/*.ts"]
    }
  },
  "ai": {
    "provider": "claude"
  },
  "files": {
    "include": ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx", "**/*.mjs", "**/*.cjs"],
    "exclude": ["**/node_modules/**", "**/dist/**", "**/build/**", "**/.git/**"]
  },
  "codeEditor": {
    "highlightErrors": true,
    "highlightWarnings": true,
    "highlightInfos": true,
    "highlightHints": true,
    "autoScanInterval": 0,
    "autoAiScanInterval": 0,
    "startupScan": "cached",
    "startupAiScan": "off"
  }
}

{
  "$schema": "https://unpkg.com/tscanner@latest/schema.json",
  "rules": {
    "builtin": {
      "no-explicit-any": {}
    },
    "regex": {},
    "script": {}
  },
  "aiRules": {},
  "files": {
    "include": ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx", "**/*.mjs", "**/*.cjs"],
    "exclude": ["**/node_modules/**", "**/dist/**", "**/build/**", "**/.git/**"]
  }
}

Per-rule file patterns: Each rule can have its own include/exclude patterns:

{
  "rules": {
    "builtin": {
      "no-console": { "exclude": ["src/logger.ts"] },
      "max-function-length": { "include": ["src/core/**/*.ts"] }
    }
  }
}

Inline disables:

// tscanner-ignore-next-line no-explicit-any
const data: any = fetchData();

// tscanner-ignore
// Entire file is skipped

Type Safety (6)

Code Quality (13)

Bug Prevention (4)

Variables (3)

Imports (8)

Style (4)

Define patterns to match in your code using regular expressions:

Config (.tscanner/config.jsonc):

{
  "rules": {
    "regex": {
      "no-rust-deprecated": {
        "pattern": "allow\\(deprecated\\)",
        "message": "No deprecated methods",
        "include": ["packages/rust-core/**/*.rs"]
      },
      "no-process-env": {
        "pattern": "process\\.env",
        "message": "No process env"
      },
      "no-debug-logs": {
        "pattern": "console\\.(log|debug|info)",
        "message": "Remove debug statements",
        "exclude": ["**/*.test.ts"]
      }
    }
  }
}

Run custom scripts in any language (TypeScript, Python, Rust, Go, etc.) that reads JSON from stdin and outputs JSON to stdout.

Input contract (received via stdin):

{
  "files": [
    {
      "path": "src/utils.ts",
      "content": "export function add(a: number, b: number)...",
      "lines": ["export function add(a: number, b: number)", "..."]
    }
  ],
  "options": { "maxLines": 300 },
  "workspaceRoot": "/path/to/project"
}

Output contract (expected via stdout):

{
  "issues": [
    { "file": "src/utils.ts", "line": 10, "message": "Issue description" }
  ]
}

Config (.tscanner/config.jsonc):

{
  "rules": {
    "script": {
      "no-long-files": {
        "command": "npx tsx script-rules/no-long-files.ts",
        "message": "File exceeds 300 lines limit",
        "include": ["**/*.ts", "**/*.rs", "**/*.py", "**/*.go"]
      }
    }
  }
}

#!/usr/bin/env npx tsx
import { stdin } from 'node:process';

async function main() {
  let data = '';
  for await (const chunk of stdin) data += chunk;

  const input = JSON.parse(data);
  const issues = [];

  for (const file of input.files) {
    if (file.lines.length > 300) {
      issues.push({ file: file.path, line: 301, message: `File exceeds 300 lines` });
    }
  }

  console.log(JSON.stringify({ issues }));
}
main().catch((err) => {
  console.error(err);
  process.exit(1);
});

#!/usr/bin/env python3
import json, sys

def main():
    input_data = json.loads(sys.stdin.read())
    issues = []

    for file in input_data["files"]:
        if len(file["lines"]) > 300:
            issues.append({"file": file["path"], "line": 301, "message": "File exceeds 300 lines"})

    print(json.dumps({"issues": issues}))

if __name__ == "__main__":
    main()

#!/usr/bin/env rust-script
use std::io::{self, Read};
use serde::{Deserialize, Serialize};

#[derive(Deserialize)]
struct ScriptFile { path: String, lines: Vec<String> }

#[derive(Deserialize)]
struct ScriptInput { files: Vec<ScriptFile> }

#[derive(Serialize)]
struct ScriptIssue { file: String, line: usize, message: String }

#[derive(Serialize)]
struct ScriptOutput { issues: Vec<ScriptIssue> }

fn main() -> io::Result<()> {
    let mut data = String::new();
    io::stdin().read_to_string(&mut data)?;
    let input: ScriptInput = serde_json::from_str(&data).unwrap();
    let mut issues = Vec::new();

    for file in input.files {
        if file.lines.len() > 300 {
            issues.push(ScriptIssue { file: file.path, line: 301, message: "File exceeds 300 lines".into() });
        }
    }

    println!("{}", serde_json::to_string(&ScriptOutput { issues }).unwrap());
    Ok(())
}

💡 See real examples in the .tscanner/script-rules/ and registry/script-rules/ folders.

Use AI prompts (markdown files) to perform semantic code analysis. Works with any AI provider (Claude, OpenAI, Ollama, etc.).

Modes - How files are passed to the AI: | Mode | Description | Best for | |------|-------------|----------| | paths | Only file paths (AI reads files via tools) | Large codebases, many files | | content | Full file content in prompt | Small files, quick analysis | | agentic | Paths + AI can explore freely | Cross-file analysis, complex patterns |

Placeholders - Use in your prompt markdown: | Placeholder | Replaced with | |-------------|---------------| | {{FILES}} | List of files to analyze (required) | | {{OPTIONS}} | Custom options from config (optional) |

Output contract - AI must return JSON:

{
  "issues": [
    { "file": "src/utils.ts", "line": 10, "column": 1, "message": "Description" }
  ]
}

Config (.tscanner/config.jsonc):

{
  "aiRules": {
    "find-enum-candidates": {
      "prompt": "find-enum-candidates.md",
      "mode": "agentic",
      "message": "Type union could be replaced with an enum",
      "severity": "warning",
      "include": ["**/*.ts", "**/*.tsx", "**/*.rs"]
    },
    "no-dead-code": {
      "prompt": "no-dead-code.md",
      "mode": "content",
      "message": "Dead code detected",
      "severity": "error",
      "include": ["**/*.rs"],
      "options": { "allowTestFiles": true }
    }
  },
  "ai": {
    "provider": "claude"
  }
}

# Enum Candidates Detector

Find type unions that could be replaced with enums.

## What to look for

1. String literal unions: \`type Status = 'pending' | 'active'\`
2. Repeated string literals across files
3. Type unions used as discriminators

## Exploration hints

- Check how the type is used across files
- Look for related constants

---

## Files

{{FILES}}

# Dead Code Detector

Detect dead code patterns.

## Rules

1. No \`#[allow(dead_code)]\` attributes
2. No unreachable code after return/break

## Options

{{OPTIONS}}

## Files

{{FILES}}

💡 See real examples in the .tscanner/ai-rules/ and registry/ai-rules/ folders.

• Biome:
  • multi-crate Rust architecture (cli, core, server separation)
  • LSP server implementation for real-time IDE diagnostics
  • parallel file processing with Rayon
  • SWC parser integration for JavaScript/TypeScript AST
  • visitor pattern for AST node traversal
  • file-level result caching strategy
• ESLint:
  • inline suppression system (disable-next-line, disable-file patterns)
  • precursor on javascript linting concepts
  • inspiration for rule ideas and detection patterns
• Vitest:
  • glob pattern matching techniques for file discovery
• VSCode Bookmarks:
  • sidebar icon badge displaying issue count