homegraph 1.6.2 → 1.6.4

package/dist/extraction/jsdoc-type-tags.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Spec 0066 — parse JSDoc `@returns` / `@param` type tags as a fallback when
+ * the signature has no usable return/param type name. Docstring text still
+ * lives on `nodes.docstring` (Spec 0020); this only extracts type *names*.
+ */
+/**
+ * Unwrap Promise/Array/… and strip arrays/generics to a bare type identifier.
+ * Returns undefined for empty / primitive / void-like results.
+ */
+export declare function extractBaseTypeName(raw: string | undefined | null): string | undefined;
+/** `@returns {Type}` or `@return Type` → base type name. */
+export declare function parseJsdocReturns(docstring: string | undefined | null): string | undefined;
+export interface JsdocParamType {
+    paramName: string;
+    typeName: string;
+}
+/** `@param {Type} name` entries with a resolvable type name. */
+export declare function parseJsdocParams(docstring: string | undefined | null): JsdocParamType[];
+//# sourceMappingURL=jsdoc-type-tags.d.ts.map

package/dist/extraction/jsdoc-type-tags.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * Spec 0066 — parse JSDoc `@returns` / `@param` type tags as a fallback when
+ * the signature has no usable return/param type name. Docstring text still
+ * lives on `nodes.docstring` (Spec 0020); this only extracts type *names*.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractBaseTypeName = extractBaseTypeName;
+exports.parseJsdocReturns = parseJsdocReturns;
+exports.parseJsdocParams = parseJsdocParams;
+const PRIMITIVE_OR_VOID = new Set([
+    'void',
+    'undefined',
+    'null',
+    'never',
+    'any',
+    'unknown',
+    'object',
+    'Object',
+    'string',
+    'String',
+    'number',
+    'Number',
+    'boolean',
+    'Boolean',
+    'bigint',
+    'symbol',
+    'Symbol',
+    'this',
+    'self',
+    'static',
+]);
+/**
+ * Unwrap Promise/Array/… and strip arrays/generics to a bare type identifier.
+ * Returns undefined for empty / primitive / void-like results.
+ */
+function extractBaseTypeName(raw) {
+    if (!raw)
+        return undefined;
+    let t = raw.trim();
+    if (!t)
+        return undefined;
+    // Drop leading `readonly` / `export` noise occasionally glued into tags.
+    t = t.replace(/^(?:readonly|export|declare)\s+/i, '').trim();
+    // Take the first union arm: `Foo | null` → `Foo`.
+    if (t.includes('|')) {
+        t = t.split('|')[0].trim();
+    }
+    // Function type → skip (no single type node).
+    if (t.includes('=>'))
+        return undefined;
+    if (t.endsWith('[]')) {
+        t = t.slice(0, -2).trim();
+    }
+    const wrapper = t.match(/^(?:Promise|Array|ReadonlyArray|Callback|Set|Iterable|Partial|Required|Readonly)\s*<\s*(.+)\s*>$/i);
+    if (wrapper?.[1]) {
+        t = wrapper[1].trim();
+        // Nested commas in Map/Record — take last type arg when present.
+        if (t.includes(',')) {
+            const mapLike = t.match(/^(?:Map|Record)\s*<[^,]+,\s*(.+)>$/i);
+            if (mapLike?.[1])
+                t = mapLike[1].trim();
+            else
+                t = t.split(',').pop().trim();
+        }
+    }
+    const mapMatch = t.match(/^(?:Map|Record)\s*<[^,]+,\s*(.+)>$/i);
+    if (mapMatch?.[1])
+        t = mapMatch[1].trim();
+    // Strip remaining generics: `Foo<T>` → `Foo`
+    t = t.replace(/<[^>]*>/g, '').replace(/\[\]/g, '').trim();
+    if (!t)
+        return undefined;
+    // Qualified → trailing simple name (`ns.Bar` → `Bar`)
+    const simple = t.split('.').filter(Boolean).pop() ?? t;
+    if (!simple || PRIMITIVE_OR_VOID.has(simple))
+        return undefined;
+    // Must look like an identifier (PascalCase preferred but allow any word).
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(simple))
+        return undefined;
+    return simple;
+}
+/** `@returns {Type}` or `@return Type` → base type name. */
+function parseJsdocReturns(docstring) {
+    if (!docstring)
+        return undefined;
+    const re = /@returns?\s+(?:\{([^}]+)\}|([A-Za-z_][\w.<>[\],\s|]*))/gi;
+    let m;
+    while ((m = re.exec(docstring)) !== null) {
+        const raw = (m[1] ?? m[2] ?? '').trim();
+        const base = extractBaseTypeName(raw);
+        if (base)
+            return base;
+    }
+    return undefined;
+}
+/** `@param {Type} name` entries with a resolvable type name. */
+function parseJsdocParams(docstring) {
+    if (!docstring)
+        return [];
+    const out = [];
+    const re = /@param(?:eter)?\s+(?:\{([^}]+)\}\s+)?\[?(\w+)\]?/gi;
+    let m;
+    while ((m = re.exec(docstring)) !== null) {
+        const typeRaw = m[1]?.trim();
+        const paramName = m[2];
+        if (!typeRaw || !paramName)
+            continue;
+        const typeName = extractBaseTypeName(typeRaw);
+        if (typeName)
+            out.push({ paramName, typeName });
+    }
+    return out;
+}
+//# sourceMappingURL=jsdoc-type-tags.js.map

