@mf-toolkit/shared-inspector 0.1.0

package/README.md

@@ -0,0 +1,254 @@
+# `@mf-toolkit/shared-inspector`
+
+[![status](https://img.shields.io/badge/status-in_development-orange)](https://github.com/zvitaly7/mf-toolkit)
+[![version](https://img.shields.io/badge/version-0.1.0_unreleased-lightgrey)](https://github.com/zvitaly7/mf-toolkit)
+[![license](https://img.shields.io/badge/license-MIT-blue)](https://github.com/zvitaly7/mf-toolkit/blob/main/LICENSE)
+[![node](https://img.shields.io/badge/node-%E2%89%A518-339933?logo=node.js)](https://nodejs.org)
+
+> ⚠️ **Work in progress.** This package is feature-complete and fully tested (179 tests) but has not yet been published to npm. The API is stable but may receive minor changes before the official release. Do not use in production until v0.1.0 is tagged.
+
+Build-time analyser for Module Federation `shared` dependencies. Two-phase architecture: **collect facts → analyse facts**.
+
+## 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).
+- **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
+
+```bash
+npm install --save-dev @mf-toolkit/shared-inspector
+```
+
+## Quick start
+
+### Programmatic API (two-phase)
+
+```typescript
+import { buildProjectManifest, analyzeProject } from '@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
+});
+
+// Phase 2: analyse facts
+const report = analyzeProject(manifest, {
+  alwaysShared: ['react', 'react-dom'],
+});
+
+console.log(report.unused);
+// [{ package: 'lodash', singleton: false }]
+
+console.log(report.candidates);
+// [{ package: 'mobx', importCount: 12, via: 'reexport', files: ['src/shared/index.ts'] }]
+
+console.log(report.mismatched);
+// [{ package: 'react', configured: '^19.0.0', installed: '18.3.1' }]
+
+console.log(report.eagerRisks);
+// [{ package: 'react-dom' }]  ← eager: true without singleton: true
+```
+
+### Shortcut API
+
+```typescript
+import { inspect } from '@mf-toolkit/shared-inspector';
+
+const report = await inspect({
+  name: 'checkout',
+  sourceDirs: ['./src'],
+  sharedConfig: { /* ... */ },
+});
+```
+
+### 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 } },
+    }),
+
+    new MfSharedInspectorPlugin({
+      sourceDirs: ['./src'],
+      sharedConfig: {
+        react: { singleton: true, requiredVersion: '^19.0.0' },
+        mobx: { singleton: true },
+      },
+      tsconfigPath: './tsconfig.json',   // resolve @alias/* imports
+      warn: true,
+      writeManifest: true,              // writes project-manifest.json for CI
+    }),
+  ],
+};
+```
+
+## 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:
+
+```ts
+// src/shared/index.ts
+export { observer } from 'mobx-react';    // re-export
+export { makeAutoObservable } from 'mobx'; // re-export
+```
+
+```ts
+// src/app.tsx
+import { observer } from './shared';  // relative import — direct mode stops here
+```
+
+- **`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.
+
+## TypeScript path aliases
+
+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:
+
+```typescript
+// tsconfig.json
+{ "compilerOptions": { "baseUrl": ".", "paths": { "@components/*": ["src/components/*"] } } }
+
+// src/app.tsx
+import { Button } from '@components/Button'; // ← followed as local file, not external package
+```
+
+```typescript
+await buildProjectManifest({
+  sourceDirs: ['./src'],
+  tsconfigPath: './tsconfig.json', // enables alias resolution
+});
+```
+
+Without `tsconfigPath`, `@components/Button` is treated as an external package name and packages imported inside it are invisible in local-graph mode.
+
+## Workspace packages
+
+In a monorepo where local packages import each other, use `workspacePackages` to prevent internal packages from appearing in `resolvedPackages`:
+
+```typescript
+await buildProjectManifest({
+  sourceDirs: ['./src'],
+  workspacePackages: ['@my-org/design-system', '@my-org/*'],
+});
+```
+
+## Terminal output
+
+```
+[MfSharedInspector] checkout (depth: local-graph, 47 files scanned)
+
+  Version mismatch (sharing silently broken):
+    ⚠ react — requires ^19.0.0, installed 18.3.1
+
+  Unused shared (safe to remove):
+    ✗ lodash — 0 imports, shared without singleton
+    ✗ @tanstack/react-query — 0 imports, shared as singleton
+
+  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)
+
+  Singleton risks (add singleton: true):
+    ⚠ react-router-dom — manages global state, singleton: true recommended
+
+  Eager risks (add singleton: true or remove eager: true):
+    ⚠ react-dom — eager: true without singleton: true, risk of duplicate instances
+
+  Total: 12 shared, 10 used, 2 unused, 2 candidates, 1 mismatch, 1 eager risks
+```
+
+## CI pipeline: project → federation
+
+Each microfrontend generates a manifest as a build artifact:
+
+```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
+```
+
+`analyzeFederation()` (v0.2) will accept N manifests and detect cross-MF issues: ghost sharing, host gaps, version conflicts.
+
+## API reference
+
+### `buildProjectManifest(options)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `name` | `string` | — | Project name |
+| `sourceDirs` | `string[]` | — | Directories to scan |
+| `depth` | `'direct' \| 'local-graph'` | `'local-graph'` | Scan depth |
+| `sharedConfig` | `Record<string, SharedDepConfig>` | `{}` | MF shared config |
+| `packageJsonPath` | `string` | `'./package.json'` | Path to package.json |
+| `extensions` | `string[]` | `['.ts','.tsx','.js','.jsx']` | File extensions |
+| `ignore` | `string[]` | `[]` | Packages to exclude (supports `@scope/*`) |
+| `tsconfigPath` | `string` | `undefined` | tsconfig.json for path alias resolution |
+| `workspacePackages` | `string[]` | `[]` | Local monorepo packages to exclude |
+| `kind` | `'host' \| 'remote' \| 'unknown'` | `'unknown'` | Project role |
+
+### `analyzeProject(manifest, options?)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `alwaysShared` | `string[]` | `['react','react-dom']` | Never flag as unused |
+| `additionalCandidates` | `string[]` | `[]` | Extend built-in candidates list |
+| `additionalSingletonRisks` | `string[]` | `[]` | Extend built-in singleton-risk list |
+
+## Detection categories
+
+| 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.*
+
+## Known limitations
+
+- **TypeScript path aliases without `tsconfigPath`**: aliased imports are treated as external package names. Pass `tsconfigPath` to resolve them correctly.
+- **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.
+- **`analyzeFederation()`** (cross-MF analysis): v0.2.
+
+## Demo
+
+```bash
+npx tsx packages/shared-inspector/demo/run.ts
+```
+
+## License
+
+MIT

package/dist/analyzer/analyze-project.d.ts

@@ -0,0 +1,9 @@
+import type { ProjectManifest, ProjectReport, AnalysisOptions } from '../types.js';
+/**
+ * Analyze a single ProjectManifest and return a ProjectReport.
+ *
+ * Pure function — no I/O. All findings are scoped to what the collector
+ * observed at the chosen depth (manifest.source.depth).
+ */
+export declare function analyzeProject(manifest: ProjectManifest, options?: AnalysisOptions): ProjectReport;
+//# sourceMappingURL=analyze-project.d.ts.map

package/dist/analyzer/analyze-project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-project.d.ts","sourceRoot":"","sources":["../../src/analyzer/analyze-project.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAInF;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,eAAe,EACzB,OAAO,CAAC,EAAE,eAAe,GACxB,aAAa,CAiCf"}

package/dist/analyzer/analyze-project.js

@@ -0,0 +1,38 @@
+import { detectIssues } from './detect-issues.js';
+import { mergePolicy } from './policy.js';
+/**
+ * Analyze a single ProjectManifest and return a ProjectReport.
+ *
+ * Pure function — no I/O. All findings are scoped to what the collector
+ * observed at the chosen depth (manifest.source.depth).
+ */
+export function analyzeProject(manifest, options) {
+    const policy = mergePolicy(options);
+    const { unused, candidates, mismatched, singletonRisks, eagerRisks } = detectIssues({
+        resolvedPackages: manifest.usage.resolvedPackages,
+        packageDetails: manifest.usage.packageDetails,
+        sharedDeclared: manifest.shared.declared,
+        installedVersions: manifest.versions.installed,
+        policy,
+    });
+    const totalShared = Object.keys(manifest.shared.declared).length;
+    const resolvedSet = new Set(manifest.usage.resolvedPackages);
+    const usedShared = Object.keys(manifest.shared.declared).filter(pkg => resolvedSet.has(pkg)).length;
+    return {
+        unused,
+        candidates,
+        mismatched,
+        singletonRisks,
+        eagerRisks,
+        summary: {
+            totalShared,
+            usedShared,
+            unusedCount: unused.length,
+            candidatesCount: candidates.length,
+            mismatchedCount: mismatched.length,
+            singletonRisksCount: singletonRisks.length,
+            eagerRisksCount: eagerRisks.length,
+        },
+    };
+}
+//# sourceMappingURL=analyze-project.js.map

package/dist/analyzer/analyze-project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-project.js","sourceRoot":"","sources":["../../src/analyzer/analyze-project.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAC5B,QAAyB,EACzB,OAAyB;IAEzB,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IAEpC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,cAAc,EAAE,UAAU,EAAE,GAAG,YAAY,CAAC;QAClF,gBAAgB,EAAE,QAAQ,CAAC,KAAK,CAAC,gBAAgB;QACjD,cAAc,EAAE,QAAQ,CAAC,KAAK,CAAC,cAAc;QAC7C,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ;QACxC,iBAAiB,EAAE,QAAQ,CAAC,QAAQ,CAAC,SAAS;QAC9C,MAAM;KACP,CAAC,CAAC;IAEH,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC;IACjE,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;IAC7D,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CACpE,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CACrB,CAAC,MAAM,CAAC;IAET,OAAO;QACL,MAAM;QACN,UAAU;QACV,UAAU;QACV,cAAc;QACd,UAAU;QACV,OAAO,EAAE;YACP,WAAW;YACX,UAAU;YACV,WAAW,EAAE,MAAM,CAAC,MAAM;YAC1B,eAAe,EAAE,UAAU,CAAC,MAAM;YAClC,eAAe,EAAE,UAAU,CAAC,MAAM;YAClC,mBAAmB,EAAE,cAAc,CAAC,MAAM;YAC1C,eAAe,EAAE,UAAU,CAAC,MAAM;SACnC;KACF,CAAC;AACJ,CAAC"}

package/dist/analyzer/detect-issues.d.ts

@@ -0,0 +1,33 @@
+import type { UnusedEntry, CandidateEntry, MismatchedEntry, SingletonRiskEntry, EagerRiskEntry } from '../types.js';
+import type { ResolvedPolicy } from './policy.js';
+export interface DetectIssuesInput {
+    resolvedPackages: string[];
+    packageDetails: Array<{
+        package: string;
+        importCount: number;
+        files: string[];
+        via: 'direct' | 'reexport';
+    }>;
+    sharedDeclared: Record<string, {
+        singleton?: boolean;
+        eager?: boolean;
+        requiredVersion?: string;
+    }>;
+    /** From node_modules. Empty object = not accessible, mismatch checks skipped for absent entries. */
+    installedVersions: Record<string, string>;
+    policy: ResolvedPolicy;
+}
+export interface DetectIssuesResult {
+    unused: UnusedEntry[];
+    candidates: CandidateEntry[];
+    mismatched: MismatchedEntry[];
+    singletonRisks: SingletonRiskEntry[];
+    eagerRisks: EagerRiskEntry[];
+}
+/**
+ * Pure function — no I/O.
+ * Cross-checks manifest data against policy to produce findings.
+ * All results are scoped to what the collector observed at the chosen depth.
+ */
+export declare function detectIssues(input: DetectIssuesInput): DetectIssuesResult;
+//# sourceMappingURL=detect-issues.d.ts.map

package/dist/analyzer/detect-issues.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect-issues.d.ts","sourceRoot":"","sources":["../../src/analyzer/detect-issues.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,cAAc,EACf,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD,MAAM,WAAW,iBAAiB;IAChC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,cAAc,EAAE,KAAK,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,MAAM,EAAE,CAAC;QAChB,GAAG,EAAE,QAAQ,GAAG,UAAU,CAAC;KAC5B,CAAC,CAAC;IACH,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE;QAC7B,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,CAAC,CAAC;IACH,oGAAoG;IACpG,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,cAAc,EAAE,kBAAkB,EAAE,CAAC;IACrC,UAAU,EAAE,cAAc,EAAE,CAAC;CAC9B;AAID;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,kBAAkB,CA8DzE"}

package/dist/analyzer/detect-issues.js

@@ -0,0 +1,69 @@
+import semver from 'semver';
+// ─── Core detection ───────────────────────────────────────────────────────────
+/**
+ * Pure function — no I/O.
+ * Cross-checks manifest data against policy to produce findings.
+ * All results are scoped to what the collector observed at the chosen depth.
+ */
+export function detectIssues(input) {
+    const resolvedSet = new Set(input.resolvedPackages);
+    const sharedEntries = Object.entries(input.sharedDeclared);
+    const detailsMap = new Map(input.packageDetails.map(d => [d.package, d]));
+    // Unused: in shared config but not observed in resolvedPackages
+    // Packages in alwaysShared are always excluded from this list.
+    const unused = sharedEntries
+        .filter(([pkg]) => !resolvedSet.has(pkg) && !input.policy.alwaysShared.has(pkg))
+        .map(([pkg, config]) => ({
+        package: pkg,
+        singleton: config.singleton ?? false,
+    }));
+    // Candidates: observed but not shared, and in the built-in share-candidates list
+    const candidates = input.resolvedPackages
+        .filter(pkg => !input.sharedDeclared[pkg] && input.policy.shareCandidates.has(pkg))
+        .map(pkg => {
+        const detail = detailsMap.get(pkg);
+        return {
+            package: pkg,
+            importCount: detail?.importCount ?? 1,
+            files: detail?.files ?? [],
+            via: detail?.via ?? 'direct',
+        };
+    });
+    // Mismatched: requiredVersion does not satisfy the installed version.
+    // Skipped when installed version is unknown (installedVersions[pkg] absent).
+    const mismatched = [];
+    for (const [pkg, config] of sharedEntries) {
+        if (!config.requiredVersion)
+            continue;
+        const installed = input.installedVersions[pkg];
+        if (!installed)
+            continue;
+        // semver.validRange returns null for invalid ranges; skip to avoid false positives
+        if (!semver.validRange(config.requiredVersion))
+            continue;
+        try {
+            if (!semver.satisfies(installed, config.requiredVersion)) {
+                mismatched.push({
+                    package: pkg,
+                    configured: config.requiredVersion,
+                    installed,
+                });
+            }
+        }
+        catch {
+            // Defensive: skip if satisfies throws unexpectedly
+        }
+    }
+    // Singleton risks: in the singleton-risk list but shared without singleton: true
+    const singletonRisks = sharedEntries
+        .filter(([pkg, config]) => input.policy.singletonRisks.has(pkg) && !config.singleton)
+        .map(([pkg]) => ({ package: pkg }));
+    // Eager risks: eager: true without singleton: true.
+    // Eager-loading without singleton can produce duplicate module instances
+    // when multiple MFs initialise the same package before version negotiation.
+    const eagerRisks = sharedEntries
+        .filter(([_, config]) => config.eager === true && config.singleton !== true)
+        .map(([pkg]) => ({ package: pkg }));
+    return { unused, candidates, mismatched, singletonRisks, eagerRisks };
+}
+//# sourceMappingURL=detect-issues.js.map

package/dist/analyzer/detect-issues.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect-issues.js","sourceRoot":"","sources":["../../src/analyzer/detect-issues.ts"],"names":[],"mappings":"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"}

package/dist/analyzer/policy.d.ts

@@ -0,0 +1,27 @@
+import type { AnalysisOptions } from '../types.js';
+/**
+ * Packages that are never flagged as unused by default.
+ * React is consumed transitively by JSX Transform (no explicit import needed).
+ */
+export declare const DEFAULT_ALWAYS_SHARED: readonly string[];
+/**
+ * Packages with global state — should be shared with singleton: true.
+ * Duplicating these causes runtime errors (e.g. "Invalid hook call").
+ */
+export declare const SINGLETON_RISK_PACKAGES: readonly string[];
+/**
+ * Packages that are typically shared across microfrontends.
+ * Used for the candidates heuristic — presence in this list + not in shared config = suggestion.
+ */
+export declare const SHARE_CANDIDATE_PACKAGES: readonly string[];
+export interface ResolvedPolicy {
+    alwaysShared: Set<string>;
+    singletonRisks: Set<string>;
+    shareCandidates: Set<string>;
+}
+/**
+ * Merge built-in policy with user-supplied AnalysisOptions.
+ * User lists extend (not replace) the built-in lists.
+ */
+export declare function mergePolicy(options?: AnalysisOptions): ResolvedPolicy;
+//# sourceMappingURL=policy.d.ts.map

package/dist/analyzer/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/analyzer/policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAInD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAGlD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAepD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EA2BrD,CAAC;AAIF,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1B,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5B,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,cAAc,CAgBrE"}

package/dist/analyzer/policy.js

@@ -0,0 +1,84 @@
+// ─── Built-in lists ───────────────────────────────────────────────────────────
+/**
+ * Packages that are never flagged as unused by default.
+ * React is consumed transitively by JSX Transform (no explicit import needed).
+ */
+export const DEFAULT_ALWAYS_SHARED = [
+    'react',
+    'react-dom',
+];
+/**
+ * Packages with global state — should be shared with singleton: true.
+ * Duplicating these causes runtime errors (e.g. "Invalid hook call").
+ */
+export const SINGLETON_RISK_PACKAGES = [
+    'react',
+    'react-dom',
+    'react-router',
+    'react-router-dom',
+    'vue',
+    'vue-router',
+    'mobx',
+    'mobx-react',
+    'mobx-react-lite',
+    'styled-components',
+    '@emotion/react',
+    '@emotion/styled',
+    'redux',
+    '@reduxjs/toolkit',
+];
+/**
+ * Packages that are typically shared across microfrontends.
+ * Used for the candidates heuristic — presence in this list + not in shared config = suggestion.
+ */
+export const SHARE_CANDIDATE_PACKAGES = [
+    // Frameworks
+    'react',
+    'react-dom',
+    'vue',
+    'svelte',
+    'solid-js',
+    // Routing
+    'react-router',
+    'react-router-dom',
+    'vue-router',
+    // State management
+    'mobx',
+    'mobx-react',
+    'mobx-react-lite',
+    'redux',
+    '@reduxjs/toolkit',
+    'zustand',
+    'jotai',
+    'recoil',
+    // Data fetching
+    '@tanstack/react-query',
+    'swr',
+    // Styling
+    'styled-components',
+    '@emotion/react',
+    '@emotion/styled',
+];
+/**
+ * Merge built-in policy with user-supplied AnalysisOptions.
+ * User lists extend (not replace) the built-in lists.
+ */
+export function mergePolicy(options) {
+    const alwaysShared = new Set(DEFAULT_ALWAYS_SHARED);
+    const singletonRisks = new Set(SINGLETON_RISK_PACKAGES);
+    const shareCandidates = new Set(SHARE_CANDIDATE_PACKAGES);
+    if (options?.alwaysShared) {
+        for (const pkg of options.alwaysShared)
+            alwaysShared.add(pkg);
+    }
+    if (options?.additionalSingletonRisks) {
+        for (const pkg of options.additionalSingletonRisks)
+            singletonRisks.add(pkg);
+    }
+    if (options?.additionalCandidates) {
+        for (const pkg of options.additionalCandidates)
+            shareCandidates.add(pkg);
+    }
+    return { alwaysShared, singletonRisks, shareCandidates };
+}
+//# sourceMappingURL=policy.js.map

package/dist/analyzer/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../src/analyzer/policy.ts"],"names":[],"mappings":"AAEA,iFAAiF;AAEjF;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAsB;IACtD,OAAO;IACP,WAAW;CACZ,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAsB;IACxD,OAAO;IACP,WAAW;IACX,cAAc;IACd,kBAAkB;IAClB,KAAK;IACL,YAAY;IACZ,MAAM;IACN,YAAY;IACZ,iBAAiB;IACjB,mBAAmB;IACnB,gBAAgB;IAChB,iBAAiB;IACjB,OAAO;IACP,kBAAkB;CACnB,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAsB;IACzD,aAAa;IACb,OAAO;IACP,WAAW;IACX,KAAK;IACL,QAAQ;IACR,UAAU;IACV,UAAU;IACV,cAAc;IACd,kBAAkB;IAClB,YAAY;IACZ,mBAAmB;IACnB,MAAM;IACN,YAAY;IACZ,iBAAiB;IACjB,OAAO;IACP,kBAAkB;IAClB,SAAS;IACT,OAAO;IACP,QAAQ;IACR,gBAAgB;IAChB,uBAAuB;IACvB,KAAK;IACL,UAAU;IACV,mBAAmB;IACnB,gBAAgB;IAChB,iBAAiB;CAClB,CAAC;AAUF;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,OAAyB;IACnD,MAAM,YAAY,GAAG,IAAI,GAAG,CAAS,qBAAqB,CAAC,CAAC;IAC5D,MAAM,cAAc,GAAG,IAAI,GAAG,CAAS,uBAAuB,CAAC,CAAC;IAChE,MAAM,eAAe,GAAG,IAAI,GAAG,CAAS,wBAAwB,CAAC,CAAC;IAElE,IAAI,OAAO,EAAE,YAAY,EAAE,CAAC;QAC1B,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,YAAY;YAAE,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChE,CAAC;IACD,IAAI,OAAO,EAAE,wBAAwB,EAAE,CAAC;QACtC,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,wBAAwB;YAAE,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC9E,CAAC;IACD,IAAI,OAAO,EAAE,oBAAoB,EAAE,CAAC;QAClC,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,oBAAoB;YAAE,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC3E,CAAC;IAED,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,CAAC;AAC3D,CAAC"}

package/dist/collector/build-project-manifest.d.ts

@@ -0,0 +1,10 @@
+import type { CollectorOptions, ProjectManifest } from '../types.js';
+/**
+ * Phase 1 of the two-phase pipeline: collect observable dependency facts
+ * and assemble them into a self-contained ProjectManifest.
+ *
+ * The manifest captures facts at the chosen depth; it does not make
+ * any policy decisions — that is the analyzer's job.
+ */
+export declare function buildProjectManifest(options: CollectorOptions): Promise<ProjectManifest>;
+//# sourceMappingURL=build-project-manifest.d.ts.map

package/dist/collector/build-project-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-project-manifest.d.ts","sourceRoot":"","sources":["../../src/collector/build-project-manifest.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAqB,MAAM,aAAa,CAAC;AAQxF;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,CA2F1B"}

package/dist/collector/build-project-manifest.js

@@ -0,0 +1,82 @@
+import { resolve, dirname } from 'node:path';
+import { collectImports, scanFiles } from './collect-imports.js';
+import { traverseLocalModules } from './traverse-local-modules.js';
+import { parseSharedConfig } from './parse-shared-config.js';
+import { resolveVersions } from './resolve-versions.js';
+const DEFAULT_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
+/**
+ * Phase 1 of the two-phase pipeline: collect observable dependency facts
+ * and assemble them into a self-contained ProjectManifest.
+ *
+ * The manifest captures facts at the chosen depth; it does not make
+ * any policy decisions — that is the analyzer's job.
+ */
+export async function buildProjectManifest(options) {
+    const { name, sourceDirs, depth = 'local-graph', sharedConfig, kind = 'unknown', packageJsonPath = './package.json', extensions = DEFAULT_EXTENSIONS, ignore, tsconfigPath, workspacePackages, } = options;
+    const resolvedPkgJsonPath = resolve(packageJsonPath);
+    const root = dirname(resolvedPkgJsonPath);
+    // ── Step 1: scan files (for filesScanned count) ───────────────────────────
+    const allFiles = await scanFiles(sourceDirs, extensions);
+    // ── Step 2: collect package occurrences ───────────────────────────────────
+    let occurrences;
+    let effectiveDepth;
+    if (depth === 'local-graph') {
+        occurrences = await traverseLocalModules({ sourceDirs, extensions, ignore, tsconfigPath, workspacePackages });
+        effectiveDepth = 'local-graph';
+    }
+    else {
+        occurrences = await collectImports({ sourceDirs, extensions, ignore, workspacePackages });
+        effectiveDepth = 'direct';
+    }
+    // ── Step 3: aggregate occurrences into packageDetails ────────────────────
+    const byPackage = new Map();
+    for (const occ of occurrences) {
+        if (!byPackage.has(occ.package)) {
+            byPackage.set(occ.package, { files: new Set([occ.file]), via: occ.via });
+        }
+        else {
+            const entry = byPackage.get(occ.package);
+            entry.files.add(occ.file);
+            // Direct import takes precedence over reexport at the manifest level too
+            if (occ.via === 'direct')
+                entry.via = 'direct';
+        }
+    }
+    const packageDetails = Array.from(byPackage.entries()).map(([pkg, { files, via }]) => ({
+        package: pkg,
+        importCount: files.size,
+        files: [...files].sort(),
+        via,
+    }));
+    const directPackages = packageDetails
+        .filter((d) => d.via === 'direct')
+        .map((d) => d.package);
+    // resolvedPackages = all observed packages (direct + reexport)
+    const resolvedPackages = packageDetails.map((d) => d.package);
+    // ── Step 4: parse shared config ───────────────────────────────────────────
+    const sharedDeclared = parseSharedConfig(sharedConfig);
+    // ── Step 5: resolve versions ──────────────────────────────────────────────
+    const versions = await resolveVersions(resolvedPkgJsonPath);
+    // ── Assemble manifest ─────────────────────────────────────────────────────
+    return {
+        schemaVersion: 1,
+        generatedAt: new Date().toISOString(),
+        project: { name, root, kind },
+        source: {
+            depth: effectiveDepth,
+            sourceDirs,
+            filesScanned: allFiles.length,
+        },
+        usage: {
+            directPackages,
+            resolvedPackages,
+            packageDetails,
+        },
+        shared: {
+            declared: sharedDeclared,
+            source: 'explicit',
+        },
+        versions,
+    };
+}
+//# sourceMappingURL=build-project-manifest.js.map

package/dist/collector/build-project-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-project-manifest.js","sourceRoot":"","sources":["../../src/collector/build-project-manifest.ts"],"names":[],"mappings":"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"}