@cleartrip/frontguard 0.3.2 → 0.3.4

package/README.md

@@ -27,7 +27,7 @@ npx frontguard init
 
 This does three things:
 
-- **Creates `frontguard.config.js`** with all available options as commented examples
+- **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)
 
@@ -35,7 +35,7 @@ This does three things:
 
 ### 3. Configure
 
-Open `frontguard.config.js` and uncomment the checks you want. Every option is documented inline.
+Open `frontguard.config.mjs` and uncomment the checks you want. Every option is documented inline.
 
 ### 4. Set Up CI
 
@@ -61,8 +61,8 @@ The PR comment includes:
 
 | Check | What it does | Default |
 |-------|-------------|---------|
-| **eslint** | Runs ESLint with your project config | Enabled |
-| **prettier** | Verifies Prettier formatting | Enabled |
+| **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 |
@@ -95,7 +95,7 @@ The bundle check supports multiple strategies for extracting the size metric:
 
 **Next.js (auto-detected):**
 ```js
-// frontguard.config.js — no strategy override needed
+// frontguard.config.mjs — no strategy override needed
 bundle: {
   buildCommand: 'yarn build',
   maxDeltaBytes: 50_000,
@@ -122,7 +122,25 @@ Commit this to your base branch. FrontGuard compares the current build against i
 
 ## Configuration
 
-All configuration lives in `frontguard.config.js` at your project root:
+FrontGuard loads the first file that exists, in order: **`frontguard.config.mjs`** → **`frontguard.config.cjs`** → **`frontguard.config.js`**.
+
+- **`.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`):
+
+```js
+// frontguard.config.cjs
+module.exports = {
+  checks: {
+    bundle: { buildCommand: 'yarn build:prod', bundleSizeStrategy: 'next' },
+  },
+}
+```
+
+- **`.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).
+
+**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>`.
+
+All configuration lives in one of those files at your project root (same directory you run `frontguard` from):
 
 ```js
 import { defineConfig } from '@cleartrip/frontguard'
