@pruddiman/hem 0.0.1-beta-5671db0 → 0.0.1-beta-72c22cf

package/dist/grouping-priors.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Structural priors for the deterministic grouping phase.
+ *
+ * The grouping pipeline respects two priors before falling back to derived
+ * clustering:
+ *
+ *   1. **Existing docs-folder scaffolding** — top-level subfolders of the
+ *      destination directory (e.g. `docs/auth/`, `docs/api/`) become
+ *      candidate group labels. Source files flow into the matching bucket.
+ *   2. **Src top-level structure** — depth-1 directories in the source tree
+ *      that contain enough files are promoted as group labels, preserving
+ *      parent-child nesting.
+ *
+ * This module handles prior #1 (destination scan) and exports matching
+ * utilities that `src/grouping.ts` uses for both priors.
+ */
+/** A candidate group label derived from an existing docs-folder. */
+export interface DocFolderPrior {
+    /** Folder name as it appears on disk (display label, original casing). */
+    name: string;
+    /** Lowercased key used for matching source files. */
+    key: string;
+}
+/** Collected priors from the destination directory. */
+export interface GroupingPriors {
+    /**
+     * Top-level doc subfolders that should anchor grouping. Empty when the
+     * destination doesn't exist yet or has no subfolders.
+     */
+    docFolders: DocFolderPrior[];
+}
+/**
+ * Scan the destination directory for top-level subfolders and return them
+ * as grouping priors. When the destination doesn't exist or contains no
+ * subdirectories, returns empty priors.
+ *
+ * Folders prefixed with `.` or `_` are ignored (treated as metadata).
+ */
+export declare function loadGroupingPriors(destinationPath: string): Promise<GroupingPriors>;
+/**
+ * Test whether a file should be assigned to a doc-folder prior.
+ *
+ * Three match modes (any one counts as a hit):
+ *   1. The folder key appears as a directory segment in the file's path.
+ *   2. The file's stem contains the folder key as a word-boundary token.
+ *   3. The file's deepest common directory matches the folder key.
+ */
+export declare function matchDocFolder(filePath: string, priors: readonly DocFolderPrior[]): DocFolderPrior | null;
+/**
+ * Normalize a folder name to a matching key. Lowercases and collapses
+ * underscores/spaces to hyphens so `User_Auth/` and `user-auth/` share a
+ * key.
+ */
+export declare function normalizeFolderKey(name: string): string;

package/dist/grouping-priors.js

