praxis-kit 4.0.1 → 4.1.0

package/dist/_shared/diagnostics.d.ts

@@ -0,0 +1,209 @@
+import { Except } from 'type-fest';
+
+declare enum DiagnosticCategory {
+    Contract = 0,
+    HTML = 1,
+    ARIA = 2,
+    Composition = 3,
+    Rendering = 4,
+    Accessibility = 5,
+    Performance = 6,
+    Internal = 7,
+    Deprecation = 8,
+    Lint = 9
+}
+
+declare enum DiagnosticCode {
+    MissingRequiredChild = "COMP1001",
+    InvalidParent = "COMP1002",
+    InvalidChild = "COMP1003",
+    UnexpectedChild = "COMP1004",
+    AmbiguousChild = "COMP1005",
+    CardinalityMin = "COMP1006",
+    CardinalityMax = "COMP1007",
+    PositionViolation = "COMP1008",
+    AllowedAsViolation = "COMP1009",
+    SlotExclusive = "SLOT1001",
+    SlotSingleChild = "SLOT1002",
+    SlotDiscardedChildren = "SLOT1003",
+    SlotRenderFn = "SLOT1004",
+    MissingAriaRelationship = "ARIA2001",
+    AriaViolation = "ARIA2002",
+    AriaAttributeInvalid = "ARIA2003",
+    AriaMissingLiveRegion = "ARIA2004",
+    AriaMissingAtomic = "ARIA2005",
+    AriaRelevantInvalidToken = "ARIA2006",
+    AriaRelevantSuperseded = "ARIA2007",
+    AriaInvalidRole = "ARIA2008",
+    AriaMissingAccessibleName = "ARIA2009",
+    AriaAttributeOnPresentational = "ARIA2010",
+    AriaHiddenOnFocusable = "ARIA2011",
+    AriaRequiredProperty = "ARIA2012",
+    AriaInvalidAttributeValue = "ARIA2013",
+    AriaRedundantLevelAttribute = "ARIA2014",
+    InvalidHeadingHierarchy = "HTML3001",
+    HtmlEmptyRole = "HTML3002",
+    HtmlImplicitRoleRedundant = "HTML3003",
+    HtmlImplicitRoleOverride = "HTML3004",
+    HtmlStandaloneRegionOverride = "HTML3005",
+    HtmlLandmarkRoleOverride = "HTML3006",
+    HtmlInvalidChild = "HTML3007",
+    InvalidRenderingTarget = "RENDER4001",
+    LintDeadCompoundKey = "LINT5001",
+    LintDeadCompoundValue = "LINT5002",
+    LintDeadCompoundNonLiteral = "LINT5003",
+    LintMissingStrict = "LINT5004",
+    LintInvalidDefaultKey = "LINT5005",
+    LintInvalidDefaultValue = "LINT5006",
+    LintInvalidDefaultNonLiteral = "LINT5007",
+    LintNegativeMin = "LINT5008",
+    LintNegativeMax = "LINT5009",
+    LintMaxLessThanMin = "LINT5010",
+    LintZeroMax = "LINT5011",
+    LintMultipleFirst = "LINT5012",
+    LintMultipleLast = "LINT5013",
+    LintMinSumExceedsCapacity = "LINT5014",
+    LintCardinalityViolation = "LINT5015",
+    LintAriaTagOverride = "LINT5016",
+    ContractUnknownVariantDim = "COMP1010",
+    ContractUnknownVariantValue = "COMP1011",
+    ContractUnknownRecipeKey = "COMP1012",
+    ContractInvalidVariantValue = "COMP1013",
+    TailwindMultipleDisplayProps = "CSS6001",
+    TailwindReservedLayoutLiteral = "CSS6002",
+    TailwindDeadVariantClass = "CSS6003",
+    PluginInvalidShape = "PLUGIN7001",
+    PluginPipelineReturnType = "PLUGIN7002",
+    InternalError = "INTERNAL9000"
+}
+
+type StringMap<T = unknown> = Record<string, T>;
+type AnyRecord = StringMap<unknown>;
+
+declare enum Severity {
+    Debug = 0,
+    Info = 1,
+    Warning = 2,
+    Error = 3,
+    Fatal = 4
+}
+declare function isAtLeast(s: Severity, threshold: Severity): boolean;
+
+type Context = AnyRecord;
+type Metadata = AnyRecord;
+interface SourcePosition {
+    line: number;
+    col: number;
+}
+interface SourceLocation {
+    file: string;
+    start: SourcePosition;
+    end?: SourcePosition;
+}
+interface DiagnosticSuggestion {
+    title: string;
+    description?: string;
+    fix?: string;
+}
+interface Diagnostic {
+    code: DiagnosticCode;
+    severity: Severity;
+    category: DiagnosticCategory;
+    message: string;
+    rationale?: string;
+    component?: string;
+    contract?: string;
+    location?: SourceLocation;
+    suggestions?: DiagnosticSuggestion[];
+    context?: Context;
+    metadata?: Metadata;
+}
+interface DiagnosticReporter {
+    report(diagnostic: Diagnostic): void;
+}
+
+declare enum Enforcement {
+    Ignore = 0,
+    Report = 1,
+    Throw = 2
+}
+interface DiagnosticPolicy {
+    resolve(diagnostic: Diagnostic): Enforcement;
+}
+interface DefaultPolicyOptions {
+    reportThreshold?: Severity;
+    throwThreshold?: Severity;
+}
+declare class DefaultPolicy implements DiagnosticPolicy {
+    private readonly reportThreshold;
+    private readonly throwThreshold;
+    constructor({ reportThreshold, throwThreshold, }?: DefaultPolicyOptions);
+    resolve(diagnostic: Diagnostic): Enforcement;
+}
+
+type DiagnosticInput = Except<Diagnostic, 'severity'>;
+declare class Diagnostics {
+    private readonly reporter;
+    private readonly policy;
+    readonly active: boolean;
+    constructor(reporter: DiagnosticReporter, policy?: DiagnosticPolicy);
+    report(diagnostic: Diagnostic): Diagnostic;
+    warn(input: DiagnosticInput): Diagnostic;
+    error(input: DiagnosticInput): Diagnostic;
+    info(input: DiagnosticInput): Diagnostic;
+}
+
+declare class PraxisError extends Error {
+    readonly diagnostic: Diagnostic;
+    constructor(diagnostic: Diagnostic);
+}
+
+type Formatter = (diagnostic: Diagnostic) => string;
+declare function formatDiagnostic(diagnostic: Diagnostic): string;
+
+interface ValidationResult {
+    valid: boolean;
+    diagnostics: readonly Diagnostic[];
+}
+type Ok<T> = {
+    readonly ok: true;
+    readonly value: T;
+};
+type Err<E> = {
+    readonly ok: false;
+    readonly error: E;
+};
+type Result<T, E = ValidationResult> = Ok<T> | Err<E>;
+declare function ok<T>(value: T): Ok<T>;
+declare function err<E>(error: E): Err<E>;
+
+declare class AsyncConsoleReporter implements DiagnosticReporter {
+    private readonly pending;
+    private scheduled;
+    report(diagnostic: Diagnostic): void;
+    /** Clears pending messages. Exposed for test isolation only. */
+    reset(): void;
+}
+
+declare class CollectingReporter implements DiagnosticReporter {
+    private readonly collected;
+    report(diagnostic: Diagnostic): void;
+    get diagnostics(): readonly Diagnostic[];
+    clear(): void;
+}
+
+declare class ConsoleReporter implements DiagnosticReporter {
+    report(diagnostic: Diagnostic): void;
+}
+
+declare const nullReporter: DiagnosticReporter;
+
+declare class ThrowingReporter implements DiagnosticReporter {
+    report(diagnostic: Diagnostic): void;
+}
+
+declare const silentDiagnostics: Diagnostics;
+declare const warnDiagnostics: Diagnostics;
+declare const throwDiagnostics: Diagnostics;
+
+export { AsyncConsoleReporter, CollectingReporter, ConsoleReporter, DefaultPolicy, type DefaultPolicyOptions, type Diagnostic, DiagnosticCategory, DiagnosticCode, type DiagnosticInput, type DiagnosticPolicy, type DiagnosticReporter, type DiagnosticSuggestion, Diagnostics, Enforcement, type Err, type Formatter, type Ok, PraxisError, type Result, Severity, type SourceLocation, type SourcePosition, ThrowingReporter, type ValidationResult, err, formatDiagnostic, isAtLeast, nullReporter, ok, silentDiagnostics, throwDiagnostics, warnDiagnostics };

