mfe-guard 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aneeq Rehman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,134 @@
-# Temporary Holding Version
+# mfe-guard
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Catch Module Federation shared-dependency conflicts before they crash your micro-frontends in production.**
+
+You deploy a new remote. Everything builds. Then an older remote dies in the browser with:
+
+```
+Error: [ Federation Runtime ]: Version 19.2.3 from inventory of shared singleton
+module @angular/material/autocomplete does not satisfy the requirement of orders which needs 19.2.1
+```
+
+…or worse, a cryptic `ReferenceError: Cannot access '_t' before initialization`.
+
+`mfe-guard` reads the `mf-manifest.json` of every shell and remote, works out which version of each shared singleton will **actually win at runtime**, and fails CI when any participant will not accept it, with the exact fix.
+
+```
+✖ error singleton-unsatisfied @angular/material (3 entry points)
+    @angular/material singleton resolves to 19.2.3, which does not satisfy orders
+      inventory provides 19.2.3 → wins as singleton (highest version)
+      orders requires "19.2.1" ✗
+    fix: in orders: change @angular/material "19.2.1" → "^19.2.1" (or align both on 19.2.3)
+```
+
+## Install
+
+```bash
+npx mfe-guard check --help        # no install needed
+npm i -D mfe-guard                # or as a dev dependency
+```
+
+Requires Node 18.17+.
+
+## Usage
+
+### Manifest mode (recommended)
+
+`@module-federation/enhanced` (and Nx, rspack, Modern.js on top of it) emits `mf-manifest.json` next to `remoteEntry.js`. Point mfe-guard at the deployed manifests of every participant. They can live in completely separate repos:
+
+```bash
+npx mfe-guard check \
+  -m shell=https://app.test.example.com/mf-manifest.json \
+  -m orders=https://orders.test.example.com/mf-manifest.json \
+  -m inventory=https://inventory.test.example.com/mf-manifest.json
+```
+
+Local paths work too (`-m orders=./dist/orders/mf-manifest.json`), and so do `mf-stats.json` files.
+
+### Project mode (no build needed)
+
+Compare project folders directly. The required range comes from `package.json`, and the shipped version comes from `node_modules` when installed:
+
+```bash
+npx mfe-guard check -p orders=../orders-app -p inventory=../inventory-app --singletons "*"
+```
+
+By default only well-known singletons (`@angular/*`, `rxjs`, `zone.js`, `primeng`, `@primeng/*`, `@ngrx/*`, `@ngxs/*`, `react`, `react-dom`, `vue`) are compared. **Nx shares every dependency as a singleton**, so pass `--singletons "*"` there.
+
+### Config file
+
+Drop a `mfe-guard.config.json` in the repo and just run `npx mfe-guard check`:
+
+```json
+{
+  "participants": [
+    { "name": "shell", "manifest": "https://app.test.example.com/mf-manifest.json" },
+    { "name": "orders", "manifest": "https://orders.test.example.com/mf-manifest.json" },
+    { "name": "inventory", "project": "../inventory-app" }
+  ],
+  "ignore": ["version-drift", "exact-pin:@acme/ui-kit"],
+  "failOn": "error"
+}
+```
+
+CLI flags are merged on top of the config.
+
+## Rules
+
+| Rule | Severity | What it catches |
+|---|---|---|
+| `singleton-unsatisfied` | error | The version that wins a singleton (the highest provided) does not satisfy another participant's `requiredVersion`. With `strictVersion` it throws at runtime; without it, you silently run on a version you never tested. |
+| `major-mismatch` | error | Participants ship different major versions of the same shared package. |
+| `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. |
+
+Secondary entry points (`@angular/material/autocomplete`, `@angular/common/http`, …) are collapsed into their root package, so you get one finding instead of forty.
+
+Ignore by rule (`exact-pin`), by package (`leaflet`), or by both (`exact-pin:leaflet`).
+
+## CI
+
+```yaml
+# .github/workflows/mfe-guard.yml
+name: mfe-guard
+on: [pull_request]
+jobs:
+  federation:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20 }
+      - 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.
+
+## Programmatic API
+
+```ts
+import { check, loadManifest, formatText } from 'mfe-guard';
+
+const result = check([
+  await loadManifest('https://orders.test.example.com/mf-manifest.json', 'orders'),
+  await loadManifest('./dist/inventory/mf-manifest.json', 'inventory'),
+]);
+console.log(result.summary); // { error: 2, warn: 3, info: 1 }
+```
+
+## How resolution is modelled
+
+For a singleton, the Module Federation runtime picks the **highest** version offered by any loaded participant (default `shareStrategy`). mfe-guard assumes every listed participant is loaded together, which is the worst case and therefore the one worth guarding against in CI.
+
+## Roadmap
+
+- Lockfile parsing (pnpm / npm / yarn) for exact versions without `node_modules`
+- Nx executor and a ready-made GitHub Action
+- HTML report
+- Classic webpack `remoteEntry.js` (no manifest) support
+
+## License
+
+MIT © Aneeq Rehman

