@relational-fabric/canon 1.0.0 → 1.2.0

package/README.md

@@ -183,7 +183,7 @@ Universal APIs provide functions that work across all registered canons. They ar
 - Automatic adaptation to different data shapes
 - Full type safety maintained across all shapes
 
-See [reference/api.md](reference/api.md) for available APIs.
+See [docs/reference/api.md](docs/reference/api.md) for available APIs.
 
 ## Package Exports
 
@@ -306,11 +306,11 @@ Canon provides comprehensive documentation to help you understand and use the sy
 
 ### Reference Documentation
 
-- **[API Reference](reference/api.md)** - Complete API documentation
-- **[Core Axioms](reference/axioms.md)** - Detailed axiom specifications
-- **[Canons Reference](reference/canons.md)** - Canon implementation guide
+- **[API Reference](docs/reference/api.md)** - Complete API documentation
+- **[Core Axioms](docs/reference/axioms.md)** - Detailed axiom specifications
+- **[Canons Reference](docs/reference/canons.md)** - Canon implementation guide
 - **[Type Testing Utilities](docs/type-testing/)** - Compile-time type assertions and invariants
-- **[Third-Party Integrations](reference/third-party.md)** - External library integrations
+- **[Canon Kit & Third-Party Utilities](docs/reference/kit.md)** - Curated third-party surface and transparent access paths
 
 ### Examples
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@relational-fabric/canon",
   "type": "module",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "A modern TypeScript package template with ESLint and TypeScript configurations for starting new projects",
   "author": "Relational Fabric",
   "license": "MIT",
@@ -24,6 +24,14 @@
       "types": "./src/index.ts",
       "import": "./src/index.ts"
     },
