tessl/npm-finos--calm-cli

A comprehensive command-line interface for working with the Common Architecture Language Model (CALM)

Overview

Eval results

Files

Validate Command

Name: tessl/npm-finos--calm-cli
Author: tessl

NOTE: This is a CLI-only command. @finos/calm-cli does not export functions for programmatic use.

The validate command verifies that a CALM architecture conforms to a given pattern or schema. It performs comprehensive validation including JSON schema validation and Spectral-based linting, providing detailed error and warning reports in multiple output formats.

Capabilities

Validate Command

Validates a CALM architecture against a pattern with detailed error and warning reporting.

/**
 * Validate that an architecture conforms to a given CALM pattern
 * @command calm validate [options]
 */
interface ValidateCommandOptions {
  /** Path to pattern file (file path or URL)
   * CLI flags: -p, --pattern <file>
   */
  pattern?: string;

  /** Path to architecture file (file path or URL)
   * CLI flags: -a, --architecture <file>
   */
  architecture?: string;

  /** Path to directory containing meta schemas
   * CLI flags: -s, --schema-directory <path>
   * Default: CALM_META_SCHEMA_DIRECTORY
   */
  schemaDirectory?: string;

  /** Fail if warnings are reported
   * CLI flags: --strict
   * Default: false
   */
  strict?: boolean;

  /** Output format: 'json', 'junit', or 'pretty'
   * CLI flags: -f, --format <format>
   * Default: 'json'
   */
  format?: 'json' | 'junit' | 'pretty';

  /** Output file path (stdout if not specified)
   * CLI flags: -o, --output <file>
   */
  output?: string;

  /** Enable verbose logging
   * CLI flags: -v, --verbose
   * Default: false
   */
  verbose?: boolean;
}

Requirements:

At least one of pattern or architecture must be specified
If only architecture is provided, pattern is loaded from the architecture's $schema field

Usage Examples:

# Validate with both architecture and pattern
calm validate -a architecture.json -p pattern.json

# Validate with JSON output to file
calm validate -a architecture.json -p pattern.json -f json -o results.json

# Validate in strict mode (fail on warnings)
calm validate -a architecture.json -p pattern.json --strict

# Validate with JUnit output format (for CI/CD)
calm validate -a architecture.json -p pattern.json -f junit -o results.xml

# Validate with pretty-printed output
calm validate -a architecture.json -p pattern.json -f pretty

# Validate architecture against its embedded schema
calm validate -a architecture.json

# Use custom schema directory
calm validate -a architecture.json -p pattern.json -s ./custom-schemas

# Enable verbose logging
calm validate -a architecture.json -p pattern.json -v

Output Formats

JSON Format (Default)

Structured JSON output containing validation results:

{
  "jsonSchemaValidationOutputs": [],
  "spectralSchemaValidationOutputs": [
    {
      "code": "architecture-has-no-placeholder-properties-string",
      "severity": "warning",
      "message": "String placeholder detected in architecture.",
      "path": "/nodes/0/interfaces/0/host",
      "schemaPath": "",
      "line_start": 10,
      "line_end": 10,
      "character_start": 18,
      "character_end": 30
    }
  ],
  "hasErrors": false,
  "hasWarnings": true
}

JUnit Format

XML format compatible with CI/CD systems like Jenkins:

<?xml version="1.0" encoding="UTF-8"?>
<testsuites>
  <testsuite name="CALM Validation" tests="1" failures="0">
    <testcase name="architecture.json" />
  </testsuite>
</testsuites>

Pretty Format

Human-readable formatted output for terminal display:

✓ No errors found
⚠ 2 warnings found:
  - String placeholder detected at /nodes/0/interfaces/0/host
  - Numerical placeholder detected at /nodes/0/interfaces/0/port

Validation Modes

Standard Mode (Default)

Reports both errors and warnings
Exit code 0 if no errors, 1 if errors present
Warnings do not affect exit code

Strict Mode

Enabled with --strict flag:

Reports both errors and warnings
Exit code 1 if either errors or warnings are present
Useful for enforcing zero-warning policies in CI/CD

Validation Types

JSON Schema Validation

Validates architecture structure against JSON schemas:

Checks required fields are present
Validates data types (strings, numbers, arrays, objects)
Enforces schema constraints (min/max, patterns, enums)
Validates references and IDs

Spectral Validation

Applies additional linting rules using Spectral:

Detects placeholder values (strings like "PLACEHOLDER", numbers like -1)
Validates architectural patterns and conventions
Checks naming conventions
Enforces best practices

Loading Patterns and Architectures

From Local Files

calm validate -a ./path/to/architecture.json -p ./path/to/pattern.json

