@relational-fabric/canon 1.0.0

package/src/axioms/timestamps.ts

@@ -0,0 +1,77 @@
+/**
+ * Timestamps axiom implementation
+ *
+ * Provides universal access to timestamp data with format conversion.
+ */
+
+import type { RepresentationAxiom, Satisfies } from '../types/index.js'
+import { inferAxiom } from '../axiom.js'
+
+/**
+ * Register Timestamps axiom in global Axioms interface
+ */
+declare module '@relational-fabric/canon' {
+  interface Axioms {
+    /**
+     * Timestamps concept - might be number, string, Date, etc.
+     */
+    Timestamps: RepresentationAxiom<number | string | Date, Date>
+  }
+}
+
+/**
+ * Check if a value is a canonical timestamp (Date object)
+ *
+ * @param value - The value to check
+ * @returns True if the value is a Date object
+ */
+export function isCanonicalTimestamp(value: number | string | Date): value is Date {
+  return value instanceof Date
+}
+
+/**
+ * Extract and convert timestamp data to canonical Date format
+ *
+ * @param x - The timestamp value to convert
+ * @returns The timestamp as a Date object
+ *
+ * @example
+ * ```typescript
+ * const unixTimestamp = 1640995200000
+ * const isoTimestamp = '2022-01-01T00:00:00Z'
+ * const dateTimestamp = new Date('2022-01-01')
+ *
+ * console.log(timestampsOf(unixTimestamp)) // Converted to canonical Date
+ * console.log(timestampsOf(isoTimestamp)) // Converted to canonical Date
+ * console.log(timestampsOf(dateTimestamp)) // Already canonical Date
+ * ```
+ */
+export function timestampsOf<T extends Satisfies<'Timestamps'>>(x: T): Date {
+  const config = inferAxiom('Timestamps', x)
+
+  if (!config) {
+    throw new Error('No matching canon found for Timestamps axiom')
+  }
+
+  // Check if already canonical
+  if (isCanonicalTimestamp(x)) {
+    return x
+  }
+
+  // Convert to canonical format
+  if (typeof x === 'number') {
+    // Assume Unix timestamp in milliseconds
+    return new Date(x)
+  }
+
+  if (typeof x === 'string') {
+    // Try to parse as ISO string or other date format
+    const date = new Date(x)
+    if (Number.isNaN(date.getTime())) {
+      throw new TypeError(`Invalid date string: ${x}`)
+    }
+    return date
+  }
+
+  throw new TypeError(`Expected number, string, or Date, got ${typeof x}`)
+}

package/src/axioms/type.ts

@@ -0,0 +1,53 @@
+/**
+ * Type axiom implementation
+ *
+ * Provides universal access to entity classification across different data formats.
+ */
+
+import type { KeyNameAxiom, Satisfies } from '../types/index.js'
+import { inferAxiom } from '../axiom.js'
+
+/**
+ * Register Type axiom in global Axioms interface
+ */
+declare module '@relational-fabric/canon' {
+  interface Axioms {
+    /**
+     * Type concept - might be 'type', '@type', '_type', etc.
+     */
+    Type: KeyNameAxiom
+  }
+}
+
+/**
+ * Extract the type value from any entity that satisfies the Type axiom
+ *
+ * @param x - The entity to extract type from
+ * @returns The type value as a string
+ *
+ * @example
+ * ```typescript
+ * const data = { type: 'user', name: 'Test' }
+ * const type = typeOf(data) // "user"
+ * ```
+ */
+export function typeOf<T extends Satisfies<'Type'>>(x: T): string {
+  const config = inferAxiom('Type', x)
+
+  if (!config) {
+    throw new Error('No matching canon found for Type axiom')
+  }
+
+  // For KeyNameAxiom, extract using the key field
+  if ('key' in config && typeof config.key === 'string') {
+    const value = (x as Record<string, unknown>)[config.key]
+
+    if (typeof value !== 'string') {
+      throw new TypeError(`Expected string type, got ${typeof value}`)
+    }
+
+    return value
+  }
+
+  throw new Error('Invalid Type axiom configuration')
+}

package/src/axioms/version.ts

