homegraph 1.5.8 → 1.6.0

package/dist/mcp/index-availability.js

@@ -1,44 +1,62 @@
 "use strict";
 /**
- * Product-facing index availability for MCP tool results (Spec 0032).
+ * Product-facing index availability for MCP tool results (Spec 0032 + 0035).
  *
- * Internal `build_phase` stays as-is; this layer maps it (+ write-lock / busy)
- * to the four states hosts and agents should see in tool text.
+ * Internal `build_phase` stays as-is; this layer maps it (+ write-lock / busy /
+ * pending dirty files) to the five states hosts and agents should see.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.BOUND_PROJECT_PATH_PIN_MARKER = exports.PROJECT_ROOT_HINT_MARKER = exports.PRODUCT_STATUS_GLOSSARY = void 0;
 exports.productIndexGuidance = productIndexGuidance;
+exports.formatProductStatusLine = formatProductStatusLine;
 exports.resolveProductIndexState = resolveProductIndexState;
 exports.isSqliteBusyMessage = isSqliteBusyMessage;
-const EMPTY_LINES = [
-    'HomeGraph status=empty — project map is not ready yet.',
-    'Retry in a few seconds (or call `homegraph_project` once the fast build completes).',
-];
-const FAST_LINES = [
-    'HomeGraph status=fast — module/file map is ready; full symbol index is still building.',
-    'Use `homegraph_project` for the module/file map now, then retry this tool once indexing finishes.',
-];
-const SYNCING_LINES = [
-    'HomeGraph status=syncing — the index is being written (lock held or local index/sync in progress).',
-    'Retry this tool shortly; do not busy-loop.',
-];
+exports.textAlreadyHasProductStatus = textAlreadyHasProductStatus;
+exports.formatProjectRootPathHint = formatProjectRootPathHint;
+exports.textAlreadyHasProjectRootHint = textAlreadyHasProjectRootHint;
+exports.formatBoundProjectPathPinNotice = formatBoundProjectPathPinNotice;
+exports.textAlreadyHasBoundProjectPathPinNotice = textAlreadyHasBoundProjectPathPinNotice;
+/** One-line glossary for MCP initialize / tool surface (Spec 0035). */
+exports.PRODUCT_STATUS_GLOSSARY = 'status: empty=not ready · fast=map only (homegraph_project) · full=fresh · dirty=usable but listed paths outdated · syncing=write lock, retry';
+const MAX_DIRTY_PATHS = 5;
+/** Whole-response guidance when the tool cannot usefully answer yet. */
 function productIndexGuidance(state) {
     switch (state) {
         case 'empty':
-            return EMPTY_LINES.join('\n');
+            return 'HomeGraph status=empty — not ready; retry shortly.';
         case 'fast':
-            return FAST_LINES.join('\n');
+            return 'HomeGraph status=fast — map only; use homegraph_project; retry other tools later.';
         case 'syncing':
-            return SYNCING_LINES.join('\n');
+            return 'HomeGraph status=syncing — locked; retry shortly, do not loop.';
+    }
+}
+/**
+ * Single status line for tool footers (and for guidance-only replies).
+ * `pendingPaths` only used when `state === 'dirty'`.
+ */
+function formatProductStatusLine(state, opts) {
+    switch (state) {
+        case 'empty':
+        case 'fast':
+        case 'syncing':
+            return productIndexGuidance(state);
+        case 'full':
+            return 'HomeGraph status=full — complete and up to date.';
+        case 'dirty': {
+            const paths = opts?.pendingPaths ?? [];
+            if (paths.length === 0) {
+                return 'HomeGraph status=dirty — outdated: pending files';
+            }
+            const shown = paths.slice(0, MAX_DIRTY_PATHS);
+            const more = paths.length > MAX_DIRTY_PATHS ? `, …+${paths.length - MAX_DIRTY_PATHS}` : '';
+            return `HomeGraph status=dirty — outdated: ${shown.join(', ')}${more}`;
+        }
     }
 }
 /**
  * Resolve the product state from a live HomeGraph handle.
  *
- * - empty: fast map not ready (`none` / `building_fast`)
- * - fast: map ready, full index not done (`fast` / `indexing`)
- * - full: symbol index ready
- * - syncing: full (or empty-while-contended-init) and a writer holds the lock /
- *   this process is indexing — reads may fail or see a moving target
+ * Priority: syncing > empty > fast > dirty > full
  */
 function resolveProductIndexState(cg) {
     let phase;
@@ -69,10 +87,58 @@ function resolveProductIndexState(cg) {
     catch {
         return 'syncing';
     }
+    let pendingCount = 0;
+    try {
+        pendingCount = cg.getPendingFiles?.()?.length ?? 0;
+    }
+    catch {
+        pendingCount = 0;
+    }
+    if (pendingCount > 0)
+        return 'dirty';
     return 'full';
 }
 /** True when an error message indicates SQLite writer contention. */
 function isSqliteBusyMessage(message) {
     return /SQLITE_BUSY|database is locked/i.test(message);
 }
+/** True when text is already a pure (or leading) HomeGraph status line. */
+function textAlreadyHasProductStatus(text) {
+    return /^\s*HomeGraph status=/m.test(text);
+}
+/** Marker line for Spec 0038 project-root path hint (idempotent prepend). */
+exports.PROJECT_ROOT_HINT_MARKER = 'HomeGraph project root:';
+/**
+ * Short preamble: absolute project root + how to join repo-relative paths (Spec 0038).
+ * `absRoot` should already be resolved (platform-native absolute path).
+ */
+function formatProjectRootPathHint(absRoot) {
+    const root = absRoot.trim();
+    return (`${exports.PROJECT_ROOT_HINT_MARKER} \`${root}\`\n` +
+        'Paths below are repo-relative to that root. Pass them to Read/Grep as-is, or join as `<root>/<relative>` (use `/`). Do not invent experiment/result directory prefixes.');
+}
+/** True when text already carries a Spec 0038 project-root hint. */
+function textAlreadyHasProjectRootHint(text) {
+    return text.includes(exports.PROJECT_ROOT_HINT_MARKER);
+}
+/** Marker for Spec 0043 bound-root projectPath soft-pin notice (idempotent prepend). */
+exports.BOUND_PROJECT_PATH_PIN_MARKER = 'This MCP session is bound to';
+/**
+ * English preamble when a tool `projectPath` resolves to a different index root
+ * than the MCP session's default bound root (Spec 0043). Success-shaped — not isError.
+ */
+function formatBoundProjectPathPinNotice(opts) {
+    const bound = opts.boundRoot.trim();
+    const requested = opts.requestedPath.trim();
+    const resolved = opts.resolvedRoot === null
+        ? 'no .homegraph/ found walking up from it'
+        : `resolves to \`${opts.resolvedRoot.trim()}\``;
+    return (`${exports.BOUND_PROJECT_PATH_PIN_MARKER} \`${bound}\`.\n` +
+        `Ignoring projectPath=\`${requested}\` (${resolved}).\n` +
+        'Results below are from the bound project root only. Omit projectPath, or pass a path under that root.');
+}
+/** True when text already carries a Spec 0043 pin notice. */
+function textAlreadyHasBoundProjectPathPinNotice(text) {
+    return text.includes(exports.BOUND_PROJECT_PATH_PIN_MARKER);
+}
 //# sourceMappingURL=index-availability.js.map

package/dist/mcp/index.js

@@ -73,6 +73,7 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
 const directory_1 = require("../directory");
+const runtime_log_1 = require("../runtime-log");
 const transport_1 = require("./transport");
 const engine_1 = require("./engine");
 const session_1 = require("./session");
@@ -298,6 +299,7 @@ class MCPServer {
             // Runs until the host disconnects; the proxy installs its own watchdog and
             // falls back to an in-process engine if the daemon never comes up.
             this.mode = 'proxy';
+            (0, runtime_log_1.logLifecycle)('mcp.start', { projectRoot: root, mode: 'proxy' });
             await this.runProxyWithLocalHandshake(root);
             return;
         }
@@ -306,6 +308,7 @@ class MCPServer {
             // is still safe to recover from with a direct-mode session.
             const msg = err instanceof Error ? err.message : String(err);
             process.stderr.write(`[HomeGraph MCP] Proxy path failed (${msg}); falling back to direct mode.\n`);
+            (0, runtime_log_1.logLifecycleError)('mcp.proxy.fail', { projectRoot: root, msg });
             return this.startDirect('proxy path threw');
         }
     }
