Static Code Analysis Typescript

Static Code Analysis for TypeScript Projects

Use this skill when you need to create, review, fix, or modernize static code analysis in a Node.js + TypeScript repository.

It is designed for repositories that use or should use:

• eslint (flat config)
• typescript-eslint
• typescript
• tsconfig.json
• prettier
• eslint-plugin-simple-import-sort (import sorting via ESLint)
• husky
• lint-staged
• package.json scripts
• CI quality gates (GitHub Actions)

When to Use

Use this skill when the user asks things like:

• "set up static analysis for TypeScript"
• "add ESLint / typescript-eslint / Prettier"
• "review our lint, tsc, husky, or lint-staged setup"
• "fix package.json scripts for code quality"
• "prepare CI checks for linting and type checking"
• "standardize naming for static code analysis scripts"
• "audit whether this repo follows current best practices"
• "set up import sorting"
• "replace trivago import sorting plugin"
• "add a CI quality gate workflow"

Goals

This skill should help produce a setup that is:

• explicit
• reproducible
• CI-friendly
• fast enough for local development
• strict enough to catch issues early
• easy to understand from package.json, README.md, and the config files
• portable across Playwright, Cypress, and general TypeScript projects

Recommended Outcome

A strong baseline should usually include:

• ESLint flat config (eslint.config.mjs)
• typescript-eslint for TypeScript-aware linting
• direct typescript dependency when tsc is used directly
• strict tsconfig.json
• clear split between formatting and linting responsibilities
• import sorting via ESLint (eslint-plugin-simple-import-sort)
• husky hook for local guardrails
• lint-staged for staged-file workflows
• CI commands that do not mutate files
• explicit Node version support in package.json#engines
• a CI quality gate (integrated into an existing workflow when one exists)

Concrete baseline files (eslint.config.mjs, package.json scripts, tsconfig, Prettier, Husky, VS Code settings, CI workflows) live in ./resources/example-configs.md.

Procedure

1. Inspect the existing setup

Check at least these files when they exist:

