@pruddiman/hem 0.0.1-beta-5671db0

package/dist/merge-utils.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Merge utilities for combining results from parallel agent runs.
+ *
+ * When a file group is explored by multiple sub-agents in parallel,
+ * their individual ExplorationFindings must be merged into a single
+ * combined result for downstream consumption by the DocumentationAgent.
+ */
+import type { ExplorationFindings } from "./types.js";
+/**
+ * Merges multiple `ExplorationFindings` from parallel exploration agents
+ * covering the same file group into a single combined result.
+ *
+ * The natural-language texts from each agent are concatenated with a
+ * double newline separator so all perspectives are preserved.
+ *
+ * @param findings - Array of findings from multiple exploration agents.
+ *                   Must contain at least one element.
+ * @param groupId  - The group ID to use for the merged result.
+ * @returns A single merged `ExplorationFindings`.
+ * @throws If `findings` is empty.
+ */
+export declare function mergeExplorationFindings(findings: ExplorationFindings[], groupId: string): ExplorationFindings;

package/dist/merge-utils.js

@@ -0,0 +1,34 @@
+/**
+ * Merge utilities for combining results from parallel agent runs.
+ *
+ * When a file group is explored by multiple sub-agents in parallel,
+ * their individual ExplorationFindings must be merged into a single
+ * combined result for downstream consumption by the DocumentationAgent.
+ */
+// ── Exploration Findings Merge ──────────────────────────────────────────
+/**
+ * Merges multiple `ExplorationFindings` from parallel exploration agents
+ * covering the same file group into a single combined result.
+ *
+ * The natural-language texts from each agent are concatenated with a
+ * double newline separator so all perspectives are preserved.
+ *
+ * @param findings - Array of findings from multiple exploration agents.
+ *                   Must contain at least one element.
+ * @param groupId  - The group ID to use for the merged result.
+ * @returns A single merged `ExplorationFindings`.
+ * @throws If `findings` is empty.
+ */
+export function mergeExplorationFindings(findings, groupId) {
+    if (findings.length === 0) {
+        throw new Error("mergeExplorationFindings requires at least one findings object");
+    }
+    if (findings.length === 1) {
+        return { ...findings[0], groupId };
+    }
+    const text = findings
+        .map((f) => f.text.trim())
+        .filter((t) => t.length > 0)
+        .join("\n\n");
+    return { groupId, text };
+}

package/dist/orchestrator.d.ts

