shuymn/exportsurf
GitHub: shuymn/exportsurf
exportsurf 扫描 Go 模块中导出但无外部引用的符号，辅助开发者进行 API 表面审查与冗余导出清理。
Stars: 0 | Forks: 0
# exportsurf
`exportsurf` 会扫描 Go module，并报告没有外部引用的导出符号。每个候选项都包含引用计数和置信度标注，供 API surface 审查使用。
## 安装
```
go install github.com/shuymn/exportsurf@latest
```
## 用法
```
exportsurf ./... # text output (default)
exportsurf ./... --json # JSON output
exportsurf ./... --sarif # SARIF v2.1.0 output
exportsurf ./... --baseline baseline.json # filter accepted symbols
exportsurf ./... --fail-on-findings # exit non-zero on candidates (CI)
```
`--sarif` 和 `--json` 互斥。
## Baseline
`--baseline` 会过滤掉已知的未使用导出。`--json` 的输出可以直接用作 baseline 文件。
```
exportsurf ./... --json > baseline.json
exportsurf ./... --baseline baseline.json # exclude symbols listed in baseline
```
## 配置
配置会按以下顺序从工作目录中自动发现：`.exportsurf.yaml`、`.exportsurf.yml`、`exportsurf.yaml`、`exportsurf.yml`。使用 `--config ` 指定显式路径（覆盖自动发现）。
```
# 针对 packages 和 symbols 的 Exact-match filters。
exclude:
packages:
- github.com/your/module/cmd/tool
symbols:
- github.com/your/module/pkg.FuncName
- github.com/your/module/pkg.Type.Method
rules:
# Which symbol kinds to scan. All default to true.
include_funcs: true
include_types: true
include_vars: true
include_consts: true
include_methods: true
include_fields: true
# Count external _test.go references as external uses. CLI flag --treat-tests-as-external is an additive override.
treat_tests_as_external: false
# Which patterns trigger low confidence. All default to true.
# Set to false to keep matching candidates as high confidence.
mark_low_confidence:
package_main: true
package_under_cmd: true
generated_file: true
reflect_usage: true
plugin_usage: true
cgo_export: true
linkname: true
interface_satisfaction: true
embedded_field: true
serialization_tag: true
```
## 输出
默认输出为 go vet 风格的文本：
```
lib/lib.go:3: Candidate (type)
lib/lib.go:7: ExportedConst (const)
```
`--json` 会输出一个候选对象数组：
```
[
{
// symbol: fully qualified symbol name
"symbol": "github.com/your/module/lib.Candidate",
// kind: func, type, var, const, method, field
"kind": "type",
// src: source file and line
"src": "lib/lib.go:3",
// internal_ref_count: references within the defining package
"internal_ref_count": 4,
// confidence: high or low
"confidence": "high",
// reasons: why confidence was downgraded (e.g. package_main, reflect_usage)
"reasons": []
}
]
```
`--sarif` 会输出 SARIF v2.1.0 JSON。高置信度的候选项映射为 `level: "warning"`，低置信度映射为 `level: "note"`。
## 已知限制
- 可能会遗漏 Build tags、`GOOS` 和 `GOARCH` 相关的引用。扫描器会使用默认的 build 约束来加载 package。
## 开发
使用 [Task](https://taskfile.dev) 作为开发接口：
```
task check # lint + build + test (primary gate)
task test # tests with race detection
task lint # golangci-lint
task fmt # format
task build # build binary
```
Git hooks：`lefthook install`
标签：API审查, EVTX分析, Go, Ruby工具, SOC Prime, 云安全监控, 开发工具, 日志审计, 死代码检测, 静态分析