@principal-ai/subsystems-core 0.29.0

package/src/rules/types.ts

@@ -0,0 +1,426 @@
+/**
+ * Rules Engine Type Definitions
+ * Provides types for configuration validation rules
+ */
+
+// ============================================================================
+// Rule Severity and Categories
+// ============================================================================
+
+/**
+ * Severity levels following ESLint convention
+ * - "off" or 0: Disable rule
+ * - "warn" or 1: Warning (doesn't affect exit code)
+ * - "error" or 2: Error (exit code 1)
+ */
+export type RuleSeverity = 'off' | 'warn' | 'error' | 0 | 1 | 2;
+
+/**
+ * Normalized severity (string form only)
+ */
+export type NormalizedSeverity = 'off' | 'warn' | 'error';
+
+/**
+ * Rule categories for grouping and filtering
+ */
+export type RuleCategory = 'schema' | 'reference' | 'structure' | 'pattern' | 'library';
+
+// ============================================================================
+// Rule Configuration (RC File)
+// ============================================================================
+
+/**
+ * Full rule configuration object
+ */
+export interface RuleConfig {
+  /**
+   * Rule severity
+   * @default "error"
+   */
+  severity?: RuleSeverity;
+
+  /**
+   * Rule-specific options
+   */
+  options?: Record<string, unknown>;
+}
+
+/**
+ * VGC Configuration file schema
+ */
+export interface PrivuConfig {
+  /**
+   * Schema version for forward compatibility
+   */
+  $schema?: string;
+
+  /**
+   * Extend from a shared configuration
+   * Can be a package name or relative path
+   */
+  extends?: string | string[];
+
+  /**
+   * Root flag - stop searching parent directories
+   * @default false
+   */
+  root?: boolean;
+
+  /**
+   * Path to default component library
+   * Used by library-node-type-match rule
+   */
+  library?: string;
+
+  /**
+   * Glob patterns for configuration files to lint
+   * @default [".principal-views/**\/*.yaml", ".principal-views/**\/*.yml", ".principal-views/**\/*.json"]
+   */
+  include?: string[];
+
+  /**
+   * Glob patterns to exclude from linting
+   * @default ["**\/node_modules/**", "**\/*.test.*"]
+   */
+  exclude?: string[];
+
+  /**
+   * Rule configurations
+   */
+  rules?: {
+    [ruleId: string]: RuleConfig | RuleSeverity | false;
+  };
+}
+
+// ============================================================================
+// Rule Definition
+// ============================================================================
+
+/**
+ * Rule-specific options type (varies per rule)
+ */
+export type RuleOptions = Record<string, unknown>;
+
+/**
+ * Definition of a validation rule
+ */
+export interface GraphRule<TOptions extends RuleOptions = RuleOptions> {
+  /**
+   * Unique rule identifier (kebab-case)
+   */
+  id: string;
+
+  /**
+   * Human-readable rule name
+   */
+  name: string;
+
+  /**
+   * Brief description of what the rule checks
+   */
+  description: string;
+
+  /**
+   * Explanation of why this rule matters
+   */
+  impact: string;
+
+  /**
+   * Default severity level
+   * @default "error"
+   */
+  severity: NormalizedSeverity;
+
+  /**
+   * Rule category for grouping
+   */
+  category: RuleCategory;
+
+  /**
+   * Whether the rule is enabled by default
+   * @default true
+   */
+  enabled: boolean;
+
+  /**
+   * Whether the rule supports auto-fix
+   * @default false
+   */
+  fixable: boolean;
+
+  /**
+   * Default options for this rule
+   */
+  defaultOptions?: TOptions;
+
+  /**
+   * Execute the rule check
+   */
+  check: (context: GraphRuleContext<TOptions>) => Promise<GraphRuleViolation[]>;
+
+  /**
+   * Optional auto-fix implementation
+   */
+  fix?: (violation: GraphRuleViolation, context: GraphRuleContext<TOptions>) => Promise<FixResult>;
+}
+
+// ============================================================================
+// Rule Context
+// ============================================================================
+
+import type { GraphConfiguration } from '../types';
+import type { ComponentLibrary } from '../types/library';
+
+/**
+ * Context passed to rules during evaluation
+ */
+export interface GraphRuleContext<TOptions extends RuleOptions = RuleOptions> {
+  /**
+   * The configuration being validated
+   */
+  configuration: GraphConfiguration;
+
+  /**
+   * Optional component library for library rules
+   */
+  library?: ComponentLibrary;
+
+  /**
+   * Path to the configuration file (for error reporting)
+   */
+  configPath?: string;
+
+  /**
+   * Path to the library file (for error reporting)
+   */
+  libraryPath?: string;
+
+  /**
+   * Raw YAML/JSON string (for line number lookup)
+   */
+  rawContent?: string;
+
+  /**
+   * Rule-specific options (merged with defaults)
+   */
+  options: TOptions;
+
+  /**
+   * All rule options from config (for cross-rule access if needed)
+   */
+  allRuleOptions?: Map<string, RuleOptions>;
+}
+
+// ============================================================================
+// Rule Violations
+// ============================================================================
+
+/**
+ * A violation detected by a rule
+ */
+export interface GraphRuleViolation {
+  /**
+   * ID of the rule that detected this violation
+   */
+  ruleId: string;
+
+  /**
+   * Severity of this violation
+   */
+  severity: NormalizedSeverity;
+
+  /**
+   * Path to the file containing the violation
+   */
+  file?: string;
+
+  /**
+   * Line number in the file (1-indexed)
+   */
+  line?: number;
+
+  /**
+   * Column number in the file (1-indexed)
+   */
+  column?: number;
+
+  /**
+   * JSON path to the problematic field (e.g., "nodeTypes.service.shape")
+   */
+  path?: string;
+
+  /**
+   * Clear, actionable error message
+   */
+  message: string;
+
+  /**
+   * Explanation of why this matters
+   */
+  impact: string;
+
+  /**
+   * Suggestion for how to fix
+   */
+  suggestion?: string;
+
+  /**
+   * Whether this violation can be auto-fixed
+   */
+  fixable: boolean;
+
+  /**
+   * Data needed for auto-fix
+   */
+  fixData?: Record<string, unknown>;
+}
+
+// ============================================================================
+// Lint Results
+// ============================================================================
+
+/**
+ * Result of running all rules
+ */
+export interface GraphLintResult {
+  /**
+   * All violations found
+   */
+  violations: GraphRuleViolation[];
+
+  /**
+   * Count of error-level violations
+   */
+  errorCount: number;
+
+  /**
+   * Count of warning-level violations
+   */
+  warningCount: number;
+
+  /**
+   * Count of fixable violations
+   */
+  fixableCount: number;
+
+  /**
+   * Violations grouped by category
+   */
+  byCategory: Record<RuleCategory, number>;
+
+  /**
+   * Violations grouped by rule ID
+   */
+  byRule: Record<string, number>;
+}
+
+// ============================================================================
+// Fix Results
+// ============================================================================
+
+/**
+ * Result of attempting to fix a violation
+ */
+export interface FixResult {
+  /**
+   * Whether the fix was successful
+   */
+  success: boolean;
+
+  /**
+   * Description of what was fixed
+   */
+  message?: string;
+
+  /**
+   * New content after fix (if applicable)
+   */
+  newContent?: string;
+
+  /**
+   * Error message if fix failed
+   */
+  error?: string;
+}
+
+// ============================================================================
+// Lint Options
+// ============================================================================
+
+/**
+ * Options for the lint operation
+ */
+export interface LintOptions {
+  /**
+   * Only run these rules (by ID)
+   */
+  enabledRules?: string[];
+
+  /**
+   * Skip these rules (by ID)
+   */
+  disabledRules?: string[];
+
+  /**
+   * Override severity for specific rules
+   */
+  severityOverrides?: Map<string, NormalizedSeverity>;
+
+  /**
+   * Component library for library rules
+   */
+  library?: ComponentLibrary;
+
+  /**
+   * Path to config file (for error reporting)
+   */
+  configPath?: string;
+
+  /**
+   * Path to library file (for error reporting)
+   */
+  libraryPath?: string;
+
+  /**
+   * Raw content for line number reporting
+   */
+  rawContent?: string;
+
+  /**
+   * Rule-specific options
+   */
+  ruleOptions?: Map<string, RuleOptions>;
+}
+
+// ============================================================================
+// Utility Types
+// ============================================================================
+
+/**
+ * Normalize severity to string form
+ */
+export function normalizeSeverity(severity: RuleSeverity): NormalizedSeverity {
+  if (typeof severity === 'number') {
+    switch (severity) {
+      case 0:
+        return 'off';
+      case 1:
+        return 'warn';
+      case 2:
+        return 'error';
+      default:
+        return 'error';
+    }
+  }
+  return severity;
+}
+
+/**
+ * Check if a severity means the rule is disabled
+ */
+export function isRuleDisabled(severity: RuleSeverity | false | undefined): boolean {
+  if (severity === false || severity === 'off' || severity === 0) {
+    return true;
+  }
+  return false;
+}

