gitnexushub 0.4.5 → 0.6.0

package/dist/wiki/incremental.d.ts

@@ -0,0 +1,72 @@
+import type { HubAPI } from '../api.js';
+export interface FileDiff {
+    added: string[];
+    modified: string[];
+    deleted: string[];
+}
+/**
+ * Run `git diff --name-status <from>..<to>` in `repoRoot` and classify
+ * changed files as added/modified/deleted. Renames (R100) are treated
+ * as delete+add so both source and destination modules are re-generated.
+ * Returns null on any git failure — caller should fall back to a full
+ * regeneration.
+ */
+export declare function diffChangedFiles(repoRoot: string, fromCommit: string, toCommit: string): FileDiff | null;
+export interface TreeNode {
+    name: string;
+    slug: string;
+    files: string[];
+    children?: TreeNode[];
+}
+export interface FilterResult {
+    /** Subset of the tree's leaf nodes whose pages need regenerating. */
+    affected: TreeNode[];
+    /** The tree with deleted files removed and unmapped new files added to "Other". */
+    tree: TreeNode[];
+}
+/**
+ * Walk `prevTree` and determine which leaf modules are affected by `diff`.
+ * - Modified/deleted files → their containing module is affected.
+ * - Added files → if >5 can't be mapped to an existing module, return null
+ *   (caller falls back to full gen). ≤5 unmapped are appended to an "Other"
+ *   module (created if absent).
+ * - Empty modules (all files deleted) are dropped from the returned tree.
+ */
+export declare function filterAffectedModules(diff: FileDiff, prevTree: TreeNode[]): FilterResult | null;
+export interface IncrementalUploadInput {
+    repoId: string;
+    repoRoot: string;
+    headCommit: string;
+    clientVersion: string;
+    clientModel: string;
+    api: HubAPI;
+    regenerateModule: (node: TreeNode) => Promise<{
+        title: string;
+        contentMd: string;
+    }>;
+    regenerateOverview: (tree: TreeNode[]) => Promise<{
+        title: string;
+        contentMd: string;
+    }>;
+    /** Reuse a status already fetched by the caller. Avoids a redundant API round-trip. */
+    precomputedStatus?: {
+        fromCommit?: string | null;
+    } | null;
+    /** Reuse a diff already computed by the caller. Avoids a redundant git diff. */
+    precomputedDiff?: FileDiff | null;
+}
+export type IncrementalUploadResult = {
+    status: 'ok';
+    sessionId: string;
+    pagesPersisted: number;
+} | {
+    status: 'fallback-full';
+};
+/**
+ * Run an incremental wiki upload: compare local HEAD to the Hub's recorded
+ * fromCommit, regenerate only affected modules, upload via incremental session.
+ * On any signal that the local or remote state can't support an incremental
+ * update (no prior wiki, divergent branch, too many new unmapped files),
+ * returns { status: 'fallback-full' } and the caller should run full gen.
+ */
+export declare function tryIncrementalUpload(input: IncrementalUploadInput): Promise<IncrementalUploadResult>;

package/dist/wiki/incremental.js

