homegraph 1.5.2 → 1.5.4

package/dist/extraction/languages/arkts.js

@@ -78,8 +78,11 @@ exports.isArkTSBatchPersisted = isArkTSBatchPersisted;
 exports.isArkTSBatchCommitted = isArkTSBatchCommitted;
 exports.resetArkTSBatch = resetArkTSBatch;
 exports.shrinkArkTSBatchPostParse = shrinkArkTSBatchPostParse;
+exports.createArkRelPathNormalizer = createArkRelPathNormalizer;
 exports.collectExportedRtaEntryPointsFromFiles = collectExportedRtaEntryPointsFromFiles;
 exports.stateDecoratorKinds = stateDecoratorKinds;
+exports.fieldDecoratorEntries = fieldDecoratorEntries;
+exports.fieldDecoratorsEncoded = fieldDecoratorsEncoded;
 exports.stateTransferViaForField = stateTransferViaForField;
 exports.isUnclearArkClassSignature = isUnclearArkClassSignature;
 exports.isUnclearArkMethodSignature = isUnclearArkMethodSignature;
@@ -105,6 +108,7 @@ exports.readOhosSdkPlatformVersion = readOhosSdkPlatformVersion;
 exports.discoverLocalOhosSdkCandidates = discoverLocalOhosSdkCandidates;
 exports.findLocalOhosSdkForVersion = findLocalOhosSdkForVersion;
 exports.resolveOhosApiVersionForProject = resolveOhosApiVersionForProject;
+exports.tryDownloadOhosApiDbFromNpm = tryDownloadOhosApiDbFromNpm;
 exports.ensureOhosApiDb = ensureOhosApiDb;
 exports.attachExistingOhosApiDbForProject = attachExistingOhosApiDbForProject;
 exports.bindOhosApiDbForProject = bindOhosApiDbForProject;
@@ -122,9 +126,12 @@ const directory_1 = require("../../directory");
 const project_config_1 = require("../../project-config");
 const context_1 = require("../context");
 const default_ignore_1 = require("../default-ignore");
+const generated_detection_1 = require("../generated-detection");
 const extraction_version_1 = require("../extraction-version");
 const version_1 = require("../../mcp/version");
 const liveness_watchdog_1 = require("../../mcp/liveness-watchdog");
+const migrate_semantics_1 = require("../../arkui/migrate-semantics");
+const migrate_passage_1 = require("../../arkui/migrate-passage");
 const tree_sitter_helpers_1 = require("../tree-sitter-helpers");
 const wasm_runtime_flags_1 = require("../wasm-runtime-flags");
 const ignore_1 = __importDefault(require("ignore"));
