@archora/core 1.1.0

package/src/analyzer/contracts.ts

@@ -0,0 +1,265 @@
+// Architectural contracts engine.
+//
+// Compiles user-defined boundary, budget and api-stability rules from
+// `.archora.json -> contracts` into a list of `ContractViolation`s after a
+// scan completes. The engine is *purely structural* - it operates on the
+// already-built modules/edges/cycles/metrics tuple, no I/O, no parsing.
+//
+// Glob matching reuses the `ignore` package (same dialect as `layerOverrides`
+// and `discover.extraIgnoreGlobs`), so users get a single mental model for
+// every globbed field in our config.
+
+import ignore, { type Ignore } from 'ignore';
+
+import type { BoundaryRule, BudgetRule, ContractsConfig } from '../config/frontScopeConfig';
+import type { Cycle, DependencyEdge, ModuleId, ModuleMetrics, ModuleNode } from './types';
+
+export interface ContractViolation {
+  /** Stable id for grouping/diffing. Format: `<rule-kind>:<rule-name>:<idx>`. */
+  id: string;
+  /** Which kind of contract was violated. `api-stability` is only a stub now. */
+  kind: 'boundary' | 'budget' | 'api-stability' | 'rsc-leak';
+  ruleName: string;
+  severity: 'error' | 'warning';
+  /** Human-readable headline (CLI/UI use this verbatim). */
+  message: string;
+  /** Free-form `description` echoed from the rule, if present. */
+  description?: string;
+  /**
+   * Module(s) that triggered the violation. For boundary rules these are the
+   * `from` and `to` of the offending edge; for budget rules - the offending
+   * module(s).
+   */
+  modules: ModuleId[];
+  /** Set for boundary violations: identity of the offending edge. */
+  edge?: { from: ModuleId; to: ModuleId; specifier: string };
+  /** Numeric details for budget violations (`metric=value vs limit`). */
+  detail?: {
+    metric: 'fanIn' | 'fanOut' | 'loc' | 'cycles';
+    value: number;
+    limit: number;
+  };
+}
+
+export interface CheckContractsInput {
+  modules: ModuleNode[];
+  edges: DependencyEdge[];
+  metrics: Record<ModuleId, ModuleMetrics>;
+  cycles: Cycle[];
+  contracts?: ContractsConfig;
+}
+
+/**
+ * Run every configured contract rule against a finished scan. Returns an
+ * empty array when no contracts are configured.
+ */
+export function checkContracts(input: CheckContractsInput): ContractViolation[] {
+  const cfg = input.contracts;
+  if (!cfg) return [];
+  const out: ContractViolation[] = [];
+
+  if (cfg.boundaries) {
+    for (const rule of cfg.boundaries) out.push(...evalBoundary(rule, input));
+  }
+  if (cfg.budgets) {
+    for (const rule of cfg.budgets) out.push(...evalBudget(rule, input));
+  }
+  // api-stability: schema only, full diff lives in 6.4. We surface a single
+  // informational violation per rule so users see the policy is recognized.
+  // Skipped here to avoid noise - revisit when 6.4 lands.
+
+  return out;
+}
+
+// --- Boundary ----------------------------------------------------------------
+
+function evalBoundary(rule: BoundaryRule, input: CheckContractsInput): ContractViolation[] {
+  const fromMatcher = makeMatcher(rule.from);
+  const toMatcher = makeMatcher(rule.to);
+  const exceptMatcher = rule.except && rule.except.length > 0 ? makeMatcher(rule.except) : null;
+  if (!fromMatcher || !toMatcher) return [];
+  const severity = rule.severity ?? 'error';
+  // crossInstance: extract the segment matched by the first `*` (single-star)
+  // wildcard in each pattern. Edges where these segments are equal are
+  // considered same-instance (e.g. both modules under `features/auth/...`)
+  // and skipped. We only support the symmetric case (same wildcard depth in
+  // `from` and `to`) - asymmetric users can construct patterns explicitly.
+  const crossDepth = rule.crossInstance ? wildcardDepth(rule.from, rule.to) : -1;
+  const out: ContractViolation[] = [];
+  let idx = 0;
+
+  for (const e of input.edges) {
+    if (!e.resolved) continue;
+    // type-only imports don't carry runtime semantics; treating them as
+    // boundary violations would force users to either suppress with `except`
+    // or thread `import type` everywhere. We exclude them - mirrors how the
+    // built-in layer-violation check treats them.
+    if (e.kind === 'type-only') continue;
+    if (e.from === e.to) continue; // self-imports already produce a warning
+    if (!fromMatcher.ignores(e.from)) continue;
+
+    if (crossDepth >= 0 && segmentAt(e.from, crossDepth) === segmentAt(e.to, crossDepth)) {
+      continue;
+    }
+
+    const targetMatches = toMatcher.ignores(e.to);
+    const isException = exceptMatcher ? exceptMatcher.ignores(e.to) : false;
+
+    let trips = false;
+    if (rule.mode === 'must-not') {
+      // Forbidden edge: target matches AND is not in the whitelist.
+      trips = targetMatches && !isException;
+    } else {
+      // can-only: any edge from a `from`-module that DOESN'T land on `to` (or
+      // an exception) is forbidden. Edges that stay within `from`'s own glob
+      // are allowed - keeps internal refactors free.
+      const insideFromGlob = fromMatcher.ignores(e.to);
+      trips = !targetMatches && !isException && !insideFromGlob;
+    }
+    if (!trips) continue;
+
+    out.push({
+      id: `boundary:${rule.name}:${idx++}`,
+      kind: 'boundary',
+      ruleName: rule.name,
+      severity,
+      message:
+        rule.mode === 'must-not'
+          ? `${shortId(e.from)} must not import ${shortId(e.to)} (rule "${rule.name}")`
+          : `${shortId(e.from)} can only import ${describeTo(rule)}, but imports ${shortId(e.to)} (rule "${rule.name}")`,
+      ...(rule.description ? { description: rule.description } : {}),
+      modules: [e.from, e.to],
+      edge: { from: e.from, to: e.to, specifier: e.specifier },
+    });
+  }
+  return out;
+}
+
+function describeTo(rule: BoundaryRule): string {
+  return rule.except && rule.except.length > 0
+    ? `${rule.to} (except ${rule.except.length} whitelisted)`
+    : rule.to;
+}
+
+// --- Budget ------------------------------------------------------------------
+
+function evalBudget(rule: BudgetRule, input: CheckContractsInput): ContractViolation[] {
+  const matcher = makeMatcher(rule.module);
+  if (!matcher) return [];
+  const severity = rule.severity ?? 'error';
+  const out: ContractViolation[] = [];
+  let idx = 0;
+
+  for (const m of input.modules) {
+    if (!matcher.ignores(m.id)) continue;
+    const mt = input.metrics[m.id];
+    if (mt === undefined) continue;
+    if (rule.maxFanIn !== undefined && mt.fanIn > rule.maxFanIn) {
+      out.push(budget(rule, severity, idx++, m.id, 'fanIn', mt.fanIn, rule.maxFanIn));
+    }
+    if (rule.maxFanOut !== undefined && mt.fanOut > rule.maxFanOut) {
+      out.push(budget(rule, severity, idx++, m.id, 'fanOut', mt.fanOut, rule.maxFanOut));
+    }
+    if (rule.maxLoc !== undefined && m.loc > rule.maxLoc) {
+      out.push(budget(rule, severity, idx++, m.id, 'loc', m.loc, rule.maxLoc));
+    }
+  }
+
+  // Cycles: aggregate. A single budget breach is "this glob owns >N cycles
+  // (any cycle that touches at least one module under the glob)". We emit a
+  // single violation pointing at the offending modules.
+  if (rule.maxCycles !== undefined) {
+    const matched = input.cycles.filter((c) => c.modules.some((id) => matcher.ignores(id)));
+    if (matched.length > rule.maxCycles) {
+      const touched = unique(matched.flatMap((c) => c.modules.filter((id) => matcher.ignores(id))));
+      out.push({
+        id: `budget:${rule.name}:${idx++}`,
+        kind: 'budget',
+        ruleName: rule.name,
+        severity,
+        message: `${matched.length} cycle(s) touching "${rule.module}" exceed limit of ${rule.maxCycles} (rule "${rule.name}")`,
+        ...(rule.description ? { description: rule.description } : {}),
+        modules: touched,
+        detail: { metric: 'cycles', value: matched.length, limit: rule.maxCycles },
+      });
+    }
+  }
+  return out;
+}
+
+function budget(
+  rule: BudgetRule,
+  severity: 'error' | 'warning',
+  idx: number,
+  moduleId: ModuleId,
+  metric: 'fanIn' | 'fanOut' | 'loc',
+  value: number,
+  limit: number,
+): ContractViolation {
+  return {
+    id: `budget:${rule.name}:${idx}`,
+    kind: 'budget',
+    ruleName: rule.name,
+    severity,
+    message: `${shortId(moduleId)} ${metric}=${value} exceeds budget ${limit} (rule "${rule.name}")`,
+    ...(rule.description ? { description: rule.description } : {}),
+    modules: [moduleId],
+    detail: { metric, value, limit },
+  };
+}
+
+// --- Helpers -----------------------------------------------------------------
+
+/**
+ * Find the path-segment depth of the first single-star (`*`, not `**`)
+ * wildcard, only when both patterns share the same depth. Returns -1 when
+ * patterns differ structurally - the caller falls back to plain matching.
+ */
+function wildcardDepth(fromPattern: string, toPattern: string): number {
+  const fa = singleStarDepth(fromPattern);
+  const fb = singleStarDepth(toPattern);
+  if (fa === -1 || fb === -1) return -1;
+  return fa === fb ? fa : -1;
+}
+
+function singleStarDepth(pattern: string): number {
+  const segs = pattern.split('/');
+  for (let i = 0; i < segs.length; i++) {
+    if (segs[i] === '*') return i;
+  }
+  return -1;
+}
+
+function segmentAt(id: string, depth: number): string | undefined {
+  return id.split('/')[depth];
+}
+
+function makeMatcher(pattern: string | string[]): Ignore | null {
+  try {
+    const ig = ignore();
+    ig.add(pattern);
+    return ig;
+  } catch {
+    return null;
+  }
+}
+
+function shortId(moduleId: ModuleId): string {
+  // Match the displayShortId style without pulling its full implementation
+  // (which depends on the existing module list). The full path stays in
+  // `modules[]` for consumers that need it.
+  const segs = moduleId.split('/');
+  if (segs.length <= 3) return moduleId;
+  return `…/${segs.slice(-3).join('/')}`;
+}
+
+function unique<T>(arr: readonly T[]): T[] {
+  const seen = new Set<T>();
+  const out: T[] = [];
+  for (const x of arr) {
+    if (seen.has(x)) continue;
+    seen.add(x);
+    out.push(x);
+  }
+  return out;
+}

