@principal-ai/subsystems-core 0.29.0

package/src/types/resource-match.ts

@@ -0,0 +1,263 @@
+/**
+ * Resource Matching Types
+ *
+ * Defines how logs are matched to canvas nodes based on OTEL resource attributes.
+ * Supports multiple matching strategies: exact, glob, regex, existence, and oneOf.
+ *
+ * @example
+ * ```yaml
+ * # In canvas configuration
+ * nodes:
+ *   - id: "payment-service"
+ *     resourceMatch:
+ *       service.name: "payment-*"           # Glob pattern
+ *       deployment.environment: "production" # Exact match
+ *       db.system: { exists: true }         # Must have db.system attribute
+ * ```
+ */
+
+/**
+ * Exact match operator
+ *
+ * @example
+ * ```typescript
+ * const match: ExactMatch = { exact: 'checkout-api' };
+ * ```
+ */
+export interface ExactMatch {
+  exact: string;
+}
+
+/**
+ * Glob pattern match operator
+ * Supports * (any characters) and ? (single character)
+ *
+ * @example
+ * ```typescript
+ * const match: GlobMatch = { glob: 'payment-*' };  // matches payment-service, payment-worker
+ * const match2: GlobMatch = { glob: 'api-?' };     // matches api-1, api-2
+ * ```
+ */
+export interface GlobMatch {
+  glob: string;
+}
+
+/**
+ * Regex pattern match operator
+ *
+ * @example
+ * ```typescript
+ * const match: RegexMatch = { regex: '^checkout-.+$' };
+ * ```
+ */
+export interface RegexMatch {
+  regex: string;
+}
+
+/**
+ * Existence check operator
+ *
+ * @example
+ * ```typescript
+ * const mustExist: ExistsMatch = { exists: true };   // attribute must be present
+ * const mustNotExist: ExistsMatch = { exists: false }; // attribute must be absent
+ * ```
+ */
+export interface ExistsMatch {
+  exists: boolean;
+}
+
+/**
+ * OneOf match operator - matches any of the specified values
+ *
+ * @example
+ * ```typescript
+ * const match: OneOfMatch = { oneOf: ['production', 'staging'] };
+ * ```
+ */
+export interface OneOfMatch {
+  oneOf: string[];
+}
+
+/**
+ * Match operator union type
+ *
+ * Can be one of the structured operators or a plain string (shorthand for exact match).
+ *
+ * @example
+ * ```typescript
+ * // These are equivalent:
+ * const op1: MatchOperator = 'checkout-api';
+ * const op2: MatchOperator = { exact: 'checkout-api' };
+ *
+ * // Other operators:
+ * const glob: MatchOperator = { glob: 'payment-*' };
+ * const regex: MatchOperator = { regex: '^api-.+$' };
+ * const exists: MatchOperator = { exists: true };
+ * const oneOf: MatchOperator = { oneOf: ['prod', 'staging'] };
+ * ```
+ */
+export type MatchOperator = ExactMatch | GlobMatch | RegexMatch | ExistsMatch | OneOfMatch | string;
+
+/**
+ * Resource match criteria
+ *
+ * All specified conditions must match (AND logic).
+ * Use for defining which logs should route to a specific node.
+ *
+ * @example
+ * ```typescript
+ * const match: ResourceMatch = {
+ *   'service.name': 'checkout-api',              // Exact match (shorthand)
+ *   'deployment.environment': 'production',      // Exact match (shorthand)
+ *   'k8s.namespace.name': { glob: 'checkout-*' } // Glob pattern
+ * };
+ * ```
+ */
+export interface ResourceMatch {
+  // Service identification (most common matching targets)
+  'service.name'?: MatchOperator;
+  'service.namespace'?: MatchOperator;
+  'service.instance.id'?: MatchOperator;
+  'service.version'?: MatchOperator;
+
+  // Deployment
+  'deployment.environment'?: MatchOperator;
+
+  // Kubernetes
+  'k8s.namespace.name'?: MatchOperator;
+  'k8s.deployment.name'?: MatchOperator;
+  'k8s.pod.name'?: MatchOperator;
+  'k8s.container.name'?: MatchOperator;
+  'k8s.node.name'?: MatchOperator;
+
+  // Database
+  'db.system'?: MatchOperator;
+  'db.name'?: MatchOperator;
+
+  // Host
+  'host.name'?: MatchOperator;
+  'host.id'?: MatchOperator;
+
+  // Cloud
+  'cloud.provider'?: MatchOperator;
+  'cloud.region'?: MatchOperator;
+
+  // Messaging
+  'messaging.system'?: MatchOperator;
+  'messaging.destination.name'?: MatchOperator;
+
+  // Allow arbitrary attribute matching
+  [key: string]: MatchOperator | undefined;
+}
+
+/**
+ * Result of a match attempt
+ *
+ * Includes the match outcome, specificity score for priority resolution,
+ * and details about which criteria matched or failed.
+ */
+export interface MatchResult {
+  /** Whether all criteria matched */
+  matched: boolean;
+
+  /**
+   * Match specificity score (higher = more specific match)
+   *
+   * Scoring rules:
+   * - Each exact match: +10 points
+   * - Each oneOf match: +8 points
+   * - Each regex match: +5 points
+   * - Each glob match: +3 points
+   * - Each exists match: +1 point
+   *
+   * Used to resolve conflicts when multiple nodes match the same log.
+   */
+  score: number;
+
+  /** List of criteria keys that matched */
+  matchedCriteria: string[];
+
+  /** List of criteria keys that failed (for debugging) */
+  failedCriteria?: string[];
+}
+
+/**
+ * Interface for nodes that support resource-based matching
+ *
+ * Nodes can have both resourceMatch (OTEL attributes) and sources (file paths).
+ * When routing logs, resourceMatch takes priority over sources.
+ */
+export interface ResourceMatchableNode {
+  /** Node identifier */
+  id: string;
+
+  /**
+   * Resource-based matching criteria (OTEL attributes)
+   * Takes priority over sources when both are specified.
+   */
+  resourceMatch?: ResourceMatch;
+
+  /**
+   * Path-based matching (source file globs)
+   * Used as fallback when resourceMatch is not specified or doesn't match.
+   * Also used for code coverage analysis.
+   */
+  sources?: string[];
+}
+
+// Type guards for match operators
+
+/**
+ * Check if operator is an exact match
+ */
+export function isExactMatch(op: MatchOperator): op is ExactMatch {
+  return typeof op === 'object' && 'exact' in op;
+}
+
+/**
+ * Check if operator is a glob match
+ */
+export function isGlobMatch(op: MatchOperator): op is GlobMatch {
+  return typeof op === 'object' && 'glob' in op;
+}
+
+/**
+ * Check if operator is a regex match
+ */
+export function isRegexMatch(op: MatchOperator): op is RegexMatch {
+  return typeof op === 'object' && 'regex' in op;
+}
+
+/**
+ * Check if operator is an exists match
+ */
+export function isExistsMatch(op: MatchOperator): op is ExistsMatch {
+  return typeof op === 'object' && 'exists' in op;
+}
+
+/**
+ * Check if operator is a oneOf match
+ */
+export function isOneOfMatch(op: MatchOperator): op is OneOfMatch {
+  return typeof op === 'object' && 'oneOf' in op;
+}
+
+/**
+ * Check if operator is a string shorthand (exact match)
+ */
+export function isStringShorthand(op: MatchOperator): op is string {
+  return typeof op === 'string';
+}
+
+/**
+ * Normalize a match operator to its canonical form
+ */
+export function normalizeOperator(
+  op: MatchOperator
+): ExactMatch | GlobMatch | RegexMatch | ExistsMatch | OneOfMatch {
+  if (typeof op === 'string') {
+    return { exact: op };
+  }
+  return op;
+}

