@veewo/gitnexus 1.5.0-rc.4 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veewo/gitnexus",
-  "version": "1.5.0-rc.4",
+  "version": "1.5.0",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",
@@ -37,7 +37,7 @@
     "vendor"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc",
+    "build": "rm -rf dist && tsc && chmod +x dist/cli/index.js",
     "dev": "tsx watch src/cli/index.ts",
     "test": "vitest run test/unit",
     "test:integration": "vitest run test/integration",
@@ -84,18 +84,18 @@
     "lru-cache": "^11.0.0",
     "mnemonist": "^0.39.0",
     "pandemonium": "^2.4.0",
-    "tree-sitter": "^0.21.0",
-    "tree-sitter-c": "^0.21.0",
-    "tree-sitter-c-sharp": "^0.21.0",
-    "tree-sitter-cpp": "^0.22.0",
-    "tree-sitter-go": "^0.21.0",
-    "tree-sitter-java": "^0.21.0",
-    "tree-sitter-javascript": "^0.21.0",
+    "tree-sitter": "^0.22.0",
+    "tree-sitter-c": "^0.23.0",
+    "tree-sitter-c-sharp": "^0.23.1",
+    "tree-sitter-cpp": "^0.23.0",
+    "tree-sitter-go": "^0.23.0",
+    "tree-sitter-java": "^0.23.2",
+    "tree-sitter-javascript": "^0.23.0",
     "tree-sitter-php": "^0.23.12",
-    "tree-sitter-python": "^0.21.0",
+    "tree-sitter-python": "^0.23.2",
     "tree-sitter-ruby": "^0.23.1",
