V07-ts-quality

Files (1)

• SKILL.md

SKILL.md (first lines)

# V07 — ts-quality

> **Owner**: `hooks/validators/ts_quality.py`
> **Tier**: 2 (PostToolUse) — per-file regex (any/colors/console/MUI) + single-file `eslint`. 3 (Stop) — adds project-wide `tsc --noEmit`, full `eslint`, `madge --circular`, `knip` (dead code).
> **File patterns**: `**/*.ts`, `**/*.tsx`, `**/package.json`, `**/tsconfig.json`

## Rules

| Rule ID | Severity | When |
|---|---|---|
| `V07-NO-ANY` | warning | Edited file uses `: any` / `as any` / `<any>` (matched outside comments and strings). |
| `V07-HARDCODED-COLOR` | warning | Inline style with literal `#hex` / `rgb(...)` / `rgba(...)` / `hsl(...)`. Theme-token recommended. |
| `V07-NO-CONSOLE` | warning | `console.log` / `console.debug` / `console.info` outside test / Storybook files. |
| `V07-DEPRECATED-MUI` | warning | `makeStyles`, `withStyles`, or `@material-ui/` import (MUI v4 patterns deprecated in v5). |
| `V07-ESLINT-<rule>` | error | `eslint --format json` reported an issue; original ESLint rule name preserved. |
| `V07-TSC-<code>` | error | `tsc --noEmit --pretty` printed `(.+)\((\d+),\d+\): error (TS\d+): (.+)`. |
| `V07-CIRCULAR-IMPORT` | warning | `madge --circular --json src/` returned a cycle. |
| `V07-UNUSED-CODE` | warning | `knip` reported dead exports / files / dependencies. |
| `V07-VITE-ENV-TYPED` | warning | `import.meta.env.VITE_*` referenced in code but not declared in `web/src/vite-env.d.ts` (or `env.d.ts`). |

## Why this verifier exists

The TypeScript ecosystem's value comes from the *combination* of `tsc`, `eslint`, and per-tool conventions — each by itself is incomplete:

- `tsc --noEmit` proves type correctness but says nothing about style.
- `eslint` catches style + suspicious patterns but defers to `tsc` for types.
- `madge` finds cycles that don't fail compilation but cause runtime initialization order bugs.
- `knip` finds dead code that bloats bundles + maintenance surface.

V07 packages all four into hook checks so the user doesn't have to remember which tool to run for which problem. Plus the four cheap regexes (`any`, hardcoded colors, console.log, MUI v4 imports) catch the most-common-instant-fix issues that AI agents are slowest to self-correct.

## Design rationale

### Cache strategy

V07 uses two tool-native cache mechanisms to speed up repeated runs:

**ESLint — `--cache --cache-strategy content --cache-location .verifiers/cache/eslint/`**

Applied in both `_check_eslint_single` (Tier 2) and `_check_eslint_full` (Tier 3). ESLint writes per-file cache entries inside `.verifiers/cache/eslint/`. `--cache-strategy content` uses SHA-based invalidation instead of mtime, which is more reliable on CI and across checkouts.

A lock-file gate (`_invalidate_eslint_cache_if_lock_changed`) computes a SHA-256 of `web/bun.lockb` (falling back to `package-lock.json` / `yarn.lock`) and stores it in `.verifiers/cache/eslint/.lock-hash`. If the lock hash changes (e.g. after `bun add`), the entire cache directory is deleted before ESLint runs, guarding against "plugin upgraded but cache still says PASS".

**TypeScript — `--incremental --tsBuildInfoFile .verifiers/cache/tsc.tsbuildinfo`**

Applied in `_check_tsc` (Tier 3 only). TypeScript writes a single `.tsbuildinfo` JSON file that tracks per-file type state. Only enabled when TypeScript ≥ 5.0 is detected (`_supports_incremental`), because TS 4.x had known bugs with `noEmit + incremental` combined.

**Cache paths**

