homegraph 1.5.8 → 1.6.0

package/dist/runtime-log.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Spec 0046 — coarse lifecycle lines + optional HOMEGRAPH_DEBUG tool traces.
+ *
+ * Sink: `.homegraph/daemon.log` (same file daemon stdio already uses) when a
+ * project root is known; always mirror to stderr. Soft-rotate at ~5 MiB.
+ */
+/** Soft rotate threshold for `.homegraph/daemon.log` (Spec 0046). */
+export declare const DAEMON_LOG_MAX_BYTES: number;
+/** Truncate free-text fields in log context (queries, messages). */
+export declare const RUNTIME_LOG_TEXT_MAX = 80;
+export type RuntimeLogLevel = 'info' | 'warn' | 'error' | 'debug';
+export declare function getDaemonLogPath(projectRoot: string): string;
+/** Compact `k=v` pairs; strings truncated; omit undefined/null. */
+export declare function formatRuntimeLogContext(context?: Record<string, unknown>): string;
+/**
+ * Stable one-line format (Spec 0046):
+ * `ISO8601Z [HomeGraph] <level> <event> key=value …`
+ */
+export declare function formatRuntimeLogLine(level: RuntimeLogLevel, event: string, context?: Record<string, unknown>, now?: Date): string;
+/** Rename oversized log to `daemon.log.1` (overwrite prior `.1`). */
+export declare function maybeRotateDaemonLog(logPath: string, maxBytes?: number): void;
+/**
+ * Append one line to `.homegraph/daemon.log` under `projectRoot`.
+ * Never throws to callers — logging must not break MCP.
+ */
+export declare function appendProjectDaemonLog(projectRoot: string | null | undefined, line: string): void;
+/**
+ * Always-on coarse event: stderr + daemon.log when `projectRoot` is set.
+ */
+export declare function logLifecycle(event: string, context?: Record<string, unknown> & {
+    projectRoot?: string;
+}): void;
+/**
+ * Always-on error-shaped lifecycle (still info-level event name namespace).
+ */
+export declare function logLifecycleError(event: string, context?: Record<string, unknown> & {
+    projectRoot?: string;
+}): void;
+/** True when fine-grained tool traces should emit (Spec 0046). */
+export declare function isHomegraphDebugEnabled(): boolean;
+/**
+ * Tool-call summary — only when `HOMEGRAPH_DEBUG` is set.
+ * Does not dump full query/body; truncates query text.
+ */
+export declare function logToolDebug(toolName: string, context: {
+    projectRoot?: string;
+    durationMs: number;
+    isError?: boolean;
+    evidenceStatus?: string;
+    query?: string;
+}): void;
+//# sourceMappingURL=runtime-log.d.ts.map

package/dist/runtime-log.js

