@testgorilla/tgo-code-checker

TGO Code Checker

@testgorilla/tgo-code-checker — a deterministic production-code checker for TestGorilla Angular projects, enforcing the Angular code canon (components, services, directives, signals, naming, files) behind the angular-code-reviewer / angular-code-writer skills as CI-enforceable lint.

Production-code sibling of @testgorilla/tgo-testing-checker (test rules); shares the @testgorilla/tgo-checker-core engine, so both emit the same JSON the tgo-graph PR gate consumes via --import-findings.

Advisory by default. Every rule ships at warning; the checker exits 0 until a rule is promoted to error. Complements, never duplicates, the ESLint preset @testgorilla/tgo-linting; see RULES.md for the split.

Quick start

# Scan the whole source tree
npx tgo-code-checker --src src

# Diff-scope to a PR's changed files (what CI runs)
git diff --name-only origin/main...HEAD > changed.txt
npx tgo-code-checker --src src --files-from changed.txt

# Machine-readable output (the gate's --import-findings contract)
npx tgo-code-checker --src src --json

# Only specific rules
npx tgo-code-checker --rule FE-CMP-01,FE-SIG-02

# List every rule (id, severity, canon slug, name, description)
npx tgo-code-checker --list-rules

CLI flags

Flag	Description
--src <path>	Source root to scan (default: src).
--config <path>	Per-repo JSON config merged over the defaults (enable/severity).
--files <paths>	Comma-separated changed files (repo-relative): scan only these.
--files-from <path>	Read the changed-file list (one per line), e.g. git diff --name-only.
--exclude <glob>	Skip files matching this glob (repeatable; * spans /). Additive to the config's exclude; the generated @api/ client is excluded by default.
--rule <ids>	Comma-separated rule IDs to run (e.g. FE-CMP-01).
--json	Emit JSON (top-level totals + violationsByRule + failed files[] + sections[]).
--errors-only / --warnings-only	Filter which severities are displayed.
--group-by rule	Group the human report by rule instead of by file.
--compact	Summary only — no per-violation lines.
--list-rules	Print the rule table and exit.
-h, --help	Show usage and exit.

Exit code is 1 iff any error-severity violation is found — 0 while the whole tier is warning. Diagnostics go to stderr so --json stdout stays clean.

Per-repo config

{
  "srcRoot": "src",
  "exclude": ["@api/*", "*/@api/*", "src/generated/*"], // replaces the default; skips generated code
  "rules": {
    "FE-CMP-01": { "enabled": true, "severity": "error" }, // promote to blocking
    "FE-TPL-02": { "enabled": false }                       // opt out
  }
}

Only overridden entries need appear; the rest keep their defaults (enabled: true, severity: warning). exclude replaces the built-in default (["@api/*", "*/@api/*"], the generated tgo-yasag client); --exclude flags are additive. A repo whose generated client is at src/api/ (no @) sets "exclude": ["api/*", "*/api/*"] here.

Rules

The full catalog — each FE-* ID, the tgo-ai-knowledge canon slug it enforces, what it fires on, deferred bullets, and calibration — is in RULES.md. Eleven rules today (components, DI, signals, forms, naming, files, templates); Canopy and translations are planned tier 2.

Architecture

@testgorilla/tgo-checker-core   engine + rule/report model + AST helpers + reporter
        ▲                       (shared with tgo-testing-checker)
        │
src/code-domain.ts              production file surfaces + test-file exclusion + sections
src/rules/ast/*  grep/*         one file per rule (FE-*), registered in ast-rules.ts / grep-rules.ts
src/config/default-config.ts    the rule enable/severity registry (all warning)
src/index.ts                    CLI (bin: tgo-code-checker)

• AST rules parse with the TypeScript compiler API (a peer dependency, so the consumer repo's TS version is used); return [] on parse failure.
• grep rules run line regexes (template *.component.html checks).
• Test & mock files (*.spec.ts, *.test.ts, *.mock.ts, *.mocks.ts, and __tests__/ / __mocks__/ / mocks/ dirs) are excluded from production scanning by the file domain — production conventions don't apply to test doubles.
• Generated code is skipped via the exclude globs (default: the @api/ client) plus any --exclude flags.

CI / gate integration

Drop the diff-scoped --json run into a repo's CI as a required status check, or feed its output to the tgo-graph gate via --import-findings (JSON shape is identical to the test checker's). Gating on FE-* findings requires code_rules in the gate's --fail-on and an error-severity rule — a no-op while the tier is advisory.

Development

nx test tgo-code-checker      # jest
nx lint tgo-code-checker
nx build tgo-code-checker     # tsc -> dist/packages/tgo-code-checker (builds core first)

Adding or tuning a rule: follow the Maintaining section of RULES.md.