@pruddiman/hem 0.0.1-beta-5671db0

package/dist/discovery.js

@@ -0,0 +1,405 @@
+/**
+ * File discovery module for Hem.
+ *
+ * Scans a source directory for files matching a glob pattern, classifies
+ * each file as text or binary, and returns a `FileInfo[]` array.
+ *
+ * Also provides `detectProjectName()` for inferring the project name
+ * from manifest files (package.json, Cargo.toml, etc.) in ancestor
+ * directories of the source path.
+ *
+ * Reference: FR-002 (file scanning), FR-014 (binary detection), FR-015 (destination exclusion).
+ */
+import { resolve, relative, extname, basename, dirname, join } from "node:path";
+import { stat, open, readFile, access } from "node:fs/promises";
+import fg from "fast-glob";
+import { isPathWithin } from "./helpers/paths.js";
+/**
+ * Directories that are almost always irrelevant to documentation and
+ * should be excluded from file discovery regardless of .gitignore.
+ */
+const DEFAULT_IGNORE_PATTERNS = [
+    "**/node_modules/**",
+    "**/.git/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/coverage/**",
+    "**/.cache/**",
+    "**/.tmp/**",
+];
+/**
+ * Known binary file extensions.
+ *
+ * Files with any of these extensions are classified as binary without
+ * reading their contents. The set covers images, fonts, audio/video,
+ * archives, executables, and compiled artifacts.
+ */
+const BINARY_EXTENSIONS = new Set([
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".bmp",
+    ".ico",
+    ".svg",
+    ".woff",
+    ".woff2",
+    ".ttf",
+    ".eot",
+    ".mp3",
+    ".mp4",
+    ".avi",
+    ".mov",
+    ".zip",
+    ".tar",
+    ".gz",
+    ".pdf",
+    ".exe",
+    ".dll",
+    ".so",
+    ".dylib",
+    ".o",
+    ".class",
+    ".pyc",
+    ".wasm",
+]);
+/**
+ * Detects whether a file is binary by checking the first 512 bytes for
+ * null bytes (`0x00`). This heuristic is used only for files whose
+ * extension is not in the known binary list.
+ *
+ * @param absolutePath - Absolute path to the file.
+ * @returns `true` if null bytes are found (likely binary).
+ */
+async function detectBinaryByContent(absolutePath) {
+    let fh;
+    try {
+        fh = await open(absolutePath, "r");
+        const buffer = Buffer.alloc(512);
+        const { bytesRead } = await fh.read(buffer, 0, 512, 0);
+        for (let i = 0; i < bytesRead; i++) {
+            if (buffer[i] === 0x00) {
+                return true;
+            }
+        }
+        return false;
+    }
+    catch {
+        // If we can't read the file, treat it as non-binary so it still
+        // shows up in results (the caller can handle read errors later).
+        return false;
+    }
+    finally {
+        try {
+            await fh?.close();
+        }
+        catch {
+            // Best-effort close; ignore failure to avoid masking the main return value
+            // or (in the catch branch above) the original read error.
+        }
+    }
+}
+/**
+ * Determines whether a file is binary based on its extension and,
+ * when the extension is not in the known list, by inspecting the
+ * first 512 bytes for null bytes.
+ *
+ * @param absolutePath - Absolute path to the file.
+ * @param extension - File extension including the leading dot.
+ * @returns `true` if the file is binary.
+ */
+async function isBinaryFile(absolutePath, extension) {
+    if (BINARY_EXTENSIONS.has(extension.toLowerCase())) {
+        return true;
+    }
+    // For files with no extension or an unrecognised extension, fall back
+    // to the content-based heuristic.
+    if (extension === "" || !extension.startsWith(".")) {
+        return detectBinaryByContent(absolutePath);
+    }
+    return false;
+}
+/**
+ * Discovers source files within `sourcePath` that match the given glob
+ * pattern. Each file is classified as binary or text and returned as a
+ * `FileInfo` object.
+ *
+ * Key behaviours:
+ *   - `sourcePath` and `destinationPath` are resolved to absolute paths.
+ *   - Files within `destinationPath` are excluded when the destination
+ *     overlaps with the source (FR-015).
+ *   - Binary files are included in the returned array with
+ *     `isBinary: true` so callers can count/warn about them.
+ *
+ * @param sourcePath - Root directory to scan.
+ * @param globPattern - Glob pattern relative to `sourcePath`.
+ * @param destinationPath - Destination directory for generated docs
+ *   (excluded from results when overlapping with source).
+ * @returns Array of `FileInfo` objects for every matched file.
+ */
+export async function discoverFiles(sourcePath, globPattern, destinationPath) {
+    const absoluteSource = resolve(sourcePath);
+    const absoluteDestination = resolve(destinationPath);
+    // FR-015: When the destination directory overlaps with or is inside
+    // the source directory, add it as an ignore pattern so fast-glob
+    // skips those files entirely (better performance than post-hoc
+    // filtering for large trees). We also keep a post-hoc safety check
+    // below as a defence-in-depth measure.
+    const destIgnorePatterns = [];
+    if (isPathWithin(absoluteDestination, absoluteSource)) {
+        const relDest = relative(absoluteSource, absoluteDestination);
+        // fast-glob ignore patterns are relative to cwd.
+        destIgnorePatterns.push(relDest === "" ? "**/*" : `${relDest}/**`);
+    }
+    const gitignorePatterns = await loadGitignorePatterns(absoluteSource);
+    const allIgnorePatterns = [
+        ...DEFAULT_IGNORE_PATTERNS,
+        ...destIgnorePatterns,
+        ...gitignorePatterns,
+    ];
+    // Use fast-glob to discover files. The `cwd` option makes the
+    // pattern relative to the source directory. `dot: true` includes
+    // dotfiles; `onlyFiles: true` excludes directories.
+    const matches = await fg(globPattern, {
+        cwd: absoluteSource,
+        onlyFiles: true,
+        dot: true,
+        absolute: true,
+        ignore: allIgnorePatterns,
+    });
+    const results = [];
+    for (const absolutePath of matches) {
+        // Defence-in-depth: exclude files inside the destination directory
+        // even if fast-glob's ignore didn't catch them (e.g., symlinks,
+        // race conditions, or destination outside source that somehow
+        // appeared in results).
+        if (isPathWithin(absolutePath, absoluteDestination)) {
+            continue;
+        }
+        const relativePath = relative(absoluteSource, absolutePath);
+        const extension = extname(absolutePath);
+        let fileSize;
+        try {
+            const fileStat = await stat(absolutePath);
+            fileSize = fileStat.size;
+        }
+        catch {
+            // Skip files we cannot stat (e.g., broken symlinks).
+            continue;
+        }
+        const binary = await isBinaryFile(absolutePath, extension);
+        results.push({
+            path: relativePath,
+            absolutePath,
+            extension,
+            size: fileSize,
+            isBinary: binary,
+        });
+    }
+    // Sort by relative path for deterministic ordering.
+    results.sort((a, b) => a.path.localeCompare(b.path));
+    return results;
+}
+// ── Project name detection ──────────────────────────────────────────────
+/**
+ * Maximum number of ancestor directories to walk when searching for
+ * manifest files. Prevents runaway traversal.
+ */
+const MAX_WALK_DEPTH = 5;
+/**
+ * Common directory basenames that are poor project names.
+ * If `basename(sourcePath)` matches one of these, we look harder.
+ */
+const GENERIC_DIR_NAMES = new Set([
+    "src",
+    "lib",
+    "app",
+    "source",
+    "sources",
+    "code",
+    "packages",
+    "modules",
+    "internal",
+    "cmd",
+    "pkg",
+]);
+/**
+ * Reads .gitignore at `dir` and converts its patterns to fast-glob
+ * ignore patterns. Returns an empty array if the file is absent.
+ * @internal
+ */
+async function loadGitignorePatterns(dir) {
+    const content = await tryReadFile(join(dir, ".gitignore"));
+    if (!content)
+        return [];
+    return content
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && !line.startsWith("#") && !line.startsWith("!"))
+        .flatMap((pattern) => {
+        // Strip leading slash — gitignore root-anchors with /, fast-glob uses cwd
+        const p = pattern.startsWith("/") ? pattern.slice(1) : pattern;
+        const bare = p.replace(/\/$/, "");
+        // Patterns with no interior slash match anywhere in the tree
+        const hasInteriorSlash = bare.includes("/");
+        if (!hasInteriorSlash) {
+            return [`**/${bare}`, `**/${bare}/**`];
+        }
+        return [bare, `${bare}/**`];
+    });
+}
+/**
+ * Try to read a file at `filePath` and return its text content,
+ * or `undefined` if the file does not exist or cannot be read.
+ * @internal
+ */
+async function tryReadFile(filePath) {
+    try {
+        return await readFile(filePath, "utf-8");
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Extract the project name from a `package.json` file.
+ * Returns `undefined` if the file is missing, malformed, or the
+ * `name` field is absent/empty.
+ * @internal
+ */
+async function nameFromPackageJson(dir) {
+    const content = await tryReadFile(join(dir, "package.json"));
+    if (!content)
+        return undefined;
+    try {
+        const pkg = JSON.parse(content);
+        const raw = pkg.name;
+        if (typeof raw !== "string" || raw.trim().length === 0)
+            return undefined;
+        // Scoped packages: "@scope/foo" → "foo"
+        const name = raw.trim();
+        const slashIdx = name.indexOf("/");
+        return slashIdx >= 0 ? name.slice(slashIdx + 1) : name;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Extract the project name from a `Cargo.toml` file.
+ * Uses a simple regex — avoids pulling in a TOML parser.
+ * @internal
+ */
+async function nameFromCargoToml(dir) {
+    const content = await tryReadFile(join(dir, "Cargo.toml"));
+    if (!content)
+        return undefined;
+    // Match `name = "..."` under `[package]` section
+    const packageMatch = content.match(/\[package\][^[]*?name\s*=\s*"([^"]+)"/s);
+    return packageMatch?.[1] || undefined;
+}
+/**
+ * Extract the project name from a `pyproject.toml` file.
+ * Checks `[project]` and `[tool.poetry]` sections.
+ * @internal
+ */
+async function nameFromPyprojectToml(dir) {
+    const content = await tryReadFile(join(dir, "pyproject.toml"));
+    if (!content)
+        return undefined;
+    // Try [project] section first
+    const projectMatch = content.match(/\[project\][^[]*?name\s*=\s*"([^"]+)"/s);
+    if (projectMatch?.[1])
+        return projectMatch[1];
+    // Try [tool.poetry] section
+    const poetryMatch = content.match(/\[tool\.poetry\][^[]*?name\s*=\s*"([^"]+)"/s);
+    return poetryMatch?.[1] || undefined;
+}
+/**
+ * Extract the project name from a `go.mod` file.
+ * The module path's last segment is used as the name.
+ * @internal
+ */
+async function nameFromGoMod(dir) {
+    const content = await tryReadFile(join(dir, "go.mod"));
+    if (!content)
+        return undefined;
+    const moduleMatch = content.match(/^module\s+(\S+)/m);
+    if (!moduleMatch?.[1])
+        return undefined;
+    const modulePath = moduleMatch[1];
+    const lastSegment = modulePath.split("/").pop();
+    return lastSegment || undefined;
+}
+/**
+ * Check whether a `.git` directory exists at the given path.
+ * @internal
+ */
+async function hasGitDir(dir) {
+    try {
+        await access(join(dir, ".git"));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Detect the project name by walking up from the source directory
+ * and inspecting manifest files.
+ *
+ * Detection priority (first match wins):
+ *   1. `package.json` → `name` field (scoped names stripped)
+ *   2. `Cargo.toml` → `[package] name`
+ *   3. `pyproject.toml` → `[project] name` or `[tool.poetry] name`
+ *   4. `go.mod` → last segment of module path
+ *
+ * The walk starts at the parent of `sourcePath` (since `sourcePath`
+ * itself is typically `src/` or similar) and continues up to the
+ * git root or a maximum of {@link MAX_WALK_DEPTH} levels.
+ *
+ * If no manifest is found, falls back to the basename of the
+ * directory containing the first manifest-like file, the parent
+ * directory, or ultimately `basename(sourcePath)`.
+ *
+ * @param sourcePath - The absolute source directory path.
+ * @returns The detected project name.
+ */
+export async function detectProjectName(sourcePath) {
+    const absoluteSource = resolve(sourcePath);
+    let dir = dirname(absoluteSource); // Start at parent of source
+    const detectors = [
+        nameFromPackageJson,
+        nameFromCargoToml,
+        nameFromPyprojectToml,
+        nameFromGoMod,
+    ];
+    for (let depth = 0; depth < MAX_WALK_DEPTH; depth++) {
+        // Try each manifest detector at this directory level
+        for (const detect of detectors) {
+            const name = await detect(dir);
+            if (name)
+                return name;
+        }
+        // If we hit a .git directory, this is the repo root — stop walking
+        if (await hasGitDir(dir)) {
+            // Use the repo root directory name as project name
+            const repoName = basename(dir);
+            if (repoName && !GENERIC_DIR_NAMES.has(repoName.toLowerCase())) {
+                return repoName;
+            }
+            break;
+        }
+        // Move up one level
+        const parent = dirname(dir);
+        if (parent === dir)
+            break; // Reached filesystem root
+        dir = parent;
+    }
+    // Fallback chain: parent basename → source basename
+    const parentName = basename(dirname(absoluteSource));
+    if (parentName && !GENERIC_DIR_NAMES.has(parentName.toLowerCase())) {
+        return parentName;
+    }
+    return basename(absoluteSource);
+}

package/dist/grouping.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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.
+ *
+ * Reference: FR-003, data-model.md lines 93-108.
+ */
+import type { FileInfo, FileGroup } from "./types.js";
+/**
+ * Finds the common parent directory for a set of file paths.
+ *
+ * @param files - Array of FileInfo objects.
+ * @returns The common parent directory (relative path), or `"."` for root.
+ */
+export declare function commonDirectory(files: FileInfo[]): 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.
+ *
+ * @param files - Discovered files (may include binary files).
+ * @returns Array of `FileGroup` objects.
+ */
+export declare function groupFiles(files: FileInfo[]): FileGroup[];