@cleartrip/frontguard 0.3.6 → 1.0.0

package/README.md

@@ -1,308 +1,336 @@
 # FrontGuard
 
-Org-wide frontend PR guardrails for Bitbucket Cloud. Runs automated checks on every pull request — linting, type safety, bundle size, secrets, PR hygiene, and more — then posts a summary comment with a link to the full interactive report.
+Automated frontend code quality checks for every pull request. Runs in CI, catches issues before merge, and posts a clean report comment with a link to the full interactive HTML report.
 
 ---
 
-## Quick Start
+## What it checks
+
+| Check | What it does | Runs on |
+|:------|:------------|:--------|
+| **eslint** | Linting with your project's ESLint config | Changed files |
+| **prettier** | Formatting check against your Prettier config | Changed files |
+| **typescript** | `tsc --noEmit` type checking | Whole project |
+| **secrets** | Regex scan for leaked tokens, keys, private keys | Changed files |
+| **pr-hygiene** | PR description length, required sections, AI disclosure | PR metadata |
+| **pr-size** | Flags PRs that are too large to review effectively | PR diff |
+| **ts-any-delta** | Counts new `any` usage introduced in this diff | PR diff |
+| **cycles** | Circular import detection via `madge` | Source tree |
+| **dead-code** | Unused exports via `ts-prune` | Whole project |
+| **bundle** | Bundle size measured after build, compared to a baseline | Build output |
+| **core-web-vitals** | Static JSX/TSX hints for LCP, CLS, FID patterns | Changed files |
+| **react-native** | Metro config, SwiftLint, native file hints (RN projects only) | Changed files |
+| **custom-rules** | Your own file/content checks defined in config | Changed files |
+| **ai-assisted-strict** | Stricter checks on AI-generated code regions | Opt-in |
+
+All checks are **enabled by default** except `ai-assisted-strict` and `llm` (both off by default). Every check can be disabled or tuned individually.
+
+---
+
+## Quick start
 
 ### 1. Install
 
 ```bash
-# yarn
-yarn add -D @cleartrip/frontguard
-
-# npm
 npm install -D @cleartrip/frontguard
-
-# pnpm
+# or
+yarn add -D @cleartrip/frontguard
+# or
 pnpm add -D @cleartrip/frontguard
 ```
 
-### 2. Initialize
+### 2. Initialise
 
 ```bash
 npx frontguard init
 ```
 
-This does three things:
-
-- **Creates `frontguard.config.mjs`** (ESM) with all available options as commented examples — works even when `package.json` is not `"type": "module"`
-- **Creates `pull_request_template.md`** with AI disclosure checkboxes
-- **Merges the FrontGuard step** into your existing `bitbucket-pipelines.yml` (or creates one if missing)
-
-> If your repo already has a `pull-requests:` section in the pipeline, `init` appends the FrontGuard step to it without touching your `image`, `clone`, or other pipeline config.
-
-### 3. Configure
-
-Open `frontguard.config.mjs` and uncomment the checks you want. Every option is documented inline.
-
-### 4. Set Up CI
+This creates three files:
 
-Add `BITBUCKET_ACCESS_TOKEN` as a **secured variable** in your Bitbucket repo settings. The token needs permission to **post pull request comments**.
+- **`frontguard.config.mjs`** — config file with every option documented as comments
+- **`pull_request_template.md`** — PR template with AI disclosure checkboxes
+- **`bitbucket-pipelines.yml`** — creates or updates the pipeline with a FrontGuard step
 
----
-
-## How It Works
+### 3. Run locally
 