package/src/analyzer/cyclePatterns.ts

@@ -0,0 +1,138 @@
+import type { DependencyEdge, ModuleId } from './types';
+import { type EdgeKey, parseEdgeKey } from './feedbackArcSet';
+
+/**
+ * Architectural patterns detected on the feedback arc set of a SCC. The label
+ * dictates the action advice shown in the UI - each pattern maps to a
+ * different idiom ("use useRouter()", "import sibling directly", ...).
+ *
+ * Order of evaluation is fixed: barrel-cycle is checked before hub-feedback,
+ * so a barrel-import that also looks like a feedback hub still gets the
+ * sibling-direct advice (the more specific fix).
+ */
+export type CyclePattern =
+  | { kind: 'mutual-pair'; a: ModuleId; b: ModuleId }
+  | { kind: 'barrel-cycle'; barrel: ModuleId; sibling: ModuleId }
+  | {
+      kind: 'hub-feedback';
+      hub: ModuleId;
+      incomingCount: number;
+      valueImports: number;
+    }
+  | { kind: 'long-chain'; length: number; bridge: EdgeKey }
+  | { kind: 'mixed' };
+
+const HUB_THRESHOLD = 0.7;
+const LONG_CHAIN_MIN = 8;
+const LONG_CHAIN_MAX_FEEDBACK = 2;
+
+/**
+ * Pattern-match a SCC by its FAS feedback edges.
+ *
+ * Inputs:
+ *  - scc: module ids in the SCC
+ *  - feedback: result of `feedbackArcSet`
+ *  - internalEdges: SCC-internal edges (deduped); used to count value vs
+ *    type-only imports per hub
+ */
+export function classifyCyclePattern(args: {
+  scc: ModuleId[];
+  internalEdges: DependencyEdge[];
+  feedback: Set<EdgeKey>;
+}): CyclePattern {
+  const { scc, internalEdges, feedback } = args;
+  const fbList = [...feedback].map(parseEdgeKey);
+
+  // 1. mutual-pair: SCC of exactly 2 with both directed edges. The FAS will
+  //    only flag one as feedback, but the architecture issue is the pair.
+  if (scc.length === 2) {
+    const [a, b] = [...scc].sort();
+    const hasAB = internalEdges.some((e) => e.from === a && e.to === b);
+    const hasBA = internalEdges.some((e) => e.from === b && e.to === a);
+    if (hasAB && hasBA) return { kind: 'mutual-pair', a: a!, b: b! };
+  }
+
+  // 2. barrel-cycle: SCC contains a single `index.*` module and at least one
+  //    sibling that participates in the SCC. The canonical fix is to import
+  //    the sibling directly bypassing the barrel; the FAS-picked feedback
+  //    direction is a tie-breaker artefact and doesn't change the diagnosis.
+  if (fbList.length <= 2) {
+    const barrels = scc.filter(isBarrel);
+    if (barrels.length === 1) {
+      const barrel = barrels[0]!;
+      const dir = parentDir(barrel);
+      const sibling = scc.find((m) => m !== barrel && parentDir(m) === dir);
+      if (sibling) return { kind: 'barrel-cycle', barrel, sibling };
+    }
+  }
+
+  // 3. hub-feedback: ≥70% of feedback edges point into the same target.
+  //    Counts the number of value imports (anything not type-only) - the
+  //    user advice ("use useRouter() / DI / split instance") only makes
+  //    sense for value imports.
+  if (fbList.length >= 2) {
+    const targets = new Map<ModuleId, number>();
+    for (const f of fbList) targets.set(f.to, (targets.get(f.to) ?? 0) + 1);
+    let bestHub: ModuleId | null = null;
+    let bestCount = 0;
+    for (const [t, n] of targets) {
+      if (n > bestCount) {
+        bestCount = n;
+        bestHub = t;
+      }
+    }
+    if (bestHub !== null && bestCount / fbList.length >= HUB_THRESHOLD) {
+      const valueImports = countValueImportsInto(bestHub, internalEdges, feedback);
+      return {
+        kind: 'hub-feedback',
+        hub: bestHub,
+        incomingCount: bestCount,
+        valueImports,
+      };
+    }
+  }
+
+  // 4. long-chain: large SCC closed by 1-2 feedback edges. The "fix" is
+  //    usually a misplaced shared type, not a re-architecture.
+  if (
+    scc.length > LONG_CHAIN_MIN &&
+    fbList.length <= LONG_CHAIN_MAX_FEEDBACK &&
+    fbList.length > 0
+  ) {
+    const bridge = fbList[0]!;
+    return {
+      kind: 'long-chain',
+      length: scc.length,
+      bridge: `${bridge.from}\u0001${bridge.to}`,
+    };
+  }
+
+  return { kind: 'mixed' };
+}
+
+function isBarrel(id: ModuleId): boolean {
+  const i = id.lastIndexOf('/');
+  const base = i === -1 ? id : id.slice(i + 1);
+  return /^index\.(ts|tsx|js|jsx|mjs|cjs|vue|svelte)$/.test(base);
+}
+
+function parentDir(id: ModuleId): string {
+  const i = id.lastIndexOf('/');
+  return i === -1 ? '' : id.slice(0, i);
+}
+
+function countValueImportsInto(
+  target: ModuleId,
+  internalEdges: DependencyEdge[],
+  feedback: Set<EdgeKey>,
+): number {
+  let n = 0;
+  for (const e of internalEdges) {
+    if (e.to !== target) continue;
+    if (e.kind === 'type-only') continue;
+    // count only feedback edges into this hub
+    if (!feedback.has(`${e.from}\u0001${e.to}`)) continue;
+    n++;
+  }
+  return n;
+}

