homegraph 1.5.8 → 1.6.0

package/CHANGELOG.md

@@ -10,6 +10,38 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [Unreleased]
 
 
+## [1.6.0] - 2026-09-23
+
+### Improvements
+
+- MCP auto-init (Spec 0049): empty workspace roots no longer create `.homegraph/` on `--auto-init` / `HOMEGRAPH_AUTO_INIT` (fixes DevEco in-place `devecocli create` hitting `PROJECT_EXISTS` because only an index dir existed). A 60s probe (`HOMEGRAPH_DEFER_PROBE_MS`; `0` = tool-kick only) and the first `homegraph_*` call re-check `isIndexableRoot` (root `build-profile.json5` or any indexable source); once non-empty, the existing fast-map + background full index path runs once. Status footers stay the product empty/fast/full/dirty/syncing lines. Lifecycle logging no longer mkdir's `.homegraph/` just to write `daemon.log`.
+- Harmony locate seams (Spec 0048): index `form_config.json` / `shortcuts_config.json` (plus module.json5 form extensionAbilities and shortcuts/form metadata) as searchable capability nodes — explore may lead with **Capability profiles**, or an explicit no-in-repo form note instead of SDK `.d.ts`. Resource hits can append in-repo `$r('app.string.<key>')` **bound** `.ets` anchors. `homegraph_project` adds a **Module roster** (oh-package + local `file:` deps) and lists capability profile paths separately from rawfile. Explore may prepend **Seam notes** for nearby profiles and empty/log-only stubs.
+- MCP product lifecycle (Spec 0047): main-thread liveness watchdog is **off by default** (enable with `HOMEGRAPH_WATCHDOG=1`; `HOMEGRAPH_NO_WATCHDOG=1` still forces off) so concurrent DevEco init no longer gets false "Main thread unresponsive" kills — file watch / incremental sync unchanged. Shared daemon idle linger defaults to **60s** after the last client disconnects; if auto-init/full index is still in `building_fast`/`indexing`, idle exit waits until that build settles, then starts the 60s linger. While any client is connected the daemon never idle-exits.
+- MCP runtime log (Spec 0046): always-on coarse lifecycle lines (`mcp.start` / `mcp.initialize` / `auto-init.*` / `index.*` / `watcher.degraded`) go to stderr and `.homegraph/daemon.log` (same file daemon stdio already uses); soft-rotate at ~5 MiB to `daemon.log.1`. Set `HOMEGRAPH_DEBUG=1` for per-tool summaries (`tool.<name>` with duration / error / truncated query). No new `logs/` directory; default is not a full request ledger.
+- ArkUI index-time edge synthesis (Spec 0045): `build` / `@Builder` bodies that call another in-repo `@Component` / `@Builder` gain `arkui-child` edges (ambiguous names dropped); literal `pushPathByName` / `replacePathByName` / `pushNamedRoute({ name })` link to indexed `route` nodes as `arkui-named-nav`. Complements existing `arkui-route` (`pushUrl`) and Spec 0039 route_map edges — no query-time synthesis.
+- Explore locate contract (Spec 0044): Chinese/UI **literal witness** files stay in the first pack and rank ahead of Logger/hilog/Toast spines unless the query names those APIs; **Located** / **Partial** / **Miss** banners (Partial next-step → `node`/`usages`/`search`, no same-name Grep); Miss omits source bodies and lists fuzzy paths; filename≠primary-declaration risk note; `homegraph_node` for symbols already on the explore locate list bypasses the Partial depth-fuse cap. Dynamic-edge synthesis (10.3) remains deferred.
+- When an MCP session already has a bound default project (`--path` / opened root), a tool `projectPath` that resolves to a **different** `.homegraph/` index root is soft-pinned: HomeGraph keeps answering from the bound root and prepends a short English notice (not `isError`). Same-root nested paths are unchanged; sessions with no default project still open cross-project indexes (Spec 0043).
+- In-repo locate for explore: `taskContext` no longer enters the lexical/FTS query string (quoted literals from it still merge); PascalCase identifiers (≥8 chars) seed exact file/symbol roots like `Foo.ets`; business-oriented queries default `sourceScope=local` so SDK `.d.ts` stubs do not become roots; MCP trails / used-by / evidence packs hide `@dummyFile` and `%AM*` noise. `homegraph_project` adds a bounded HarmonyOS **resources path inventory** (string.json / rawfile / media dir counts / on-disk modules with zero indexed sources) — paths only, no JSON bodies or edges (Spec 0042).
+- Harmony `resources/**/element/string.json` is indexed as searchable `constant` nodes (key + UI value in FTS). Explore may lead with a short **Resource hits** table and a `$r('app.string.<key>')` Grep hint — **no** graph edges to controls. Color/media/rawfile stay out of scope (Spec 0041).
+- `homegraph_project` on Harmony repos now prints a **skeleton summary**: `bundle` from `app.json5`, a note that modules come from `build-profile.json5`, per-module `route profile:` paths (`route_map` / `router_map` / `main_pages`), and `oh-package` names when present. Still no call edges or profile JSON bodies — use explore for route→page (Spec 0039) and Read to edit. Tool descriptions and MCP initialize instructions spell out project vs explore (Spec 0040).
+- Harmony `route_map.json` / `router_map.json` / `main_pages.json` are indexed (basename allowlist) and linked into the graph as `route` nodes → page / `buildFunction` symbols. Edges carry `synthesizedBy: arkts-route-map` and `registeredAt` pointing at the config file so explore/trails show the JSON wiring site. When an explore query mentions those filenames, replies lead with a short **Registration sources** table — evidence from those profiles, reducing blind re-Read of the JSON (Spec 0039).
+- MCP tool replies that know the indexed project now begin with `HomeGraph project root: \`<absolute>\`` plus a one-line join rule: repo-relative paths below that root should be passed to Read/Grep as-is (or `<root>/<relative>` with `/`), without inventing experiment/result prefixes. MCP initialize instructions mention the same join base. Indexed path storage stays repo-relative (Spec 0038).
+
+## [1.5.10] - 2026-09-20
+
+### Fixes
+
+- ArkTS synthetic PROJECT modules are limited to Node `package.json` trees (e.g. hvigor plugins). Forgotten Harmony HARs that only have `oh-package.json5` / loose `.ets` outside root `build-profile.json5` are no longer registered for `analyseByModule` BODIES — on SceneBoard-scale repos that was reloading already-indexed monorepo deps into ModuleCache and inflating wall time and peak RSS. Those orphans are indexed via tree-sitter instead. Parent-dir swallow of real Harmony modules (e.g. `synthetic:feature/`) remains blocked (Spec 0036).
+- After a streamed ArkTS modular batch finishes and releases the Scene, orphan `.ets` files that were never PROJECT-persisted no longer trigger a second full `analyseByModule` (the “127/127 done → starts again at 1/127” loop). They use the TypeScript tree-sitter fallback instead (Spec 0036).
+- `homegraph init`/`index` reported duration now covers the full wall clock (extract + FTS rebuild + resolve/link + maintenance), not only the extraction orchestrator phase (Spec 0036).
+- Harmony `build-profile.json5` files that use single-quoted strings (e.g. `'2in1'`) and bare keys now parse correctly, so multi-module ArkTS dirty sync can map changed `.ets` files to PROJECT modules instead of always falling back to a full rebuild (Spec 0034).
+
+### Improvements
+
+- Bump `arkanalyzer` to **1.0.94**.
+- Harmony projects with a root `build-profile.json5` now default to **serial indexing** after ArkAnalyzer: one parse worker and no resolve/synthesis worker pool. On SceneBoard-scale repos this cut peak process-tree PrivateMemory from ~8.5GB to ~3.8GB with only ~6% more wall clock. Opt out with `HOMEGRAPH_HARMONY_SERIAL=0`; force on with `=1`. Explicit `CODEGRAPH_PARSE_WORKERS` still overrides parse concurrency (Spec 0037).
+- MCP product index readiness is now five short states (`empty` / `fast` / `full` / `dirty` / `syncing`): tool replies use a one-line `HomeGraph status=…` footer (or that line alone when the tool cannot answer yet). Pending edits surface as `dirty` with path list instead of the long stale banner; write locks stay `syncing`. MCP initialize includes a one-line status glossary (Spec 0035).
+
 ## [1.5.8] - 2026-09-15
 
 ### Improvements
