@living-architecture/riviere-schema 0.2.0

package/src/component-id.ts

@@ -0,0 +1,97 @@
+/**
+ * Parts that make up a component ID.
+ */
+export interface ComponentIdParts {
+  domain: string
+  module: string
+  type: string
+  name: string
+}
+
+/**
+ * Represents a structured component identifier.
+ *
+ * Component IDs follow the format `{domain}:{module}:{type}:{name}` in kebab-case.
+ *
+ * @example
+ * ```typescript
+ * const id = ComponentId.create({
+ *   domain: 'orders',
+ *   module: 'checkout',
+ *   type: 'api',
+ *   name: 'Create Order'
+ * })
+ * id.toString() // 'orders:checkout:api:create-order'
+ * ```
+ */
+export class ComponentId {
+  private readonly _name: string
+  private readonly value: string
+
+  private constructor(name: string, value: string) {
+    this._name = name
+    this.value = value
+  }
+
+  /**
+   * Creates a ComponentId from individual parts.
+   *
+   * @param parts - Domain, module, type, and name segments
+   * @returns A new ComponentId instance
+   *
+   * @example
+   * ```typescript
+   * const id = ComponentId.create({
+   *   domain: 'orders',
+   *   module: 'checkout',
+   *   type: 'api',
+   *   name: 'Create Order'
+   * })
+   * ```
+   */
+  static create(parts: ComponentIdParts): ComponentId {
+    const nameSegment = parts.name.toLowerCase().replace(/\s+/g, '-')
+    const value = `${parts.domain}:${parts.module}:${parts.type}:${nameSegment}`
+    return new ComponentId(nameSegment, value)
+  }
+
+  /**
+   * Parses a string ID into a ComponentId instance.
+   *
+   * @param id - String in format `domain:module:type:name`
+   * @returns A ComponentId instance
+   * @throws If the format is invalid
+   *
+   * @example
+   * ```typescript
+   * const id = ComponentId.parse('orders:checkout:api:create-order')
+   * id.name() // 'create-order'
+   * ```
+   */
+  static parse(id: string): ComponentId {
+    const parts = id.split(':')
+    const name = parts[3]
+    if (parts.length !== 4 || name === undefined) {
+      throw new Error(`Invalid component ID format: '${id}'. Expected 'domain:module:type:name'`)
+    }
+    return new ComponentId(name, id)
+  }
+
+  /**
+   * Returns the full component ID string.
+   *
+   * @returns Full ID in format `domain:module:type:name`
+   */
+  toString(): string {
+    return this.value
+  }
+
+  /**
+   * Returns the name segment of the component ID.
+   *
+   * @returns The kebab-case name portion
+   */
+  name(): string {
+    return this._name
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './schema';
+export { parseRiviereGraph, isRiviereGraph, formatValidationErrors } from './validation';
+export { ComponentId, type ComponentIdParts } from './component-id';

package/src/schema.spec.ts

@@ -0,0 +1,169 @@
+import type {
+  RiviereGraph,
+  Component,
+  UIComponent,
+  APIComponent,
+  Link,
+  GraphMetadata,
+} from './schema'
+import { parseRiviereGraph, formatValidationErrors } from './validation'
+
+describe('formatValidationErrors()', () => {
+  it('returns generic message when errors is null', () => {
+    const result = formatValidationErrors(null)
+    expect(result).toBe('validation failed without specific errors')
+  })
+
+  it('returns generic message when errors is empty array', () => {
+    const result = formatValidationErrors([])
+    expect(result).toBe('validation failed without specific errors')
+  })
+
+  it('formats single error with path and message', () => {
+    const errors = [{ instancePath: '/version', message: 'must match pattern' }]
+    const result = formatValidationErrors(errors)
+    expect(result).toBe('/version: must match pattern')
+  })
+
+  it('formats multiple errors joined by newlines', () => {
+    const errors = [
+      { instancePath: '/version', message: 'must match pattern' },
+      { instancePath: '/components/0/type', message: 'must be equal to one of the allowed values' },
+    ]
+    const result = formatValidationErrors(errors)
+    expect(result).toBe('/version: must match pattern\n/components/0/type: must be equal to one of the allowed values')
+  })
+})
+
+describe('parseRiviereGraph()', () => {
+  it('parses valid graph and returns typed RiviereGraph', () => {
+    const input = {
+      version: '1.0',
+      metadata: { domains: { test: { description: 'Test', systemType: 'domain' } } },
+      components: [],
+      links: [],
+    }
+
+    const result = parseRiviereGraph(input)
+
+    expect(result.version).toBe('1.0')
+    expect(result.components).toHaveLength(0)
+  })
+
+  it('throws on invalid component type', () => {
+    const input = {
+      version: '1.0',
+      metadata: { domains: { test: { description: 'Test', systemType: 'domain' } } },
+      components: [{ id: 'x', type: 'InvalidType', name: 'X', domain: 'test', module: 'mod', sourceLocation: { repository: 'r', filePath: 'f' } }],
+      links: [],
+    }
+
+    expect(() => parseRiviereGraph(input)).toThrow()
+  })
+
+  it('throws on missing required field with error details', () => {
+    const input = {
+      metadata: { domains: { test: { description: 'Test', systemType: 'domain' } } },
+      components: [],
+      links: [],
+    }
+
+    expect(() => parseRiviereGraph(input)).toThrow(/Invalid RiviereGraph/)
+  })
+
+  it('throws on invalid version format', () => {
+    const input = {
+      version: 'not-a-version',
+      metadata: { domains: { test: { description: 'Test', systemType: 'domain' } } },
+      components: [],
+      links: [],
+    }
+
+    expect(() => parseRiviereGraph(input)).toThrow()
+  })
+})
+
+describe('riviere-schema types', () => {
+  it('compiles a minimal valid graph structure', () => {
+    const graph: RiviereGraph = {
+      version: '1.0',
+      metadata: {
+        domains: {
+          test: {
+            description: 'Test domain',
+            systemType: 'domain',
+          },
+        },
+      },
+      components: [
+        {
+          id: 'test:mod:ui:page',
+          type: 'UI',
+          name: 'Test Page',
+          domain: 'test',
+          module: 'mod',
+          route: '/test',
+          sourceLocation: {
+            repository: 'test-repo',
+            filePath: 'src/page.tsx',
+          },
+        },
+      ],
+      links: [],
+    }
+
+    expect(graph.version).toBe('1.0')
+    expect(graph.components).toHaveLength(1)
+  })
+
+  it('enforces discriminated union for component types', () => {
+    const uiComponent: UIComponent = {
+      id: 'test:mod:ui:page',
+      type: 'UI',
+      name: 'Page',
+      domain: 'test',
+      module: 'mod',
+      route: '/page',
+      sourceLocation: { repository: 'repo', filePath: 'file.ts' },
+    }
+
+    const apiComponent: APIComponent = {
+      id: 'test:mod:api:endpoint',
+      type: 'API',
+      name: 'Endpoint',
+      domain: 'test',
+      module: 'mod',
+      apiType: 'REST',
+      httpMethod: 'POST',
+      path: '/api/test',
+      sourceLocation: { repository: 'repo', filePath: 'api.ts' },
+    }
+
+    const components: Component[] = [uiComponent, apiComponent]
+    expect(components).toHaveLength(2)
+  })
+
+  it('enforces link structure', () => {
+    const link: Link = {
+      source: 'component-a',
+      target: 'component-b',
+      type: 'sync',
+    }
+
+    expect(link.source).toBe('component-a')
+    expect(link.target).toBe('component-b')
+  })
+
+  it('enforces metadata structure with required domains', () => {
+    const metadata: GraphMetadata = {
+      domains: {
+        orders: {
+          description: 'Order management',
+          systemType: 'domain',
+        },
+      },
+    }
+
+    expect(metadata.domains['orders']?.systemType).toBe('domain')
+  })
+})

package/src/schema.ts

@@ -0,0 +1,184 @@
+export interface SourceLocation {
+  repository: string
+  filePath: string
+  lineNumber?: number
+  endLineNumber?: number
+  methodName?: string
+  url?: string
+}
+
+export interface OperationParameter {
+  name: string
+  type: string
+  description?: string
+}
+
+export interface OperationSignature {
+  parameters?: OperationParameter[]
+  returnType?: string
+}
+
+export interface OperationBehavior {
+  reads?: string[]
+  validates?: string[]
+  modifies?: string[]
+  emits?: string[]
+}
+
+export interface StateTransition {
+  from: string
+  to: string
+  trigger?: string
+}
+
+export type ComponentType =
+  | 'UI'
+  | 'API'
+  | 'UseCase'
+  | 'DomainOp'
+  | 'Event'
+  | 'EventHandler'
+  | 'Custom'
+
+interface ComponentBase {
+  id: string
+  name: string
+  domain: string
+  module: string
+  description?: string
+  sourceLocation: SourceLocation
+  metadata?: Record<string, unknown>
+}
+
+export interface UIComponent extends ComponentBase {
+  type: 'UI'
+  route: string
+}
+
+export type ApiType = 'REST' | 'GraphQL' | 'other'
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS'
+
+export interface APIComponent extends ComponentBase {
+  type: 'API'
+  apiType: ApiType
+  httpMethod?: HttpMethod
+  path?: string
+  operationName?: string
+}
+
+export interface UseCaseComponent extends ComponentBase {
+  type: 'UseCase'
+}
+
+export interface DomainOpComponent extends ComponentBase {
+  type: 'DomainOp'
+  operationName: string
+  entity?: string
+  signature?: OperationSignature
+  behavior?: OperationBehavior
+  stateChanges?: StateTransition[]
+  businessRules?: string[]
+}
+
+export interface EventComponent extends ComponentBase {
+  type: 'Event'
+  eventName: string
+  eventSchema?: string
+}
+
+export interface EventHandlerComponent extends ComponentBase {
+  type: 'EventHandler'
+  subscribedEvents: string[]
+}
+
+export interface CustomComponent extends ComponentBase {
+  type: 'Custom'
+  customTypeName: string
+}
+
+export type Component =
+  | UIComponent
+  | APIComponent
+  | UseCaseComponent
+  | DomainOpComponent
+  | EventComponent
+  | EventHandlerComponent
+  | CustomComponent
+
+export type LinkType = 'sync' | 'async'
+
+export interface PayloadDefinition {
+  type?: string
+  schema?: Record<string, unknown>
+}
+
+export interface Link {
+  id?: string
+  source: string
+  target: string
+  type?: LinkType
+  payload?: PayloadDefinition
+  sourceLocation?: SourceLocation
+  metadata?: Record<string, unknown>
+}
+
+export interface ExternalTarget {
+  name: string
+  domain?: string
+  repository?: string
+  url?: string
+}
+
+export interface ExternalLink {
+  id?: string
+  source: string
+  target: ExternalTarget
+  type?: LinkType
+  description?: string
+  sourceLocation?: SourceLocation
+  metadata?: Record<string, unknown>
+}
+
+export type SystemType = 'domain' | 'bff' | 'ui' | 'other'
+
+export interface DomainMetadata {
+  description: string
+  systemType: SystemType
+  [key: string]: unknown
+}
+
+export type CustomPropertyType = 'string' | 'number' | 'boolean' | 'array' | 'object'
+
+export interface CustomPropertyDefinition {
+  type: CustomPropertyType
+  description?: string
+}
+
+export interface CustomTypeDefinition {
+  description?: string
+  requiredProperties?: Record<string, CustomPropertyDefinition>
+  optionalProperties?: Record<string, CustomPropertyDefinition>
+}
+
+export interface SourceInfo {
+  repository: string
+  commit?: string
+  extractedAt?: string
+}
+
+export interface GraphMetadata {
+  name?: string
+  description?: string
+  generated?: string
+  sources?: SourceInfo[]
+  domains: Record<string, DomainMetadata>
+  customTypes?: Record<string, CustomTypeDefinition>
+}
+
+export interface RiviereGraph {
+  version: string
+  metadata: GraphMetadata
+  components: Component[]
+  links: Link[]
+  externalLinks?: ExternalLink[]
+}

package/src/validation.ts

@@ -0,0 +1,32 @@
+import Ajv from 'ajv'
+import addFormats from 'ajv-formats'
+import type { RiviereGraph } from './schema'
+import rawSchema from '../riviere.schema.json' with { type: 'json' }
+
+const ajv = new Ajv({ allErrors: true })
+addFormats(ajv)
+
+const validate = ajv.compile(rawSchema)
+
+export function isRiviereGraph(data: unknown): data is RiviereGraph {
+  return validate(data) === true
+}
+
+interface ValidationErrorLike {
+  instancePath: string
+  message?: string
+}
+
+export function formatValidationErrors(errors: ValidationErrorLike[] | null | undefined): string {
+  if (!errors || errors.length === 0) {
+    return 'validation failed without specific errors'
+  }
+  return errors.map((e) => `${e.instancePath}: ${e.message}`).join('\n')
+}
+
+export function parseRiviereGraph(data: unknown): RiviereGraph {
+  if (isRiviereGraph(data)) {
+    return data
+  }
+  throw new Error(`Invalid RiviereGraph:\n${formatValidationErrors(validate.errors)}`)
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ]
+}

package/tsconfig.lib.json

@@ -0,0 +1,28 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "rootDir": "src",
+    "outDir": "dist",
+    "tsBuildInfoFile": "dist/tsconfig.lib.tsbuildinfo",
+    "emitDeclarationOnly": false,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "references": [],
+  "exclude": [
+    "vite.config.ts",
+    "vite.config.mts",
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.js",
+    "src/**/*.spec.js",
+    "src/**/*.test.jsx",
+    "src/**/*.spec.jsx"
+  ]
+}