@@ -0,0 +1,130 @@
+/**
+ * Structural priors for the deterministic grouping phase.
+ *
+ * The grouping pipeline respects two priors before falling back to derived
+ * clustering:
+ *
+ *   1. **Existing docs-folder scaffolding** — top-level subfolders of the
+ *      destination directory (e.g. `docs/auth/`, `docs/api/`) become
+ *      candidate group labels. Source files flow into the matching bucket.
+ *   2. **Src top-level structure** — depth-1 directories in the source tree
+ *      that contain enough files are promoted as group labels, preserving
+ *      parent-child nesting.
+ *
+ * This module handles prior #1 (destination scan) and exports matching
+ * utilities that `src/grouping.ts` uses for both priors.
+ */
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+// ── Public API ──────────────────────────────────────────────────────────
+/**
+ * Scan the destination directory for top-level subfolders and return them
+ * as grouping priors. When the destination doesn't exist or contains no
+ * subdirectories, returns empty priors.
+ *
+ * Folders prefixed with `.` or `_` are ignored (treated as metadata).
+ */
+export async function loadGroupingPriors(destinationPath) {
+    let entries;
+    try {
+        entries = await readdir(destinationPath);
+    }
+    catch {
+        return { docFolders: [] };
+    }
+    const docFolders = [];
+    for (const entry of entries) {
+        if (entry.startsWith(".") || entry.startsWith("_"))
+            continue;
+        const entryPath = join(destinationPath, entry);
+        let stats;
+        try {
+            stats = await stat(entryPath);
+        }
+        catch {
+            continue;
+        }
+        if (!stats.isDirectory())
+            continue;
+        docFolders.push({ name: entry, key: normalizeFolderKey(entry) });
+    }
+    // Stable ordering for reproducible runs.
+    docFolders.sort((a, b) => a.key.localeCompare(b.key));
+    return { docFolders };
+}
+/**
+ * Test whether a file should be assigned to a doc-folder prior.
+ *
+ * Three match modes (any one counts as a hit):
+ *   1. The folder key appears as a directory segment in the file's path.
+ *   2. The file's stem contains the folder key as a word-boundary token.
+ *   3. The file's deepest common directory matches the folder key.
+ */
+export function matchDocFolder(filePath, priors) {
+    if (priors.length === 0)
+        return null;
+    const segments = filePath.split("/").map((s) => s.toLowerCase());
+    const fileStem = extractStem(segments[segments.length - 1] ?? "");
+    // Prefer the prior with the longest key match to avoid `auth` stealing
+    // files that should go to `authentication`.
+    let best = null;
+    for (const prior of priors) {
+        const score = scoreMatch(segments, fileStem, prior.key);
+        if (score > 0 && (!best || score > best.score)) {
+            best = { prior, score };
+        }
+    }
+    return best?.prior ?? null;
+}
+/**
+ * Normalize a folder name to a matching key. Lowercases and collapses
+ * underscores/spaces to hyphens so `User_Auth/` and `user-auth/` share a
+ * key.
+ */
+export function normalizeFolderKey(name) {
+    return name
+        .toLowerCase()
+        .replace(/[\s_]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+// ── Internal helpers ────────────────────────────────────────────────────
+function extractStem(basename) {
+    const dotIndex = basename.indexOf(".");
+    return (dotIndex === -1 ? basename : basename.substring(0, dotIndex)).toLowerCase();
+}
+/**
+ * Scoring:
+ *   - 3 for a directory-segment match (strongest signal).
+ *   - 2 for a word-boundary match in the file stem.
+ *   - 1 for a loose prefix/suffix/containment match in the stem.
+ *   - 0 for no match.
+ *
+ * Longer keys win on ties (handled by caller).
+ */
+function scoreMatch(segments, fileStem, key) {
+    if (key.length === 0)
+        return 0;
+    // 3: directory segment
+    for (let i = 0; i < segments.length - 1; i++) {
+        if (segments[i] === key)
+            return 3 + key.length / 100;
+    }
+    // 2: word-boundary in stem
+    const tokens = splitWordBoundaries(fileStem);
+    if (tokens.includes(key))
+        return 2 + key.length / 100;
+    // 1: substring with hyphen/underscore boundary
+    const paddedStem = "-" + fileStem + "-";
+    const paddedKey = "-" + key + "-";
+    if (paddedStem.includes(paddedKey))
+        return 1 + key.length / 100;
+    return 0;
+}
+function splitWordBoundaries(s) {
+    return s
+        .replace(/([a-z])([A-Z])/g, "$1-$2")
+        .toLowerCase()
+        .split(/[-_]/)
+        .filter((t) => t.length > 0);
+}

package/dist/grouping.d.ts

@@ -1,14 +1,22 @@
 /**
  * File grouping module for Hem.
  *
- * Analyses discovered source files and groups them by feature vertical
- * (e.g., "user", "order") or architectural layer (e.g., controllers,
- * services). Each file appears in at most one group; feature grouping
- * takes priority over layer grouping.
+ * Analyses discovered source files and groups them in this priority order:
  *
- * Reference: FR-003, data-model.md lines 93-108.
+ *   1. Existing docs-folder priors — folders already present in the
+ *      destination directory anchor matching files (stable across runs).
+ *   2. Src top-level promotion — depth-1 source directories with ≥3 files
+ *      become vertical groups, preserving parent-child nesting.
+ *   3. Legacy feature extraction — deepest non-layer directory as a label.
+ *   4. Architectural layer heuristic — suffix/dir pattern matching.
+ *   5. Import-graph connected components — clusters for files the above
+ *      passes miss.
+ *   6. Catch-all "Other" group.
+ *
+ * Each file appears in exactly one group.
  */
 import type { FileInfo, FileGroup } from "./types.js";
+import { type GroupingPriors } from "./grouping-priors.js";
 /**
  * Finds the common parent directory for a set of file paths.
  *
@@ -16,22 +24,21 @@ import type { FileInfo, FileGroup } from "./types.js";
  * @returns The common parent directory (relative path), or `"."` for root.
  */
 export declare function commonDirectory(files: FileInfo[]): string;
+/** Optional inputs that steer deterministic grouping. */
+export interface GroupingOptions {
+    /** Priors derived from the destination directory (if it exists). */
+    priors?: GroupingPriors;
+    /**
+     * Local-import adjacency map produced by `buildImportGraph`. When
+     * provided, files left unassigned after heuristic passes are clustered
+     * by connected components.
+     */
+    localEdges?: Map<string, string[]>;
+}
 /**
- * Groups discovered files by feature vertical or architectural layer.
- *
- * Grouping strategy:
- *   1. Filter out binary files.
- *   2. Attempt to assign each file to a **feature vertical** group
- *      based on its directory structure (e.g., files under `user/` →
- *      "User" feature group).
- *   3. Files not assigned to a feature group are checked for
- *      **architectural layer** membership based on file name suffixes
- *      (e.g., `.controller.ts` → "Controllers" layer) or containing
- *      directory (e.g., `services/` → "Services").
- *   4. Remaining files go into a catch-all "Other" group.
- *   5. Each file appears in at most one group.
+ * Groups discovered files. See module docstring for the priority order.
  *
- * @param files - Discovered files (may include binary files).
- * @returns Array of `FileGroup` objects.
+ * @param files   - Discovered files (may include binary files).
+ * @param options - Optional priors and precomputed import graph.
  */
-export declare function groupFiles(files: FileInfo[]): FileGroup[];
+export declare function groupFiles(files: FileInfo[], options?: GroupingOptions): FileGroup[];

package/dist/grouping.js

@@ -1,15 +1,24 @@
 /**
  * File grouping module for Hem.
  *
- * Analyses discovered source files and groups them by feature vertical
- * (e.g., "user", "order") or architectural layer (e.g., controllers,
- * services). Each file appears in at most one group; feature grouping
- * takes priority over layer grouping.
+ * Analyses discovered source files and groups them in this priority order:
  *
- * Reference: FR-003, data-model.md lines 93-108.
+ *   1. Existing docs-folder priors — folders already present in the
+ *      destination directory anchor matching files (stable across runs).
+ *   2. Src top-level promotion — depth-1 source directories with ≥3 files
+ *      become vertical groups, preserving parent-child nesting.
+ *   3. Legacy feature extraction — deepest non-layer directory as a label.
+ *   4. Architectural layer heuristic — suffix/dir pattern matching.
+ *   5. Import-graph connected components — clusters for files the above
+ *      passes miss.
+ *   6. Catch-all "Other" group.
+ *
+ * Each file appears in exactly one group.
  */
 import { dirname } from "node:path";
 import { toKebabCase } from "./helpers/strings.js";
+import { connectedComponents } from "./import-graph.js";
+import { matchDocFolder, } from "./grouping-priors.js";
 // ── Layer detection ─────────────────────────────────────────────────────
 /**
  * Maps well-known file name suffixes to their architectural layer label.
@@ -216,99 +225,138 @@ function toDisplayLabel(name) {
         .replace(/\b\w/g, (ch) => ch.toUpperCase());
 }
 // ── Main ────────────────────────────────────────────────────────────────
+/** Minimum files a top-level src directory needs before it's promoted. */
+const TOP_LEVEL_PROMOTION_THRESHOLD = 3;
+/** Minimum size of an import-graph connected component to become a group. */
+const MIN_COMPONENT_SIZE = 2;
+/** Components larger than this split along directory boundaries. */
+const MAX_COMPONENT_SIZE = 6;
 /**
- * Groups discovered files by feature vertical or architectural layer.
- *
- * Grouping strategy:
- *   1. Filter out binary files.
- *   2. Attempt to assign each file to a **feature vertical** group
- *      based on its directory structure (e.g., files under `user/` →
- *      "User" feature group).
- *   3. Files not assigned to a feature group are checked for
- *      **architectural layer** membership based on file name suffixes
- *      (e.g., `.controller.ts` → "Controllers" layer) or containing
- *      directory (e.g., `services/` → "Services").
- *   4. Remaining files go into a catch-all "Other" group.
- *   5. Each file appears in at most one group.
+ * Groups discovered files. See module docstring for the priority order.
  *
- * @param files - Discovered files (may include binary files).
- * @returns Array of `FileGroup` objects.
+ * @param files   - Discovered files (may include binary files).
+ * @param options - Optional priors and precomputed import graph.
  */
-export function groupFiles(files) {
-    // Step 1: filter to non-binary files only
+export function groupFiles(files, options = {}) {
     const textFiles = files.filter((f) => !f.isBinary);
     if (textFiles.length === 0)
         return [];
-    // Step 2: Build feature and layer buckets
+    const priors = options.priors?.docFolders ?? [];
+    const localEdges = options.localEdges;
+    /** Key → display label for vertical groups. */
+    const featureLabels = new Map();
+    /** Key → bucket of FileInfo for vertical groups. */
     const featureBuckets = new Map();
+    /** Keys that came from priors and should not be demoted. */
+    const pinnedKeys = new Set();
+    /** Layer buckets, keyed by display label. */
     const layerBuckets = new Map();
-    const ungrouped = [];
-    const assigned = new Set(); // track by relative path
-    // First pass: try to assign every file to a feature vertical
+    /** Paths that already belong to a bucket. */
+    const assigned = new Set();
+    const addFeature = (key, label, file) => {
+        if (!featureBuckets.has(key)) {
+            featureBuckets.set(key, []);
+            featureLabels.set(key, label);
+        }
+        featureBuckets.get(key).push(file);
+        assigned.add(file.path);
+    };
+    // ── Pass 1: existing docs-folder priors ──
+    for (const file of textFiles) {
+        const match = matchDocFolder(file.path, priors);
+        if (!match)
+            continue;
+        addFeature(match.key, toDisplayLabel(match.name), file);
+        pinnedKeys.add(match.key);
+    }
+    // ── Pass 2: src top-level promotion (≥3 files) ──
+    const topLevelCounts = countTopLevelDirs(textFiles);
+    for (const file of textFiles) {
+        if (assigned.has(file.path))
+            continue;
+        const top = topLevelDir(file.path);
+        if (!top)
+            continue;
+        if (LAYER_DIRECTORIES.has(top.toLowerCase()))
+            continue;
+        const count = topLevelCounts.get(top) ?? 0;
+        if (count < TOP_LEVEL_PROMOTION_THRESHOLD)
+            continue;
+        addFeature(top.toLowerCase(), toDisplayLabel(top), file);
+    }
+    // ── Pass 3: legacy feature extraction (deepest non-layer dir) ──
     for (const file of textFiles) {
+        if (assigned.has(file.path))
+            continue;
         const feature = extractFeatureName(file.path);
-        if (feature) {
-            const key = feature.toLowerCase();
-            if (!featureBuckets.has(key)) {
-                featureBuckets.set(key, []);
-            }
-            featureBuckets.get(key).push(file);
-            assigned.add(file.path);
-        }
+        if (!feature)
+            continue;
+        addFeature(feature.toLowerCase(), toDisplayLabel(feature), file);
     }
-    // Promote single-file features back to unassigned — features with
-    // only one file aren't meaningful groups by themselves. They'll get
-    // a chance to be grouped by layer instead.
+    // Demote single-file feature buckets (unless pinned by a prior).
     for (const [key, bucket] of featureBuckets) {
+        if (pinnedKeys.has(key))
+            continue;
         if (bucket.length < 2) {
-            for (const file of bucket) {
+            for (const file of bucket)
                 assigned.delete(file.path);
-            }
             featureBuckets.delete(key);
+            featureLabels.delete(key);
         }
     }
-    // Second pass: unassigned files → try layer grouping
+    // ── Pass 4: architectural layers ──
     for (const file of textFiles) {
         if (assigned.has(file.path))
             continue;
         const layer = detectLayer(file.path) ?? detectLayerByDirectory(file.path);
-        if (layer) {
-            if (!layerBuckets.has(layer)) {
-                layerBuckets.set(layer, []);
-            }
-            layerBuckets.get(layer).push(file);
-            assigned.add(file.path);
-        }
+        if (!layer)
+            continue;
+        if (!layerBuckets.has(layer))
+            layerBuckets.set(layer, []);
+        layerBuckets.get(layer).push(file);
+        assigned.add(file.path);
     }
-    // Promote single-file layers back to ungrouped
+    // Demote single-file layer buckets.
     for (const [key, bucket] of layerBuckets) {
         if (bucket.length < 2) {
-            for (const file of bucket) {
+            for (const file of bucket)
                 assigned.delete(file.path);
-            }
             layerBuckets.delete(key);
         }
     }
-    // Third pass: remaining → "Other"
-    for (const file of textFiles) {
-        if (!assigned.has(file.path)) {
-            ungrouped.push(file);
+    // ── Pass 5: import-graph connected components ──
+    if (localEdges) {
+        const remaining = textFiles.filter((f) => !assigned.has(f.path));
+        const remainingPaths = remaining.map((f) => f.path);
+        const byPath = new Map(remaining.map((f) => [f.path, f]));
+        const components = connectedComponents(remainingPaths, localEdges);
+        const componentGroups = buildComponentGroups(components, byPath);
+        for (const cg of componentGroups) {
+            const key = cg.key;
+            if (!featureBuckets.has(key)) {
+                featureBuckets.set(key, []);
+                featureLabels.set(key, cg.label);
+            }
+            for (const file of cg.files) {
+                featureBuckets.get(key).push(file);
+                assigned.add(file.path);
+            }
         }
     }
-    // Step 3: Convert buckets to FileGroup objects
+    // ── Pass 6: catch-all "Other" ──
+    const ungrouped = textFiles.filter((f) => !assigned.has(f.path));
+    // ── Build FileGroup objects ──
     const groups = [];
-    // Feature (vertical) groups
     for (const [key, bucket] of featureBuckets) {
-        const displayLabel = toDisplayLabel(key);
+        const label = featureLabels.get(key) ?? toDisplayLabel(key);
         groups.push({
-            id: toKebabCase(displayLabel) + "-feature",
-            label: displayLabel,
+            id: toKebabCase(label) + "-feature",
+            label,
             type: "vertical",
             files: bucket.sort((a, b) => a.path.localeCompare(b.path)),
             directory: commonDirectory(bucket),
         });
     }
-    // Layer (horizontal) groups
     for (const [label, bucket] of layerBuckets) {
         groups.push({
             id: toKebabCase(label) + "-layer",
@@ -318,7 +366,6 @@ export function groupFiles(files) {
             directory: commonDirectory(bucket),
         });
     }
-    // Catch-all "Other" group
     if (ungrouped.length > 0) {
         groups.push({
             id: "other",
@@ -328,11 +375,9 @@ export function groupFiles(files) {
             directory: commonDirectory(ungrouped),
         });
     }
-    // Sort groups: verticals first, then horizontals, alphabetically within
     groups.sort((a, b) => {
         if (a.type !== b.type)
             return a.type === "vertical" ? -1 : 1;
-        // "Other" always last within its type
         if (a.id === "other")
             return 1;
         if (b.id === "other")
@@ -341,3 +386,86 @@ export function groupFiles(files) {
     });
     return groups;
 }
+// ── Internal pass helpers ───────────────────────────────────────────────
+/**
+ * Returns the first path segment of a file's directory, or `null` when the
+ * file sits at the source root.
+ */
+function topLevelDir(relativePath) {
+    const dir = dirname(relativePath);
+    if (dir === "." || dir === "")
+        return null;
+    const [head] = dir.split("/");
+    return head && head.length > 0 ? head : null;
+}
+function countTopLevelDirs(files) {
+    const counts = new Map();
+    for (const file of files) {
+        const top = topLevelDir(file.path);
+        if (!top)
+            continue;
+        counts.set(top, (counts.get(top) ?? 0) + 1);
+    }
+    return counts;
+}
+/**
+ * Turn connected components into groups suitable for the vertical buckets.
+ * Small components (2-6) stay intact; larger components bisect by
+ * directory prefix.
+ */
+function buildComponentGroups(components, byPath) {
+    const out = [];
+    for (const component of components) {
+        if (component.length < MIN_COMPONENT_SIZE)
+            continue;
+        const files = component
+            .map((p) => byPath.get(p))
+            .filter((f) => Boolean(f));
+        if (files.length < MIN_COMPONENT_SIZE)
+            continue;
+        if (files.length <= MAX_COMPONENT_SIZE) {
+            out.push(componentToGroup(files));
+            continue;
+        }
+        for (const sub of bisectByDirectory(files)) {
+            if (sub.length < MIN_COMPONENT_SIZE)
+                continue;
+            out.push(componentToGroup(sub));
+        }
+    }
+    return out;
+}
+function componentToGroup(files) {
+    const commonDir = commonDirectory(files);
+    const basename = commonDir.split("/").filter((s) => s.length > 0).pop() ?? "cluster";
+    const label = toDisplayLabel(basename);
+    // Append a stable short hash of paths to avoid collisions with other buckets.
+    const key = basename.toLowerCase() + "-cluster";
+    return { key, label, files };
+}
+/**
+ * Split a large component into sub-groups by directory prefix. Files are
+ * bucketed by their first directory segment; singletons collapse back into
+ * a "mixed" bucket to avoid proliferation.
+ */
+function bisectByDirectory(files) {
+    const byTop = new Map();
+    for (const file of files) {
+        const dir = dirname(file.path);
+        const top = dir === "." ? "" : dir.split("/")[0] ?? "";
+        if (!byTop.has(top))
+            byTop.set(top, []);
+        byTop.get(top).push(file);
+    }
+    const buckets = [];
+    const mixed = [];
+    for (const bucket of byTop.values()) {
+        if (bucket.length >= MIN_COMPONENT_SIZE)
+            buckets.push(bucket);
+        else
+            mixed.push(...bucket);
+    }
+    if (mixed.length >= MIN_COMPONENT_SIZE)
+        buckets.push(mixed);
+    return buckets;
+}

package/dist/import-graph.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Import graph extraction for Hem.
+ *
+ * Produces two views of a file set, both built from regex-based import
+ * scanning (no AST / compiler API):
+ *
+ *   - A **local** graph of resolved relative imports between known files,
+ *     used by grouping for connected-component clustering.
+ *   - An **external** map of bare-specifier imports per file (with line
+ *     numbers), used by exploration to match packages against the
+ *     integration catalog with file:line citations.
+ */
+import type { FileInfo } from "./types.js";
+/** One observation of an external import in a file. */
+export interface ImportOccurrence {
+    /** The bare specifier as written (e.g., `"@azure/storage-blob"`, `"react"`). */
+    specifier: string;
+    /** 1-based line number where the import appears. */
+    line: number;
+}
+/** Two views of the import graph. */
+export interface ImportAnalysis {
+    /**
+     * Undirected-friendly adjacency: file path → list of resolved local file
+     * paths it imports. Only includes edges where the target is a known file
+     * in the input set.
+     */
+    localEdges: Map<string, string[]>;
+    /**
+     * External imports per file (npm / PyPI / Go module / etc. bare
+     * specifiers). Each entry carries the original specifier and the line
+     * number it was found on so catalog hits can produce file:line citations.
+     */
+    externalImports: Map<string, ImportOccurrence[]>;
+}
+/**
+ * Build the import graph for a set of files. Files that fail to read are
+ * silently skipped (they contribute no edges). Reads run in parallel with
+ * a bounded concurrency to keep wall-clock time low on large projects.
+ */
+export declare function buildImportGraph(files: FileInfo[]): Promise<ImportAnalysis>;
+/**
+ * Union-find based connected-components over an undirected view of the
+ * local graph. `universe` is the set of files under consideration;
+ * isolated nodes appear as singleton components.
+ */
+export declare function connectedComponents(universe: readonly string[], localEdges: Map<string, string[]>): string[][];
+/**
+ * Compute fan-in (how many files import this file) and fan-out (how many
+ * files this file imports) for every node in `universe`.
+ */
+export declare function computeDegrees(universe: readonly string[], localEdges: Map<string, string[]>): Map<string, {
+    fanIn: number;
+    fanOut: number;
+}>;
+/**
+ * Identify files participating in an import cycle. Uses iterative Tarjan's
+ * SCC; any SCC with ≥2 members or a self-loop marks its members as cyclic.
+ */
+export declare function nodesInCycles(localEdges: Map<string, string[]>): Set<string>;
+/**
+ * Yield every import specifier found in `content` along with the 1-based
+ * line number it appears on.
+ */
+export declare function extractImports(content: string): Generator<{
+    specifier: string;
+    line: number;
+}>;
+/**
+ * Resolve a relative specifier from `fromFile` against the set of known
+ * file paths. Handles the common `.js` → `.ts`/`.tsx` mapping used in
+ * TypeScript sources.
+ */
+export declare function resolveRelative(fromFile: string, specifier: string, knownFiles: ReadonlySet<string>): string | null;

package/dist/import-graph.js

@@ -0,0 +1,330 @@
+/**
+ * Import graph extraction for Hem.
+ *
+ * Produces two views of a file set, both built from regex-based import
+ * scanning (no AST / compiler API):
+ *
+ *   - A **local** graph of resolved relative imports between known files,
+ *     used by grouping for connected-component clustering.
+ *   - An **external** map of bare-specifier imports per file (with line
+ *     numbers), used by exploration to match packages against the
+ *     integration catalog with file:line citations.
+ */
+import { readFile } from "node:fs/promises";
+import pLimit from "p-limit";
+/**
+ * Files larger than this byte count are skipped when building the import
+ * graph. Huge generated files (lockfiles, bundled output) rarely contain
+ * useful import edges and reading them can stall the pipeline for minutes.
+ */
+const MAX_FILE_BYTES = 2 * 1024 * 1024; // 2 MB
+/** Parallel file reads when building the graph. */
+const READ_CONCURRENCY = 32;
+// ── Regexes ─────────────────────────────────────────────────────────────
+// Static: `import ... from "x"` or `export ... from "x"`
+const STATIC_RE = /(?:import|export)\s+[^;'"`]*?\s+from\s+["']([^"']+)["']/g;
+// Dynamic: `import("x")` or `require("x")`
+const DYNAMIC_RE = /(?:import|require)\s*\(\s*["']([^"']+)["']\s*\)/g;
+// ── Public API ──────────────────────────────────────────────────────────
+/**
+ * Build the import graph for a set of files. Files that fail to read are
+ * silently skipped (they contribute no edges). Reads run in parallel with
+ * a bounded concurrency to keep wall-clock time low on large projects.
+ */
+export async function buildImportGraph(files) {
+    const known = new Set(files.map((f) => f.path));
+    const localEdges = new Map();
+    const externalImports = new Map();
+    const limit = pLimit(READ_CONCURRENCY);
+    await Promise.all(files.map((file) => limit(async () => {
+        if (file.isBinary)
+            return;
+        if (file.size > MAX_FILE_BYTES)
+            return;
+        let content;
+        try {
+            content = await readFile(file.absolutePath, "utf-8");
+        }
+        catch {
+            return;
+        }
+        const local = [];
+        const external = [];
+        for (const { specifier, line } of extractImports(content)) {
+            if (isRelativeSpecifier(specifier)) {
+                const resolved = resolveRelative(file.path, specifier, known);
+                if (resolved && resolved !== file.path) {
+                    local.push(resolved);
+                }
+            }
+            else if (isBareSpecifier(specifier)) {
+                external.push({ specifier, line });
+            }
+            // Absolute filesystem paths and URL-like specifiers are ignored.
+        }
+        if (local.length > 0) {
+            localEdges.set(file.path, dedupe(local));
+        }
+        if (external.length > 0) {
+            externalImports.set(file.path, external);
+        }
+    })));
+    return { localEdges, externalImports };
+}
+/**
+ * Union-find based connected-components over an undirected view of the
+ * local graph. `universe` is the set of files under consideration;
+ * isolated nodes appear as singleton components.
+ */
+export function connectedComponents(universe, localEdges) {
+    const parent = new Map();
+    const rank = new Map();
+    for (const node of universe) {
+        parent.set(node, node);
+        rank.set(node, 0);
+    }
+    const find = (x) => {
+        let cur = x;
+        // Iterative path compression
+        while (parent.get(cur) !== cur) {
+            const p = parent.get(cur);
+            parent.set(cur, parent.get(p));
+            cur = parent.get(cur);
+        }
+        return cur;
+    };
+    const union = (a, b) => {
+        const ra = find(a);
+        const rb = find(b);
+        if (ra === rb)
+            return;
+        const rankA = rank.get(ra);
+        const rankB = rank.get(rb);
+        if (rankA < rankB) {
+            parent.set(ra, rb);
+        }
+        else if (rankA > rankB) {
+            parent.set(rb, ra);
+        }
+        else {
+            parent.set(rb, ra);
+            rank.set(ra, rankA + 1);
+        }
+    };
+    const inUniverse = new Set(universe);
+    for (const [from, tos] of localEdges) {
+        if (!inUniverse.has(from))
+            continue;
+        for (const to of tos) {
+            if (!inUniverse.has(to))
+                continue;
+            union(from, to);
+        }
+    }
+    const components = new Map();
+    for (const node of universe) {
+        const root = find(node);
+        if (!components.has(root))
+            components.set(root, []);
+        components.get(root).push(node);
+    }
+    return [...components.values()].map((c) => c.slice().sort((a, b) => a.localeCompare(b)));
+}
+/**
+ * Compute fan-in (how many files import this file) and fan-out (how many
+ * files this file imports) for every node in `universe`.
+ */
+export function computeDegrees(universe, localEdges) {
+    const degrees = new Map();
+    for (const node of universe) {
+        degrees.set(node, { fanIn: 0, fanOut: 0 });
+    }
+    for (const [from, tos] of localEdges) {
+        const d = degrees.get(from);
+        if (!d)
+            continue;
+        d.fanOut = tos.length;
+        for (const to of tos) {
+            const td = degrees.get(to);
+            if (td)
+                td.fanIn += 1;
+        }
+    }
+    return degrees;
+}
+/**
+ * Identify files participating in an import cycle. Uses iterative Tarjan's
+ * SCC; any SCC with ≥2 members or a self-loop marks its members as cyclic.
+ */
+export function nodesInCycles(localEdges) {
+    const index = new Map();
+    const lowlink = new Map();
+    const onStack = new Set();
+    const stack = [];
+    const result = new Set();
+    let counter = 0;
+    const nodes = new Set();
+    for (const [from, tos] of localEdges) {
+        nodes.add(from);
+        for (const to of tos)
+            nodes.add(to);
+    }
+    const strongConnect = (start) => {
+        const frames = [];
+        index.set(start, counter);
+        lowlink.set(start, counter);
+        counter++;
+        stack.push(start);
+        onStack.add(start);
+        frames.push({
+            node: start,
+            iter: (localEdges.get(start) ?? [])[Symbol.iterator](),
+        });
+        while (frames.length > 0) {
+            const frame = frames[frames.length - 1];
+            const next = frame.iter.next();
+            if (next.done) {
+                // Finished with frame.node — check if it's an SCC root.
+                if (lowlink.get(frame.node) === index.get(frame.node)) {
+                    const component = [];
+                    let w;
+                    do {
+                        w = stack.pop();
+                        onStack.delete(w);
+                        component.push(w);
+                    } while (w !== frame.node);
+                    const neighbours = localEdges.get(frame.node) ?? [];
+                    const hasSelfLoop = neighbours.includes(frame.node);
+                    if (component.length >= 2 || hasSelfLoop) {
+                        for (const m of component)
+                            result.add(m);
+                    }
+                }
+                frames.pop();
+                // Propagate lowlink to parent.
+                if (frames.length > 0) {
+                    const parentFrame = frames[frames.length - 1];
+                    const pl = lowlink.get(parentFrame.node);
+                    const cl = lowlink.get(frame.node);
+                    if (cl < pl)
+                        lowlink.set(parentFrame.node, cl);
+                }
+                continue;
+            }
+            const w = next.value;
+            if (!index.has(w)) {
+                index.set(w, counter);
+                lowlink.set(w, counter);
+                counter++;
+                stack.push(w);
+                onStack.add(w);
+                frames.push({ node: w, iter: (localEdges.get(w) ?? [])[Symbol.iterator]() });
+            }
+            else if (onStack.has(w)) {
+                const cur = lowlink.get(frame.node);
+                const wIndex = index.get(w);
+                if (wIndex < cur)
+                    lowlink.set(frame.node, wIndex);
+            }
+        }
+    };
+    for (const node of nodes) {
+        if (!index.has(node))
+            strongConnect(node);
+    }
+    return result;
+}
+// ── Internal helpers ────────────────────────────────────────────────────
+/**
+ * Yield every import specifier found in `content` along with the 1-based
+ * line number it appears on.
+ */
+export function* extractImports(content) {
+    for (const re of [STATIC_RE, DYNAMIC_RE]) {
+        // Fresh state per content call.
+        re.lastIndex = 0;
+        let match;
+        while ((match = re.exec(content)) !== null) {
+            const specifier = match[1];
+            const line = lineNumberAt(content, match.index);
+            yield { specifier, line };
+        }
+    }
+}
+function lineNumberAt(content, offset) {
+    let line = 1;
+    for (let i = 0; i < offset && i < content.length; i++) {
+        if (content.charCodeAt(i) === 10 /* \n */)
+            line++;
+    }
+    return line;
+}
+function isRelativeSpecifier(spec) {
+    return spec.startsWith("./") || spec.startsWith("../") || spec === "." || spec === "..";
+}
+/**
+ * A bare specifier is an npm/Go/PyPI-style package reference: not relative,
+ * not an absolute filesystem path, not a URL, not an alias starting with
+ * `@/` or `~/`.
+ */
+function isBareSpecifier(spec) {
+    if (spec.length === 0)
+        return false;
+    if (isRelativeSpecifier(spec))
+        return false;
+    if (spec.startsWith("/"))
+        return false;
+    if (spec.startsWith("~"))
+        return false;
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(spec))
+        return false; // URL
+    // `@/foo` bundler aliases look like scoped packages; disambiguate by
+    // requiring a scoped package to contain a slash after the scope
+    // (`@scope/pkg`) while plain `@/alias` does not.
+    if (spec.startsWith("@") && !spec.slice(1).includes("/"))
+        return false;
+    return true;
+}
+/**
+ * Resolve a relative specifier from `fromFile` against the set of known
+ * file paths. Handles the common `.js` → `.ts`/`.tsx` mapping used in
+ * TypeScript sources.
+ */
+export function resolveRelative(fromFile, specifier, knownFiles) {
+    const parts = fromFile.split("/");
+    parts.pop();
+    const dir = parts.join("/");
+    const segments = (dir ? dir + "/" + specifier : specifier).split("/");
+    const resolved = [];
+    for (const seg of segments) {
+        if (seg === "." || seg === "")
+            continue;
+        if (seg === "..") {
+            resolved.pop();
+        }
+        else {
+            resolved.push(seg);
+        }
+    }
+    const resolvedPath = resolved.join("/");
+    if (knownFiles.has(resolvedPath))
+        return resolvedPath;
+    const withoutJs = resolvedPath.replace(/\.js$/, "");
+    if (knownFiles.has(withoutJs + ".ts"))
+        return withoutJs + ".ts";
+    if (knownFiles.has(withoutJs + ".tsx"))
+        return withoutJs + ".tsx";
+    if (knownFiles.has(resolvedPath + ".ts"))
+        return resolvedPath + ".ts";
+    if (knownFiles.has(resolvedPath + ".tsx"))
+        return resolvedPath + ".tsx";
+    // Directory imports — try `index.ts` / `index.tsx`.
+    if (knownFiles.has(resolvedPath + "/index.ts"))
+        return resolvedPath + "/index.ts";
+    if (knownFiles.has(resolvedPath + "/index.tsx"))
+        return resolvedPath + "/index.tsx";
+    return null;
+}
+function dedupe(xs) {
+    return [...new Set(xs)];
+}

package/dist/index.js

@@ -33,7 +33,8 @@ import { createOpencode } from "@opencode-ai/sdk";
 import { findFreePort, trackServer, untrackServer, startWithRetry } from "./server-utils.js";
 import { discoverFiles, detectProjectName } from "./discovery.js";
 import { groupFiles } from "./grouping.js";
-import { GroupingAgent } from "./agents/grouping-agent.js";
+import { buildImportGraph } from "./import-graph.js";
+import { loadGroupingPriors } from "./grouping-priors.js";
 import { DocumentationAgent } from "./agents/documentation-agent.js";
 import { ArchitectureAgent } from "./agents/architecture-agent.js";
 import { IndexAgent } from "./agents/index-agent.js";
@@ -511,15 +512,27 @@ export async function handleGenerate(opts, deps = defaultDeps) {
             await waitUntilExit();
             return null;
         }
-        // ── Step 10c: Grouping phase (LLM with heuristic fallback) ─────────
-        const groupingAgent = new GroupingAgent(provider, projectName);
-        let groups = await groupingAgent.run(textFiles, verboseLog, PROJECT_CONFIG_DIR);
-        if (!groups) {
-            if (cliOptions.verbose) {
-                verboseLog(`[grouping] LLM grouping unavailable, using heuristic fallback`);
-            }
-            groups = deps.groupFiles(textFiles);
+        // ── Step 10c: Deterministic grouping (priors + import graph) ──────
+        const priors = await loadGroupingPriors(absoluteDestination);
+        if (cliOptions.verbose && priors.docFolders.length > 0) {
+            verboseLog(`[grouping] ${priors.docFolders.length} doc-folder prior(s): ${priors.docFolders
+                .map((p) => p.name)
+                .join(", ")}`);
+        }
+        if (cliOptions.verbose) {
+            verboseLog(`[grouping] building import graph from ${textFiles.length} files...`);
         }
+        const importGraphStart = Date.now();
+        const importAnalysis = await buildImportGraph(textFiles);
+        if (cliOptions.verbose) {
+            const elapsed = ((Date.now() - importGraphStart) / 1000).toFixed(1);
+            verboseLog(`[grouping] import graph built in ${elapsed}s: ${importAnalysis.localEdges.size} files with local edges, ` +
+                `${importAnalysis.externalImports.size} with external imports`);
+        }
+        const groups = deps.groupFiles(textFiles, {
+            priors,
+            localEdges: importAnalysis.localEdges,
+        });
         const featureGroups = groups.filter((g) => g.type === "vertical").length;
         const layerGroups = groups.filter((g) => g.type === "horizontal").length;
         if (cliOptions.verbose) {

package/dist/orchestrator.d.ts

@@ -16,6 +16,7 @@
  *
  * Reference: FR-005, FR-006, FR-007.
  */
+import { type LimitFunction } from "p-limit";
 import type { ModelSelection, CLIOptions, FileGroup, GenerationContext, GenerationResult, ProgressState, ExplorationFindings } from "./types.js";
 import { createOpencode } from "@opencode-ai/sdk";
 import { DocumentationAgent } from "./agents/documentation-agent.js";
@@ -142,9 +143,15 @@ export declare function filterRelevantDocs(allDocs: Array<{
  * @param onGroupComplete  - Optional callback invoked each time a group's
  *                           exploration finishes successfully. Used by the
  *                           streaming pipeline to launch doc agents eagerly.
+ * @param sharedLimit      - Optional p-limit instance to share with the
+ *                           downstream documentation phase. When omitted, a
+ *                           local instance sized to `computeMaxConcurrency`
+ *                           is created. Passing a shared limit is how the
+ *                           real pipeline prevents exploration + generation
+ *                           from each spawning their own resource budget.
  * @returns All successful `ExplorationFindings[]`.
  */
-export declare function runExploration(explorationAgent: ExplorationAgent, groups: FileGroup[], options: CLIOptions, onProgress: (state: Partial<ProgressState>) => void, onGroupComplete?: (groupId: string, findings: ExplorationFindings) => void): Promise<ExplorationFindings[]>;
+export declare function runExploration(explorationAgent: ExplorationAgent, groups: FileGroup[], options: CLIOptions, onProgress: (state: Partial<ProgressState>) => void, onGroupComplete?: (groupId: string, findings: ExplorationFindings) => void, sharedLimit?: LimitFunction): Promise<ExplorationFindings[]>;
 /**
  * Runs the doc agent for a single file group.
  *

package/dist/orchestrator.js

@@ -390,9 +390,15 @@ async function resolveRelevantDocs(searchIndex, destinationPath, existingDocs, g
  * @param onGroupComplete  - Optional callback invoked each time a group's
  *                           exploration finishes successfully. Used by the
  *                           streaming pipeline to launch doc agents eagerly.
+ * @param sharedLimit      - Optional p-limit instance to share with the
+ *                           downstream documentation phase. When omitted, a
+ *                           local instance sized to `computeMaxConcurrency`
+ *                           is created. Passing a shared limit is how the
+ *                           real pipeline prevents exploration + generation
+ *                           from each spawning their own resource budget.
  * @returns All successful `ExplorationFindings[]`.
  */
-export async function runExploration(explorationAgent, groups, options, onProgress, onGroupComplete) {
+export async function runExploration(explorationAgent, groups, options, onProgress, onGroupComplete, sharedLimit) {
     const sourceRoot = resolve(options.source);
     const verbose = options.verbose
         ? (msg) => {
@@ -403,7 +409,8 @@ export async function runExploration(explorationAgent, groups, options, onProgre
     const effectiveConcurrency = computeMaxConcurrency(options.concurrency);
     if (verbose) {
         verbose(`[orchestrator] Resource limits: ${describeResourceLimits(options.concurrency)}`);
-        verbose(`[orchestrator] Starting exploration: ${groups.length} groups, concurrency=${effectiveConcurrency}`);
+        verbose(`[orchestrator] Starting exploration: ${groups.length} groups, concurrency=${effectiveConcurrency}` +
+            (sharedLimit ? " (shared with generation)" : ""));
     }
     // Build allGroups summary for cross-group awareness
     const allGroups = groups.map((group) => ({
@@ -429,7 +436,7 @@ export async function runExploration(explorationAgent, groups, options, onProgre
         phase: "exploration",
         explorationStatuses: [...explorationStatuses],
     });
-    const limit = pLimit(effectiveConcurrency);
+    const limit = sharedLimit ?? pLimit(effectiveConcurrency);
     // ── Single-agent path (existing behavior, totalFiles < threshold) ──
     if (!isMultiAgent) {
         const results = await Promise.allSettled(groups.map((group, i) => limit(async () => {
@@ -756,6 +763,14 @@ export async function generateDocumentation(agent, groups, options, onProgress,
     }
     // Accumulated findings — grows as explorations complete.
     const allFindings = [];
+    // ── Shared concurrency limit ─────────────────────────────────────
+    // Exploration and documentation run concurrently via the streaming
+    // gate pattern below. Without a shared p-limit each phase would spin
+    // up its own resource budget, doubling the effective concurrency and
+    // OOMing Node on large projects. One semaphore spans both phases so
+    // `computeMaxConcurrency` actually caps total in-flight LLM sessions.
+    const sharedConcurrency = computeMaxConcurrency(options.concurrency);
+    const sharedLimit = pLimit(sharedConcurrency);
     // ── Launch exploration + existingDocs scan in parallel ───────────
     let explorationPromise;
     let existingDocsPromise;
@@ -768,7 +783,7 @@ export async function generateDocumentation(agent, groups, options, onProgress,
         (groupId, findings) => {
             allFindings.push(findings);
             groupGates.get(groupId)?.resolve(findings);
-        });
+        }, sharedLimit);
         // When exploration fully settles, resolve any remaining gates for groups
         // whose exploration failed so their doc agents can proceed without findings.
         // On AuthExpiredError, reject all remaining gates to abort doc agents.
@@ -842,16 +857,15 @@ export async function generateDocumentation(agent, groups, options, onProgress,
         completedSessions: 0,
         failedSessions: 0,
     });
-    const docConcurrency = computeMaxConcurrency(options.concurrency);
     // ── Multi-agent documentation detection ──────────────────────────
     const totalFiles = groups.reduce((sum, g) => sum + g.files.length, 0);
     const docAgentsPerGroup = computeAgentsPerGroup(totalFiles);
     const isMultiAgentDoc = docAgentsPerGroup > 1;
     if (verbose) {
-        verbose(`[orchestrator] Starting documentation: ${groups.length} groups, concurrency=${docConcurrency}` +
+        verbose(`[orchestrator] Starting documentation: ${groups.length} groups, concurrency=${sharedConcurrency} (shared with exploration)` +
             (isMultiAgentDoc ? `, multi-agent=${docAgentsPerGroup} agents/group` : ""));
     }
-    const limit = pLimit(docConcurrency);
+    const limit = sharedLimit;
     const results = await Promise.allSettled(groups.map((group, i) => {
         if (!isMultiAgentDoc) {
             // ── Single-agent path (existing behavior) ──────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pruddiman/hem",
-  "version": "0.0.1-beta-5671db0",
+  "version": "0.0.1-beta-72c22cf",
   "type": "module",
   "bin": {
     "hem": "./dist/index.js"