@archora/core 1.1.0

package/src/analyzer/bundle/analyzeBundle.ts

@@ -0,0 +1,147 @@
+// Map a parsed bundler stats payload onto the analyzer's module graph and
+// derive `bundle-bloat` issues from the result.
+//
+// Mapping strategy: chunk modules carry a `normalizedPath`; we look it up
+// against the set of `ModuleNode.id` values produced by the analyzer. Misses
+// are kept on the chunk for size accounting but don't surface as recs (we'd
+// flag them as "external" otherwise, which is noise on every chunk).
+
+import type { ModuleId, ModuleNode } from '../types';
+import {
+  DEFAULT_BUNDLE_THRESHOLDS,
+  type BundleBloat,
+  type BundleChunk,
+  type BundleChunkModule,
+  type BundleReport,
+  type BundleThresholds,
+  type ParsedBundleStats,
+} from './types';
+import { displayShortId } from '../displayId';
+
+export interface AnalyzeBundleInput {
+  modules: ModuleNode[];
+  stats: ParsedBundleStats;
+  thresholds?: Partial<BundleThresholds>;
+}
+
+export function analyzeBundle(input: AnalyzeBundleInput): BundleReport {
+  const thresholds: BundleThresholds = {
+    ...DEFAULT_BUNDLE_THRESHOLDS,
+    ...(input.thresholds ?? {}),
+  };
+  const moduleIds = new Set(input.modules.map((m) => m.id));
+
+  const chunks: BundleChunk[] = input.stats.chunks.map((c) => ({
+    ...c,
+    modules: c.modules.map((m) => attachModuleId(m, moduleIds)),
+  }));
+
+  const moduleToChunks: Record<ModuleId, string[]> = {};
+  for (const c of chunks) {
+    for (const m of c.modules) {
+      if (!m.moduleId) continue;
+      const arr = moduleToChunks[m.moduleId] ?? [];
+      if (!arr.includes(c.id)) arr.push(c.id);
+      moduleToChunks[m.moduleId] = arr;
+    }
+  }
+
+  const totalSize = chunks.reduce((acc, c) => acc + c.size, 0);
+  const bloat = detectBloat(chunks, moduleToChunks, thresholds);
+
+  return {
+    format: input.stats.format,
+    totalSize,
+    chunks,
+    moduleToChunks,
+    bloat,
+  };
+}
+
+function attachModuleId(m: BundleChunkModule, ids: Set<ModuleId>): BundleChunkModule {
+  // Direct hit first (cheap path; covers most webpack/vite output).
+  if (ids.has(m.normalizedPath)) {
+    return { ...m, moduleId: m.normalizedPath };
+  }
+  // Some bundlers emit paths without the leading `src/` segment; try both
+  // directions before giving up.
+  const stripped = m.normalizedPath.replace(/^src\//u, '');
+  if (ids.has(stripped)) return { ...m, moduleId: stripped };
+  const prefixed = `src/${m.normalizedPath}`;
+  if (ids.has(prefixed)) return { ...m, moduleId: prefixed };
+  return m;
+}
+
+function detectBloat(
+  chunks: BundleChunk[],
+  moduleToChunks: Record<ModuleId, string[]>,
+  thresholds: BundleThresholds,
+): BundleBloat[] {
+  const out: BundleBloat[] = [];
+  let serial = 0;
+
+  // 1. duplicate modules across chunks
+  for (const [moduleId, chunkIds] of Object.entries(moduleToChunks)) {
+    if (chunkIds.length < thresholds.duplicateMinChunks) continue;
+    const totalSize = chunks
+      .filter((c) => chunkIds.includes(c.id))
+      .reduce((acc, c) => {
+        const m = c.modules.find((x) => x.moduleId === moduleId);
+        return acc + (m?.size ?? 0);
+      }, 0);
+    out.push({
+      id: `bundle:dup:${serial++}:${moduleId}`,
+      kind: 'duplicate',
+      severity: chunkIds.length >= 4 ? 'high' : chunkIds.length >= 3 ? 'medium' : 'low',
+      message: `Module "${displayShortId(moduleId)}" is duplicated across ${chunkIds.length} chunks`,
+      modules: [moduleId],
+      chunks: chunkIds,
+      detail: { sizeBytes: totalSize, chunkCount: chunkIds.length },
+    });
+  }
+
+  // 2. heavy chunks
+  for (const c of chunks) {
+    if (c.size < thresholds.heavyChunkBytes) continue;
+    const ratio = c.size / thresholds.heavyChunkBytes;
+    out.push({
+      id: `bundle:heavy:${serial++}:${c.id}`,
+      kind: 'heavy-chunk',
+      severity: ratio >= 4 ? 'high' : ratio >= 2 ? 'medium' : 'low',
+      message: `Chunk "${c.name}" is ${formatBytes(c.size)} (limit ${formatBytes(thresholds.heavyChunkBytes)})`,
+      modules: c.modules.flatMap((m) => (m.moduleId ? [m.moduleId] : [])),
+      chunks: [c.id],
+      detail: { sizeBytes: c.size },
+    });
+  }
+
+  // 3. solo-hot module: a single internal module dominates its chunk
+  for (const c of chunks) {
+    if (c.size === 0 || c.modules.length === 0) continue;
+    const internal = c.modules.filter((m) => m.moduleId);
+    if (internal.length === 0) continue;
+    const top = [...internal].sort((a, b) => b.size - a.size)[0]!;
+    const share = top.size / c.size;
+    if (share < thresholds.soloHotShare) continue;
+    // Only flag when chunk is meaningfully large; a 12 KB chunk dominated by
+    // a single 11 KB module is just a normal small chunk.
+    if (c.size < thresholds.heavyChunkBytes / 2) continue;
+    out.push({
+      id: `bundle:solo:${serial++}:${c.id}`,
+      kind: 'solo-hot',
+      severity: c.size >= thresholds.heavyChunkBytes ? 'high' : 'medium',
+      message: `Module "${displayShortId(top.moduleId!)}" takes ${Math.round(share * 100)}% of chunk "${c.name}"`,
+      modules: [top.moduleId!],
+      chunks: [c.id],
+      detail: { sizeBytes: top.size, sharePercent: Math.round(share * 100) },
+    });
+  }
+
+  return out;
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(2)} MB`;
+}

package/src/analyzer/bundle/index.ts

@@ -0,0 +1,12 @@
+export { parseBundleStats, type ParseStatsOptions } from './parseStats';
+export { analyzeBundle, type AnalyzeBundleInput } from './analyzeBundle';
+export {
+  DEFAULT_BUNDLE_THRESHOLDS,
+  type BundleBloat,
+  type BundleBloatKind,
+  type BundleChunk,
+  type BundleChunkModule,
+  type BundleReport,
+  type BundleThresholds,
+  type ParsedBundleStats,
+} from './types';

package/src/analyzer/bundle/parseStats.ts

@@ -0,0 +1,152 @@
+// Parse two bundler stats formats into a single normalized shape:
+//
+//   1. Webpack `stats.json` (or `compilation.toJson()` output): top-level
+//      `{ chunks: [{ id, names, files, size, modules: [{ name, size }] }] }`.
+//   2. `rollup-plugin-visualizer` JSON template: `{ tree: { name, children } }`
+//      where the first level under `tree.children` is per-chunk and leaves
+//      have a `value` (gzip size) / `size` (raw size) field. Nested groups
+//      represent directories.
+//
+// Both are also produced by Vite (visualizer plugin) and Webpack respectively,
+// so users on Vite/Rollup/Webpack pipelines can feed us any of them.
+//
+// Path normalization: we strip query strings, leading `./`, and resolve
+// against the project root if the path is absolute. The result is a forward-
+// slash relative path that matches `ModuleNode.id` produced by the analyzer.
+
+import type { BundleChunk, BundleChunkModule, ParsedBundleStats } from './types';
+
+export interface ParseStatsOptions {
+  /** Project root path; used to relativize absolute module paths. */
+  rootPath: string;
+}
+
+export function parseBundleStats(raw: unknown, options: ParseStatsOptions): ParsedBundleStats {
+  if (!raw || typeof raw !== 'object') {
+    return { format: 'unknown', chunks: [] };
+  }
+  const r = raw as Record<string, unknown>;
+  if (Array.isArray(r['chunks'])) {
+    return parseWebpack(r['chunks'] as unknown[], options);
+  }
+  if (r['tree'] && typeof r['tree'] === 'object') {
+    return parseRollupVisualizer(r['tree'] as Record<string, unknown>, options);
+  }
+  return { format: 'unknown', chunks: [] };
+}
+
+// --- webpack ---------------------------------------------------------------
+
+function parseWebpack(rawChunks: unknown[], options: ParseStatsOptions): ParsedBundleStats {
+  const chunks: BundleChunk[] = [];
+  for (const c of rawChunks) {
+    if (!c || typeof c !== 'object') continue;
+    const cr = c as Record<string, unknown>;
+    const id = stringOrNumber(cr['id']);
+    if (id === null) continue;
+    const names = Array.isArray(cr['names'])
+      ? (cr['names'] as unknown[]).filter((x): x is string => typeof x === 'string')
+      : [];
+    const files = Array.isArray(cr['files'])
+      ? (cr['files'] as unknown[]).filter((x): x is string => typeof x === 'string')
+      : [];
+    const name = files[0] ?? names[0] ?? id;
+    const size = typeof cr['size'] === 'number' ? cr['size'] : 0;
+    const modules: BundleChunkModule[] = [];
+    if (Array.isArray(cr['modules'])) {
+      for (const m of cr['modules'] as unknown[]) {
+        if (!m || typeof m !== 'object') continue;
+        const mr = m as Record<string, unknown>;
+        const path = typeof mr['name'] === 'string' ? mr['name'] : null;
+        if (!path) continue;
+        const moduleSize = typeof mr['size'] === 'number' ? mr['size'] : 0;
+        modules.push(buildChunkModule(path, moduleSize, options));
+      }
+    }
+    chunks.push({ id, name, size, modules });
+  }
+  return { format: 'webpack', chunks };
+}
+
+// --- rollup-plugin-visualizer ---------------------------------------------
+
+interface VisualizerNode {
+  name?: unknown;
+  children?: unknown;
+  value?: unknown;
+  size?: unknown;
+}
+
+function parseRollupVisualizer(
+  tree: Record<string, unknown>,
+  options: ParseStatsOptions,
+): ParsedBundleStats {
+  const top = (tree['children'] ?? []) as unknown[];
+  if (!Array.isArray(top)) return { format: 'rollup-visualizer', chunks: [] };
+  const chunks: BundleChunk[] = [];
+  for (const node of top) {
+    if (!node || typeof node !== 'object') continue;
+    const n = node as VisualizerNode;
+    const name = typeof n.name === 'string' ? n.name : '<chunk>';
+    const leaves: { path: string; size: number }[] = [];
+    collectVisualizerLeaves(n, '', leaves);
+    if (leaves.length === 0) continue;
+    const modules = leaves.map((l) => buildChunkModule(l.path, l.size, options));
+    const size = leaves.reduce((acc, l) => acc + l.size, 0);
+    chunks.push({ id: name, name, size, modules });
+  }
+  return { format: 'rollup-visualizer', chunks };
+}
+
+function collectVisualizerLeaves(
+  node: VisualizerNode,
+  prefix: string,
+  out: { path: string; size: number }[],
+): void {
+  const name = typeof node.name === 'string' ? node.name : '';
+  const here = prefix && name ? `${prefix}/${name}` : prefix || name;
+  if (Array.isArray(node.children) && node.children.length > 0) {
+    for (const child of node.children as unknown[]) {
+      if (child && typeof child === 'object')
+        collectVisualizerLeaves(child as VisualizerNode, here, out);
+    }
+    return;
+  }
+  // Leaf: prefer `size` (raw bytes), fall back to `value`.
+  const size =
+    typeof node.size === 'number' ? node.size : typeof node.value === 'number' ? node.value : 0;
+  if (here) out.push({ path: here, size });
+}
+
+// --- shared helpers --------------------------------------------------------
+
+function buildChunkModule(
+  path: string,
+  size: number,
+  options: ParseStatsOptions,
+): BundleChunkModule {
+  const normalizedPath = normalizePath(path, options.rootPath);
+  return { rawPath: path, normalizedPath, size };
+}
+
+function normalizePath(input: string, rootPath: string): string {
+  // Strip query strings and webpack-style loader prefixes (e.g. `!!`).
+  let p = input.replace(/\?.*$/u, '');
+  const bang = p.lastIndexOf('!');
+  if (bang !== -1) p = p.slice(bang + 1);
+  p = p.replace(/\\/gu, '/');
+  if (p.startsWith('./')) p = p.slice(2);
+
+  const rootNorm = rootPath.replace(/\\/gu, '/').replace(/\/+$/u, '');
+  if (rootNorm && p.startsWith(`${rootNorm}/`)) p = p.slice(rootNorm.length + 1);
+
+  // Drop pnpm-style virtual prefixes that visualizer sometimes emits.
+  p = p.replace(/^\/+/u, '');
+  return p;
+}
+
+function stringOrNumber(v: unknown): string | null {
+  if (typeof v === 'string') return v;
+  if (typeof v === 'number') return String(v);
+  return null;
+}

package/src/analyzer/bundle/types.ts

@@ -0,0 +1,85 @@
+// Bundle-aware analysis.
+//
+// `BundleReport` is computed when the user supplies a parsed bundler stats
+// file (`AnalyzeOptions.bundleStats`). We never read disk here - the CLI is
+// responsible for loading the file and handing us a parsed object.
+
+import type { ModuleId } from '../types';
+
+/** Normalized chunk after parsing whatever stats format we got. */
+export interface BundleChunk {
+  /** Stable identifier from the source stats (chunk id, output filename, etc.). */
+  id: string;
+  /** Display name (output filename when available). */
+  name: string;
+  /** Total chunk size in bytes. */
+  size: number;
+  /** Modules attached to this chunk, after path normalization. */
+  modules: BundleChunkModule[];
+}
+
+export interface BundleChunkModule {
+  /** Module id matching `ModuleNode.id` when resolution succeeds. */
+  moduleId?: ModuleId;
+  /** Path as it appears in the stats file (relative or absolute). */
+  rawPath: string;
+  /** Path normalized relative to project root, forward slashes. */
+  normalizedPath: string;
+  /** Module size inside this chunk (bytes). */
+  size: number;
+}
+
+export type BundleBloatKind = 'duplicate' | 'heavy-chunk' | 'solo-hot';
+
+export interface BundleBloat {
+  /** Stable id for grouping/diffing. */
+  id: string;
+  kind: BundleBloatKind;
+  severity: 'high' | 'medium' | 'low';
+  /** One-line headline (rendered verbatim by CLI). */
+  message: string;
+  /** Module(s) implicated. */
+  modules: ModuleId[];
+  /** Chunk(s) involved (chunk.id values). */
+  chunks: string[];
+  /** Optional metric details for tooltips/CI output. */
+  detail?: {
+    sizeBytes?: number;
+    chunkCount?: number;
+    sharePercent?: number;
+  };
+}
+
+export interface BundleReport {
+  /** Source format we recognized. */
+  format: 'webpack' | 'rollup-visualizer' | 'unknown';
+  /** Total uncompressed size summed across chunks. */
+  totalSize: number;
+  chunks: BundleChunk[];
+  /** Map module id -> list of chunk ids it landed in. */
+  moduleToChunks: Record<ModuleId, string[]>;
+  /** Detected bundle-bloat issues (drives recommendations + UI). */
+  bloat: BundleBloat[];
+}
+
+/** User-tunable thresholds. Wired through `.archora.json -> bundle`. */
+export interface BundleThresholds {
+  /** Chunk size in bytes that triggers `heavy-chunk`. */
+  heavyChunkBytes: number;
+  /** Module appearing in >= N chunks triggers `duplicate`. */
+  duplicateMinChunks: number;
+  /** Module taking >= share of a heavy chunk triggers `solo-hot` (0..1). */
+  soloHotShare: number;
+}
+
+export const DEFAULT_BUNDLE_THRESHOLDS: BundleThresholds = {
+  heavyChunkBytes: 500_000,
+  duplicateMinChunks: 2,
+  soloHotShare: 0.8,
+};
+
+/** Parsed-but-not-yet-analyzed stats. Produced by the format parsers. */
+export interface ParsedBundleStats {
+  format: BundleReport['format'];
+  chunks: BundleChunk[];
+}

package/src/analyzer/classify.ts

@@ -0,0 +1,54 @@
+import type { ModuleKind, ParsedFile } from './types';
+
+// `.config.[ext]` is the catch-all that covers rollup/webpack/astro/svelte/
+// playwright/cypress/jest/babel/tsup/etc. without listing each one. The
+// explicit entries above it stay because they match flat names (`vite.config`)
+// or non-`.config` conventions (`.eslintrc.cjs`).
+const INFRA_PATTERNS = [
+  /\.d\.ts$/u,
+  /(^|\/)vite\.config\.[cm]?[jt]sx?$/u,
+  /(^|\/)vitest\.config\.[cm]?[jt]sx?$/u,
+  /(^|\/)eslint\.[a-z]+\.[cm]?[jt]sx?$/u,
+  /(^|\/)\.eslintrc\.[a-z]+$/u,
+  /(^|\/)postcss\.config\.[cm]?[jt]sx?$/u,
+  /(^|\/)tailwind\.config\.[cm]?[jt]sx?$/u,
+  /\.config\.[cm]?[jt]sx?$/u,
+];
+
+export function isInfra(relPath: string): boolean {
+  return INFRA_PATTERNS.some((p) => p.test(relPath));
+}
+
+// runtime-integration files (loaders/plugins/registries/...). kept in graph
+// but skipped by recommendations (they look like fanIn=0 leaves otherwise).
+const INTEGRATION_NAME_RE =
+  /(^|\/)([A-Za-z0-9]+)?(?:Loader|Plugin|Registry|Provider|Bootstrap)(?:\.[a-z]+)?(?:\.[jt]sx?|\.vue|\.svelte)$/u;
+
+export function classifyKind(parsed: ParsedFile, relPath: string): ModuleKind {
+  if (/(^|\/)(__tests__|tests?|spec|e2e)(\/|\.)/u.test(relPath)) return 'test';
+  if (/\.(test|spec)\.[cm]?[jt]sx?$/u.test(relPath)) return 'test';
+  if (/\.config\.[cm]?[jt]sx?$/u.test(relPath) || /(^|\/)config(\/|\.)/u.test(relPath)) {
+    return 'config';
+  }
+  if (/(^|\/)(styles?|theme|tokens)\//u.test(relPath) || /\.(css|scss|sass)$/u.test(relPath)) {
+    return 'style';
+  }
+  if (INTEGRATION_NAME_RE.test(relPath)) return 'integration';
+  if (parsed.language === 'vue' || parsed.language === 'svelte') return 'component';
+  if (parsed.hasDefineStore) return 'store';
+  if (/(^|\/)(api|openapi|graphql)(\/|\.)/u.test(relPath)) return 'api';
+  if (/(^|\/)(services?|clients?|repositories)(\/|\.)/u.test(relPath)) return 'service';
+  if (/(^|\/)(model|state)(\/|\.)/u.test(relPath)) return 'model';
+  if (/(^|\/)(schemas?|dto|types)(\/|\.)/u.test(relPath)) return 'schema';
+  if (
+    /(^|\/)composables\//u.test(relPath) ||
+    /(^|\/)use[A-Z][A-Za-z0-9]*\.[jt]sx?$/u.test(relPath)
+  ) {
+    return 'composable';
+  }
+  if (parsed.exports.some((n) => /^use[A-Z]/u.test(n))) return 'composable';
+  if (/(^|\/)router(\/|\.)/u.test(relPath)) return 'route';
+  if (/(^|\/)(utils|lib|helpers)(\/|\.)/u.test(relPath)) return 'util';
+  if (/(^|\/)(main|index|entry)\.[jt]sx?$/u.test(relPath)) return 'entry';
+  return 'module';
+}