-```
-PR opened → Bitbucket pipeline triggers → FrontGuard runs all enabled checks
-  → Generates HTML report → Uploads to FreeKit → Posts Markdown comment on PR
+```bash
+npx frontguard run
 ```
 
-The PR comment includes:
-- **RISK score** (LOW / MEDIUM / HIGH) based on findings and PR size
-- **Table of failing checks** (only checks with issues — clean checks are omitted)
-- **Link to full interactive HTML report** hosted on FreeKit
+Run the same checks locally before pushing. No CI environment needed.
 
 ---
 
-## Checks
-
-| Check | What it does | Default |
-|-------|-------------|---------|
-| **eslint** | Runs ESLint with your project config (skips `frontguard.config.*` by default) | Enabled |
-| **prettier** | Verifies Prettier formatting (skips `frontguard.config.*` by default) | Enabled |
-| **typescript** | Runs `tsc --noEmit` for type errors | Enabled |
-| **secrets** | Scans for leaked tokens, keys, passwords | Enabled |
-| **pr-hygiene** | Validates PR description, sections, AI disclosure | Enabled |
-| **pr-size** | Flags oversized PRs by line count | Enabled |
-| **ts-any-delta** | Counts new `any` usage in the diff | Enabled |
-| **cycles** | Detects circular imports via madge | Enabled |
-| **dead-code** | Finds unused exports via ts-prune | Enabled |
-| **bundle** | Measures bundle size, compares to baseline | Enabled |
-| **react-native** | Metro config, optional align-deps / doctor, SwiftLint + native hints (RN deps only) | Enabled |
-| **core-web-vitals** | Static CWV hints in JSX/TSX | Enabled |
-| **ai-assisted-strict** | Static heuristics on AI-marked code / AI PRs | **Off** (under development) |
-| **custom-rules** | Your own pattern checks defined in config | Enabled |
-| **llm** | Automated diff review / fix hints | **Off** (under development) |
-
----
+## Configuration
 
-## React Native check (`react-native`)
+Config lives in `frontguard.config.mjs` (recommended), `frontguard.config.cjs`, or `frontguard.config.js` at your project root.
 
-Runs when `react-native` is in dependencies (skipped otherwise).
+```js
+// frontguard.config.mjs
+import { defineConfig } from '@cleartrip/frontguard'
 
-| Sub-feature | Default | Notes |
-|-------------|---------|--------|
-| Metro config | **On** | Expects `metro.config.js` (or `.mjs` / `.cjs` / `.ts`) at project root. |
-| `@rnx-kit/align-deps` | **Off** | Set `checks.reactNative.runAlignDeps: true` (uses `npx`, needs registry). Tune `alignDepsArgs` (e.g. `['--requirements', 'react-native@0.76']`). |
-| `react-native doctor` | **Off** | Set `runDoctor: true` where the local CLI exists (can be slow / macOS-heavy). |
-| SwiftLint | **On** (PR only) | If the PR touches `*.swift` and `swiftlint` is on `PATH`, violations are reported; otherwise an info hint. |
-| Android / ObjC hints | **On** (PR only) | Info reminders when `android/**/*.kt|java` or `.m` / `.mm` change — does not run Gradle or Xcode. |
+export default defineConfig({
+  // 'warn'    = advisory only, CI never fails (default)
+  // 'enforce' = CI exits non-zero on any block-severity finding
+  mode: 'warn',
 
-This is intentionally lightweight; you can extend CI with Detekt, Android Lint, or deeper Metro analysis later.
+  checks: {
+    // Tune any check by key — only set what you want to override
+    prSize: {
+      tiers: [
+        { minLines: 800,  severity: 'block', message: 'PR too large (${lines} lines). Split it up.' },
+        { minLines: 400,  severity: 'warn',  message: 'Large PR (${lines} lines). Consider splitting.' },
+      ],
+    },
+    bundle: {
+      buildCommand: 'yarn build',
+      maxDeltaBytes: 50_000,   // fail if bundle grows more than 50 kB
+    },
+    // Disable a check entirely
+    deadCode: { enabled: false },
+    // Custom rules — plain JS functions
+    // (see Custom rules section below)
+  },
+})
+```
 
----
+Run `frontguard init` to generate the full annotated template.
 
-## Bundle Size Strategies
+### Severity levels
 
-The bundle check supports multiple strategies for extracting the size metric:
+| Level | Meaning |
+|:------|:--------|
+| `info` | Informational note — never fails CI |
+| `warn` | Advisory — visible in report, CI passes unless `mode: 'enforce'` |
+| `block` | Failing — CI exits non-zero when `mode: 'enforce'` is set |
 
-| Strategy | How it works |
-|----------|-------------|
-| `auto` | Auto-detects from `package.json` — Next.js, Vite, CRA, or falls back to glob |
-| `next` | Parses `next build` stdout for "First Load JS shared by all" |
-| `vite` | Sums JS files under `dist/assets/` after build |
-| `cra` | Parses `react-scripts build` stdout for gzipped JS total |
-| `glob` | Sums raw bytes under `measureGlobs` (generic fallback) |
-| `custom` | Runs your `bundleSizeCommand`, reads a single number (bytes) from stdout |
+### Gate modes
 
-### Examples
+Most checks have a `gate` option that controls the severity of their findings:
 
-**Next.js (auto-detected):**
 ```js
