gitnexus 1.6.11-rc.8 → 1.6.11

package/dist/core/group/sync.js

@@ -2,7 +2,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { Buffer } from 'node:buffer';
 import { initLbug, executeParameterized, pinRepo, getMaxResidentRepos, } from '../lbug/pool-adapter.js';
-import { readRegistry, readRegistryStrict, } from '../../storage/repo-manager.js';
+import { findRegistryEntryByName, canonicalizePath, registryPathEquals, readRegistry, readRegistryStrict, RegistryAmbiguousTargetError, } from '../../storage/repo-manager.js';
 import { HttpRouteExtractor } from './extractors/http-route-extractor.js';
 import { GraphqlExtractor } from './extractors/graphql-extractor.js';
 import { GrpcExtractor } from './extractors/grpc-extractor.js';
@@ -13,6 +13,7 @@ import { ManifestExtractor } from './extractors/manifest-extractor.js';
 import { discoverWorkspaceLinks } from './extractors/workspace-extractor.js';
 import { buildProviderIndex, runExactMatch, runWildcardMatch } from './matching.js';
 import { detectServiceBoundaries, assignService } from './service-boundary-detector.js';
+import { applyDegradedFlag } from './normalization.js';
 import { getContractRegistryPath, readContractRegistry, writeContractRegistry } from './storage.js';
 import { markBridgeProvenanceUnknown, refreshPreservedBridgeMeta, writeBridgeUnlocked, } from './bridge-db.js';
 import { withGroupSyncLock } from './group-lock.js';
@@ -28,9 +29,16 @@ export function stableRepoPoolId(entry, allEntries) {
     }
     return base;
 }
