@relational-fabric/canon 1.0.0

package/src/types/radar.ts

@@ -0,0 +1,106 @@
+/**
+ * Technology Radar data structures and types
+ */
+
+import { type Expect, invariant } from '../testing.js'
+
+export interface RadarEntry {
+  /** The name of the technology or practice */
+  name: string
+  /** Description of the technology or practice */
+  description: string
+  /** Whether this is a new entry */
+  isNew: boolean
+  /** Optional justification for the placement */
+  justification?: string
+}
+
+export interface Quadrant {
+  /** Unique identifier for the quadrant */
+  id: string
+  /** Display name for the quadrant */
+  name: string
+  /** Description of what this quadrant represents */
+  description: string
+}
+
+export interface Ring {
+  /** Unique identifier for the ring */
+  id: string
+  /** Display name for the ring */
+  name: string
+  /** Description of what this ring represents */
+  description: string
+  /** Color code for the ring (hex format) */
+  color: string
+}
+
+export interface RadarMetadata {
+  /** Title of the radar */
+  title: string
+  /** Subtitle of the radar */
+  subtitle: string
+  /** Version of the radar data */
+  version: string
+  /** Last updated date */
+  lastUpdated: string
+  /** Optional description */
+  description?: string
+}
+
+export interface RadarData {
+  /** Metadata about the radar */
+  metadata: RadarMetadata
+  /** Quadrant definitions */
+  quadrants: Quadrant[]
+  /** Ring definitions */
+  rings: Ring[]
+  /** Radar entries organized by quadrant and ring */
+  entries: Record<string, Record<string, RadarEntry[]>>
+}
+
+export interface RadarConfig {
+  /** Configuration for the radar */
+  metadata: RadarMetadata
+  /** Quadrant configuration */
+  quadrants: Quadrant[]
+  /** Ring configuration */
+  rings: Ring[]
+  /** Build configuration */
+  buildConfig: {
+    csvOutput: string
+    yamlInput: string
+    includeMetadata: boolean
+    sortByRing: boolean
+  }
+}
+
+export interface CsvRow {
+  name: string
+  ring: string
+  quadrant: string
+  isNew: boolean
+  description: string
+}
+
+export type QuadrantKey =
+  | 'tools-libraries'
+  | 'techniques-patterns'
+  | 'features-capabilities'
+  | 'data-structures-formats'
+export type RingKey = 'adopt' | 'trial' | 'assess' | 'hold'
+
+// ---------------------------------------------------------------------------
+// Compile-time invariants
+// ---------------------------------------------------------------------------
+
+void invariant<Expect<RadarEntry['isNew'], boolean>>()
+void invariant<Expect<Quadrant['id'], string>>()
+void invariant<Expect<Ring['color'], string>>()
+void invariant<
+  Expect<
+    QuadrantKey,
+    'tools-libraries' | 'techniques-patterns' | 'features-capabilities' | 'data-structures-formats'
+  >
+>()
+void invariant<Expect<RingKey, 'adopt' | 'trial' | 'assess' | 'hold'>>()

package/src/utils/guards.test.ts

@@ -0,0 +1,27 @@
+/**
+ * Tests for type guard utilities
+ */
+
+import { describe, expect, it } from 'vitest'
+import { typeGuard } from './guards.js'
+
+describe('typeGuard', () => {
+  it('should convert predicate to TypeGuard', () => {
+    const isString = typeGuard<string>((v: unknown) => typeof v === 'string')
+
+    expect(isString('hello')).toBe(true)
+    expect(isString(123)).toBe(false)
+    expect(isString(null)).toBe(false)
+  })
+
+  it('should work with complex predicates', () => {
+    const hasId = typeGuard<{ id: string }>(
+      (v: unknown) =>
+        typeof v === 'object' && v !== null && 'id' in v && typeof (v as any).id === 'string',
+    )
+
+    expect(hasId({ id: '123' })).toBe(true)
+    expect(hasId({ name: 'test' })).toBe(false)
+    expect(hasId(null)).toBe(false)
+  })
+})