• package.json
• eslint.config.* (or legacy .eslintrc*)
• tsconfig.json
• .prettierrc*
• .prettierignore
• .husky/*
• .github/workflows/*
• .vscode/settings.json
• .vscode/extensions.json
• README.md
• any existing audit or decision documents

Identify:

• what tools are already installed
• whether the repo uses flat config or legacy ESLint config
• whether typescript is direct or transitive
• whether tsc is used as a real gate
• whether prettier is standalone, inside ESLint, or split by file type
• whether commit hooks validate the whole repo or only staged files
• whether CI enforces the same checks as local hooks
• how import sorting is handled (Prettier plugin, ESLint plugin, VS Code, or not at all)
• whether VS Code source.organizeImports could conflict with other import sorting

2. Classify the current architecture

Choose the current model before editing anything:

• Model A - Separate responsibilities: ESLint for code quality; Prettier for formatting; prettier --check used directly; eslint-config-prettier avoids rule conflicts.
• Model B - ESLint also enforces Prettier in TypeScript: eslint-plugin-prettier runs formatting checks inside ESLint, often paired with a separate Prettier CLI check for non-TS files.
• Model C - Mixed or inconsistent: scripts overlap, responsibilities are unclear, TS formatting may be checked twice or not clearly at all.

When possible, make the final state explicit in docs so the split is understandable.

3. Normalize dependency expectations

For TypeScript repositories, prefer these principles:

• if the repo runs tsc, add typescript directly in devDependencies
• if ESLint is used, make the config style explicit and modern (flat config)
• if typescript-eslint is installed, ensure versions are compatible with ESLint and TypeScript
• if tooling requires newer Node versions, declare them in package.json#engines

Typical direct dev dependencies: eslint, @eslint/js, typescript-eslint, typescript, prettier, eslint-config-prettier, eslint-plugin-simple-import-sort, globals, husky, lint-staged, optionally eslint-plugin-prettier and repo-specific plugins such as eslint-plugin-playwright.

If the repository contains Playwright tests, strongly consider:

• eslint-plugin-playwright
• Playwright-specific rule tuning in ESLint
• ignoring generated Playwright artifacts such as playwright-report/** and test-results/**

4. Assess import sorting

Check how imports are currently sorted:

• No sorting → add eslint-plugin-simple-import-sort
• @trivago/prettier-plugin-sort-imports → migrate to eslint-plugin-simple-import-sort (Babel parser, no Prettier 4 support)
• @ianvs/prettier-plugin-sort-imports → consider migrating for cleaner separation
• eslint-plugin-simple-import-sort → already optimal
• eslint-plugin-perfectionist → acceptable if broader sorting rules are wanted
• VS Code source.organizeImports → remove if any other import sorting tool is active; it conflicts

Rationale, decision tree, and step-by-step migrations are in ./resources/import-sorting.md.

After migration, run npx eslint . --fix to normalize all imports, then verify with npx eslint . --max-warnings=0.

5. Normalize script naming in package.json

Prefer predictable script names:

• lint → runs ESLint in non-fix mode and should fail on warnings if that is the chosen policy
• format → mutating formatter run, usually prettier --write
• format:check → non-mutating formatting validation
• tsc:check → tsc --noEmit
• check → aggregate quality command (local, may mutate)
• check:ci → aggregate quality command (CI, non-mutating)
• lint-staged → entrypoint for staged-file validation

Guidelines:

• commands used in CI should not mutate files
• provide both check (local, with --write) and check:ci (CI, with --check)
• if the repo intentionally splits non-TS and TS formatting, make that explicit with names such as format:check and format:check:non-ts

6. Decide how formatting should work

Make one of the following explicit:

• Preferred modern baseline: Prettier CLI validates formatting; ESLint handles code-quality rules; eslint-config-prettier disables formatting-conflicting lint rules.
• Acceptable intentional split: TypeScript files are checked via ESLint + eslint-plugin-prettier; non-TypeScript files are checked by prettier --check; docs clearly explain the split.

Avoid leaving the repo in a state where it is unclear whether *.ts files are checked by Prettier CLI, by ESLint, twice, or not consistently at all.

7. Validate TypeScript configuration

For tsconfig.json, prefer:

• strict: true
• module: "ESNext" when the project uses ESM import/export syntax (the default for modern TypeScript projects)
• moduleResolution: "bundler" - required when module is "ESNext" and TypeScript does not emit code; without it TS falls back to "classic" resolution which cannot resolve node_modules
• noEmit: true when TypeScript is used only for type checking
• explicit baseUrl / paths only when justified

Common mistake: "module": "CommonJS" with "target": "ESNext" - the project writes ESM but tells TypeScript to resolve modules as CJS. See the tsconfig notes in ./resources/example-configs.md for the full rationale.

If the repo uses path aliases, confirm they are supported consistently by TypeScript, runtime/test tooling, and editor tooling.

8. Set up Husky and lint-staged correctly

Recommended pattern:

• lint-staged handles staged-file formatting and fixable lint checks (including import sorting)
• full-project tsc:check may still run in pre-commit or pre-push, depending on repo size and tolerance for slower hooks

Good staged-file mapping examples:

• *.ts → prettier --write, eslint --fix (auto-sorts imports and fixes lint issues)
• *.{json,md,yml,yaml,mjs} → prettier --write

Guidelines:

• use lint-staged for fast local feedback
• avoid running whole-repo ESLint in pre-commit if staged-only checks are enough
• if full tsc:check is too slow for pre-commit, move it to pre-push or CI
• review ignored outputs so formatters and linters do not waste time on generated artifacts

9. Define CI quality gates

A minimal CI quality job should:

1. Install dependencies reproducibly (npm ci)
2. npm run format:check
3. npm run lint
4. npm run tsc:check

Pipeline discovery strategy (IMPORTANT): always prefer integrating quality checks into an existing CI workflow rather than creating a separate one.

1. Search for existing workflows - look in .github/workflows/ for any existing CI pipeline (e.g. playwright-e2e-tests.yml, ci.yml, test.yml, build.yml)
2. If a main pipeline exists - add a quality job to that workflow, with the test job depending on it via needs: quality
3. Only if NO existing pipeline is found - create a new standalone workflow (example in ./resources/example-configs.md)

Why integrate rather than separate: a single workflow gives one status check in PRs, shared triggers and concurrency reduce drift, and needs ensures tests don't waste CI minutes on code that fails basic quality checks.

CI principles:

• use non-mutating commands only
• do not rely solely on local hooks - CI is the authoritative gate
• keep CI aligned with local script names
• use permissions: contents: read for least-privilege
• cache npm dependencies for speed
• match the CI Node version to engines.node from package.json