+/** Operator copy for group sync — unique `--name`, not a path in yaml. */
+export function formatGroupSyncAmbiguousError(err) {
+    const listing = err.matches.map((m) => `  - ${m.path}`).join('\n');
+    return (`Multiple registered repos are named "${err.target}":\n${listing}\n` +
+        `Give each clone a unique registry name with \`gitnexus analyze --name\`, then re-sync. ` +
+        `Do not put a filesystem path in group.yaml.`);
+}
 function defaultResolveHandle(allEntries) {
     return async (registryName, groupPath) => {
-        const e = allEntries.find((en) => en.name === registryName);
+        const e = findRegistryEntryByName(allEntries, registryName);
         if (!e)
             return null;
         const poolId = stableRepoPoolId(e, allEntries);
@@ -120,6 +128,8 @@ export function partitionManifestWindows(links, knownRepos, maxResident) {
 }
 export async function syncGroup(config, opts) {
     const missingRepos = [];
+    const failedRepos = [];
+    const warnings = [];
     // Repos that ARE registered but that we could not extract from — the index
     // would not open, or an extractor threw partway and the repo's staged
     // contracts were dropped. Kept separate from `missingRepos` because the two
@@ -136,6 +146,9 @@ export async function syncGroup(config, opts) {
     // windowed manifest resolution below (re-init + lease per window). Keyed by
     // group path because manifest links reference repos by group path.
     const repoHandles = new Map();
+    // Keep resolved disk paths even when extraction fails and removes the
+    // corresponding handle; workspace discovery does not need a readable index.
+    const resolvedRepoPaths = new Map();
     // Every eviction lease this sync holds. Window loops release their own leases
     // (bounding residency); this set is the defensive outer-finally sweep —
     // release disposers are idempotent, so double-release is a safe no-op.
@@ -153,6 +166,11 @@ export async function syncGroup(config, opts) {
             registryEntries = await readRegistryStrict();
             const entries = registryEntries;
             const resolve = opts?.resolveRepoHandle ?? defaultResolveHandle(entries);
+            if (!opts?.resolveRepoHandle) {
+                for (const regName of Object.values(config.repos)) {
+                    findRegistryEntryByName(entries, regName);
+                }
+            }
             const httpEx = new HttpRouteExtractor();
             const graphqlEx = new GraphqlExtractor();
             const grpcEx = new GrpcExtractor();
@@ -165,6 +183,7 @@ export async function syncGroup(config, opts) {
                     missingRepos.push(groupPath);
                     continue;
                 }
+                resolvedRepoPaths.set(groupPath, handle.repoPath);
                 const poolId = handle.id;
                 const lbugPath = path.join(handle.storagePath, 'lbug');
                 // Staged per repo, not appended straight to `autoContracts`. Extractors
@@ -183,7 +202,7 @@ export async function syncGroup(config, opts) {
                     // resolution no longer reuses these executors — it re-inits + leases
                     // each repo per window (see windowed resolution below, issue #2189).
                     // Record the pool identity so windowed resolution can re-init.
-                    repoHandles.set(groupPath, { poolId, lbugPath });
+                    repoHandles.set(groupPath, { poolId, lbugPath, repoPath: handle.repoPath });
                     const executor = (query, params) => executeParameterized(poolId, query, params ?? {});
                     const boundaries = await detectServiceBoundaries(handle.repoPath);
                     if (config.detect.http) {
@@ -256,7 +275,8 @@ export async function syncGroup(config, opts) {
                         };
                     }
                     catch {
-                        const e = entries.find((en) => en.name === regName);
+                        const resolvedHandlePath = canonicalizePath(handle.repoPath);
+                        const e = entries.find((en) => registryPathEquals(canonicalizePath(en.path), resolvedHandlePath));
                         repoSnapshots[groupPath] = {
                             indexedAt: e?.indexedAt || '',
                             lastCommit: e?.lastCommit || '',
@@ -279,6 +299,8 @@ export async function syncGroup(config, opts) {
                         autoContracts.push(contract);
                 }
                 catch (err) {
+                    if (err instanceof RegistryAmbiguousTargetError)
+                        throw err;
                     // This spans initLbug plus all contract extraction for the repo. The
                     // error used to be discarded entirely, so the only trace of (say) a
                     // storage-version mismatch was an empty contracts.json and a later
@@ -290,6 +312,10 @@ export async function syncGroup(config, opts) {
                     // stack before logging it defeats the point.
                     logger.warn({ err, repo: regName, groupPath, lbugPath }, "⚠️ Could not read this repo's index; its contracts are omitted from this sync.");
                     unreadableRepos.push(groupPath);
+                    failedRepos.push({
+                        repo: groupPath,
+                        reason: err instanceof Error ? err.message : String(err),
+                    });
                     // Forget the handle recorded above (present only if the failure came
                     // after initLbug). Deferred manifest resolution derives its known-repo
                     // set from this map, so leaving the entry here re-opens a repo this
@@ -309,7 +335,14 @@ export async function syncGroup(config, opts) {
             if (!registryEntries)
                 registryEntries = await readRegistry();
             for (const [groupPath, regName] of Object.entries(config.repos)) {
-                const e = registryEntries.find((en) => en.name === regName);
+                const resolvedPath = resolvedRepoPaths.get(groupPath);
+                if (resolvedPath) {
+                    repoPaths.set(groupPath, resolvedPath);
+                    continue;
+                }
+                if (opts?.resolveRepoHandle)
+                    continue;
+                const e = findRegistryEntryByName(registryEntries, regName);
                 if (e)
                     repoPaths.set(groupPath, e.path);
             }
@@ -433,7 +466,7 @@ export async function syncGroup(config, opts) {
     // manifest-declared link can also emit a matchType:'exact' CrossLink with the
     // same endpoints. Prefer the manifest version — it reflects operator intent
     // and carries matchType:'manifest' which downstream consumers may rely on.
-    const crossLinks = dedupeCrossLinks([...manifestCrossLinks, ...matched, ...wildcard.matched]);
+    const crossLinks = dedupeCrossLinks([...manifestCrossLinks, ...matched, ...wildcard.matched]).map(applyDegradedFlag);
     const allContracts = autoContracts;
     const registry = {
         version: 1,
@@ -645,10 +678,12 @@ export async function syncGroup(config, opts) {
                             'a lower bound rather than as complete.'
                         : 'Its metadata could NOT be marked provenance-unknown, so those answers may still ' +
                             'report as complete despite describing an older sync.';
-                    logger.warn({ err: msg, groupDir, bridgeProvenanceWithdrawn: withdrawn }, '⚠️ writeBridge failed; contracts.json is intact and is the canonical copy, ' +
+                    const writeBridgeWarn = '⚠️ writeBridge failed; contracts.json is intact and is the canonical copy, ' +
                         'but bridge.lbug was not replaced: cross-repo queries may still answer from ' +
                         `the previous sync's contracts. ${provenanceNote} ` +
-                        'Re-run `gitnexus group sync` to retry.');
+                        'Re-run `gitnexus group sync` to retry.';
+                    logger.warn({ err: msg, groupDir, bridgeProvenanceWithdrawn: withdrawn }, writeBridgeWarn);
+                    warnings.push(writeBridgeWarn);
                 }
             }
         });
@@ -660,6 +695,9 @@ export async function syncGroup(config, opts) {
         unmatched: wildcard.remaining,
         missingRepos,
         unreadableRepos,
+        failedRepos,
+        warnings,
+        degradedLinks: crossLinks.filter((l) => l.degraded === true).length,
         repoSnapshots,
         registryOutcome,
     };

package/dist/core/group/types.d.ts

@@ -80,6 +80,19 @@ export interface CrossLink {
     contractId: string;
     matchType: MatchType;
     confidence: number;
+    /**
+     * `true` when the PROVIDER endpoint (`to`) has no resolved graph symbol —
+     * empty `symbolUid` / `symbolRef` at sync time (e.g. the handler failed to
+     * resolve and `symbolName` degraded to the file name). The contract boundary
+     * is still proven, but the link cannot anchor a cross-impact fan-out: an
+     * empty provider uid never matches a Phase-1 symbol id, and a downstream
+     * fan-out into it has no neighbor symbol to resolve. Derived once at the
+     * sync persistence boundary (`isUnresolvedEndpoint` in normalization.ts) and
+     * re-derived by `dedupeCrossLinks` when a merge backfills the uid. Absent on
+     * fully-anchored links. Distinct from manifest `manifest::…` synthetic UIDs,
+     * which have their own `fanout_status: 'not_attempted'` channel downstream.
+     */
+    degraded?: boolean;
 }
 export interface RepoSnapshot {
     indexedAt: string;

package/dist/core/incremental/derived-writeback.d.ts

@@ -0,0 +1,36 @@
+import type { KnowledgeGraph } from '../graph/types.js';
+import type { FileHashDiff } from '../../storage/file-hash.js';
+/** The FTS-backed members of `tables`. */
+export declare const ftsTablesAmong: (tables: Iterable<string>) => Set<string>;
+/**
+ * Whether a surgical incremental write may reuse the persisted derived layer.
+ *
+ * Deletions disqualify it: the persisted Community/Process rows and their
+ * MEMBER_OF / STEP_IN_PROCESS edges can reference nodes that no longer exist
+ * after this run, and nothing short of re-deriving can tell which.
+ *
+ * Added or content-changed files also disqualify it: they can introduce,
+ * rename, or retarget symbols and CALLS edges that Leiden and flow extraction
+ * consume. File-deletion-only was too weak a proof that the derived graph is
+ * still valid.
+ */
+export declare const shouldPreservePersistedDerivedGraph: (diff: Pick<FileHashDiff, "deleted" | "added" | "changed">) => boolean;
+/**
+ * FTS-backed node tables that the fresh graph will WRITE rows into for
+ * `fileSet` — the inserting half of the DML.
+ *
+ * Callers must union this with a DB probe for the deleting half
+ * (`nodeTablesWithRowsForFiles`): a table whose last row in these files was
+ * just removed by the edit has nothing here, but still holds a stale row that
+ * the writeback must delete, and deleting it means taking its index down too.
+ */
+export declare const incrementalFtsTablesFromGraph: (graph: KnowledgeGraph, fileSet: ReadonlySet<string>) => Set<string>;
+/**
+ * The node tables an incremental DETACH DELETE should target, given the FTS
+ * tables this run is rebuilding.
+ *
+ * Every non-FTS table (Folder, CodeElement, …) deletes as before. An FTS-backed
+ * table only deletes when its index is being rebuilt anyway, because deleting
+ * from it otherwise would mean DML against a live FTS index (#2589).
+ */
+export declare const nodeTablesForIncrementalDelete: (allNodeTables: readonly string[], rebuildingFtsTables: ReadonlySet<string>) => string[];

package/dist/core/incremental/derived-writeback.js

@@ -0,0 +1,68 @@
+/**
+ * Incremental derived-layer writeback helpers (#3016).
+ *
+ * The derived layers — Leiden communities, execution flows, and the FTS
+ * indexes — are graph-wide, so every analyze run rebuilt all three in full no
+ * matter how small the diff. A surgical incremental write can instead:
+ *   - drop and rebuild only the FTS indexes whose tables hold rows in the
+ *     write set (LadybugDB still cannot DML a table with a live FTS index —
+ *     #2589 — so a table being written must still lose its index first);
+ *   - leave the untouched tables' rows alone, so their indexes stay live;
+ *   - reuse persisted Community/Process rows only when the file-hash diff is
+ *     empty (no added, changed, or deleted files). Any content change can
+ *     add, rename, or retarget symbols that Leiden and flow extraction
+ *     consume — a no-deletion edit is not a validity proof.
+ */
+import { FTS_INDEXES } from '../search/fts-schema.js';
+const FTS_TABLE_NAMES = new Set(FTS_INDEXES.map((i) => i.table));
+/** The FTS-backed members of `tables`. */
+export const ftsTablesAmong = (tables) => {
+    const out = new Set();
+    for (const table of tables) {
+        if (FTS_TABLE_NAMES.has(table))
+            out.add(table);
+    }
+    return out;
+};
+/**
+ * Whether a surgical incremental write may reuse the persisted derived layer.
+ *
+ * Deletions disqualify it: the persisted Community/Process rows and their
+ * MEMBER_OF / STEP_IN_PROCESS edges can reference nodes that no longer exist
+ * after this run, and nothing short of re-deriving can tell which.
+ *
+ * Added or content-changed files also disqualify it: they can introduce,
+ * rename, or retarget symbols and CALLS edges that Leiden and flow extraction
+ * consume. File-deletion-only was too weak a proof that the derived graph is
+ * still valid.
+ */
+export const shouldPreservePersistedDerivedGraph = (diff) => diff.deleted.length === 0 && diff.added.length === 0 && diff.changed.length === 0;
+/**
+ * FTS-backed node tables that the fresh graph will WRITE rows into for
+ * `fileSet` — the inserting half of the DML.
+ *
+ * Callers must union this with a DB probe for the deleting half
+ * (`nodeTablesWithRowsForFiles`): a table whose last row in these files was
+ * just removed by the edit has nothing here, but still holds a stale row that
+ * the writeback must delete, and deleting it means taking its index down too.
+ */
+export const incrementalFtsTablesFromGraph = (graph, fileSet) => {
+    const touched = new Set();
+    graph.forEachNode((n) => {
+        const filePath = n.properties?.filePath;
+        if (!filePath || !fileSet.has(filePath))
+            return;
+        if (FTS_TABLE_NAMES.has(n.label))
+            touched.add(n.label);
+    });
+    return touched;
+};
+/**
+ * The node tables an incremental DETACH DELETE should target, given the FTS
+ * tables this run is rebuilding.
+ *
+ * Every non-FTS table (Folder, CodeElement, …) deletes as before. An FTS-backed
+ * table only deletes when its index is being rebuilt anyway, because deleting
+ * from it otherwise would mean DML against a live FTS index (#2589).
+ */
+export const nodeTablesForIncrementalDelete = (allNodeTables, rebuildingFtsTables) => allNodeTables.filter((tableName) => !FTS_TABLE_NAMES.has(tableName) || rebuildingFtsTables.has(tableName));

package/dist/core/incremental/spring-config-drift.d.ts

@@ -0,0 +1,12 @@
+import type { KnowledgeGraph } from '../graph/types.js';
+export interface PersistedSpringConfigConsumerRow {
+    readonly id?: unknown;
+    readonly description?: unknown;
+}
+/**
+ * Find unchanged Spring consumer files whose unresolved markers changed.
+ *
+ * A removed config key also removes the old USES edge from the fresh graph, so
+ * ordinary new-graph boundary expansion cannot discover the consumer file.
+ */
+export declare function collectSpringConfigConsumerDriftFiles(graph: KnowledgeGraph, persistedRows: readonly PersistedSpringConfigConsumerRow[]): Set<string>;

package/dist/core/incremental/spring-config-drift.js

@@ -0,0 +1,46 @@
+import { SPRING_CONFIG_UNRESOLVED_PREFIX } from '../ingestion/frameworks/spring/config-bindings.js';
+const CONSUMER_LABELS = new Set(['Property', 'Class', 'Record']);
+function unresolvedKeys(description) {
+    if (typeof description !== 'string')
+        return [];
+    return description
+        .split(';')
+        .map((part) => part.trim())
+        .filter((part) => part.startsWith(SPRING_CONFIG_UNRESOLVED_PREFIX))
+        .map((part) => part.slice(SPRING_CONFIG_UNRESOLVED_PREFIX.length))
+        .sort();
+}
+/**
+ * Find unchanged Spring consumer files whose unresolved markers changed.
+ *
+ * A removed config key also removes the old USES edge from the fresh graph, so
+ * ordinary new-graph boundary expansion cannot discover the consumer file.
+ */
+export function collectSpringConfigConsumerDriftFiles(graph, persistedRows) {
+    const persistedById = new Map();
+    for (const row of persistedRows) {
+        if (typeof row.id !== 'string')
+            continue;
+        persistedById.set(row.id, unresolvedKeys(row.description));
+    }
+    const driftFiles = new Set();
+    graph.forEachNode((node) => {
+        if (!CONSUMER_LABELS.has(node.label))
+            return;
+        const filePath = node.properties.filePath;
+        if (typeof filePath !== 'string')
+            return;
+        const description = node.properties.description;
+        const persisted = persistedById.get(node.id);
+        if (persisted === undefined &&
+            (typeof description !== 'string' || !description.includes(SPRING_CONFIG_UNRESOLVED_PREFIX))) {
+            return;
+        }
+        const current = unresolvedKeys(description);
+        const prior = persisted ?? [];
+        if (current.length !== prior.length || current.some((key, index) => key !== prior[index])) {
+            driftFiles.add(filePath);
+        }
+    });
+    return driftFiles;
+}

package/dist/core/incremental/subgraph-extract.d.ts

@@ -6,9 +6,10 @@
  * replaced, produce a smaller KnowledgeGraph that contains:
  *
  *   - Every node whose `properties.filePath` is in `toWriteSet`.
- *   - Every graph-wide node (Community, Process, and Spring metadata
- *     placeholders) — these are regenerated each run and must be fully
- *     rewritten.
+ *   - Graph-wide Community/Process nodes unless `includeDerivedGraphWide`
+ *     is false (#3016 incremental preserve). Spring metadata placeholders
+ *     and `Destination` nodes are always included — their owning phase
+ *     delete-alls them unconditionally before the writeback.
  *   - Every relationship where AT LEAST ONE endpoint is in the writable
  *     set above. Relationships entirely between unchanged-file nodes
  *     are skipped — their rows are still in the DB and re-inserting
@@ -48,7 +49,9 @@
  * IMPORTS from the pre-pipeline DB) covers that case instead.
  */
 import type { KnowledgeGraph } from '../graph/types.js';
-export declare const extractChangedSubgraph: (fullGraph: KnowledgeGraph, toWriteSet: ReadonlySet<string>) => KnowledgeGraph;
+export declare const extractChangedSubgraph: (fullGraph: KnowledgeGraph, toWriteSet: ReadonlySet<string>, options?: {
+    includeDerivedGraphWide?: boolean;
+}) => KnowledgeGraph;
 /**
  * Public — derive the EFFECTIVE write-set: `toWriteSet` expanded by one
  * hop along every file-owned edge in the new graph that crosses the

package/dist/core/incremental/subgraph-extract.js

@@ -6,9 +6,10 @@
  * replaced, produce a smaller KnowledgeGraph that contains:
  *
  *   - Every node whose `properties.filePath` is in `toWriteSet`.
- *   - Every graph-wide node (Community, Process, and Spring metadata
- *     placeholders) — these are regenerated each run and must be fully
- *     rewritten.
+ *   - Graph-wide Community/Process nodes unless `includeDerivedGraphWide`
+ *     is false (#3016 incremental preserve). Spring metadata placeholders
+ *     and `Destination` nodes are always included — their owning phase
+ *     delete-alls them unconditionally before the writeback.
  *   - Every relationship where AT LEAST ONE endpoint is in the writable
  *     set above. Relationships entirely between unchanged-file nodes
  *     are skipped — their rows are still in the DB and re-inserting
@@ -50,8 +51,30 @@
 import { createKnowledgeGraph } from '../graph/graph.js';
 import { isSpringAutoConfigurationDeclaration, isSpringAutoConfigurationSyntheticClass, } from '../ingestion/frameworks/spring/auto-configuration.js';
 import { isSpringAopEvidenceNode } from '../ingestion/frameworks/spring/aop.js';
+/**
+ * `Destination` is graph-wide for the same reason as the Spring AOP evidence
+ * nodes: the layer is recomputed in full on every run and deleted in full
+ * before the writeback (`deleteAllDestinations`), so it must be re-included in
+ * full or it is simply lost.
+ *
+ * The endpoint-writability rule cannot carry it. A RESOLVED destination stores
+ * no `filePath` at all — deliberately, so an incremental delete keyed on
+ * `filePath IN [...]` cannot cut a node shared across files — and the include
+ * test below starts from exactly that property. The result was a defect in both
+ * directions: a newly added file publishing to a new topic reported
+ * `added=1, exit 0` and silently put neither the destination nor the
+ * publisher's edge into the graph, so after the first index every new topic was
+ * invisible until a full rebuild; and a destination whose last referrer stopped
+ * referring to it survived forever as an edgeless orphan still carrying
+ * `address`, the cross-repository join key.
+ *
+ * Unresolved destinations DO carry a file path and would ride the ordinary
+ * rule, but they are included here too: the delete-all removes them as well, so
+ * anything not re-included would be dropped rather than merely stale.
+ */
 const isGraphWideNode = (node) => node.label === 'Community' ||
     node.label === 'Process' ||
+    node.label === 'Destination' ||
     isSpringAopEvidenceNode(node) ||
     isSpringAutoConfigurationSyntheticClass(node);
 /**
@@ -108,12 +131,14 @@ const indexNodeFilePaths = (fullGraph) => {
     });
     return idx;
 };
-export const extractChangedSubgraph = (fullGraph, toWriteSet) => {
+export const extractChangedSubgraph = (fullGraph, toWriteSet, options) => {
     const sub = createKnowledgeGraph();
     const writableNodeIds = new Set();
+    const includeDerivedGraphWide = options?.includeDerivedGraphWide !== false;
     fullGraph.forEachNode((n) => {
         const filePath = n.properties?.filePath;
-        const include = (filePath && toWriteSet.has(filePath)) || isGraphWideNode(n);
+        const derivedWide = includeDerivedGraphWide || (n.label !== 'Community' && n.label !== 'Process');
+        const include = (filePath && toWriteSet.has(filePath)) || (isGraphWideNode(n) && derivedWide);
         if (include) {
             sub.addNode(n);
             writableNodeIds.add(n.id);