# @accordproject/concerto-linter 中文文档

规范地址：https://npmcn.com/package/%40accordproject/concerto-linter/

版本：5\.2\.1
npm 元数据更新时间：2026-10-17T23:42:12.371Z
中文译文更新时间：2026-11-05T22:22:28.983Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40accordproject/concerto-linter
原文对照：https://npmcn.com/package/%40accordproject/concerto-linter/?lang=original
项目主页：https://github.com/accordproject/concerto
源码仓库：https://github.com/accordproject/concerto

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：20.6 MB，71 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：9 个
- 首次发布：2025-06-19T10:16:42.802Z
- 最新版本发布：2026-10-17T23:42:11.988Z
- 近 30 天下载量：12671（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：50（近 12 个月 26 个）

## 中文简介

使用光谱规则的 Concerto Linter

## 安装

```sh
npm install @accordproject/concerto-linter
```

也可以使用：`pnpm add @accordproject/concerto-linter`、`yarn add @accordproject/concerto-linter`、`bun add @accordproject/concerto-linter`

## README

# 协奏曲 linter

Linter提供了lintModel函数,为使用Spectral的Linting Concerto模型提供了有力而有效的解决方案. 它确保您的模型遵守预定义或自定义规则,促进代码库中的一致性、质量和可维护性.

## 目录

