@monoes/monograph 1.0.0 → 1.2.0

package/src/pipeline/phases/god-nodes.ts

@@ -5,8 +5,37 @@ import type { CrossFileOutput } from './cross-file.js';
 
 const EXCLUDED_LABELS = new Set(['File', 'Folder', 'Community', 'Concept']);
 
+export type GodNodeCategory =
+  | 'HIGH_CENTRALITY'
+  | 'BRIDGE_NODE'
+  | 'ISOLATED_CLUSTER'
+  | 'CHURN_HOTSPOT'
+  | 'CIRCULAR_IMPORT'
+  | 'UNREACHABLE';
+
+export interface ContributingFactor {
+  metric: string;
+  value: number;
+  threshold: number;
+}
+
+export interface GodNodesThresholds {
+  p75FanIn: number;
+  p90FanIn: number;
+  p95FanIn: number;
+  p75FanOut: number;
+  p90FanOut: number;
+}
+
 export interface GodNodesOutput {
-  godNodes: GodNode[];
+  godNodes: (GodNode & { category: GodNodeCategory; contributingFactors: ContributingFactor[] })[];
+  thresholds: GodNodesThresholds;
+}
+
+function percentile(sorted: number[], p: number): number {
+  if (sorted.length === 0) return 0;
+  const idx = Math.floor((p / 100) * sorted.length);
+  return sorted[Math.min(idx, sorted.length - 1)];
 }
 
 export const godNodesPhase: PipelinePhase<GodNodesOutput> = {
@@ -24,17 +53,66 @@ export const godNodesPhase: PipelinePhase<GodNodesOutput> = {
       inDeg.set(e.targetId, (inDeg.get(e.targetId) ?? 0) + 1);
     }
 
-    const godNodes: GodNode[] = symbolNodes
-      .filter(n => !EXCLUDED_LABELS.has(n.label) && (inDeg.get(n.id) ?? 0) + (outDeg.get(n.id) ?? 0) > 0)
-      .map(n => ({
-        ...n,
-        inDegree: inDeg.get(n.id) ?? 0,
-        outDegree: outDeg.get(n.id) ?? 0,
-        degree: (inDeg.get(n.id) ?? 0) + (outDeg.get(n.id) ?? 0),
-      }))
+    // Compute degree distributions from all symbol nodes
+    const allFanIn = symbolNodes
+      .filter(n => !EXCLUDED_LABELS.has(n.label))
+      .map(n => inDeg.get(n.id) ?? 0)
+      .sort((a, b) => a - b);
+
+    const allFanOut = symbolNodes
+      .filter(n => !EXCLUDED_LABELS.has(n.label))
+      .map(n => outDeg.get(n.id) ?? 0)
+      .sort((a, b) => a - b);
+
+    const thresholds: GodNodesThresholds = {
+      p75FanIn: percentile(allFanIn, 75),
+      p90FanIn: percentile(allFanIn, 90),
+      p95FanIn: percentile(allFanIn, 95),
+      p75FanOut: percentile(allFanOut, 75),
+      p90FanOut: percentile(allFanOut, 90),
+    };
+
+    const p95FanIn = thresholds.p95FanIn;
+    const p75FanIn = thresholds.p75FanIn;
+    const p75FanOut = thresholds.p75FanOut;
+
+    const godNodes = symbolNodes
+      .filter(n => !EXCLUDED_LABELS.has(n.label) && (inDeg.get(n.id) ?? 0) + (outDeg.get(n.id) ?? 0) > p95FanIn)
+      .map(n => {
+        const fanIn = inDeg.get(n.id) ?? 0;
+        const fanOut = outDeg.get(n.id) ?? 0;
+        const degree = fanIn + fanOut;
+
+        const contributingFactors: ContributingFactor[] = [];
+        if (fanIn > p95FanIn) {
+          contributingFactors.push({ metric: 'fanIn', value: fanIn, threshold: p95FanIn });
+        }
+        if (fanIn > p75FanIn) {
+          contributingFactors.push({ metric: 'fanInP75', value: fanIn, threshold: p75FanIn });
+        }
+        if (fanOut > p75FanOut) {
+          contributingFactors.push({ metric: 'fanOut', value: fanOut, threshold: p75FanOut });
+        }
+
+        let category: GodNodeCategory;
+        if (fanIn > p95FanIn && fanOut > p75FanOut) {
+          category = 'BRIDGE_NODE';
+        } else {
+          category = 'HIGH_CENTRALITY';
+        }
+
+        return {
+          ...n,
+          inDegree: fanIn,
+          outDegree: fanOut,
+          degree,
+          category,
+          contributingFactors,
+        };
+      })
       .sort((a, b) => b.degree - a.degree)
       .slice(0, 20);
 
-    return { godNodes };
+    return { godNodes, thresholds };
   },
 };

