dsh-capdiff 0.0.0-stage → 0.1.0

package/DESIGN.md

@@ -0,0 +1,201 @@
+# DESIGN — dsh-capdiff
+
+> 状态：MVP `0.1.0`，未发布。实现只用 Node 内建模块，无第三方依赖。
+> 本文说明「为什么这样实现」，以及它**故意不做**什么。
+
+## 1. 目标
+
+给定一个 DSH 插件目录和一份 manifest，回答：
+
+1. 代码里静态可见的能力，manifest 声明了吗？（`undeclared`）
+2. manifest 声明的能力，在扫描文件里看得到吗？（`unused`）
+3. 两边都有的能力是哪些？（`matched`）
+
+输出三种形态：人类摘要、JSON、SARIF 2.1.0。作为 CI/PR 的**第一道提示**，而不是安全判定。
+
+## 2. 非目标
+
+- 不做运行时沙箱、不执行插件代码、不发起网络请求。
+- 不做完整 JavaScript 解析器 / AST 类型检查。
+- 不验证 manifest 的真实性、签名或来源；manifest 在本工具眼里只是不可信输入。
+- 不证明插件安全，不输出「checked / safe」结论。
+- 不做依赖树分析（不递归 `node_modules`，也不分析传递依赖）。
+
+## 3. 架构与流水线
+
+```text
+CLI (src/cli.js)
+  parseArgs / read manifest / print
+        │
+        ▼
+core (src/core.js)
+  scanTarget(target)
+    ├─ collectSourceFiles()      递归收集 .js/.mjs/.cjs
+    ├─ analyzeSource(code)
+    │    ├─ extractImports()     正则 + 注释/字符串遮蔽
+    │    ├─ collectCapabilityEvidence()
+    │    └─ mapCapabilities()    去重、保持首次出现顺序
+    └─ 聚合跨文件的 capabilities + firstEvidence
+  parseDeclared(manifest)
+  diffCapabilities(declared, actual)
+  buildFindings(diff, firstEvidence)
+  toSarif(findings)
+```
+
+`src/core.js` 只 import `node:fs/promises` 与 `node:path`，无第三方包；`src/cli.js` 只做参数解析、文件读取与输出，业务逻辑都在 core。因此 `node --test` 可离线运行。
+
+## 4. 数据模型
+
+```js
+// extractImports() 的一项
+{ specifier: 'node:fs', kind: 'static', index: 42 }
+// kind: 'static' | 'dynamic' | 'require' | 're-export'
+
+// collectCapabilityEvidence() 的一项（内部/导出）
+{
+  capability: 'env',
+  origin: 'code',          // 'import' | 'code'
+  kind: 'usage',           // import 时保留静态种类
+  specifier: null,         // code 证据没有 specifier
+  evidence: 'process.env',
+  index: 120,
+  line: 7
+}
+
+// diffCapabilities()
+{
+  matched: ['filesystem'],
+  undeclared: ['env'],
+  unused: ['network']
+}
+
+// buildFindings() 的一项
+{ kind: 'undeclared', capability: 'env', file: 'src/a.js', line: 7,
+  evidence: 'process.env', message: '...' }
+```
+
+所有数组都保持确定性顺序：import/能力证据按源码偏移，`matched`/`unused` 按声明顺序，`undeclared` 按实际检测顺序。重复能力折叠为一项。
+
+## 5. 静态提取（extractImports）
+
+| kind | 正则覆盖 |
+|---|---|
+| `static` | `import x from 'm'`、`import {a} from 'm'`、`import * as n from 'm'`、`import 'm'` |
+| `dynamic` | `import('m')`（字符串字面量） |
+| `require` | `require('m')`（字符串字面量） |
+| `re-export` | `export {a} from 'm'`、`export * from 'm'`、`export * as n from 'm'` |
+
+实现细节：
+
+- 关键字前用 `(?<![\w$.])`，避免把 `foo.import(...)` / `foo.require(...)` 当作模块加载。
+- `import` 子句字符集限制为标识符、空白、`{}`、`,`、`*`，避免在畸形源码里 `[\s\S]*?` 跨行吞掉无关文本。
+- 副作用 import 的 `(?!\()` 防止把 `import ('m')` 重复记成 static 与 dynamic。
+- `maskNonCode()` 把注释、字符串、模板字面量内容替换成空格，**长度与换行不变**。所有 match 再检查起始字符在原文与遮蔽文本中是否一致，从而跳过注释/字符串里的假 import 与假 `eval`。
+- `index` 是语句关键字在源码中的 UTF-16 偏移；行号由 `lineOfIndex()` 换算（1-based）。
+
+已知盲区：计算出的 specifier、`createRequire`、正则字面量、模板 `${...}` 中的代码（整段模板被遮蔽）、TypeScript/JSX。详见 §10。
+
+## 6. 能力映射
+
+`CAPABILITY_MAP` 是显式表：
+
+- `node:fs` / `fs` / `fs/promises` → `filesystem`
+- `node:net` / `net` / `node:http(s)` / `http(s)` / `http2` / `tls` / `dgram` / `fetch` → `network`
+- `node:child_process` / `child_process` → `process`
+- `node:crypto` / `crypto` → `crypto`
+- 语言级：`process.env` → `env`；`eval`、`new Function` → `eval`
+
+查找顺序：精确匹配 → 去掉 `node:` 再匹配 → 取 specifier 第一段匹配（因此 `node:fs/promises` 继承 `fs`）→ 否则 `unknown`。`unknown` 是有意保留的兜底：它既覆盖第三方包，也覆盖相对路径 import，提醒复核而不是假装不存在。
+
+语言级检测对 `process.env`、`process['env']`、`eval(...)`、`new Function(...)` 生效；`eval` 用 lookbehind 排除 `obj.eval(...)`。这仍是正则，不处理 `(0, eval)`、`globalThis.eval`、`const { env } = process` 等变体。
+
+## 7. 声明解析与规范化
+
+`parseDeclared()` 支持：
+
+- `{ dsh: { capabilities: [...] } }`
+- `{ dsh: { capabilities: { network: true, filesystem: false } } }`（truthy 才声明）
+- `{ capabilities: [...] }`（脚本便利）
+- 直接数组
+- 数组元素 `{ capability | name | id | type }`，或 `{ network: true }`
+
+规范化规则：
+
+1. 去空白、转小写；
+2. 精确命中 `CAPABILITY_MAP` 的 specifier 先映射（避免 `node:child_process` 中的 `_` 被折叠破坏）；
+3. 空白/下划线折叠为 `-` 后查规范名与别名表（`fs`→`filesystem`、`http`→`network`、`environment_variables`→`env` 等）；
+4. 未知自定义名保留为小写 token，不擅自归入 `unknown`。
+
+声明顺序保留，重复项折叠。`diffCapabilities()` 对 declared/actual 再做一次同样的规范化，所以手写 `'fs'` 与 `'filesystem'` 能正确匹配。
+
+## 8. 差异与 SARIF
+
+`diffCapabilities()` 是纯集合运算：
+
+- `matched = declared ∩ actual`
+- `undeclared = actual − declared`
+- `unused = declared − actual`
+
+`buildFindings()` 把 `undeclared` 关联到该能力的首个证据（文件 + 行 + 触发文本），把 `unused` 关联到 manifest（若 CLI 已知）。`toSarif()` 输出：
+
+- `version: "2.1.0"`、`$schema`；
+- `runs[0].tool.driver.name = "dsh-capdiff"`；
+- 规则 `dsh-capdiff/undeclared`（level `warning`）与 `dsh-capdiff/unused`（level `note`）；
+- 每结果带 `ruleId`、`ruleIndex`、`message.text`、`properties.capability/kind`；
+- 有文件时带 `physicalLocation.artifactLocation.uri`，有行号时带 `region.startLine`。
+
+为什么 `undeclared` 不是 `error`：静态启发式有误报，且 manifest 可能只是尚未更新。工具应提示复核，不应把启发式当 blocker；CI 可用 JSON 的 `diff.undeclared` 自定义退出策略。
+
+## 9. CLI contract
+
+- `--json` 与 `--sarif` 互斥（同时给出 → exit 1），避免输出格式歧义。
+- 未给出 `--manifest`：声明视为空集合，实际检测全部进入 `undeclared`；不自动猜 manifest 路径，避免错误归属。
+- 目标不存在/不是可读路径、manifest 读不到或非法 JSON → stderr + exit 1。
+- 扫描成功但存在 findings → 仍 exit 0；是否失败交给 CI 判断。
+- 人类输出固定包含 heuristic 免责声明；JSON 的 `findings` 保留机器可读的 file/line/evidence。
+
+## 10. 误报 / 漏报模型
+
+| 类型 | 例子 | 结果 |
+|---|---|---|
+| 误报 | 对象/类方法 `eval() {}` 被当作 `eval` 调用 | 多报 `undeclared eval` |
+| 误报 | 类型/死代码中的 import、仅测试用的 `node:fs` | 多报 |
+| 误报 | manifest 用未收录的自定义名声明已知能力 | 可能出现 `undeclared` + `unused` 并存 |
+| 漏报 | `import(name)`、`require(name)`、`createRequire()` | 看不到 |
+| 漏报 | 模板中的 `${process.env.X}`（整段模板被遮蔽） | 看不到 `env` |
+| 漏报 | `globalThis.process.env`、`const { env } = process`、`process['e'+'nv']` | 看不到 |
+| 漏报 | `eval` 别名、`Function(...)`（不带 `new`）、`node:vm`、native addon | 看不到 |
+| 漏报 | 运行时从配置/网络加载的模块 | 看不到 |
+
+因此 `matched` 只表示「声明与静态可见集合一致」；0 findings 只表示「当前启发式没发现差异」。两者都**不是**安全结论，也不覆盖「声明了但实际滥用」的情形。
+
+## 11. 安全与信任边界
+
+- 输入源码与 manifest 都按不可信文本处理；CLI 只读文件，不执行、不 eval、不联网。
+- 本工具不验证 manifest 签名；信任链是另一个问题。若需要内容哈希/签名/撤销，应配合 `testatum-attest` 一类工具（本仓库另一包，未在此依赖）。
+- SARIF 中的路径可能暴露本地目录结构；共享报告前请自行裁剪（CLI 不自动做绝对/相对路径策略之外的脱敏）。
+
+## 12. 测试
+
+`test/` 共 26 个 `node:test` 用例：
+
+- `core.test.js`：静态/动态/require/re-export 提取、注释与字符串过滤、映射表、别名、`env`/`eval`、声明解析、diff、行号、SARIF、findings。
+- `scan.test.js`：临时目录递归、扩展名过滤、`node_modules`/`.git` 跳过、跨文件证据聚合、空目录。
+- `cli.test.js`：`--help`/`--version`、目录 + `--json`、`--sarif`、非法 manifest、互斥参数。
+
+临时目录使用 `os.tmpdir()` + `mkdtemp`，测试结束在 `t.after` 中先断言路径位于 tmpdir 下再 `rm -rf`。验收命令：
+
+```sh
+cd packages/dsh-capdiff
+node --check src/*.js
+node --test test/*.test.js
+node src/cli.js --help
+```
+
+## 13. 未来工作（不阻塞 0.1.0）
+
+- 可选 AST 解析器（仍保持默认零依赖）以降低误报/漏报。
+- 可配置 ignore glob、测试目录排除、baseline 与 SARIF fingerprints。
+- 扩展语言级模式：`globalThis.process.env`、解构、`node:vm`、全局 `fetch`。
+- 校验 manifest schema / 版本，报告未知声明名。
+- 与 attestation 工具联动：把 manifest 签名状态带进报告。

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,210 @@
-# Temporary Holding Version
+# dsh-capdiff
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> 社区项目，**与 DeepSeek（深度求索）及 DeepSeek Harness 官方无隶属关系、无赞助、无背书**。
+> Apache-2.0，版本 `0.1.0`，**尚未发布到 npm**。
+
+## 是什么
+
+`dsh-capdiff` 是一个**静态能力差异扫描器**：读取 DSH 插件 manifest 里的 `dsh.capabilities`，扫描源码中**静态可见**的模块引用与语言级能力使用，然后报告：
+
+| 结果 | 含义 |
+|---|---|
+| `matched` | manifest 声明了，扫描也看到了 |
+| `undeclared` | 代码里静态可见，但 manifest 没声明 |
+| `unused` | manifest 声明了，但在被扫描文件里没看到 |
+
+它**不执行**插件代码。它输出的是供人复核的候选差异，**不是安全审计，也不声称 `checked=safe`**。
+
+## 为什么
+
+DSH 插件 manifest 可以声明 `dsh.capabilities`，但声明是手写的，代码里实际 import 了什么往往没人对照。`dsh-capdiff` 用零依赖的正则启发式做第一道低成本检查：
+
+- PR / 发版前看一眼「声明和 import 是否对得上」；
+- 把差异转成 SARIF，接进代码扫描面板；
+- 把「声明了但没看到」的项当成清理提示，而不是结论。
+
+## 安装
+
+本版本未发布，直接从源码运行（需要 Node `^22.19.0 || >=24.9.0`）：
+
+```sh
+node packages/dsh-capdiff/src/cli.js <file-or-dir> [--manifest path] [--json|--sarif]
+```
+
+作为 npm `bin` 使用（本地 `npm link` 或在该包目录 `npm install -g .` 之后）：
+
+```sh
+dsh-capdiff ./my-plugin --manifest ./my-plugin/plugin.json
+```
+
+离线测试：
+
+```sh
+cd packages/dsh-capdiff && npm test
+# 或仓库根目录：
+node --test packages/dsh-capdiff/test/*.test.js
+```
+
+## 用法
+
+```text
+dsh-capdiff <file-or-dir> [options]
+
+  --manifest <path>  manifest JSON（含 dsh.capabilities）
+  --json             输出机器可读 JSON
+  --sarif            输出 SARIF 2.1.0
+  -h, --help         帮助
+  -V, --version      版本（输出 `dsh-capdiff 0.1.0` 并 exit 0）
+```
+
+- 目标是目录时递归扫描 `.js` / `.mjs` / `.cjs`，跳过任意层级的 `node_modules` 与 `.git`，不跟随 symlink。
+- 未传 `--manifest` 时声明集合为空，所有检测到的能力都会成为 `undeclared`；人类可读输出会提示这一点。
+- 是否在 CI 中失败由调用方根据 `diff.undeclared` 或 SARIF 决定，本工具不把 findings 当作失败。
+
+退出码：
+
+| 码 | 含义 |
+|---|---|
+| `0` | 扫描完成（**即使有 findings**） |
+| `1` | 保留：本工具没有“业务否定”状态 |
+| `2` | 用法、输入、manifest 或 IO 错误（无参数、未知选项、缺文件） |
+
+### manifest 格式
+
+数组：
+
+```json
+{
+  "name": "example-plugin",
+  "dsh": {
+    "capabilities": ["filesystem", "network"]
+  }
+}
+```
+
+对象（truthy 表示声明，`false`/`0`/`null` 表示未声明）：
+
+```json
+{
+  "dsh": {
+    "capabilities": {
+      "filesystem": true,
+      "network": {
+        "outbound": ["api.example.com"]
+      },
+      "eval": false
+    }
+  }
+}
+```
+
+为了方便脚本调用，`manifest.capabilities` 和直接传入的声明数组也会被接受；数组元素除了字符串，也可以是 `{ "capability": "network" }` / `{ "name": "network" }` 形式的对象。
+
+### 能力映射
+
+| capability | 静态触发示例 |
+|---|---|
+| `filesystem` | `import fs from 'node:fs'`、`require('fs/promises')` |
+| `network` | `node:net`、`node:http`、`node:https`、`node:http2`、`node:tls`、`node:dgram`；`fetch` 仅作为 import specifier 映射，全局 `fetch(...)` 调用目前不扫描 |
+| `process` | `node:child_process` |
+| `env` | `process.env`、`process['env']` |
+| `eval` | `eval(...)`、`new Function(...)` |
+| `crypto` | `node:crypto` |
+| `unknown` | 映射表之外的 import（含相对路径、第三方包、其他内建模块） |
+
+声明侧会做有限规范化（大小写、`_`/空格、常见别名），例如 `fs` → `filesystem`、`http` → `network`、`child_process` → `process`、`environment_variables` → `env`。`unknown` 是兜底类别，不是真实能力；相对路径 import 也会落到 `unknown`，通常应结合上下文判断，或显式声明 `unknown`。
+
+### 输出
+
+人类可读摘要（默认）：
+
+```text
+dsh-capdiff 0.1.0 - static capability diff (heuristic)
+Target:   examples/my-plugin
+Manifest: examples/my-plugin/plugin.json
+Files:    2 source file(s) scanned
+Declared: filesystem, network
+Detected: env, filesystem, network
+
+Undeclared (1) - used in code, absent from manifest:
+  - env (src/index.js:12, process.env)
+
+Matched (2): filesystem, network
+
+Note: static heuristic only - "matched" and zero findings are not proof of safety.
+```
+
+`--json` 输出目标、文件数、`declared`、`actual`、`diff` 与 `findings`：
+
+```json
+{
+  "command": "scan",
+  "ok": true,
+  "tool": "dsh-capdiff",
+  "version": "0.1.0",
+  "target": "/abs/path/my-plugin",
+  "manifest": "/abs/path/my-plugin/plugin.json",
+  "filesScanned": 2,
+  "declared": ["filesystem", "network"],
+  "actual": ["env", "filesystem", "network"],
+  "diff": {
+    "matched": ["filesystem", "network"],
+    "undeclared": ["env"],
+    "unused": []
+  },
+  "findings": [
+    {
+      "kind": "undeclared",
+      "capability": "env",
+      "file": "src/index.js",
+      "line": 12,
+      "evidence": "process.env",
+      "message": "..."
+    }
+  ]
+}
+```
+
+`--sarif` 输出最小 SARIF 2.1.0：`runs[0].tool.driver.rules` 只有 `dsh-capdiff/undeclared`（`warning`）与 `dsh-capdiff/unused`（`note`）两条规则，按需出现；`locations` 指向首个证据文件与行号（`unused` 指向 manifest，若已知）。
+
+## 限制
+
+**这是静态启发式，不是解析器、不是沙箱、不是审计。**
+
+- **只报「静态可见」**。以下都可能完全看不到：
+  - 计算出的 specifier：`import(name)`、`require(name)`；
+  - `createRequire()`、`node:vm`、native addon、子进程里再 require；
+  - `globalThis['process']['env']`、`const { env } = process`、`process['e' + 'nv']`；
+  - 配置驱动 / 插件加载器在运行时加载的模块；
+  - 传递依赖里的能力（本工具只扫描目标目录内的源码）。
+- **`unused` 不是死代码证明**：能力可能通过动态方式使用，或只在未扫描的分支/文件中使用。
+- **`matched` / 0 findings 不是安全证明**：manifest 本身可能漏声明、错声明或不可信；本工具不验证 manifest 的签名/来源，也不验证能力使用是否安全。
+- **误报**：正则不解析 AST；对象方法 `eval() {}`、类方法、注释/字符串边界、正则字面量等场景可能产生误报。代码中的注释与字符串内容会被遮蔽，但模板字面量整体被遮蔽，`${process.env.X}` 这类用法会漏报；正则字面量中的引号也可能干扰遮蔽。
+- **范围**：只扫描 `.js` / `.mjs` / `.cjs`；不扫描 `.ts` / `.jsx` / `.json` / native 文件；跳过 `node_modules`/`.git`，不跟随 symlink；不读取 `package.json` 的 `imports`/`exports` 语义。
+- **声明规范化是有限的**：未知的自定义能力名会保留（小写、空白/下划线折叠），不会自动变成某个已知类别。
+
+因此：**「没有差异」只能说明「这两个集合在当前启发式下一致」，不能说明插件安全。**
+
+## 命名核验
+
+核验日期：**2026-11-14**（Asia/Shanghai）。
+
+- npm Registry：`GET https://registry.npmjs.org/dsh-capdiff` → **HTTP 404**（`{"error":"Not found"}`），当前 npm 上无同名包。
+- GitHub：`GET https://api.github.com/search/repositories?q=dsh-capdiff+in:name` → **`total_count: 0`**，当前仓库名搜索无同名仓库。
+
+核验命令可复现：
+
+```sh
+curl -sS -o /dev/null -w '%{http_code}\n' https://registry.npmjs.org/dsh-capdiff
+curl -sS 'https://api.github.com/search/repositories?q=dsh-capdiff+in:name'
+```
+
+以上只表示该日期这两个索引中没有同名项，**不构成商标或名称专有性判断**；发布前应重新核验。
+
+## 非官方声明
+
+这是一个社区工具，不隶属于 DeepSeek（深度求索）或 DeepSeek Harness 官方，也未获得其赞助或背书。“DeepSeek Harness”“DSH”仅用于说明兼容对象。
+
+## License
+
+Apache-2.0，见 [LICENSE](./LICENSE)。

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "dsh-capdiff",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Static capability diff scanner for DSH plugin manifests: declared dsh.capabilities vs imports and eval/env use found in code, with JSON and SARIF output.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "bin": {
+    "dsh-capdiff": "./src/cli.js"
+  },
+  "exports": {
+    ".": "./src/core.js",
+    "./cli": "./src/cli.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "DESIGN.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.9.0"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "capabilities",
+    "plugin-security",
+    "sarif",
+    "static-analysis"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PerryLink/dsh-next-suite.git",
+    "directory": "packages/dsh-capdiff"
+  },
+  "homepage": "https://github.com/PerryLink/dsh-next-suite/tree/main/packages/dsh-capdiff#readme",
+  "bugs": {
+    "url": "https://github.com/PerryLink/dsh-next-suite/issues"
+  },
+  "author": "PerryLink",
+  "publishConfig": {
+    "access": "public"
+  }
+}