@cleartrip/frontguard 0.2.8 → 0.3.0

package/README.md

@@ -0,0 +1,268 @@
+# 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.
+
+---
+
+## Quick Start
+
+### 1. Install
+
+```bash
+# yarn
+yarn add -D @cleartrip/frontguard
+
+# npm
+npm install -D @cleartrip/frontguard
+
+# pnpm
+pnpm add -D @cleartrip/frontguard
+```
+
+### 2. Initialize
+
+```bash
+npx frontguard init
+```
+
+This does three things:
+
+- **Creates `frontguard.config.js`** with all available options as commented examples
+- **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.js` and uncomment the checks you want. Every option is documented inline.
+
+### 4. Set Up CI
+
+Add `BITBUCKET_ACCESS_TOKEN` as a **secured variable** in your Bitbucket repo settings. The token needs permission to **post pull request comments**.
+
+---
+
+## How It Works
+
+```
+PR opened → Bitbucket pipeline triggers → FrontGuard runs all enabled checks
+  → Generates HTML report → Uploads to FreeKit → Posts Markdown comment on PR
+```
+
+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
+
+---
+
+## Checks
+
+| Check | What it does | Default |
+|-------|-------------|---------|
+| **eslint** | Runs ESLint with your project config | Enabled |
+| **prettier** | Verifies Prettier formatting | 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 |
+| **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) |
+
+---
+
+## Bundle Size Strategies
+
+The bundle check supports multiple strategies for extracting the size metric:
+
+| 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 |
+
+### Examples
+
+**Next.js (auto-detected):**
+```js
+// frontguard.config.js — no strategy override needed
+bundle: {
+  buildCommand: 'yarn build',
+  maxDeltaBytes: 50_000,
+}
+```
+
+**Custom script:**
+```js
+bundle: {
+  bundleSizeStrategy: 'custom',
+  bundleSizeCommand: 'node scripts/bundle-size.js',
+  buildCommand: 'yarn build',
+}
+```
+
+**Baseline file** (`.frontguard/bundle-baseline.json`):
+```json
+{ "totalBytes": 245760 }
+```
+
+Commit this to your base branch. FrontGuard compares the current build against it.
+
+---
+
+## Configuration
+
+All configuration lives in `frontguard.config.js` at your project root:
+
+```js
+import { defineConfig } from '@cleartrip/frontguard'
+
+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.
+
+### Shared Org Config
+
+Publish a shared config package and extend it:
+
+```js
+export default defineConfig({
+  extends: '@your-org/frontguard-config/base',
+  checks: {
+    // project-specific overrides
+  },
+})
+```
+
+---
+
+## CLI
+
+```bash
+# Initialize project (config + pipeline + PR template)
+frontguard init
+
+# Run all checks (console + markdown output)
+frontguard run
+
+# Run with markdown-only output
+frontguard run --markdown
+
+# Run in enforce mode (exit 1 on blocking findings)
+frontguard run --enforce
+
+# Generate HTML report + PR comment markdown
+frontguard run --htmlOut report.html --prCommentOut comment.md
+
+# Append manual review notes
+frontguard run --append ./notes.md
+```
+
+---
+
+## Pipeline Integration
+
+### How `init` handles your pipeline
+
+| 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**.
+
+### Required Variables
+
+| Variable | Type | Purpose |
+|----------|------|---------|
+| `BITBUCKET_ACCESS_TOKEN` | Secured | Post PR comments |
+| `FREEKIT_BASE_URL` | Optional | Override report hosting endpoint |
+
+---
+
+## Risk Scoring
+
+The composite risk score is a heuristic combining:
+
+| 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+ |
+
+---
+
+## AI-assisted review and LLM (under development)
+
+These features are **implemented in code but turned off by default** so day-to-day CI stays predictable.
+
+| Feature | Config | Default |
+|---------|--------|---------|
+| **AI-assisted strict** (`ai-assisted-strict` check) | `checks.aiAssistedReview.enabled` | `false` |
+| **LLM appendix + Cursor rules context** | `checks.llm.enabled` | `false` |
+
+When you are ready to try them:
+
+1. Set `checks.aiAssistedReview.enabled: true` for static heuristics on `@frontguard-ai` regions or AI-disclosed PRs (see `frontguard.config.js` 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.
+
+### Cursor rules (LLM only)
+
+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.
+
+---
+
+## Local Development
+
+```bash
+# Run checks locally (same as CI)
+npx frontguard run
+```
+
+---
+
+## Requirements
+
+- **Node.js** >= 18
+- **Bitbucket Cloud** pipelines
+- `BITBUCKET_ACCESS_TOKEN` for PR comments
+
+---
+
+## License
+
+MIT