@@ -240,3 +272,5 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 [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
 [1.5.8]: https://github.com/fujiaxin-coder/homegraph/releases/tag/v1.5.8
+[1.5.10]: https://github.com/fujiaxin-coder/homegraph/releases/tag/v1.5.10
+[1.6.0]: https://github.com/fujiaxin-coder/homegraph/releases/tag/v1.6.0

package/dist/extraction/grammars.d.ts

@@ -45,6 +45,25 @@ export declare function isErlangAppFile(filePath: string): boolean;
 export declare function isPlayRoutesFile(filePath: string): boolean;
 /** HarmonyOS module manifest — parsed by the arkts-entry framework extractor. */
 export declare function isArkModuleJson5(filePath: string): boolean;
+/**
+ * Harmony Navigation / pages profile JSON (Spec 0039) — basename allowlist only.
+ * Parsed by arkts-entry; not general `.json` indexing.
+ */
+export declare function isHarmonyRouteProfileJson(filePath: string): boolean;
+/**
+ * Harmony element string resources (Spec 0041) — path allowlist only.
+ * `…/resources/…/element/string.json` (not bare string.json, not color/media).
+ * Indexed as yaml file-level + arkts-entry constants for FTS; no graph edges.
+ */
+export declare function isHarmonyElementStringJson(filePath: string): boolean;
+/**
+ * Harmony capability profiles (Spec 0048) — basename allowlist only.
+ * `form_config.json` (service widgets) and `shortcuts_config.json` (home-screen shortcuts).
+ * Indexed as yaml + arkts-entry constants; no UI call edges.
+ */
+export declare function isHarmonyCapabilityProfileJson(filePath: string): boolean;
+/** Config files that host ArkTS `route` nodes (module manifest + Spec 0039 profiles). */
+export declare function isHarmonyRouteConfigFile(filePath: string): boolean;
 /**
  * Initialize the tree-sitter WASM runtime. Must be called before loading grammars.
  * Does NOT load any grammar WASM files — use loadGrammarsForLanguages() for that.

package/dist/extraction/grammars.js

@@ -46,6 +46,10 @@ exports.isShopifyLiquidJson = isShopifyLiquidJson;
 exports.isErlangAppFile = isErlangAppFile;
 exports.isPlayRoutesFile = isPlayRoutesFile;
 exports.isArkModuleJson5 = isArkModuleJson5;
+exports.isHarmonyRouteProfileJson = isHarmonyRouteProfileJson;
+exports.isHarmonyElementStringJson = isHarmonyElementStringJson;
+exports.isHarmonyCapabilityProfileJson = isHarmonyCapabilityProfileJson;
+exports.isHarmonyRouteConfigFile = isHarmonyRouteConfigFile;
 exports.initGrammars = initGrammars;
 exports.vendoredWasmFilenames = vendoredWasmFilenames;
 exports.readGrammarWasmBytes = readGrammarWasmBytes;
@@ -235,6 +239,12 @@ function isSourceFile(filePath, overrides) {
         return true; // Play `conf/routes` is extensionless
     if (isArkModuleJson5(filePath))
         return true;
+    if (isHarmonyRouteProfileJson(filePath))
+        return true; // Spec 0039
+    if (isHarmonyElementStringJson(filePath))
+        return true; // Spec 0041
+    if (isHarmonyCapabilityProfileJson(filePath))
+        return true; // Spec 0048
     if (isShopifyLiquidJson(filePath))
         return true; // Shopify OS 2.0 JSON templates / section groups
     if (isErlangAppFile(filePath))
@@ -280,6 +290,35 @@ function isPlayRoutesFile(filePath) {
 function isArkModuleJson5(filePath) {
     return filePath.endsWith('module.json5');
 }
+/**
+ * Harmony Navigation / pages profile JSON (Spec 0039) — basename allowlist only.
+ * Parsed by arkts-entry; not general `.json` indexing.
+ */
+function isHarmonyRouteProfileJson(filePath) {
+    const base = filePath.replace(/\\/g, '/').split('/').pop()?.toLowerCase() ?? '';
+    return base === 'route_map.json' || base === 'router_map.json' || base === 'main_pages.json';
+}
+/**
+ * Harmony element string resources (Spec 0041) — path allowlist only.
+ * `…/resources/…/element/string.json` (not bare string.json, not color/media).
+ * Indexed as yaml file-level + arkts-entry constants for FTS; no graph edges.
+ */
+function isHarmonyElementStringJson(filePath) {
+    return /(?:^|\/)resources\/(?:[^/]+\/)*element\/string\.json$/i.test(filePath.replace(/\\/g, '/'));
+}
+/**
+ * Harmony capability profiles (Spec 0048) — basename allowlist only.
+ * `form_config.json` (service widgets) and `shortcuts_config.json` (home-screen shortcuts).
+ * Indexed as yaml + arkts-entry constants; no UI call edges.
+ */
+function isHarmonyCapabilityProfileJson(filePath) {
+    const base = filePath.replace(/\\/g, '/').split('/').pop()?.toLowerCase() ?? '';
+    return base === 'form_config.json' || base === 'shortcuts_config.json';
+}
+/** Config files that host ArkTS `route` nodes (module manifest + Spec 0039 profiles). */
+function isHarmonyRouteConfigFile(filePath) {
+    return isArkModuleJson5(filePath) || isHarmonyRouteProfileJson(filePath);
+}
 /**
  * Caches for loaded grammars and parsers
  */
@@ -450,8 +489,12 @@ function detectLanguage(filePath, source, overrides) {
         return 'yaml';
     if (isArkModuleJson5(filePath))
         return 'yaml';
-    if (isArkModuleJson5(filePath))
+    if (isHarmonyRouteProfileJson(filePath))
         return 'yaml';
+    if (isHarmonyElementStringJson(filePath))
+        return 'yaml'; // Spec 0041
+    if (isHarmonyCapabilityProfileJson(filePath))
+        return 'yaml'; // Spec 0048
     const ext = filePath.substring(filePath.lastIndexOf('.')).toLowerCase();
     // Shopify OS 2.0 JSON templates / section groups → the Liquid extractor (it
     // links each section `"type"` to its `sections/<type>.liquid`).

package/dist/extraction/index.js

@@ -1475,17 +1475,25 @@ class ExtractionOrchestrator {
                 await (0, arkts_1.primeArkTSBatch)(this.rootDir, this.queries, firstEtsFile);
                 errors.push(...(0, arkts_1.drainArkTSIndexNotices)());
             }
-            // Start parse pool only after Scene teardown — most .ets are already in DB.
-            const remainingToParse = files.filter((f) => !((0, arkts_1.isArkTSBatchPersisted)(f) || ((0, arkts_1.isArkTSBatchCommitted)() && (0, arkts_1.isArkAnalyzerSourcePath)(f)))).length;
+            // Start parse pool only after Scene teardown — AA-persisted .ets are already
+            // in DB. Ark sources that never entered a PROJECT module (forgotten HARs /
+            // packageless orphans) are NOT skipped here — they fall through to tree-sitter.
+            const remainingToParse = files.filter((f) => !(0, arkts_1.isArkTSBatchPersisted)(f)).length;
             if (useWorker) {
                 // CODEGRAPH_PARSE_WORKERS: explicit worker count; 1 = the old single-worker
                 // behaviour (the conservative rollback). Unset → clamp(cores-1, 1, 8).
+                // Harmony modular repos default to 1 worker (Spec 0037) unless overridden.
                 let poolSize = (0, parse_pool_1.resolveParsePoolSize)(process.env.CODEGRAPH_PARSE_WORKERS, os.cpus().length);
-                if (!process.env.CODEGRAPH_PARSE_WORKERS?.trim() && remainingToParse < 500) {
-                    poolSize = Math.min(poolSize, 2);
-                }
-                else if (!process.env.CODEGRAPH_PARSE_WORKERS?.trim() && remainingToParse < 2000) {
-                    poolSize = Math.min(poolSize, 4);
+                if (!process.env.CODEGRAPH_PARSE_WORKERS?.trim()) {
+                    if ((0, arkts_1.preferHarmonySerialIndexing)(this.rootDir)) {
+                        poolSize = 1;
+                    }
+                    else if (remainingToParse < 500) {
+                        poolSize = Math.min(poolSize, 2);
+                    }
+                    else if (remainingToParse < 2000) {
+                        poolSize = Math.min(poolSize, 4);
+                    }
                 }
                 pool = new parse_pool_1.ParseWorkerPool({
                     languages: neededLanguages,
@@ -1523,8 +1531,7 @@ class ExtractionOrchestrator {
                 const batch = files.slice(i, i + FILE_IO_BATCH_SIZE);
                 // Read files in parallel (with path validation before any I/O)
                 const fileContents = await Promise.all(batch.map(async (fp) => {
-                    if ((0, arkts_1.isArkTSBatchPersisted)(fp) ||
-                        ((0, arkts_1.isArkTSBatchCommitted)() && (0, arkts_1.isArkAnalyzerSourcePath)(fp))) {
+                    if ((0, arkts_1.isArkTSBatchPersisted)(fp)) {
                         return {
                             filePath: fp,
                             content: null,
@@ -1559,9 +1566,7 @@ class ExtractionOrchestrator {
                         aborted = true;
                         break;
                     }
-                    if ((0, arkts_1.isArkTSBatchPersisted)(filePath) ||
-                        arktsBatchSkipped ||
-                        ((0, arkts_1.isArkTSBatchCommitted)() && (0, arkts_1.isArkAnalyzerSourcePath)(filePath))) {
+                    if ((0, arkts_1.isArkTSBatchPersisted)(filePath) || arktsBatchSkipped) {
                         processed++;
                         filesIndexed++;
                         onProgress?.({ phase: 'parsing', current: processed, total, currentFile: filePath });

package/dist/extraction/languages/arkts.d.ts

@@ -49,6 +49,16 @@ export declare function buildArkMethodSignatureFields(method: ArkMethod): {
  * the indexer (rare Photos-scale Windows cases).
  */
 export declare function shouldUseIsolatedArkTSBuild(): boolean;
+/**
+ * Default to serial parse + no resolve worker pool on Harmony modular repos.
+ * analyseByModule dominates wall clock; worker pools mainly spike peak RSS after
+ * Scene release (Spec 0037). Explicit CODEGRAPH_PARSE_WORKERS still wins when set.
+ *
+ * - unset: true iff root `build-profile.json5` exists
+ * - `HOMEGRAPH_HARMONY_SERIAL=0`/`false`: never
+ * - `HOMEGRAPH_HARMONY_SERIAL=1`/`true`: always
+ */
+export declare function preferHarmonySerialIndexing(rootDir: string): boolean;
 /** One PROJECT module from root `build-profile.json5`. */
 export interface HarmonyModuleRef {
     name: string;
@@ -63,19 +73,38 @@ export declare function normalizeHarmonyModuleSrcPath(srcPath: string): string;
  */
 export declare function listHarmonyProjectModules(rootDir: string): HarmonyModuleRef[];
 /**
- * Nearest package-like directory for an orphan Ark source, or the first path
- * segment. Never returns the project root (registering `.` would re-scan every
- * Harmony module). Lone files directly under the root return null.
+ * True when registering `srcPath` as a synthetic PROJECT would re-load real
+ * Harmony modules: exact path collision, or a parent of existing `srcPath`s
+ * (e.g. synthetic `feature/` swallowing `feature/appcenter`).
  */
-export declare function findSyntheticArkModuleRoot(rootDir: string, relFile: string): string | null;
+export declare function syntheticRootConflictsWithHarmonyModules(srcPath: string, modules: readonly HarmonyModuleRef[]): boolean;
+/**
+ * Nearest **Node** `package.json` directory for an orphan Ark/TS source.
+ * Never returns the project root (registering `.` would re-scan every Harmony
+ * module). Lone files directly under the root return null.
+ *
+ * Only `package.json` counts — not `oh-package.json5`. Forgotten Harmony HARs
+ * left out of root `build-profile.json5` (scene_board `feature/visionglass`
+ * etc.) often declare heavy `file:`/`../` deps on modules already indexed as
+ * real PROJECT modules; registering them as synthetic PROJECT→BODIES reloads
+ * those deps into ModuleCache and spikes wall time + RSS for almost no unique
+ * coverage. Those orphans fall through to tree-sitter instead.
+ *
+ * When `harmonyModules` is provided, skips roots that would swallow those
+ * modules (e.g. a plugin under `feature/intelligent` must not become
+ * `synthetic:feature/` and re-BODIES the whole `feature/` tree).
+ */
+export declare function findSyntheticArkModuleRoot(rootDir: string, relFile: string, harmonyModules?: readonly HarmonyModuleRef[]): string | null;
 /**
  * ArkAnalyzer sources under `scannedFiles` that are not inside any
  * build-profile PROJECT module `srcPath`.
  */
 export declare function listOrphanArkAnalyzerSources(scannedFiles: Iterable<string>, harmonyModules: HarmonyModuleRef[]): string[];
 /**
- * Cluster orphan `.ets`/`.ts`/`.d.ts` into synthetic PROJECT module roots
- * (e.g. `HMRouterPlugin` for a Node hvigor plugin living beside HAP modules).
+ * Cluster orphan `.ets`/`.ts`/`.d.ts` into synthetic PROJECT module roots for
+ * Node-style packages only (`package.json`, e.g. HMRouterPlugin). Harmony
+ * `oh-package.json5` trees omitted from build-profile are not registered —
+ * analyseByModule would re-SIGNATURES their monorepo deps at high RSS cost.
  */
 export declare function listSyntheticArkModuleRoots(rootDir: string, scannedFiles: Iterable<string>, harmonyModules?: HarmonyModuleRef[]): HarmonyModuleRef[];
 export type DirtyHarmonyModuleResolution = {
@@ -273,7 +302,11 @@ export interface BindOhosApiDbOptions extends EnsureOhosApiDbOptions {
 /** Prefix applied to API db node file paths so explore can render without disk reads. */
 export declare function markOhosApiFilePath(relativePath: string): string;
 export declare function isOhosApiFilePath(filePath: string): boolean;
-/** Strip json5 comments/trailing commas enough for compileSdkVersion extraction. */
+/**
+ * DevEco / Harmony JSON5 subset → JSON.parse.
+ * Supports: line/block comments, trailing commas, bare keys, single-quoted strings
+ * (e.g. deviceTypes: ['phone', '2in1']). Not a full JSON5 implementation.
+ */
 export declare function parseJson5Minimal(text: string): unknown;
 /** Normalize compileSdkVersion values like "6.0.1(21)" → "6.0.1". */
 export declare function normalizeOhosApiVersion(raw: unknown): string | null;