package/src/scopes/ScopePathIndex.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from 'bun:test';
+import { ScopePathIndex } from './ScopePathIndex';
+
+function makeIndex(entries: Array<{ scope: string; paths: string[] }>) {
+  const idx = new ScopePathIndex();
+  idx.addAll(entries);
+  return idx;
+}
+
+describe('ScopePathIndex.resolve', () => {
+  test('empty index resolves to null', () => {
+    const idx = new ScopePathIndex();
+    expect(idx.resolve('packages/subsystems-core/src/foo.ts')).toBeNull();
+  });
+
+  test('matches file nested under a declared folder path', () => {
+    const idx = makeIndex([{ scope: 'principal-ai.core', paths: ['packages/subsystems-core/src'] }]);
+    const match = idx.resolve('packages/subsystems-core/src/events/foo.ts');
+    expect(match?.entry.scope).toBe('principal-ai.core');
+    expect(match?.matchedPath).toBe('packages/subsystems-core/src');
+  });
+
+  test('returns null when no path covers the file', () => {
+    const idx = makeIndex([{ scope: 'principal-ai.core', paths: ['packages/subsystems-core/src'] }]);
+    expect(idx.resolve('packages/principal-studio-cli/src/foo.ts')).toBeNull();
+  });
+
+  test('longest-prefix wins: nested child scope beats parent', () => {
+    const idx = makeIndex([
+      { scope: 'principal-ai.core', paths: ['packages/subsystems-core/src'] },
+      { scope: 'principal-ai.core.validation', paths: ['packages/subsystems-core/src/validation'] },
+    ]);
+
+    // Parent-only subtree → parent wins
+    expect(idx.resolve('packages/subsystems-core/src/events/foo.ts')?.entry.scope).toBe('principal-ai.core');
+    // Child subtree → child wins (longer prefix)
+    expect(idx.resolve('packages/subsystems-core/src/validation/engine.ts')?.entry.scope).toBe(
+      'principal-ai.core.validation',
+    );
+    // Deeper under child → still child (inherited)
+    expect(idx.resolve('packages/subsystems-core/src/validation/rules/foo.ts')?.entry.scope).toBe(
+      'principal-ai.core.validation',
+    );
+  });
+
+  test('sibling scopes resolve disjointly', () => {
+    const idx = makeIndex([
+      { scope: 'principal-ai.core', paths: ['packages/subsystems-core/src'] },
+      { scope: 'principal-ai.cli', paths: ['packages/principal-studio-cli/src'] },
+    ]);
+    expect(idx.resolve('packages/subsystems-core/src/foo.ts')?.entry.scope).toBe('principal-ai.core');
+    expect(idx.resolve('packages/principal-studio-cli/src/foo.ts')?.entry.scope).toBe('principal-ai.cli');
+  });
+
+  test('exact-file path matches when declared as a file', () => {
+    const idx = makeIndex([{ scope: 'tiny', paths: ['packages/tiny/src/index.ts'] }]);
+    expect(idx.resolve('packages/tiny/src/index.ts')?.entry.scope).toBe('tiny');
+    expect(idx.resolve('packages/tiny/src/other.ts')).toBeNull();
+  });
+
+  test('normalization: trailing slash and ./ prefix are equivalent', () => {
+    const idx = makeIndex([{ scope: 's', paths: ['packages/subsystems-core/src/'] }]);
+    expect(idx.resolve('./packages/subsystems-core/src/foo.ts')?.entry.scope).toBe('s');
+  });
+
+  test('similar-prefix paths are not mistaken for nesting', () => {
+    const idx = makeIndex([
+      { scope: 'foo', paths: ['packages/foo/src'] },
+      { scope: 'foobar', paths: ['packages/foobar/src'] },
+    ]);
+    expect(idx.resolve('packages/foobar/src/x.ts')?.entry.scope).toBe('foobar');
+    expect(idx.resolve('packages/foo/src/x.ts')?.entry.scope).toBe('foo');
+  });
+});
+
+describe('ScopePathIndex.getEntry / getScopes', () => {
+  test('getEntry returns null when scope not registered', () => {
+    const idx = makeIndex([{ scope: 's', paths: ['packages/subsystems-core/src'] }]);
+    expect(idx.getEntry('other')).toBeNull();
+  });
+
+  test('getEntry returns the entry when present', () => {
+    const idx = makeIndex([{ scope: 's', paths: ['packages/subsystems-core/src'] }]);
+    expect(idx.getEntry('s')?.paths).toEqual(['packages/subsystems-core/src']);
+  });
+
+  test('getScopes lists each scope once', () => {
+    const idx = makeIndex([
+      { scope: 'a', paths: ['packages/a/src'] },
+      { scope: 'b', paths: ['packages/b/src'] },
+    ]);
+    expect(idx.getScopes().slice().sort()).toEqual(['a', 'b']);
+  });
+});