-   [协奏曲 linter](https://npmcn.com/package/%40accordproject/concerto-linter/#readme-concerto-linter)
    -   [目录](https://npmcn.com/package/%40accordproject/concerto-linter/#readme-table-of-contents)
    -   [特征](https://npmcn.com/package/%40accordproject/concerto-linter/#readme-features)
        -   [模型输入](https://npmcn.com/package/%40accordproject/concerto-linter/#readme-model-input)
        -   [规则发现](https://npmcn.com/package/%40accordproject/concerto-linter/#readme-ruleset-discovery)
        -   [灵活性](https://npmcn.com/package/%40accordproject/concerto-linter/#readme-ruleset-flexibility)
        -   [命名空间过滤](https://npmcn.com/package/%40accordproject/concerto-linter/#readme-namespace-filtering)
        -   [JSON 输出](https://npmcn.com/package/%40accordproject/concerto-linter/#readme-json-output)
    -   [开始](https://npmcn.com/package/%40accordproject/concerto-linter/#readme-getting-started)
    -   [安装](https://npmcn.com/package/%40accordproject/concerto-linter/#readme-installation)
        -   [提供协奏曲模式](https://npmcn.com/package/%40accordproject/concerto-linter/#readme-providing-the-concerto-model)
            -   [作为 CTO 字符串](https://npmcn.com/package/%40accordproject/concerto-linter/#readme-as-a-cto-string)
            -   [作为已解析的 AST 对象](https://npmcn.com/package/%40accordproject/concerto-linter/#readme-as-a-parsed-ast-object)
    -   [规则集配置](https://npmcn.com/package/%40accordproject/concerto-linter/#readme-ruleset-configuration)
        -   [默认规则](https://npmcn.com/package/%40accordproject/concerto-linter/#readme-default-ruleset)
        -   [自定义规则](https://npmcn.com/package/%40accordproject/concerto-linter/#readme-custom-rulesets)
        -   [自动规则发现](https://npmcn.com/package/%40accordproject/concerto-linter/#readme-automatic-ruleset-discovery)
        -   [创建自定义规则](https://npmcn.com/package/%40accordproject/concerto-linter/#readme-creating-custom-rulesets)
    -   [线性输出](https://npmcn.com/package/%40accordproject/concerto-linter/#readme-the-linter-output)
        -   [命名空间过滤](https://npmcn.com/package/%40accordproject/concerto-linter/#readme-namespace-filtering-1)
    -   [许可证](https://npmcn.com/package/%40accordproject/concerto-linter/#readme-license)

## 特征

### 模型输入

-   **Versatile 模型输入**: 支持作为 CTO 字符串或解析的抽象语法树(AST)对象提供的协奏曲模型.

### 规则发现

-   **自动规则发现**:当没有指定明确的规则时,自动检测光谱规则文件(如:光谱.yaml,光谱.yml,光谱.json,光谱.js等)于当前或母目录中.

### 灵活性

-   **自定义规则灵活性**: 允许您指定其文件路径, 用于剪接规则, 从而启用自定义 Spectral 规则 .

### 命名空间过滤

-   **命名空间过滤**: 过滤器会按命名空间进行林入结果,具有可配置的排除模式. 默认,不包括 `'concerto.*'` 财务报告和审定财务报表 `'org.accordproject.*'` 名称空间.

### JSON 输出

-   **结构化 JSON 输出**: 返回内嵌结果采用一致的JSON格式,以便于与其他工具和工作流程进行整合.

## 开始

插座很定制 默认情况下,它会使用@accordproject/concerto-linter-default-rulesset来给任何 Concerto 模型加注,但您也可以扩展它或创建自定义规则集.

## 安装

通过 npm 安装软件包 :

```bash
npm install @accordproject/concerto-linter
```

### 提供协奏曲模式

LintModel 函数以两种格式之一接受您的 Concerto 模式:

#### 作为 CTO 字符串

```javascript
const model = `
namespace org.example
asset MyProduct {
  o String ProductId
}
`;
```

#### 作为已解析的 AST 对象

```javascript
import { ModelManager } from '@accordproject/concerto-core';

const modelManager = new ModelManager();
const model = `
namespace org.example
asset MyProduct {
  o String ProductId
}
`;
modelManager.addCTOModel(model);
const ast = modelManager.getAst();
```

## 规则集配置

协奏曲 Linter 提供了灵活的 `ruleset` 配置选项以适应您的项目需要.

### 默认规则

默认情况下, linter 使用 `@accordproject/concerto-linter-default-ruleset`,它为协奏曲模型提供了一整套规则. 此规则在未指定自定义规则时自动被应用 .

### 自定义规则

您可以从几个方面定制林定规则:

1.  **创建规则集文件** 在项目目录中使用任何这些支持的格式:
    
    -   `.spectral.yaml`
    -   `.spectral.yml`
    -   `.spectral.json`
    -   `.spectral.js`
2.  **指定规则路径** 明确调用电线时:
    
    ```javascript
    const results = await lintModel(ast, {ruleset: 'path/to/your/custom-ruleset.yaml'});
    ```
    
3.  **强制默认规则**
    
    ```javascript
    const results = await lintModel(ast, {ruleset: 'default'});
    ```
    

### 自动规则发现

当你打电话 `lintModel` 在不指定规则集的情况下, linter 将按以下顺序自动搜索规则集文件:

1.  `.spectral.yaml`
2.  `.spectral.yml`
3.  `.spectral.json`
4.  `.spectral.js`

如果你想的话 **部队** 即使在工程中存在自定义规则集文件时使用内置默认规则集的linter, pass `ruleset: 'default'` 选项中:

```javascript
import { lintModel } from '@accordproject/concerto-linter';

const results = await lintModel(ast, { ruleset: 'default' });
```

如果在当前目录或父目录中找不到这些文件, linter 将返回到使用默认规则(`@accordproject/concerto-linter-default-ruleset`) (中文(简体) ).

```javascript
import { lintModel } from '@accordproject/concerto-linter';

// The linter will automatically detect ruleset files in your project
const results = await lintModel(ast); // Pass the AST object
// OR
const results = await lintModel(model); // Pass the CTO string directly
```

### 创建自定义规则

你可以创建自己的自定义规则来强制实施您的音乐会模式的特定规则. 关于创建自定义规则的详细指导意见,参见: [默认规则集文档](https://npmcn.com/package/%40accordproject/concerto-linter/default-ruleset/README.md)。 。 。 .

自定义规则按照Spectral ruleset格式,可以在YAML,JSON或JavaScript中创建. 一旦创建, linter 将自动检测您的 rudeet 文件, 如果它使用标准名称之一, 或者您可以明确指定其路径, 如上面的例子所示 .

## 线性输出

LintModel 函数返回一个承诺, 以 JSON 格式解析出一系列林入结果 :

每期插图以平面 JSON 对象表示:

```ts
interface ILintResult {
  /** Unique rule identifier (e.g. 'no-unused-concept') */
  code: string;

  /** Human-readable description of the violation */
  message: string;

  /** Severity level ('error' | 'warning' | 'info' | 'hint') */
  severity: string;

  /**
   * JSONPath-style pointer as an array of keys/indices
   * (e.g. ['declarations', 3])
   */
  path: Array<string | number>;

  /** Namespace where the violation occurred (e.g. 'org.accordproject') */
  namespace: string;

}
```

示例输出 :

```json
[
  {
    "code": "camel-case-properties",
    "message": "Property 'FirstVal' should be camelCase (e.g. 'myProperty').",
    "severity": "warning",
    "path": ["declarations", 3],
    "namespace": "org.example.model",
    "source": "concerto-lintr"
  }
```

### 命名空间过滤

默认情况下, 命名空间匹配的结果 `'concerto.*'` 财务报告和审定财务报表 `'org.accordproject.*'` 不包括产出。 您可以使用 `excludeNamespaces` 选项.

```javascript
// Override default namespace exclusions
const results = await lintModel(ast, { 
  excludeNamespaces: ['org.example.*', 'com.acme.*'] 
});

// Combine custom ruleset and namespace filtering
const results = await lintModel(ast, {
  ruleset: "D:\\linter-test\\my-ruleset.yaml",
  excludeNamespaces: ['org.example.*']
});
```

## 许可证

Accord Project源代码文件在位于LICENSE文件的Apache许可证2.0版本(Apache-2.0)下提供. 协议项目文件文件根据创用CC-BY-4.0国际许可证提供.

## 常见问题

### @accordproject/concerto-linter 是什么？

使用光谱规则的 Concerto Linter

### 如何安装 @accordproject/concerto-linter？

在项目目录运行 npm install @accordproject/concerto-linter，或使用 pnpm add / yarn add / bun add。

### @accordproject/concerto-linter 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @accordproject/concerto-linter 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @accordproject/concerto-linter 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @accordproject/concerto-linter 可以商用吗？

@accordproject/concerto-linter 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @accordproject/concerto-linter 的下载量有多少？

根据 npm 官方下载统计，@accordproject/concerto-linter 在 2026/10/05 – 2026/11/03 这 30 天内被下载 12,671 次，日均约 422 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @accordproject/concerto-linter 还在维护吗？

最新版本 5\.2\.1 发布于 2026/10/18（19 天前）；至今共发布 50 个版本，其中过去 12 个月发布了 26 个；首次发布于 2025/06/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。