@@ -0,0 +1,214 @@
+import { execFileSync } from 'child_process';
+/**
+ * Run `git diff --name-status <from>..<to>` in `repoRoot` and classify
+ * changed files as added/modified/deleted. Renames (R100) are treated
+ * as delete+add so both source and destination modules are re-generated.
+ * Returns null on any git failure — caller should fall back to a full
+ * regeneration.
+ */
+export function diffChangedFiles(repoRoot, fromCommit, toCommit) {
+    let raw;
+    try {
+        raw = execFileSync('git', ['diff', '--name-status', '-M', `${fromCommit}..${toCommit}`], {
+            cwd: repoRoot,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+    }
+    catch {
+        return null;
+    }
+    const added = [];
+    const modified = [];
+    const deleted = [];
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        const parts = line.split('\t');
+        const code = parts[0] ?? '';
+        if (code === 'A') {
+            added.push(parts[1]);
+        }
+        else if (code === 'M') {
+            modified.push(parts[1]);
+        }
+        else if (code === 'D') {
+            deleted.push(parts[1]);
+        }
+        else if (code.startsWith('R')) {
+            if (parts[1])
+                deleted.push(parts[1]);
+            if (parts[2])
+                added.push(parts[2]);
+        }
+    }
+    return { added, modified, deleted };
+}
+/**
+ * Walk `prevTree` and determine which leaf modules are affected by `diff`.
+ * - Modified/deleted files → their containing module is affected.
+ * - Added files → if >5 can't be mapped to an existing module, return null
+ *   (caller falls back to full gen). ≤5 unmapped are appended to an "Other"
+ *   module (created if absent).
+ * - Empty modules (all files deleted) are dropped from the returned tree.
+ */
+export function filterAffectedModules(diff, prevTree) {
+    // Deep copy the tree so we can mutate.
+    const tree = JSON.parse(JSON.stringify(prevTree));
+    // Build file→node lookup (leaves only).
+    const fileToLeaf = new Map();
+    const leaves = [];
+    const walkLeaves = (nodes) => {
+        for (const n of nodes) {
+            if (n.children && n.children.length > 0) {
+                walkLeaves(n.children);
+            }
+            else {
+                leaves.push(n);
+                for (const f of n.files)
+                    fileToLeaf.set(f, n);
+            }
+        }
+    };
+    walkLeaves(tree);
+    const affected = new Set();
+    for (const fp of diff.modified) {
+        const leaf = fileToLeaf.get(fp);
+        if (leaf)
+            affected.add(leaf);
+    }
+    for (const fp of diff.deleted) {
+        const leaf = fileToLeaf.get(fp);
+        if (leaf) {
+            leaf.files = leaf.files.filter((f) => f !== fp);
+            affected.add(leaf);
+        }
+    }
+    // Classify added files.
+    const unmapped = [];
+    for (const fp of diff.added) {
+        // Try to place it in an existing leaf whose files share the deepest prefix.
+        const leaf = findClosestLeaf(fp, leaves);
+        if (leaf) {
+            leaf.files.push(fp);
+            affected.add(leaf);
+        }
+        else {
+            unmapped.push(fp);
+        }
+    }
+    if (unmapped.length > 5)
+        return null;
+    if (unmapped.length > 0) {
+        let other = tree.find((n) => n.slug === 'other');
+        if (!other) {
+            other = { name: 'Other', slug: 'other', files: [] };
+            tree.push(other);
+            leaves.push(other);
+        }
+        other.files.push(...unmapped);
+        affected.add(other);
+    }
+    // Drop leaves with no files and propagate to parents.
+    const pruneEmpty = (nodes) => nodes
+        .map((n) => {
+        if (n.children) {
+            n.children = pruneEmpty(n.children);
+            return n.children.length === 0 && n.files.length === 0 ? null : n;
+        }
+        return n.files.length === 0 ? null : n;
+    })
+        .filter((n) => n !== null);
+    const prunedTree = pruneEmpty(tree);
+    return {
+        affected: Array.from(affected).filter((n) => n.files.length > 0),
+        tree: prunedTree,
+    };
+}
+/**
+ * Find the leaf whose existing files share the longest common directory prefix
+ * with `newFile`. Returns null when no leaf has any common prefix.
+ */
+function findClosestLeaf(newFile, leaves) {
+    const newParts = newFile.replace(/\\/g, '/').split('/');
+    let bestLeaf = null;
+    let bestDepth = 0;
+    for (const leaf of leaves) {
+        for (const f of leaf.files) {
+            const parts = f.replace(/\\/g, '/').split('/');
+            let depth = 0;
+            while (depth < newParts.length && depth < parts.length && newParts[depth] === parts[depth]) {
+                depth++;
+            }
+            // Only count if we matched at least 2 directory components (e.g., src/auth).
+            // A match on just "src" alone is too broad.
+            if (depth >= 2 && depth > bestDepth) {
+                bestDepth = depth;
+                bestLeaf = leaf;
+            }
+        }
+    }
+    return bestLeaf;
+}
+/**
+ * Run an incremental wiki upload: compare local HEAD to the Hub's recorded
+ * fromCommit, regenerate only affected modules, upload via incremental session.
+ * On any signal that the local or remote state can't support an incremental
+ * update (no prior wiki, divergent branch, too many new unmapped files),
+ * returns { status: 'fallback-full' } and the caller should run full gen.
+ */
+export async function tryIncrementalUpload(input) {
+    const status = input.precomputedStatus ?? (await input.api.wikiStatus(input.repoId));
+    if (!status?.fromCommit)
+        return { status: 'fallback-full' };
+    const treeResp = await input.api.wikiTree(input.repoId);
+    if (!treeResp?.tree?.length)
+        return { status: 'fallback-full' };
+    const diff = input.precomputedDiff ?? diffChangedFiles(input.repoRoot, status.fromCommit, input.headCommit);
+    if (!diff)
+        return { status: 'fallback-full' };
+    const filtered = filterAffectedModules(diff, treeResp.tree);
+    if (!filtered)
+        return { status: 'fallback-full' };
+    const session = await input.api.wikiUploadStart(input.repoId, {
+        mode: 'incremental',
+        fromCommit: input.headCommit,
+        clientVersion: input.clientVersion,
+        clientModel: input.clientModel,
+    });
+    if (filtered.affected.length === 0) {
+        await input.api.wikiUploadFinish(input.repoId, session.sessionId, {
+            moduleTree: filtered.tree,
+            receivedSlugs: [],
+        });
+        return { status: 'ok', sessionId: session.sessionId, pagesPersisted: 0 };
+    }
+    const receivedSlugs = [];
+    try {
+        for (const node of filtered.affected) {
+            const page = await input.regenerateModule(node);
+            await input.api.wikiUploadPage(input.repoId, session.sessionId, {
+                slug: node.slug,
+                title: page.title,
+                contentMd: page.contentMd,
+            });
+            receivedSlugs.push(node.slug);
+        }
+        const overview = await input.regenerateOverview(filtered.tree);
+        await input.api.wikiUploadPage(input.repoId, session.sessionId, {
+            slug: 'overview',
+            title: overview.title,
+            contentMd: overview.contentMd,
+        });
+        receivedSlugs.push('overview');
+    }
+    catch (err) {
+        await input.api.wikiUploadAbort(input.repoId, session.sessionId).catch(() => { });
+        throw err;
+    }
+    const finished = await input.api.wikiUploadFinish(input.repoId, session.sessionId, {
+        moduleTree: filtered.tree,
+        receivedSlugs,
+    });
+    return { status: 'ok', sessionId: session.sessionId, pagesPersisted: finished.pagesPersisted };
+}

package/dist/wiki/index.js

@@ -97,6 +97,43 @@ export function registerWikiCommand(program) {
             reportError(err);
         }
     });