-    "tree-sitter-rust": "^0.21.0",
-    "tree-sitter-typescript": "^0.21.0",
+    "tree-sitter-rust": "^0.23.0",
+    "tree-sitter-typescript": "^0.23.0",
     "uuid": "^13.0.0"
   },
   "optionalDependencies": {

package/scripts/check-sync-manifest-traceability.mjs

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const planArg = process.argv[2];
+if (!planArg) {
+  console.error('Usage: node gitnexus/scripts/check-sync-manifest-traceability.mjs <plan.md>');
+  process.exit(1);
+}
+
+const root = process.cwd();
+const planPath = path.resolve(root, planArg);
+
+const requiredCriticalDc = {
+  'DC-01': {
+    semanticCases: [
+      {
+        id: 'directive parsing',
+        file: 'gitnexus/src/cli/analyze-options.test.ts',
+        pattern: "resolveEffectiveAnalyzeOptions reads @extensions/@repoAlias/@embeddings from manifest",
+      },
+      {
+        id: 'unknown directive fail-fast',
+        file: 'gitnexus/src/cli/analyze-options.test.ts',
+        pattern: 'resolveEffectiveAnalyzeOptions rejects unknown manifest directives',
+      },
+    ],
+    commandMustInclude: ['gitnexus/dist/cli/analyze-options.test.js'],
+  },
+  'DC-02': {
+    semanticCases: [
+      {
+        id: 'precedence merge case',
+        file: 'gitnexus/src/cli/analyze-options.test.ts',
+        pattern: 'resolveEffectiveAnalyzeOptions enforces precedence CLI > manifest > meta',
+      },
+    ],
+    commandMustInclude: ['gitnexus/dist/cli/analyze-options.test.js'],
+  },
+  'DC-03': {
+    semanticCases: [
+      {
+        id: 'auto default sync-manifest load case',
+        file: 'gitnexus/src/cli/analyze.test.ts',
+        pattern: 'analyze auto-loads .gitnexus/sync-manifest.txt when CLI scope options are omitted',
+      },
+    ],
+    commandMustInclude: ['gitnexus/dist/cli/analyze.test.js'],
+  },
+  'DC-04': {
+    semanticCases: [
+      {
+        id: 'mismatch prompt decision case',
+        file: 'gitnexus/src/cli/sync-manifest.test.ts',
+        pattern: 'when explicit CLI values differ from manifest, TTY mode asks whether to update manifest',
+      },
+      {
+        id: 'update decision case',
+        file: 'gitnexus/src/cli/sync-manifest.test.ts',
+        pattern: 'policy=update rewrites manifest with normalized directives',
+      },
+    ],
+    commandMustInclude: [
+      'gitnexus/dist/cli/sync-manifest.test.js',
+      'gitnexus/dist/cli/analyze.test.js',
+    ],
+  },
+  'DC-05': {
+    semanticCases: [
+      {
+        id: 'unknown directive fail-fast case',
+        file: 'gitnexus/src/cli/analyze-options.test.ts',
+        pattern: 'resolveEffectiveAnalyzeOptions rejects unknown manifest directives',
+      },
+    ],
+    commandMustInclude: ['gitnexus/dist/cli/analyze-options.test.js'],
+  },
+  'DC-08': {
+    semanticCases: [
+      {
+        id: 'placeholder rejection case',
+        file: 'gitnexus/src/cli/sync-manifest.test.ts',
+        pattern: 'rejects placeholder manifest path values',
+      },
+      {
+        id: 'non-TTY policy gate case',
+        file: 'gitnexus/src/cli/sync-manifest.test.ts',
+        pattern: 'non-TTY without explicit policy exits with actionable error',
+      },
+    ],
+    commandMustInclude: [
+      'gitnexus/dist/cli/sync-manifest.test.js',
+      'gitnexus/dist/cli/analyze.test.js',
+    ],
+  },
+};
+
+function normalizeCell(value) {
+  return value.trim().replace(/^`|`$/g, '').trim();
+}
+
+function parseTraceabilityRows(planText) {
+  const rows = [];
+  for (const line of planText.split(/\r?\n/)) {
+    if (!line.startsWith('DC-')) continue;
+    const parts = line.split(' | ').map((p) => p.trim());
+    if (parts.length < 6) continue;
+
+    const idMatch = parts[0].match(/^(DC-\d+)/);
+    if (!idMatch) continue;
+
+    rows.push({
+      id: idMatch[1],
+      criticality: parts[1],
+      mappedTasks: normalizeCell(parts[2]),
+      verificationCommand: normalizeCell(parts[3]),
+      artifactEvidenceField: normalizeCell(parts[4]),
+      failureSignal: normalizeCell(parts.slice(5).join(' | ')),
+      raw: line,
+    });
+  }
+  return rows;
+}
+
+function validateCriticalRowShape(row, errors) {
+  if (!row.mappedTasks || row.mappedTasks === '-') {
+    errors.push(`${row.id}: missing mapped tasks`);
+  }
+  if (!/Task\s*\d+/i.test(row.mappedTasks)) {
+    errors.push(`${row.id}: mapped tasks do not reference concrete task ids`);
+  }
+  if (!row.verificationCommand || row.verificationCommand === '-') {
+    errors.push(`${row.id}: missing verification command`);
+  }
+  if (!row.artifactEvidenceField || row.artifactEvidenceField === '-') {
+    errors.push(`${row.id}: missing artifact evidence field`);
+  }
+  if (!row.failureSignal || row.failureSignal === '-') {
+    errors.push(`${row.id}: missing failure signal`);
+  }
+}
+
+async function validateSemanticCases(dcId, config, errors) {
+  for (const semanticCase of config.semanticCases) {
+    const casePath = path.resolve(root, semanticCase.file);
+    let content = '';
+    try {
+      content = await fs.readFile(casePath, 'utf-8');
+    } catch {
+      errors.push(`${dcId}: missing semantic case file ${semanticCase.file}`);
+      continue;
+    }
+    if (!content.includes(semanticCase.pattern)) {
+      errors.push(`${dcId}: missing semantic case '${semanticCase.id}' in ${semanticCase.file}`);
+    }
+  }
+}
+
+function validateCommandCoverage(row, config, errors) {
+  for (const requiredFragment of config.commandMustInclude) {
+    if (!row.verificationCommand.includes(requiredFragment)) {
+      errors.push(`${row.id}: verification command missing '${requiredFragment}'`);
+    }
+  }
+}
+
+async function main() {
+  const planText = await fs.readFile(planPath, 'utf-8');
+  const rows = parseTraceabilityRows(planText);
+  const rowById = new Map(rows.map((row) => [row.id, row]));
+  const errors = [];
+
+  for (const dcId of Object.keys(requiredCriticalDc)) {
+    const row = rowById.get(dcId);
+    if (!row) {
+      errors.push(`missing critical row ${dcId} in Design Traceability Matrix`);
+      continue;
+    }
+
+    if (row.criticality !== 'critical') {
+      errors.push(`${dcId}: expected critical criticality, got '${row.criticality}'`);
+    }
+
+    validateCriticalRowShape(row, errors);
+    validateCommandCoverage(row, requiredCriticalDc[dcId], errors);
+    await validateSemanticCases(dcId, requiredCriticalDc[dcId], errors);
+  }
+
+  if (errors.length > 0) {
+    console.error('Sync-manifest traceability check failed:\n');
+    for (const error of errors) {
+      console.error(`- ${error}`);
+    }
+    process.exit(1);
+  }
+
+  console.log('Sync-manifest traceability check passed.');
+}
+
+main().catch((error) => {
+  console.error(error?.stack || String(error));
+  process.exit(1);
+});

package/scripts/tree-sitter-audit-classify.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const CONTAINER_KEYS = ['class', 'interface', 'struct', 'record', 'delegate', 'enum'];
+
+function toNumber(value) {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string' && value.trim() !== '') {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return 0;
+}
+
+function normalizeContainerCounts(record) {
+  const counts = {
+    class: toNumber(record.class_count),
+    interface: toNumber(record.interface_count),
+    struct: toNumber(record.struct_count),
+    record: toNumber(record.record_count),
+    delegate: toNumber(record.delegate_count),
+    enum: toNumber(record.enum_count),
+  };
+
+  if (record.container_counts && typeof record.container_counts === 'object') {
+    for (const key of CONTAINER_KEYS) {
+      counts[key] = toNumber(record.container_counts[key] ?? counts[key]);
+    }
+  }
+
+  return counts;
+}
+
+function computeClassifiedType(record, containerCounts) {
+  const methodCount = toNumber(record.method_count);
+  const rootHasError = Boolean(record.root_has_error);
+  const rawErrorType = String(record.error_type || '');
+  const totalContainers = CONTAINER_KEYS.reduce((sum, key) => sum + containerCounts[key], 0);
+  const legacyMissingClass = methodCount > 0 && containerCounts.class === 0;
+  const missingContainer = methodCount > 0 && totalContainers === 0;
+  const isFalsePositiveLikely = legacyMissingClass && !missingContainer;
+
+  let errorType = 'ok';
+  if (rawErrorType === 'parse_throw') {
+    errorType = 'parse_throw';
+  } else if (rootHasError || rawErrorType === 'root_has_error') {
+    errorType = 'root_has_error';
+  } else if (missingContainer) {
+    errorType = 'missing_container_with_methods';
+  }
+
+  return {
+    errorType,
+    legacyMissingClass,
+    missingContainer,
+    isFalsePositiveLikely,
+  };
+}
+
+export function classifyTreeSitterAuditRecords(records) {
+  const byType = {
+    parse_throw: 0,
+    root_has_error: 0,
+    missing_container_with_methods: 0,
+    ok: 0,
+  };
+
+  const containerTotals = {
+    class: 0,
+    interface: 0,
+    struct: 0,
+    record: 0,
+    delegate: 0,
+    enum: 0,
+  };
+
+  let compatibilityMissingClassCount = 0;
+  let falsePositiveLikelyCount = 0;
+
+  const classified = records.map((record) => {
+    const containerCounts = normalizeContainerCounts(record);
+    const classification = computeClassifiedType(record, containerCounts);
+    const compatibilityTags = [];
+
+    if (classification.legacyMissingClass) {
+      compatibilityTags.push('missing_class_with_methods');
+      compatibilityMissingClassCount += 1;
+    }
+    if (classification.isFalsePositiveLikely) {
+      falsePositiveLikelyCount += 1;
+    }
+
+    for (const key of CONTAINER_KEYS) {
+      containerTotals[key] += containerCounts[key];
+    }
+
+    byType[classification.errorType] += 1;
+
+    return {
+      ...record,
+      container_counts: containerCounts,
+      classified_error_type: classification.errorType,
+      compatibility_tags: compatibilityTags,
+      is_false_positive_likely: classification.isFalsePositiveLikely,
+    };
+  });
+
+  return {
+    summary: {
+      total: classified.length,
+      byType,
+      compatibility: {
+        missing_class_with_methods: compatibilityMissingClassCount,
+      },
+      falsePositiveLikely: falsePositiveLikelyCount,
+      containerTotals,
+    },
+    records: classified,
+  };
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 2; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--input') args.input = argv[i + 1];
+    if (arg === '--output') args.output = argv[i + 1];
+  }
+  return args;
+}
+
+async function readJsonl(inputPath) {
+  const raw = await fs.readFile(inputPath, 'utf-8');
+  return raw
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+}
+
+async function writeOutput(outputPath, data) {
+  const resolved = path.resolve(outputPath);
+  await fs.mkdir(path.dirname(resolved), { recursive: true });
+  await fs.writeFile(resolved, `${JSON.stringify(data, null, 2)}\n`, 'utf-8');
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  if (!args.input) {
+    console.error('Usage: node scripts/tree-sitter-audit-classify.mjs --input <diagnostics.jsonl> [--output <report.json>]');
+    process.exitCode = 1;
+    return;
+  }
+
+  const records = await readJsonl(path.resolve(args.input));
+  const report = classifyTreeSitterAuditRecords(records);
+
+  if (args.output) {
+    await writeOutput(args.output, report);
+  } else {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}

package/skills/gitnexus-cli.md

@@ -5,7 +5,25 @@ description: "Use when the user needs to run GitNexus CLI commands like analyze/
 
 # GitNexus CLI Commands
 
-Use one command alias in the session so every CLI/MCP call stays on one version line. After `setup`, treat `~/.gitnexus/config.json` as the only npx version source.
+Use one command alias in the session so every CLI/MCP call stays on one version line. After `setup`, use `~/.gitnexus/config.json` as the CLI package spec source (`cliPackageSpec` first, then `cliVersion`). MCP wiring and skill install locations are scope-dependent (`project` vs `global`).
+
+### setup — choose scope explicitly
+
+```bash
+gitnexus setup --scope project --agent codex --cli-spec @veewo/gitnexus@<version>
+```
+
+Rules:
+
+- If user asks "setup this repository" / "本仓库 setup", use `--scope project`.
+- `--scope project` updates repo-local files:
+  - Codex MCP config: `.codex/config.toml`
+  - Skills: `.agents/skills/gitnexus/`
+- `--scope global` updates user-global files:
+  - Codex MCP config: `~/.codex/config.toml`
+  - Skills: `~/.agents/skills/gitnexus/`
+- `--scope global` does not overwrite repo-local `.agents/skills` or `.codex/config.toml`.
+- Never rely on setup defaults for scope; pass `--scope` explicitly to avoid global/project mismatch.
 
 ```bash
 if command -v gitnexus >/dev/null 2>&1; then
@@ -46,16 +64,30 @@ Run from the project root. This parses all source files, builds the knowledge gr
 | -------------------------- | ----------------------------------------------------------------------------------------- |
 | `--force`                  | Force full re-index even if up to date                                                    |
 | `--embeddings`             | Enable embedding generation for semantic search (off by default)                          |
-| `--extensions <ext>`       | Limit parsing to specific file types (e.g., `--extensions ".cs .meta"` for Unity)        |
+| `--extensions <ext>`       | Limit parsing to specific file types (comma-separated, e.g., `--extensions ".cs,.meta"`) |
+| `--csharp-define-csproj <path>` | Load C# `DefineConstants` from a `.csproj` and normalize `#if/#elif/#else/#endif` before parsing |
 | `--scope-prefix <prefix>`  | Limit analysis to a path prefix (e.g., `--scope-prefix Assets/` for Unity)               |
 | `--scope-manifest <file>`  | Read scope rules from a manifest file (e.g., `.gitnexus/sync-manifest.txt`)              |
+| `--sync-manifest-policy <policy>` | Drift policy when explicit CLI values differ from manifest directives: `ask|update|keep|error` |
 | `--skills`                 | Generate repo-specific skill files from detected code communities                         |
 
-**Scope manifest syntax:** Each line is a **path prefix** (not glob). `Assets/Code` matches all files under `Assets/Code/`. Trailing `*` is a wildcard prefix (`Packages/com.veewo.*` matches `Packages/com.veewo.stat/...`). Lines starting with `#` are comments. Do **not** use glob patterns like `**/*.cs` — they will match nothing. Use `--extensions` for file type filtering instead.
+**Scope manifest syntax:** Non-`@` lines are path-prefix scope rules (same semantics as before). `@key=value` directives set analyze options: `@extensions=<csv>`, `@repoAlias=<name>`, `@embeddings=<true|false>`. Unknown directives fail fast.
+
+**Defaulting + drift guard:** If `.gitnexus/sync-manifest.txt` exists and you do not pass `--scope-manifest`/`--scope-prefix`, analyze auto-uses that file. When explicit CLI values (`--extensions`, `--repo-alias`, `--embeddings`) differ from manifest directives, CLI follows `--sync-manifest-policy` (default `ask`; non-TTY requires explicit policy).
 
 **When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook runs `analyze` automatically after `git commit` and `git merge`, preserving embeddings if previously generated.
 
-**Unity projects:** Add `--extensions ".cs .meta"` to ensure Unity asset edges (`UNITY_ASSET_GUID_REF`, `UNITY_COMPONENT_INSTANCE`) are parsed. Add `--scope-prefix Assets/` to limit scope if all code lives under `Assets/`.
+**Unity projects:** Add `--extensions ".cs,.meta"` to ensure Unity asset edges (`UNITY_ASSET_GUID_REF`, `UNITY_COMPONENT_INSTANCE`) are parsed. Add `--scope-prefix Assets/` to limit scope if all code lives under `Assets/`.
+
+**C# conditional-compilation projects (recommended):**
+
+- Unity: pass `--csharp-define-csproj /path/to/Assembly-CSharp.csproj` (for neonspark, use `/Volumes/Shuttle/projects/neonspark/Assembly-CSharp.csproj`).
+- Non-Unity: discover candidate project files first, then pass the intended one explicitly:
+
+```bash
+rg --files -g '*.csproj'
+$GN analyze --extensions ".cs" --csharp-define-csproj <picked-project>.csproj
+```
 
 ### status — Check index freshness
 

package/skills/gitnexus-unity-rule-gen.md

@@ -28,7 +28,7 @@ mcp__gitnexus__cypher:
 如果这两种边不存在，说明索引时未启用 Unity 资源解析，需要重新 analyze，**必须加 Unity 参数**：
 
 ```bash
-gitnexus analyze --force --extensions ".cs .meta"
+gitnexus analyze --force --extensions ".cs,.meta"
 # 如果所有代码都在 Assets/ 下，可加 --scope-prefix Assets/ 缩短分析时间
 ```
 
@@ -254,7 +254,7 @@ gitnexus rule-lab compile --repo-path "$TARGET_REPO"
 ### 2.4 重建索引
 
 ```bash
-gitnexus analyze "$TARGET_REPO" --force --extensions ".cs .meta"
+gitnexus analyze "$TARGET_REPO" --force --extensions ".cs,.meta"
 # 如果所有代码都在 Assets/ 下，可加 --scope-prefix Assets/
 ```