homegraph 1.5.5 → 1.5.7

package/CHANGELOG.md

@@ -10,6 +10,50 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [Unreleased]
 
 
+## [1.5.7] - 2026-09-09
+
+### Fixes
+
+- ArkTS indexing aligns with ArkAnalyzer `ClassCategory`: **object literals**, **type literals**, and **unions** are no longer stored as HomeGraph `class` nodes (they were inflating `graph_class` as `<Object$anon@N>` / `%AC*` under the file). Real classes — including true anonymous `ClassCategory.CLASS` — are unchanged. Re-index to refresh existing databases (Spec 0026).
+- Harmony multi-module ArkTS indexing: register **synthetic PROJECT modules** for ArkAnalyzer sources that sit outside `build-profile.json5` `srcPath` (e.g. ohrouter `HMRouterPlugin/**/*.ts`), so they enter the same `analyseByModule` pipeline instead of being skipped by both AA and tree-sitter. Incremental dirty mapping can target those synthetic roots. AA-persisted files now get truthful `files`/`nodes.language` by extension (`.ets`→`arkts`, `.ts`/`.d.ts`→`typescript`) instead of hard-coding `arkts` (Spec 0025).
+
+### Improvements
+
+- MCP `initialize` instructions: **single-file path-pinned edits → Read + edit, skip `homegraph_*`**; explore only when locate/cross-file is needed.
+- Explore **defers** (`Skip HomeGraph`, kind `path-pinned-edit`) when the query names one `…/File.ext` and is a code-change shape — avoids explore context tax on 082-style tasks.
+- Path scaffolding (`features/.../Foo.ets` + basename-as-Type) no longer counts as multi-anchor; `.ets`/`.ts`/… are not parsed as member access.
+
+### New Features
+
+- Experimental structured query planning for explore (Spec 0022): shared local routing features; optional, explicitly configured one-call model intent/decomposition/rephrase; bounded dependent retrieval with a shared deadline/output budget, validated anchors, worker propagation, context hints and direction-aware cache keys. Model failures fall back locally; compact diagnostic metadata includes planning usage/time and per-step coverage. No remote model calls by default.
+
+### Fixes
+
+- Grounded retrieval plans separate concise semantic concepts, verbatim UI text, exact anchors, source scope and relationship direction. Unanchored reference requests first discover source and retain the missing reference obligation. Bounded literal/resource lookup prioritizes local application evidence; rendering deduplicates same-source declarations and marks incomplete evidence. Repeat protection permits a bounded recovery for weak or changed evidence, and retrieval guidance no longer closes the coding task (Spec 0024).
+- The optional model planner now requests English step queries and short English semantic search terms, while preserving literal identifiers, paths and task constraints. This is a prompt-only refinement: retrieval, anchor validation, request count and budgets are unchanged (Spec 0023).
+- Model-planned explore steps now keep their own retrieval terms instead of repeating the whole task as search seeds. General/flow steps consume planned hints through full context retrieval; task constraints remain separate. Dependency candidates come only from displayed source declarations and retain node/file identity, with visible location receipts surviving shared-output trimming. Unseen fuzzy hits and inherited nodes no longer manufacture new bindings; default rule routes are unchanged (Spec 0023).
+- Explicit model planning now considers task-scoped natural-language queries before shape fast paths; exact symbol/path lookups remain cheap. Compact metadata explains planning eligibility, skip reasons and the original rule route, separately from provider failures (Spec 0023).
+- Planner instructions distinguish read-only evidence lookup from code-editing workflows and provide a compact JSON shape; more than three steps still fail closed, with a specific step-count diagnostic and no silent truncation or retry (Spec 0023).
+- After a model planning request fails, local fallback retrieval now uses the remaining shared deadline instead of the unbounded main-thread fast path; rule-only fast retrieval is unchanged (Spec 0023).
+- Query planning keeps framework labels out of lexical retrieval, preserves host-provided task constraints before agent shorthand, accepts bounded numeric step IDs, and supports an explicit planning timeout up to 10 seconds while reserving retrieval time within the shared deadline (default remains 5 seconds; Spec 0023).
+- Experimental query planning (Spec 0023): focused feature queries cannot be broadened into whole-project overviews by a model rewrite. Optional bounded task context preserves original actions/product scope across planning and cache keys; model-proposed broad anchors are discarded when an unauthorized overview is downgraded. Explicit project maps remain supported.
+- An explicit `HOMEGRAPH_MCP_TOOLS` selection now overrides default small-repository tool trimming, so requested specialized tools remain callable on small ArkTS projects (Spec 0023).
+
+- MCP first-tool guidance now gives `homegraph_usages`, `homegraph_modules`, and `homegraph_native` mutually exclusive priority for their narrow intents instead of simultaneously telling agents those questions are explore-first; general `homegraph_explore` remains the compatibility fallback and still auto-routes high-confidence shapes.
+
+## [1.5.6] - 2026-09-03
+
+### New Features
+
+- Product-host indexing (Spec 0021): `--auto-init` / `HOMEGRAPH_AUTO_INIT` creates `.homegraph/` when missing, builds a seconds-scale **project map** (modules → files in `project_modules` / `project_module_files`, schema v11), exposes read tool `homegraph_project`, then runs the full symbol index in a **detached** `homegraph index` child so the MCP stdio server stays responsive on large repos. `build_phase` metadata (`fast` / `indexing` / `full`) gates deep tools with success-shaped guidance while symbols are still building; opening an index heals a stuck phase after `index_state` completes.
+- Watch coalesce for product hosts: `HOMEGRAPH_WATCH_FIXED_WINDOW_MS` arms a fixed window on the **first** change (later edits in the window do not extend it), then incremental sync — e.g. DevEco sets `300000` (5 minutes).
+- ArkTS / ArkUI indexing stores the component `.id('…')` from ViewTree onto the matching custom `@Component` node as `arkuiId` (DB column `arkui_id`) — distinct from the graph primary key (Spec 0019).
+- ArkTS indexing fills `nodes.docstring` from ArkAnalyzer leading comments / JSDoc (Scene `enableLeadingComments` + `enableJSDoc`), so declaration docs join `nodes_fts` like other languages (Spec 0020).
+
+### Docs
+
+- `DEVELOPMENT.md` documents the **code-first Spec closing** order (§1.4.1): write Spec → verify code → check acceptance → CHANGELOG `[Unreleased]` → commit with `Spec:` footer.
+
 ## [1.5.5] - 2026-08-31
 
 ### Docs