@@ -0,0 +1,194 @@
+/**
+ * OpenCode server lifecycle management and documentation generation for Hem.
+ *
+ * Starts the OpenCode server via `createOpencode()` from `@opencode-ai/sdk`,
+ * configures model and permission settings, provides a clean shutdown
+ * mechanism, and orchestrates parallel documentation generation across all
+ * file groups using `p-limit` for concurrency control.
+ *
+ * Architecture (v2):
+ *   - Agents that produce documents write them directly via the edit tool.
+ *   - Agents that return structured data return strict JSON only.
+ *   - The doc agent has full autonomy over file naming, structure, and
+ *     how many files to create per group.
+ *   - Permissions are scoped: `edit: "allow"` + `external_directory`
+ *     restricted to the destination directory for writing agents.
+ *
+ * Reference: FR-005, FR-006, FR-007.
+ */
+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";
+import { ExplorationAgent } from "./agents/exploration-agent.js";
+import type { Provider } from "./providers/index.js";
+import type { SearchIndex } from "./search-index.js";
+export { READ_ONLY_BASH, ORG_AGENT_BASH } from "./providers/index.js";
+/**
+ * Total file count threshold above which multi-agent exploration is activated.
+ * Below this threshold, the existing 1-agent-per-group behavior is used.
+ */
+export declare const LARGE_PROJECT_THRESHOLD = 200;
+/**
+ * Hard ceiling on exploration sub-agents per group.
+ * Actual count is computed by `computeAgentsPerGroup()`.
+ */
+export declare const MAX_EXPLORATION_AGENTS_PER_GROUP = 8;
+/**
+ * Compute the number of sub-agents to use per exploration group based on
+ * total file count. Returns 1 (no splitting) when below the threshold.
+ *
+ * Scaling: starts at 4 agents at the threshold, grows to MAX at 2x the threshold.
+ */
+export declare function computeAgentsPerGroup(totalFiles: number): number;
+/**
+ * Partition a group's files into N sub-groups for parallel exploration.
+ * Uses round-robin assignment (files sorted by path for determinism).
+ * Each sub-group is a new `FileGroup` with id `{group.id}:sub-{n}`.
+ *
+ * Returns the original group as a single-element array if agentCount is 1
+ * or the group has fewer files than MIN_FILES_PER_AGENT * agentCount.
+ */
+export declare function partitionGroupFiles(group: FileGroup, agentCount: number): FileGroup[];
+/**
+ * Merge exploration findings from multiple sub-agents that explored
+ * different partitions of the same group.
+ *
+ * Strategy:
+ *   - `groupId`: use the original group ID (not the sub-agent IDs)
+ *   - `questions`: concatenate, deduplicate by `question` text
+ *   - `integrations`: concatenate, deduplicate by `name`; merge `sourceLocations` and `operationalQuestions` for duplicates
+ *   - `complexitySignals`: concatenate, deduplicate by `description`
+ *   - `crossGroupDependencies`: merge into a Set (unique strings)
+ *   - `styleGuides`: concatenate, deduplicate by `filePath`
+ *   - `summary`: join all summaries with newline separator
+ */
+export declare function mergeExplorationFindings(groupId: string, findingsArray: ExplorationFindings[]): ExplorationFindings;
+/** Options for creating the orchestrator. */
+export interface OrchestratorOptions {
+    /** Absolute path to the destination directory for generated docs. */
+    destinationPath: string;
+}
+/** The result of `createOrchestrator()`. */
+export interface OrchestratorResult {
+    /** The provider instance for creating sessions and sending prompts. */
+    client: Provider;
+    /** Cleanly stops the OpenCode server. */
+    shutdown: () => Promise<void>;
+}
+/** Overridable factory for `createOpencode`, used for testing. */
+export type CreateOpencodeFn = typeof createOpencode;
+/**
+ * Starts the OpenCode server and returns a client with a shutdown function.
+ *
+ * Delegates to {@link OpenCodeProvider} for server lifecycle management,
+ * permission configuration, and MCP tool setup.
+ *
+ * @param model   - The resolved model selection (provider + model ID).
+ * @param options - Orchestrator options including the destination path.
+ * @param factory - Optional `createOpencode` override for testing.
+ * @param findPort - Optional port finder override for testing.
+ * @returns An object with `client` and `shutdown`.
+ * @throws If the OpenCode server fails to start.
+ * @throws If `destinationPath` is empty or blank.
+ */
+export declare function createOrchestrator(model: ModelSelection, options: OrchestratorOptions, factory?: CreateOpencodeFn, findPort?: () => Promise<number>): Promise<OrchestratorResult>;
+/**
+ * Scans the destination directory for existing `.md` files and reads
+ * their content. Used to provide merge context to the doc agent.
+ *
+ * @param destinationPath - Absolute path to the documentation destination.
+ * @param verbose         - Optional verbose logger.
+ * @returns An array of `{ path, content }` for each existing `.md` file.
+ */
+export declare function scanExistingDocs(destinationPath: string, verbose?: (msg: string) => void): Promise<Array<{
+    path: string;
+    content: string;
+}>>;
+/**
+ * Filters the full set of existing docs down to the most relevant subset
+ * for a specific file group.
+ *
+ * Returns:
+ *  - `relevantDocs`: up to `MAX_RELEVANT_DOCS` docs with full content,
+ *     sorted by relevance score (highest first).
+ *  - `mentionedPaths`: paths of remaining docs (no content) so the agent
+ *     knows they exist.
+ *
+ * Relevance is scored by path overlap with the group's files/directory,
+ * label/ID keyword matches in the doc heading, and topic keyword overlap
+ * from the group's exploration findings.
+ */
+export declare function filterRelevantDocs(allDocs: Array<{
+    path: string;
+    content: string;
+}>, group: FileGroup, groupFindings: ExplorationFindings | undefined): {
+    relevantDocs: Array<{
+        path: string;
+        content: string;
+    }>;
+    mentionedPaths: string[];
+};
+/**
+ * Runs the exploration phase for all groups in parallel.
+ *
+ * Each group gets its own ExplorationAgent session. Results are collected
+ * via `Promise.allSettled` — failed explorations are logged as warnings
+ * but do not abort the pipeline.
+ *
+ * @param explorationAgent - The exploration agent instance.
+ * @param groups           - The file groups to explore.
+ * @param options          - CLI options including source path and concurrency.
+ * @param onProgress       - Callback to update progress state.
+ * @param onGroupComplete  - Optional callback invoked each time a group's
+ *                           exploration finishes successfully. Used by the
+ *                           streaming pipeline to launch doc agents eagerly.
+ * @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[]>;
+/**
+ * Runs the doc agent for a single file group.
+ *
+ * The agent writes documentation files directly via the edit tool.
+ * The pipeline discovers what was produced by scanning the destination
+ * directory afterward.
+ *
+ * @param agent           - The documentation agent instance.
+ * @param group           - The file group to document.
+ * @param context         - Shared generation context.
+ * @param verbose         - Optional verbose logger.
+ * @returns A `GenerationResult` indicating success or failure.
+ */
+export declare function runDocAgent(agent: DocumentationAgent, group: FileGroup, context: GenerationContext, verbose?: (msg: string) => void): Promise<GenerationResult>;
+/**
+ * Generates documentation for all file groups in parallel.
+ *
+ * Implements a streaming pipeline that overlaps exploration and documentation:
+ *   - **Exploration + existing docs scan** run in parallel.
+ *   - **Documentation** for each group starts as soon as its exploration
+ *     finishes, rather than waiting for all explorations to complete.
+ *   - Each doc agent receives accumulated exploration findings at launch time.
+ *
+ * When no `explorationAgent` is provided, all doc agents launch immediately.
+ *
+ * @param agent              - The documentation agent instance.
+ * @param groups             - The file groups to document.
+ * @param options            - CLI options including source/destination paths.
+ * @param onProgress         - Callback to update progress state.
+ * @param explorationAgent   - Optional exploration agent.
+ * @returns Results, exploration findings, and existing docs.
+ */
+export declare function generateDocumentation(agent: DocumentationAgent, groups: FileGroup[], options: CLIOptions, onProgress: (state: Partial<ProgressState>) => void, explorationAgent?: ExplorationAgent, searchIndex?: SearchIndex): Promise<{
+    results: GenerationResult[];
+    explorationFindings: ExplorationFindings[];
+    existingDocs: Array<{
+        path: string;
+        content: string;
+    }>;
+}>;
+/**
+ * Determine the exit code from documentation generation results.
+ *
+ * @param results - Generation results for all groups.
+ * @returns 0 if all succeeded, 1 if some failed, 2 if all failed or empty.
+ */
+export declare function getExitCode(results: GenerationResult[]): number;