From 8a4ebd985fa187f430158e59e8faab8be08a60b3 Mon Sep 17 00:00:00 2001 From: articultur <547692615@qq.com> Date: Sun, 4 Oct 2026 00:03:40 -0700 Subject: [PATCH] fix(cypher): align schema fallback and override hints Derive resource columns from canonical DDL and recommend METHOD_OVERRIDES for legacy table-name errors without changing legacy queries. Add schema consistency and native backend regressions. --- gitnexus/src/mcp/local/cypher-error-hint.ts | 3 + gitnexus/src/mcp/resources.ts | 39 +++++++--- .../local-backend-calltool.test.ts | 71 ++++++++++++++++++- gitnexus/test/unit/resources.test.ts | 70 ++++++++++++++++++ 4 files changed, 173 insertions(+), 10 deletions(-) diff --git a/gitnexus/src/mcp/local/cypher-error-hint.ts b/gitnexus/src/mcp/local/cypher-error-hint.ts index b783c0ac7..73c40d8de 100644 --- a/gitnexus/src/mcp/local/cypher-error-hint.ts +++ b/gitnexus/src/mcp/local/cypher-error-hint.ts @@ -74,6 +74,9 @@ export function getCypherErrorHint(message: string, repoName: string): string | )?.[1]; if (!table) return undefined; const relation = REL_TYPES.find((type) => type.toLowerCase() === table.toLowerCase()); + if (relation === 'OVERRIDES') { + return `Relationships use :${REL_TABLE_NAME} {type: 'METHOD_OVERRIDES'}, not a '${table}' table. OVERRIDES is a legacy type value used by older indexes. ${schema}`; + } if (relation) { return `Relationships use :${REL_TABLE_NAME} {type: '${relation}'}, not a '${relation}' table. ${schema}`; } diff --git a/gitnexus/src/mcp/resources.ts b/gitnexus/src/mcp/resources.ts index 49687fa9b..3cbd13948 100644 --- a/gitnexus/src/mcp/resources.ts +++ b/gitnexus/src/mcp/resources.ts @@ -10,6 +10,14 @@ import { checkStaleness } from './staleness.js'; import { loadMeta } from '../storage/repo-manager.js'; import { ANALYZER_RUNNER_IDENTITY_SCHEMA_VERSION } from '../core/analyzer-identity.js'; import { getIndexIncompleteReasons } from '../core/index-freshness.js'; +import { + EMBEDDING_SCHEMA, + EMBEDDING_TABLE_NAME, + NODE_SCHEMA_QUERIES, + NODE_TABLES, + RELATION_SCHEMA, + REL_TABLE_NAME, +} from '../core/lbug/schema.js'; import { checkoutIsDirectory, contentRetentionFromMeta, @@ -517,8 +525,20 @@ async function getProcessesResource(backend: LocalBackend, repoName?: string): P * Schema resource — graph structure for Cypher queries */ function getSchemaResource(): string { + // Render the stored columns, not the richer ingestion-only symbol metadata. + const properties = (ddl: string): string => + [...ddl.matchAll(/^\s+(\w+) ([A-Z][A-Z0-9]*(?:\[\d*\])?),?$/gm)] + .map(([, name, type]) => `${name} (${type})`) + .join(', '); + const nodeProperties = NODE_SCHEMA_QUERIES.map((ddl) => { + const table = ddl.match(/CREATE NODE TABLE `?(\w+)`?\s*\(/)?.[1]; + return ` ${table}: "${properties(ddl)}"`; + }).join('\n'); + return `# GitNexus Graph Schema +schema_scope: "Schema created by this GitNexus version; older indexes may differ. Properties vary by table." + nodes: - File: Source code files - Folder: Directory containers @@ -530,17 +550,18 @@ nodes: - Community: Auto-detected functional area (Leiden algorithm) - Process: Execution flow trace -additional_node_types: "Multi-language: Struct, Enum, Macro, Typedef, Union, Namespace, Trait, Impl, TypeAlias, Const, Static, Property, Record, Delegate, Annotation, Constructor, Template, Module (use backticks in queries: \`Struct\`, \`Enum\`, etc.)" +node_tables: "${NODE_TABLES.join(', ')} (use backticks in queries: \`Struct\`, \`Enum\`, etc.)" node_properties: - common: "name (STRING), filePath (STRING), startLine (INT32), endLine (INT32)" +${nodeProperties} + +embedding_storage: + ${EMBEDDING_TABLE_NAME}: "${properties(EMBEDDING_SCHEMA)}" + +property_notes: line_numbers: "startLine/endLine on symbol nodes are 0-BASED (tree-sitter rows) in storage AND in raw Cypher results. The context, query, impact, group/cross-repo trace, and explain/pdg_query (symbol anchor) tools present them 1-BASED (editor / sed / less -N aligned), so a symbol spans editor lines (startLine+1)..(endLine+1) — e.g. sed ',!d' . Single-repo trace symbol lines stay 0-BASED for now (full-parity follow-up). content holds the exact symbol span. (BasicBlock / PDG statement lines are separately 1-based.) (#2377, #2380)" - Method: "parameterCount (INT32), returnType (STRING), isVariadic (BOOL), visibility (STRING), isStatic (BOOL), isAbstract (BOOL), isFinal (BOOL), isVirtual (BOOL), isOverride (BOOL), isAsync (BOOL), isPartial (BOOL), requiredParameterCount (INT32), parameterTypes (STRING[]), annotations (STRING[])" - Function: "parameterCount (INT32), returnType (STRING), isVariadic (BOOL), visibility (STRING), isStatic (BOOL), isAbstract (BOOL), isFinal (BOOL), isAsync (BOOL), parameterTypes (STRING[]), annotations (STRING[])" Property: "declaredType (STRING) — the field's type annotation (e.g., 'Address', 'City'). Used for field-access chain resolution." - Constructor: "parameterCount (INT32), visibility (STRING), isStatic (BOOL), parameterTypes (STRING[])" - Community: "heuristicLabel (STRING), cohesion (DOUBLE), symbolCount (INT32), keywords (STRING[]), description (STRING), enrichedBy (STRING)" - Process: "heuristicLabel (STRING), processType (STRING — 'intra_community' or 'cross_community'), stepCount (INT32), communities (STRING[]), entryPointId (STRING), terminalId (STRING)" + Process: "processType is 'intra_community' or 'cross_community'." relationships: - CONTAINS: File/Folder contains child @@ -558,12 +579,12 @@ relationships: - STEP_IN_PROCESS: Symbol is step N in process pdg_layers: "Recorded ONLY when indexed with 'gitnexus analyze --pdg'. Intra-procedural, basic-block granular; both endpoints are BasicBlock nodes. Prefer the pdg_query tool over raw Cypher." - - BasicBlock: "Basic-block node. Columns: id, filePath, startLine, endLine, text. id = 'BasicBlock::::'." + - BasicBlock: "Basic-block node; columns are listed in node_properties. id = 'BasicBlock::::'." - CFG: "Control-flow edge BasicBlock->BasicBlock. Edge kind (seq/cond-true/cond-false/loop-back/...) is in reason." - CDG: "Control-DEPENDENCE edge BasicBlock->BasicBlock — the source predicate gates the target's execution. Branch sense 'T'|'F' in reason. Query via pdg_query mode:'controls'." - REACHING_DEF: "Data-dependence (def->use) edge BasicBlock->BasicBlock. Source-level variable name is in reason. Query via pdg_query mode:'flows'." -relationship_table: "All relationships use a single CodeRelation table with a 'type' property. Properties: type (STRING), confidence (DOUBLE), reason (STRING), step (INT32)" +relationship_table: "All relationships use a single ${REL_TABLE_NAME} table with a 'type' property. Properties: ${properties(RELATION_SCHEMA)}" example_queries: find_callers: | diff --git a/gitnexus/test/integration/local-backend-calltool.test.ts b/gitnexus/test/integration/local-backend-calltool.test.ts index a3bea5318..9a40a25dc 100644 --- a/gitnexus/test/integration/local-backend-calltool.test.ts +++ b/gitnexus/test/integration/local-backend-calltool.test.ts @@ -8,6 +8,7 @@ import fs from 'fs/promises'; import { describe, it, expect, beforeAll, vi } from 'vitest'; import { LocalBackend } from '../../src/mcp/local/local-backend.js'; +import { readResource } from '../../src/mcp/resources.js'; import { listRegisteredRepos, saveMeta } from '../../src/storage/repo-manager.js'; import { withTestLbugDB } from '../helpers/test-indexed-db.js'; import { @@ -1105,6 +1106,69 @@ withTestLbugDB( expect(result.hint).toContain(":CodeRelation {type: 'CALLS'}"); }); + it.each(['OVERRIDES', 'overrides'])( + 'directs the legacy %s table spelling to current override edges', + async function recommendsCurrentOverrideEdges(table) { + const result = await backend.callTool('cypher', { + statement: `MATCH ()-[:${table}]->() RETURN count(*)`, + }); + expect(result.error).toBe( + `Prepare failed: Binder exception: Table ${table} does not exist.`, + ); + expect(result.hint).toContain(":CodeRelation {type: 'METHOD_OVERRIDES'}"); + expect(result.hint).toMatch(/OVERRIDES.*legacy/); + expect(result.hint).toContain('older indexes'); + const advisedPattern = result.hint.match(/:CodeRelation \{type: '[A-Z_]+'\}/)?.[0]; + expect(advisedPattern).toBeDefined(); + const corrected = await backend.callTool('cypher', { + statement: `MATCH (a)-[${advisedPattern}]->(b) RETURN a.id AS source, b.id AS target`, + }); + expect(corrected.row_count).toBe(1); + expect(corrected.markdown).toContain('method:AuthService.authenticate'); + expect(corrected.markdown).toContain('method:BaseService.authenticate'); + expect(corrected).not.toHaveProperty('hint'); + }, + ); + + it('keeps the canonical METHOD_OVERRIDES hint unchanged', async function preservesCanonicalOverrideHint() { + const result = await backend.callTool('cypher', { + statement: 'MATCH ()-[:METHOD_OVERRIDES]->() RETURN count(*)', + }); + expect(result.error).toBe( + 'Prepare failed: Binder exception: Table METHOD_OVERRIDES does not exist.', + ); + expect(result.hint).toBe( + "Relationships use :CodeRelation {type: 'METHOD_OVERRIDES'}, not a 'METHOD_OVERRIDES' table. Read gitnexus://repo/schema-hints-repo/schema for the schema.", + ); + }); + + it('preserves a valid explicit legacy-type query instead of rewriting it', async function preservesLegacyOverrideQuery() { + const result = await backend.callTool('cypher', { + statement: "MATCH ()-[r:CodeRelation {type: 'OVERRIDES'}]->() RETURN r.reason AS reason", + }); + expect(result.row_count).toBe(1); + expect(result.markdown).toContain('legacy-index-row'); + expect(result.markdown).not.toContain('mro-resolution'); + expect(result).not.toHaveProperty('hint'); + }); + + it('preserves wrong-table property errors and links to accurate per-table columns', async function linksToAccuratePropertyColumns() { + const result = await backend.callTool('cypher', { + statement: 'MATCH (n:Function) RETURN n.parameterCount', + }); + expect(result.error).toBe( + 'Prepare failed: Binder exception: Cannot find property parameterCount for n.', + ); + expect(result.hint).not.toContain('Did you mean'); + expect(result.hint).toContain('properties vary by table'); + const resourceUri = result.hint.match(/gitnexus:\/\/\S+/)?.[0] ?? ''; + expect(resourceUri).toBe('gitnexus://repo/schema-hints-repo/schema'); + const resource = await readResource(resourceUri, backend); + const properties = resource.split('node_properties:\n')[1].split('\n\n')[0]; + expect(properties.match(/^ Function: (.+)$/m)?.[1]).not.toContain('parameterCount'); + expect(properties.match(/^ Method: (.+)$/m)?.[1]).toContain('parameterCount (INT32)'); + }); + it.each([ 'MATCH (n:UnrelatedMissingThing) RETURN n', 'MATCH (n:FunctionWithAnUnrelatedSuffix) RETURN n', @@ -1164,7 +1228,12 @@ withTestLbugDB( }); }, { - seed: LOCAL_BACKEND_SEED_DATA, + seed: [ + ...LOCAL_BACKEND_SEED_DATA, + `MATCH (a:Method {id: 'method:AuthService.authenticate'}), + (b:Method {id: 'method:BaseService.authenticate'}) + CREATE (a)-[:CodeRelation {type: 'OVERRIDES', reason: 'legacy-index-row'}]->(b)`, + ], poolAdapter: true, afterSetup: async (handle) => { vi.mocked(listRegisteredRepos).mockResolvedValue([ diff --git a/gitnexus/test/unit/resources.test.ts b/gitnexus/test/unit/resources.test.ts index 4d50a610d..3cc666bcb 100644 --- a/gitnexus/test/unit/resources.test.ts +++ b/gitnexus/test/unit/resources.test.ts @@ -16,6 +16,14 @@ import { readResource, } from '../../src/mcp/resources.js'; import type { RepoMeta } from '../../src/storage/repo-manager.js'; +import { + EMBEDDING_DIMS, + EMBEDDING_SCHEMA, + EMBEDDING_TABLE_NAME, + NODE_SCHEMA_QUERIES, + NODE_TABLES, + RELATION_SCHEMA, +} from '../../src/core/lbug/schema.js'; // Mock loadMeta so getContextResource doesn't hit the filesystem (#2438 fix). // Default: returns null (simulates no on-disk meta — falls back to cached handle). @@ -268,6 +276,68 @@ describe('readResource', () => { expect(result).toContain('IMPORTS'); }); + it('documents every canonical node table and its exact DDL columns', async function documentsCanonicalNodeColumns() { + const result = await readResource('gitnexus://repo/any/schema', createMockBackend()); + const section = result.split('node_properties:\n')[1].split('\n\n')[0]; + const documented = Object.fromEntries( + [...section.matchAll(/^ (\w+): "([^"]*)"$/gm)].map((match) => [match[1], match[2]]), + ); + expect(Object.keys(documented).sort()).toEqual([...NODE_TABLES].sort()); + + for (const ddl of NODE_SCHEMA_QUERIES) { + const [declaration, ...lines] = ddl + .replace(/\/\*[\s\S]*?\*\//g, '') + .trim() + .split('\n'); + const table = declaration.split(/\s+/)[3].replaceAll('`', ''); + // Independently read declarations, including array types, without the + // renderer's column-matching regex or a hand-maintained property list. + const expected = lines + .map((line) => line.trim().replace(/,$/, '')) + .filter((line) => line && line !== ')' && !line.startsWith('PRIMARY KEY')) + .map((line) => { + const [name, type] = line.split(/\s+/); + return `${name} (${type})`; + }); + expect(documented[table].split(', '), table).toEqual(expected); + } + expect(documented.Function).not.toContain('parameterCount'); + expect(documented.Constructor).not.toContain('parameterCount'); + expect(documented.Method).toContain('parameterCount (INT32), returnType (STRING)'); + expect(documented.BasicBlock).toContain('callees (STRING), calleeIds (STRING)'); + expect(documented.File).not.toContain('startLine'); + expect(documented.Function).toContain('startLine (INT64)'); + expect(result).not.toContain('common:'); + expect(result).toContain('0-BASED'); + expect(result).toContain('find_callers:'); + expect(result).toContain('declaredType'); + }); + + it('documents embedding storage and every relationship column from the DDL', async function documentsEmbeddingAndRelationshipColumns() { + const result = await readResource('gitnexus://repo/any/schema', createMockBackend()); + expect(result).toContain('embedding_storage:\n'); + const embedding = result.split('embedding_storage:\n')[1].split('\n\n')[0]; + expect(embedding).toContain(`${EMBEDDING_TABLE_NAME}:`); + expect(embedding).toContain(`embedding (FLOAT[${EMBEDDING_DIMS}])`); + const relation = result.split('relationship_table: ')[1].split('\n')[0]; + for (const [ddl, rendered] of [ + [EMBEDDING_SCHEMA, embedding], + [RELATION_SCHEMA, relation], + ]) { + const declarations = ddl.trim().split('\n').slice(1, -1); + const columns = declarations + .map((line) => line.trim().replace(/,$/, '')) + .filter((line) => !line.startsWith('PRIMARY KEY') && !line.startsWith('FROM ')) + .map((line) => line.split(/\s+/)); + const actual = [...rendered.matchAll(/(\w+) \(([^)]+)\)/g)].map((match) => [ + match[1], + match[2], + ]); + expect(actual).toEqual(columns); + } + expect(relation).toContain('staticGated (BOOLEAN)'); + }); + it('routes gitnexus://repo/{name}/clusters correctly', async () => { const backend = createMockBackend({ clusters: {