package/src/pipeline/phases/import-resolver.ts

@@ -0,0 +1,82 @@
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join, resolve } from 'path';
+import type { PipelinePhase, PipelineContext } from '../types.js';
+
+export interface WorkspacePackage {
+  name: string;
+  path: string;
+}
+
+export interface ImportResolverOutput {
+  workspacePackages: WorkspacePackage[];
+  resolvedCount: number;
+}
+
+function globWorkspacePattern(repoPath: string, pattern: string): string[] {
+  if (!pattern.includes('*')) {
+    return [join(repoPath, pattern)];
+  }
+  const [base] = pattern.split('/*');
+  const baseDir = join(repoPath, base ?? '');
+  if (!existsSync(baseDir)) return [];
+  try {
+    return readdirSync(baseDir, { withFileTypes: true })
+      .filter(d => d.isDirectory())
+      .map(d => join(baseDir, d.name));
+  } catch {
+    return [];
+  }
+}
+
+export function detectWorkspacePackages(repoPath: string): WorkspacePackage[] {
+  const pkgPath = join(repoPath, 'package.json');
+  if (!existsSync(pkgPath)) return [];
+
+  let workspaceGlobs: string[] = [];
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    const ws = pkg.workspaces;
+    if (Array.isArray(ws)) workspaceGlobs = ws;
+    else if (ws && Array.isArray(ws.packages)) workspaceGlobs = ws.packages;
+  } catch {
+    return [];
+  }
+
+  const result: WorkspacePackage[] = [];
+  for (const glob of workspaceGlobs) {
+    const dirs = globWorkspacePattern(repoPath, glob);
+    for (const dir of dirs) {
+      const subPkgPath = join(dir, 'package.json');
+      if (!existsSync(subPkgPath)) continue;
+      try {
+        const subPkg = JSON.parse(readFileSync(subPkgPath, 'utf8'));
+        if (subPkg.name) {
+          result.push({ name: subPkg.name, path: resolve(dir) });
+        }
+      } catch { /* skip */ }
+    }
+  }
+
+  return result;
+}
+
+export function resolveWorkspaceImport(
+  importSpecifier: string,
+  packages: WorkspacePackage[],
+): string | null {
+  for (const pkg of packages) {
+    if (importSpecifier === pkg.name || importSpecifier.startsWith(pkg.name + '/')) {
+      return pkg.path;
+    }
+  }
+  return null;
+}
+
+export const importResolverPhase: PipelinePhase<ImportResolverOutput> = {
+  name: 'import-resolver',
+  deps: ['cross-file'],
+  async execute(ctx: PipelineContext): Promise<ImportResolverOutput> {
+    const workspacePackages = detectWorkspacePackages(ctx.repoPath);
+    return { workspacePackages, resolvedCount: 0 };
+  },
+};

package/src/pipeline/phases/leiden.ts

