gitnexus 1.6.6-rc.4 → 1.6.6-rc.6

package/dist/cli/analyze.js

@@ -58,12 +58,55 @@ const installFatalHandlers = () => {
         process.exit(1);
     });
 };
-const HEAP_MB = 8192;
-const HEAP_FLAG = `--max-old-space-size=${HEAP_MB}`;
+const HEAP_MB = 16384;
+const TEST_RESPAWN_HEAP_MB = Number(process.env.GITNEXUS_TEST_RESPAWN_HEAP_MB);
+const RESPAWN_HEAP_MB = Number.isFinite(TEST_RESPAWN_HEAP_MB) && TEST_RESPAWN_HEAP_MB > 0
+    ? Math.floor(TEST_RESPAWN_HEAP_MB)
+    : HEAP_MB;
+const HEAP_FLAG = `--max-old-space-size=${RESPAWN_HEAP_MB}`;
 /** Increase default stack size (KB) to prevent stack overflow on deep class hierarchies. */
 const STACK_KB = 4096;
 const STACK_FLAG = `--stack-size=${STACK_KB}`;
-/** Re-exec the process with an 8GB heap and larger stack if we're currently below that. */
+/**
+ * Heuristic for "child re-exec likely died from V8 OOM".
+ *
+ * Platform-independent detection is best-effort: V8/Node usually emit
+ * stable heap-exhaustion phrases in stderr/message across Linux/macOS/Windows
+ * (for example "JavaScript heap out of memory" or "Reached heap limit"),
+ * while some environments only expose status/signal (e.g. 134/SIGABRT).
+ * We combine both text signatures and process-exit signatures.
+ */
+const childProcessLikelyOom = (err) => {
+    if (!err || typeof err !== 'object')
+        return false;
+    const e = err;
+    const hasHeapOomSignature = (v) => {
+        const text = (Buffer.isBuffer(v) ? v.toString('utf8') : typeof v === 'string' ? v : '').toLowerCase();
+        if (!text)
+            return false;
+        return (text.includes('javascript heap out of memory') ||
+            text.includes('reached heap limit') ||
+            text.includes('allocation failed - javascript heap out of memory') ||
+            text.includes('fatalprocessoutofmemory'));
+    };
+    const fields = [e.message, e.stderr, e.stdout];
+    if (fields.some((v) => hasHeapOomSignature(v)))
+        return true;
+    const hasAnyChildOutput = [e.stderr, e.stdout].some((v) => (Buffer.isBuffer(v) && v.length > 0) || (typeof v === 'string' && v.length > 0));
+    if (hasAnyChildOutput)
+        return false;
+    return e.status === 134 || e.signal === 'SIGABRT';
+};
+const forceHeapOOMForTestIfEnabled = () => {
+    if (process.env.GITNEXUS_TEST_FORCE_HEAP_OOM !== '1')
+        return;
+    // Allocate JS strings (not Buffers) so pressure lands on V8 heap itself.
+    // Buffers can allocate off-heap, which makes OOM triggering less reliable.
+    const chunks = [];
+    for (;;)
+        chunks.push('x'.repeat(1024 * 1024));
+};
+/** Re-exec the process with a 16GB heap and larger stack if we're currently below that. */
 function ensureHeap() {
     const nodeOpts = process.env.NODE_OPTIONS || '';
     if (nodeOpts.includes('--max-old-space-size'))
@@ -83,6 +126,13 @@ function ensureHeap() {
         });
     }
     catch (e) {
+        if (childProcessLikelyOom(e)) {
+            cliError(`  Analysis likely ran out of memory.\n` +
+                `  Retry with a larger heap if your machine allows it:\n` +
+                `    NODE_OPTIONS="--max-old-space-size=24576" gitnexus analyze [your-args]\n` +
+                `    (Windows: set NODE_OPTIONS=--max-old-space-size=24576 && gitnexus analyze [your-args])\n` +
+                `  If this persists, it may be a native crash unrelated to heap size.\n`, { recoveryHint: 'heap-oom-respawn' });
+        }
         process.exitCode = e.status ?? 1;
     }
     return true;
