gitnexus 1.6.0 → 1.6.2-rc.1

package/README.md

@@ -234,6 +234,79 @@ Installed automatically by both `gitnexus analyze` (per-repo) and `gitnexus setu
 - Node.js >= 18
 - Git repository (uses git for commit tracking)
 
+## Release candidates
+
+Stable releases publish to the default `latest` dist-tag. When a pull request
+with non-documentation changes merges into `main`, an automated workflow also
+publishes a prerelease build under the `rc` dist-tag, so early adopters can
+try in-flight fixes without waiting for the next stable cut. (Docs-only
+merges are skipped.)
+
+```bash
+# Try the latest release candidate (pre-stable — may change at any time)
+npm install -g gitnexus@rc
+# — or —
+npx gitnexus@rc analyze
+```
+
+Release-candidate versions follow the standard semver prerelease format
+`X.Y.Z-rc.N`, where `X.Y.Z` is the next stable target (bumped from the
+current `latest` by patch by default; `minor` or `major` when kicking off a
+bigger cycle) and `N` increments per published rc. Example sequence:
+`1.6.2-rc.1`, `1.6.2-rc.2`, …, then once `1.6.2` ships stable,
+`1.6.3-rc.1`. See the [Releases page](https://github.com/abhigyanpatwari/GitNexus/releases)
+for the full list; stable `latest` is unaffected.
+
+## Troubleshooting
+
+### `Cannot destructure property 'package' of 'node.target' as it is null`
+
+This crash was caused by a dependency URL format that is incompatible with
+certain npm/arborist versions ([npm/cli#8126](https://github.com/npm/cli/issues/8126)).
+It is fixed in **gitnexus v1.6.2+**. Upgrade to the latest version:
+
+```bash
+npx gitnexus@latest analyze          # always uses the newest release
+# — or —
+npm install -g gitnexus@latest       # upgrade a global install
+```
+
+If you still hit npm install issues after upgrading, these generic workarounds
+may help:
+
+```bash
+npm install -g npm@latest            # update npm itself
+npm cache clean --force              # clear a possibly corrupt cache
+```
+
+### Installation fails with native module errors
+
+Some optional language grammars (Dart, Kotlin, Swift) require native compilation. If they fail, GitNexus still works — those languages will be skipped.
+
+If `npm install -g gitnexus` fails on native modules:
+
+```bash
+# Ensure build tools are available (Linux/macOS)
+# Ubuntu/Debian: sudo apt install python3 make g++
+# macOS: xcode-select --install
+
+# Retry installation
+npm install -g gitnexus
+```
+
+### Analysis runs out of memory
+
+For very large repositories:
+
+```bash
+# Increase Node.js heap size
+NODE_OPTIONS="--max-old-space-size=16384" npx gitnexus analyze
+
+# Exclude large directories
+echo "vendor/" >> .gitnexusignore
+echo "dist/" >> .gitnexusignore
+```
+
 ## Privacy
 
 - All processing happens locally on your machine

package/dist/cli/analyze.js

@@ -18,7 +18,10 @@ import { runFullAnalysis } from '../core/run-analyze.js';
 import fs from 'fs/promises';
 const HEAP_MB = 8192;
 const HEAP_FLAG = `--max-old-space-size=${HEAP_MB}`;
-/** Re-exec the process with an 8GB heap if we're currently below that. */
+/** 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. */
 function ensureHeap() {
     const nodeOpts = process.env.NODE_OPTIONS || '';
     if (nodeOpts.includes('--max-old-space-size'))
@@ -26,8 +29,13 @@ function ensureHeap() {
     const v8Heap = v8.getHeapStatistics().heap_size_limit;
     if (v8Heap >= HEAP_MB * 1024 * 1024 * 0.9)
         return false;
+    // --stack-size is a V8 flag not allowed in NODE_OPTIONS on Node 24+,
+    // so pass it only as a direct CLI argument, not via the environment.
+    const cliFlags = [HEAP_FLAG];
+    if (!nodeOpts.includes('--stack-size'))
+        cliFlags.push(STACK_FLAG);
     try {
-        execFileSync(process.execPath, [HEAP_FLAG, ...process.argv.slice(1)], {
+        execFileSync(process.execPath, [...cliFlags, ...process.argv.slice(1)], {
             stdio: 'inherit',
             env: { ...process.env, NODE_OPTIONS: `${nodeOpts} ${HEAP_FLAG}`.trim() },
         });
@@ -222,7 +230,46 @@ export const analyzeCommand = async (inputPath, options) => {
         console.warn = origWarn;
         console.error = origError;
         bar.stop();
-        console.error(`\n  Analysis failed: ${err.message}\n`);
+        const msg = err.message || String(err);
+        console.error(`\n  Analysis failed: ${msg}\n`);
+        // Provide helpful guidance for known failure modes
+        if (msg.includes('Maximum call stack size exceeded') ||
+            msg.includes('call stack') ||
+            msg.includes('Map maximum size') ||
+            msg.includes('Invalid array length') ||
+            msg.includes('Invalid string length') ||
+            msg.includes('allocation failed') ||
+            msg.includes('heap out of memory') ||
+            msg.includes('JavaScript heap')) {
+            console.error('  This error typically occurs on very large repositories.');
+            console.error('  Suggestions:');
+            console.error('    1. Add large vendored/generated directories to .gitnexusignore');
+            console.error('    2. Increase Node.js heap: NODE_OPTIONS="--max-old-space-size=16384"');
+            console.error('    3. Increase stack size: NODE_OPTIONS="--stack-size=4096"');
+            console.error('');
+        }
+        else if (msg.includes('ERESOLVE') || msg.includes('Could not resolve dependency')) {
+            // Note: the original arborist "Cannot destructure property 'package' of
+            // 'node.target'" crash happens inside npm *before* gitnexus code runs,
+            // so it can't be caught here.  This branch handles dependency-resolution
+            // errors that surface at runtime (e.g. dynamic require failures).
+            console.error('  This looks like an npm dependency resolution issue.');
+            console.error('  Suggestions:');
+            console.error('    1. Clear the npm cache:    npm cache clean --force');
+            console.error('    2. Update npm:             npm install -g npm@latest');
+            console.error('    3. Reinstall gitnexus:     npm install -g gitnexus@latest');
+            console.error('    4. Or try npx directly:    npx gitnexus@latest analyze');
+            console.error('');
+        }
+        else if (msg.includes('MODULE_NOT_FOUND') ||
+            msg.includes('Cannot find module') ||
+            msg.includes('ERR_MODULE_NOT_FOUND')) {
+            console.error('  A required module could not be loaded. The installation may be corrupt.');
+            console.error('  Suggestions:');
+            console.error('    1. Reinstall:   npm install -g gitnexus@latest');
+            console.error('    2. Clear cache: npm cache clean --force && npx gitnexus@latest analyze');
+            console.error('');
+        }
         process.exitCode = 1;
         return;
     }

package/dist/core/group/extractors/fs-utils.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Safely read a file inside a repo, rejecting any path that escapes
+ * `repoPath` via `..` traversal or absolute segments. Returns `null` if
+ * the path is outside the repo or the file can't be read.
+ *
+ * Used by every source-scan extractor under this directory. Kept as a
+ * single shared implementation so the path-traversal guard (security-
+ * sensitive) lives in exactly one place.
+ */
+export declare function readSafe(repoPath: string, rel: string): string | null;

package/dist/core/group/extractors/fs-utils.js

@@ -0,0 +1,24 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * Safely read a file inside a repo, rejecting any path that escapes
+ * `repoPath` via `..` traversal or absolute segments. Returns `null` if
+ * the path is outside the repo or the file can't be read.
+ *
+ * Used by every source-scan extractor under this directory. Kept as a
+ * single shared implementation so the path-traversal guard (security-
+ * sensitive) lives in exactly one place.
+ */
+export function readSafe(repoPath, rel) {
+    const abs = path.resolve(repoPath, rel);
+    const base = path.resolve(repoPath);
+    const relToBase = path.relative(base, abs);
+    if (relToBase.startsWith('..') || path.isAbsolute(relToBase))
+        return null;
+    try {
+        return fs.readFileSync(abs, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/group/extractors/grpc-extractor.d.ts

@@ -1,16 +1,25 @@
 import type { ContractExtractor, CypherExecutor } from '../contract-extractor.js';
 import type { ExtractedContract, RepoHandle } from '../types.js';
+export interface ProtoServiceInfo {
+    package: string;
+    serviceName: string;
+    methods: string[];
+    protoPath: string;
+}
+export declare function buildProtoMap(repoPath: string): Promise<Map<string, ProtoServiceInfo[]>>;
+export declare function resolveProtoConflict(serviceName: string, sourceFilePath: string, candidates: ProtoServiceInfo[]): ProtoServiceInfo | null;
+export declare function serviceContractId(pkg: string, serviceName: string): string;
 export declare class GrpcExtractor implements ContractExtractor {
     type: "grpc";
     canExtract(_repo: RepoHandle): Promise<boolean>;
     extract(_dbExecutor: CypherExecutor | null, repoPath: string, _repo: RepoHandle): Promise<ExtractedContract[]>;
-    private parseProtoFile;
-    private scanGoProviders;
-    private scanGoConsumers;
-    private scanJavaProviders;
-    private scanJavaConsumers;
-    private scanPythonProviders;
-    private scanPythonConsumers;
-    private scanTsProviders;
+    /**
+     * Convert a plugin `GrpcDetection` into a concrete `ExtractedContract`
+     * by resolving the short service name against the proto map, building
+     * either a service-level (`grpc::pkg.Svc/*`) or method-level
+     * (`grpc::pkg.Svc/Method`) contract id, and selecting confidence
+     * based on whether the proto map had an entry.
+     */
+    private detectionToContract;
     private dedupe;
 }