gitnexushub 0.4.5 → 0.6.0

package/dist/wiki/claude.d.ts

@@ -1,12 +1,18 @@
 export interface ClaudeGenerationResult {
     text: string;
+    structuredOutput?: unknown;
     durationMs: number;
 }
+export interface ClaudeRunOptions {
+    cwd: string;
+    model?: string;
+    allowedTools?: string[];
+    outputFormat?: {
+        type: 'json_schema';
+        schema: Record<string, unknown>;
+    };
+}
 export interface ClaudeRunner {
-    run(prompt: string, opts: {
-        cwd: string;
-        model?: string;
-        allowedTools?: string[];
-    }): Promise<ClaudeGenerationResult>;
+    run(prompt: string, opts: ClaudeRunOptions): Promise<ClaudeGenerationResult>;
 }
 export declare function createClaudeRunner(): ClaudeRunner;

package/dist/wiki/claude.js

@@ -14,6 +14,7 @@ export function createClaudeRunner() {
         async run(prompt, opts) {
             const start = Date.now();
             let finalText = '';
+            let structuredOutput;
             try {
                 for await (const msg of query({
                     prompt,
@@ -21,11 +22,15 @@ export function createClaudeRunner() {
                         cwd: opts.cwd,
                         model: opts.model,
                         allowedTools: opts.allowedTools ?? DEFAULT_ALLOWED_TOOLS,
+                        outputFormat: opts.outputFormat,
                     },
                 })) {
                     const m = msg;
-                    if (m.type === 'result' && typeof m.result === 'string') {
-                        finalText = m.result;
+                    if (m.type === 'result') {
+                        if (typeof m.result === 'string')
+                            finalText = m.result;
+                        if (m.structured_output !== undefined)
+                            structuredOutput = m.structured_output;
                     }
                 }
             }
@@ -42,7 +47,7 @@ export function createClaudeRunner() {
                 });
             }
             const durationMs = Date.now() - start;
-            return { text: finalText, durationMs };
+            return { text: finalText, structuredOutput, durationMs };
         },
     };
 }

package/dist/wiki/compose-overview.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Deterministic wiki overview composer (connect-package mirror of
+ * gitnexus/src/core/wiki/compose-overview.ts).
+ *
+ * Skips the per-repo LLM "synthesize an overview" call by assembling:
+ * - Repo title heading
+ * - Auto-generated boilerplate
+ * - Table of contents linking to module slugs
+ * - Per-module section with the module's first-paragraph summary
+ * - Optional Mermaid architecture diagram
+ *
+ * Saves ~1 minute per generation. Quality is comparable because the LLM's
+ * overview was largely rephrasing leaf summaries anyway.
+ *
+ * Mirrored separately rather than imported across packages because
+ * gitnexus-connect is a distributable CLI that should not transitively pull
+ * in the OSS gitnexus runtime.
+ */
+export interface OverviewModule {
+    slug: string;
+    title: string;
+    summary: string;
+}
+export interface ComposeOverviewParams {
+    repoName: string;
+    modules: OverviewModule[];
+    architectureMermaid?: string;
+}
+export declare function composeOverview(p: ComposeOverviewParams): string;

package/dist/wiki/compose-overview.js