@@ -0,0 +1,53 @@
+/**
+ * Version axiom implementation
+ *
+ * Provides universal access to version information across different data formats.
+ */
+
+import type { KeyNameAxiom, Satisfies } from '../types/index.js'
+import { inferAxiom } from '../axiom.js'
+
+/**
+ * Register Version axiom in global Axioms interface
+ */
+declare module '@relational-fabric/canon' {
+  interface Axioms {
+    /**
+     * Version concept - might be 'version', '@version', '_version', etc.
+     */
+    Version: KeyNameAxiom
+  }
+}
+
+/**
+ * Extract the version value from any entity that satisfies the Version axiom
+ *
+ * @param x - The entity to extract version from
+ * @returns The version value as a string or number
+ *
+ * @example
+ * ```typescript
+ * const data = { version: 5, name: 'Test' }
+ * const version = versionOf(data) // 5
+ * ```
+ */
+export function versionOf<T extends Satisfies<'Version'>>(x: T): string | number {
+  const config = inferAxiom('Version', x)
+
+  if (!config) {
+    throw new Error('No matching canon found for Version axiom')
+  }
+
+  // For KeyNameAxiom, extract using the key field
+  if ('key' in config && typeof config.key === 'string') {
+    const value = (x as Record<string, unknown>)[config.key]
+
+    if (typeof value !== 'string' && typeof value !== 'number') {
+      throw new TypeError(`Expected string or number version, got ${typeof value}`)
+    }
+
+    return value
+  }
+
+  throw new Error('Invalid Version axiom configuration')
+}

package/src/canon.ts