+    wiki
+        .command('dry-run')
+        .description('Generate the wiki locally and write it to a single markdown file — nothing is uploaded to the Hub')
+        .option('--output <path>', 'output markdown file', 'wiki-dry-run.md')
+        .option('--model <model>', 'Claude model to use', REAL_DEFAULT_MODEL)
+        .action(async (opts) => {
+        const cwd = process.cwd();
+        const deps = buildRealDeps(cwd);
+        if (opts.model)
+            deps.model = opts.model;
+        const ac = new AbortController();
+        const onSig = () => {
+            warn('interrupt received, aborting dry run...');
+            ac.abort();
+        };
+        process.on('SIGINT', onSig);
+        process.on('SIGTERM', onSig);
+        try {
+            info(`Resolving repo context...`);
+            const result = await runWikiUpload({
+                cwd,
+                mode: 'full',
+                model: opts.model,
+                abortSignal: ac.signal,
+                dryRunOutputPath: opts.output,
+            }, deps);
+            ok(`Dry-run complete: ${result.pagesPersisted} pages written to ${opts.output}`);
+            info('Nothing was uploaded to the Hub.');
+        }
+        catch (err) {
+            reportError(err);
+        }
+        finally {
+            process.off('SIGINT', onSig);
+            process.off('SIGTERM', onSig);
+        }
+    });
     wiki
         .command('abort')
         .description('Abort the active wiki upload session for the current repo')