@@ -0,0 +1,48 @@
+/**
+ * Deterministic wiki overview composer (connect-package mirror of
+ * gitnexus/src/core/wiki/compose-overview.ts).
+ *
+ * Skips the per-repo LLM "synthesize an overview" call by assembling:
+ * - Repo title heading
+ * - Auto-generated boilerplate
+ * - Table of contents linking to module slugs
+ * - Per-module section with the module's first-paragraph summary
+ * - Optional Mermaid architecture diagram
+ *
+ * Saves ~1 minute per generation. Quality is comparable because the LLM's
+ * overview was largely rephrasing leaf summaries anyway.
+ *
+ * Mirrored separately rather than imported across packages because
+ * gitnexus-connect is a distributable CLI that should not transitively pull
+ * in the OSS gitnexus runtime.
+ */
+export function composeOverview(p) {
+    const parts = [];
+    parts.push(`# ${p.repoName}`);
+    parts.push('');
+    parts.push('Auto-generated wiki overview.');
+    parts.push('');
+    parts.push('## Table of Contents');
+    parts.push('');
+    for (const m of p.modules) {
+        parts.push(`- [${m.title}](${m.slug})`);
+    }
+    parts.push('');
+    parts.push('## Modules');
+    parts.push('');
+    for (const m of p.modules) {
+        parts.push(`### [${m.title}](${m.slug})`);
+        parts.push('');
+        parts.push((m.summary || '').trim() || '_(no summary available)_');
+        parts.push('');
+    }
+    if (p.architectureMermaid && p.architectureMermaid.trim().length > 0) {
+        parts.push('## Architecture Diagram');
+        parts.push('');
+        parts.push('```mermaid');
+        parts.push(p.architectureMermaid.trim());
+        parts.push('```');
+        parts.push('');
+    }
+    return parts.join('\n').replace(/\n{3,}/g, '\n\n');
+}

package/dist/wiki/concurrency.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Bounded concurrency with adaptive 429 backoff.
+ *
+ * Ports the Hub's runParallel pattern (gitnexus/src/core/wiki/generator.ts:1004-1056)
+ * to the client. Runs up to `concurrency` tasks in parallel; on any task that
+ * rejects with an Error whose message contains "429", the active concurrency
+ * drops by one (floor 1), the task is requeued, and the scheduler pauses for
+ * 5 seconds before retrying. All other errors propagate normally.
+ *
+ * Returns an array of results in the SAME ORDER as the input items.
+ */
+export interface RunConcurrentOptions {
+    /** Max tasks running simultaneously. Must be >= 1. */
+    concurrency: number;
+    /** Optional abort signal — in-flight tasks finish, no new ones start. */
+    abortSignal?: AbortSignal;
+    /** Optional callback to report adaptive concurrency drops. */
+    onRateLimit?: (newConcurrency: number) => void;
+}
+export declare function runConcurrent<T, R>(items: T[], fn: (item: T, index: number) => Promise<R>, opts: RunConcurrentOptions): Promise<R[]>;

package/dist/wiki/concurrency.js

@@ -0,0 +1,91 @@
+/**
+ * Bounded concurrency with adaptive 429 backoff.
+ *
+ * Ports the Hub's runParallel pattern (gitnexus/src/core/wiki/generator.ts:1004-1056)
+ * to the client. Runs up to `concurrency` tasks in parallel; on any task that
+ * rejects with an Error whose message contains "429", the active concurrency
+ * drops by one (floor 1), the task is requeued, and the scheduler pauses for
+ * 5 seconds before retrying. All other errors propagate normally.
+ *
+ * Returns an array of results in the SAME ORDER as the input items.
+ */
+const RATE_LIMIT_DELAY_MS = 5000;
+export async function runConcurrent(items, fn, opts) {
+    if (opts.concurrency < 1) {
+        throw new Error(`runConcurrent: concurrency must be >= 1, got ${opts.concurrency}`);
+    }
+    if (items.length === 0)
+        return [];
+    const results = new Array(items.length);
+    let activeConcurrency = opts.concurrency;
+    let running = 0;
+    let nextIdx = 0;
+    // Re-queued indices (from 429 backoff). Drained before picking new work.
+    const requeue = [];
+    let firstError = null;
+    return new Promise((resolve, reject) => {
+        const finishIfDone = () => {
+            if (firstError !== null) {
+                // Wait until every in-flight task settles before rejecting, so we don't
+                // resolve/reject while promises are still racing.
+                if (running === 0)
+                    reject(firstError);
+                return;
+            }
+            if (running === 0 && nextIdx >= items.length && requeue.length === 0) {
+                resolve(results);
+            }
+        };
+        const tick = () => {
+            if (firstError !== null) {
+                finishIfDone();
+                return;
+            }
+            if (opts.abortSignal?.aborted) {
+                firstError = opts.abortSignal.reason ?? new Error('aborted');
+                finishIfDone();
+                return;
+            }
+            while (running < activeConcurrency) {
+                let idx;
+                if (requeue.length > 0) {
+                    idx = requeue.shift();
+                }
+                else if (nextIdx < items.length) {
+                    idx = nextIdx++;
+                }
+                else {
+                    break;
+                }
+                running++;
+                Promise.resolve()
+                    .then(() => fn(items[idx], idx))
+                    .then((value) => {
+                    results[idx] = value;
+                    running--;
+                    tick();
+                })
+                    .catch((err) => {
+                    running--;
+                    const msg = err instanceof Error ? err.message : String(err);
+                    if (msg.includes('429')) {
+                        activeConcurrency = Math.max(1, activeConcurrency - 1);
+                        opts.onRateLimit?.(activeConcurrency);
+                        requeue.push(idx);
+                        const t = setTimeout(tick, RATE_LIMIT_DELAY_MS);
+                        t.unref?.();
+                    }
+                    else if (firstError === null) {
+                        firstError = err;
+                        finishIfDone();
+                    }
+                    else {
+                        finishIfDone();
+                    }
+                });
+            }
+            finishIfDone();
+        };
+        tick();
+    });
+}

