@mf-toolkit/shared-inspector 0.4.0 → 0.4.1

package/README.md

@@ -6,81 +6,108 @@
 
 **Stop debugging Module Federation in production.**
 
-`shared` config breaks in silence — wrong versions ship, 10× React ends up in the bundle, singleton chains collapse, and teams get paged for "Invalid hook call" on Friday night. `shared-inspector` catches these mistakes at build time. Every finding comes with a risk score and a ready-to-paste fix.
+`shared` config breaks in silence — wrong versions ship, duplicate React copies can end up in the bundle, singleton negotiation fails, and teams get paged for "Invalid hook call" on Friday night. `shared-inspector` catches these mistakes at build time. Every finding comes with a risk score and a ready-to-paste fix.
 
 ## The problem
 
 Module Federation teams manually manage `shared` config and make three kinds of mistakes:
 
 - **Over-sharing** — packages listed in `shared` that the microfrontend never imports. Creates artificial version coupling between independent teams.
-- **Under-sharing** — packages used by both host and remote but missing from `shared`. Each microfrontend bundles its own copy (10× React = 10× 130 KB).
+- **Under-sharing** — packages used by both host and remote but missing from `shared`. Each microfrontend may bundle its own copy (e.g. multiple React instances, each ~130 KB).
 - **Version mismatch** — `requiredVersion` doesn't match the installed version. Module Federation silently falls back to a local bundle. For packages with global state (React, styled-components) this causes "Invalid hook call" in production.
 
 Existing tools (webpack-bundle-analyzer, source-map-explorer) show *what ended up in the bundle*, not *why shared config is suboptimal*. Different questions.
 
-## Installation
+## Why not bundle analyzer?
 
-```bash
-npm install --save-dev @mf-toolkit/shared-inspector
-```
+Bundle analyzers (webpack-bundle-analyzer, source-map-explorer, stats.json inspection) answer a different question: *what is in the output?* They are useful for auditing final bundle size, but they don't model Module Federation's shared dependency negotiation.
 
-## CLI
+| Question | Bundle analyzer | shared-inspector |
+|----------|----------------|-----------------|
+| Which packages are large? | ✅ | — |
+| Is React duplicated across MFs? | Visible after the fact | ✅ Detected before build ships |
+| Is `requiredVersion` out of sync with the installed version? | ✗ | ✅ |
+| Is a package marked `singleton` in one MF but not another? | ✗ | ✅ |
+| Which packages are declared `shared` but never imported? | ✗ | ✅ |
+| Which used packages are missing from `shared` entirely? | ✗ | ✅ |
+| Cross-MF version conflicts across teams? | ✗ | ✅ via federation manifests |
 
-The fastest way to get started — no config file, no webpack required:
+In short: bundle analyzers are useful for post-build inspection. `shared-inspector` is focused on the `shared` config itself — catching misconfiguration at build time and explaining what the runtime consequences would be.
 
-```bash
-# Analyse the current project (auto-reads name from package.json)
-npx @mf-toolkit/shared-inspector
+## Example
 
-# Step-by-step interactive wizard — answers guide you through all options
-npx @mf-toolkit/shared-inspector --interactive
+A `shell` host app (React 18) and a `checkout` remote have been developed by separate teams. Their `shared` configs have drifted:
 
-# Pass options directly
-npx @mf-toolkit/shared-inspector --source ./src --shared react,react-dom --fail-on mismatch
+```js
+// shell — webpack.config.js
+shared: {
+  react:     { singleton: true, requiredVersion: '^18.2.0' },
+  'react-dom': { singleton: true, requiredVersion: '^18.2.0' },
+  zustand:   { singleton: true },
+}
 
-# Load shared config from a JSON file
-npx @mf-toolkit/shared-inspector --shared ./shared-config.json --write-manifest
+// checkout — webpack.config.js
+shared: {
+  react:     { singleton: true, requiredVersion: '^17.0.2' }, // ← stale version
+  'react-dom': { singleton: true, requiredVersion: '^17.0.2' },
+  lodash:    {},                                               // ← never imported
+  // zustand: missing — checkout imports it, but it's not in shared
+}
+```
+
+Running `npx @mf-toolkit/shared-inspector` in the `checkout` project:
 
-# Cross-MF federation analysis from saved manifests
-npx @mf-toolkit/shared-inspector federation checkout.json catalog.json cart.json
 ```
