canship 0.3.1 → 0.4.0

package/README-zh-CN.md

@@ -2,15 +2,17 @@
 
 面向 JavaScript / TypeScript 项目的本地静态扫描器，检测凭据暴露与访问控制配置错误。扫描不执行项目代码、不上传文件、不联网。
 
-本文档对应 0.3.x，适用于匹配的 [npm 版本](https://www.npmjs.com/package/canship) 或本地构建。
+[English](./README.md)
+
+## 快速开始
 
 ```powershell
 npx canship .
 ```
 
-要求 Node.js ≥18，无运行时依赖。`npx` 可能联网下载软件包；扫描仅使用本地文件与 Git 历史。Git 仓库中无法调用 Git 时，扫描标记为未完成。
+要求 Node.js ≥18，无运行时依赖。安装软件包可能联网；Git 检查仅使用本地历史。仓库中无法调用 Git 时，扫描标记为未完成。
 
-[English](./README.md)
+> 本文对应 0.4.0，较早的 [npm 版本](https://www.npmjs.com/package/canship) 可能不包含下述全部功能。
 
 ## 检测范围
 
@@ -18,64 +20,108 @@ npx canship .
 |---|---|
 | 硬编码凭据、私钥及含密码的数据库连接串 | P0 |
 | 公开环境变量中的私密值 | P0 |
-| Supabase 管理员密钥暴露至客户端 | P0 |
+| 源码或公开环境变量中的 Supabase 管理员凭据 | P0 |
 | Git 跟踪及历史 `.env` 文件中的凭据或疑似私密值 | P0 |
-| Supabase 迁移记录中未启用行级安全（RLS）的表 | P1 |
-| Firebase 无条件访问及固定日期测试规则 | P1 |
-| Next.js API 数据操作未识别到鉴权 | P0 / P1 |
+| Supabase 迁移中未启用行级安全（RLS）的表 | P1 |
+| Supabase 条件恒为真的 RLS 策略 | P1 |
+| 内容可被列举的 Supabase 公开存储桶 | P2 |
+| Firebase 无条件访问及固定日期测试规则（Firestore、Storage、Realtime Database） | P1 |
+| 服务端数据操作未识别到鉴权 | P0 / P1 |
 | 携带凭据的 CORS 来源回显或通配符配置 | P1 / P2 |
 
-支持 OpenAI、Anthropic、AWS、Stripe、GitHub、npm、Slack、SendGrid 等凭据格式及常见前端公开环境变量前缀。API 鉴权检查仅覆盖 Next.js `/api`，支持 App Router、Pages Router、路由组和工作区应用。
+识别 OpenAI、Anthropic、AWS、Stripe、GitHub、npm 等凭据格式及常见前端公开环境变量前缀。规则 ID、范围与限制见 `--list-rules`。
+
+### 鉴权检查范围
+
+| 框架 | 检查入口 |
+|---|---|
+| Next.js | `app/` 下的 route 处理函数、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` 中的端点 |
+
+支持路由组和工作区应用，不检查 SvelteKit 页面 load 与 remote function。已识别的 Next.js、Astro 中间件鉴权可抑制覆盖路由的结果；Server Function 需在函数内鉴权。SvelteKit hooks、Nuxt 中间件及本地鉴权函数可降低置信度，但不抑制结果。
+
+Supabase 检查重放本地迁移并读取支持的存储桶配置，不检查仅在控制台修改的配置或省略子句隐含的策略条件。
 
-置信度分为确定（`certain`）和疑似（`likely`），仅描述静态证据，不验证凭据有效性或线上状态。默认只展示确定结果；隐藏的疑似结果仍影响退出码。
+### 置信度与证据
 
-## 用法
+`certain`（确定）与 `likely`（疑似）描述静态证据，不验证凭据有效性或线上状态。默认仅展示 `certain`；隐藏的 `likely` 仍影响退出码。
 
-省略路径时扫描当前目录。
+管理员客户端相关结果附带数据操作、导入和客户端构造位置。支持限定语法内的 Supabase 构造器别名、本地鉴权导入、重导出及返回函数的封装。鉴权解析最多 8 跳，证据链最多 24 步，截断时提示。间接鉴权证据仅降低置信度；导入关系不证明运行时数据流。
 
-| 参数 | 说明 |
+## 命令行
+
+省略路径时扫描当前目录。报告正文为英文。
+
+| 参数 | 作用 |
 |---|---|
-| `-a`, `--all` | 展示疑似结果 |
+| `-a`, `--all` | 所有格式包含 `likely` 结果 |
 | `--json` | 输出 JSON |
 | `--fix-prompt` | 输出修复指令及独立的人工操作清单 |
 | `--report[=file]` | 写入 HTML，默认 `canship-report.html` |
 | `--sarif[=file]` | 写入 SARIF 2.1.0，默认 `canship.sarif` |
-| `--best-effort` | 无结果时，允许不完整扫描退出 `0` |
-| `--baseline[=file]` | 应用基线，默认 `canship-baseline.json` |
-| `--baseline-write[=file]` | 写入当前结果为基线后退出，同上默认路径 |
-| `--only=ids` | 仅执行匹配规则，支持逗号分隔及重复参数 |
-| `--skip=ids` | 排除匹配规则，支持逗号分隔及重复参数 |
+| `--no-excerpts` | 省略源码摘录，不改变结果和退出码 |
+| `--changed-since=ref` | 按变更文件筛选报告，不改变扫描范围和退出码 |
+| `--only=ids` / `--skip=ids` | 选择或排除规则，支持逗号分隔及重复参数 |
+| `--list-rules` | 列出规则，不扫描；支持 `--json` |
+| `--baseline[=file]` | 抑制基线结果，默认 `canship-baseline.json` |
+| `--baseline-write[=file]` | 记录结果后退出，默认路径同上 |
 | `--no-config` | 忽略项目配置 |
-| `--no-ignore-markers` | 不遵从被扫描源码中的忽略标记 |
-| `--list-rules` | 列出规则及限制，不扫描；支持 `--json` |
-| `--no-excerpts` | 所有报告省略源码摘录，不改变结果和退出码 |
-| `-h`, `--help` | 显示帮助 |
-| `-v`, `--version` | 显示版本 |
+| `--no-ignore-markers` | 不遵从源码忽略标记 |
+| `--best-effort` | 无结果时，允许不完整扫描退出 `0` |
+| `-h`, `--help` / `-v`, `--version` | 显示帮助或版本 |
 
-`--json` 与 `--fix-prompt` 互斥；HTML、SARIF 可与任一模式组合。报告正文为英文，`--all` 对所有格式生效。
+`--json` 与 `--fix-prompt` 互斥；HTML、SARIF 可与任一模式组合。
 
 ### 退出码
 
 | 退出码 | 含义 |
 |---|---|
-| `0` | 无结果，且扫描完整或由 `--best-effort` 接受不完整扫描 |
+| `0` | 无结果；扫描完整，或由 `--best-effort` 接受不完整状态 |
 | `1` | 存在 `certain` 的 P0/P1 结果 |
-| `2` | 存在其他结果，包括被隐藏的 `likely` |
+| `2` | 存在其他结果，包括隐藏的 `likely` |
 | `3` | 参数或工具错误，或未被接受的不完整扫描 |
 
-结果退出码优先于不完整状态；`--best-effort` 不改变 `1` 或 `2`。
+统计以规则筛选、忽略标记和基线处理后的结果为准。结果退出码优先于不完整状态；`--best-effort` 不改变 `1` 或 `2`。
 
-### 机器可读输出
+### 变更文件视图
 
-JSON 使用独立于包版本的 `schemaVersion: 1`，npm 包附带 [结构定义](./schemas/scan-report-v1.schema.json)。调用方应兼容新增字段、拒绝不支持的结构版本；`--list-rules --json` 为独立的 `kind: "rule-catalog"` 文档。
+`--changed-since=origin/main` 比较本地共同祖先与工作区，包含未被 Git 忽略的新文件，不拉取远程。仍扫描全项目，仅展示主位置或证据位置发生变更的结果；仓库级结果及证据链截断的结果保留。
 
-`findings` 为抑制和筛选后的结果；`hiddenLikely`、`baselineSuppressed`、`baselineStale` 提供相关统计。完整性需另查 `partial`、`errors`、`skipped`、`filesScanned`；SARIF 提供执行状态与诊断通知。
+隐藏结果仍影响退出码：此功能用于审阅，不是“仅新增问题阻断 CI”的策略。缺少 Git、引用或共同历史时退出 `3`，`--best-effort` 不豁免。不能与 `--baseline-write` 组合。
 
-## GitHub Action
+### 结构化报告
+
+JSON 使用 `schemaVersion: 1`，包内附带 [结构定义](./schemas/scan-report-v1.schema.json)。调用方应兼容新增字段，拒绝不支持的结构版本。
+
+- `findings`：抑制及展示筛选后的结果。
+- `hiddenLikely`、`baselineSuppressed`、`baselineStale`：筛选与基线统计。
+- `partial`、`errors`、`skipped`、`filesScanned`：扫描完整性，须独立于退出码检查。
+- `changeView`：启用变更视图时的筛选统计及全量扫描统计。
 
-保存为 `.github/workflows/canship.yml`，在推送和 PR 时扫描并生成统计摘要。安装扫描器需要联网，扫描不联网；不安装或执行项目依赖，默认不上传 SARIF。
+SARIF 包含执行诊断与证据关联位置。`--list-rules --json` 返回独立的 `kind: "rule-catalog"` 文档。
 
-示例固定 Action 提交，显式安装 npm 版 `0.3.0`；`version` 不使用仓库中的未发布源码。Action 兼容 0.2.1 无 `schemaVersion` 的报告。
+## 程序化 API
+
+提供 Node.js ESM 入口及 TypeScript 类型：
+
+```js
+import { scan, summarize, listRules } from 'canship'
+
+const result = await scan('./my-app', { noExcerpts: true })
+console.log(summarize(result))
+console.log(listRules())
+```
+
+`scan()` 返回全部置信度结果，支持 `only`、`skip`、`honorIgnoreMarkers`（默认 `true`）、`noExcerpts`（默认 `false`）。不读取项目配置、不应用基线、不写报告、不设置进程退出码。无效参数或根目录抛出异常；扫描缺口保留在结果中。
+
+`summarize()` 返回结果数、阻断数、疑似数、`partial` 及默认 CLI 退出码。`listRules()` 返回独立的规则目录副本。
+
+## GitHub Action
+
+保存为 `.github/workflows/canship.yml`。Action 安装指定 npm 版本，扫描检出目录并生成统计摘要；不安装或执行项目依赖，SARIF 需显式启用上传。
 
 ```yaml
 name: canship
@@ -90,25 +136,27 @@ jobs:
         with:
           fetch-depth: 0
           persist-credentials: false
-      - uses: Tasomei/canship@8b1a3aa88c77e92e2806b343af6003372855bc70
+      - uses: Tasomei/canship@b4cbbfe6b5c4c88164b9388d121f7651032259a4
         with:
-          version: '0.3.0'
+          version: '0.4.0'
 ```
 
+提交号固定 Action 实现；`version` 选择 npm 扫描器，不使用仓库源码。该固定提交默认安装 0.3.2；示例显式选择 0.4.0。
+
 | 输入 | 默认值 | 说明 |
 |---|---|---|
 | `path` | `.` | 检出目录内的扫描路径 |
-| `version` | `0.3.0` | 精确 npm 版本，不接受范围或标签 |
-| `fail-on` | `blocking` | `blocking`：确定的 P0/P1；`any`：全部结果；`none`：仅报告结果 |
-| `only` / `skip` | 未设置 | 互斥，逗号分隔的规则选择器 |
+| `version` | `0.3.2` | 精确 npm 版本，不接受范围或标签 |
+| `fail-on` | `blocking` | `blocking`：确定的 P0/P1；`any`：全部结果；`none`：仅报告 |
+| `only` / `skip` | 未设置 | 互斥的规则选择器 |
 | `baseline` | 未设置 | 相对扫描目录的已有基线 |
 | `use-config` | `false` | 启用项目配置 |
-| `upload-sarif` | `false` | 上传 SARIF 至 GitHub 代码扫描 |
-| `category` | `canship` | 每个扫描目标使用独立分类 |
+| `upload-sarif` | `false` | 上传至 GitHub 代码扫描 |
+| `category` | `canship` | 扫描目标的 SARIF 分类 |
 
-输出：`exit-code`、`findings`、`blocking`、`partial`。策略统计包含疑似结果，基线与忽略仍生效；扫描不完整、工具错误或报告不兼容始终失败，包括 `fail-on: none`。
+输出：`exit-code`、`findings`、`blocking`、`partial`。统计包含基线与排除处理后的疑似结果。扫描不完整、工具错误或报告不兼容始终失败，`fail-on: none` 也不例外。
 
-上传 SARIF 需 `security-events: write` 及 [GitHub 代码扫描支持](https://docs.github.com/en/code-security/how-tos/find-and-fix-code-vulnerabilities/integrate-with-existing-tools/upload-sarif-file)，Fork PR 可能无权限。上传前审阅报告中的路径与详情；不可信 PR 使用 `pull_request`，不要使用 `pull_request_target`。Action 为后续步骤设置 Node.js 22，需要其他版本时应使用独立扫描任务。
+上传 SARIF 需 `security-events: write` 及 [代码扫描支持](https://docs.github.com/en/code-security/how-tos/find-and-fix-code-vulnerabilities/integrate-with-existing-tools/upload-sarif-file)，Fork PR 可能权限不足。上传前需审阅报告。不可信 PR 使用 `pull_request`，不要使用 `pull_request_target`。Action 为后续步骤设置 Node.js 22；需要其他版本时使用独立扫描任务。
 
 ## 配置与基线
 
@@ -121,18 +169,18 @@ jobs:
 }
 ```
 
-命令行参数优先；`only`、`skip` 互斥，接受规则 ID 或命名空间。未选规则不执行，`ruleSelection.removed` 仅统计已执行规则中被过滤的结果。扫描不可信项目时同时使用 `--no-config --no-ignore-markers`，二者均由被扫描项目控制；`bestEffort` 仅限命令行设置。
+命令行参数优先。`only`、`skip` 互斥，接受规则 ID 或命名空间。`--best-effort` 仅限命令行。扫描不可信项目时使用 `--no-config --no-ignore-markers`。
 
 ### 忽略标记
 
-独占注释行的 `canship-ignore-file` 排除整个文件；`canship-ignore-next-line` 忽略下一行，可附规则 ID：
+独占注释行的 `canship-ignore-file` 排除整个文件；`canship-ignore-next-line` 抑制下一行，可限定规则：
 
 ```ts
 // canship-ignore-next-line cors/wildcard-with-credentials
 const corsOptions = { origin: '*', credentials: true }
 ```
 
-报告披露忽略、规则筛选和基线抑制信息；主动排除不标记为未完成。标记可使退出码降为 `0`；`--no-config` 不影响标记，`--no-ignore-markers` 使两种标记均失效。
+报告披露排除与抑制信息。主动排除不标记为未完成，可使退出码降为 `0`。`--no-config` 不禁用标记，`--no-ignore-markers` 才会禁用。
 
 ### 基线
 
@@ -142,29 +190,27 @@ const corsOptions = { origin: '*', credentials: true }
 npx canship --baseline-write
 ```
 
-仅报告新增结果：
+后续扫描抑制这些结果：
 
 ```powershell
 npx canship --baseline
 ```
 
-默认基线位于扫描目录，显式路径相对工作目录。写入成功退出 `0`，不代表无问题；扫描不完整或启用规则筛选时会提示。
+默认路径相对扫描目录，显式路径相对工作目录；读取与写入模式互斥。写入成功退出 `0`，不表示无问题；扫描不完整或启用规则筛选时会提示。
 
-基线格式为 v2，移动行号不改变指纹，替换凭据会改变。缺失、损坏及 v1 基线均退出 `3`。基线不含源码，但包含路径、规则和问题描述，提交前需审阅。
+基线格式为 v2，移动行号不改变指纹，替换凭据会改变。缺失、损坏及 v1 基线均退出 `3`。基线不含源码摘录，但包含路径、规则和问题描述，提交前需审阅。
 
 ## 隐私与限制
 
-- 静态分析可能误报或漏报，不验证线上行为，不覆盖限流、注入、依赖漏洞或业务授权。无结果不等于安全。
-- 脱敏仅覆盖已识别格式，未知秘密可能出现在源码摘录中。`--no-excerpts` 省略摘录，JSON 以 `excerptsOmitted` 标明；路径、名称、说明及基线不匿名化，分享前仍需审阅。
-- Google/Firebase/Maps 的 `AIza...` 值按公开标识符处理，不单凭其值判定泄露。
+- 静态检查可能漏报或将预期配置报为问题，不验证线上行为，不覆盖限流、注入、依赖漏洞或业务授权。无结果不等于安全。
+- 脱敏仅覆盖已识别格式。未识别的敏感值可能保留在摘录中；`--no-excerpts` 移除摘录，并设置 JSON `excerptsOmitted`。路径、名称、说明和基线不匿名化。
+- Google/Firebase/Maps 的 `AIza...` 密钥按公开标识符处理，不单凭其值判定泄露。
 - 读取上限：单文件 2 MiB，单次 128 MiB、10,000 个文件，目录 16 层。每文件跨规则最多 100 条结果，优先保留高严重度、高置信度结果。
-- Git 历史每文件最多 100 个相关版本，单条 Git 命令超时 30 秒。超限、超时均报告检查缺口。
-- 不跟随符号链接；嵌套仓库、子模块需单独扫描。范围内跳过项使扫描未完成，内置排除的构建和依赖目录除外。
+- Git 历史每文件最多 100 个相关版本，单条命令超时 30 秒；Supabase 策略及存储桶语句最多解析 4,000 个字符。超限报告扫描未完成。
+- 不跟随符号链接；嵌套仓库、子模块需单独扫描。范围内跳过项使扫描未完成，内置排除的依赖和构建目录除外。
 
 ## 开发
 
-新增规则需包含应检出与不应检出的 [测试用例](./test/fixtures/)。
-
 ```powershell
 npm ci
 ```
@@ -173,28 +219,30 @@ npm ci
 npm run prepublishOnly
 ```
 
-离线评估：
+```powershell
+npm run test:package
+```
+
+新增规则需包含应检出与不应检出的 [夹具](./test/fixtures/)。运行离线 [评估集](./test/fixtures/evaluation/)：
 
 ```powershell
 npm run evaluate
 ```
 
-评估集含 10 个构造用例、9 个固定版本上游示例及变体，同时纳入 `npm test`；[来源与许可](./test/fixtures/evaluation/) 随样本保存。断言覆盖规则、文件、严重度、置信度与扫描完整性，不代表真实项目检出率。
-
-另有 5 个 [应用目录快照](./test/evaluation/projects.json)。准备阶段联网并校验 Git 对象摘要，目标须为 Git 仓库外的新目录：
+[应用快照](./test/evaluation/projects.json) 需先联网获取并校验来源，目标为 Git 仓库外的新目录：
 
 ```powershell
 node scripts/fetch-evaluation-projects.mjs "$env:TEMP/canship-evaluation"
 ```
 
-随后离线评估，不安装或运行样本依赖：
+随后离线评估：
 
 ```powershell
 npm run evaluate:projects -- "$env:TEMP/canship-evaluation"
 ```
 
-CI 使用同一评估集，不验证 Git 历史或线上行为。
+项目评估使用临时副本，比较原项目及开放、受限测试变体的全部结果，不安装或运行样本依赖。这些测试不衡量真实项目检出率、Git 历史覆盖率或线上行为。
 
 ## 许可
 
-[MIT](./LICENSE)。Supabase、Firebase 样本保留 Apache-2.0，Next.js、`cors` 样本保留 MIT；各样本附来源及许可证。
+[MIT](./LICENSE)。Supabase、Firebase 夹具保留 Apache-2.0，Next.js、`cors` 夹具保留 MIT；来源与许可证随夹具保存。

package/README.md

@@ -1,16 +1,18 @@
 # canship
 
-A local static scanner for JavaScript and TypeScript projects. Detects exposed credentials and access-control misconfigurations. Scans do not execute project code, upload files, or use the network.
+A local static scanner for JavaScript and TypeScript projects. Detects exposed credentials and access-control misconfigurations without executing project code, uploading files, or making network requests.
 
-This documentation covers 0.3.x: use a matching [npm version](https://www.npmjs.com/package/canship) or local build.
+[简体中文](./README-zh-CN.md)
+
+## Quick start
 
 ```powershell
 npx canship .
 ```
 
-Requires Node.js ≥18; no runtime dependencies. `npx` may download the package; scans use only local files and Git history. Unavailable Git in a repository marks the scan incomplete.
+Requires Node.js ≥18; no runtime dependencies. Package installation may use the network. Git checks use local history only; unavailable Git in a repository marks the scan incomplete.
 
-[简体中文](./README-zh-CN.md)
+> Documentation for 0.4.0. Earlier [npm versions](https://www.npmjs.com/package/canship) may not include all features below.
 
 ## Checks
 
@@ -18,64 +20,108 @@ Requires Node.js ≥18; no runtime dependencies. `npx` may download the package;
 |---|---|
 | Hardcoded credentials, private keys, and database URLs containing passwords | P0 |
 | Private values in public environment variables | P0 |
-| Supabase admin keys exposed to clients | P0 |
+| Supabase admin credentials in source or public environment variables | P0 |
 | Credentials or suspected private values in Git-tracked and historical `.env` files | P0 |
 | Supabase tables without Row Level Security (RLS) in migrations | P1 |
-| Firebase unconditional access and date-based test rules | P1 |
-| Next.js API data operations without recognised authentication | P0 / P1 |
+| Supabase RLS policies with always-true conditions | P1 |
+| Public Supabase storage buckets with listable contents | P2 |
+| Firebase unconditional access and date-based test rules (Firestore, Storage, Realtime Database) | P1 |
+| Server-side data operations without recognised authentication | P0 / P1 |
 | Credentialed CORS with reflected or wildcard origins | P1 / P2 |
 
-Supports OpenAI, Anthropic, AWS, Stripe, GitHub, npm, Slack, SendGrid, and other credential formats, plus common frontend public environment prefixes. API authentication checks cover only Next.js `/api`: App Router, Pages Router, route groups, and workspace applications.
+Recognises OpenAI, Anthropic, AWS, Stripe, GitHub, npm, and other credential formats, plus common frontend public environment prefixes. Use `--list-rules` for rule IDs, scope, and limits.
+
+### Authentication coverage
+
+| Framework | Checked entry points |
+|---|---|
+| Next.js | Route handlers under `app/`, Pages Router `/api`, and `'use server'` functions |
+| SvelteKit | `+server` endpoints and `+page.server` form actions |
+| Nuxt | `server/api` and `server/routes` |
+| Remix / React Router | `loader` and `action` exports in `app/routes` |
+| Astro | Endpoints in `src/pages` |
+
+Supports route groups and workspace applications. SvelteKit page loads and remote functions are outside scope. Recognised Next.js and Astro middleware guards may suppress covered route findings; Server Functions require a guard within each function. SvelteKit hooks, Nuxt middleware, and local auth helpers can lower confidence without suppressing findings.
 
-Confidence is `certain` or `likely`, describing static evidence rather than credential validity or deployed state. Only certain findings are shown by default; hidden likely findings still affect the exit code.
+Supabase checks replay local migrations and read supported bucket configuration. Dashboard-only changes and policy conditions implied by missing clauses are not checked.
 
-## Usage
+### Confidence and evidence
 
-Omitting the path scans the current directory.
+`certain` and `likely` describe static evidence, not credential validity or deployed state. Only `certain` findings are shown by default; hidden `likely` findings still affect exit status.
 
-| Option | Description |
+Admin-client findings include operation, import, and client-construction locations. Supabase constructor aliases and local auth imports, re-exports, and function-returning wrappers are recognised within bounded patterns. Auth resolution follows up to eight hops; evidence chains contain at most 24 steps and disclose truncation. Indirect auth evidence retains the finding at lower confidence; import relationships do not prove runtime data flow.
+
+## CLI
+
+Omitting the path scans the current directory. Reports are in English.
+
+| Option | Effect |
 |---|---|
-| `-a`, `--all` | Include likely findings |
+| `-a`, `--all` | Include `likely` findings in every format |
 | `--json` | Output JSON |
-| `--fix-prompt` | Output remediation instructions and separate manual actions |
+| `--fix-prompt` | Output repair instructions and separate manual actions |
 | `--report[=file]` | Write HTML; default: `canship-report.html` |
 | `--sarif[=file]` | Write SARIF 2.1.0; default: `canship.sarif` |
-| `--best-effort` | Permit exit `0` for an incomplete scan with no findings |
-| `--baseline[=file]` | Apply a baseline; default: `canship-baseline.json` |
-| `--baseline-write[=file]` | Write current findings as a baseline and exit; same default path |
-| `--only=ids` | Run matching rules; comma-separated and repeatable |
-| `--skip=ids` | Exclude matching rules; comma-separated and repeatable |
+| `--no-excerpts` | Omit source excerpts; preserve findings and exit status |
+| `--changed-since=ref` | Filter the report by changed files, not the scan or exit status |
+| `--only=ids` / `--skip=ids` | Select or exclude rules; comma-separated and repeatable |
+| `--list-rules` | List rules without scanning; supports `--json` |
+| `--baseline[=file]` | Suppress recorded findings; default: `canship-baseline.json` |
+| `--baseline-write[=file]` | Record findings and exit; same default path |
 | `--no-config` | Ignore project configuration |
-| `--no-ignore-markers` | Disregard ignore markers in scanned source |
-| `--list-rules` | List rules and limits without scanning; supports `--json` |
-| `--no-excerpts` | Omit source excerpts from every report; preserve findings and exit status |
-| `-h`, `--help` | Show help |
-| `-v`, `--version` | Show version |
+| `--no-ignore-markers` | Disregard source ignore markers |
+| `--best-effort` | Allow exit `0` for an incomplete scan with no findings |
+| `-h`, `--help` / `-v`, `--version` | Show help or version |
 
-`--json` and `--fix-prompt` are mutually exclusive; HTML and SARIF work with either. Reports are in English. `--all` applies to every format.
+`--json` and `--fix-prompt` are mutually exclusive; HTML and SARIF can accompany either.
 
 ### Exit codes
 
 | Code | Meaning |
 |---|---|
-| `0` | No findings, with a complete scan or an incomplete scan accepted by `--best-effort` |
-| `1` | At least one certain P0/P1 finding |
-| `2` | Other findings, including hidden likely findings |
-| `3` | Invalid arguments, a tool error, or an unaccepted incomplete scan |
+| `0` | No findings; scan complete or incompleteness accepted by `--best-effort` |
+| `1` | At least one `certain` P0/P1 finding |
+| `2` | Other findings, including hidden `likely` findings |
+| `3` | Invalid arguments, tool error, or unaccepted incomplete scan |
 
-Finding exit codes take precedence over incompleteness; `--best-effort` does not change `1` or `2`.
+Counts apply after rule selection, ignore markers, and baselines. Findings take precedence over incompleteness; `--best-effort` does not change `1` or `2`.
 
-### Machine-readable output
+### Changed-file view
 
-JSON uses `schemaVersion: 1`, independent of the package version; the npm package includes its [schema](./schemas/scan-report-v1.schema.json). Accept additive fields and reject unsupported schema versions. `--list-rules --json` is a separate `kind: "rule-catalog"` document.
+`--changed-since=origin/main` compares the local merge base with the working tree, including non-ignored untracked files. It does not fetch. The whole project is still scanned; findings are shown when their primary or evidence locations changed. Repository-wide findings and truncated evidence are retained.
 
-`findings` contains results after suppressions and filtering; `hiddenLikely`, `baselineSuppressed`, and `baselineStale` provide related counts. Check coverage separately through `partial`, `errors`, `skipped`, and `filesScanned`. SARIF includes execution status and diagnostic notifications.
+Hidden findings still affect exit status: this is a review view, not a “new issues only” CI policy. Missing Git, refs, or merge history exits `3`, even with `--best-effort`. Cannot be combined with `--baseline-write`.
 
-## GitHub Action
+### Structured reports
+
+JSON uses `schemaVersion: 1`; the package includes its [schema](./schemas/scan-report-v1.schema.json). Consumers should accept additive fields and reject unsupported schema versions.
+
+- `findings`: results after suppression and display filtering.
+- `hiddenLikely`, `baselineSuppressed`, `baselineStale`: filtering and baseline counts.
+- `partial`, `errors`, `skipped`, `filesScanned`: scan coverage; check separately from exit status.
+- `changeView`: changed-file filtering counts and full-scan totals, when enabled.
+
+SARIF includes execution diagnostics and related evidence locations. `--list-rules --json` returns a separate `kind: "rule-catalog"` document.
 
-Save as `.github/workflows/canship.yml` to scan on pushes and pull requests, with a counts-only summary. Scanner installation requires network access; scanning does not. Project dependencies are not installed or executed, and SARIF upload is disabled by default.
+## Programmatic API
 
-The example pins the Action commit and explicitly installs npm version `0.3.0`; `version` does not use unreleased repository source. The Action accepts 0.2.1 reports without `schemaVersion`.
+Node.js ESM with TypeScript declarations:
+
+```js
+import { scan, summarize, listRules } from 'canship'
+
+const result = await scan('./my-app', { noExcerpts: true })
+console.log(summarize(result))
+console.log(listRules())
+```
+
+`scan()` returns all confidence levels. Options: `only`, `skip`, `honorIgnoreMarkers` (default `true`), `noExcerpts` (default `false`). It does not load project configuration, apply baselines, write reports, or set the process exit code. Invalid arguments or root directories throw; coverage gaps remain in the result.
+
+`summarize()` returns finding, blocking and likely counts, `partial`, and the default CLI exit code. `listRules()` returns an independent catalog copy.
+
+## GitHub Action
+
+Save as `.github/workflows/canship.yml`. The Action installs an exact npm version, scans the checkout, and produces a counts-only summary. It does not install or execute project dependencies; SARIF upload is opt-in.
 
 ```yaml
 name: canship
@@ -90,29 +136,31 @@ jobs:
         with:
           fetch-depth: 0
           persist-credentials: false
-      - uses: Tasomei/canship@8b1a3aa88c77e92e2806b343af6003372855bc70
+      - uses: Tasomei/canship@b4cbbfe6b5c4c88164b9388d121f7651032259a4
         with:
-          version: '0.3.0'
+          version: '0.4.0'
 ```
 
+The commit pins the Action wrapper; `version` selects the npm scanner, not repository source. The pinned Action defaults to 0.3.2; this example explicitly selects 0.4.0.
+
 | Input | Default | Meaning |
 |---|---|---|
-| `path` | `.` | Directory within the checkout |
-| `version` | `0.3.0` | Exact npm version; no ranges or tags |
-| `fail-on` | `blocking` | `blocking`: certain P0/P1; `any`: all findings; `none`: findings only reported |
-| `only` / `skip` | unset | Mutually exclusive, comma-separated rule selectors |
-| `baseline` | unset | Existing baseline relative to the scanned directory |
+| `path` | `.` | Scan directory within the checkout |
+| `version` | `0.3.2` | Exact npm version; no ranges or tags |
+| `fail-on` | `blocking` | `blocking`: certain P0/P1; `any`: all findings; `none`: report only |
+| `only` / `skip` | unset | Mutually exclusive rule selectors |
+| `baseline` | unset | Existing baseline relative to the scan directory |
 | `use-config` | `false` | Enable project configuration |
-| `upload-sarif` | `false` | Upload SARIF to GitHub code scanning |
-| `category` | `canship` | Distinct SARIF category for each scan target |
+| `upload-sarif` | `false` | Upload to GitHub code scanning |
+| `category` | `canship` | SARIF category for the scan target |
 
-Outputs: `exit-code`, `findings`, `blocking`, `partial`. Policies include likely findings; baselines and exclusions still apply. Incomplete scans, tool errors, and incompatible reports always fail, including with `fail-on: none`.
+Outputs: `exit-code`, `findings`, `blocking`, `partial`. Counts include likely findings after baselines and exclusions. Incomplete scans, tool errors, and incompatible reports always fail, even with `fail-on: none`.
 
-SARIF upload requires `security-events: write` and [GitHub code scanning support](https://docs.github.com/en/code-security/how-tos/find-and-fix-code-vulnerabilities/integrate-with-existing-tools/upload-sarif-file); fork PRs may lack permission. Review paths and finding details before upload. Use `pull_request`, not `pull_request_target`, for untrusted PRs. The Action sets Node.js 22 for subsequent steps; use a separate scan job if another version is needed.
+SARIF upload needs `security-events: write` and [code scanning support](https://docs.github.com/en/code-security/how-tos/find-and-fix-code-vulnerabilities/integrate-with-existing-tools/upload-sarif-file); fork PR permissions may be insufficient. Review reports before upload. Use `pull_request`, not `pull_request_target`, for untrusted PRs. The Action sets Node.js 22 for subsequent steps; isolate the scan job if another version is required.
 
 ## Configuration and baselines
 
-Place `canship.config.json` in the scanned directory. Supported keys: `baseline`, `only`, `skip`, `all`.
+`canship.config.json` in the scan directory accepts `baseline`, `only`, `skip`, and `all`:
 
 ```json
 {
@@ -121,18 +169,18 @@ Place `canship.config.json` in the scanned directory. Supported keys: `baseline`
 }
 ```
 
-CLI options take precedence. `only` and `skip` are mutually exclusive and accept rule IDs or namespaces. Unselected rules do not run; `ruleSelection.removed` counts filtered findings only from executed rules. For untrusted projects use `--no-config --no-ignore-markers`; the scanned project controls both. `bestEffort` is CLI-only.
+CLI options take precedence. `only` and `skip` are mutually exclusive and accept rule IDs or namespaces. `--best-effort` is CLI-only. For untrusted projects, use `--no-config --no-ignore-markers`.
 
 ### Ignore markers
 
-A standalone `canship-ignore-file` comment excludes a file; `canship-ignore-next-line` suppresses the next line, with an optional rule ID:
+A standalone `canship-ignore-file` comment excludes the file. `canship-ignore-next-line` suppresses the next line, optionally for one rule:
 
 ```ts
 // canship-ignore-next-line cors/wildcard-with-credentials
 const corsOptions = { origin: '*', credentials: true }
 ```
 
-Reports disclose exclusions, rule selection, and baseline suppression. Deliberate exclusions do not mark the scan incomplete. Markers can lower the exit code to `0`; `--no-config` does not affect them, `--no-ignore-markers` disables both kinds.
+Reports disclose exclusions and suppressions. Deliberate exclusions do not mark the scan incomplete and can reduce the exit code to `0`. `--no-config` does not disable markers; `--no-ignore-markers` does.
 
 ### Baselines
 
@@ -142,29 +190,27 @@ Record existing findings:
 npx canship --baseline-write
 ```
 
-Report only new findings:
+Suppress them on subsequent scans:
 
 ```powershell
 npx canship --baseline
 ```
 
-The default baseline is in the scanned directory; explicit paths are relative to the working directory. A successful write exits `0`, regardless of findings; incomplete or selectively scanned input produces a warning.
+The default path is relative to the scan directory; explicit paths are relative to the working directory. Read and write modes are mutually exclusive. Successful writes exit `0` regardless of findings; incomplete or selective scans produce a warning.
 
-Baseline format v2 fingerprints survive line moves but change when credentials change. Missing, malformed, and v1 baselines exit `3`. Baselines omit source but retain paths, rules, and issue descriptions; review before committing.
+Format v2 fingerprints survive line moves but change with credentials. Missing, malformed, or v1 baselines exit `3`. Baselines omit source excerpts but retain paths, rules, and issue descriptions; review before committing.
 
-## Privacy and limitations
+## Privacy and limits
 
-- Static analysis may produce false positives or negatives. Deployed behaviour, rate limiting, injection, dependency vulnerabilities, and business authorisation are outside scope. No findings does not prove security.
-- Redaction covers recognised formats only; unknown secrets may appear in source excerpts. `--no-excerpts` omits excerpts, recorded as `excerptsOmitted` in JSON. Paths, names, descriptions, and baselines are not anonymised; review before sharing.
-- Google/Firebase/Maps `AIza...` values are public identifiers, not evidence of a leak on their own.
+- Static checks can miss issues or report intentional configurations. They do not verify deployed behaviour, rate limiting, injection, dependency vulnerabilities, or business authorisation. No findings does not prove security.
+- Redaction covers recognised formats only. Unknown secrets may remain in excerpts; `--no-excerpts` omits excerpts and sets JSON `excerptsOmitted`. Paths, names, descriptions, and baselines are not anonymised.
+- Google/Firebase/Maps `AIza...` keys are treated as public identifiers, not leak evidence on their own.
 - Read limits: 2 MiB per file, 128 MiB and 10,000 files per scan, 16 directory levels. At most 100 findings per file across rules, prioritising severity and confidence.
-- Git history checks cover up to 100 relevant revisions per file, with a 30-second timeout per Git command. Exceeded limits and timeouts report coverage gaps.
-- Symbolic links are not followed; scan nested repositories and submodules separately. Skipped paths within scope mark the scan incomplete; built-in build and dependency exclusions do not.
+- Git history: up to 100 relevant revisions per file; 30-second timeout per Git command. Supabase policy and bucket statements: 4,000-character parse limit. Exceeded limits report incomplete coverage.
+- Symbolic links are not followed; nested repositories and submodules need separate scans. Skipped in-scope paths mark coverage incomplete; built-in dependency and build exclusions do not.
 
 ## Development
 
-New rules require positive and negative [test cases](./test/fixtures/).
-
 ```powershell
 npm ci
 ```
@@ -173,28 +219,30 @@ npm ci
 npm run prepublishOnly
 ```
 
-Offline evaluation:
+```powershell
+npm run test:package
+```
+
+New rules need positive and negative [fixtures](./test/fixtures/). Run the offline [evaluation corpus](./test/fixtures/evaluation/):
 
 ```powershell
 npm run evaluate
 ```
 
-The corpus has 10 synthetic cases and nine pinned upstream examples and mutations, also run by `npm test`. [Sources and licences](./test/fixtures/evaluation/) accompany the fixtures. Assertions cover rules, files, severity, confidence, and coverage, not real-world detection rates.
-
-Five [application-directory snapshots](./test/evaluation/projects.json) provide additional evaluation. Preparation uses the network and verifies Git object hashes; the target must be a new directory outside Git:
+For [application snapshots](./test/evaluation/projects.json), fetch and verify sources into a new directory outside Git:
 
 ```powershell
 node scripts/fetch-evaluation-projects.mjs "$env:TEMP/canship-evaluation"
 ```
 
-Then evaluate offline without installing or running sample dependencies:
+Then evaluate offline:
 
 ```powershell
 npm run evaluate:projects -- "$env:TEMP/canship-evaluation"
 ```
 
-CI uses the same corpus. Git history and deployed behaviour are outside this evaluation.
+Project evaluation compares all findings in original and open/guarded test variants using temporary copies. Sample dependencies are not installed or run. These tests do not measure real-world detection rates, Git-history coverage, or deployed behaviour.
 
 ## License
 
-[MIT](./LICENSE). Supabase and Firebase fixtures retain Apache-2.0; Next.js and `cors` fixtures retain MIT. Each includes its source and licence.
+[MIT](./LICENSE). Supabase and Firebase fixtures retain Apache-2.0; Next.js and `cors` fixtures retain MIT. Sources and licences accompany the fixtures.