@accordproject/concerto-linter 1.0.0

package/.eslintignore

@@ -0,0 +1,20 @@
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+coverage
+node_modules
+out
+lib/parser.js
+test/data
+dist

package/.eslintrc.yml

@@ -0,0 +1,45 @@
+env:
+    es6: true
+    node: true
+    mocha: true
+extends:
+ - 'eslint:recommended'
+ - 'plugin:@typescript-eslint/eslint-recommended'
+ - 'plugin:@typescript-eslint/recommended'
+parser: '@typescript-eslint/parser'
+plugins:
+ - '@typescript-eslint'
+parserOptions:
+    ecmaVersion: 13
+    sourceType: script
+rules:
+    indent:
+        - error
+        - 4
+    linebreak-style:
+        - warn
+        - unix
+    quotes:
+        - error
+        - single
+    semi:
+        - error
+        - always
+    no-console: warn
+    curly: error
+    eqeqeq: error
+    no-throw-literal: error
+    strict: 0
+    no-var: error
+    dot-notation: error
+    no-tabs: error
+    no-trailing-spaces: error
+    # no-use-before-define: error
+    no-useless-call: error
+    no-with: error
+    operator-linebreak: error
+    require-jsdoc: 0
+    valid-jsdoc:
+        - error
+        - requireReturn: false
+    yoda: error

package/HEADER.md

@@ -0,0 +1,2 @@
+## License <a name="license"></a>
+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), available at http://creativecommons.org/licenses/by/4.0/.

package/README.md

