@garrick0/c2-core-domain

Pure domain types and stateless functions for the C2 check system.

Overview

This package contains the domain layer of the C2 microkernel architecture. It defines the core abstractions for the check system with zero external dependencies.

Installation

npm install @garrick0/c2-core-domain

Key Concepts

Observable

A versioned, immutable snapshot of observed state with query capability.

interface Observable<TData> {
  readonly id: ObservableId;      // { type: 'git-branch', key: '/path' }
  readonly version: number;
  readonly timestamp: Date;
  readonly data: TData;
  query(params: QueryParams): QueryResponse;
}

CheckDefinition

A declarative specification of a check that runs against an Observable.

interface CheckDefinition {
  id: string;                    // 'git:no-protected-branch'
  name: string;                  // 'No Protected Branch'
  observableType: string;        // 'git-branch'
  query: QueryParams;            // { operation: 'branchIsProtected' }
  mustBe: boolean;               // Expected query result
  message: string | ((response, observable) => string);
  defaultSeverity?: ViolationSeverity;
}

CheckRunner

Executes checks against Observables and returns results.

const runner = createCheckRunner();
const result = runner.runOne(observable, activeCheck);
// { checkId, passed, violation?, response, ... }

API Reference

Types

| Type | Description | |------|-------------| | Observable<TData> | Versioned snapshot with query capability | | ObservableId | { type: string, key: string } | | QueryParams | { operation: string, ...params } | | QueryResponse<T> | { ok: boolean, data: T, message? } | | CheckDefinition | Declarative check specification | | CheckConfigEntry | Configuration for a check | | ActiveCheckDefinition | CheckDefinition resolved with config | | CheckResult | Result of running a single check | | CheckBatchResult | Result of running multiple checks | | Violation | Represents a failed check | | ViolationSeverity | 'error' \| 'warning' \| 'info' | | Result<T, E> | Functional error handling type |

Functions

// CheckDefinition resolution
resolveCheckDefinition(definition, configEntry?): ActiveCheckDefinition | null
resolveCheckDefinitions(definitions, configMap): ActiveCheckDefinition[]

// CheckRunner
createCheckRunner(): ICheckRunner

// Result utilities
ok(value): Result<T, never>
err(error): Result<never, E>
isOk(result): result is Ok<T>
isErr(result): result is Err<E>
map(result, fn): Result<U, E>
flatMap(result, fn): Result<U, E>
mapError(result, fn): Result<T, F>
unwrapOr(result, defaultValue): T
combine(results): Result<T[], E>
tryCatch(fn): Result<T, Error>
asyncTryCatch(fn): Promise<Result<T, Error>>

Usage Example

import {
  createCheckRunner,
  resolveCheckDefinition,
  type Observable,
  type CheckDefinition,
} from '@garrick0/c2-core-domain';

// Create a mock observable
const observable: Observable<{ value: number }> = {
  id: { type: 'test', key: 'example' },
  version: 1,
  timestamp: new Date(),
  data: { value: 42 },
  query(params) {
    if (params.operation === 'isAbove') {
      const threshold = (params.threshold as number) ?? 0;
      return { ok: this.data.value > threshold, data: { value: this.data.value } };
    }
    return { ok: false, data: null };
  },
};

// Define a check
const checkDef: CheckDefinition = {
  id: 'test:value-above-10',
  name: 'Value Above 10',
  observableType: 'test',
  query: { operation: 'isAbove', threshold: 10 },
  mustBe: true,
  message: 'Value must be above 10',
  defaultSeverity: 'error',
};

// Resolve and run
const activeCheck = resolveCheckDefinition(checkDef);
if (activeCheck) {
  const runner = createCheckRunner();
  const result = runner.runOne(observable, activeCheck);
  console.log(result.passed);  // true (42 > 10)
}

Architecture

This package is the innermost layer of the C2 architecture:

c2-cli → c2 → core-application → core-domain (this package)
                    ↓
           observable-git (plugin)

It has no dependencies on other packages and contains only:

• Type definitions
• Pure functions
• Stateless services

Development

# Build
npx nx build @garrick0/c2-core-domain

# Test
npx nx test @garrick0/c2-core-domain

# Lint
npx nx lint @garrick0/c2-core-domain

License

MIT