@principal-ai/principal-view-core 0.5.6

package/dist/rules/types.d.ts

@@ -0,0 +1,309 @@
+/**
+ * Rules Engine Type Definitions
+ * Provides types for configuration validation rules
+ */
+/**
+ * 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';
+/**
+ * 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 [".vgc/**\/*.yaml", ".vgc/**\/*.yml", ".vgc/**\/*.json"]
+     */
+    include?: string[];
+    /**
+     * Glob patterns to exclude from linting
+     * @default ["**\/node_modules/**", "**\/*.test.*"]
+     */
+    exclude?: string[];
+    /**
+     * Rule configurations
+     */
+    rules?: {
+        [ruleId: string]: RuleConfig | RuleSeverity | false;
+    };
+}
+/**
+ * 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>;
+}
+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>;
+}
+/**
+ * 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>;
+}
+/**
+ * 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>;
+}
+/**
+ * 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;
+}
+/**
+ * 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>;
+}
+/**
+ * Normalize severity to string form
+ */
+export declare function normalizeSeverity(severity: RuleSeverity): NormalizedSeverity;
+/**
+ * Check if a severity means the rule is disabled
+ */
+export declare function isRuleDisabled(severity: RuleSeverity | false | undefined): boolean;
+//# sourceMappingURL=types.d.ts.map

package/dist/rules/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/rules/types.ts"],"names":[],"mappings":"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"}

package/dist/rules/types.js

@@ -0,0 +1,35 @@
+/**
+ * Rules Engine Type Definitions
+ * Provides types for configuration validation rules
+ */
+// ============================================================================
+// Utility Types
+// ============================================================================
+/**
+ * Normalize severity to string form
+ */
+export function normalizeSeverity(severity) {
+    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) {
+    if (severity === false || severity === 'off' || severity === 0) {
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=types.js.map

package/dist/rules/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/rules/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAuYH,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAE/E;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAsB;IACtD,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACjC,QAAQ,QAAQ,EAAE,CAAC;YACjB,KAAK,CAAC;gBACJ,OAAO,KAAK,CAAC;YACf,KAAK,CAAC;gBACJ,OAAO,MAAM,CAAC;YAChB,KAAK,CAAC;gBACJ,OAAO,OAAO,CAAC;YACjB;gBACE,OAAO,OAAO,CAAC;QACnB,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,QAA0C;IACvE,IAAI,QAAQ,KAAK,KAAK,IAAI,QAAQ,KAAK,KAAK,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;QAC/D,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}