+[MfSharedInspector] checkout (depth: local-graph, 34 files scanned)
+────────────────────────────────────────────────────────────
+
+⚠  Version Mismatch — react
+   configured: ^17.0.2 | installed: 17.0.2
+   → Risk: Invalid hook call, broken context across MFs
+   💡 Fix:
+   shared: {
+     react: { singleton: true, requiredVersion: "^18.2.0" }
+   }
 
-### Interactive wizard
+→  Not Shared — zustand (8 imports in 5 files)
+   → Risk: Each MF may get its own store instance — state changes may not propagate across MFs
+   💡 Fix:
+   shared: {
+     zustand: { singleton: true }
+   }
+
+✗  Unused Shared — lodash
+   0 imports, shared without singleton
+   → Wastes bundle negotiation overhead with no benefit
+   💡 Fix: Remove "lodash" from shared config
 
+────────────────────────────────────────────────────────────
+Score: 69/100  🟠 RISKY
 ```
-$ npx @mf-toolkit/shared-inspector --interactive
 
-[MfSharedInspector] Interactive setup
+**After manually updating the config based on the suggestions above** — `react` version aligned, `zustand` added to `shared`, `lodash` removed:
 
-Source directories to scan (default: ./src):
-Scan depth — direct or local-graph (default: local-graph):
-Shared packages — comma-separated names or path to .json (empty to skip): react,react-dom,mobx
-Path to tsconfig.json for alias resolution (empty to skip):
-Workspace packages to exclude, comma-separated (empty to skip):
-Fail build on findings — mismatch / unused / any / none (default: none): mismatch
-Write project-manifest.json? (y/N): n
+```
+Score: 100/100  ✅ HEALTHY
 ```
 
-### CLI reference
+The cross-team federation report also clears: `shell` and `checkout` now negotiate a single React instance and a single Zustand store at runtime.
 
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--source, -s <dirs>` | `./src` | Source dirs to scan, comma-separated |
-| `--depth <depth>` | `local-graph` | Scan depth: `direct` \| `local-graph` |
-| `--shared <packages\|file>` | — | Comma-separated package names or path to `.json` config |
-| `--tsconfig <path>` | — | tsconfig.json for path alias resolution |
-| `--workspace-packages <pkgs>` | — | Comma-separated workspace packages to exclude |
-| `--name <name>` | auto from `package.json` | Project name |
-| `--fail-on <rule>` | — | Exit 1 when findings match: `mismatch` \| `unused` \| `any` |
-| `--write-manifest` | `false` | Write `project-manifest.json` to output dir |
-| `--output-dir <dir>` | `.` | Output directory for manifest |
-| `--interactive, -i` | — | Launch step-by-step wizard |
-| `--version, -v` | — | Print version and exit |
-| `--help, -h` | — | Show help |
+## Installation
 
-## Terminal output
+```bash
+npm install --save-dev @mf-toolkit/shared-inspector
+```
+
+## Quick start
 