package/src/scopes/ScopePathIndex.ts

@@ -0,0 +1,89 @@
+/**
+ * Scope Path Index
+ *
+ * Maps a filepath to the `otel-scope` that owns it, using the `paths` field
+ * declared on `otel-scope` nodes.
+ *
+ * Resolution uses the longest-prefix partitioning rule: when multiple scopes
+ * have paths covering the same file, the one whose matched path is the most
+ * specific (longest after normalization) wins. This naturally supports nested
+ * scopes by dotted-name (e.g. `principal-ai.core` and
+ * `principal-ai.core.validation`), where the child claims its subtree without
+ * stealing the parent's.
+ *
+ * Pure/browser-safe — no filesystem access, just string comparison.
+ */
+
+import { normalizePath, pathCovers } from '../events/path-helpers';
+
+/**
+ * One declared scope/paths tuple. Multiple entries may share the same scope
+ * if a scope canvas needs to declare more than one region (generated code,
+ * platform splits, migration periods).
+ */
+export interface ScopePathEntry {
+  scope: string;
+  paths: string[];
+  /** Optional — useful for surfacing where a match came from in diagnostics. */
+  sourceCanvasPath?: string;
+}
+
+/**
+ * Result of resolving a file against the index.
+ */
+export interface ScopePathMatch {
+  /** The winning entry (by longest-prefix). */
+  entry: ScopePathEntry;
+  /** Which of the entry's paths covered the file — the one that won. */
+  matchedPath: string;
+}
+
+export class ScopePathIndex {
+  private entries: ScopePathEntry[] = [];
+
+  /** Register a single scope/paths entry. */
+  add(entry: ScopePathEntry): void {
+    this.entries.push(entry);
+  }
+
+  /** Register many entries at once. */
+  addAll(entries: readonly ScopePathEntry[]): void {
+    for (const e of entries) this.add(e);
+  }
+
+  /**
+   * Resolve a filepath to its owning scope.
+   * Returns null if no entry has a path covering the file.
+   */
+  resolve(filepath: string): ScopePathMatch | null {
+    const normalizedFile = normalizePath(filepath);
+    let best: { entry: ScopePathEntry; matchedPath: string; length: number } | null = null;
+
+    for (const entry of this.entries) {
+      for (const declared of entry.paths) {
+        if (!pathCovers(declared, normalizedFile)) continue;
+        const normalizedDeclared = normalizePath(declared);
+        const length = normalizedDeclared.length;
+        if (best === null || length > best.length) {
+          best = { entry, matchedPath: declared, length };
+        }
+      }
+    }
+
+    return best ? { entry: best.entry, matchedPath: best.matchedPath } : null;
+  }
+
+  /**
+   * Look up the entry for a specific scope. Returns null when the scope
+   * isn't registered — either because its scopes-canvas node omits `paths`
+   * (opt-out of enforcement) or because no such scope is declared.
+   */
+  getEntry(scope: string): ScopePathEntry | null {
+    return this.entries.find((e) => e.scope === scope) ?? null;
+  }
+
+  /** All scopes present in the index. */
+  getScopes(): readonly string[] {
+    return Array.from(new Set(this.entries.map((e) => e.scope)));
+  }
+}