package/src/types/subsystem-model.ts

@@ -0,0 +1,352 @@
+/**
+ * Subsystem Model Types
+ *
+ * Two layers — do not conflate them:
+ *
+ * 1. **Portable document** (`SubsystemModelDocument`) — the shareable standard.
+ *    Schema: `schemas/subsystem-model.schema.json`
+ *    (`https://principal-ai.dev/schemas/subsystem-model.schema.json`).
+ *
+ * 2. **Hydrated envelope** (`SubsystemModelHydrated`) — portable document plus
+ *    host/machine binding (local roots, provenance, store ids, verification).
+ *    Used by viewers and stores; not part of the portable standard.
+ *
+ * Ontology: construct = what a node is, framework + stereotype = which
+ * framework pattern it plays, role = where it sits, process = where it runs.
+ * `symbol` is the code identity; `name` is the display label.
+ */
+
+/** What the node IS as a declaration. `module` is not an authored construct —
+ *  a module is its own subsystem. */
+export type SubsystemConstruct =
+  | 'class'
+  | 'function'
+  | 'method'
+  | 'interface'
+  | 'type_alias'
+  | 'enum'
+  | 'store'
+  | 'external';
+
+/** Where the node sits in the topology, orthogonal to construct. */
+export type SubsystemComponentRole = 'entry' | 'service';
+
+/**
+ * Framework that owns a stereotype vocabulary (open string).
+ * Examples: `react`, `vue`, `nestjs`, `django`, `spring`.
+ * Empty when the node is language-only / framework-agnostic.
+ */
+export type SubsystemFramework = string;
+
+/**
+ * Framework-level pattern stamped on a language construct (open string).
+ * Examples: `component`, `hook`, `middleware`, `controller`, `guard`.
+ * Empty when no framework pattern applies. Pair with `framework` when set.
+ */
+export type SubsystemStereotype = string;
+
+/** How `from` relates to `to` on an edge. */
+export type SubsystemEdgeMechanism =
+  | 'imports'
+  | 'imports_from'
+  | 're_exports'
+  | 'defines'
+  | 'calls'
+  | 'extends'
+  | 'inherits'
+  | 'implements'
+  | 'mixes_in'
+  | 'uses'
+  | 'method'
+  | 'references'
+  | 'contains'
+  | 'feeds'
+  | 'produces'
+  | 'writes'
+  | 'reads'
+  | 'watches'
+  | 'registers-into';
+
+export type SubsystemCapture = 'edited' | 'analyzed' | 'referenced';
+
+export type SubsystemDeclarationProvenance = 'verified' | 'authored';
+
+export type SubsystemDeclTokenKind =
+  | 'keyword'
+  | 'name'
+  | 'member'
+  | 'type'
+  | 'punctuation'
+  | 'string'
+  | 'newline';
+
+export interface SubsystemDeclToken {
+  text: string;
+  kind: SubsystemDeclTokenKind;
+  /** Optional foreground when pre-tokenized for a theme. */
+  color?: string;
+}
+
+/** Anchored declaration location (usually from verify tooling). */
+export interface SubsystemDeclarationRef {
+  file: string;
+  startLine: number;
+  lineHash: string;
+  graphifyNodeId?: string;
+  capturedAt: string;
+  revision?: {
+    headSha: string;
+    dirtyHash?: string | null;
+  };
+}
+
+export interface SubsystemParamInfo {
+  name?: string;
+  type: string;
+  ref?: SubsystemReferenceInfo;
+}
+
+export interface SubsystemPropertyInfo {
+  name: string;
+  type?: string;
+  typeRef?: SubsystemReferenceInfo;
+  nodeId?: string;
+}
+
+export interface SubsystemMethodInfo {
+  nodeId: string;
+  name: string;
+  parameters?: SubsystemParamInfo[];
+  returnType?: string;
+  returnTypeRef?: SubsystemReferenceInfo;
+}
+
+export interface SubsystemCallInfo {
+  nodeId: string;
+  name: string;
+  source_location?: string;
+}
+
+export interface SubsystemReferenceInfo {
+  nodeId: string;
+  name: string;
+  context?: string;
+  source_location?: string;
+}
+
+export interface SubsystemImportInfo {
+  nodeId: string;
+  name: string;
+  relation?: string;
+  source_location?: string;
+}
+
+export interface SubsystemClassDeclaration {
+  kind: 'class';
+  methods: SubsystemMethodInfo[];
+  properties: SubsystemPropertyInfo[];
+  extends: string[];
+  implements: string[];
+  instantiations: SubsystemCallInfo[];
+  references: SubsystemReferenceInfo[];
+}
+
+export interface SubsystemFunctionDeclaration {
+  kind: 'function';
+  parameters: SubsystemParamInfo[];
+  returnType?: string;
+  returnTypeRef?: SubsystemReferenceInfo;
+  callers: SubsystemCallInfo[];
+  callees: SubsystemCallInfo[];
+}
+
+export interface SubsystemMethodDeclaration {
+  kind: 'method';
+  hostClass: string;
+  parameters?: SubsystemParamInfo[];
+  returnType?: string;
+}
+
+export interface SubsystemTypeDeclaration {
+  kind: 'type';
+  properties: SubsystemPropertyInfo[];
+  usedBy: SubsystemReferenceInfo[];
+  implementors: string[];
+}
+
+export interface SubsystemModuleDeclaration {
+  kind: 'module';
+  exports: string[];
+  imports: SubsystemImportInfo[];
+  symbols: string[];
+}
+
+export interface SubsystemExternalDeclaration {
+  kind: 'external';
+  label: string;
+}
+
+export interface SubsystemStoreDeclaration {
+  kind: 'store';
+  properties: SubsystemPropertyInfo[];
+}
+
+/** Structured declaration shape of a construct. */
+export type SubsystemConstructDeclaration =
+  | SubsystemClassDeclaration
+  | SubsystemFunctionDeclaration
+  | SubsystemMethodDeclaration
+  | SubsystemTypeDeclaration
+  | SubsystemModuleDeclaration
+  | SubsystemExternalDeclaration
+  | SubsystemStoreDeclaration;
+
+/** A component node — the named unit, construct-tagged. */
+export interface SubsystemComponent {
+  id: string;
+  /** Display label. Prefer aligning with `symbol` when present. */
+  name: string;
+  construct: SubsystemConstruct;
+  /** Repo-root-relative source path. */
+  file: string;
+  /** PURL for repo/package grouping. */
+  purl: string;
+  purpose?: string;
+  role?: SubsystemComponentRole;
+  /**
+   * Framework that owns the stereotype (e.g. `react`, `nestjs`).
+   * Orthogonal to `construct` — a React component is still `construct: function`.
+   */
+  framework?: SubsystemFramework;
+  /**
+   * Framework pattern this declaration plays (e.g. `component`, `hook`).
+   * Prefer this over inventing framework-specific constructs.
+   */
+  stereotype?: SubsystemStereotype;
+  process?: string;
+  /** Code identity — real declaration in `file` when set. */
+  symbol?: string;
+  layer?: number;
+  capture?: SubsystemCapture;
+  /** Structured declaration shape of the construct (params, members, …). */
+  declaration?: SubsystemConstructDeclaration;
+  declarationProvenance?: SubsystemDeclarationProvenance;
+  tokens?: SubsystemDeclToken[];
+  /** Location anchor (file/line/hash) — distinct from `declaration` (shape). */
+  declarationRef?: SubsystemDeclarationRef;
+}
+
+/** A cross-component edge. */
+export interface SubsystemComponentEdge {
+  id: string;
+  /** Source component id. */
+  from: string;
+  /** Target component id (or external label). */
+  to: string;
+  mechanism: SubsystemEdgeMechanism;
+  /** Concrete file/symbol evidence (often purls). */
+  refs?: string[];
+}
+
+export interface SubsystemThroughlineStep {
+  edgeId: string;
+  file: string;
+  /** 1-based line within `file`. */
+  line: number;
+  /** Frame name for this hop (function/method/symbol). Optional. */
+  symbol?: string;
+  /**
+   * Free-text note anchored to this hop's site line. Optional — informative
+   * only, never verified against source; viewers surface it via the codeview's
+   * annotation column.
+   */
+  annotation?: string;
+}
+
+/** Ordered execution story over existing edges (one per flow). */
+export interface SubsystemThroughline {
+  id: string;
+  title: string;
+  steps: SubsystemThroughlineStep[];
+}
+
+export interface SubsystemRepoRef {
+  owner: string;
+  name: string;
+}
+
+/**
+ * Portable subsystem model — the shareable standard.
+ * No host paths, provenance, document-level repo, store ids, or verification.
+ * Repo identity lives on each component's `purl`.
+ */
+export interface SubsystemModelDocument {
+  /**
+   * Optional pointer to the JSON Schema that describes this file. Lets editors
+   * give autocomplete and validation when the field is set.
+   */
+  $schema?: string;
+
+  title: string;
+  description?: string;
+  components: SubsystemComponent[];
+  edges: SubsystemComponentEdge[];
+  throughlines?: SubsystemThroughline[];
+}
+
+/**
+ * Host/machine fields layered onto a portable document for local use.
+ * Not part of the portable standard — viewers and stores own this envelope.
+ */
+export interface SubsystemModelHostBinding {
+  /** Provenance of the model (e.g. `agent:<name>`, `manual`). */
+  source?: string;
+  /**
+   * Optional document-level repo summary for host indexes/listings.
+   * Portable identity lives on each component's `purl`.
+   */
+  repo?: SubsystemRepoRef;
+  /**
+   * Local filesystem root component `file` paths resolve against.
+   * Opt-in; sandboxed reads for single-repo models.
+   */
+  repoRoot?: string;
+  /**
+   * Per-repo local roots for multi-repo models, keyed by purl repo key
+   * (`pkg:github/owner/name`, fragment stripped).
+   */
+  repoRoots?: Record<string, string>;
+}
+
+/**
+ * Hydrated model: portable document + host binding + optional store metadata.
+ * Shape used after a host accepts/persists a model for viewing on a machine.
+ */
+export interface SubsystemModelHydrated
+  extends SubsystemModelDocument, SubsystemModelHostBinding {
+  /** Store-assigned id when persisted. */
+  id?: string;
+  createdAt?: string;
+  updatedAt?: string;
+  /** Host verification result; shape is host-defined. */
+  verification?: unknown;
+}
+
+/**
+ * Type guard: true when the value plausibly conforms to a portable
+ * subsystem model. Shallow check — full validation belongs to the schema /
+ * host validator.
+ */
+export function isSubsystemModelDocument(value: unknown): value is SubsystemModelDocument {
+  if (!value || typeof value !== 'object') return false;
+  const v = value as {
+    title?: unknown;
+    components?: unknown;
+    edges?: unknown;
+  };
+  return (
+    typeof v.title === 'string' &&
+    Array.isArray(v.components) &&
+    Array.isArray(v.edges)
+  );
+}