package/dist/wiki/helpers.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Pure helpers for client-side wiki generation, ported from the
+ * retired server-side WikiGenerator (gitnexus/src/core/wiki/generator.ts).
+ */
+/**
+ * Extract a short summary from a generated page.
+ * Tries, in order: <!-- summary-end --> marker, content up to first ## heading,
+ * sentence-boundary truncation near maxLength.
+ */
+export declare function extractSummary(content: string, maxLength?: number): string;
+/**
+ * Rough token-count heuristic: ~4 characters per token.
+ * Matches gitnexus/src/core/wiki/llm-client.ts:estimateTokens.
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Sum the estimated token count across a module's files on disk.
+ * Unreadable files (missing, permission errors, binary, etc.) contribute
+ * zero — mirrors Hub's generator.ts:estimateModuleTokens behavior.
+ */
+export declare function estimateModuleTokens(filePaths: string[], repoRoot: string): Promise<number>;
+/**
+ * Read a human-readable project description from the repo root.
+ * Reads the first matching config file from a known allowlist plus a
+ * README excerpt. Returns a formatted multi-line string.
+ * Never throws; falls back to `Project: <dirname>` on any error.
+ */
+export declare function readProjectInfo(repoRoot: string): Promise<string>;
+export interface ModuleRegistryEntry {
+    name: string;
+    slug: string;
+    symbols: string[];
+}
+/**
+ * Fix broken [text](slug.md) links in generated markdown.
+ * Priority: valid slug > fuzzy name match > substring match > strip link.
+ * Only touches `[text](slug.md)` patterns — external URLs are untouched.
+ */
+export declare function validateAndFixCrossReferences(markdown: string, registry: Map<string, ModuleRegistryEntry>): string;
+export interface FileWithExports {
+    filePath: string;
+    symbols: Array<{
+        name: string;
+        type: string;
+    }>;
+}
+/**
+ * Ensure every file the Hub told us about ends up in some module.
+ *
+ * The LLM can quietly drop files when producing the module tree (especially
+ * on longer file lists). Hub's generator.ts:499-502 swept these into an
+ * "Other" bucket; we mirror that here. If an "Other" module already exists
+ * (e.g., from fallback grouping), the unassigned files are merged into it.
+ *
+ * If `filesWithExportsRaw` is empty (older Hub that doesn't expose the
+ * field), this is a no-op.
+ */
+export declare function ensureAllFilesAssigned<T extends {
+    slug: string;
+    title: string;
+    files?: string[];
+}>(modules: T[], filesWithExportsRaw: FileWithExports[], makeNode: (slug: string, title: string, files: string[]) => T): T[];
+interface TreeNodeLike {
+    name: string;
+    slug: string;
+    files?: string[];
+    children?: TreeNodeLike[];
+}
+/**
+ * Build a slug→{name,slug,symbols} registry from the module tree and
+ * per-file exported-symbol metadata. Collects up to 10 symbol names per module.
+ */
+export declare function buildModuleRegistry(tree: TreeNodeLike[], filesWithExports: FileWithExports[]): Map<string, ModuleRegistryEntry>;
+/**
+ * Render the module registry as a markdown list for injection into prompts.
+ * Excludes `currentSlug` when provided so a module doesn't link to itself.
+ */
+export declare function formatModuleRegistry(registry: Map<string, ModuleRegistryEntry>, currentSlug?: string): string;
+/**
+ * Fallback grouping for when the LLM's module-tree response is malformed.
+ * Uses graph communities if available, otherwise groups by top-level directory.
+ */
+export declare function fallbackGrouping(files: FileWithExports[], communityMapping?: Array<{
+    label: string;
+    files: string[];
+}>): Record<string, string[]>;
+export interface SplitNode {
+    name: string;
+    slug: string;
+    files: string[];
+}
+/**
+ * Split a module's files into sub-modules by community membership.
+ * Each file is assigned to the community it appears in most.
+ * Returns null when the split doesn't yield >1 bucket — caller should
+ * fall back to subdirectory-based splitting.
+ */
+export declare function splitByCommunity(parentName: string, files: string[], communityMapping: Array<{
+    label: string;
+    files: string[];
+}>): SplitNode[] | null;
+export {};

