mfe-guard 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.1
+
+- Manifests and config files saved with a UTF-8 byte-order mark (Windows Notepad) now load.
+- Invalid JSON errors show the line and column, and say so when a URL returned HTML.
+- Patch-only `version-drift` is folded into one summary line; `--verbose` lists each package.
+- Minor `version-drift` now notes which participant will run on the newer version at runtime.
+
+## 0.1.0
+
+- First release: manifest and project modes; rules `singleton-unsatisfied`, `major-mismatch`,
+  `duplicate-name`, `exact-pin`, `not-singleton`, `version-drift`; text and JSON output.

package/README.md

@@ -24,7 +24,7 @@ module @angular/material/autocomplete does not satisfy the requirement of orders
 ## Install
 
 ```bash
-npx mfe-guard check --help        # no install needed
+npx -y mfe-guard check --help     # no install needed
 npm i -D mfe-guard                # or as a dev dependency
 ```
 
@@ -82,7 +82,7 @@ CLI flags are merged on top of the config.
 | `duplicate-name` | error | Two participants share a federation `name` or global/chunk name, so they overwrite each other's modules. |
 | `exact-pin` | warn | A singleton is required as an exact version (`"19.2.1"`), so any patch bump elsewhere breaks it. |
 | `not-singleton` | warn | Framework packages (`@angular/core`, `rxjs`, `zone.js`, `react`, …) shared without `singleton: true`. |
-| `version-drift` | info | Versions differ but are still compatible; shown so you know what will run. |
+| `version-drift` | info | Versions differ but are still compatible. Minor drift is listed with a note on what will actually run; patch-only drift is folded into one line (`--verbose` lists it). |
 
 Secondary entry points (`@angular/material/autocomplete`, `@angular/common/http`, …) are collapsed into their root package, so you get one finding instead of forty.
 
