@the-cascade-protocol/cli 0.2.0

package/src/lib/output.ts

@@ -0,0 +1,76 @@
+/**
+ * Output formatting utilities for consistent CLI output.
+ *
+ * Supports both human-readable text and machine-readable JSON output modes.
+ */
+
+export interface OutputOptions {
+  json: boolean;
+  verbose: boolean;
+}
+
+/**
+ * Format data for output in either JSON or human-readable text mode.
+ */
+export function formatOutput(data: unknown, opts: OutputOptions): string {
+  if (opts.json) {
+    return JSON.stringify(data, null, 2);
+  }
+
+  if (typeof data === 'string') {
+    return data;
+  }
+
+  if (Array.isArray(data)) {
+    return data.map((item) => formatSingleItem(item)).join('\n');
+  }
+
+  return formatSingleItem(data);
+}
+
+/**
+ * Format a single item for human-readable output.
+ */
+function formatSingleItem(item: unknown): string {
+  if (typeof item === 'string') {
+    return item;
+  }
+
+  if (typeof item === 'object' && item !== null) {
+    const entries = Object.entries(item as Record<string, unknown>);
+    return entries.map(([key, value]) => `  ${key}: ${String(value)}`).join('\n');
+  }
+
+  return String(item);
+}
+
+/**
+ * Print result data to stdout.
+ */
+export function printResult(data: unknown, opts: OutputOptions): void {
+  console.log(formatOutput(data, opts));
+}
+
+/**
+ * Print an error message to stderr.
+ */
+export function printError(message: string, opts: OutputOptions): void {
+  if (opts.json) {
+    console.error(JSON.stringify({ error: message }));
+  } else {
+    console.error(`ERROR: ${message}`);
+  }
+}
+
+/**
+ * Print a verbose/debug message (only if verbose mode is enabled).
+ */
+export function printVerbose(message: string, opts: OutputOptions): void {
+  if (opts.verbose) {
+    if (opts.json) {
+      console.error(JSON.stringify({ debug: message }));
+    } else {
+      console.error(`[verbose] ${message}`);
+    }
+  }
+}

package/src/lib/shacl-validator.ts