package/dist/check.d.ts

@@ -0,0 +1,4 @@
+import type { CheckOptions, CheckResult, Participant } from './types.js';
+export declare const DEFAULT_CRITICAL_SINGLETONS: string[];
+/** Run every rule over the given participants. Pure function — no I/O. */
+export declare function check(input: Participant[], opts?: CheckOptions): CheckResult;

package/dist/check.js

@@ -0,0 +1,166 @@
+import semver from 'semver';
+import { collapseEntryPoints, isExactPin, isRange, matchesPattern } from './util.js';
+export const DEFAULT_CRITICAL_SINGLETONS = [
+    '@angular/core',
+    '@angular/common',
+    '@angular/router',
+    '@angular/platform-browser',
+    'rxjs',
+    'zone.js',
+    'react',
+    'react-dom',
+];
+const SEVERITY_ORDER = { error: 0, warn: 1, info: 2 };
+function versionLabel(u) {
+    return u.e.versionGuessed ? `${u.e.version} (guessed from "${u.e.requiredVersion}" — install deps for the exact version)` : `${u.e.version}`;
+}
+/** Run every rule over the given participants. Pure function — no I/O. */
+export function check(input, opts = {}) {
+    const critical = opts.criticalSingletons ?? DEFAULT_CRITICAL_SINGLETONS;
+    const ignore = opts.ignore ?? [];
+    const isIgnored = (rule, pkg) => ignore.includes(rule) || ignore.includes(`${rule}:${pkg}`) || ignore.includes(pkg);
+    const participants = input.map((p) => ({ ...p, shared: collapseEntryPoints(p.shared) }));
+    const findings = [];
+    const add = (f) => {
+        if (!isIgnored(f.rule, f.package))
+            findings.push(f);
+    };
+    // ── duplicate-name ──────────────────────────────────────────────
+    for (const key of ['federationName', 'globalName']) {
+        const byName = new Map();
+        for (const p of participants) {
+            const n = p[key];
+            if (!n)
+                continue;
+            byName.set(n, [...(byName.get(n) ?? []), p]);
+        }
+        for (const [n, ps] of byName) {
+            if (ps.length < 2)
+                continue;
+            add({
+                rule: 'duplicate-name',
+                severity: 'error',
+                package: '',
+                message: `${ps.length} participants use the same ${key === 'globalName' ? 'global (chunk) name' : 'federation name'} "${n}"`,
+                details: ps.map((p) => `${p.name} ← ${p.source}`),
+                fix: 'give every remote a unique MF `name` (and `output.uniqueName`) — they will overwrite each other\'s modules at runtime',
+                participants: ps.map((p) => p.name),
+            });
+        }
+    }
+    // ── per-package rules ──────────────────────────────────────────
+    const byPkg = new Map();
+    for (const p of participants) {
+        for (const e of p.shared)
+            byPkg.set(e.name, [...(byPkg.get(e.name) ?? []), { p, e }]);
+    }
+    let packagesCompared = 0;
+    for (const [pkg, uses] of [...byPkg].sort(([a], [b]) => a.localeCompare(b))) {
+        if (uses.length < 2)
+            continue; // only one participant shares it — nothing to conflict with
+        packagesCompared++;
+        const entryPoints = Math.max(...uses.map((u) => u.e.entryPoints ?? 1));
+        const names = uses.map((u) => u.p.name);
+        const isSingleton = uses.some((u) => u.e.singleton);
+        // not-singleton
+        if (critical.some((c) => matchesPattern(pkg, c))) {
+            const loose = uses.filter((u) => !u.e.singleton);
+            if (loose.length) {
+                add({
+                    rule: 'not-singleton',
+                    severity: 'warn',
+                    package: pkg,
+                    entryPoints,
+                    message: `${pkg} must be a singleton but is not in ${loose.map((u) => u.p.name).join(', ')}`,
+                    details: uses.map((u) => `${u.p.name}: singleton=${u.e.singleton}`),
+                    fix: `set { singleton: true } for ${pkg} in every participant — two copies break DI / zones / shared state`,
+                    participants: loose.map((u) => u.p.name),
+                });
+            }
+        }
+        const providers = uses.filter((u) => u.e.version && semver.valid(u.e.version));
+        // major-mismatch
+        const majors = new Set(providers.map((u) => semver.major(u.e.version)));
+        if (majors.size > 1) {
+            add({
+                rule: 'major-mismatch',
+                severity: 'error',
+                package: pkg,
+                entryPoints,
+                message: `${pkg} is shipped in ${majors.size} different major versions`,
+                details: providers.map((u) => `${u.p.name} ships ${versionLabel(u)}`),
+                fix: `align every participant on the same major version of ${pkg}`,
+                participants: providers.map((u) => u.p.name),
+            });
+            continue;
+        }
+        if (!isSingleton || providers.length === 0)
+            continue;
+        // singleton-unsatisfied — MF picks the highest provided version for a singleton
+        const winner = providers.reduce((a, b) => (semver.gt(b.e.version, a.e.version) ? b : a));
+        const winVer = winner.e.version;
+        const unsatisfied = uses.filter((u) => u.e.version !== winVer &&
+            isRange(u.e.requiredVersion) &&
+            !semver.satisfies(winVer, u.e.requiredVersion, { includePrerelease: true }));
+        if (unsatisfied.length) {
+            const fixes = unsatisfied.map((u) => {
+                const range = u.e.requiredVersion;
+                const lo = semver.minVersion(range);
+                if (lo && semver.lt(winVer, lo.version)) {
+                    return `upgrade ${pkg} in ${winner.p.name} to >= ${lo.version}`;
+                }
+                if (lo && semver.major(lo) === semver.major(winVer)) {
+                    return `in ${u.p.name}: change ${pkg} "${range}" → "^${lo.version}" (or align both on ${winVer})`;
+                }
+                return `align ${pkg} versions between ${u.p.name} and ${winner.p.name}`;
+            });
+            add({
+                rule: 'singleton-unsatisfied',
+                severity: 'error',
+                package: pkg,
+                entryPoints,
+                message: `${pkg} singleton resolves to ${winVer}, which does not satisfy ${unsatisfied.map((u) => u.p.name).join(', ')}`,
+                details: [
+                    `${winner.p.name} provides ${versionLabel(winner)} → wins as singleton (highest version)`,
+                    ...unsatisfied.map((u) => `${u.p.name} requires "${u.e.requiredVersion}" ✗`),
+                ],
+                fix: fixes.join('; '),
+                participants: names,
+            });
+        }
+        else {
+            const distinct = [...new Set(providers.map((u) => u.e.version))];
+            if (distinct.length > 1) {
+                add({
+                    rule: 'version-drift',
+                    severity: 'info',
+                    package: pkg,
+                    entryPoints,
+                    message: `${pkg} versions differ (${distinct.join(', ')}); singleton resolves to ${winVer}`,
+                    details: providers.map((u) => `${u.p.name} ships ${versionLabel(u)}`),
+                    participants: names,
+                });
+            }
+        }
+        // exact-pin — fragile even when it happens to work today
+        const unsatisfiedSet = new Set(unsatisfied.map((u) => u.p.name));
+        const pinned = uses.filter((u) => u.e.singleton && isRange(u.e.requiredVersion) && isExactPin(u.e.requiredVersion) && !unsatisfiedSet.has(u.p.name));
+        if (pinned.length) {
+            add({
+                rule: 'exact-pin',
+                severity: 'warn',
+                package: pkg,
+                entryPoints,
+                message: `${pkg} is pinned to an exact version in ${pinned.map((u) => u.p.name).join(', ')}`,
+                details: pinned.map((u) => `${u.p.name} requires exactly "${u.e.requiredVersion}"`),
+                fix: `use a caret range (e.g. "^${pinned[0].e.requiredVersion.replace(/^=/, '')}") so a patch bump in another remote does not break it`,
+                participants: pinned.map((u) => u.p.name),
+            });
+        }
+    }
+    findings.sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity] || a.package.localeCompare(b.package));
+    const summary = { error: 0, warn: 0, info: 0 };
+    for (const f of findings)
+        summary[f.severity]++;
+    return { participants, packagesCompared, findings, summary };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import { readFileSync, existsSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { check } from './check.js';
+import { DEFAULT_CONFIG_FILE, loadConfig } from './config.js';
+import { loadManifest } from './loaders/manifest.js';
+import { loadProject } from './loaders/project.js';
+import { formatJson, formatText } from './report.js';
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+const HELP = `mfe-guard v${VERSION} — catch Module Federation shared-dependency conflicts before production
+
+Usage
+  mfe-guard check [options]
+
+Inputs (repeatable, at least two participants)
+  -m, --manifest <name=url|path>   mf-manifest.json (or mf-stats.json) of a shell/remote
+  -p, --project  <name=dir>        project folder with package.json (+ node_modules)
+  -c, --config   <file>            JSON config (default: ./${DEFAULT_CONFIG_FILE} if present)
+
+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)
+      --json                       machine-readable output
+  -h, --help
+  -v, --version
+
+Examples
+  mfe-guard check -m shell=https://app.test/mf-manifest.json \\
+                  -m orders=https://orders.test/mf-manifest.json \\
+                  -m inventory=https://inventory.test/mf-manifest.json
+
+  mfe-guard check -p orders=../orders-app -p inventory=../inventory-app --singletons "*"
+
+Exit codes: 0 ok · 1 findings at/above --fail-on · 2 usage or load error`;
+function splitPair(v, flag) {
+    const i = v.indexOf('=');
+    if (i <= 0 || i === v.length - 1)
+        throw new UsageError(`${flag} expects name=value, got "${v}"`);
+    return { name: v.slice(0, i), value: v.slice(i + 1) };
+}
+const list = (v) => (v ? v.split(',').map((s) => s.trim()).filter(Boolean) : undefined);
+class UsageError extends Error {
+}
+async function main(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            manifest: { type: 'string', short: 'm', multiple: true },
+            project: { type: 'string', short: 'p', multiple: true },
+            config: { type: 'string', short: 'c' },
+            singletons: { type: 'string' },
+            ignore: { type: 'string' },
+            'fail-on': { type: 'string' },
+            json: { type: 'boolean' },
+            help: { type: 'boolean', short: 'h' },
+            version: { type: 'boolean', short: 'v' },
+        },
+    });
+    if (values.version) {
+        console.log(VERSION);
+        return 0;
+    }
+    if (values.help || positionals.length === 0) {
+        console.log(HELP);
+        return positionals.length === 0 && !values.help ? 2 : 0;
+    }
+    if (positionals[0] !== 'check')
+        throw new UsageError(`unknown command "${positionals[0]}" (try: mfe-guard check)`);
+    // config file (explicit or auto-detected) + CLI flags are merged
+    const configPath = values.config ?? (existsSync(DEFAULT_CONFIG_FILE) ? DEFAULT_CONFIG_FILE : undefined);
+    const config = configPath ? await loadConfig(configPath) : { participants: [] };
+    const participantsCfg = [
+        ...config.participants,
+        ...(values.manifest ?? []).map((v) => {
+            const { name, value } = splitPair(v, '--manifest');
+            return { name, manifest: value };
+        }),
+        ...(values.project ?? []).map((v) => {
+            const { name, value } = splitPair(v, '--project');
+            return { name, project: value };
+        }),
+    ];
+    if (participantsCfg.length < 2) {
+        throw new UsageError('need at least two participants (use --manifest / --project or a config file)');
+    }
+    const failOn = (values['fail-on'] ?? config.failOn ?? 'error');
+    if (!['error', 'warn', 'never'].includes(failOn))
+        throw new UsageError(`--fail-on must be error, warn or never`);
+    const singletons = list(values.singletons) ?? config.singletons;
+    const participants = await Promise.all(participantsCfg.map((p) => p.manifest ? loadManifest(p.manifest, p.name) : loadProject(p.project, p.name, { singletons })));
+    const result = check(participants, {
+        ignore: [...(config.ignore ?? []), ...(list(values.ignore) ?? [])],
+        criticalSingletons: config.criticalSingletons,
+    });
+    console.log(values.json ? formatJson(result, VERSION) : formatText(result, VERSION));
+    if (failOn === 'never')
+        return 0;
+    if (result.summary.error > 0)
+        return 1;
+    if (failOn === 'warn' && result.summary.warn > 0)
+        return 1;
+    return 0;
+}
+main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+    console.error(`mfe-guard: ${err instanceof Error ? err.message : String(err)}`);
+    if (err instanceof UsageError)
+        console.error('run "mfe-guard --help" for usage');
+    process.exit(2);
+});