package/src/analyzer/cycles.ts

@@ -0,0 +1,98 @@
+import type { Cycle, DependencyEdge, ModuleId, ModuleNode } from './types';
+
+export function detectCycles(modules: ModuleNode[], edges: DependencyEdge[]): Cycle[] {
+  const adj = buildAdjacency(modules, edges);
+  const ids = modules.map((m) => m.id);
+
+  const indices = new Map<ModuleId, number>();
+  const lowlinks = new Map<ModuleId, number>();
+  const onStack = new Set<ModuleId>();
+  const stack: ModuleId[] = [];
+  let nextIndex = 0;
+  const sccs: ModuleId[][] = [];
+
+  const strongconnect = (v: ModuleId): void => {
+    indices.set(v, nextIndex);
+    lowlinks.set(v, nextIndex);
+    nextIndex++;
+    stack.push(v);
+    onStack.add(v);
+
+    for (const w of adj.get(v) ?? []) {
+      if (!indices.has(w)) {
+        strongconnect(w);
+        lowlinks.set(v, Math.min(lowlinks.get(v) ?? 0, lowlinks.get(w) ?? 0));
+      } else if (onStack.has(w)) {
+        lowlinks.set(v, Math.min(lowlinks.get(v) ?? 0, indices.get(w) ?? 0));
+      }
+    }
+
+    if (lowlinks.get(v) === indices.get(v)) {
+      const component: ModuleId[] = [];
+      let w: ModuleId | undefined;
+      do {
+        w = stack.pop();
+        if (w === undefined) break;
+        onStack.delete(w);
+        component.push(w);
+      } while (w !== v);
+      sccs.push(component);
+    }
+  };
+
+  for (const id of ids) {
+    if (!indices.has(id)) strongconnect(id);
+  }
+
+  const cycles: Cycle[] = [];
+  for (const comp of sccs) {
+    if (comp.length === 1) {
+      const only = comp[0];
+      if (only !== undefined && (adj.get(only) ?? []).includes(only)) {
+        cycles.push({
+          id: cycleId(comp),
+          modules: comp,
+          length: 1,
+          severity: 'direct',
+        });
+      }
+      continue;
+    }
+    cycles.push({
+      id: cycleId(comp),
+      modules: [...comp].sort(),
+      length: comp.length,
+      severity: comp.length === 2 ? 'direct' : 'indirect',
+    });
+  }
+  cycles.sort((a, b) => b.length - a.length || a.id.localeCompare(b.id));
+  return cycles;
+}
+
+function buildAdjacency(modules: ModuleNode[], edges: DependencyEdge[]): Map<ModuleId, ModuleId[]> {
+  const adj = new Map<ModuleId, ModuleId[]>();
+  for (const m of modules) adj.set(m.id, []);
+  for (const e of edges) {
+    if (e.kind === 'type-only') continue;
+    const list = adj.get(e.from);
+    if (list) list.push(e.to);
+  }
+  return adj;
+}
+
+// Stable, short, content-addressed cycle id derived from the sorted member
+// list. The concrete modules stay on `cycle.modules` for display. The older
+// `modules.join('|')` form produced 2kB+ strings on dense indirect SCCs and
+// blew up fix-plan ids, baseline diffs and report headers.
+function cycleId(modules: ModuleId[]): string {
+  return `cycle:${fnv1a32([...modules].sort().join('\u0001'))}`;
+}
+
+function fnv1a32(input: string): string {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(16).padStart(8, '0');
+}