@@ -173,3 +217,5 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 [1.5.1]: https://gitcode.com/ProgramAnalysis/homegraph/tags/v1.5.1
 [1.5.0]: https://gitcode.com/ProgramAnalysis/homegraph/tags/v1.5.0
 [1.4.1]: https://gitcode.com/ProgramAnalysis/homegraph/tags/v1.4.1
+[1.5.6]: https://github.com/fujiaxin-coder/homegraph/releases/tag/v1.5.6
+[1.5.7]: https://github.com/fujiaxin-coder/homegraph/releases/tag/v1.5.7

package/README.md

@@ -179,10 +179,10 @@ Agent 侧工具名前缀为 `homegraph_`。
 
 | 工具 | 用途 |
 |------|------|
-| `homegraph_explore` | **主工具**：一次调用返回相关符号的完整源码、调用路径与影响范围；支持自然语言问题或符号/文件名列表。高置信度的用法 / 模块依赖 / NAPI 问法会委派到下方三个聚焦工具的同一套 survey |
-| `homegraph_usages` | 只读用法清单：命名 API / member / field / 常量的引用与调用点（常量袋可走有界文本扫描） |
-| `homegraph_modules` | 只读模块依赖 / 循环依赖清单（命名模块或路径） |
-| `homegraph_native` | 只读 NAPI / native export 清单（命名路径或 Type） |
+| `homegraph_usages` | **精确用法清单首选**：查询一个已命名 API、成员、常量或字段在哪里被引用 |
+| `homegraph_modules` | **模块拓扑首选**：查询已命名模块之间的依赖关系或循环依赖 |
+| `homegraph_native` | **Native 边界首选**：查询已命名路径或类型的 NAPI/native 导出和注册位置 |
+| `homegraph_explore` | **通用结构探索**：一次调用返回相关符号的源码、调用路径与影响范围；窄清单问题优先使用上面三个专用工具 |
 | `homegraph_search` | 按名称快速搜索符号（仅返回位置，不含源码） |
 | `homegraph_node` | 读取单个符号或整个文件的源码（带行号）及调用关系；可替代 Read 读文件 |
 | `homegraph_callers` / `homegraph_callees` | 查看调用方 / 被调用方 |
@@ -195,6 +195,12 @@ Agent 侧工具名前缀为 `homegraph_`。
 | `homegraph_spec_find` | 根据文件路径反向查找关联的Spec |
 | `homegraph_spec_trace` | 根据代码符号追溯回关联的Spec |
 
+### 查询规划（实验性）
+
+`homegraph_explore` 现在共用结构化查询计划：默认 `HOMEGRAPH_QUERY_PLANNER=rules`，保持本地确定性路由；`off` 可回退旧执行路径。显式启用 `llm` 后，复杂问题可在一次模型调用中做意图识别、问题分解和检索改写，再复用既有工具的内部实现。
+
+模型规划需要单独配置 URL、模型和密钥；仅发送问题，不发送仓库源码。最多 3 个子任务共用截止时间和输出预算，规划失败退回本地规则。配置、指标、限制见 [查询规划指南](docs/query-planning.md)。这不是新增的 CodeGraph 构建算法，也尚未证明能降低真实任务的 token 或延迟。
+
 ### Commit4Spec（Spec知识图谱）
 
 Commit4Spec 提供两条互补路径将设计Spec与 Git 历史关联，存入 `.homegraph/commit4spec/commit4spec.db`：

package/dist/bin/homegraph.js

@@ -1421,6 +1421,11 @@ function main() {
         if (options.watch === false) {
             process.env.HOMEGRAPH_NO_WATCH = '1';
         }
+        // Product hosts (DevEco Code) pass --auto-init so unindexed workspaces get
+        // .homegraph/ + background index + watch without a separate `homegraph init`.
+        if (options.autoInit) {
+            process.env.HOMEGRAPH_AUTO_INIT = '1';
+        }
         // Spec 0005: resolve --sources over HOMEGRAPH_SOURCES, then stamp env so
         // detached daemons and in-process opens share the same mode.
         const { resolveGraphSources, applyGraphSourcesToEnv, GRAPH_SOURCES_MODES } = await Promise.resolve().then(() => __importStar(require('../graph-sources')));
@@ -1491,6 +1496,7 @@ function main() {
         .option('-p, --path <path>', 'Project path (optional for MCP mode, uses rootUri from client)')
         .option('--mcp', 'Legacy alias for `serve mcp` (stdio MCP server)')
         .option('--no-watch', 'Disable the file watcher (no auto-sync; useful on slow filesystems like WSL2 /mnt drives)')
+        .option('--auto-init', 'If no .homegraph/ exists, create it and index in the background (for product hosts)')
         .option('--sources <mode>', 'Graph sources for MCP queries: both|project|sdk|none (default both; env HOMEGRAPH_SOURCES)')
         .action(async (mode, options) => {
         try {