## 概述
ngcompass 是一个为 Angular 项目构建的命令行静态分析工具。它读取 TypeScript、Angular 模板、样式和项目配置，而无需运行应用程序，然后报告通用 TypeScript 检查器通常遗漏的问题。
它旨在为希望对 Angular 特定风险有更清晰视图的团队设计：组件架构、渲染性能、SSR 兼容性、Signals 和 RxJS 模式、模板安全性和现代 Angular API 采用。
## 突出特点
| 区域 | ngcompass 帮助找到的内容 |
| ------------ | --------------------------------------------------------------------------------------------- |
| 架构 | 循环依赖、边界违规和脆弱的组件关系 |
| 性能 | 缺少 `OnPush`、昂贵的模板表达式、缺少 `trackBy` 和低效的绑定 |
| SSR | 通用代码中的浏览器仅 API、水合风险和渲染生命周期陷阱 |
| 安全 | 不安全的模板绑定和清理器绕过 |
| 反应性 | RxJS 订阅问题、Signals 使用不当和迁移机会 |
| 代码质量 | 已弃用的模式、专注的测试和现代 Angular API 改进 |
## 安装
全局安装 beta CLI：
```
npm install -g ngcompass@beta
```
或将它添加到项目中：
```
npm install --save-dev ngcompass@beta
```
使用 pnpm：
```
pnpm add -D ngcompass@beta
```
## 快速入门
```
cd my-angular-app
ngcompass init
ngcompass analyze
```
生成一个自包含的视觉报告：
```
ngcompass analyze --format ui
```
运行项目本地安装：
```
npx ngcompass analyze
pnpm exec ngcompass analyze
```
## 输出格式
| 命令 | 输出 |
| ------------------------------------------------------ | ------------------------------ |
| `ngcompass analyze` | 默认终端报告 |
| `ngcompass analyze --format console --compact` | 紧凑的一行问题输出 |
| `ngcompass analyze --format html --output report.html` | 自包含的 HTML 报告 |
| `ngcompass analyze --format ui` | 交互式 HTML 报告别名 |
| `ngcompass analyze --format json > results.json` | 可读性 JSON |
| `ngcompass analyze --format sarif > results.sarif` | GitHub 代码扫描的 SARIF |
## 配置
创建一个配置文件：
```
ngcompass init
```
这将生成 `ngcompass.config.ts`：
```
import { defineConfig } from '@ngcompass/config';
export default defineConfig({
extends: 'ngcompass:recommended',
include: ['src/**/*.ts', 'src/**/*.html'],
exclude: [
'node_modules/**',
'dist/**',
'build/**',
'coverage/**',
'**/*.d.ts',
'**/*.spec.ts',
'**/*.test.ts',
],
profiles: {
ci: {
outputFormat: 'json',
maxWarnings: 0,
},
},
});
```
### 预设
| 预设 | 目的 |
| ----------------------- | ------------------------------------------- |
| `ngcompass:recommended` | 大多数 Angular 项目的平衡默认设置 |
| `ngcompass:strict` | 成熟代码库的更强执行力度 |
| `ngcompass:performance` | 渲染和变更检测检查 |
| `ngcompass:reactivity` | Signals 和 RxJS 正确性 |
| `ngcompass:security` | 以安全为重点的 Angular 检查 |
| `ngcompass:ssr` | 服务器渲染和水合安全性 |
| `ngcompass:all` | 所有内置规则在其默认严重性下 |
在相同的配置中覆盖单个规则：
```
export default defineConfig({
extends: ['ngcompass:recommended', 'ngcompass:performance'],
rules: {
'prefer-on-push-component-change-detection': 'error',
'no-document-access': 'warn',
},
});
```
## 命令
| 命令 | 描述 |
| ------------------------- | ---------------------------- |
| `ngcompass init` | 创建 `ngcompass.config.ts` |
| `ngcompass analyze` | 运行分析 |
| `ngcompass rules` | 列出可用规则 |
| `ngcompass rules
` | 检查一个规则 |
| `ngcompass config health` | 验证配置 |
| `ngcompass cache info` | 显示缓存状态 |
| `ngcompass cache clear` | 清除缓存的分析数据 |
| `ngcompass cache path` | 打印缓存目录 |
### 分析选项
| 选项 | 描述 |
| ------------------------------ | ------------------------------------------------------- |
| `--format ` | `console`, `json`, `sarif`, `html`, 或 `ui` |
| `--output ` | HTML/UI 报告的输出路径 |
| `--compact` | 使用紧凑的问题输出 |
| `-q, --quiet` | 仅显示摘要计数 |
| `--no-recommendation` | 隐藏修复建议 |
| `--rule ` | 独立运行一个规则 |
| `--force` | 忽略缓存的成果 |
| `-p, --profile ` | 运行一个命名的配置配置文件 |
| `--max-workers ` | 限制工作线程 |
| `--skip-type-check` | 跳过需要 TypeScript 类型检查的规则 |
## 持续集成
当分析通过时，ngcompass 以代码 `0` 退出，当找到配置违规时以非零代码退出。
```
- name: Run ngcompass
run: ngcompass analyze --format sarif > results.sarif
- name: Upload SARIF
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: results.sarif
```
## 缓存
ngcompass 缓存文件发现、执行计划、AST 工作、规则结果和完整分析输出。预热运行可以重用未更改的工作，而不是再次解析和分析整个项目。
```
ngcompass cache info
ngcompass cache clear
ngcompass analyze --force
```
## 单一代码库
| 包 | 责任 |
| -------------------------------------------- | ------------------------------------------------------- |
| [`ngcompass`](packages/cli) | CLI 入口点 |
| [`@ngcompass/config`](packages/config) | 配置加载、验证、配置文件和健康检查 |
| [`@ngcompass/scanner`](packages/scanner) | 文件发现和过滤 |
| [`@ngcompass/rules`](packages/rules) | 内置规则、预设和规则注册表 |
| [`@ngcompass/planner`](packages/planner) | 增量执行计划 |
| [`@ngcompass/engine`](packages/engine) | 规则执行和分析编排 |
| [`@ngcompass/ast`](packages/ast) | TypeScript、模板和样式解析助手 |
| [`@ngcompass/cache`](packages/cache) | 内存和磁盘缓存服务 |
| [`@ngcompass/reporters`](packages/reporters) | 控制台、JSON、SARIF 和 HTML 报告器 |
| [`@ngcompass/common`](packages/common) | 共享类型和实用程序 |
| [`@ngcompass/site`](packages/site) | 文档站点 |
## 开发
```
pnpm install
pnpm build
pnpm test
pnpm typecheck
```
额外的 workspace 检查：
```
pnpm smoke
pnpm validate:packages
pnpm prerelease:check
```
## 要求
- Node.js `^20.19.0` 或 `>=22.12.0`
- Angular v15 或更高版本
- pnpm 用于仓库开发
## 测试版说明
- 规则名称、消息和报告布局在 `1.0` 之前可能会更改。
- 对于高度动态的模板，模板分析是尽力而为。
- 在将其作为必需的 CI 网关之前，请先对 ngcompass 进行项目验证。