@@ -0,0 +1,314 @@
+/**
+ * SHACL validation utilities.
+ *
+ * Wraps rdf-validate-shacl to validate RDF data against
+ * Cascade Protocol SHACL shapes.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Parser, Store } from 'n3';
+import SHACLValidator from 'rdf-validate-shacl';
+import { parseTurtle, detectVocabularies, CASCADE_NAMESPACES } from './turtle-parser.js';
+import type { ParseResult } from './turtle-parser.js';
+
+export interface ValidationResult {
+  valid: boolean;
+  file: string;
+  results: ValidationIssue[];
+  shapesUsed: string[];
+  quadCount: number;
+  subjects: Array<{ uri: string; types: string[] }>;
+}
+
+export interface ValidationIssue {
+  severity: 'violation' | 'warning' | 'info';
+  shape: string;
+  property: string;
+  message: string;
+  focusNode?: string;
+  value?: string;
+  specLink?: string;
+}
+
+/** Mapping from shape file prefixes to their documentation base URLs */
+const SPEC_BASE_URLS: Record<string, string> = {
+  core: 'https://cascadeprotocol.org/docs/core/v1',
+  health: 'https://cascadeprotocol.org/docs/health/v1',
+  clinical: 'https://cascadeprotocol.org/docs/clinical/v1',
+  pots: 'https://cascadeprotocol.org/docs/pots/v1',
+  checkup: 'https://cascadeprotocol.org/docs/checkup/v1',
+  coverage: 'https://cascadeprotocol.org/docs/coverage/v1',
+};
+
+/**
+ * Resolve the bundled shapes directory.
+ * Works from both src/ (dev via tsx) and dist/ (built).
+ */
+function getShapesDir(): string {
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = path.dirname(__filename);
+
+  // When running from dist/lib/, shapes are at dist/shapes/
+  // When running from src/lib/ (dev), shapes are at src/shapes/
+  const shapesDir = path.resolve(__dirname, '..', 'shapes');
+
+  if (!fs.existsSync(shapesDir)) {
+    throw new Error(
+      `Shapes directory not found at ${shapesDir}. ` +
+        'Run "npm run build" to bundle shapes.',
+    );
+  }
+  return shapesDir;
+}
+
+/**
+ * Load and parse a Turtle file into an N3 Store.
+ */
+function loadTurtleFile(filePath: string): Store {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const parser = new Parser({ baseIRI: '' });
+  const store = new Store();
+  const quads = parser.parse(content);
+  store.addQuads(quads);
+  return store;
+}
+
+/**
+ * Load all bundled SHACL shapes from the shapes directory into a single store.
+ * If a custom shapes path is provided, load from there instead.
+ */
+export function loadShapes(customShapesPath?: string): { store: Store; shapeFiles: string[] } {
+  const shapesDir = customShapesPath ?? getShapesDir();
+  const store = new Store();
+  const shapeFiles: string[] = [];
+
+  if (!fs.existsSync(shapesDir)) {
+    throw new Error(`Shapes directory not found: ${shapesDir}`);
+  }
+
+  const files = fs.readdirSync(shapesDir).filter((f) => f.endsWith('.shapes.ttl'));
+
+  if (files.length === 0) {
+    throw new Error(`No SHACL shape files (*.shapes.ttl) found in ${shapesDir}`);
+  }
+
+  for (const file of files) {
+    const filePath = path.join(shapesDir, file);
+    const fileStore = loadTurtleFile(filePath);
+    for (const quad of fileStore) {
+      store.addQuad(quad);
+    }
+    shapeFiles.push(file);
+  }
+
+  // Also load vocabulary/ontology files so the validator knows about class hierarchies
+  const vocabFiles = fs.readdirSync(shapesDir).filter(
+    (f) => f.endsWith('.ttl') && !f.endsWith('.shapes.ttl'),
+  );
+
+  for (const file of vocabFiles) {
+    const filePath = path.join(shapesDir, file);
+    const fileStore = loadTurtleFile(filePath);
+    for (const quad of fileStore) {
+      store.addQuad(quad);
+    }
+  }
+
+  return { store, shapeFiles };
+}
+
+/**
+ * Generate a spec link from a shape URI.
+ *
+ * Examples:
+ *   https://ns.cascadeprotocol.org/clinical/v1#MedicationShape
+ *     -> https://cascadeprotocol.org/docs/clinical/v1#Medication
+ *   https://ns.cascadeprotocol.org/health/v1#SelfReportShape
+ *     -> https://cascadeprotocol.org/docs/health/v1#SelfReport
+ */
+function generateSpecLink(shapeUri: string): string | undefined {
+  for (const [vocab, ns] of Object.entries(CASCADE_NAMESPACES)) {
+    if (shapeUri.startsWith(ns)) {
+      const localName = shapeUri.slice(ns.length);
+      // Remove "Shape" suffix for the spec link
+      const className = localName.replace(/Shape$/, '');
+      const baseUrl = SPEC_BASE_URLS[vocab];
+      if (baseUrl) {
+        return `${baseUrl}#${className}`;
+      }
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Map SHACL severity URI to our severity level.
+ */
+function mapSeverity(severityUri: string): 'violation' | 'warning' | 'info' {
+  if (severityUri.endsWith('#Violation') || severityUri.endsWith('Violation')) {
+    return 'violation';
+  }
+  if (severityUri.endsWith('#Warning') || severityUri.endsWith('Warning')) {
+    return 'warning';
+  }
+  if (severityUri.endsWith('#Info') || severityUri.endsWith('Info')) {
+    return 'info';
+  }
+  // Default to violation for unknown severity
+  return 'violation';
+}
+
+/**
+ * Extract a human-readable name from a URI by taking the fragment or last path segment.
+ */
+function uriToName(uri: string): string {
+  if (uri.includes('#')) {
+    return uri.split('#').pop() ?? uri;
+  }
+  return uri.split('/').pop() ?? uri;
+}
+
+/**
+ * Validate an already-parsed Turtle file against SHACL shapes.
+ */
+export function validateParsed(
+  parseResult: ParseResult,
+  shapesStore: Store,
+  shapeFiles: string[],
+  filePath: string,
+): ValidationResult {
+  if (!parseResult.success) {
+    return {
+      valid: false,
+      file: filePath,
+      results: parseResult.errors.map((err) => ({
+        severity: 'violation' as const,
+        shape: '',
+        property: '',
+        message: `Parse error: ${err}`,
+      })),
+      shapesUsed: [],
+      quadCount: 0,
+      subjects: [],
+    };
+  }
+
+  // Detect vocabularies used so we can report which shapes apply
+  const vocabsUsed = detectVocabularies(parseResult);
+  const shapesUsed = shapeFiles.filter((f) => {
+    const vocabName = f.replace('.shapes.ttl', '');
+    return vocabsUsed.includes(vocabName);
+  });
+
+  // Run SHACL validation
+  const validator = new SHACLValidator(shapesStore, { allowNamedNodeInList: true });
+  const report = validator.validate(parseResult.store);
+
+  // Map results to our interface
+  const issues: ValidationIssue[] = [];
+
+  for (const result of report.results) {
+    const severityUri = result.severity?.value ?? '';
+    const severity = mapSeverity(severityUri);
+
+    const shapeUri = result.sourceShape?.value ?? '';
+    const pathUri = result.path?.value ?? '';
+    const focusNodeUri = result.focusNode?.value ?? '';
+    const valueStr = result.value?.value;
+
+    // Get the message - result.message is an array of Terms
+    const messages = result.message ?? [];
+    const messageText = messages.length > 0
+      ? messages.map((m) => m.value).join('; ')
+      : `Constraint violation on ${uriToName(pathUri)} of ${uriToName(shapeUri)}`;
+
+    const specLink = generateSpecLink(shapeUri);
+
+    issues.push({
+      severity,
+      shape: uriToName(shapeUri),
+      property: uriToName(pathUri),
+      message: messageText,
+      focusNode: focusNodeUri || undefined,
+      value: valueStr,
+      specLink,
+    });
+  }
+
+  return {
+    valid: report.conforms,
+    file: filePath,
+    results: issues,
+    shapesUsed,
+    quadCount: parseResult.quadCount,
+    subjects: parseResult.subjects,
+  };
+}
+
+/**
+ * Validate a Turtle string against SHACL shapes.
+ */
+export function validateTurtle(
+  turtleContent: string,
+  shapesStore: Store,
+  shapeFiles: string[],
+  filePath: string,
+): ValidationResult {
+  const parseResult = parseTurtle(turtleContent);
+  return validateParsed(parseResult, shapesStore, shapeFiles, filePath);
+}
+
+/**
+ * Validate a Turtle file against SHACL shapes.
+ */
+export function validateFile(
+  filePath: string,
+  shapesStore: Store,
+  shapeFiles: string[],
+): ValidationResult {
+  if (!fs.existsSync(filePath)) {
+    return {
+      valid: false,
+      file: filePath,
+      results: [{
+        severity: 'violation',
+        shape: '',
+        property: '',
+        message: `File not found: ${filePath}`,
+      }],
+      shapesUsed: [],
+      quadCount: 0,
+      subjects: [],
+    };
+  }
+
+  const content = fs.readFileSync(filePath, 'utf-8');
+  return validateTurtle(content, shapesStore, shapeFiles, filePath);
+}
+
+/**
+ * Recursively find all .ttl files in a directory.
+ */
+export function findTurtleFiles(dirPath: string): string[] {
+  const results: string[] = [];
+
+  function walk(dir: string): void {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        // Skip hidden directories and node_modules
+        if (!entry.name.startsWith('.') && entry.name !== 'node_modules') {
+          walk(fullPath);
+        }
+      } else if (entry.isFile() && entry.name.endsWith('.ttl')) {
+        results.push(fullPath);
+      }
+    }
+  }
+
+  walk(dirPath);
+  return results.sort();
+}

package/src/lib/turtle-parser.ts

@@ -0,0 +1,277 @@
+/**
+ * Turtle parsing utilities.
+ *
+ * Wraps the n3 library to provide Cascade-specific Turtle parsing
+ * with support for Cascade Protocol namespaces.
+ */
+
+import { Parser, Store, DataFactory } from 'n3';
+import type { Quad } from 'n3';
+import * as fs from 'fs/promises';
+
+const { namedNode } = DataFactory;
+
+/** Well-known RDF predicates */
+const RDF_TYPE_IRI = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type';
+
+/** Known Cascade Protocol namespace prefixes */
+export const CASCADE_NAMESPACES: Record<string, string> = {
+  core: 'https://ns.cascadeprotocol.org/core/v1#',
+  cascade: 'https://ns.cascadeprotocol.org/core/v1#',
+  health: 'https://ns.cascadeprotocol.org/health/v1#',
+  clinical: 'https://ns.cascadeprotocol.org/clinical/v1#',
+  pots: 'https://ns.cascadeprotocol.org/pots/v1#',
+  checkup: 'https://ns.cascadeprotocol.org/checkup/v1#',
+  coverage: 'https://ns.cascadeprotocol.org/coverage/v1#',
+} as const;
+
+/** Well-known non-Cascade namespaces for IRI shortening */
+const WELL_KNOWN_NAMESPACES: Record<string, string> = {
+  foaf: 'http://xmlns.com/foaf/0.1/',
+  solid: 'http://www.w3.org/ns/solid/terms#',
+  ldp: 'http://www.w3.org/ns/ldp#',
+  dct: 'http://purl.org/dc/terms/',
+  dcterms: 'http://purl.org/dc/terms/',
+  prov: 'http://www.w3.org/ns/prov#',
+  rdf: 'http://www.w3.org/1999/02/22-rdf-syntax-ns#',
+  xsd: 'http://www.w3.org/2001/XMLSchema#',
+  fhir: 'http://hl7.org/fhir/',
+  rxnorm: 'http://www.nlm.nih.gov/research/umls/rxnorm/',
+  sct: 'http://snomed.info/sct/',
+  loinc: 'http://loinc.org/rdf#',
+  icd10: 'http://hl7.org/fhir/sid/icd-10-cm/',
+  cvx: 'http://hl7.org/fhir/sid/cvx/',
+};
+
+export interface ParseResult {
+  success: boolean;
+  quads: Quad[];
+  store: Store;
+  quadCount: number;
+  prefixes: Record<string, string>;
+  errors: string[];
+  subjects: SubjectInfo[];
+}
+
+export interface SubjectInfo {
+  uri: string;
+  types: string[];
+}
+
+/**
+ * Parse a Turtle string into quads and a Store.
+ */
+export function parseTurtle(input: string, baseIRI?: string): ParseResult {
+  const parser = new Parser({ baseIRI: baseIRI ?? '' });
+  const store = new Store();
+  const prefixes: Record<string, string> = {};
+  const errors: string[] = [];
+
+  let quads: Quad[];
+  try {
+    quads = parser.parse(input, null, (prefix, prefixNode) => {
+      prefixes[prefix] = prefixNode.value;
+    });
+    store.addQuads(quads);
+  } catch (e: unknown) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return {
+      success: false,
+      quads: [],
+      store,
+      quadCount: 0,
+      prefixes,
+      errors: [msg],
+      subjects: [],
+    };
+  }
+
+  // Extract subjects with their types
+  const subjects = extractSubjectsWithTypes(store);
+
+  return {
+    success: true,
+    quads,
+    store,
+    quadCount: quads.length,
+    prefixes,
+    errors,
+    subjects,
+  };
+}
+
+/**
+ * Extract all subjects with their rdf:type values from a store.
+ */
+function extractSubjectsWithTypes(store: Store): SubjectInfo[] {
+  const subjectMap = new Map<string, string[]>();
+
+  const typeQuads = store.getQuads(null, namedNode(RDF_TYPE_IRI), null, null);
+  for (const quad of typeQuads) {
+    const subjectUri = quad.subject.value;
+    const typeUri = quad.object.value;
+    if (!subjectMap.has(subjectUri)) {
+      subjectMap.set(subjectUri, []);
+    }
+    subjectMap.get(subjectUri)!.push(typeUri);
+  }
+
+  return Array.from(subjectMap.entries()).map(([uri, types]) => ({ uri, types }));
+}
+
+/**
+ * Detect which Cascade Protocol vocabularies are used in a parsed Turtle file
+ * based on prefixes and type URIs.
+ */
+export function detectVocabularies(result: ParseResult): string[] {
+  const vocabs = new Set<string>();
+
+  // Check prefix declarations
+  for (const [, iri] of Object.entries(result.prefixes)) {
+    for (const [name, ns] of Object.entries(CASCADE_NAMESPACES)) {
+      if (iri === ns || iri.startsWith(ns.replace(/#$/, ''))) {
+        vocabs.add(name);
+      }
+    }
+  }
+
+  // Check type URIs
+  for (const subject of result.subjects) {
+    for (const typeUri of subject.types) {
+      for (const [name, ns] of Object.entries(CASCADE_NAMESPACES)) {
+        if (typeUri.startsWith(ns)) {
+          vocabs.add(name);
+        }
+      }
+    }
+  }
+
+  // Also scan all quads for namespace usage (predicates, objects)
+  for (const quad of result.quads) {
+    const values = [quad.predicate.value, quad.object.value];
+    for (const val of values) {
+      for (const [name, ns] of Object.entries(CASCADE_NAMESPACES)) {
+        if (val.startsWith(ns)) {
+          vocabs.add(name);
+        }
+      }
+    }
+  }
+
+  return Array.from(vocabs);
+}
+
+/**
+ * Parse a Turtle file from disk.
+ */
+export async function parseTurtleFile(filePath: string): Promise<ParseResult> {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return parseTurtle(content, `file://${filePath}`);
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      success: false,
+      quads: [],
+      store: new Store(),
+      quadCount: 0,
+      prefixes: {},
+      errors: [`Failed to read file ${filePath}: ${message}`],
+      subjects: [],
+    };
+  }
+}
+
+/**
+ * Return all subject URIs that have rdf:type matching the given type IRI.
+ */
+export function getSubjectsByType(store: Store, rdfType: string): string[] {
+  const subjects = store.getSubjects(namedNode(RDF_TYPE_IRI), namedNode(rdfType), null);
+  return subjects.map((s) => s.value);
+}
+
+/**
+ * Return all predicate-value pairs for a given subject.
+ * Returns a map of predicate IRI -> array of object values.
+ */
+export function getProperties(store: Store, subject: string): Record<string, string[]> {
+  const result: Record<string, string[]> = {};
+  const quads = store.getQuads(subject as never, null, null, null);
+
+  for (const quad of quads) {
+    const predicate = quad.predicate.value;
+    if (!result[predicate]) {
+      result[predicate] = [];
+    }
+    result[predicate].push(quad.object.value);
+  }
+
+  return result;
+}
+
+/**
+ * Count subjects of a given rdf:type.
+ */
+export function countSubjectsByType(store: Store, rdfType: string): number {
+  return store.countQuads(null, namedNode(RDF_TYPE_IRI), namedNode(rdfType), null);
+}
+
+/**
+ * Get all unique rdf:type values in the store.
+ */
+export function getAllTypes(store: Store): string[] {
+  const objects = store.getObjects(null, namedNode(RDF_TYPE_IRI), null);
+  const types = new Set<string>();
+  for (const obj of objects) {
+    types.add(obj.value);
+  }
+  return Array.from(types);
+}
+
+/**
+ * Shorten a full IRI using known Cascade namespace prefixes.
+ * Returns the prefixed form (e.g., "health:MedicationRecord") or the full IRI if no match.
+ */
+export function shortenIRI(iri: string, prefixes?: Record<string, string>): string {
+  const allPrefixes: Record<string, string> = {
+    ...CASCADE_NAMESPACES,
+    ...WELL_KNOWN_NAMESPACES,
+    ...(prefixes ?? {}),
+  };
+
+  for (const [prefix, namespace] of Object.entries(allPrefixes)) {
+    if (iri.startsWith(namespace)) {
+      return `${prefix}:${iri.slice(namespace.length)}`;
+    }
+  }
+  return iri;
+}
+
+/**
+ * Extract a human-readable label for a record from its properties.
+ * Tries common name predicates in order of preference.
+ */
+export function extractLabel(props: Record<string, string[]>): string | undefined {
+  const namePredicates = [
+    CASCADE_NAMESPACES.health + 'medicationName',
+    CASCADE_NAMESPACES.health + 'conditionName',
+    CASCADE_NAMESPACES.health + 'allergen',
+    CASCADE_NAMESPACES.clinical + 'supplementName',
+    CASCADE_NAMESPACES.clinical + 'vaccineName',
+    CASCADE_NAMESPACES.health + 'vaccineName',
+    CASCADE_NAMESPACES.health + 'testName',
+    CASCADE_NAMESPACES.health + 'labTestName',
+    CASCADE_NAMESPACES.clinical + 'planName',
+    CASCADE_NAMESPACES.cascade + 'planName',
+    'http://xmlns.com/foaf/0.1/name',
+    'http://xmlns.com/foaf/0.1/givenName',
+    'http://purl.org/dc/terms/title',
+  ];
+
+  for (const pred of namePredicates) {
+    if (props[pred]?.[0]) {
+      return props[pred][0];
+    }
+  }
+  return undefined;
+}