homegraph 1.1.2 → 1.2.0

package/dist/extraction/languages/arkts.js

@@ -42,18 +42,248 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ArkTSExtractor = void 0;
+exports.OHOS_API_DB_PATH_META = exports.OHOS_API_VERSION_META = exports.OHOS_API_FILE_PREFIX = exports.OhosSdkInputError = exports.ArkTSExtractor = void 0;
+exports.cleanArkTypeString = cleanArkTypeString;
+exports.normalizeArktsReturnType = normalizeArktsReturnType;
+exports.buildArkMethodSignatureFields = buildArkMethodSignatureFields;
+exports.isArkAnalyzerSourcePath = isArkAnalyzerSourcePath;
+exports.runIsolatedArkTSBatchEntry = runIsolatedArkTSBatchEntry;
+exports.primeArkTSBatch = primeArkTSBatch;
+exports.isArkTSBatchPersisted = isArkTSBatchPersisted;
 exports.resetArkTSBatch = resetArkTSBatch;
+exports.stateDecoratorKinds = stateDecoratorKinds;
+exports.stateTransferViaForField = stateTransferViaForField;
+exports.drainArkTSIndexNotices = drainArkTSIndexNotices;
+exports.parseOhosToolsVersionFromName = parseOhosToolsVersionFromName;
+exports.isArchivePath = isArchivePath;
+exports.findOhosSdkHome = findOhosSdkHome;
+exports.hasOpenHarmonyEts = hasOpenHarmonyEts;
+exports.listOhosApiEtsRoots = listOhosApiEtsRoots;
+exports.resolveOhosSdkInput = resolveOhosSdkInput;
+exports.ohosApiDbFilename = ohosApiDbFilename;
+exports.ohosApiDbPackageName = ohosApiDbPackageName;
+exports.ohosApiDbInstallPath = ohosApiDbInstallPath;
+exports.indexOhosApiDb = indexOhosApiDb;
+exports.markOhosApiFilePath = markOhosApiFilePath;
+exports.isOhosApiFilePath = isOhosApiFilePath;
+exports.parseJson5Minimal = parseJson5Minimal;
+exports.normalizeOhosApiVersion = normalizeOhosApiVersion;
+exports.detectOhosCompileSdkVersion = detectOhosCompileSdkVersion;
+exports.isOhosArktsProject = isOhosArktsProject;
+exports.ensureOhosApiDb = ensureOhosApiDb;
+exports.bindOhosApiDbForProject = bindOhosApiDbForProject;
+exports.restoreOhosApiDbAttach = restoreOhosApiDbAttach;
 const crypto = __importStar(require("crypto"));
 const fs = __importStar(require("fs"));
+const fsp = __importStar(require("fs/promises"));
+const os = __importStar(require("os"));
 const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
 const arkanalyzer_1 = require("arkanalyzer");
-const tree_sitter_helpers_1 = require("../tree-sitter-helpers");
+const db_1 = require("../../db");
+const queries_1 = require("../../db/queries");
 const context_1 = require("../context");
-const arkts_viewtree_1 = require("./arkts-viewtree");
+const extraction_version_1 = require("../extraction-version");
+const version_1 = require("../../mcp/version");
+const tree_sitter_helpers_1 = require("../tree-sitter-helpers");
+const wasm_runtime_flags_1 = require("../wasm-runtime-flags");
+/** Primitive / void return types — not stored in nodes.return_type (inference-only column). */
+const ARKTS_NON_CLASS_RETURN = new Set([
+    'void',
+    'number',
+    'string',
+    'boolean',
+    'bigint',
+    'undefined',
+    'null',
+    'never',
+    'any',
+    'unknown',
+    'Object',
+]);
+/** Strip arkanalyzer file-location prefixes from type text (`@proj/file.ets: Foo` → `Foo`). */
+function cleanArkTypeString(raw) {
+    return raw.replace(/@[^/\s]+\/[^\s:]*:\s*/g, '').trim();
+}
+/**
+ * Normalize an ArkTS method return type to a bare class name for receiver inference
+ * (aligned with C++/Java `return_type` usage elsewhere in HomeGraph).
+ */
+function normalizeArktsReturnType(raw) {
+    if (!raw)
+        return undefined;
+    let t = cleanArkTypeString(raw);
+    if (!t || ARKTS_NON_CLASS_RETURN.has(t))
+        return undefined;
+    // Unwrap common wrappers to the pointee (`Promise<Foo>` → `Foo`).
+    const wrapper = t.match(/\b(?:Promise|Array|ReadonlyArray|Set|Map)\s*<\s*([^,>]+?)\s*>/);
+    if (wrapper?.[1])
+        t = wrapper[1].trim();
+    t = t.replace(/<[^>]*>/g, ' ').replace(/\[\]/g, ' ').replace(/\s+/g, ' ').trim();
+    if (!t || ARKTS_NON_CLASS_RETURN.has(t))
+        return undefined;
+    const last = t.split('.').filter(Boolean).pop() ?? t;
+    return last || undefined;
+}
+function formatArkMethodSignatureLine(method, sig, useParamNames) {
+    const sub = sig.getMethodSubSignature();
+    const name = sub.getMethodName();
+    const ret = cleanArkTypeString(sub.getReturnType()?.toString() ?? 'void');
+    const paramTypes = sub.getParameterTypes();
+    let params;
+    if (useParamNames) {
+        const named = method.getParameters();
+        if (named.length > 0 && named.length === paramTypes.length) {
+            params = named
+                .map((p, i) => {
+                const rest = p.isRest?.() ? '...' : '';
+                const optional = p.isOptional?.() ? '?' : '';
+                const typeStr = cleanArkTypeString(p.getType()?.toString() ?? paramTypes[i]?.toString() ?? 'unknown');
+                return `${rest}${p.getName()}${optional}: ${typeStr}`;
+            })
+                .join(', ');
+        }
+        else {
+            params = paramTypes
+                .map((t) => cleanArkTypeString(t?.toString() ?? 'unknown'))
+                .join(', ');
+        }
+    }
+    else {
+        params = paramTypes
+            .map((t) => cleanArkTypeString(t?.toString() ?? 'unknown'))
+            .join(', ');
+    }
+    const prefix = sub.isStatic() ? 'static ' : '';
+    return `${prefix}${name}(${params}): ${ret}`;
+}
+/** Collect human-readable signature lines (canonical first, overloads on following lines). */
+function buildArkMethodSignatureFields(method) {
+    const impl = method.getImplementationSignature();
+    const declares = method.getDeclareSignatures();
+    const primary = impl ?? method.getSignature();
+    if (!primary && (!declares || declares.length === 0))
+        return {};
+    const lines = [];
+    const seen = new Set();
+    const push = (line) => {
+        const trimmed = line.trim();
+        if (!trimmed || seen.has(trimmed))
+            return;
+        seen.add(trimmed);
+        lines.push(trimmed);
+    };
+    if (impl) {
+        push(formatArkMethodSignatureLine(method, impl, true));
+    }
+    if (declares?.length) {
+        for (const d of declares) {
+            push(formatArkMethodSignatureLine(method, d, false));
+        }
+    }
+    else if (!impl && primary) {
+        push(formatArkMethodSignatureLine(method, primary, true));
+    }
+    if (lines.length === 0)
+        return {};
+    const canonicalSig = impl ?? declares?.[0] ?? primary;
+    const retRaw = canonicalSig.getMethodSubSignature().getReturnType()?.toString();
+    return {
+        signature: lines.join('\n'),
+        returnType: normalizeArktsReturnType(retRaw),
+    };
+}
+/** Parallel read chunk size during ArkTS batch persist (writes stay sequential for SQLite). */
+function resolveArkTSPersistParallel(etsFileCount) {
+    const raw = process.env.HOMEGRAPH_ARKTS_PERSIST_PARALLEL?.trim();
+    if (raw !== undefined && raw !== '') {
+        const n = parseInt(raw, 10);
+        if (!Number.isNaN(n) && n >= 1)
+            return n;
+    }
+    // Large repos: serial reads — slower but stable on Windows / huge trees.
+    if (etsFileCount >= 500)
+        return 1;
+    return 8;
+}
+/** Stack sizes (KB) for isolated ArkTS worker retries (Windows native stack overflow). */
+function resolveArkTSWorkerStackSizesKb() {
+    const raw = process.env.HOMEGRAPH_ARKTS_STACK_SIZES_KB?.trim();
+    if (raw) {
+        const parsed = raw.split(',').map((s) => parseInt(s.trim(), 10)).filter((n) => n > 0);
+        if (parsed.length > 0)
+            return parsed;
+    }
+    return [32768, 65536, 131072, 262144];
+}
+/** Windows STATUS_STACK_OVERFLOW — process killed during deep native/JS recursion. */
+function isStackOverflowExitCode(code) {
+    if (code === null)
+        return false;
+    return code === 3221225725 || code === -1073741571;
+}
+function shouldUseIsolatedArkTSBuild(etsCount) {
+    const mode = process.env.HOMEGRAPH_ARKTS_ISOLATED?.trim();
+    if (mode === '1' || mode === 'true')
+        return true;
+    if (mode === '0' || mode === 'false')
+        return false;
+    // Photos-scale repos on Windows: build Scene in a child with a larger stack.
+    if (process.platform === 'win32' && etsCount >= 500)
+        return true;
+    return false;
+}
+function homegraphDbPath(rootDir) {
+    return path.join(rootDir, '.homegraph', 'homegraph.db');
+}
 const ARK_PROVENANCE = 'heuristic';
 /** Virtual file path for ArkAnalyzer's in-scene dummy entry (not on disk). */
 const ARKANALYZER_DUMMY_FILE = '@dummyFile.ets';
