@principal-ai/subsystems-core 0.29.0 → 0.31.0

package/src/rules/types.ts

@@ -1,426 +0,0 @@
-/**
- * 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

@@ -1,94 +0,0 @@
-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

@@ -1,89 +0,0 @@
-/**
- * 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)));
-  }
-}