From URLs

calm validate \
  -a https://example.com/architectures/my-arch.json \
  -p https://example.com/patterns/api-gateway.json

From Architecture $schema Field

If architecture includes a $schema field pointing to a pattern:

{
  "$schema": "https://calm.finos.org/patterns/api-gateway.json",
  "nodes": [...]
}

You can validate without specifying pattern:

calm validate -a architecture.json

The CLI will automatically load the pattern from the $schema URL.

Configuration

CALMHub Integration

The validate command supports loading patterns and architectures from a CALMHub instance using the user configuration file:

Via User Configuration File (~/.calm.json):

{
  "calmHubUrl": "https://calmhub.example.com"
}

Important: Unlike the generate command which accepts a -c, --calm-hub-url command-line option, the validate command does NOT accept --calm-hub-url as a command-line flag. The validate command will only use the CALMHub URL from the ~/.calm.json configuration file if present.

When a CALMHub URL is configured, the validate command uses it to:

Load patterns specified as CALMHub URLs (e.g., when using -p https://calmhub.example.com/patterns/api-gateway.json)
Load architectures specified as CALMHub URLs
Resolve remote schema references

To configure CALMHub for validation:

Create or edit ~/.calm.json in your home directory
Add the calmHubUrl property with your CALMHub instance URL
Run validation commands normally - the CALMHub URL will be used automatically for remote resources

Example with CALMHub configuration:

# After configuring ~/.calm.json with calmHubUrl
calm validate -a architecture.json -p https://calmhub.example.com/patterns/api-pattern.json

The pattern will be loaded from the configured CALMHub instance.

Exit Codes

Exit Code	Condition
0	Validation successful (no errors, warnings allowed in standard mode)
1	Validation failed (errors present) or strict mode with warnings

Error Handling

Common Errors

Missing Required Options:

error: one of the required options '-p, --pattern' or '-a, --architecture' was not specified

Solution: Provide at least one of the options.

Invalid JSON Format:

An error occurred while validating: Invalid JSON format

Solution: Verify architecture file contains valid JSON.

File Not Found:

An error occurred while validating: ENOENT: no such file or directory

Solution: Verify file paths are correct.

Schema Not Found:

An error occurred while validating: Schema not found

Solution: Verify schema directory path and that required schemas are present.

Network Errors:

An error occurred while validating: Failed to fetch URL

Solution: Verify URLs are accessible and network connection is available.

Validation Outcome Structure

// Validation outcome from @finos/calm-shared
interface ValidationOutcome {
  /** JSON schema validation errors */
  jsonSchemaValidationOutputs: ValidationError[];
  /** Spectral linting errors and warnings */
  spectralSchemaValidationOutputs: SpectralError[];
  /** Whether any errors were found */
  hasErrors: boolean;
  /** Whether any warnings were found */
  hasWarnings: boolean;
}

interface ValidationError {
  /** Error code (string or number) */
  code: string | number;
  /** Error message */
  message: string;
  /** JSON path to error location */
  path: string;
  /** Schema path that failed */
  schemaPath: string;
}

interface SpectralError {
  /** Error/warning code */
  code: string;
  /** Severity level */
  severity: 'error' | 'warning' | 'info' | 'hint';
  /** Error/warning message */
  message: string;
  /** JSON path to issue location */
  path: string;
  /** Schema path */
  schemaPath: string;
  /** Line number where issue starts */
  line_start: number;
  /** Line number where issue ends */
  line_end: number;
  /** Character position where issue starts */
  character_start: number;
  /** Character position where issue ends */
  character_end: number;
}

Integration with CI/CD

GitHub Actions Example

name: Validate CALM Architecture
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm install -g @finos/calm-cli
      - run: calm validate -a architecture.json -p pattern.json --strict -f junit -o results.xml
      - uses: actions/upload-artifact@v3
        if: always()
        with:
          name: validation-results
          path: results.xml

GitLab CI Example

validate-calm:
  image: node:18
  script:
    - npm install -g @finos/calm-cli
    - calm validate -a architecture.json -p pattern.json --strict -f junit -o results.xml
  artifacts:
    reports:
      junit: results.xml

Best Practices

Use Strict Mode in CI/CD: Enable --strict to enforce zero-warning policy
Use JUnit Format for CI: JUnit output integrates with most CI/CD platforms
Version Control Patterns: Store patterns in version control alongside architectures
Validate Early: Run validation as part of pre-commit hooks or PR checks
Use Verbose Mode for Debugging: Enable -v when troubleshooting validation issues
Fix Placeholders: Generated architectures contain placeholders that trigger warnings
Schema Versioning: Pin schema versions in $schema field for reproducibility