@@ -0,0 +1,207 @@
+# 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](#concerto-linter)
+  - [Table of contents](#table-of-contents)
+  - [Features](#features)
+    - [Model Input](#model-input)
+    - [Ruleset Discovery](#ruleset-discovery)
+    - [Ruleset Flexibility](#ruleset-flexibility)
+    - [Namespace Filtering](#namespace-filtering)
+    - [JSON Output](#json-output)
+  - [Getting Started](#getting-started)
+  - [Installation](#installation)
+    - [Providing the concerto Model](#providing-the-concerto-model)
+      - [As a CTO String](#as-a-cto-string)
+      - [As a Parsed AST Object](#as-a-parsed-ast-object)
+  - [Ruleset Configuration](#ruleset-configuration)
+    - [Default Ruleset](#default-ruleset)
+    - [Custom Rulesets](#custom-rulesets)
+    - [Automatic Ruleset Discovery](#automatic-ruleset-discovery)
+    - [Creating Custom Rulesets](#creating-custom-rulesets)
+  - [The linter output](#the-linter-output)
+    - [Namespace Filtering](#namespace-filtering-1)
+  - [License](#license)
+
+<!-- tocstop -->
+## 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:
+```bash
+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
+```javascript
+const model = `
+namespace org.example
+asset MyProduct {
+  o String ProductId
+}
+`;
+```
+
+#### As a Parsed AST Object
+```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();
+```
+## 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:
+
+1. **Create a ruleset file** in your project directory using any of these supported formats:
+   - `.spectral.yaml`
+   - `.spectral.yml`
+   - `.spectral.json`
+   - `.spectral.js`
+
+2. **Specify a ruleset path** explicitly when calling the linter:
+   ```javascript
+   const results = await lintModel(ast, {ruleset: 'path/to/your/custom-ruleset.yaml'});
+   ```
+
+3. **Force the default ruleset** 
+   ```javascript
+   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:
+
+1. `.spectral.yaml`
+2. `.spectral.yml`
+3. `.spectral.json`
+4. `.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:
+
+```javascript
+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`).
+
+```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
+```
+
+### 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](./default-ruleset/README.md).
+
+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:
+
+```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;
+
+}
+```
+Example Output :
+
+```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"
+  }
+```
+
+### 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.
+
+```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.*']
+});
+```
+## 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).

package/default-ruleset/.eslintignore

@@ -0,0 +1,20 @@
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+coverage
+node_modules
+out
+lib/parser.js
+test/data
+dist

package/default-ruleset/.eslintrc.yml

@@ -0,0 +1,45 @@
+env:
+    es6: true
+    node: true
+    mocha: true
+extends:
+ - 'eslint:recommended'
+ - 'plugin:@typescript-eslint/eslint-recommended'
+ - 'plugin:@typescript-eslint/recommended'
+parser: '@typescript-eslint/parser'
+plugins:
+ - '@typescript-eslint'
+parserOptions:
+    ecmaVersion: 13
+    sourceType: script
+rules:
+    indent:
+        - error
+        - 4
+    linebreak-style:
+        - warn
+        - unix
+    quotes:
+        - error
+        - single
+    semi:
+        - error
+        - always
+    no-console: warn
+    curly: error
+    eqeqeq: error
+    no-throw-literal: error
+    strict: 0
+    no-var: error
+    dot-notation: error
+    no-tabs: error
+    no-trailing-spaces: error
+    # no-use-before-define: error
+    no-useless-call: error
+    no-with: error
+    operator-linebreak: error
+    require-jsdoc: 0
+    valid-jsdoc:
+        - error
+        - requireReturn: false
+    yoda: error

package/default-ruleset/README.md

@@ -0,0 +1,300 @@
+# Concerto Linter Default Ruleset
+
+A comprehensive set of linting rules designed to validate concerto models against industry best practices and consistent naming conventions. This default ruleset helps maintain high-quality, readable, and maintainable concerto models across your projects. It is fully configurable - you can extend it, add new rules, disable existing ones, or create an entirely new ruleset without extending this one.
+
+This sub-package is part of the `@accordproject/concerto-linter` package. Read the [concerto-linter README](https://github.com/accordproject/concerto/tree/main/packages/concerto-linter) if you want to know how to use this ruleset with concerto models.
+
+## Table of Contents
+
+- [Concerto Linter Default Ruleset](#concerto-linter-default-ruleset)
+  - [Table of Contents](#table-of-contents)
+  - [Key Benefits](#key-benefits)
+  - [Available Rules](#available-rules)
+  - [Installation](#installation)
+  - [Usage](#usage)
+  - [Customization](#customization)
+    - [Extending the Default Ruleset](#extending-the-default-ruleset)
+    - [Disabling Specific Rules](#disabling-specific-rules)
+      - [Available Rule IDs](#available-rule-ids)
+    - [Enabling Specific Rules](#enabling-specific-rules)
+    - [Adjusting Rule Severity](#adjusting-rule-severity)
+  - [Creating Custom Rules](#creating-custom-rules)
+  - [License](#license)
+
+## Key Benefits
+
+- **Consistent Code Style**: Enforce uniform naming conventions across your concerto models
+- **Error Prevention**: Catch common modeling mistakes before they cause issues
+- **Best Practices**: Apply industry-standard modeling practices automatically
+- **Customizable**: Easily extend or modify rules to match your project's specific needs
+- **Integration Ready**: Works seamlessly with the concerto Linter and your development workflow
+
+## Available Rules
+
+The following table provides an overview of the available linting rules in the default ruleset:
+
+<table>
+<tr>
+<th>Rule Id</th><th>Description</th>
+</tr>
+<tr>
+<td><a href="#namespace-version">namespace-version</a></td>
+<td>Ensures that the namespace declaration in the model includes a version number. This rule enforces semantic versioning in namespaces, promoting clarity and compatibility management.</td>
+</tr>
+<tr>
+<td><a href="#no-reserved-keywords">no-reserved-keywords</a></td>
+<td>Enforces that names used for declarations, properties, and decorators in concerto models do not use reserved keywords. Reserved keywords are language-specific terms that may cause conflicts or unexpected behavior if used as identifiers.</td>
+</tr>
+<tr>
+<td><a href="#pascal-case-declarations">pascal-case-declarations</a></td>
+<td>Ensures that declaration names (scalar, enum, concept, asset, participant, transaction, event) follow PascalCase naming convention (e.g., 'MyDeclaration'). This promotes consistency and readability across model declarations.</td>
+</tr>
+<tr>
+<td><a href="#camel-case-properties">camel-case-properties</a></td>
+<td>Ensures that properties of type String, Double, Integer, Long, DateTime, and Boolean are named using camelCase. This promotes consistency and readability in property naming conventions across the model.</td>
+</tr>
+<tr>
+<td><a href="#upper-snake-case-enum-constants">upper-snake-case-enum-constants</a></td>
+<td>Enforces that all enum constant names follow the UPPER_SNAKE_CASE convention. This rule checks each enum property name and reports an error if it does not match the required pattern. Ensures consistency and readability in enum naming across the model.</td>
+</tr>
+<tr>
+<td><a href="#pascal-case-decorators">pascal-case-decorators</a></td>
+<td>Ensures that decorator names follow PascalCase naming convention (e.g., 'MyDecorator'). This promotes consistency and readability across model decorators.</td>
+</tr>
+<tr>
+<td><a href="#string-length-validator">string-length-validator</a></td>
+<td>Ensures that all string properties within the data model have a length validator applied, which helps prevent inconsistent data length and ensure proper storage.</td>
+</tr>
+<tr>
+<td><a href="#no-empty-declarations">no-empty-declarations</a></td>
+<td>Detects and reports any model declarations that are empty. This rule helps maintain model integrity by ensuring that all declarations contain meaningful content, preventing the inclusion of unused or placeholder declarations in the model.</td>
+</tr>
+<tr>
+<td><a href="#abstract-must-subclassed">abstract-must-subclassed</a></td>
+<td>Ensures that every abstract declaration in the model has at least one concrete subclass. This helps prevent unused or orphaned abstract types, enforcing better model design.</td>
+</tr>
+</table> 
+
+## Installation
+
+First, install the package as a development dependency:
+
+```bash
+npm install --save-dev @accordproject/concerto-linter-default-ruleset
+```
+
+## Usage
+
+Once installed, the default ruleset is automatically used by the concerto Linter when no custom ruleset is specified:
+
+```javascript
+import { lintModel } from '@accordproject/concerto-linter';
+
+// The default ruleset will be used automatically
+const results = await lintModel(modelText);
+console.log(results);
+```
+
+To explicitly specify the default ruleset:
+
+```javascript
+const results = await lintModel(modelText, { ruleset: 'default' });
+```
+
+## Customization
+
+To create your own ruleset that fits your project needs, you can either extend the default ruleset, or create an entirely new ruleset from scratch.
+
+Your ruleset should be defined in one of these file formats: `.spectral.yaml`, `.spectral.yml`, `.spectral.json`, or `.spectral.js`. The concerto Linter will automatically detect and use these files, or you can specify a custom path using the `ruleset` property: `ruleset: "./path/to/my-ruleset.yaml"`. 
+
+### Extending the Default Ruleset
+
+You can extend the default ruleset in multiple formats:
+
+**YAML (.spectral.yaml)**
+```yaml
+extends: '@accordproject/concerto-linter-default-ruleset'
+```
+
+---
+
+**JSON (.spectral.json)**
+```json
+{
+  "extends": "@accordproject/concerto-linter-default-ruleset"
+}
+```
+
+---
+
+**JavaScript (.spectral.js)**
+```javascript
+const rules = require('@accordproject/concerto-linter-default-ruleset');
+module.exports = {
+  extends: rules
+};
+```
+
+### Disabling Specific Rules
+
+You can disable specific rules that don't match your project's requirements by setting them to `'off'`. The rule identifiers are defined in the `ruleset-main.ts` file located at `concerto/packages/concerto-linter/default-ruleset/src`.
+
+#### Available Rule IDs
+
+Here are all the rule IDs that can be disabled:
+
+| Rule ID | Description |
+|---------|-------------|
+| `namespace-version` | Ensures namespaces include version numbers |
+| `no-reserved-keywords` | Prevents use of reserved keywords |
+| `pascal-case-declarations` | Enforces PascalCase for declarations |
+| `camel-case-properties` | Enforces camelCase for properties |
+| `upper-snake-case-enum-constants` | Enforces UPPER_SNAKE_CASE for enum constants |
+| `pascal-case-decorators` | Enforces PascalCase for decorators |
+| `string-length-validator` | Requires string length validators |
+| `no-empty-declarations` | Prevents empty declarations |
+| `abstract-must-subclassed` | Ensures abstract classes have concrete subclasses |
+
+
+**YAML (.spectral.yaml)**
+```yaml
+extends: '@accordproject/concerto-linter-default-ruleset'
+rules:
+  pascal-case-declarations: 'off'
+  camel-case-properties: 'off'
+```
+
+---
+
+**JSON (.spectral.json)**
+```json
+{
+  "extends": "@accordproject/concerto-linter-default-ruleset",
+  "rules": {
+    "pascal-case-declarations": "off",
+    "camel-case-properties": "off"
+  }
+}
+```
+
+**JavaScript (.spectral.js)**
+```javascript
+const rules = require('@accordproject/concerto-linter-default-ruleset');
+module.exports = {
+  extends: rules,
+  rules: {
+    'pascal-case-declarations': off,
+    'namespace-version': off
+  }
+};
+```
+### Enabling Specific Rules
+
+You can selectively start with everything off and enable only specific rules:
+
+**YAML (.spectral.yaml)**
+```yaml
+extends: [['@accordproject/concerto-linter-default-ruleset', 'off']]
+rules:
+  pascal-case-declarations: true
+  namespace-version: true
+```
+
+**JSON (.spectral.json)**
+```json
+{
+  "extends": [["@accordproject/concerto-linter-default-ruleset", "off"]],
+  "rules": {
+    "pascal-case-declarations": true,
+    "namespace-version": true
+  }
+}
+```
+
+**JavaScript (.spectral.js)**
+```javascript
+const rules = require('@accordproject/concerto-linter-default-ruleset');
+module.exports = {
+  extends: [[rules, 'off']],
+  rules: {
+    'pascal-case-declarations': true,
+    'namespace-version': true
+  }
+};
+```
+---
+### Adjusting Rule Severity
+
+You can customize the severity level of each rule to control how violations are reported.  
+- **0** = error (must be fixed)  
+- **1** = warn (should be addressed)  
+- **2** = info (useful information)  
+- **3** = hint (optional suggestion)  
+
+**YAML (.spectral.yaml)**
+```yaml
+extends: '@accordproject/concerto-linter-default-ruleset'
+rules:
+  pascal-case-declarations: 'warn'  # Change from error to warning
+  camel-case-properties: 'info'     # Change to informational
+```
+
+**JSON (.spectral.json)**
+```json
+{
+  "extends": "@accordproject/concerto-linter-default-ruleset",
+  "rules": {
+    "pascal-case-declarations": "warn",
+    "camel-case-properties": "info"
+  }
+}
+```
+
+**JavaScript (.spectral.js)**
+```javascript
+const rules = require('@accordproject/concerto-linter-default-ruleset');
+module.exports = {
+  extends: rules,
+  rules: {
+    'pascal-case-declarations': 'warn',
+    'camel-case-properties': 'info'
+  }
+};
+```
+
+## Creating Custom Rules
+
+Whether you want to add new rules to the default ruleset or create an entirely new ruleset, you can follow the Spectral ruleset format. For comprehensive documentation, see the [Spectral ruleset documentation](https://meta.stoplight.io/docs/spectral/e5b9616d6d50c-rulesets).
+
+Here's a simple example of what a custom rule looks like:
+
+```yaml
+# description (optional): Explains what the ruleset is about.
+description: "Declaration names (scalar, enum, concept, asset, participant, transaction, event) should be PascalCase."
+
+# given (required): JSONPath expression that specifies where the rule applies.
+given: "$.models[*].declarations[*].name"
+
+# message (required): The error/warning message shown when the rule is violated.
+message: "Declaration '{{value}}' should be PascalCase (e.g. 'MyDeclaration')"
+
+# severity (optional): The level of violation.
+# 0 = error, 1 = warning, 2 = info, 3 = hint
+severity: 0
+
+# then (required): Defines what function to apply and how.
+then:
+  # function (required): The function that validates the rule.
+  function: casing
+
+  # functionOptions (optional): Extra options for the function.
+  functionOptions:
+    type: pascal
+```
+
+For more complex rules, you can create custom JavaScript functions following [Spectral ruleset documentation](https://meta.stoplight.io/docs/spectral/e5b9616d6d50c-rulesets) and import it into your rule, similar to how the built-in rules work.
+
+
+## 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).

package/default-ruleset/jest.config.js

@@ -0,0 +1,7 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} **/
+module.exports = {
+    testEnvironment: 'node',
+    transform: {
+        '^.+.tsx?$': ['ts-jest', {}],
+    },
+};