package/tsconfig.spec.json

@@ -0,0 +1,34 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./out-tsc/vitest",
+    "types": [
+      "vitest/globals",
+      "vitest/importMeta",
+      "vite/client",
+      "node",
+      "vitest"
+    ],
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": [
+    "vite.config.ts",
+    "vite.config.mts",
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.js",
+    "src/**/*.spec.js",
+    "src/**/*.test.jsx",
+    "src/**/*.spec.jsx",
+    "src/**/*.d.ts"
+  ],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    }
+  ]
+}

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"fileNames":[],"fileInfos":[],"root":[],"options":{"composite":true,"declarationMap":true,"emitDeclarationOnly":true,"exactOptionalPropertyTypes":true,"importHelpers":true,"module":199,"noEmitOnError":true,"noFallthroughCasesInSwitch":true,"noImplicitOverride":true,"noImplicitReturns":true,"noPropertyAccessFromIndexSignature":true,"noUncheckedIndexedAccess":true,"noUnusedLocals":true,"noUnusedParameters":true,"skipLibCheck":true,"strict":true,"target":9,"verbatimModuleSyntax":true},"version":"5.9.3"}

package/vite.config.ts

@@ -0,0 +1,20 @@
+/// <reference types='vitest' />
+import { defineConfig } from 'vite';
+
+export default defineConfig(() => ({
+  root: import.meta.dirname,
+  cacheDir: '../node_modules/.vite/riviere-schema',
+  plugins: [],
+  test: {
+    name: '@living-architecture/riviere-schema',
+    watch: false,
+    globals: true,
+    environment: 'node',
+    include: ['{src,tests}/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
+    reporters: ['default'],
+    coverage: {
+      reportsDirectory: './test-output/vitest/coverage',
+      provider: 'v8' as const,
+    },
+  },
+}));

package/vitest.config.mts

@@ -0,0 +1,24 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig(() => ({
+  root: __dirname,
+  cacheDir: '../../node_modules/.vite/packages/riviere-schema',
+  test: {
+    name: '@living-architecture/riviere-schema',
+    watch: false,
+    globals: true,
+    environment: 'node',
+    include: ['{src,tests}/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
+    reporters: ['default'],
+    coverage: {
+      reportsDirectory: './test-output/vitest/coverage',
+      provider: 'v8' as const,
+      thresholds: {
+        lines: 100,
+        statements: 100,
+        functions: 100,
+        branches: 100,
+      },
+    },
+  },
+}));