-// frontguard.config.mjs — no strategy override needed
-bundle: {
-  buildCommand: 'yarn build',
-  maxDeltaBytes: 50_000,
-}
+cycles: { gate: 'block' }    // circular deps now fail CI in enforce mode
+tsAnyDelta: { gate: 'warn' } // any usage is advisory (default)
 ```
 
-**Custom script:**
-```js
-bundle: {
-  bundleSizeStrategy: 'custom',
-  bundleSizeCommand: 'node scripts/bundle-size.js',
-  buildCommand: 'yarn build',
-}
-```
+---
 
-**Baseline file** (`.frontguard/bundle-baseline.json`):
-```json
-{ "totalBytes": 245760 }
-```
+## Custom rules
 
-Commit this to your base branch. FrontGuard compares the current build against it.
+Define your own checks inline in the config file. The function receives `{ path, content }` for each file and returns `true` when the rule is violated.
+
+```js
+export default defineConfig({
+  rules: {
+    'no-console-log': {
+      severity: 'warn',
+      message: 'Remove console.log before merging',
+      check: (file) =>
+        /\.(ts|tsx|js|jsx)$/.test(file.path) && /console\.log\(/.test(file.content),
+    },
+    'no-todo-comments': {
+      severity: 'info',
+      message: 'Unresolved TODO comment',
+      check: (file) => /\bTODO\b/.test(file.content),
+    },
+    'no-inline-styles': {
+      severity: 'info',
+      message: 'Prefer CSS classes over inline style objects',
+      check: (file) => /\.tsx$/.test(file.path) && file.content.includes('style={{'),
+    },
+  },
+})
+```
 
 ---
 
-## Configuration
+## Bundle size
 
-FrontGuard loads the first file that exists, in order: **`frontguard.config.mjs`** → **`frontguard.config.cjs`** → **`frontguard.config.js`**.
+The bundle check builds your project and compares the output size against a baseline file you commit to your repo.
 
-- **`.mjs`** — ESM (`import` / `export default`). Use this in CommonJS-only repos (no `"type": "module"` needed). **Recommended.**
-- **`.cjs`** — CommonJS without importing the package (plain object merges like `defineConfig`):
+### Setup
 
-```js
-// frontguard.config.cjs
-module.exports = {
-  checks: {
-    bundle: { buildCommand: 'yarn build:prod', bundleSizeStrategy: 'next' },
-  },
-}
-```
+1. Run your build once and create the baseline:
+   ```bash
+   echo '{ "totalBytes": 245760 }' > .frontguard/bundle-baseline.json
+   git add .frontguard/bundle-baseline.json
+   ```
 
-- **`.js`** — Only reliable as ESM if your `package.json` has `"type": "module"`; otherwise Node may refuse to load it (you will see an ESM warning and defaults will apply).
+2. Configure the check:
+   ```js
+   bundle: {
+     buildCommand: 'yarn build',
+     maxDeltaBytes: 50_000,   // warn/block if bundle grows > 50 kB
+     maxTotalBytes: null,     // or set an absolute cap
+   }
+   ```
 
-**CI / monorepos:** Run `frontguard` with `cwd` set to the app root that contains `package.json` and the config file. **Git:** If you see `fatal: Needed a single revision`, increase clone depth or fetch the PR destination branch (e.g. `git fetch origin main:refs/remotes/origin/main`) so diff and baseline reads can resolve `origin/<branch>`.
+3. FrontGuard reads the baseline from `baselineRef` (default: `main`) when the file is not on disk, so it works in PR pipelines automatically.
 
-All configuration lives in one of those files at your project root (same directory you run `frontguard` from):
+### Size strategies
 
-```js
-import { defineConfig } from '@cleartrip/frontguard'
+| Strategy | Use when |
+|:---------|:---------|
+| `auto` | Most projects — auto-detects Next.js, Vite, CRA, or falls back to glob |
+| `next` | Next.js — reads "First Load JS shared by all" from build output |
+| `vite` | Vite — sums `dist/assets/*.js` |
+| `cra` | Create React App — reads gzipped JS total from build output |
+| `glob` | Custom build tools — sums files matching `measureGlobs` |
+| `custom` | Anything else — runs `bundleSizeCommand`, reads bytes from stdout |
 
-export default defineConfig({
-  mode: 'warn',              // 'warn' or 'enforce'
-  checks: {
-    bundle: {
-      buildCommand: 'yarn build',
-      bundleSizeStrategy: 'auto',
-      maxDeltaBytes: 50_000,
-    },
-    prSize: {
-      tiers: [
-        { minLines: 1000, severity: 'block', message: 'PR too large (${lines} lines)' },
-        { minLines: 500,  severity: 'warn',  message: 'Consider splitting (${lines} lines)' },
-      ],
-    },
-    // AI-assisted + LLM are WIP — leave off unless you opt in explicitly:
-    // aiAssistedReview: { enabled: true },
-    // llm: { enabled: true, provider: 'ollama', model: 'llama3.2' },
-  },
-})
-```
+---
 
-Run `frontguard init` to generate a config file with every option documented as comments.
+## PR hygiene
 
-### ESLint / Prettier vs `frontguard.config.*`
+Validates the PR description when running in CI (requires `FRONTGUARD_PR_BODY` env var):
 
-Defaults exclude `frontguard.config.mjs`, `frontguard.config.js`, and `frontguard.config.cjs` via `checks.eslint.ignorePatterns` and `checks.prettier.ignorePatterns` (picomatch globs, repo-relative). That keeps tool config from being judged by product rules. Set `ignorePatterns: []` on either check if you want those files linted/formatted. To extend the list in shared config, spread `DEFAULT_FRONTGUARD_CONFIG_IGNORE_PATTERNS` from `@cleartrip/frontguard`.
+```js
+prHygiene: {
+  minBodyLength: 80,           // minimum characters in description
+  requireSections: true,       // require headers from sectionHints
+  sectionHints: ['what', 'why', 'test', 'screenshot'],
+  requireAiDisclosureSection: true,  // expect an ## AI disclosure section
+}
+```
 
-### Bitbucket PR comment table
+The `pull_request_template.md` created by `frontguard init` includes the AI disclosure section automatically.
 
-The short PR comment lists **only checks that reported findings**. Skipped checks stay out of that table; the full HTML report still shows every check, including skips.
+---
 
-### Shared Org Config
+## Shared org config
 
-Publish a shared config package and extend it:
+Publish defaults to an npm package and extend them in each repo:
 
 ```js
+// frontguard.config.mjs
 export default defineConfig({
-  extends: '@your-org/frontguard-config/base',
+  extends: '@your-org/frontguard-config',
   checks: {
-    // project-specific overrides
+    // repo-specific overrides
   },
 })
 ```
 
+The org config is deep-merged as a base layer. Individual repos only need to set what differs.
+
 ---
 
-## CLI
+## CLI reference
 
 ```bash
-# Initialize project (config + pipeline + PR template)
+# Scaffold config, PR template, and pipeline step
 frontguard init
 
-# Run all checks (console + markdown output)
+# Run all checks (console output + markdown report)
 frontguard run
 
-# Run with markdown-only output
+# Fail CI on block-severity findings
+frontguard run --enforce
+
+# Output markdown only (good for capturing in CI logs)
 frontguard run --markdown
 
-# Run in enforce mode (exit 1 on blocking findings)
-frontguard run --enforce
+# Generate HTML report file
+frontguard run --htmlOut report.html
 
-# Generate HTML report + PR comment markdown
-frontguard run --htmlOut report.html --prCommentOut comment.md
+# Generate Bitbucket PR comment markdown
+frontguard run --prCommentOut comment.md
 
-# Append manual review notes
+# Append manual review notes to the report
 frontguard run --append ./notes.md
 ```
 
 ---
 
-## Pipeline Integration
+## CI integration (Bitbucket)
 
-### How `init` handles your pipeline
+`frontguard init` creates or updates `bitbucket-pipelines.yml` with a ready-to-use step. It:
 
-| Scenario | What `init` does |
-|----------|-----------------|
-| No `bitbucket-pipelines.yml` | Creates one with `image`, `clone`, and the FrontGuard step |
-| File exists, no `pull-requests:` section | Appends a `pull-requests:` section with the FrontGuard step |
-| File exists, `pull-requests:` with existing steps | Appends the FrontGuard step after your existing steps |
-| FrontGuard step already present | Skips (no duplicate) |
-
-Your `image`, `clone`, `definitions`, and other pipeline sections are **never modified**.
+1. Runs all checks
+2. Generates an HTML report
+3. Uploads it to [FreeKit](https://freekit.dev) (static hosting, free, no login)
+4. Posts a comment on the PR with the risk score and a link to the full report
 
-### Required Variables
+### Required variables
 
-| Variable | Type | Purpose |
-|----------|------|---------|
-| `BITBUCKET_ACCESS_TOKEN` | Secured | Post PR comments |
-| `FREEKIT_BASE_URL` | Optional | Override report hosting endpoint |
+Add these as secured variables in your Bitbucket repo settings:
 
----
+| Variable | Required | Purpose |
+|:---------|:---------|:--------|
+| `BITBUCKET_ACCESS_TOKEN` | Yes | Post PR comments |
+| `FREEKIT_BASE_URL` | No | Override report hosting (default: `https://freekit.dev`) |
+| `FRONTGUARD_PR_BODY` | No | Pass PR description to `pr-hygiene` check |
 
-## Risk Scoring
+### Pipeline init scenarios
 
-The composite risk score is a heuristic combining:
+| Situation | What `init` does |
+|:----------|:----------------|
+| No `bitbucket-pipelines.yml` | Creates one with `image`, `clone`, and the FrontGuard step |
+| File exists, no `pull-requests:` section | Appends a `pull-requests:` section |
+| File exists, `pull-requests:` present | Appends the FrontGuard step after existing steps |
+| FrontGuard step already present | Skips (no duplicates) |
 
-| Signal | LOW | MEDIUM | HIGH |
-|--------|-----|--------|------|
-| Blocking findings | 0 | — | 1+ |
-| Warning count | < 3 | 3–7 | 8+ |
-| PR size (lines) | < 400 | 400–799 | 800+ |
-| Changed files | < 25 | — | 25+ |
+Your `image`, `clone`, `definitions`, and other pipeline config are never modified.
 
 ---
 
-## AI-assisted review and LLM (under development)
+## Risk scoring
 
-These features are **implemented in code but turned off by default** so day-to-day CI stays predictable.
+The risk score is a heuristic shown at the top of every report.
 
-| Feature | Config | Default |
-|---------|--------|---------|
-| **AI-assisted strict** (`ai-assisted-strict` check) | `checks.aiAssistedReview.enabled` | `false` |
-| **LLM appendix + Cursor rules context** | `checks.llm.enabled` | `false` |
+| Score | When |
+|:------|:-----|
+| 🔴 HIGH | 1+ blocking findings, or 8+ warnings, or 800+ changed lines |
+| 🟡 MEDIUM | 3–7 warnings, or 400–799 changed lines, or 25+ files changed |
+| 🟢 LOW | No significant findings |
 
-When you are ready to try them:
+The score is informational — it does not affect CI pass/fail by itself.
 
-1. Set `checks.aiAssistedReview.enabled: true` for static heuristics on `@frontguard-ai` regions or AI-disclosed PRs (see `frontguard.config.mjs` comments).
-2. Set `checks.llm.enabled: true` and choose `provider: 'ollama' | 'openai' | 'anthropic'` for automated review text.
+---
 
-**PR template:** The init flow still adds an **AI disclosure** section to `pull_request_template.md` for human reviewers. With AI-assisted review off, that disclosure is recorded as an info finding and does not enable extra static checks until you opt in.
+## React Native
 
-### Cursor rules (LLM only)
+The `react-native` check runs automatically when `react-native` is in your dependencies.
 
-When **`checks.llm.enabled`** is true, FrontGuard loads `.cursor/rules/*.{md,mdc}`, `.cursorrules`, and `AGENTS.md` (up to ~32 kB) and injects them into the LLM prompts. With LLM off, those files are not read.
+| Sub-check | Default | What it does |
+|:----------|:--------|:-------------|
+| Metro config | On | Warns if `metro.config.*` is missing |
+| SwiftLint | On | Runs `swiftlint` when PR touches `.swift` files |
+| Android hint | On | Reminds to run Android Lint when `.kt`/`.java` change |
+| `@rnx-kit/align-deps` | Off | Validates RN dependency alignment (opt-in, needs network) |
+| `react-native doctor` | Off | Runs the RN doctor CLI (opt-in, slow) |
 
 ---
 
-## Local Development
+## AI-assisted review (opt-in)
 
-```bash
-# Run checks locally (same as CI)
-npx frontguard run
+Stricter checks for code written by AI tools. Disabled by default.
+
+```js
+aiAssistedReview: {
+  enabled: true,
+  gate: 'warn',
+  strictScanMode: 'decorator',  // 'decorator' | 'pr-disclosure' | 'both'
+}
 ```
 
+Mark AI-generated code with inline comments:
+
+```ts
+// @frontguard-ai:start
+const result = eval(userInput)  // flagged: eval in AI region
+// @frontguard-ai:end
+```
+
+Detects: `eval()`, `dangerouslySetInnerHTML`, `@ts-ignore`, empty `catch`, `new Function()`, plain HTTP URLs, tokens in `localStorage`, dynamic SQL, and more.
+
 ---
 
 ## Requirements
 
-- **Node.js** >= 18
-- **Bitbucket Cloud** pipelines
-- `BITBUCKET_ACCESS_TOKEN` for PR comments
+- **Node.js** ≥ 18
+- Git (for diff and baseline operations)
+- Bitbucket Cloud pipelines (for PR context and comment posting)
 
 ---