@@ -104,6 +154,7 @@ export const shouldGenerateCommunitySkillFiles = (options, pipelineResult) => Bo
 export const analyzeCommand = async (inputPath, options) => {
     if (ensureHeap())
         return;
+    forceHeapOOMForTestIfEnabled();
     // Install fatal handlers immediately after re-exec resolution so any
     // async error that escapes the try/catch below (#1169) surfaces with
     // a stack trace and a non-zero exit code instead of a silent exit 0.

package/dist/cli/index.js

@@ -108,6 +108,7 @@ program
     .option('--gist', 'Publish wiki as a public GitHub Gist after generation')
     .option('-v, --verbose', 'Enable verbose output (show LLM commands and responses)')
     .option('--review', 'Stop after grouping to review module structure before generating pages')
+    .option('--lang <lang>', 'Output language for generated documentation (e.g. english, chinese, spanish, japanese)')
     .action(createLazyAction(() => import('./wiki.js'), 'wikiCommand'));
 program
     .command('augment <pattern>')

package/dist/cli/wiki.d.ts

@@ -19,5 +19,6 @@ export interface WikiCommandOptions {
     review?: boolean;
     timeout?: string;
     retries?: string;
+    lang?: string;
 }
 export declare const wikiCommand: (inputPath?: string, options?: WikiCommandOptions) => Promise<void>;

package/dist/cli/wiki.js

@@ -364,6 +364,7 @@ export const wikiCommand = async (inputPath, options) => {
         force: options?.force,
         concurrency: options?.concurrency ? parseInt(options.concurrency, 10) : undefined,
         reviewOnly: options?.review,
+        lang: options?.lang,
     };
     const generator = new WikiGenerator(repoPath, storagePath, lbugPath, llmConfig, wikiOptions, (phase, percent, detail) => {
         const label = detail || phase;

package/dist/core/wiki/generator.d.ts

@@ -16,11 +16,14 @@ export interface WikiOptions {
     concurrency?: number;
     /** If true, stop after building module tree for user review */
     reviewOnly?: boolean;
+    /** Output language for generated documentation (e.g. 'english', 'chinese', 'spanish') */
+    lang?: string;
 }
 export interface WikiMeta {
     fromCommit: string;
     generatedAt: string;
     model: string;
+    lang: string;
     moduleFiles: Record<string, string[]>;
     moduleTree: ModuleTreeNode[];
 }
@@ -62,6 +65,16 @@ export declare class WikiGenerator {
      * Also touches the DB connection periodically to prevent idle timeout.
      */
     private streamOpts;
+    /**
+     * Return the effective lang string: strip control characters, trim, cap at 50 chars,
+     * then validate against a character allowlist. Returns '' if the value is absent or invalid.
+     * Used for both prompt construction and meta storage/comparison so they are always in sync.
+     */
+    private effectiveLang;
+    /**
+     * Append an output-language instruction to a system prompt when --lang is set.
+     */
+    private buildSystemPrompt;
     /**
      * Route LLM call to the appropriate provider (OpenAI-compatible or Cursor CLI).
      */

package/dist/core/wiki/generator.js

@@ -89,6 +89,27 @@ export class WikiGenerator {
             },
         };
     }
+    /**
+     * Return the effective lang string: strip control characters, trim, cap at 50 chars,
+     * then validate against a character allowlist. Returns '' if the value is absent or invalid.
+     * Used for both prompt construction and meta storage/comparison so they are always in sync.
+     */
+    effectiveLang() {
+        const lang = (this.options.lang ?? '')
+            .replace(/[\x00-\x1F\x7F]/g, '')
+            .trim()
+            .slice(0, 50);
+        return /^[a-zA-Z -]+$/.test(lang) ? lang : '';
+    }
+    /**
+     * Append an output-language instruction to a system prompt when --lang is set.
+     */
+    buildSystemPrompt(base) {
+        const lang = this.effectiveLang();
+        if (!lang)
+            return base;
+        return `${base}\n\nIMPORTANT: Write ALL documentation content in ${lang}. This includes prose, code comments in examples, and diagram labels. Note: page titles (H1 headings) are generated separately and will remain in English.`;
+    }
     /**
      * Route LLM call to the appropriate provider (OpenAI-compatible or Cursor CLI).
      */
@@ -112,6 +133,13 @@ export class WikiGenerator {
         const forceMode = this.options.force;
         // Up-to-date check (skip if --force)
         if (!forceMode && existingMeta && existingMeta.fromCommit === currentCommit) {
+            const currentLang = this.effectiveLang();
+            const metaLang = existingMeta.lang ?? '';
+            if (currentLang !== metaLang) {
+                const prevDisplay = metaLang || 'english (default)';
+                const nextDisplay = currentLang || 'english (default)';
+                throw new Error(`Wiki was generated in ${prevDisplay}; use --force to regenerate in ${nextDisplay}.`);
+            }
             // Still regenerate the HTML viewer in case it's missing
             await this.ensureHTMLViewer();
             return { pagesGenerated: 0, mode: 'up-to-date', failedModules: [] };
@@ -139,6 +167,13 @@ export class WikiGenerator {
         let result;
         try {
             if (!forceMode && existingMeta && existingMeta.fromCommit) {
+                const currentLang = this.effectiveLang();
+                const metaLang = existingMeta.lang ?? '';
+                if (currentLang !== metaLang) {
+                    const prevDisplay = metaLang || 'english (default)';
+                    const nextDisplay = currentLang || 'english (default)';
+                    throw new Error(`Wiki was generated in ${prevDisplay}; use --force to regenerate in ${nextDisplay}.`);
+                }
                 result = await this.incrementalUpdate(existingMeta, currentCommit);
             }
             else {
@@ -257,6 +292,7 @@ export class WikiGenerator {
             fromCommit: currentCommit,
             generatedAt: new Date().toISOString(),
             model: this.llmConfig.model,
+            lang: this.effectiveLang(),
             moduleFiles,
             moduleTree,
         });
@@ -298,6 +334,9 @@ export class WikiGenerator {
             FILE_LIST: fileList,
             DIRECTORY_TREE: dirTree,
         });
+        // Grouping is a structured-data phase (JSON output), not documentation.
+        // Do NOT apply buildSystemPrompt here — a language instruction would risk
+        // translating module-name keys, breaking slug stability and JSON parsing.
         const response = await this.invokeLLM(prompt, GROUPING_SYSTEM_PROMPT, this.streamOpts('Grouping files', 15, 13));
         const grouping = this.parseGroupingResponse(response.content, files);
         // Convert to tree nodes
@@ -444,8 +483,8 @@ export class WikiGenerator {
             INCOMING_CALLS: formatCallEdges(interCalls.incoming),
             PROCESSES: formatProcesses(processes),
         });
-        const response = await this.invokeLLM(prompt, MODULE_SYSTEM_PROMPT, this.streamOpts(node.name));
-        // Write page with front matter
+        const response = await this.invokeLLM(prompt, this.buildSystemPrompt(MODULE_SYSTEM_PROMPT), this.streamOpts(node.name));
+        // H1 uses the English module name (stable slug source); body is LLM-translated.
         const pageContent = sanitizeMermaidMarkdown(`# ${node.name}\n\n${response.content}`);
         await fs.writeFile(path.join(this.wikiDir, `${node.slug}.md`), pageContent, 'utf-8');
     }
@@ -480,7 +519,7 @@ export class WikiGenerator {
             CROSS_MODULE_CALLS: formatCallEdges(crossCalls),
             CROSS_PROCESSES: formatProcesses(processes),
         });
-        const response = await this.invokeLLM(prompt, PARENT_SYSTEM_PROMPT, this.streamOpts(node.name));
+        const response = await this.invokeLLM(prompt, this.buildSystemPrompt(PARENT_SYSTEM_PROMPT), this.streamOpts(node.name));
         const pageContent = sanitizeMermaidMarkdown(`# ${node.name}\n\n${response.content}`);
         await fs.writeFile(path.join(this.wikiDir, `${node.slug}.md`), pageContent, 'utf-8');
     }
@@ -516,7 +555,7 @@ export class WikiGenerator {
             MODULE_EDGES: edgesText,
             TOP_PROCESSES: formatProcesses(topProcesses),
         });