+/** HarmonyOS sources indexed via ArkAnalyzer Scene batch (`.ets`, `.ts`, `.d.ts`). */
+function isArkAnalyzerSourcePath(filePath) {
+    const base = path.basename(filePath);
+    // `.d.ts` ends with `.ts` (Node extname) — one `.ts` suffix covers both.
+    return base.endsWith('.ets') || base.endsWith('.ts');
+}
+function isEtsFileName(name) {
+    return name.endsWith('.ets');
+}
+function isCoLocatedArkTsFileName(name) {
+    return isArkAnalyzerSourcePath(name) && !isEtsFileName(name);
+}
+/** True when the tree looks like a HarmonyOS / ArkTS project (not a generic TS repo). */
+function hasHarmonyProjectMarkers(rootDir) {
+    const found = [];
+    function walk(dir) {
+        if (found.length > 0)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === '.homegraph') {
+                    continue;
+                }
+                walk(full);
+            }
+            else if (entry.isFile() && (isEtsFileName(entry.name) || entry.name === 'module.json5')) {
+                found.push(full);
+                return;
+            }
+        }
+    }
+    walk(rootDir);
+    return found.length > 0;
+}
+function normIndexPath(filePath) {
+    return filePath.replace(/\\/g, '/');
+}
 /** Member calls through a native `.so` binding: `sdk.Asset_setCropRect(`. */
 const NAPI_MEMBER_CALL_RE = /\.\s*([A-Z][A-Za-z0-9_]*(?:_[A-Za-z0-9_]+)+)\s*\(/g;
 function isNapiSymbolName(name) {
@@ -62,6 +292,8 @@ function isNapiSymbolName(name) {
 let persistedBatch = null;
 /** File that triggered the most recent batch persist (for indexAll edge stats). */
 let batchTriggerFile = null;
+/** Paths written by the current in-memory batch (fast skip for later .ets hits). */
+let batchPersistedPaths = new Set();
 function hashContent(content) {
     return crypto.createHash('sha256').update(content).digest('hex');
 }
@@ -75,7 +307,8 @@ function emptyResult(filePath, message, severity) {
     };
 }
 function scanEtsFiles(rootDir) {
-    const found = [];
+    const etsFiles = [];
+    const coLocated = [];
     function walk(dir) {
         let entries;
         try {
@@ -91,25 +324,40 @@ function scanEtsFiles(rootDir) {
                     continue;
                 walk(full);
             }
-            else if (entry.isFile() && entry.name.endsWith('.ets')) {
-                found.push(path.relative(rootDir, full).replace(/\\/g, '/'));
+            else if (entry.isFile()) {
+                const rel = path.relative(rootDir, full).replace(/\\/g, '/');
+                if (isEtsFileName(entry.name)) {
+                    etsFiles.push(rel);
+                }
+                else if (isCoLocatedArkTsFileName(entry.name)) {
+                    coLocated.push(rel);
+                }
             }
         }
     }
     walk(rootDir);
+    if (etsFiles.length === 0 && !hasHarmonyProjectMarkers(rootDir)) {
+        return [];
+    }
+    const found = etsFiles.length > 0 ? [...etsFiles, ...coLocated] : coLocated;
     found.sort();
     return found;
 }
 function computeBatchKey(rootDir, etsFiles) {
+    // mtime + size only — full content hashes happen per-file at persist time.
     return etsFiles
         .map((rel) => {
         const full = path.join(rootDir, rel);
         const stat = fs.statSync(full);
-        const content = fs.readFileSync(full, 'utf-8');
-        return `${rel}:${stat.mtimeMs}:${hashContent(content)}`;
+        return `${rel}:${stat.mtimeMs}:${stat.size}`;
     })
         .join('\0');
 }
+/** True when a full ArkTS batch has been committed for this index run. */
+let batchBuildCommitted = false;
+function reportBatchProgress(subphase, current, total, currentFile) {
+    (0, context_1.reportArkTSBatchProgress)({ subphase, current, total, currentFile });
+}
 function persistFileResult(queries, filePath, content, stats, result) {
     const contentHash = hashContent(content);
     const existingFile = queries.getFileByPath(filePath);
@@ -155,18 +403,128 @@ function persistFileResult(queries, filePath, content, stats, result) {
     };
     queries.upsertFile(fileRecord);
 }
-/** Build Scene, run RTA, and write every `.ets` file + cross-file edges to the DB. */
-function runArkTSBatch(rootDir, queries, triggerFile) {
-    const etsFiles = scanEtsFiles(rootDir);
+async function persistBatchResultsAsync(rootDir, queries, index) {
+    const entries = [...index.fileResults.entries()];
+    const persistTotal = entries.length;
+    const parallel = resolveArkTSPersistParallel(persistTotal);
+    for (let start = 0; start < entries.length; start += parallel) {
+        const chunk = entries.slice(start, start + parallel);
+        const prepared = await Promise.all(chunk.map(async ([filePath, fileResult]) => {
+            const isVirtual = filePath.startsWith('@');
+            if (isVirtual) {
+                return {
+                    filePath,
+                    fileResult,
+                    content: '',
+                    stats: { size: 0, mtimeMs: Date.now() },
+                };
+            }
+            const full = path.join(rootDir, filePath);
+            const [content, stats] = await Promise.all([
+                fsp.readFile(full, 'utf-8'),
+                fsp.stat(full),
+            ]);
+            return { filePath, fileResult, content, stats };
+        }));
+        for (let i = 0; i < prepared.length; i++) {
+            const persistIndex = start + i + 1;
+            const item = prepared[i];
+            reportBatchProgress('persist', persistIndex, persistTotal, item.filePath);
+            persistFileResult(queries, item.filePath, item.content, item.stats, item.fileResult);
+        }
+    }
+}
+function persistBatchResultsSync(rootDir, queries, index) {
+    const persistTotal = index.fileResults.size;
+    let persistIndex = 0;
+    for (const [filePath, fileResult] of index.fileResults) {
+        persistIndex++;
+        reportBatchProgress('persist', persistIndex, persistTotal, filePath);
+        const isVirtual = filePath.startsWith('@');
+        const full = path.join(rootDir, filePath);
+        const content = isVirtual ? '' : fs.readFileSync(full, 'utf-8');
+        const stats = isVirtual
+            ? { size: 0, mtimeMs: Date.now() }
+            : fs.statSync(full);
+        persistFileResult(queries, filePath, content, stats, fileResult);
+    }
+}
+function commitArkTSBatch(rootDir, batchKey, etsFiles, index, triggerFile) {
+    batchPersistedPaths = new Set([...index.fileResults.keys()].map(normIndexPath));
+    persistedBatch = { ...index, rootDir, batchKey, etsFiles };
+    batchTriggerFile = normIndexPath(triggerFile);
+    if (index.fileResults.size > 0) {
+        batchBuildCommitted = true;
+    }
+    return persistedBatch;
+}
+function tryReturnCachedBatch(rootDir, triggerFile, etsFiles) {
+    const normalizedTrigger = normIndexPath(triggerFile);
+    if (persistedBatch &&
+        persistedBatch.rootDir === rootDir &&
+        batchPersistedPaths.has(normalizedTrigger)) {
+        return persistedBatch;
+    }
     const batchKey = etsFiles.length > 0 ? computeBatchKey(rootDir, etsFiles) : '';
     if (persistedBatch &&
         persistedBatch.rootDir === rootDir &&
+        persistedBatch.batchKey === batchKey &&
+        persistedBatch.fileResults.size > 0) {
+        batchPersistedPaths = new Set([...persistedBatch.fileResults.keys()].map(normIndexPath));
+        return persistedBatch;
+    }
+    if (batchBuildCommitted &&
+        persistedBatch &&
+        persistedBatch.rootDir === rootDir &&
+        persistedBatch.fileResults.size > 0 &&
         persistedBatch.batchKey === batchKey) {
         return persistedBatch;
     }
+    return null;
+}
+function markBatchCommittedAfterWorker(rootDir, triggerFile, etsFiles, batchKey) {
+    batchTriggerFile = normIndexPath(triggerFile);
+    batchPersistedPaths = new Set(etsFiles.map(normIndexPath));
+    batchBuildCommitted = true;
+    persistedBatch = {
+        fileResults: new Map(),
+        crossFileEdges: [],
+        nodeIds: new Set(),
+        errors: [],
+        rootDir,
+        batchKey,
+        etsFiles,
+    };
+    return persistedBatch;
+}
+function spawnIsolatedArkTSBatchWorker(rootDir, dbPath, triggerFile) {
+    const workerPath = path.join(__dirname, '..', 'arkts-batch-worker.js');
+    let lastCode = null;
+    for (const stackKb of resolveArkTSWorkerStackSizesKb()) {
+        process.stderr.write(`\n\x1b[33m    ArkTS: full Scene build in isolated process (--stack-size=${stackKb} KB, enableMethodBodyBuild=true)...\x1b[0m\n`);
+        const argv = (0, wasm_runtime_flags_1.buildRelaunchArgv)(workerPath, [rootDir, dbPath, triggerFile], [`--stack-size=${stackKb}`]);
+        const result = (0, child_process_1.spawnSync)(process.execPath, argv, {
+            stdio: 'inherit',
+            env: process.env,
+            timeout: 60 * 60 * 1000,
+            windowsHide: true,
+        });
+        lastCode = result.status;
+        if (result.status === 0) {
+            return { ok: true, lastCode };
+        }
+        if (!isStackOverflowExitCode(result.status)) {
+            break;
+        }
+    }
+    return { ok: false, lastCode };
+}
+function runArkTSBatchFullCore(rootDir, queries, triggerFile, etsFiles, batchKey) {
     batchTriggerFile = null;
+    batchPersistedPaths = new Set();
     if (etsFiles.length === 0) {
         persistedBatch = null;
+        batchBuildCommitted = false;
         return {
             fileResults: new Map(),
             crossFileEdges: [],
@@ -174,33 +532,131 @@ function runArkTSBatch(rootDir, queries, triggerFile) {
             errors: [],
             rootDir,
             batchKey: '',
+            etsFiles: [],
         };
     }
-    const index = buildArkTSIndex(rootDir, etsFiles);
-    queries.deleteArkTSCrossFileCallEdges();
-    for (const [filePath, fileResult] of index.fileResults) {
-        const isVirtual = filePath.startsWith('@');
-        const full = path.join(rootDir, filePath);
-        const content = isVirtual ? '' : fs.readFileSync(full, 'utf-8');
-        const stats = isVirtual
-            ? { size: 0, mtimeMs: Date.now() }
-            : fs.statSync(full);
-        persistFileResult(queries, filePath, content, stats, fileResult);
+    (0, context_1.setArktsBatchRunning)(true);
+    try {
+        reportBatchProgress('scene', 0, etsFiles.length);
+        const index = buildArkTSIndex(rootDir, etsFiles);
+        if (index.fileResults.size === 0) {
+            const fatal = index.errors.find((e) => e.severity === 'error');
+            throw new Error(fatal?.message ?? 'ArkTS batch produced no indexed files');
+        }
+        queries.deleteArkTSCrossFileCallEdges();
+        persistBatchResultsSync(rootDir, queries, index);
+        if (index.crossFileEdges.length > 0) {
+            const valid = index.crossFileEdges.filter((e) => index.nodeIds.has(e.source) && index.nodeIds.has(e.target));
+            if (valid.length > 0) {
+                queries.insertEdges(valid);
+            }
+        }
+        return commitArkTSBatch(rootDir, batchKey, etsFiles, index, triggerFile);
+    }
+    finally {
+        (0, context_1.setArktsBatchRunning)(false);
     }
-    if (index.crossFileEdges.length > 0) {
-        const valid = index.crossFileEdges.filter((e) => index.nodeIds.has(e.source) && index.nodeIds.has(e.target));
-        if (valid.length > 0) {
-            queries.insertEdges(valid);
+}
+function runArkTSBatchFull(rootDir, queries, triggerFile, etsFiles, batchKey) {
+    if (shouldUseIsolatedArkTSBuild(etsFiles.length)) {
+        const dbPath = homegraphDbPath(rootDir);
+        if (!fs.existsSync(dbPath)) {
+            throw new Error(`ArkTS isolated build requires ${dbPath}`);
+        }
+        (0, context_1.setArktsBatchRunning)(true);
+        try {
+            reportBatchProgress('scene', 0, etsFiles.length);
+            const spawned = spawnIsolatedArkTSBatchWorker(rootDir, dbPath, triggerFile);
+            if (!spawned.ok) {
+                throw new Error(`ArkTS isolated Scene build failed (exit ${spawned.lastCode ?? 'unknown'}). ` +
+                    'Try HOMEGRAPH_ARKTS_STACK_SIZES_KB=65536,131072,262144');
+            }
+            return markBatchCommittedAfterWorker(rootDir, triggerFile, etsFiles, batchKey);
+        }
+        finally {
+            (0, context_1.setArktsBatchRunning)(false);
         }
     }
-    persistedBatch = { ...index, rootDir, batchKey };
-    batchTriggerFile = triggerFile;
-    return persistedBatch;
+    return runArkTSBatchFullCore(rootDir, queries, triggerFile, etsFiles, batchKey);
 }
-/** Clear cached batch state (tests). */
+/** Worker entry — full batch in an isolated process (no nested spawn). */
+function runIsolatedArkTSBatchEntry(rootDir, dbPath, triggerFile) {
+    const db = db_1.DatabaseConnection.open(dbPath);
+    try {
+        const queries = new queries_1.QueryBuilder(db.getDb());
+        (0, context_1.bindExtractionContext)(rootDir, queries);
+        const etsFiles = scanEtsFiles(rootDir);
+        const batchKey = etsFiles.length > 0 ? computeBatchKey(rootDir, etsFiles) : '';
+        runArkTSBatchFullCore(rootDir, queries, normIndexPath(triggerFile), etsFiles, batchKey);
+    }
+    finally {
+        db.close();
+    }
+}
+/** Build Scene, run RTA, and write every `.ets` file + cross-file edges to the DB. */
+function runArkTSBatch(rootDir, queries, triggerFile) {
+    const normalizedTrigger = normIndexPath(triggerFile);
+    const etsFiles = scanEtsFiles(rootDir);
+    const cached = tryReturnCachedBatch(rootDir, normalizedTrigger, etsFiles);
+    if (cached) {
+        return cached;
+    }
+    const batchKey = etsFiles.length > 0 ? computeBatchKey(rootDir, etsFiles) : '';
+    return runArkTSBatchFull(rootDir, queries, normalizedTrigger, etsFiles, batchKey);
+}
+/** Async batch build with parallel file reads during persist (used by indexAll). */
+async function primeArkTSBatch(rootDir, queries, triggerFile) {
+    const normalizedTrigger = normIndexPath(triggerFile);
+    const etsFiles = scanEtsFiles(rootDir);
+    const cached = tryReturnCachedBatch(rootDir, normalizedTrigger, etsFiles);
+    if (cached) {
+        return;
+    }
+    const batchKey = etsFiles.length > 0 ? computeBatchKey(rootDir, etsFiles) : '';
+    batchTriggerFile = null;
+    batchPersistedPaths = new Set();
+    if (etsFiles.length === 0) {
+        persistedBatch = null;
+        batchBuildCommitted = false;
+        return;
+    }
+    if (shouldUseIsolatedArkTSBuild(etsFiles.length)) {
+        runArkTSBatchFull(rootDir, queries, normalizedTrigger, etsFiles, batchKey);
+        return;
+    }
+    (0, context_1.setArktsBatchRunning)(true);
+    try {
+        reportBatchProgress('scene', 0, etsFiles.length);
+        const index = buildArkTSIndex(rootDir, etsFiles);
+        if (index.fileResults.size === 0) {
+            const fatal = index.errors.find((e) => e.severity === 'error');
+            throw new Error(fatal?.message ?? 'ArkTS batch produced no indexed files');
+        }
+        queries.deleteArkTSCrossFileCallEdges();
+        await persistBatchResultsAsync(rootDir, queries, index);
+        if (index.crossFileEdges.length > 0) {
+            const valid = index.crossFileEdges.filter((e) => index.nodeIds.has(e.source) && index.nodeIds.has(e.target));
+            if (valid.length > 0) {
+                queries.insertEdges(valid);
+            }
+        }
+        commitArkTSBatch(rootDir, batchKey, etsFiles, index, normalizedTrigger);
+    }
+    finally {
+        (0, context_1.setArktsBatchRunning)(false);
+    }
+}
+/** True when this `.ets` file was already written by the in-memory ArkTS batch. */
+function isArkTSBatchPersisted(filePath) {
+    return batchPersistedPaths.has(normIndexPath(filePath));
+}
+/** Clear cached batch state (tests and full re-index). */
 function resetArkTSBatch() {
     persistedBatch = null;
     batchTriggerFile = null;
+    batchPersistedPaths = new Set();
+    batchBuildCommitted = false;
+    arktsIndexNotices = [];
 }
 class ArkTSExtractor {
     filePath;
@@ -217,21 +673,21 @@ class ArkTSExtractor {
                 durationMs: Date.now() - startTime,
             };
         }
-        const batch = runArkTSBatch(rootDir, queries, this.filePath);
+        const batch = runArkTSBatch(rootDir, queries, normIndexPath(this.filePath));
         if (batch.fileResults.size === 0) {
             return {
                 ...emptyResult(this.filePath, 'No .ets files in project', 'warning'),
                 durationMs: Date.now() - startTime,
             };
         }
-        const cached = batch.fileResults.get(this.filePath);
+        const cached = batch.fileResults.get(normIndexPath(this.filePath));
         if (!cached) {
             return {
                 ...emptyResult(this.filePath, 'File not present in ArkTS index', 'warning'),
                 durationMs: Date.now() - startTime,
             };
         }
-        const edges = this.filePath === batchTriggerFile
+        const edges = normIndexPath(this.filePath) === batchTriggerFile
             ? [...cached.edges, ...batch.crossFileEdges]
             : cached.edges;
         return {
@@ -305,10 +761,13 @@ function anonymousClassDisplayName(cls) {
 function classDisplayName(cls) {
     return cls.isAnonymousClass() ? anonymousClassDisplayName(cls) : cls.getName();
 }
+function isAnonymousArkMethod(method) {
+    return method.isAnonymousMethod?.() === true || method.getName().startsWith(arkanalyzer_1.ANONYMOUS_METHOD_PREFIX);
+}
 function shouldSkipArkMethod(method) {
     if (method.isDefaultArkMethod())
         return true;
-    if (method.isAnonymousMethod())
+    if (isAnonymousArkMethod(method))
         return true;
     const name = method.getName();
     if (name === arkanalyzer_1.DEFAULT_ARK_METHOD_NAME)
@@ -321,6 +780,15 @@ function shouldSkipArkMethod(method) {
         return true;
     return false;
 }
+/** User-facing or ArkAnalyzer-stable name for graph nodes (includes `%AMn` for anonymous). */
+function arkMethodDisplayName(method) {
+    const resolved = resolveMethodDisplayName(method);
+    if (resolved)
+        return resolved;
+    if (isAnonymousArkMethod(method))
+        return method.getName();
+    return null;
+}
 /** Decode ArkAnalyzer nested-method encoding (`%inner$outer`) to the user-visible name. */
 function resolveMethodDisplayName(method) {
     const name = method.getName();
@@ -371,11 +839,11 @@ function buildMethodQualifiedName(method, displayName) {
     }
     const outer = method.getOuterMethod();
     if (outer) {
-        const outerName = resolveMethodDisplayName(outer);
+        const outerName = arkMethodDisplayName(outer);
         if (outerName)
             parts.push(outerName);
     }
-    parts.push(displayName ?? resolveMethodDisplayName(method) ?? method.getName());
+    parts.push(displayName ?? arkMethodDisplayName(method) ?? method.getName());
     return buildQualifiedName(parts);
 }
 function buildClassQualifiedName(cls) {
@@ -558,6 +1026,138 @@ function sceneHasArkUiEntries(scene) {
     }
     return false;
 }
+// =============================================================================
+// ArkUI ViewTree — component tree, @Prop/@Link transfer, event bindings
+// =============================================================================
+const VIEWTREE_CALLBACK_ATTRS = new Set(arkanalyzer_1.CALLBACK_METHOD_NAME);
+/** State decorator kinds on a field (@State, @Prop, @Link, …) from arkanalyzer. */
+function stateDecoratorKinds(field) {
+    const decs = field.getStateDecorators?.();
+    if (!decs)
+        return [];
+    return [...decs].map((d) => d.getKind()).filter(Boolean);
+}
+/** Child @Prop / @Link — edge `via` uses the decorator name as-is. */
+function stateTransferViaForField(field) {
+    for (const kind of stateDecoratorKinds(field)) {
+        if (kind === 'Prop' || kind === 'Link')
+            return kind;
+    }
+    return null;
+}
+function viewTreeLineFromStmt(stmt) {
+    return stmt?.getOriginFullPosition()?.getFirstLine() ?? 1;
+}
+function isViewTreeClassSignature(sig) {
+    return sig instanceof arkanalyzer_1.ClassSignature;
+}
+function walkViewTree(node, visit) {
+    visit(node);
+    for (const child of node.children) {
+        walkViewTree(child, visit);
+    }
+}
+function indexViewTreeForClass(ctx, cls, result, relativePath) {
+    if (!cls.hasViewTree())
+        return;
+    const viewTree = cls.getViewTree();
+    if (!viewTree)
+        return;
+    const root = viewTree.getRoot();
+    if (!root)
+        return;
+    const classNodeId = ctx.resolveClassNodeId(cls);
+    if (!classNodeId)
+        return;
+    const buildMethod = cls.getMethods(true).find((m) => m.getName() === 'build');
+    if (!buildMethod)
+        return;
+    const buildId = ctx.ensureMethodNode(buildMethod, relativePath, result, classNodeId);
+    if (!buildId)
+        return;
+    const seen = new Set();
+    const link = (source, target, kind, via, line) => {
+        const key = `${source}>${target}>${kind}>${via}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        ctx.addEdge(result, source, target, kind, relativePath, via, line);
+    };
+    for (const [field] of viewTree.getStateValues()) {
+        const fieldId = ctx.fieldToId.get(field);
+        if (fieldId) {
+            ctx.markFieldStateDecorators?.(field, fieldId, result);
+            const line = field.getOriginFullPosition?.()?.getFirstLine?.() ??
+                buildMethod.getImplOriginFullPosition()?.getFirstLine() ??
+                1;
+            link(fieldId, buildId, 'references', 'state-binding', line);
+        }
+    }
+    walkViewTree(root, (node) => {
+        const sig = node.signature;
+        if (sig) {
+            if (isViewTreeClassSignature(sig)) {
+                const childCls = ctx.scene.getClass(sig);
+                if (childCls) {
+                    const childId = ctx.resolveClassNodeId(childCls);
+                    if (childId) {
+                        const firstAttr = node.attributes.values().next().value;
+                        const line = firstAttr
+                            ? viewTreeLineFromStmt(firstAttr[0])
+                            : buildMethod.getImplOriginFullPosition()?.getFirstLine() ?? 1;
+                        link(buildId, childId, 'references', 'child-component', line);
+                    }
+                }
+            }
+            else {
+                const builderMethod = ctx.scene.getMethod(sig);
+                if (builderMethod) {
+                    const builderId = ctx.ensureMethodNode(builderMethod, relativePath, result, classNodeId);
+                    if (builderId) {
+                        link(buildId, builderId, 'references', 'builder', builderMethod.getImplOriginFullPosition()?.getFirstLine() ?? 1);
+                    }
+                }
+            }
+        }
+        if (node.stateValuesTransfer) {
+            for (const [childField, parentValue] of node.stateValuesTransfer) {
+                const childFieldId = ctx.fieldToId.get(childField);
+                if (parentValue instanceof arkanalyzer_1.ArkField) {
+                    const via = stateTransferViaForField(childField);
+                    if (!via || !childFieldId)
+                        continue;
+                    ctx.markFieldStateDecorators?.(childField, childFieldId, result);
+                    const parentFieldId = ctx.fieldToId.get(parentValue);
+                    if (parentFieldId) {
+                        ctx.markFieldStateDecorators?.(parentValue, parentFieldId, result);
+                        link(parentFieldId, childFieldId, 'references', via, childField.getOriginFullPosition()?.getFirstLine() ?? 1);
+                    }
+                }
+                else if (parentValue instanceof arkanalyzer_1.ArkMethod) {
+                    const builderId = ctx.ensureMethodNode(parentValue, relativePath, result, classNodeId);
+                    if (childFieldId && builderId) {
+                        link(builderId, childFieldId, 'references', 'builder-param', childField.getOriginFullPosition()?.getFirstLine() ?? 1);
+                    }
+                }
+            }
+        }
+        for (const [attr, [stmt, values]] of node.attributes) {
+            if (!VIEWTREE_CALLBACK_ATTRS.has(attr))
+                continue;
+            const line = viewTreeLineFromStmt(stmt);
+            for (const v of values) {
+                if (!(v instanceof arkanalyzer_1.MethodSignature))
+                    continue;
+                const handler = ctx.scene.getMethod(v);
+                if (!handler)
+                    continue;
+                const handlerId = ctx.ensureMethodNode(handler, relativePath, result, classNodeId);
+                if (handlerId)
+                    link(buildId, handlerId, 'references', attr, line);
+            }
+        }
+    });
+}
 class ArkTSAdapter {
     rootDir;
     scanned;
@@ -580,7 +1180,7 @@ class ArkTSAdapter {
             const relativePath = normalizeRelPath(this.rootDir, arkFile.getFilePath());
             if (!this.scanned.has(relativePath))
                 continue;
-            if (!relativePath.endsWith('.ets'))
+            if (!isArkAnalyzerSourcePath(relativePath))
                 continue;
             this.indexFile(arkFile);
         }
@@ -589,12 +1189,22 @@ class ArkTSAdapter {
                 continue;
             const arkFile = cls.getDeclaringArkFile();
             const relativePath = normalizeRelPath(this.rootDir, arkFile.getFilePath());
-            if (!this.scanned.has(relativePath) || !relativePath.endsWith('.ets'))
+            if (!this.scanned.has(relativePath) || !isArkAnalyzerSourcePath(relativePath))
                 continue;
             const result = this.fileResults.get(relativePath);
             if (!result)
                 continue;
-            (0, arkts_viewtree_1.indexViewTreeForClass)(this.viewTreeContext(), cls, result, relativePath);
+            try {
+                indexViewTreeForClass(this.viewTreeContext(), cls, result, relativePath);
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                result.errors.push({
+                    message: `ViewTree indexing skipped for ${cls.getName()}: ${message}`,
+                    filePath: relativePath,
+                    severity: 'warning',
+                });
+            }
         }
         if (dummyMain) {
             this.indexArkanalyzerDummyMain(dummyMain);
@@ -614,12 +1224,13 @@ class ArkTSAdapter {
                 if (!caller || !callee)
                     continue;
                 if (shouldSkipArkMethod(caller) &&
+                    !isAnonymousArkMethod(caller) &&
                     !caller.getDeclaringArkClass().isDefaultArkClass() &&
                     !caller.isGenerated()) {
                     continue;
                 }
-                const callerId = this.methodToId.get(caller);
-                const calleeId = this.methodToId.get(callee);
+                const callerId = this.resolveMethodNodeId(caller);
+                const calleeId = this.resolveMethodNodeId(callee);
                 if (!callerId || !calleeId)
                     continue;
                 const callerFile = relPathForArkFile(this.rootDir, caller.getDeclaringArkFile());
@@ -899,8 +1510,10 @@ class ArkTSAdapter {
             return;
         const { line, endLine, col } = linesFromPosition(field.getOriginFullPosition());
         const qn = buildFieldQualifiedName(field);
+        const stateDecs = stateDecoratorKinds(field);
         const fieldNode = makeNode(relativePath, language, kind, name, qn, line, endLine, col, {
             signature: field.getType()?.toString(),
+            ...(stateDecs.length > 0 ? { decorators: stateDecs } : {}),
             ...modelModifiersToNodeExtras(field),
         });
         this.addNode(result, fieldNode);
@@ -923,11 +1536,63 @@ class ArkTSAdapter {
             addEdge: (result, source, target, kind, callerFile, via, line) => this.addViewTreeEdge(result, source, target, kind, callerFile, via, line),
             ensureMethodNode: (method, relativePath, result, parentId) => this.ensureMethodNode(method, relativePath, result, parentId),
             resolveClassNodeId: (cls) => this.resolveClassNodeId(cls),
+            markFieldStateDecorators: (field, fieldNodeId, result) => {
+                const kinds = stateDecoratorKinds(field);
+                if (kinds.length === 0)
+                    return;
+                const node = result.nodes.find((n) => n.id === fieldNodeId);
+                if (node)
+                    node.decorators = kinds;
+            },
         };
     }
     resolveClassNodeId(cls) {
         return this.componentToId.get(cls) ?? this.classToId.get(cls) ?? null;
     }
+    /** Parent node id for a method: owning class/component, or file for default-class methods. */
+    resolveMethodParentId(method, relativePath, result) {
+        const cls = method.getDeclaringArkClass();
+        if (cls.isDefaultArkClass()) {
+            return `file:${relativePath}`;
+        }
+        const classId = this.resolveClassNodeId(cls);
+        if (classId)
+            return classId;
+        const fileId = `file:${relativePath}`;
+        this.indexClass(relativePath, 'arkts', result, cls, fileId);
+        return this.resolveClassNodeId(cls) ?? fileId;
+    }
+    /**
+     * Resolve a method to a graph node id, lazily indexing anonymous ArkMethods
+     * that RTA / ViewTree reference but the main file walk skipped.
+     */
+    resolveMethodNodeId(method) {
+        const existing = this.methodToId.get(method);
+        if (existing)
+            return existing;
+        if (shouldSkipArkMethod(method) && !isAnonymousArkMethod(method))
+            return null;
+        const displayName = arkMethodDisplayName(method);
+        if (!displayName)
+            return null;
+        const arkFile = method.getDeclaringArkFile();
+        const relativePath = normalizeRelPath(this.rootDir, arkFile.getFilePath());
+        if (!this.scanned.has(relativePath) || !isArkAnalyzerSourcePath(relativePath))
+            return null;
+        let lineCount = 1;
+        try {
+            lineCount = arkFile.getCode()?.split('\n').length ?? 1;
+        }
+        catch {
+            // use default
+        }
+        const result = this.fileResults.get(relativePath) ?? this.ensureFileResult(relativePath, lineCount);
+        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);
+        return this.methodToId.get(method) ?? null;
+    }
     addViewTreeEdge(result, source, target, kind, callerFile, via, line) {
         const edge = arkEdge(source, target, kind, {
             metadata: {
@@ -947,14 +1612,14 @@ class ArkTSAdapter {
         const existing = this.methodToId.get(method);
         if (existing)
             return existing;
-        if (method.isAnonymousMethod?.() || method.getName().startsWith(arkanalyzer_1.ANONYMOUS_METHOD_PREFIX)) {
-            const line = method.getImplOriginFullPosition()?.getFirstLine() ?? 1;
-            this.indexMethod(relativePath, 'arkts', result, method, parentId, 'method', `@callback:${line}`);
-            return this.methodToId.get(method) ?? null;
-        }
-        if (shouldSkipArkMethod(method))
+        if (shouldSkipArkMethod(method) && !isAnonymousArkMethod(method))
+            return null;
+        const displayName = arkMethodDisplayName(method);
+        if (!displayName)
             return null;
-        this.indexMethod(relativePath, 'arkts', result, method, parentId);
+        const cls = method.getDeclaringArkClass();
+        const kind = cls.isDefaultArkClass() ? 'function' : 'method';
+        this.indexMethod(relativePath, 'arkts', result, method, parentId, kind, displayName);
         return this.methodToId.get(method) ?? null;
     }
     indexMethod(relativePath, language, result, method, parentId, forcedKind, forcedDisplayName) {
@@ -965,9 +1630,10 @@ class ArkTSAdapter {
         const kind = forcedKind ?? (cls.isDefaultArkClass() ? 'function' : 'method');
         const qn = buildMethodQualifiedName(method, displayName);
         const { line, endLine, col } = linesFromPosition(method.getImplOriginFullPosition());
-        const sig = method.getSignature()?.toString();
+        const { signature, returnType } = buildArkMethodSignatureFields(method);
         const methodNode = makeNode(relativePath, language, kind, displayName, qn, line, endLine, col, {
-            signature: sig,
+            ...(signature ? { signature } : {}),
+            ...(returnType ? { returnType } : {}),
             ...modelModifiersToNodeExtras(method),
         });
         this.addNode(result, methodNode);
@@ -1040,30 +1706,593 @@ class ArkTSAdapter {
         }
     }
 }
-function buildArkTSIndex(rootDir, scannedFiles) {
-    const errors = [];
-    const config = (0, arkanalyzer_1.buildSceneConfigFromProject)(rootDir, process.env.OHOS_SDK_HOME, {
-        supportFileExts: ['.ets'],
+/** User-visible notices from the most recent ArkTS batch (surfaced in CLI / IndexResult). */
+let arktsIndexNotices = [];
+/** Drain notices for merging into IndexResult.errors (clears the buffer). */
+function drainArkTSIndexNotices() {
+    const out = arktsIndexNotices;
+    arktsIndexNotices = [];
+    return out;
+}
+function buildSceneConfig(rootDir) {
+    return (0, arkanalyzer_1.buildSceneConfigFromProject)(rootDir, process.env.OHOS_SDK_HOME, {
+        supportFileExts: ['.ets', '.ts', '.d.ts'],
         enableMethodBodyBuild: true,
     });
+}
+function tryBuildArkScene(rootDir) {
+    const errors = [];
     const scene = new arkanalyzer_1.Scene();
     try {
-        scene.buildSceneFromProjectDir(config);
+        scene.buildSceneFromProjectDir(buildSceneConfig(rootDir));
         scene.inferTypes();
+        return { scene, errors };
     }
     catch (e) {
         const message = e instanceof Error ? e.message : String(e);
         errors.push({ message: `ArkTS Scene build failed: ${message}`, severity: 'error' });
+        return { scene: null, errors };
+    }
+}
+function emptyArkTSBatchIndex(errors) {
+    return {
+        fileResults: new Map(),
+        crossFileEdges: [],
+        nodeIds: new Set(),
+        errors,
+    };
+}
+function buildArkTSIndex(rootDir, scannedFiles) {
+    const { scene, errors } = tryBuildArkScene(rootDir);
+    if (!scene) {
+        return emptyArkTSBatchIndex(errors);
+    }
+    try {
+        const adapter = new ArkTSAdapter(rootDir, scannedFiles);
+        const index = adapter.build(scene);
+        index.errors.push(...errors);
+        return index;
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        errors.push({ message: `ArkTS adapter failed: ${message}`, severity: 'error' });
+        return emptyArkTSBatchIndex(errors);
+    }
+}
+// =============================================================================
+// OHOS SDK input resolution + prebuilt API database indexing
+// =============================================================================
+const OHOS_ARCHIVE_EXTENSIONS = ['.tar.gz', '.tgz', '.zip', '.tar'];
+class OhosSdkInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'OhosSdkInputError';
+    }
+}
+exports.OhosSdkInputError = OhosSdkInputError;
+/** Parse `6.1.1.290` or `commandline-tools-linux-x64-6.1.1.290.zip` → `6.1.1`. */
+function parseOhosToolsVersionFromName(name) {
+    const base = path.basename(name);
+    const withoutExt = stripOhosArchiveExtension(base);
+    const match = withoutExt.match(/(\d+\.\d+\.\d+)(?:\.\d+)?$/);
+    return match?.[1] ?? null;
+}
+function stripOhosArchiveExtension(filename) {
+    for (const ext of OHOS_ARCHIVE_EXTENSIONS) {
+        if (filename.toLowerCase().endsWith(ext)) {
+            return filename.slice(0, -ext.length);
+        }
+    }
+    return filename;
+}
+function isArchivePath(inputPath) {
+    const lower = inputPath.toLowerCase();
+    return OHOS_ARCHIVE_EXTENSIONS.some((ext) => lower.endsWith(ext));
+}
+/** Locate `sdk/default` that contains `openharmony/ets` under an extracted tree. */
+function findOhosSdkHome(searchRoot) {
+    const resolved = path.resolve(searchRoot);
+    const direct = [
+        path.join(resolved, 'sdk', 'default'),
+        path.join(resolved, 'command-line-tools', 'sdk', 'default'),
+    ];
+    for (const candidate of direct) {
+        if (hasOpenHarmonyEts(candidate)) {
+            return candidate;
+        }
+    }
+    const queue = [{ dir: resolved, depth: 0 }];
+    const seen = new Set();
+    while (queue.length > 0) {
+        const { dir, depth } = queue.shift();
+        if (seen.has(dir) || depth > 5)
+            continue;
+        seen.add(dir);
+        const sdkDefault = path.join(dir, 'sdk', 'default');
+        if (hasOpenHarmonyEts(sdkDefault)) {
+            return sdkDefault;
+        }
+        if (depth >= 5)
+            continue;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (entry.name === 'node_modules' || entry.name === '.git')
+                continue;
+            queue.push({ dir: path.join(dir, entry.name), depth: depth + 1 });
+        }
+    }
+    return null;
+}
+function hasOpenHarmonyEts(sdkHome) {
+    return fs.existsSync(path.join(sdkHome, 'openharmony', 'ets'));
+}
+function listOhosApiEtsRoots(sdkHome) {
+    const roots = [];
+    const openharmony = path.join(sdkHome, 'openharmony', 'ets');
+    if (fs.existsSync(openharmony)) {
+        roots.push(openharmony);
+    }
+    const hms = path.join(sdkHome, 'hms', 'ets');
+    if (fs.existsSync(hms)) {
+        roots.push(hms);
+    }
+    return roots;
+}
+/** Resolve a command-line-tools archive or directory to an SDK home + API db version. */
+function resolveOhosSdkInput(options) {
+    const inputPath = path.resolve(options.inputPath);
+    if (!fs.existsSync(inputPath)) {
+        throw new OhosSdkInputError(`Path does not exist: ${inputPath}`);
+    }
+    let searchRoot = inputPath;
+    let cleanup;
+    if (fs.statSync(inputPath).isFile()) {
+        if (!isArchivePath(inputPath)) {
+            throw new OhosSdkInputError(`Unsupported file type: ${path.basename(inputPath)} (expected .zip, .tar.gz, .tgz, or .tar)`);
+        }
+        const extracted = extractOhosSdkArchive(inputPath);
+        searchRoot = extracted.dir;
+        cleanup = extracted.cleanup;
+    }
+    const sdkHome = findOhosSdkHome(searchRoot);
+    if (!sdkHome) {
+        cleanup?.();
+        throw new OhosSdkInputError(`Could not find sdk/default/openharmony/ets under ${inputPath}. ` +
+            'Expected HarmonyOS command-line-tools layout.');
+    }
+    const version = options.versionOverride?.trim() ||
+        parseOhosToolsVersionFromName(inputPath) ||
+        parseOhosToolsVersionFromName(searchRoot);
+    if (!version) {
+        cleanup?.();
+        throw new OhosSdkInputError('Could not determine API db version. Use a path like commandline-tools-linux-x64-6.1.1.290.zip ' +
+            'or pass the version as the second argument.');
+    }
+    return {
+        sdkHome,
+        version,
+        sourcePath: inputPath,
+        cleanup,
+    };
+}
+function extractOhosSdkArchive(archivePath) {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'homegraph-ohos-sdk-'));
+    const lower = archivePath.toLowerCase();
+    try {
+        if (lower.endsWith('.zip')) {
+            (0, child_process_1.execFileSync)('unzip', ['-q', archivePath, '-d', tempDir], { stdio: 'pipe' });
+        }
+        else if (lower.endsWith('.tar.gz') || lower.endsWith('.tgz')) {
+            (0, child_process_1.execFileSync)('tar', ['-xzf', archivePath, '-C', tempDir], { stdio: 'pipe' });
+        }
+        else if (lower.endsWith('.tar')) {
+            (0, child_process_1.execFileSync)('tar', ['-xf', archivePath, '-C', tempDir], { stdio: 'pipe' });
+        }
+        else {
+            throw new OhosSdkInputError(`Unsupported archive: ${path.basename(archivePath)}`);
+        }
+    }
+    catch (err) {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new OhosSdkInputError(`Failed to extract ${archivePath}: ${msg}`);
+    }
+    return {
+        dir: tempDir,
+        cleanup: () => {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        },
+    };
+}
+/** Default filename for a versioned OHOS API db. */
+function ohosApiDbFilename(version) {
+    return `ohos-api-${version}.db`;
+}
+/** npm package name — one package per API version (e.g. homegraph-ohos-api-db-6.0.1). */
+function ohosApiDbPackageName(version) {
+    return `homegraph-ohos-api-db-${version}`;
+}
+/** Target path under ~/.homegraph/api/ for a versioned db. */
+function ohosApiDbInstallPath(version) {
+    return path.join(os.homedir(), '.homegraph', 'api', ohosApiDbFilename(version));
+}
+function scanFirstOhosApiTriggerFile(etsRoot) {
+    let found = null;
+    function walk(dir) {
+        if (found)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === 'node_modules' || entry.name === '.git')
+                    continue;
+                walk(full);
+            }
+            else if (entry.isFile()) {
+                const lower = entry.name.toLowerCase();
+                if (lower.endsWith('.ets') ||
+                    lower.endsWith('.d.ts') ||
+                    lower.endsWith('.d.ets') ||
+                    (lower.endsWith('.ts') && !lower.endsWith('.d.ts'))) {
+                    found = path.relative(etsRoot, full).replace(/\\/g, '/');
+                    return;
+                }
+            }
+        }
+    }
+    walk(etsRoot);
+    return found;
+}
+function countOhosApiSources(etsRoot) {
+    let count = 0;
+    function walk(dir) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === 'node_modules' || entry.name === '.git')
+                    continue;
+                walk(full);
+            }
+            else if (entry.isFile()) {
+                const lower = entry.name.toLowerCase();
+                if (lower.endsWith('.ets') ||
+                    lower.endsWith('.d.ts') ||
+                    lower.endsWith('.d.ets') ||
+                    (lower.endsWith('.ts') && !lower.endsWith('.d.ts'))) {
+                    count++;
+                }
+            }
+        }
+    }
+    walk(etsRoot);
+    return count;
+}
+/** Index OpenHarmony (and optional HMS) SDK API declarations into a SQLite db. */
+async function indexOhosApiDb(options) {
+    const sdkHome = path.resolve(options.sdkHome);
+    if (!hasOpenHarmonyEts(sdkHome)) {
+        throw new Error(`SDK home is missing openharmony/ets: ${sdkHome}`);
+    }
+    const etsRoots = listOhosApiEtsRoots(sdkHome);
+    if (etsRoots.length === 0) {
+        throw new Error(`No API ets roots found under ${sdkHome}`);
+    }
+    const outputPath = path.resolve(options.outputPath ?? path.join(process.cwd(), ohosApiDbFilename(options.version)));
+    if (fs.existsSync(outputPath)) {
+        fs.unlinkSync(outputPath);
+    }
+    const startTime = Date.now();
+    const errors = [];
+    let filesIndexed = 0;
+    const db = db_1.DatabaseConnection.initialize(outputPath);
+    const queries = new queries_1.QueryBuilder(db.getDb());
+    try {
+        for (const etsRoot of etsRoots) {
+            const trigger = scanFirstOhosApiTriggerFile(etsRoot);
+            if (!trigger) {
+                errors.push({
+                    message: `No ArkTS sources under ${etsRoot}`,
+                    severity: 'warning',
+                });
+                continue;
+            }
+            const total = countOhosApiSources(etsRoot);
+            options.onProgress?.({
+                phase: 'arkts-batch',
+                current: 0,
+                total,
+                currentFile: etsRoot,
+                subphase: 'scene',
+            });
+            resetArkTSBatch();
+            (0, context_1.resetExtractionContext)();
+            (0, context_1.bindExtractionContext)(etsRoot, queries);
+            await primeArkTSBatch(etsRoot, queries, trigger);
+            filesIndexed += total;
+            options.onProgress?.({
+                phase: 'arkts-batch',
+                current: total,
+                total,
+                currentFile: etsRoot,
+                subphase: 'persist',
+            });
+        }
+        const counts = queries.getNodeAndEdgeCount();
+        queries.setMetadata('ohos_api_version', options.version);
+        queries.setMetadata('ohos_api_sdk_home', sdkHome);
+        queries.setMetadata('ohos_api_db_kind', ohosApiDbPackageName(options.version));
+        queries.setMetadata('indexed_with_version', version_1.HomeGraphPackageVersion);
+        queries.setMetadata('indexed_with_extraction_version', String(extraction_version_1.EXTRACTION_VERSION));
+        db.runMaintenance();
         return {
-            fileResults: new Map(),
-            crossFileEdges: [],
-            nodeIds: new Set(),
+            success: errors.every((e) => e.severity !== 'error'),
+            filesIndexed,
+            filesSkipped: 0,
+            filesErrored: errors.filter((e) => e.severity === 'error').length,
+            nodesCreated: counts.nodes,
+            edgesCreated: counts.edges,
             errors,
+            durationMs: Date.now() - startTime,
+        };
+    }
+    finally {
+        resetArkTSBatch();
+        (0, context_1.resetExtractionContext)();
+        db.close();
+    }
+}
+// =============================================================================
+// OHOS API db consumer: compileSdkVersion detect, npm fetch, ATTACH for queries
+// =============================================================================
+exports.OHOS_API_FILE_PREFIX = 'ohos-sdk:';
+exports.OHOS_API_VERSION_META = 'ohos_api_version';
+exports.OHOS_API_DB_PATH_META = 'ohos_api_db_path';
+/** Prefix applied to API db node file paths so explore can render without disk reads. */
+function markOhosApiFilePath(relativePath) {
+    return `${exports.OHOS_API_FILE_PREFIX}${relativePath.replace(/\\/g, '/')}`;
+}
+function isOhosApiFilePath(filePath) {
+    return filePath.startsWith(exports.OHOS_API_FILE_PREFIX);
+}
+/** Strip json5 comments/trailing commas enough for compileSdkVersion extraction. */
+function parseJson5Minimal(text) {
+    const stripped = text
+        .replace(/\/\/.*$/gm, '')
+        .replace(/\/\*[\s\S]*?\*\//g, '')
+        .replace(/,(\s*[}\]])/g, '$1');
+    return JSON.parse(stripped);
+}
+/** Normalize compileSdkVersion values like "6.0.1(21)" → "6.0.1". */
+function normalizeOhosApiVersion(raw) {
+    if (raw == null)
+        return null;
+    if (typeof raw === 'number') {
+        const s = String(raw);
+        if (/^\d+$/.test(s) && s.length >= 8) {
+            const major = Math.floor(Number(s) / 1_000_000);
+            const minor = Math.floor((Number(s) % 1_000_000) / 1000);
+            const patch = Number(s) % 1000;
+            return `${major}.${minor}.${patch}`;
+        }
+        return null;
+    }
+    const match = String(raw).match(/(\d+\.\d+\.\d+)/);
+    return match?.[1] ?? null;
+}
+function findBuildProfileFiles(projectRoot) {
+    const found = [];
+    const rootProfile = path.join(projectRoot, 'build-profile.json5');
+    if (fs.existsSync(rootProfile))
+        found.push(rootProfile);
+    let entries;
+    try {
+        entries = fs.readdirSync(projectRoot, { withFileTypes: true });
+    }
+    catch {
+        return found;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === '.homegraph')
+            continue;
+        const nested = path.join(projectRoot, entry.name, 'build-profile.json5');
+        if (fs.existsSync(nested))
+            found.push(nested);
+    }
+    return found;
+}
+function extractCompileSdkFromObject(obj) {
+    if (!obj || typeof obj !== 'object')
+        return null;
+    const record = obj;
+    for (const key of ['compileSdkVersion', 'compileSdk', 'targetSdkVersion']) {
+        const v = normalizeOhosApiVersion(record[key]);
+        if (v)
+            return v;
+    }
+    const app = record.app;
+    if (app && typeof app === 'object') {
+        const products = app.products;
+        if (Array.isArray(products)) {
+            for (const product of products) {
+                const v = extractCompileSdkFromObject(product);
+                if (v)
+                    return v;
+            }
+        }
+    }
+    for (const value of Object.values(record)) {
+        if (value && typeof value === 'object') {
+            const v = extractCompileSdkFromObject(value);
+            if (v)
+                return v;
+        }
+    }
+    return null;
+}
+/** Read compileSdkVersion from build-profile.json5 (root or module). */
+function detectOhosCompileSdkVersion(projectRoot) {
+    const envOverride = process.env.HOMEGRAPH_OHOS_API_VERSION?.trim();
+    if (envOverride) {
+        return normalizeOhosApiVersion(envOverride) ?? envOverride;
+    }
+    for (const profilePath of findBuildProfileFiles(projectRoot)) {
+        try {
+            const text = fs.readFileSync(profilePath, 'utf-8');
+            const parsed = parseJson5Minimal(text);
+            const version = extractCompileSdkFromObject(parsed);
+            if (version)
+                return version;
+        }
+        catch {
+            const match = fs.readFileSync(profilePath, 'utf-8').match(/compileSdkVersion\s*:\s*['"]?([^'"\s,)]+)/);
+            const v = normalizeOhosApiVersion(match?.[1]);
+            if (v)
+                return v;
+        }
+    }
+    return null;
+}
+function isOhosArktsProject(projectRoot, languages) {
+    if (languages?.includes('arkts'))
+        return true;
+    if (findBuildProfileFiles(projectRoot).length > 0)
+        return true;
+    return hasEtsUnder(projectRoot, 0);
+}
+function hasEtsUnder(dir, depth) {
+    if (depth > 4)
+        return false;
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isFile() && entry.name.endsWith('.ets'))
+            return true;
+        if (entry.isDirectory()) {
+            if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === '.homegraph')
+                continue;
+            if (hasEtsUnder(full, depth + 1))
+                return true;
+        }
+    }
+    return false;
+}
+/** Install npm package if local db is missing; non-throwing on failure. */
+function ensureOhosApiDb(version) {
+    const dbPath = ohosApiDbInstallPath(version);
+    if (fs.existsSync(dbPath)) {
+        return {
+            version,
+            dbPath,
+            packageName: ohosApiDbPackageName(version),
+            installed: false,
         };
     }
-    const adapter = new ArkTSAdapter(rootDir, scannedFiles);
-    const index = adapter.build(scene);
-    index.errors.push(...errors);
-    return index;
+    const packageName = ohosApiDbPackageName(version);
+    const installDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hg-ohos-npm-'));
+    try {
+        (0, child_process_1.execFileSync)('npm', ['install', '--no-save', packageName], {
+            cwd: installDir,
+            stdio: 'pipe',
+            timeout: 180_000,
+            env: { ...process.env, npm_config_loglevel: 'error' },
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            code: 'ohos_api_install_failed',
+            message: `Could not fetch ${packageName} (${msg}). ` +
+                'Explore will use project code only until the matching API db is available.',
+        };
+    }
+    finally {
+        fs.rmSync(installDir, { recursive: true, force: true });
+    }
+    if (!fs.existsSync(dbPath)) {
+        return {
+            code: 'ohos_api_db_missing',
+            message: `${packageName} was fetched but ${ohosApiDbFilename(version)} is missing under ~/.homegraph/api/. ` +
+                'Explore will use project code only.',
+        };
+    }
+    return { version, dbPath, packageName, installed: true };
+}
+/** Detect version, ensure db, persist metadata, ATTACH — never throws. */
+function bindOhosApiDbForProject(projectRoot, queries, languages) {
+    if (!isOhosArktsProject(projectRoot, languages))
+        return null;
+    const version = detectOhosCompileSdkVersion(projectRoot);
+    if (!version) {
+        return {
+            code: 'ohos_api_version_unknown',
+            message: 'HarmonyOS project detected but compileSdkVersion not found in build-profile.json5. ' +
+                'SDK API lookup disabled; project indexing continues normally.',
+        };
+    }
+    const ensured = ensureOhosApiDb(version);
+    if ('code' in ensured)
+        return ensured;
+    try {
+        queries.attachOhosApiDb(ensured.dbPath);
+        queries.setMetadata(exports.OHOS_API_VERSION_META, ensured.version);
+        queries.setMetadata(exports.OHOS_API_DB_PATH_META, ensured.dbPath);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            code: 'ohos_api_db_missing',
+            message: `Failed to attach OHOS API db at ${ensured.dbPath}: ${msg}`,
+        };
+    }
+    return ensured;
+}
+/** Re-ATTACH from project metadata after reopen / new QueryBuilder. */
+function restoreOhosApiDbAttach(queries) {
+    const dbPath = queries.getMetadata(exports.OHOS_API_DB_PATH_META);
+    const version = queries.getMetadata(exports.OHOS_API_VERSION_META);
+    if (!dbPath || !version || !fs.existsSync(dbPath))
+        return null;
+    try {
+        queries.attachOhosApiDb(dbPath);
+        return {
+            version,
+            dbPath,
+            packageName: ohosApiDbPackageName(version),
+            installed: false,
+        };
+    }
+    catch {
+        return null;
+    }
 }
 //# sourceMappingURL=arkts.js.map