-Each finding is rendered as a diagnostic card: what's wrong, what breaks at runtime, and a ready-to-paste fix.
+Run against any MF project — no config file needed:
+
+```bash
+npx @mf-toolkit/shared-inspector
+```
+
+The tool scans `./src`, reads installed versions from `package.json`, and prints a diagnostic report. Each finding includes what's wrong, what breaks at runtime, and a ready-to-paste fix:
 
 ```
   mf-inspector  v0.4.0
@@ -104,7 +131,7 @@ Each finding is rendered as a diagnostic card: what's wrong, what breaks at runt
    💡 Fix: Remove "lodash" from shared config
 
 →  Not Shared — mobx (12 imports in 8 files via re-export in src/shared/index.ts)
-   → Risk: Each MF gets its own MobX — observables and reactions won't sync between MFs
+   → Risk: Each MF may get its own MobX instance — observables and reactions can fail to sync between MFs
    💡 Fix:
    shared: {
      mobx: { singleton: true }
@@ -123,7 +150,7 @@ Total: 12 shared, 10 used, 1 unused, 1 candidates, 1 mismatch, 0 eager risks
 
 Colors are auto-applied in TTY terminals and disabled in CI / piped output (`NO_COLOR` / `TERM=dumb` respected).
 
-## Risk scoring
+### Risk scoring
 
 Every report ends with a score out of 100:
 
@@ -140,7 +167,43 @@ Every report ends with a score out of 100:
 | 40–69 | 🟠 RISKY |
 | 0–39 | 🔴 CRITICAL |
 
-Use `scoreProjectReport` / `scoreFederationReport` programmatically to integrate with dashboards or custom CI gates:
+## CI mode
+
+Integrate into build pipelines to fail on findings, gate on score, or emit manifests for later federation analysis.
+
+### Failing the build
+
+Use `--fail-on` to exit with code 1 when specific findings are detected:
+
+```bash
+npx @mf-toolkit/shared-inspector --source ./src --shared react,react-dom --fail-on mismatch
+```
+
+With the webpack plugin:
+
+```typescript
+import { MfSharedInspectorPlugin } from '@mf-toolkit/shared-inspector/webpack';
+
+module.exports = {
+  plugins: [
+    new ModuleFederationPlugin({
+      name: 'checkout',
+      shared: { react: { singleton: true }, mobx: { singleton: true } },
+    }),
+
+    // sharedConfig not needed — auto-extracted from ModuleFederationPlugin above
+    new MfSharedInspectorPlugin({
+      sourceDirs: ['./src'],
+      failOn: 'mismatch', // 'mismatch' | 'unused' | 'any'
+      warn: true,
+    }),
+  ],
+};
+```
+
+### Gating on score
+
+Use `scoreProjectReport` programmatically to set custom thresholds:
 
 ```typescript
 import { analyzeProject, scoreProjectReport } from '@mf-toolkit/shared-inspector';
@@ -154,9 +217,67 @@ if (score < 70) {
 }
 ```
 
-## Quick start
+### Writing manifests for federation analysis
+
+Each MF can emit a `project-manifest.json` as a build artifact to enable cross-team analysis in a later step:
+
+```bash
+npx @mf-toolkit/shared-inspector --shared ./shared-config.json --write-manifest
+```
+
+With the webpack plugin:
+
+```typescript
+new MfSharedInspectorPlugin({
+  sourceDirs: ['./src'],
+  writeManifest: true, // writes project-manifest.json for CI aggregation
+  warn: true,
+})
+```
+
+Upload the manifest as a CI artifact:
+
+```yaml
+# .github/workflows/build.yml
+jobs:
+  build-checkout:
+    steps:
+      - run: npm run build   # MfSharedInspectorPlugin writes project-manifest.json
+      - uses: actions/upload-artifact@v4
+        with: { name: manifest-checkout, path: project-manifest.json }
+```
+
+## Federation mode
+
+Once each MF has emitted its manifest, aggregate them to detect cross-team conflicts: version mismatches, singleton inconsistencies, and shared-config gaps across host and remotes.
+
+### CLI
+
+```bash
+npx @mf-toolkit/shared-inspector federation checkout.json catalog.json cart.json
+```
+
+### Programmatic
+
+```typescript
+import { analyzeFederation, formatFederationReport, scoreFederationReport } from '@mf-toolkit/shared-inspector';
+
+const report = analyzeFederation([checkoutManifest, catalogManifest, cartManifest]);
+const { score, label } = scoreFederationReport(report);
 
-### Programmatic API (two-phase)
+console.log(formatFederationReport(report));
+// ⚠  Version Conflict — react
+//    checkout: ^17.0.0
+//    catalog: ^18.0.0
+//    → Risk: MF singleton negotiation may silently load the wrong version → Invalid hook call
+//    💡 Fix: shared: { react: { singleton: true, requiredVersion: "^18.0.0" } }
+//
+// Score: 60/100  🟠 RISKY
+```
+
+## Programmatic API
+
+### Two-phase API
 
 ```typescript
 import { buildProjectManifest, analyzeProject, formatReport } from '@mf-toolkit/shared-inspector';