-        const response = await this.invokeLLM(prompt, OVERVIEW_SYSTEM_PROMPT, this.streamOpts('Generating overview', 88));
+        const response = await this.invokeLLM(prompt, this.buildSystemPrompt(OVERVIEW_SYSTEM_PROMPT), this.streamOpts('Generating overview', 88));
         const pageContent = sanitizeMermaidMarkdown(`# ${path.basename(this.repoPath)} — Wiki\n\n${response.content}`);
         await fs.writeFile(path.join(this.wikiDir, 'overview.md'), pageContent, 'utf-8');
     }
@@ -538,6 +577,7 @@ export class WikiGenerator {
                 ...existingMeta,
                 fromCommit: currentCommit,
                 generatedAt: new Date().toISOString(),
+                lang: this.effectiveLang(),
             });
             return { pagesGenerated: 0, mode: 'incremental', failedModules: [] };
         }
@@ -627,6 +667,7 @@ export class WikiGenerator {
             fromCommit: currentCommit,
             generatedAt: new Date().toISOString(),
             model: this.llmConfig.model,
+            lang: this.effectiveLang(),
         });
         this.onProgress('done', 100, 'Incremental update complete');
         return { pagesGenerated, mode: 'incremental', failedModules: [...this.failedModules] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.6-rc.4",
+  "version": "1.6.6-rc.6",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",