@@ -0,0 +1,70 @@
+import louvain from 'graphology-communities-louvain';
+import type Graph from 'graphology';
+
+/**
+ * Leiden-like community detection with post-processing refinement.
+ *
+ * Since `graphology-communities-leiden` does not exist as a published package,
+ * this module implements a two-phase approach that improves on plain Louvain:
+ *
+ * Phase 1: Run Louvain with randomWalk disabled for deterministic output.
+ * Phase 2: Merge singleton communities (size === 1) into the largest
+ *           neighboring community, which mirrors the Leiden refinement idea
+ *           of guaranteeing well-connected communities.
+ *
+ * The result is seed-stable because Louvain is run deterministically
+ * (randomWalk: false) and the refinement step is purely deterministic.
+ *
+ * @param graph  Any graphology Graph instance (directed or undirected).
+ * @returns      A mapping of nodeId → communityId (numeric).
+ */
+export function leiden(graph: Graph, _options: { seed?: number } = {}): Record<string, number> {
+  if (graph.order === 0) {
+    return {};
+  }
+
+  // Phase 1: Louvain with deterministic settings
+  const communities: Record<string, number> = louvain(graph, { randomWalk: false });
+
+  // Phase 2: Refinement — merge singletons into their largest neighbor's community
+  const communitySizes = new Map<number, number>();
+  for (const comm of Object.values(communities)) {
+    communitySizes.set(comm, (communitySizes.get(comm) ?? 0) + 1);
+  }
+
+  // Refinement: merge singletons into their largest neighbor's community.
+  // Pass 1: update communitySizes eagerly (so adjacent singletons see each other's moves
+  //         and avoid mutual-swap cycles), collect community writes into `pending`.
+  // Pass 2: apply community writes — keeps the community map consistent at all times.
+  const pending = new Map<string, number>();
+  for (const [nodeId, commId] of Object.entries(communities)) {
+    if ((communitySizes.get(commId) ?? 0) <= 1) {
+      let bestComm = commId;
+      let bestSize = 0;
+
+      graph.forEachNeighbor(nodeId, (neighbor: string) => {
+        const neighborComm = communities[neighbor];
+        if (neighborComm === undefined) return;
+        const size = communitySizes.get(neighborComm) ?? 0;
+        if (size > bestSize) {
+          bestSize = size;
+          bestComm = neighborComm;
+        }
+      });
+
+      if (bestComm !== commId) {
+        // Update sizes eagerly so subsequent singletons see the correct community sizes
+        communitySizes.set(commId, (communitySizes.get(commId) ?? 1) - 1);
+        communitySizes.set(bestComm, (communitySizes.get(bestComm) ?? 0) + 1);
+        pending.set(nodeId, bestComm);
+      }
+    }
+  }
+
+  // Apply deferred community writes
+  for (const [nodeId, bestComm] of pending) {
+    communities[nodeId] = bestComm;
+  }
+
+  return communities;
+}

package/src/pipeline/phases/llm-extract.ts

