@cleartrip/frontguard 0.3.1 → 0.3.3

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
 
@@ -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'
@@ -235,7 +253,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

@@ -2768,12 +2768,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)) {
@@ -3154,9 +3162,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,6 +3200,7 @@ 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;
@@ -3199,7 +3208,9 @@ async function loadConfig(cwd) {
       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 +3219,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);
@@ -5149,15 +5175,29 @@ async function bundleBuildPrecheck(cwd, buildCommand) {
   } catch {
     return {
       run: false,
-      message: "Skipped bundle build \u2014 no readable package.json",
-      detail: "Set checks.bundle.buildCommand to your real build (e.g. `vite build`), set checks.bundle.runBuild to false, or add a package.json with the matching script."
+      message: "Bundle check: build not run (unreadable package.json)",
+      detail: [
+        "Front Guard did not start the build because package.json could not be read next to the project root.",
+        "No bundle size was measured.",
+        "",
+        "Fix: ensure package.json exists, or set checks.bundle.runBuild to false to only measure files already on disk."
+      ].join("\n")
     };
   }
   if (!scripts?.[script]) {
+    const keys = scripts ? Object.keys(scripts).sort().join(", ") : "(none)";
     return {
       run: false,
-      message: `Skipped bundle build \u2014 no scripts.${script} in package.json`,
-      detail: "The bundle check runs a production build, then measures the output. Libraries and non-web repos often have no `build` script \u2014 set checks.bundle.runBuild to false, or set checks.bundle.buildCommand to whatever produces your artifacts."
+      message: `Bundle check: build not run (missing scripts["${script}"])`,
+      detail: [
+        `Configured checks.bundle.buildCommand is: \`${buildCommand}\``,
+        `That maps to package.json scripts["${script}"], which is not defined.`,
+        `Existing script names: ${keys}`,
+        "",
+        "Front Guard did not run a production build, so no bundle size was measured (nothing to compare to a baseline).",
+        "",
+        "Fix: set buildCommand to an existing script (e.g. `npm run build:prod` / `yarn run prod:build`), add the missing script, or set checks.bundle.runBuild to false if artifacts are produced elsewhere."
+      ].join("\n")
     };
   }
   return { run: true };
@@ -5184,6 +5224,7 @@ async function runBundle(cwd, config, stack) {
   const strategy = resolveStrategy(cfg.bundleSizeStrategy, stack);
   const preFindings = [];
   let buildStdout = "";
+  let buildExecuted = false;
   if (cfg.runBuild) {
     const parts = tokenizeCommand(cfg.buildCommand);
     if (parts.length === 0) {
@@ -5225,6 +5266,7 @@ async function runBundle(cwd, config, stack) {
         };
       }
       buildStdout = (res.stdout ?? "") + "\n" + (res.stderr ?? "");
+      buildExecuted = true;
     }
   }
   let sizeResult = null;
@@ -5275,6 +5317,23 @@ async function runBundle(cwd, config, stack) {
   const total = sizeResult?.bytes ?? 0;
   const sizeLabel = sizeResult?.label ?? `(no bundle output detected for strategy "${strategy}")`;
   if (total === 0) {
+    const buildSkippedPrecheck = preFindings.some((f4) => f4.id === "bundle-build-skipped");
+    if (buildSkippedPrecheck) {
+      return {
+        checkId: "bundle",
+        findings: preFindings,
+        durationMs: Math.round(performance.now() - t0)
+      };
+    }
+    const emptyDetail = buildExecuted ? [
+      `Strategy "${strategy}" did not find a size after the build finished.`,
+      sizeLabel,
+      "",
+      "For Next.js, confirm `next build` still prints the line `First Load JS shared by all`, or that `.next/static/**/*.js` exists. You can try bundleSizeStrategy `glob` or `custom` if your setup differs."
+    ].join("\n") : [
+      sizeLabel,
+      cfg.runBuild ? "No production build ran successfully before this measurement (unexpected)." : "checks.bundle.runBuild is false \u2014 only existing files on disk are measured. Run a build earlier in the pipeline, or set runBuild to true."
+    ].join("\n");
     return {
       checkId: "bundle",
       findings: [
@@ -5282,9 +5341,8 @@ async function runBundle(cwd, config, stack) {
         {
           id: "bundle-empty",
           severity: "info",
-          message: `No bundle size detected (strategy: ${strategy})`,
-          detail: `${sizeLabel}
-Ensure the build produces artifacts, or switch to a different bundleSizeStrategy.`
+          message: buildExecuted ? `No bundle size extracted (strategy: ${strategy})` : `No bundle size detected (strategy: ${strategy})`,
+          detail: emptyDetail
         }
       ],
       durationMs: Math.round(performance.now() - t0)
@@ -6859,7 +6917,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");
 }
@@ -7387,7 +7445,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"
     );
   }
 });