@@ -150,6 +168,14 @@ export default defineConfig({
 
 Run `frontguard init` to generate a config file with every option documented as comments.
 
+### ESLint / Prettier vs `frontguard.config.*`
+
+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`.
+
+### Bitbucket PR comment table
+
+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
 
 Publish a shared config package and extend it:
@@ -235,7 +261,7 @@ These features are **implemented in code but turned off by default** so day-to-d
 
 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).
+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.

package/dist/cli.js

@@ -8,8 +8,9 @@ import path6, { sep, normalize, delimiter, resolve, dirname } from 'path';
 import fs from 'fs/promises';
 import { execFileSync, spawn } from 'child_process';
 import { createRequire } from 'module';
-import fs2 from 'fs';
+import fs3 from 'fs';
 import { pathToFileURL } from 'url';
+import picomatch from 'picomatch';
 import fg from 'fast-glob';
 import { pipeline } from 'stream/promises';
 import { PassThrough } from 'stream';
@@ -2430,16 +2431,28 @@ export default defineConfig({
   checks: {
     // \u2500\u2500\u2500 ESLint \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
     // Runs ESLint using your project config on PR-scoped files.
+    // Default ignores frontguard.config.{mjs,js,cjs} (tool config, not app code).
     // eslint: {
     //   enabled: true,
-    //   glob: '**/*.{js,cjs,mjs,jsx,ts,tsx}',   // files to lint
+    //   glob: '**/*.{js,cjs,mjs,jsx,ts,tsx}',
+    //   ignorePatterns: [
+    //     '**/frontguard.config.mjs',
+    //     '**/frontguard.config.js',
+    //     '**/frontguard.config.cjs',
+    //   ],
     // },
 
     // \u2500\u2500\u2500 Prettier \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
     // Checks that files match Prettier formatting.
+    // Default ignores the same FrontGuard config filenames as ESLint.
     // prettier: {
     //   enabled: true,
     //   glob: '**/*.{js,cjs,mjs,jsx,ts,tsx,json,md,css,scss,yml,yaml}',
+    //   ignorePatterns: [
+    //     '**/frontguard.config.mjs',
+    //     '**/frontguard.config.js',
+    //     '**/frontguard.config.cjs',
+    //   ],
     // },
 
     // \u2500\u2500\u2500 TypeScript \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
@@ -2768,12 +2781,20 @@ function findEndOfLastSection(lines, pipelinesIdx) {
 }
 async function initFrontGuard(cwd) {
   const actions = [];
-  const cfgPath = path6.join(cwd, "frontguard.config.js");
-  if (!await fileExists(cfgPath)) {
+  const cfgCandidates = [
+    "frontguard.config.mjs",
+    "frontguard.config.js",
+    "frontguard.config.cjs"
+  ];
+  const cfgPath = path6.join(cwd, "frontguard.config.mjs");
+  const hasAny = await Promise.all(
+    cfgCandidates.map((n3) => fileExists(path6.join(cwd, n3)))
+  ).then((xs) => xs.some(Boolean));
+  if (!hasAny) {
     await fs.writeFile(cfgPath, CONFIG_TEMPLATE, "utf8");
-    actions.push("created frontguard.config.js");
+    actions.push("created frontguard.config.mjs");
   } else {
-    actions.push("frontguard.config.js already exists (skipped)");
+    actions.push("frontguard config already exists (.mjs / .js / .cjs) \u2014 skipped");
   }
   const prTplPath = path6.join(cwd, "pull_request_template.md");
   if (!await fileExists(prTplPath)) {
@@ -2829,18 +2850,13 @@ function mdTableCell(s3) {
   return s3.replace(/\|/g, "\\|").replace(/\r?\n/g, " ").trim();
 }
 function statusForPrTable(r4) {
-  if (r4.skipped) {
-    const t3 = r4.skipped.replace(/\s+/g, " ").trim();
-    const short = t3.length > 120 ? `${t3.slice(0, 117)}\u2026` : t3;
-    return `Skipped \u2014 ${short}`;
-  }
   const n3 = r4.findings.length;
   const blocks = r4.findings.filter((f4) => f4.severity === "block").length;
   if (blocks > 0) return `${n3} issue(s), ${blocks} blocking`;
   return `${n3} issue(s)`;
 }
 function checkNeedsRow(r4) {
-  return Boolean(r4.skipped) || r4.findings.length > 0;
+  return !r4.skipped && r4.findings.length > 0;
 }
 function formatBitbucketPrSnippet(report) {
   const publicReport = process.env.FRONTGUARD_PUBLIC_REPORT_URL?.trim();
@@ -3059,16 +3075,99 @@ function createDefu2(merger) {
   );
 }
 var defu2 = createDefu2();
+function normalizePrPath(p2) {
+  return p2.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function hasPrFileList(pr) {
+  return Boolean(pr?.files?.length);
+}
+function prPathSet(pr) {
+  if (!hasPrFileList(pr)) return null;
+  return new Set(pr.files.map(normalizePrPath));
+}
+function isPathInPrScope(relOrAbs, cwd, prSet) {
+  const raw = relOrAbs.replace(/^file:\/\//, "");
+  let rel = normalizePrPath(raw);
+  if (path6.isAbsolute(raw)) {
+    rel = normalizePrPath(path6.relative(cwd, raw));
+  }
+  if (prSet.has(rel)) return true;
+  const trimmed = rel.replace(/^\.\//, "");
+  if (prSet.has(trimmed)) return true;
+  return false;
+}
+var ESLINT_EXT = /\.(js|cjs|mjs|jsx|ts|tsx)$/i;
+var PRETTIER_EXT = /\.(js|cjs|mjs|jsx|ts|tsx|json|md|css|scss|sass|less|yml|yaml|vue|svelte)$/i;
+var CYCLES_EXT = /\.(tsx?|jsx?|mjs|cjs|js)$/i;
+function filterPrFilesForEslint(pr) {
+  if (!hasPrFileList(pr)) return null;
+  return pr.files.map(normalizePrPath).filter((f4) => ESLINT_EXT.test(f4));
+}
+function filterPrFilesForPrettier(pr) {
+  if (!hasPrFileList(pr)) return null;
+  return pr.files.map(normalizePrPath).filter((f4) => PRETTIER_EXT.test(f4));
+}
+function filterPrFilesForMadge(pr) {
+  if (!hasPrFileList(pr)) return null;
+  return pr.files.map(normalizePrPath).filter((f4) => CYCLES_EXT.test(f4));
+}
+async function existingRepoPaths(cwd, rels) {
+  const out = [];
+  for (const rel of rels) {
+    try {
+      await fs.access(path6.join(cwd, rel));
+      out.push(rel);
+    } catch {
+    }
+  }
+  return out;
+}
+function filterTscOutputToPrFiles(output, cwd, prSet) {
+  const lines = output.split("\n");
+  const kept = [];
+  for (const line of lines) {
+    const m3 = /^(.+?)\(\d+,\d+\):\s/.exec(line);
+    if (m3?.[1]) {
+      if (isPathInPrScope(m3[1], cwd, prSet)) kept.push(line);
+      continue;
+    }
+  }
+  return kept.join("\n").trim();
+}
+
+// src/lib/glob-ignore.ts
+var DEFAULT_FRONTGUARD_CONFIG_IGNORE_PATTERNS = [
+  "**/frontguard.config.mjs",
+  "**/frontguard.config.js",
+  "**/frontguard.config.cjs"
+];
+function pathMatchesIgnorePatterns(relPath, patterns) {
+  if (patterns.length === 0) return false;
+  const posixRel = normalizePrPath(relPath);
+  for (const pattern of patterns) {
+    const pm = picomatch(pattern, { dot: true });
+    if (pm(posixRel) || pm(`./${posixRel}`)) return true;
+  }
+  return false;
+}
+function negatedPrettierGlobs(patterns) {
+  return patterns.map((p2) => p2.startsWith("!") ? p2 : `!${p2}`);
+}
 
 // src/config/defaults.ts
 var defaultConfig = {
   mode: "warn",
   rules: {},
   checks: {
-    eslint: { enabled: true, glob: "**/*.{js,cjs,mjs,jsx,ts,tsx}" },
+    eslint: {
+      enabled: true,
+      glob: "**/*.{js,cjs,mjs,jsx,ts,tsx}",
+      ignorePatterns: [...DEFAULT_FRONTGUARD_CONFIG_IGNORE_PATTERNS]
+    },
     prettier: {
       enabled: true,
-      glob: "**/*.{js,cjs,mjs,jsx,ts,tsx,json,md,css,scss,yml,yaml}"
+      glob: "**/*.{js,cjs,mjs,jsx,ts,tsx,json,md,css,scss,yml,yaml}",
+      ignorePatterns: [...DEFAULT_FRONTGUARD_CONFIG_IGNORE_PATTERNS]
     },
     typescript: { enabled: true },
     secrets: { enabled: true },
@@ -3154,9 +3253,9 @@ function migrateLegacyConfigKeys(config) {
 
 // src/config/load.ts
 var CONFIG_NAMES = [
-  "frontguard.config.js",
   "frontguard.config.mjs",
-  "frontguard.config.cjs"
+  "frontguard.config.cjs",
+  "frontguard.config.js"
 ];
 async function importConfig(absolutePath) {
   const url = pathToFileURL(absolutePath).href;
@@ -3192,14 +3291,17 @@ async function loadExtendsLayer(cwd, spec) {
 }
 async function loadConfig(cwd) {
   let userFile = null;
+  const loadErrors = [];
   for (const name of CONFIG_NAMES) {
     const full = path6.join(cwd, name);
-    if (!fs2.existsSync(full)) continue;
+    if (!fs3.existsSync(full)) continue;
     try {
       const mod = await importConfig(full);
       userFile = normalizeExport(mod);
       break;
-    } catch {
+    } catch (e3) {
+      const msg = e3 instanceof Error ? e3.message : String(e3);
+      loadErrors.push(`${name}: ${msg}`);
       continue;
     }
   }
@@ -3208,6 +3310,21 @@ async function loadConfig(cwd) {
   migrateLegacyConfigKeys(orgLayer);
   if (userFile) migrateLegacyConfigKeys(userFile);
   const user = userFile ? stripExtends(userFile) : {};
+  if (!userFile) {
+    if (loadErrors.length > 0) {
+      g.stderr.write(
+        `FrontGuard: config file(s) exist under ${path6.resolve(cwd)} but failed to load:
+${loadErrors.map((l3) => `  \u2022 ${l3}`).join("\n")}
+Common fix: use frontguard.config.mjs (ESM, no package.json "type" required), or frontguard.config.cjs with require(). See README.
+`
+      );
+    } else {
+      g.stderr.write(
+        `FrontGuard: no ${CONFIG_NAMES.join(", ")} found under ${path6.resolve(cwd)} \u2014 using built-in defaults only (e.g. checks.bundle.buildCommand defaults to "npm run build"). Add a config file or run from the directory that contains it.
+`
+      );
+    }
+  }
   const base = structuredClone(defaultConfig);
   const withOrg = defu2(orgLayer, base);
   return defu2(user, withOrg);
@@ -3348,65 +3465,6 @@ function stripFrontmatter(content) {
   if (endIdx === -1) return content;
   return content.slice(endIdx + 3).trim();
 }
-function normalizePrPath(p2) {
-  return p2.replace(/\\/g, "/").replace(/^\.\//, "");
-}
-function hasPrFileList(pr) {
-  return Boolean(pr?.files?.length);
-}
-function prPathSet(pr) {
-  if (!hasPrFileList(pr)) return null;
-  return new Set(pr.files.map(normalizePrPath));
-}
-function isPathInPrScope(relOrAbs, cwd, prSet) {
-  const raw = relOrAbs.replace(/^file:\/\//, "");
-  let rel = normalizePrPath(raw);
-  if (path6.isAbsolute(raw)) {
-    rel = normalizePrPath(path6.relative(cwd, raw));
-  }
-  if (prSet.has(rel)) return true;
-  const trimmed = rel.replace(/^\.\//, "");
-  if (prSet.has(trimmed)) return true;
-  return false;
-}
-var ESLINT_EXT = /\.(js|cjs|mjs|jsx|ts|tsx)$/i;
-var PRETTIER_EXT = /\.(js|cjs|mjs|jsx|ts|tsx|json|md|css|scss|sass|less|yml|yaml|vue|svelte)$/i;
-var CYCLES_EXT = /\.(tsx?|jsx?|mjs|cjs|js)$/i;
-function filterPrFilesForEslint(pr) {
-  if (!hasPrFileList(pr)) return null;
-  return pr.files.map(normalizePrPath).filter((f4) => ESLINT_EXT.test(f4));
-}
-function filterPrFilesForPrettier(pr) {
-  if (!hasPrFileList(pr)) return null;
-  return pr.files.map(normalizePrPath).filter((f4) => PRETTIER_EXT.test(f4));
-}
-function filterPrFilesForMadge(pr) {
-  if (!hasPrFileList(pr)) return null;
-  return pr.files.map(normalizePrPath).filter((f4) => CYCLES_EXT.test(f4));
-}
-async function existingRepoPaths(cwd, rels) {
-  const out = [];
-  for (const rel of rels) {
-    try {
-      await fs.access(path6.join(cwd, rel));
-      out.push(rel);
-    } catch {
-    }
-  }
-  return out;
-}
-function filterTscOutputToPrFiles(output, cwd, prSet) {
-  const lines = output.split("\n");
-  const kept = [];
-  for (const line of lines) {
-    const m3 = /^(.+?)\(\d+,\d+\):\s/.exec(line);
-    if (m3?.[1]) {
-      if (isPathInPrScope(m3[1], cwd, prSet)) kept.push(line);
-      continue;
-    }
-  }
-  return kept.join("\n").trim();
-}
 function stripFileUrl(p2) {
   let s3 = p2.trim();
   if (!/^file:/i.test(s3)) return s3;
@@ -4204,6 +4262,8 @@ async function runEslint(cwd, config, _stack, pr) {
     };
   }
   const glob = config.checks.eslint.glob ?? "**/*.{js,cjs,mjs,jsx,ts,tsx}";
+  const ignorePatterns = config.checks.eslint.ignorePatterns ?? DEFAULT_FRONTGUARD_CONFIG_IGNORE_PATTERNS;
+  const ignoreArgs = ignorePatterns.flatMap((p2) => ["--ignore-pattern", p2]);
   const prPaths = filterPrFilesForEslint(pr);
   let exitCode;
   let stdout2;
@@ -4218,7 +4278,8 @@ async function runEslint(cwd, config, _stack, pr) {
       };
     }
     const existing = await existingRepoPaths(cwd, prPaths);
-    if (existing.length === 0) {
+    const lintable = existing.filter((p2) => !pathMatchesIgnorePatterns(p2, ignorePatterns));
+    if (lintable.length === 0) {
       return {
         checkId: "eslint",
         findings: [],
@@ -4226,10 +4287,11 @@ async function runEslint(cwd, config, _stack, pr) {
         skipped: hasPrFileList(pr) ? "no lintable files in PR diff (added/modified only)" : "no files"
       };
     }
-    ({ exitCode, stdout: stdout2, stderr } = await runEslintOnPaths(cwd, existing));
+    ({ exitCode, stdout: stdout2, stderr } = await runEslintOnPaths(cwd, lintable));
   } else {
     ({ exitCode, stdout: stdout2, stderr } = await runNpmBinary(cwd, "eslint", [
       glob,
+      ...ignoreArgs,
       "--max-warnings",
       "0",
       "--no-error-on-unmatched-pattern",
@@ -4331,6 +4393,8 @@ async function runPrettier(cwd, config, pr) {
     };
   }
   const glob = config.checks.prettier.glob ?? "**/*.{js,cjs,mjs,jsx,ts,tsx,json,md,css,scss,yml,yaml}";
+  const ignorePatterns = config.checks.prettier.ignorePatterns ?? DEFAULT_FRONTGUARD_CONFIG_IGNORE_PATTERNS;
+  const prettierNegations = negatedPrettierGlobs(ignorePatterns);
   let exitCode;
   let stdout2;
   let stderr;
@@ -4345,7 +4409,8 @@ async function runPrettier(cwd, config, pr) {
       };
     }
     const existing = await existingRepoPaths(cwd, prPaths);
-    if (existing.length === 0) {
+    const formattable = existing.filter((p2) => !pathMatchesIgnorePatterns(p2, ignorePatterns));
+    if (formattable.length === 0) {
       return {
         checkId: "prettier",
         findings: [],
@@ -4353,12 +4418,13 @@ async function runPrettier(cwd, config, pr) {
         skipped: hasPrFileList(pr) ? "no formattable files in PR diff" : "no files"
       };
     }
-    ({ exitCode, stdout: stdout2, stderr } = await runPrettierOnPaths(cwd, existing));
+    ({ exitCode, stdout: stdout2, stderr } = await runPrettierOnPaths(cwd, formattable));
   } else {
     ({ exitCode, stdout: stdout2, stderr } = await runNpmBinary(cwd, "prettier", [
       "--check",
+      "--ignore-unknown",
       glob,
-      "--ignore-unknown"
+      ...prettierNegations
     ]));
   }
   const findings = [];
@@ -6891,7 +6957,7 @@ function formatMarkdown(p2) {
   );
   sb.push("");
   sb.push(
-    "_Configure checks in `frontguard.config.js` \xB7 [Shields.io](https://shields.io) badge images load in Bitbucket PR comments (HTML tags like `<details>` are not supported there)._"
+    "_Configure checks in `frontguard.config.mjs` (or `.cjs` / `.js`) \xB7 [Shields.io](https://shields.io) badge images load in Bitbucket PR comments (HTML tags like `<details>` are not supported there)._"
   );
   return sb.join("\n");
 }
@@ -7419,7 +7485,7 @@ var init2 = defineCommand({
 `);
     }
     g.stdout.write(
-      "\nNext steps:\n  1. Review frontguard.config.js \u2014 uncomment and tune the checks you need\n  2. Review bitbucket-pipelines.yml \u2014 check the merged FrontGuard step\n  3. Set BITBUCKET_ACCESS_TOKEN as a secured variable in your repo\n  4. Install the package: yarn add -D @cleartrip/frontguard\n\n"
+      "\nNext steps:\n  1. Review frontguard.config.mjs \u2014 uncomment and tune the checks you need\n  2. Review bitbucket-pipelines.yml \u2014 check the merged FrontGuard step\n  3. Set BITBUCKET_ACCESS_TOKEN as a secured variable in your repo\n  4. Install the package: yarn add -D @cleartrip/frontguard\n\n"
     );
   }
 });