@@ -0,0 +1,199 @@
+"use strict";
+/**
+ * Spec 0046 — coarse lifecycle lines + optional HOMEGRAPH_DEBUG tool traces.
+ *
+ * Sink: `.homegraph/daemon.log` (same file daemon stdio already uses) when a
+ * project root is known; always mirror to stderr. Soft-rotate at ~5 MiB.
+ */
+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.RUNTIME_LOG_TEXT_MAX = exports.DAEMON_LOG_MAX_BYTES = void 0;
+exports.getDaemonLogPath = getDaemonLogPath;
+exports.formatRuntimeLogContext = formatRuntimeLogContext;
+exports.formatRuntimeLogLine = formatRuntimeLogLine;
+exports.maybeRotateDaemonLog = maybeRotateDaemonLog;
+exports.appendProjectDaemonLog = appendProjectDaemonLog;
+exports.logLifecycle = logLifecycle;
+exports.logLifecycleError = logLifecycleError;
+exports.isHomegraphDebugEnabled = isHomegraphDebugEnabled;
+exports.logToolDebug = logToolDebug;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const directory_1 = require("./directory");
+/** Soft rotate threshold for `.homegraph/daemon.log` (Spec 0046). */
+exports.DAEMON_LOG_MAX_BYTES = 5 * 1024 * 1024;
+/** Truncate free-text fields in log context (queries, messages). */
+exports.RUNTIME_LOG_TEXT_MAX = 80;
+function getDaemonLogPath(projectRoot) {
+    return path.join((0, directory_1.getHomeGraphDir)(projectRoot), 'daemon.log');
+}
+/** Compact `k=v` pairs; strings truncated; omit undefined/null. */
+function formatRuntimeLogContext(context) {
+    if (!context)
+        return '';
+    const parts = [];
+    for (const [key, raw] of Object.entries(context)) {
+        if (raw === undefined || raw === null)
+            continue;
+        let value;
+        if (typeof raw === 'string') {
+            value = raw.length > exports.RUNTIME_LOG_TEXT_MAX
+                ? `${raw.slice(0, exports.RUNTIME_LOG_TEXT_MAX)}…`
+                : raw;
+        }
+        else if (typeof raw === 'number' || typeof raw === 'boolean') {
+            value = String(raw);
+        }
+        else {
+            try {
+                const json = JSON.stringify(raw);
+                value = json.length > exports.RUNTIME_LOG_TEXT_MAX
+                    ? `${json.slice(0, exports.RUNTIME_LOG_TEXT_MAX)}…`
+                    : json;
+            }
+            catch {
+                value = String(raw);
+            }
+        }
+        // Keep one token: spaces → _
+        value = value.replace(/\s+/g, '_');
+        parts.push(`${key}=${value}`);
+    }
+    return parts.length ? ` ${parts.join(' ')}` : '';
+}
+/**
+ * Stable one-line format (Spec 0046):
+ * `ISO8601Z [HomeGraph] <level> <event> key=value …`
+ */
+function formatRuntimeLogLine(level, event, context, now = new Date()) {
+    const iso = now.toISOString();
+    return `${iso} [HomeGraph] ${level} ${event}${formatRuntimeLogContext(context)}`;
+}
+/** Rename oversized log to `daemon.log.1` (overwrite prior `.1`). */
+function maybeRotateDaemonLog(logPath, maxBytes = exports.DAEMON_LOG_MAX_BYTES) {
+    try {
+        const st = fs.statSync(logPath);
+        if (st.size < maxBytes)
+            return;
+        const rotated = `${logPath}.1`;
+        try {
+            fs.unlinkSync(rotated);
+        }
+        catch {
+            /* no prior .1 */
+        }
+        fs.renameSync(logPath, rotated);
+    }
+    catch {
+        /* missing or unreadable — append will create */
+    }
+}
+/**
+ * Append one line to `.homegraph/daemon.log` under `projectRoot`.
+ * Never throws to callers — logging must not break MCP.
+ */
+function appendProjectDaemonLog(projectRoot, line) {
+    if (!projectRoot)
+        return;
+    try {
+        const dir = (0, directory_1.getHomeGraphDir)(projectRoot);
+        // Spec 0049: never create `.homegraph/` solely to write a log line — that
+        // recreated the empty-workspace PROJECT_EXISTS trap for DevEco create.
+        if (!fs.existsSync(dir))
+            return;
+        const logPath = path.join(dir, 'daemon.log');
+        maybeRotateDaemonLog(logPath);
+        fs.appendFileSync(logPath, line.endsWith('\n') ? line : `${line}\n`, 'utf8');
+    }
+    catch {
+        /* ignore I/O errors */
+    }
+}
+function writeStderr(line) {
+    try {
+        fs.writeSync(2, `${line}\n`);
+    }
+    catch {
+        /* ignore */
+    }
+}
+/**
+ * Always-on coarse event: stderr + daemon.log when `projectRoot` is set.
+ */
+function logLifecycle(event, context) {
+    const { projectRoot, ...rest } = context ?? {};
+    const line = formatRuntimeLogLine('info', event, {
+        ...(projectRoot ? { root: projectRoot } : {}),
+        ...rest,
+    });
+    writeStderr(line);
+    appendProjectDaemonLog(projectRoot, line);
+}
+/**
+ * Always-on error-shaped lifecycle (still info-level event name namespace).
+ */
+function logLifecycleError(event, context) {
+    const { projectRoot, ...rest } = context ?? {};
+    const line = formatRuntimeLogLine('error', event, {
+        ...(projectRoot ? { root: projectRoot } : {}),
+        ...rest,
+    });
+    writeStderr(line);
+    appendProjectDaemonLog(projectRoot, line);
+}
+/** True when fine-grained tool traces should emit (Spec 0046). */
+function isHomegraphDebugEnabled() {
+    const v = process.env.HOMEGRAPH_DEBUG?.trim();
+    if (!v)
+        return false;
+    return v !== '0' && v.toLowerCase() !== 'false' && v.toLowerCase() !== 'off';
+}
+/**
+ * Tool-call summary — only when `HOMEGRAPH_DEBUG` is set.
+ * Does not dump full query/body; truncates query text.
+ */
+function logToolDebug(toolName, context) {
+    if (!isHomegraphDebugEnabled())
+        return;
+    const { projectRoot, query, ...rest } = context;
+    const line = formatRuntimeLogLine('debug', `tool.${toolName}`, {
+        ...(projectRoot ? { root: projectRoot } : {}),
+        ...rest,
+        ...(query !== undefined ? { query } : {}),
+    });
+    writeStderr(line);
+    appendProjectDaemonLog(projectRoot, line);
+}
+//# sourceMappingURL=runtime-log.js.map

