hs = this.mapCriticalPaths(graph, flagged);

return {
  criticalConcentration: concentration,
  criticalPaths: paths,
  flaggedPackages: flagged
};

}

private parseLockfile(): Record<string, DependencyNode> { const raw = readFileSync(join(process.cwd(), this.lockfilePath), 'utf-8'); const lockfile = JSON.parse(raw); return lockfile.packages || {}; }

private deduplicatePackages(graph: Record<string, DependencyNode>): string[] { const names = new Set<string>(); for (const key of Object.keys(graph)) { if (key.startsWith('node_modules/')) { const parts = key.split('node_modules/'); const packageName = parts[parts.length - 1]; names.add(packageName); } } return Array.from(names); }

private async fetchRegistryData(packages: string[]): Promise<RegistryMetadata[]> { const results: RegistryMetadata[] = []; for (const pkg of packages) { try { const res = await fetch(https://registry.npmjs.org/${pkg}); if (!res.ok) continue; const data = await res.json();

    const latest = data['dist-tags']?.latest || Object.keys(data.versions).pop();
    const versionData = data.versions[latest];
    
    results.push({
      name: pkg,
      weeklyDownloads: await this.getWeeklyDownloads(pkg),
      publisher: versionData._npmUser?.name || 'unknown',
      lastRelease: versionData.time || new Date().toISOString(),
      hasTrustedPublishing: versionData.publishConfig?.access === 'public' && 
                            versionData._npmVersion?.includes('trusted') || false
    });
  } catch {
    continue;
  }
}
return results;

}

private async getWeeklyDownloads(pkg: string): Promise<number> { const res = await fetch(https://api.npmjs.org/downloads/point/last-week/${pkg}); const data = await res.json(); return data.downloads || 0; }

private isCritical(meta: RegistryMetadata): boolean { const meetsVolume = meta.weeklyDownloads > this.DOWNLOAD_THRESHOLD; const isSolePublisher = true; // Simplified for example; real impl checks maintainer array const notMitigated = !meta.hasTrustedPublishing; return meetsVolume && isSolePublisher && notMitigated; }

private mapCriticalPaths( graph: Record<string, DependencyNode>, flagged: RegistryMetadata[] ): Map<string, string[]> { const paths = new Map<string, string[]>(); const flaggedNames = new Set(flagged.map(f => f.name));

for (const [key, node] of Object.entries(graph)) {
  if (key.startsWith('node_modules/')) {
    const directDeps = Object.keys(node.dependencies || {});
    const matches = directDeps.filter(dep => flaggedNames.has(dep));
    if (matches.length > 0) {
      const directName = key.split('node_modules/').pop() || 'root';
      paths.set(directName, matches);
    }
  }
}
return paths;

} }

export { TransitiveRiskAnalyzer };

### Architecture Decisions & Rationale

- **Lockfile over `node_modules`**: Parsing `package-lock.json` guarantees deterministic results and avoids scanning symlinked or hoisted duplicates. It reflects exactly what will be installed in production.
- **Registry API over local cache**: Publisher metadata and download telemetry are not stored locally. Querying the registry ensures you evaluate current ecosystem state, not stale local snapshots.
- **Threshold at 10M downloads**: This balances signal-to-noise. Packages below this threshold rarely represent systemic blast radius. The number is configurable per organizational risk tolerance.
- **OIDC/Trusted Publishing exclusion**: Packages using npm Trusted Publishing or OIDC workflows decouple publish access from personal tokens. Excluding them from critical flags prevents false positives and rewards secure publishing practices.
- **Path mapping over flat listing**: Knowing which direct dependency pulls in a critical transitive package enables targeted remediation. You cannot drop `express`, but you can evaluate whether `axios`'s transitive footprint justifies switching to native `fetch` or an alternative HTTP client.

## Pitfall Guide

1. **Treating Staleness as Safety**
   Packages with no releases in 12+ months are often assumed stable. In concentration analysis, staleness combined with high download volume increases risk. A dormant package with millions of weekly downloads is a high-value target for credential compromise because maintainers are less likely to notice anomalous publish activity.
   *Fix:* Flag packages with >12 months since last release as WARN, regardless of CVE status.

2. **Ignoring Lockfile Deduplication**
   npm and pnpm hoist dependencies, creating multiple `node_modules` paths for the same package. Counting each path separately inflates concentration metrics.
   *Fix:* Extract unique package names before querying registry data. Aggregate by canonical name, not by filesystem path.

3. **Overlooking Trusted Publishing Mitigations**
   Packages that migrated to npm Trusted Publishing or OIDC workflows no longer rely on personal access tokens. Flagging them as critical misrepresents actual risk.
   *Fix:* Check `publishConfig` and registry metadata for trusted publishing flags. Exclude OIDC-enabled packages from critical concentration sums.

4. **Focusing Only on Depth-1 Dependencies**
   Direct dependencies rarely carry the highest concentration. The risk compounds in transitive layers where utility packages aggregate massive download volumes under single publishers.
   *Fix:* Traverse to depth 2 and beyond. Most critical concentration hides in the second or third transitive layer.

5. **Assuming Download Volume Equals Quality**
   High weekly downloads indicate popularity, not security posture. In concentration analysis, volume measures blast radius, not trustworthiness.
   *Fix:* Treat download metrics as exposure indicators, not quality signals. Pair concentration data with publisher activity and release cadence.

6. **Hardcoding Thresholds Without Context**
   A 10M download threshold works for enterprise stacks but may be too aggressive for internal tooling or low-traffic services.
   *Fix:* Make thresholds configurable. Allow teams to adjust based on deployment scale, compliance requirements, and risk appetite.

7. **Running Scans Infrequently**
   Publisher metadata changes. Packages migrate to trusted publishing. New transitive dependencies enter the tree. A one-time scan provides a snapshot, not continuous assurance.
   *Fix:* Integrate into CI pipelines. Schedule weekly or per-PR scans. Cache registry responses to avoid rate limits.

## Production Bundle

### Action Checklist
- [ ] Integrate concentration analyzer into CI pipeline as a pre-merge gate
- [ ] Configure download threshold and staleness window per project risk profile
- [ ] Enable OIDC/Trusted Publishing exclusion to reduce false positives
- [ ] Map critical paths to identify which direct dependencies pull high-risk transitive packages
- [ ] Establish remediation playbook: vendor, pin, replace, or formally accept risk
- [ ] Cache registry API responses to prevent rate limiting during large scans
- [ ] Schedule periodic re-scans to capture publisher metadata changes
- [ ] Document concentration baselines for compliance and audit trails

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| High-concentration transitive dep in public API | Replace or vendor the dependency | Blast radius affects external users; credential compromise could cause widespread outage | Medium (refactor time) |
| Low-concentration internal tooling | Accept risk with explicit documentation | Internal exposure limited; remediation cost outweighs potential impact | Low (documentation only) |
| Package migrated to Trusted Publishing | Exclude from critical flags | OIDC decouples publish access from personal tokens; structural risk reduced | None |
| Stale package with >50M weekly downloads | Pin to known-good version + monitor publisher | High volume + inactivity = elevated compromise risk; pinning prevents automatic updates | Low-Medium (monitoring overhead) |
| Monorepo with shared transitive deps | Run deduplicated scan at workspace root | Prevents double-counting; provides accurate ecosystem-wide concentration | Low (CI config adjustment) |

### Configuration Template

```yaml
# concentration-scan.config.yaml
thresholds:
  weekly_downloads: 10000000
  staleness_months: 12

mitigations:
  exclude_trusted_publishing: true
  exclude_oidc_workflows: true

output:
  format: json
  path: ./reports/concentration-report.json
  include_critical_paths: true

cache:
  enabled: true
  ttl_hours: 24
  storage_path: ./.cache/registry-metadata

ci:
  fail_on_critical: true
  warn_on_stale: true
  max_scan_duration_seconds: 300

Quick Start Guide

1. Install the analyzer package or clone the TypeScript implementation into your repository.
2. Place the configuration template at the root of your project and adjust thresholds to match your risk tolerance.
3. Run npx concentration-scan --lockfile package-lock.json to generate the initial report.
4. Review the critical_paths output to identify which direct dependencies pull high-concentration transitive packages.
5. Integrate the scan into your CI pipeline using the provided configuration template. Set fail_on_critical: true to block merges that introduce unmitigated concentration risk.