homegraph 1.5.10 → 1.6.0

package/dist/resolution/frameworks/arkts-entry.js

@@ -1,14 +1,63 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.arktsEntryResolver = void 0;
+exports.harmonyModuleRootFromProfile = harmonyModuleRootFromProfile;
+exports.resolveHarmonyPageSourcePath = resolveHarmonyPageSourcePath;
+exports.parseHarmonyRouterMap = parseHarmonyRouterMap;
+exports.parseHarmonyMainPages = parseHarmonyMainPages;
+exports.parseHarmonyStringResources = parseHarmonyStringResources;
+exports.parseHarmonyFormConfig = parseHarmonyFormConfig;
+exports.parseHarmonyShortcutsConfig = parseHarmonyShortcutsConfig;
 exports.findArktsEntryPageComponent = findArktsEntryPageComponent;
 exports.findArktsLifecycleMethod = findArktsLifecycleMethod;
+/**
+ * ArkTS entry / module manifest + Harmony route profile resolver (Spec 0039)
+ * + element/string.json lightweight constants (Spec 0041, no edges)
+ * + form_config / shortcuts_config capability profiles (Spec 0048, no UI edges).
+ *
+ * Parses:
+ * - `module.json5` pages → @Entry components, loadContent(url) → lifecycle
+ * - `route_map.json` / `router_map.json` routerMap[] → page / buildFunction
+ * - `main_pages.json` src[] → @Entry (same as module pages)
+ * - resources/.../element/string.json → constant nodes for FTS (no references)
+ * - form_config.json / shortcuts_config.json → capability constants (Spec 0048)
+ * - module.json5 form extensionAbilities + shortcuts/form metadata (Spec 0048)
+ */
+const jsonc_parser_1 = require("jsonc-parser");
+const grammars_1 = require("../../extraction/grammars");
 const LOAD_CONTENT_PAGE_RE = /loadContent\s*\(\s*['"]([^'"]+)['"]/g;
+/** Cap string.json entries per file (Spec 0041). */
+const STRING_JSON_ENTRY_CAP = 2000;
+const STRING_JSON_VALUE_CAP = 200;
+const CAPABILITY_ENTRY_CAP = 64;
 function pageStem(pagePath) {
     const normalized = pagePath.replace(/\\/g, '/');
     const base = normalized.split('/').pop() ?? normalized;
     return base.replace(/\.ets$/i, '');
 }
+function lineOfNeedle(content, needle) {
+    const idx = content.indexOf(needle);
+    if (idx < 0)
+        return 1;
+    return content.slice(0, idx).split('\n').length;
+}
+/** Module root = path prefix before `/src/main/` (Harmony HAP/HAR layout). */
+function harmonyModuleRootFromProfile(profileRel) {
+    const n = profileRel.replace(/\\/g, '/');
+    const marker = '/src/main/';
+    const i = n.indexOf(marker);
+    if (i < 0)
+        return '';
+    return n.slice(0, i);
+}
+/** Resolve `pageSourceFile` (module-relative) against the profile's module root. */
+function resolveHarmonyPageSourcePath(profileRel, pageSourceFile) {
+    const modRoot = harmonyModuleRootFromProfile(profileRel);
+    const page = pageSourceFile.replace(/\\/g, '/').replace(/^\.\//, '');
+    if (!modRoot)
+        return page;
+    return `${modRoot}/${page}`.replace(/\/+/g, '/');
+}
 function parseModuleJson5Pages(content) {
     const pages = [];
     const seen = new Set();
@@ -37,6 +86,63 @@ function parseModuleAbilities(content) {
     }
     return abilities;
 }
+/** Parse standard Harmony `routerMap` JSON (route_map / router_map). */
+function parseHarmonyRouterMap(content) {
+    let data;
+    try {
+        data = JSON.parse(content);
+    }
+    catch {
+        return [];
+    }
+    if (!data || typeof data !== 'object')
+        return [];
+    const arr = data.routerMap;
+    if (!Array.isArray(arr))
+        return [];
+    const out = [];
+    for (const item of arr) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const rec = item;
+        const name = typeof rec.name === 'string' ? rec.name.trim() : '';
+        const pageSourceFile = typeof rec.pageSourceFile === 'string' ? rec.pageSourceFile.trim() : '';
+        if (!name || !pageSourceFile)
+            continue;
+        const buildFunction = typeof rec.buildFunction === 'string' && rec.buildFunction.trim()
+            ? rec.buildFunction.trim()
+            : undefined;
+        out.push({ name, pageSourceFile, buildFunction });
+    }
+    return out;
+}
+/** Parse `main_pages.json` `{ "src": ["pages/Index", ...] }`. */
+function parseHarmonyMainPages(content) {
+    let data;
+    try {
+        data = JSON.parse(content);
+    }
+    catch {
+        return [];
+    }
+    if (!data || typeof data !== 'object')
+        return [];
+    const src = data.src;
+    if (!Array.isArray(src))
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const p of src) {
+        if (typeof p !== 'string')
+            continue;
+        const t = p.trim();
+        if (!t || t.includes('$') || seen.has(t))
+            continue;
+        seen.add(t);
+        out.push(t);
+    }
+    return out;
+}
 function findArktsComponentByName(context, name) {
     for (const kind of ['component', 'struct', 'class']) {
         const iter = context.iterateNodesByKind?.(kind) ?? context.getNodesByKind(kind);
@@ -67,6 +173,33 @@ function findArktsPageComponent(context, pagePath) {
     }
     return null;
 }
+function findArktsSymbolInFile(context, fileRel, name) {
+    const norm = fileRel.replace(/\\/g, '/');
+    const nodes = context.getNodesInFile(norm);
+    for (const n of nodes) {
+        if (n.name !== name)
+            continue;
+        if (n.kind === 'component' ||
+            n.kind === 'struct' ||
+            n.kind === 'class' ||
+            n.kind === 'function' ||
+            n.kind === 'method') {
+            return n;
+        }
+    }
+    return null;
+}
+function findArktsBuilderByName(context, name) {
+    for (const kind of ['function', 'method']) {
+        const iter = context.iterateNodesByKind?.(kind) ?? context.getNodesByKind(kind);
+        for (const n of iter) {
+            if (n.language !== 'arkts' || n.name !== name)
+                continue;
+            return n;
+        }
+    }
+    return null;
+}
 function findArktsMethodInComponent(context, component, methodName) {
     let owner = component;
     if (component.kind === 'component') {
@@ -86,12 +219,341 @@ function findArktsMethodInComponent(context, component, methodName) {
     }
     return null;
 }
+function pushPageRoute(nodes, references, filePath, content, page, now) {
+    const line = lineOfNeedle(content, page);
+    const routeId = `arkts-route:${filePath}:${page}`;
+    nodes.push({
+        id: routeId,
+        kind: 'route',
+        name: page,
+        qualifiedName: `${filePath}::${page}`,
+        filePath,
+        language: 'yaml',
+        startLine: line,
+        endLine: line,
+        startColumn: 0,
+        endColumn: 0,
+        isExported: false,
+        updatedAt: now,
+    });
+    references.push({
+        fromNodeId: routeId,
+        referenceName: pageStem(page),
+        referenceKind: 'references',
+        line,
+        column: 0,
+        filePath,
+        language: 'yaml',
+    });
+}
+function extractRouterMapProfile(filePath, content, now) {
+    const nodes = [];
+    const references = [];
+    for (const entry of parseHarmonyRouterMap(content)) {
+        const line = lineOfNeedle(content, `"name": "${entry.name}"`) || lineOfNeedle(content, entry.name);
+        const pageRel = resolveHarmonyPageSourcePath(filePath, entry.pageSourceFile);
+        const routeId = `arkts-route:${filePath}:${entry.name}`;
+        const sigParts = [`pageSourceFile=${entry.pageSourceFile}`];
+        if (entry.buildFunction)
+            sigParts.push(`buildFunction=${entry.buildFunction}`);
+        nodes.push({
+            id: routeId,
+            kind: 'route',
+            name: entry.name,
+            qualifiedName: `${filePath}::${entry.name}`,
+            filePath,
+            language: 'yaml',
+            startLine: line,
+            endLine: line,
+            startColumn: 0,
+            endColumn: 0,
+            isExported: false,
+            signature: sigParts.join('; '),
+            updatedAt: now,
+        });
+        references.push({
+            fromNodeId: routeId,
+            referenceName: pageStem(entry.pageSourceFile),
+            referenceKind: 'references',
+            line,
+            column: 0,
+            filePath,
+            language: 'yaml',
+            candidates: [pageRel],
+        });
+        if (entry.buildFunction) {
+            references.push({
+                fromNodeId: routeId,
+                referenceName: entry.buildFunction,
+                referenceKind: 'references',
+                line,
+                column: 0,
+                filePath,
+                language: 'yaml',
+                candidates: [pageRel],
+            });
+        }
+    }
+    return { nodes, references };
+}
+/**
+ * Spec 0041 — collect `{ name, value }` string resource entries (no edges).
+ * Same shape as literal-evidence: walk objects; skip illegal keys.
+ */
+function parseHarmonyStringResources(content) {
+    const data = (0, jsonc_parser_1.parse)(content, undefined, { allowTrailingComma: true });
+    if (data === undefined || data === null)
+        return [];
+    const out = [];
+    let visited = 0;
+    const visit = (value, depth) => {
+        if (++visited > 10000 || depth > 12 || !value || typeof value !== 'object')
+            return;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item, depth + 1);
+            return;
+        }
+        const entry = value;
+        if (typeof entry.name === 'string'
+            && typeof entry.value === 'string'
+            && /^[A-Za-z_][\w]*$/.test(entry.name)
+            && out.length < STRING_JSON_ENTRY_CAP) {
+            const needle = JSON.stringify(entry.name);
+            const idx = content.indexOf(needle);
+            const line = idx < 0 ? 1 : content.slice(0, idx).split('\n').length;
+            out.push({
+                name: entry.name,
+                value: entry.value.slice(0, STRING_JSON_VALUE_CAP),
+                line,
+            });
+        }
+        for (const child of Object.values(entry))
+            visit(child, depth + 1);
+    };
+    visit(data, 0);
+    return out;
+}
+function extractHarmonyStringJson(filePath, content, now) {
+    const nodes = [];
+    for (const entry of parseHarmonyStringResources(content)) {
+        nodes.push({
+            id: `harmony-string:${filePath}:${entry.name}`,
+            kind: 'constant',
+            name: entry.name,
+            qualifiedName: `app.string.${entry.name}`,
+            filePath,
+            language: 'yaml',
+            startLine: entry.line,
+            endLine: entry.line,
+            startColumn: 0,
+            endColumn: 0,
+            isExported: false,
+            docstring: entry.value,
+            signature: `$r('app.string.${entry.name}')`,
+            updatedAt: now,
+        });
+    }
+    return { nodes, references: [] };
+}
+/** Spec 0048 — form_config.json `forms[].name`. */
+function parseHarmonyFormConfig(content) {
+    let data;
+    try {
+        data = JSON.parse(content);
+    }
+    catch {
+        try {
+            data = (0, jsonc_parser_1.parse)(content, undefined, { allowTrailingComma: true });
+        }
+        catch {
+            return [];
+        }
+    }
+    if (!data || typeof data !== 'object')
+        return [];
+    const forms = data.forms;
+    if (!Array.isArray(forms))
+        return [];
+    const out = [];
+    for (const item of forms) {
+        if (out.length >= CAPABILITY_ENTRY_CAP)
+            break;
+        if (!item || typeof item !== 'object')
+            continue;
+        const name = typeof item.name === 'string'
+            ? item.name.trim()
+            : '';
+        if (!name)
+            continue;
+        const needle = JSON.stringify(name);
+        const idx = content.indexOf(needle);
+        const line = idx < 0 ? 1 : content.slice(0, idx).split('\n').length;
+        out.push({ name, line });
+    }
+    return out;
+}
+/** Spec 0048 — shortcuts_config.json `shortcuts[]`. */
+function parseHarmonyShortcutsConfig(content) {
+    let data;
+    try {
+        data = JSON.parse(content);
+    }
+    catch {
+        try {
+            data = (0, jsonc_parser_1.parse)(content, undefined, { allowTrailingComma: true });
+        }
+        catch {
+            return [];
+        }
+    }
+    if (!data || typeof data !== 'object')
+        return [];
+    const shortcuts = data.shortcuts;
+    if (!Array.isArray(shortcuts))
+        return [];
+    const out = [];
+    for (const item of shortcuts) {
+        if (out.length >= CAPABILITY_ENTRY_CAP)
+            break;
+        if (!item || typeof item !== 'object')
+            continue;
+        const rec = item;
+        const shortcutId = typeof rec.shortcutId === 'string' ? rec.shortcutId.trim() : '';
+        if (!shortcutId)
+            continue;
+        const label = typeof rec.label === 'string' ? rec.label.trim() : '';
+        let abilityName;
+        if (Array.isArray(rec.wants) && rec.wants[0] && typeof rec.wants[0] === 'object') {
+            const w = rec.wants[0];
+            if (typeof w.abilityName === 'string' && w.abilityName.trim()) {
+                abilityName = w.abilityName.trim();
+            }
+        }
+        const needle = JSON.stringify(shortcutId);
+        const idx = content.indexOf(needle);
+        const line = idx < 0 ? 1 : content.slice(0, idx).split('\n').length;
+        out.push({ shortcutId, label, abilityName, line });
+    }
+    return out;
+}
+function extractHarmonyFormConfig(filePath, content, now) {
+    const nodes = [];
+    for (const entry of parseHarmonyFormConfig(content)) {
+        nodes.push({
+            id: `harmony-form:${filePath}:${entry.name}`,
+            kind: 'constant',
+            name: entry.name,
+            qualifiedName: `harmony.form.${entry.name}`,
+            filePath,
+            language: 'yaml',
+            startLine: entry.line,
+            endLine: entry.line,
+            startColumn: 0,
+            endColumn: 0,
+            isExported: false,
+            docstring: 'form_config',
+            signature: `form_config name=${entry.name}`,
+            updatedAt: now,
+        });
+    }
+    return { nodes, references: [] };
+}
+function extractHarmonyShortcutsConfig(filePath, content, now) {
+    const nodes = [];
+    for (const entry of parseHarmonyShortcutsConfig(content)) {
+        const sigParts = [`shortcuts_config id=${entry.shortcutId}`];
+        if (entry.label)
+            sigParts.push(`label=${entry.label}`);
+        if (entry.abilityName)
+            sigParts.push(`ability=${entry.abilityName}`);
+        nodes.push({
+            id: `harmony-shortcut:${filePath}:${entry.shortcutId}`,
+            kind: 'constant',
+            name: entry.shortcutId,
+            qualifiedName: `harmony.shortcut.${entry.shortcutId}`,
+            filePath,
+            language: 'yaml',
+            startLine: entry.line,
+            endLine: entry.line,
+            startColumn: 0,
+            endColumn: 0,
+            isExported: false,
+            docstring: entry.label || 'shortcut',
+            signature: sigParts.join('; '),
+            updatedAt: now,
+        });
+    }
+    return { nodes, references: [] };
+}
+/** Spec 0048 — module.json5 form extensions + shortcuts/form metadata. */
+function extractModuleCapabilityWiring(filePath, content, now, nodes) {
+    // Locate `"type": "form"` then take the nearest preceding `"name"` in a 500-char window.
+    for (const m of content.matchAll(/"type"\s*:\s*"form"/g)) {
+        const start = Math.max(0, (m.index ?? 0) - 500);
+        const window = content.slice(start, (m.index ?? 0) + m[0].length + 200);
+        const names = [...window.matchAll(/"name"\s*:\s*"([^"]+)"/g)];
+        const name = names.length ? names[names.length - 1][1] : '';
+        if (!name || name.startsWith('ohos.'))
+            continue;
+        const src = /"srcEntry"\s*:\s*"([^"]+)"/.exec(window)?.[1] ?? '';
+        const line = lineOfNeedle(content, name);
+        const id = `harmony-form-ability:${filePath}:${name}`;
+        if (nodes.some((n) => n.id === id))
+            continue;
+        nodes.push({
+            id,
+            kind: 'route',
+            name: `formAbility:${name}`,
+            qualifiedName: `${filePath}::formAbility::${name}`,
+            filePath,
+            language: 'yaml',
+            startLine: line,
+            endLine: line,
+            startColumn: 0,
+            endColumn: 0,
+            isExported: false,
+            docstring: 'FormExtensionAbility',
+            signature: `type=form; srcEntry=${src}`,
+            updatedAt: now,
+        });
+    }
+    for (const m of content.matchAll(/\{\s*"name"\s*:\s*"([^"]+)"\s*,\s*"resource"\s*:\s*"(\$profile:[^"]+)"\s*\}/g)) {
+        const metaName = m[1];
+        const resource = m[2];
+        const isShortcut = /shortcut/i.test(metaName) || /shortcuts_config/i.test(resource);
+        const isForm = /ohos\.extension\.form/i.test(metaName) || /form_config/i.test(resource);
+        if (!isShortcut && !isForm)
+            continue;
+        const kind = isForm ? 'form' : 'shortcut';
+        const line = content.slice(0, m.index ?? 0).split('\n').length;
+        nodes.push({
+            id: `harmony-capability-meta:${filePath}:${metaName}:${resource}`,
+            kind: 'constant',
+            name: metaName,
+            qualifiedName: `harmony.capability.${kind}.${metaName}`,
+            filePath,
+            language: 'yaml',
+            startLine: line,
+            endLine: line,
+            startColumn: 0,
+            endColumn: 0,
+            isExported: false,
+            docstring: kind,
+            signature: `metadata ${metaName} → ${resource}`,
+            updatedAt: now,
+        });
+    }
+}
 exports.arktsEntryResolver = {
     name: 'arkts-entry',
     languages: ['arkts', 'yaml'],
     detect(context) {
         for (const file of context.getAllFiles()) {
-            if (file.endsWith('module.json5'))
+            if (file.endsWith('module.json5')
+                || (0, grammars_1.isHarmonyRouteProfileJson)(file)
+                || (0, grammars_1.isHarmonyElementStringJson)(file)
+                || (0, grammars_1.isHarmonyCapabilityProfileJson)(file))
                 return true;
             if (!file.endsWith('.ets'))
                 continue;
@@ -102,43 +564,22 @@ exports.arktsEntryResolver = {
         return false;
     },
     claimsReference(name) {
-        return name.startsWith('pages/') || /^[A-Z][A-Za-z0-9]*$/.test(name);
+        return (name.startsWith('pages/') ||
+            /^[A-Z][A-Za-z0-9]*$/.test(name) ||
+            /Builder$/.test(name));
     },
     extract(filePath, content) {
         const nodes = [];
         const references = [];
         const now = Date.now();
+        const base = filePath.replace(/\\/g, '/').split('/').pop()?.toLowerCase() ?? '';
         if (filePath.endsWith('module.json5')) {
             const pages = parseModuleJson5Pages(content);
             for (const page of pages) {
-                const line = content.split('\n').findIndex((l) => l.includes(page)) + 1 || 1;
-                const routeId = `arkts-route:${filePath}:${page}`;
-                nodes.push({
-                    id: routeId,
-                    kind: 'route',
-                    name: page,
-                    qualifiedName: `${filePath}::${page}`,
-                    filePath,
-                    language: 'yaml',
-                    startLine: line > 0 ? line : 1,
-                    endLine: line > 0 ? line : 1,
-                    startColumn: 0,
-                    endColumn: 0,
-                    isExported: false,
-                    updatedAt: now,
-                });
-                references.push({
-                    fromNodeId: routeId,
-                    referenceName: pageStem(page),
-                    referenceKind: 'references',
-                    line: line > 0 ? line : 1,
-                    column: 0,
-                    filePath,
-                    language: 'yaml',
-                });
+                pushPageRoute(nodes, references, filePath, content, page, now);
             }
             for (const ability of parseModuleAbilities(content)) {
-                const line = content.split('\n').findIndex((l) => l.includes(ability.name)) + 1 || 1;
+                const line = lineOfNeedle(content, ability.name);
                 const abilityId = `arkts-ability:${filePath}:${ability.name}`;
                 nodes.push({
                     id: abilityId,
@@ -147,8 +588,8 @@ exports.arktsEntryResolver = {
                     qualifiedName: `${filePath}::ability::${ability.name}`,
                     filePath,
                     language: 'yaml',
-                    startLine: line > 0 ? line : 1,
-                    endLine: line > 0 ? line : 1,
+                    startLine: line,
+                    endLine: line,
                     startColumn: 0,
                     endColumn: 0,
                     isExported: false,
@@ -156,8 +597,27 @@ exports.arktsEntryResolver = {
                     updatedAt: now,
                 });
             }
+            extractModuleCapabilityWiring(filePath, content, now, nodes);
+            return { nodes, references };
+        }
+        if (base === 'route_map.json' || base === 'router_map.json') {
+            return extractRouterMapProfile(filePath, content, now);
+        }
+        if (base === 'main_pages.json') {
+            for (const page of parseHarmonyMainPages(content)) {
+                pushPageRoute(nodes, references, filePath, content, page, now);
+            }
             return { nodes, references };
         }
+        if ((0, grammars_1.isHarmonyElementStringJson)(filePath)) {
+            return extractHarmonyStringJson(filePath, content, now);
+        }
+        if (base === 'form_config.json') {
+            return extractHarmonyFormConfig(filePath, content, now);
+        }
+        if (base === 'shortcuts_config.json') {
+            return extractHarmonyShortcutsConfig(filePath, content, now);
+        }
         if (!filePath.endsWith('.ets')) {
             return { nodes, references };
         }
@@ -181,6 +641,18 @@ exports.arktsEntryResolver = {
     resolve(ref, context) {
         if (ref.referenceKind !== 'references')
             return null;
+        const preferredFile = ref.candidates?.[0]?.replace(/\\/g, '/');
+        if (preferredFile) {
+            const inFile = findArktsSymbolInFile(context, preferredFile, ref.referenceName);
+            if (inFile) {
+                return {
+                    original: ref,
+                    targetNodeId: inFile.id,
+                    confidence: 0.92,
+                    resolvedBy: 'framework',
+                };
+            }
+        }
         if (ref.referenceName.startsWith('pages/')) {
             const routesIter = context.iterateNodesByKind?.('route') ?? context.getNodesByKind('route');
             for (const n of routesIter) {
@@ -204,6 +676,17 @@ exports.arktsEntryResolver = {
             }
             return null;
         }
+        if (/Builder$/.test(ref.referenceName)) {
+            const builder = findArktsBuilderByName(context, ref.referenceName);
+            if (builder) {
+                return {
+                    original: ref,
+                    targetNodeId: builder.id,
+                    confidence: 0.85,
+                    resolvedBy: 'framework',
+                };
+            }
+        }
         const component = findArktsComponentByName(context, ref.referenceName);
         if (component) {
             return {

package/dist/resolution/index.js

@@ -56,6 +56,7 @@ const go_module_1 = require("./go-module");
 const workspace_packages_1 = require("./workspace-packages");
 const errors_1 = require("../errors");
 const lru_cache_1 = require("./lru-cache");
+const grammars_1 = require("../extraction/grammars");
 /** Node kinds that can declare supertypes (extends/implements). */
 const SUPERTYPE_BEARING_KINDS = new Set([
     'class', 'struct', 'interface', 'trait', 'protocol', 'enum',
@@ -1087,27 +1088,30 @@ class ReferenceResolver {
                 kind,
                 line: ref.original.line,
                 column: ref.original.column,
-                metadata: {
-                    confidence: ref.confidence,
-                    resolvedBy: ref.resolvedBy,
-                    // The ORIGINAL reference text (and kind, when edge-kind promotion
-                    // rewrote it — calls→instantiates, extends→implements,
-                    // function_ref→references). If this edge's target is later removed
-                    // by a re-index, the edge is resurrected as exactly this ref and
-                    // re-resolved (#1240 removal case) — a faithful resurrection, so
-                    // re-resolution can never bind anywhere a full re-index wouldn't.
-                    // Reconstruction from the target node's name instead would strip
-                    // receiver/qualifier context (`h.greet` → `greet`) and risk a
-                    // wrong rebind; edges without refName (pre-#1240, synthesized) are
-                    // deliberately NOT resurrected for the same reason.
-                    refName: ref.original.referenceName,
-                    ...(ref.original.referenceKind !== kind ? { refKind: ref.original.referenceKind } : {}),
-                    // Uniform marker for function-as-value edges (#756), regardless of
-                    // which strategy resolved them (import vs matchFunctionRef) — lets
-                    // tooling label "callback registration" and lets validation diff
-                    // exactly the edges this feature added.
-                    ...(ref.original.referenceKind === 'function_ref' ? { fnRef: true } : {}),
-                },
+                // Spec 0039: Harmony route configs → page/builder edges need heuristic
+                // provenance + registeredAt so explore/trail show the JSON wiring site.
+                ...(() => {
+                    const sourceNode = this.queries.getNodeById(ref.original.fromNodeId);
+                    const isRouteMap = sourceNode?.kind === 'route' &&
+                        (0, grammars_1.isHarmonyRouteConfigFile)(sourceNode.filePath);
+                    const baseMeta = {
+                        confidence: ref.confidence,
+                        resolvedBy: ref.resolvedBy,
+                        refName: ref.original.referenceName,
+                        ...(ref.original.referenceKind !== kind ? { refKind: ref.original.referenceKind } : {}),
+                        ...(ref.original.referenceKind === 'function_ref' ? { fnRef: true } : {}),
+                    };
+                    if (!isRouteMap)
+                        return { metadata: baseMeta };
+                    return {
+                        provenance: 'heuristic',
+                        metadata: {
+                            ...baseMeta,
+                            synthesizedBy: 'arkts-route-map',
+                            registeredAt: `${sourceNode.filePath.replace(/\\/g, '/')}:${ref.original.line}`,
+                        },
+                    };
+                })(),
             };
         });
     }