@@ -203,30 +324,6 @@ const report = await inspect({
 });
 ```
 
-### Webpack plugin
-
-`sharedConfig` is optional — the plugin auto-extracts it from `ModuleFederationPlugin` when not provided:
-
-```typescript
-import { MfSharedInspectorPlugin } from '@mf-toolkit/shared-inspector/webpack';
-
-module.exports = {
-  plugins: [
-    new ModuleFederationPlugin({
-      name: 'checkout',
-      shared: { react: { singleton: true }, mobx: { singleton: true } },
-    }),
-
-    // sharedConfig not needed — auto-extracted from ModuleFederationPlugin above
-    new MfSharedInspectorPlugin({
-      sourceDirs: ['./src'],
-      warn: true,
-      writeManifest: true, // writes project-manifest.json for CI aggregation
-    }),
-  ],
-};
-```
-
 ## Analysis depth
 
 | Depth | What it finds | Speed |
@@ -262,41 +359,40 @@ await buildProjectManifest({
 
 Without `tsconfigPath`, `@components/Button` is treated as an external package and packages imported inside it are invisible in `local-graph` mode.
 
-## CI pipeline: project → federation
+## Interactive wizard
 
-Each microfrontend generates a manifest as a build artifact, then they're aggregated for cross-team analysis:
+Not sure which flags to pass? Run the step-by-step wizard:
 
-```yaml
-# .github/workflows/build.yml
-jobs:
-  build-checkout:
-    steps:
-      - run: npm run build   # MfSharedInspectorPlugin writes project-manifest.json
-      - uses: actions/upload-artifact@v4
-        with: { name: manifest-checkout, path: project-manifest.json }
 ```
+$ npx @mf-toolkit/shared-inspector --interactive
 
-```typescript
-import { analyzeFederation, formatFederationReport, scoreFederationReport } from '@mf-toolkit/shared-inspector';
-
-const report = analyzeFederation([checkoutManifest, catalogManifest, cartManifest]);
-const { score, label } = scoreFederationReport(report);
+[MfSharedInspector] Interactive setup
 
-console.log(formatFederationReport(report));
-// ⚠  Version Conflict — react
-//    checkout: ^17.0.0
-//    catalog: ^18.0.0
-//    → Risk: MF singleton negotiation will silently load wrong version → Invalid hook call
-//    💡 Fix: shared: { react: { singleton: true, requiredVersion: "^18.0.0" } }
-//
-// Score: 60/100  🟠 RISKY
+Source directories to scan (default: ./src):
+Scan depth — direct or local-graph (default: local-graph):
+Shared packages — comma-separated names or path to .json (empty to skip): react,react-dom,mobx
+Path to tsconfig.json for alias resolution (empty to skip):
+Workspace packages to exclude, comma-separated (empty to skip):
+Fail build on findings — mismatch / unused / any / none (default: none): mismatch
+Write project-manifest.json? (y/N): n
 ```
 
-Or use the CLI directly:
+## CLI reference
 
-```bash
-npx @mf-toolkit/shared-inspector federation checkout.json catalog.json cart.json
-```
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--source, -s <dirs>` | `./src` | Source dirs to scan, comma-separated |
+| `--depth <depth>` | `local-graph` | Scan depth: `direct` \| `local-graph` |
+| `--shared <packages\|file>` | — | Comma-separated package names or path to `.json` config |
+| `--tsconfig <path>` | — | tsconfig.json for path alias resolution |
+| `--workspace-packages <pkgs>` | — | Comma-separated workspace packages to exclude |
+| `--name <name>` | auto from `package.json` | Project name |
+| `--fail-on <rule>` | — | Exit 1 when findings match: `mismatch` \| `unused` \| `any` |
+| `--write-manifest` | `false` | Write `project-manifest.json` to output dir |
+| `--output-dir <dir>` | `.` | Output directory for manifest |
+| `--interactive, -i` | — | Launch step-by-step wizard |
+| `--version, -v` | — | Print version and exit |
+| `--help, -h` | — | Show help |
 
 ## API reference
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mf-toolkit/shared-inspector",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Stop debugging Module Federation in production. Audit shared config at build time.",
   "author": "Vitaly Zheltko",
   "license": "MIT",
@@ -48,7 +48,9 @@
     "typescript": ">=4.7"
   },
   "peerDependenciesMeta": {
-    "typescript": { "optional": true }
+    "typescript": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/semver": "^7.5.8",