| Tool | Path |
|---|---|
| ESLint cache dir | `<project_root>/.verifiers/cache/eslint/` |
| ESLint lock hash | `<project_root>/.verifiers/cache/eslint/.lock-hash` |
| TypeScript build info | `<project_root>/.verifiers/cache/tsc.tsbuildinfo` |

**Escape hatch — `VERIFIERS_NO_CACHE=1`**

Set this env var to disable all cache flags for both ESLint and tsc. Useful for CI jobs that must verify from a clean state or when debugging stale-cache issues:

```bash
VERIFIERS_NO_CACHE=1 python hooks/validators/ts_quality.py
```

- **`any` warning, not error.** Sometimes `any` is the right escape hatch (e.g. third-party lib without types). The warning surfaces it for review without blocking.
- **Hardcoded color regex is style-attribute-only.** A regex that flagged `const RED = "#f00"` would explode with false positives. V07 only flags when the literal is in a `style={{...}}` JSX prop or `style.color =` assignment.
- **`console.log` exempt for test / Storybook.** Files matching `*.test.ts(x)`, `*.spec.ts(x)`, `*.stories.tsx`, `__tests__/` are skipped — those are the legitimate use cases.
- **MUI deprecation rule.** `makeStyles` / `withStyles` survived v5 via `@mui/styles` but are officially deprecated. V07 doesn't enforce migration per se — just warns so it's visible in code review.
- **JSON output for tsc / eslint / madge / knip.** Each tool has a `--format json` flag; V07 uses it. Text-format parsing is fragile across versions.
- **`bun` / `bunx` over `npm` / `npx`.** V07 invokes via `bun run eslint --format json` and `bunx madge --circular --json src/`. The user's project chose Bun; running the wrong package manager spawns a separate dependency tree and produces inconsistent results.

## How it checks (implementation)

Lives in `hooks/validators/ts_quality.py`. `validate_file` runs the per-edit fast-path; `validate_project` runs the project-wide heavy-path.

### Tier 2 (`validate_file`)

```python
def validate_file(self, ctx, file_path):
    if not (ctx.web_dir and ctx.web_dir.exists()):
        return []
    if not file_path.endswith((".ts", ".tsx")):
        return []
    findings: list[Finding] = []
    findings.extend(self._check_any_type(file_path))
    findings.extend(self._check_hardcoded_colors(file_path))
    findings.extend(self._check_console_log(file_path))
    findings.extend(self._check_deprecated_mui(file_path))
    findings.extend(self._check_eslint_single(ctx, file_path))
    return findings
```

### `_check_any_type(file_path)` — V07-NO-ANY

```python
ANY = re.compile(r'(?:^|\s|[<,(=])(:?\s*any\b|as\s+any\b|<any[,>])')
COMMENT = re.compile(r'^\s*(//|\*|/\*)')
for line_num, line in enumerate(file.read_text().splitlines(), 1):
    if COMMENT.match(line):
        continue
    if ANY.search(line):
        yield Finding(rule="V07-NO-ANY", line=line_num, ...)
```

The character-class boundary (`[<,(=]`) avoids matching identifiers like `manyHandlers`. Comment skip is naive (only line-prefix); a real tokenizer would also skip JSX comments and strings — currently a known false-positive source.

### `_check_hardcoded_colors(file_path)` — V07-HARDCODED-COLOR

```python
STYLE = re.compile(
    r'style\s*=\s*\{\{[^}]*?(#[0-9a-f]{3,8}|rgba?\(|hsla?\()',
    re.IGNORECASE
)
```

Triggers only inside `style={{...}}` so a `const TOKEN_RED = "#f00"` constant doesn't fire.

### `_check_console_log(file_path)` — V07-NO-CONSOLE

```python
TEST_PATH = ("__tests__/", ".test.", ".spec.", ".stories.")

From HwangTaehyun/verifiers, MIT.

More from HwangTaehyun/verifiers