Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
Merge origin/main into fix/map-coalesce-rerun
KageBinary79f08df3f8ef
diff --cc ix-cli/src/cli/commands/map.tsindex 7f777f48,3ed67711..2e2cc317--- a/ix-cli/src/cli/commands/map.ts+++ b/ix-cli/src/cli/commands/map.ts@@@ -815,341 -1104,3 +815,341 @@@ function formatRegionLine(region: MapReconst signalText = signals.length > 0 ? chalk.dim(` ${signals}`) : "";return `${badge} ${chalk.bold(region.label)} ${fileText} ${clarityColor(`${clarity} ${confPct}%`)}${signalText}${crosscut}`;}++/** What a map that ran holds when it finishes: the workspace whose lock it took. */+interface HeldMap { root?: string; local?: boolean }++async function runMapCommand(pathArg: string | undefined, opts: { format: string; level?: string; minConfidence: string; maxItems: string; allItems?: boolean; sort: string; graph?: boolean; list?: boolean; full?: boolean; verbose?: boolean; silent?: boolean }, held: HeldMap): Promise<void> {+ let cwd: string;+ try {+ cwd = resolveMapRoot(pathArg);+ } catch (err: any) {+ const message = err?.message ?? "Invalid map path";+ if (opts.format === "json") {+ printJson({ error: "invalid_map_path", message });+ } else if (opts.format === "llm") {+ console.log(llmError("invalid_map_path", message));+ } else {+ console.error(chalk.red("Error:"), message);+ }+ process.exitCode = 1;+ return;+ }++ const silent = opts.silent === true || opts.format === "silent";++ // Single-flight: refuse to stack. Background refresh can fire `ix map`+ // repeatedly (e.g. once per change); if a map is slow or the backend is+ // unhealthy, those invocations would otherwise pile up and run concurrently+ // against the backend. The first map for a workspace holds the lock; any+ // concurrent one coalesces and exits 0 here. The lock auto-releases on+ // process exit (see single-flight.ts) and a stale lock from a crashed map+ // is stolen, so this never wedges.+ const mapLock = acquireMapLock(cwd, `ix map ${cwd}`);+ if (!mapLock) {+ if (!silent && opts.format !== "json" && opts.format !== "llm") {+ process.stderr.write(chalk.dim(" Another ix map is already running for this workspace — skipping.\n"));+ }+ // Tell the holder: this run's reason (an edit, usually) may have come+ // after it read the file, so it runs one more ingest before it lets go.+ requestMapRerun(cwd);+ applyRequestedMapCoalesceExitCode();+ return; // coalesce; the in-flight map will refresh the graph+ }+ // Holding the lock: whatever a map that coalesced before now asked for, this+ // run covers -- it has not read the tree yet.+ takeMapRerun(cwd);+ held.root = cwd;++ // Background refresh is a local-only convenience. When invoked+ // automatically (IX_AUTO_MAP=1, set by the editor/agent hooks) against a+ // remote backend, skip: a remote graph should be fed deliberately, not by+ // a write on every change from every client. Manual `ix map` is never+ // skipped; opt the automatic path back in with IX_AUTO_MAP_CLOUD=1.+ const autoMap = process.env.IX_AUTO_MAP === "1";+ const cloudReady = await isCloudReady();+ if (shouldSkipAutoMap({ auto: autoMap, cloudReady })) {+ if (!silent && opts.format !== "json" && opts.format !== "llm") {+ process.stderr.write(chalk.dim(" Skipping automatic map: active backend is remote (run `ix map` manually to refresh it).\n"));+ }+ return; // lock releases on process exit+ }++ // Shared wall-clock deadline applied to every backend request this command+ // makes (ingest + map), so the whole operation is bounded even if the+ // backend stalls on individual long per-request timeouts.+ const deadlineSignal = mapDeadlineSignal();++ // Auto-detect a multi-repo system (>= 2 child repo roots). When present we+ // scope the map to its system_id; otherwise it's an ordinary single-repo map.+ const systemId = detectSystem(cwd)?.systemId;++ // json and llm are machine formats: suppress progress chatter and route+ // ingestion through the quiet path so stdout carries only the result.+ const machineFormat = opts.format === "json" || opts.format === "llm";+ // Report an error on the right channel: structured record for llm, prose for the rest.+ const emitError = (msg: string) => {+ if (opts.format === "llm") console.log(llmError("backend_error", msg));+ else console.error(chalk.red("Error:"), msg);+ };++ // Print warning when --full override is active+ if (opts.full && !machineFormat && !silent) {+ console.log(chalk.yellow("\nWarning"));+ console.log(chalk.yellow(" Full local map override enabled.\n"));+ console.log(" Ix will ignore automatic local safety limits and attempt full local mapping.");+ console.log(" This may take a long time or fail on very large systems.\n");+ }++ // Ingest the path before mapping so the graph is up to date.+ //+ // Routing: if Pro is loaded AND the user has an active cloud+ // instance configured (isCloudReady === true), route ingestion+ // through the cloud pipeline. To force local, switch the active+ // instance with `ix instance use local` (or `ix instance bind+ // local` to scope to one workspace).+ //+ // The local backend bootstrap below only runs on the local path —+ // cloud ingestion doesn't require a local Ix backend.+ const ingestStart = performance.now();+ let localIngest: IngestFilesSummary | undefined;+ if (cloudReady) {+ const runner = getRemoteRunner()!; // isCloudReady guarantees non-null+ try {+ await runner.runIngestion({+ cwd,+ silent,+ format: (machineFormat || silent) ? "json" : "text",+ });+ } catch (err: any) {+ emitError(formatFetchError(err));+ process.exitCode = 1;+ return;+ }+ } else {+ try {+ await bootstrap(cwd);+ } catch (err: any) {+ emitError(err.message);+ process.exitCode = 1;+ return;+ }+ try {+ localIngest = await ingestFiles(cwd, {+ recursive: true,+ format: (machineFormat || silent) ? "json" : "text",+ printSummary: false,+ suppressOutput: true,+ mapMode: mapModeForIngest(),+ deadlineSignal,+ // `ix map` has no --debug, so the per-file `[commit error] <uri>`+ // detail was unreachable from the command that produced the+ // failure — and the failure message told the user to pass a flag+ // that does not exist. --verbose is map's equivalent lever.+ debug: Boolean(opts.verbose),+ });+ } catch (err: any) {+ emitError(formatFetchError(err));+ process.exitCode = 1;+ return;+ }+ // Only a local ingest that got through earns the rerun: after a failed+ // one the backend was just seen to be down or out of time.+ held.local = true;+ }+ const ingestMs = Math.round(performance.now() - ingestStart);+- const client = new IxClient(getEndpoint(), deadlineSignal);++ const client = createClient({ deadlineSignal });++ const mapBarWidth = 25;+ const mapStart = performance.now();++ // Path-2 grouping (Ix#225 Half B): a co-ingest system is found by detectSystem+ // above; a SEPARATELY-ingested repo that the stitcher joined into a system has+ // no local marker, so look its system_id up from the backend and scope to it,+ // making `ix map <repo>` show the whole stitched system.+ let effectiveSystemId = systemId;+ if (!effectiveSystemId) {+ const ws = resolveWorkspaceId(cwd);+ if (ws) {+ // Best-effort, as before workspaceSystem started reporting failures:+ // an unanswered lookup leaves the map at workspace scope.+ const looked = await client.workspaceSystem(ws).catch(() => ({ systemId: null }));+ if (looked.systemId) effectiveSystemId = looked.systemId;+ }+ }+ const mapRequest = { full: opts.full, workspaceId: effectiveSystemId ? undefined : resolveWorkspaceId(cwd), systemId: effectiveSystemId };++ // Reuse the last response when this run's ingest wrote nothing and the+ // backend's head revision has not moved since it was computed. Local+ // only: a cloud ingest reports no summary, so it cannot vouch for that.+ const cacheSlot = localIngest ? await resolveMapCacheSlot(client, mapRequest, () => readBackendHealth(client)) : undefined;+ const cached = cacheSlot && localIngest?.graphUnchanged ? loadCachedMap(cwd, cacheSlot) : undefined;++ let result: MapView;+ if (cached) {+ result = cached;+ } else {+ // Same gate as the ingest bar: --silent and the machine formats were the+ // only ways to avoid this, and neither is available to something merely+ // capturing normal output.+ const mapInterval = (!machineFormat && !silent && canRenderProgress()) ? setInterval(() => {+ const elapsed = performance.now() - mapStart;+ const pct = 1 - Math.exp(-elapsed / 4000);+ const filled = Math.round(pct * mapBarWidth);+ const bar = chalk.cyan('█'.repeat(filled)) + chalk.dim('░'.repeat(mapBarWidth - filled));+ const pctStr = chalk.cyan(`${Math.min(Math.round(pct * 100), 99)}%`.padStart(4));+ process.stderr.write(`\r Computing map... ${bar} ${pctStr}`);+ }, 80) : null;++ try {+ result = await client.map(mapRequest) as MapResult;+ } catch (err: any) {+ if (mapInterval) { clearInterval(mapInterval); process.stderr.write('\r' + ' '.repeat(60) + '\r'); }+ clearMapResultCache(cwd);+ emitError(formatFetchError(err));+ process.exitCode = 1;+ return;+ }+ if (mapInterval) { clearInterval(mapInterval); process.stderr.write('\r' + ' '.repeat(60) + '\r'); }+ }+ const mapMs = Math.round(performance.now() - mapStart);++ const emptyMapError = invalidateBaselineForIncompleteCompletedMap(result, localIngest, cwd);+ if (emptyMapError) {+ emitError(emptyMapError);+ process.exitCode = 1;+ return;+ }+ // The cache holds the latest response the backend gave, or nothing: a+ // response that is not kept removes the one before it, so a later hit+ // can never be older than a miss in between.+ if (persistCompletedMapBaseline(result, cwd) && cacheSlot) {+ if (!cached) saveCachedMap(cwd, cacheSlot, result);+ } else {+ clearMapResultCache(cwd);+ }++ // stderr, so it reaches a human on the text path and never contaminates+ // the JSON/llm payload on stdout. The exit code deliberately stays 0:+ // plugins read this command's JSON through runners that discard stdout on+ // a non-zero exit, so failing here would hide the very diagnostics the+ // caller needs (the #539 lesson).+ emitDroppedFileWarning(localIngest);++ if (silent) {+ const systems = result.regions.filter(r => r.label_kind === "system").length;+ const subsystems = result.regions.filter(r => r.label_kind === "subsystem").length;+ const modules = result.regions.filter(r => r.label_kind === "module").length;+ // Ix#568: `--silent` returns before both format branches AND wins over+ // `--format llm`, so it is the one output the hooks this field exists+ // for actually see. A skipped stitch deliberately does not move the exit+ // code -- without a token here an automated consumer cannot tell a clean+ // map from one whose cross-repo edges are up to 15 minutes stale.+ // Ix#568. The RULE, not just the fact -- and not for `incomplete`.+ //+ // `--silent` is the hook surface: one terse line per run. `incomplete`+ // fires on nearly every incremental map, so emitting it here would put+ // a token on almost every line and make `stitch_skipped` useless as a+ // signal, while a consumer that actually needs to know an incremental+ // map registered nothing has `--format json` and `--format llm`, which+ // both carry it. What stays here is the guard refusing -- the case that+ // means a backend is being protected from stacked joins.+ const rule = localIngest?.stitchSkippedRule;+ const stitch =+ rule === undefined || rule === "incomplete" || rule === "run-errors"+ ? ""+ // `stitch_skipped_rule`, not `stitch_skipped`. The json and llm+ // formats put the English prose under `stitch_skipped` and the rule+ // under `stitch_skipped_rule`, and emitting the RULE under the+ // prose key here gave one name two value spaces: a hook matching+ // `stitch_skipped=cooling` on this line silently stopped matching+ // the moment it was pointed at `--format json`.+ : ` · stitch_skipped_rule=${rule}`;+ process.stderr.write(+ `map: ${result.file_count} files · ${systems}s/${subsystems}ss/${modules}m regions · ${mapMs}ms${stitch}\n`+ );+ return;+ }++ if (!machineFormat) {+ const mapSec = (mapMs / 1000).toFixed(1);+ process.stderr.write(chalk.dim(` Mapped in ${mapSec}s\n`));+ }++ const minConf = parseFloat(opts.minConfidence ?? "0");+ const levelFilter = opts.level ? parseInt(opts.level, 10) : null;+ const parsedMaxItems = parseInt(opts.maxItems ?? "10", 10);+ const maxItems = Number.isFinite(parsedMaxItems) && parsedMaxItems > 0 ? parsedMaxItems : 10;+ const sortMode = normalizeSortMode(opts.sort);++ let regions = result.regions;+ if (levelFilter !== null) regions = regions.filter(r => r.level === levelFilter);+ if (minConf > 0) regions = regions.filter(r => r.confidence >= minConf);++ if (opts.format === "json") {+ printJson({+ file_count: result.file_count,+ region_count: regions.length,+ levels: result.levels,+ map_rev: result.map_rev,+ outcome: result.outcome,+ // Always present so a consumer can branch on them without a key check.+ // A dropped file is silent otherwise: the backend still answers with a+ // completed outcome, so `outcome` alone cannot distinguish a whole map+ // from one missing every file that failed to build a patch (#554).+ parse_errors: localIngest?.parseErrors ?? 0,+ commit_errors: localIngest?.commitErrors ?? 0,+ // Ix#568. The whole reason this is reported at all is hooks that run+ // `ix map` and read the machine output; leaving it only in+ // `ix ingest --format json` puts it where those hooks never look.+ // `?? null`, not left undefined: JSON.stringify drops an undefined+ // value, so a consumer could not tell the field apart from an older+ // CLI that never emitted it. Its siblings are always present too.+ stitch_skipped: localIngest?.stitchSkipped ?? null,+ stitch_skipped_rule: localIngest?.stitchSkippedRule ?? null,+ regions: regions.map((r: any) => ({+ label: r.label,+ level: r.level,+ files: r.file_count,+ cohesion: roundFloat(r.cohesion),+ coupling: roundFloat(r.external_coupling),+ confidence: roundFloat(r.confidence),+ signals: r.dominant_signals,+ })),+ });+ return;+ }+ if (opts.format === "llm") {+ renderMapLlm(result, regions, localIngest);+ return;+ }+ renderMapText(result, cwd, opts);+}++/**+ * One more ingest when a map that coalesced into this one asked for it (see+ * `requestMapRerun`), before the lock is let go. One pass at most: under a+ * stream of edits a rerun per request would never finish, and the next edit's+ * own map picks up whatever arrives after it. Ingest only -- this run's output+ * has already been printed, and the hierarchy is refreshed by the next map.+ */+async function rerunIfRequested(root: string, local: boolean, opts: { silent?: boolean; format: string }): Promise<void> {+ if (!local || !takeMapRerun(root)) return;+ try {+ await ingestFiles(root, {+ recursive: true,+ format: "json",+ printSummary: false,+ suppressOutput: true,+ mapMode: mapModeForIngest(),+ // Bounded like the run it follows: its own budget, since the first+ // run's may be all but spent.+ deadlineSignal: mapDeadlineSignal(),+ });+ } catch (err: any) {+ if (opts.silent !== true && opts.format !== "json" && opts.format !== "llm") {+ process.stderr.write(chalk.dim(` Re-run for a map that waited on this one failed: ${err?.message ?? err}\n`));+ }+ }+}