package/src/analyzer/detect.ts

@@ -0,0 +1,34 @@
+import type { FileSource } from './fileSource';
+
+export type Framework = 'vue' | 'react' | 'svelte' | 'nuxt' | 'next' | 'generic' | 'unknown';
+
+export interface DetectResult {
+  framework: Framework;
+  signals: Framework[];
+}
+
+const PRIORITY: Framework[] = ['nuxt', 'next', 'svelte', 'vue', 'react'];
+
+export async function detectFramework(source: FileSource): Promise<DetectResult> {
+  let deps: Record<string, string>;
+  try {
+    const raw = await source.read('package.json');
+    const pkg = JSON.parse(raw) as {
+      dependencies?: Record<string, string>;
+      devDependencies?: Record<string, string>;
+    };
+    deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+  } catch {
+    return { framework: 'generic', signals: [] };
+  }
+
+  const signals: Framework[] = [];
+  if ('nuxt' in deps || 'nuxt3' in deps) signals.push('nuxt');
+  if ('next' in deps) signals.push('next');
+  if ('svelte' in deps) signals.push('svelte');
+  if ('vue' in deps) signals.push('vue');
+  if ('react' in deps) signals.push('react');
+
+  const framework = PRIORITY.find((f) => signals.includes(f)) ?? 'generic';
+  return { framework, signals };
+}