package/dist/_shared/diagnostics.js

@@ -0,0 +1,289 @@
+// ../../lib/diagnostics/src/category.ts
+var DiagnosticCategory = /* @__PURE__ */ ((DiagnosticCategory2) => {
+  DiagnosticCategory2[DiagnosticCategory2["Contract"] = 0] = "Contract";
+  DiagnosticCategory2[DiagnosticCategory2["HTML"] = 1] = "HTML";
+  DiagnosticCategory2[DiagnosticCategory2["ARIA"] = 2] = "ARIA";
+  DiagnosticCategory2[DiagnosticCategory2["Composition"] = 3] = "Composition";
+  DiagnosticCategory2[DiagnosticCategory2["Rendering"] = 4] = "Rendering";
+  DiagnosticCategory2[DiagnosticCategory2["Accessibility"] = 5] = "Accessibility";
+  DiagnosticCategory2[DiagnosticCategory2["Performance"] = 6] = "Performance";
+  DiagnosticCategory2[DiagnosticCategory2["Internal"] = 7] = "Internal";
+  DiagnosticCategory2[DiagnosticCategory2["Deprecation"] = 8] = "Deprecation";
+  DiagnosticCategory2[DiagnosticCategory2["Lint"] = 9] = "Lint";
+  return DiagnosticCategory2;
+})(DiagnosticCategory || {});
+
+// ../../lib/diagnostics/src/codes.ts
+var DiagnosticCode = /* @__PURE__ */ ((DiagnosticCode2) => {
+  DiagnosticCode2["MissingRequiredChild"] = "COMP1001";
+  DiagnosticCode2["InvalidParent"] = "COMP1002";
+  DiagnosticCode2["InvalidChild"] = "COMP1003";
+  DiagnosticCode2["UnexpectedChild"] = "COMP1004";
+  DiagnosticCode2["AmbiguousChild"] = "COMP1005";
+  DiagnosticCode2["CardinalityMin"] = "COMP1006";
+  DiagnosticCode2["CardinalityMax"] = "COMP1007";
+  DiagnosticCode2["PositionViolation"] = "COMP1008";
+  DiagnosticCode2["AllowedAsViolation"] = "COMP1009";
+  DiagnosticCode2["SlotExclusive"] = "SLOT1001";
+  DiagnosticCode2["SlotSingleChild"] = "SLOT1002";
+  DiagnosticCode2["SlotDiscardedChildren"] = "SLOT1003";
+  DiagnosticCode2["SlotRenderFn"] = "SLOT1004";
+  DiagnosticCode2["MissingAriaRelationship"] = "ARIA2001";
+  DiagnosticCode2["AriaViolation"] = "ARIA2002";
+  DiagnosticCode2["AriaAttributeInvalid"] = "ARIA2003";
+  DiagnosticCode2["AriaMissingLiveRegion"] = "ARIA2004";
+  DiagnosticCode2["AriaMissingAtomic"] = "ARIA2005";
+  DiagnosticCode2["AriaRelevantInvalidToken"] = "ARIA2006";
+  DiagnosticCode2["AriaRelevantSuperseded"] = "ARIA2007";
+  DiagnosticCode2["AriaInvalidRole"] = "ARIA2008";
+  DiagnosticCode2["AriaMissingAccessibleName"] = "ARIA2009";
+  DiagnosticCode2["AriaAttributeOnPresentational"] = "ARIA2010";
+  DiagnosticCode2["AriaHiddenOnFocusable"] = "ARIA2011";
+  DiagnosticCode2["AriaRequiredProperty"] = "ARIA2012";
+  DiagnosticCode2["AriaInvalidAttributeValue"] = "ARIA2013";
+  DiagnosticCode2["AriaRedundantLevelAttribute"] = "ARIA2014";
+  DiagnosticCode2["InvalidHeadingHierarchy"] = "HTML3001";
+  DiagnosticCode2["HtmlEmptyRole"] = "HTML3002";
+  DiagnosticCode2["HtmlImplicitRoleRedundant"] = "HTML3003";
+  DiagnosticCode2["HtmlImplicitRoleOverride"] = "HTML3004";
+  DiagnosticCode2["HtmlStandaloneRegionOverride"] = "HTML3005";
+  DiagnosticCode2["HtmlLandmarkRoleOverride"] = "HTML3006";
+  DiagnosticCode2["HtmlInvalidChild"] = "HTML3007";
+  DiagnosticCode2["InvalidRenderingTarget"] = "RENDER4001";
+  DiagnosticCode2["LintDeadCompoundKey"] = "LINT5001";
+  DiagnosticCode2["LintDeadCompoundValue"] = "LINT5002";
+  DiagnosticCode2["LintDeadCompoundNonLiteral"] = "LINT5003";
+  DiagnosticCode2["LintMissingStrict"] = "LINT5004";
+  DiagnosticCode2["LintInvalidDefaultKey"] = "LINT5005";
+  DiagnosticCode2["LintInvalidDefaultValue"] = "LINT5006";
+  DiagnosticCode2["LintInvalidDefaultNonLiteral"] = "LINT5007";
+  DiagnosticCode2["LintNegativeMin"] = "LINT5008";
+  DiagnosticCode2["LintNegativeMax"] = "LINT5009";
+  DiagnosticCode2["LintMaxLessThanMin"] = "LINT5010";
+  DiagnosticCode2["LintZeroMax"] = "LINT5011";
+  DiagnosticCode2["LintMultipleFirst"] = "LINT5012";
+  DiagnosticCode2["LintMultipleLast"] = "LINT5013";
+  DiagnosticCode2["LintMinSumExceedsCapacity"] = "LINT5014";
+  DiagnosticCode2["LintCardinalityViolation"] = "LINT5015";
+  DiagnosticCode2["LintAriaTagOverride"] = "LINT5016";
+  DiagnosticCode2["ContractUnknownVariantDim"] = "COMP1010";
+  DiagnosticCode2["ContractUnknownVariantValue"] = "COMP1011";
+  DiagnosticCode2["ContractUnknownRecipeKey"] = "COMP1012";
+  DiagnosticCode2["ContractInvalidVariantValue"] = "COMP1013";
+  DiagnosticCode2["TailwindMultipleDisplayProps"] = "CSS6001";
+  DiagnosticCode2["TailwindReservedLayoutLiteral"] = "CSS6002";
+  DiagnosticCode2["TailwindDeadVariantClass"] = "CSS6003";
+  DiagnosticCode2["PluginInvalidShape"] = "PLUGIN7001";
+  DiagnosticCode2["PluginPipelineReturnType"] = "PLUGIN7002";
+  DiagnosticCode2["InternalError"] = "INTERNAL9000";
+  return DiagnosticCode2;
+})(DiagnosticCode || {});
+
+// ../../lib/diagnostics/src/error.ts
+var PraxisError = class extends Error {
+  diagnostic;
+  constructor(diagnostic) {
+    super(diagnostic.message);
+    this.name = "PraxisError";
+    this.diagnostic = diagnostic;
+  }
+};
+
+// ../../lib/diagnostics/src/severity.ts
+var Severity = /* @__PURE__ */ ((Severity2) => {
+  Severity2[Severity2["Debug"] = 0] = "Debug";
+  Severity2[Severity2["Info"] = 1] = "Info";
+  Severity2[Severity2["Warning"] = 2] = "Warning";
+  Severity2[Severity2["Error"] = 3] = "Error";
+  Severity2[Severity2["Fatal"] = 4] = "Fatal";
+  return Severity2;
+})(Severity || {});
+function isAtLeast(s, threshold) {
+  return s >= threshold;
+}
+
+// ../../lib/diagnostics/src/policy.ts
+var Enforcement = /* @__PURE__ */ ((Enforcement2) => {
+  Enforcement2[Enforcement2["Ignore"] = 0] = "Ignore";
+  Enforcement2[Enforcement2["Report"] = 1] = "Report";
+  Enforcement2[Enforcement2["Throw"] = 2] = "Throw";
+  return Enforcement2;
+})(Enforcement || {});
+var DefaultPolicy = class {
+  reportThreshold;
+  throwThreshold;
+  constructor({
+    reportThreshold = 1 /* Info */,
+    throwThreshold = 4 /* Fatal */
+  } = {}) {
+    this.reportThreshold = reportThreshold;
+    this.throwThreshold = throwThreshold;
+  }
+  resolve(diagnostic) {
+    if (diagnostic.severity >= this.throwThreshold) return 2 /* Throw */;
+    if (diagnostic.severity >= this.reportThreshold) return 1 /* Report */;
+    return 0 /* Ignore */;
+  }
+};
+
+// ../../lib/diagnostics/src/diagnostics.ts
+var Diagnostics = class {
+  reporter;
+  policy;
+  // Pre-computed at construction time: true if Warning-level diagnostics are not ignored.
+  active;
+  constructor(reporter, policy = new DefaultPolicy()) {
+    this.reporter = reporter;
+    this.policy = policy;
+    this.active = policy.resolve({ severity: 2 /* Warning */ }) !== 0 /* Ignore */;
+  }
+  report(diagnostic) {
+    const enforcement = this.policy.resolve(diagnostic);
+    if (enforcement === 0 /* Ignore */) return diagnostic;
+    if (enforcement === 2 /* Throw */) throw new PraxisError(diagnostic);
+    this.reporter.report(diagnostic);
+    return diagnostic;
+  }
+  warn(input) {
+    return this.report({ ...input, severity: 2 /* Warning */ });
+  }
+  error(input) {
+    return this.report({ ...input, severity: 3 /* Error */ });
+  }
+  info(input) {
+    return this.report({ ...input, severity: 1 /* Info */ });
+  }
+};
+
+// ../../lib/diagnostics/src/formatter.ts
+function formatDiagnostic(diagnostic) {
+  const level = Severity[diagnostic.severity];
+  const category = DiagnosticCategory[diagnostic.category];
+  const prefix = category !== void 0 ? `[${category}] ` : "";
+  return `${level} ${diagnostic.code}: ${prefix}${diagnostic.message}`;
+}
+
+// ../../lib/diagnostics/src/result.ts
+function ok(value) {
+  return { ok: true, value };
+}
+function err(error) {
+  return { ok: false, error };
+}
+
+// ../../lib/diagnostics/src/async-console-reporter.ts
+var AsyncConsoleReporter = class {
+  pending = /* @__PURE__ */ new Set();
+  scheduled = false;
+  report(diagnostic) {
+    const message = formatDiagnostic(diagnostic);
+    if (this.pending.has(message)) return;
+    this.pending.add(message);
+    if (!this.scheduled) {
+      this.scheduled = true;
+      queueMicrotask(() => {
+        this.scheduled = false;
+        for (const msg of this.pending) {
+          console.warn(msg);
+        }
+        this.pending.clear();
+      });
+    }
+  }
+  /** Clears pending messages. Exposed for test isolation only. */
+  reset() {
+    this.pending.clear();
+    this.scheduled = false;
+  }
+};
+
+// ../../lib/diagnostics/src/collecting-reporter.ts
+var CollectingReporter = class {
+  collected = [];
+  report(diagnostic) {
+    this.collected.push(diagnostic);
+  }
+  get diagnostics() {
+    return this.collected;
+  }
+  clear() {
+    this.collected.length = 0;
+  }
+};
+
+// ../../lib/diagnostics/src/console-reporter.ts
+var ConsoleReporter = class {
+  report(diagnostic) {
+    const message = formatDiagnostic(diagnostic);
+    switch (diagnostic.severity) {
+      case 0 /* Debug */:
+        console.debug(message);
+        break;
+      case 1 /* Info */:
+        console.info(message);
+        break;
+      case 2 /* Warning */:
+        console.warn(message);
+        break;
+      case 3 /* Error */:
+      case 4 /* Fatal */:
+        console.error(message);
+        break;
+    }
+  }
+};
+
+// ../../lib/diagnostics/src/null-reporter.ts
+var nullReporter = {
+  report() {
+  }
+};
+
+// ../../lib/diagnostics/src/throwing-reporter.ts
+var ThrowingReporter = class {
+  report(diagnostic) {
+    throw new PraxisError(diagnostic);
+  }
+};
+
+// ../../lib/diagnostics/src/presets.ts
+var ignoreAllPolicy = {
+  resolve(_) {
+    return 0 /* Ignore */;
+  }
+};
+var warnOnlyReporter = {
+  report(diagnostic) {
+    console.warn(formatDiagnostic(diagnostic));
+  }
+};
+var silentDiagnostics = new Diagnostics(nullReporter, ignoreAllPolicy);
+var warnDiagnostics = new Diagnostics(
+  warnOnlyReporter,
+  new DefaultPolicy({ reportThreshold: 2 /* Warning */, throwThreshold: 4 /* Fatal */ })
+);
+var throwDiagnostics = new Diagnostics(
+  new ConsoleReporter(),
+  new DefaultPolicy({ reportThreshold: 2 /* Warning */, throwThreshold: 3 /* Error */ })
+);
+export {
+  AsyncConsoleReporter,
+  CollectingReporter,
+  ConsoleReporter,
+  DefaultPolicy,
+  DiagnosticCategory,
+  DiagnosticCode,
+  Diagnostics,
+  Enforcement,
+  PraxisError,
+  Severity,
+  ThrowingReporter,
+  err,
+  formatDiagnostic,
+  isAtLeast,
+  nullReporter,
+  ok,
+  silentDiagnostics,
+  throwDiagnostics,
+  warnDiagnostics
+};