Static Analysis Rule Runner

Project roadmap

1. 01

   Design the rule system

   ~2h

   Write DESIGN.md: a rule has an id, a description, a default severity, a Zod schema for its options, and a create(context) function returning visitor callbacks for node kinds; a finding has the file, start and end position, rule id, severity and message; the config file enables rules and sets their options. Describe the output formats and caching. Done when: DESIGN.md defines rules, findings, config and outputs.

2. 02

   Parse files and walk the tree

   ~2.5h

   Create a TypeScript project using the typescript package. Find the files to analyze from a tsconfig.json, parse each with ts.createSourceFile (or a Program when rules need type information), and walk every node with ts.forEachChild, calling each enabled rule's callbacks for matching node kinds. Convert positions to line and column with getLineAndCharacterOfPosition. Done when: a debug rule can print every function name with its line.

3. 03

   Write the first rules

   ~3h

   Implement at least five rules: no-console (with allowed methods as an option), max-function-lines, no-banned-imports (a list of module names), no-floating-promises (a call returning a Promise that isn't awaited or handled, using the type checker), and prefer-const (let variables never reassigned). Validate each rule's options with its Zod schema and report config errors clearly. Done when: each rule finds its problems in fixture files.

4. 04

   Report findings

   ~2h

   Print findings as readable text grouped by file with the line of code and a marker under the problem, as JSON, or as SARIF 2.1 for code hosting sites. Support disabling a rule on one line with a comment (// analyzer-disable-next-line rule-id). Exit with code 1 when errors are found. Done when: all three formats work, and disable comments are respected.

5. 05

   Handle large projects

   ~2h

   Cache results per file, keyed by a hash of the file content, the rule config and the tool version, and reuse them for unchanged files. Report files that fail to parse without stopping the run, and set a limit on file size. Measure the time on a large open-source TypeScript project with and without the cache and record it in README.md. Done when: a second run on an unchanged project is much faster, and README.md shows the timings.

6. 06

   Build the React viewer

   ~2h

   Build a small React page that loads the JSON output (validated with Zod when loading) and shows findings grouped by file or rule, with counts, filters by severity and rule, and the code line for each finding. Done when: the viewer shows a real project's findings and the filters work.

7. 07

   Test the rules

   ~2h

   Write Vitest tests for each rule using fixture files with the expected findings written in comments (for example // expect: no-console), plus tests for option validation, disable comments, the output formats, and cache invalidation when the config changes. Done when: npm test passes.

Resources

• DocsTypeScript compiler API (wiki)
• DocsTypeScript AST Viewer
• DocsESLint: custom rules (a design to learn from)
• DocsSARIF specification (OASIS)
• DocsZod documentation