gitnexus 1.6.10-rc.217 → 1.6.10-rc.219

package/dist/cli/group.js

@@ -100,7 +100,24 @@ export function registerGroupCommands(program) {
             console.log('  Repo index / contracts staleness:');
             for (const [repoPath, row] of Object.entries(st.repos || {})) {
                 if (row.missing) {
-                    console.log(`  ${repoPath.padEnd(25)} MISSING   (not in registry or unreadable)`);
+                    // Two different facts with two different remedies: a repo the
+                    // registry never heard of is fixed by indexing it, while an entry
+                    // the resolver choked on is fixed by repairing the registry.
+                    // Printing "no entry in the registry" for the second one states a
+                    // cause that was never measured, and points at the wrong repair.
+                    if (row.unresolvable) {
+                        // The reason can be multi-line — an ambiguous registry names
+                        // every colliding clone. Fold it onto this row's line rather
+                        // than truncating it: those paths are what the operator acts on,
+                        // and a table row that swallows half its own explanation is the
+                        // failure this label exists to stop.
+                        const why = (row.unresolvableReason ?? 'the registry entry could not be resolved')
+                            .replace(/\s+/g, ' ')
+                            .trim();
+                        console.log(`  ${repoPath.padEnd(25)} UNRESOLVABLE (${why})`);
+                        continue;
+                    }
+                    console.log(`  ${repoPath.padEnd(25)} MISSING   (no entry in the registry)`);
                     continue;
                 }
                 const idx = row.indexStale
@@ -109,6 +126,25 @@ export function registerGroupCommands(program) {
                 const ctr = row.contractsStale ? ' CONTRACTS_STALE' : '';
                 console.log(`  ${repoPath.padEnd(25)} ${idx}${ctr}`);
             }
+            // `undefined` and `[]` are different answers here: a registry written
+            // before this was tracked has no opinion, while an empty array is a
+            // measurement. Printing nothing for both would let an unmeasured sync
+            // read as evidence that every index opened cleanly.
+            //
+            // `undefined` covers two ways of not knowing — the field is absent, or
+            // it held something that was not a list of repo paths and `getStatus`
+            // declined to guess. Naming only the first would make a corrupt
+            // registry read as a merely old one, which is the same shape of wrong
+            // answer this command exists to stop giving.
+            const unreadable = st.unreadableRepos;
+            if (unreadable === undefined) {
+                console.log(`\n  Last sync unreadable repos: not recorded` +
+                    `\n     (the registry predates this field, or its value could not be read)` +
+                    `\n     Re-run \`gitnexus group sync\` to record it.`);
+            }
+            else if (unreadable.length > 0) {
+                console.log(`\n  Last sync unreadable repos: ${unreadable.join(', ')}`);
+            }
             if ((st.missingRepos || []).length > 0) {
                 console.log(`\n  Last sync missing repos: ${st.missingRepos.join(', ')}`);
             }
@@ -129,25 +165,85 @@ export function registerGroupCommands(program) {
         const { getGroupDir, getDefaultGitnexusDir } = await import('../core/group/storage.js');
         const { loadGroupConfig } = await import('../core/group/config-parser.js');
         const { syncGroup } = await import('../core/group/sync.js');
+        const { GroupSyncLockError } = await import('../core/group/group-lock.js');
         const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
         const config = await loadGroupConfig(groupDir);
         console.log(`Syncing group "${name}" (${Object.keys(config.repos).length} repos)...\n`);
-        const result = await syncGroup(config, {
-            groupDir,
-            allowStale: Boolean(opts.allowStale),
-            verbose: Boolean(opts.verbose),
-            skipEmbeddings: Boolean(opts.skipEmbeddings),
-            exactOnly: Boolean(opts.exactOnly),
-        });
+        let result;
+        try {
+            result = await syncGroup(config, {
+                groupDir,
+                allowStale: Boolean(opts.allowStale),
+                verbose: Boolean(opts.verbose),
+                skipEmbeddings: Boolean(opts.skipEmbeddings),
+                exactOnly: Boolean(opts.exactOnly),
+            });
+        }
+        catch (err) {
+            // A sync that could not take the group's lock did NOT run and wrote
+            // nothing (R9 fails closed). That is an operator-actionable outcome, not
+            // a crash, so report it as a failed command rather than letting it
+            // surface as an unhandled rejection with a stack trace — commander's
+            // async actions have no error handler, so an uncaught throw here would
+            // print exactly that.
+            if (!(err instanceof GroupSyncLockError))
+                throw err;
+            logger.error(`⚠️ Did not sync group "${name}": ${err.message}`);
+            process.exitCode = 1;
+            return;
+        }
         if (opts.json) {
             console.log(JSON.stringify(result, null, 2));
         }
         else {
+            // Repos we could not read are the most likely explanation for a small
+            // or empty contract count, so they are reported before the counts —
+            // otherwise a run that read nothing looks exactly like a clean run.
+            if (result.unreadableRepos.length > 0) {
+                // No "re-run with GITNEXUS_LOG_LEVEL=warn" hint: the default level is
+                // `info`, and pino emits `warn` (40) at `info` (30), so the reason was
+                // already printed by this same run — raising the level to `warn` would
+                // only suppress the surrounding `info` output.
+                console.log(`\n  ⚠️ Could not extract contracts from: ${result.unreadableRepos.join(', ')}` +
+                    `\n     None of their contracts are included in this sync (the warning above says why),` +
+                    `\n     or check \`gitnexus doctor\` in the affected repo.`);
+            }
+            if (result.missingRepos.length > 0) {
+                console.log(`\n  ⚠️ Not found in the registry: ${result.missingRepos.join(', ')}` +
+                    `\n     Index them with \`gitnexus analyze\`, or remove them from group.yaml.`);
+            }
             console.log(`\nMatching cascade:`);
             const exactLinks = result.crossLinks.filter((l) => l.matchType === 'exact');
             console.log(`  exact:     ${exactLinks.length} cross-links (confidence 1.0)`);
             console.log(`  unmatched: ${result.unmatched.length} contracts`);
-            console.log(`\nWrote contracts.json (${result.contracts.length} contracts, ${result.crossLinks.length} cross-links)`);
+            // Driven by what actually happened to the file. This line used to be
+            // unconditional, so a run that deliberately preserved the previous
+            // registry still announced `Wrote contracts.json (0 contracts, 0
+            // cross-links)` — a confident false statement about persisted state, on
+            // the exact path this command exists to make legible.
+            // Exhaustive by construction: a `Record` keyed on the union means a
+            // new outcome fails the build here instead of printing nothing, which
+            // is what previously pushed a distinct state into `preserved` and made
+            // this summary false on one of the two branches it then covered.
+            const OUTCOME_LINE = {
+                written: `\nWrote contracts.json (${result.contracts.length} contracts, ` +
+                    `${result.crossLinks.length} cross-links)`,
+                preserved: `\nKept the previous contracts.json — no repo in this group could be read.` +
+                    `\n  Its contracts and cross-links are unchanged; only the unreadable/missing` +
+                    `\n  repo lists were refreshed to describe THIS run. Fix the repos above and re-run.`,
+                superseded: `\nDid NOT touch contracts.json — no repo in this group could be read, and another` +
+                    `\n  sync replaced the file while this one waited for the group lock. That sync's` +
+                    `\n  result stands and this run's repo lists were NOT recorded: they describe a` +
+                    `\n  group state older than what is on disk. Fix the repos above and re-run.`,
+                'no-prior-registry': `\nDid NOT write contracts.json — no repo in this group could be read,` +
+                    `\n  and there is no previous contracts.json to fall back on. Fix the repos` +
+                    `\n  above and re-run.`,
+                // Nothing to say: the caller asked for no write.
+                'not-attempted': null,
+            };
+            const line = OUTCOME_LINE[result.registryOutcome];
+            if (line)
+                console.log(line);
         }
     });
     group
@@ -306,9 +402,15 @@ export function registerGroupCommands(program) {
                 process.exitCode = 1;
                 return;
             }
-            const { contracts, crossLinks } = raw;
+            const { contracts, crossLinks, truncated, unreadableRepos, missingRepos } = raw;
             if (opts.json) {
-                console.log(JSON.stringify({ contracts, crossLinks }, null, 2));
+                // The whole payload, not a re-serialized subset. Destructuring the two
+                // fields this command happens to print and rebuilding an object from
+                // them dropped everything else the service returned — which is how the
+                // completeness fields were invisible here while the MCP tool carried
+                // them. Printing `raw` means a field added to the service reaches
+                // `--json` without a matching edit in this file.
+                console.log(JSON.stringify(raw, null, 2));
             }
             else {
                 console.log(`Contracts (${contracts.length}):`);
@@ -319,6 +421,17 @@ export function registerGroupCommands(program) {
                 for (const l of crossLinks) {
                     console.log(`  ${l.from.repo} -> ${l.to.repo}  [${l.matchType}, conf=${l.confidence}]  ${l.contractId}`);
                 }
+                if (truncated) {
+                    // Counts above are a floor, not a census. Name the repos when the
+                    // registry recorded them, and say so plainly when it did not — a
+                    // listing that cannot say what it is missing is still incomplete.
+                    const absent = [...(unreadableRepos ?? []), ...(missingRepos ?? [])];
+                    console.log(absent.length > 0
+                        ? `\n⚠️ This listing is incomplete: the last sync could not account for ${absent.join(', ')}.` +
+                            `\n   Contracts from those repos are absent, so the counts above are a lower bound.`
+                        : `\n⚠️ This listing is incomplete: the last sync did not record which repos it could` +
+                            `\n   read, so the counts above are a lower bound. Re-run group sync.`);
+                }
             }
         }
         finally {

package/dist/core/group/bridge-db.d.ts

@@ -111,12 +111,138 @@ export declare function queryBridge<T>(handle: BridgeHandle, cypher: string, par
  */
 export declare function closeBridgeDb(handle: BridgeHandle): Promise<void>;
 export declare function writeBridgeMeta(groupDir: string, meta: BridgeMeta): Promise<void>;
+/**
+ * Does `meta` still describe the `bridge.lbug` sitting next to it?
+ *
+ * `writeBridge` stamps the database's size and mtime into the metadata it
+ * writes, so a metadata file left over from an earlier sync cannot match a
+ * database that was replaced after it. Callers whose answer depends on the
+ * metadata being true of THIS database (cross-repo impact reads completeness
+ * from it) must not treat a mismatch as fact.
+ *
+ * When BOTH halves of the stamp are absent the metadata predates stamping, and
+ * it is judged on the write order of the two files instead — see
+ * {@link unstampedMetaPairsByWriteOrder}. Failing every unstamped metadata
+ * closed would mark all pre-existing bridges as incomplete until re-synced,
+ * trading a narrow window for a repo-wide regression; accepting them all hands
+ * back "verified" for the very window this pairing exists to catch.
+ *
+ * A stamp is a PAIR, so exactly one half present is rejected rather than waved
+ * through. That is not the legacy shape: something wrote a stamp and did not
+ * finish, which is the very condition stamping was added to detect. Joining the
+ * two `undefined` checks with `||` returned "verified" for precisely the shape
+ * that most deserves suspicion.
+ *
+ * Returns `false` when the database itself cannot be stat'd, on either path,
+ * since metadata describing a file that is not there describes nothing.
+ *
+ * The checks are ORDERED by how strong their evidence is, strongest first, and
+ * each later one is reached only because every earlier one had nothing to say.
+ * `provenanceUnknown` therefore comes first: a metadata file whose own writer
+ * says it cannot vouch for the database beside it has settled the question, and
+ * neither the stamp nor the write-order heuristic may overturn that.
+ *
+ * The marker is not decoration. `refreshPreservedBridgeMeta` rewrites this file
+ * atomically without touching the database, which leaves `meta.mtime` newer —
+ * the write order a paired write produces, and the one the unstamped branch
+ * ACCEPTS. Reading the marker after that branch (or not at all) hands back
+ * "verified" for a pair the same code path had just found broken.
+ */
+export declare function bridgeMetaMatchesFile(groupDir: string, meta: BridgeMeta): Promise<boolean>;
+/**
+ * Read `meta.json`, validating the SHAPE of what it holds.
+ *
+ * The read and the parse have always been guarded — an absent or unparseable
+ * file answers `version: 0`, which every caller already treats as "no
+ * provenance". What was not guarded is a file that parses into something that
+ * is not this shape: `runGroupImpact` spread both repo lists directly into a
+ * `Set`, so a non-iterable there threw a TypeError out of the whole cross-repo
+ * query, from a point where the bridge lease had been taken and not yet
+ * released. A malformed file is a reason to answer "provenance unknown", never
+ * a reason to crash the question.
+ */
 export declare function readBridgeMeta(groupDir: string): Promise<BridgeMeta>;
+/**
+ * What a refresh did to `meta.json`.
+ *
+ * - `restamped`          — the pair still matched, so the lists were refreshed
+ *                          and the stamp re-taken from the database on disk.
+ * - `provenance-unknown` — the pair did NOT match (or there is no database to
+ *                          match), so the lists were refreshed and the metadata
+ *                          marked as unable to vouch for the file beside it.
+ * - `no-bridge`          — neither `meta.json` nor `bridge.lbug` exists, so
+ *                          there is no pair to keep honest and nothing written.
+ */
+export type PreservedBridgeMetaOutcome = 'restamped' | 'provenance-unknown' | 'no-bridge';
+/**
+ * Bring `meta.json`'s diagnostic lists up to date with a sync that PRESERVED
+ * the bridge instead of rebuilding it, without ever making the metadata claim
+ * more about the database than it did before.
+ *
+ * `syncGroup`'s total-failure path keeps the previous run's contracts and
+ * deliberately leaves `bridge.lbug` alone — the contracts that bridge holds are
+ * the ones being preserved. But `runGroupImpact` reads completeness from
+ * `meta.json`, not from `contracts.json`, so leaving the metadata alone too left
+ * the two files telling different stories: the registry said "this sync could
+ * not read svc/users" while a cross-repo query answered "complete, nothing
+ * depends on this" (R4/R6).
+ *
+ * The refresh is the whole difficulty. It rewrites `meta.json` atomically, so
+ * the file's mtime becomes now while the database's stays old — which is the
+ * write order a paired write produces, and precisely what
+ * `unstampedMetaPairsByWriteOrder` accepts. Three rules follow, and each of them
+ * is load-bearing:
+ *
+ *  1. Ask `bridgeMetaMatchesFile` FIRST, on the file as it stands. After the
+ *     write the question is unanswerable, because the write is what destroys
+ *     the evidence.
+ *  2. Re-stamp only when that answer was yes. Re-stamping a pair that already
+ *     failed would MANUFACTURE the provenance the failure just denied — the
+ *     same metadata/database mis-pairing stamping exists to prevent (KTD6).
+ *  3. When it was no, record `provenanceUnknown` explicitly and carry the
+ *     existing stamp fields through verbatim. Writing "no stamp" instead is
+ *     worse, not better: an unstamped file is judged on the two file times,
+ *     and this write has just put them in the accepting order.
+ *
+ * Nothing here opens, reads, or writes the database. The only `stat` of it
+ * happens on the branch where the pair was just verified.
+ *
+ * NOT SPLIT into locked/unlocked halves the way {@link writeBridge} is, and
+ * deliberately. Its one caller is `syncGroup`'s preserve branch, which is
+ * already inside `withGroupSyncLock` — so this write is ALREADY serialized
+ * against every other sync of the group, and taking the lock here would be the
+ * second acquisition of a non-reentrant primitive that the split exists to
+ * avoid. An acquiring wrapper would therefore have zero production callers,
+ * and no test calls this function at all: it would be dead code standing in for
+ * a guarantee the caller already provides. If a caller outside the critical
+ * section ever appears, it needs the same treatment `writeBridge` got — a
+ * wrapper, not a lock moved down here.
+ */
+export declare function refreshPreservedBridgeMeta(groupDir: string, diagnostics: {
+    missingRepos: string[];
+    unreadableRepos: string[];
+}): Promise<PreservedBridgeMetaOutcome>;
 export interface WriteBridgeInput {
     contracts: StoredContract[];
     crossLinks: CrossLink[];
     repoSnapshots: Record<string, RepoSnapshot>;
     missingRepos: string[];
+    /**
+     * Repos this sync could not extract from — see
+     * `ContractRegistry.unreadableRepos` for the full definition, which this
+     * field carries unchanged.
+     *
+     * Deliberately not restated here. The narrower wording this once had ("whose
+     * index could not be opened") described one of the two causes and silently
+     * excluded the other, an extractor that threw partway through — so the same
+     * field meant one thing on the registry, another on the bridge input, and a
+     * third on the result. One definition, referenced twice, cannot drift.
+     *
+     * Recorded in meta.json so cross-repo impact can tell "nothing depends on
+     * this" from "we could not look": the bridge built here is missing every
+     * contract those repos own.
+     */
+    unreadableRepos?: string[];
 }
 /**
  * Non-fatal issues encountered during writeBridge. Callers can log these to
@@ -138,6 +264,53 @@ export interface WriteBridgeReport {
         message: string;
     }>;
 }
+/**
+ * Rebuild `bridge.lbug` and its `meta.json`, ASSUMING THE CALLER ALREADY HOLDS
+ * THE GROUP SYNC LOCK for `groupDir` (R9).
+ *
+ * PRECONDITION — the group lock is held. There is exactly one production call
+ * site, `syncGroup` in sync.ts, and it is already inside
+ * `withGroupSyncLock(groupDir, …)` when it gets here. Enforced by this comment
+ * rather than by a type, matching `registerRepoUnlocked` / `withRegistryLock`
+ * in repo-manager.ts, which splits the same shape for the same reason.
+ *
+ * WHY THE SPLIT EXISTS AT ALL. The swap this function performs — old database
+ * aside, temp database into place, then `meta.json` written as a SECOND
+ * operation — is the write two concurrent syncs can interleave into a pairing
+ * that never existed: one sync's metadata beside the other's database. That
+ * needs mutual exclusion. But taking the lock HERE would be a second
+ * acquisition of a non-reentrant primitive inside a region that already holds
+ * it, and it would hang every single sync on the happy path, not some rare
+ * interleave. So the exclusion is the caller's, and this function only states
+ * the precondition. {@link writeBridge} is the acquiring wrapper for callers
+ * who are not already inside that region.
+ *
+ * SCOPE — writer-writer only. The reader-side promotion of a leftover
+ * `bridge.lbug.bak` runs on ordinary reads, outside anybody's critical section;
+ * `bridgeMetaMatchesFile` remains the reader's defense there and is not
+ * replaced by this lock.
+ */
+export declare function writeBridgeUnlocked(groupDir: string, input: WriteBridgeInput): Promise<WriteBridgeReport>;
+/**
+ * Rebuild `bridge.lbug` and its `meta.json` as the only writer of `groupDir`.
+ *
+ * The acquiring half of the split described on {@link writeBridgeUnlocked}: for
+ * callers that are NOT already inside the group's critical section, this takes
+ * the group sync lock around the whole swap and releases it afterwards. Two
+ * concurrent calls therefore run one after the other, so the `meta.json` left
+ * on disk is stamped for the `bridge.lbug` left on disk instead of for the
+ * loser's, which is the pairing the swap-plus-metadata sequence would otherwise
+ * let them interleave into.
+ *
+ * NOT used by `syncGroup`, and it must not be: that path already holds this
+ * lock, and `acquireIndexLock` is not reentrant, so routing it here would make
+ * every ordinary sync wait out the full `GROUP_SYNC_LOCK_TIMEOUT_MS` ceiling
+ * against itself. It calls {@link writeBridgeUnlocked} directly.
+ *
+ * Fails closed exactly as `withGroupSyncLock` does: if the lock cannot be
+ * acquired, a `GroupSyncLockError` is thrown and NOTHING is written —
+ * `bridge.lbug` and `meta.json` are left as they were.
+ */
 export declare function writeBridge(groupDir: string, input: WriteBridgeInput): Promise<WriteBridgeReport>;
 export declare function openBridgeDbReadOnly(groupDir: string): Promise<BridgeHandle | null>;
 export declare function bridgeExists(groupDir: string): Promise<boolean>;