package/dist/config.d.ts

@@ -0,0 +1,19 @@
+export type FailOn = 'error' | 'warn' | 'never';
+export interface ParticipantConfig {
+    name: string;
+    /** URL or path to mf-manifest.json / mf-stats.json. */
+    manifest?: string;
+    /** Path to a project folder containing package.json (and ideally node_modules). */
+    project?: string;
+}
+export interface MfeGuardConfig {
+    participants: ParticipantConfig[];
+    /** Project mode: packages treated as shared singletons. ["*"] matches Nx defaults. */
+    singletons?: string[];
+    criticalSingletons?: string[];
+    ignore?: string[];
+    failOn?: FailOn;
+}
+export declare const DEFAULT_CONFIG_FILE = "mfe-guard.config.json";
+/** Load a JSON config; relative project/manifest paths resolve against the config file. */
+export declare function loadConfig(path: string): Promise<MfeGuardConfig>;

package/dist/config.js

@@ -0,0 +1,26 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, isAbsolute, resolve } from 'node:path';
+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;
+    try {
+        raw = JSON.parse(await readFile(abs, 'utf8'));
+    }
+    catch (e) {
+        throw new Error(`cannot read config ${path}: ${e.message}`);
+    }
+    if (!Array.isArray(raw.participants)) {
+        throw new Error(`${path}: "participants" must be an array`);
+    }
+    const base = dirname(abs);
+    const fix = (s) => (s && !/^https?:\/\//i.test(s) && !isAbsolute(s) ? resolve(base, s) : s);
+    raw.participants = raw.participants.map((p, i) => {
+        if (!p?.name || (!p.manifest && !p.project)) {
+            throw new Error(`${path}: participants[${i}] needs "name" and either "manifest" or "project"`);
+        }
+        return { ...p, manifest: fix(p.manifest), project: fix(p.project) };
+    });
+    return raw;
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { check, DEFAULT_CRITICAL_SINGLETONS } from './check.js';
+export { parseManifest, loadManifest } from './loaders/manifest.js';
+export { loadProject, DEFAULT_SINGLETONS } from './loaders/project.js';
+export { loadConfig } from './config.js';
+export { formatText, formatJson } from './report.js';
+export type * from './types.js';
+export type { MfeGuardConfig, ParticipantConfig, FailOn } from './config.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { check, DEFAULT_CRITICAL_SINGLETONS } from './check.js';
+export { parseManifest, loadManifest } from './loaders/manifest.js';
+export { loadProject, DEFAULT_SINGLETONS } from './loaders/project.js';
+export { loadConfig } from './config.js';
+export { formatText, formatJson } from './report.js';

package/dist/loaders/manifest.d.ts

@@ -0,0 +1,8 @@
+import type { Participant } from '../types.js';
+/**
+ * Parse an `mf-manifest.json` (or `mf-stats.json`) produced by
+ * @module-federation/enhanced, webpack or rspack.
+ */
+export declare function parseManifest(json: unknown, source: string, label?: string): Participant;
+/** Load a manifest from an http(s) URL or a local path. */
+export declare function loadManifest(source: string, label?: string): Promise<Participant>;

package/dist/loaders/manifest.js

@@ -0,0 +1,55 @@
+import { readFile } from 'node:fs/promises';
+/**
+ * Parse an `mf-manifest.json` (or `mf-stats.json`) produced by
+ * @module-federation/enhanced, webpack or rspack.
+ */
+export function parseManifest(json, source, label) {
+    if (!json || typeof json !== 'object') {
+        throw new Error(`${source}: not a JSON object`);
+    }
+    const m = json;
+    const meta = (m.metaData ?? {});
+    const federationName = m.name ?? meta.name ?? m.id;
+    if (!Array.isArray(m.shared)) {
+        throw new Error(`${source}: no "shared" array found. Point mfe-guard at mf-manifest.json (or mf-stats.json), not remoteEntry.js.`);
+    }
+    const shared = m.shared
+        .filter((s) => s && typeof s.name === 'string')
+        .map((s) => ({
+        name: s.name,
+        version: typeof s.version === 'string' ? s.version : undefined,
+        requiredVersion: s.requiredVersion === false ? false : typeof s.requiredVersion === 'string' ? s.requiredVersion : undefined,
+        singleton: s.singleton === true,
+        strictVersion: typeof s.strictVersion === 'boolean' ? s.strictVersion : undefined,
+        eager: typeof s.eager === 'boolean' ? s.eager : undefined,
+    }));
+    return {
+        name: label ?? federationName ?? source,
+        federationName,
+        globalName: typeof meta.globalName === 'string' ? meta.globalName : undefined,
+        source,
+        kind: 'manifest',
+        shared,
+    };
+}
+/** Load a manifest from an http(s) URL or a local path. */
+export async function loadManifest(source, label) {
+    let text;
+    if (/^https?:\/\//i.test(source)) {
+        const res = await fetch(source, { headers: { accept: 'application/json' } });
+        if (!res.ok)
+            throw new Error(`${source}: HTTP ${res.status} ${res.statusText}`);
+        text = await res.text();
+    }
+    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);
+}