@@ -0,0 +1,47 @@
+/**
+ * Canon API functions
+ */
+
+import type { CanonConfig } from './types/index.js'
+import { getRegistry } from './shell.js'
+
+/**
+ * Infer which canon matches a value
+ *
+ * Finds the canon with the MOST matching axioms for the value.
+ * If multiple canons match the same number of axioms, returns the first.
+ *
+ * @param value - The value to check
+ * @returns The best matching canon config or undefined
+ *
+ * @example
+ * ```typescript
+ * const canon = inferCanon({ id: 'test-123' })
+ * const jsonLdCanon = inferCanon({ '@id': 'uri' })
+ * ```
+ */
+export function inferCanon(value: unknown): CanonConfig | undefined {
+  const registry = getRegistry()
+
+  let bestCanon: CanonConfig | undefined
+  let maxMatches = 0
+
+  for (const canonConfig of registry) {
+    let matches = 0
+
+    // Count how many axioms match
+    for (const axiomConfig of Object.values(canonConfig.axioms)) {
+      if (axiomConfig.$basis(value)) {
+        matches++
+      }
+    }
+
+    // Keep the canon with the most matches
+    if (matches > maxMatches) {
+      maxMatches = matches
+      bestCanon = canonConfig
+    }
+  }
+
+  return maxMatches > 0 ? bestCanon : undefined
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+// Axiom and Canon APIs
+export * from './axiom.js'
+// Specific Axioms
+export * from './axioms/id.js'
+export * from './axioms/references.js'
+export * from './axioms/timestamps.js'
+export * from './axioms/type.js'
+export * from './axioms/version.js'
+
+export * from './canon.js'
+
+// Radar
+export * from './radar/index.js'
+
+// Registry and Shell
+export * from './registry.js'
+export * from './shell.js'
+
+// Type testing utilities (compile-time helpers only)
+export * from './testing.js'
+
+// Type system (includes defineAxiom, defineCanon)
+export * from './types/index.js'
+
+// Utilities
+export * from './utils/guards.js'
+export * from './utils/objects.js'
+
+// Re-export utility libraries used internally
+export { defu } from 'defu'

package/src/radar/converter.ts

@@ -0,0 +1,124 @@
+/**
+ * Technology Radar data conversion utilities
+ */
+
+import type { CsvRow, QuadrantKey, RadarData, RingKey } from '../types/radar.js'
+
+import { readFileSync, writeFileSync } from 'node:fs'
+import process from 'node:process'
+import { parse } from 'yaml'
+
+// Quadrant mapping for CSV output
+const QUADRANT_MAP: Record<QuadrantKey, string> = {
+  'tools-libraries': 'Tools & Libraries',
+  'techniques-patterns': 'Techniques & Patterns',
+  'features-capabilities': 'Features & Capabilities',
+  'data-structures-formats': 'Data Structures, Formats & Standards',
+}
+
+// Ring mapping for CSV output
+const RING_MAP: Record<RingKey, string> = {
+  adopt: 'Adopt',
+  trial: 'Trial',
+  assess: 'Assess',
+  hold: 'Hold',
+}
+
+/**
+ * Convert YAML radar data to CSV format
+ */
+export function convertYamlToCsv(yamlContent: string): string {
+  const data = parse(yamlContent) as RadarData
+
+  // Generate CSV content
+  const csvRows: string[] = ['name,ring,quadrant,isNew,description']
+
+  // Process each quadrant in the entries section
+  Object.entries(data.entries).forEach(([quadrantKey, quadrantData]) => {
+    const quadrantName = QUADRANT_MAP[quadrantKey as QuadrantKey] || quadrantKey
+
+    // Process each ring in the quadrant
+    Object.entries(quadrantData).forEach(([ringKey, items]) => {
+      const ringName = RING_MAP[ringKey as RingKey] || ringKey
+
+      // Process each item in the ring
+      ;(items as any[]).forEach((item: any) => {
+        const row: CsvRow = {
+          name: item.name,
+          ring: ringName,
+          quadrant: quadrantName,
+          isNew: item.isNew,
+          description: item.description,
+        }
+
+        csvRows.push(formatCsvRow(row))
+      })
+    })
+  })
+
+  return csvRows.join('\n')
+}
+
+/**
+ * Convert radar data from file paths
+ */
+export function convertYamlFileToCsv(yamlPath: string, csvPath: string): void {
+  try {
+    // Read and parse YAML file
+    const yamlContent = readFileSync(yamlPath, 'utf8')
+    const csvContent = convertYamlToCsv(yamlContent)
+
+    // Write CSV file
+    writeFileSync(csvPath, csvContent)
+    // Success: Converted YAML to CSV
+  } catch (error) {
+    console.error(
+      '❌ Error converting YAML to CSV:',
+      error instanceof Error ? error.message : 'Unknown error',
+    )
+    process.exit(1)
+  }
+}
+
+/**
+ * Format a CSV row with proper escaping
+ */
+function formatCsvRow(row: CsvRow): string {
+  return [
+    escapeCsvField(row.name),
+    escapeCsvField(row.ring),
+    escapeCsvField(row.quadrant),
+    row.isNew ? 'true' : 'false',
+    escapeCsvField(row.description),
+  ].join(',')
+}
+
+/**
+ * Escape CSV field values
+ */
+function escapeCsvField(field: string): string {
+  if (typeof field !== 'string')
+    return String(field)
+
+  // Escape quotes and wrap in quotes if contains comma, quote, or newline
+  if (field.includes('"') || field.includes(',') || field.includes('\n')) {
+    return `"${field.replace(/"/g, '""')}"`
+  }
+
+  return field
+}
+
+/**
+ * Parse YAML radar data
+ */
+export function parseRadarYaml(yamlContent: string): RadarData {
+  return parse(yamlContent) as RadarData
+}
+
+/**
+ * Read and parse radar YAML file
+ */
+export function readRadarYaml(yamlPath: string): RadarData {
+  const yamlContent = readFileSync(yamlPath, 'utf8')
+  return parseRadarYaml(yamlContent)
+}

package/src/radar/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Technology Radar utilities
+ *
+ * This module provides utilities for working with technology radar data,
+ * including conversion between YAML and CSV formats, validation, and
+ * data manipulation.
+ */
+
+export * from '../types/radar.js'
+export * from './converter.js'
+export * from './validator.js'

package/src/radar/validator.ts

@@ -0,0 +1,310 @@
+/**
+ * Technology Radar data validation utilities
+ */
+
+import type { QuadrantKey, RadarData, RingKey } from '../types/radar.js'
+
+const VALID_QUADRANTS: QuadrantKey[] = [
+  'tools-libraries',
+  'techniques-patterns',
+  'features-capabilities',
+  'data-structures-formats',
+]
+const VALID_RINGS: RingKey[] = ['adopt', 'trial', 'assess', 'hold']
+
+export interface ValidationError {
+  type: 'missing_field' | 'invalid_value' | 'duplicate_entry' | 'invalid_structure'
+  message: string
+  path?: string
+}
+
+export interface ValidationResult {
+  isValid: boolean
+  errors: ValidationError[]
+  warnings: string[]
+}
+
+/**
+ * Validate radar data structure
+ */
+export function validateRadarData(data: any): ValidationResult {
+  const errors: ValidationError[] = []
+  const warnings: string[] = []
+
+  // Validate metadata
+  if (!data.metadata) {
+    errors.push({
+      type: 'missing_field',
+      message: 'Missing metadata section',
+      path: 'metadata',
+    })
+  } else {
+    validateMetadata(data.metadata, errors)
+  }
+
+  // Validate the entries section
+  if (!data.entries) {
+    errors.push({
+      type: 'missing_field',
+      message: 'Missing entries section',
+      path: 'entries',
+    })
+  } else {
+    validateEntries(data.entries, errors, warnings)
+  }
+
+  return {
+    isValid: errors.length === 0,
+    errors,
+    warnings,
+  }
+}
+
+/**
+ * Validate metadata section
+ */
+function validateMetadata(metadata: any, errors: ValidationError[]): void {
+  const requiredFields = ['title', 'subtitle', 'version', 'lastUpdated']
+
+  for (const field of requiredFields) {
+    if (!metadata[field] || typeof metadata[field] !== 'string') {
+      errors.push({
+        type: 'missing_field',
+        message: `Missing or invalid ${field} in metadata`,
+        path: `metadata.${field}`,
+      })
+    }
+  }
+
+  // Validate version format
+  if (metadata.version && !/^\d+\.\d+\.\d+/.test(metadata.version)) {
+    errors.push({
+      type: 'invalid_value',
+      message: 'Version should follow semantic versioning (e.g., 1.0.0)',
+      path: 'metadata.version',
+    })
+  }
+
+  // Validate date format
+  if (metadata.lastUpdated && !/^\d{4}-\d{2}-\d{2}/.test(metadata.lastUpdated)) {
+    errors.push({
+      type: 'invalid_value',
+      message: 'Last updated should be in YYYY-MM-DD format',
+      path: 'metadata.lastUpdated',
+    })
+  }
+}
+
+/**
+ * Validate quadrants section
+ */
+function _validateQuadrants(quadrants: any[], errors: ValidationError[]): void {
+  const quadrantIds = new Set<string>()
+
+  quadrants.forEach((quadrant, index) => {
+    if (!quadrant.id || typeof quadrant.id !== 'string') {
+      errors.push({
+        type: 'missing_field',
+        message: `Missing or invalid id in quadrant ${index}`,
+        path: `quadrants[${index}].id`,
+      })
+    } else if (quadrantIds.has(quadrant.id)) {
+      errors.push({
+        type: 'duplicate_entry',
+        message: `Duplicate quadrant id: ${quadrant.id}`,
+        path: `quadrants[${index}].id`,
+      })
+    } else {
+      quadrantIds.add(quadrant.id)
+    }
+
+    if (!quadrant.name || typeof quadrant.name !== 'string') {
+      errors.push({
+        type: 'missing_field',
+        message: `Missing or invalid name in quadrant ${index}`,
+        path: `quadrants[${index}].name`,
+      })
+    }
+
+    if (!quadrant.description || typeof quadrant.description !== 'string') {
+      errors.push({
+        type: 'missing_field',
+        message: `Missing or invalid description in quadrant ${index}`,
+        path: `quadrants[${index}].description`,
+      })
+    }
+  })
+}
+
+/**
+ * Validate rings section
+ */
+function _validateRings(rings: any[], errors: ValidationError[]): void {
+  const ringIds = new Set<string>()
+
+  rings.forEach((ring, index) => {
+    if (!ring.id || typeof ring.id !== 'string') {
+      errors.push({
+        type: 'missing_field',
+        message: `Missing or invalid id in ring ${index}`,
+        path: `rings[${index}].id`,
+      })
+    } else if (ringIds.has(ring.id)) {
+      errors.push({
+        type: 'duplicate_entry',
+        message: `Duplicate ring id: ${ring.id}`,
+        path: `rings[${index}].id`,
+      })
+    } else {
+      ringIds.add(ring.id)
+    }
+
+    if (!ring.name || typeof ring.name !== 'string') {
+      errors.push({
+        type: 'missing_field',
+        message: `Missing or invalid name in ring ${index}`,
+        path: `rings[${index}].name`,
+      })
+    }
+
+    if (!ring.description || typeof ring.description !== 'string') {
+      errors.push({
+        type: 'missing_field',
+        message: `Missing or invalid description in ring ${index}`,
+        path: `rings[${index}].description`,
+      })
+    }
+
+    if (!ring.color || typeof ring.color !== 'string' || !/^#[0-9a-f]{6}$/i.test(ring.color)) {
+      errors.push({
+        type: 'invalid_value',
+        message: `Invalid color format in ring ${index}. Should be hex color (e.g., #93c47d)`,
+        path: `rings[${index}].color`,
+      })
+    }
+  })
+}
+
+/**
+ * Validate entries section
+ */
+function validateEntries(entries: any, errors: ValidationError[], warnings: string[]): void {
+  const entryNames = new Set<string>()
+
+  Object.entries(entries).forEach(([quadrantKey, quadrantData]) => {
+    if (quadrantKey === 'metadata')
+      return // Skip metadata
+
+    if (!VALID_QUADRANTS.includes(quadrantKey as QuadrantKey)) {
+      warnings.push(`Unknown quadrant: ${quadrantKey}`)
+    }
+
+    if (typeof quadrantData !== 'object' || quadrantData === null) {
+      errors.push({
+        type: 'invalid_structure',
+        message: `Invalid quadrant data for ${quadrantKey}`,
+        path: `entries.${quadrantKey}`,
+      })
+      return
+    }
+
+    Object.entries(quadrantData).forEach(([ringKey, items]) => {
+      if (!VALID_RINGS.includes(ringKey as RingKey)) {
+        warnings.push(`Unknown ring: ${ringKey} in quadrant ${quadrantKey}`)
+      }
+
+      if (!Array.isArray(items)) {
+        errors.push({
+          type: 'invalid_structure',
+          message: `Invalid ring data for ${ringKey} in quadrant ${quadrantKey}`,
+          path: `entries.${quadrantKey}.${ringKey}`,
+        })
+        return
+      }
+
+      items.forEach((item: any, index: number) => {
+        validateRadarEntry(item, errors, warnings, `${quadrantKey}.${ringKey}[${index}]`)
+
+        // Check for duplicate names
+        if (item.name && entryNames.has(item.name)) {
+          errors.push({
+            type: 'duplicate_entry',
+            message: `Duplicate entry name: ${item.name}`,
+            path: `entries.${quadrantKey}.${ringKey}[${index}].name`,
+          })
+        } else if (item.name) {
+          entryNames.add(item.name)
+        }
+      })
+    })
+  })
+}
+
+/**
+ * Validate individual radar entry
+ */
+function validateRadarEntry(
+  entry: any,
+  errors: ValidationError[],
+  warnings: string[],
+  path: string,
+): void {
+  if (!entry.name || typeof entry.name !== 'string') {
+    errors.push({
+      type: 'missing_field',
+      message: 'Missing or invalid name',
+      path: `entries.${path}.name`,
+    })
+  }
+
+  if (!entry.description || typeof entry.description !== 'string') {
+    errors.push({
+      type: 'missing_field',
+      message: 'Missing or invalid description',
+      path: `entries.${path}.description`,
+    })
+  }
+
+  if (typeof entry.isNew !== 'boolean') {
+    errors.push({
+      type: 'missing_field',
+      message: 'Missing or invalid isNew field',
+      path: `entries.${path}.isNew`,
+    })
+  }
+
+  if (entry.justification && typeof entry.justification !== 'string') {
+    errors.push({
+      type: 'invalid_value',
+      message: 'Justification must be a string',
+      path: `entries.${path}.justification`,
+    })
+  }
+}
+
+/**
+ * Validate radar data from file
+ */
+export async function validateRadarFile(filePath: string): Promise<ValidationResult> {
+  try {
+    const fs = await import('node:fs')
+    const yaml = await import('yaml')
+
+    const yamlContent = fs.readFileSync(filePath, 'utf8')
+    const data = yaml.parse(yamlContent) as RadarData
+
+    return validateRadarData(data)
+  } catch (error) {
+    return {
+      isValid: false,
+      errors: [
+        {
+          type: 'invalid_structure',
+          message: `Failed to parse file: ${error instanceof Error ? error.message : 'Unknown error'}`,
+          path: filePath,
+        },
+      ],
+      warnings: [],
+    }
+  }
+}