package/dist/extraction/languages/arkts.js

@@ -141,6 +141,7 @@ 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 jsdoc_type_tags_1 = require("../jsdoc-type-tags");
 const wasm_runtime_flags_1 = require("../wasm-runtime-flags");
 const ignore_1 = __importDefault(require("ignore"));
 /** Primitive / void return types — not stored in nodes.return_type (inference-only column). */
@@ -2026,6 +2027,47 @@ function filesHaveArkUiEntries(files) {
 // ArkUI ViewTree — component tree, @Prop/@Link transfer, event bindings
 // =============================================================================
 const VIEWTREE_CALLBACK_ATTRS = new Set(arkanalyzer_1.CALLBACK_METHOD_NAME);
+/**
+ * Framework decorators with no project-local definition. Emitting them as
+ * unresolved `decorates` refs lets name-matcher bind @State → enum State, etc.
+ */
+const ARKUI_BUILTIN_DECORATORS = new Set([
+    'State',
+    'Prop',
+    'Link',
+    'Provide',
+    'Consume',
+    'Watch',
+    'Builder',
+    'BuilderParam',
+    'Styles',
+    'Extend',
+    'AnimatableExtend',
+    'Component',
+    'ComponentV2',
+    'Entry',
+    'CustomDialog',
+    'Observed',
+    'ObservedV2',
+    'ObjectLink',
+    'LocalStorageLink',
+    'LocalStorageProp',
+    'StorageLink',
+    'StorageProp',
+    'Track',
+    'Require',
+    'Once',
+    'Reusable',
+    'Concurrent',
+    'Sendable',
+    'Local',
+    'Param',
+    'Event',
+    'Monitor',
+    'Computed',
+    'Trace',
+    'Type',
+]);
 /** State decorator kinds on a field (@State, @Prop, @Link, …) from arkanalyzer. */
 function stateDecoratorKinds(field) {
     const decs = field.getStateDecorators?.();
@@ -2727,6 +2769,11 @@ class ArkTSAdapter {
                     continue;
                 if (!this.scanned.has(rel) || !isArkAnalyzerSourcePath(rel))
                     continue;
+                // Already indexed (usually streamed to DB). Re-running indexScannedFile
+                // would hit addNode's nodeIds short-circuit and leave an empty shell;
+                // live IR rebind is handled by bindLiveMapsFromResident.
+                if (this.nodeIds.has(`file:${rel}`))
+                    continue;
                 this.indexScannedFile(arkFile);
                 if (this.fileResults.has(rel))
                     seeded.push(rel);
@@ -3279,6 +3326,20 @@ class ArkTSAdapter {
         const result = this.fileResults.get(relativePath);
         return result?.nodes.some((n) => n.id === nodeId) ?? false;
     }
+    /**
+     * Same-file edges stay on the file's ExtractionResult (persistFileResult FK
+     * filter). Cross-file edges go to crossFileEdges and are inserted after all
+     * modules persist — do not require nodeIds.has(target) at emit time (target
+     * may be indexed later in the same batch).
+     */
+    addMaybeCrossFileEdge(result, callerFile, edge) {
+        if (this.nodeInFile(edge.target, callerFile)) {
+            result.edges.push(edge);
+        }
+        else {
+            this.crossFileEdges.push(edge);
+        }
+    }
     ensureFileResult(relativePath, lineCount) {
         let result = this.fileResults.get(relativePath);
         if (!result) {
@@ -3431,6 +3492,10 @@ class ArkTSAdapter {
             const kind = dec.getKind();
             if (!kind)
                 continue;
+            // Built-in ArkUI/ArkTS decorators have no project definition; name-match
+            // would falsely link @State → enum State, @Builder → class Builder, etc.
+            if (ARKUI_BUILTIN_DECORATORS.has(kind))
+                continue;
             result.unresolvedReferences.push({
                 fromNodeId,
                 referenceName: kind,
@@ -3529,17 +3594,62 @@ class ArkTSAdapter {
         if (superName) {
             const superCls = cls.getHeritageClass(superName);
             if (superCls && !superCls.isDefaultArkClass()) {
-                const superId = this.classToId.get(superCls);
+                const superId = this.classToId.get(superCls) ?? this.resolveClassNodeId(superCls);
+                const edgeKind = superCls.getCategory() === CLASS_CATEGORY.INTERFACE ? 'implements' : 'extends';
                 if (superId) {
-                    const edgeKind = superCls.getCategory() === CLASS_CATEGORY.INTERFACE ? 'implements' : 'extends';
-                    result.edges.push(arkEdge(classNode.id, superId, edgeKind));
+                    this.addMaybeCrossFileEdge(result, relativePath, arkEdge(classNode.id, superId, edgeKind));
+                }
+                else {
+                    const simple = superName.includes('.') ? superName.split('.').pop() : superName;
+                    if (simple && simple !== 'Object') {
+                        result.unresolvedReferences.push({
+                            fromNodeId: classNode.id,
+                            referenceName: simple,
+                            referenceKind: edgeKind,
+                            line,
+                            column: col,
+                            filePath: relativePath,
+                            language,
+                        });
+                    }
+                }
+            }
+            else if (superName && superName !== 'Object') {
+                const simple = superName.includes('.') ? superName.split('.').pop() : superName;
+                if (simple) {
+                    result.unresolvedReferences.push({
+                        fromNodeId: classNode.id,
+                        referenceName: simple,
+                        referenceKind: 'extends',
+                        line,
+                        column: col,
+                        filePath: relativePath,
+                        language,
+                    });
                 }
             }
         }
         for (const ifaceName of cls.getImplementedInterfaceNames()) {
             const iface = cls.getImplementedInterface(ifaceName);
-            if (iface && this.classToId.has(iface)) {
-                result.edges.push(arkEdge(classNode.id, this.classToId.get(iface), 'implements'));
+            const ifaceId = iface
+                ? (this.classToId.get(iface) ?? this.resolveClassNodeId(iface))
+                : null;
+            if (ifaceId) {
+                this.addMaybeCrossFileEdge(result, relativePath, arkEdge(classNode.id, ifaceId, 'implements'));
+            }
+            else if (ifaceName) {
+                const simple = ifaceName.includes('.') ? ifaceName.split('.').pop() : ifaceName;
+                if (simple) {
+                    result.unresolvedReferences.push({
+                        fromNodeId: classNode.id,
+                        referenceName: simple,
+                        referenceKind: 'implements',
+                        line,
+                        column: col,
+                        filePath: relativePath,
+                        language,
+                    });
+                }
             }
         }
         for (const method of cls.getMethods(true)) {
@@ -3886,29 +3996,18 @@ class ArkTSAdapter {
             this.crossFileEdges.push(edge);
         }
     }
-    ensureMethodNode(method, relativePath, result, parentId) {
-        const existing = this.methodToId.get(method);
-        if (existing)
-            return existing;
-        try {
-            const bySig = this.methodSigToId.get(method.getSignature().toString());
-            if (bySig) {
-                this.methodToId.set(method, bySig);
-                return bySig;
-            }
-        }
-        catch {
-            // fall through
-        }
-        if (shouldSkipArkMethod(method) && !isAnonymousArkMethod(method))
-            return null;
-        const displayName = arkMethodDisplayName(method);
-        if (!displayName)
-            return null;
-        const cls = method.getDeclaringArkClass();
-        const kind = cls.isDefaultArkClass() ? 'function' : 'method';
-        this.indexMethod(relativePath, languageForArkAnalyzerPath(relativePath), result, method, parentId, kind, displayName);
-        return this.methodToId.get(method) ?? null;
+    /**
+     * Lazily index a method for ViewTree (and any caller that used to pass the
+     * ViewTree owner path). Attribution always follows the method's declaring
+     * ArkFile / class — same as {@link resolveMethodNodeId} — so nested ViewTree
+     * walks cannot pin `%AM*` handlers onto the importer (Spec 0064).
+     *
+     * `relativePath` / `result` / `parentId` from the caller are ignored for the
+     * node row (kept on the signature so ViewTree call sites stay unchanged);
+     * ViewTree *edges* still use the importer via {@link addViewTreeEdge}.
+     */
+    ensureMethodNode(method, _relativePath, _result, _parentId) {
+        return this.resolveMethodNodeId(method);
     }
     indexMethod(relativePath, language, result, method, parentId, forcedKind, forcedDisplayName) {
         const displayName = forcedDisplayName ?? resolveMethodDisplayName(method);
@@ -3948,6 +4047,52 @@ class ArkTSAdapter {
         result.edges.push(arkEdge(parentId, methodNode.id, 'contains'));
         this.indexDecorators(result, methodNode.id, method, relativePath, language, line);
         this.indexNativeNapiCalls(method, methodNode.id, relativePath, language, result);
+        // Spec 0066: return/param types as resolvable `returns` / `type_of` refs.
+        this.emitMethodTypeEdges(method, methodNode.id, relativePath, language, line, returnType, methodNode.docstring, result);
+    }
+    /**
+     * Spec 0066 — push unresolved `returns` / `type_of` from signature types,
+     * falling back to JSDoc `@returns` / `@param` when the signature lacks them.
+     */
+    emitMethodTypeEdges(method, fromNodeId, relativePath, language, line, returnType, docstring, result) {
+        const push = (referenceName, referenceKind) => {
+            result.unresolvedReferences.push({
+                fromNodeId,
+                referenceName,
+                referenceKind,
+                line,
+                column: 0,
+                filePath: relativePath,
+                language,
+            });
+        };
+        if (returnType) {
+            push(returnType, 'returns');
+        }
+        else {
+            const fromDoc = (0, jsdoc_type_tags_1.parseJsdocReturns)(docstring);
+            if (fromDoc)
+                push(fromDoc, 'returns');
+        }
+        let emittedParam = false;
+        try {
+            for (const p of method.getParameters()) {
+                const raw = p.getType()?.toString();
+                const base = normalizeArktsReturnType(raw);
+                if (base) {
+                    push(base, 'type_of');
+                    emittedParam = true;
+                }
+            }
+        }
+        catch {
+            // parameters unavailable
+        }
+        if (!emittedParam) {
+            for (const p of (0, jsdoc_type_tags_1.parseJsdocParams)(docstring)) {
+                push(p.typeName, 'type_of');
+            }
+        }
     }
     indexNativeNapiCalls(method, fromNodeId, relativePath, language, result) {
         const code = method.getCode();
@@ -4017,12 +4162,34 @@ class ArkTSAdapter {
                 const targetFile = exportInfo.getDeclaringArkFile();
                 if (targetFile) {
                     const targetRel = this.normalizeRelPath(targetFile.getFilePath());
-                    const targetFileId = `file:${targetRel}`;
-                    if (this.nodeIds.has(targetFileId)) {
-                        result.edges.push(arkEdge(importNode.id, targetFileId, 'imports', {
+                    if (targetRel) {
+                        const targetFileId = `file:${targetRel}`;
+                        this.addMaybeCrossFileEdge(result, relativePath, arkEdge(importNode.id, targetFileId, 'imports', {
                             metadata: { synthesizedBy: 'arkanalyzer', module: modulePath },
                         }));
                     }
+                    else if (modulePath) {
+                        result.unresolvedReferences.push({
+                            fromNodeId: importNode.id,
+                            referenceName: modulePath,
+                            referenceKind: 'imports',
+                            line,
+                            column: 0,
+                            filePath: relativePath,
+                            language,
+                        });
+                    }
+                }
+                else if (modulePath) {
+                    result.unresolvedReferences.push({
+                        fromNodeId: importNode.id,
+                        referenceName: modulePath,
+                        referenceKind: 'imports',
+                        line,
+                        column: 0,
+                        filePath: relativePath,
+                        language,
+                    });
                 }
             }
             else if (modulePath) {

package/dist/extraction/store-flush-guard.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Store-phase flush / backpressure guards (Spec 0065).
+ *
+ * When `flushOrdered` records a store failure in `flushError` but returns a
+ * resolved promise, the feed backpressure `while` would otherwise spin on
+ * `await Promise.resolve()` forever (100% CPU hang). Call this at the top of
+ * that loop (and anywhere else that waits on flush progress).
+ */
+/** Throw if the ordered store flush already failed or the run was aborted. */
+export declare function throwIfStoreFlushFailed(aborted: boolean, flushError: unknown): void;
+//# sourceMappingURL=store-flush-guard.d.ts.map

package/dist/extraction/store-flush-guard.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * Store-phase flush / backpressure guards (Spec 0065).
+ *
+ * When `flushOrdered` records a store failure in `flushError` but returns a
+ * resolved promise, the feed backpressure `while` would otherwise spin on
+ * `await Promise.resolve()` forever (100% CPU hang). Call this at the top of
+ * that loop (and anywhere else that waits on flush progress).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.throwIfStoreFlushFailed = throwIfStoreFlushFailed;
+/** Throw if the ordered store flush already failed or the run was aborted. */
+function throwIfStoreFlushFailed(aborted, flushError) {
+    if (flushError)
+        throw flushError;
+    if (aborted)
+        throw new Error('Aborted');
+}
+//# sourceMappingURL=store-flush-guard.js.map

package/dist/extraction/store-worker.d.ts

@@ -6,8 +6,9 @@
  * connection: the orchestrator posts one message per file (in file order) and
  * the worker applies them in arrival order, which preserves the #1015
  * insertion-order determinism exactly as if the main thread had run the same
- * calls. The main thread performs NO database access while the writer is
- * active (fresh-DB path only), so there is no cross-connection contention.
+ * calls. Spec 0065: the main connection is closed for the worker's lifetime
+ * (`exclusiveHandoff`) — an idle open handle on MEMORY/non-WAL backends was
+ * enough to surface SQLITE_BUSY during ArkTS→store handoff.
  *
  * Protocol (main → worker):
  *   {type:'open', dbPath, fastInit}  → open connection, reply {type:'ready'}

package/dist/extraction/store-worker.js

@@ -7,8 +7,9 @@
  * connection: the orchestrator posts one message per file (in file order) and
  * the worker applies them in arrival order, which preserves the #1015
  * insertion-order determinism exactly as if the main thread had run the same
- * calls. The main thread performs NO database access while the writer is
- * active (fresh-DB path only), so there is no cross-connection contention.
+ * calls. Spec 0065: the main connection is closed for the worker's lifetime
+ * (`exclusiveHandoff`) — an idle open handle on MEMORY/non-WAL backends was
+ * enough to surface SQLITE_BUSY during ArkTS→store handoff.
  *
  * Protocol (main → worker):
  *   {type:'open', dbPath, fastInit}  → open connection, reply {type:'ready'}

package/dist/extraction/tree-sitter.d.ts

@@ -595,9 +595,15 @@ export declare class TreeSitterExtractor {
     private readonly BUILTIN_TYPES;
     /**
      * Extract type references from type annotations on a function/method/field node.
-     * Creates 'references' edges for parameter types, return types, and field types.
+     * Spec 0066: parameter / field types → `type_of`; return types → `returns`.
+     * Dart / Scala mixed signature walks stay `references` (out of this Spec).
      */
     private extractTypeAnnotations;
+    /**
+     * Spec 0066: when the AST omitted return/param types, emit unresolved
+     * `returns` / `type_of` refs from JSDoc `@returns` / `@param {Type}`.
+     */
+    private emitJsdocTypeFallbacks;
     /**
      * Extract C# type references from a node that owns a type position —
      * a method/constructor declaration, a property declaration, or a
@@ -647,6 +653,7 @@ export declare class TreeSitterExtractor {
     /**
      * Recursively walk a subtree and extract all type_identifier references.
      * Handles unions, intersections, generics, arrays, etc.
+     * Spec 0066: callers pass `returns` / `type_of` for signature positions.
      */
     private extractTypeRefsFromSubtree;
     /**