Shared Package - AI Assistant Guide

Project Overview

The shared package contains common utilities, helpers, and core logic used across the CALM monorepo. It is a critical dependency for:

WARNING: Changes in this package affect multiple downstream projects.

ALWAYS run the full test suite (npm run test from root) after making changes here.
Do not break existing public APIs unless absolutely necessary (and coordinated with all consumers).

Because this is a shared library, rigorous testing is mandatory.

IMPORTANT: Always run npm commands from the repository root using workspaces.

# Run tests for this package only (from repository root)
npm test --workspace shared

# Run tests for ALL packages (REQUIRED before PR)
npm test

Document Loader: Strategies for loading CALM documents (FileSystem, MultiStrategy).
Template Processor: Handlebars-based template generation logic.
Model Visitors: Visitor pattern implementations for traversing CALM models.
Validation: Core validation logic (Spectral integration) and output enrichment.
- runValidation() - Main validation function used by CLI and VSCode
- enrichWithDocumentPositions() - Adds precise line/character positions to validation output using @stoplight/json
- parseDocumentWithPositions() - Parses JSON/YAML with position tracking for error location
Schema Directory: Registry of bundled CALM schemas, used for lookup by schema URL.

IMPORTANT: Always run npm commands from the repository root using workspaces, not from within this package directory.

# Build this package (from repository root)
npm run build --workspace shared