@accordproject/concerto-linter

concerto linter

The linter provide the lintModel function which provides a robust and efficient solution for linting Concerto models using Spectral. It ensures your models adhere to predefined or custom rulesets, promoting consistency, quality, and maintainability in your codebase.

Table of contents

• concerto linter
  • Table of contents
  • Features
    • Model Input
    • Ruleset Discovery
    • Ruleset Flexibility
    • Namespace Filtering
    • JSON Output
  • Getting Started
  • Installation
    • Providing the concerto Model
      • As a CTO String
      • As a Parsed AST Object
  • Ruleset Configuration
    • Default Ruleset
    • Custom Rulesets
    • Automatic Ruleset Discovery
    • Creating Custom Rulesets
  • The linter output
    • Namespace Filtering
  • License

Features

Model Input

• Versatile Model Input: Supports concerto models provided as either a CTO string or a parsed Abstract Syntax Tree (AST) object.

Ruleset Discovery

• Automatic Ruleset Discovery: Automatically detects Spectral ruleset files (e.g., .spectral.yaml, .spectral.yml, .spectral.json, .spectral.js) in the current or parent directories when no explicit ruleset is specified.

Ruleset Flexibility

• Custom Ruleset Flexibility: Enables the use of a custom Spectral ruleset by allowing you to specify its file path for tailored linting rules.

Namespace Filtering

• Namespace Filtering: Filters linting results by namespace, with configurable exclusion patterns. By default, excludes 'concerto.*' and 'org.accordproject.*' namespaces.

JSON Output

• Structured JSON Output: Returns linting results in a consistent JSON format for easier integration with other tools and workflows.

Getting Started

The linter is highly customizable. By default, it will lint any Concerto model using the @accordproject/concerto-linter-default-ruleset, but you can also extend it or create your own custom ruleset.

Installation

Install the package via npm:

npm install @accordproject/concerto-linter

Providing the concerto Model

The lintModel function accepts your Concerto model in one of two formats:

As a CTO String

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

As a Parsed AST Object

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();

Ruleset Configuration

The concerto Linter provides flexible ruleset configuration options to suit your project needs.

Default Ruleset

By default, the linter uses @accordproject/concerto-linter-default-ruleset, which provides a comprehensive set of rules for concerto models. This ruleset is automatically applied when no custom ruleset is specified.

Custom Rulesets

You can customize the linting rules in several ways:

• Create a ruleset file in your project directory using any of these supported formats:

  • .spectral.yaml
  • .spectral.yml
  • .spectral.json
  • .spectral.js

• Specify a ruleset path explicitly when calling the linter:

  const results = await lintModel(ast, {ruleset: 'path/to/your/custom-ruleset.yaml'});
  

• Force the default ruleset

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

Automatic Ruleset Discovery

When you call lintModel without specifying a ruleset, the linter will automatically search for ruleset files in the following order:

• .spectral.yaml
• .spectral.yml
• .spectral.json
• .spectral.js

If you want to force the linter to use the built-in default ruleset even when custom ruleset files are present in the project, pass ruleset: 'default' in the options:

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

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

If none of these files are found in the current or parent directories, the linter will fall back to using the default ruleset (@accordproject/concerto-linter-default-ruleset).

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

Creating Custom Rulesets

You can create your own custom ruleset to enforce specific rules for your Concerto models. For detailed guidance on creating custom rulesets, refer to the default-ruleset documentation.

Custom rulesets follow the Spectral ruleset format and can be created in YAML, JSON, or JavaScript. Once created, the linter will automatically detect your ruleset file if it uses one of the standard names, or you can explicitly specify its path as shown in the examples above.

The linter output

The lintModel function returns a Promise that resolves to an array of linting results in JSON format:

Each lint issue is represented as a flat JSON object:

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;

}

Example Output :

[
  {
    "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"
  }

Namespace Filtering

By default, results from namespaces matching 'concerto.*' and 'org.accordproject.*' are excluded from the output. You can customize this behavior using the excludeNamespaces option.

// 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.*']
});

License

Accord Project source code files are made available under the Apache License, Version 2.0 (Apache-2.0), located in the LICENSE file. Accord Project documentation files are made available under the Creative Commons Attribution 4.0 International License (CC-BY-4.0).