package/src/utils/guards.ts

@@ -0,0 +1,29 @@
+/**
+ * Type guard utility functions
+ */
+
+import type { Predicate, TypeGuard } from '../types/index.js'
+
+/**
+ * Convert a predicate function to a proper TypeGuard
+ *
+ * Accepts predicates (boolean-returning functions) and converts them to
+ * TypeGuards with proper overload signatures that discriminate types correctly.
+ *
+ * @param predicate - A boolean-returning predicate function
+ * @returns A TypeGuard with proper type discrimination
+ *
+ * @example
+ * ```typescript
+ * // Convert a simple predicate to a type guard
+ * const isString = typeGuard<string>(v => typeof v === 'string')
+ *
+ * // Use with object checks
+ * const hasId = typeGuard<{ id: string }>(v =>
+ *   isPojo(v) && 'id' in v && typeof v.id === 'string'
+ * )
+ * ```
+ */
+export function typeGuard<T>(predicate: Predicate<T>): TypeGuard<T> {
+  return predicate as TypeGuard<T>
+}

package/src/utils/objects.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Tests for object utilities
+ */
+
+import { describe, expect, it } from 'vitest'
+import {
+  isPojo,
+  objectEntries,
+  objectKeys,
+  objectValues,
+  pojoHas,
+  pojoHasOfType,
+  pojoWithOfType,
+} from './objects.js'
+
+describe('isPojo', () => {
+  it('should return true for plain objects', () => {
+    expect(isPojo({})).toBe(true)
+    expect(isPojo({ id: '123' })).toBe(true)
+    expect(isPojo({ nested: { value: 1 } })).toBe(true)
+  })
+
+  it('should return false for arrays', () => {
+    expect(isPojo([])).toBe(false)
+    expect(isPojo([1, 2, 3])).toBe(false)
+  })
+
+  it('should return false for null', () => {
+    expect(isPojo(null)).toBe(false)
+  })
+
+  it('should return false for primitives', () => {
+    expect(isPojo('string')).toBe(false)
+    expect(isPojo(123)).toBe(false)
+    expect(isPojo(true)).toBe(false)
+    expect(isPojo(undefined)).toBe(false)
+  })
+
+  it('should return false for class instances', () => {
+    class MyClass {}
+    expect(isPojo(new MyClass())).toBe(false)
+    expect(isPojo(new Date())).toBe(false)
+    expect(isPojo(new Map())).toBe(false)
+  })
+
+  it('should return false for objects with custom prototypes', () => {
+    const customProto = Object.create({ custom: true })
+    expect(isPojo(customProto)).toBe(false)
+  })
+})
+
+describe('pojoHas', () => {
+  it('should return true when property exists', () => {
+    const obj = { id: '123', name: 'Test' }
+    expect(pojoHas(obj, 'id')).toBe(true)
+    expect(pojoHas(obj, 'name')).toBe(true)
+  })
+
+  it('should return false when property does not exist', () => {
+    const obj = { id: '123' }
+    expect(pojoHas(obj, 'missing')).toBe(false)
+  })
+})
+
+describe('pojoHasOfType', () => {
+  it('should return true for object with string field', () => {
+    expect(pojoHasOfType({ id: '123' }, 'id', 'string')).toBe(true)
+    expect(pojoHasOfType({ '@id': 'uri' }, '@id', 'string')).toBe(true)
+  })
+
+  it('should return false for non-string field when checking for string', () => {
+    expect(pojoHasOfType({ id: 123 }, 'id', 'string')).toBe(false)
+    expect(pojoHasOfType({ id: null }, 'id', 'string')).toBe(false)
+  })
+
+  it('should return false for missing field', () => {
+    expect(pojoHasOfType({ name: 'test' }, 'id', 'string')).toBe(false)
+  })
+
+  it('should return false for non-objects', () => {
+    expect(pojoHasOfType('string', 'id', 'string')).toBe(false)
+    expect(pojoHasOfType(null, 'id', 'string')).toBe(false)
+  })
+
+  it('should work with number type', () => {
+    expect(pojoHasOfType({ count: 123 }, 'count', 'number')).toBe(true)
+    expect(pojoHasOfType({ count: '123' }, 'count', 'number')).toBe(false)
+  })
+
+  it('should work with boolean type', () => {
+    expect(pojoHasOfType({ active: true }, 'active', 'boolean')).toBe(true)
+    expect(pojoHasOfType({ active: 'true' }, 'active', 'boolean')).toBe(false)
+  })
+
+  it('should work with object type', () => {
+    expect(pojoHasOfType({ meta: { nested: true } }, 'meta', 'object')).toBe(true)
+    expect(pojoHasOfType({ meta: 'string' }, 'meta', 'object')).toBe(false)
+  })
+})
+
+describe('pojoWithOfType', () => {
+  it('should create reusable type guard for string fields', () => {
+    const hasStringId = pojoWithOfType('id', 'string')
+    expect(hasStringId({ id: '123' })).toBe(true)
+    expect(hasStringId({ id: 123 })).toBe(false)
+    expect(hasStringId({ name: 'test' })).toBe(false)
+  })
+
+  it('should create reusable type guard for number fields', () => {
+    const hasNumberCount = pojoWithOfType('count', 'number')
+    expect(hasNumberCount({ count: 42 })).toBe(true)
+    expect(hasNumberCount({ count: '42' })).toBe(false)
+  })
+})
+
+describe('objectKeys', () => {
+  it('should return typed keys', () => {
+    const obj = { a: 1, b: 2, c: 3 }
+    const keys = objectKeys(obj)
+    expect(keys).toEqual(['a', 'b', 'c'])
+  })
+})
+
+describe('objectValues', () => {
+  it('should return values', () => {
+    const obj = { a: 1, b: 2, c: 3 }
+    const values = objectValues(obj)
+    expect(values).toEqual([1, 2, 3])
+  })
+})
+
+describe('objectEntries', () => {
+  it('should return entries', () => {
+    const obj = { a: 1, b: 2 }
+    const entries = objectEntries(obj)
+    expect(entries).toEqual([
+      ['a', 1],
+      ['b', 2],
+    ])
+  })
+})

