canship 0.7.1 → 0.8.0

package/README-zh-CN.md

@@ -1,114 +1,71 @@
 # canship
 
-面向 JavaScript / TypeScript Web 应用的本地静态扫描器，检查凭据暴露、访问控制配置及请求输入风险。扫描不执行项目代码、不上传文件、不联网。
+面向 JavaScript / TypeScript Web 应用的发布前安全检查工具。Canship 在源码中查找凭据泄露、缺失的访问控制及不安全的请求输入处理，并可选择对你拥有的部署进行校验。
 
-[English](./README.md)
+静态扫描在本地运行：只读、不执行项目代码、不发起网络请求。部署校验是独立的可选模式，只访问经你确认的目标。
 
-> 本文对应 `0.7.1`。使用 `npx canship --version` 确认已安装版本。
+[English](./README.md) · [使用参考](./docs/reference-zh-CN.md) · [发布说明](https://github.com/Tasomei/canship/releases) · [npm](https://www.npmjs.com/package/canship)
+
+> 本文对应 npm `latest` 渠道的 `0.8.0`。其他版本见[发布说明](https://github.com/Tasomei/canship/releases)。
 
 ## 快速开始
 
+要求 Node.js 18 及以上，无运行时依赖。
+
 ```powershell
-npx canship
+npx canship@0.8.0
 ```
 
-默认扫描当前目录，也可指定路径。要求 Node.js ≥18，无运行时依赖，安装可能联网。Git 检查覆盖本地跟踪文件及提交历史，不访问远程仓库；历史无法读取时标记扫描不完整。
+扫描指定目录：
+
+```powershell
+npx canship@0.8.0 "./my-app"
+```
 
-以下报告来自发布前开发构建，使用示例数据。
+合成项目的输出示例：
 
 ![终端报告](https://raw.githubusercontent.com/Tasomei/canship/main/docs/images/terminal.png)
 
 ## 检测范围
 
-| 类别 | 级别 | 范围 |
+| 类别 | 级别 | 内容 |
 |---|:---:|---|
-| 凭据 | `P0` | 硬编码密钥、私钥、含密码的数据库连接串、公开变量中的私密值、Supabase 管理员密钥、Git 跟踪或历史中的非模板 `.env` 文件 |
-| API 访问 | `P0/P1` | 未识别到鉴权的数据库操作、服务端信任 Supabase `getSession()`、未验证的 Stripe webhook |
-| 数据库规则 | `P1/P2` | Supabase 表未启用 RLS、无条件放行策略、允许公开列出对象的存储桶；Firebase 开放规则及限时测试规则 |
-| CORS | `P1/P2` | 携带凭据的来源回显或通配符配置 |
-| 请求输入 | `P1/P2` | 请求输入参与 SQL 或命令构造、调用方可控的请求主机和重定向目标 |
-
-凭据格式包括 OpenAI、Anthropic、AWS、Stripe、GitHub、npm 等。Firebase 覆盖 Firestore、Storage、Realtime Database。`--list-rules` 列出规则 ID、范围及局限。
+| 凭据 | `P0` | 硬编码密钥、公开环境变量中的密钥、Supabase 服务密钥、被 Git 跟踪或存在于历史中的 `.env` 文件 |
+| API 访问 | `P0/P1` | 未识别到鉴权的数据库操作、服务端信任 Supabase `getSession()`、未验签的 Stripe webhook |
+| 数据库规则 | `P1/P2` | 未启用 Supabase RLS、过宽的策略、公开存储列表、开放的 Firebase 规则 |
+| CORS | `P1/P2` | 携带凭据时回显来源或使用通配符 |
+| 代码（Code） | `P1/P2` | 由请求输入拼接的 SQL 与 shell 命令；向调用方指定地址发起的服务端请求和重定向 |
 
-### 服务端入口
+路由分析覆盖 Next.js、SvelteKit、Nuxt、Remix / React Router、Astro、Express、Hono、Fastify 的指定入口，详见[入口及限制](./docs/reference-zh-CN.md#服务端入口)。
 
-| 框架 | 入口 |
-|---|---|
-| 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` 目录 |
-
-已识别的 Next.js/Astro 中间件可抑制匹配路由的鉴权结果；Server Function 需在函数内检查。Express/Hono/Fastify 仅接受已解析的拒绝逻辑或已知鉴权库。Fastify 装饰器和插件的保护证据限定于当前实例。
-
-会话校验及 webhook 验签（Stripe、Polar、Clerk、Svix、QStash）须在失败时拒绝请求，异步调用须等待或返回。项目辅助函数与包装器、SvelteKit hooks、Nuxt 中间件的间接证据可降低置信度；未解析的鉴权来源不能消除结果。
+```powershell
+npx canship@0.8.0 --list-rules
+```
 
-输入追踪支持赋值、解构、字符串构造及可解析的跨文件透传函数，不以辅助函数名称证明输入已净化。
+## 审阅结果
 
-Express、Hono、Fastify 路由会跟进被调项目函数中的写入，最多两层（处理函数 → service → model）；文件约定路由只报告路由文件内的写入。路由分析不覆盖 SvelteKit 页面 load、remote function 和 Hono 的 `app.openapi()` 路由；凭据、CORS 等内容规则仍适用。
+每条结果标为 `certain`（静态证据充分）或 `likely`（需人工审阅），默认只显示 `certain`。两者都不代表凭据有效或问题可被利用。
 
-## 结果
+```powershell
+npx canship@0.8.0 --all --verbose
+```
 
-报告正文为英文。终端按文件分组，`--verbose` 展开摘录、说明、证据和修复步骤。HTML 为自包含离线报告，支持筛选、分组、人工操作清单及修复提示复制。
+```powershell
+npx canship@0.8.0 --all --report
+```
 
 ![HTML 报告](https://raw.githubusercontent.com/Tasomei/canship/main/docs/images/report.png)
 
-`certain` 表示静态证据充分，`likely` 需人工审阅；测试和示例中的结果降为 `likely`。默认仅展示 `certain`，`--all` 显示全部。置信度仅反映静态证据，不代表凭据有效或风险已在运行时验证。
+离线 HTML 报告支持筛选和复制修复提示；`--fix-prompt` 在终端输出同样的说明。报告包含文件路径，也可能包含源码摘录：`--no-excerpts` 去除摘录，`--share-summary` 仅输出计数。可下载[合成示例报告](https://github.com/Tasomei/canship/blob/main/docs/demo.html)查看。
 
 | 退出码 | 含义 |
 |---|---|
-| `0` | 无结果，且扫描完整或由 `--best-effort` 接受 |
+| `0` | 无结果，且覆盖完整（或经 `--best-effort` 接受不完整覆盖） |
 | `1` | 至少一条 `certain` 的 P0/P1 结果 |
-| `2` | 其他结果，包括隐藏的 `likely` |
-| `3` | 参数错误、工具错误或未被接受的不完整扫描 |
-
-退出码基于规则筛选、忽略注释和基线处理后的结果。有结果时优先于扫描不完整；`--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 格式不受行号移动影响，但凭据变化会重新报告。
+| `2` | 其他结果，包括被隐藏的 `likely` |
+| `3` | 输入无效、工具错误或覆盖不完整 |
 
-默认路径相对扫描目录，显式路径相对工作目录；读取与写入互斥。缺失、无效或 v1 基线退出 `3`。写入成功退出 `0`，不完整或选择性扫描会提示。
-
-## GitHub Action
+## 接入 CI
 
 保存为 `.github/workflows/canship.yml`：
 
@@ -125,78 +82,38 @@ jobs:
         with:
           fetch-depth: 0
           persist-credentials: false
-      - uses: Tasomei/canship@7465c9560b8b3692777af080e8cc67b4be2335d7
+      - uses: Tasomei/canship@8ae4d5f4508fbd68fc2cf440e138c1217064a0e0
         with:
-          version: '0.7.1'
+          version: '0.8.0'
           honor-ignore-markers: false
 ```
 
-提交哈希固定 Action 实现，`version` 指定 npm 扫描器版本，不使用开发分支源码。Action 使用 Node.js 22，不安装或运行项目依赖，仅输出统计摘要。
+提交哈希固定 Action 实现，`version` 固定 npm 扫描器版本。Action 不安装项目依赖，只输出计数摘要；扫描不完整或工具出错时始终失败。SARIF 上传需显式开启。
 
-| 输入 | 默认值 | 含义 |
+| 输入 | 固定 Action 的默认值 | 含义 |
 |---|---|---|
-| `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`。
-
-## API 与结构化输出
-
-```js
-import { scan, summarize } from 'canship'
-
-const result = await scan('./my-app', { noExcerpts: true })
-console.log(summarize(result))
-```
-
-`scan()` 返回全部置信度结果，支持 `only`、`skip`、`honorIgnoreMarkers`（默认 `true`）、`noExcerpts`（默认 `false`）。不加载配置、不应用基线、不写报告、不设置进程退出码；无效参数抛出异常。`listRules()` 返回规则目录。
-
-JSON 使用 [schemaVersion 1](./schemas/scan-report-v1.schema.json)。须独立于退出码检查 `partial`、`errors`、`skipped`、`filesScanned`。SARIF 包含证据位置和执行诊断。
-
-## 隐私与限制
-
-- 静态检查可能误报或漏报，不验证业务授权、限流、依赖漏洞或线上配置。
-- 脱敏仅覆盖已识别格式，未知敏感值可能保留在摘录中；`--no-excerpts` 可移除摘录。路径、名称和基线描述仍可见。
-- Google/Firebase/Maps 的 `AIza…` 密钥按公开标识符处理，不单凭其值判定泄露。Supabase 检查依据本地迁移及支持的存储桶配置。
-- 评估快照获取和可选的 SARIF 上传可能联网。
-- 不跟随符号链接；嵌套仓库与子模块需单独扫描。范围内跳过项及分析超限标记扫描不完整；鉴权辅助函数解析超限不会隐藏结果，改为在受影响的结果上注明。默认排除的依赖和构建目录不计为扫描缺口。
+| `version` | `0.8.0` | 精确的 npm 扫描器版本；请如上例显式设置 |
+| `fail-on` | `blocking` | `blocking`：`certain` 的 P0/P1；`any`：全部结果；`none`：仅报告 |
 
-| 项目 | 上限 |
-|---|---|
-| 文件读取 | 单文件 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 步，截断时提示。
+完整说明见 [Action 输入](https://github.com/Tasomei/canship/blob/main/action.yml)。
 
-## 开发
+## 扫描之外
 
-```powershell
-npm ci
-```
+- **基线**：接受已审阅的结果，可附理由和到期时间，见[基线管理](./docs/reference-zh-CN.md#配置)。
+- **报告比较**：比较两份已保存的 JSON 报告，列出新增、持续存在和不再出现的结果，见[命令参考](./docs/reference-zh-CN.md#命令行)。
+- **工作区与配置**：独立扫描 monorepo 子项目、排除路径，并用 `--explain-config` 或 `--doctor` 查看生效设置。
+- **模板**：用 `--init` 预览 CI 与 pre-commit 配置。pre-commit 钩子扫描工作区，而非暂存区快照。
+- **部署校验**：`--probe=https://…` 预览少量无认证的 HTTPS 请求，确认计划前不会发出任何请求。使用前请阅读[范围与隐私说明](./docs/reference-zh-CN.md#部署校验)。
+- **API 与编辑器**：[编程接口](./docs/reference-zh-CN.md#api-与结构化输出)及 [VS Code 插件预览版](https://github.com/Tasomei/canship/tree/main/extensions/vscode#readme)。
 
-```powershell
-npm run prepublishOnly
-```
+## 限制
 
-```powershell
-npm run test:package
-```
-
-```powershell
-npm run evaluate
-```
+- 静态分析可能漏报或误报有意为之的配置，不评估业务授权、限流或依赖漏洞。
+- 脱敏仅覆盖已识别的密钥格式。详细报告和基线应作为内部资料处理。
+- Google 与 Firebase 的 `AIza…` 密钥属于公开标识符，不单独作为泄露报告。
 
-新增规则需包含应检出和不应检出的 [夹具](./test/fixtures/)。固定项目评估见 [清单](./test/evaluation/projects.json)、[获取脚本](./scripts/fetch-evaluation-projects.mjs)、[评估器](./scripts/evaluate-projects.ts)。样本通过不代表真实检出率。
+详见[隐私与覆盖限制](./docs/reference-zh-CN.md#隐私与限制)。
 
-## 许可
+## 开发与许可
 
-[MIT](./LICENSE)。Supabase/Firebase 夹具保留 Apache-2.0，Next.js/`cors` 夹具保留 MIT。
+见[开发参考](./docs/reference-zh-CN.md#开发)。采用 [MIT](./LICENSE) 许可；Supabase 与 Firebase 测试夹具保留 Apache-2.0，Next.js 与 `cors` 夹具保留 MIT。

package/README.md

@@ -1,114 +1,71 @@
 # 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.
+Pre-deployment security checks for JavaScript and TypeScript web applications. Canship finds exposed credentials, missing access controls and unsafe handling of request input in your source code, and can optionally probe a deployment you own.
 
-[简体中文](./README-zh-CN.md)
+Static scans run locally: they are read-only, execute no project code and make no network requests. Deployment probes are a separate, opt-in mode that contacts only a target you confirm.
 
-> Documentation for `0.7.1`. Check the installed version with `npx canship --version`.
+[简体中文](./README-zh-CN.md) · [Reference](./docs/reference.md) · [Releases](https://github.com/Tasomei/canship/releases) · [npm](https://www.npmjs.com/package/canship)
+
+> Documentation for `0.8.0` on npm `latest`. Other versions are listed under [Releases](https://github.com/Tasomei/canship/releases).
 
 ## Quick start
 
+Requires Node.js 18 or later; no runtime dependencies.
+
 ```powershell
-npx canship
+npx canship@0.8.0
 ```
 
-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.
+Scan a specific directory:
+
+```powershell
+npx canship@0.8.0 "./my-app"
+```
 
-Output examples use sample data from a pre-release development build.
+Example output for a synthetic project:
 
 ![Terminal report](https://raw.githubusercontent.com/Tasomei/canship/main/docs/images/terminal.png)
 
 ## Checks
 
-| Category | Severity | Scope |
+| Category | Severity | Covers |
 |---|:---:|---|
-| 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 secrets, secrets in public environment variables, Supabase service keys, `.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 |
-| 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 |
-
-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.
+| Database rules | `P1/P2` | Missing Supabase RLS, permissive policies, public storage listing, open Firebase rules |
+| CORS | `P1/P2` | Reflected or wildcard origins combined with credentials |
+| Code | `P1/P2` | SQL and shell commands built from request input; server-side requests and redirects to caller-chosen URLs |
 
-### Server entry points
+Route analysis covers documented entry points in Next.js, SvelteKit, Nuxt, Remix / React Router, Astro, Express, Hono and Fastify. See [entry points and limits](./docs/reference.md#server-entry-points).
 
-| 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 |
-
-Recognised Next.js/Astro middleware may suppress covered auth findings; Server Functions need local checks. Express/Hono/Fastify require resolved rejection logic or known auth libraries. Fastify decorator and plugin evidence is scoped to the local instance.
-
-Session checks and webhook verification (Stripe, Polar, Clerk, Svix, QStash) must reject failures; asynchronous calls must be awaited or returned. Indirect evidence from project helpers/wrappers, SvelteKit hooks, or Nuxt middleware may lower confidence. Unresolved auth sources do not suppress findings.
+```powershell
+npx canship@0.8.0 --list-rules
+```
 
-Input analysis follows assignments, destructuring, string construction, and resolvable cross-file passthrough helpers. Helper names alone do not prove sanitisation.
+## Reviewing findings
 
-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.
+Each finding is rated `certain` (strong static evidence) or `likely` (needs review); only `certain` findings are shown by default. Neither rating proves that a credential is valid or that an issue is exploitable.
 
-## Results
+```powershell
+npx canship@0.8.0 --all --verbose
+```
 
-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 --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.
+The offline HTML report supports filtering and copyable repair prompts; `--fix-prompt` prints the same instructions in the terminal. Reports include file paths and may include source excerpts: use `--no-excerpts` to omit excerpts, or `--share-summary` for counts only. A [synthetic sample report](https://github.com/Tasomei/canship/blob/main/docs/demo.html) is available for download.
 
-| Exit | Meaning |
+| Exit code | Meaning |
 |---|---|
-| `0` | No findings; coverage complete or accepted with `--best-effort` |
+| `0` | No findings, with complete coverage (or incomplete coverage accepted via `--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 |
-
-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.
+| `2` | Other findings, including hidden `likely` findings |
+| `3` | Invalid input, tool error, or incomplete coverage |
 
-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.
-
-## GitHub Action
+## Continuous integration
 
 Save as `.github/workflows/canship.yml`:
 
@@ -125,78 +82,38 @@ jobs:
         with:
           fetch-depth: 0
           persist-credentials: false
-      - uses: Tasomei/canship@7465c9560b8b3692777af080e8cc67b4be2335d7
+      - uses: Tasomei/canship@8ae4d5f4508fbd68fc2cf440e138c1217064a0e0
         with:
-          version: '0.7.1'
+          version: '0.8.0'
           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 commit hash pins the Action and `version` pins the npm scanner. The Action does not install project dependencies and writes a counts-only job summary; it always fails on incomplete scans or tool errors. SARIF upload is opt-in.
 
-| Input | Default | Meaning |
+| Input | Default in the pinned Action | Meaning |
 |---|---|---|
-| `version` | `0.7.0` | Exact npm scanner version |
-| `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
-
-- 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.
+| `version` | `0.8.0` | Exact npm scanner version; set explicitly as above |
+| `fail-on` | `blocking` | `blocking`: `certain` P0/P1; `any`: all findings; `none`: report only |
 
-| 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 |
-
-Evidence traces are capped at 24 steps and disclose truncation.
+See all [Action inputs](https://github.com/Tasomei/canship/blob/main/action.yml).
 
-## Development
+## Beyond scanning
 
-```powershell
-npm ci
-```
+- **Baselines**: accept reviewed findings with an optional reason and expiry date. See [baseline management](./docs/reference.md#configuration).
+- **Report comparison**: compare two saved JSON reports to list added, persisting and no-longer-observed findings. See the [CLI reference](./docs/reference.md#cli).
+- **Workspaces and configuration**: scan monorepo packages independently, exclude paths, and inspect effective settings with `--explain-config` or `--doctor`.
+- **Templates**: preview CI and pre-commit setups with `--init`. The pre-commit hook scans the working tree, not the staged snapshot.
+- **Deployment probes**: `--probe=https://…` previews a small set of unauthenticated HTTPS requests; nothing is sent until you confirm the plan. Review the [scope and privacy notes](./docs/reference.md#deployment-probes) first.
+- **API and editor**: a [programmatic API](./docs/reference.md#api-and-structured-output) and a [VS Code extension preview](https://github.com/Tasomei/canship/tree/main/extensions/vscode#readme).
 
-```powershell
-npm run prepublishOnly
-```
+## Limitations
 
-```powershell
-npm run test:package
-```
-
-```powershell
-npm run evaluate
-```
+- Static analysis can miss issues or flag intentional configurations. It does not assess business authorisation, rate limiting or dependency vulnerabilities.
+- Redaction covers recognised secret formats only. Treat detailed reports and baselines as internal material.
+- Google and Firebase `AIza…` keys are public identifiers and are not reported as leaks on their own.
 
-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.
+See [privacy and coverage limits](./docs/reference.md#privacy-and-limits).
 
-## License
+## Development and license
 
-[MIT](./LICENSE). Supabase/Firebase fixtures retain Apache-2.0; Next.js/`cors` fixtures retain MIT.
+See the [development reference](./docs/reference.md#development). Licensed under [MIT](./LICENSE); Supabase and Firebase test fixtures retain Apache-2.0, and Next.js and `cors` fixtures retain MIT.