dsh-code-index 0.9.1 → 0.10.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to dsh-code-index are documented here.
 
+## 0.10.0 — ArkTS & Reliable Code Context (stable candidate, unreleased)
+
+- Add dedicated `.ets` parsing using pinned harmony-contrib/tree-sitter-arkts
+  0.3.0 / ABI-14 WASM bundled with MIT notices; no native grammar installation.
+- Extract component structs, methods, fields, decorators and TS-style business
+  declarations with stable qualified IDs and decorator-inclusive source ranges.
+  Integrate mixed ETS/TS imports, tools, Git changes and Context Packs.
+- Avoid UI built-in/attribute false relationships: UI calls need local or explicit
+  bindings; decorators/leading-dot modifiers are metadata. Keep default imports
+  import-scoped and ambiguous ETS/TS stems unresolved. No state/rerender graph.
+- Record lightweight parsed/partial/failed diagnostics and bounded issue locations;
+  omit unreliable ArkTS declarations, report index gaps, and rebuild schema-2 caches.
+- Add 15 ArkTS regression tests and pinned official sources (seven Browser files,
+  all 15 `@Local` documentation snippets). Node 22.23.3 and 24.19.0 each pass
+  235 tests, typecheck, server/client builds and real package-consumer smoke.
+  See `RELEASE_EVIDENCE_v0.10.0.md` for actual methods and Desktop results.
+- v0.9.1 remains the published stable version. No v0.10 tag, npm publication,
+  GitHub Release or main push has been performed.
+
 ## 0.9.1 — Gitignore directory whitelist fix (2026-10-10)
 
 - Fix Gitignore directory whitelist rules (`!dir/`) silently excluding source trees: directory probes now retain their trailing slash in both the scanner and watcher. Thanks to @bbskye5008 for the detailed report and reproduction in [Issue #2](https://github.com/lemonxiny55/dsh-code-index/issues/2).

package/README.md

@@ -5,7 +5,7 @@
 
 English | [中文](README.zh.md)
 
-**v0.9.0 — Edit-ready Context Packs**
+**v0.10.0 stable candidate — ArkTS & Reliable Code Context**
 
 Give your [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) agent the bounded source context it needs to start a code task. One `code_context` call selects primary declarations, strong callers/callees, imports, current changes, and likely tests, with exact source ranges and reasons for inclusion. When evidence is missing, the pack says so.
 
@@ -14,7 +14,11 @@ Give your [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) ag
 - **Evidence you can inspect:** inclusion reasons are separate from `exact` / `import-scoped` / `name-only` relationship provenance. No probability or confidence estimate is invented.
 - **Local and current:** isolated repo/worktree indexes, external add/change/delete freshness, no external indexing API key. Existing full/compact surfaces and v0.8 configuration remain supported.
 
-v0.9.0 is published on npm and passed real Agent verification in DSH Desktop `0.2.0-rc.2`. See [release evidence](RELEASE_EVIDENCE_v0.9.0.md).
+v0.9.1 is published on npm and fixes Gitignore directory whitelist rules that silently omitted source trees. The packaged candidate passed real Agent verification in DSH Desktop `0.2.0-rc.2`. See [release evidence](RELEASE_EVIDENCE_v0.9.1.md).
+
+This branch prepares the unpublished `0.10.0` stable candidate; npm `latest` remains v0.9.1.
+ArkTS `.ets` files now use a pinned, bundled MIT grammar rather than the TS
+parser. See [ArkTS PoC](ARKTS_POC_v0.10.0.md) and [v0.10 evidence](RELEASE_EVIDENCE_v0.10.0.md).
 
 ## On this page
 
@@ -33,7 +37,7 @@ v0.9.0 is published on npm and passed real Agent verification in DSH Desktop `0.
 Requires Node 22/24 and a matching DSH `0.2.0-rc.2` host group. Install the published version into a Web profile:
 
 ```sh
-npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web add dsh-code-index@0.9.0
+npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web add dsh-code-index@0.9.1
 npx @deepseek-ai/dsh@0.2.0-rc.2 web
 ```
 
@@ -85,7 +89,7 @@ Plus an optional **auto-injected system prompt section** (`code-index:repo-map`,
 
 Requires `dsh` (any install path — npx, npm, or source) and Node ≥ 22.
 
-The development compatibility target is `@deepseek-ai/dsh@0.2.0-rc.2` / `@deepseek-ai/dsh-tools@0.2.0-rc.2` (Node 22 and 24 CI matrix). The DSH plugin surface is still a preview API, so upstream changes may require compatibility updates.
+The verified compatibility target is `@deepseek-ai/dsh@0.2.0-rc.2` / `@deepseek-ai/dsh-tools@0.2.0-rc.2` (Node 22 and 24 verification matrix). The DSH plugin surface is still a preview API, so upstream changes may require compatibility updates.
 
 v0.9 requires the matching `0.2.0-rc.2` tool runtime; the peer pin prevents fresh npm installs from selecting the older registry `latest` tag. Upgrade the host group together. The text/config/tool-surface compatibility above does not promise support for older DSH APIs.
 
@@ -173,7 +177,38 @@ Options are passed as the plugin row's `config` in the profile patch (or default
 
 ## Supported languages
 
-TypeScript, JavaScript, Python, Go, Rust, Java, C++ and C (`.ts .tsx .mts .cts .js .jsx .mjs .cjs .py .pyi .go .rs .java .cpp .cc .cxx .c++ .hpp .hxx .hh .h .ipp .tpp .inl .c`) via tree-sitter WASM — pure parsing, no native build. The symbol provider seam (`src/extract.ts` + grammars) is where other languages/embeddings plug in later. C/C++ symbol extraction resolves names through the declarator chain (templates, qualified `ns::name` definitions, in-class methods), and `#include "…"` specifiers feed the repo-map reference graph.
+ArkTS, TypeScript, JavaScript, Python, Go, Rust, Java, C++ and C (`.ets .ts .tsx .mts .cts .js .jsx .mjs .cjs .py .pyi .go .rs .java .cpp .cc .cxx .c++ .hpp .hxx .hh .h .ipp .tpp .inl .c`) via tree-sitter WASM — pure parsing, no native build. The symbol provider seam (`src/extract.ts` + grammars) is where other languages/embeddings plug in later. C/C++ symbol extraction resolves names through the declarator chain (templates, qualified `ns::name` definitions, in-class methods), and `#include "…"` specifiers feed the repo-map reference graph.
+
+### ArkTS scope and limits
+
+- Components declared with `struct` appear as `kind: class`, signature `struct Name`.
+  Methods, fields, global functions, classes/interfaces/types/enums and module
+  variables have stable qualified IDs, owners and source line ranges. Decorators
+  (`@Component`, `@ComponentV2`, `@State`, `@Local`, `@Builder`, etc.) are retained
+  as metadata and included in the definition's source range.
+- `build()` and nested declarative UI blocks parse as ArkTS. Local components and
+  explicit ETS/TS imports feed symbols, search, map, references, change context
+  and Context Packs. `@Extend` metadata and UI attribute chains are excluded from
+  call relationships. Bare capitalized calls in UI bodies have no global-name or
+  imported-module fallback; unbound SDK components cannot acquire unrelated
+  same-named project targets. Ordinary callback/business calls retain existing
+  provenance. `code_refs` uses binding-aware candidates for ArkTS call sites.
+- Relative mixed ETS/TS imports work when the target is statically unique.
+  Extensionless stems with both ETS and another source file stay unresolved.
+  Default imports remain `import-scoped`; no HAR/oh-package/module alias, SDK
+  typing, re-export chain, state-update or UI rerender semantics are inferred.
+  Unbound/global custom UI components may therefore have no relationship edge.
+  Syntax acceptance does not prove valid ArkTS or HarmonyOS runtime behavior.
+- Each indexed file records `parsed`, `partial`, or `failed` syntax/read status,
+  ERROR/MISSING counts and at most three issue locations. Unreliable ArkTS
+  declarations are omitted rather than assigned misleading IDs. `code_index`
+  reports a bounded incomplete-index summary, and Context Packs/change context
+  carry gaps within their existing budgets. `parsed` means syntax extraction
+  completed, not that the index contains every semantic reference. Cache schema
+  3 rebuilds older caches automatically; source bodies remain unpersisted.
+- Grammar: [harmony-contrib 0.3.0](https://github.com/harmony-contrib/tree-sitter-arkts),
+  ABI 14, unchanged npm WASM bundled with its MIT notices. Consumer installation
+  requires no native ArkTS addon. [Asset provenance](grammars/README.md).
 
 ## How it works
 

package/README.zh.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-**v0.9.0 — Edit-ready Context Packs**
+**v0.10.0 稳定候选 — ArkTS & Reliable Code Context**
 
 让 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Agent 用一次 `code_context` 调用拿到开始处理任务所需的有界源码上下文：主要声明、强相关 caller/callee、imports、当前变化和相关测试。每个关键 item 都有入选理由，源码有准确行号；证据不足时明确说明缺口。
 
@@ -11,7 +11,11 @@
 - **可检查的证据：**入选 reason 与关系的 `exact` / `import-scoped` / `name-only` provenance 分开，不编造概率或 confidence。
 - **本地、隔离、实时：**repo/worktree 独立，外部增改删自动刷新，不需要外部索引 API key；保留 full/compact surface 和 v0.8 配置。
 
-v0.9.0 已发布到 npm，并通过 DSH Desktop `0.2.0-rc.2` 真实 Agent 验证。验证边界见[release evidence](RELEASE_EVIDENCE_v0.9.0.md)。
+v0.9.1 已发布到 npm，修复了 Gitignore 目录白名单规则静默遗漏源码的问题。打包候选产物已通过 DSH Desktop `0.2.0-rc.2` 真实 Agent 验证。验证边界见[release evidence](RELEASE_EVIDENCE_v0.9.1.md)。
+
+本分支准备尚未发布的 `0.10.0` 稳定候选，npm `latest` 仍是已发布的 v0.9.1。
+`.ets` 现在使用锁定版本、随包附带 MIT 许可证的 ArkTS grammar，独立于 TS parser。
+见 [ArkTS PoC](ARKTS_POC_v0.10.0.md) 和 [v0.10 验证证据](RELEASE_EVIDENCE_v0.10.0.md)。
 
 ## 本页导航
 
@@ -30,7 +34,7 @@ v0.9.0 已发布到 npm，并通过 DSH Desktop `0.2.0-rc.2` 真实 Agent 验证
 需要 Node 22/24 与匹配的 DSH `0.2.0-rc.2` 宿主版本组。将已发布版本安装到 Web profile：
 
 ```sh
-npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web add dsh-code-index@0.9.0
+npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web add dsh-code-index@0.9.1
 npx @deepseek-ai/dsh@0.2.0-rc.2 web
 ```
 
@@ -170,7 +174,30 @@ Git 变化使用固定的 baseline commit 判定 added/modified/deleted，保留
 
 ## 支持的语言
 
-TypeScript、JavaScript、Python、Go、Rust、Java、C++、C(`.ts .tsx .mts .cts .js .jsx .mjs .cjs .py .pyi .go .rs .java .cpp .cc .cxx .c++ .hpp .hxx .hh .h .ipp .tpp .inl .c`),通过 tree-sitter WASM 解析——纯解析,无需原生编译。符号提供方的接缝(`src/extract.ts` + 语法文件)预留了后续接入其他语言/嵌入检索的位置。C/C++ 符号提取通过 declarator 链解析名字(模板、`ns::name` 限定定义、类内方法),`#include "…"` 会接入 repo map 的引用图。
+ArkTS、TypeScript、JavaScript、Python、Go、Rust、Java、C++、C(`.ets .ts .tsx .mts .cts .js .jsx .mjs .cjs .py .pyi .go .rs .java .cpp .cc .cxx .c++ .hpp .hxx .hh .h .ipp .tpp .inl .c`),通过 tree-sitter WASM 解析——纯解析,无需原生编译。符号提供方的接缝(`src/extract.ts` + 语法文件)预留了后续接入其他语言/嵌入检索的位置。C/C++ 符号提取通过 declarator 链解析名字(模板、`ns::name` 限定定义、类内方法),`#include "…"` 会接入 repo map 的引用图。
+
+### ArkTS 功能与限制
+
+- `struct` 组件使用现有 `kind: class`，签名为 `struct Name`。方法、字段、全局函数、
+  class/interface/type/enum 和模块变量保留稳定的限定 ID、所属作用域和源码行号。
+  `@Component`、`@ComponentV2`、`@State`、`@Local`、`@Builder` 等装饰器保留为元数据，
+  装饰器所在行纳入定义源码范围。
+- 能解析 `build()` 和嵌套声明式 UI；本地组件、显式 ETS/TS import 接入符号、搜索、地图、
+  引用、变更上下文和 Context Pack。`@Extend` 元数据及 UI 属性链不会被当作业务调用关系。
+  UI 块内大写裸调用不使用全仓库同名或仅导入模块的回退，避免给无绑定的 SDK 组件关联
+  无关项目符号。普通 callback/业务调用沿用已有 provenance；ArkTS 的 `code_refs` 使用
+  按绑定解析的候选关系。
+- 唯一可确定目标的相对 ETS/TS import 可解析；同一无扩展名路径同时存在 ETS 和其他源码
+  时不猜测。默认 import 保留 `import-scoped`，不推断 HAR/oh-package/模块别名、SDK 类型、
+  re-export 链、状态更新或 UI 重渲染语义。无显式绑定的全局自定义 UI 组件可能没有关系边。
+  语法解析通过不等于 ArkTS 编译通过或鸿蒙运行时行为已验证。
+- 每个索引文件记录 `parsed` / `partial` / `failed`、ERROR/MISSING 数量和最多三处位置。
+  不可靠的 ArkTS 声明会被省略，避免错误的范围或所属作用域。`code_index` 提供有限的
+  索引不完整摘要，Context Pack 和变更上下文在原有预算内保留缺口。`parsed` 只表示语法
+  提取完成，不承诺完整语义引用。缓存 schema 3 自动重建旧缓存，仍不持久化源码正文。
+- grammar 使用 [harmony-contrib 0.3.0](https://github.com/harmony-contrib/tree-sitter-arkts)，
+  ABI 14，未经修改的 npm WASM 与 MIT 声明随包发布，消费端无需原生 ArkTS addon。
+  见 [WASM 来源](grammars/README.md)。
 
 ## 工作原理
 

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import Schema from '@deepseek-ai/schemastery';
 
 /** Shared data model for dsh-code-index. */
 /** On-disk cache layout version. Bump when persisted graph/symbol shapes change. */
-declare const REPO_INDEX_SCHEMA_VERSION: 2;
+declare const REPO_INDEX_SCHEMA_VERSION: 3;
 type SymbolKind = 'function' | 'method' | 'class' | 'interface' | 'type' | 'enum' | 'variable' | 'field' | 'import' | 'module';
 /** Stable, file-qualified symbol identity: `sym:v1:<file>#<scope>/<segment>`. */
 type SymbolId = string;
@@ -16,6 +16,8 @@ interface SymbolScopePart {
     ordinal: number;
 }
 interface SymbolInfo {
+    /** ArkTS decorators as written; their source lines belong to the definition. */
+    decorators?: string[];
     /** Stable qualified id; unique within a RepoIndex. */
     id: SymbolId;
     /** Symbol name (identifier / type id / member name). */
@@ -53,6 +55,8 @@ interface ImportInfo {
 }
 /** One call site: callee name, line, and enclosing function ('' = module level). */
 interface CallInfo {
+    /** ArkUI syntax requires an explicit/local binding; no global name guessing. */
+    context?: 'arkui';
     /** Callee name as written (identifier, member/property, or qualified tail). */
     name: string;
     /** 1-based line of the call expression. */
@@ -65,6 +69,8 @@ interface CallInfo {
     qualifier: string | null;
 }
 interface IndexedFile {
+    /** Syntax/read completeness, not a typecheck or HarmonyOS runtime verdict. */
+    diagnostic?: ParseDiagnostic;
     /** Repo-relative path (forward-slash). */
     path: string;
     lang: string;
@@ -79,6 +85,16 @@ interface IndexedFile {
      *  Optional because caches written before call-graph support lack it. */
     calls?: CallInfo[];
 }
+interface ParseDiagnostic {
+    status: 'parsed' | 'partial' | 'failed';
+    errorCount: number;
+    missingCount: number;
+    issues: Array<{
+        kind: 'ERROR' | 'MISSING';
+        line: number;
+    }>;
+    reason?: 'source-unavailable' | 'parser-failed';
+}
 interface RepoIndex {
     /** Persisted layout version; see {@link REPO_INDEX_SCHEMA_VERSION}. */
     schemaVersion: typeof REPO_INDEX_SCHEMA_VERSION;
@@ -122,14 +138,14 @@ declare function findRepoRoot(startDir: string, maxLevels?: number): Promise<str
  * Parses a source text with a per-language grammar (web-tree-sitter WASM,
  * static grammars from tree-sitter-wasms) and returns flat SymbolInfo rows.
  *
- * NOTE on the dependency pin: web-tree-sitter must stay at ^0.20.x — newer
- * releases expect dylinked grammar wasm, while tree-sitter-wasms ships
- * static builds. Verified working pair: web-tree-sitter@0.20.8 + tree-sitter-wasms@0.1.13.
+ * web-tree-sitter 0.25 loads the existing tree-sitter-wasms grammars and the
+ * pinned ArkTS ABI-14 asset. See grammars/README.md for provenance.
  */
 
-type LanguageId = 'typescript' | 'javascript' | 'python' | 'go' | 'rust' | 'java' | 'cpp' | 'c';
+type LanguageId = 'arkts' | 'typescript' | 'javascript' | 'python' | 'go' | 'rust' | 'java' | 'cpp' | 'c';
 declare function languageForFile(filePath: string): LanguageId | null;
 interface ExtractedFile {
+    diagnostic: ParseDiagnostic;
     symbols: SymbolInfo[];
     /** Derived compatibility view of {@link importDetails} specifiers. */
     imports: string[];
@@ -171,6 +187,9 @@ declare function defaultCachePath(root: string, cacheDir?: string): string;
 declare function loadIndex(cachePath: string): Promise<RepoIndex | null>;
 declare function saveIndex(cachePath: string, index: RepoIndex): Promise<void>;
 
+/** One summary and at most three file locations. No source or exception dump. */
+declare function indexIntegrityWarnings(index: RepoIndex): string[];
+
 /** Pure search / filter logic over a RepoIndex — unit-testable, no IO. */
 
 interface SymbolFilter {
@@ -631,4 +650,4 @@ declare const name = "dsh-code-index";
 declare const inject: readonly ["tools", "systemPrompt"];
 declare function apply(ctx: MinimalContext, pluginConfig?: PluginConfig): void;
 
-export { type AffectedTest, CACHE_DIR_NAME, type ChangeContextInput, type ChangeContextOptions, type ChangeContextResult, type ChangeKind, type ChangedSymbol, type CodeChangeContextArgs, Config, type ContextFile, type ContextOptions, type ContextPack, type ContextPackItem, type ContextRelationship, type ContextRoute, type ContextSymbol, type ContextTaskKind, DEFAULT_EXCLUDED_DIRS, type DiffHunk, type FileChange, type ImpactHop, type ImpactRow, type ImportDependent, type IndexOptions, type IndexedFile, type RepoIndex, SUPPORTED_EXTS, type SymbolInfo, type SymbolKind, type SymbolPath, type TaskContextResult, type UnmappedChange, apply, buildChangeContext, buildIndex, buildIndexWithCache, buildModuleGraph, buildSymbolTable, buildTaskContext, callerCounts, changeContextInputFromArgs, defaultCachePath, extractAll, extractSymbols, findCycles, findOrphanModules, findRepoRoot, inject, languageForFile, loadIndex, name, parseFileToSymbols, parseUnifiedDiff, rankRepoMap, readGitFileAtRef, readWorkingTreeDiff, renderChangeContext, renderContextPack, renderHit, renderRepoMap, renderTaskContext, routeTask, saveIndex, scanRepo, scoreFile, searchSymbols, symbolCount, symbolRefs, tools };
+export { type AffectedTest, CACHE_DIR_NAME, type ChangeContextInput, type ChangeContextOptions, type ChangeContextResult, type ChangeKind, type ChangedSymbol, type CodeChangeContextArgs, Config, type ContextFile, type ContextOptions, type ContextPack, type ContextPackItem, type ContextRelationship, type ContextRoute, type ContextSymbol, type ContextTaskKind, DEFAULT_EXCLUDED_DIRS, type DiffHunk, type FileChange, type ImpactHop, type ImpactRow, type ImportDependent, type IndexOptions, type IndexedFile, type ParseDiagnostic, type RepoIndex, SUPPORTED_EXTS, type SymbolInfo, type SymbolKind, type SymbolPath, type TaskContextResult, type UnmappedChange, apply, buildChangeContext, buildIndex, buildIndexWithCache, buildModuleGraph, buildSymbolTable, buildTaskContext, callerCounts, changeContextInputFromArgs, defaultCachePath, extractAll, extractSymbols, findCycles, findOrphanModules, findRepoRoot, indexIntegrityWarnings, inject, languageForFile, loadIndex, name, parseFileToSymbols, parseUnifiedDiff, rankRepoMap, readGitFileAtRef, readWorkingTreeDiff, renderChangeContext, renderContextPack, renderHit, renderRepoMap, renderTaskContext, routeTask, saveIndex, scanRepo, scoreFile, searchSymbols, symbolCount, symbolRefs, tools };