package/src/utils/objects.ts

@@ -0,0 +1,172 @@
+/**
+ * Object utilities for Canon
+ *
+ * Helpers for working with plain JavaScript objects.
+ */
+
+import type { JsType, JsTypeName, Pojo, PojoWith, TypeGuard } from '../types/index.js'
+import { typeGuard } from './guards.js'
+
+/**
+ * Re-export types for convenience
+ */
+export type { Pojo, PojoWith }
+
+/**
+ * Type guard to check if a value is a plain JavaScript object
+ *
+ * @example
+ * ```typescript
+ * isPojo({ id: '123' }) // true
+ * isPojo([1, 2, 3]) // false
+ * isPojo(null) // false
+ * isPojo('string') // false
+ * ```
+ */
+export const isPojo = typeGuard<Pojo>(
+  (value: unknown) =>
+    typeof value === 'object'
+    && value !== null
+    && !Array.isArray(value)
+    && Object.getPrototypeOf(value) === Object.prototype,
+)
+
+/**
+ * Create a type guard for Pojo with a specific property
+ *
+ * Higher-order function that returns a reusable TypeGuard.
+ *
+ * @param key - The property name to check for
+ * @returns TypeGuard that checks if value is a Pojo with that property
+ *
+ * @example
+ * ```typescript
+ * const hasId = pojoWith('id')
+ * hasId({ id: '123' }) // true
+ * hasId({ name: 'test' }) // false
+ * ```
+ */
+export function pojoWith<K extends string>(key: K): TypeGuard<PojoWith<Pojo, K, unknown>> {
+  return typeGuard((value: unknown) => isPojo(value) && key in value)
+}
+
+/**
+ * Convenience function to check if a Pojo has a specific property
+ *
+ * Uses pojoWith() internally.
+ *
+ * @param obj - The object to check
+ * @param key - The property name to look for
+ * @returns True if the object has the property
+ *
+ * @example
+ * ```typescript
+ * const data = { id: '123', name: 'Test' }
+ * pojoHas(data, 'id') // true
+ * pojoHas(data, 'missing') // false
+ * ```
+ */
+export function pojoHas<T extends Pojo, K extends string>(
+  obj: T | unknown,
+  key: K,
+): obj is PojoWith<T, K, unknown> {
+  return pojoWith(key)(obj)
+}
+
+export function pojoWithOfType<K extends string, V extends JsTypeName>(
+  key: K,
+  type: V,
+): TypeGuard<PojoWith<Pojo, K, JsType[V]>> {
+  return typeGuard((value: unknown) => {
+    if (!pojoHas(value, key)) {
+      return false
+    }
+    const valueType: JsTypeName = typeof value[key] // Needs to be seperate because we're not using a string literal
+    return valueType === type
+  })
+}
+
+/**
+ * Convenience function to check if a value has a specific string field
+ *
+ * @param value - The value to check
+ * @param key - The field name that should contain a string
+ * @returns True if value is a Pojo with the specified string field
+ *
+ * @example
+ * ```typescript
+ * pojoHasString({ id: '123' }, 'id') // true
+ * pojoHasString({ id: 123 }, 'id') // false
+ * pojoHasString('not object', 'id') // false
+ * ```
+ */
+export function pojoHasOfType<T extends Pojo, K extends string, V extends JsTypeName>(
+  value: T | unknown,
+  key: K,
+  type: V,
+): value is PojoWith<T, K, JsType[V]> {
+  return pojoWithOfType(key, type)(value)
+}
+
+/**
+ * Type-safe Object.keys that handles both objects and arrays correctly
+ *
+ * For arrays, returns numeric indices. For objects, returns property keys.
+ *
+ * @param obj - The object to get keys from
+ * @returns Array of object keys
+ *
+ * @example
+ * ```typescript
+ * objectKeys({ a: 1, b: 2 }) // ['a', 'b']
+ * objectKeys([1, 2, 3]) // [0, 1, 2]
+ * ```
+ */
+export function objectKeys<T extends object>(obj: T): Array<keyof T> {
+  if (Array.isArray(obj)) {
+    return Array.from(obj.keys()) as Array<keyof T>
+  }
+  return Object.keys(obj) as Array<keyof T>
+}
+
+/**
+ * Type-safe Object.values that handles both objects and arrays correctly
+ *
+ * For arrays, returns array values. For objects, returns property values.
+ *
+ * @param obj - The object to get values from
+ * @returns Array of object values
+ *
+ * @example
+ * ```typescript
+ * objectValues({ a: 1, b: 2 }) // [1, 2]
+ * objectValues([1, 2, 3]) // [1, 2, 3]
+ * ```
+ */
+export function objectValues<T extends object>(obj: T): unknown[] {
+  if (Array.isArray(obj)) {
+    return Array.from(obj)
+  }
+  return Object.values(obj)
+}
+
+/**
+ * Type-safe Object.entries that handles both objects and arrays correctly
+ *
+ * For arrays, returns [index, value] pairs. For objects, returns [key, value] pairs.
+ *
+ * @param obj - The object to get entries from
+ * @returns Array of [key, value] tuples
+ *
+ * @example
+ * ```typescript
+ * objectEntries({ a: 1, b: 2 }) // [['a', 1], ['b', 2]]
+ * objectEntries([1, 2, 3]) // [[0, 1], [1, 2], [2, 3]]
+ * ```
+ */
+export function objectEntries<T extends object>(obj: T): Array<[keyof T, T[keyof T]]> {
+  if (Array.isArray(obj)) {
+    return Array.from(obj.entries()) as Array<[keyof T, T[keyof T]]>
+  }
+  return Object.entries(obj) as Array<[keyof T, T[keyof T]]>
+}

package/tsconfig.base.json

@@ -0,0 +1,11 @@
+{
+  "extends": "@tsconfig/node-lts/tsconfig.json",
+  "compilerOptions": {
+    "resolveJsonModule": true,
+    "strict": true,
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true
+  }
+}