@mf-toolkit/shared-inspector 0.3.2 → 0.4.1

package/README.md

@@ -4,18 +4,95 @@
 [![license](https://img.shields.io/npm/l/@mf-toolkit/shared-inspector?color=blue)](https://github.com/zvitaly7/mf-toolkit/blob/main/LICENSE)
 [![node](https://img.shields.io/node/v/@mf-toolkit/shared-inspector?color=339933&logo=node.js)](https://nodejs.org)
 
-Build-time analyser for Module Federation `shared` dependencies. Two-phase architecture: **collect facts → analyse facts**.
+**Stop debugging Module Federation in production.**
+
+`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.
 
+## Why not bundle analyzer?
+
+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.
+
+| 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 |
+
+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.
+
+## Example
+
+A `shell` host app (React 18) and a `checkout` remote have been developed by separate teams. Their `shared` configs have drifted:
+
+```js
+// shell — webpack.config.js
+shared: {
+  react:     { singleton: true, requiredVersion: '^18.2.0' },
+  'react-dom': { singleton: true, requiredVersion: '^18.2.0' },
+  zustand:   { singleton: true },
+}
+
+// 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:
+
+```
+[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" }
+   }
+
+→  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
+```
+
+**After manually updating the config based on the suggestions above** — `react` version aligned, `zustand` added to `shared`, `lodash` removed:
+
+```
+Score: 100/100  ✅ HEALTHY
+```
+
+The cross-team federation report also clears: `shell` and `checkout` now negotiate a single React instance and a single Zustand store at runtime.
+
 ## Installation
 
 ```bash
@@ -24,58 +101,85 @@ npm install --save-dev @mf-toolkit/shared-inspector
 
 ## Quick start
 
-### Programmatic API (two-phase)
+Run against any MF project — no config file needed:
 
-```typescript
-import { buildProjectManifest, analyzeProject } from '@mf-toolkit/shared-inspector';
+```bash
+npx @mf-toolkit/shared-inspector
+```
 
-// Phase 1: collect facts
-const manifest = await buildProjectManifest({
-  name: 'checkout',
-  sourceDirs: ['./src'],
-  sharedConfig: {
-    react: { singleton: true, requiredVersion: '^19.0.0' },
-    'react-dom': { singleton: true, requiredVersion: '^19.0.0' },
-    lodash: {},
-  },
-  // depth: 'local-graph'       ← default, follows barrel re-exports
-  // tsconfigPath: './tsconfig.json'  ← optional, resolves @alias/* imports
-  // workspacePackages: ['@my-org/*'] ← optional, excludes local monorepo packages
-});
+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:
 
-// Phase 2: analyse facts
-const report = analyzeProject(manifest, {
-  alwaysShared: ['react', 'react-dom'],
-});
+```
+  mf-inspector  v0.4.0
 
-console.log(report.unused);
-// [{ package: 'lodash', singleton: false }]
+✓  Scanned 47 files
 
-console.log(report.candidates);
-// [{ package: 'mobx', importCount: 12, via: 'reexport', files: ['src/shared/index.ts'] }]
+[MfSharedInspector] checkout (depth: local-graph, 47 files scanned)
+────────────────────────────────────────────────────────────
+
+⚠  Version Mismatch — react
+   configured: ^18.0.0 | installed: 17.0.2
+   → Risk: Invalid hook call, broken context across MFs
+   💡 Fix:
+   shared: {
+     react: { singleton: true, requiredVersion: "^18.0.0" }
+   }
+
+✗  Unused Shared — lodash
+   0 imports, shared without singleton
+   → Wastes bundle negotiation overhead with no benefit
+   💡 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 may get its own MobX instance — observables and reactions can fail to sync between MFs
+   💡 Fix:
+   shared: {
+     mobx: { singleton: true }
+   }
+
+────────────────────────────────────────────────────────────
+Score: 62/100  🟠 RISKY
+
+Issues:
+  🔴  1 high    — version mismatch
+  🟠  1 medium  — singleton gaps, duplicate libs
+  🟡  1 low     — over-sharing
+
+Total: 12 shared, 10 used, 1 unused, 1 candidates, 1 mismatch, 0 eager risks
+```
 
-console.log(report.mismatched);
-// [{ package: 'react', configured: '^19.0.0', installed: '18.3.1' }]
+Colors are auto-applied in TTY terminals and disabled in CI / piped output (`NO_COLOR` / `TERM=dumb` respected).
 
-console.log(report.eagerRisks);
-// [{ package: 'react-dom' }]  ← eager: true without singleton: true
-```
+### Risk scoring
 
-### Shortcut API
+Every report ends with a score out of 100:
 
-```typescript
-import { inspect } from '@mf-toolkit/shared-inspector';
+| Severity | Penalty | Covers |
+|----------|---------|--------|
+| 🔴 HIGH | −20 each | Version mismatches, cross-MF version conflicts |
+| 🟠 MEDIUM | −8 each | Singleton risks, eager risks, duplicate libs, host gaps |
+| 🟡 LOW | −3 each | Unused shared packages, ghost shares |
 
-const report = await inspect({
-  name: 'checkout',
-  sourceDirs: ['./src'],
-  sharedConfig: { /* ... */ },
-});
-```
+| Score | Label |
+|-------|-------|
+| 90–100 | ✅ HEALTHY |
+| 70–89 | 🟡 GOOD |
+| 40–69 | 🟠 RISKY |
+| 0–39 | 🔴 CRITICAL |
 
-### Webpack plugin
+## CI mode
 
-`sharedConfig` is optional — the plugin auto-extracts it from `ModuleFederationPlugin` when not provided:
+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';
@@ -90,144 +194,206 @@ module.exports = {
     // sharedConfig not needed — auto-extracted from ModuleFederationPlugin above
     new MfSharedInspectorPlugin({
       sourceDirs: ['./src'],
+      failOn: 'mismatch', // 'mismatch' | 'unused' | 'any'
       warn: true,
-      writeManifest: true, // writes project-manifest.json for CI aggregation
     }),
   ],
 };
 ```
 
-Pass `sharedConfig` explicitly to override auto-extraction:
+### Gating on score
+
+Use `scoreProjectReport` programmatically to set custom thresholds:
 
 ```typescript
-new MfSharedInspectorPlugin({
-  sourceDirs: ['./src'],
-  sharedConfig: { react: { singleton: true, requiredVersion: '^18.0.0' } },
-})
-```
+import { analyzeProject, scoreProjectReport } from '@mf-toolkit/shared-inspector';
 
-## Analysis depth
+const report = analyzeProject(manifest);
+const { score, label, high, medium, low } = scoreProjectReport(report);
 
-| Depth | What it finds | Speed |
-|-------|--------------|-------|
-| `'direct'` | Explicit `import` / `require` statements | Fast (ms) |
-| `'local-graph'` *(default)* | + packages reachable via barrel re-exports and local wrappers | Slower (seconds) |
+if (score < 70) {
+  console.error(`Shared config score: ${score}/100 (${label})`);
+  process.exit(1);
+}
+```
 
-The difference matters when your project uses barrel files:
+### Writing manifests for federation analysis
 
-```ts
-// src/shared/index.ts
-export { observer } from 'mobx-react';    // re-export
-export { makeAutoObservable } from 'mobx'; // re-export
+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
 ```
 
-```ts
-// src/app.tsx
-import { observer } from './shared';  // relative import — direct mode stops here
+With the webpack plugin:
+
+```typescript
+new MfSharedInspectorPlugin({
+  sourceDirs: ['./src'],
+  writeManifest: true, // writes project-manifest.json for CI aggregation
+  warn: true,
+})
 ```
 
-- **`depth: 'direct'`** scans `app.tsx`, sees `./shared` (relative) → skips. `mobx` not found.
-- **`depth: 'local-graph'`** follows `./shared` → `shared/index.ts` → finds `mobx` and `mobx-react` via re-export.
+Upload the manifest as a CI artifact:
 
-## TypeScript path aliases
+```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 }
+```
 
-When your project uses `paths` in `tsconfig.json`, pass `tsconfigPath` so the traverser follows aliased imports into local files instead of treating them as external packages:
+## Federation mode
 
-```typescript
-// tsconfig.json
-{ "compilerOptions": { "baseUrl": ".", "paths": { "@components/*": ["src/components/*"] } } }
+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.
 
-// src/app.tsx
-import { Button } from '@components/Button'; // ← followed as local file, not external package
+### CLI
+
+```bash
+npx @mf-toolkit/shared-inspector federation checkout.json catalog.json cart.json
 ```
 
+### Programmatic
+
 ```typescript
-await buildProjectManifest({
-  sourceDirs: ['./src'],
-  tsconfigPath: './tsconfig.json', // enables alias resolution
-});
-```
+import { analyzeFederation, formatFederationReport, scoreFederationReport } from '@mf-toolkit/shared-inspector';
 
-Without `tsconfigPath`, `@components/Button` is treated as an external package name and packages imported inside it are invisible in local-graph mode.
+const report = analyzeFederation([checkoutManifest, catalogManifest, cartManifest]);
+const { score, label } = scoreFederationReport(report);
+
+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
+```
 
-## Workspace packages
+## Programmatic API
 
-In a monorepo where local packages import each other, use `workspacePackages` to prevent internal packages from appearing in `resolvedPackages`:
+### Two-phase API
 
 ```typescript
-await buildProjectManifest({
+import { buildProjectManifest, analyzeProject, formatReport } from '@mf-toolkit/shared-inspector';
+
+// Phase 1: collect facts
+const manifest = await buildProjectManifest({
+  name: 'checkout',
   sourceDirs: ['./src'],
-  workspacePackages: ['@my-org/design-system', '@my-org/*'],
+  sharedConfig: {
+    react: { singleton: true, requiredVersion: '^18.0.0' },
+    'react-dom': { singleton: true, requiredVersion: '^18.0.0' },
+    lodash: {},
+  },
+  // depth: 'local-graph'            ← default, follows barrel re-exports
+  // tsconfigPath: './tsconfig.json' ← optional, resolves @alias/* imports
+  // workspacePackages: ['@my-org/*'] ← optional, excludes local monorepo packages
 });
-```
 
-## Terminal output
+// Phase 2: analyse facts
+const report = analyzeProject(manifest);
 
-```
-[MfSharedInspector] checkout (depth: local-graph, 47 files scanned)
+console.log(report.mismatched);
+// [{ package: 'react', configured: '^18.0.0', installed: '17.0.2' }]
 
-  Version mismatch (sharing silently broken):
-    ⚠ react — requires ^19.0.0, installed 18.3.1
+console.log(report.candidates);
+// [{ package: 'mobx', importCount: 12, via: 'reexport', files: ['src/shared/index.ts'] }]
 
-  Unused shared (safe to remove):
-    ✗ lodash — 0 imports, shared without singleton
-    ✗ @tanstack/react-query — 0 imports, shared as singleton
+console.log(report.unused);
+// [{ package: 'lodash', singleton: false }]
 
-  Candidates (consider adding to shared):
-    → mobx (12 imports in 8 files, via re-export in src/shared/index.ts)
-    → react-router-dom (6 imports in 4 files)
+// Human-readable output with risk descriptions and fix snippets
+console.log(formatReport(report, { name: manifest.project.name }));
+```
 
-  Singleton risks (add singleton: true):
-    ⚠ react-router-dom — manages global state, singleton: true recommended
+### Shortcut API
 
-  Eager risks (add singleton: true or remove eager: true):
-    ⚠ react-dom — eager: true without singleton: true, risk of duplicate instances
+```typescript
+import { inspect } from '@mf-toolkit/shared-inspector';
 
-  Total: 12 shared, 10 used, 2 unused, 2 candidates, 1 mismatch, 1 eager risks
+const report = await inspect({
+  name: 'checkout',
+  sourceDirs: ['./src'],
+  sharedConfig: { /* ... */ },
+});
 ```
 
-## CI pipeline: project → federation
+## Analysis depth
+
+| Depth | What it finds | Speed |
+|-------|--------------|-------|
+| `'direct'` | Explicit `import` / `require` statements | Fast (ms) |
+| `'local-graph'` *(default)* | + packages reachable via barrel re-exports and local wrappers | Slower (seconds) |
+
+The difference matters when your project uses barrel files:
 
-Each microfrontend generates a manifest as a build artifact:
+```ts
+// src/shared/index.ts
+export { observer } from 'mobx-react';    // re-export
+export { makeAutoObservable } from 'mobx'; // re-export
 
-```yaml
-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
+// src/app.tsx
+import { observer } from './shared';  // relative import — direct mode stops here
 ```
 
-Each MF manifest can then be aggregated for cross-team analysis:
+- **`depth: 'direct'`** sees `./shared` (relative) → skips. `mobx` not found.
+- **`depth: 'local-graph'`** follows `./shared` → finds `mobx` and `mobx-react` via re-export.
+
+## TypeScript path aliases
 
 ```typescript
-import { analyzeFederation, formatFederationReport } from '@mf-toolkit/shared-inspector';
+// tsconfig.json
+{ "compilerOptions": { "paths": { "@components/*": ["src/components/*"] } } }
 
-const report = analyzeFederation([checkoutManifest, catalogManifest, cartManifest]);
-console.log(formatFederationReport(report));
+await buildProjectManifest({
+  sourceDirs: ['./src'],
+  tsconfigPath: './tsconfig.json', // enables alias resolution
+});
 ```
 
-```
-[MfSharedInspector] federation analysis (3 MFs)
+Without `tsconfigPath`, `@components/Button` is treated as an external package and packages imported inside it are invisible in `local-graph` mode.
 
-  Version conflicts (singleton negotiation will fail):
-    ⚠ react — checkout: ^17.0.0, catalog: ^18.0.0
+## Interactive wizard
 
-  Singleton mismatches (add singleton: true to all MFs):
-    ⚠ mobx — singleton in [checkout], not singleton in [catalog, cart]
+Not sure which flags to pass? Run the step-by-step wizard:
 
-  Host gaps (add to shared — each MF bundles its own copy):
-    → axios — used by [checkout, catalog], not in shared
+```
+$ npx @mf-toolkit/shared-inspector --interactive
 
-  Ghost shares (remove from shared — no other MF benefits):
-    ✗ lodash — shared only by cart, unused by all other MFs
+[MfSharedInspector] Interactive setup
 
-  Total: 3 MFs, 1 version conflicts, 1 singleton mismatches, 1 host gaps, 1 ghost shares
+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
 ```
 
+## CLI reference
+
+| 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
 
 ### `buildProjectManifest(options)`
@@ -253,6 +419,20 @@ console.log(formatFederationReport(report));
 | `additionalCandidates` | `string[]` | `[]` | Extend built-in candidates list |
 | `additionalSingletonRisks` | `string[]` | `[]` | Extend built-in singleton-risk list |
 
+### `scoreProjectReport(report)` / `scoreFederationReport(report)`
+
+Returns a `RiskScore`:
+
+```typescript
+interface RiskScore {
+  score: number;                           // 0–100, higher is better
+  label: 'HEALTHY' | 'GOOD' | 'RISKY' | 'CRITICAL';
+  high: number;                            // count of high-severity findings
+  medium: number;                          // count of medium-severity findings
+  low: number;                             // count of low-severity findings
+}
+```
+
 ### `analyzeFederation(manifests, options?)`
 
 Accepts N `ProjectManifest` objects (one per microfrontend) and returns a `FederationReport`.
@@ -261,20 +441,12 @@ Accepts N `ProjectManifest` objects (one per microfrontend) and returns a `Feder
 |--------|------|---------|-------------|
 | `alwaysShared` | `string[]` | `['react','react-dom']` | Exclude from ghost/gap detection |
 
-### `formatFederationReport(report)`
-
-Formats a `FederationReport` as a human-readable terminal string.
-
 ### `MfSharedInspectorPlugin` options
 
 Extends all `buildProjectManifest` options (except `name`, auto-resolved from compiler) plus:
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `sourceDirs` | `string[]` | — | Directories to scan |
-| `sharedConfig` | `Record<string, SharedDepConfig>` | auto-extracted | Override auto-extraction from `ModuleFederationPlugin` |
-| `tsconfigPath` | `string` | `undefined` | tsconfig.json for path alias resolution |
-| `workspacePackages` | `string[]` | `[]` | Local monorepo packages to exclude |
 | `warn` | `boolean` | `true` | Print findings to console |
 | `failOn` | `'mismatch' \| 'unused' \| 'any'` | `undefined` | Fail the build when findings match |
 | `writeManifest` | `boolean` | `false` | Write `project-manifest.json` to `outputDir` |
@@ -285,37 +457,29 @@ Extends all `buildProjectManifest` options (except `name`, auto-resolved from co
 
 ### Per-project (`analyzeProject`)
 
-| Category | Type | Description |
-|----------|------|-------------|
-| `mismatched` | Deterministic | `requiredVersion` doesn't satisfy installed version |
-| `unused` | Deterministic* | In `shared` config but not observed in scanned sources |
-| `candidates` | Heuristic | Observed packages not in `shared` that are typically shared |
-| `singletonRisks` | Heuristic | Global-state packages shared without `singleton: true` |
-| `eagerRisks` | Heuristic | `eager: true` without `singleton: true` — risk of duplicate instances |
-
-*Within the visibility of the chosen depth.*
+| Category | Severity | Description |
+|----------|----------|-------------|
+| `mismatched` | 🔴 HIGH | `requiredVersion` doesn't satisfy installed version |
+| `singletonRisks` | 🟠 MEDIUM | Global-state packages shared without `singleton: true` |
+| `eagerRisks` | 🟠 MEDIUM | `eager: true` without `singleton: true` |
+| `candidates` | 🟠 MEDIUM | Used packages missing from `shared` (each MF bundles own copy) |
+| `unused` | 🟡 LOW | In `shared` config but not observed in scanned sources |
 
 ### Cross-MF (`analyzeFederation`)
 
-| Category | Type | Description |
-|----------|------|-------------|
-| `versionConflicts` | Deterministic | `requiredVersion` ranges across MFs have no overlap |
-| `singletonMismatches` | Deterministic | `singleton: true` in some MFs, absent in others |
-| `hostGaps` | Heuristic | Package used by 2+ MFs but not declared in `shared` by anyone |
-| `ghostShares` | Heuristic | Package in `shared` of one MF, unused/unshared by all others |
+| Category | Severity | Description |
+|----------|----------|-------------|
+| `versionConflicts` | 🔴 HIGH | `requiredVersion` ranges across MFs have no overlap |
+| `singletonMismatches` | 🟠 MEDIUM | `singleton: true` in some MFs, absent in others |
+| `hostGaps` | 🟠 MEDIUM | Package used by 2+ MFs but not declared in `shared` by anyone |
+| `ghostShares` | 🟡 LOW | Package in `shared` of one MF, unused/unshared by all others |
 
 ## Known limitations
 
-- **TypeScript path aliases without `tsconfigPath`**: aliased imports are treated as external package names. Pass `tsconfigPath` to resolve them correctly.
+- **TypeScript path aliases without `tsconfigPath`**: aliased imports are treated as external package names.
 - **Dynamic imports with variables** (`import(moduleName)`): not analysed — requires runtime information.
-- **Exact tsconfig alias patterns** (non-wildcard, e.g. `"@root": ["."]`): not supported, only `"@alias/*"` wildcard form.
-- **Subclassed `ModuleFederationPlugin`**: auto-extraction matches by constructor name. A custom subclass (`class MyMFP extends ModuleFederationPlugin`) won't be detected — pass `sharedConfig` explicitly in that case.
-
-## Demo
-
-```bash
-npx tsx packages/shared-inspector/demo/run.ts
-```
+- **Exact tsconfig alias patterns** (non-wildcard): only `"@alias/*"` wildcard form is supported.
+- **Subclassed `ModuleFederationPlugin`**: auto-extraction matches by constructor name — pass `sharedConfig` explicitly for custom subclasses.
 
 ## License
 

package/dist/cli/args.d.ts

@@ -0,0 +1,5 @@
+import type { CliArgs } from './types.js';
+import type { SharedDepConfig } from '../types.js';
+export declare function parseArgs(argv: string[]): CliArgs;
+export declare function parseSharedValue(value: string): Record<string, SharedDepConfig>;
+//# sourceMappingURL=args.d.ts.map

package/dist/cli/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAKnD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAuFjD;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAS/E"}