package/dist/wiki/session.d.ts

@@ -21,10 +21,20 @@ export interface RunSessionDeps {
     modules: ModuleNode[];
     moduleTree: unknown;
     generatePage: GeneratePageFn;
+    /**
+     * Number of leading `modules[]` entries that may run in parallel (leaves).
+     * Remaining modules (parents + overview) always run sequentially because
+     * they depend on prior phase outputs via extractSummary. Defaults to 0 —
+     * fully sequential, matching original behavior.
+     */
+    parallelCount?: number;
+    /** Max concurrent tasks within the parallel phase. Defaults to 1. */
+    concurrency?: number;
     onSessionStart?: (sessionId: string) => void;
     onPageStart?: (slug: string) => void;
     onPageDone?: (slug: string, bytes: number) => void;
     onPageFail?: (slug: string, err: unknown) => void;
+    onRateLimit?: (newConcurrency: number) => void;
 }
 export interface RunSessionResult {
     sessionId: string;

package/dist/wiki/session.js

@@ -1,4 +1,5 @@
 import { GnxError, ErrorCode } from './errors.js';
+import { runConcurrent } from './concurrency.js';
 export async function runWikiUploadSession(deps) {
     const { api, repoId } = deps;
     const started = await api.wikiUploadStart(repoId, {
@@ -12,21 +13,22 @@ export async function runWikiUploadSession(deps) {
     const receivedSlugs = [];
     const failedSlugs = [];
     let aborted = false;
+    let uploadError = null;
     const abortOnce = async (reason) => {
         if (aborted)
             return;
         aborted = true;
+        uploadError = reason;
         try {
             await api.wikiUploadAbort(repoId, sessionId);
         }
         catch {
             /* ignore secondary errors */
         }
-        throw reason instanceof Error
-            ? reason
-            : new GnxError(ErrorCode.GENERATION_FAILED, String(reason));
     };
-    for (const mod of deps.modules) {
+    const processModule = async (mod) => {
+        if (aborted)
+            return;
         deps.onPageStart?.(mod.slug);
         let page;
         try {
@@ -41,13 +43,13 @@ export async function runWikiUploadSession(deps) {
             }
             catch (err2) {
                 deps.onPageFail?.(mod.slug, err2);
-                continue;
+                return;
             }
         }
         if (!page.contentMd || !page.contentMd.trim()) {
             failedSlugs.push(mod.slug);
             deps.onPageFail?.(mod.slug, new Error('empty generation result'));
-            continue;
+            return;
         }
         try {
             await api.wikiUploadPage(repoId, sessionId, {
@@ -55,16 +57,94 @@ export async function runWikiUploadSession(deps) {
                 title: page.title,
                 contentMd: page.contentMd,
             });
-            receivedSlugs.push(mod.slug);
-            deps.onPageDone?.(mod.slug, Buffer.byteLength(page.contentMd, 'utf8'));
+            if (!aborted) {
+                receivedSlugs.push(mod.slug);
+                deps.onPageDone?.(mod.slug, Buffer.byteLength(page.contentMd, 'utf8'));
+            }
         }
         catch (err) {
             await abortOnce(err);
         }
+    };
+    const parallelCount = Math.max(0, Math.min(deps.parallelCount ?? 0, deps.modules.length));
+    const concurrency = Math.max(1, deps.concurrency ?? 1);
+    const parallelModules = deps.modules.slice(0, parallelCount);
+    const sequentialModules = deps.modules.slice(parallelCount);
+    if (parallelModules.length > 0) {
+        try {
+            await runConcurrent(parallelModules, processModule, {
+                concurrency,
+                onRateLimit: deps.onRateLimit,
+            });
+        }
+        catch (err) {
+            // runConcurrent only rejects on non-429 errors from processModule. Since
+            // processModule already swallows generation errors and routes upload
+            // errors through abortOnce, this branch only fires for truly unexpected
+            // rejections. Ensure the session is aborted before rethrowing.
+            if (!aborted)
+                await abortOnce(err);
+        }
+        // If every leaf failed generation, bail out before running the sequential
+        // phase. Parents and overview read leaf content via extractSummary — without
+        // any leaves they'd emit "(Documentation not yet generated)" placeholders
+        // and the session would "succeed" with a garbage wiki. failedSlugs may be
+        // non-zero here, but the real signal is whether anything was uploaded.
+        if (!aborted && receivedSlugs.length === 0) {
+            await abortOnce(new GnxError(ErrorCode.GENERATION_FAILED, `all ${parallelModules.length} leaf page(s) failed to generate`));
+        }
     }
-    if (receivedSlugs.length === 0) {
+    // Phase 5.1 (connect mirror): parents run in parallel too. They read leaf
+    // content via extractSummary on already-uploaded leaf pages — the Hub
+    // persists every leaf synchronously inside wikiUploadPage, so by the time
+    // the leaf phase resolves all leaves are durable and parents can fetch
+    // them independently.
+    //
+    // Overview is the one exception: it summarises parents AND leaves, so it
+    // must run after both. The upload-command contract places the overview
+    // entry as the trailing element of `modules`. We respect that here by
+    // peeling it off the end and running it after the parent fan-out.
+    // If the caller doesn't follow that contract (e.g. unit tests with
+    // arbitrary module ordering), we fall back to the original sequential
+    // semantics so behavior stays predictable.
+    if (!aborted) {
+        const tail = sequentialModules[sequentialModules.length - 1];
+        const overviewIsTrailing = tail?.slug === 'overview';
+        if (overviewIsTrailing) {
+            const parentMods = sequentialModules.slice(0, -1);
+            if (parentMods.length > 0) {
+                try {
+                    await runConcurrent(parentMods, processModule, {
+                        concurrency,
+                        onRateLimit: deps.onRateLimit,
+                    });
+                }
+                catch (err) {
+                    if (!aborted)
+                        await abortOnce(err);
+                }
+            }
+            if (!aborted) {
+                await processModule(tail);
+            }
+        }
+        else {
+            // Legacy ordering: process every sequential module in declared order.
+            for (const mod of sequentialModules) {
+                if (aborted)
+                    break;
+                await processModule(mod);
+            }
+        }
+    }
+    if (uploadError === null && receivedSlugs.length === 0) {
         await abortOnce(new GnxError(ErrorCode.GENERATION_FAILED, 'no pages were generated successfully'));
     }
+    if (uploadError !== null) {
+        throw uploadError instanceof Error
+            ? uploadError
+            : new GnxError(ErrorCode.GENERATION_FAILED, String(uploadError));
+    }
     const finished = await api.wikiUploadFinish(repoId, sessionId, {
         moduleTree: deps.moduleTree,
         receivedSlugs,

package/dist/wiki/upload-command.d.ts

@@ -5,6 +5,18 @@ export interface RunWikiUploadOptions {
     mode?: 'full' | 'incremental';
     model?: string;
     abortSignal?: AbortSignal;
+    /**
+     * When set, skip the upload session entirely: generate every page and write
+     * the concatenated markdown to this path. Hub `wiki_pages` is untouched.
+     * Always uses full-generation mode regardless of `mode`.
+     */
+    dryRunOutputPath?: string;
+    /**
+     * Max concurrent Claude Code calls for leaf-page generation. Defaults to
+     * the GNX_WIKI_CONCURRENCY env var (10 if unset). Parents and overview
+     * always run sequentially because they depend on prior phase outputs.
+     */
+    concurrency?: number;
 }
 export interface RunWikiUploadDeps extends ResolveContextDeps {
     createClaudeRunner: () => ClaudeRunner;