package/dist/search/query-plan-provider.js

@@ -75,7 +75,8 @@ function validateModelQueryPlan(value, local, options) {
     const v = value;
     const taskContext = (0, query_plan_1.normalizeQueryPlanTaskContext)(options.taskContext ?? local.taskContext);
     const context = taskContext ? `\n${taskContext}` : '';
-    const originalConstraints = local.originalQuery + context;
+    // Spec 0042: taskContext is retained on the plan for planner/literals, but must
+    // not be concatenated into the lexical canonicalQuery / FTS string.
     const allowsOverview = (0, query_plan_1.queryExplicitlyRequestsProjectMap)(local.originalQuery);
     const proposedRelation = relation(v.relation);
     const proposedSourceScope = sourceScope(v.sourceScope) ?? 'local';
@@ -152,7 +153,7 @@ function validateModelQueryPlan(value, local, options) {
     const retainedAnchors = normalized.anchors;
     searchTerms = [...new Set([...searchTerms, ...normalized.terms])].slice(0, 24);
     const canonicalQuery = (0, query_plan_1.adaptQueryPlanQuery)(downgradedOverview
-        ? originalConstraints : `${originalConstraints}\n${rewrite}`, chosenIntent, retainedAnchors, proposedRelation);
+        ? local.originalQuery : `${local.originalQuery}\n${rewrite}`, chosenIntent, retainedAnchors, proposedRelation);
     if (canonicalQuery.length > 9000)
         throw new Error('input_too_long');
     // Every compiled step retains originalQuery/taskContext as constraints, not

package/dist/search/query-plan.js

@@ -58,11 +58,6 @@ exports.QUERY_SOURCE_SCOPES = ['local', 'sdk', 'all'];
 function normalizeQueryPlanTaskContext(value) {
     return typeof value === 'string' ? value.trim().slice(0, 4000) || undefined : undefined;
 }
-function withTaskContext(query, taskContext) {
-    // This string reaches lexical retrieval. Framework prose such as "code evidence"
-    // would become unrelated symbol seeds, so concatenate only the supplied data.
-    return taskContext && taskContext !== query ? `${query}\n${taskContext}` : query;
-}
 /** A host's original task cannot be replaced by an agent's abbreviated focus. */
 function mergeQueryPlanTaskContext(original, focus) {
     const parts = [normalizeQueryPlanTaskContext(original), normalizeQueryPlanTaskContext(focus)]
@@ -182,14 +177,19 @@ function extractQueryPlanLiteralTexts(query) {
 function buildRuleQueryPlan(query, originalTaskContext) {
     const started = Date.now();
     const taskContext = normalizeQueryPlanTaskContext(originalTaskContext);
-    const canonicalQuery = withTaskContext(query, taskContext);
+    // Spec 0042: retrieval string is the user query only — never append taskContext.
+    const canonicalQuery = query;
     const features = queryPlanFeatures(canonicalQuery);
     const route = localRoute(canonicalQuery, features);
     const intent = route === 'usages' || route === 'modules' || route === 'native'
         ? route : features.queryAsCrossModuleFlowSurvey ? 'flow' : 'general';
-    const anchors = [...new Set([...extractQueryPlanAnchors(query),
-            ...extractQueryPlanAnchors(taskContext ?? '')])].slice(0, 16);
-    const literalTexts = extractQueryPlanLiteralTexts(canonicalQuery);
+    // Anchors for retrieval come from the query only (taskContext prose must not seed FTS).
+    const anchors = [...new Set(extractQueryPlanAnchors(query))].slice(0, 16);
+    const literalTexts = [...new Set([
+            ...extractQueryPlanLiteralTexts(query),
+            ...extractQueryPlanLiteralTexts(taskContext ?? ''),
+        ])].slice(0, 8);
+    const sourceScope = shape.resolveExploreSourceScope(query);
     return {
         version: exports.QUERY_PLAN_VERSION,
         originalQuery: query,
@@ -200,8 +200,11 @@ function buildRuleQueryPlan(query, originalTaskContext) {
         anchors,
         ...(literalTexts.length ? { literalTexts } : {}),
         searchTerms: shape.extractSearchTerms(canonicalQuery, { stems: false }).slice(0, 24),
+        ...(sourceScope !== 'all' ? { sourceScope } : {}),
         steps: [{ id: 's1', query, intent, anchors: [...anchors],
-                ...(literalTexts.length ? { literalTexts: [...literalTexts] } : {}), dependsOn: [] }],
+                ...(literalTexts.length ? { literalTexts: [...literalTexts] } : {}),
+                ...(sourceScope !== 'all' ? { sourceScope } : {}),
+                dependsOn: [] }],
         features,
         source: 'rules',
         confidence: route !== 'general' || anchors.length ? 1 : 0.5,
@@ -293,20 +296,18 @@ function compileQueryPlanStep(plan, step, resolvedAnchors = []) {
     const stepIntent = intentForQueryRelation(downgradedOverview ? 'general' : step.intent, relation);
     const query = downgradedOverview ? plan.originalQuery : step.query;
     const literalTexts = step.literalTexts ?? (plan.steps.length === 1 ? plan.literalTexts : undefined) ?? [];
-    const sourceScope = step.sourceScope ?? plan.sourceScope;
-    // Scope and negations remain losslessly in originalQuery/taskContext for the
-    // executor and cache. Repeating that prose here erases the step's focus.
-    // A planner's English explanation is not source text. Only its typed slots
-    // become seeds; this prevents a verb such as "locate" matching an SDK method.
-    // Legacy/malformed seedless steps retain the USER's query, never planner prose.
+    // Spec 0042: non-LLM retrieval must not concatenate taskContext into the FTS string.
+    // Planner prose stays out of seeds; only typed slots (anchors/searchTerms/literalTexts) retrieve.
     const seeds = [...new Set([...anchors, ...(step.searchTerms ?? []), ...literalTexts])];
     const retrievalQuery = plan.source === 'llm'
-        ? seeds.join(' ') || plan.originalQuery : withTaskContext(query, plan.taskContext);
+        ? seeds.join(' ') || plan.originalQuery : query;
     const canonicalQuery = plan.source === 'rules' && stepIntent === 'general'
         ? retrievalQuery : adaptQueryPlanQuery(retrievalQuery, stepIntent, anchors, relation);
     const searchTerms = plan.source === 'llm' && seeds.length
         ? seeds.slice(0, 24) : [...new Set([...anchors, ...(step.searchTerms ?? []),
             ...shape.extractSearchTerms(retrievalQuery, { stems: false })])].slice(0, 24);
+    const resolvedScope = step.sourceScope ?? plan.sourceScope
+        ?? shape.resolveExploreSourceScope(plan.originalQuery);
     return {
         ...plan,
         canonicalQuery,
@@ -316,8 +317,9 @@ function compileQueryPlanStep(plan, step, resolvedAnchors = []) {
         searchTerms,
         literalTexts,
         relation,
-        sourceScope,
-        steps: [{ ...step, intent: stepIntent, anchors, literalTexts, sourceScope, dependsOn: [] }],
+        sourceScope: resolvedScope === 'all' ? undefined : resolvedScope,
+        steps: [{ ...step, intent: stepIntent, anchors, literalTexts,
+                sourceScope: resolvedScope === 'all' ? undefined : resolvedScope, dependsOn: [] }],
         features: queryPlanFeatures(canonicalQuery),
     };
 }

package/dist/search/query-utils.d.ts

@@ -19,6 +19,19 @@ export interface QueryMemberAccess {
  * File basenames from queries — supports `Foo.ets` and path-style `common\\constants.ets`.
  */
 export declare function extractFileBasenamesFromQuery(query: string): string[];
+export declare function extractInRepoLocateAnchors(query: string): string[];
+/** Query explicitly asks for SDK / Kit / d.ts surface (must not force sourceScope=local). */
+export declare function queryExplicitlyRequestsSdkScope(query: string): boolean;
+/**
+ * Spec 0042 — default explore retrieval scope.
+ * `local` when the query has in-repo locate signals; never override an explicit SDK ask.
+ */
+export declare function resolveExploreSourceScope(query: string, planScope?: 'local' | 'sdk' | 'all'): 'local' | 'sdk' | 'all';
+/** MCP-visible graph noise (ArkAnalyzer virtual entry / anonymous methods). */
+export declare function isMcpNoiseNode(node: {
+    name: string;
+    filePath: string;
+}): boolean;
 /**
  * Path-shaped anchors from a query — `feature/foo`, `staticcommon/launchercommon`.
  */

package/dist/search/query-utils.js

@@ -41,6 +41,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.IMPLEMENTATION_ENTRY_NAME_RE = exports.GENERIC_VERB_ANCHOR_NOISE = exports.STOP_WORDS = exports.FRAMEWORK_UI_DECORATOR_NAMES = exports.QUERY_SOURCE_FILE_EXT = void 0;
 exports.normalizeNameToken = normalizeNameToken;
 exports.extractFileBasenamesFromQuery = extractFileBasenamesFromQuery;
+exports.extractInRepoLocateAnchors = extractInRepoLocateAnchors;
+exports.queryExplicitlyRequestsSdkScope = queryExplicitlyRequestsSdkScope;
+exports.resolveExploreSourceScope = resolveExploreSourceScope;
+exports.isMcpNoiseNode = isMcpNoiseNode;
 exports.extractPathSegmentsFromQuery = extractPathSegmentsFromQuery;
 exports.queryMentionsCodeContext = queryMentionsCodeContext;
 exports.extractKitModuleNamesFromQuery = extractKitModuleNamesFromQuery;
@@ -181,6 +185,66 @@ function extractFileBasenamesFromQuery(query) {
     }
     return [...basenames];
 }
+/**
+ * Spec 0042 — PascalCase / CamelCase identifiers (≥8 chars) for in-repo locate seeding.
+ * Excludes short generic English tokens that pollute FTS when taken from taskContext-like prose.
+ */
+const IN_REPO_LOCATE_BLACKLIST = new Set([
+    'page', 'view', 'component', 'input', 'target', 'size', 'button', 'text', 'index',
+    'main', 'app', 'data', 'type', 'item', 'list', 'info', 'name', 'value', 'state',
+    'props', 'build', 'export', 'import', 'class', 'struct', 'method', 'function',
+    'object', 'string', 'number', 'boolean', 'result', 'error', 'event', 'option',
+    'config', 'manager', 'service', 'helper', 'utils', 'common', 'layout', 'style',
+]);
+function extractInRepoLocateAnchors(query) {
+    const out = new Set();
+    for (const m of query.matchAll(/\b([A-Z][A-Za-z0-9]*[a-z][A-Za-z0-9]*|[A-Z][a-z]+[A-Z][A-Za-z0-9]*)\b/g)) {
+        const tok = m[1];
+        if (tok.length < 8)
+            continue;
+        if (IN_REPO_LOCATE_BLACKLIST.has(tok.toLowerCase()))
+            continue;
+        out.add(tok);
+    }
+    for (const base of extractFileBasenamesFromQuery(query)) {
+        if (base.length >= 2 && !IN_REPO_LOCATE_BLACKLIST.has(base.toLowerCase()))
+            out.add(base);
+    }
+    return [...out].slice(0, 6);
+}
+/** Query explicitly asks for SDK / Kit / d.ts surface (must not force sourceScope=local). */
+function queryExplicitlyRequestsSdkScope(query) {
+    return (/@kit\.|@ohos\./i.test(query)
+        || /\.d\.ts\b/i.test(query)
+        || /\b(?:HarmonyOS|OpenHarmony)\s+API\b/i.test(query)
+        || /\bSDK\s+(?:API|docs?|declaration|stub)s?\b/i.test(query)
+        || /\b(?:official\s+)?(?:API\s+)?reference\s+for\s+@/i.test(query));
+}
+/**
+ * Spec 0042 — default explore retrieval scope.
+ * `local` when the query has in-repo locate signals; never override an explicit SDK ask.
+ */
+function resolveExploreSourceScope(query, planScope) {
+    if (planScope === 'sdk')
+        return 'sdk';
+    if (queryExplicitlyRequestsSdkScope(query)) {
+        return planScope ?? 'all';
+    }
+    if (extractFileBasenamesFromQuery(query).length > 0
+        || extractInRepoLocateAnchors(query).length > 0
+        || /[\u4e00-\u9fff]{2,}/.test(query)
+        || queryAsCodeChangeOrientation(query)) {
+        return 'local';
+    }
+    return planScope ?? 'all';
+}
+/** MCP-visible graph noise (ArkAnalyzer virtual entry / anonymous methods). */
+function isMcpNoiseNode(node) {
+    const fp = node.filePath.replace(/\\/g, '/');
+    return (fp.includes('@dummy')
+        || node.name.startsWith('@dummy')
+        || /^%AM\d+/i.test(node.name));
+}
 /**
  * Path-shaped anchors from a query — `feature/foo`, `staticcommon/launchercommon`.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homegraph",
-  "version": "1.5.8",
+  "version": "1.6.0",
   "description": "Supercharge AI coding agents with semantic code intelligence — surgical context, fewer tool calls, faster answers. 100% local.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -36,7 +36,7 @@
   "license": "MIT",
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "arkanalyzer": "^1.0.92",
+    "arkanalyzer": "^1.0.94",
     "commander": "^14.0.3",
     "fast-string-width": "^3.0.2",
     "fast-wrap-ansi": "^0.2.0",