scriptoriumadmin/GitNexus
1
0
Fork 0
mirror of https://github.com/abhigyanpatwari/GitNexus.git synced 2026-10-05 02:43:32 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 11

Merge branch 'main' into devb-gitnexus-httpx

Browse source
This commit is contained in:
Gergő Magyar 2026-05-08 15:15:22 +01:00 • committed by GitHub
commit 532cde6355
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
116 changed files with 5093 additions and 773 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
.github/scripts/check-tree-sitter-upgrade-readiness.py vendored
View file

@ -32,6 +32,7 @@ import pathlib
import re
import sys
import urllib.error
import urllib.parse
import urllib.request
REPO_ROOT = pathlib.Path(__file__).resolve().parents[2]
@ -190,7 +191,17 @@ def fetch_text(url: str, timeout: int = 8) -> str | None:
set (raises the rate limit from 60 to 5 000 requests/hour).
"""
headers: dict[str, str] = {}
if _GITHUB_TOKEN and ("github.com" in url or "githubusercontent.com" in url):
# Parse the URL and check the hostname rather than substring-matching
# on the full URL string (CodeQL py/incomplete-url-substring-sanitization).
# `https://evil.com/?u=github.com` would have passed the substring check.
try:
parsed_host = urllib.parse.urlparse(url).hostname or ""
except ValueError:
parsed_host = ""
is_github_host = parsed_host == "github.com" or parsed_host.endswith(
(".github.com", ".githubusercontent.com")
) or parsed_host == "githubusercontent.com"
if _GITHUB_TOKEN and is_github_host:
headers["Authorization"] = f"Bearer {_GITHUB_TOKEN}"
try:
req = urllib.request.Request(url, headers=headers)

68
.github/workflows/ci-report.yml vendored
View file

@ -138,14 +138,15 @@ jobs:
const fs = require('fs');
const path = require('path');
// Find the latest successful CI run on main
// Find recent successful CI runs on main (check several in case
// the most recent artifact has expired).
const runs = await github.rest.actions.listWorkflowRuns({
owner: context.repo.owner,
repo: context.repo.repo,
workflow_id: 'ci.yml',
branch: 'main',
status: 'success',
per_page: 1,
per_page: 5,
});
if (runs.data.workflow_runs.length === 0) {
@ -154,32 +155,47 @@ jobs:
return;
}
const mainRunId = runs.data.workflow_runs[0].id;
const artifacts = await github.rest.actions.listWorkflowRunArtifacts({
owner: context.repo.owner,
repo: context.repo.repo,
run_id: mainRunId,
});
// Try each run until we find a downloadable test-reports artifact
for (const run of runs.data.workflow_runs) {
const artifacts = await github.rest.actions.listWorkflowRunArtifacts({
owner: context.repo.owner,
repo: context.repo.repo,
run_id: run.id,
});
const testReports = artifacts.data.artifacts.find(a => a.name === 'test-reports');
if (!testReports) {
core.setOutput('found', 'false');
core.info('No test-reports artifact on main branch');
return;
const testReports = artifacts.data.artifacts.find(a => a.name === 'test-reports');
if (!testReports) {
core.info(`Run ${run.id}: no test-reports artifact, trying next`);
continue;
}
try {
const zip = await github.rest.actions.downloadArtifact({
owner: context.repo.owner,
repo: context.repo.repo,
artifact_id: testReports.id,
archive_format: 'zip',
});
const dest = path.join(process.env.RUNNER_TEMP, 'base-coverage');
fs.mkdirSync(dest, { recursive: true });
fs.writeFileSync(path.join(dest, 'base.zip'), Buffer.from(zip.data));
core.setOutput('found', 'true');
core.setOutput('dir', dest);
return;
} catch (err) {
// 410 Gone means the artifact expired; try the next run
if (err.status === 410 || err.response?.status === 410) {
core.info(`Run ${run.id}: artifact expired, trying next`);
continue;
}
throw err;
}
}
const zip = await github.rest.actions.downloadArtifact({
owner: context.repo.owner,
repo: context.repo.repo,
artifact_id: testReports.id,
archive_format: 'zip',
});
const dest = path.join(process.env.RUNNER_TEMP, 'base-coverage');
fs.mkdirSync(dest, { recursive: true });
fs.writeFileSync(path.join(dest, 'base.zip'), Buffer.from(zip.data));
core.setOutput('found', 'true');
core.setOutput('dir', dest);
// All attempts exhausted — no usable base coverage
core.setOutput('found', 'false');
core.info('No downloadable test-reports artifact found on main (all expired or missing)');
- name: Extract base coverage
if: steps.meta.outputs.skip != 'true' && steps.base-coverage.outputs.found == 'true'
@ -234,7 +250,7 @@ jobs:
printf -v "${prefix}_BRANCH_COV" '%s' ""
printf -v "${prefix}_FUNCS_COV" '%s' ""
printf -v "${prefix}_LINES_COV" '%s' ""
return 1
return 0
fi
}

16
.github/workflows/release-candidate.yml vendored
View file

@ -123,7 +123,16 @@ jobs:
runs-on: ubuntu-latest
timeout-minutes: 20
permissions:
contents: write # push rc tag + marker
# The default GITHUB_TOKEN cannot be granted `workflows: write`, so
# tag pushes that reach a commit which modified `.github/workflows/**`
# are rejected with: "refusing to allow a GitHub App to create or
# update workflow ... without `workflows` permission". We pass a
# fine-grained PAT (RELEASE_PUSH_TOKEN, scoped to this repo with
# Contents: write + Workflows: write) to `actions/checkout` so that
# the subsequent `git push --atomic` of the v-tag and rc marker
# carries the PAT's identity. Job-level GITHUB_TOKEN keeps its
# scoped permissions for everything else (npm provenance, etc.).
contents: write # push rc tag + marker (via PAT)
id-token: write # npm provenance
outputs:
vtag: ${{ steps.reltag.outputs.vtag }}
@ -132,6 +141,11 @@ jobs:
with:
fetch-depth: 0
fetch-tags: true
# Use the PAT so `origin` is preauthed for `git push`. Without
# this the default GITHUB_TOKEN is wired into the remote, and a
# workflows-touching tag push is rejected — see the permissions
# block above.
token: ${{ secrets.RELEASE_PUSH_TOKEN }}
- uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
with:

85
eslint.config.mjs
View file

@ -4,6 +4,38 @@ import unusedImports from 'eslint-plugin-unused-imports';
import reactHooks from 'eslint-plugin-react-hooks';
import prettierConfig from 'eslint-config-prettier';
// Selectors that protect MCP-reachable code from corrupting the JSON-RPC
// stdio frame stream. The MCP-reachable block below uses these directly;
// the lbug-adapter file-specific block must spread them in too because
// ESLint flat config REPLACES (not merges) `no-restricted-syntax` when
// multiple matching configs target the same file. Extracting to a const
// makes the dependency mechanical instead of documentation-enforced.
const mcpStdoutWriteSelectors = [
{
selector:
"MemberExpression[object.type='MemberExpression'][object.object.name='process'][object.property.name='stdout'][property.name='write']",
message:
'Direct process.stdout.write is forbidden in MCP-reachable code. Route diagnostics through console.error or process.stderr.write — the MCP stdio transport owns stdout for JSON-RPC frames.',
},
{
selector:
"CallExpression[callee.type='MemberExpression'][callee.object.type='MemberExpression'][callee.object.object.name='process'][callee.object.property.name='stdout'][callee.property.name='write']",
message:
'Direct process.stdout.write is forbidden in MCP-reachable code. Route diagnostics through console.error or process.stderr.write — the MCP stdio transport owns stdout for JSON-RPC frames.',
},
{
// Catches the canonical destructuring shape:
// const { write } = process.stdout;
// (and any other ObjectPattern destructure rooted at process.stdout)
// which would otherwise capture a reference to the original write
// and bypass the sentinel.
selector:
"VariableDeclarator[init.type='MemberExpression'][init.object.name='process'][init.property.name='stdout'] > ObjectPattern",
message:
'Destructuring process.stdout is forbidden in MCP-reachable code — bypasses the sentinel. Use process.stderr.write for diagnostics.',
},
];
export default [
// Global ignores
{
@ -59,11 +91,26 @@ export default [
},
},
// CLI package — allow console.log (it's a CLI tool)
// CLI/server packages — `console.log` IS the contract (CLI tool data output
// on stdout, e.g. `gitnexus query | jq`; server pretty-printed banners).
// Diagnostic logging (`warn`/`error`/`debug`/`info`) goes through pino like
// the rest of the codebase.
{
files: ['gitnexus/src/cli/**/*.ts', 'gitnexus/src/server/**/*.ts'],
rules: {
'no-console': 'off',
'no-console': ['error', { allow: ['log'] }],
},
},
// Forcing function for the pino migration. Severity is `error` — the
// codebase-wide migration is complete; new `console.*` in core source
// must fail lint. CLI/server are exempt above (legitimate stdout output).
// Tests, bin scripts, and the logger module itself remain exempt.
{
files: ['gitnexus/src/**/*.ts'],
ignores: ['gitnexus/src/cli/**', 'gitnexus/src/server/**', 'gitnexus/src/core/logger.ts'],
rules: {
'no-console': 'error',
},
},
@ -84,32 +131,7 @@ export default [
],
rules: {
'no-console': ['error', { allow: ['error'] }],
'no-restricted-syntax': [
'error',
{
selector:
"MemberExpression[object.type='MemberExpression'][object.object.name='process'][object.property.name='stdout'][property.name='write']",
message:
'Direct process.stdout.write is forbidden in MCP-reachable code. Route diagnostics through console.error or process.stderr.write — the MCP stdio transport owns stdout for JSON-RPC frames.',
},
{
selector:
"CallExpression[callee.type='MemberExpression'][callee.object.type='MemberExpression'][callee.object.object.name='process'][callee.object.property.name='stdout'][callee.property.name='write']",
message:
'Direct process.stdout.write is forbidden in MCP-reachable code. Route diagnostics through console.error or process.stderr.write — the MCP stdio transport owns stdout for JSON-RPC frames.',
},
{
// Catches the canonical destructuring shape:
// const { write } = process.stdout;
// (and any other ObjectPattern destructure rooted at process.stdout)
// which would otherwise capture a reference to the original write
// and bypass the sentinel.
selector:
"VariableDeclarator[init.type='MemberExpression'][init.object.name='process'][init.property.name='stdout'] > ObjectPattern",
message:
'Destructuring process.stdout is forbidden in MCP-reachable code — bypasses the sentinel. Use process.stderr.write for diagnostics.',
},
],
'no-restricted-syntax': ['error', ...mcpStdoutWriteSelectors],
},
},
@ -129,11 +151,18 @@ export default [
// All close operations must go through safeClose() so the WAL is always
// flushed before the connection is released. The sole authorised call site
// inside safeClose itself uses an eslint-disable-next-line override.
//
// ESLint flat config REPLACES (not merges) `no-restricted-syntax` when
// multiple matching configs target the same file. lbug-adapter.ts is also
// covered by the MCP-reachable block above, so we spread the shared
// mcpStdoutWriteSelectors here alongside the safeClose selectors. Without
// this, lbug-adapter would silently lose its MCP stdout-write protection.
{
files: ['gitnexus/src/core/lbug/lbug-adapter.ts'],
rules: {
'no-restricted-syntax': [
'error',
...mcpStdoutWriteSelectors,
{
selector: "CallExpression[callee.object.name='conn'][callee.property.name='close']",
message: 'Use safeClose() instead of calling conn.close() directly (#1376).',

6
gitnexus-web/src/core/llm/agent.ts
View file

@ -277,8 +277,10 @@ const extractInstanceName = (endpoint: string): string => {
try {
const url = new URL(endpoint);
const hostname = url.hostname;
// Extract the first part before .openai.azure.com
const match = hostname.match(/^([^.]+)\.openai\.azure\.com/);
// Extract the first part before .openai.azure.com. The trailing `$`
// anchor is required (CodeQL js/regex/missing-regexp-anchor): without
// it `evil.openai.azure.com.attacker.tld` would match.
const match = hostname.match(/^([^.]+)\.openai\.azure\.com$/);
if (match) {
return match[1];
}

7
gitnexus-web/src/core/llm/tools.ts
View file

@ -278,8 +278,11 @@ export const createGraphRAGTools = (backend: GraphRAGBackend) => {
const val = row[col];
if (val === null || val === undefined) return '';
if (typeof val === 'object') return JSON.stringify(val);
// Truncate long values and escape pipe characters
const str = String(val).replace(/\|/g, '\\|');
// Truncate long values and escape pipe characters. Escape
// backslashes FIRST so the subsequent pipe escape isn't
// unescaped by a trailing backslash (CodeQL
// js/incomplete-sanitization).
const str = String(val).replace(/\\/g, '\\\\').replace(/\|/g, '\\|');
return str.length > 60 ? str.slice(0, 57) + '...' : str;
});
return `| ${values.join(' | ')} |`;

252
gitnexus/package-lock.json generated
View file

@ -30,6 +30,8 @@
"mnemonist": "^0.40.3",
"onnxruntime-node": "^1.24.0",
"pandemonium": "^2.4.0",
"pino": "^10.3.1",
"pino-pretty": "^13.1.3",
"tree-sitter": "^0.21.1",
"tree-sitter-c": "0.21.4",
"tree-sitter-c-sharp": "0.23.1",
@ -1579,6 +1581,12 @@
"url": "https://github.com/sponsors/Boshen"
}
},
"node_modules/@pinojs/redact": {
"version": "0.4.0",
"resolved": "https://registry.npmjs.org/@pinojs/redact/-/redact-0.4.0.tgz",
"integrity": "sha512-k2ENnmBugE/rzQfEcdWHcCY+/FM3VLzH9cYEsbdsoqrvzAKRhUZeRNhAZvB8OitQJ1TBed3yqWtdjzS6wJKBwg==",
"license": "MIT"
},
"node_modules/@protobufjs/aspromise": {
"version": "1.1.2",
"resolved": "https://registry.npmjs.org/@protobufjs/aspromise/-/aspromise-1.1.2.tgz",
@ -2057,9 +2065,9 @@
"license": "MIT"
},
"node_modules/@types/node": {
"version": "25.6.0",
"resolved": "https://registry.npmjs.org/@types/node/-/node-25.6.0.tgz",
"integrity": "sha512-+qIYRKdNYJwY3vRCZMdJbPLJAtGjQBudzZzdzwQYkEPQd+PJGixUL5QfvCLDaULoLv+RhT3LDkwEfKaAkgSmNQ==",
"version": "25.6.1",
"resolved": "https://registry.npmjs.org/@types/node/-/node-25.6.1.tgz",
"integrity": "sha512-coJCN8O1q4AGyyqCAUSP06P+SrMTu18BkEj3NVAK07q6QUneD2wzj3CLv9+yP+BMeZQlMvneXqqvDe3w+xcq7g==",
"license": "MIT",
"dependencies": {
"undici-types": "~7.19.0"
@ -2380,6 +2388,15 @@
"js-tokens": "^10.0.0"
}
},
"node_modules/atomic-sleep": {
"version": "1.0.0",
"resolved": "https://registry.npmjs.org/atomic-sleep/-/atomic-sleep-1.0.0.tgz",
"integrity": "sha512-kNOjDqAh7px0XWNI+4QbzoiR/nTkHAWNud2uvnJquD1/x5a7EQZMJT0AczqK0Qn67oY/TTQ1LbUKajZpp3I9tQ==",
"license": "MIT",
"engines": {
"node": ">=8.0.0"
}
},
"node_modules/balanced-match": {
"version": "4.0.4",
"resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz",
@ -2579,6 +2596,12 @@
"integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==",
"license": "MIT"
},
"node_modules/colorette": {
"version": "2.0.20",
"resolved": "https://registry.npmjs.org/colorette/-/colorette-2.0.20.tgz",
"integrity": "sha512-IfEDxwoWIjkeXL1eXcDiow4UbKjhLdq6/EuSVR9GMN7KVH3r9gQ83e73hsz1Nd1T3ijd5xv1wcWRYO+D6kCI2w==",
"license": "MIT"
},
"node_modules/commander": {
"version": "14.0.3",
"resolved": "https://registry.npmjs.org/commander/-/commander-14.0.3.tgz",
@ -2683,6 +2706,15 @@
"node": ">= 8"
}
},
"node_modules/dateformat": {
"version": "4.6.3",
"resolved": "https://registry.npmjs.org/dateformat/-/dateformat-4.6.3.tgz",
"integrity": "sha512-2P0p0pFGzHS5EMnhdxQi7aJN+iMheud0UhG4dlE1DLAlvL8JHjJJTX/CSm4JXwV0Ka5nGk3zC5mcb5bUQUxxMA==",
"license": "MIT",
"engines": {
"node": "*"
}
},
"node_modules/debug": {
"version": "4.4.3",
"resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
@ -2806,6 +2838,15 @@
"node": ">= 0.8"
}
},
"node_modules/end-of-stream": {
"version": "1.4.5",
"resolved": "https://registry.npmjs.org/end-of-stream/-/end-of-stream-1.4.5.tgz",
"integrity": "sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg==",
"license": "MIT",
"dependencies": {
"once": "^1.4.0"
}
},
"node_modules/es-define-property": {
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz",
@ -3050,12 +3091,24 @@
"integrity": "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==",
"license": "MIT"
},
"node_modules/fast-copy": {
"version": "4.0.3",
"resolved": "https://registry.npmjs.org/fast-copy/-/fast-copy-4.0.3.tgz",
"integrity": "sha512-58apWr0GUiDFM8+3afrO6eYwJBn9ZAhDOzG3L+/9llab/haCARS2UIfffmOurYLwbgDRs8n0rfr6qAAPEAuAQw==",
"license": "MIT"
},
"node_modules/fast-deep-equal": {
"version": "3.1.3",
"resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
"integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
"license": "MIT"
},
"node_modules/fast-safe-stringify": {
"version": "2.1.1",
"resolved": "https://registry.npmjs.org/fast-safe-stringify/-/fast-safe-stringify-2.1.1.tgz",
"integrity": "sha512-W+KJc2dmILlPplD/H4K9l9LcAHAfPtP6BY84uVLXQ6Evcz9Lcg33Y2z1IVblT6xdY54PXYVHEv+0Wpq8Io6zkA==",
"license": "MIT"
},
"node_modules/fast-uri": {
"version": "3.1.0",
"resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.0.tgz",
@ -3416,6 +3469,12 @@
"node": ">= 0.4"
}
},
"node_modules/help-me": {
"version": "5.0.0",
"resolved": "https://registry.npmjs.org/help-me/-/help-me-5.0.0.tgz",
"integrity": "sha512-7xgomUX6ADmcYzFik0HzAxh/73YlKR9bmFzf51CZwR+b6YtzU2m0u49hQCqV6SvlqIqsaxovfwdvbnsw3b/zpg==",
"license": "MIT"
},
"node_modules/hono": {
"version": "4.12.16",
"resolved": "https://registry.npmjs.org/hono/-/hono-4.12.16.tgz",
@ -3575,6 +3634,15 @@
"url": "https://github.com/sponsors/panva"
}
},
"node_modules/joycon": {
"version": "3.1.1",
"resolved": "https://registry.npmjs.org/joycon/-/joycon-3.1.1.tgz",
"integrity": "sha512-34wB/Y7MW7bzjKRjUKTa46I2Z7eV62Rkhva+KkopW7Qvv/OSWBqvkSY7vusOPrNuZcUG3tApvdVgNB8POj3SPw==",
"license": "MIT",
"engines": {
"node": ">=10"
}
},
"node_modules/js-tokens": {
"version": "10.0.0",
"resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-10.0.0.tgz",
@ -4183,6 +4251,15 @@
],
"license": "MIT"
},
"node_modules/on-exit-leak-free": {
"version": "2.1.2",
"resolved": "https://registry.npmjs.org/on-exit-leak-free/-/on-exit-leak-free-2.1.2.tgz",
"integrity": "sha512-0eJJY6hXLGf1udHwfNftBqH+g73EU4B504nZeKpz1sYRKafAghwxEJunB2O7rDZkL4PGfsMVnTXZ2EjibbqcsA==",
"license": "MIT",
"engines": {
"node": ">=14.0.0"
}
},
"node_modules/on-finished": {
"version": "2.4.1",
"resolved": "https://registry.npmjs.org/on-finished/-/on-finished-2.4.1.tgz",
@ -4332,6 +4409,79 @@
"url": "https://github.com/sponsors/jonschlinkert"
}
},
"node_modules/pino": {
"version": "10.3.1",
"resolved": "https://registry.npmjs.org/pino/-/pino-10.3.1.tgz",
"integrity": "sha512-r34yH/GlQpKZbU1BvFFqOjhISRo1MNx1tWYsYvmj6KIRHSPMT2+yHOEb1SG6NMvRoHRF0a07kCOox/9yakl1vg==",
"license": "MIT",
"dependencies": {
"@pinojs/redact": "^0.4.0",
"atomic-sleep": "^1.0.0",
"on-exit-leak-free": "^2.1.0",
"pino-abstract-transport": "^3.0.0",
"pino-std-serializers": "^7.0.0",
"process-warning": "^5.0.0",
"quick-format-unescaped": "^4.0.3",
"real-require": "^0.2.0",
"safe-stable-stringify": "^2.3.1",
"sonic-boom": "^4.0.1",
"thread-stream": "^4.0.0"
},
"bin": {
"pino": "bin.js"
}
},
"node_modules/pino-abstract-transport": {
"version": "3.0.0",
"resolved": "https://registry.npmjs.org/pino-abstract-transport/-/pino-abstract-transport-3.0.0.tgz",
"integrity": "sha512-wlfUczU+n7Hy/Ha5j9a/gZNy7We5+cXp8YL+X+PG8S0KXxw7n/JXA3c46Y0zQznIJ83URJiwy7Lh56WLokNuxg==",
"license": "MIT",
"dependencies": {
"split2": "^4.0.0"
}
},
"node_modules/pino-pretty": {
"version": "13.1.3",
"resolved": "https://registry.npmjs.org/pino-pretty/-/pino-pretty-13.1.3.tgz",
"integrity": "sha512-ttXRkkOz6WWC95KeY9+xxWL6AtImwbyMHrL1mSwqwW9u+vLp/WIElvHvCSDg0xO/Dzrggz1zv3rN5ovTRVowKg==",
"license": "MIT",
"dependencies": {
"colorette": "^2.0.7",
"dateformat": "^4.6.3",
"fast-copy": "^4.0.0",
"fast-safe-stringify": "^2.1.1",
"help-me": "^5.0.0",
"joycon": "^3.1.1",
"minimist": "^1.2.6",
"on-exit-leak-free": "^2.1.0",
"pino-abstract-transport": "^3.0.0",
"pump": "^3.0.0",
"secure-json-parse": "^4.0.0",
"sonic-boom": "^4.0.1",
"strip-json-comments": "^5.0.2"
},
"bin": {
"pino-pretty": "bin.js"
}
},
"node_modules/pino-pretty/node_modules/strip-json-comments": {
"version": "5.0.3",
"resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-5.0.3.tgz",
"integrity": "sha512-1tB5mhVo7U+ETBKNf92xT4hrQa3pm0MZ0PQvuDnWgAAGHDsfp4lPSpiS6psrSiet87wyGPh9ft6wmhOMQ0hDiw==",
"license": "MIT",
"engines": {
"node": ">=14.16"
},
"funding": {
"url": "https://github.com/sponsors/sindresorhus"
}
},
"node_modules/pino-std-serializers": {
"version": "7.1.0",
"resolved": "https://registry.npmjs.org/pino-std-serializers/-/pino-std-serializers-7.1.0.tgz",
"integrity": "sha512-BndPH67/JxGExRgiX1dX0w1FvZck5Wa4aal9198SrRhZjH3GxKQUKIBnYJTdj2HDN3UQAS06HlfcSbQj2OHmaw==",
"license": "MIT"
},
"node_modules/pkce-challenge": {
"version": "5.0.1",
"resolved": "https://registry.npmjs.org/pkce-challenge/-/pkce-challenge-5.0.1.tgz",
@ -4376,6 +4526,22 @@
"node": "^10 || ^12 || >=14"
}
},
"node_modules/process-warning": {
"version": "5.0.0",
"resolved": "https://registry.npmjs.org/process-warning/-/process-warning-5.0.0.tgz",
"integrity": "sha512-a39t9ApHNx2L4+HBnQKqxxHNs1r7KF+Intd8Q/g1bUh6q0WIp9voPXJ/x0j+ZL45KF1pJd9+q2jLIRMfvEshkA==",
"funding": [
{
"type": "github",
"url": "https://github.com/sponsors/fastify"
},
{
"type": "opencollective",
"url": "https://opencollective.com/fastify"
}
],
"license": "MIT"
},
"node_modules/protobufjs": {
"version": "7.5.5",
"resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.5.5.tgz",
@ -4413,6 +4579,16 @@
"node": ">= 0.10"
}
},
"node_modules/pump": {
"version": "3.0.4",
"resolved": "https://registry.npmjs.org/pump/-/pump-3.0.4.tgz",
"integrity": "sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA==",
"license": "MIT",
"dependencies": {
"end-of-stream": "^1.1.0",
"once": "^1.3.1"
}
},
"node_modules/qs": {
"version": "6.14.2",
"resolved": "https://registry.npmjs.org/qs/-/qs-6.14.2.tgz",
@ -4428,6 +4604,12 @@
"url": "https://github.com/sponsors/ljharb"
}
},
"node_modules/quick-format-unescaped": {
"version": "4.0.4",
"resolved": "https://registry.npmjs.org/quick-format-unescaped/-/quick-format-unescaped-4.0.4.tgz",
"integrity": "sha512-tYC1Q1hgyRuHgloV/YXs2w15unPVh8qfu/qCTfhTYamaw7fyhumKa2yGpdSo87vY32rIclj+4fWYQXUMs9EHvg==",
"license": "MIT"
},
"node_modules/range-parser": {
"version": "1.2.1",
"resolved": "https://registry.npmjs.org/range-parser/-/range-parser-1.2.1.tgz",
@ -4483,6 +4665,15 @@
"rc": "cli.js"
}
},
"node_modules/real-require": {
"version": "0.2.0",
"resolved": "https://registry.npmjs.org/real-require/-/real-require-0.2.0.tgz",
"integrity": "sha512-57frrGM/OCTLqLOAh0mhVA9VBMHd+9U7Zb2THMGdBUoZVOtGbJzjxsYGDJ3A9AYYCP4hn6y1TVbaOfzWtm5GFg==",
"license": "MIT",
"engines": {
"node": ">= 12.13.0"
}
},
"node_modules/require-directory": {
"version": "2.1.1",
"resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz",
@ -4591,12 +4782,37 @@
],
"license": "MIT"
},
"node_modules/safe-stable-stringify": {
"version": "2.5.0",
"resolved": "https://registry.npmjs.org/safe-stable-stringify/-/safe-stable-stringify-2.5.0.tgz",
"integrity": "sha512-b3rppTKm9T+PsVCBEOUR46GWI7fdOs00VKZ1+9c1EWDaDMvjQc6tUwuFyIprgGgTcWoVHSKrU8H31ZHA2e0RHA==",
"license": "MIT",
"engines": {
"node": ">=10"
}
},
"node_modules/safer-buffer": {
"version": "2.1.2",
"resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz",
"integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==",
"license": "MIT"
},
"node_modules/secure-json-parse": {
"version": "4.1.0",
"resolved": "https://registry.npmjs.org/secure-json-parse/-/secure-json-parse-4.1.0.tgz",
"integrity": "sha512-l4KnYfEyqYJxDwlNVyRfO2E4NTHfMKAWdUuA8J0yve2Dz/E/PdBepY03RvyJpssIpRFwJoCD55wA+mEDs6ByWA==",
"funding": [
{
"type": "github",
"url": "https://github.com/sponsors/fastify"
},
{
"type": "opencollective",
"url": "https://opencollective.com/fastify"
}
],
"license": "BSD-3-Clause"
},
"node_modules/semver": {
"version": "7.7.4",
"resolved": "https://registry.npmjs.org/semver/-/semver-7.7.4.tgz",
@ -4828,6 +5044,15 @@
"dev": true,
"license": "ISC"
},
"node_modules/sonic-boom": {
"version": "4.2.1",
"resolved": "https://registry.npmjs.org/sonic-boom/-/sonic-boom-4.2.1.tgz",
"integrity": "sha512-w6AxtubXa2wTXAUsZMMWERrsIRAdrK0Sc+FUytWvYAhBJLyuI4llrMIC1DtlNSdI99EI86KZum2MMq3EAZlF9Q==",
"license": "MIT",
"dependencies": {
"atomic-sleep": "^1.0.0"
}
},
"node_modules/source-map-js": {
"version": "1.2.1",
"resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
@ -4838,6 +5063,15 @@
"node": ">=0.10.0"
}
},
"node_modules/split2": {
"version": "4.2.0",
"resolved": "https://registry.npmjs.org/split2/-/split2-4.2.0.tgz",
"integrity": "sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg==",
"license": "ISC",
"engines": {
"node": ">= 10.x"
}
},
"node_modules/stackback": {
"version": "0.0.2",
"resolved": "https://registry.npmjs.org/stackback/-/stackback-0.0.2.tgz",
@ -4925,6 +5159,18 @@
"node": ">=18"
}
},
"node_modules/thread-stream": {
"version": "4.0.0",
"resolved": "https://registry.npmjs.org/thread-stream/-/thread-stream-4.0.0.tgz",
"integrity": "sha512-4iMVL6HAINXWf1ZKZjIPcz5wYaOdPhtO8ATvZ+Xqp3BTdaqtAwQkNmKORqcIo5YkQqGXq5cwfswDwMqqQNrpJA==",
"license": "MIT",
"dependencies": {
"real-require": "^0.2.0"
},
"engines": {
"node": ">=20"
}
},
"node_modules/tinybench": {
"version": "2.9.0",
"resolved": "https://registry.npmjs.org/tinybench/-/tinybench-2.9.0.tgz",

2
gitnexus/package.json
View file

@ -73,6 +73,8 @@
"mnemonist": "^0.40.3",
"onnxruntime-node": "^1.24.0",
"pandemonium": "^2.4.0",
"pino": "^10.3.1",
"pino-pretty": "^13.1.3",
"tree-sitter": "^0.21.1",
"tree-sitter-c": "0.21.4",
"tree-sitter-c-sharp": "0.23.1",

3
gitnexus/src/cli/ai-context.ts
View file

@ -10,6 +10,7 @@ import fs from 'fs/promises';
import path from 'path';
import { fileURLToPath } from 'url';
import { type GeneratedSkillInfo } from './skill-gen.js';
import { logger } from '../core/logger.js';
// ESM equivalent of __dirname
const __filename = fileURLToPath(import.meta.url);
@ -293,7 +294,7 @@ Use GitNexus tools to accomplish this task.
installedSkills.push(skill.name);
} catch (err) {
// Skip on error, don't fail the whole process
console.warn(`Warning: Could not install skill ${skill.name}:`, err);
logger.warn({ err }, `Warning: Could not install skill ${skill.name}:`);
}
}

112
gitnexus/src/cli/analyze.ts
View file

@ -26,6 +26,8 @@ import { getMaxFileSizeBannerMessage } from '../core/ingestion/utils/max-file-si
import { warnMissingOptionalGrammars } from './optional-grammars.js';
import { glob } from 'glob';
import fs from 'fs/promises';
import { cliError } from './cli-message.js';
import { isHfDownloadFailure } from '../core/embeddings/hf-env.js';
// Capture stderr.write at module load BEFORE anything (LadybugDB native
// init, progress bar, console redirection) can monkey-patch it. The
@ -167,7 +169,7 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
if (options?.workerTimeout) {
const workerTimeoutSeconds = Number(options.workerTimeout);
if (!Number.isFinite(workerTimeoutSeconds) || workerTimeoutSeconds < 1) {
console.error(' --worker-timeout must be at least 1 second.\n');
cliError(' --worker-timeout must be at least 1 second.\n');
process.exitCode = 1;
return;
}
@ -184,7 +186,7 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
if (typeof options?.embeddings === 'string') {
const parsed = Number(options.embeddings);
if (!Number.isInteger(parsed) || parsed < 0) {
console.error(
cliError(
` --embeddings expects a non-negative integer (got "${options.embeddings}"). ` +
`Pass 0 to disable the safety cap, or omit the value to keep the default.\n`,
);
@ -203,7 +205,7 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
if (value === undefined) return true;
const parsed = Number(value);
if (!Number.isInteger(parsed) || parsed <= 0) {
console.error(` ${optionName} must be a positive integer.\n`);
cliError(` ${optionName} must be a positive integer.\n`);
process.exitCode = 1;
return false;
}
@ -234,7 +236,7 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
if (options?.embeddingDevice) {
const allowed = new Set(['auto', 'cpu', 'dml', 'cuda', 'wasm']);
if (!allowed.has(options.embeddingDevice)) {
console.error(' --embedding-device must be one of: auto, cpu, dml, cuda, wasm.\n');
cliError(' --embedding-device must be one of: auto, cpu, dml, cuda, wasm.\n');
process.exitCode = 1;
return;
}
@ -330,7 +332,9 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
bar.start(100, 0, { phase: 'Initializing...' });
// Graceful SIGINT handling
// Graceful SIGINT handling. Pino's default destination is `sync: false`
// (buffered) — flush before exit so in-flight records reach stderr.
// See `gitnexus/src/core/logger.ts:flushLoggerSync`.
let aborted = false;
const sigintHandler = () => {
if (aborted) process.exit(1);
@ -339,13 +343,23 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
console.log('\n Interrupted — cleaning up...');
closeLbug()
.catch(() => {})
.finally(() => process.exit(130));
.finally(async () => {
const { flushLoggerSync } = await import('../core/logger.js');
flushLoggerSync();
process.exit(130);
});
};
process.on('SIGINT', sigintHandler);
// Route console output through bar.log() to prevent progress bar corruption
// Route console output through bar.log() to prevent progress bar corruption.
// This is a deliberate UI pattern (not a logging concern): analyze runs a
// long-lived progress bar on stdout; any concurrent console.* write would
// overwrite the bar mid-render. We capture originals, swap to barLog for
// the lifetime of the run, and restore on completion/error/SIGINT.
const origLog = console.log.bind(console);
// eslint-disable-next-line no-console -- intentional console-routing for progress bar UX
const origWarn = console.warn.bind(console);
// eslint-disable-next-line no-console -- intentional console-routing for progress bar UX
const origError = console.error.bind(console);
let barCurrentValue = 0;
const barLog = (...args: any[]) => {
@ -354,7 +368,9 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
bar.update(barCurrentValue);
};
console.log = barLog;
// eslint-disable-next-line no-console -- intentional console-routing for progress bar UX
console.warn = barLog;
// eslint-disable-next-line no-console -- intentional console-routing for progress bar UX
console.error = barLog;
// Track elapsed time per phase
@ -420,7 +436,9 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
clearInterval(elapsedTimer);
process.removeListener('SIGINT', sigintHandler);
console.log = origLog;
// eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
console.warn = origWarn;
// eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
console.error = origError;
bar.stop();
console.log(' Already up to date\n');
@ -493,7 +511,9 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
process.removeListener('SIGINT', sigintHandler);
console.log = origLog;
// eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
console.warn = origWarn;
// eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
console.error = origError;
bar.update(100, { phase: 'Done' });
@ -518,7 +538,9 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
clearInterval(elapsedTimer);
process.removeListener('SIGINT', sigintHandler);
console.log = origLog;
// eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
console.warn = origWarn;
// eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
console.error = origError;
bar.stop();
@ -527,14 +549,14 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
// Registry name-collision from --name (#829) — surface as an
// actionable error rather than a generic stack-trace.
if (err instanceof RegistryNameCollisionError) {
console.error(`\n Registry name collision:\n`);
console.error(` "${err.registryName}" is already used by "${err.existingPath}".\n`);
console.error(` Options:`);
console.error(` • Pick a different alias: gitnexus analyze --name <alias>`);
console.error(
` • Allow the duplicate: gitnexus analyze --allow-duplicate-name (leaves "-r ${err.registryName}" ambiguous)`,
cliError(
`\n Registry name collision:\n` +
` "${err.registryName}" is already used by "${err.existingPath}".\n\n` +
` Options:\n` +
` • Pick a different alias: gitnexus analyze --name <alias>\n` +
` • Allow the duplicate: gitnexus analyze --allow-duplicate-name (leaves "-r ${err.registryName}" ambiguous)\n`,
{ registryName: err.registryName, existingPath: err.existingPath },
);
console.error('');
process.exitCode = 1;
return;
}
@ -555,6 +577,26 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
return;
}
// HF download failure — show clean guidance without the raw stack trace.
// Checked before writeFatalToStderr so the user sees one focused message
// rather than a stack-trace dump followed by a second remediation block.
if (isHfDownloadFailure(msg) || msg.includes('Failed to download embedding model')) {
cliError(
` The embedding model could not be downloaded.\n` +
` huggingface.co may be unreachable from your network\n` +
` (e.g. behind a corporate proxy or a regional firewall).\n` +
` Suggestions:\n` +
` 1. Set HF_ENDPOINT to a mirror and retry:\n` +
` HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings\n` +
` (Windows: set HF_ENDPOINT=https://hf-mirror.com && npx gitnexus analyze --embeddings)\n` +
` 2. Check your proxy / VPN settings.\n` +
` 3. Once downloaded the model is cached — future runs work offline.\n`,
{ recoveryHint: 'hf-endpoint-unreachable' },
);
process.exitCode = 1;
return;
}
// Bypass the redirected console.error and write the full stack to
// the real stderr captured at module load. The redirected
// console.error wraps every line with `\\x1b[2K\\r` (ANSI clear-line)
@ -574,34 +616,40 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
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('');
cliError(
` This error typically occurs on very large repositories.\n` +
` Suggestions:\n` +
` 1. Add large vendored/generated directories to .gitnexusignore\n` +
` 2. Increase Node.js heap: NODE_OPTIONS="--max-old-space-size=16384"\n` +
` 3. Increase stack size: NODE_OPTIONS="--stack-size=4096"\n`,
{ recoveryHint: 'large-repo' },
);
} 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('');
cliError(
` This looks like an npm dependency resolution issue.\n` +
` Suggestions:\n` +
` 1. Clear the npm cache: npm cache clean --force\n` +
` 2. Update npm: npm install -g npm@latest\n` +
` 3. Reinstall gitnexus: npm install -g gitnexus@latest\n` +
` 4. Or try npx directly: npx gitnexus@latest analyze\n`,
{ recoveryHint: 'npm-resolution' },
);
} 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('');
cliError(
` A required module could not be loaded. The installation may be corrupt.\n` +
` Suggestions:\n` +
` 1. Reinstall: npm install -g gitnexus@latest\n` +
` 2. Clear cache: npm cache clean --force && npx gitnexus@latest analyze\n`,
{ recoveryHint: 'module-not-found' },
);
}
process.exitCode = 1;

7
gitnexus/src/cli/clean.ts
View file

@ -6,6 +6,7 @@
*/
import fs from 'fs/promises';
import { logger } from '../core/logger.js';
import {
findRepo,
unregisterRepo,
@ -45,7 +46,7 @@ export const cleanCommand = async (options?: { force?: boolean; all?: boolean })
assertSafeStoragePath(entry);
} catch (err) {
if (err instanceof UnsafeStoragePathError) {
console.error(`Refusing to clean ${entry.name}: ${err.message}`);
logger.error(`Refusing to clean ${entry.name}: ${err.message}`);
continue;
}
throw err;
@ -56,7 +57,7 @@ export const cleanCommand = async (options?: { force?: boolean; all?: boolean })
await unregisterRepo(entry.path);
console.log(`Deleted: ${entry.name} (${entry.storagePath})`);
} catch (err) {
console.error(`Failed to delete ${entry.name}:`, err);
logger.error({ err }, `Failed to delete ${entry.name}:`);
}
}
return;
@ -85,6 +86,6 @@ export const cleanCommand = async (options?: { force?: boolean; all?: boolean })
await unregisterRepo(repo.repoPath);
console.log(`Deleted: ${repo.storagePath}`);
} catch (err) {
console.error('Failed to delete:', err);
logger.error({ err }, 'Failed to delete:');
}
};

65
gitnexus/src/cli/cli-message.ts Normal file
View file

@ -0,0 +1,65 @@
/**
* CLI message helpers — for user-facing banners, error guidance, and
* recovery hints emitted by `gitnexus` subcommands.
*
* These functions write **plain text** directly to `process.stderr` AND
* tee a structured pino record through the singleton `logger`. Plain text
* preserves the human-readable contract for users running `gitnexus`
* interactively, redirecting to a file, or piping to `cat`/`grep`. The
* structured tee keeps log aggregators happy.
*
* **Use these for:**
* - User-facing banners ("Server listening on http://...:N")
* - Validation errors ("--worker-timeout must be at least 1 second")
* - Recovery hints ("Suggestions: 1. Clear the npm cache, 2. ...")
* - One-line user notices ("No indexed repositories found.")
*
* **Do NOT use these for:**
* - Internal diagnostics (worker progress, retry counts, telemetry)
* — use `logger.info`/`warn`/`error` directly. Internal logs only
* need structured fields, not double-output to stderr.
* - High-volume hot paths — every `cliMessage` call writes twice (raw
* + structured). Acceptable for user-facing messages, wasteful for
* ingestion pipeline events.
*
* Design note: stderr is the right channel even for non-error messages
* because GitNexus CLI tools (`query`, `cypher`, `impact`) emit JSON
* data on stdout for piping (`gitnexus query | jq`). User banners on
* stdout would corrupt that pipeline.
*/
import { logger } from '../core/logger.js';
function writeStderr(msg: string): void {
// Direct write — bypassing `console.*` so it cannot be intercepted by
// progress-bar redirection (see `cli/analyze.ts:barLog`) or other
// routing. The structured tee below still goes through the logger so
// log aggregation works either way.
process.stderr.write(msg.endsWith('\n') ? msg : msg + '\n');
}
/**
* User-facing informational message. Use for banners, listening URLs,
* and any message the user expects to read in plain text.
*/
export function cliInfo(msg: string, fields?: Record<string, unknown>): void {
writeStderr(msg);
logger.info(fields ?? {}, msg);
}
/**
* User-facing warning. Operator-actionable but non-fatal — `cliWarn`
* indicates the command can still proceed in some form.
*/
export function cliWarn(msg: string, fields?: Record<string, unknown>): void {
writeStderr(msg);
logger.warn(fields ?? {}, msg);
}
/**
* User-facing error. Indicates the command cannot proceed; usually
* paired with a non-zero exit code at the call site.
*/
export function cliError(msg: string, fields?: Record<string, unknown>): void {
writeStderr(msg);
logger.error(fields ?? {}, msg);
}

52
gitnexus/src/cli/eval-server.ts
View file

@ -27,6 +27,8 @@
import http from 'http';
import { writeSync } from 'node:fs';
import { LocalBackend } from '../mcp/local/local-backend.js';
import { logger } from '../core/logger.js';
import { cliInfo, cliWarn } from './cli-message.js';
export interface EvalServerOptions {
port?: string;
@ -332,13 +334,19 @@ export async function evalServerCommand(options?: EvalServerOptions): Promise<vo
const ok = await backend.init();
if (!ok) {
console.error('GitNexus eval-server: No indexed repositories found. Run: gitnexus analyze');
// Operator-actionable but the server cannot start; warn-level so log
// aggregators don't trip error alerts on a configuration miss. Use
// cliWarn so the diagnostic reaches stderr synchronously before
// process.exit() — direct logger.warn would be lost to the buffered
// pino destination on hard exit (skips beforeExit flush).
cliWarn('GitNexus eval-server: No indexed repositories found. Run: gitnexus analyze');
process.exit(1);
}
const repos = await backend.listRepos();
console.error(
`GitNexus eval-server: ${repos.length} repo(s) loaded: ${repos.map((r) => r.name).join(', ')}`,
logger.info(
{ repoCount: repos.length, repos: repos.map((r) => r.name) },
'GitNexus eval-server: repos loaded',
);
let idleTimer: ReturnType<typeof setTimeout> | null = null;
@ -347,7 +355,7 @@ export async function evalServerCommand(options?: EvalServerOptions): Promise<vo
if (idleTimeoutSec <= 0) return;
if (idleTimer) clearTimeout(idleTimer);
idleTimer = setTimeout(async () => {
console.error('GitNexus eval-server: Idle timeout reached, shutting down');
logger.info({ idleTimeoutSec }, 'GitNexus eval-server: idle timeout reached, shutting down');
await backend.disconnect();
process.exit(0);
}, idleTimeoutSec * 1000);
@ -419,16 +427,34 @@ export async function evalServerCommand(options?: EvalServerOptions): Promise<vo
});
server.listen(port, '127.0.0.1', () => {
console.error(`GitNexus eval-server: listening on http://127.0.0.1:${port}`);
console.error(` POST /tool/query — search execution flows`);
console.error(` POST /tool/context — 360-degree symbol view`);
console.error(` POST /tool/impact — blast radius analysis`);
console.error(` POST /tool/cypher — raw Cypher query`);
console.error(` GET /health — health check`);
console.error(` POST /shutdown — graceful shutdown`);
// Plain-text banner for the human watching stderr; structured record
// for log aggregation (split into two so the user sees a real banner
// not `{"level":30,"msg":"...","port":4747,"endpoints":[...]}`).
const bannerLines = [
`GitNexus eval-server: listening on http://127.0.0.1:${port}`,
` POST /tool/query — search execution flows`,
` POST /tool/context — 360-degree symbol view`,
` POST /tool/impact — blast radius analysis`,
` POST /tool/cypher — raw Cypher query`,
` GET /health — health check`,
` POST /shutdown — graceful shutdown`,
];
if (idleTimeoutSec > 0) {
console.error(` Auto-shutdown after ${idleTimeoutSec}s idle`);
bannerLines.push(` Auto-shutdown after ${idleTimeoutSec}s idle`);
}
cliInfo(bannerLines.join('\n'), {
port,
host: '127.0.0.1',
idleTimeoutSec: idleTimeoutSec > 0 ? idleTimeoutSec : undefined,
endpoints: [
'POST /tool/query',
'POST /tool/context',
'POST /tool/impact',
'POST /tool/cypher',
'GET /health',
'POST /shutdown',
],
});
try {
// Use fd 1 directly — LadybugDB captures process.stdout (#324)
writeSync(1, `GITNEXUS_EVAL_SERVER_READY:${port}\n`);
@ -440,7 +466,7 @@ export async function evalServerCommand(options?: EvalServerOptions): Promise<vo
resetIdleTimer();
const shutdown = async () => {
console.error('GitNexus eval-server: shutting down...');
logger.info('GitNexus eval-server: shutting down...');
await backend.disconnect();
server.close();
process.exit(0);

7
gitnexus/src/cli/group.ts
View file

@ -1,6 +1,7 @@
// gitnexus/src/cli/group.ts
import { createRequire } from 'node:module';
import type { Command } from 'commander';
import { logger } from '../core/logger.js';
const _require = createRequire(import.meta.url);
const yaml = _require('js-yaml') as typeof import('js-yaml');
@ -51,7 +52,7 @@ export function registerGroupCommands(program: Command): void {
const groupDir = getGroupDir(getDefaultGitnexusDir(), groupName);
const config = await loadGroupConfig(groupDir);
if (!(repoPath in config.repos)) {
console.error(`Repo path "${repoPath}" not found in group "${groupName}"`);
logger.error(`Repo path "${repoPath}" not found in group "${groupName}"`);
process.exitCode = 1;
return;
}
@ -239,7 +240,7 @@ export function registerGroupCommands(program: Command): void {
const raw = await backend.getGroupService().groupImpact(payload);
if (raw && typeof raw === 'object' && 'error' in raw) {
console.error(String((raw as { error: string }).error));
logger.error(String((raw as { error: string }).error));
process.exitCode = 1;
return;
}
@ -333,7 +334,7 @@ export function registerGroupCommands(program: Command): void {
});
if (raw && typeof raw === 'object' && 'error' in raw) {
console.error(String((raw as { error: string }).error));
logger.error(String((raw as { error: string }).error));
process.exitCode = 1;
return;
}

21
gitnexus/src/cli/mcp.ts
View file

@ -41,11 +41,17 @@ export const mcpCommand = async () => {
// path runs cleanly with full stack traces. Registering duplicates here
// would only produce noisy double-logging on the same exception.
// Now safe to dynamically import the heavy backend modules. Anything
// they emit to stdout during evaluation will route through the sentinel.
const [{ startMCPServer }, { LocalBackend }] = await Promise.all([
// Dynamically import heavy backend modules AND the pino logger AFTER
// the sentinel installs. The logger is dynamic-imported (rather than
// static) to preserve the leaf-only static-import closure documented at
// the top of this file — `core/logger.js` itself doesn't write to
// stdout at module init, but transitive deps (pino, pino-pretty, the
// worker-thread transport) could in theory, and the import-closure
// regression test enforces the leaf invariant.
const [{ startMCPServer }, { LocalBackend }, { logger }] = await Promise.all([
import('../mcp/server.js'),
import('../mcp/local/local-backend.js'),
import('../core/logger.js'),
]);
// Missing-optional-grammar warnings are intentionally NOT emitted here.
@ -62,12 +68,15 @@ export const mcpCommand = async () => {
const repos = await backend.listRepos();
if (repos.length === 0) {
console.error(
// Operator-actionable but the server still starts and serves; warn-level,
// not error. Tools will discover newly-analyzed repos via lazy refresh.
logger.warn(
'GitNexus: No indexed repos yet. Run `gitnexus analyze` in a git repo — the server will pick it up automatically.',
);
} else {
console.error(
`GitNexus: MCP server starting with ${repos.length} repo(s): ${repos.map((r) => r.name).join(', ')}`,
logger.info(
{ repoCount: repos.length, repos: repos.map((r) => r.name) },
'GitNexus: MCP server starting',
);
}

19
gitnexus/src/cli/optional-grammars.ts
View file

@ -13,6 +13,7 @@
*/
import { createRequire } from 'module';
import { cliWarn } from './cli-message.js';
const _require = createRequire(import.meta.url);
@ -65,9 +66,14 @@ export function detectMissingOptionalGrammars(): MissingGrammar[] {
/could not find|no native build|prebuilds/i.test(msg);
if (!looksMissing) {
// Present but broken — surface so the user doesn't get a misleading
// "reinstall" recovery message that wouldn't actually help.
console.error(
// "reinstall" recovery message that wouldn't actually help. cliWarn
// writes plain text to stderr AND tees a structured logger.warn
// record; the merged repo-wide ESLint pino-migration rule forbids
// direct `console.error` in CLI code (only `console.log` is allowed
// there for tool-data stdout output).
cliWarn(
`GitNexus: optional grammar "${g.name}" is installed but failed to load (${msg.slice(0, 200)}). ${g.extensions.join('/')} files will not be parsed.`,
{ grammar: g.name, extensions: g.extensions, error: msg },
);
}
missing.push({ name: g.name, extensions: g.extensions });
@ -92,12 +98,17 @@ export function warnMissingOptionalGrammars(opts?: {
const missing = detectMissingOptionalGrammars();
if (missing.length === 0) return;
const ctx = opts?.context ? ` [${opts.context}]` : '';
// Hoist the optional set into a local so the closure below can narrow
// its type; references to `opts?.relevantExtensions` inside `.some()`
// lose the outer null-check narrowing and require a non-null assertion.
const relevantExtensions = opts?.relevantExtensions;
for (const g of missing) {
if (opts?.relevantExtensions && !g.extensions.some((e) => opts.relevantExtensions!.has(e))) {
if (relevantExtensions && !g.extensions.some((e) => relevantExtensions.has(e))) {
continue;
}
console.error(
cliWarn(
`GitNexus${ctx}: optional grammar "${g.name}" is unavailable — ${g.extensions.join('/')} files will not be parsed. Reinstall without GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 (and ensure python3, make, g++) to enable.`,
{ grammar: g.name, extensions: g.extensions, context: opts?.context },
);
}
}

11
gitnexus/src/cli/remove.ts
View file

@ -27,6 +27,8 @@
*/
import fs from 'fs/promises';
import { logger } from '../core/logger.js';
import { cliError } from './cli-message.js';
import {
readRegistry,
resolveRegistryEntry,
@ -51,14 +53,14 @@ export const removeCommand = async (target: string, options?: { force?: boolean
// Idempotent: missing target is a no-op warning, not an error.
// The `availableNames` hint comes from the error itself so users
// can see what they might have meant.
console.warn(`Nothing to remove: ${err.message}`);
logger.warn(`Nothing to remove: ${err.message}`);
return;
}
if (err instanceof RegistryAmbiguousTargetError) {
// Duplicate aliases are allowed via --allow-duplicate-name (#829);
// refuse to guess which one the user meant — surface the full list
// and exit non-zero so scripts don't silently pick the wrong repo.
console.error(`Error: ${err.message}`);
cliError(`Error: ${err.message}`);
process.exit(1);
}
throw err;
@ -86,7 +88,7 @@ export const removeCommand = async (target: string, options?: { force?: boolean
assertSafeStoragePath(entry);
} catch (err) {
if (err instanceof UnsafeStoragePathError) {
console.error(`Error: ${err.message}`);
cliError(`Error: ${err.message}`);
process.exit(1);
}
throw err;
@ -104,7 +106,8 @@ export const removeCommand = async (target: string, options?: { force?: boolean
console.log(` Path: ${entry.path}`);
console.log(` Storage: ${entry.storagePath}`);
} catch (err) {
console.error(`Failed to remove ${entry.name}:`, err);
const msg = err instanceof Error ? err.message : String(err);
cliError(`Failed to remove ${entry.name}: ${msg}`, { err });
process.exit(1);
}
};

46
gitnexus/src/cli/serve.ts
View file

@ -1,14 +1,26 @@
import { createServer } from '../server/api.js';
import { logger, flushLoggerSync } from '../core/logger.js';
import { cliError } from './cli-message.js';
// Catch anything that would cause a silent exit
// Catch anything that would cause a silent exit. Pino v10's default
// destination is `sync: false` (SonicBoom buffered) — call
// `flushLoggerSync()` between the log and `process.exit(1)` so the crash
// record is not lost to the unflushed buffer. Worker-thread transports
// (pino-pretty under TTY) handle their own flush on process exit in v10,
// so no separate `pino.final` integration is needed (the API was removed
// in v10 because the transport architecture made it unnecessary).
//
// We pass the Error itself in `{ err }` so pino's built-in err serializer
// captures `type`, `message`, and `stack` as structured fields.
process.on('uncaughtException', (err) => {
console.error('\n[gitnexus serve] Uncaught exception:', err.message);
if (process.env.DEBUG) console.error(err.stack);
logger.error({ err }, '[gitnexus serve] Uncaught exception');
flushLoggerSync();
process.exit(1);
});
process.on('unhandledRejection', (reason: any) => {
console.error('\n[gitnexus serve] Unhandled rejection:', reason?.message || reason);
if (process.env.DEBUG) console.error(reason?.stack);
process.on('unhandledRejection', (reason) => {
const err = reason instanceof Error ? reason : new Error(String(reason));
logger.error({ err }, '[gitnexus serve] Unhandled rejection');
flushLoggerSync();
process.exit(1);
});
@ -22,16 +34,26 @@ export const serveCommand = async (options?: { port?: string; host?: string }) =
try {
await createServer(port, host);
} catch (err: any) {
console.error(`\nFailed to start GitNexus server:\n`);
console.error(` ${err.message || err}\n`);
if (err.code === 'EADDRINUSE') {
console.error(` Port ${port} is already in use. Either:`);
console.error(` 1. Stop the other process using port ${port}`);
console.error(` 2. Use a different port: gitnexus serve --port 4748\n`);
cliError(
`\nFailed to start GitNexus server:\n` +
` ${err.message || err}\n\n` +
` Port ${port} is already in use. Either:\n` +
` 1. Stop the other process using port ${port}\n` +
` 2. Use a different port: gitnexus serve --port 4748\n`,
{ code: err.code, port, host },
);
} else {
cliError(`\nFailed to start GitNexus server:\n ${err.message || err}\n`, {
code: err.code,
port,
host,
});
}
if (err.stack && process.env.DEBUG) {
console.error(err.stack);
logger.debug({ stack: err.stack }, 'serve start error stack');
}
flushLoggerSync();
process.exit(1);
}
};

9
gitnexus/src/cli/setup.ts
View file

@ -365,7 +365,12 @@ async function installClaudeCodeHooks(result: SetupResult): Promise<void> {
}
const hookPath = path.join(destHooksDir, 'gitnexus-hook.cjs').replace(/\\/g, '/');
const hookCmd = `node "${hookPath.replace(/"/g, '\\"')}"`;
// Escape backslashes FIRST, then quotes (CodeQL js/incomplete-sanitization).
// The previous shape `replace(/"/g, '\\"')` alone would let `path\with"quote`
// become `path\with\"quote`, where the trailing `\` before `"` could
// unescape the quote inside the surrounding double-quoted shell context.
const escapedHookPath = hookPath.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
const hookCmd = `node "${escapedHookPath}"`;
// Check which hook events need entries (idempotent: skip if already registered)
const parsed = await (async () => {
@ -622,7 +627,7 @@ async function installOpenCodeSkills(result: SetupResult): Promise<void> {
const installed = await installSkillsTo(skillsDir);
if (installed.length > 0) {
result.configured.push(
`OpenCode skills (${installed.length} skills → ~/.config/opencode/skill/)`,
`OpenCode skills (${installed.length} skills → ~/.config/opencode/skills/)`,
);
}
} catch (err: any) {

11
gitnexus/src/cli/tool.ts
View file

@ -17,6 +17,7 @@
import { writeSync } from 'node:fs';
import { LocalBackend } from '../mcp/local/local-backend.js';
import { cliError } from './cli-message.js';
let _backend: LocalBackend | null = null;
@ -25,7 +26,7 @@ async function getBackend(): Promise<LocalBackend> {
_backend = new LocalBackend();
const ok = await _backend.init();
if (!ok) {
console.error('GitNexus: No indexed repositories found. Run: gitnexus analyze');
cliError('GitNexus: No indexed repositories found. Run: gitnexus analyze');
process.exit(1);
}
return _backend;
@ -67,7 +68,7 @@ export async function queryCommand(
},
): Promise<void> {
if (!queryText?.trim()) {
console.error('Usage: gitnexus query <search_query>');
cliError('Usage: gitnexus query <search_query>');
process.exit(1);
}
@ -93,7 +94,7 @@ export async function contextCommand(
},
): Promise<void> {
if (!name?.trim() && !options?.uid) {
console.error('Usage: gitnexus context <symbol_name> [--uid <uid>] [--file <path>]');
cliError('Usage: gitnexus context <symbol_name> [--uid <uid>] [--file <path>]');
process.exit(1);
}
@ -118,7 +119,7 @@ export async function impactCommand(
},
): Promise<void> {
if (!target?.trim()) {
console.error('Usage: gitnexus impact <symbol_name> [--direction upstream|downstream]');
cliError('Usage: gitnexus impact <symbol_name> [--direction upstream|downstream]');
process.exit(1);
}
@ -153,7 +154,7 @@ export async function cypherCommand(
},
): Promise<void> {
if (!query?.trim()) {
console.error('Usage: gitnexus cypher <cypher_query>');
cliError('Usage: gitnexus cypher <cypher_query>');
process.exit(1);
}

48
gitnexus/src/cli/wiki.ts
View file

@ -19,6 +19,7 @@ import {
import { WikiGenerator, type WikiOptions } from '../core/wiki/generator.js';
import { resolveLLMConfig, type LLMProvider } from '../core/wiki/llm-client.js';
import { detectCursorCLI } from '../core/wiki/cursor-client.js';
import { logger } from '../core/logger.js';
export interface WikiCommandOptions {
force?: boolean;
@ -583,7 +584,7 @@ export const wikiCommand = async (inputPath?: string, options?: WikiCommandOptio
} else {
console.log(`\n Error: ${err.message}\n`);
if (process.env.GITNEXUS_VERBOSE) {
console.error(err);
logger.error({ err }, 'wiki command failed');
}
}
process.exitCode = 1;
@ -601,6 +602,38 @@ function hasGhCLI(): boolean {
}
}
/**
* Strict Gist URL predicate. Rejects:
* - any URL that does not parse (URL constructor throws)
* - schemes other than https (drops `http:`, `file:`, `gist:`-style spoofs)
* - hostnames that are not exactly `gist.github.com` (drops substring spoofs
* like `https://evil.com/?u=gist.github.com` and userinfo-prefixed shapes
* like `https://[email protected]/...` — note that URL.hostname
* strips userinfo, so the equality check rejects the userinfo-prefixed
* spoof if the actual host differs from gist.github.com)
* - any URL containing userinfo (`username[:password]@`), which the URL
* parser exposes via `.username` / `.password`. Defense-in-depth: even
* when hostname matches, a credential-bearing URL is suspect and not
* produced by `gh gist create`.
*
* Closes the substring-bypass class CodeQL `js/incomplete-url-substring-
* sanitization` flags.
*/
function isGistUrl(line: string): boolean {
const trimmed = line.trim();
try {
const u = new URL(trimmed);
return (
u.protocol === 'https:' &&
u.hostname === 'gist.github.com' &&
u.username === '' &&
u.password === ''
);
} catch {
return false;
}
}
function publishGist(htmlPath: string): { url: string; rawUrl: string } | null {
try {
const output = execFileSync(
@ -609,13 +642,14 @@ function publishGist(htmlPath: string): { url: string; rawUrl: string } | null {
{ encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] },
).trim();
// gh gist create prints the gist URL as the last line
const lines = output.split('\n');
const gistUrl = lines.find((l) => l.includes('gist.github.com')) || lines[lines.length - 1];
// `gh gist create` prints the gist URL as a line in the output. Find the
// first parseable Gist URL — if no line is a valid Gist URL, fail closed
// (do NOT fall back to lines[last]: a non-Gist last line would propagate
// through the regex below and produce a malformed `rawUrl`).
const gistUrl = output.split('\n').find(isGistUrl);
if (!gistUrl) return null;
if (!gistUrl || !gistUrl.includes('gist.github.com')) return null;
// Build a raw viewer URL via gist.githack.com
// Build a raw viewer URL via gist.githack.com.
// gist URL format: https://gist.github.com/{user}/{id}
const match = gistUrl.match(/gist\.github\.com\/([^/]+)\/([a-f0-9]+)/);
let rawUrl = gistUrl;

3
gitnexus/src/config/ignore-service.ts
View file

@ -2,6 +2,7 @@ import ignore, { type Ignore } from 'ignore';
import fs from 'fs/promises';
import nodePath from 'path';
import type { Path } from 'path-scurry';
import { logger } from '../core/logger.js';
const DEFAULT_IGNORE_LIST = new Set([
// Version Control
@ -365,7 +366,7 @@ export const loadIgnoreRules = async (
} catch (err: unknown) {
const code = (err as NodeJS.ErrnoException).code;
if (code !== 'ENOENT') {
console.warn(` Warning: could not read ${filename}: ${(err as Error).message}`);
logger.warn(` Warning: could not read ${filename}: ${(err as Error).message}`);
}
}
}

89
gitnexus/src/core/embeddings/embedder.ts
View file

@ -14,7 +14,12 @@ if (!process.env.ORT_LOG_LEVEL) {
process.env.ORT_LOG_LEVEL = '3';
}
import { pipeline, env, type FeatureExtractionPipeline } from '@huggingface/transformers';
import {
pipeline,
env,
type FeatureExtractionPipeline,
type ProgressInfo,
} from '@huggingface/transformers';
import { existsSync } from 'fs';
import { execFileSync } from 'child_process';
import { join, dirname } from 'path';
@ -22,7 +27,8 @@ import { createRequire } from 'module';
import { DEFAULT_EMBEDDING_CONFIG, type EmbeddingConfig, type ModelProgress } from './types.js';
import { isHttpMode, getHttpDimensions, httpEmbed } from './http-client.js';
import { resolveEmbeddingConfig } from './config.js';
import { applyHfEnvOverrides } from './hf-env.js';
import { applyHfEnvOverrides, isHfDownloadFailure, withHfDownloadRetry } from './hf-env.js';
import { logger } from '../logger.js';
/**
* Check whether the onnxruntime-node package that @huggingface/transformers
@ -166,17 +172,22 @@ export const initEmbedder = async (
const isDev = process.env.NODE_ENV === 'development';
if (isDev) {
console.error(`🧠 Loading embedding model: ${finalConfig.modelId}`);
logger.info(`🧠 Loading embedding model: ${finalConfig.modelId}`);
}
const progressCallback = onProgress
? (data: any) => {
? (data: ProgressInfo) => {
const progress: ModelProgress = {
status: data.status || 'progress',
file: data.file,
progress: data.progress,
loaded: data.loaded,
total: data.total,
// Map the `progress_total` aggregate event (not in ModelProgress.status)
// back to 'progress' so callers don't need to handle it separately.
status:
data.status === 'progress_total'
? 'progress'
: ((data.status as ModelProgress['status']) ?? 'progress'),
file: 'file' in data ? data.file : undefined,
progress: 'progress' in data ? data.progress : undefined,
loaded: 'loaded' in data ? data.loaded : undefined,
total: 'total' in data ? data.total : undefined,
};
onProgress(progress);
}
@ -192,26 +203,38 @@ export const initEmbedder = async (
for (const device of devicesToTry) {
try {
if (isDev && device === 'dml') {
console.error('🔧 Trying DirectML (DirectX12) GPU backend...');
logger.info('🔧 Trying DirectML (DirectX12) GPU backend...');
} else if (isDev && device === 'cuda') {
console.error('🔧 Trying CUDA GPU backend...');
logger.info('🔧 Trying CUDA GPU backend...');
} else if (isDev && device === 'cpu') {
console.error('🔧 Using CPU backend...');
logger.info('🔧 Using CPU backend...');
} else if (isDev && device === 'wasm') {
console.error('🔧 Using WASM backend (slower)...');
logger.info('🔧 Using WASM backend (slower)...');
}
embedderInstance = await (pipeline as any)('feature-extraction', finalConfig.modelId, {
device: device,
dtype: 'fp32',
progress_callback: progressCallback,
session_options: {
logSeverityLevel: 3,
intraOpNumThreads: finalConfig.threads,
interOpNumThreads: 1,
executionMode: 'sequential',
embedderInstance = await withHfDownloadRetry(
() =>
pipeline('feature-extraction', finalConfig.modelId, {
device: device,
dtype: 'fp32',
progress_callback: progressCallback,
session_options: {
logSeverityLevel: 3,
intraOpNumThreads: finalConfig.threads,
interOpNumThreads: 1,
executionMode: 'sequential',
},
}),
{
onRetry: isDev
? (attempt, max, err) =>
logger.warn(
{ attempt, max, err: err.message },
`⚠️ Model download network error (attempt ${attempt}/${max}), retrying…`,
)
: undefined,
},
});
);
currentDevice = device;
if (isDev) {
@ -221,15 +244,29 @@ export const initEmbedder = async (
: device === 'cuda'
? 'GPU (CUDA)'
: device.toUpperCase();
console.error(`✅ Using ${label} backend`);
console.error('✅ Embedding model loaded successfully');
logger.info(`✅ Using ${label} backend`);
logger.info('✅ Embedding model loaded successfully');
}
return embedderInstance!;
} catch (deviceError) {
// Network errors and circuit-open errors are not device-specific —
// they will fail the same way on every device. Rethrow immediately
// with actionable HF_ENDPOINT guidance rather than silently falling
// back to the next device.
const errMsg = deviceError instanceof Error ? deviceError.message : String(deviceError);
if (isHfDownloadFailure(errMsg)) {
const endpointHint = process.env.HF_ENDPOINT
? `The configured endpoint (${process.env.HF_ENDPOINT}) may be unreachable.`
: `huggingface.co may be unreachable from your network.\n` +
` Set HF_ENDPOINT to a mirror and retry:\n` +
` HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings\n` +
` (Windows: set HF_ENDPOINT=https://hf-mirror.com && npx gitnexus analyze --embeddings)`;
throw new Error(`Failed to download embedding model: ${errMsg}\n ${endpointHint}`);
}
if (isDev && (device === 'cuda' || device === 'dml')) {
const gpuType = device === 'dml' ? 'DirectML' : 'CUDA';
console.error(`⚠️ ${gpuType} not available, falling back to CPU...`);
logger.info(`⚠️ ${gpuType} not available, falling back to CPU...`);
}
// Continue to next device in list
if (device === devicesToTry[devicesToTry.length - 1]) {

31
gitnexus/src/core/embeddings/embedding-pipeline.ts
View file

@ -44,6 +44,7 @@ import {
} from '../lbug/schema.js';
import { loadVectorExtension } from '../lbug/lbug-adapter.js';
import { getExactScanLimit } from '../platform/capabilities.js';
import { logger } from '../logger.js';
const isDev = process.env.NODE_ENV === 'development';
@ -157,7 +158,7 @@ const queryEmbeddableNodes = async (
}
} catch (error) {
if (isDev) {
console.error(`Query for ${label} nodes failed:`, error);
logger.warn({ error }, `Query for ${label} nodes failed:`);
}
}
}
@ -212,7 +213,7 @@ const createVectorIndex = async (
return true;
} catch (error) {
if (isDev) {
console.error('Vector index creation warning:', error);
logger.warn({ error }, 'Vector index creation warning:');
}
return false;
}
@ -256,7 +257,9 @@ export const runEmbeddingPipeline = async (
try {
const vectorAvailable = await ensureVectorExtensionAvailable();
if (!vectorAvailable && isDev) console.error(vectorUnavailableMessage);
if (!vectorAvailable && isDev) {
logger.warn(vectorUnavailableMessage);
}
// Phase 1: Load embedding model
onProgress({
@ -283,7 +286,7 @@ export const runEmbeddingPipeline = async (
});
if (isDev) {
console.error('🔍 Querying embeddable nodes...');
logger.info('🔍 Querying embeddable nodes...');
}
// Phase 2: Query embeddable nodes
@ -325,7 +328,7 @@ export const runEmbeddingPipeline = async (
// (Kuzu forbids SET on vector-indexed properties; DELETE-then-INSERT is the sanctioned pattern)
if (staleNodeIds.length > 0) {
if (isDev) {
console.error(`🔄 Deleting ${staleNodeIds.length} stale embedding rows for re-embed`);
logger.info(`🔄 Deleting ${staleNodeIds.length} stale embedding rows for re-embed`);
}
try {
await executeWithReusedStatement(
@ -346,7 +349,7 @@ export const runEmbeddingPipeline = async (
}
if (isDev) {
console.error(
logger.info(
`📦 Incremental embeddings: ${beforeCount} total, ${existingEmbeddings.size} cached, ${staleNodeIds.length} stale, ${nodes.length} to embed`,
);
}
@ -355,7 +358,7 @@ export const runEmbeddingPipeline = async (
const totalNodes = nodes.length;
if (isDev) {
console.error(`📊 Found ${totalNodes} embeddable nodes`);
logger.info(`📊 Found ${totalNodes} embeddable nodes`);
}
if (totalNodes === 0) {
@ -442,9 +445,9 @@ export const runEmbeddingPipeline = async (
);
} catch (chunkErr) {
if (isDev) {
console.error(
logger.warn(
{ chunkErr },
`⚠️ AST chunking failed for ${node.label} "${node.name}" (${node.filePath}), falling back to character-based chunking:`,
chunkErr,
);
}
chunks = characterChunk(node.content, startLine, endLine, chunkSize, overlap);
@ -482,9 +485,9 @@ export const runEmbeddingPipeline = async (
try {
embeddings = await embedBatch(subTexts);
} catch (embedErr) {
console.error(
logger.error(
{ embedErr },
`❌ embedBatch failed for ${subTexts.length} texts (first: "${subTexts[0]?.substring(0, 80)}..."):`,
embedErr,
);
throw embedErr;
}
@ -520,7 +523,7 @@ export const runEmbeddingPipeline = async (
});
if (isDev) {
console.error('📇 Creating vector index...');
logger.info('📇 Creating vector index...');
}
const vectorIndexReady = await createVectorIndex(executeQuery);
@ -533,7 +536,7 @@ export const runEmbeddingPipeline = async (
});
if (isDev) {
console.error(
logger.info(
`✅ Embedding pipeline complete! (${totalChunks} chunks from ${totalNodes} nodes)`,
);
}
@ -547,7 +550,7 @@ export const runEmbeddingPipeline = async (
const errorMessage = error instanceof Error ? error.message : 'Unknown error';
if (isDev) {
console.error('❌ Embedding pipeline error:', error);
logger.error({ error }, '❌ Embedding pipeline error:');
}
onProgress({

281
gitnexus/src/core/embeddings/hf-env.ts
View file

@ -1,6 +1,25 @@
import os from 'node:os';
import { join } from 'node:path';
// ---------------------------------------------------------------------------
// Download resilience defaults
// ---------------------------------------------------------------------------
/** Per-attempt timeout for the full model download (5 minutes). */
export const HF_DOWNLOAD_TIMEOUT_MS = 5 * 60 * 1_000;
/** Maximum total download attempts (1 initial + N-1 retries). */
export const HF_MAX_ATTEMPTS = 3;
/** Initial delay between retry attempts; doubles on each subsequent retry. */
export const HF_BASE_DELAY_MS = 2_000;
/** Number of consecutive failures required to open the circuit. */
export const CB_FAILURE_THRESHOLD = 3;
/** How long the circuit stays open before transitioning to half-open. */
export const CB_RESET_TIMEOUT_MS = 60_000;
/** Upper bound clamped on the env-override per-attempt timeout (30 minutes). */
export const HF_MAX_TIMEOUT_MS = 30 * 60 * 1_000;
/** Upper bound clamped on the env-override attempt count. */
export const HF_MAX_ATTEMPTS_CAP = 10;
/**
* @internal Exported only for unit tests and the two embedder entry points
* (`core/embeddings/embedder.ts` + `mcp/core/embedder.ts`). Not part of the
@ -60,3 +79,265 @@ export function applyHfEnvOverrides(env: HfEnvSubset): void {
env.remoteHost = endpoint.endsWith('/') ? endpoint : endpoint + '/';
}
}
/**
* @internal Exported for unit tests and the two embedder entry points.
*
* Returns true when an error message indicates a network-level fetch failure
* during HuggingFace model download (e.g. `TypeError: fetch failed`,
* `ECONNREFUSED`, `ENOTFOUND`, `ETIMEDOUT`, `ECONNRESET`).
*
* These errors are not device-specific and cannot be fixed by falling back to
* a different ONNX device — the caller should rethrow immediately with
* guidance about `HF_ENDPOINT`.
*/
export function isNetworkFetchError(message: string): boolean {
return (
message.includes('fetch failed') ||
message.includes('ECONNREFUSED') ||
message.includes('ENOTFOUND') ||
message.includes('ETIMEDOUT') ||
message.includes('ECONNRESET')
);
}
// ---------------------------------------------------------------------------
// Circuit breaker
// ---------------------------------------------------------------------------
/** @internal Used by `withHfDownloadRetry` to mark a circuit-open rejection. */
export const CIRCUIT_OPEN_TAG = 'hf-circuit-open';
/** Circuit-breaker states. */
type CircuitState = 'closed' | 'open' | 'half-open';
/**
* Circuit breaker for HuggingFace model downloads.
*
* After `failureThreshold` consecutive network failures the circuit opens and
* all subsequent calls to `withHfDownloadRetry` fail immediately without
* issuing any network requests. After `resetTimeoutMs` the circuit enters the
* half-open state and the next call is attempted — if it succeeds the circuit
* closes again; if it fails the circuit re-opens.
*
* Exported for unit-testing; production code should use the module-level
* `hfDownloadCircuit` singleton.
*/
export class HfDownloadCircuitBreaker {
private _state: CircuitState = 'closed';
private _failures = 0;
/** Timestamp of the last recorded failure (ms since epoch). */
lastFailureAt = 0;
constructor(
readonly failureThreshold: number = CB_FAILURE_THRESHOLD,
readonly resetTimeoutMs: number = CB_RESET_TIMEOUT_MS,
) {}
/** Effective state, factoring in the reset-timeout transition. */
get state(): CircuitState {
if (this._state === 'open' && Date.now() - this.lastFailureAt > this.resetTimeoutMs) {
this._state = 'half-open';
}
return this._state;
}
/** Returns true when the circuit is open and calls should be rejected. */
isOpen(): boolean {
return this.state === 'open';
}
/** Record a successful call — resets the failure counter and closes the circuit. */
recordSuccess(): void {
this._failures = 0;
this._state = 'closed';
}
/** Record a failed call — increments the counter and opens the circuit when the threshold is reached. */
recordFailure(): void {
this._failures++;
this.lastFailureAt = Date.now();
if (this._failures >= this.failureThreshold) {
this._state = 'open';
}
}
/** @internal Reset to initial state (used in tests). */
reset(): void {
this._failures = 0;
this._state = 'closed';
this.lastFailureAt = 0;
}
}
/** Module-level singleton shared by both embedder entry points. */
export const hfDownloadCircuit = new HfDownloadCircuitBreaker();
// ---------------------------------------------------------------------------
// Retry + timeout wrapper
// ---------------------------------------------------------------------------
/** @internal Returns true for errors that should abort without retry (circuit-open). */
export function isHfCircuitOpenError(message: string): boolean {
return message.includes(CIRCUIT_OPEN_TAG);
}
/**
* Returns true for any HuggingFace download failure that warrants showing the
* `HF_ENDPOINT` remediation hint: either a raw network error or a
* circuit-open rejection (which itself was caused by repeated network errors).
*/
export function isHfDownloadFailure(message: string): boolean {
return isNetworkFetchError(message) || isHfCircuitOpenError(message);
}
/** @internal Wraps `fn` in a hard time-limit. The timeout error contains
* `ETIMEDOUT` so that `isNetworkFetchError` classifies it correctly.
*/
export function withDownloadTimeout<T>(fn: () => Promise<T>, timeoutMs: number): Promise<T> {
return new Promise<T>((resolve, reject) => {
const timer = setTimeout(
() =>
reject(
new Error(
`ETIMEDOUT: model download timed out after ${Math.round(timeoutMs / 1000)}s — ` +
`check your network speed or set HF_ENDPOINT to a faster mirror`,
),
),
timeoutMs,
);
fn().then(
(v) => {
clearTimeout(timer);
resolve(v);
},
(e) => {
clearTimeout(timer);
reject(e);
},
);
});
}
/** @internal Async sleep (exposed for testing). */
export function sleep(ms: number): Promise<void> {
return new Promise((resolve) => setTimeout(resolve, ms));
}
export interface HfRetryOptions {
/** Maximum total attempts including the initial one (default: `HF_MAX_ATTEMPTS`). */
maxAttempts?: number;
/** Delay before the first retry; doubles on each subsequent attempt (default: `HF_BASE_DELAY_MS`). */
baseDelayMs?: number;
/** Per-attempt wall-clock timeout in ms (default: `HF_DOWNLOAD_TIMEOUT_MS`). */
timeoutMs?: number;
/**
* Circuit-breaker instance to use. Defaults to the module-level
* `hfDownloadCircuit` singleton. Pass a fresh instance in tests.
*/
circuit?: HfDownloadCircuitBreaker;
/**
* Optional callback invoked before each retry (not the initial attempt).
* @param attempt - 1-based retry number
* @param max - total allowed attempts
* @param error - the error that triggered the retry
*/
onRetry?: (attempt: number, max: number, error: Error) => void;
}
/**
* Retry wrapper for HuggingFace model downloads with per-attempt timeout and
* circuit-breaker protection.
*
* Behaviour:
* - If the circuit is **open**, fails immediately with a `CIRCUIT_OPEN_TAG`
* message (so `isHfDownloadFailure` still returns true and the caller can
* show `HF_ENDPOINT` guidance).
* - Each attempt is wrapped in `withDownloadTimeout`.
* - On a network-level error (`isNetworkFetchError`) the attempt is retried
* with exponential back-off; non-network errors (e.g. ONNX device failure)
* are rethrown immediately without retry.
* - Every network failure is recorded on the circuit breaker; a success resets
* it.
* - After all attempts are exhausted, the last network error is rethrown
* so the existing `isNetworkFetchError` / `isHfDownloadFailure` guards in
* the calling code still fire.
*/
export async function withHfDownloadRetry<T>(
fn: () => Promise<T>,
options: HfRetryOptions = {},
): Promise<T> {
// Resolve effective values — explicit options take precedence over env vars,
// which take precedence over built-in defaults. This lets users lower the
// per-attempt timeout without rebuilding (e.g.
// HF_DOWNLOAD_TIMEOUT_MS=60000 npx gitnexus analyze --embeddings
// reduces the worst-case wait from 15 minutes to ~3 minutes).
//
// Upper bounds are clamped to prevent accidental runaway configuration:
// - timeoutMs is capped at HF_MAX_TIMEOUT_MS (30 min)
// - maxAttempts is floored (fractional values → integer) and capped at
// HF_MAX_ATTEMPTS_CAP (10). Values ≤ 0, NaN, or Infinity fall back to
// the built-in defaults.
const envTimeout = Number(process.env.HF_DOWNLOAD_TIMEOUT_MS);
const envMaxAttempts = Number(process.env.HF_MAX_ATTEMPTS);
const resolvedTimeout =
Number.isFinite(envTimeout) && envTimeout > 0
? Math.min(envTimeout, HF_MAX_TIMEOUT_MS)
: HF_DOWNLOAD_TIMEOUT_MS;
const resolvedMaxAttempts =
Number.isFinite(envMaxAttempts) && envMaxAttempts > 0
? Math.min(Math.floor(envMaxAttempts), HF_MAX_ATTEMPTS_CAP)
: HF_MAX_ATTEMPTS;
const {
maxAttempts = resolvedMaxAttempts,
baseDelayMs = HF_BASE_DELAY_MS,
timeoutMs = resolvedTimeout,
circuit = hfDownloadCircuit,
onRetry,
} = options;
if (circuit.isOpen()) {
const secsUntilReset = Math.ceil(
(circuit.resetTimeoutMs - (Date.now() - circuit.lastFailureAt)) / 1000,
);
throw new Error(
`${CIRCUIT_OPEN_TAG}: HuggingFace download circuit is open after repeated network failures` +
(secsUntilReset > 0 ? ` — will reset in ~${secsUntilReset}s` : ''),
);
}
let lastError: Error = new Error('unknown error');
for (let attempt = 0; attempt < maxAttempts; attempt++) {
try {
const result = await withDownloadTimeout(fn, timeoutMs);
circuit.recordSuccess();
return result;
} catch (err) {
lastError = err instanceof Error ? err : new Error(String(err));
if (!isNetworkFetchError(lastError.message)) {
// Non-network error (e.g. CUDA unavailable) — propagate without retry
throw lastError;
}
circuit.recordFailure();
if (circuit.isOpen()) {
// Circuit just tripped — fail fast, no more retries
throw new Error(
`${CIRCUIT_OPEN_TAG}: HuggingFace download circuit opened after ${circuit.failureThreshold} consecutive failures`,
);
}
if (attempt < maxAttempts - 1) {
const delay = baseDelayMs * Math.pow(2, attempt);
onRetry?.(attempt + 1, maxAttempts, lastError);
await sleep(delay);
}
}
}
// All retries exhausted — throw the last network error so isNetworkFetchError
// patterns in the calling code still match and surface HF_ENDPOINT guidance.
throw lastError;
}

38
gitnexus/src/core/git-staleness.ts
View file

@ -3,11 +3,14 @@
* Lives in core/ so application code does not depend on the MCP package layer.
*/
import { execFileSync } from 'node:child_process';
import { execFile, execFileSync } from 'node:child_process';
import { promisify } from 'node:util';
import path from 'path';
import { readRegistry, type RegistryEntry, type CwdMatch } from '../storage/repo-manager.js';
import { findGitRootByDotGit, getCurrentCommit, getRemoteUrl } from '../storage/git.js';
const execFileAsync = promisify(execFile);
export interface StalenessInfo {
isStale: boolean;
commitsBehind: number;
@ -41,6 +44,39 @@ export function checkStaleness(repoPath: string, lastCommit: string): StalenessI
}
}
/**
* Async variant of {@link checkStaleness} — spawns git as a child process
* instead of blocking the event loop. Used by `listRepos()` to check many
* repos in parallel (issue #1363: 200 repos × sync spawn ≈ 50 s).
*/
export async function checkStalenessAsync(
repoPath: string,
lastCommit: string,
): Promise<StalenessInfo> {
try {
// Note: promisified execFile captures stdout/stderr by default (no stdio option needed,
// unlike the sync variant which requires explicit stdio: ['pipe','pipe','pipe']).
const { stdout } = await execFileAsync('git', ['rev-list', '--count', `${lastCommit}..HEAD`], {
cwd: repoPath,
encoding: 'utf-8',
});
const commitsBehind = parseInt(stdout.trim(), 10) || 0;
if (commitsBehind > 0) {
return {
isStale: true,
commitsBehind,
hint: `⚠️ Index is ${commitsBehind} commit${commitsBehind > 1 ? 's' : ''} behind HEAD. Run analyze tool to update.`,
};
}
return { isStale: false, commitsBehind: 0 };
} catch {
return { isStale: false, commitsBehind: 0 };
}
}
/**
* Compare a sibling-clone HEAD against an indexed `lastCommit`. Returns
* `undefined` when the indexed commit is not reachable from the sibling

433
gitnexus/src/core/group/bridge-db.ts
View file

@ -11,6 +11,9 @@ import {
type LbugConnectionHandle,
} from '../lbug/lbug-config.js';
import { dedupeContracts, dedupeCrossLinks } from './normalization.js';
import { createLogger } from '../logger.js';
const bridgeLogger = createLogger('bridge-db', { debugEnvVar: 'GITNEXUS_DEBUG_BRIDGE' });
/**
* Sidecar files that LadybugDB creates next to a `bridge.lbug` file.
@ -41,26 +44,6 @@ async function removeLbugFile(basePath: string): Promise<void> {
}
}
/**
* Remove all stale `bridge.lbug.tmp.*` files (and their sidecars) from a
* group directory. With randomBytes-based temp names, a crashed writeBridge
* leaves behind a uniquely-named tmp file that no future run will target by
* name — so we glob for the prefix and clean up everything matching.
*/
async function cleanStaleBridgeTmpFiles(groupDir: string): Promise<void> {
try {
const entries = await fsp.readdir(groupDir);
const staleBases = entries.filter(
(e) => e.startsWith('bridge.lbug.tmp.') && !LBUG_SIDECAR_SUFFIXES.some((s) => e.endsWith(s)),
);
for (const name of staleBases) {
await removeLbugFile(path.join(groupDir, name));
}
} catch {
/* best-effort: directory may not exist yet */
}
}
export function contractNodeId(
repo: string,
contractId: string,
@ -296,8 +279,24 @@ export async function retryRename(src: string, dst: string, attempts = 3): Promi
export async function writeBridgeMeta(groupDir: string, meta: BridgeMeta): Promise<void> {
const target = path.join(groupDir, 'meta.json');
// Unpredictable suffix + O_EXCL via `'wx'` flag closes the symlink/
// pre-create attack window. The third argument `0o600` is the
// user-only mode mask — CodeQL's `js/insecure-temporary-file` query
// sources its verdict from the `mode` argument, NOT from `flags`:
// its `isSecureMode(mode)` predicate requires the low 6 bits to be
// zero (no group/world bits). Without an explicit mode the file is
// created with the process umask (typically 0o644 = group/world
// readable), which the query treats as the actual vulnerability.
// Both `'wx'` (runtime O_EXCL) AND `0o600` (CodeQL-credited mode)
// are needed: one closes the symlink race, the other closes the
// permissions exposure.
const tmp = `${target}.tmp.${randomBytes(8).toString('hex')}`;
await fsp.writeFile(tmp, JSON.stringify(meta, null, 2), 'utf-8');
const handle = await fsp.open(tmp, 'wx', 0o600);
try {
await handle.writeFile(JSON.stringify(meta, null, 2), 'utf-8');
} finally {
await handle.close();
}
// Use retryRename for consistency with writeBridge's atomic swap — on
// Windows a concurrent reader can cause EBUSY/EPERM even on a tiny
// meta.json, and we don't want meta write to be less robust than the
@ -366,7 +365,19 @@ export async function writeBridge(
const crossLinks = dedupeCrossLinks(input.crossLinks);
const finalPath = path.join(groupDir, 'bridge.lbug');
const tmpPath = path.join(groupDir, `bridge.lbug.tmp.${randomBytes(8).toString('hex')}`);
// Stage the temp database inside a unique mkdtemp directory rather than
// a fixed `bridge.lbug.tmp` name. The previous shape was flagged by
// CodeQL js/insecure-temporary-file as a predictable path: a co-located
// attacker (or a parallel writeBridge call into the same group) could
// pre-create or symlink that path before this writer opens it. mkdtemp
// returns a directory whose suffix is filled with cryptographically
// random bytes, so the staging path is unguessable AND collision-free
// across parallel callers. We anchor the staging directory inside
// `groupDir` so the subsequent rename of `bridge.lbug` (and its
// `.wal` / `.shadow` sidecars) into place stays on the same filesystem
// and remains atomic — moving across `os.tmpdir()` could trip EXDEV.
const stagingDir = await fsp.mkdtemp(path.join(groupDir, 'bridge-tmp-'));
const tmpPath = path.join(stagingDir, 'bridge.lbug');
const bakPath = path.join(groupDir, 'bridge.lbug.bak');
const report: WriteBridgeReport = {
@ -386,43 +397,42 @@ export async function writeBridge(
}
};
// Clean up stale tmp files left behind by previously crashed writeBridge
// runs. With randomBytes-based names each run picks a unique path, so
// the old fixed-name `removeLbugFile(tmpPath)` was a no-op — stale
// artifacts accumulated. The glob-based helper finds *all* leftover
// `bridge.lbug.tmp.*` entries and removes them (including sidecars).
await cleanStaleBridgeTmpFiles(groupDir);
// The mkdtemp staging directory above is freshly created with a unique
// random suffix, so there are no leftover `bridge.lbug.tmp` / `.wal` /
// `.shadow` sidecars from a previous crashed run to clean up here — the
// directory is empty by construction.
// 1. Create temp DB, insert all data.
//
// Everything after `openBridgeDb` must run inside a try/finally so that
// if ANY step before the explicit `closeBridgeDb` throws — schema
// creation, a contract insert loop that rethrows, a snapshot write, the
// cross-link loop, or anything else — the handle is still released. A
// leaked handle holds the native LadybugDB file lock on tmpPath, which
// (a) leaks a FD and (b) prevents the next writeBridge call from
// reusing the same tmp slot.
const handle = await openBridgeDb(tmpPath);
let handleClosed = false;
try {
await ensureBridgeSchema(handle);
// 1. Create temp DB, insert all data.
//
// Everything after `openBridgeDb` must run inside a try/finally so that
// if ANY step before the explicit `closeBridgeDb` throws — schema
// creation, a contract insert loop that rethrows, a snapshot write, the
// cross-link loop, or anything else — the handle is still released. A
// leaked handle holds the native LadybugDB file lock on tmpPath, which
// (a) leaks a FD and (b) prevents the next writeBridge call from
// reusing the same tmp slot.
const handle = await openBridgeDb(tmpPath);
let handleClosed = false;
try {
await ensureBridgeSchema(handle);
// Build the lookup index incrementally as contracts are inserted, so
// failed inserts are never in the index (and therefore never resolved
// by the cross-link loop below). This replaces a previous N+1 query
// pattern where each link made up to 6 DB round-trips to find its
// endpoints — see ContractLookupIndex.
const lookupIndex = createContractLookupIndex();
// Build the lookup index incrementally as contracts are inserted, so
// failed inserts are never in the index (and therefore never resolved
// by the cross-link loop below). This replaces a previous N+1 query
// pattern where each link made up to 6 DB round-trips to find its
// endpoints — see ContractLookupIndex.
const lookupIndex = createContractLookupIndex();
// Insert contracts — tolerate individual failures (e.g., a corrupt meta
// that can't be serialized). The whole sync must not fail because one
// contract is broken.
for (const c of contracts) {
const id = contractNodeId(c.repo, c.contractId, c.role, c.symbolRef.filePath);
try {
await queryBridge(
handle,
`CREATE (n:Contract {
// Insert contracts — tolerate individual failures (e.g., a corrupt meta
// that can't be serialized). The whole sync must not fail because one
// contract is broken.
for (const c of contracts) {
const id = contractNodeId(c.repo, c.contractId, c.role, c.symbolRef.filePath);
try {
await queryBridge(
handle,
`CREATE (n:Contract {
id: $id,
contractId: $contractId,
type: $type,
@ -435,91 +445,91 @@ export async function writeBridge(
confidence: $confidence,
meta: $meta
})`,
{
id,
contractId: c.contractId,
type: c.type,
role: c.role,
repo: c.repo,
service: c.service ?? '',
symbolUid: c.symbolUid,
filePath: c.symbolRef.filePath,
symbolName: c.symbolName,
confidence: c.confidence,
meta: JSON.stringify(c.meta),
},
);
report.contractsInserted++;
// Only index on successful insert — the cross-link loop must never
// resolve to a row that isn't actually in the DB.
indexContract(lookupIndex, c, id);
} catch (err) {
report.contractsFailed++;
recordError('contract', id, err);
{
id,
contractId: c.contractId,
type: c.type,
role: c.role,
repo: c.repo,
service: c.service ?? '',
symbolUid: c.symbolUid,
filePath: c.symbolRef.filePath,
symbolName: c.symbolName,
confidence: c.confidence,
meta: JSON.stringify(c.meta),
},
);
report.contractsInserted++;
// Only index on successful insert — the cross-link loop must never
// resolve to a row that isn't actually in the DB.
indexContract(lookupIndex, c, id);
} catch (err) {
report.contractsFailed++;
recordError('contract', id, err);
}
}
}
// Insert repo snapshots
for (const [repoId, snap] of Object.entries(input.repoSnapshots)) {
try {
await queryBridge(
handle,
`CREATE (s:RepoSnapshot {
// Insert repo snapshots
for (const [repoId, snap] of Object.entries(input.repoSnapshots)) {
try {
await queryBridge(
handle,
`CREATE (s:RepoSnapshot {
id: $id,
indexedAt: $indexedAt,
lastCommit: $lastCommit
})`,
{
id: repoId,
indexedAt: snap.indexedAt,
lastCommit: snap.lastCommit,
},
);
report.snapshotsInserted++;
} catch (err) {
report.snapshotsFailed++;
recordError('snapshot', repoId, err);
}
}
// Insert cross-links (tolerating missing nodes).
//
// `findContractNode` consults the in-memory lookup index built above,
// not the DB — that's an O(1) pure-function lookup per endpoint instead
// of the previous 2-3 DB queries. For M cross-links, the previous code
// issued up to 6M round-trips; this version issues zero.
//
// `link.contractId` may differ between the consumer and provider sides
// (e.g. wildcard consumer `grpc::Service/*` → method-level provider
// `grpc::Service/Method`) — that's why we resolve each endpoint
// independently via its own `(repo, role, symbolUid, filePath, symbolName)`
// tuple rather than matching on contractId.
for (const link of crossLinks) {
const linkId = `${link.from.repo}::${link.contractId}->${link.to.repo}::${link.contractId}`;
try {
const fromId = findContractNode(
lookupIndex,
link.from.repo,
'consumer',
link.from.symbolUid,
link.from.symbolRef.filePath,
link.from.symbolRef.name,
);
const toId = findContractNode(
lookupIndex,
link.to.repo,
'provider',
link.to.symbolUid,
link.to.symbolRef.filePath,
link.to.symbolRef.name,
);
if (!fromId || !toId) {
report.linksDroppedMissingNode++;
continue;
{
id: repoId,
indexedAt: snap.indexedAt,
lastCommit: snap.lastCommit,
},
);
report.snapshotsInserted++;
} catch (err) {
report.snapshotsFailed++;
recordError('snapshot', repoId, err);
}
await queryBridge(
handle,
`
}
// Insert cross-links (tolerating missing nodes).
//
// `findContractNode` consults the in-memory lookup index built above,
// not the DB — that's an O(1) pure-function lookup per endpoint instead
// of the previous 2-3 DB queries. For M cross-links, the previous code
// issued up to 6M round-trips; this version issues zero.
//
// `link.contractId` may differ between the consumer and provider sides
// (e.g. wildcard consumer `grpc::Service/*` → method-level provider
// `grpc::Service/Method`) — that's why we resolve each endpoint
// independently via its own `(repo, role, symbolUid, filePath, symbolName)`
// tuple rather than matching on contractId.
for (const link of crossLinks) {
const linkId = `${link.from.repo}::${link.contractId}->${link.to.repo}::${link.contractId}`;
try {
const fromId = findContractNode(
lookupIndex,
link.from.repo,
'consumer',
link.from.symbolUid,
link.from.symbolRef.filePath,
link.from.symbolRef.name,
);
const toId = findContractNode(
lookupIndex,
link.to.repo,
'provider',
link.to.symbolUid,
link.to.symbolRef.filePath,
link.to.symbolRef.name,
);
if (!fromId || !toId) {
report.linksDroppedMissingNode++;
continue;
}
await queryBridge(
handle,
`
MATCH (a:Contract), (b:Contract)
WHERE a.id = $fromId AND b.id = $toId
CREATE (a)-[:ContractLink {
@ -530,83 +540,93 @@ export async function writeBridge(
toRepo: $toRepo
}]->(b)
`,
{
fromId,
toId,
matchType: link.matchType,
confidence: link.confidence,
contractId: link.contractId,
fromRepo: link.from.repo,
toRepo: link.to.repo,
},
);
report.linksInserted++;
} catch (err) {
report.linksFailed++;
recordError('link', linkId, err);
{
fromId,
toId,
matchType: link.matchType,
confidence: link.confidence,
contractId: link.contractId,
fromRepo: link.from.repo,
toRepo: link.to.repo,
},
);
report.linksInserted++;
} catch (err) {
report.linksFailed++;
recordError('link', linkId, err);
}
}
// 2. Close temp DB (happy path). The finally block also calls
// closeBridgeDb if we threw above; `handleClosed` prevents a
// double-close on the native handle.
await closeBridgeDb(handle);
handleClosed = true;
} finally {
if (!handleClosed) {
await closeBridgeDb(handle).catch(() => {
/* ignore: cleanup path, best effort */
});
}
}
// 2. Close temp DB (happy path). The finally block also calls
// closeBridgeDb if we threw above; `handleClosed` prevents a
// double-close on the native handle.
await closeBridgeDb(handle);
handleClosed = true;
} finally {
if (!handleClosed) {
await closeBridgeDb(handle).catch(() => {
/* ignore: cleanup path, best effort */
});
// 3. Atomic swap: old→.bak, tmp→final, rm .bak
//
// The current database file (with its `.wal` / `.shadow` sidecars) is
// moved aside, then the freshly built tmp database takes its place.
// We move the sidecars together with the main file so the open below
// and any external readers see a consistent set; orphan sidecars from
// the tmp namespace are then removed because LadybugDB looks for them
// under the renamed-to base name and would reject mismatching IDs.
try {
await fsp.access(finalPath);
await retryRename(finalPath, bakPath);
for (const suffix of LBUG_SIDECAR_SUFFIXES) {
try {
await fsp.access(`${finalPath}${suffix}`);
await retryRename(`${finalPath}${suffix}`, `${bakPath}${suffix}`);
} catch {
/* sidecar absent — nothing to move */
}
}
} catch {
/* no existing db */
}
}
// 3. Atomic swap: old→.bak, tmp→final, rm .bak
//
// The current database file (with its `.wal` / `.shadow` sidecars) is
// moved aside, then the freshly built tmp database takes its place.
// We move the sidecars together with the main file so the open below
// and any external readers see a consistent set; orphan sidecars from
// the tmp namespace are then removed because LadybugDB looks for them
// under the renamed-to base name and would reject mismatching IDs.
try {
await fsp.access(finalPath);
await retryRename(finalPath, bakPath);
await retryRename(tmpPath, finalPath);
for (const suffix of LBUG_SIDECAR_SUFFIXES) {
// Rename — not delete — so the WAL (which may carry uncommitted-at-
// close-time pages on a graceful close, depending on
// `autoCheckpoint` / `checkpointThreshold`) and the `.shadow`
// checkpoint snapshot stay paired with the database file under its
// final name. LadybugDB 0.16.0's database-id check rejects an open
// when the sidecars belong to a different base name.
try {
await fsp.access(`${finalPath}${suffix}`);
await retryRename(`${finalPath}${suffix}`, `${bakPath}${suffix}`);
await fsp.access(`${tmpPath}${suffix}`);
await retryRename(`${tmpPath}${suffix}`, `${finalPath}${suffix}`);
} catch {
/* sidecar absent — nothing to move */
}
}
} catch {
/* no existing db */
}
await retryRename(tmpPath, finalPath);
for (const suffix of LBUG_SIDECAR_SUFFIXES) {
// Rename — not delete — so the WAL (which may carry uncommitted-at-
// close-time pages on a graceful close, depending on
// `autoCheckpoint` / `checkpointThreshold`) and the `.shadow`
// checkpoint snapshot stay paired with the database file under its
// final name. LadybugDB 0.16.0's database-id check rejects an open
// when the sidecars belong to a different base name.
try {
await fsp.access(`${tmpPath}${suffix}`);
await retryRename(`${tmpPath}${suffix}`, `${finalPath}${suffix}`);
} catch {
/* sidecar absent — nothing to move */
}
}
await removeLbugFile(bakPath);
await removeLbugFile(bakPath);
// 4. Write meta.json
await writeBridgeMeta(groupDir, {
version: BRIDGE_SCHEMA_VERSION,
generatedAt: new Date().toISOString(),
missingRepos: input.missingRepos,
});
// 4. Write meta.json
await writeBridgeMeta(groupDir, {
version: BRIDGE_SCHEMA_VERSION,
generatedAt: new Date().toISOString(),
missingRepos: input.missingRepos,
});
return report;
return report;
} finally {
// Always remove the mkdtemp staging directory. On the happy path the
// main file and sidecars have been renamed out of it, so it's empty;
// on any error path it may still contain a partial database — either
// way `recursive: true, force: true` removes it without surfacing
// "directory not empty" or ENOENT.
await fsp.rm(stagingDir, { recursive: true, force: true }).catch(() => {
/* best-effort cleanup */
});
}
}
/* ------------------------------------------------------------------ */
@ -702,14 +722,15 @@ export async function openBridgeDbReadOnly(groupDir: string): Promise<BridgeHand
await new Promise((r) => setTimeout(r, delay));
}
}
if (process.env.GITNEXUS_DEBUG_BRIDGE) {
console.warn(
`[bridge-db] openBridgeDbReadOnly(${groupDir}) gave up after ` +
`${LBUG_OPEN_RETRY_ATTEMPTS} attempts: ${
lastErr instanceof Error ? lastErr.message : String(lastErr)
}`,
);
}
// Pino's NDJSON serialization is structurally injection-resistant
// (CodeQL js/log-injection): groupDir and err.message are JSON-escaped
// by the serializer, so no manual CRLF / U+2028 / ANSI sanitization is
// needed. Demoted to debug — only fires when the bridge truly gave up
// after retries, and operators only need it at debug verbosity.
bridgeLogger.debug(
{ groupDir, err: lastErr, attempts: LBUG_OPEN_RETRY_ATTEMPTS },
'openBridgeDbReadOnly gave up',
);
return null;
}

120
gitnexus/src/core/group/cross-impact.ts
View file

@ -91,6 +91,25 @@ function clampCrossDepth(raw: unknown): { depth: number; warning?: string } {
return { depth: d };
}
/**
* Clamp the impact timeout to a sane bounded range. Callers can feed this
* via tool params, so an unclamped value lets a single request hold a
* timer slot for an arbitrarily long duration (CodeQL js/resource-
* exhaustion). 100ms lower bound preserves test-suite scenarios that
* exercise tight timeouts; 5min upper bound is well above any legitimate
* single-impact compute. Applied at the validate boundary so the
* downstream `deadline` (Date.now() + timeoutMs) and the local-leg
* `setTimeout` see the same clamped value — earlier shapes had a 1hr
* outer cap and a 5min inner clamp that disagreed.
*/
export const IMPACT_TIMEOUT_MIN_MS = 100;
export const IMPACT_TIMEOUT_MAX_MS = 5 * 60 * 1_000;
export function clampTimeout(timeoutMs: number): number {
if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return IMPACT_TIMEOUT_MIN_MS;
return Math.min(IMPACT_TIMEOUT_MAX_MS, Math.max(IMPACT_TIMEOUT_MIN_MS, Math.trunc(timeoutMs)));
}
export function validateGroupImpactParams(params: Record<string, unknown>):
| {
ok: true;
@ -143,13 +162,19 @@ export function validateGroupImpactParams(params: Record<string, unknown>):
const service = normalizeServicePrefix(params.service);
const subgroup = typeof params.subgroup === 'string' ? params.subgroup : undefined;
let timeoutMs =
// Clamp at the validate boundary so the downstream `deadline` (line
// ~366) and `safeLocalImpact`'s `setTimeout` both see a single
// bounded value. Without this, the outer deadline budgeted Phase-2
// cross-repo fanout up to 1hr while only the inner setTimeout was
// capped to 5min — the two halves of CodeQL #184's mitigation
// disagreed.
const rawTimeoutMs =
typeof params.timeoutMs === 'number' && params.timeoutMs > 0
? params.timeoutMs
: typeof params.timeout === 'number' && params.timeout > 0
? params.timeout
: DEFAULT_LOCAL_IMPACT_TIMEOUT_MS;
if (timeoutMs > 3_600_000) timeoutMs = 3_600_000;
const timeoutMs = clampTimeout(rawTimeoutMs);
return {
ok: true,
@ -191,12 +216,13 @@ async function safeLocalImpact(
impactParams: Parameters<GroupToolPort['impact']>[1],
timeoutMs: number,
): Promise<{ value: unknown; timedOut: boolean }> {
const safeTimeoutMs = clampTimeout(timeoutMs);
let timer: ReturnType<typeof setTimeout> | undefined;
const impactP = port.impact(repo, impactParams).catch((err) => ({
error: err instanceof Error ? err.message : String(err),
}));
const timeoutP = new Promise<'timeout'>((resolve) => {
timer = setTimeout(() => resolve('timeout'), timeoutMs);
timer = setTimeout(() => resolve('timeout'), safeTimeoutMs);
});
const won = await Promise.race([
impactP.then((v) => ({ tag: 'impact' as const, v })),
@ -212,6 +238,65 @@ async function safeLocalImpact(
return { value: won.v, timedOut: false };
}
/**
* Race a single Phase-2 `impactByUid` call against a remaining-budget
* timer. The Codex adversarial review on PR #1331 surfaced that the
* fanout loop only checked `Date.now() > deadline` *between* neighbor
* calls — once `await port.impactByUid(...)` was reached, a hung
* neighbor could pin the request indefinitely, and slow neighbors
* could compound past the 5-min `IMPACT_TIMEOUT_MAX_MS` cap.
*
* This helper wraps each call: a `setTimeout(remainingMs)` aborts an
* `AbortController` whose signal is forwarded to `impactByUid`, and a
* `Promise.race` resolves to `{ timedOut: true }` when the timer
* fires before the call completes. Implementors that ignore the
* signal (current local backend) still see their await resolved by
* the race; full cooperative cancellation inside the BFS is a future
* follow-up. On rejection, the value is `null` (matching the
* fanout's existing `if (fan == null)` truncation contract).
*
* Exported for direct unit testing — the helper IS the load-bearing
* mitigation surface, so the U3 regression test pins it directly
* rather than driving the full `runGroupImpact` path.
*/
export async function safeNeighborImpact(
port: GroupToolPort,
repoId: string,
uid: string,
direction: string,
opts: {
maxDepth: number;
relationTypes: string[];
minConfidence: number;
includeTests: boolean;
},
remainingMs: number,
): Promise<{ value: unknown; timedOut: boolean }> {
const controller = new AbortController();
let timer: ReturnType<typeof setTimeout> | undefined;
const callP = port
.impactByUid(repoId, uid, direction, { ...opts, signal: controller.signal })
.catch(() => null);
const timeoutP = new Promise<'timeout'>((resolve) => {
timer = setTimeout(
() => {
controller.abort();
resolve('timeout');
},
Math.max(0, remainingMs),
);
});
const won = await Promise.race([
callP.then((v) => ({ tag: 'impact' as const, v })),
timeoutP.then(() => ({ tag: 'timeout' as const })),
]);
if (timer !== undefined) clearTimeout(timer);
if (won.tag === 'timeout') {
return { value: null, timedOut: true };
}
return { value: won.v, timedOut: false };
}
export function collectImpactSymbolUids(
local: unknown,
servicePrefix: string | undefined,
@ -476,7 +561,8 @@ export async function runGroupImpact(
if (seen.has(key)) continue;
seen.add(key);
if (Date.now() > deadline) {
const remainingMs = deadline - Date.now();
if (remainingMs <= 0) {
truncatedRepos.push(n.neighborRepo);
continue;
}
@ -492,13 +578,25 @@ export async function runGroupImpact(
continue;
}
const fan = await deps.port.impactByUid(neighborHandle.id, n.neighborUid, direction, {
maxDepth,
relationTypes: relationTypes ?? [],
minConfidence,
includeTests,
});
if (fan == null) {
// Phase-2 hardening: race each impactByUid against a per-call
// timeout derived from the remaining budget. Without this wrap a
// single hung neighbor would pin the request past the clamped
// timeout, which Codex's adversarial review on PR #1331 flagged
// as the still-open half of CodeQL #184 / js/resource-exhaustion.
const { value: fan, timedOut: neighborTimedOut } = await safeNeighborImpact(
deps.port,
neighborHandle.id,
n.neighborUid,
direction,
{
maxDepth,
relationTypes: relationTypes ?? [],
minConfidence,
includeTests,
},
remainingMs,
);
if (neighborTimedOut || fan == null) {
truncatedRepos.push(n.neighborRepo);
continue;
}

3
gitnexus/src/core/group/extractors/elixir-workspace-extractor.ts
View file

@ -4,6 +4,7 @@ import type { CypherExecutor } from '../contract-extractor.js';
import type { GroupManifestLink, ContractRole } from '../types.js';
import { shouldIgnorePath, loadIgnoreRules } from '../../../config/ignore-service.js';
import { logger } from '../../logger.js';
interface ElixirAppMeta {
appName: string;
modulePrefix: string;
@ -202,7 +203,7 @@ export async function extractElixirWorkspaceLinks(
};
const existing = appsByName.get(manifest.appName);
if (existing) {
console.warn(
logger.warn(
`[elixir-workspace-extractor] duplicate app "${manifest.appName}" in "${groupPath}" and "${existing.groupPath}" — skipping "${groupPath}"`,
);
continue;

3
gitnexus/src/core/group/extractors/go-workspace-extractor.ts
View file

@ -4,6 +4,7 @@ import type { CypherExecutor } from '../contract-extractor.js';
import type { GroupManifestLink, ContractRole } from '../types.js';
import { shouldIgnorePath, loadIgnoreRules } from '../../../config/ignore-service.js';
import { logger } from '../../logger.js';
interface GoModuleMeta {
modulePath: string;
groupPath: string;
@ -211,7 +212,7 @@ export async function extractGoWorkspaceLinks(
};
const existing = modulesByPath.get(manifest.modulePath);
if (existing) {
console.warn(
logger.warn(
`[go-workspace-extractor] duplicate module "${manifest.modulePath}" in "${groupPath}" and "${existing.groupPath}" — skipping "${groupPath}"`,
);
continue;

3
gitnexus/src/core/group/extractors/grpc-extractor.ts
View file

@ -5,6 +5,7 @@ import { createIgnoreFilter } from '../../../config/ignore-service.js';
import type { ContractExtractor, CypherExecutor } from '../contract-extractor.js';
import type { ExtractedContract, RepoHandle } from '../types.js';
import { readSafe } from './fs-utils.js';
import { logger } from '../../logger.js';
import {
GRPC_SCAN_GLOB,
getPluginForFile,
@ -344,7 +345,7 @@ export function resolveProtoConflict(
// services under a fabricated package-qualified contract id.
if (winners.length !== 1) {
const paths = candidates.map((c) => c.protoPath).join(', ');
console.warn(
logger.warn(
`[grpc-extractor] Ambiguous proto resolution for service "${serviceName}" from ${sourceFilePath}: ${winners.length} candidates tied at score ${maxScore} among [${paths}] — skipping canonical contract`,
);
return null;

3
gitnexus/src/core/group/extractors/java-workspace-extractor.ts
View file

@ -4,6 +4,7 @@ import type { CypherExecutor } from '../contract-extractor.js';
import type { GroupManifestLink, ContractRole } from '../types.js';
import { shouldIgnorePath, loadIgnoreRules } from '../../../config/ignore-service.js';
import { logger } from '../../logger.js';
interface JavaProjectMeta {
groupId: string;
artifactId: string;
@ -213,7 +214,7 @@ export async function extractJavaWorkspaceLinks(
};
const existing = projectsByKey.get(key);
if (existing) {
console.warn(
logger.warn(
`[java-workspace-extractor] duplicate artifact "${key}" in "${groupPath}" and "${existing.groupPath}" — skipping "${groupPath}"`,
);
continue;

3
gitnexus/src/core/group/extractors/manifest-extractor.ts
View file

@ -1,6 +1,7 @@
import type { ContractType, CrossLink, GroupManifestLink, StoredContract } from '../types.js';
import type { CypherExecutor } from '../contract-extractor.js';
import { logger } from '../../logger.js';
export interface ManifestExtractResult {
contracts: StoredContract[];
crossLinks: CrossLink[];
@ -303,7 +304,7 @@ export class ManifestExtractor {
// fail the whole manifest extraction. Unresolved contracts still
// get a synthetic symbolUid below, so cross-impact can proceed.
const message = err instanceof Error ? err.message : String(err);
console.warn(
logger.warn(
`[manifest-extractor] resolveSymbol failed for ${link.type}:${link.contract} ` +
`in ${repoPathKey}: ${message}`,
);

3
gitnexus/src/core/group/extractors/node-workspace-extractor.ts
View file

@ -4,6 +4,7 @@ import type { CypherExecutor } from '../contract-extractor.js';
import type { GroupManifestLink, ContractRole } from '../types.js';
import { shouldIgnorePath, loadIgnoreRules } from '../../../config/ignore-service.js';
import { logger } from '../../logger.js';
interface PackageMeta {
name: string;
groupPath: string;
@ -205,7 +206,7 @@ export async function extractNodeWorkspaceLinks(
};
const existing = packagesByName.get(manifest.name);
if (existing) {
console.warn(
logger.warn(
`[node-workspace-extractor] duplicate package name "${manifest.name}" in "${groupPath}" and "${existing.groupPath}" — skipping "${groupPath}"`,
);
continue;

3
gitnexus/src/core/group/extractors/python-workspace-extractor.ts
View file

@ -4,6 +4,7 @@ import type { CypherExecutor } from '../contract-extractor.js';
import type { GroupManifestLink, ContractRole } from '../types.js';
import { shouldIgnorePath, loadIgnoreRules } from '../../../config/ignore-service.js';
import { logger } from '../../logger.js';
interface PythonPackageMeta {
name: string;
importName: string;
@ -204,7 +205,7 @@ export async function extractPythonWorkspaceLinks(
};
const existing = packagesByImportName.get(manifest.importName);
if (existing) {
console.warn(
logger.warn(
`[python-workspace-extractor] duplicate package "${manifest.name}" in "${groupPath}" and "${existing.groupPath}" — skipping "${groupPath}"`,
);
continue;

34
gitnexus/src/core/group/extractors/rust-workspace-extractor.ts
View file

@ -5,6 +5,7 @@ import type { GroupManifestLink, ContractRole } from '../types.js';
import { shouldIgnorePath } from '../../../config/ignore-service.js';
import { loadIgnoreRules } from '../../../config/ignore-service.js';
import { logger } from '../../logger.js';
/**
* Discover cross-crate contracts in a Rust workspace by reading each
* member's `Cargo.toml` dependencies and scanning source files for
@ -30,6 +31,32 @@ interface ImportedSymbol {
filePath: string;
}
/**
* Linear-time `[package].name = "..."` lookup. The previous regex
* `^\[package\]\s*\n(?:[^\[]*?\n)*?name\s*=\s*"([^"]+)"` had a nested
* lazy quantifier on `\n` that CodeQL js/redos flagged as exponential
* on inputs like `[package]\n` + many bare `\n`. We walk lines
* explicitly: scan from the first `[package]` header until we hit the
* next `[...]` section header, looking for the `name = "..."` line.
* O(n) with the line count.
*
* Exported so the U8 ReDoS regression test can drive the production
* line-walk directly with adversarial fixtures (multi-line strings,
* trailing sections, etc.) instead of duplicating it inline.
*/
export function parseCargoPackageName(content: string): string | null {
const lines = content.split('\n');
const packageStart = lines.findIndex((l) => l.trim() === '[package]');
if (packageStart < 0) return null;
for (let i = packageStart + 1; i < lines.length; i++) {
const line = lines[i].trimStart();
if (line.startsWith('[')) break; // hit the next section header
const m = /^name\s*=\s*"([^"]+)"/.exec(line);
if (m) return m[1];
}
return null;
}
/**
* Parse a Cargo.toml to extract the crate name and workspace dependency
* names. Uses simple line-based parsing — no TOML library needed for
@ -46,12 +73,9 @@ async function parseCrateManifest(
return null;
}
let name = '';
const name = parseCargoPackageName(content) ?? '';
const workspaceDeps: string[] = [];
const nameMatch = content.match(/^\[package\]\s*\n(?:[^\[]*?\n)*?name\s*=\s*"([^"]+)"/m);
if (nameMatch) name = nameMatch[1];
// Match dependencies that use workspace = true, which indicates they
// are workspace-internal deps:
// dep_name = { workspace = true }
@ -224,7 +248,7 @@ export async function extractRustWorkspaceLinks(
};
const existing = cratesByName.get(manifest.name);
if (existing) {
console.warn(
logger.warn(
`[rust-workspace-extractor] duplicate crate name "${manifest.name}" in "${groupPath}" and "${existing.groupPath}" — skipping "${groupPath}"`,
);
continue;

18
gitnexus/src/core/group/service.ts
View file

@ -14,6 +14,7 @@ import {
} from './group-path-utils.js';
import { getDefaultGitnexusDir, getGroupDir, listGroups, readContractRegistry } from './storage.js';
import { syncGroup } from './sync.js';
import { logger } from '../logger.js';
import type {
ContractRegistry,
CrossLink,
@ -64,6 +65,15 @@ export interface GroupToolPort {
relationTypes: string[];
minConfidence: number;
includeTests: boolean;
// Optional cancellation signal. Callers (notably the cross-impact
// Phase-2 fanout) wrap this call in a Promise.race against a
// setTimeout-driven AbortController so a single hung neighbor
// cannot exceed the request's clamped timeout budget. Implementors
// may honor the signal cooperatively or simply let the caller's
// race resolve the await — the latter is sufficient for the
// resource-exhaustion mitigation. When the signal is absent or
// already aborted at call time, behavior is unchanged.
signal?: AbortSignal;
},
): Promise<unknown | null>;
context(
@ -170,11 +180,11 @@ async function loadContractRegistryResilient(
contracts.push(row);
} else {
skippedCorrupt++;
console.warn('[group] skipping corrupt contract row in contracts.json');
logger.warn('[group] skipping corrupt contract row in contracts.json');
}
} catch {
skippedCorrupt++;
console.warn('[group] skipping corrupt contract row in contracts.json');
logger.warn('[group] skipping corrupt contract row in contracts.json');
}
}
}
@ -187,11 +197,11 @@ async function loadContractRegistryResilient(
crossLinks.push(row);
} else {
skippedCorrupt++;
console.warn('[group] skipping corrupt crossLinks row in contracts.json');
logger.warn('[group] skipping corrupt crossLinks row in contracts.json');
}
} catch {
skippedCorrupt++;
console.warn('[group] skipping corrupt crossLinks row in contracts.json');
logger.warn('[group] skipping corrupt crossLinks row in contracts.json');
}
}
}

59
gitnexus/src/core/group/storage.ts
View file

@ -5,6 +5,15 @@ import * as os from 'node:os';
import { randomBytes } from 'node:crypto';
import type { ContractRegistry } from './types.js';
/**
* Build an unpredictable suffix for atomic-write tmp files. Replaces the
* previous `Date.now()` pattern which CodeQL flagged as
* js/insecure-temporary-file: a guessable suffix in a writable directory
* lets a co-located attacker pre-create or symlink the tmp path before the
* write lands.
*/
const tmpSuffix = (): string => randomBytes(8).toString('hex');
const CONTRACTS_FILE = 'contracts.json';
export function getDefaultGitnexusDir(): string {
@ -35,9 +44,21 @@ export async function writeContractRegistry(
registry: ContractRegistry,
): Promise<void> {
const targetPath = path.join(groupDir, CONTRACTS_FILE);
const tmpPath = `${targetPath}.tmp.${randomBytes(8).toString('hex')}`;
const tmpPath = `${targetPath}.tmp.${tmpSuffix()}`;
await fsp.writeFile(tmpPath, JSON.stringify(registry, null, 2), 'utf-8');
// O_EXCL via `'wx'` flag + explicit `0o600` mode — closes both halves
// of the CodeQL js/insecure-temporary-file finding: `'wx'` rejects a
// pre-planted symlink at the path, and `0o600` (user-only) prevents
// the file from being created group/world readable while it briefly
// contains contract data en route to the rename. The query's
// `isSecureMode` predicate inspects ONLY the mode argument, not the
// flags, so the explicit mode is what credits the fix.
const handle = await fsp.open(tmpPath, 'wx', 0o600);
try {
await handle.writeFile(JSON.stringify(registry, null, 2), 'utf-8');
} finally {
await handle.close();
}
await fsp.rename(tmpPath, targetPath);
}
@ -107,6 +128,38 @@ matching:
# exclude_links_paths: [/ping, /health, /healthcheck]
# exclude_links_param_only_paths: false
`;
await fsp.writeFile(path.join(groupDir, 'group.yaml'), template, 'utf-8');
// Always write group.yaml with O_EXCL via `fsp.open(..., 'wx')` —
// refuses to follow a pre-planted symlink at the target path, closing
// the TOCTOU window between the existence check (line ~98) and the
// write that CodeQL js/insecure-temporary-file flags. Under
// `force=true` we unlink the existing file first (best-effort, no-op
// when absent) so the subsequent O_EXCL open succeeds AND the same
// symlink-rejection guarantee holds — this is strictly safer than
// the previous `flag: force ? 'w' : 'wx'` shape, which silently
// followed symlinks under force. CodeQL's rule does not recognize
// the `writeFile(path, content, { flag: 'wx' })` shape as O_EXCL;
// the explicit open() handle below is what credits the mitigation.
const yamlPath = path.join(groupDir, 'group.yaml');
if (force) {
try {
await fsp.unlink(yamlPath);
} catch (err) {
// ENOENT (file absent) is expected on first run; rethrow anything
// else so we don't silently mask permission/EBUSY failures.
if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
}
}
// `'wx'` rejects a pre-planted symlink at the path; `0o600` is
// user-only (no group/world bits) — gitnexus storage is per-user
// (`~/.gitnexus/...`), so any "other user wants to read this" case is
// a misconfiguration, not a feature. Keeping the file user-only also
// satisfies CodeQL's `isSecureMode` predicate (low 6 bits == 0) and
// closes the js/insecure-temporary-file alert at this site.
const handle = await fsp.open(yamlPath, 'wx', 0o600);
try {
await handle.writeFile(template, 'utf-8');
} finally {
await handle.close();
}
return groupDir;
}

7
gitnexus/src/core/group/sync.ts
View file

@ -16,6 +16,7 @@ import type { CypherExecutor } from './contract-extractor.js';
import { writeContractRegistry } from './storage.js';
import type { ContractRegistry } from './types.js';
import { logger } from '../logger.js';
export interface SyncOptions {
extractorOverride?:
| ((repo: RepoHandle) => Promise<StoredContract[]>)
@ -211,7 +212,7 @@ export async function syncGroup(config: GroupConfig, opts?: SyncOptions): Promis
allLinks = [...allLinks, ...wsResult.links];
if (opts?.verbose) {
for (const s of wsResult.stats) {
console.log(
logger.info(
` workspace-deps: discovered ${s.linkCount} cross-${s.ecosystem.toLowerCase()} links from ${s.projectCount} ${s.ecosystem} projects`,
);
}
@ -230,7 +231,7 @@ export async function syncGroup(config: GroupConfig, opts?: SyncOptions): Promis
for (const link of allLinks) {
const dangling = [link.from, link.to].filter((r) => !knownRepos.has(r));
if (dangling.length > 0) {
console.warn(
logger.warn(
`[group/sync] manifest link ${link.type}:${link.contract} references repos not in config.repos: ${dangling.join(', ')} — cross-links will use synthetic UIDs`,
);
}
@ -241,7 +242,7 @@ export async function syncGroup(config: GroupConfig, opts?: SyncOptions): Promis
autoContracts.push(...manifestResult.contracts);
manifestCrossLinks = manifestResult.crossLinks;
if (opts?.verbose) {
console.log(
logger.info(
` manifest: ${manifestCrossLinks.length} cross-links from ${allLinks.length} links (${config.links.length} declared + ${allLinks.length - config.links.length} discovered)`,
);
}

3
gitnexus/src/core/ingestion/ast-cache.ts
View file

@ -1,6 +1,7 @@
import { LRUCache } from 'lru-cache';
import Parser from 'tree-sitter';
import { logger } from '../logger.js';
/**
* Minimal structural shape consumers need when reading Trees back
* through a phase-dependency boundary. Declared here so phases that
@ -49,7 +50,7 @@ export const createASTCache = (maxSize: number = 50): ASTCache => {
// will hand freed memory to scope-resolution.
(tree as unknown as { delete?: () => void }).delete?.();
} catch (e) {
console.warn('Failed to delete tree from WASM memory', e);
logger.warn({ e }, 'Failed to delete tree from WASM memory');
}
},
});

5
gitnexus/src/core/ingestion/call-processor.ts
View file

@ -75,6 +75,7 @@ import { extractReturnTypeName, stripNullable } from './type-extractors/shared.j
import type { LiteralTypeInferrer } from './type-extractors/types.js';
import type { SyntaxNode } from './utils/ast-helpers.js';
import { logger } from '../logger.js';
/** Per-file resolved type bindings for exported symbols.
* Populated during call processing, consumed by Phase 14 re-resolution pass. */
export type ExportedTypeMap = Map<string, Map<string, string>>;
@ -784,7 +785,7 @@ export const processCalls = async (
const query = new Parser.Query(lang, queryStr);
matches = query.matches(tree.rootNode);
} catch (queryError) {
console.warn(`Query error for ${file.path}:`, queryError);
logger.warn({ queryError }, `Query error for ${file.path}:`);
continue;
}
@ -1391,7 +1392,7 @@ export const processCalls = async (
if (skippedByLang && skippedByLang.size > 0) {
for (const [lang, count] of skippedByLang.entries()) {
console.warn(
logger.warn(
`[ingestion] Skipped ${count} ${lang} file(s) in call processing — ${lang} parser not available.`,
);
}

5
gitnexus/src/core/ingestion/cluster-enricher.ts
View file

@ -7,6 +7,7 @@
import { CommunityNode } from './community-processor.js';
import { logger } from '../logger.js';
// ============================================================================
// TYPES
// ============================================================================
@ -128,7 +129,7 @@ export const enrichClusters = async (
enrichments.set(community.id, enrichment);
} catch (error) {
// On error, fallback to heuristic
console.warn(`Failed to enrich cluster ${community.id}:`, error);
logger.warn({ error }, `Failed to enrich cluster ${community.id}:`);
enrichments.set(community.id, {
name: community.heuristicLabel,
keywords: [],
@ -210,7 +211,7 @@ Output JSON array:
}
}
} catch (error) {
console.warn('Batch enrichment failed, falling back to heuristics:', error);
logger.warn({ error }, 'Batch enrichment failed, falling back to heuristics:');
// Fallback for this batch
for (const community of batch) {
enrichments.set(community.id, {

7
gitnexus/src/core/ingestion/cobol/cobol-copy-expander.ts
View file

@ -1,3 +1,4 @@
import { logger } from '../../logger.js';
/**
* COBOL COPY statement expansion engine.
*
@ -454,7 +455,7 @@ export function expandCopies(
if (visited.has(resolvedPath)) {
if (!warnedCircular.has(resolvedPath)) {
warnedCircular.add(resolvedPath);
console.warn(
logger.warn(
`[cobol-copy-expander] Circular COPY detected: ${cs.target} (${resolvedPath}) ` +
`includes itself. Skipping expansion.`,
);
@ -464,7 +465,7 @@ export function expandCopies(
// Max depth exceeded — keep unexpanded
if (depth >= maxDepth) {
console.warn(
logger.warn(
`[cobol-copy-expander] Max expansion depth (${maxDepth}) reached for ` +
`COPY ${cs.target} in ${srcPath}. Skipping expansion.`,
);
@ -475,7 +476,7 @@ export function expandCopies(
if (++totalExpansions > MAX_TOTAL_EXPANSIONS) {
if (!warnedCircular.has('__max_total__')) {
warnedCircular.add('__max_total__');
console.warn(
logger.warn(
`[cobol-copy-expander] Max total expansions (${MAX_TOTAL_EXPANSIONS}) reached ` +
`in ${srcPath}. Skipping further expansions.`,
);

17
gitnexus/src/core/ingestion/cobol/cobol-preprocessor.ts
View file

@ -369,9 +369,20 @@ const RE_USE_AFTER =
/\bUSE\s+(?:AFTER\s+)?(?:STANDARD\s+)?(?:EXCEPTION|ERROR)\s+ON\s+([A-Z][A-Z0-9-]+|INPUT|OUTPUT|I-O|EXTEND)\b/i;
// SET statement (condition, index)
const RE_SET_TO_TRUE = /\bSET\s+((?:[A-Z][A-Z0-9-]+(?:\s+OF\s+[A-Z][A-Z0-9-]+)?\s+)+)TO\s+TRUE\b/i;
const RE_SET_INDEX =
/\bSET\s+((?:[A-Z][A-Z0-9-]+\s+)+)(TO|UP\s+BY|DOWN\s+BY)\s+(\d+|[A-Z][A-Z0-9-]+)/i;
//
// Catastrophic-backtracking note (CodeQL js/redos): the previous shape
// `((?:[A-Z][A-Z0-9-]+(?:\s+OF\s+[A-Z][A-Z0-9-]+)?\s+)+)TO\s+TRUE`
// nested `\s+` quantifiers across alternations and was exponential on
// inputs like "SET a OF a OF a ... TO TRUE". Replaced with a lazy
// dot-match bounded by the explicit `\s+TO\s+TRUE` suffix — `.+?` is
// O(n) with the trailing anchor, and the captured group is parsed
// downstream the same way as before.
// Exported so the U8 ReDoS regression test can pin the exact production
// pattern. Direct import is the only way to ensure the test's
// pathological-input timing assertion exercises the production regex
// instead of an inline copy that drifts.
export const RE_SET_TO_TRUE = /\bSET\s+(.+?)\s+TO\s+TRUE\b/i;
export const RE_SET_INDEX = /\bSET\s+(.+?)\s+(TO|UP\s+BY|DOWN\s+BY)\s+(\d+|[A-Z][A-Z0-9-]+)/i;
// INITIALIZE statement — data reset (captures targets before REPLACING/WITH clause)
const RE_INITIALIZE = /\bINITIALIZE\s+([\s\S]*?)(?=\bREPLACING\b|\bWITH\b|\.\s*$|$)/i;

5
gitnexus/src/core/ingestion/filesystem-walker.ts
View file

@ -5,6 +5,7 @@ import path from 'path';
import { glob } from 'glob';
import { createIgnoreFilter } from '../../config/ignore-service.js';
import { logger } from '../logger.js';
export interface FileEntry {
path: string;
content: string;
@ -74,10 +75,10 @@ export const walkRepositoryPaths = async (
if (skippedLarge > 0) {
const isDefault = maxFileSizeBytes === DEFAULT_MAX_FILE_SIZE_BYTES;
const suffix = isDefault ? ', likely generated/vendored' : '';
console.warn(` Skipped ${skippedLarge} large files (>${maxFileSizeBytes / 1024}KB${suffix})`);
logger.warn(` Skipped ${skippedLarge} large files (>${maxFileSizeBytes / 1024}KB${suffix})`);
if (isVerboseIngestionEnabled()) {
for (const p of skippedLargePaths) {
console.warn(` - ${p}`);
logger.warn(` - ${p}`);
}
}
}

5
gitnexus/src/core/ingestion/heritage-processor.ts
View file

@ -34,6 +34,7 @@ import type { ResolutionContext } from './model/resolution-context.js';
import { TIER_CONFIDENCE } from './model/resolution-context.js';
import type { HeritageInfo } from './heritage-types.js';
import { logger } from '../logger.js';
/**
* Derive the heritage-resolution strategy for a language from its
* `LanguageProvider`. This is the production wiring that `buildHeritageMap`
@ -237,7 +238,7 @@ export const processHeritage = async (
query = new Parser.Query(treeSitterLang, queryStr);
matches = query.matches(tree.rootNode);
} catch (queryError) {
console.warn(`Heritage query error for ${file.path}:`, queryError);
logger.warn({ queryError }, `Heritage query error for ${file.path}:`);
continue;
}
@ -267,7 +268,7 @@ export const processHeritage = async (
if (skippedByLang && skippedByLang.size > 0) {
for (const [lang, count] of skippedByLang.entries()) {
console.warn(
logger.warn(
`[ingestion] Skipped ${count} ${lang} file(s) in heritage processing — ${lang} parser not available.`,
);
}

29
gitnexus/src/core/ingestion/import-processor.ts
View file

@ -27,6 +27,7 @@ import type { SyntaxNode } from './utils/ast-helpers.js';
import { isDev } from './utils/env.js';
import { isRegistryPrimary } from './registry-primary-flag.js';
import { logger } from '../logger.js';
// Type: Map<FilePath, Set<ResolvedFilePath>>
// Stores all files that a given file imports from
export type ImportMap = Map<string, Set<string>>;
@ -324,14 +325,18 @@ export const processImports = async (
matches = query.matches(tree.rootNode);
} catch (queryError: any) {
if (isDev) {
console.group(`🔴 Query Error: ${file.path}`);
console.log('Language:', language);
console.log('Query (first 200 chars):', queryStr.substring(0, 200) + '...');
console.log('Error:', queryError?.message || queryError);
console.log('File content (first 300 chars):', file.content.substring(0, 300));
console.log('AST root type:', tree.rootNode?.type);
console.log('AST has errors:', tree.rootNode?.hasError);
console.groupEnd();
logger.error(
{
file: file.path,
language,
err: queryError?.message || queryError,
queryPreview: queryStr.substring(0, 200) + '...',
contentPreview: file.content.substring(0, 300),
astRootType: tree.rootNode?.type,
astHasError: tree.rootNode?.hasError,
},
'tree-sitter query error',
);
}
if (wasReparsed) (tree as unknown as { delete?: () => void }).delete?.();
@ -346,7 +351,7 @@ export const processImports = async (
const sourceNode = captureMap['import.source'];
if (!sourceNode) {
if (isDev) {
console.log(`⚠️ Import captured but no source node in ${file.path}`);
logger.info(`⚠️ Import captured but no source node in ${file.path}`);
}
return;
}
@ -399,14 +404,14 @@ export const processImports = async (
if (skippedByLang && skippedByLang.size > 0) {
for (const [lang, count] of skippedByLang.entries()) {
console.warn(
logger.warn(
`[ingestion] Skipped ${count} ${lang} file(s) in import processing — ${lang} parser not available.`,
);
}
}
if (isDev) {
console.log(
logger.info(
`📊 Import processing complete: ${getResolvedCount()}/${totalImportsFound} imports resolved to graph edges`,
);
}
@ -498,7 +503,7 @@ export const processImportsFromExtracted = async (
);
if (isDev) {
console.log(
logger.info(
`📊 Import processing (fast path): ${getResolvedCount()}/${totalImportsFound} imports resolved to graph edges`,
);
}

11
gitnexus/src/core/ingestion/language-config.ts
View file

@ -4,6 +4,7 @@ import type { ImportConfigs } from './import-resolvers/types.js';
import { isDev } from './utils/env.js';
import { logger } from '../logger.js';
// ============================================================================
// LANGUAGE-SPECIFIC CONFIG TYPES
// ============================================================================
@ -82,7 +83,7 @@ export async function loadTsconfigPaths(repoRoot: string): Promise<TsconfigPaths
if (aliases.size > 0) {
if (isDev) {
console.log(`📦 Loaded ${aliases.size} path aliases from ${filename}`);
logger.info(`📦 Loaded ${aliases.size} path aliases from ${filename}`);
}
return { aliases, baseUrl };
}
@ -104,7 +105,7 @@ export async function loadGoModulePath(repoRoot: string): Promise<GoModuleConfig
const match = content.match(/^module\s+(\S+)/m);
if (match) {
if (isDev) {
console.log(`📦 Loaded Go module path: ${match[1]}`);
logger.info(`📦 Loaded Go module path: ${match[1]}`);
}
return { modulePath: match[1] };
}
@ -132,7 +133,7 @@ export async function loadComposerConfig(repoRoot: string): Promise<ComposerConf
}
if (isDev) {
console.log(`📦 Loaded ${psr4.size} PSR-4 mappings from composer.json`);
logger.info(`📦 Loaded ${psr4.size} PSR-4 mappings from composer.json`);
}
return { psr4 };
} catch {
@ -178,7 +179,7 @@ export async function loadCSharpProjectConfig(repoRoot: string): Promise<CSharpP
const projectDir = path.relative(repoRoot, dir).replace(/\\/g, '/');
configs.push({ rootNamespace, projectDir });
if (isDev) {
console.log(
logger.info(
`📦 Loaded C# project: ${entry.name} (namespace: ${rootNamespace}, dir: ${projectDir})`,
);
}
@ -217,7 +218,7 @@ export async function loadSwiftPackageConfig(repoRoot: string): Promise<SwiftPac
if (targets.size > 0) {
if (isDev) {
console.log(`📦 Loaded ${targets.size} Swift package targets`);
logger.info(`📦 Loaded ${targets.size} Swift package targets`);
}
return { targets };
}

3
gitnexus/src/core/ingestion/method-extractors/generic.ts
View file

@ -8,6 +8,7 @@
*/
import type { SyntaxNode } from '../utils/ast-helpers.js';
import { logger } from '../../logger.js';
import type {
MethodExtractor,
MethodExtractorContext,
@ -158,7 +159,7 @@ function findBodies(node: SyntaxNode, bodyNodeSet: Set<string>): SyntaxNode[] {
// Fallback: body field exists but its type is not in bodyNodeTypes.
// This may indicate a config typo — log for debugging if NODE_ENV is development.
if (process.env.NODE_ENV === 'development') {
console.warn(
logger.warn(
`[MethodExtractor] body field type '${bodyField.type}' not in bodyNodeTypes for node '${node.type}'`,
);
}

13
gitnexus/src/core/ingestion/parsing-processor.ts
View file

@ -34,6 +34,7 @@ import {
import type { LanguageProvider } from './language-provider.js';
import type { ParsedFile } from 'gitnexus-shared';
import { WorkerPool } from './workers/worker-pool.js';
import { logger } from '../logger.js';
import type {
ParseWorkerResult,
ParseWorkerInput,
@ -191,7 +192,7 @@ const processParsingWithWorkers = async (
const summary = Array.from(skippedLanguages.entries())
.map(([lang, count]) => `${lang}: ${count}`)
.join(', ');
console.warn(` Skipped unsupported languages: ${summary}`);
logger.warn(` Skipped unsupported languages: ${summary}`);
}
// Final progress
@ -382,7 +383,7 @@ const processParsingSequential = async (
bufferSize: getTreeSitterBufferSize(parseContent),
});
} catch (parseError) {
console.warn(`Skipping unparseable file: ${file.path}`);
logger.warn(`Skipping unparseable file: ${file.path}`);
continue;
}
@ -408,7 +409,7 @@ const processParsingSequential = async (
query = new Parser.Query(language, queryString);
matches = query.matches(tree.rootNode);
} catch (queryError) {
console.warn(`Query error for ${file.path}:`, queryError);
logger.warn({ queryError }, `Query error for ${file.path}:`);
continue;
}
@ -701,7 +702,7 @@ const processParsingSequential = async (
if (skippedByLang && skippedByLang.size > 0) {
for (const [lang, count] of skippedByLang.entries()) {
console.warn(
logger.warn(
`[ingestion] Skipped ${count} ${lang} file(s) in parsing processing — ${lang} parser not available.`,
);
}
@ -742,7 +743,7 @@ export const processParsing = async (
// in scope-resolution with an empty cache and get re-parsed.
// Surfacing this in PROF mode prevents silent perf cliffs when
// a repo crosses the worker-pool threshold.
console.warn(
logger.warn(
`[scope-resolution prof] worker pool engaged for ${files.length} files — cross-phase tree cache will be empty; scope-resolution re-parses.`,
);
}
@ -757,7 +758,7 @@ export const processParsing = async (
);
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
console.warn('Worker pool parsing stopped; continuing with sequential parser:', message);
logger.warn({ message }, 'Worker pool parsing stopped; continuing with sequential parser:');
reportProgress?.(
lastProgress,
files.length,

7
gitnexus/src/core/ingestion/pipeline-phases/cobol.ts
View file

@ -15,6 +15,7 @@ import { readFileContents } from '../filesystem-walker.js';
import type { StructureOutput } from './structure.js';
import { isDev } from '../utils/env.js';
import { logger } from '../../logger.js';
export interface CobolOutput {
programs: number;
paragraphs: number;
@ -47,7 +48,7 @@ export const cobolPhase: PipelinePhase<CobolOutput> = {
const cobolResult = processCobol(ctx.graph, cobolFiles, allPathSet);
if (isDev) {
console.log(
logger.info(
` COBOL: ${cobolResult.programs} programs, ${cobolResult.paragraphs} paragraphs, ${cobolResult.sections} sections from ${cobolFiles.length} files`,
);
if (
@ -55,12 +56,12 @@ export const cobolPhase: PipelinePhase<CobolOutput> = {
cobolResult.execCicsBlocks > 0 ||
cobolResult.entryPoints > 0
) {
console.log(
logger.info(
` COBOL enriched: ${cobolResult.execSqlBlocks} SQL blocks, ${cobolResult.execCicsBlocks} CICS blocks, ${cobolResult.entryPoints} entry points, ${cobolResult.moves} moves, ${cobolResult.fileDeclarations} file declarations`,
);
}
if (cobolResult.jclJobs > 0) {
console.log(` JCL: ${cobolResult.jclJobs} jobs, ${cobolResult.jclSteps} steps`);
logger.info(` JCL: ${cobolResult.jclJobs} jobs, ${cobolResult.jclSteps} steps`);
}
}

3
gitnexus/src/core/ingestion/pipeline-phases/communities.ts
View file

@ -15,6 +15,7 @@ import type { StructureOutput } from './structure.js';
import { processCommunities, type CommunityDetectionResult } from '../community-processor.js';
import { isDev } from '../utils/env.js';
import { logger } from '../../logger.js';
export interface CommunitiesOutput {
communityResult: CommunityDetectionResult;
}
@ -47,7 +48,7 @@ export const communitiesPhase: PipelinePhase<CommunitiesOutput> = {
});
if (isDev) {
console.log(
logger.info(
`🏘️ Community detection: ${communityResult.stats.totalCommunities} communities found (modularity: ${communityResult.stats.modularity.toFixed(3)})`,
);
}

9
gitnexus/src/core/ingestion/pipeline-phases/cross-file-impl.ts
View file

@ -23,6 +23,7 @@ import { topologicalLevelSort } from '../utils/graph-sort.js';
import type { KnowledgeGraph } from '../../graph/types.js';
import { isDev } from '../utils/env.js';
import { logger } from '../../logger.js';
/** Max AST trees to keep in LRU cache for cross-file binding propagation. */
const AST_CACHE_CAP = 50;
@ -60,7 +61,7 @@ export async function runCrossFileBindingPropagation(
const { levels, cycleCount } = topologicalLevelSort(ctx.importMap);
if (isDev && cycleCount > 0) {
console.log(`🔄 ${cycleCount} files in import cycles (processed last in undefined order)`);
logger.info(`🔄 ${cycleCount} files in import cycles (processed last in undefined order)`);
}
let filesWithGaps = 0;
@ -88,7 +89,7 @@ export async function runCrossFileBindingPropagation(
const gapRatio = totalFiles > 0 ? filesWithGaps / totalFiles : 0;
if (gapRatio < CROSS_FILE_SKIP_THRESHOLD && filesWithGaps < gapThreshold) {
if (isDev) {
console.log(
logger.info(
`⏭️ Cross-file re-resolution skipped (${filesWithGaps}/${totalFiles} files, ${(gapRatio * 100).toFixed(1)}% < ${CROSS_FILE_SKIP_THRESHOLD * 100}% threshold)`,
);
}
@ -193,7 +194,7 @@ export async function runCrossFileBindingPropagation(
if (crossFileResolved >= MAX_CROSS_FILE_REPROCESS) {
if (isDev)
console.log(`⚠️ Cross-file re-resolution capped at ${MAX_CROSS_FILE_REPROCESS} files`);
logger.info(`⚠️ Cross-file re-resolution capped at ${MAX_CROSS_FILE_REPROCESS} files`);
break;
}
}
@ -204,7 +205,7 @@ export async function runCrossFileBindingPropagation(
const elapsed = Date.now() - crossFileStart;
const totalElapsed = Date.now() - pipelineStart;
const reResolutionPct = totalElapsed > 0 ? ((elapsed / totalElapsed) * 100).toFixed(1) : '0';
console.log(
logger.info(
`🔗 Cross-file re-resolution: ${crossFileResolved} candidates re-processed` +
` in ${elapsed}ms (${reResolutionPct}% of total ingestion time so far)`,
);

5
gitnexus/src/core/ingestion/pipeline-phases/cross-file.ts
View file

@ -36,6 +36,7 @@ import type { ParseOutput } from './parse.js';
import { runCrossFileBindingPropagation } from './cross-file-impl.js';
import { isDev } from '../utils/env.js';
import { logger } from '../../logger.js';
export interface CrossFileOutput {
/** Number of files re-processed during cross-file propagation. */
filesReprocessed: number;
@ -59,11 +60,11 @@ export const crossFilePhase: PipelinePhase<CrossFileOutput> = {
if (isDev) {
if (bindingAccumulator.totalBindings > 0) {
const memKB = Math.round(bindingAccumulator.estimateMemoryBytes() / 1024);
console.log(
logger.info(
`📦 BindingAccumulator: ${bindingAccumulator.totalBindings} bindings across ${bindingAccumulator.fileCount} files (~${memKB} KB)`,
);
} else if (totalFiles > 0) {
console.log(
logger.info(
`📦 BindingAccumulator: EMPTY — 0 bindings across 0 files despite ${totalFiles} parsed files. If the codebase has typed bindings, this indicates an upstream regression.`,
);
}

3
gitnexus/src/core/ingestion/pipeline-phases/markdown.ts
View file

@ -15,6 +15,7 @@ import { readFileContents } from '../filesystem-walker.js';
import type { StructureOutput } from './structure.js';
import { isDev } from '../utils/env.js';
import { logger } from '../../logger.js';
export interface MarkdownOutput {
/** Number of markdown sections extracted. */
sections: number;
@ -48,7 +49,7 @@ export const markdownPhase: PipelinePhase<MarkdownOutput> = {
const mdResult = processMarkdown(ctx.graph, mdFiles, allPathSet);
if (isDev) {
console.log(
logger.info(
` Markdown: ${mdResult.sections} sections, ${mdResult.links} cross-links from ${mdFiles.length} files`,
);
}

3
gitnexus/src/core/ingestion/pipeline-phases/mro.ts
View file

@ -15,6 +15,7 @@ import type { StructureOutput } from './structure.js';
import { computeMRO } from '../mro-processor.js';
import { isDev } from '../utils/env.js';
import { logger } from '../../logger.js';
export interface MROOutput {
entries: number;
ambiguityCount: number;
@ -42,7 +43,7 @@ export const mroPhase: PipelinePhase<MROOutput> = {
const mroResult = computeMRO(ctx.graph);
if (isDev && mroResult.entries.length > 0) {
console.log(
logger.info(
`🔀 MRO: ${mroResult.entries.length} classes analyzed, ${mroResult.ambiguityCount} ambiguities, ${mroResult.overrideEdges} METHOD_OVERRIDES, ${mroResult.methodImplementsEdges} METHOD_IMPLEMENTS`,
);
}

3
gitnexus/src/core/ingestion/pipeline-phases/orm.ts
View file

@ -16,6 +16,7 @@ import type { ExtractedORMQuery } from '../workers/parse-worker.js';
import type { KnowledgeGraph } from '../../graph/types.js';
import { isDev } from '../utils/env.js';
import { logger } from '../../logger.js';
export interface ORMOutput {
edgesCreated: number;
modelCount: number;
@ -91,7 +92,7 @@ function processORMQueries(
}
if (isDev) {
console.log(
logger.info(
`ORM dataflow: ${edgesCreated} QUERIES edges, ${modelNodes.size} models (${queries.length} total calls)`,
);
}

21
gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts
View file

@ -69,6 +69,7 @@ import { isDev } from '../utils/env.js';
import { synthesizeWildcardImportBindings, needsSynthesis } from './wildcard-synthesis.js';
import { extractORMQueriesInline } from './orm-extraction.js';
import { logger } from '../../logger.js';
// ── Constants ──────────────────────────────────────────────────────────────
/** Max bytes of source content to load per parse chunk. */
@ -136,7 +137,7 @@ export async function runChunkedParseAndResolve(
}
}
for (const [lang, count] of skippedByLang) {
console.warn(
logger.warn(
`Skipping ${count} ${lang} file(s) — ${lang} parser not available (native binding may not have built). Try: npm rebuild tree-sitter-${lang}`,
);
}
@ -171,7 +172,7 @@ export async function runChunkedParseAndResolve(
if (isDev) {
const totalMB = parseableScanned.reduce((s, f) => s + f.size, 0) / (1024 * 1024);
console.log(
logger.info(
`📂 Scan: ${totalFiles} paths, ${totalParseable} parseable (${totalMB.toFixed(0)}MB), ${numChunks} chunks @ ${CHUNK_BYTE_BUDGET / (1024 * 1024)}MB budget`,
);
}
@ -220,9 +221,9 @@ export async function runChunkedParseAndResolve(
}
workerPool = createWorkerPool(workerUrl);
} catch (err) {
console.warn(
logger.warn(
{ err: (err as Error).message },
'Worker pool creation failed, using sequential fallback:',
(err as Error).message,
);
}
}
@ -339,7 +340,7 @@ export async function runChunkedParseAndResolve(
exportedTypeMap,
);
if (isDev && enrichedCount > 0) {
console.log(
logger.info(
`🔗 E1: Seeded ${enrichedCount} cross-file receiver types (chunk ${chunkIdx + 1})`,
);
}
@ -538,7 +539,7 @@ export async function runChunkedParseAndResolve(
const rcStats = ctx.getStats();
const total = rcStats.cacheHits + rcStats.cacheMisses;
const hitRate = total > 0 ? ((rcStats.cacheHits / total) * 100).toFixed(1) : '0';
console.log(
logger.info(
`🔍 Resolution cache: ${rcStats.cacheHits} hits, ${rcStats.cacheMisses} misses (${hitRate}% hit rate)`,
);
}
@ -554,15 +555,15 @@ export async function runChunkedParseAndResolve(
bindingAccumulator.finalize();
const enriched = enrichExportedTypeMap(bindingAccumulator, graph, exportedTypeMap);
if (isDev && enriched > 0) {
console.log(
logger.info(
`🔗 Worker TypeEnv enrichment: ${enriched} fixpoint-inferred exports added to ExportedTypeMap`,
);
}
} catch (enrichErr) {
if (isDev) {
console.warn(
logger.warn(
{ err: (enrichErr as Error).message },
'Post-fallback finalize/enrich failed during cleanup:',
(enrichErr as Error).message,
);
}
}
@ -571,7 +572,7 @@ export async function runChunkedParseAndResolve(
if (!hasSynthesized) {
const synthesized = synthesizeWildcardImportBindings(graph, ctx);
if (isDev && synthesized > 0) {
console.log(
logger.info(
`🔗 Synthesized ${synthesized} additional wildcard import bindings (Go/Ruby/C++/Swift/Python)`,
);
}

5
gitnexus/src/core/ingestion/pipeline-phases/processes.ts
View file

@ -19,6 +19,7 @@ import { processProcesses, type ProcessDetectionResult } from '../process-proces
import { generateId } from '../../../lib/utils.js';
import { isDev } from '../utils/env.js';
import { logger } from '../../logger.js';
export interface ProcessesOutput {
processResult: ProcessDetectionResult;
}
@ -67,7 +68,7 @@ export const processesPhase: PipelinePhase<ProcessesOutput> = {
);
if (isDev) {
console.log(
logger.info(
`🔄 Process detection: ${processResult.stats.totalProcesses} processes found (${processResult.stats.crossCommunityCount} cross-community)`,
);
}
@ -167,7 +168,7 @@ export const processesPhase: PipelinePhase<ProcessesOutput> = {
}
}
if (isDev && linked > 0) {
console.log(`🔗 Linked ${linked} Route/Tool nodes to execution flows`);
logger.info(`🔗 Linked ${linked} Route/Tool nodes to execution flows`);
}
}

7
gitnexus/src/core/ingestion/pipeline-phases/routes.ts
View file

@ -32,6 +32,7 @@ import { generateId } from '../../../lib/utils.js';
import { readFileContents } from '../filesystem-walker.js';
import { isDev } from '../utils/env.js';
import { logger } from '../../logger.js';
const EXPO_NAV_PATTERNS = [
/router\.(push|replace|navigate)\(\s*['"`]([^'"`]+)['"`]/g,
/<Link\s+[^>]*href=\s*['"`]([^'"`]+)['"`]/g,
@ -174,7 +175,7 @@ export const routesPhase: PipelinePhase<RoutesOutput> = {
}
if (isDev) {
console.log(
logger.info(
`🗺️ Route registry: ${routeRegistry.size} routes${duplicateRoutes > 0 ? ` (${duplicateRoutes} duplicate URLs skipped)` : ''}`,
);
}
@ -224,7 +225,7 @@ export const routesPhase: PipelinePhase<RoutesOutput> = {
linkedCount++;
}
if (isDev && linkedCount > 0) {
console.log(
logger.info(
`🛡️ Linked ${mwPath} middleware [${mwLabel.join(', ')}] to ${linkedCount} routes`,
);
}
@ -290,7 +291,7 @@ export const routesPhase: PipelinePhase<RoutesOutput> = {
processNextjsFetchRoutes(ctx.graph, allFetchCalls, routeURLToFile, consumerContents);
if (isDev) {
console.log(
logger.info(
`🔗 Processed ${allFetchCalls.length} fetch() calls against ${routeRegistry.size} routes`,
);
}

5
gitnexus/src/core/ingestion/pipeline-phases/runner.ts
View file

@ -15,6 +15,7 @@
import type { PipelinePhase, PipelineContext, PhaseResult } from './types.js';
import { isDev } from '../utils/env.js';
import { logger } from '../../logger.js';
/**
* Validate that the phases form a valid dependency graph (no cycles, all deps present).
* Returns phases in topological execution order.
@ -176,7 +177,7 @@ export async function runPipeline(
const start = Date.now();
if (isDev) {
console.log(`▶ Phase: ${phase.name}`);
logger.info(`▶ Phase: ${phase.name}`);
}
// Only expose declared dependencies — prevents hidden coupling to undeclared phases.
@ -220,7 +221,7 @@ export async function runPipeline(
});
if (isDev) {
console.log(`✓ Phase: ${phase.name} (${durationMs}ms)`);
logger.info(`✓ Phase: ${phase.name} (${durationMs}ms)`);
}
}

3
gitnexus/src/core/ingestion/pipeline-phases/tools.ts
View file

@ -16,6 +16,7 @@ import { generateId } from '../../../lib/utils.js';
import { readFileContents } from '../filesystem-walker.js';
import { isDev } from '../utils/env.js';
import { logger } from '../../logger.js';
export interface ToolDef {
name: string;
filePath: string;
@ -104,7 +105,7 @@ export const toolsPhase: PipelinePhase<ToolsOutput> = {
}
if (isDev) {
console.log(`🔧 Tool registry: ${toolDefs.length} tools detected`);
logger.info(`🔧 Tool registry: ${toolDefs.length} tools detected`);
}
}

7
gitnexus/src/core/ingestion/process-processor.ts
View file

@ -17,6 +17,7 @@ import { calculateEntryPointScore, isTestFile } from './entry-point-scoring.js';
import { SupportedLanguages } from 'gitnexus-shared';
import { isDev } from './utils/env.js';
import { logger } from '../logger.js';
// ============================================================================
// CONFIGURATION
// ============================================================================
@ -319,13 +320,13 @@ const findEntryPoints = (
// DEBUG: Log top candidates with new scoring details
if (sorted.length > 0 && isDev) {
console.log(`[Process] Top 10 entry point candidates (new scoring):`);
logger.info(`[Process] Top 10 entry point candidates (new scoring):`);
sorted.slice(0, 10).forEach((c, i) => {
const node = graph.getNode(c.id);
const exported = node?.properties.isExported ? '✓' : '✗';
const shortPath = node?.properties.filePath?.split('/').slice(-2).join('/') || '';
console.log(` ${i + 1}. ${node?.properties.name} [exported:${exported}] (${shortPath})`);
console.log(` score: ${c.score.toFixed(2)} = [${c.reasons.join(' × ')}]`);
logger.info(` ${i + 1}. ${node?.properties.name} [exported:${exported}] (${shortPath})`);
logger.info(` score: ${c.score.toFixed(2)} = [${c.reasons.join(' × ')}]`);
});
}

3
gitnexus/src/core/ingestion/scope-extractor-bridge.ts
View file

@ -28,6 +28,7 @@ import type { ParsedFile } from 'gitnexus-shared';
import { extract as extractScope } from './scope-extractor.js';
import type { LanguageProvider } from './language-provider.js';
import { logger } from '../logger.js';
/** Callback used to report scope-extraction warnings to the host (worker or direct). */
export type ScopeBridgeWarn = (message: string) => void;
@ -53,7 +54,7 @@ export function extractParsedFile(
err instanceof Error ? err.message : String(err)
}`;
if (onWarn !== undefined) onWarn(message);
else console.warn(message);
logger.warn(message);
return undefined;
}
}

5
gitnexus/src/core/ingestion/scope-resolution/pipeline/phase.ts
View file

@ -38,6 +38,7 @@ import { runScopeResolution } from './run.js';
import { SCOPE_RESOLVERS } from './registry.js';
import { isDev, isSemanticModelValidatorEnabled } from '../../utils/env.js';
import { logger } from '../../../logger.js';
export interface ScopeResolutionOutput {
/** True when at least one language ran. */
readonly ran: boolean;
@ -144,7 +145,7 @@ export const scopeResolutionPhase: PipelinePhase<ScopeResolutionOutput> = {
resolutionConfig,
onWarn: (msg) => {
if (isSemanticModelValidatorEnabled()) {
console.warn(`[scope-resolution:${lang}] ${msg}`);
logger.warn(`[scope-resolution:${lang}] ${msg}`);
}
},
},
@ -162,7 +163,7 @@ export const scopeResolutionPhase: PipelinePhase<ScopeResolutionOutput> = {
});
if (isDev) {
console.log(
logger.info(
`[scope-resolution:${lang}] ${stats.filesProcessed} files → ${stats.importsEmitted} IMPORTS + ${stats.referenceEdgesEmitted} reference edges (${stats.resolve.unresolved} unresolved sites, ${stats.referenceSkipped} skipped)`,
);
}

3
gitnexus/src/core/ingestion/scope-resolution/pipeline/run.ts
View file

@ -41,6 +41,7 @@ import { emitImportEdges } from '../graph-bridge/imports-to-edges.js';
import type { ScopeResolver } from '../contract/scope-resolver.js';
import { buildWorkspaceResolutionIndex } from '../workspace-index.js';
import { logger } from '../../../logger.js';
interface RunScopeResolutionInput {
readonly graph: KnowledgeGraph;
/**
@ -279,7 +280,7 @@ export function runScopeResolution(
if (PROF) {
const tEnd = process.hrtime.bigint();
const ns = (a: bigint, b: bigint): number => Number(b - a) / 1_000_000;
console.warn(
logger.warn(
`[scope-resolution prof] extract=${ns(tStart, tExtract).toFixed(0)}ms` +
` finalize=${ns(tExtract, tFinalize).toFixed(0)}ms` +
` propagate=${ns(tFinalize, tPropagate).toFixed(0)}ms` +

3
gitnexus/src/core/ingestion/type-env.ts
View file

@ -24,6 +24,7 @@ import {
import type { SemanticModel } from './model/index.js';
import type { NodeLabel } from 'gitnexus-shared';
import { logger } from '../logger.js';
/**
* Per-file scoped type environment: maps (scope, variableName) → typeName.
* Scope-aware: variables inside functions are keyed by function name,
@ -769,7 +770,7 @@ const resolveFixpointBindings = (
if (iter === MAX_FIXPOINT_ITERATIONS - 1 && process.env.GITNEXUS_DEBUG) {
const unresolved = pendingItems.length - resolved.size;
if (unresolved > 0) {
console.warn(
logger.warn(
`[type-env] fixpoint hit iteration cap (${MAX_FIXPOINT_ITERATIONS}), ${unresolved} items unresolved`,
);
}

3
gitnexus/src/core/ingestion/utils/max-file-size.ts
View file

@ -1,5 +1,6 @@
import { TREE_SITTER_MAX_BUFFER } from '../constants.js';
import { logger } from '../../logger.js';
/** Default threshold (512 KB). Files larger than this are skipped by the walker. */
export const DEFAULT_MAX_FILE_SIZE_BYTES = 512 * 1024;
@ -11,7 +12,7 @@ const warned = new Set<string>();
const warnOnce = (key: string, message: string): void => {
if (warned.has(key)) return;
warned.add(key);
console.warn(message);
logger.warn(message);
};
/**

19
gitnexus/src/core/ingestion/vue-sfc-extractor.ts
View file

@ -23,7 +23,24 @@ interface ScriptBlock {
lang: string;
}
const SCRIPT_RE = /<script(\s[^>]*)?>([^]*?)<\/script>/g;
// Closing-tag pattern accepts:
// - whitespace before `>` — `</script >`, `</script\t\n>`
// - attribute-like junk after `script` — `</script foo="bar">`,
// `</script\t\n bar>`
// - any case — `</SCRIPT>`, `</Script>`
//
// HTML5 parses `</script foo>` as a valid close tag (attributes on
// close tags are ignored by the parser but still terminate the script
// block). A strict `<\/script\s*>` would miss those forms and let a
// crafted Vue file hide content from this extractor — exactly the
// CodeQL `js/bad-tag-filter` failure mode (the published test cases
// it checks include `</script foo="bar">` and `</script\t\n bar>`).
//
// `[^>]*` after `</script` accepts everything up to the next `>`,
// matching the HTML parser's actual close-tag behaviour. The `i` flag
// covers the case axis. PR #1330 CI surfaced both the case and
// attribute axes; this expression closes both at once.
const SCRIPT_RE = /<script(\s[^>]*)?>([^]*?)<\/script[^>]*>/gi;
const TEMPLATE_COMPONENT_RE = /<([A-Z][A-Za-z0-9]+)/g;
// Greedy: matches from the first <template> to the *last* </template>.
// This is intentional — nested <template v-slot:...> tags are valid Vue

9
gitnexus/src/core/ingestion/workers/parse-worker.ts
View file

@ -85,6 +85,7 @@ import type { LanguageProvider } from '../language-provider.js';
import type { ParsedFile } from 'gitnexus-shared';
import { extractParsedFile } from '../scope-extractor-bridge.js';
import { logger } from '../../logger.js';
// ============================================================================
// Types for serializable results
// ============================================================================
@ -1385,7 +1386,7 @@ const processFileGroup = (
if (parentPort) {
parentPort.postMessage({ type: 'warning', message });
} else {
console.warn(message);
logger.warn(message);
}
return;
}
@ -1414,7 +1415,7 @@ const processFileGroup = (
bufferSize: getTreeSitterBufferSize(parseContent),
});
} catch (err) {
console.warn(
logger.warn(
`Failed to parse file ${file.path}: ${err instanceof Error ? err.message : String(err)}`,
);
continue;
@ -1427,7 +1428,7 @@ const processFileGroup = (
try {
matches = query.matches(tree.rootNode);
} catch (err) {
console.warn(
logger.warn(
`Query execution failed for ${file.path}: ${err instanceof Error ? err.message : String(err)}`,
);
continue;
@ -1447,7 +1448,7 @@ const processFileGroup = (
file.path,
(message) => {
if (parentPort) parentPort.postMessage({ type: 'warning', message });
else console.warn(message);
else logger.warn(message);
},
tree,
);

33
gitnexus/src/core/ingestion/workers/worker-pool.ts
View file

@ -3,6 +3,7 @@ import os from 'node:os';
import fs from 'node:fs';
import { fileURLToPath } from 'node:url';
import { logger } from '../../logger.js';
export interface WorkerPool {
/**
* Dispatch items across workers. Items are split into bounded jobs, each job
@ -297,11 +298,18 @@ export const createWorkerPool = (
splitDepth: job.splitDepth + 1,
timeoutMs: nextTimeout,
};
console.warn(
`Worker ${workerIndex} parse job idle timeout after ${job.timeoutMs / 1000}s ` +
`(${job.items.length} items, ${job.estimatedBytes} bytes, last progress: ${lastProgress}). ` +
`Splitting into ${first.items.length}/${second.items.length} item jobs with ` +
`${nextTimeout / 1000}s timeout.`,
logger.warn(
{
workerIndex,
timeoutSec: job.timeoutMs / 1000,
items: job.items.length,
estimatedBytes: job.estimatedBytes,
lastProgress,
firstSplitItems: first.items.length,
secondSplitItems: second.items.length,
nextTimeoutSec: nextTimeout / 1000,
},
`Worker ${workerIndex} parse job idle timeout. Splitting into ${first.items.length}/${second.items.length} item jobs.`,
);
// Preserve intuitive retry order; final result order is still enforced by startIndex sort.
jobs.unshift(first, second);
@ -310,10 +318,15 @@ export const createWorkerPool = (
const nextAttempt = job.attempt + 1;
if (nextAttempt <= poolOptions.maxTimeoutRetries) {
console.warn(
`Worker ${workerIndex} parse job idle timeout after ${job.timeoutMs / 1000}s ` +
`(single item, attempt ${nextAttempt}/${poolOptions.maxTimeoutRetries + 1}). ` +
`Retrying with ${nextTimeout / 1000}s timeout.`,
logger.warn(
{
workerIndex,
timeoutSec: job.timeoutMs / 1000,
attempt: nextAttempt,
maxAttempts: poolOptions.maxTimeoutRetries + 1,
nextTimeoutSec: nextTimeout / 1000,
},
`Worker ${workerIndex} parse job idle timeout (single item). Retrying with ${nextTimeout / 1000}s timeout.`,
);
jobs.unshift({
...job,
@ -402,7 +415,7 @@ export const createWorkerPool = (
reportProgress();
} else if (msg.type === 'warning') {
resetIdleTimer();
console.warn(msg.message);
logger.warn(msg.message);
} else if (msg.type === 'sub-batch-done') {
waitingForFlush = true;
resetIdleTimer();

3
gitnexus/src/core/lbug/extension-loader.ts
View file

@ -1,6 +1,7 @@
import { spawn } from 'child_process';
import { fileURLToPath } from 'node:url';
import { LBUG_MAX_DB_SIZE } from './lbug-config.js';
import { logger } from '../logger.js';
const DEFAULT_EXTENSION_INSTALL_TIMEOUT_MS = 15_000;
const EXTENSION_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/;
@ -188,7 +189,7 @@ export class ExtensionManager {
const policy = opts.policy ?? this.options.policy ?? resolvePolicyFromEnv();
const timeoutMs =
opts.installTimeoutMs ?? this.options.installTimeoutMs ?? getExtensionInstallTimeoutMs();
const warn = this.options.warn ?? console.error;
const warn = this.options.warn ?? ((msg: string) => logger.warn(msg));
if (policy === 'never') {
this.markUnavailable(name, label, 'extension install policy is "never"', warn);

69
gitnexus/src/core/lbug/lbug-adapter.ts
View file

@ -19,11 +19,15 @@ import type { CachedEmbedding } from '../embeddings/types.js';
import { extensionManager, type ExtensionEnsureOptions } from './extension-loader.js';
import {
closeLbugConnection,
isDbBusyError,
isOpenRetryExhausted,
openLbugConnection,
waitForWindowsHandleRelease,
type LbugConnectionHandle,
} from './lbug-config.js';
import { isVectorExtensionSupportedByPlatform } from '../platform/capabilities.js';
import { logger } from '../logger.js';
// ---------------------------------------------------------------------------
// Relationship CSV splitting — extracted for testability (PR #818)
// ---------------------------------------------------------------------------
@ -184,21 +188,6 @@ const DB_LOCK_RETRY_ATTEMPTS = 3;
/** Base back-off in ms between BUSY retries (multiplied by attempt number). */
const DB_LOCK_RETRY_DELAY_MS = 500;
/**
* Return true when the error message indicates that another process holds
* an exclusive lock on the LadybugDB file (e.g. `gitnexus analyze` or
* `gitnexus serve` running at the same time).
*/
export const isDbBusyError = (err: unknown): boolean => {
const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
return (
msg.includes('busy') ||
msg.includes('lock') ||
msg.includes('already in use') ||
msg.includes('could not set lock')
);
};
/**
* Return true when the error message indicates a write was attempted against
* a read-only LadybugDB connection. The MCP query pool opens DBs read-only,
@ -251,7 +240,11 @@ export const withLbugDb = async <T>(dbPath: string, operation: () => Promise<T>)
});
} catch (err) {
lastError = err;
if (!isDbBusyError(err) || attempt === DB_LOCK_RETRY_ATTEMPTS) {
// Skip outer retry when the inner open-retry already exhausted: the
// ~1.5s open-time budget was just spent, repeating the full reset+
// reopen cycle would only add 4-5s of tail latency without changing
// the outcome (both layers consult the same isDbBusyError matcher).
if (!isDbBusyError(err) || isOpenRetryExhausted(err) || attempt === DB_LOCK_RETRY_ATTEMPTS) {
throw err;
}
// Close stale connection inside the session lock to prevent race conditions
@ -329,8 +322,17 @@ const doInitLbug = async (dbPath: string) => {
await conn.query(schemaQuery);
} catch (err) {
const msg = err instanceof Error ? err.message : String(err);
if (!msg.includes('already exists')) {
console.error(`[gitnexus:lbug] schema creation warning: ${msg.slice(0, 120)}`);
// Suppression list:
// - "already exists": expected idempotent re-create on existing DBs
// - "could not set lock on file": LadybugDB v0.16.1 emits this on
// Windows when CREATE NODE TABLE runs against a path that was
// just opened (the WAL handle from a fresh Database briefly
// contests the table's first-write lock). The table is created
// anyway and any genuine cross-process lock contention surfaces
// on the next operation via withLbugDb's retry. Logging it here
// would just be noise in CI.
if (!msg.includes('already exists') && !isDbBusyError(err)) {
logger.warn(`⚠️ Schema creation warning: ${msg.slice(0, 120)}`);
}
}
}
@ -683,7 +685,7 @@ export const insertNodeToLbug = async (
return false;
} catch (e: any) {
// Node may already exist or other error
console.error(`Failed to insert ${label} node:`, e.message);
logger.error({ err: e.message }, `Failed to insert ${label} node:`);
return false;
}
};
@ -1010,15 +1012,15 @@ export const fetchExistingEmbeddingHashes = async (
const nodeId = r.nodeId ?? r[0];
if (nodeId) map.set(nodeId, STALE_HASH_SENTINEL);
}
console.error(
`[gitnexus:embed] ${map.size} nodes in legacy DB (missing chunk-aware columns) — all treated as stale`,
logger.info(
`[embed] ${map.size} nodes in legacy DB (missing chunk-aware columns) — all treated as stale`,
);
return map;
} catch (fallbackErr: any) {
const fallbackMsg = fallbackErr?.message ?? '';
if (isMissingColumnOrTableError(fallbackMsg)) {
console.error(
`[gitnexus:embed] CodeEmbedding table not yet present — full embedding run (${fallbackMsg})`,
logger.info(
`[embed] CodeEmbedding table not yet present — full embedding run (${fallbackMsg})`,
);
return undefined;
}
@ -1063,6 +1065,9 @@ export const flushWAL = async (): Promise<void> => {
*/
export const safeClose = async (): Promise<void> => {
await flushWAL();
// Capture before close — currentDbPath stays set so the Windows post-close
// probe below knows which file to wait on.
const closingDbPath = currentDbPath;
if (conn) {
try {
// eslint-disable-next-line no-restricted-syntax -- sole authorised close site
@ -1081,6 +1086,24 @@ export const safeClose = async (): Promise<void> => {
}
db = null;
}
// Windows: libuv reports `db.close()` resolved before the kernel has
// released the file handle. A subsequent `new Database(samePath)` in
// the same process can race the release. The probe (lbug-config.ts)
// forces any residual lock to surface as EBUSY/EPERM/EACCES so the
// open-time retry absorbs the lag.
if (process.platform === 'win32' && closingDbPath) {
const released = await waitForWindowsHandleRelease(closingDbPath);
if (!released) {
// Probe exhausted with a lock code still in flight. The next
// openLbugConnection will absorb whatever residual lag remains, but
// a chronic warning helps operators spot AV interference (Windows
// Defender holding the file far past the 250ms budget).
logger.warn(
{ dbPath: closingDbPath },
'⚠️ LadybugDB file handle still locked after close (Windows). If this repeats, check antivirus/Defender exclusions for the GitNexus storage directory.',
);
}
}
};
export const closeLbug = async (): Promise<void> => {

266
gitnexus/src/core/lbug/lbug-config.ts
View file

@ -1,3 +1,6 @@
import fs from 'fs/promises';
import os from 'os';
import path from 'path';
import type lbug from '@ladybugdb/core';
/**
@ -42,10 +45,23 @@ export const LBUG_MAX_DB_SIZE: number = (() => {
return 16 * 1024 * 1024 * 1024;
})();
/** Matches WAL corruption errors from the LadybugDB engine. */
const WAL_CORRUPTION_RE = /corrupt(ed)?\s+wal|invalid\s+wal\s+record|wal.*corrupt|checksum.*wal/i;
export const WAL_RECOVERY_SUGGESTION =
'WAL corruption detected. Run `gitnexus analyze` to rebuild the index.';
export function isWalCorruptionError(err: unknown): boolean {
if (!err) return false;
const msg = err instanceof Error ? err.message : String(err);
return WAL_CORRUPTION_RE.test(msg);
}
type LbugModule = typeof lbug;
export interface LbugDatabaseOptions {
readOnly?: boolean;
throwOnWalReplayFailure?: boolean;
}
export interface LbugConnectionHandle {
@ -53,20 +69,200 @@ export interface LbugConnectionHandle {
conn: lbug.Connection;
}
/**
* Return true when the error message indicates that a LadybugDB file lock
* could not be acquired — either at construction time
* (`new lbug.Database(...)` raises from `local_file_system.cpp`) or during
* a query (another writer holds the exclusive lock).
*
* Lives here (not in `lbug-adapter.ts`) so both the construction-time
* retry (`openWithLockRetry` in this file) and the query-time retry
* (`withLbugDb` in `lbug-adapter.ts`) consult the same matcher. Callers
* import directly from this module — no re-export to keep in sync.
*/
export const isDbBusyError = (err: unknown): boolean => {
const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
// `lock` already subsumes `could not set lock`; the broader term is kept
// because graph-DB transient errors include "deadlock", "lock contention",
// and the LadybugDB native module's "could not set lock on file" — all of
// which deserve a retry. If a non-transient lock-shaped error ever
// surfaces (e.g., "lock file missing" during recovery), tighten this
// matcher rather than raising the retry budget.
return msg.includes('busy') || msg.includes('lock') || msg.includes('already in use');
};
export function createLbugDatabase(
lbugModule: LbugModule,
databasePath: string,
options: LbugDatabaseOptions = {},
): lbug.Database {
return new lbugModule.Database(
// .d.ts declares fewer args than the native constructor accepts.
return new (lbugModule.Database as any)(
databasePath,
0,
false,
0, // bufferManagerSize
false, // enableCompression (pinned for v0.16.0)
options.readOnly ?? false,
LBUG_MAX_DB_SIZE,
);
true, // autoCheckpoint
-1, // checkpointThreshold
options.throwOnWalReplayFailure ?? true,
true, // enableChecksums
) as lbug.Database;
}
// ─── Lock-busy retry tuning knobs ───────────────────────────────────────────
//
// All four GitNexus retry pairs that touch native LadybugDB locks live with
// a comment cross-reference here so an SRE tuning Windows flakes finds them
// in one grep:
//
// 1. OPEN_LOCK_RETRY_ATTEMPTS / OPEN_LOCK_RETRY_DELAY_MS (this file)
// → `new lbug.Database()` constructor lock failures
// 2. HANDLE_RELEASE_PROBE_ATTEMPTS / HANDLE_RELEASE_PROBE_DELAY_MS (this file)
// → post-close fs.open probe to absorb Windows handle-release lag
// 3. DB_LOCK_RETRY_ATTEMPTS / DB_LOCK_RETRY_DELAY_MS (lbug-adapter.ts withLbugDb)
// → query-time busy/lock retry around already-open connections
//
// `new lbug.Database()` calls into the native module which performs an
// OS-level exclusive lock on `<dbPath>`. On Windows that lock can fail
// for reasons specific to the OS (Defender briefly opens new files,
// libuv handle release lags the JS-side close). 5 attempts × 100ms
// linear back-off (max sleep 100+200+300+400 = 1s, plus 5 ctor RTTs
// of 10–50ms each = ~1.0–1.2s worst case) clears the typical
// AV-scanner hold without masking real cross-process conflicts.
//
// Source: https://github.com/LadybugDB/ladybug/blob/v0.16.1/src/common/file_system/local_file_system.cpp#L126
const OPEN_LOCK_RETRY_ATTEMPTS = 5;
const OPEN_LOCK_RETRY_DELAY_MS = 100;
const HANDLE_RELEASE_PROBE_ATTEMPTS = 5;
const HANDLE_RELEASE_PROBE_DELAY_MS = 50;
const HANDLE_RELEASE_LOCK_CODES = new Set(['EBUSY', 'EPERM', 'EACCES']);
/**
* Test-fixture directory prefixes recognized by `isTestFixturePath`.
*
* IMPORTANT: this list must stay in sync with the prefixes passed to
* `createTempDir` in `gitnexus/test/helpers/test-db.ts` and the prefixes
* used by `withTestLbugDB` (`gitnexus/test/helpers/test-indexed-db.ts`).
* If you add a new test that passes a custom prefix to `createTempDir`,
* add it here too — otherwise the stale-sidecar sweep silently won't
* fire for that fixture and CI flakes return.
*
* The default `createTempDir('gitnexus-test-')` and the lbug variant
* `'gitnexus-lbug-'` cover today's call sites.
*/
const TEST_FIXTURE_PREFIXES = ['gitnexus-lbug-', 'gitnexus-test-'];
/**
* Marker symbol attached to lock errors after `openWithLockRetry` exhausts
* its budget. `withLbugDb`'s outer query-time retry consults this so it
* does not re-retry a path that just spent up to ~1.5s in the open-time
* loop — preventing 6s tail latencies (3× outer × 5× inner attempts).
*
* The symbol is internal to GitNexus; consumers should treat the underlying
* error message as the user-visible signal.
*/
export const LBUG_OPEN_RETRY_EXHAUSTED = Symbol.for('gitnexus.lbug.openRetryExhausted');
export const isOpenRetryExhausted = (err: unknown): boolean => {
if (err === null || err === undefined || typeof err !== 'object') return false;
return (err as { [LBUG_OPEN_RETRY_EXHAUSTED]?: boolean })[LBUG_OPEN_RETRY_EXHAUSTED] === true;
};
const tagOpenRetryExhausted = (err: unknown): unknown => {
if (err && typeof err === 'object') {
(err as { [LBUG_OPEN_RETRY_EXHAUSTED]?: boolean })[LBUG_OPEN_RETRY_EXHAUSTED] = true;
}
return err;
};
/**
* True when `dbPath` resolves to a recognized test fixture under the OS
* temp directory. Used to gate the stale-sidecar sweep so production
* paths never have their `.wal` / `.lock` files deleted.
*
* Defensive shape:
* - `path.resolve` normalizes `..` segments before the prefix check, so
* `<tmp>/gitnexus-lbug-x/../../etc/passwd` is rejected.
* - The tmpRoot check trims any trailing separator returned by some
* Windows TMP configurations (`C:\Users\X\Temp\`) so the startsWith
* comparison stays correct.
* - Only the IMMEDIATE parent directory is matched against the prefix
* list. An ancestor walk would let a tmpdir whose own basename starts
* with `gitnexus-lbug-` accept arbitrary nested paths under it.
*/
const isTestFixturePath = (dbPath: string): boolean => {
const tmpRoot = os.tmpdir().replace(new RegExp(`${path.sep === '\\' ? '\\\\' : path.sep}+$`), '');
const resolved = path.resolve(dbPath);
if (!resolved.startsWith(tmpRoot + path.sep) && resolved !== tmpRoot) return false;
const parentBase = path.basename(path.dirname(resolved));
return TEST_FIXTURE_PREFIXES.some((p) => parentBase.startsWith(p));
};
/** Exported only for direct unit testing — production callers use `openWithLockRetry`. */
export const _isTestFixturePathForTest = isTestFixturePath;
const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
/**
* Attempt to remove stale `.wal` / `.lock` sidecars that a previous aborted
* test run may have left behind. Best-effort: ENOENT is normal, anything
* else is swallowed so the caller's retry can surface the original error.
*/
const sweepStaleSidecars = async (dbPath: string): Promise<void> => {
for (const suffix of ['.wal', '.lock']) {
try {
await fs.unlink(dbPath + suffix);
} catch {
/* missing sidecar or permission error — let the open retry surface it */
}
}
};
/**
* Run `construct` with bounded retries when `new lbug.Database(...)` throws
* a busy/lock error. The original (loop-captured) error is preferred over
* any post-sweep error so triage sees the real LadybugDB lock message.
* On exhaustion the rethrown error is tagged via
* `LBUG_OPEN_RETRY_EXHAUSTED` so the outer query-time retry in
* `withLbugDb` skips re-retrying a freshly-exhausted path.
*/
const openWithLockRetry = async (
construct: () => lbug.Database,
dbPath: string,
): Promise<lbug.Database> => {
let originalLockError: unknown;
for (let attempt = 1; attempt <= OPEN_LOCK_RETRY_ATTEMPTS; attempt++) {
try {
return construct();
} catch (err) {
if (!isDbBusyError(err)) throw err;
originalLockError = err;
if (attempt === OPEN_LOCK_RETRY_ATTEMPTS) break;
await sleep(OPEN_LOCK_RETRY_DELAY_MS * attempt);
}
}
// Final defense: only for recognized test fixtures, sweep stale sidecars
// (a prior aborted test run can leave a `.wal` lock that survives the
// tmp dir cleanup). Production paths never reach this branch — the guard
// requires the immediate parent dir to match a test prefix AND the
// resolved path to live under the OS temp directory.
if (isTestFixturePath(dbPath)) {
await sweepStaleSidecars(dbPath);
try {
return construct();
} catch {
// Intentionally do NOT overwrite originalLockError. The user-actionable
// signal is "we exhausted lock retries" — a different error from the
// post-sweep attempt is less useful than the lock failure that drove
// the sweep in the first place.
}
}
throw tagOpenRetryExhausted(originalLockError);
};
export async function openLbugConnection(
lbugModule: LbugModule,
databasePath: string,
@ -74,7 +270,10 @@ export async function openLbugConnection(
): Promise<LbugConnectionHandle> {
let db: lbug.Database | undefined;
try {
db = createLbugDatabase(lbugModule, databasePath, options);
db = await openWithLockRetry(
() => createLbugDatabase(lbugModule, databasePath, options),
databasePath,
);
return { db, conn: new lbugModule.Connection(db) };
} catch (err) {
if (db) await db.close().catch(() => {});
@ -86,3 +285,60 @@ export async function closeLbugConnection(handle: LbugConnectionHandle): Promise
await handle.conn.close().catch(() => {});
await handle.db.close().catch(() => {});
}
/**
* Probe `dbPath` AND its `.wal` sidecar after `db.close()` so any
* residual native file handle surfaces as EBUSY/EPERM/EACCES and the
* bounded retry absorbs the release lag. Windows-only — Linux/macOS do
* not exhibit this race.
*
* Both files matter. Empirically, on rapid open→close→reopen cycles the
* main `dbPath` handle releases first; the `.wal` handle from the
* previous Database lingers and the new Database's first write (CREATE
* NODE TABLE during schema init) fails with "Could not set lock on
* file". Probing both makes safeClose actually return when the kernel
* is fully done with the path.
*
* Returns `true` when both probes succeeded (or skipped on non-lock
* errors / missing files). Returns `false` when either probe exhausted
* its budget with a lock code still in flight.
*
* Defensive shape:
* - Opens read+write (`'r+'`) so the probe actually surfaces exclusive
* locks held by the previous Database. A read-only probe (`'r'`) is
* insufficient — Windows will grant read access while the previous
* handle's exclusive write lock is still in flight, which lets
* `safeClose` return before the next CREATE NODE TABLE can lock the
* file.
* - `try/finally` around `handle.close()` guarantees no fd leak even
* if close itself throws.
*/
export const waitForWindowsHandleRelease = async (dbPath: string): Promise<boolean> => {
const mainReleased = await probeSinglePath(dbPath);
const walReleased = await probeSinglePath(dbPath + '.wal');
return mainReleased && walReleased;
};
const probeSinglePath = async (filePath: string): Promise<boolean> => {
for (let attempt = 1; attempt <= HANDLE_RELEASE_PROBE_ATTEMPTS; attempt++) {
let handle: fs.FileHandle | undefined;
try {
handle = await fs.open(filePath, 'r+');
return true;
} catch (err) {
const code = (err as NodeJS.ErrnoException | undefined)?.code;
if (!code || !HANDLE_RELEASE_LOCK_CODES.has(code)) return true; // ENOENT / unrelated → not our problem
if (attempt === HANDLE_RELEASE_PROBE_ATTEMPTS) return false;
await sleep(HANDLE_RELEASE_PROBE_DELAY_MS * attempt);
} finally {
if (handle) {
try {
await handle.close();
} catch {
/* swallow — caller cannot do anything useful with a probe-close failure */
}
}
}
}
return false;
};

65
gitnexus/src/core/lbug/pool-adapter.ts
View file

@ -18,7 +18,7 @@
import fs from 'fs/promises';
import lbug from '@ladybugdb/core';
import { loadFTSExtension } from './lbug-adapter.js';
import { createLbugDatabase } from './lbug-config.js';
import { createLbugDatabase, isWalCorruptionError } from './lbug-config.js';
/** Per-repo pool: one Database, many Connections */
interface PoolEntry {
@ -97,7 +97,7 @@ let idleTimer: ReturnType<typeof setInterval> | null = null;
// @ladybugdb/core), corrupting stdout in the pre-sentinel window. Routing
// through the leaf breaks that chain.
export { realStdoutWrite, realStderrWrite, setActiveStdoutWrite } from '../../mcp/stdio-capture.js';
import { getActiveStdoutWrite } from '../../mcp/stdio-capture.js';
import { getActiveStdoutWrite, realStderrWrite } from '../../mcp/stdio-capture.js';
let stdoutSilenceCount = 0;
/** True while pre-warming connections — prevents watchdog from prematurely restoring stdout */
@ -263,6 +263,46 @@ const WAITER_TIMEOUT_MS = 15_000;
const LOCK_RETRY_ATTEMPTS = 3;
const LOCK_RETRY_DELAY_MS = 2000;
async function openReadOnlyDatabase(dbPath: string): Promise<lbug.Database> {
let db: lbug.Database | undefined;
silenceStdout();
try {
db = createLbugDatabase(lbug, dbPath, {
readOnly: true,
throwOnWalReplayFailure: false,
});
await db.init();
return db;
} catch (err) {
if (db) await db.close().catch(() => {});
throw err;
} finally {
restoreStdout();
}
}
/**
* Quarantine the .wal file and retry opening the database.
* Used when the initial open fails with a WAL corruption error.
*/
async function tryQuarantineAndReopen(dbPath: string, repoId: string): Promise<lbug.Database> {
const walPath = dbPath + '.wal';
const quarantineName = `${walPath}.corrupt.${Date.now()}-${Math.random().toString(36).slice(2)}`;
try {
await fs.rename(walPath, quarantineName);
} catch {
throw new Error(
`LadybugDB WAL corruption detected for ${repoId}. ` +
`Run \`gitnexus analyze\` to rebuild the index. (quarantine failed)`,
);
}
realStderrWrite(
`GitNexus: LadybugDB WAL quarantined for ${repoId}; graph may be stale. ` +
`Run \`gitnexus analyze\` to rebuild the index.\n`,
);
return await openReadOnlyDatabase(dbPath);
}
/** Deduplicates concurrent initLbug calls for the same repoId */
const initPromises = new Map<string, Promise<void>>();
@ -319,16 +359,29 @@ async function doInitLbug(repoId: string, dbPath: string): Promise<void> {
// avoids lock conflicts when `gitnexus analyze` is writing.
let lastError: Error | null = null;
for (let attempt = 1; attempt <= LOCK_RETRY_ATTEMPTS; attempt++) {
silenceStdout();
try {
const db = createLbugDatabase(lbug, dbPath, { readOnly: true });
restoreStdout();
const db = await openReadOnlyDatabase(dbPath);
shared = { db, refCount: 0, ftsLoaded: false };
dbCache.set(dbPath, shared);
break;
} catch (err: any) {
restoreStdout();
lastError = err instanceof Error ? err : new Error(String(err));
if (isWalCorruptionError(lastError)) {
try {
const db = await tryQuarantineAndReopen(dbPath, repoId);
shared = { db, refCount: 0, ftsLoaded: false };
dbCache.set(dbPath, shared);
break;
} catch (retryErr) {
throw new Error(
`LadybugDB WAL corruption detected for ${repoId}. ` +
`Run \`gitnexus analyze\` to rebuild the index. ` +
`(${retryErr instanceof Error ? retryErr.message : String(retryErr)})`,
);
}
}
const isLockError =
lastError.message.includes('Could not set lock') || lastError.message.includes('lock');
if (!isLockError || attempt === LOCK_RETRY_ATTEMPTS) break;

375
gitnexus/src/core/logger.ts Normal file
View file

@ -0,0 +1,375 @@
/**
* Centralized structured logger for GitNexus.
*
* Wraps `pino` so the rest of the codebase imports from one place. Pino's
* NDJSON output is structurally log-injection-resistant (CWE-117 / CodeQL
* `js/log-injection`): each record is a single JSON object on its own line,
* with all string field values JSON-escaped. This replaces hand-rolled
* sanitizers (see PR #1329 history) that had recurring edge-case gaps
* (undefined Error.message, U+2028/U+2029, ANSI/C0).
*
* Usage:
* import { logger, createLogger } from '../core/logger.js';
* logger.warn({ groupDir }, 'msg');
* const childLogger = createLogger('bridge-db', { debugEnvVar: 'GITNEXUS_DEBUG_BRIDGE' });
*
* Operator semantics:
* - Default level: 'info' (matches pino default; preserves visibility of
* existing `console.log` migrations)
* - When `opts.debugEnvVar` is set and that env var is truthy at
* createLogger time, that named child logs at level 'debug'
* - Output is NDJSON in production / CI / vitest. pino-pretty is used only
* when stdout is a TTY AND CI is unset AND VITEST is unset, so test
* and pipeline output stay parseable.
*
* Test capture:
* The exported `logger` singleton is a Proxy that forwards every call to a
* lazily-built pino instance. Tests use `_captureLogger()` to redirect that
* inner instance to a memory stream so they can assert on records the
* production code logged. See `gitnexus/test/unit/logger.test.ts` for the
* pattern.
*/
import pino, { type Logger, type LoggerOptions, type DestinationStream } from 'pino';
import { Writable } from 'node:stream';
import { createRequire } from 'node:module';
export interface CreateLoggerOptions {
/** When set, this env var (truthy at construction time) bumps level to 'debug'. */
debugEnvVar?: string;
/** Override destination stream — primarily for tests. */
destination?: DestinationStream;
}
function isTruthyEnv(value: string | undefined): boolean {
if (!value) return false;
const v = value.toLowerCase();
return v !== '' && v !== '0' && v !== 'false' && v !== 'no' && v !== 'off';
}
function shouldUsePretty(): boolean {
// Logger writes to stderr (fd 2) so CLI data on stdout (fd 1) stays clean.
// Pretty-print only when stderr is a TTY and not in CI/test environments.
return (
process.stderr.isTTY === true &&
!isTruthyEnv(process.env.CI) &&
!isTruthyEnv(process.env.VITEST)
);
}
/**
* Default pino destination — writes to stderr (fd 2) so CLI commands can
* keep stdout (fd 1) clean for tool data output (#324). Pino defaults to
* stdout; we override here.
*
* `sync: false` (SonicBoom buffered writes) so logger calls don't issue a
* blocking `write(2)` syscall on every record. Hot paths (parse-impl,
* ingestion phases, per-query backend calls) pay the cost without it.
*
* The buffered-write trade-off is record loss on hard exit. We mitigate via:
* - A `process.on('beforeExit')` hook below that calls `flushSync()` on
* normal exits.
* - The exported `flushLoggerSync()` helper, which entry-point shutdown
* handlers (SIGINT/SIGTERM) MUST call before `process.exit(N)` so
* in-flight buffered records still reach stderr.
* - `pino.final(...)` integration in `uncaughtException` / `unhandledRejection`
* handlers (see `gitnexus/src/cli/serve.ts` and `gitnexus/src/server/api.ts`).
*
* Skipped under `VITEST` so vitest's between-test cleanup doesn't fight
* `_captureLogger()`'s lifecycle. Tests use an in-memory destination via
* `_captureLogger()` and never reach this branch.
*/
let _dest: ReturnType<typeof pino.destination> | undefined;
function defaultDestination(): DestinationStream {
if (_dest) return _dest;
_dest = pino.destination({ dest: 2, sync: false });
return _dest;
}
/**
* Flush any buffered records on the default destination. Entry-point
* shutdown handlers (`SIGINT` / `SIGTERM`) MUST call this before
* `process.exit(N)` — otherwise async-buffered records are lost on hard
* exit. No-op when the destination hasn't been constructed yet (logger
* module imported but never emitted) or when called from `_captureLogger`
* test mode (tests use an in-memory destination).
*/
export function flushLoggerSync(): void {
if (!_dest) return;
try {
_dest.flushSync();
} catch {
// Defend against a destination that has already been closed (e.g.,
// double-flush on rapid shutdown). Losing the flush attempt is the
// correct trade-off vs. throwing during shutdown.
}
}
/**
* Idempotent registration: `process.on('beforeExit')` flushes the buffered
* destination before normal exit. Skipped under VITEST to avoid interfering
* with `_captureLogger()`'s lifecycle and vitest's per-worker cleanup.
*/
let _flushHookInstalled = false;
function installFlushHook(): void {
if (_flushHookInstalled) return;
if (isTruthyEnv(process.env.VITEST)) return;
_flushHookInstalled = true;
process.on('beforeExit', () => {
flushLoggerSync();
});
}
/**
* Probe whether `pino-pretty` is resolvable from this module. Cached for
* the lifetime of the process — the resolve cost only happens once, and
* the one-time stderr warning on miss only fires once.
*
* Production installs ship pino-pretty as a runtime dependency (see
* gitnexus/package.json). The probe is the safety net for `--omit=optional`,
* `--no-package-lock` style installs and for any environment where the
* module turns out to be missing for reasons we can't predict — pino's
* own transport-resolution path resolves the target lazily at FIRST log
* write, so without this probe a missing module would throw deep inside
* the pino call site rather than at logger construction.
*/
let _prettyAvailable: boolean | null = null;
const _require = createRequire(import.meta.url);
function isPrettyAvailable(): boolean {
if (_prettyAvailable !== null) return _prettyAvailable;
try {
_require.resolve('pino-pretty');
_prettyAvailable = true;
} catch {
_prettyAvailable = false;
// One-time stderr warning so operators learn why TTY output is plain
// NDJSON instead of pretty-printed. Use realStderrWrite-style direct
// write — going through `logger` here would recurse.
process.stderr.write(
'[gitnexus:logger] pino-pretty unavailable; falling back to NDJSON on stderr\n',
);
}
return _prettyAvailable;
}
/**
* @internal Test-only reset for the pino-pretty availability cache. Lets
* unit tests exercise both resolve outcomes within the same vitest worker.
*/
export function _resetPrettyAvailableCache(): void {
_prettyAvailable = null;
}
/**
* Build the pino-pretty transport options. Internal — exported only so unit
* tests can exercise the probe path without going through `shouldUsePretty()`
* (which is structurally false under vitest).
*/
export function _tryBuildPrettyTransport(): LoggerOptions['transport'] | undefined {
if (!isPrettyAvailable()) return undefined;
return {
target: 'pino-pretty',
options: {
// Route to stderr (fd 2) so pretty output doesn't contaminate
// CLI tool data on stdout (fd 1). pino-pretty's default is fd 1,
// which would interleave with `gitnexus query | jq` output.
destination: 2,
colorize: true,
translateTime: 'SYS:HH:MM:ss.l',
ignore: 'pid,hostname',
},
};
}
/**
* Pino accepts `'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace' | 'silent'`.
* Anything else is silently ignored at runtime; we narrow here so a typo in
* the env var produces the documented default rather than masking the issue.
*/
const PINO_LEVELS = new Set(['fatal', 'error', 'warn', 'info', 'debug', 'trace', 'silent']);
function resolveBaseLevel(): string {
const fromEnv = process.env.GITNEXUS_LOG_LEVEL;
if (fromEnv && PINO_LEVELS.has(fromEnv.toLowerCase())) {
return fromEnv.toLowerCase();
}
return 'info';
}
function buildBaseOptions(): LoggerOptions {
const opts: LoggerOptions = {
level: resolveBaseLevel(),
base: undefined,
};
if (shouldUsePretty()) {
const transport = _tryBuildPrettyTransport();
if (transport) opts.transport = transport;
}
return opts;
}
/**
* Create a named child logger. When `opts.destination` is provided it bypasses
* the default stdout sink (useful for test capture). When `opts.debugEnvVar` is
* set and truthy at call time, the child runs at 'debug' level.
*/
export function createLogger(name: string, opts?: CreateLoggerOptions): Logger {
const debugRequested = opts?.debugEnvVar ? isTruthyEnv(process.env[opts.debugEnvVar]) : false;
if (opts?.destination) {
return pino(
{ level: debugRequested ? 'debug' : 'info', base: undefined, name },
opts.destination,
);
}
const base = buildBaseOptions();
// When using a transport (pino-pretty), pino manages the destination
// internally and we cannot pass one explicitly. When transport is absent,
// route to stderr so stdout stays clean for CLI data output.
let root: Logger;
if (base.transport) {
root = pino({ ...base, level: debugRequested ? 'debug' : base.level });
} else {
root = pino({ ...base, level: debugRequested ? 'debug' : base.level }, defaultDestination());
// The default destination is buffered (`sync: false`); register the
// graceful-exit flush hook now that we know the destination will be
// used. Idempotent — runs at most once per process. Skipped under
// VITEST so test cleanup doesn't fight `_captureLogger`.
installFlushHook();
}
return root.child({ name });
}
/* ------------------------------------------------------------------ */
/* Default singleton (Proxy-backed for test capture) */
/* ------------------------------------------------------------------ */
let _activeDestination: DestinationStream | undefined;
let _cached: Logger | undefined;
function _getInner(): Logger {
if (_cached) return _cached;
// Always go through createLogger so future defaults (serializers, redaction,
// formatters) apply uniformly. The destination override is honored when set
// by `_captureLogger()` below.
_cached = createLogger(
'gitnexus',
_activeDestination ? { destination: _activeDestination } : undefined,
);
return _cached;
}
/**
* Default singleton logger (`name: 'gitnexus'`). Backed by a Proxy so test
* capture (`_captureLogger()`) can redirect output without breaking modules
* that already imported the singleton at module-load time.
*/
export const logger = new Proxy({} as Logger, {
get(_target, prop) {
const inner = _getInner();
// Reflect.get keeps symbol-keyed lookups (e.g. Symbol.toPrimitive) intact;
// a `prop as string` cast would silently coerce them to the wrong key.
const value = Reflect.get(inner as object, prop, inner);
if (typeof value === 'function') {
return (value as (...a: unknown[]) => unknown).bind(inner);
}
return value;
},
}) as Logger;
/**
* Shape of a parsed pino record. `level`, `time`, and `msg` are always
* present; `name` is set when emitted from a named child logger; arbitrary
* additional fields appear when callers pass a structured first arg.
*
* Exported so test helpers and downstream skills can type-narrow capture
* results without inline `Record<string, unknown>` casts.
*/
export interface PinoLogRecord {
level: number;
time: number;
msg: string;
name?: string;
[key: string]: unknown;
}
/**
* In-memory Writable used by `_captureLogger()` and by tests that build
* their own pino destination. Exported so the shape lives in one place
* (previously duplicated between this module and `logger.test.ts`).
*
* `text()` and `records()` are convenience helpers test code calls. They
* don't appear in production hot paths — only test destinations capture
* here — so the surface is intentionally small.
*/
export class MemoryWritable extends Writable {
chunks: string[] = [];
_write(chunk: Buffer | string, _enc: BufferEncoding, cb: (err?: Error | null) => void): void {
this.chunks.push(typeof chunk === 'string' ? chunk : chunk.toString('utf-8'));
cb();
}
/** Concatenate every captured write back into a single string. */
text(): string {
return this.chunks.join('');
}
/** Parse captured writes as one NDJSON record per non-empty line. */
records(): PinoLogRecord[] {
return this.text()
.split('\n')
.filter((l) => l.length > 0)
.map((l) => JSON.parse(l) as PinoLogRecord);
}
}
export interface LoggerCapture {
records(): PinoLogRecord[];
text(): string;
restore(): void;
}
/**
* Test helper. Redirects the default `logger` singleton to an in-memory
* stream and returns a capture object plus a restore function.
*
* Pattern:
* let cap: LoggerCapture;
* beforeEach(() => { cap = _captureLogger(); });
* afterEach(() => { cap.restore(); });
* it('warns', () => {
* fnUnderTest();
* expect(cap.records().some(r => r.msg?.includes('clamping'))).toBe(true);
* });
*
* Not a public API; underscore-prefixed and called only from test code.
* Throws if a previous capture is still active — see the body for context.
*/
export function _captureLogger(): LoggerCapture {
// Guard against double-capture: forgetting `restore()` between two
// `_captureLogger()` calls silently abandoned the previous capture and
// corrupted logger state for the rest of the vitest worker. Throwing here
// surfaces the bug at the moment of misuse instead of as inscrutable
// missing-records assertions in unrelated tests.
if (_activeDestination !== undefined) {
throw new Error(
'_captureLogger: a previous capture is still active — call restore() before starting a new one.',
);
}
const w = new MemoryWritable();
_activeDestination = w;
_cached = undefined;
return {
records: () =>
w.chunks
.join('')
.split('\n')
.filter((l) => l.length > 0)
.map((l) => JSON.parse(l) as PinoLogRecord),
text: () => w.chunks.join(''),
restore: () => {
_activeDestination = undefined;
_cached = undefined;
},
};
}

13
gitnexus/src/core/tree-sitter/parser-loader.ts
View file

@ -2,6 +2,7 @@ import Parser from 'tree-sitter';
import { createRequire } from 'node:module';
import { SupportedLanguages } from 'gitnexus-shared';
import { logger } from '../logger.js';
const _require = createRequire(import.meta.url);
/**
@ -175,10 +176,14 @@ const logFailure = (key: string, result: LoadResult): void => {
logged.add(key);
const message = `[gitnexus] ${result.note} (${result.error.message})`;
// Both severities go to stderr — console.warn writes to stderr too, but
// console.error is the stdout-safe channel we standardize on across
// MCP-reachable code so the ESLint rule covers this directory.
console.error(message);
// Severity routes to the correct pino level. Both go to stderr (pino's
// default destination), so MCP stdio framing is preserved either way —
// the level tag drives log filtering, not channel selection.
if (result.severity === 'error') {
logger.error(message);
} else {
logger.warn(message);
}
};
export const resolveLanguageKey = (language: SupportedLanguages, filePath?: string): string =>

3
gitnexus/src/core/wiki/cursor-client.ts
View file

@ -10,6 +10,7 @@
import { spawn, execSync } from 'child_process';
import type { LLMResponse, CallLLMOptions } from './llm-client.js';
import { logger } from '../logger.js';
export interface CursorConfig {
model?: string;
workingDirectory?: string;
@ -21,7 +22,7 @@ function isVerbose(): boolean {
function verboseLog(...args: unknown[]): void {
if (isVerbose()) {
console.log('[cursor-cli]', ...args);
logger.info({ args }, '[cursor-cli]');
}
}

9
gitnexus/src/core/wiki/llm-client.ts
View file

@ -1,3 +1,4 @@
import { logger } from '../logger.js';
/**
* LLM Client for Wiki Generation
*
@ -85,8 +86,10 @@ export function isAzureProvider(baseUrl: string): boolean {
const { hostname } = new URL(baseUrl);
return hostname.endsWith('.openai.azure.com') || hostname.endsWith('.services.ai.azure.com');
} catch {
// If URL is malformed, fall back to substring check
return baseUrl.includes('.openai.azure.com') || baseUrl.includes('.services.ai.azure.com');
// Malformed URL — refuse to call this Azure rather than fall back to a
// substring check, which is bypassable by `https://evil.com/?u=.openai.azure.com`
// (CodeQL js/incomplete-url-substring-sanitization).
return false;
}
}
@ -135,7 +138,7 @@ export async function callLLM(
// Warn when using Azure legacy deployment URL without api-version
if (azure && !config.apiVersion && config.baseUrl.includes('/deployments/')) {
console.warn(
logger.warn(
'[gitnexus] Warning: Azure legacy deployment URL detected but no api-version set. Add --api-version 2024-10-21 or use the v1 API format.',
);
}

49
gitnexus/src/mcp/core/embedder.ts
View file

@ -12,9 +12,14 @@ import {
httpEmbedQuery,
} from '../../core/embeddings/http-client.js';
import { resolveEmbeddingConfig } from '../../core/embeddings/config.js';
import { applyHfEnvOverrides } from '../../core/embeddings/hf-env.js';
import {
applyHfEnvOverrides,
isHfDownloadFailure,
withHfDownloadRetry,
} from '../../core/embeddings/hf-env.js';
import { silenceStdout, restoreStdout, realStderrWrite } from '../../core/lbug/pool-adapter.js';
import { logger } from '../../core/logger.js';
// Model config
const MODEL_ID = 'Snowflake/snowflake-arctic-embed-xs';
@ -51,7 +56,7 @@ export const initEmbedder = async (): Promise<FeatureExtractionPipeline> => {
applyHfEnvOverrides(env);
const embeddingConfig = resolveEmbeddingConfig();
console.error('GitNexus: Loading embedding model (first search may take a moment)...');
logger.info('GitNexus: Loading embedding model (first search may take a moment)...');
const devicesToTry: Array<'dml' | 'cuda' | 'cpu'> =
embeddingConfig.device === 'dml' || embeddingConfig.device === 'cuda'
@ -68,23 +73,39 @@ export const initEmbedder = async (): Promise<FeatureExtractionPipeline> => {
silenceStdout();
process.stderr.write = (() => true) as any;
try {
embedderInstance = await (pipeline as any)('feature-extraction', MODEL_ID, {
device: device,
dtype: 'fp32',
session_options: {
logSeverityLevel: 3,
intraOpNumThreads: embeddingConfig.threads,
interOpNumThreads: 1,
executionMode: 'sequential',
},
});
embedderInstance = await withHfDownloadRetry(() =>
pipeline('feature-extraction', MODEL_ID, {
device: device,
dtype: 'fp32',
session_options: {
logSeverityLevel: 3,
intraOpNumThreads: embeddingConfig.threads,
interOpNumThreads: 1,
executionMode: 'sequential',
},
}),
);
} finally {
restoreStdout();
process.stderr.write = realStderrWrite;
}
console.error(`GitNexus: Embedding model loaded (${device})`);
logger.info({ device }, 'GitNexus: Embedding model loaded');
return embedderInstance!;
} catch {
} catch (deviceError) {
// Network errors and circuit-open errors are not device-specific —
// they will fail the same way on every device. Rethrow immediately
// with actionable HF_ENDPOINT guidance rather than silently falling
// back to the next device.
const errMsg = deviceError instanceof Error ? deviceError.message : String(deviceError);
if (isHfDownloadFailure(errMsg)) {
const endpointHint = process.env.HF_ENDPOINT
? `The configured endpoint (${process.env.HF_ENDPOINT}) may be unreachable.`
: `huggingface.co may be unreachable from your network.\n` +
` Set HF_ENDPOINT to a mirror and retry:\n` +
` HF_ENDPOINT=https://hf-mirror.com npx gitnexus analyze --embeddings\n` +
` (Windows: set HF_ENDPOINT=https://hf-mirror.com && npx gitnexus analyze --embeddings)`;
throw new Error(`Failed to download embedding model: ${errMsg}\n ${endpointHint}`);
}
if (device === 'cpu') throw new Error('Failed to load embedding model');
}
}

92
gitnexus/src/mcp/local/local-backend.ts
View file

@ -16,6 +16,7 @@ import {
isLbugReady,
isWriteQuery,
} from '../../core/lbug/pool-adapter.js';
import { isWalCorruptionError, WAL_RECOVERY_SUGGESTION } from '../../core/lbug/lbug-config.js';
export { isWriteQuery };
// Embedding imports are lazy (dynamic import) to avoid loading onnxruntime-node
// at MCP server startup — crashes on unsupported Node ABI versions (#89)
@ -40,7 +41,8 @@ import {
isVectorExtensionSupportedByPlatform,
} from '../../core/platform/capabilities.js';
import { PhaseTimer } from '../../core/search/phase-timer.js';
import { checkStaleness, checkCwdMatch } from '../../core/git-staleness.js';
import { checkStalenessAsync, checkCwdMatch } from '../../core/git-staleness.js';
import { logger } from '../../core/logger.js';
// AI context generation is CLI-only (gitnexus analyze)
// import { generateAIContextFiles } from '../../cli/ai-context.js';
@ -164,29 +166,27 @@ const confidenceForRelType = (relType: string | undefined): number =>
/** Structured error logging for query failures — replaces empty catch blocks */
function logQueryError(context: string, err: unknown): void {
const msg = err instanceof Error ? err.message : String(err);
console.error(`GitNexus [${context}]: ${msg}`);
logger.error({ context, err: msg }, 'GitNexus query failed');
}
/**
* Structured per-query latency log for production aggregation (#553).
* Per-query latency telemetry for production aggregation (#553).
*
* Emitted on stderr — NOT stdout — because the MCP stdio transport uses
* stdout exclusively for JSON-RPC responses (#324), and the CLI e2e test
* `tool output goes to stdout via fd 1` asserts that stdout parses cleanly
* as JSON. Any `console.log` from inside a tool handler would corrupt the
* protocol. Matches the existing `logQueryError` convention above, which
* uses stderr for the same reason.
* Logged at `debug` level — timing is observability/telemetry, not an
* error. Operators wanting per-query timing set `GITNEXUS_LOG_LEVEL=debug`
* (or equivalent). Emitting at `error` level (the original migration
* artifact) caused alerting rules to fire on every successful query and
* inflated stderr noise for every MCP/CLI invocation.
*
* The `GitNexus [query:timing] …` prefix keeps lines greppable; the
* `phases` payload is JSON so log-scraping pipelines can parse it
* without custom format knowledge.
* Emitted via the project logger which routes to stderr — never stdout —
* because the MCP stdio transport uses stdout exclusively for JSON-RPC
* responses (#324) and the CLI e2e test `tool output goes to stdout via
* fd 1` asserts stdout parses cleanly as JSON.
*/
function logQueryTiming(query: string, phases: Record<string, number>): void {
const totalMs = phases.wall ?? Object.values(phases).reduce((a, b) => a + b, 0);
const truncated = query.length > 80 ? `${query.slice(0, 80)}…` : query;
console.error(
`GitNexus [query:timing] query=${JSON.stringify(truncated)} totalMs=${totalMs} phases=${JSON.stringify(phases)}`,
);
logger.debug({ query: truncated, totalMs, phases }, 'GitNexus query timing');
}
export interface CodebaseContext {
@ -287,7 +287,7 @@ export class LocalBackend {
// If kuzu exists but lbug doesn't, warn so the user knows to re-analyze.
const kuzu = await cleanupOldKuzuFiles(storagePath);
if (kuzu.found && kuzu.needsReindex) {
console.error(
logger.error(
`GitNexus: "${entry.name}" has a stale KuzuDB index. Run: gitnexus analyze ${entry.path}`,
);
}
@ -555,8 +555,15 @@ export class LocalBackend {
byRemote.set(h.remoteUrl, list);
}
return handles.map((h) => {
const stale = checkStaleness(h.repoPath, h.lastCommit);
// Check staleness for all repos in parallel instead of sequentially.
// Each check spawns an async `git rev-list` — with 200 repos the sync
// variant took ~50 s; parallel async brings it under a second (#1363).
const stalenessResults = await Promise.all(
handles.map((h) => checkStalenessAsync(h.repoPath, h.lastCommit)),
);
return handles.map((h, i) => {
const stale = stalenessResults[i];
const selfNorm = norm(h.repoPath);
const siblings = h.remoteUrl
? (byRemote.get(h.remoteUrl) ?? []).filter((e) => norm(e.repoPath) !== selfNorm)
@ -637,7 +644,7 @@ export class LocalBackend {
}
this.warnedSiblingDrift.add(cacheKey);
console.error(`GitNexus: ${match.hint}`);
logger.error(`GitNexus: ${match.hint}`);
}
// ─── Tool Dispatch ───────────────────────────────────────────────
@ -990,7 +997,10 @@ export class LocalBackend {
try {
bm25Results = await searchFTSFromLbug(query, limit, repo.id);
} catch (err: any) {
console.error('GitNexus: BM25/FTS search failed (FTS indexes may not exist) -', err.message);
logger.error(
{ err: err.message },
'GitNexus: BM25/FTS search failed (FTS indexes may not exist) -',
);
return { results: [], ftsUsed: false };
}
@ -1114,7 +1124,7 @@ export class LocalBackend {
// policy. Emitted once per `LocalBackend` instance lifetime to avoid
// noisy stderr on hot semantic-search paths (DoD §2.8).
this.warnedVectorUnsupported = true;
console.error(
logger.warn(
'GitNexus [query:vector]: VECTOR extension not supported on this platform; using exact scan fallback',
);
}
@ -1216,7 +1226,14 @@ export class LocalBackend {
const result = await executeQuery(repo.id, params.query);
return result;
} catch (err: any) {
return { error: err.message || 'Query failed' };
const msg = err.message || 'Query failed';
if (isWalCorruptionError(err)) {
return {
error: msg,
recoverySuggestion: WAL_RECOVERY_SUGGESTION,
};
}
return { error: msg };
}
}
@ -1670,6 +1687,30 @@ export class LocalBackend {
kind?: string;
include_content?: boolean;
},
): Promise<any> {
try {
return await this._contextImpl(repo, params);
} catch (err: any) {
const msg = (err instanceof Error ? err.message : String(err)) || 'Context query failed';
if (isWalCorruptionError(err)) {
return {
error: msg,
recoverySuggestion: WAL_RECOVERY_SUGGESTION,
};
}
throw err;
}
}
private async _contextImpl(
repo: RepoHandle,
params: {
name?: string;
uid?: string;
file_path?: string;
kind?: string;
include_content?: boolean;
},
): Promise<any> {
await this.ensureInitialized(repo.id);
@ -2431,6 +2472,7 @@ export class LocalBackend {
impactedCount: 0,
risk: 'UNKNOWN',
suggestion: 'The graph query failed — try gitnexus context <symbol> as a fallback',
...(isWalCorruptionError(err) ? { recoverySuggestion: WAL_RECOVERY_SUGGESTION } : {}),
};
}
}
@ -2982,8 +3024,14 @@ export class LocalBackend {
relationTypes: string[];
minConfidence: number;
includeTests: boolean;
signal?: AbortSignal;
},
): Promise<any | null> {
// Honor an already-aborted signal at the entry boundary as a fast
// path. Cooperative cancellation inside _runImpactBFS is out of
// scope — the caller's Promise.race against the same signal
// resolves the await regardless of how long this body runs.
if (opts.signal?.aborted) return null;
try {
await this.refreshRepos();
await this.ensureInitialized(repoId);

8
gitnexus/src/mcp/server.ts
View file

@ -312,7 +312,11 @@ export async function startMCPServer(backend: LocalBackend): Promise<void> {
// stray writes even when individual payloads were truncated/suppressed.
process.on('exit', () => sentinel.flushSummary());
// Graceful shutdown helper
// Graceful shutdown helper. Pino's default destination is `sync: false`
// (buffered), so we must `flushLoggerSync()` before `process.exit` —
// otherwise records emitted during disconnect/close are lost. The flush
// is a no-op when the singleton was never used or when running under
// vitest. See `gitnexus/src/core/logger.ts`.
let shuttingDown = false;
const shutdown = async (exitCode = 0) => {
if (shuttingDown) return;
@ -323,6 +327,8 @@ export async function startMCPServer(backend: LocalBackend): Promise<void> {
try {
await server.close();
} catch {}
const { flushLoggerSync } = await import('../core/logger.js');
flushLoggerSync();
process.exit(exitCode);
};

34
gitnexus/src/server/api.ts
View file

@ -27,8 +27,6 @@ import { isWriteQuery } from '../core/lbug/pool-adapter.js';
import { NODE_TABLES, type GraphNode, type GraphRelationship } from 'gitnexus-shared';
import { searchFTSFromLbug } from '../core/search/bm25-index.js';
import { hybridSearch } from '../core/search/hybrid-search.js';
// Embedding imports are lazy (dynamic import) to avoid loading onnxruntime-node
// at server startup — crashes on unsupported Node ABI versions (#89)
import { LocalBackend } from '../mcp/local/local-backend.js';
import { mountMCPEndpoints } from './mcp-http.js';
import { fork } from 'child_process';
@ -36,6 +34,7 @@ import { fileURLToPath, pathToFileURL } from 'url';
import { JobManager } from './analyze-job.js';
import { assertString, escapeRegExp, BadRequestError, createRouteLimiter } from './validation.js';
import { extractRepoName, getCloneDir, cloneOrPull } from './git-clone.js';
import { logger, flushLoggerSync } from '../core/logger.js';
const _require = createRequire(import.meta.url);
const pkg = _require('../../package.json');
@ -143,7 +142,7 @@ export const resolveWebDistDir = async (
return dir;
} catch (err: any) {
if (err?.code !== 'ENOENT') {
console.warn(`[serve] could not access web UI dir ${dir}:`, err.message);
logger.warn({ err: err.message }, `[serve] could not access web UI dir ${dir}:`);
}
}
}
@ -1490,7 +1489,7 @@ export const createServer = async (port: number, host: string = '127.0.0.1') =>
});
})
.catch((err) => {
console.error('backend.init() failed after analyze:', err);
logger.error({ err }, 'backend.init() failed after analyze:');
jobManager.updateJob(job.id, {
status: 'failed',
error: 'Server failed to reload after analysis. Try again.',
@ -1522,7 +1521,7 @@ export const createServer = async (port: number, host: string = '127.0.0.1') =>
j.retryCount++;
const delay = 1000 * Math.pow(2, j.retryCount - 1); // 1s, 2s
const lastErr = stderrChunks.trim().split('\n').pop() || '';
console.warn(
logger.warn(
`Analyze worker crashed (code ${code}), retry ${j.retryCount}/${MAX_WORKER_RETRIES} in ${delay}ms` +
(lastErr ? `: ${lastErr}` : ''),
);
@ -1790,7 +1789,7 @@ export const createServer = async (port: number, host: string = '127.0.0.1') =>
// Global error handler — catch anything the route handlers miss
app.use((err: any, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
console.error('Unhandled error:', err);
logger.error({ err }, 'Unhandled error:');
res.status(500).json({ error: 'Internal server error' });
});
@ -1804,7 +1803,9 @@ export const createServer = async (port: number, host: string = '127.0.0.1') =>
});
server.on('error', (err) => reject(err));
// Graceful shutdown — close Express + LadybugDB cleanly
// Graceful shutdown — close Express + LadybugDB cleanly. Pino's default
// destination is `sync: false` (buffered); `flushLoggerSync()` before
// `process.exit` so records emitted during cleanup reach stderr.
const shutdown = async () => {
console.log('\nShutting down...');
server.close();
@ -1813,22 +1814,33 @@ export const createServer = async (port: number, host: string = '127.0.0.1') =>
await cleanupMcp();
await closeLbug();
await backend.disconnect();
const { flushLoggerSync } = await import('../core/logger.js');
flushLoggerSync();
process.exit(0);
};
process.once('SIGINT', shutdown);
process.once('SIGTERM', shutdown);
// Catch-all crash guards (mirrors startMCPServer in mcp/server.ts)
// Catch-all crash guards (mirrors startMCPServer in mcp/server.ts).
// Pino v10's default destination is buffered (`sync: false`) — call
// `flushLoggerSync()` after logging and before triggering shutdown
// so the crash record reaches stderr regardless of how cleanup goes.
// Worker-thread transports (pino-pretty under TTY) handle their own
// flush on process exit in v10. `pino.final` was removed in v10
// because the new transport architecture made it unnecessary.
let shuttingDown = false;
process.on('uncaughtException', (err) => {
console.error('GitNexus uncaughtException:', err?.stack || err);
logger.error({ err }, 'GitNexus uncaughtException');
flushLoggerSync();
if (!shuttingDown) {
shuttingDown = true;
shutdown().catch(() => {});
}
});
process.on('unhandledRejection', (reason: any) => {
console.error('GitNexus unhandledRejection:', reason?.stack || reason);
process.on('unhandledRejection', (reason: unknown) => {
// Availability-first: log the rejection without exiting.
const err = reason instanceof Error ? reason : new Error(String(reason));
logger.error({ err }, 'GitNexus unhandledRejection');
});
});
};

3
gitnexus/src/server/git-clone.ts
View file

@ -10,6 +10,7 @@ import path from 'path';
import os from 'os';
import fs from 'fs/promises';
import { isIP } from 'net';
import { logger } from '../core/logger.js';
/** Root directory for all cloned repositories. Targets must resolve inside this. */
const CLONE_ROOT = path.resolve(path.join(os.homedir(), '.gitnexus', 'repos'));
@ -446,7 +447,7 @@ function runGit(args: string[], cwd?: string): Promise<void> {
if (code === 0) resolve();
else {
// Log full stderr internally but don't expose it to API callers (SSRF mitigation)
if (stderr.trim()) console.error(`git ${args[0]} stderr: ${stderr.trim()}`);
if (stderr.trim()) logger.error(`git ${args[0]} stderr: ${stderr.trim()}`);
reject(new Error(`git ${args[0]} failed (exit code ${code})`));
}
});

3
gitnexus/src/server/mcp-http.ts
View file

@ -15,6 +15,7 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { createMCPServer } from '../mcp/server.js';
import type { LocalBackend } from '../mcp/local/local-backend.js';
import { randomUUID } from 'crypto';
import { logger } from '../core/logger.js';
interface MCPSession {
server: Server;
@ -87,7 +88,7 @@ export function mountMCPEndpoints(app: Express, backend: LocalBackend): () => Pr
app.all('/api/mcp', (req: Request, res: Response) => {
void handleMcpRequest(req, res).catch((err: any) => {
console.error('MCP HTTP request failed:', err);
logger.error({ err }, 'MCP HTTP request failed:');
if (res.headersSent) return;
res.status(500).json({
jsonrpc: '2.0',

7
gitnexus/test/helpers/test-db.ts
View file

@ -37,6 +37,13 @@ export async function cleanupTempDir(tmpDir: string): Promise<void> {
/**
* Create a temporary directory for LadybugDB tests.
* Returns the path and a cleanup function.
*
* IMPORTANT: when adding a new test that passes a custom `prefix`, also add
* the prefix to `TEST_FIXTURE_PREFIXES` in
* `gitnexus/src/core/lbug/lbug-config.ts`. The stale-sidecar sweep relies
* on the prefix list to recognize test fixtures; an unknown prefix means
* the sweep silently won't fire for that fixture and Windows CI flakes
* return.
*/
export async function createTempDir(prefix: string = 'gitnexus-test-'): Promise<TestDBHandle> {
const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), prefix));

122
gitnexus/test/integration/cli/tool-no-index-stderr.test.ts Normal file
View file

@ -0,0 +1,122 @@
/**
* Regression test for the buffered-pino + hard-exit diagnostic-loss bug
* (Codex adversarial review on PR #1336, plan 002).
*
* Symptom before the fix: `gitnexus tool query <foo>` with no indexed
* repos exits non-zero with EMPTY stderr — the `logger.error()` call was
* routed through pino's `sync: false` SonicBoom buffer, and the
* subsequent synchronous `process.exit(1)` killed the process before the
* buffer could drain. Operators saw a silent failure.
*
* The fix routes user-facing CLI diagnostics through `cliError` (in
* `gitnexus/src/cli/cli-message.ts`), which writes plain text directly
* to `process.stderr` AND tees a structured pino record. Direct stderr
* writes don't go through the buffer, so they survive `process.exit`.
*
* This test spawns the built CLI in a child process and asserts the
* diagnostic line reaches stderr before exit. Without the fix it fails;
* with the fix it passes. Characterization-first contract, locked in
* end-to-end against `dist/`.
*/
import { describe, it, expect } from 'vitest';
import { spawn } from 'node:child_process';
import path from 'node:path';
import fs from 'node:fs';
import os from 'node:os';
import { fileURLToPath } from 'node:url';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
const DIST_CLI = path.join(REPO_ROOT, 'dist', 'cli', 'index.js');
const CHILD_TIMEOUT_MS = process.env.CI ? 20_000 : 10_000;
interface ChildResult {
exitCode: number | null;
stdout: string;
stderr: string;
}
/**
* Spawn the built `gitnexus` CLI with arguments, wait for exit, and
* return captured streams + exit code. Pin GITNEXUS_HOME to a fresh
* empty temp dir so the LocalBackend init reliably finds zero indexed
* repos. Force NODE_OPTIONS empty to prevent host-environment overrides
* from changing buffer / heap behavior (plan 001 U3 added the buffered
* destination, which is what this test guards against).
*/
function runCli(args: string[]): Promise<ChildResult> {
const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'gitnexus-cli-no-index-'));
return new Promise<ChildResult>((resolve, reject) => {
const proc = spawn(process.execPath, [DIST_CLI, ...args], {
cwd: REPO_ROOT,
env: {
...process.env,
GITNEXUS_HOME: tmpHome,
NODE_OPTIONS: '',
// Force NDJSON path: pino-pretty only activates when stderr is a
// TTY and !CI && !VITEST. spawn() pipes stderr, so it's not a
// TTY in this child anyway, but the explicit env is defense-in-depth.
CI: '1',
},
stdio: ['pipe', 'pipe', 'pipe'],
});
const stdoutChunks: Buffer[] = [];
const stderrChunks: Buffer[] = [];
proc.stdout.on('data', (chunk: Buffer) => stdoutChunks.push(chunk));
proc.stderr.on('data', (chunk: Buffer) => stderrChunks.push(chunk));
const timer = setTimeout(() => {
proc.kill('SIGKILL');
reject(new Error(`child process exceeded ${CHILD_TIMEOUT_MS}ms timeout`));
}, CHILD_TIMEOUT_MS);
proc.on('close', (code) => {
clearTimeout(timer);
// Best-effort cleanup of the empty temp home; ignore errors so they
// don't mask test failures.
try {
fs.rmSync(tmpHome, { recursive: true, force: true });
} catch {
/* ignore */
}
resolve({
exitCode: code,
stdout: Buffer.concat(stdoutChunks).toString('utf8'),
stderr: Buffer.concat(stderrChunks).toString('utf8'),
});
});
proc.on('error', (err) => {
clearTimeout(timer);
reject(err);
});
});
}
describe('CLI tool query — diagnostic survives hard exit (plan 002)', () => {
it('emits the no-index diagnostic to stderr before exit code 1', async () => {
if (!fs.existsSync(DIST_CLI)) {
throw new Error(
`dist/cli/index.js missing — run \`npm run build\` first (or use \`npm run test:integration\` which builds via pretest:integration).`,
);
}
const result = await runCli(['query', 'whatever']);
// Without the plan-002 fix, stderr was empty. The diagnostic must be
// visible regardless of how `process.exit(1)` interacts with the
// buffered pino destination.
expect(result.stderr).toContain('No indexed repositories found');
expect(result.stderr).toContain('gitnexus analyze');
// Exit code stays 1 — we're only changing the message channel, not
// the failure semantics.
expect(result.exitCode).toBe(1);
// Stdout should not carry the diagnostic. CLI tool data is reserved
// for stdout (e.g., `gitnexus query | jq`); diagnostics are stderr.
expect(result.stdout).not.toContain('No indexed repositories found');
}, 30_000);
});

23
gitnexus/test/integration/filesystem-walker.test.ts
View file

@ -8,6 +8,7 @@ import {
} from '../../src/core/ingestion/filesystem-walker.js';
import { _resetMaxFileSizeWarnings } from '../../src/core/ingestion/utils/max-file-size.js';
import { _captureLogger } from '../../src/core/logger.js';
describe('filesystem-walker', () => {
let tmpDir: string;
@ -328,7 +329,7 @@ describe('filesystem-walker', () => {
const BIG_FILE = 'src/big.ts';
const BIG_FILE_BYTES = 600 * 1024;
const ORIGINAL_ENV = process.env.GITNEXUS_MAX_FILE_SIZE;
let warnSpy: ReturnType<typeof vi.spyOn>;
let cap: ReturnType<typeof _captureLogger>;
beforeAll(async () => {
sizeDir = await fs.mkdtemp(path.join(os.tmpdir(), 'gn-walker-size-test-'));
@ -344,7 +345,7 @@ describe('filesystem-walker', () => {
beforeEach(() => {
delete process.env.GITNEXUS_MAX_FILE_SIZE;
_resetMaxFileSizeWarnings();
warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
cap = _captureLogger();
});
afterEach(() => {
@ -353,7 +354,7 @@ describe('filesystem-walker', () => {
} else {
process.env.GITNEXUS_MAX_FILE_SIZE = ORIGINAL_ENV;
}
warnSpy.mockRestore();
cap.restore();
});
it('skips a 600KB file by default', async () => {
@ -375,27 +376,27 @@ describe('filesystem-walker', () => {
const files = await walkRepositoryPaths(sizeDir);
const paths = files.map((f) => f.path.replace(/\\/g, '/'));
expect(paths).not.toContain(BIG_FILE);
const invalidWarnings = warnSpy.mock.calls.filter((c) =>
String(c[0]).includes('must be a positive integer'),
);
const invalidWarnings = cap
.records()
.filter((r) => String(r.msg ?? '').includes('must be a positive integer'));
expect(invalidWarnings).toHaveLength(1);
});
it('omits the "generated/vendored" suffix when threshold is overridden', async () => {
process.env.GITNEXUS_MAX_FILE_SIZE = '1';
await walkRepositoryPaths(sizeDir);
const skipWarnings = warnSpy.mock.calls.filter((c) => String(c[0]).includes('Skipped '));
const skipWarnings = cap.records().filter((r) => String(r.msg ?? '').includes('Skipped '));
expect(skipWarnings.length).toBeGreaterThan(0);
for (const call of skipWarnings) {
expect(String(call[0])).not.toContain('generated/vendored');
for (const r of skipWarnings) {
expect(String(r.msg ?? '')).not.toContain('generated/vendored');
}
});
it('keeps the "generated/vendored" suffix under the default threshold', async () => {
await walkRepositoryPaths(sizeDir);
const skipWarnings = warnSpy.mock.calls.filter((c) => String(c[0]).includes('Skipped '));
const skipWarnings = cap.records().filter((r) => String(r.msg ?? '').includes('Skipped '));
expect(skipWarnings.length).toBeGreaterThan(0);
expect(String(skipWarnings[0][0])).toContain('generated/vendored');
expect(String(skipWarnings[0].msg ?? '')).toContain('generated/vendored');
});
});
});

41
gitnexus/test/integration/lbug-close-handle-release.test.ts Normal file
View file

@ -0,0 +1,41 @@
/**
* Integration test: safeClose's Windows post-close handle-release wait.
*
* On Windows, libuv reports `db.close()` resolved before the kernel has
* released the file handle. A subsequent open of the same path can then
* race the release and surface "Could not set lock on file". `safeClose`
* probes the file with `fs.open` to force the residual lock to surface,
* absorbed by the open-time retry in `lbug-config.ts`.
*/
import path from 'path';
import { describe, it } from 'vitest';
import { createTempDir } from '../helpers/test-db.js';
describe('safeClose — close + reopen does not surface lock errors', () => {
it('survives 10 sequential open/close/reopen cycles on the same path', async () => {
const tmp = await createTempDir('gitnexus-lbug-close-cycle-');
const dbPath = path.join(tmp.dbPath, 'lbug');
try {
const adapter = await import('../../src/core/lbug/lbug-adapter.js');
for (let i = 0; i < 10; i++) {
await adapter.initLbug(dbPath);
await adapter.closeLbug();
}
} finally {
await tmp.cleanup();
}
});
it('safeClose is idempotent — calling twice in a row does not throw', async () => {
const tmp = await createTempDir('gitnexus-lbug-idempotent-');
const dbPath = path.join(tmp.dbPath, 'lbug');
try {
const adapter = await import('../../src/core/lbug/lbug-adapter.js');
await adapter.initLbug(dbPath);
await adapter.closeLbug();
await adapter.closeLbug();
} finally {
await tmp.cleanup();
}
});
});

14
gitnexus/test/integration/lbug-lock-retry.test.ts
View file

@ -14,7 +14,7 @@ import { withTestLbugDB } from '../helpers/test-indexed-db.js';
// Pure-function tests — no DB needed, but grouped here for cohesion
// with the retry logic they guard.
import { isDbBusyError } from '../../src/core/lbug/lbug-adapter.js';
import { isDbBusyError } from '../../src/core/lbug/lbug-config.js';
describe('isDbBusyError', () => {
it('returns true for "busy" errors (case-insensitive)', () => {
@ -46,6 +46,18 @@ describe('isDbBusyError', () => {
expect(isDbBusyError(undefined)).toBe(false);
});
// Documented behavior for lock-shaped strings: the matcher is intentionally
// broad because in graph-DB contexts these are all transient. If LadybugDB
// ever surfaces a non-transient lock-shaped error (e.g., a recovery-time
// "lock file missing"), tighten the matcher and add a negative test here
// rather than raising the retry budget.
it('treats other lock-shaped errors as transient (current intentional behavior)', () => {
expect(isDbBusyError(new Error('deadlock detected'))).toBe(true);
expect(isDbBusyError(new Error('unlock failed'))).toBe(true);
expect(isDbBusyError(new Error('lock contention'))).toBe(true);
expect(isDbBusyError(new Error('Could not open lock file'))).toBe(true);
});
it('handles non-Error values gracefully', () => {
expect(isDbBusyError('BUSY error')).toBe(true);
expect(isDbBusyError(42)).toBe(false);

310
gitnexus/test/integration/lbug-open-retry.test.ts Normal file
View file

@ -0,0 +1,310 @@
/**
* Integration tests: open-time lock-busy retry in `lbug-config.ts`.
*
* The lock IO exception raised by `local_file_system.cpp` happens
* synchronously inside `new lbug.Database(...)`, before any query is
* issued — so `withLbugDb`'s query-time retry cannot see it. These tests
* exercise the construction-time retry wrapper directly by stubbing the
* `Database` constructor.
*
* See: docs/plans/2026-05-08-002-fix-windows-lbug-lock-ci-flakes-plan.md
*/
import fs from 'fs/promises';
import os from 'os';
import path from 'path';
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import {
_isTestFixturePathForTest as isTestFixturePath,
isDbBusyError,
isOpenRetryExhausted,
openLbugConnection,
waitForWindowsHandleRelease,
} from '../../src/core/lbug/lbug-config.js';
// ─── Minimal stub of the `lbug` module surface used by openLbugConnection ──
interface StubModuleControl {
/** Errors thrown by sequential `new Database(...)` calls. `null` = success. */
databaseThrows: Array<Error | null>;
/** Number of times the `Database` constructor was invoked. */
databaseCallCount: number;
/** Number of times `db.close()` was called. */
closeCallCount: number;
}
const makeStubLbug = (control: StubModuleControl) => {
class FakeDatabase {
constructor(_path: string, ..._rest: unknown[]) {
control.databaseCallCount++;
const next = control.databaseThrows.shift();
if (next instanceof Error) throw next;
}
async close(): Promise<void> {
control.closeCallCount++;
}
}
class FakeConnection {
constructor(_db: FakeDatabase) {}
async close(): Promise<void> {}
}
return { Database: FakeDatabase, Connection: FakeConnection } as any;
};
describe('isDbBusyError', () => {
it('matches the documented Windows lock-error wording', () => {
expect(isDbBusyError(new Error('Could not set lock on file foo.lbug'))).toBe(true);
expect(isDbBusyError(new Error('database is locked'))).toBe(true);
});
it('does not match unrelated errors', () => {
expect(isDbBusyError(new Error('Cypher syntax error'))).toBe(false);
expect(isDbBusyError(null)).toBe(false);
});
});
describe('openLbugConnection — open-time lock-busy retry', () => {
it('returns a handle when the constructor succeeds on the first try', async () => {
const control: StubModuleControl = {
databaseThrows: [null],
databaseCallCount: 0,
closeCallCount: 0,
};
const stub = makeStubLbug(control);
const handle = await openLbugConnection(stub, '/some/path/lbug');
expect(handle.db).toBeDefined();
expect(handle.conn).toBeDefined();
expect(control.databaseCallCount).toBe(1);
});
it('retries on busy/lock errors and succeeds on a later attempt', async () => {
const control: StubModuleControl = {
databaseThrows: [new Error('Could not set lock on file'), null],
databaseCallCount: 0,
closeCallCount: 0,
};
const stub = makeStubLbug(control);
const handle = await openLbugConnection(stub, '/some/path/lbug');
expect(handle.db).toBeDefined();
expect(control.databaseCallCount).toBe(2);
});
it('exhausts the retry budget and rethrows the last error preserving its message', async () => {
const lockErr = new Error('Could not set lock on file foo.lbug');
const control: StubModuleControl = {
// 5 attempts + production paths get no sweep retry, so 5 throws total.
databaseThrows: [lockErr, lockErr, lockErr, lockErr, lockErr],
databaseCallCount: 0,
closeCallCount: 0,
};
const stub = makeStubLbug(control);
await expect(openLbugConnection(stub, '/var/data/non-test/lbug')).rejects.toThrow(
'Could not set lock on file foo.lbug',
);
expect(control.databaseCallCount).toBe(5);
});
it('tags the exhausted error so withLbugDb skips its outer retry', async () => {
const lockErr = new Error('Could not set lock on file');
const control: StubModuleControl = {
databaseThrows: [lockErr, lockErr, lockErr, lockErr, lockErr],
databaseCallCount: 0,
closeCallCount: 0,
};
const stub = makeStubLbug(control);
let caught: unknown;
try {
await openLbugConnection(stub, '/var/data/non-test/lbug');
} catch (err) {
caught = err;
}
expect(caught).toBeDefined();
expect(isOpenRetryExhausted(caught)).toBe(true);
expect(isOpenRetryExhausted(new Error('plain error'))).toBe(false);
expect(isOpenRetryExhausted(null)).toBe(false);
expect(isOpenRetryExhausted(undefined)).toBe(false);
});
it('does not retry non-busy errors', async () => {
const syntaxErr = new Error('Cypher syntax error');
const control: StubModuleControl = {
databaseThrows: [syntaxErr],
databaseCallCount: 0,
closeCallCount: 0,
};
const stub = makeStubLbug(control);
await expect(openLbugConnection(stub, '/some/path/lbug')).rejects.toThrow(
'Cypher syntax error',
);
expect(control.databaseCallCount).toBe(1);
});
});
describe('openLbugConnection — stale-sidecar sweep (test fixtures only)', () => {
let fixtureDir: string;
let dbPath: string;
beforeEach(async () => {
fixtureDir = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-lbug-sweep-'));
dbPath = path.join(fixtureDir, 'lbug');
});
afterEach(async () => {
await fs.rm(fixtureDir, { recursive: true, force: true }).catch(() => {});
});
it('sweeps stale .wal/.lock for a recognized test fixture path and retries once', async () => {
await fs.writeFile(dbPath + '.wal', 'stale');
await fs.writeFile(dbPath + '.lock', 'stale');
const lockErr = new Error('Could not set lock on file');
const control: StubModuleControl = {
// 5 retries throw, then sweep + 1 final attempt succeeds (6 total).
databaseThrows: [lockErr, lockErr, lockErr, lockErr, lockErr, null],
databaseCallCount: 0,
closeCallCount: 0,
};
const stub = makeStubLbug(control);
const handle = await openLbugConnection(stub, dbPath);
expect(handle.db).toBeDefined();
expect(control.databaseCallCount).toBe(6);
// Sidecars removed by the sweep
await expect(fs.access(dbPath + '.wal')).rejects.toThrow();
await expect(fs.access(dbPath + '.lock')).rejects.toThrow();
});
it('does not sweep production paths even if they share the prefix', async () => {
// A non-tmp dir that *starts* with the prefix must still be rejected.
const lockErr = new Error('Could not set lock on file');
const control: StubModuleControl = {
databaseThrows: [lockErr, lockErr, lockErr, lockErr, lockErr],
databaseCallCount: 0,
closeCallCount: 0,
};
const stub = makeStubLbug(control);
// Path is outside os.tmpdir() so the predicate must reject it.
await expect(openLbugConnection(stub, '/var/data/gitnexus-lbug-fake/lbug')).rejects.toThrow(
'Could not set lock on file',
);
expect(control.databaseCallCount).toBe(5); // no sweep retry
});
it('handles missing sidecars gracefully (ENOENT swallowed, retry runs)', async () => {
// No .wal or .lock pre-created — sweep ENOENTs both, then succeeds.
const lockErr = new Error('Could not set lock on file');
const control: StubModuleControl = {
databaseThrows: [lockErr, lockErr, lockErr, lockErr, lockErr, null],
databaseCallCount: 0,
closeCallCount: 0,
};
const stub = makeStubLbug(control);
const handle = await openLbugConnection(stub, dbPath);
expect(handle.db).toBeDefined();
expect(control.databaseCallCount).toBe(6);
});
it('sweep retry that throws a different error preserves the original lock error', async () => {
// 5 lock errors, then sweep fires, then post-sweep throws an unrelated
// error. The user-actionable signal is "lock retries exhausted" — the
// post-sweep error must NOT shadow the original lock message.
const lockErr = new Error('Could not set lock on file foo.lbug');
const unrelatedErr = new Error('Schema validation error during open');
const control: StubModuleControl = {
databaseThrows: [lockErr, lockErr, lockErr, lockErr, lockErr, unrelatedErr],
databaseCallCount: 0,
closeCallCount: 0,
};
const stub = makeStubLbug(control);
let caught: Error | undefined;
try {
await openLbugConnection(stub, dbPath);
} catch (err) {
caught = err as Error;
}
expect(caught?.message).toBe('Could not set lock on file foo.lbug');
expect(control.databaseCallCount).toBe(6); // sweep retry did fire
});
});
describe('isTestFixturePath — production-safety guard', () => {
it('accepts a fixture under os.tmpdir with a recognized prefix on the immediate parent', () => {
const tmp = os.tmpdir();
expect(isTestFixturePath(path.join(tmp, 'gitnexus-lbug-XXX', 'lbug'))).toBe(true);
expect(isTestFixturePath(path.join(tmp, 'gitnexus-test-YYY', 'lbug'))).toBe(true);
});
it('rejects production paths even with a matching prefix', () => {
expect(isTestFixturePath('/var/data/gitnexus-lbug-fake/lbug')).toBe(false);
expect(isTestFixturePath('/home/user/gitnexus-test-foo/lbug')).toBe(false);
});
it('rejects path traversal attempts that resolve outside tmpdir', () => {
const tmp = os.tmpdir();
const traversal = path.join(tmp, 'gitnexus-lbug-x', '..', '..', 'etc', 'passwd');
expect(isTestFixturePath(traversal)).toBe(false);
});
it('rejects when the immediate parent does not match even if a deeper ancestor does', () => {
// Tightening: ancestor walk would have allowed nested paths under
// `<tmp>/gitnexus-lbug-x/inner/lbug` to satisfy the predicate. We
// require the immediate parent to match.
const tmp = os.tmpdir();
expect(isTestFixturePath(path.join(tmp, 'gitnexus-lbug-x', 'inner', 'lbug'))).toBe(false);
});
it('handles tmpdir trailing-separator gracefully', () => {
// Some Windows TMP configs return a trailing separator; the predicate
// strips it before the prefix check so fixtures still match.
const tmp = os.tmpdir();
const fixture = path.join(tmp, 'gitnexus-lbug-trailing', 'lbug');
// Whether or not os.tmpdir() itself has a trailing separator,
// the predicate must accept legit fixtures.
expect(isTestFixturePath(fixture)).toBe(true);
});
it('rejects unrelated prefixes in tmpdir', () => {
const tmp = os.tmpdir();
expect(isTestFixturePath(path.join(tmp, 'random-dir', 'lbug'))).toBe(false);
expect(isTestFixturePath(path.join(tmp, 'malicious', 'lbug'))).toBe(false);
});
});
describe('waitForWindowsHandleRelease', () => {
let fixtureDir: string;
let dbPath: string;
beforeEach(async () => {
fixtureDir = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-lbug-probe-'));
dbPath = path.join(fixtureDir, 'lbug');
});
afterEach(async () => {
await fs.rm(fixtureDir, { recursive: true, force: true }).catch(() => {});
});
it('returns true when the file exists and is openable', async () => {
await fs.writeFile(dbPath, 'fake-db-content');
const released = await waitForWindowsHandleRelease(dbPath);
expect(released).toBe(true);
});
it('returns true when the file does not exist (ENOENT is non-lock)', async () => {
// No fs.writeFile — path does not exist. Probe should bail to true,
// not retry, since ENOENT is not a lock code.
const released = await waitForWindowsHandleRelease(dbPath);
expect(released).toBe(true);
});
it('does not leak the file handle when close succeeds', async () => {
// Smoke test: 50 sequential probes with a real file. If close were
// skipped, fd usage would climb. We rely on test process not OOMing
// as the simplest indicator; fd table caps catch egregious leaks.
await fs.writeFile(dbPath, 'fake-db-content');
for (let i = 0; i < 50; i++) {
await waitForWindowsHandleRelease(dbPath);
}
});
});

15
gitnexus/test/integration/setup-skills.test.ts
View file

@ -52,6 +52,21 @@ describe('setupCommand skills integration', () => {
await fs.rm(tempHome, { recursive: true, force: true });
});
it('reports the OpenCode skills install path with the plural skills directory', async () => {
await fs.mkdir(path.join(tempHome, '.config', 'opencode'), { recursive: true });
await setupCommand();
const installedSkill = await fs.readFile(
path.join(tempHome, '.config', 'opencode', 'skills', 'gitnexus-cli', 'SKILL.md'),
'utf-8',
);
expect(installedSkill).toContain('GitNexus CLI Commands');
await expect(
fs.access(path.join(tempHome, '.config', 'opencode', 'skill', 'gitnexus-cli', 'SKILL.md')),
).rejects.toThrow();
});
it('installs packaged, flat-file, and directory skills into cursor skills directory', async () => {
await setupCommand();

50
gitnexus/test/integration/worker-pool.test.ts
View file

@ -6,13 +6,14 @@
* This is critical for cross-platform CI where vitest runs from src/
* but workers need compiled .js files.
*/
import { describe, it, expect, afterEach, vi } from 'vitest';
import { describe, it, expect, afterEach } from 'vitest';
import { createWorkerPool, WorkerPool } from '../../src/core/ingestion/workers/worker-pool.js';
import { pathToFileURL } from 'node:url';
import path from 'node:path';
import fs from 'node:fs';
import os from 'node:os';
import { _captureLogger } from '../../src/core/logger.js';
const DIST_WORKER = path.resolve(
__dirname,
'..',
@ -211,7 +212,7 @@ describe('worker pool integration', () => {
`,
);
const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
const cap = _captureLogger();
const workerUrl = pathToFileURL(workerPath) as URL;
pool = createWorkerPool(workerUrl, 1);
@ -221,9 +222,9 @@ describe('worker pool integration', () => {
]);
expect(results).toHaveLength(1);
expect(results[0].fileCount).toBe(1);
expect(warnSpy).toHaveBeenCalledWith('warning before result');
expect(cap.records().some((r) => r.msg === 'warning before result')).toBe(true);
} finally {
warnSpy.mockRestore();
cap.restore();
fs.rmSync(tempDir, { recursive: true, force: true });
}
});
@ -298,7 +299,7 @@ describe('worker pool integration', () => {
`,
);
const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
const cap = _captureLogger();
pool = createWorkerPool(pathToFileURL(workerPath) as URL, 1, {
subBatchIdleTimeoutMs: 500,
maxTimeoutRetries: 1,
@ -308,9 +309,12 @@ describe('worker pool integration', () => {
try {
const results = await pool.dispatch<any, any>([{ path: 'retry.ts', content: '' }]);
expect(results).toEqual([{ fileCount: 1, recovered: true }]);
expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Retrying with 2s timeout'));
// 500ms idle timeout × 4 backoff factor = 2000ms = "2s" in the retry log.
expect(
cap.records().some((r) => String(r.msg ?? '').includes('Retrying with 2s timeout')),
).toBe(true);
} finally {
warnSpy.mockRestore();
cap.restore();
fs.rmSync(tempDir, { recursive: true, force: true });
}
});
@ -337,7 +341,11 @@ describe('worker pool integration', () => {
`,
);
const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
// Capture pino output AND assert on it: the worker pool should emit a
// warn-level record naming the crash before rejecting, so an operator
// can tell a startup-crash from a stalled-worker rejection. Asserting
// here keeps coverage parity with the prior console.warn spy version.
const cap = _captureLogger();
pool = createWorkerPool(pathToFileURL(workerPath) as URL, 1, {
subBatchIdleTimeoutMs: 150,
maxTimeoutRetries: 1,
@ -348,8 +356,10 @@ describe('worker pool integration', () => {
await expect(pool.dispatch<any, any>([{ path: 'crash.ts', content: '' }])).rejects.toThrow(
/simulated startup crash|exited with code/,
);
const warnRecords = cap.records().filter((r) => Number(r.level) >= 40 /* warn or above */);
expect(warnRecords.length).toBeGreaterThan(0);
} finally {
warnSpy.mockRestore();
cap.restore();
fs.rmSync(tempDir, { recursive: true, force: true });
}
});
@ -383,7 +393,7 @@ describe('worker pool integration', () => {
`,
);
const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
const cap = _captureLogger();
pool = createWorkerPool(pathToFileURL(workerPath) as URL, 1, {
subBatchSize: 2,
subBatchIdleTimeoutMs: 150,
@ -411,9 +421,11 @@ describe('worker pool integration', () => {
]);
expect(progressCalls).toEqual([...progressCalls].sort((a, b) => a - b));
expect(progressCalls.at(-1)).toBe(4);
expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Splitting into 1/1 item jobs'));
expect(
cap.records().some((r) => String(r.msg ?? '').includes('Splitting into 1/1 item jobs')),
).toBe(true);
} finally {
warnSpy.mockRestore();
cap.restore();
fs.rmSync(tempDir, { recursive: true, force: true });
}
});
@ -479,7 +491,7 @@ describe('worker pool integration', () => {
`,
);
const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
const cap = _captureLogger();
pool = createWorkerPool(pathToFileURL(workerPath) as URL, 2, {
subBatchSize: 2,
subBatchIdleTimeoutMs: 150,
@ -505,9 +517,11 @@ describe('worker pool integration', () => {
'tail-a.ts',
'tail-b.ts',
]);
expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Splitting into 1/1 item jobs'));
expect(
cap.records().some((r) => String(r.msg ?? '').includes('Splitting into 1/1 item jobs')),
).toBe(true);
} finally {
warnSpy.mockRestore();
cap.restore();
fs.rmSync(tempDir, { recursive: true, force: true });
}
});
@ -543,7 +557,7 @@ describe('worker pool integration', () => {
`,
);
const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
const cap = _captureLogger();
// 2 workers but subBatchSize=4 means all 4 items form 1 job; second worker stays idle.
pool = createWorkerPool(pathToFileURL(workerPath) as URL, 2, {
subBatchSize: 4,
@ -562,9 +576,9 @@ describe('worker pool integration', () => {
const allPaths = results.flatMap((r: any) => r.paths);
expect(allPaths.sort()).toEqual(['a.ts', 'b.ts', 'c.ts', 'd.ts']);
expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Splitting into'));
expect(cap.records().some((r) => String(r.msg ?? '').includes('Splitting into'))).toBe(true);
} finally {
warnSpy.mockRestore();
cap.restore();
fs.rmSync(tempDir, { recursive: true, force: true });
}
}, 15_000);

16
gitnexus/test/unit/analyze-embeddings-limit.test.ts
View file

@ -44,17 +44,23 @@ describe('analyzeCommand --embeddings [limit] parsing', () => {
it.each(['abc', '-1', '1.5', 'NaN', 'Infinity'])(
'rejects invalid --embeddings value %s before analysis starts',
async (embeddings) => {
const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
// The validator routes through cli-message (`cliError`), which
// writes plain text directly to process.stderr. Spy on the raw
// stderr handle rather than `console.error`, since the migration
// bypasses console entirely.
const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
const { analyzeCommand } = await import('../../src/cli/analyze.js');
await analyzeCommand(undefined, { embeddings });
expect(process.exitCode).toBe(1);
expect(runFullAnalysisMock).not.toHaveBeenCalled();
const msg = errorSpy.mock.calls[0]?.[0] ?? '';
expect(msg).toContain('--embeddings expects a non-negative integer');
expect(msg).toContain(`got "${embeddings}"`);
errorSpy.mockRestore();
const allWrites = stderrSpy.mock.calls
.map(([chunk]) => (typeof chunk === 'string' ? chunk : chunk.toString()))
.join('');
expect(allWrites).toContain('--embeddings expects a non-negative integer');
expect(allWrites).toContain(`got "${embeddings}"`);
stderrSpy.mockRestore();
},
);

11
gitnexus/test/unit/analyze-worker-timeout.test.ts
View file

@ -39,15 +39,20 @@ describe('analyzeCommand worker timeout validation', () => {
it.each(['0', 'abc', '-5', 'Infinity'])(
'rejects invalid --worker-timeout value %s before analysis starts',
async (workerTimeout) => {
const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
// Import _captureLogger from the SAME module instance analyze.js will
// see — vi.resetModules() in beforeEach invalidates the singleton.
const { _captureLogger } = await import('../../src/core/logger.js');
const cap = _captureLogger();
const { analyzeCommand } = await import('../../src/cli/analyze.js');
await analyzeCommand(undefined, { workerTimeout });
expect(process.exitCode).toBe(1);
expect(errorSpy).toHaveBeenCalledWith(' --worker-timeout must be at least 1 second.\n');
expect(
cap.records().some((r) => r.msg === ' --worker-timeout must be at least 1 second.\n'),
).toBe(true);
expect(runFullAnalysisMock).not.toHaveBeenCalled();
errorSpy.mockRestore();
cap.restore();
},
);

28
gitnexus/test/unit/calltool-dispatch.test.ts
View file

@ -48,6 +48,7 @@ vi.mock('../../src/storage/repo-manager.js', () => ({
// tests don't shell out to git.
vi.mock('../../src/core/git-staleness.js', () => ({
checkStaleness: vi.fn().mockReturnValue({ isStale: false, commitsBehind: 0 }),
checkStalenessAsync: vi.fn().mockResolvedValue({ isStale: false, commitsBehind: 0 }),
checkCwdMatch: vi.fn().mockResolvedValue({ match: 'none' }),
}));
@ -71,6 +72,7 @@ vi.mock('../../src/mcp/core/embedder.js', () => ({
import { LocalBackend } from '../../src/mcp/local/local-backend.js';
import { listRegisteredRepos, cleanupOldKuzuFiles } from '../../src/storage/repo-manager.js';
import { _captureLogger } from '../../src/core/logger.js';
import {
initLbug,
executeQuery,
@ -194,7 +196,7 @@ describe('LocalBackend.callTool', () => {
});
it('skips vector index query when VECTOR is unsupported by the platform', async () => {
const consoleError = vi.spyOn(console, 'error').mockImplementation(() => undefined);
const cap = _captureLogger();
platformMocks.isVectorExtensionSupportedByPlatform.mockReturnValue(false);
(executeQuery as any).mockImplementation(async (_repoId: string, cypher: string) => {
if (cypher.includes('COUNT(*) AS cnt')) return [{ cnt: 1 }];
@ -217,13 +219,17 @@ describe('LocalBackend.callTool', () => {
cypher.includes('e.embedding AS embedding'),
),
).toBe(true);
expect(consoleError).toHaveBeenCalledWith(
expect.stringContaining(
'GitNexus [query:vector]: VECTOR extension not supported on this platform',
),
);
expect(
cap
.records()
.some((r) =>
String(r.msg ?? '').includes(
'GitNexus [query:vector]: VECTOR extension not supported on this platform',
),
),
).toBe(true);
} finally {
consoleError.mockRestore();
cap.restore();
}
});
@ -835,7 +841,7 @@ describe('LocalBackend.resolveRepo', () => {
hint: '⚠️ stale sibling clone',
});
const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
const cap = _captureLogger();
try {
await backend.init();
@ -846,13 +852,15 @@ describe('LocalBackend.resolveRepo', () => {
await backend.resolveRepo();
await backend.resolveRepo();
const drift = errSpy.mock.calls.filter((c) => String(c[0]).includes('stale sibling clone'));
const drift = cap
.records()
.filter((r) => String(r.msg ?? '').includes('stale sibling clone'));
expect(drift).toHaveLength(1);
// checkCwdMatch should also only run once — the cache check
// happens BEFORE the shellout-heavy match call.
expect(checkCwdMatch).toHaveBeenCalledTimes(1);
} finally {
errSpy.mockRestore();
cap.restore();
(checkCwdMatch as any).mockResolvedValue({ match: 'none' });
}
});

99
gitnexus/test/unit/cli-message.test.ts Normal file
View file

@ -0,0 +1,99 @@
/**
* Unit tests for `gitnexus/src/cli/cli-message.ts`.
*
* cli-message is the helper for user-facing CLI banners and error guidance.
* The contract: each call writes plain text to stderr AND emits a
* structured pino record through the singleton logger.
*
* Tests verify both halves of the tee, plus shape contracts (newline
* handling, structured fields, tee survival across messages with
* embedded newlines).
*/
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import { cliInfo, cliWarn, cliError } from '../../src/cli/cli-message.js';
import { _captureLogger, type LoggerCapture } from '../../src/core/logger.js';
describe('cli-message — stderr + logger tee', () => {
let cap: LoggerCapture;
let stderrSpy: ReturnType<typeof vi.spyOn>;
beforeEach(() => {
cap = _captureLogger();
stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
});
afterEach(() => {
stderrSpy.mockRestore();
cap.restore();
});
it('cliInfo writes plain text to stderr and emits a structured info record', () => {
cliInfo('hello');
// Plain stderr write
const stderrCalls = stderrSpy.mock.calls.map(([chunk]) =>
typeof chunk === 'string' ? chunk : chunk.toString(),
);
expect(stderrCalls).toContain('hello\n');
// Structured logger record
const records = cap.records();
expect(records.some((r) => r.msg === 'hello' && r.level === 30)).toBe(true);
});
it('cliWarn writes to stderr and emits at warn level (40)', () => {
cliWarn('caution');
const stderrCalls = stderrSpy.mock.calls.map(([chunk]) =>
typeof chunk === 'string' ? chunk : chunk.toString(),
);
expect(stderrCalls).toContain('caution\n');
const records = cap.records();
expect(records.some((r) => r.msg === 'caution' && r.level === 40)).toBe(true);
});
it('cliError writes to stderr and emits at error level (50) with structured fields', () => {
cliError('boom', { code: 'EADDRINUSE', port: 4747 });
const stderrCalls = stderrSpy.mock.calls.map(([chunk]) =>
typeof chunk === 'string' ? chunk : chunk.toString(),
);
expect(stderrCalls).toContain('boom\n');
const records = cap.records();
const errorRecord = records.find((r) => r.msg === 'boom' && r.level === 50);
expect(errorRecord).toBeDefined();
expect(errorRecord?.code).toBe('EADDRINUSE');
expect(errorRecord?.port).toBe(4747);
});
it('does not double-newline an already-newlined message', () => {
cliInfo('already-terminated\n');
const stderrCalls = stderrSpy.mock.calls.map(([chunk]) =>
typeof chunk === 'string' ? chunk : chunk.toString(),
);
// Exactly one trailing \n, not two.
expect(stderrCalls).toContain('already-terminated\n');
expect(stderrCalls.includes('already-terminated\n\n')).toBe(false);
});
it('preserves embedded newlines in multi-line messages (does not split into multiple records)', () => {
cliError('line one\nline two\nline three');
const stderrCalls = stderrSpy.mock.calls.map(([chunk]) =>
typeof chunk === 'string' ? chunk : chunk.toString(),
);
// The whole multi-line block goes to stderr in one write, with a
// trailing newline appended.
expect(stderrCalls).toContain('line one\nline two\nline three\n');
// The structured record carries the full message as a single field.
const records = cap.records();
expect(records.some((r) => r.msg === 'line one\nline two\nline three' && r.level === 50)).toBe(
true,
);
});
it('handles an empty message — stderr gets a bare newline, logger gets msg:""', () => {
cliInfo('');
const stderrCalls = stderrSpy.mock.calls.map(([chunk]) =>
typeof chunk === 'string' ? chunk : chunk.toString(),
);
expect(stderrCalls).toContain('\n');
const records = cap.records();
expect(records.some((r) => r.msg === '' && r.level === 30)).toBe(true);
});
});

90
gitnexus/test/unit/group/bridge-storage-tempfile.test.ts Normal file
View file

@ -0,0 +1,90 @@
/**
* Regression tests for U6 — closes CodeQL js/insecure-temporary-file
* (#191/#192/#193) and js/log-injection (#188) in core/group.
*
* The fixes replace `Date.now()` suffix tmp files with crypto.randomBytes
* suffixes + open the tmp file with `flag: 'wx'` (O_EXCL). These tests
* pin both behaviors so a future refactor that drops either signal
* regenerates the CodeQL alert AND fails a test.
*/
import { afterAll, beforeAll, describe, expect, it } from 'vitest';
import path from 'node:path';
import fs from 'node:fs/promises';
import os from 'node:os';
import { writeContractRegistry, createGroupDir } from '../../../src/core/group/storage.js';
import { writeBridgeMeta } from '../../../src/core/group/bridge-db.js';
import type { ContractRegistry } from '../../../src/core/group/types.js';
/**
* Build a minimal `ContractRegistry` literal with overridable fields.
* Replaces the `as never` cast that bypassed the type entirely — keeps
* the test free of unrelated boilerplate while still type-checking the
* fields under test.
*/
function makeRegistry(overrides: Partial<ContractRegistry> = {}): ContractRegistry {
return {
version: 1,
generatedAt: '2026-05-07T00:00:00Z',
repoSnapshots: {},
missingRepos: [],
contracts: [],
crossLinks: [],
...overrides,
};
}
let tmpRoot: string;
let groupDir: string;
beforeAll(async () => {
tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-u6-'));
groupDir = path.join(tmpRoot, 'fixture-group');
await fs.mkdir(groupDir, { recursive: true });
});
afterAll(async () => {
await fs.rm(tmpRoot, { recursive: true, force: true });
});
describe('writeContractRegistry — tempfile hardening', () => {
it('back-to-back writes within the same ms do not collide on the tmp path', async () => {
// The previous `${path}.tmp.${Date.now()}` shape collided when two writers
// landed in the same millisecond. crypto.randomBytes makes the suffix
// essentially-unique. Sequential writes here pin the unique-suffix
// property without depending on Windows-specific concurrent-rename
// behavior (which has its own pre-existing retry pattern in the
// sibling `writeBridge` function and is out of scope for this test).
await writeContractRegistry(groupDir, makeRegistry({ version: 1 }));
await writeContractRegistry(groupDir, makeRegistry({ version: 2 }));
const written = await fs.readFile(path.join(groupDir, 'contracts.json'), 'utf-8');
const parsed = JSON.parse(written);
expect(parsed.version).toBe(2);
});
});
describe('writeBridgeMeta — tempfile hardening', () => {
it('back-to-back writes do not collide on the tmp path', async () => {
await writeBridgeMeta(groupDir, { version: 1, generatedAt: 'a', missingRepos: [] });
await writeBridgeMeta(groupDir, { version: 2, generatedAt: 'b', missingRepos: [] });
const meta = JSON.parse(await fs.readFile(path.join(groupDir, 'meta.json'), 'utf-8'));
expect(meta.version).toBe(2);
});
});
describe('createGroupDir — exclusive-create on group.yaml', () => {
it('refuses to overwrite an existing group without force', async () => {
const gnxDir = path.join(tmpRoot, 'gnx-existing');
await createGroupDir(gnxDir, 'mygroup');
// Second call without force should throw — same behavior as before this
// commit, but now backed by O_EXCL at the writeFile level rather than
// only the up-front existence check (closes the TOCTOU CodeQL flagged).
await expect(createGroupDir(gnxDir, 'mygroup')).rejects.toThrow(/already exists/);
});
it('overwrites with force=true', async () => {
const gnxDir = path.join(tmpRoot, 'gnx-force');
await createGroupDir(gnxDir, 'mygroup');
// Should succeed without throwing.
await expect(createGroupDir(gnxDir, 'mygroup', true)).resolves.toBeTruthy();
});
});

121
gitnexus/test/unit/group/cross-impact-phase2-timeout.test.ts Normal file
View file

@ -0,0 +1,121 @@
/**
* Phase-2 fanout timeout regression test.
*
* Codex adversarial review on PR #1331 surfaced that `validateGroupImpactParams`
* clamps `timeoutMs` and `safeLocalImpact` enforces it on the local leg, but
* the Phase-2 cross-repo fanout (`cross-impact.ts:521-526`) awaits each
* `port.impactByUid(...)` call without a per-call timeout. A single hung
* neighbor pins the request indefinitely; multiple slow neighbors compound
* past the clamped budget because each starts before `Date.now() > deadline`.
*
* This test pins the contract of the mitigation: a `safeNeighborImpact`
* helper that races `port.impactByUid` against a remaining-budget timer
* and returns `{ value: null, timedOut: true }` when the call cannot
* complete in time.
*
* Direct import + named symbol so this is a real regression net — no
* `??`-fallback or dynamic-import dance (the U8 false-green pattern).
*/
import { describe, expect, it } from 'vitest';
import { safeNeighborImpact } from '../../../src/core/group/cross-impact.js';
import type { GroupToolPort } from '../../../src/core/group/service.js';
const minimalOpts = {
maxDepth: 3,
relationTypes: [] as string[],
minConfidence: 0,
includeTests: false,
};
function makePort(impactByUid: GroupToolPort['impactByUid']): GroupToolPort {
return {
resolveRepo: async () => {
throw new Error('not used');
},
impact: async () => {
throw new Error('not used');
},
query: async () => {
throw new Error('not used');
},
context: async () => {
throw new Error('not used');
},
impactByUid,
};
}
describe('safeNeighborImpact — Phase-2 fanout per-call timeout', () => {
it('returns timedOut=true when impactByUid never resolves, within ~remainingMs', async () => {
// Hung neighbor: the promise never resolves. Without the timeout wrap
// this would hang the test runner.
const port = makePort(() => new Promise(() => {}));
const start = performance.now();
const result = await safeNeighborImpact(port, 'repo-id', 'uid:1', 'upstream', minimalOpts, 150);
const elapsedMs = performance.now() - start;
expect(result.timedOut).toBe(true);
expect(result.value).toBeNull();
// Allow generous slack for slow CI; the contract is "bounded", not
// "exactly remainingMs". A regression that drops the timeout entirely
// would hang far past 1500ms; a regression that uses the wrong unit
// (seconds vs ms) would fire much faster.
expect(elapsedMs).toBeGreaterThanOrEqual(140);
expect(elapsedMs).toBeLessThan(1500);
});
it('returns the resolved value and timedOut=false on a fast happy path', async () => {
const fakeFan = { byDepth: { 1: [{ id: 'u1' }] } };
const port = makePort(async () => fakeFan);
const result = await safeNeighborImpact(
port,
'repo-id',
'uid:1',
'upstream',
minimalOpts,
1000,
);
expect(result.timedOut).toBe(false);
expect(result.value).toBe(fakeFan);
});
it('returns timedOut=true immediately when remainingMs is 0 and the call still hangs', async () => {
// Defensive: even if the caller passes 0, the helper must not block.
const port = makePort(() => new Promise(() => {}));
const start = performance.now();
const result = await safeNeighborImpact(port, 'repo-id', 'uid:1', 'upstream', minimalOpts, 0);
const elapsedMs = performance.now() - start;
expect(result.timedOut).toBe(true);
expect(result.value).toBeNull();
// 0ms timeout fires on the next tick — should be well under 50ms even on slow CI.
expect(elapsedMs).toBeLessThan(50);
});
it('does not compound across calls — two hung neighbors complete within ~2× remainingMs total', async () => {
// The contract is per-call timeout. Two sequential hung calls should
// total ~2× remainingMs, not (numNeighbors × remainingMs² / 2) or
// anything compounding. A regression that shares one timer across
// calls would pass the first test but fail this one.
const port = makePort(() => new Promise(() => {}));
const start = performance.now();
const r1 = await safeNeighborImpact(port, 'repo', 'u1', 'upstream', minimalOpts, 100);
const r2 = await safeNeighborImpact(port, 'repo', 'u2', 'upstream', minimalOpts, 100);
const elapsedMs = performance.now() - start;
expect(r1.timedOut).toBe(true);
expect(r2.timedOut).toBe(true);
expect(elapsedMs).toBeGreaterThanOrEqual(180);
expect(elapsedMs).toBeLessThan(1000);
});
it('propagates an immediate rejection from impactByUid as timedOut=false with null value', async () => {
// If the port itself rejects (rather than hangs), the helper should
// surface that as a non-timeout failure — the existing fanout block
// already handles `if (fan == null)` truncation, so returning null
// here keeps that path intact.
const port = makePort(async () => {
throw new Error('connection refused');
});
const result = await safeNeighborImpact(port, 'repo', 'u1', 'upstream', minimalOpts, 1000);
expect(result.timedOut).toBe(false);
expect(result.value).toBeNull();
});
});

29
gitnexus/test/unit/group/grpc-extractor.test.ts
View file

@ -1,4 +1,4 @@
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import * as fs from 'node:fs';
import fsp from 'node:fs/promises';
import * as path from 'node:path';
@ -11,6 +11,7 @@ import {
} from '../../../src/core/group/extractors/grpc-extractor.js';
import type { ProtoServiceInfo } from '../../../src/core/group/extractors/grpc-extractor.js';
import type { RepoHandle } from '../../../src/core/group/types.js';
import { _captureLogger } from '../../../src/core/logger.js';
describe('GrpcExtractor', () => {
let tmpDir: string;
@ -797,18 +798,18 @@ describe('resolveProtoConflict', () => {
});
it('test_all_zero_tie_returns_null', () => {
const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
const cap = _captureLogger();
const candidates = [
makeInfo('pkgA', 'totally/unrelated/a/svc.proto'),
makeInfo('pkgB', 'completely/different/b/svc.proto'),
];
const result = resolveProtoConflict('Svc', 'src/main.go', candidates);
expect(result).toBeNull();
warnSpy.mockRestore();
cap.restore();
});
it('test_positive_score_tie_returns_null', () => {
const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
const cap = _captureLogger();
// Both candidates share `src/proto` with the source dir — equal shared runs.
const candidates = [
makeInfo('pkgA', 'src/proto/a/svc.proto'),
@ -816,11 +817,11 @@ describe('resolveProtoConflict', () => {
];
const result = resolveProtoConflict('Svc', 'src/proto/main.go', candidates);
expect(result).toBeNull();
warnSpy.mockRestore();
cap.restore();
});
it('test_three_way_zero_tie_returns_null', () => {
const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
const cap = _captureLogger();
const candidates = [
makeInfo('pkgA', 'aaa/svc.proto'),
makeInfo('pkgB', 'bbb/svc.proto'),
@ -828,7 +829,7 @@ describe('resolveProtoConflict', () => {
];
const result = resolveProtoConflict('Svc', 'src/main.go', candidates);
expect(result).toBeNull();
warnSpy.mockRestore();
cap.restore();
});
it('test_unique_winner_among_ties', () => {
@ -843,19 +844,19 @@ describe('resolveProtoConflict', () => {
});
it('test_ambiguous_emits_single_warn_with_service_and_paths', () => {
const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
const cap = _captureLogger();
const candidates = [
makeInfo('pkgA', 'totally/unrelated/a/svc.proto'),
makeInfo('pkgB', 'completely/different/b/svc.proto'),
];
resolveProtoConflict('MyService', 'src/main.go', candidates);
expect(warnSpy).toHaveBeenCalledTimes(1);
const msg = String(warnSpy.mock.calls[0][0]);
expect(cap.records().length).toBe(1);
const msg = String(String(cap.records()[0]?.msg ?? ''));
expect(msg).toContain('MyService');
expect(msg).toContain('src/main.go');
expect(msg).toContain('totally/unrelated/a/svc.proto');
expect(msg).toContain('completely/different/b/svc.proto');
warnSpy.mockRestore();
cap.restore();
});
});
@ -879,7 +880,7 @@ describe('GrpcExtractor.extract ambiguous proto resolution', () => {
});
it('test_ambiguous_short_name_across_unrelated_protos_yields_no_source_contract', async () => {
const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
const cap = _captureLogger();
// Two unrelated proto files defining the same short name `UserService` in
// unrelated directories, neither sharing path segments with the Go source.
await fsp.mkdir(path.join(tmpDir, 'billing-team', 'proto'), { recursive: true });
@ -906,8 +907,8 @@ describe('GrpcExtractor.extract ambiguous proto resolution', () => {
(c) => c.meta.source === 'go_client' && c.meta.service === 'UserService',
);
expect(sourceContracts).toHaveLength(0);
expect(warnSpy).toHaveBeenCalled();
warnSpy.mockRestore();
expect(cap.records().length).toBeGreaterThan(0);
cap.restore();
});
});

Some files were not shown because too many files have changed in this diff Show more