@@ -346,6 +349,11 @@ class MCPServer {
         if (reason && process.env.HOMEGRAPH_MCP_DEBUG) {
             process.stderr.write(`[HomeGraph MCP] Direct mode: ${reason}.\n`);
         }
+        (0, runtime_log_1.logLifecycle)('mcp.start', {
+            projectRoot: this.projectPath ?? undefined,
+            mode: 'direct',
+            reason,
+        });
         // Direct mode = one client. Do NOT start a query-pool worker: each worker
         // is a second V8 isolate + a second open of the project DB, and on large
         // indexes (hundreds of MB) that alone pushed process-tree RSS to ~5GB.
@@ -392,6 +400,7 @@ class MCPServer {
      */
     async startDaemonProcess() {
         const root = resolveDaemonRoot(this.projectPath) ?? this.projectPath ?? process.cwd();
+        (0, runtime_log_1.logLifecycle)('mcp.start', { projectRoot: root, mode: 'daemon' });
         for (let attempt = 0; attempt < TAKEOVER_MAX_RETRIES; attempt++) {
             const lock = (0, daemon_1.tryAcquireDaemonLock)(root);
             if (lock.kind === 'acquired') {

package/dist/mcp/indexable-root.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Cheap “is this root worth creating a HomeGraph index?” probe (Spec 0049).
+ *
+ * Used by MCP auto-init to avoid writing `.homegraph/` into empty workspaces
+ * (e.g. DevEco Code task dirs before `devecocli create`).
+ */
+/**
+ * True when `root` already looks like a project HomeGraph should index.
+ * Short-circuits on root `build-profile.json5`, else bounded BFS for any
+ * {@link isSourceFile} hit. Ignores `.homegraph*` and common build/vendor dirs.
+ */
+export declare function isIndexableRoot(rootDir: string, opts?: {
+    maxDirs?: number;
+    maxDepth?: number;
+}): boolean;
+/**
+ * Parse `HOMEGRAPH_DEFER_PROBE_MS`. Default **60000**.
+ * `0` disables the timer (tool-call kick only). Invalid → default.
+ * Clamp: 0, or 1000ms … 10min.
+ */
+export declare function parseDeferProbeMs(raw: string | undefined): number;
+//# sourceMappingURL=indexable-root.d.ts.map

package/dist/mcp/indexable-root.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * Cheap “is this root worth creating a HomeGraph index?” probe (Spec 0049).
+ *
+ * Used by MCP auto-init to avoid writing `.homegraph/` into empty workspaces
+ * (e.g. DevEco Code task dirs before `devecocli create`).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isIndexableRoot = isIndexableRoot;
+exports.parseDeferProbeMs = parseDeferProbeMs;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const grammars_1 = require("../extraction/grammars");
+const directory_1 = require("../directory");
+const HARMONY_PROFILE = 'build-profile.json5';
+/** Dirs skipped during the bounded source walk (names only). */
+const SKIP_DIR_NAMES = new Set([
+    'node_modules',
+    'oh_modules',
+    '.git',
+    '.hvigor',
+    '.preview',
+    '.cxx',
+    'dist',
+    'build',
+    'out',
+    'coverage',
+    'vendor',
+    'Pods',
+    'DerivedData',
+    '__pycache__',
+    '.venv',
+    'venv',
+    'target',
+    '.gradle',
+    'obj',
+]);
+const DEFAULT_MAX_DIRS = 4000;
+const DEFAULT_MAX_DEPTH = 8;
+/**
+ * True when `root` already looks like a project HomeGraph should index.
+ * Short-circuits on root `build-profile.json5`, else bounded BFS for any
+ * {@link isSourceFile} hit. Ignores `.homegraph*` and common build/vendor dirs.
+ */
+function isIndexableRoot(rootDir, opts) {
+    const root = path.resolve(rootDir);
+    let st;
+    try {
+        st = fs.statSync(root);
+    }
+    catch {
+        return false;
+    }
+    if (!st.isDirectory())
+        return false;
+    if (fs.existsSync(path.join(root, HARMONY_PROFILE)))
+        return true;
+    const maxDirs = opts?.maxDirs ?? DEFAULT_MAX_DIRS;
+    const maxDepth = opts?.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const queue = [{ dir: root, depth: 0 }];
+    let dirsSeen = 0;
+    while (queue.length > 0 && dirsSeen < maxDirs) {
+        const { dir, depth } = queue.shift();
+        dirsSeen += 1;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const ent of entries) {
+            const name = ent.name;
+            if (name === '.' || name === '..')
+                continue;
+            if ((0, directory_1.isHomeGraphDataDir)(name) || SKIP_DIR_NAMES.has(name))
+                continue;
+            const full = path.join(dir, name);
+            if (ent.isDirectory()) {
+                if (depth + 1 <= maxDepth)
+                    queue.push({ dir: full, depth: depth + 1 });
+                continue;
+            }
+            if (ent.isFile() && (0, grammars_1.isSourceFile)(full))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Parse `HOMEGRAPH_DEFER_PROBE_MS`. Default **60000**.
+ * `0` disables the timer (tool-call kick only). Invalid → default.
+ * Clamp: 0, or 1000ms … 10min.
+ */
+function parseDeferProbeMs(raw) {
+    if (raw === undefined || !raw.trim())
+        return 60_000;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || !Number.isInteger(n))
+        return 60_000;
+    if (n === 0)
+        return 0;
+    if (n < 1000 || n > 10 * 60 * 1000)
+        return 60_000;
+    return n;
+}
+//# sourceMappingURL=indexable-root.js.map

package/dist/mcp/liveness-watchdog.d.ts

@@ -7,6 +7,11 @@ export declare const DEFAULT_WATCHDOG_TIMEOUT_MS = 60000;
  * beyond any legitimate statement). 10× the 60s default ⇒ 10 minutes.
  */
 export declare const PROGRESS_CAP_MULTIPLIER = 10;
+/**
+ * Spec 0047: liveness watchdog is opt-in.
+ * Armed only when `HOMEGRAPH_WATCHDOG` is truthy and `HOMEGRAPH_NO_WATCHDOG` is not.
+ */
+export declare function isLivenessWatchdogEnabled(env?: NodeJS.ProcessEnv): boolean;
 /** Parse the timeout env, falling back to the default for missing/invalid values. */
 export declare function parseWatchdogTimeoutMs(raw: string | undefined, fallback?: number): number;
 /** Derive a heartbeat cadence that emits several beats inside the timeout window. */
@@ -42,7 +47,7 @@ export declare function installMainThreadWatchdog(options?: WatchdogOptions): Wa
  * resume function. Nested calls refcount; a `stop()` while suspended cancels
  * the pending re-arm.
  *
- * No-op when nothing is armed (tests, `HOMEGRAPH_NO_WATCHDOG`, library embeds).
+ * No-op when nothing is armed (tests, default-off Spec 0047, `HOMEGRAPH_NO_WATCHDOG`, library embeds).
  */
 export declare function suspendLivenessWatchdog(): () => void;
 /**

package/dist/mcp/liveness-watchdog.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PROGRESS_CAP_MULTIPLIER = exports.DEFAULT_WATCHDOG_TIMEOUT_MS = void 0;
+exports.isLivenessWatchdogEnabled = isLivenessWatchdogEnabled;
 exports.parseWatchdogTimeoutMs = parseWatchdogTimeoutMs;
 exports.deriveCheckIntervalMs = deriveCheckIntervalMs;
 exports.installMainThreadWatchdog = installMainThreadWatchdog;
@@ -73,8 +74,9 @@ exports.runWithoutLivenessWatchdog = runWithoutLivenessWatchdog;
  * (off-thread) and the daemon's indexing shells out to a child process, so the
  * daemon's main thread only ever does fast, bounded work. The default timeout
  * is ~300× the 5h #850 wedge shorter, yet far longer than any legitimate
- * main-thread block. Opt out with `HOMEGRAPH_NO_WATCHDOG=1`; tune with
- * `HOMEGRAPH_WATCHDOG_TIMEOUT_MS`.
+ * main-thread block. Spec 0047: **opt in** with `HOMEGRAPH_WATCHDOG=1` (default
+ * off for product / DevEco concurrent init); `HOMEGRAPH_NO_WATCHDOG=1` still
+ * forces off. Tune with `HOMEGRAPH_WATCHDOG_TIMEOUT_MS`.
  *
  * **Disk-progress deferral (`progressPaths`).** The CLI `index`/`init` path is
  * different: it runs the SQLite store on this thread, and one long synchronous
@@ -118,6 +120,15 @@ function isEnvTruthy(raw) {
         return false;
     return ['1', 'true', 'yes', 'on'].includes(raw.trim().toLowerCase());
 }
+/**
+ * Spec 0047: liveness watchdog is opt-in.
+ * Armed only when `HOMEGRAPH_WATCHDOG` is truthy and `HOMEGRAPH_NO_WATCHDOG` is not.
+ */
+function isLivenessWatchdogEnabled(env = process.env) {
+    if (isEnvTruthy(env.HOMEGRAPH_NO_WATCHDOG))
+        return false;
+    return isEnvTruthy(env.HOMEGRAPH_WATCHDOG);
+}
 /** Parse the timeout env, falling back to the default for missing/invalid values. */
 function parseWatchdogTimeoutMs(raw, fallback = exports.DEFAULT_WATCHDOG_TIMEOUT_MS) {
     if (raw === undefined)
@@ -153,7 +164,7 @@ const capMs = Number(process.argv[3]);
 const progressPaths = process.argv.slice(4);
 const secs = Math.round(timeoutMs / 1000);
 function kill(extra) {
-  try { fs.writeSync(2, Buffer.from('[HomeGraph] Main thread unresponsive for ~' + secs + 's' + (extra || '') + ' — killing the wedged process so a fresh one can start (#850). Disable with HOMEGRAPH_NO_WATCHDOG=1.\\n')); } catch (e) {}
+  try { fs.writeSync(2, Buffer.from('[HomeGraph] Main thread unresponsive for ~' + secs + 's' + (extra || '') + ' — killing the wedged process so a fresh one can start (#850). Disable with HOMEGRAPH_NO_WATCHDOG=1 (default off; enable with HOMEGRAPH_WATCHDOG=1).\\n')); } catch (e) {}
   try { process.kill(parentPid, 'SIGKILL'); } catch (e) {}
   process.exit(0);
 }
@@ -318,7 +329,8 @@ function rearmFromOptions(options) {
  * current generation.
  */
 function installMainThreadWatchdog(options = {}) {
-    if (isEnvTruthy(process.env.HOMEGRAPH_NO_WATCHDOG))
+    // Spec 0047: default off — set HOMEGRAPH_WATCHDOG=1 to arm.
+    if (!isLivenessWatchdogEnabled())
         return null;
     // Replace any prior generation (including a mid-suspend pending re-arm).
     suspendDepth = 0;
@@ -336,7 +348,7 @@ function installMainThreadWatchdog(options = {}) {
  * resume function. Nested calls refcount; a `stop()` while suspended cancels
  * the pending re-arm.
  *
- * No-op when nothing is armed (tests, `HOMEGRAPH_NO_WATCHDOG`, library embeds).
+ * No-op when nothing is armed (tests, default-off Spec 0047, `HOMEGRAPH_NO_WATCHDOG`, library embeds).
  */
 function suspendLivenessWatchdog() {
     suspendDepth++;

package/dist/mcp/locate-contract.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Spec 0044 — explore locate contract helpers (Located / Miss / Partial,
+ * literal-first demotion of log/toast spines, filename≠declaration hint,
+ * depth-fuse exemption for already-located symbols).
+ */
+import type { ExploreEmission, ExploreCallRecord, ExploreProjectState } from './explore-session-state';
+export type LocateOutcome = 'located' | 'partial' | 'miss';
+/** Marker strings (idempotent checks). */
+export declare const LOCATED_MARKER = "**Located**";
+export declare const MISS_MARKER = "**Miss**";
+export declare const FILENAME_DECL_MISMATCH_MARKER = "Filename does not match primary declaration";
+/** Query explicitly names a log/toast API — then those nodes may stay on the spine. */
+export declare function queryNamesLogOrToast(query: string): boolean;
+export declare function isLogOrToastSpineName(name: string): boolean;
+/** Demote log/toast when the user did not ask for them. */
+export declare function shouldDemoteLogToastSpine(name: string, query: string): boolean;
+/**
+ * Classify locate outcome for explore (Spec 0044 §8–9).
+ * Exact anchor / literal witness beats fuzzy-only FTS.
+ */
+export declare function classifyLocateOutcome(opts: {
+    hasExactAnchorHit: boolean;
+    hasLiteralWitness: boolean;
+    hasFullDeclarations: boolean;
+    missingStaticRelation: boolean;
+    budgetPartial: boolean;
+}): LocateOutcome;
+export declare function formatLocatedBanner(): string;
+export declare function formatPartialBanner(): string;
+/** Miss: paths only, no source bodies. */
+export declare function formatMissBanner(candidatePaths: readonly string[]): string;
+/**
+ * When file basename (sans extension) ≠ primary declaration name.
+ * Returns null when names match or inputs are empty.
+ */
+export declare function formatFilenameDeclarationMismatch(filePath: string, primaryDeclName: string | null | undefined): string | null;
+/** Names recorded on the latest counted explore emission. */
+export declare function locatedNamesFromEmission(emission: ExploreEmission | ExploreCallRecord | null | undefined): string[];
+export declare function symbolMatchesLocatedNames(symbol: string | undefined, locatedNames: readonly string[]): boolean;
+/**
+ * Spec 0044 §10.2 — do not depth-fuse-refuse a symbol already present on the
+ * latest explore locate list (even after Partial spent its one generic drill).
+ */
+export declare function shouldExemptDepthFuseForLocatedSymbol(prior: ExploreProjectState | null | undefined, symbol: string | undefined): boolean;
+/** Strip CJK→ASCII synonym seeds when Miss-bound (Spec 0044 §9). */
+export declare function shouldSuppressSynonymExpansion(opts: {
+    hasExactAnchorHit: boolean;
+    hasLiteralWitness: boolean;
+}): boolean;
+//# sourceMappingURL=locate-contract.d.ts.map

package/dist/mcp/locate-contract.js

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * Spec 0044 — explore locate contract helpers (Located / Miss / Partial,
+ * literal-first demotion of log/toast spines, filename≠declaration hint,
+ * depth-fuse exemption for already-located symbols).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FILENAME_DECL_MISMATCH_MARKER = exports.MISS_MARKER = exports.LOCATED_MARKER = void 0;
+exports.queryNamesLogOrToast = queryNamesLogOrToast;
+exports.isLogOrToastSpineName = isLogOrToastSpineName;
+exports.shouldDemoteLogToastSpine = shouldDemoteLogToastSpine;
+exports.classifyLocateOutcome = classifyLocateOutcome;
+exports.formatLocatedBanner = formatLocatedBanner;
+exports.formatPartialBanner = formatPartialBanner;
+exports.formatMissBanner = formatMissBanner;
+exports.formatFilenameDeclarationMismatch = formatFilenameDeclarationMismatch;
+exports.locatedNamesFromEmission = locatedNamesFromEmission;
+exports.symbolMatchesLocatedNames = symbolMatchesLocatedNames;
+exports.shouldExemptDepthFuseForLocatedSymbol = shouldExemptDepthFuseForLocatedSymbol;
+exports.shouldSuppressSynonymExpansion = shouldSuppressSynonymExpansion;
+const explore_session_state_1 = require("./explore-session-state");
+const explore_repeat_guard_1 = require("./explore-repeat-guard");
+/** Marker strings (idempotent checks). */
+exports.LOCATED_MARKER = '**Located**';
+exports.MISS_MARKER = '**Miss**';
+exports.FILENAME_DECL_MISMATCH_MARKER = 'Filename does not match primary declaration';
+const LOG_TOAST_NAME_RE = /^(?:Logger|Hilog|HiLog|Toast|promptAction|log(?:Info|Error|Warn|Debug|Fatal)?|hilog)$/i;
+/** Query explicitly names a log/toast API — then those nodes may stay on the spine. */
+function queryNamesLogOrToast(query) {
+    return /\b(?:Logger|hilog|HiLog|Toast|promptAction|logInfo|logError|logWarn|logDebug)\b/i.test(query)
+        || /日志|弹窗|吐司/.test(query);
+}
+function isLogOrToastSpineName(name) {
+    return LOG_TOAST_NAME_RE.test(name.trim());
+}
+/** Demote log/toast when the user did not ask for them. */
+function shouldDemoteLogToastSpine(name, query) {
+    return isLogOrToastSpineName(name) && !queryNamesLogOrToast(query);
+}
+/**
+ * Classify locate outcome for explore (Spec 0044 §8–9).
+ * Exact anchor / literal witness beats fuzzy-only FTS.
+ */
+function classifyLocateOutcome(opts) {
+    if (!opts.hasExactAnchorHit && !opts.hasLiteralWitness)
+        return 'miss';
+    if (opts.budgetPartial || opts.missingStaticRelation)
+        return 'partial';
+    if (opts.hasFullDeclarations && (opts.hasExactAnchorHit || opts.hasLiteralWitness)) {
+        return 'located';
+    }
+    return 'partial';
+}
+function formatLocatedBanner() {
+    return (`> ${exports.LOCATED_MARKER} — exact anchor declaration(s) are in this reply. `
+        + 'Reuse them; do **not** Grep the same symbol names again. '
+        + 'Runtime behavior may still need validation after edits.');
+}
+function formatPartialBanner() {
+    return ('> **Partial** — evidence is incomplete (missing relation or budget). '
+        + 'Next: `homegraph_node` / `homegraph_usages` / `homegraph_search` for the named gap — '
+        + 'do **not** Grep the same symbol names already shown.');
+}
+/** Miss: paths only, no source bodies. */
+function formatMissBanner(candidatePaths) {
+    const paths = candidatePaths
+        .map((p) => p.replace(/\\/g, '/').trim())
+        .filter(Boolean)
+        .slice(0, 12);
+    const list = paths.length
+        ? paths.map((p) => `- \`${p}\``).join('\n')
+        : '- _(no fuzzy path candidates)_';
+    return [
+        `> ${exports.MISS_MARKER} — no exact in-repo anchor or literal witness. Source bodies omitted.`,
+        'Fuzzy candidate paths (no source):',
+        list,
+        'Next: `homegraph_search` with a more precise symbol, file basename, or quoted UI label.',
+    ].join('\n');
+}
+/**
+ * When file basename (sans extension) ≠ primary declaration name.
+ * Returns null when names match or inputs are empty.
+ */
+function formatFilenameDeclarationMismatch(filePath, primaryDeclName) {
+    if (!primaryDeclName?.trim())
+        return null;
+    const base = filePath.replace(/\\/g, '/').split('/').pop() ?? '';
+    const stem = base.replace(/\.[^.]+$/, '');
+    if (!stem)
+        return null;
+    const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, '');
+    if (norm(stem) === norm(primaryDeclName))
+        return null;
+    return (`> ⚠ ${exports.FILENAME_DECL_MISMATCH_MARKER}: file \`${stem}\` vs \`${primaryDeclName.trim()}\` — `
+        + 'prefer the declaration name for edits and follow-up queries.');
+}
+/** Names recorded on the latest counted explore emission. */
+function locatedNamesFromEmission(emission) {
+    if (!emission?.locatedNodes?.length)
+        return [];
+    const out = new Set();
+    for (const n of emission.locatedNodes) {
+        if (n?.name)
+            out.add(n.name);
+        if (n?.qualifiedName) {
+            out.add(n.qualifiedName);
+            const leaf = n.qualifiedName.split(/[.::]/).pop();
+            if (leaf)
+                out.add(leaf);
+        }
+    }
+    return [...out];
+}
+function symbolMatchesLocatedNames(symbol, locatedNames) {
+    const raw = symbol?.trim();
+    if (!raw || locatedNames.length === 0)
+        return false;
+    const needle = raw.toLowerCase();
+    const leaf = needle.split(/[.::]/).pop() ?? needle;
+    for (const n of locatedNames) {
+        const ln = n.toLowerCase();
+        if (ln === needle || ln === leaf)
+            return true;
+        if (ln.endsWith(`.${leaf}`) || ln.endsWith(`::${leaf}`))
+            return true;
+    }
+    return false;
+}
+/**
+ * Spec 0044 §10.2 — do not depth-fuse-refuse a symbol already present on the
+ * latest explore locate list (even after Partial spent its one generic drill).
+ */
+function shouldExemptDepthFuseForLocatedSymbol(prior, symbol) {
+    const last = (0, explore_repeat_guard_1.latestCountedExplore)(prior);
+    if (!last)
+        return false;
+    // Closed explores already skip the fuse; exemption matters for Partial/Miss.
+    if ((0, explore_session_state_1.inferExploreEvidenceStatus)(last) === 'complete')
+        return false;
+    return symbolMatchesLocatedNames(symbol, locatedNamesFromEmission(last));
+}
+/** Strip CJK→ASCII synonym seeds when Miss-bound (Spec 0044 §9). */
+function shouldSuppressSynonymExpansion(opts) {
+    return !opts.hasExactAnchorHit && !opts.hasLiteralWitness;
+}
+//# sourceMappingURL=locate-contract.js.map