+    "./_/*": {
+      "types": "./src/_/*.ts",
+      "import": "./src/_/*.ts"
+    },
+    "./index": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
     "./radar": {
       "types": "./src/radar/index.ts",
       "import": "./src/radar/index.ts"
@@ -85,33 +93,37 @@
     }
   },
   "dependencies": {
-    "@antfu/eslint-config": "^3.0.0",
-    "@tsconfig/node-lts": "^20.0.0",
-    "yaml": "^2.4.1"
+    "@antfu/eslint-config": "^6.2.0",
+    "@tsconfig/node-lts": "^22.0.2",
+    "immutable": "^5.1.4",
+    "object-hash": "^3.0.0",
+    "reflect-metadata": "^0.2.2",
+    "yaml": "^2.8.1"
   },
   "optionalDependencies": {
     "defu": "^6.1.4"
   },
   "devDependencies": {
     "@types/mdast": "^4.0.4",
-    "@types/node": "^24.7.1",
-    "@vitest/coverage-v8": "^3.2.4",
+    "@types/node": "^24.10.0",
+    "@vitest/coverage-v8": "^4.0.8",
     "adr-tools": "^2.0.4",
     "chokidar-cli": "^3.0.0",
     "dedent": "^1.7.0",
     "depcheck": "^1.4.7",
-    "eslint": "^9.10.0",
+    "eslint": "^9.39.1",
     "husky": "^9.1.7",
     "lint-staged": "^16.2.6",
+    "npm-check-updates": "^19.1.2",
     "npm-run-all": "^4.1.5",
     "remark": "^15.0.1",
     "remark-parse": "^11.0.0",
     "remark-stringify": "^11.0.0",
-    "tsx": "^4.7.0",
-    "typescript": "^5.4.0",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3",
     "unified": "^11.0.5",
-    "vitepress": "^1.0.0",
-    "vitest": "^3.2.4"
+    "vitepress": "^1.6.4",
+    "vitest": "^4.0.8"
   },
   "husky": {
     "hooks": {

package/src/_/antfu.ts

@@ -0,0 +1,2 @@
+export { default } from '@antfu/eslint-config'
+export * from '@antfu/eslint-config'

package/src/_/defu.ts

@@ -0,0 +1,2 @@
+export { default } from 'defu'
+export * from 'defu'

package/src/_/immutable.ts

@@ -0,0 +1,4 @@
+import ImmutableNamespace from 'immutable'
+
+export default ImmutableNamespace
+export const Immutable = ImmutableNamespace

package/src/_/object-hash.ts

@@ -0,0 +1,2 @@
+export { default } from 'object-hash'
+export * from 'object-hash'

package/src/_/yaml.ts

@@ -0,0 +1 @@
+export * from 'yaml'

package/src/index.ts

@@ -9,22 +9,25 @@ export * from './axioms/version.js'
 
 export * from './canon.js'
 
+// Opinionated kit exports
+export * from './kit.js'
+
+// Metadata helpers
+export * from './meta.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'
+export * from './utils/objects.js'

package/src/kit.ts

@@ -0,0 +1,21 @@
+import ImmutableNamespace from 'immutable'
+import * as eslintModule from '../eslint.js'
+
+type CreateEslintConfig = (
+  options?: Record<string, unknown>,
+  ...configs: Record<string, unknown>[]
+) => Record<string, unknown>
+
+const moduleDefault = (eslintModule as { default?: CreateEslintConfig }).default
+const createEslintConfigExport = (
+  moduleDefault ?? (eslintModule as unknown as CreateEslintConfig)
+) as CreateEslintConfig
+
+// Third-party dependencies blessed for consumer use
+export { defu } from 'defu'
+export const Immutable = ImmutableNamespace
+export { default as objectHash } from 'object-hash'
+export * from 'object-hash'
+export { parse as parseYaml } from 'yaml'
+
+export const createEslintConfig = createEslintConfigExport

package/src/meta.ts

@@ -0,0 +1,32 @@
+import type { Metadata } from './types/metadata.js'
+
+import 'reflect-metadata'
+
+const METADATA_KEY = Symbol.for('@relational-fabric/canon:meta')
+
+export function metaOf<T extends object, M extends Metadata = Metadata>(obj: T): M {
+  const existing = Reflect.getMetadata(METADATA_KEY, obj) as M | undefined
+  return (existing ?? ({} as M))
+}
+
+export function withMeta<T extends object, M extends Metadata = Metadata>(obj: T, metadata: M): T {
+  Reflect.defineMetadata(METADATA_KEY, metadata, obj)
+  return obj
+}
+
+export function updateMeta<T extends object, M extends Metadata = Metadata>(
+  obj: T,
+  updater: (metadata?: M) => M | undefined,
+): T {
+  const current = Reflect.getMetadata(METADATA_KEY, obj) as M | undefined
+  const next = updater(current)
+
+  if (next === undefined) {
+    if (Reflect.hasMetadata(METADATA_KEY, obj))
+      Reflect.deleteMetadata(METADATA_KEY, obj)
+  } else {
+    Reflect.defineMetadata(METADATA_KEY, next, obj)
+  }
+
+  return obj
+}

package/src/radar/converter.ts

@@ -4,9 +4,12 @@
 
 import type { CsvRow, QuadrantKey, RadarData, RingKey } from '../types/radar.js'
 
+import { Console } from 'node:console'
 import { readFileSync, writeFileSync } from 'node:fs'
 import process from 'node:process'
-import { parse } from 'yaml'
+import { parseYaml } from '../kit.js'
+
+const logger = new Console(process.stdout, process.stderr)
 
 // Quadrant mapping for CSV output
 const QUADRANT_MAP: Record<QuadrantKey, string> = {
@@ -28,7 +31,7 @@ const RING_MAP: Record<RingKey, string> = {
  * Convert YAML radar data to CSV format
  */
 export function convertYamlToCsv(yamlContent: string): string {
-  const data = parse(yamlContent) as RadarData
+  const data = parseYaml(yamlContent) as RadarData
 
   // Generate CSV content
   const csvRows: string[] = ['name,ring,quadrant,isNew,description']
@@ -72,7 +75,7 @@ export function convertYamlFileToCsv(yamlPath: string, csvPath: string): void {
     writeFileSync(csvPath, csvContent)
     // Success: Converted YAML to CSV
   } catch (error) {
-    console.error(
+    logger.error(
       '❌ Error converting YAML to CSV:',
       error instanceof Error ? error.message : 'Unknown error',
     )
@@ -112,7 +115,7 @@ function escapeCsvField(field: string): string {
  * Parse YAML radar data
  */
 export function parseRadarYaml(yamlContent: string): RadarData {
-  return parse(yamlContent) as RadarData
+  return parseYaml(yamlContent) as RadarData
 }
 
 /**

package/src/radar/validator.ts

@@ -3,6 +3,7 @@
  */
 
 import type { QuadrantKey, RadarData, RingKey } from '../types/radar.js'
+import { parseYaml } from '../kit.js'
 
 const VALID_QUADRANTS: QuadrantKey[] = [
   'tools-libraries',
@@ -288,10 +289,9 @@ function validateRadarEntry(
 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
+    const data = parseYaml(yamlContent) as RadarData
 
     return validateRadarData(data)
   } catch (error) {

package/src/registry.ts

@@ -38,8 +38,8 @@ export class Registry {
   /**
    * Make registry iterable - iterates over canon configs
    */
-  *[Symbol.iterator](): Iterator<CanonConfig> {
-    yield * this.canons.values()
+  * [Symbol.iterator](): Iterator<CanonConfig> {
+    yield* this.canons.values()
   }
 
   /**

package/src/shell.ts

@@ -4,8 +4,9 @@
  * Singleton registry instance with convenience API.
  */
 
+import type { Registry } from './registry.js'
 import type { CanonConfig, Canons } from './types/index.js'
-import { createRegistry, type Registry } from './registry.js'
+import { createRegistry } from './registry.js'
 import { defineCanon } from './types/index.js'
 
 /**

package/src/types/axioms.ts

@@ -5,8 +5,9 @@
  * (like ID, type, version) that can be found in different data structures.
  */
 
+import type { Expect } from '../testing.js'
 import type { TypeGuard } from './guards.js'
-import { type Expect, invariant } from '../testing.js'
+import { invariant } from '../testing.js'
 
 /**
  * Base axiom type that merges configuration with metadata

package/src/types/canons.ts

@@ -6,8 +6,9 @@
  * different formats.
  */
 
+import type { Expect } from '../testing.js'
 import type { AxiomConfig, Axioms } from './axioms.js'
-import { type Expect, invariant } from '../testing.js'
+import { invariant } from '../testing.js'
 
 /**
  * Canon type that maps axiom labels to their type-level configurations

package/src/types/guards.ts

@@ -2,7 +2,8 @@
  * Type guard utilities for Canon type system
  */
 
-import { type Expect, invariant } from '../testing.js'
+import type { Expect } from '../testing.js'
+import { invariant } from '../testing.js'
 
 /**
  * Type guard pattern that preserves specific types when narrowing

package/src/types/index.ts

@@ -6,5 +6,6 @@ export * from './axioms.js'
 export * from './canons.js'
 export * from './guards.js'
 export * from './js.js'
+export * from './metadata.js'
 export * from './objects.js'
 export * from './radar.js'

package/src/types/js.ts

@@ -1,4 +1,5 @@
-import { type Expect, invariant } from '../testing.js'
+import type { Expect } from '../testing.js'
+import { invariant } from '../testing.js'
 
 export interface JsType {
   string: string

package/src/types/metadata.ts

@@ -0,0 +1 @@
+export type Metadata = Record<PropertyKey, unknown>

package/src/types/objects.ts

@@ -2,7 +2,8 @@
  * Object type definitions for Canon
  */
 
-import { type Expect, invariant } from '../testing.js'
+import type { Expect } from '../testing.js'
+import { invariant } from '../testing.js'
 
 /**
  * Plain old JavaScript object type

package/src/types/radar.ts

@@ -2,7 +2,8 @@
  * Technology Radar data structures and types
  */
 
-import { type Expect, invariant } from '../testing.js'
+import type { Expect } from '../testing.js'
+import { invariant } from '../testing.js'
 
 export interface RadarEntry {
   /** The name of the technology or practice */
@@ -83,11 +84,11 @@ export interface CsvRow {
   description: string
 }
 
-export type QuadrantKey =
-  | 'tools-libraries'
-  | 'techniques-patterns'
-  | 'features-capabilities'
-  | 'data-structures-formats'
+export type QuadrantKey
+  = | 'tools-libraries'
+    | 'techniques-patterns'
+    | 'features-capabilities'
+    | 'data-structures-formats'
 export type RingKey = 'adopt' | 'trial' | 'assess' | 'hold'
 
 // ---------------------------------------------------------------------------