homegraph 1.5.6 → 1.5.8

package/dist/db/sqlite-adapter.d.ts

@@ -1,16 +1,12 @@
 /**
  * SQLite Adapter
  *
- * Three-tier selection (first success wins):
+ * Two-tier selection (first success wins):
  *   1. `node:sqlite` (`DatabaseSync`) — real SQLite + WAL + FTS5, Node ≥22.5
  *      (skipped when the build lacks FTS5 — e.g. some Node 23.x official builds)
- *   2. `better-sqlite3` — native addon (optionalDependency)
- *   3. `node-sqlite3-wasm` — last-resort fallback (no WAL; slower / lock-prone)
+ *   2. `node-sqlite3-wasm` — cross-platform fallback (no WAL; slower / lock-prone)
  *
- * Library hosts on Node 22.0–22.4 land on (2) or (3). Node ≥22.5 prefers (1) when
- * FTS5 is present and skips the native build. Override with
- * `HOMEGRAPH_SQLITE_BACKEND=node-sqlite|native|wasm`.
- * optionalDependency `better-sqlite3` is 12.x (Node 22+); wasm remains the last resort.
+ * Override with `HOMEGRAPH_SQLITE_BACKEND=node-sqlite|wasm`.
  */
 export interface SqliteStatement {
     run(...params: any[]): {
@@ -37,11 +33,11 @@ export interface SqliteDatabase {
     readonly open: boolean;
 }
 /** Active SQLite backend after {@link createDatabase}. */
-export type SqliteBackend = 'node-sqlite' | 'native' | 'wasm';
+export type SqliteBackend = 'node-sqlite' | 'wasm';
 /**
  * One-line recovery hint when WASM is active (no WAL — slower / lock-prone).
  */
-export declare const WASM_FALLBACK_FIX_RECIPE: string;
+export declare const WASM_FALLBACK_FIX_RECIPE = "upgrade to Node.js 22.5+ (uses built-in node:sqlite with FTS5), then restart homegraph";
 /**
  * Banner shown to stderr when falling back to WASM.
  */
@@ -49,11 +45,9 @@ export declare function buildWasmFallbackBanner(priorErrors?: string): string;
 /** True when `require('node:sqlite').DatabaseSync` succeeds. */
 export declare function isNodeSqliteAvailable(): boolean;
 export declare function isNodeSqliteFts5Available(): boolean;
-/** True when `require('better-sqlite3')` succeeds. */
-export declare function isNativeSqliteAvailable(): boolean;
 /**
  * Create a database connection.
- * Order: node:sqlite (with FTS5) → better-sqlite3 → node-sqlite3-wasm (unless overridden).
+ * Order: node:sqlite (with FTS5) → node-sqlite3-wasm (unless overridden).
  */
 export declare function createDatabase(dbPath: string, opts?: {
     readOnly?: boolean;

package/dist/db/sqlite-adapter.js

@@ -2,30 +2,23 @@
 /**
  * SQLite Adapter
  *
- * Three-tier selection (first success wins):
+ * Two-tier selection (first success wins):
  *   1. `node:sqlite` (`DatabaseSync`) — real SQLite + WAL + FTS5, Node ≥22.5
  *      (skipped when the build lacks FTS5 — e.g. some Node 23.x official builds)
- *   2. `better-sqlite3` — native addon (optionalDependency)
- *   3. `node-sqlite3-wasm` — last-resort fallback (no WAL; slower / lock-prone)
+ *   2. `node-sqlite3-wasm` — cross-platform fallback (no WAL; slower / lock-prone)
  *
- * Library hosts on Node 22.0–22.4 land on (2) or (3). Node ≥22.5 prefers (1) when
- * FTS5 is present and skips the native build. Override with
- * `HOMEGRAPH_SQLITE_BACKEND=node-sqlite|native|wasm`.
- * optionalDependency `better-sqlite3` is 12.x (Node 22+); wasm remains the last resort.
+ * Override with `HOMEGRAPH_SQLITE_BACKEND=node-sqlite|wasm`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WASM_FALLBACK_FIX_RECIPE = void 0;
 exports.buildWasmFallbackBanner = buildWasmFallbackBanner;
 exports.isNodeSqliteAvailable = isNodeSqliteAvailable;
 exports.isNodeSqliteFts5Available = isNodeSqliteFts5Available;
-exports.isNativeSqliteAvailable = isNativeSqliteAvailable;
 exports.createDatabase = createDatabase;
 /**
  * One-line recovery hint when WASM is active (no WAL — slower / lock-prone).
  */
-exports.WASM_FALLBACK_FIX_RECIPE = 'upgrade to Node.js 22.5+ (uses built-in node:sqlite), or ' +
-    '`xcode-select --install` (macOS) / `apt install build-essential` (Debian/Ubuntu) ' +
-    'then `npm rebuild better-sqlite3`.';
+exports.WASM_FALLBACK_FIX_RECIPE = 'upgrade to Node.js 22.5+ (uses built-in node:sqlite with FTS5), then restart homegraph';
 /**
  * Banner shown to stderr when falling back to WASM.
  */
@@ -33,20 +26,15 @@ function buildWasmFallbackBanner(priorErrors) {
     const sep = '─'.repeat(72);
     const lines = [
         sep,
-        '[HomeGraph] WASM SQLite fallback active (node:sqlite + better-sqlite3 unavailable)',
+        '[HomeGraph] WASM SQLite fallback active (node:sqlite unavailable or lacks FTS5)',
         sep,
         'Indexing and sync will be 5-10x slower than a WAL backend, and concurrent',
-        'reads can hit "database is locked". Prefer Node 22.5+ or better-sqlite3.',
+        'reads can hit "database is locked". Prefer Node.js 22.5 or newer.',
         '',
-        'Fix — use built-in SQLite (best when you can):',
+        'Fix — use built-in SQLite:',
         '  Use Node.js 22.5 or newer, then restart homegraph',
         '',
-        'Fix — native better-sqlite3:',
-        '  macOS:  xcode-select --install && npm rebuild better-sqlite3',
-        '  Linux:  sudo apt install build-essential python3 make && npm rebuild better-sqlite3',
-        '  Any:    npm install better-sqlite3 --save',
-        '',
-        'Verify after fix: `homegraph status` should show Backend: node-sqlite or native.',
+        'Verify after fix: `homegraph status` should show Backend: node-sqlite.',
     ];
     if (priorErrors) {
         lines.push('', `Prior load errors: ${priorErrors}`);
@@ -155,20 +143,9 @@ function isNodeSqliteFts5Available() {
     }
     return cachedNodeSqliteFts5;
 }
-/** True when `require('better-sqlite3')` succeeds. */
-function isNativeSqliteAvailable() {
-    try {
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
-        require('better-sqlite3');
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 /**
  * Wraps Node's built-in `node:sqlite` (`DatabaseSync`) to match the
- * better-sqlite3 interface the rest of the code expects.
+ * statement/database interface the rest of the code expects.
  */
 class NodeSqliteAdapter {
     _db;
@@ -362,10 +339,11 @@ class WasmDatabaseAdapter {
 }
 function resolveBackendOrder() {
     const raw = process.env.HOMEGRAPH_SQLITE_BACKEND?.trim().toLowerCase();
-    if (raw === 'node-sqlite' || raw === 'native' || raw === 'wasm') {
+    if (raw === 'node-sqlite' || raw === 'wasm') {
         return [raw];
     }
-    return ['node-sqlite', 'native', 'wasm'];
+    // Unknown values (including legacy `native`) fall through to the default order.
+    return ['node-sqlite', 'wasm'];
 }
 function tryOpenBackend(backend, dbPath, opts) {
     try {
@@ -379,12 +357,6 @@ function tryOpenBackend(backend, dbPath, opts) {
             }
             return { db: new NodeSqliteAdapter(dbPath, opts), backend: 'node-sqlite' };
         }
-        if (backend === 'native') {
-            // eslint-disable-next-line @typescript-eslint/no-require-imports
-            const Database = require('better-sqlite3');
-            const db = opts?.readOnly ? new Database(dbPath, { readonly: true }) : new Database(dbPath);
-            return { db: db, backend: 'native' };
-        }
         return { db: new WasmDatabaseAdapter(dbPath, opts), backend: 'wasm' };
     }
     catch (error) {
@@ -393,7 +365,7 @@ function tryOpenBackend(backend, dbPath, opts) {
 }
 /**
  * Create a database connection.
- * Order: node:sqlite (with FTS5) → better-sqlite3 → node-sqlite3-wasm (unless overridden).
+ * Order: node:sqlite (with FTS5) → node-sqlite3-wasm (unless overridden).
  */
 function createDatabase(dbPath, opts) {
     const order = resolveBackendOrder();

package/dist/directory.d.ts

@@ -63,7 +63,7 @@ export declare function isInitialized(projectRoot: string): boolean;
  * The returned string is a human phrase that slots into "… looks like {reason}".
  */
 export declare function unsafeIndexRootReason(projectRoot: string): string | null;
-export declare function findNearestHomeGraphRoot(startPath: string): string | null;
+export declare function findNearestHomeGraphRoot(startPath: string, floor?: string): string | null;
 /**
  * Indexed sub-project roots beneath `root` (bounded breadth-first scan). For
  * the monorepo case behind #964: the index lives in a CHILD

package/dist/directory.js

@@ -183,17 +183,41 @@ function unsafeIndexRootReason(projectRoot) {
     }
     return null;
 }
-function findNearestHomeGraphRoot(startPath) {
+function findNearestHomeGraphRoot(startPath, floor) {
+    // A floor (an MCP host's explicit --path / rootUri) bounds the walk: an
+    // ancestor .homegraph above it must not be adopted — a stray ancestor index
+    // hijacks every nested server, whose daemon then indexes the wrong (often
+    // huge) tree and OOMs (spec 0028). Only honored when it contains the start;
+    // a misconfigured floor must not break discovery.
+    const resolveBestEffort = (p) => {
+        try {
+            return fs.realpathSync(path.resolve(p));
+        }
+        catch {
+            return path.resolve(p);
+        }
+    };
+    // Walk the literal chain (returned to the caller in ITS coordinate system);
+    // track the realpath chain in parallel only for the boundary comparison, so
+    // a symlinked prefix (macOS /var vs /private/var) cannot desync the floor.
     let current = path.resolve(startPath);
+    let currentReal = resolveBestEffort(current);
     const root = path.parse(current).root;
+    const floorDir = floor ? resolveBestEffort(floor) : null;
+    const clamped = floorDir !== null &&
+        (currentReal === floorDir || currentReal.startsWith(floorDir + path.sep));
     while (current !== root) {
         if (isInitialized(current)) {
             return current;
         }
+        if (clamped && currentReal === floorDir) {
+            return null; // the floor itself has no index — stop, never look above
+        }
         const parent = path.dirname(current);
         if (parent === current)
             break; // Reached filesystem root
         current = parent;
+        currentReal = path.dirname(currentReal);
     }
     // Check root as well
     if (isInitialized(current)) {

package/dist/extraction/grammars.d.ts

@@ -51,6 +51,8 @@ export declare function isArkModuleJson5(filePath: string): boolean;
  * Idempotent — safe to call multiple times.
  */
 export declare function initGrammars(): Promise<void>;
+/** Filenames copy-assets must ship under dist/extraction/wasm/ (Spec 0031). */
+export declare function vendoredWasmFilenames(): string[];
 /**
  * Pre-read the grammar WASM bytes for an index set, keyed by language. The
  * orchestrator reads each grammar ONCE and hands the bytes to every parse

package/dist/extraction/grammars.js

@@ -47,6 +47,7 @@ exports.isErlangAppFile = isErlangAppFile;
 exports.isPlayRoutesFile = isPlayRoutesFile;
 exports.isArkModuleJson5 = isArkModuleJson5;
 exports.initGrammars = initGrammars;
+exports.vendoredWasmFilenames = vendoredWasmFilenames;
 exports.readGrammarWasmBytes = readGrammarWasmBytes;
 exports.loadGrammarsForLanguages = loadGrammarsForLanguages;
 exports.loadAllGrammars = loadAllGrammars;
@@ -309,13 +310,8 @@ async function initGrammars() {
  * primary constructors natively. Terraform: tree-sitter-wasms does not ship
  * HCL/Terraform at all, so we vendor the prebuilt tree-sitter-terraform.wasm
  * from @tree-sitter-grammars/tree-sitter-hcl 1.2.0 (Apache-2.0) —
- * byte-identical to the npm package's artifact. ArkTS: tree-sitter-wasms
- * doesn't ship it either; we vendor the prebuilt tree-sitter-arkts.wasm from
- * the tree-sitter-arkts 0.2.0 npm package (harmony-contrib/tree-sitter-arkts,
- * MIT) — byte-identical to the npm tarball's artifact. It extends the
- * tree-sitter-javascript grammar the same way tree-sitter-typescript does,
- * adding `struct_declaration` and the `arkui_component_expression` build()
- * DSL. Nix: tree-sitter-wasms doesn't ship it; we vendor a wasm built from
+ * byte-identical to the npm package's artifact. Nix: tree-sitter-wasms doesn't
+ * ship it; we vendor a wasm built from
  * nix-community/tree-sitter-nix @ 3d0173d (MIT) with tree-sitter-cli 0.25.10
  * (`generate` + `build --wasm`, ABI 15 — upstream's checked-in parser.c is
  * still ABI 13; all 54 upstream corpus tests pass on the regenerated parser).
@@ -324,6 +320,10 @@ const VENDORED_WASM_LANGS = new Set([
     'pascal', 'scala', 'lua', 'luau', 'csharp', 'r', 'cfml', 'cfscript', 'cfquery',
     'cobol', 'vbnet', 'erlang', 'terraform', 'nix',
 ]);
+/** Filenames copy-assets must ship under dist/extraction/wasm/ (Spec 0031). */
+function vendoredWasmFilenames() {
+    return [...new Set([...VENDORED_WASM_LANGS].map((lang) => WASM_GRAMMAR_FILES[lang]))].sort();
+}
 /** Absolute path of a language's grammar WASM (vendored or tree-sitter-wasms). */
 function resolveWasmPath(lang) {
     const wasmFile = WASM_GRAMMAR_FILES[lang];

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

@@ -26,7 +26,7 @@
  */
 import { ArkField, ArkFile, ArkMethod, ClassSignature, MethodSignature } from 'arkanalyzer';
 import type { ViewTreeNode } from 'arkanalyzer';
-import { ExtractionError, ExtractionResult } from '../../types';
+import { ExtractionError, ExtractionResult, Language } from '../../types';
 import type { QueryBuilder } from '../../db/queries';
 import type { IndexProgress, IndexResult } from '../index';
 /** Strip arkanalyzer file-location prefixes from type text (`@proj/file.ets: Foo` → `Foo`). */
@@ -62,6 +62,22 @@ export declare function normalizeHarmonyModuleSrcPath(srcPath: string): string;
  * Returns [] when missing or unparsable — callers should fall back to full Scene.
  */
 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.
+ */
+export declare function findSyntheticArkModuleRoot(rootDir: string, relFile: string): 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).
+ */
+export declare function listSyntheticArkModuleRoots(rootDir: string, scannedFiles: Iterable<string>, harmonyModules?: HarmonyModuleRef[]): HarmonyModuleRef[];
 export type DirtyHarmonyModuleResolution = {
     mode: 'full';
     reason: string;
@@ -73,12 +89,18 @@ export type DirtyHarmonyModuleResolution = {
 };
 /**
  * Map changed/removed paths to Harmony modules for incremental ArkTS sync.
- * Structural project files (`build-profile.json5`, root `oh-package.json5`) or
- * ArkAnalyzer sources outside every module force a full rebuild.
+ * Structural project files (`build-profile.json5`, root `oh-package.json5`)
+ * force a full rebuild. Orphan trees covered by synthetic PROJECT modules
+ * (e.g. `HMRouterPlugin`) map to those module srcPaths instead of full rebuild.
  */
 export declare function resolveDirtyHarmonyModules(rootDir: string, changedFiles: Iterable<string>): DirtyHarmonyModuleResolution;
 /** HarmonyOS sources indexed via ArkAnalyzer Scene batch (`.ets`, `.ts`, `.d.ts`). */
 export declare function isArkAnalyzerSourcePath(filePath: string): boolean;
+/**
+ * Graph `language` tag for an ArkAnalyzer-indexed path. Extraction still uses AA;
+ * the tag must match the source kind so status / language filters stay truthful.
+ */
+export declare function languageForArkAnalyzerPath(filePath: string): Language;
 /**
  * Enumerate ArkAnalyzer sources under `rootDir`, using the same ignore rules as
  * `scanDirectory` (defaults like `build/`/`dist/`, root `.gitignore`, exclude).

package/dist/extraction/languages/arkts.js

@@ -69,8 +69,12 @@ exports.buildArkMethodSignatureFields = buildArkMethodSignatureFields;
 exports.shouldUseIsolatedArkTSBuild = shouldUseIsolatedArkTSBuild;
 exports.normalizeHarmonyModuleSrcPath = normalizeHarmonyModuleSrcPath;
 exports.listHarmonyProjectModules = listHarmonyProjectModules;
+exports.findSyntheticArkModuleRoot = findSyntheticArkModuleRoot;
+exports.listOrphanArkAnalyzerSources = listOrphanArkAnalyzerSources;
+exports.listSyntheticArkModuleRoots = listSyntheticArkModuleRoots;
 exports.resolveDirtyHarmonyModules = resolveDirtyHarmonyModules;
 exports.isArkAnalyzerSourcePath = isArkAnalyzerSourcePath;
+exports.languageForArkAnalyzerPath = languageForArkAnalyzerPath;
 exports.scanEtsFiles = scanEtsFiles;
 exports.runIsolatedArkTSBatchEntry = runIsolatedArkTSBatchEntry;
 exports.primeArkTSBatch = primeArkTSBatch;
@@ -353,6 +357,121 @@ function listHarmonyProjectModules(rootDir) {
     }
     return out;
 }
+/**
+ * Absolute path for ArkAnalyzer module registration (realpath when available).
+ * Must match how incremental target matching resolves `srcPath`.
+ */
+function resolveArkModuleAbsPath(rootDir, relSrcPath) {
+    const resolved = path.resolve(rootDir, relSrcPath);
+    try {
+        return fs.realpathSync(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
+/**
+ * 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.
+ */
+function findSyntheticArkModuleRoot(rootDir, relFile) {
+    const file = normIndexPath(relFile);
+    if (!file || file.startsWith('@'))
+        return null;
+    let dir = path.posix.dirname(file);
+    if (dir === '.' || dir === '')
+        return null;
+    const rootAbs = path.resolve(rootDir);
+    let curAbs = path.resolve(rootDir, dir);
+    for (;;) {
+        const relFromRoot = path.relative(rootAbs, curAbs);
+        if (!relFromRoot || relFromRoot.startsWith('..') || path.isAbsolute(relFromRoot))
+            break;
+        const rel = relFromRoot.replace(/\\/g, '/');
+        if (fs.existsSync(path.join(curAbs, 'package.json')) ||
+            fs.existsSync(path.join(curAbs, 'oh-package.json5'))) {
+            return normalizeHarmonyModuleSrcPath(rel);
+        }
+        const parent = path.dirname(curAbs);
+        if (parent === curAbs)
+            break;
+        curAbs = parent;
+    }
+    const first = file.split('/')[0];
+    if (!first || first === file)
+        return null;
+    return normalizeHarmonyModuleSrcPath(first);
+}
+/**
+ * ArkAnalyzer sources under `scannedFiles` that are not inside any
+ * build-profile PROJECT module `srcPath`.
+ */
+function listOrphanArkAnalyzerSources(scannedFiles, harmonyModules) {
+    const orphans = [];
+    for (const raw of scannedFiles) {
+        const f = normIndexPath(raw);
+        if (!f || !isArkAnalyzerSourcePath(f) || f.startsWith('@'))
+            continue;
+        if (findLongestHarmonyModule(f, harmonyModules))
+            continue;
+        orphans.push(f);
+    }
+    orphans.sort();
+    return orphans;
+}
+/**
+ * Cluster orphan `.ets`/`.ts`/`.d.ts` into synthetic PROJECT module roots
+ * (e.g. `HMRouterPlugin` for a Node hvigor plugin living beside HAP modules).
+ */
+function listSyntheticArkModuleRoots(rootDir, scannedFiles, harmonyModules) {
+    const modules = harmonyModules ?? listHarmonyProjectModules(rootDir);
+    const orphans = listOrphanArkAnalyzerSources(scannedFiles, modules);
+    const bySrc = new Map();
+    for (const f of orphans) {
+        const srcPath = findSyntheticArkModuleRoot(rootDir, f);
+        if (!srcPath)
+            continue;
+        // Never shadow a real Harmony module path.
+        if (modules.some((m) => m.srcPath === srcPath))
+            continue;
+        if (bySrc.has(srcPath))
+            continue;
+        const abs = path.resolve(rootDir, srcPath);
+        if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory())
+            continue;
+        bySrc.set(srcPath, {
+            name: `synthetic:${path.basename(srcPath)}`,
+            srcPath,
+        });
+    }
+    return [...bySrc.values()].sort((a, b) => a.srcPath.localeCompare(b.srcPath));
+}
+/**
+ * Register orphan trees as PROJECT modules before dependency analysis so they
+ * enter `analyseByModule` topo order. No `oh-package.json5` → empty dep edges
+ * (npm-only deps stay unresolved); that is expected for Node plugins.
+ */
+function registerSyntheticArkModules(builder, rootDir, scannedFiles, harmonyModules) {
+    const synthetics = listSyntheticArkModuleRoots(rootDir, scannedFiles, harmonyModules);
+    for (const syn of synthetics) {
+        const abs = resolveArkModuleAbsPath(rootDir, syn.srcPath);
+        builder.registerModule(abs, syn.name);
+    }
+    return synthetics;
+}
+/** Prep PROJECT + oh_modules, inject synthetic orphan modules, then build the dep graph. */
+function prepareArkModulesWithSynthetics(scene, rootDir, scannedFiles) {
+    if (scene.isModulesRegistered())
+        return [];
+    const builder = new arkanalyzer_1.ModuleBuilder(scene);
+    builder.prepareModules();
+    const harmonyModules = listHarmonyProjectModules(rootDir);
+    const synthetics = registerSyntheticArkModules(builder, rootDir, scannedFiles, harmonyModules);
+    builder.analyzeModuleDependencies();
+    scene.setModulesRegistered(true);
+    return synthetics;
+}
 function findLongestHarmonyModule(fileRel, modules) {
     const file = normIndexPath(fileRel);
     let best = null;
@@ -367,8 +486,9 @@ function findLongestHarmonyModule(fileRel, modules) {
 }
 /**
  * Map changed/removed paths to Harmony modules for incremental ArkTS sync.
- * Structural project files (`build-profile.json5`, root `oh-package.json5`) or
- * ArkAnalyzer sources outside every module force a full rebuild.
+ * Structural project files (`build-profile.json5`, root `oh-package.json5`)
+ * force a full rebuild. Orphan trees covered by synthetic PROJECT modules
+ * (e.g. `HMRouterPlugin`) map to those module srcPaths instead of full rebuild.
  */
 function resolveDirtyHarmonyModules(rootDir, changedFiles) {
     if (!shouldUseModularArkTSBuild(rootDir)) {
@@ -389,17 +509,22 @@ function resolveDirtyHarmonyModules(rootDir, changedFiles) {
             return { mode: 'full', reason: 'root oh-package.json5 changed' };
         }
     }
+    // Synthetic roots for orphans among the changed set (cheap; no full scan).
+    const synthetics = listSyntheticArkModuleRoots(rootDir, changed, modules);
+    const allModules = [...modules, ...synthetics];
     const dirty = new Set();
     const unmatched = [];
     for (const f of changed) {
         // Virtual ArkAnalyzer paths are batch artifacts, not Harmony module sources.
         if (f.startsWith('@'))
             continue;
-        const isModuleMeta = f.endsWith('/module.json5') || f.endsWith('/oh-package.json5');
+        const isModuleMeta = f.endsWith('/module.json5') ||
+            f.endsWith('/oh-package.json5') ||
+            f.endsWith('/package.json');
         const isArkSrc = isArkAnalyzerSourcePath(f);
         if (!isArkSrc && !isModuleMeta)
             continue;
-        const match = findLongestHarmonyModule(f, modules);
+        const match = findLongestHarmonyModule(f, allModules);
         if (match)
             dirty.add(match.srcPath);
         else if (isArkSrc)
@@ -430,6 +555,21 @@ function isArkAnalyzerSourcePath(filePath) {
     // `.d.ts` ends with `.ts` (Node extname) — one `.ts` suffix covers both.
     return base.endsWith('.ets') || base.endsWith('.ts');
 }
+/**
+ * Graph `language` tag for an ArkAnalyzer-indexed path. Extraction still uses AA;
+ * the tag must match the source kind so status / language filters stay truthful.
+ */
+function languageForArkAnalyzerPath(filePath) {
+    const base = path.basename(filePath).toLowerCase();
+    if (base.endsWith('.d.ets') || base.endsWith('.ets'))
+        return 'arkts';
+    if (base.endsWith('.d.ts') || base.endsWith('.ts') || base.endsWith('.mts') || base.endsWith('.cts')) {
+        return 'typescript';
+    }
+    if (base.endsWith('.js') || base.endsWith('.mjs') || base.endsWith('.cjs'))
+        return 'javascript';
+    return 'arkts';
+}
 function isEtsFileName(name) {
     return name.endsWith('.ets');
 }
@@ -634,7 +774,7 @@ function persistFileResult(queries, filePath, content, stats, result, options) {
             .map((ref) => ({
             ...ref,
             filePath: ref.filePath ?? filePath,
-            language: ref.language ?? 'arkts',
+            language: ref.language ?? languageForArkAnalyzerPath(filePath),
         }));
         if (refsWithContext.length > 0) {
             queries.insertUnresolvedRefsBatch(refsWithContext);
@@ -643,7 +783,7 @@ function persistFileResult(queries, filePath, content, stats, result, options) {
     const fileRecord = {
         path: filePath,
         contentHash,
-        language: 'arkts',
+        language: languageForArkAnalyzerPath(filePath),
         size: stats.size,
         modifiedAt: stats.mtimeMs,
         indexedAt: Date.now(),
@@ -1197,12 +1337,27 @@ class ArkTSExtractor {
     }
 }
 exports.ArkTSExtractor = ArkTSExtractor;
+/** ArkAnalyzer {@link ClassCategory} (not re-exported from the npm entry). */
 const CLASS_CATEGORY = {
     CLASS: 0,
     STRUCT: 1,
     INTERFACE: 2,
     ENUM: 3,
+    TYPE_LITERAL: 4,
+    OBJECT: 5,
+    /** C++ frontend only; never map to HomeGraph `class`. */
+    UNION: 6,
 };
+/**
+ * IR shapes that are `ArkClass` in ArkAnalyzer but are not declaration-level
+ * types in HomeGraph's symbol graph. Indexing them as `class` inflates
+ * `graph_class` and orphans them under the file node.
+ */
+function isNonDeclarationArkClassCategory(category) {
+    return (category === CLASS_CATEGORY.TYPE_LITERAL ||
+        category === CLASS_CATEGORY.OBJECT ||
+        category === CLASS_CATEGORY.UNION);
+}
 /** ArkAnalyzer {@link FieldCategory} values (not re-exported from the npm entry). */
 const FIELD_CATEGORY = {
     PROPERTY_DECLARATION: 0,
@@ -1382,7 +1537,10 @@ function classNodeKind(cls) {
             return 'enum';
         case CLASS_CATEGORY.STRUCT:
             return 'struct';
+        case CLASS_CATEGORY.CLASS:
+            return 'class';
         default:
+            // TYPE_LITERAL / OBJECT / UNION must be filtered before indexClass.
             return 'class';
     }
 }
@@ -3048,7 +3206,7 @@ class ArkTSAdapter {
         let result = this.fileResults.get(relativePath);
         if (!result) {
             result = {
-                nodes: [makeFileNode(relativePath, 'arkts', lineCount)],
+                nodes: [makeFileNode(relativePath, languageForArkAnalyzerPath(relativePath), lineCount)],
                 edges: [],
                 unresolvedReferences: [],
                 errors: [],
@@ -3067,7 +3225,7 @@ class ArkTSAdapter {
     }
     indexFile(arkFile) {
         const relativePath = this.normalizeRelPath(arkFile.getFilePath());
-        const language = 'arkts';
+        const language = languageForArkAnalyzerPath(relativePath);
         let lineCount = 1;
         try {
             lineCount = arkFile.getCode()?.split('\n').length ?? 1;
@@ -3160,6 +3318,7 @@ class ArkTSAdapter {
         const localNode = makeNode(relativePath, language, kind, name, qn, line, endLine, col, {
             signature: local.getType()?.toString(),
             ...modelModifiersToNodeExtras(local),
+            // Local's public TS surface doesn't declare getMetadata; runtime may still carry it.
             ...docstringExtras(local),
         });
         this.addNode(result, localNode);
@@ -3179,6 +3338,7 @@ class ArkTSAdapter {
             const aliasNode = makeNode(relativePath, language, 'type_alias', name, qn, line, endLine, col, {
                 signature: aliasType.getOriginalType()?.toString(),
                 ...modelModifiersToNodeExtras(aliasType),
+                // AliasType's public TS surface doesn't declare getMetadata; runtime may still carry it.
                 ...docstringExtras(aliasType),
             });
             this.addNode(result, aliasNode);
@@ -3232,6 +3392,10 @@ class ArkTSAdapter {
     indexClass(relativePath, language, result, cls, parentId) {
         if (cls.isDefaultArkClass())
             return;
+        // Object / type literals (and C++ unions) are ArkAnalyzer IR classes, not
+        // HomeGraph declaration nodes — skip the shell and its nested fields.
+        if (isNonDeclarationArkClassCategory(cls.getCategory()))
+            return;
         const displayName = classDisplayName(cls);
         const qn = buildClassQualifiedName(cls);
         const kind = classNodeKind(cls);
@@ -3581,7 +3745,7 @@ class ArkTSAdapter {
         if (classId)
             return classId;
         const fileId = `file:${relativePath}`;
-        this.indexClass(relativePath, 'arkts', result, cls, fileId);
+        this.indexClass(relativePath, languageForArkAnalyzerPath(relativePath), result, cls, fileId);
         return this.resolveClassNodeId(cls) ?? fileId;
     }
     /**
@@ -3622,7 +3786,7 @@ class ArkTSAdapter {
         const parentId = this.resolveMethodParentId(method, relativePath, result);
         const cls = method.getDeclaringArkClass();
         const kind = cls.isDefaultArkClass() ? 'function' : 'method';
-        this.indexMethod(relativePath, 'arkts', result, method, parentId, kind, displayName);
+        this.indexMethod(relativePath, languageForArkAnalyzerPath(relativePath), result, method, parentId, kind, displayName);
         return this.methodToId.get(method) ?? null;
     }
     addViewTreeEdge(result, source, target, kind, callerFile, via, line, extraMeta) {
@@ -3666,7 +3830,7 @@ class ArkTSAdapter {
             return null;
         const cls = method.getDeclaringArkClass();
         const kind = cls.isDefaultArkClass() ? 'function' : 'method';
-        this.indexMethod(relativePath, 'arkts', result, method, parentId, kind, displayName);
+        this.indexMethod(relativePath, languageForArkAnalyzerPath(relativePath), result, method, parentId, kind, displayName);
         return this.methodToId.get(method) ?? null;
     }
     indexMethod(relativePath, language, result, method, parentId, forcedKind, forcedDisplayName) {
@@ -3871,23 +4035,21 @@ function buildArkTSIndexByModuleInner(rootDir, scannedFiles, options) {
     };
     try {
         scene.config(sceneConfig);
+        // Register build-profile modules + orphan trees (no oh-package) before the
+        // dep graph is frozen — otherwise analyseByModule never sees HMRouterPlugin-style .ts.
+        const synthetics = prepareArkModulesWithSynthetics(scene, rootDir, scannedList);
+        if (synthetics.length > 0) {
+            process.stderr.write(`\n\x1b[33m    ArkTS: synthetic PROJECT modules (${synthetics.length}, no oh-package deps): ${synthetics
+                .map((s) => s.srcPath)
+                .join(', ')}...\x1b[0m\n`);
+        }
         const config = new arkanalyzer_1.ModuleAnalysisConfig();
         config.setLoadLevel(arkanalyzer_1.ModuleDepthLevel.BODIES);
         // SIGNATURES is enough for ViewTree stubs / types; BODIES on deps caused
         // each module's RTA to re-walk shared library CFGs (multi-hour indexes).
         config.setDependencyLoadLevel(arkanalyzer_1.ModuleDepthLevel.SIGNATURES);
         if (targetSrcSet) {
-            // Prep + SDK only (no PROJECT targets) so we can resolve ModuleIDs.
-            scene.analyseByModule(() => { }, new arkanalyzer_1.ModuleAnalysisConfig());
-            const wantAbs = new Set([...targetSrcSet].map((src) => {
-                const resolved = path.resolve(rootDir, src);
-                try {
-                    return fs.realpathSync(resolved).toLowerCase();
-                }
-                catch {
-                    return resolved.toLowerCase();
-                }
-            }));
+            const wantAbs = new Set([...targetSrcSet].map((src) => resolveArkModuleAbsPath(rootDir, src).toLowerCase()));
             const ids = [];
             for (const mod of scene.getModules()) {
                 if (mod.getModuleType() !== arkanalyzer_1.ModuleType.PROJECT)