canship 0.7.0 → 0.8.0-rc.1

package/README-zh-CN.md

@@ -1,20 +1,30 @@
 # canship
 
-面向 JavaScript / TypeScript Web 应用的本地静态扫描器，检查凭据暴露、访问控制配置及请求输入风险。扫描不执行项目代码、不上传文件、不联网。
+面向 JavaScript / TypeScript Web 应用的本地静态扫描器，检测凭据暴露、访问控制配置错误及请求输入风险。
 
-[English](./README.md)
+静态扫描离线、只读，不执行项目代码。部署校验为独立功能，须显式确认请求计划。
 
-> 本文对应 `0.7.0`。使用 `npx canship --version` 确认已安装版本。
+[English](./README.md) · [使用参考](./docs/reference-zh-CN.md) · [npm](https://www.npmjs.com/package/canship)
 
-## 快速开始
+> 候选版本 `0.8.0-rc.1` 使用 npm `next` 渠道。下方示例固定此预发布版本；稳定版 `0.7.1` 请参阅[发行版文档](https://github.com/Tasomei/canship/blob/v0.7.1/README-zh-CN.md)。
+
+## 扫描项目
+
+要求 Node.js ≥18，无运行时依赖；安装可能联网。
+
+```powershell
+npx canship@0.8.0-rc.1
+```
+
+扫描其他目录：
 
 ```powershell
-npx canship
+npx canship@0.8.0-rc.1 "./my-app"
 ```
 
-默认扫描当前目录，也可指定路径。要求 Node.js ≥18，无运行时依赖，安装可能联网。Git 检查覆盖本地跟踪文件及提交历史，不访问远程仓库；历史无法读取时标记扫描不完整。
+Git 检查读取本地跟踪文件及提交历史，不访问远程仓库；历史无法读取时标记覆盖不完整。
 
-以下报告来自发布前开发构建，使用示例数据。
+以下截图使用开发构建及合成数据。
 
 ![终端报告](https://raw.githubusercontent.com/Tasomei/canship/main/docs/images/terminal.png)
 
@@ -22,89 +32,53 @@ npx canship
 
 | 类别 | 级别 | 范围 |
 |---|:---:|---|
-| 凭据 | `P0` | 硬编码密钥、私钥、含密码的数据库连接串、公开变量中的私密值、Supabase 管理员密钥、Git 跟踪或历史中的非模板 `.env` 文件 |
+| 凭据 | `P0` | 硬编码凭据、公开环境变量暴露、Supabase 管理员密钥、Git 跟踪或历史中的非模板 `.env` 文件 |
 | API 访问 | `P0/P1` | 未识别到鉴权的数据库操作、服务端信任 Supabase `getSession()`、未验证的 Stripe webhook |
-| 数据库规则 | `P1/P2` | Supabase 表未启用 RLS、无条件放行策略、允许公开列出对象的存储桶；Firebase 开放规则及限时测试规则 |
+| 数据库规则 | `P1/P2` | Supabase RLS、无条件放行策略及公开对象列表；Firebase 开放规则及测试模式到期时间 |
 | CORS | `P1/P2` | 携带凭据的来源回显或通配符配置 |
-| 请求输入 | `P1/P2` | 请求输入参与 SQL 或命令构造、调用方可控的请求主机和重定向目标 |
+| 请求输入 | `P1/P2` | SQL 和命令构造、调用方可控的请求主机及重定向目标 |
 
-凭据格式包括 OpenAI、Anthropic、AWS、Stripe、GitHub、npm 等。Firebase 覆盖 Firestore、Storage、Realtime Database。`--list-rules` 列出规则 ID、范围及局限。
+路由分析覆盖 Next.js、SvelteKit、Nuxt、Remix / React Router、Astro、Express、Hono、Fastify 的指定入口，不支持任意框架行为。详见[入口及限制](./docs/reference-zh-CN.md#服务端入口)。
 
-### 服务端入口
+```powershell
+npx canship@0.8.0-rc.1 --list-rules
+```
 
-| 框架 | 入口 |
-|---|---|
-| Next.js | App Router 处理函数、Pages Router `/api`、`'use server'` 函数 |
-| SvelteKit | `+server` 端点、`+page.server` 表单 action |
-| Nuxt | `server/api`、`server/routes` |
-| Remix / React Router | `app/routes` 中的 `loader`、`action` 导出 |
-| Astro | `src/pages` 中的端点 |
-| Express | `app`/`Router` 路由，含 `.route()` 链、挂载的子路由和其他文件中的控制器 |
-| Hono | `app.get()` 等路由、链式调用、`basePath`，以及 `app.route()` 挂载的子应用 |
-| Fastify | 简写与 `route()` 声明、`register()` 前缀与封装作用域、`@fastify/autoload` 目录 |
+## 审阅结果
+
+报告正文为英文。`certain` 表示静态证据充分，`likely` 需人工审阅。测试和示例中的结果降为 `likely`；置信度不代表凭据有效或风险可被利用。
 
-已识别的 Next.js/Astro 中间件可抑制覆盖范围内的鉴权结果；Server Function 需在函数内检查。Express、Hono、Fastify 的中间件与钩子只有解析到拒绝未认证请求的代码或已知鉴权库时才抑制鉴权结果；名称像鉴权但无法解析的中间件降低置信度。项目自定义的会话或凭据校验（如 `validateSessionToken`）及 webhook 验签（Stripe、Polar、Clerk、Svix，以及 QStash `receiver.verify` 这类须 await 的校验）只有在失败分支抛出、跳转或返回 401/403 时才算鉴权。本地辅助函数、含鉴权逻辑的项目包装函数（如 `withWorkspace`）、SvelteKit hooks、Nuxt 中间件可降低置信度或将结果标为待复核，但保留结果。输入分析追踪可见的赋值、解构和字符串构造，不以辅助函数名称证明安全。
+显示全部置信度及详细证据：
 
-Express、Hono、Fastify 路由会跟进被调项目函数中的写入，最多两层（处理函数 → service → model）；文件约定路由只报告路由文件内的写入。路由分析不覆盖 SvelteKit 页面 load、remote function 和 Hono 的 `app.openapi()` 路由；凭据、CORS 等内容规则仍适用。
+```powershell
+npx canship@0.8.0-rc.1 --all --verbose
+```
 
-## 结果
+生成离线 HTML 报告：
 
-报告正文为英文。终端按文件分组，`--verbose` 展开摘录、说明、证据和修复步骤。HTML 为自包含离线报告，支持筛选、分组、人工操作清单及修复提示复制。
+```powershell
+npx canship@0.8.0-rc.1 --all --report
+```
 
 ![HTML 报告](https://raw.githubusercontent.com/Tasomei/canship/main/docs/images/report.png)
 
-`certain` 表示静态证据充分，`likely` 需人工审阅；测试和示例中的结果降为 `likely`。默认仅展示 `certain`，`--all` 显示全部。置信度仅反映静态证据，不代表凭据有效或风险已在运行时验证。
+[合成 HTML 示例](https://github.com/Tasomei/canship/blob/main/docs/demo.html)：下载文件后在本地打开，无需安装扫描器。
+
+HTML 支持严重度及置信度筛选、稳定定位和修复提示复制。`--no-excerpts` 移除摘录，但保留路径等项目文本。`--share-summary` 仅输出计数及范围标记，分享前仍须审阅。
 
-| 退出码 | 含义 |
+| 退出码 | 静态扫描结果 |
 |---|---|
 | `0` | 无结果，且扫描完整或由 `--best-effort` 接受 |
 | `1` | 至少一条 `certain` 的 P0/P1 结果 |
 | `2` | 其他结果，包括隐藏的 `likely` |
 | `3` | 参数错误、工具错误或未被接受的不完整扫描 |
+| `130` / `143` | 收到 SIGINT / SIGTERM，不生成扫描报告 |
 
-退出码基于规则筛选、忽略注释和基线处理后的结果。有结果时优先于扫描不完整；`--best-effort` 不改变 `1` 或 `2`。
-
-## 命令行
-
-`npx canship [path] [options]`
-
-| 参数 | 作用 |
-|---|---|
-| `-a`、`--all` | 包含 `likely` 结果 |
-| `--verbose` | 展开终端结果 |
-| `--report[=file]` | 写入 HTML，默认 `canship-report.html` |
-| `--open` | 打开 `--report` 输出；CI 和非交互终端中禁用 |
-| `--json` | 输出 JSON |
-| `--sarif[=file]` | 写入 SARIF 2.1.0，默认 `canship.sarif` |
-| `--fix-prompt` | 输出修复指令及独立的人工操作清单 |
-| `--no-excerpts` | 移除所有报告中的摘录 |
-| `--changed-since=ref` | 展示变更文件结果，保留全量扫描退出码 |
-| `--only=ids` / `--skip=ids` | 选择或排除规则及命名空间，逗号分隔，可重复 |
-| `--list-rules` | 列出规则而不扫描，支持 `--json` |
-| `--baseline[=file]` / `--baseline-write[=file]` | 抑制或记录结果，默认 `canship-baseline.json` |
-| `--no-config` / `--no-ignore-markers` | 忽略项目配置或源码抑制注释 |
-| `--best-effort` | 允许没有结果的不完整扫描退出 `0` |
-| `-h`、`--help` / `-v`、`--version` | 显示帮助或版本 |
-
-`--json` 与 `--fix-prompt` 互斥，均可同时输出 HTML 和 SARIF。
-
-`--changed-since` 比较本地共同祖先与工作区，包含未被忽略的新文件，不拉取远程、不缩小扫描范围。缺少 Git、引用或共同历史时退出 `3`；不能与 `--baseline-write` 组合。
-
-## 配置
-
-`canship.config.json` 支持 `baseline`、`only`、`skip`、`all`。命令行参数优先，`only` 与 `skip` 互斥。
-
-```json
-{ "skip": ["cors/wildcard-with-credentials"], "all": false }
-```
-
-独占行注释 `canship-ignore-file` 排除整个文件；`canship-ignore-next-line [rule]` 抑制下一行，可限定单条规则。报告披露排除项；主动抑制不标记扫描不完整，可能使退出码降为 `0`。扫描不可信项目时使用 `--no-config --no-ignore-markers`。
-
-基线表示接受已有结果，不代表问题已修复。v2 格式不受行号移动影响，但凭据变化会重新报告。
+退出码基于规则选择、源码抑制及基线处理后的结果。有结果时优先于覆盖不完整；`--best-effort` 不改变 `1` 或 `2`。须另行检查 JSON 的 `partial`、`errors`、`skipped` 和 `filesScanned`。
 
-默认路径相对扫描目录，显式路径相对工作目录；读取与写入互斥。缺失、无效或 v1 基线退出 `3`。写入成功退出 `0`，不完整或选择性扫描会提示。
+基线表示接受结果，不代表问题已修复。[基线管理](./docs/reference-zh-CN.md#配置)支持审阅已有记录、选择性接受、理由及到期时间。[报告比较](./docs/reference-zh-CN.md#命令行)提供终端、JSON 和离线 HTML 视图，区分新增、持续存在及本次未再出现，不将结果消失视为修复证明。
 
-## GitHub Action
+## 接入 CI
 
 保存为 `.github/workflows/canship.yml`：
 
@@ -121,78 +95,41 @@ jobs:
         with:
           fetch-depth: 0
           persist-credentials: false
-      - uses: Tasomei/canship@7dfebc9502b786edd5c7fd71266e4926d0ad764b
+      - uses: Tasomei/canship@7465c9560b8b3692777af080e8cc67b4be2335d7
         with:
-          version: '0.7.0'
+          version: '0.8.0-rc.1'
           honor-ignore-markers: false
 ```
 
-提交哈希固定 Action 实现，`version` 指定 npm 扫描器版本，不使用开发分支源码。Action 使用 Node.js 22，不安装或运行项目依赖，仅输出统计摘要。
+提交哈希固定 Action 实现；`version` 指定此 npm 候选版本，须在候选包公开后启用工作流。Action 使用 Node.js 22，不安装或运行项目依赖，仅输出统计摘要。
 
-| 输入 | 默认值 | 含义 |
+| 输入 | 固定 Action 的默认值 | 含义 |
 |---|---|---|
-| `version` | `0.6.0` | 精确 npm 扫描器版本 |
+| `version` | `0.7.0` | 精确 npm 版本；上例已覆盖 |
 | `fail-on` | `blocking` | `blocking`：确定的 P0/P1；`any`：全部结果；`none`：仅报告 |
 
-扫描不完整或工具错误始终失败。默认不读取项目配置、不上传 SARIF。输入输出见 [action.yml](./action.yml)。
-
-上传 SARIF 需 `security-events: write` 及代码扫描支持，fork PR 可能权限不足；上传前应审阅报告。不可信 PR 使用 `pull_request`，不要使用 `pull_request_target`。
+扫描不完整或工具错误始终失败。默认不读取项目配置、不上传 SARIF。上传需 `security-events: write` 及代码扫描支持，操作前须审阅报告。不可信 PR 使用 `pull_request`，不要使用 `pull_request_target`。详见 [Action 输入](https://github.com/Tasomei/canship/blob/main/action.yml)。
 
-## API 与结构化输出
+## 进阶用法
 
-```js
-import { scan, summarize } from 'canship'
-
-const result = await scan('./my-app', { noExcerpts: true })
-console.log(summarize(result))
-```
+[完整命令参考](./docs/reference-zh-CN.md#命令行)涵盖 JSON/SARIF、规则选择、配置、排除项、独立工作区、诊断及模板预览。[API](./docs/reference-zh-CN.md#api-与结构化输出)返回结构化结果，不加载项目配置、不写文件。
 
-`scan()` 返回全部置信度结果，支持 `only`、`skip`、`honorIgnoreMarkers`（默认 `true`）、`noExcerpts`（默认 `false`）。不加载配置、不应用基线、不写报告、不设置进程退出码；无效参数抛出异常。`listRules()` 返回规则目录。
+pre-commit 模板扫描**工作区，而非暂存区快照**。部署校验默认关闭，仅支持无认证的 HTTPS 请求；使用前须审阅[范围与隐私限制](./docs/reference-zh-CN.md#部署校验)。
 
-JSON 使用 [schemaVersion 1](./schemas/scan-report-v1.schema.json)。须独立于退出码检查 `partial`、`errors`、`skipped`、`filesScanned`。SARIF 包含证据位置和执行诊断。
+[VS Code 插件](https://github.com/Tasomei/canship/tree/main/extensions/vscode#readme)为独立开发预览，本地 VSIX 打包及已验证宿主范围见插件 README；尚未发布到 Marketplace。
 
 ## 隐私与限制
 
-- 静态检查可能误报或漏报，不验证业务授权、限流、依赖漏洞或线上配置。
-- 脱敏仅覆盖已识别格式，未知敏感值可能保留在摘录中；`--no-excerpts` 可移除摘录。路径、名称和基线描述仍可见。
-- Google/Firebase/Maps 的 `AIza…` 密钥按公开标识符处理，不单凭其值判定泄露。Supabase 检查依据本地迁移及支持的存储桶配置。
-- 评估快照获取和可选的 SARIF 上传可能联网。
-- 不跟随符号链接；嵌套仓库与子模块需单独扫描。范围内跳过项及分析超限标记扫描不完整；鉴权辅助函数解析超限不会隐藏结果，改为在受影响的结果上注明。默认排除的依赖和构建目录不计为扫描缺口。
-
-| 项目 | 上限 |
-|---|---|
-| 文件读取 | 单文件 2 MiB；单次 128 MiB、10,000 个文件，含探测 |
-| 目录遍历 | 50,000 个条目；16 层 |
-| 结果 | 每文件 100 条，优先保留高严重度、高置信度结果 |
-| Git 历史 | 每文件 100 个相关版本；单条命令 30 秒 |
-| 鉴权辅助函数解析 | 8 跳；每个辅助函数 64 个符号，每个路由文件共 1,024 个 |
-| 委托写入 | 调用 2 层；每个文件 256 个被调函数；超出部分的写入不报告 |
-| 身份/控制流 | 值解析 8 步；表达式 4,000 字符；每函数 512 个赋值/区域；区域嵌套 8 层 |
-| 请求输入追踪 | 值解析 8 步；512 个赋值/区域；单条表达式 64 KiB；URL 分析 8 层、静态前缀 200 字符 |
-| Supabase 策略/存储桶解析 | 单条语句 4,000 字符 |
-
-证据链最多 24 步，截断时提示。
-
-## 开发
-
-```powershell
-npm ci
-```
-
-```powershell
-npm run prepublishOnly
-```
+- 静态分析可能误报或漏报，不验证业务授权、限流或依赖漏洞。
+- 脱敏仅覆盖已识别格式，未知敏感值可能保留在摘录中；详细报告及基线应按内部材料处理。
+- Google/Firebase/Maps 的 `AIza…` 密钥按公开标识符处理，不单凭其值判定泄露。
+- 不跟随符号链接；嵌套仓库及子模块须单独扫描。范围内跳过项及分析上限会披露；默认排除的依赖和构建目录不计为覆盖缺口。
+- 显式部署校验会访问已确认目标；安装、评估下载及可选 SARIF 上传也可能联网。静态扫描保持离线。
 
-```powershell
-npm run test:package
-```
-
-```powershell
-npm run evaluate
-```
+详见[资源上限与覆盖边界](./docs/reference-zh-CN.md#隐私与限制)。
 
-新增规则需包含应检出和不应检出的 [夹具](./test/fixtures/)。固定项目评估见 [清单](./test/evaluation/projects.json)、[获取脚本](./scripts/fetch-evaluation-projects.mjs)、[评估器](./scripts/evaluate-projects.ts)。样本通过不代表真实检出率。
+## 开发与许可
 
-## 许可
+分别运行 `npm ci`、`npm run prepublishOnly`、`npm run test:package`、`npm run evaluate`。新增规则须包含应检出和不应检出的夹具；样本通过不代表真实检出率。详见[开发参考](./docs/reference-zh-CN.md#开发)。
 
 [MIT](./LICENSE)。Supabase/Firebase 夹具保留 Apache-2.0，Next.js/`cors` 夹具保留 MIT。

package/README.md

@@ -1,20 +1,30 @@
 # canship
 
-A local static scanner for JavaScript and TypeScript web apps. Checks exposed credentials, access-control configuration, and unsafe request-input flows. No project-code execution, uploads, or network requests during scanning.
+A local static scanner for JavaScript and TypeScript web apps. Detects exposed credentials, access-control misconfiguration, and unsafe request-input flows.
 
-[简体中文](./README-zh-CN.md)
+Static scans are offline, read-only, and execute no project code. Deployment probes are separate and require explicit plan confirmation.
 
-> Documentation for `0.7.0`. Check the installed version with `npx canship --version`.
+[简体中文](./README-zh-CN.md) · [Reference](./docs/reference.md) · [npm](https://www.npmjs.com/package/canship)
 
-## Quick start
+> Release candidate `0.8.0-rc.1` for npm `next`. Examples below pin this prerelease. For stable `0.7.1`, see the [release documentation](https://github.com/Tasomei/canship/blob/v0.7.1/README.md).
+
+## Scan a project
+
+Requires Node.js ≥18. No runtime dependencies; installation may use the network.
+
+```powershell
+npx canship@0.8.0-rc.1
+```
+
+To scan another directory:
 
 ```powershell
-npx canship
+npx canship@0.8.0-rc.1 "./my-app"
 ```
 
-Scans the current directory or a specified path. Requires Node.js ≥18; no runtime dependencies. Installation may use the network. Git checks cover locally tracked files and commit history without contacting remotes; inaccessible history marks coverage incomplete.
+Git checks inspect locally tracked files and commit history without contacting remotes. Unreadable history marks coverage incomplete.
 
-Output examples use sample data from a pre-release development build.
+The following screenshots use synthetic data from a development build.
 
 ![Terminal report](https://raw.githubusercontent.com/Tasomei/canship/main/docs/images/terminal.png)
 
@@ -22,89 +32,53 @@ Output examples use sample data from a pre-release development build.
 
 | Category | Severity | Scope |
 |---|:---:|---|
-| Credentials | `P0` | Hardcoded keys, private keys, password-bearing database URLs, public env exposure, Supabase admin keys, non-template `.env` files tracked by Git or present in history |
+| Credentials | `P0` | Hardcoded credentials, public env exposure, Supabase admin keys, non-template `.env` files tracked by Git or present in history |
 | API access | `P0/P1` | Database operations without recognised authentication, server-side trust in Supabase `getSession()`, unverified Stripe webhooks |
-| Database rules | `P1/P2` | Supabase tables without RLS, unconditional policies, public object listing in storage buckets; Firebase open rules and time-limited test rules |
+| Database rules | `P1/P2` | Supabase RLS, unconditional policies and public object listing; Firebase open rules and test-mode expiry |
 | CORS | `P1/P2` | Reflected or wildcard origins with credentials |
-| Request input | `P1/P2` | Request input in SQL or command construction, caller-chosen request hosts and redirect targets |
+| Request input | `P1/P2` | SQL and command construction, caller-controlled request hosts and redirect targets |
 
-Credential formats include OpenAI, Anthropic, AWS, Stripe, GitHub, and npm. Firebase covers Firestore, Storage, and Realtime Database. `--list-rules` lists rule IDs, scope, and limitations.
+Route analysis supports documented entry points in Next.js, SvelteKit, Nuxt, Remix / React Router, Astro, Express, Hono and Fastify—not arbitrary framework behaviour. See [entry points and limits](./docs/reference.md#server-entry-points).
 
-### Server entry points
+```powershell
+npx canship@0.8.0-rc.1 --list-rules
+```
 
-| Framework | Entry points |
-|---|---|
-| Next.js | App Router handlers, Pages Router `/api`, `'use server'` functions |
-| SvelteKit | `+server` endpoints and `+page.server` form actions |
-| Nuxt | `server/api`, `server/routes` |
-| Remix / React Router | `loader` and `action` exports in `app/routes` |
-| Astro | Endpoints in `src/pages` |
-| Express | `app`/`Router` routes, including `.route()` chains, mounted routers, and controllers in other files |
-| Hono | `app.get()`-style routes, chains, `basePath`, and sub-apps mounted with `app.route()` |
-| Fastify | Shorthand and `route()` declarations, `register()` prefixes and encapsulation, `@fastify/autoload` directories |
+## Review results
+
+Reports are in English. `certain` means strong static evidence; `likely` requires review. Tests and examples are downgraded to `likely`. Neither confidence level proves credential validity or exploitability.
 
-Recognised Next.js/Astro middleware may suppress covered auth findings; Server Functions need local checks. Express, Hono, and Fastify middleware and hooks suppress auth findings only when they resolve to code that rejects unauthenticated requests or to a known auth library; auth-like middleware that cannot be followed lowers confidence. Project session or credential checks (such as `validateSessionToken`) and webhook signature verification (Stripe, Polar, Clerk, Svix, and awaited checks such as QStash `receiver.verify`) count only when the failing branch throws, redirects, or returns 401/403. Local helpers, project wrappers that contain authentication (such as `withWorkspace`), SvelteKit hooks, and Nuxt middleware may lower confidence or mark findings for review without suppressing them. Input analysis follows visible assignments, destructuring, and string construction; helper names alone do not prove sanitisation.
+Show all confidence levels and detailed evidence:
 
-For Express, Hono, and Fastify routes, writes inside called project functions are followed two levels (handler → service → model); file-based routes report writes in the route file only. SvelteKit page loads, remote functions, and Hono `app.openapi()` routes are outside route analysis. Content-based checks, including credentials and CORS, still apply.
+```powershell
+npx canship@0.8.0-rc.1 --all --verbose
+```
 
-## Results
+Generate an offline HTML report:
 
-Reports are in English. The terminal groups findings by file; `--verbose` adds excerpts, explanations, evidence, and fixes. HTML is a self-contained offline report with filters, grouping, manual steps, and copyable fix prompts.
+```powershell
+npx canship@0.8.0-rc.1 --all --report
+```
 
 ![HTML report](https://raw.githubusercontent.com/Tasomei/canship/main/docs/images/report.png)
 
-`certain` indicates strong static evidence; `likely` requires review. Findings in tests and examples are downgraded to `likely`. Default output shows only `certain`; `--all` includes both. Confidence reflects static evidence, not credential validity or runtime verification.
+[Synthetic HTML sample](https://github.com/Tasomei/canship/blob/main/docs/demo.html): download the file and open it locally; no scanner installation is required.
+
+HTML provides severity/confidence filters, stable finding links, and copyable repair prompts. Use `--no-excerpts` to omit excerpts; paths and other project text remain. For counts without project text, use `--share-summary` and review before sharing.
 
-| Exit | Meaning |
+| Exit | Static scan result |
 |---|---|
 | `0` | No findings; coverage complete or accepted with `--best-effort` |
 | `1` | At least one `certain` P0/P1 finding |
 | `2` | Other findings, including hidden `likely` results |
 | `3` | Invalid arguments, tool error, or unaccepted incomplete coverage |
+| `130` / `143` | Interrupted by SIGINT / SIGTERM; no scan report generated |
 
-Status is calculated after rule selection, ignore comments, and baselines. Findings take precedence over incomplete coverage; `--best-effort` never changes `1` or `2`.
-
-## CLI
-
-`npx canship [path] [options]`
-
-| Option | Effect |
-|---|---|
-| `-a`, `--all` | Include `likely` findings |
-| `--verbose` | Expand terminal findings |
-| `--report[=file]` | Write HTML; default `canship-report.html` |
-| `--open` | Open `--report` output; disabled in CI and non-interactive shells |
-| `--json` | Print JSON |
-| `--sarif[=file]` | Write SARIF 2.1.0; default `canship.sarif` |
-| `--fix-prompt` | Print repair instructions and separate manual actions |
-| `--no-excerpts` | Remove excerpts from all reports |
-| `--changed-since=ref` | Show changed-file findings; preserve full-scan status |
-| `--only=ids` / `--skip=ids` | Select/exclude rules or namespaces; comma-separated, repeatable |
-| `--list-rules` | List rules without scanning; supports `--json` |
-| `--baseline[=file]` / `--baseline-write[=file]` | Suppress/record findings; default `canship-baseline.json` |
-| `--no-config` / `--no-ignore-markers` | Ignore project configuration/source suppression comments |
-| `--best-effort` | Allow incomplete coverage with no findings to exit `0` |
-| `-h`, `--help` / `-v`, `--version` | Show help/version |
-
-`--json` and `--fix-prompt` are mutually exclusive; either supports HTML and SARIF output.
-
-`--changed-since` compares the local merge base with the working tree, including non-ignored untracked files. It does not fetch or narrow scan scope. Missing Git, refs, or shared history exits `3`; it cannot be combined with `--baseline-write`.
-
-## Configuration
-
-`canship.config.json` accepts `baseline`, `only`, `skip`, and `all`. CLI options take precedence; `only` and `skip` are mutually exclusive.
-
-```json
-{ "skip": ["cors/wildcard-with-credentials"], "all": false }
-```
-
-A standalone `canship-ignore-file` comment excludes a file. `canship-ignore-next-line [rule]` suppresses the next line, optionally for one rule. Exclusions are disclosed and may reduce status to `0` without marking coverage incomplete. For untrusted projects, use `--no-config --no-ignore-markers`.
-
-Baselines accept existing findings without fixing them. Format v2 tolerates line moves but reports credential changes.
+Status is calculated after rule selection, source suppressions and baselines. Findings take precedence over incomplete coverage; `--best-effort` never changes `1` or `2`. Check JSON `partial`, `errors`, `skipped` and `filesScanned` separately.
 
-Default paths are relative to the scan directory; explicit paths are relative to the working directory. Read/write modes are mutually exclusive. Missing, invalid, or v1 baselines exit `3`. A successful write exits `0`, with a warning for incomplete or selective scans.
+Baselines accept findings; they do not fix them. Review existing decisions, accept selected results, and set optional reasons or expiry through [baseline management](./docs/reference.md#configuration). [Saved-report comparison](./docs/reference.md#cli) provides terminal, JSON and offline HTML views of added, persisting and no-longer-observed records without claiming remediation.
 
-## GitHub Action
+## Connect to CI
 
 Save as `.github/workflows/canship.yml`:
 
@@ -121,78 +95,41 @@ jobs:
         with:
           fetch-depth: 0
           persist-credentials: false
-      - uses: Tasomei/canship@7dfebc9502b786edd5c7fd71266e4926d0ad764b
+      - uses: Tasomei/canship@7465c9560b8b3692777af080e8cc67b4be2335d7
         with:
-          version: '0.7.0'
+          version: '0.8.0-rc.1'
           honor-ignore-markers: false
 ```
 
-The commit hash pins the Action implementation; `version` selects the npm scanner, not development-branch source. The Action uses Node.js 22, does not install or run project dependencies, and writes a counts-only summary.
+The hash pins the Action implementation; `version` selects this npm release candidate. Enable the workflow after the candidate is public. The Action uses Node.js 22, does not install or run project dependencies, and writes a counts-only summary.
 
-| Input | Default | Meaning |
+| Input | Pinned Action default | Meaning |
 |---|---|---|
-| `version` | `0.6.0` | Exact npm scanner version |
+| `version` | `0.7.0` | Exact npm scanner version; overridden above |
 | `fail-on` | `blocking` | `blocking`: certain P0/P1; `any`: all findings; `none`: report only |
 
-Incomplete scans and tool errors always fail. Project configuration and SARIF upload are disabled by default. Inputs and outputs: [action.yml](./action.yml).
-
-SARIF upload requires `security-events: write` and code scanning support; fork PRs may lack permission. Review reports before upload. Use `pull_request`, not `pull_request_target`, for untrusted PRs.
-
-## API and structured output
-
-```js
-import { scan, summarize } from 'canship'
-
-const result = await scan('./my-app', { noExcerpts: true })
-console.log(summarize(result))
-```
-
-`scan()` returns all confidence levels. Options: `only`, `skip`, `honorIgnoreMarkers` (default `true`), `noExcerpts` (default `false`). It does not load configuration, apply baselines, write reports, or set process exit status. Invalid arguments throw. `listRules()` returns the rule catalogue.
-
-JSON uses [schemaVersion 1](./schemas/scan-report-v1.schema.json). Check `partial`, `errors`, `skipped`, and `filesScanned` independently of exit status. SARIF includes evidence locations and execution diagnostics.
-
-## Privacy and limits
+Incomplete scans and tool errors always fail. Project configuration and SARIF upload are disabled by default. Upload requires `security-events: write` and code scanning support; review reports first. Use `pull_request`, not `pull_request_target`, for untrusted PRs. See [Action inputs](https://github.com/Tasomei/canship/blob/main/action.yml).
 
-- Static checks may miss issues or flag intentional configurations. Business authorisation, rate limiting, dependency vulnerabilities, and deployed settings are not verified.
-- Redaction covers recognised formats only. Unknown secrets may remain in excerpts; `--no-excerpts` omits excerpts. Paths, names, and baseline descriptions remain visible.
-- Google/Firebase/Maps `AIza…` keys are treated as public identifiers, not leak evidence alone. Supabase checks use local migrations and supported bucket configuration.
-- Evaluation snapshot downloads and optional SARIF uploads may use the network.
-- Symbolic links are not followed; nested repositories and submodules need separate scans. In-scope skipped paths and analysis limits mark coverage incomplete; auth helper resolution limits are noted on the affected finding instead, because they cannot hide findings. Dependency and build directories excluded by default do not count as coverage gaps.
+## Advanced use
 
-| Limit | Bound |
-|---|---|
-| File reads | 2 MiB per file; 128 MiB and 10,000 files per scan, including probes |
-| Directory discovery | 50,000 entries; 16 levels |
-| Findings | 100 per file, prioritising severity and confidence |
-| Git history | 100 relevant revisions per file; 30 seconds per command |
-| Auth helper resolution | 8 hops; 64 symbols per helper, 1,024 per route file |
-| Delegated writes | 2 call levels; 256 callees per file; writes beyond these limits are not reported |
-| Identity/control flow | 8 value hops; 4,000 expression characters; 512 assignments/regions per function; 8 nested regions |
-| Request-input tracking | 8 value hops; 512 assignments/regions; 64 KiB per expression; 8 URL-analysis levels; 200 static-prefix characters |
-| Supabase policy/bucket parsing | 4,000 characters per statement |
+[Full CLI reference](./docs/reference.md#cli) covers JSON/SARIF output, rules, configuration, exclusions, independent workspaces, diagnostics and template previews. The [API](./docs/reference.md#api-and-structured-output) returns structured findings without loading project configuration or writing files.
 
-Evidence traces are capped at 24 steps and disclose truncation.
+The pre-commit template scans the **working tree, not the staged snapshot**. Deployment probes are opt-in, HTTPS-only and unauthenticated; [review their scope and privacy limits](./docs/reference.md#deployment-probes) before use.
 
-## Development
+The [VS Code extension](https://github.com/Tasomei/canship/tree/main/extensions/vscode#readme) is a separate development preview. See its README for local VSIX packaging and verified host coverage. Marketplace publication is pending.
 
-```powershell
-npm ci
-```
-
-```powershell
-npm run prepublishOnly
-```
+## Privacy and limitations
 
-```powershell
-npm run test:package
-```
+- Static analysis may miss issues or flag intentional configurations. It does not verify business authorisation, rate limiting or dependency vulnerabilities.
+- Redaction covers recognised formats only. Unknown sensitive values may remain in excerpts; detailed reports and baselines should be treated as internal material.
+- Google/Firebase/Maps `AIza…` keys are public identifiers, not leak evidence alone.
+- Symbolic links are not followed. Nested repositories and submodules need separate scans. In-scope skips and analysis limits are disclosed; default dependency/build exclusions are not coverage gaps.
+- Explicit deployment probes contact the approved target; installation, evaluation downloads and optional SARIF upload may also use the network. Static scans remain offline.
 
-```powershell
-npm run evaluate
-```
+See [resource bounds and coverage limits](./docs/reference.md#privacy-and-limits).
 
-New rules require positive and negative [fixtures](./test/fixtures/). Pinned project evaluation: [manifest](./test/evaluation/projects.json), [fetch script](./scripts/fetch-evaluation-projects.mjs), [evaluator](./scripts/evaluate-projects.ts). Passing samples do not establish real-world detection rates.
+## Development and license
 
-## License
+Run `npm ci`, `npm run prepublishOnly`, `npm run test:package` and `npm run evaluate` separately. New rules require positive and negative fixtures; passing samples do not establish real-world detection rates. See [development reference](./docs/reference.md#development).
 
 [MIT](./LICENSE). Supabase/Firebase fixtures retain Apache-2.0; Next.js/`cors` fixtures retain MIT.