package/dist/loaders/project.d.ts

@@ -0,0 +1,12 @@
+import type { Participant } from '../types.js';
+/** Packages assumed to be shared singletons in project mode unless configured otherwise. */
+export declare const DEFAULT_SINGLETONS: string[];
+export interface ProjectOptions {
+    /** Patterns of packages treated as shared singletons. Use ["*"] for Nx (shares everything). */
+    singletons?: string[];
+}
+/**
+ * Build a participant from a project folder: package.json gives the required range,
+ * node_modules (when installed) gives the version it will actually ship.
+ */
+export declare function loadProject(dir: string, label: string, opts?: ProjectOptions): Promise<Participant>;

package/dist/loaders/project.js

@@ -0,0 +1,52 @@
+import { readFile } from 'node:fs/promises';
+import semver from 'semver';
+import { join } from 'node:path';
+import { cleanVersion, isRange, matchesPattern } from '../util.js';
+/** Packages assumed to be shared singletons in project mode unless configured otherwise. */
+export const DEFAULT_SINGLETONS = [
+    '@angular/*',
+    'rxjs',
+    'zone.js',
+    'primeng',
+    '@primeng/*',
+    '@ngrx/*',
+    '@ngxs/*',
+    'react',
+    'react-dom',
+    'vue',
+];
+async function readJson(path) {
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Build a participant from a project folder: package.json gives the required range,
+ * node_modules (when installed) gives the version it will actually ship.
+ */
+export async function loadProject(dir, label, opts = {}) {
+    const pkg = await readJson(join(dir, 'package.json'));
+    if (!pkg)
+        throw new Error(`${dir}: package.json not found or unreadable`);
+    const singletons = opts.singletons ?? DEFAULT_SINGLETONS;
+    const deps = pkg.dependencies ?? {};
+    const shared = [];
+    for (const [name, range] of Object.entries(deps)) {
+        if (!singletons.some((p) => matchesPattern(name, p)))
+            continue;
+        if (!isRange(range))
+            continue; // workspace:, git urls, file: ...
+        const installed = cleanVersion((await readJson(join(dir, 'node_modules', name, 'package.json')))?.version);
+        shared.push({
+            name,
+            version: installed ?? semver.minVersion(range)?.version,
+            versionGuessed: !installed,
+            requiredVersion: range,
+            singleton: true,
+        });
+    }
+    return { name: label, source: dir, kind: 'project', shared };
+}

package/dist/report.d.ts

@@ -0,0 +1,3 @@
+import type { CheckResult } from './types.js';
+export declare function formatText(result: CheckResult, version: string): string;
+export declare function formatJson(result: CheckResult, version: string): string;

package/dist/report.js

@@ -0,0 +1,52 @@
+const useColor = () => !process.env.NO_COLOR && (process.stdout.isTTY || !!process.env.FORCE_COLOR);
+const paint = (code) => (s) => (useColor() ? `\x1b[${code}m${s}\x1b[0m` : s);
+const red = paint(31);
+const yellow = paint(33);
+const cyan = paint(36);
+const dim = paint(2);
+const bold = paint(1);
+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) {
+    const out = [];
+    out.push(bold(`mfe-guard v${version}`) +
+        dim(` — ${plural(result.participants.length, 'participant')}, ${plural(result.packagesCompared, 'shared package')} compared`));
+    for (const p of result.participants) {
+        out.push(dim(`  • ${p.name} (${p.kind}, ${p.shared.length} shared) ← ${p.source}`));
+    }
+    out.push('');
+    if (!result.findings.length) {
+        out.push(green('✔ No conflicts found.'));
+        return out.join('\n');
+    }
+    for (const f of result.findings) {
+        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}`);
+        out.push(`    ${f.message}`);
+        for (const d of f.details)
+            out.push(dim(`      ${d}`));
+        if (f.fix)
+            out.push(`    ${green('fix:')} ${f.fix}`);
+        out.push('');
+    }
+    const s = result.summary;
+    out.push([
+        s.error ? red(plural(s.error, 'error')) : plural(0, 'error'),
+        s.warn ? yellow(plural(s.warn, 'warning')) : plural(0, 'warning'),
+        plural(s.info, 'info'),
+    ].join(', '));
+    return out.join('\n');
+}
+export function formatJson(result, version) {
+    return JSON.stringify({
+        tool: 'mfe-guard',
+        version,
+        participants: result.participants.map((p) => ({ name: p.name, kind: p.kind, source: p.source, shared: p.shared.length })),
+        packagesCompared: result.packagesCompared,
+        summary: result.summary,
+        findings: result.findings,
+    }, null, 2);
+}

package/dist/types.d.ts

@@ -0,0 +1,55 @@
+/** One shared package as declared by a participant (shell or remote). */
+export interface SharedEntry {
+    /** Package name as shared, e.g. "primeng" or "primeng/autocomplete". */
+    name: string;
+    /** Version this participant ships/provides, if known. */
+    version?: string;
+    /** True when `version` was guessed from the range because node_modules was not installed. */
+    versionGuessed?: boolean;
+    /** Range this participant requires at runtime. `false` = no requirement. */
+    requiredVersion?: string | false;
+    singleton: boolean;
+    strictVersion?: boolean;
+    eager?: boolean;
+    /** How many entry points were collapsed into this entry (primeng/*, @angular/common/http...). */
+    entryPoints?: number;
+}
+/** A shell or remote taking part in the federation. */
+export interface Participant {
+    /** Label used in reports (the MF name, or the label given on the CLI). */
+    name: string;
+    /** Federation name from the manifest (used for duplicate-name detection). */
+    federationName?: string;
+    /** Global/chunk-loading name, if the manifest exposes it. */
+    globalName?: string;
+    /** Where it was loaded from (URL or path). */
+    source: string;
+    /** "manifest" = exact data from mf-manifest.json, "project" = heuristic from package.json. */
+    kind: 'manifest' | 'project';
+    shared: SharedEntry[];
+}
+export type Severity = 'error' | 'warn' | 'info';
+export type RuleId = 'singleton-unsatisfied' | 'major-mismatch' | 'duplicate-name' | 'exact-pin' | 'not-singleton' | 'version-drift';
+export interface Finding {
+    rule: RuleId;
+    severity: Severity;
+    /** Root package name, e.g. "primeng". Empty for participant-level rules. */
+    package: string;
+    entryPoints?: number;
+    message: string;
+    details: string[];
+    fix?: string;
+    participants: string[];
+}
+export interface CheckOptions {
+    /** Packages that must always be singletons (warned by `not-singleton`). */
+    criticalSingletons?: string[];
+    /** Rule ids or "rule:package" pairs to ignore. */
+    ignore?: string[];
+}
+export interface CheckResult {
+    participants: Participant[];
+    packagesCompared: number;
+    findings: Finding[];
+    summary: Record<Severity, number>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/util.d.ts

@@ -0,0 +1,16 @@
+import type { SharedEntry } from './types.js';
+/** "primeng/autocomplete" -> "primeng", "@angular/common/http" -> "@angular/common". */
+export declare function rootPackage(name: string): string;
+/** 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). */
+export declare function isRange(r: unknown): r is string;
+/** True when the range pins one exact version ("1.2.3", "=1.2.3"). */
+export declare function isExactPin(r: string): boolean;
+/** Glob-ish match: "@angular/*", "rxjs", "*". */
+export declare function matchesPattern(name: string, pattern: string): boolean;
+/**
+ * Collapse secondary entry points into one entry per root package.
+ * The root's own entry wins when present; otherwise the first entry point is used.
+ */
+export declare function collapseEntryPoints(shared: SharedEntry[]): SharedEntry[];

package/dist/util.js

@@ -0,0 +1,55 @@
+import semver from 'semver';
+/** "primeng/autocomplete" -> "primeng", "@angular/common/http" -> "@angular/common". */
+export function rootPackage(name) {
+    const parts = name.split('/');
+    return name.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+}
+/** Clean a version string into valid semver, or undefined. */
+export function cleanVersion(v) {
+    if (!v)
+        return undefined;
+    return semver.valid(v) ?? semver.coerce(v)?.version ?? undefined;
+}
+/** True for a usable semver range (rejects workspace:, git urls, "*"-less garbage). */
+export function isRange(r) {
+    return typeof r === 'string' && r.length > 0 && semver.validRange(r) !== null;
+}
+/** True when the range pins one exact version ("1.2.3", "=1.2.3"). */
+export function isExactPin(r) {
+    return semver.valid(r.replace(/^=/, '').trim()) !== null;
+}
+/** Glob-ish match: "@angular/*", "rxjs", "*". */
+export function matchesPattern(name, pattern) {
+    if (pattern === '*')
+        return true;
+    if (pattern.endsWith('/*'))
+        return name.startsWith(pattern.slice(0, -1));
+    return name === pattern;
+}
+/**
+ * Collapse secondary entry points into one entry per root package.
+ * The root's own entry wins when present; otherwise the first entry point is used.
+ */
+export function collapseEntryPoints(shared) {
+    const byRoot = new Map();
+    for (const s of shared) {
+        const root = rootPackage(s.name);
+        const existing = byRoot.get(root);
+        if (!existing) {
+            byRoot.set(root, { ...s, name: root, entryPoints: 1 });
+            continue;
+        }
+        existing.entryPoints = (existing.entryPoints ?? 1) + 1;
+        if (s.name === root) {
+            byRoot.set(root, { ...s, name: root, entryPoints: existing.entryPoints });
+        }
+        else {
+            // keep the strictest picture: singleton if any entry point is one
+            existing.singleton = existing.singleton || s.singleton;
+            existing.version ??= s.version;
+            if (existing.requiredVersion === undefined)
+                existing.requiredVersion = s.requiredVersion;
+        }
+    }
+    return [...byRoot.values()];
+}

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "mfe-guard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Catch Module Federation shared-dependency conflicts (singleton version mismatches, duplicate remote names) before they crash your micro-frontends in production.",
+  "type": "module",
+  "bin": {
+    "mfe-guard": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/clean.mjs && tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/check.test.mjs test/cli.test.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "module-federation",
+    "micro-frontends",
+    "mfe",
+    "webpack",
+    "rspack",
+    "nx",
+    "angular",
+    "singleton",
+    "shared-dependencies",
+    "ci",
+    "lint"
+  ],
+  "author": "Aneeq Rehman",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maneeq/mfe-guard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/maneeq/mfe-guard/issues"
+  },
+  "homepage": "https://github.com/maneeq/mfe-guard#readme",
+  "engines": {
+    "node": ">=18.17"
+  },
+  "dependencies": {
+    "semver": "^7.6.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "@types/semver": "^7.5.8",
+    "typescript": "~5.7.2"
+  }
+}