package/dist/wiki/helpers.js

@@ -0,0 +1,308 @@
+/**
+ * Pure helpers for client-side wiki generation, ported from the
+ * retired server-side WikiGenerator (gitnexus/src/core/wiki/generator.ts).
+ */
+/**
+ * Extract a short summary from a generated page.
+ * Tries, in order: <!-- summary-end --> marker, content up to first ## heading,
+ * sentence-boundary truncation near maxLength.
+ */
+export function extractSummary(content, maxLength = 800) {
+    const markerIdx = content.indexOf('<!-- summary-end -->');
+    if (markerIdx > 0) {
+        return content.slice(0, markerIdx).trim();
+    }
+    const lines = content.split('\n');
+    let pastTitle = false;
+    let result = '';
+    for (const line of lines) {
+        if (!pastTitle && line.startsWith('# ')) {
+            pastTitle = true;
+            result += line + '\n';
+            continue;
+        }
+        if (pastTitle && /^##\s/.test(line)) {
+            break;
+        }
+        result += line + '\n';
+    }
+    const candidate = result.trim();
+    if (candidate.length > 20 && candidate.length <= maxLength) {
+        return candidate;
+    }
+    // Use content directly if we don't have a good candidate from line parsing
+    const truncated = content.slice(0, maxLength);
+    const lastSentence = truncated.lastIndexOf('. ');
+    if (lastSentence > maxLength * 0.5) {
+        return truncated.slice(0, lastSentence + 1).trim();
+    }
+    return truncated.trim();
+}
+import fs from 'fs/promises';
+import path from 'path';
+/**
+ * Rough token-count heuristic: ~4 characters per token.
+ * Matches gitnexus/src/core/wiki/llm-client.ts:estimateTokens.
+ */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Sum the estimated token count across a module's files on disk.
+ * Unreadable files (missing, permission errors, binary, etc.) contribute
+ * zero — mirrors Hub's generator.ts:estimateModuleTokens behavior.
+ */
+export async function estimateModuleTokens(filePaths, repoRoot) {
+    let total = 0;
+    for (const fp of filePaths) {
+        try {
+            const content = await fs.readFile(path.join(repoRoot, fp), 'utf-8');
+            total += estimateTokens(content);
+        }
+        catch {
+            /* skip unreadable files */
+        }
+    }
+    return total;
+}
+/**
+ * Read a human-readable project description from the repo root.
+ * Reads the first matching config file from a known allowlist plus a
+ * README excerpt. Returns a formatted multi-line string.
+ * Never throws; falls back to `Project: <dirname>` on any error.
+ */
+export async function readProjectInfo(repoRoot) {
+    const candidates = [
+        'package.json',
+        'Cargo.toml',
+        'pyproject.toml',
+        'go.mod',
+        'pom.xml',
+        'build.gradle',
+    ];
+    const lines = [`Project: ${path.basename(repoRoot)}`];
+    for (const file of candidates) {
+        const fullPath = path.join(repoRoot, file);
+        try {
+            const content = await fs.readFile(fullPath, 'utf-8');
+            if (file === 'package.json') {
+                try {
+                    const pkg = JSON.parse(content);
+                    if (pkg.name)
+                        lines.push(`Name: ${pkg.name}`);
+                    if (pkg.description)
+                        lines.push(`Description: ${pkg.description}`);
+                    if (pkg.scripts && typeof pkg.scripts === 'object') {
+                        lines.push(`Scripts: ${Object.keys(pkg.scripts).join(', ')}`);
+                    }
+                    break;
+                }
+                catch {
+                    continue;
+                }
+            }
+            else {
+                lines.push(`\n${file}:\n${content.slice(0, 500)}`);
+                break;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    for (const readme of ['README.md', 'readme.md', 'README.txt']) {
+        try {
+            const content = await fs.readFile(path.join(repoRoot, readme), 'utf-8');
+            lines.push(`\nREADME excerpt:\n${content.slice(0, 1000)}`);
+            break;
+        }
+        catch {
+            continue;
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Fix broken [text](slug.md) links in generated markdown.
+ * Priority: valid slug > fuzzy name match > substring match > strip link.
+ * Only touches `[text](slug.md)` patterns — external URLs are untouched.
+ */
+export function validateAndFixCrossReferences(markdown, registry) {
+    const validSlugs = new Set();
+    const slugByName = new Map();
+    for (const entry of registry.values()) {
+        validSlugs.add(entry.slug);
+        slugByName.set(entry.name.toLowerCase(), entry.slug);
+    }
+    return markdown.replace(/\[([^\]]+)\]\(([a-z0-9][a-z0-9_-]*)\.md\)/g, (match, text, slug) => {
+        if (validSlugs.has(slug))
+            return match;
+        const fuzzy = slugByName.get(String(text).toLowerCase());
+        if (fuzzy)
+            return `[${text}](${fuzzy}.md)`;
+        for (const validSlug of validSlugs) {
+            if (validSlug.includes(slug) || slug.includes(validSlug)) {
+                return `[${text}](${validSlug}.md)`;
+            }
+        }
+        return String(text);
+    });
+}
+/**
+ * Ensure every file the Hub told us about ends up in some module.
+ *
+ * The LLM can quietly drop files when producing the module tree (especially
+ * on longer file lists). Hub's generator.ts:499-502 swept these into an
+ * "Other" bucket; we mirror that here. If an "Other" module already exists
+ * (e.g., from fallback grouping), the unassigned files are merged into it.
+ *
+ * If `filesWithExportsRaw` is empty (older Hub that doesn't expose the
+ * field), this is a no-op.
+ */
+export function ensureAllFilesAssigned(modules, filesWithExportsRaw, makeNode) {
+    if (filesWithExportsRaw.length === 0)
+        return modules;
+    const assigned = new Set();
+    for (const mod of modules) {
+        for (const fp of mod.files ?? [])
+            assigned.add(fp);
+    }
+    const unassigned = [];
+    for (const entry of filesWithExportsRaw) {
+        if (!assigned.has(entry.filePath))
+            unassigned.push(entry.filePath);
+    }
+    if (unassigned.length === 0)
+        return modules;
+    const existingOther = modules.find((m) => m.slug === 'other');
+    if (existingOther) {
+        existingOther.files = [...(existingOther.files ?? []), ...unassigned];
+        return modules;
+    }
+    return [...modules, makeNode('other', 'Other', unassigned)];
+}
+/**
+ * Build a slug→{name,slug,symbols} registry from the module tree and
+ * per-file exported-symbol metadata. Collects up to 10 symbol names per module.
+ */
+export function buildModuleRegistry(tree, filesWithExports) {
+    const exportMap = new Map(filesWithExports.map((f) => [f.filePath, f]));
+    const registry = new Map();
+    const addNode = (node) => {
+        const symbols = [];
+        const nodeFiles = node.children
+            ? node.children.flatMap((c) => c.files ?? [])
+            : (node.files ?? []);
+        for (const fp of nodeFiles) {
+            const fileEntry = exportMap.get(fp);
+            if (fileEntry) {
+                for (const sym of fileEntry.symbols) {
+                    if (symbols.length < 10 && !symbols.includes(sym.name))
+                        symbols.push(sym.name);
+                }
+            }
+        }
+        registry.set(node.slug, { name: node.name, slug: node.slug, symbols });
+        if (node.children) {
+            for (const child of node.children)
+                addNode(child);
+        }
+    };
+    for (const node of tree)
+        addNode(node);
+    return registry;
+}
+/**
+ * Render the module registry as a markdown list for injection into prompts.
+ * Excludes `currentSlug` when provided so a module doesn't link to itself.
+ */
+export function formatModuleRegistry(registry, currentSlug) {
+    if (registry.size === 0)
+        return 'No module registry available.';
+    const lines = [];
+    for (const entry of registry.values()) {
+        if (entry.slug === currentSlug)
+            continue;
+        const symText = entry.symbols.length > 0 ? ` — exports: ${entry.symbols.join(', ')}` : '';
+        lines.push(`- [${entry.name}](${entry.slug}.md)${symText}`);
+    }
+    return lines.length > 0 ? lines.join('\n') : 'No module registry available.';
+}
+/**
+ * Fallback grouping for when the LLM's module-tree response is malformed.
+ * Uses graph communities if available, otherwise groups by top-level directory.
+ */
+export function fallbackGrouping(files, communityMapping) {
+    if (communityMapping && communityMapping.length > 0) {
+        const result = {};
+        const assigned = new Set();
+        for (const group of communityMapping) {
+            if (group.files.length > 0) {
+                result[group.label] = [...group.files];
+                for (const f of group.files)
+                    assigned.add(f);
+            }
+        }
+        const unassigned = files.map((f) => f.filePath).filter((fp) => !assigned.has(fp));
+        if (unassigned.length > 0)
+            result['Other'] = unassigned;
+        if (Object.keys(result).length > 0)
+            return result;
+    }
+    const groups = new Map();
+    for (const f of files) {
+        const parts = f.filePath.replace(/\\/g, '/').split('/');
+        const topDir = parts.length > 1 ? parts[0] : 'Root';
+        let group = groups.get(topDir);
+        if (!group) {
+            group = [];
+            groups.set(topDir, group);
+        }
+        group.push(f.filePath);
+    }
+    return Object.fromEntries(groups);
+}
+function slugify(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, 60);
+}
+/**
+ * Split a module's files into sub-modules by community membership.
+ * Each file is assigned to the community it appears in most.
+ * Returns null when the split doesn't yield >1 bucket — caller should
+ * fall back to subdirectory-based splitting.
+ */
+export function splitByCommunity(parentName, files, communityMapping) {
+    if (communityMapping.length === 0)
+        return null;
+    const subGroups = new Map();
+    for (const fp of files) {
+        let bestLabel = '';
+        let bestCount = 0;
+        for (const group of communityMapping) {
+            const count = group.files.filter((f) => f === fp).length;
+            if (count > bestCount) {
+                bestCount = count;
+                bestLabel = group.label;
+            }
+        }
+        if (bestLabel) {
+            let g = subGroups.get(bestLabel);
+            if (!g) {
+                g = [];
+                subGroups.set(bestLabel, g);
+            }
+            g.push(fp);
+        }
+    }
+    if (subGroups.size <= 1)
+        return null;
+    return Array.from(subGroups.entries()).map(([label, subFiles]) => ({
+        name: `${parentName} — ${label}`,
+        slug: slugify(`${parentName}-${label}`),
+        files: subFiles,
+    }));
+}