@@ -104,7 +104,7 @@ jobs:
       - run: npx mfe-guard check   # reads mfe-guard.config.json
 ```
 
-Exit codes: `0` ok · `1` findings at or above `--fail-on` (default `error`) · `2` usage or load error. Use `--json` for machine-readable output.
+Exit codes: `0` ok · `1` findings at or above `--fail-on` (default `error`) · `2` usage or load error. Use `--json` for machine-readable output (always includes every finding) and `--verbose` to list patch-only drift in the text report.
 
 ## Programmatic API
 

package/dist/check.js

@@ -131,13 +131,19 @@ export function check(input, opts = {}) {
         else {
             const distinct = [...new Set(providers.map((u) => u.e.version))];
             if (distinct.length > 1) {
+                const drift = new Set(distinct.map((v) => semver.minor(v))).size > 1 ? 'minor' : 'patch';
+                const behind = providers.filter((u) => u.e.version !== winVer).map((u) => u.p.name);
                 add({
                     rule: 'version-drift',
                     severity: 'info',
                     package: pkg,
                     entryPoints,
+                    drift,
                     message: `${pkg} versions differ (${distinct.join(', ')}); singleton resolves to ${winVer}`,
                     details: providers.map((u) => `${u.p.name} ships ${versionLabel(u)}`),
+                    fix: drift === 'minor'
+                        ? `${behind.join(', ')} will run on ${pkg}@${winVer} at runtime — test against it or align on ${winVer}`
+                        : undefined,
                     participants: names,
                 });
             }

package/dist/cli.js

@@ -21,6 +21,7 @@ Options
       --singletons <a,b,...>       project mode: packages treated as singletons ("*" = Nx default)
       --ignore <rule|pkg|rule:pkg,...>
       --fail-on <error|warn|never> exit 1 at this severity (default: error)
+      --verbose                    list every finding, including patch-only version drift
       --json                       machine-readable output
   -h, --help
   -v, --version
@@ -54,6 +55,7 @@ async function main(argv) {
             ignore: { type: 'string' },
             'fail-on': { type: 'string' },
             json: { type: 'boolean' },
+            verbose: { type: 'boolean' },
             help: { type: 'boolean', short: 'h' },
             version: { type: 'boolean', short: 'v' },
         },
@@ -94,7 +96,7 @@ async function main(argv) {
         ignore: [...(config.ignore ?? []), ...(list(values.ignore) ?? [])],
         criticalSingletons: config.criticalSingletons,
     });
-    console.log(values.json ? formatJson(result, VERSION) : formatText(result, VERSION));
+    console.log(values.json ? formatJson(result, VERSION) : formatText(result, VERSION, { verbose: values.verbose }));
     if (failOn === 'never')
         return 0;
     if (result.summary.error > 0)

package/dist/config.js

@@ -1,16 +1,18 @@
 import { readFile } from 'node:fs/promises';
 import { dirname, isAbsolute, resolve } from 'node:path';
+import { parseJson } from './util.js';
 export const DEFAULT_CONFIG_FILE = 'mfe-guard.config.json';
 /** Load a JSON config; relative project/manifest paths resolve against the config file. */
 export async function loadConfig(path) {
     const abs = resolve(path);
-    let raw;
+    let text;
     try {
-        raw = JSON.parse(await readFile(abs, 'utf8'));
+        text = await readFile(abs, 'utf8');
     }
     catch (e) {
         throw new Error(`cannot read config ${path}: ${e.message}`);
     }
+    const raw = parseJson(text, path);
     if (!Array.isArray(raw.participants)) {
         throw new Error(`${path}: "participants" must be an array`);
     }

package/dist/loaders/manifest.js

@@ -1,4 +1,5 @@
 import { readFile } from 'node:fs/promises';
+import { parseJson } from '../util.js';
 /**
  * Parse an `mf-manifest.json` (or `mf-stats.json`) produced by
  * @module-federation/enhanced, webpack or rspack.
@@ -44,12 +45,5 @@ export async function loadManifest(source, label) {
     else {
         text = await readFile(source, 'utf8');
     }
-    let json;
-    try {
-        json = JSON.parse(text);
-    }
-    catch {
-        throw new Error(`${source}: response is not valid JSON`);
-    }
-    return parseManifest(json, source, label);
+    return parseManifest(parseJson(text, source), source, label);
 }

package/dist/loaders/project.js

@@ -1,7 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import semver from 'semver';
 import { join } from 'node:path';
-import { cleanVersion, isRange, matchesPattern } from '../util.js';
+import { cleanVersion, isRange, matchesPattern, parseJson } from '../util.js';
 /** Packages assumed to be shared singletons in project mode unless configured otherwise. */
 export const DEFAULT_SINGLETONS = [
     '@angular/*',
@@ -17,7 +17,7 @@ export const DEFAULT_SINGLETONS = [
 ];
 async function readJson(path) {
     try {
-        return JSON.parse(await readFile(path, 'utf8'));
+        return parseJson(await readFile(path, 'utf8'), path);
     }
     catch {
         return undefined;

package/dist/report.d.ts

@@ -1,3 +1,7 @@
 import type { CheckResult } from './types.js';
-export declare function formatText(result: CheckResult, version: string): string;
+export interface TextOptions {
+    /** Show every finding, including patch-only version drift. */
+    verbose?: boolean;
+}
+export declare function formatText(result: CheckResult, version: string, opts?: TextOptions): string;
 export declare function formatJson(result: CheckResult, version: string): string;

package/dist/report.js

@@ -9,7 +9,7 @@ const green = paint(32);
 const ICON = { error: '✖', warn: '⚠', info: 'ℹ' };
 const COLOR = { error: red, warn: yellow, info: cyan };
 const plural = (n, w) => `${n} ${w}${n === 1 ? '' : 's'}`;
-export function formatText(result, version) {
+export function formatText(result, version, opts = {}) {
     const out = [];
     out.push(bold(`mfe-guard v${version}`) +
         dim(` — ${plural(result.participants.length, 'participant')}, ${plural(result.packagesCompared, 'shared package')} compared`));
@@ -21,7 +21,10 @@ export function formatText(result, version) {
         out.push(green('✔ No conflicts found.'));
         return out.join('\n');
     }
-    for (const f of result.findings) {
+    const isPatchDrift = (f) => f.rule === 'version-drift' && f.drift === 'patch';
+    const collapsed = opts.verbose ? [] : result.findings.filter(isPatchDrift);
+    const shown = opts.verbose ? result.findings : result.findings.filter((f) => !isPatchDrift(f));
+    for (const f of shown) {
         const c = COLOR[f.severity];
         const pkg = f.package ? ` ${bold(f.package)}${f.entryPoints && f.entryPoints > 1 ? dim(` (${f.entryPoints} entry points)`) : ''}` : '';
         out.push(`${c(`${ICON[f.severity]} ${f.severity.padEnd(5)}`)} ${dim(f.rule)}${pkg}`);
@@ -29,7 +32,12 @@ export function formatText(result, version) {
         for (const d of f.details)
             out.push(dim(`      ${d}`));
         if (f.fix)
-            out.push(`    ${green('fix:')} ${f.fix}`);
+            out.push(`    ${green(f.severity === 'info' ? 'note:' : 'fix:')} ${f.fix}`);
+        out.push('');
+    }
+    if (collapsed.length) {
+        out.push(`${cyan(`${ICON.info} info `)} ${dim('version-drift')} ${plural(collapsed.length, 'package')} ${collapsed.length === 1 ? 'differs' : 'differ'} by patch version only ${dim('(--verbose to list)')}`);
+        out.push(dim(`      ${collapsed.map((f) => f.package).join(', ')}`));
         out.push('');
     }
     const s = result.summary;

package/dist/types.d.ts

@@ -40,6 +40,8 @@ export interface Finding {
     details: string[];
     fix?: string;
     participants: string[];
+    /** version-drift only: "patch" when only patch versions differ, "minor" otherwise. */
+    drift?: 'patch' | 'minor';
 }
 export interface CheckOptions {
     /** Packages that must always be singletons (warned by `not-singleton`). */

package/dist/util.d.ts

@@ -1,6 +1,11 @@
 import type { SharedEntry } from './types.js';
 /** "primeng/autocomplete" -> "primeng", "@angular/common/http" -> "@angular/common". */
 export declare function rootPackage(name: string): string;
+/**
+ * JSON.parse that tolerates a UTF-8 byte-order mark (Windows Notepad adds one)
+ * and reports where the JSON is broken.
+ */
+export declare function parseJson(text: string, source: string): unknown;
 /** Clean a version string into valid semver, or undefined. */
 export declare function cleanVersion(v: string | undefined): string | undefined;
 /** True for a usable semver range (rejects workspace:, git urls, "*"-less garbage). */

package/dist/util.js

@@ -4,6 +4,29 @@ export function rootPackage(name) {
     const parts = name.split('/');
     return name.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
 }
+/**
+ * JSON.parse that tolerates a UTF-8 byte-order mark (Windows Notepad adds one)
+ * and reports where the JSON is broken.
+ */
+export function parseJson(text, source) {
+    const clean = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    try {
+        return JSON.parse(clean);
+    }
+    catch (e) {
+        const msg = e.message;
+        const pos = /position (\d+)/.exec(msg);
+        let where = '';
+        if (pos && !/line \d+/.test(msg)) {
+            const before = clean.slice(0, Number(pos[1]));
+            const line = before.split('\n').length;
+            const col = Number(pos[1]) - before.lastIndexOf('\n');
+            where = ` (line ${line}, column ${col})`;
+        }
+        const hint = /^\s*</.test(clean) ? ' — got HTML, check the URL points at mf-manifest.json' : '';
+        throw new Error(`${source}: invalid JSON: ${msg}${where}${hint}`);
+    }
+}
 /** Clean a version string into valid semver, or undefined. */
 export function cleanVersion(v) {
     if (!v)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mfe-guard",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Catch Module Federation shared-dependency conflicts (singleton version mismatches, duplicate remote names) before they crash your micro-frontends in production.",
   "type": "module",
   "bin": {
@@ -17,7 +17,8 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "node scripts/clean.mjs && tsc -p tsconfig.json",