@@ -0,0 +1,175 @@
+import type { PipelinePhase, PipelineContext } from '../types.js';
+import type { MonographNode, MonographEdge } from '../../types.js';
+import { makeId, toNormLabel, CONFIDENCE_SCORE } from '../../types.js';
+import { insertNodes } from '../../storage/node-store.js';
+import { insertEdges } from '../../storage/edge-store.js';
+import type { EdgeRelation } from '../../types.js';
+
+export interface LlmExtractOutput {
+  triplesExtracted: number;
+  sectionsProcessed: number;
+}
+
+const ALLOWED_RELATIONS = new Set<string>([
+  'DESCRIBES', 'CAUSES', 'CONTRASTS_WITH', 'PART_OF', 'RELATED_TO', 'USES',
+]);
+
+const SYSTEM_PROMPT = `You extract knowledge graph relationships from technical documentation chunks.
+
+Return ONLY a JSON array of relationships, each with:
+- "node_1": first concept (short, specific, lowercase, max 4 words)
+- "node_2": second concept (short, specific, lowercase, max 4 words)
+- "relation": one of DESCRIBES, CAUSES, CONTRASTS_WITH, PART_OF, RELATED_TO, USES
+- "edge": brief 3-6 word phrase describing the relationship
+
+Rules:
+- Concepts must be specific technical terms (not "thing", "item", "way", "use")
+- Maximum 8 relationships per chunk
+- Skip if text is too short, navigational, or has no meaningful concepts
+- Return [] for non-substantive content
+
+Return only valid JSON array, no explanation.`;
+
+interface Triple {
+  node_1: string;
+  node_2: string;
+  relation: string;
+  edge: string;
+}
+
+async function callClaude(content: string, apiKey: string): Promise<Triple[] | null> {
+  try {
+    const res = await fetch('https://api.anthropic.com/v1/messages', {
+      method: 'POST',
+      headers: {
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({
+        model: 'claude-haiku-4-5-20251001',
+        max_tokens: 512,
+        system: SYSTEM_PROMPT,
+        messages: [{ role: 'user', content: content.slice(0, 1500) }],
+      }),
+    });
+    if (!res.ok) return null;
+    const data = await res.json() as { content: Array<{ text: string }> };
+    const text = data.content[0]?.text ?? '[]';
+    const parsed = JSON.parse(text.match(/\[[\s\S]*\]/)?.[0] ?? '[]');
+    return Array.isArray(parsed) ? parsed as Triple[] : null;
+  } catch {
+    return null;
+  }
+}
+
+export const llmExtractPhase: PipelinePhase<LlmExtractOutput> = {
+  name: 'llm-extract',
+  deps: ['docs-parse', 'pdf-parse'],
+
+  async execute(ctx: PipelineContext) {
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    const maxSections = ctx.options.llmMaxSections;
+
+    if (!apiKey || maxSections <= 0 || ctx.options.codeOnly) {
+      return { triplesExtracted: 0, sectionsProcessed: 0 };
+    }
+
+    // Fetch Section nodes with non-trivial content
+    const sections = ctx.db
+      .prepare(`
+        SELECT id, name, properties FROM nodes
+        WHERE label = 'Section'
+        AND properties IS NOT NULL
+        AND json_extract(properties, '$.content') IS NOT NULL
+        AND length(json_extract(properties, '$.content')) > 200
+        LIMIT ?
+      `)
+      .all(maxSections) as { id: string; name: string; properties: string }[];
+
+    if (sections.length === 0) return { triplesExtracted: 0, sectionsProcessed: 0 };
+
+    const conceptNodes = new Map<string, MonographNode>();
+    const allEdges: MonographEdge[] = [];
+    const seenEdges = new Set<string>();
+    let sectionsProcessed = 0;
+
+    // Fetch existing concept IDs to avoid duplicate node creation
+    const existingConcepts = new Set<string>(
+      (ctx.db.prepare(`SELECT id FROM nodes WHERE label = 'Concept'`).all() as { id: string }[])
+        .map(r => r.id),
+    );
+
+    for (const section of sections) {
+      const props = JSON.parse(section.properties) as Record<string, unknown>;
+      const content = props.content as string | undefined;
+      if (!content) continue;
+
+      const triples = await callClaude(
+        `Section: "${section.name}"\n\n${content}`,
+        apiKey,
+      );
+      if (!triples || triples.length === 0) continue;
+
+      sectionsProcessed++;
+
+      for (const triple of triples) {
+        const { node_1, node_2, relation, edge } = triple;
+        if (!node_1 || !node_2 || !relation) continue;
+
+        const rel = relation.toUpperCase();
+        if (!ALLOWED_RELATIONS.has(rel)) continue;
+
+        // Normalize concept names (lowercase, collapse spaces)
+        const n1 = node_1.toLowerCase().trim().replace(/\s+/g, '_').replace(/[^a-z0-9_]/g, '');
+        const n2 = node_2.toLowerCase().trim().replace(/\s+/g, '_').replace(/[^a-z0-9_]/g, '');
+        if (!n1 || !n2 || n1 === n2) continue;
+
+        const c1Id = makeId('concept', n1);
+        const c2Id = makeId('concept', n2);
+
+        for (const [cId, cName] of [[c1Id, n1], [c2Id, n2]] as [string, string][]) {
+          if (!conceptNodes.has(cId) && !existingConcepts.has(cId)) {
+            conceptNodes.set(cId, {
+              id: cId, label: 'Concept',
+              name: cName.replace(/_/g, ' '), normLabel: toNormLabel(cName),
+              isExported: false,
+              properties: { source: 'llm', edgeLabel: edge },
+            });
+          }
+        }
+
+        // Section → concept_1 (DESCRIBES)
+        const e1Id = makeId(section.id, c1Id, 'describes');
+        if (!seenEdges.has(e1Id)) {
+          seenEdges.add(e1Id);
+          allEdges.push({
+            id: e1Id, sourceId: section.id, targetId: c1Id,
+            relation: 'DESCRIBES', confidence: 'INFERRED', confidenceScore: CONFIDENCE_SCORE.INFERRED,
+          });
+        }
+
+        // concept_1 → concept_2 (semantic relation)
+        const e2Id = makeId(c1Id, c2Id, rel.toLowerCase());
+        if (!seenEdges.has(e2Id)) {
+          seenEdges.add(e2Id);
+          allEdges.push({
+            id: e2Id, sourceId: c1Id, targetId: c2Id,
+            relation: rel as EdgeRelation, confidence: 'INFERRED', confidenceScore: CONFIDENCE_SCORE.INFERRED,
+            weight: 1,
+          });
+        }
+      }
+    }
+
+    if (conceptNodes.size > 0) insertNodes(ctx.db, [...conceptNodes.values()]);
+    if (allEdges.length > 0) insertEdges(ctx.db, allEdges);
+
+    ctx.onProgress?.({
+      phase: 'llm-extract',
+      message: `LLM processed ${sectionsProcessed} sections → ${allEdges.length} semantic edges, ${conceptNodes.size} new concepts`,
+    });
+
+    return { triplesExtracted: allEdges.length, sectionsProcessed };
+  },
+};

package/src/pipeline/phases/markdown.ts

@@ -0,0 +1,116 @@
+import { readFileSync, statSync } from 'fs';
+import { extname, basename, relative } from 'path';
+import type { PipelinePhase } from '../types.js';
+import type { MonographNode, MonographEdge } from '../../types.js';
+import { makeId, toNormLabel } from '../../types.js';
+import { insertNodes } from '../../storage/node-store.js';
+import { insertEdges } from '../../storage/edge-store.js';
+import type { StructureOutput } from './structure.js';
+
+const MARKDOWN_EXTENSIONS = new Set(['.md', '.mdx']);
+// Inline code span: `identifier`
+const INLINE_CODE_RE = /`([^`]+)`/g;
+
+export interface MarkdownOutput {
+  documentNodes: MonographNode[];
+  referencesEdges: MonographEdge[];
+}
+
+export const markdownPhase: PipelinePhase<MarkdownOutput> = {
+  name: 'markdown',
+  // Must run after parse so symbols are already in the DB for name lookup.
+  // Also depends on structure to get the list of file nodes.
+  // Runs before communities so REFERENCES edges are visible to graph analyses.
+  deps: ['parse', 'structure'],
+  async execute(ctx, deps) {
+    const { fileNodes } = deps.get('structure') as StructureOutput;
+    const documentNodes: MonographNode[] = [];
+    const referencesEdges: MonographEdge[] = [];
+
+    const mdFiles = fileNodes.filter(fn => {
+      const ext = extname(fn.name).toLowerCase();
+      return MARKDOWN_EXTENSIONS.has(ext);
+    });
+
+    for (const fileNode of mdFiles) {
+      // fileNode.filePath is already relative per codebase convention
+      const relPath = fileNode.filePath ?? '';
+      const absPath = `${ctx.repoPath}/${relPath}`;
+
+      let source: string;
+      try {
+        const stat = statSync(absPath);
+        if (stat.size > ctx.options.maxFileSizeBytes) continue;
+        source = readFileSync(absPath, 'utf-8');
+      } catch { continue; }
+
+      const nameWithoutExt = basename(relPath).replace(/\.(mdx?)$/, '');
+      // Use 'doc' suffix to avoid collision with the 'file'-suffixed File node
+      const docId = makeId(relPath.replace(/\//g, '_'), 'doc');
+
+      const docNode: MonographNode = {
+        id: docId,
+        label: 'Document',
+        name: nameWithoutExt,
+        normLabel: toNormLabel(nameWithoutExt),
+        filePath: relPath,
+        isExported: false,
+        language: 'markdown',
+      };
+      documentNodes.push(docNode);
+
+      // Extract inline code spans and match against symbol names in the DB
+      if (ctx.db) {
+        const spans = extractCodeSpans(source);
+        for (const span of spans) {
+          // Only match single-word identifiers (not shell commands, paths, etc.)
+          if (!isIdentifier(span)) continue;
+
+          // Exact name match, excluding structural nodes to avoid matching file names
+          const rows = ctx.db
+            .prepare(
+              `SELECT id FROM nodes WHERE name = ?
+               AND label NOT IN ('File', 'Folder', 'Document')`,
+            )
+            .all(span) as { id: string }[];
+
+          if (rows.length === 1) {
+            const edgeId = makeId(docId, rows[0].id, 'references');
+            referencesEdges.push({
+              id: edgeId,
+              sourceId: docId,
+              targetId: rows[0].id,
+              relation: 'REFERENCES',
+              confidence: 'INFERRED',
+              // Literal 0.8 — intentionally higher than CONFIDENCE_SCORE.INFERRED (0.5)
+              // because inline code span matches are reasonably strong documentation signals.
+              confidenceScore: 0.8,
+            });
+          }
+        }
+      }
+    }
+
+    if (ctx.db) {
+      insertNodes(ctx.db, documentNodes);
+      insertEdges(ctx.db, referencesEdges);
+    }
+
+    return { documentNodes, referencesEdges };
+  },
+};
+
+function extractCodeSpans(source: string): string[] {
+  const spans: string[] = [];
+  let match: RegExpExecArray | null;
+  const re = new RegExp(INLINE_CODE_RE.source, 'g');
+  while ((match = re.exec(source)) !== null) {
+    spans.push(match[1].trim());
+  }
+  return spans;
+}
+
+/** Accept only simple identifiers — letters, digits, underscores, hyphens, dots (for namespaced names). */
+function isIdentifier(span: string): boolean {
+  return /^[A-Za-z_$][A-Za-z0-9_$.-]*$/.test(span);
+}

package/src/pipeline/phases/middleware-extractor.ts

@@ -0,0 +1,127 @@
+// ── Middleware chain extractor ────────────────────────────────────────────────
+//
+// Pure regex-based extraction (no tree-sitter). Only scans the first 3000 chars
+// of source for performance. Handles four patterns:
+//
+//   1. nested:  withAuth(withRateLimit(handler))
+//   2. compose: compose(withAuth, withRateLimit)(handler)
+//   3. array:   app.get('/path', authMiddleware, handler)   (args before handler)
+//   4. none:    plain handler usage
+//
+// Next.js middleware.ts detection: if the source file itself exports a
+// `middleware` function with a `matcher` config, it is treated as a middleware
+// file rather than performing per-route handler scanning.
+
+export type WrapperPattern = 'compose' | 'nested' | 'array' | 'none';
+
+export interface MiddlewareInfo {
+  middlewareNames: string[];
+  wrapperPattern: WrapperPattern;
+}
+
+const SCAN_LIMIT = 3000;
+
+/**
+ * Extracts the middleware chain wrapping a named handler in source code.
+ *
+ * @param source     Full source text of the handler file.
+ * @param handlerName  The name of the handler function to look for.
+ * @returns  MiddlewareInfo with names in outermost-first order.
+ */
+export function extractMiddlewareChain(source: string, handlerName: string): MiddlewareInfo {
+  const snippet = source.slice(0, SCAN_LIMIT);
+
+  // ── Pattern 0: Next.js middleware.ts ──────────────────────────────────────
+  // If the file exports a `middleware` function and has a `matcher` config,
+  // treat it as a global middleware file — no per-route wrapping to extract.
+  const isNextMiddleware =
+    /export\s+(?:default\s+)?(?:async\s+)?function\s+middleware\b/.test(snippet) &&
+    /matcher/.test(snippet);
+  if (isNextMiddleware) {
+    return { middlewareNames: ['middleware.ts'], wrapperPattern: 'none' };
+  }
+
+  // ── Pattern 1: compose / pipe ─────────────────────────────────────────────
+  // Matches: compose(withAuth, withRateLimit)(handler)  or  pipe(...)(handler)
+  const composeRe = /(?:compose|pipe)\s*\(([\s\S]*?)\)\s*\(\s*HANDLER_NAME\s*\)/;
+  const composeSrc = composeRe.source.replace('HANDLER_NAME', escapeRe(handlerName));
+  const composeMatch = new RegExp(composeSrc, 'i').exec(snippet);
+  if (composeMatch) {
+    const names = composeMatch[1]
+      .split(',')
+      .map((s) => s.trim())
+      .filter((s) => /^[A-Za-z_$][\w$]*$/.test(s));
+    if (names.length > 0) {
+      return { middlewareNames: names, wrapperPattern: 'compose' };
+    }
+  }
+
+  // ── Pattern 2: nested wrappers ────────────────────────────────────────────
+  // Matches: withAuth(withRateLimit(handler)) — walks outward iteratively.
+  const nestedNames = extractNestedWrappers(snippet, handlerName);
+  if (nestedNames.length > 0) {
+    return { middlewareNames: nestedNames, wrapperPattern: 'nested' };
+  }
+
+  // ── Pattern 3: array / positional args (Express-style) ───────────────────
+  // Matches: app.METHOD('/path', mw1, mw2, handler)
+  // Extract identifiers that appear *before* the handler in the same call.
+  const arrayNames = extractArrayMiddleware(snippet, handlerName);
+  if (arrayNames.length > 0) {
+    return { middlewareNames: arrayNames, wrapperPattern: 'array' };
+  }
+
+  return { middlewareNames: [], wrapperPattern: 'none' };
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/** Escape a string for use as a regex literal. */
+function escapeRe(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Walk outward from the innermost `wrapper(handler)` occurrence.
+ * Returns names in outermost-first order, e.g. ['withAuth', 'withRateLimit']
+ * for `withAuth(withRateLimit(handler))`.
+ */
+function extractNestedWrappers(snippet: string, handlerName: string): string[] {
+  const wrappers: string[] = [];
+  let inner = escapeRe(handlerName);
+
+  // Each iteration tries to find `someIdent(inner)` in the snippet.
+  // Limit iterations to prevent pathological loops.
+  for (let i = 0; i < 10; i++) {
+    const re = new RegExp(`([A-Za-z_$][\\w$]*)\\s*\\(\\s*${inner}\\s*\\)`, 'i');
+    const m = re.exec(snippet);
+    if (!m) break;
+    wrappers.unshift(m[1]); // outermost first
+    inner = escapeRe(m[1]) + `\\s*\\(\\s*${inner}\\s*\\)`;
+  }
+
+  return wrappers;
+}
+
+/**
+ * Detect Express-style middleware arrays:
+ *   app.get('/path', mw1, mw2, handler)
+ * Returns identifier args that appear before `handler` in the same call.
+ */
+function extractArrayMiddleware(snippet: string, handlerName: string): string[] {
+  // Match: something.method('path', ...args, handler  — capture everything before handler
+  const re = new RegExp(
+    `\\.(?:get|post|put|delete|patch|use)\\s*\\(\\s*['"][^'"]*['"]\\s*,\\s*([^)]+?)\\s*\\b${escapeRe(handlerName)}\\b`,
+    'i',
+  );
+  const m = re.exec(snippet);
+  if (!m) return [];
+
+  const before = m[1];
+  const names = before
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => /^[A-Za-z_$][\w$]*$/.test(s));
+
+  return names;
+}