package/src/analyzer/discover.ts

@@ -0,0 +1,131 @@
+import type { FileSource } from './fileSource';
+
+export interface DiscoverOptions {
+  excludeTests?: boolean;
+  excludeStories?: boolean;
+  excludeDeclarations?: boolean;
+  excludeConfigs?: boolean;
+  /** Glob patterns to skip (`.archora.json#ignore`). Supports `**`/`*`/`?`. */
+  extraIgnoreGlobs?: string[];
+}
+
+export interface DiscoverResult {
+  files: string[];
+  byExt: Record<string, number>;
+  skipped: number;
+}
+
+const DEFAULTS: Required<DiscoverOptions> = {
+  excludeTests: true,
+  excludeStories: true,
+  excludeDeclarations: true,
+  excludeConfigs: true,
+  extraIgnoreGlobs: [],
+};
+
+const TEST_RE = /(^|\/)__(tests|mocks|snapshots)__\/|\.(test|spec)\.[cm]?[jt]sx?$/u;
+const STORIES_RE = /\.stories\.([cm]?[jt]sx?|vue)$/u;
+const DTS_RE = /\.d\.[cm]?ts$/u;
+const CONFIG_RE =
+  /(^|\/)(vite|vitest|rollup|webpack|esbuild|jest|cypress|playwright|tailwind|postcss|svgo|babel|eslint|prettier|stylelint|tsup|rolldown|nuxt|astro)\.config\.[cm]?[jt]sx?$/u;
+const TEST_DIR_RE = /(^|\/)(cypress|playwright|e2e|\.storybook)\//u;
+
+export const ALWAYS_SKIP_DIRS: ReadonlySet<string> = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  'out',
+  '.cache',
+  '.next',
+  '.nuxt',
+  'coverage',
+  '.turbo',
+  '.svelte-kit',
+  '.output',
+  '.idea',
+  '.vscode',
+]);
+
+export const TEST_LIKE_DIRS: ReadonlySet<string> = new Set([
+  '__tests__',
+  '__mocks__',
+  '__snapshots__',
+  'cypress',
+  'playwright',
+  '.storybook',
+]);
+
+export async function discoverFiles(
+  source: FileSource,
+  options: DiscoverOptions = {},
+): Promise<DiscoverResult> {
+  const opts = { ...DEFAULTS, ...options };
+  const extraRegexes = opts.extraIgnoreGlobs.map(globToRegex);
+  const all = await source.list();
+  const files: string[] = [];
+  const byExt: Record<string, number> = {};
+  let skipped = 0;
+
+  for (const f of all) {
+    if (shouldSkip(f, opts, extraRegexes)) {
+      skipped++;
+      continue;
+    }
+    files.push(f);
+    const ext = extOf(f);
+    byExt[ext] = (byExt[ext] ?? 0) + 1;
+  }
+
+  return { files, byExt, skipped };
+}
+
+function shouldSkip(rel: string, opts: Required<DiscoverOptions>, extra: RegExp[]): boolean {
+  if (opts.excludeDeclarations && DTS_RE.test(rel)) return true;
+  if (opts.excludeTests && (TEST_RE.test(rel) || TEST_DIR_RE.test(rel))) return true;
+  if (opts.excludeStories && STORIES_RE.test(rel)) return true;
+  if (opts.excludeConfigs && CONFIG_RE.test(rel)) return true;
+  if (extra.length > 0) {
+    const norm = rel.replace(/^\.\//u, '');
+    for (const re of extra) if (re.test(norm)) return true;
+  }
+  return false;
+}
+
+export function compileGlob(glob: string): RegExp {
+  return globToRegex(glob);
+}
+
+function globToRegex(glob: string): RegExp {
+  const trimmed = glob.replace(/^\.\//u, '');
+  let re = '';
+  for (let i = 0; i < trimmed.length; i++) {
+    const c = trimmed[i]!;
+    if (c === '*') {
+      const next = trimmed[i + 1];
+      if (next === '*') {
+        if (trimmed[i + 2] === '/') {
+          re += '(?:.*/)?';
+          i += 2;
+        } else {
+          re += '.*';
+          i += 1;
+        }
+      } else {
+        re += '[^/]*';
+      }
+    } else if (c === '?') {
+      re += '[^/]';
+    } else if (/[.+^$(){}|\\[\]]/u.test(c)) {
+      re += `\\${c}`;
+    } else {
+      re += c;
+    }
+  }
+  return new RegExp(`^${re}$`);
+}
+
+function extOf(p: string): string {
+  const i = p.lastIndexOf('.');
+  return i === -1 ? '' : p.slice(i).toLowerCase();
+}

package/src/analyzer/displayId.ts

@@ -0,0 +1,21 @@
+import type { ModuleId } from './types';
+
+/**
+ * Filenames that can't stand on their own - dozens of `index.ts` /
+ * `+page.svelte` files in a SvelteKit project, several `main.ts` in a
+ * monorepo. For these we prepend the parent directory so the user can tell
+ * which file we mean. Specific names (`UserService.ts`, `cn.ts`, ...) stay
+ * bare to keep insight titles compact.
+ */
+const AMBIGUOUS_BASE =
+  /^(?:index|main|app|root)\.[a-z]+$|^\+(?:page|layout|server|error)(?:\.[a-z]+)*$/u;
+
+export function displayShortId(id: ModuleId): string {
+  const i = id.lastIndexOf('/');
+  if (i === -1) return id;
+  const base = id.slice(i + 1);
+  if (!AMBIGUOUS_BASE.test(base)) return base;
+  const parent = id.slice(0, i);
+  const j = parent.lastIndexOf('/');
+  return j === -1 ? id : `${parent.slice(j + 1)}/${base}`;
+}