@@ -480,11 +487,16 @@ function hasHarmonyProjectMarkers(rootDir) {
 function normIndexPath(filePath) {
     return filePath.replace(/\\/g, '/');
 }
-/** Member calls through a native `.so` binding: `sdk.Asset_setCropRect(`. */
+/** Photos-style member calls: `sdk.Asset_setCropRect(`. */
 const NAPI_MEMBER_CALL_RE = /\.\s*([A-Z][A-Za-z0-9_]*(?:_[A-Za-z0-9_]+)+)\s*\(/g;
+/** `libFoo.so` module path from ArkAnalyzer import infos. */
+const LIB_SO_MODULE_RE = /^lib[A-Za-z0-9_]+\.so$/;
 function isNapiSymbolName(name) {
     return /^[A-Z][A-Za-z0-9_]*_[A-Za-z0-9_]+$/.test(name);
 }
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
 let persistedBatch = null;
 /** File that triggered the most recent batch persist (for indexAll edge stats). */
 let batchTriggerFile = null;
@@ -635,6 +647,7 @@ function persistFileResult(queries, filePath, content, stats, result, options) {
         indexedAt: Date.now(),
         nodeCount: result.nodes.length,
         errors: result.errors.length > 0 ? result.errors : undefined,
+        generated: (0, generated_detection_1.detectGeneratedFile)(filePath, content),
     };
     queries.upsertFile(fileRecord);
 }
@@ -888,7 +901,9 @@ function runArkTSBatchFullCore(rootDir, queries, triggerFile, etsFiles, batchKey
         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');
+            const detail = index.errors.map((e) => `[${e.severity}] ${e.message}`).join(' | ');
+            throw new Error(fatal?.message ??
+                `ArkTS batch produced no indexed files${detail ? ` (${detail})` : ' (no Scene/adapter errors recorded)'}`);
         }
         queries.deleteArkTSCrossFileCallEdges();
         persistBatchResultsSync(rootDir, queries, index);
@@ -1025,7 +1040,9 @@ async function primeArkTSBatch(rootDir, queries, triggerFile, options) {
         const streamed = index.streamedPersistedPaths?.size ?? 0;
         if (index.fileResults.size === 0 && streamed === 0) {
             const fatal = index.errors.find((e) => e.severity === 'error');
-            throw new Error(fatal?.message ?? 'ArkTS batch produced no indexed files');
+            const detail = index.errors.map((e) => `[${e.severity}] ${e.message}`).join(' | ');
+            throw new Error(fatal?.message ??
+                `ArkTS batch produced no indexed files${detail ? ` (${detail})` : ' (no Scene/adapter errors recorded)'}`);
         }
         if (!streamModular) {
             queries.deleteArkTSCrossFileCallEdges();
@@ -1198,8 +1215,72 @@ const FIELD_CATEGORY = {
 };
 /** {@link ModifierType.CONST} — not re-exported from the arkanalyzer npm entry. */
 const MODIFIER_CONST = 128;
-function normalizeRelPath(rootDir, absolutePath) {
-    return path.relative(rootDir, absolutePath).replace(/\\/g, '/');
+/** `realpathSync` when the path (or its dirname) exists; otherwise `path.resolve`. */
+function realpathExisting(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        try {
+            return path.join(fs.realpathSync(path.dirname(p)), path.basename(p));
+        }
+        catch {
+            return path.resolve(p);
+        }
+    }
+}
+function toPosixPath(p) {
+    return p.replace(/\\/g, '/');
+}
+/**
+ * If `absolutePath` is under `canonicalRoot`, return the project-relative posix
+ * path; otherwise null. Windows compares case-insensitively.
+ */
+function tryStripRootPrefix(canonicalRoot, absolutePath) {
+    const root = toPosixPath(canonicalRoot);
+    const abs = toPosixPath(absolutePath);
+    const rootCmp = process.platform === 'win32' ? root.toLowerCase() : root;
+    const absCmp = process.platform === 'win32' ? abs.toLowerCase() : abs;
+    if (absCmp === rootCmp)
+        return '';
+    const prefix = rootCmp.endsWith('/') ? rootCmp : `${rootCmp}/`;
+    if (!absCmp.startsWith(prefix))
+        return null;
+    const sliceFrom = root.endsWith('/') ? root.length : root.length + 1;
+    return abs.slice(sliceFrom);
+}
+/**
+ * Project-relative paths for ArkAnalyzer absolutes.
+ *
+ * ArkAnalyzer often returns realpath'd absolutes (macOS: `/private/var/...`),
+ * while HomeGraph's `rootDir` from `mkdtemp` / callers may be unresolved
+ * (`/var/...`). We realpath the root **once**, then strip by prefix on the hot
+ * path; only prefix misses pay a per-path `realpath` (cached for the batch).
+ */
+function createArkRelPathNormalizer(rootDir) {
+    const canonicalRoot = realpathExisting(rootDir);
+    const cache = new Map();
+    const normalizeOnce = (absolutePath) => {
+        const fast = tryStripRootPrefix(canonicalRoot, absolutePath);
+        if (fast !== null)
+            return fast;
+        const abs = realpathExisting(absolutePath);
+        const after = tryStripRootPrefix(canonicalRoot, abs);
+        if (after !== null)
+            return after;
+        return toPosixPath(path.relative(canonicalRoot, abs));
+    };
+    return {
+        rootDir: canonicalRoot,
+        normalize(absolutePath) {
+            const hit = cache.get(absolutePath);
+            if (hit !== undefined)
+                return hit;
+            const rel = normalizeOnce(absolutePath);
+            cache.set(absolutePath, rel);
+            return rel;
+        },
+    };
 }
 /** Map ArkAnalyzer synthetic files (e.g. @dummyFile) to our virtual indexed path. */
 function resolveArkanalyzerVirtualPath(arkFile) {
@@ -1209,9 +1290,6 @@ function resolveArkanalyzerVirtualPath(arkFile) {
     }
     return null;
 }
-function relPathForArkFile(rootDir, arkFile) {
-    return resolveArkanalyzerVirtualPath(arkFile) ?? normalizeRelPath(rootDir, arkFile.getFilePath());
-}
 function buildQualifiedName(parts) {
     return parts.filter(Boolean).join('::');
 }
@@ -1655,6 +1733,52 @@ function stateDecoratorKinds(field) {
         return [];
     return [...decs].map((d) => d.getKind()).filter(Boolean);
 }
+/** All field decorators with optional string args (Provide('theme') → theme). */
+function fieldDecoratorEntries(field) {
+    const out = [];
+    const seen = new Set();
+    const push = (kind, arg) => {
+        if (!kind || seen.has(kind))
+            return;
+        seen.add(kind);
+        out.push(arg ? { kind, arg } : { kind });
+    };
+    try {
+        for (const d of field.getDecorators?.() ?? []) {
+            push(d.getKind(), (0, migrate_semantics_1.parseDecoratorArgFromContent)(d.getContent?.() ?? ''));
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    if (out.length === 0) {
+        for (const kind of stateDecoratorKinds(field))
+            push(kind);
+    }
+    return out;
+}
+/** Encoded decorators list for node.decorators (bare kinds + Kind@arg). */
+function fieldDecoratorsEncoded(field) {
+    return (0, migrate_semantics_1.encodeDecoratorEntries)(fieldDecoratorEntries(field));
+}
+function modelDecoratorEntries(model) {
+    const out = [];
+    const seen = new Set();
+    try {
+        for (const d of model.getDecorators?.() ?? []) {
+            const kind = d.getKind();
+            if (!kind || seen.has(kind))
+                continue;
+            seen.add(kind);
+            const arg = (0, migrate_semantics_1.parseDecoratorArgFromContent)(d.getContent?.() ?? '');
+            out.push(arg ? { kind, arg } : { kind });
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return out;
+}
 /** Child @Prop / @Link — edge `via` uses the decorator name as-is. */
 function stateTransferViaForField(field) {
     for (const kind of stateDecoratorKinds(field)) {
@@ -2001,12 +2125,12 @@ function indexViewTreeForClass(ctx, cls, result, relativePath) {
     if (!buildId)
         return;
     const seen = new Set();
-    const link = (source, target, kind, via, line) => {
+    const link = (source, target, kind, via, line, extraMeta) => {
         const key = `${source}>${target}>${kind}>${via}`;
         if (seen.has(key))
             return;
         seen.add(key);
-        ctx.addEdge(result, source, target, kind, relativePath, via, line);
+        ctx.addEdge(result, source, target, kind, relativePath, via, line, extraMeta);
     };
     for (const [field] of viewTree.getStateValues()) {
         const fieldId = ctx.resolveFieldNodeId(field);
@@ -2074,32 +2198,62 @@ function indexViewTreeForClass(ctx, cls, result, relativePath) {
                 // Skip this node's signature edge; keep walking siblings/children.
             }
         }
-        if (node.stateValuesTransfer) {
-            for (const [childField, parentValue] of node.stateValuesTransfer) {
-                const childFieldId = ctx.resolveFieldNodeId(childField);
-                if (parentValue instanceof arkanalyzer_1.ArkField) {
-                    const via = stateTransferViaForField(childField);
-                    if (!via || !childFieldId)
-                        continue;
-                    ctx.markFieldStateDecorators?.(childField, childFieldId, result);
-                    const parentFieldId = ctx.resolveFieldNodeId(parentValue);
-                    if (parentFieldId) {
-                        ctx.markFieldStateDecorators?.(parentValue, parentFieldId, result);
-                        link(parentFieldId, childFieldId, 'references', via, childField.getOriginFullPosition()?.getFirstLine() ?? 1);
-                    }
+        // Data passages for migrate snapshot (+ Prop/Link edges for explore).
+        try {
+            const passages = (0, migrate_passage_1.collectPassagesForViewTreeNode)(node, ctx.scene, cls);
+            for (const p of passages) {
+                const toId = ctx.resolveFieldNodeId(p.toField);
+                if (!toId)
+                    continue;
+                ctx.markFieldStateDecorators?.(p.toField, toId, result);
+                let fromId = null;
+                if (p.fromField) {
+                    fromId = ctx.resolveFieldNodeId(p.fromField);
+                    if (fromId)
+                        ctx.markFieldStateDecorators?.(p.fromField, fromId, result);
                 }
-                else if (parentValue instanceof arkanalyzer_1.ArkMethod) {
-                    let builderId = ctx.ensureMethodNode(parentValue, relativePath, result, classNodeId);
-                    if (!builderId) {
-                        try {
-                            builderId = ctx.resolveMethodIdBySig(parentValue.getSignature());
-                        }
-                        catch {
-                            builderId = null;
+                if (!fromId && p.fromIsParentComponent)
+                    fromId = classNodeId;
+                if (!fromId)
+                    continue;
+                const line = p.toField.getOriginFullPosition()?.getFirstLine() ?? 1;
+                link(fromId, toId, 'references', p.via || 'data-passage', line, {
+                    passageType: p.passageType,
+                    valueType: p.valueType,
+                    forcesMigration: p.forcesMigration,
+                    parentExpression: p.parentExpression,
+                });
+            }
+        }
+        catch {
+            // Fall back to legacy Prop/Link-only transfer below.
+            if (node.stateValuesTransfer) {
+                for (const [childField, parentValue] of node.stateValuesTransfer) {
+                    const childFieldId = ctx.resolveFieldNodeId(childField);
+                    if (parentValue instanceof arkanalyzer_1.ArkField) {
+                        const via = stateTransferViaForField(childField);
+                        if (!via || !childFieldId)
+                            continue;
+                        ctx.markFieldStateDecorators?.(childField, childFieldId, result);
+                        const parentFieldId = ctx.resolveFieldNodeId(parentValue);
+                        if (parentFieldId) {
+                            ctx.markFieldStateDecorators?.(parentValue, parentFieldId, result);
+                            link(parentFieldId, childFieldId, 'references', via, childField.getOriginFullPosition()?.getFirstLine() ?? 1);
                         }
                     }
-                    if (childFieldId && builderId) {
-                        link(builderId, childFieldId, 'references', 'builder-param', childField.getOriginFullPosition()?.getFirstLine() ?? 1);
+                    else if (parentValue instanceof arkanalyzer_1.ArkMethod) {
+                        let builderId = ctx.ensureMethodNode(parentValue, relativePath, result, classNodeId);
+                        if (!builderId) {
+                            try {
+                                builderId = ctx.resolveMethodIdBySig(parentValue.getSignature());
+                            }
+                            catch {
+                                builderId = null;
+                            }
+                        }
+                        if (childFieldId && builderId) {
+                            link(builderId, childFieldId, 'references', 'builder-param', childField.getOriginFullPosition()?.getFirstLine() ?? 1);
+                        }
                     }
                 }
             }
@@ -2126,6 +2280,7 @@ function indexViewTreeForClass(ctx, cls, result, relativePath) {
 }
 class ArkTSAdapter {
     rootDir;
+    pathNorm;
     scanned;
     scene = null;
     methodToId = new Map();
@@ -2155,10 +2310,24 @@ class ArkTSAdapter {
     crossFileEdges = [];
     /** Per-module `@dummyMain@…` created during analyseByModule (for scene aggregator). */
     moduleDummyMains = [];
+    /**
+     * Local import binding names from `lib*.so` per relative file path.
+     * Filled before method bodies are scanned so `multimodalinput.getTidByName(`
+     * can emit NAPI call refs (not only photos-style `Class_method` names).
+     */
+    soImportBindingsByFile = new Map();
     constructor(rootDir, scannedFiles) {
-        this.rootDir = rootDir;
+        this.pathNorm = createArkRelPathNormalizer(rootDir);
+        this.rootDir = this.pathNorm.rootDir;
         this.scanned = new Set(scannedFiles);
     }
+    /** ArkAnalyzer absolute → project-relative (shared batch cache). */
+    normalizeRelPath(absolutePath) {
+        return this.pathNorm.normalize(absolutePath);
+    }
+    relPathForArkFile(arkFile) {
+        return resolveArkanalyzerVirtualPath(arkFile) ?? this.normalizeRelPath(arkFile.getFilePath());
+    }
     build(scene) {
         this.scene = scene;
         for (const arkFile of scene.getFiles()) {
@@ -2176,7 +2345,7 @@ class ArkTSAdapter {
     indexModule(module, scene) {
         this.scene = scene;
         const files = [...module.getFilesMap().values()];
-        const moduleFiles = new Set(files.map((f) => normalizeRelPath(this.rootDir, f.getFilePath())).filter(Boolean));
+        const moduleFiles = new Set(files.map((f) => this.normalizeRelPath(f.getFilePath())).filter(Boolean));
         for (const arkFile of files) {
             this.indexScannedFile(arkFile);
         }
@@ -2211,7 +2380,7 @@ class ArkTSAdapter {
                 continue;
             }
             for (const arkFile of filesMap.values()) {
-                const rel = normalizeRelPath(this.rootDir, arkFile.getFilePath());
+                const rel = this.normalizeRelPath(arkFile.getFilePath());
                 if (!rel || excludeFiles.has(rel) || this.fileResults.has(rel))
                     continue;
                 if (!this.scanned.has(rel) || !isArkAnalyzerSourcePath(rel))
@@ -2244,7 +2413,7 @@ class ArkTSAdapter {
     /** Re-attach live Ark* objects to already-indexed HomeGraph node ids (sig maps). */
     bindLiveMapsFromFiles(files) {
         for (const arkFile of files) {
-            const relativePath = normalizeRelPath(this.rootDir, arkFile.getFilePath());
+            const relativePath = this.normalizeRelPath(arkFile.getFilePath());
             if (!this.scanned.has(relativePath) || !isArkAnalyzerSourcePath(relativePath))
                 continue;
             this.bindLiveClass(arkFile.getDefaultClass());
@@ -2396,13 +2565,13 @@ class ArkTSAdapter {
                 !callerArk.isGenerated()) {
                 continue;
             }
-            const callerFile = (callerArk ? relPathForArkFile(this.rootDir, callerArk.getDeclaringArkFile()) : null) ??
+            const callerFile = (callerArk ? this.relPathForArkFile(callerArk.getDeclaringArkFile()) : null) ??
                 (callerSig ? this.relPathFromMethodSignature(callerSig) : null) ??
                 '';
             if (moduleFiles && callerFile && !moduleFiles.has(callerFile)) {
                 continue;
             }
-            const calleeFile = (calleeArk ? relPathForArkFile(this.rootDir, calleeArk.getDeclaringArkFile()) : null) ??
+            const calleeFile = (calleeArk ? this.relPathForArkFile(calleeArk.getDeclaringArkFile()) : null) ??
                 (calleeSig ? this.relPathFromMethodSignature(calleeSig) : null);
             const callerId = (callerArk ? this.resolveMethodNodeId(callerArk) : null) ??
                 (callerSig ? this.resolveMethodIdBySigExact(callerSig) : null);
@@ -2441,7 +2610,7 @@ class ArkTSAdapter {
      */
     stitchModuleCfgCallsAndRefs(files, _moduleFiles) {
         for (const arkFile of files) {
-            const callerFile = normalizeRelPath(this.rootDir, arkFile.getFilePath());
+            const callerFile = this.normalizeRelPath(arkFile.getFilePath());
             const visitClass = (cls) => {
                 for (const method of cls.getMethods(true)) {
                     if (shouldSkipArkMethod(method) &&
@@ -2612,7 +2781,7 @@ class ArkTSAdapter {
             const fileName = sig.getDeclaringClassSignature().getDeclaringFileSignature().getFileName();
             if (!fileName || fileName === '%unk' || fileName.includes('%unk'))
                 return null;
-            return normalizeRelPath(this.rootDir, fileName);
+            return this.normalizeRelPath(fileName);
         }
         catch {
             return null;
@@ -2657,7 +2826,7 @@ class ArkTSAdapter {
         return [...this.fileResults.keys()];
     }
     indexScannedFile(arkFile) {
-        const relativePath = normalizeRelPath(this.rootDir, arkFile.getFilePath());
+        const relativePath = this.normalizeRelPath(arkFile.getFilePath());
         if (!this.scanned.has(relativePath))
             return;
         if (!isArkAnalyzerSourcePath(relativePath))
@@ -2666,7 +2835,7 @@ class ArkTSAdapter {
     }
     indexViewTreesFromFiles(files) {
         for (const arkFile of files) {
-            const relativePath = normalizeRelPath(this.rootDir, arkFile.getFilePath());
+            const relativePath = this.normalizeRelPath(arkFile.getFilePath());
             if (!this.scanned.has(relativePath) || !isArkAnalyzerSourcePath(relativePath))
                 continue;
             const result = this.fileResults.get(relativePath);
@@ -2688,6 +2857,70 @@ class ArkTSAdapter {
                 }
             }
         }
+        this.indexObservedClassRefs();
+    }
+    /**
+     * State / Param fields whose type names an @Observed / @ObservedV2 class →
+     * `references` via `observed-ref` (arkui-migrate).
+     */
+    indexObservedClassRefs() {
+        const observedByName = new Map();
+        for (const [, result] of this.fileResults) {
+            for (const n of result.nodes) {
+                if (n.kind !== 'class' && n.kind !== 'struct')
+                    continue;
+                const decs = n.decorators ?? [];
+                if (!decs.some((d) => migrate_semantics_1.OBSERVATION_DECORATORS.has(d.split('@')[0])))
+                    continue;
+                const arr = observedByName.get(n.name) ?? [];
+                arr.push(n.id);
+                observedByName.set(n.name, arr);
+            }
+        }
+        if (observedByName.size === 0)
+            return;
+        for (const [relativePath, result] of this.fileResults) {
+            for (const field of result.nodes) {
+                if (field.kind !== 'property' && field.kind !== 'field')
+                    continue;
+                const typeStr = field.signature ?? '';
+                const bare = typeStr.replace(/<.*>/, '').split(/[.\s|]/).filter(Boolean).pop();
+                if (!bare)
+                    continue;
+                const targets = observedByName.get(bare);
+                if (!targets || targets.length === 0)
+                    continue;
+                // Prefer unique name; if ambiguous, same-file first
+                let targetId = targets[0];
+                if (targets.length > 1) {
+                    const sameFile = targets.find((id) => {
+                        const n = result.nodes.find((x) => x.id === id);
+                        return n?.filePath === relativePath;
+                    });
+                    if (sameFile)
+                        targetId = sameFile;
+                    else
+                        continue; // ambiguous cross-file — skip (precision > recall)
+                }
+                const edgeKey = `${field.id}\0${targetId}\0observed-ref`;
+                if (this.emittedEdgeKeys.has(edgeKey))
+                    continue;
+                this.emittedEdgeKeys.add(edgeKey);
+                const edge = arkEdge(field.id, targetId, 'references', {
+                    metadata: {
+                        synthesizedBy: 'arkui-migrate',
+                        via: 'observed-ref',
+                        registeredAt: `${relativePath}:${field.startLine}`,
+                    },
+                });
+                if (this.nodeInFile(targetId, relativePath)) {
+                    result.edges.push(edge);
+                }
+                else {
+                    this.crossFileEdges.push(edge);
+                }
+            }
+        }
     }
     /** Index ArkAnalyzer's in-scene @dummyMain (DummyMainCreater output), not a HomeGraph synthetic node. */
     indexArkanalyzerDummyMain(dummyMain) {
@@ -2726,7 +2959,7 @@ class ArkTSAdapter {
         this.nodeIds.add(node.id);
     }
     indexFile(arkFile) {
-        const relativePath = normalizeRelPath(this.rootDir, arkFile.getFilePath());
+        const relativePath = this.normalizeRelPath(arkFile.getFilePath());
         const language = 'arkts';
         let lineCount = 1;
         try {
@@ -2737,6 +2970,8 @@ class ArkTSAdapter {
         }
         const result = this.ensureFileResult(relativePath, lineCount);
         const fileId = `file:${relativePath}`;
+        // Before methods: record `lib*.so` bindings so body NAPI call scan can see them.
+        this.collectSoImportBindings(relativePath, arkFile);
         for (const ns of arkFile.getNamespaces()) {
             this.indexNamespace(relativePath, language, result, ns, fileId);
         }
@@ -2745,6 +2980,59 @@ class ArkTSAdapter {
         this.indexTypeAliases(relativePath, language, result, arkFile, undefined, fileId);
         this.indexModuleLocals(relativePath, language, result, arkFile, undefined, fileId);
         this.indexImports(relativePath, language, result, arkFile, fileId);
+        this.indexStorageApiKeys(relativePath, arkFile, result);
+    }
+    /** AppStorage / LocalStorage / … literal keys → arkui-migrate edges from each component. */
+    indexStorageApiKeys(relativePath, arkFile, result) {
+        let code = '';
+        try {
+            code = arkFile.getCode() ?? '';
+        }
+        catch {
+            return;
+        }
+        if (!code)
+            return;
+        const hits = (0, migrate_semantics_1.scanStorageApiKeys)(code);
+        if (hits.length === 0)
+            return;
+        const componentIds = result.nodes
+            .filter((n) => n.kind === 'component' && n.filePath === relativePath)
+            .map((n) => n.id);
+        if (componentIds.length === 0)
+            return;
+        for (const hit of hits) {
+            const line = (0, migrate_semantics_1.lineOfOffset)(code, hit.index);
+            for (const compId of componentIds) {
+                const edgeKey = `${compId}\0storage-api\0${hit.channel}\0${hit.key}`;
+                if (this.emittedEdgeKeys.has(edgeKey))
+                    continue;
+                this.emittedEdgeKeys.add(edgeKey);
+                result.edges.push(arkEdge(compId, compId, 'references', {
+                    metadata: {
+                        synthesizedBy: 'arkui-migrate',
+                        via: 'storage-api',
+                        channel: hit.channel,
+                        key: hit.key,
+                        method: hit.method,
+                        registeredAt: `${relativePath}:${line}`,
+                    },
+                }));
+            }
+        }
+    }
+    collectSoImportBindings(relativePath, arkFile) {
+        const set = new Set();
+        for (const importInfo of arkFile.getImportInfos()) {
+            const modulePath = importInfo.getFrom();
+            if (!modulePath || !LIB_SO_MODULE_RE.test(modulePath))
+                continue;
+            const clause = importInfo.getImportClauseName();
+            if (clause)
+                set.add(clause);
+        }
+        if (set.size > 0)
+            this.soImportBindingsByFile.set(relativePath, set);
     }
     indexModuleLocals(relativePath, language, result, arkFile, ns, parentId) {
         const declaringClass = ns ? ns.getDefaultClass() : arkFile.getDefaultClass();
@@ -2838,8 +3126,10 @@ class ArkTSAdapter {
         const qn = buildClassQualifiedName(cls);
         const kind = classNodeKind(cls);
         const { line, endLine, col } = linesFromPosition(cls.getOriginFullPosition());
+        const classDecs = (0, migrate_semantics_1.encodeDecoratorEntries)(modelDecoratorEntries(cls));
         const classNode = makeNode(relativePath, language, kind, displayName, qn, line, endLine, col, {
             ...modelModifiersToNodeExtras(cls),
+            ...(classDecs.length > 0 ? { decorators: classDecs } : {}),
         });
         this.addNode(result, classNode);
         this.classToId.set(cls, classNode.id);
@@ -2867,7 +3157,10 @@ class ArkTSAdapter {
             }
         }
         if (cls.hasComponentDecorator()) {
-            const componentNode = makeNode(relativePath, language, 'component', displayName, qn, line, endLine, col, { ...modelModifiersToNodeExtras(cls) });
+            const componentNode = makeNode(relativePath, language, 'component', displayName, qn, line, endLine, col, {
+                ...modelModifiersToNodeExtras(cls),
+                ...(classDecs.length > 0 ? { decorators: classDecs } : {}),
+            });
             this.addNode(result, componentNode);
             this.componentToId.set(cls, componentNode.id);
             try {
@@ -2953,10 +3246,10 @@ class ArkTSAdapter {
             return;
         const { line, endLine, col } = linesFromPosition(field.getOriginFullPosition());
         const qn = buildFieldQualifiedName(field);
-        const stateDecs = stateDecoratorKinds(field);
+        const encodedDecs = fieldDecoratorsEncoded(field);
         const fieldNode = makeNode(relativePath, language, kind, name, qn, line, endLine, col, {
             signature: field.getType()?.toString(),
-            ...(stateDecs.length > 0 ? { decorators: stateDecs } : {}),
+            ...(encodedDecs.length > 0 ? { decorators: encodedDecs } : {}),
             ...modelModifiersToNodeExtras(field),
         });
         this.addNode(result, fieldNode);
@@ -2982,19 +3275,19 @@ class ArkTSAdapter {
             classToId: this.classToId,
             fieldToId: this.fieldToId,
             nodeIds: this.nodeIds,
-            addEdge: (result, source, target, kind, callerFile, via, line) => this.addViewTreeEdge(result, source, target, kind, callerFile, via, line),
+            addEdge: (result, source, target, kind, callerFile, via, line, extraMeta) => this.addViewTreeEdge(result, source, target, kind, callerFile, via, line, extraMeta),
             ensureMethodNode: (method, relativePath, result, parentId) => this.ensureMethodNode(method, relativePath, result, parentId),
             resolveClassNodeId: (cls) => this.resolveClassNodeId(cls),
             resolveClassIdBySig: (sig, importer) => this.resolveClassIdBySig(sig, importer),
             resolveMethodIdBySig: (sig, importer) => this.resolveMethodIdBySig(sig, importer),
             resolveFieldNodeId: (field) => this.resolveFieldNodeId(field),
             markFieldStateDecorators: (field, fieldNodeId, result) => {
-                const kinds = stateDecoratorKinds(field);
-                if (kinds.length === 0)
+                const encoded = fieldDecoratorsEncoded(field);
+                if (encoded.length === 0)
                     return;
                 const node = result.nodes.find((n) => n.id === fieldNodeId);
                 if (node)
-                    node.decorators = kinds;
+                    node.decorators = encoded;
             },
         };
     }
@@ -3058,7 +3351,7 @@ class ArkTSAdapter {
         // prefer ids from the importer's file before treating the name as ambiguous.
         if (importer) {
             try {
-                const importerPath = normalizeRelPath(this.rootDir, importer.getDeclaringArkFile().getFilePath());
+                const importerPath = this.normalizeRelPath(importer.getDeclaringArkFile().getFilePath());
                 const sameFile = candidates.filter((id) => this.classIdFilePath.get(id) === importerPath);
                 if (sameFile.length > 0)
                     candidates = sameFile;
@@ -3201,7 +3494,7 @@ class ArkTSAdapter {
         if (!displayName)
             return null;
         const arkFile = method.getDeclaringArkFile();
-        const relativePath = normalizeRelPath(this.rootDir, arkFile.getFilePath());
+        const relativePath = this.normalizeRelPath(arkFile.getFilePath());
         if (!this.scanned.has(relativePath) || !isArkAnalyzerSourcePath(relativePath))
             return null;
         let lineCount = 1;
@@ -3218,7 +3511,7 @@ class ArkTSAdapter {
         this.indexMethod(relativePath, 'arkts', result, method, parentId, kind, displayName);
         return this.methodToId.get(method) ?? null;
     }
-    addViewTreeEdge(result, source, target, kind, callerFile, via, line) {
+    addViewTreeEdge(result, source, target, kind, callerFile, via, line, extraMeta) {
         const edgeKey = `${source}\0${target}\0${kind}\0${via}`;
         if (this.emittedEdgeKeys.has(edgeKey))
             return;
@@ -3228,6 +3521,7 @@ class ArkTSAdapter {
                 synthesizedBy: 'viewtree',
                 via,
                 registeredAt: `${callerFile}:${line}`,
+                ...(extraMeta ?? {}),
             },
         });
         if (this.nodeInFile(target, callerFile)) {
@@ -3305,17 +3599,14 @@ class ArkTSAdapter {
             return;
         const baseLine = method.getImplOriginFullPosition()?.getFirstLine() ?? 1;
         const seenAtLine = new Set();
-        NAPI_MEMBER_CALL_RE.lastIndex = 0;
-        let m;
-        while ((m = NAPI_MEMBER_CALL_RE.exec(code)) !== null) {
-            const symbol = m[1];
-            if (!isNapiSymbolName(symbol))
-                continue;
-            const lineOffset = code.slice(0, m.index).split('\n').length - 1;
+        const pushCall = (symbol, matchIndex) => {
+            if (!symbol)
+                return;
+            const lineOffset = code.slice(0, matchIndex).split('\n').length - 1;
             const line = baseLine + lineOffset;
             const dedupKey = `${symbol}:${line}`;
             if (seenAtLine.has(dedupKey))
-                continue;
+                return;
             seenAtLine.add(dedupKey);
             result.unresolvedReferences.push({
                 fromNodeId,
@@ -3326,6 +3617,35 @@ class ArkTSAdapter {
                 filePath: relativePath,
                 language,
             });
+        };
+        // Photos-style `Class_method` on any receiver.
+        NAPI_MEMBER_CALL_RE.lastIndex = 0;
+        let m;
+        while ((m = NAPI_MEMBER_CALL_RE.exec(code)) !== null) {
+            const symbol = m[1];
+            if (!isNapiSymbolName(symbol))
+                continue;
+            pushCall(symbol, m.index);
+        }
+        // `import x from 'libFoo.so'` → `x.draw(` / `x.getTidByName(` (camelCase OK).
+        const soBindings = this.soImportBindingsByFile.get(relativePath);
+        if (soBindings) {
+            for (const binding of soBindings) {
+                const re = new RegExp(`\\b${escapeRegExp(binding)}\\s*\\.\\s*([A-Za-z_][A-Za-z0-9_]*)\\s*\\(`, 'g');
+                while ((m = re.exec(code)) !== null) {
+                    pushCall(m[1], m.index);
+                }
+            }
+            // define_class / instance path: `this.inst?.addVerticalRuler(` — receiver is
+            // not the import binding. Only in files that already import a lib*.so.
+            const anyMemberRe = /\?\.\s*([A-Za-z_][A-Za-z0-9_]*)\s*\(|\.\s*([A-Za-z_][A-Za-z0-9_]*)\s*\(/g;
+            while ((m = anyMemberRe.exec(code)) !== null) {
+                const symbol = m[1] ?? m[2];
+                if (!symbol)
+                    continue;
+                // Skip photos-style names already handled above; keep camelCase / plain ids.
+                pushCall(symbol, m.index);
+            }
         }
     }
     indexImports(relativePath, language, result, arkFile, fileId) {
@@ -3340,7 +3660,7 @@ class ArkTSAdapter {
             if (exportInfo) {
                 const targetFile = exportInfo.getDeclaringArkFile();
                 if (targetFile) {
-                    const targetRel = normalizeRelPath(this.rootDir, targetFile.getFilePath());
+                    const targetRel = this.normalizeRelPath(targetFile.getFilePath());
                     const targetFileId = `file:${targetRel}`;
                     if (this.nodeIds.has(targetFileId)) {
                         result.edges.push(arkEdge(importNode.id, targetFileId, 'imports', {
@@ -3481,7 +3801,7 @@ function buildArkTSIndexByModuleInner(rootDir, scannedFiles, options) {
         }
         scene.analyseByModule((module, scn) => {
             const moduleFileRels = [...module.getFilesMap().values()]
-                .map((f) => normalizeRelPath(rootDir, f.getFilePath()))
+                .map((f) => adapter.normalizeRelPath(f.getFilePath()))
                 .filter((p) => p && isArkAnalyzerSourcePath(p))
                 .map(normIndexPath);
             adapter.indexModule(module, scn);
@@ -4237,13 +4557,81 @@ function attachOhosApiDbBinding(queries, binding) {
         };
     }
 }
+/** Last-resort prebuilt npm package when the project's API version cannot be obtained. */
+const OHOS_API_FALLBACK_VERSION = '6.1.0';
+function runNpmPack(args, cwd) {
+    const inv = process.platform === 'win32'
+        ? { cmd: 'cmd.exe', args: ['/d', '/s', '/c', ['npm', ...args].join(' ')] }
+        : { cmd: 'npm', args };
+    (0, child_process_1.execFileSync)(inv.cmd, inv.args, {
+        cwd,
+        stdio: 'pipe',
+        timeout: 180_000,
+        windowsHide: true,
+        env: process.env,
+    });
+}
 /**
- * Build (or reuse) ~/.homegraph/api/ohos-api-<version>.db from a local SDK.
- * Never throws — missing SDK / build failure returns a warning.
+ * Fetch `homegraph-ohos-api-db-<version>` from npm and copy the db into
+ * `~/.homegraph/api/`. Returns null when downloads are disabled, the package
+ * is missing, or install fails. Opt out: HOMEGRAPH_OHOS_API_NO_DOWNLOAD=1.
+ */
+function tryDownloadOhosApiDbFromNpm(version) {
+    if (process.env.HOMEGRAPH_OHOS_API_NO_DOWNLOAD === '1')
+        return null;
+    const dbPath = ohosApiDbInstallPath(version);
+    const packageName = ohosApiDbPackageName(version);
+    if (fs.existsSync(dbPath)) {
+        return { version, dbPath, packageName, installed: false };
+    }
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'hg-ohos-api-npm-'));
+    try {
+        runNpmPack(['pack', packageName, '--silent'], tmp);
+        const tgz = fs.readdirSync(tmp).find((f) => f.endsWith('.tgz'));
+        if (!tgz)
+            return null;
+        const extractDir = path.join(tmp, 'extract');
+        fs.mkdirSync(extractDir, { recursive: true });
+        (0, child_process_1.execFileSync)('tar', ['-xzf', path.join(tmp, tgz), '-C', extractDir], {
+            stdio: 'pipe',
+            timeout: 60_000,
+            windowsHide: true,
+        });
+        const dbName = ohosApiDbFilename(version);
+        const src = [
+            path.join(extractDir, 'package', dbName),
+            path.join(extractDir, dbName),
+        ].find((p) => fs.existsSync(p)) ?? null;
+        if (!src)
+            return null;
+        fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+        fs.copyFileSync(src, dbPath);
+        return { version, dbPath, packageName, installed: true };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        try {
+            fs.rmSync(tmp, { recursive: true, force: true });
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+/**
+ * Build (or reuse) ~/.homegraph/api/ohos-api-<version>.db from a local SDK,
+ * then npm prebuilts. Never throws — missing SDK / build / download failure
+ * returns a warning.
+ *
+ * Order: existing db → local SDK build → npm pack for that version →
+ * npm pack homegraph-ohos-api-db-6.1.0 fallback.
  */
 async function ensureOhosApiDb(version, options = {}) {
     const dbPath = ohosApiDbInstallPath(version);
     const packageName = ohosApiDbPackageName(version);
+    // 1. Local db for the requested version
     if (fs.existsSync(dbPath)) {
         return { version, dbPath, packageName, installed: false };
     }
@@ -4255,6 +4643,7 @@ async function ensureOhosApiDb(version, options = {}) {
                 'Explore will use project code only.',
         };
     }
+    // 2. Build from a local DevEco / OpenHarmony SDK
     let sdkHome = null;
     if (options.sdkHomeHint) {
         const hintHomes = expandLocalOhosSdkHomes(options.sdkHomeHint);
@@ -4265,80 +4654,87 @@ async function ensureOhosApiDb(version, options = {}) {
     if (!sdkHome) {
         sdkHome = findLocalOhosSdkForVersion(version)?.sdkHome ?? null;
     }
-    if (!sdkHome) {
-        return {
-            code: 'ohos_api_sdk_missing',
-            message: `Local OHOS SDK for API ${version} not found (set OHOS_SDK_HOME / DEVECO_SDK_HOME / HOMEGRAPH_OHOS_SDK, ` +
-                'or install the matching DevEco SDK). SDK API lookup disabled; project indexing continues normally.',
-        };
-    }
-    fs.mkdirSync(path.dirname(dbPath), { recursive: true });
-    options.onProgress?.({
-        phase: 'ohos-api',
-        current: 0,
-        total: 1,
-        currentFile: version,
-    });
-    try {
-        const result = await indexOhosApiDb({
-            sdkHome,
-            version,
-            outputPath: dbPath,
-            onProgress: options.onProgress
-                ? (progress) => {
-                    options.onProgress?.({
-                        phase: 'ohos-api',
-                        current: progress.current,
-                        total: progress.total || 1,
-                        currentFile: progress.currentFile
-                            ? `${version} ${path.basename(progress.currentFile)}`
-                            : version,
-                        subphase: progress.subphase,
-                    });
-                }
-                : undefined,
-        });
-        if (!result.success || !fs.existsSync(dbPath)) {
-            try {
-                fs.unlinkSync(dbPath);
-            }
-            catch {
-                /* ignore */
-            }
-            const detail = result.errors
-                .filter((e) => e.severity === 'error')
-                .map((e) => e.message)
-                .join('; ');
-            return {
-                code: 'ohos_api_build_failed',
-                message: `Failed to build OHOS API db for ${version} from ${sdkHome}` +
-                    (detail ? ` (${detail})` : '') +
-                    '. SDK API lookup disabled; project indexing continues normally.',
-            };
-        }
+    if (sdkHome) {
+        fs.mkdirSync(path.dirname(dbPath), { recursive: true });
         options.onProgress?.({
             phase: 'ohos-api',
-            current: 1,
+            current: 0,
             total: 1,
             currentFile: version,
         });
-        return { version, dbPath, packageName, installed: true };
-    }
-    catch (err) {
         try {
-            if (fs.existsSync(dbPath))
+            const result = await indexOhosApiDb({
+                sdkHome,
+                version,
+                outputPath: dbPath,
+                onProgress: options.onProgress
+                    ? (progress) => {
+                        options.onProgress?.({
+                            phase: 'ohos-api',
+                            current: progress.current,
+                            total: progress.total || 1,
+                            currentFile: progress.currentFile
+                                ? `${version} ${path.basename(progress.currentFile)}`
+                                : version,
+                            subphase: progress.subphase,
+                        });
+                    }
+                    : undefined,
+            });
+            if (result.success && fs.existsSync(dbPath)) {
+                options.onProgress?.({
+                    phase: 'ohos-api',
+                    current: 1,
+                    total: 1,
+                    currentFile: version,
+                });
+                return { version, dbPath, packageName, installed: true };
+            }
+            try {
                 fs.unlinkSync(dbPath);
+            }
+            catch {
+                /* ignore */
+            }
         }
         catch {
-            /* ignore */
+            try {
+                if (fs.existsSync(dbPath))
+                    fs.unlinkSync(dbPath);
+            }
+            catch {
+                /* ignore */
+            }
         }
-        const msg = err instanceof Error ? err.message : String(err);
-        return {
-            code: 'ohos_api_build_failed',
-            message: `Failed to build OHOS API db for ${version} from ${sdkHome} (${msg}). ` +
-                'SDK API lookup disabled; project indexing continues normally.',
-        };
     }
+    // 3. Download prebuilt for the requested version from npm
+    const fromNpm = tryDownloadOhosApiDbFromNpm(version);
+    if (fromNpm)
+        return fromNpm;
+    // 4. Last resort: homegraph-ohos-api-db-6.1.0
+    if (version !== OHOS_API_FALLBACK_VERSION) {
+        const fallbackPath = ohosApiDbInstallPath(OHOS_API_FALLBACK_VERSION);
+        if (fs.existsSync(fallbackPath)) {
+            return {
+                version: OHOS_API_FALLBACK_VERSION,
+                dbPath: fallbackPath,
+                packageName: ohosApiDbPackageName(OHOS_API_FALLBACK_VERSION),
+                installed: false,
+            };
+        }
+        const fallback = tryDownloadOhosApiDbFromNpm(OHOS_API_FALLBACK_VERSION);
+        if (fallback)
+            return fallback;
+    }
+    return {
+        code: 'ohos_api_sdk_missing',
+        message: `OHOS API db for ${version} unavailable (no local SDK build, npm ${packageName} failed` +
+            (version !== OHOS_API_FALLBACK_VERSION
+                ? `, and fallback ${ohosApiDbPackageName(OHOS_API_FALLBACK_VERSION)} failed`
+                : '') +
+            '). Set OHOS_SDK_HOME / DEVECO_SDK_HOME or install the matching DevEco SDK. ' +
+            'SDK API lookup disabled; project indexing continues normally.',
+    };
 }
 /**
  * Attach a prebuilt API db if present — never builds. Used on open / wireLayers.