Skip to content

Write HTML. Render video. Built for agents.

2.1 KB
Raw Blame
export type HyperframeLintSeverity = "error" | "warning" | "info";

export type HyperframeLintFinding = {
  code: string;
  severity: HyperframeLintSeverity;
  message: string;
  file?: string;
  /** One-based coordinates in the original source; absent when no unique location exists. */
  line?: number;
  column?: number;
  selector?: string;
  elementId?: string;
  fixHint?: string;
  snippet?: string;
  /** Optional standalone entry that command-specific guidance can act on. */
  suggestedComposition?: string;
};

/**
 * Where a single lint pass spent its time. Attributed per rule-source module
 * ("gsap", "core", ...) rather than per rule, plus the single slowest rule as
 * `<group>#<index-within-group>` so a pathological rule is locatable.
 */
export type LintTimings = {
  totalMs: number;
  groupMs: Record<string, number>;
  slowestRule: string;
  slowestRuleMs: number;
};

export type HyperframeLintResult = {
  ok: boolean;
  errorCount: number;
  warningCount: number;
  infoCount: number;
  findings: HyperframeLintFinding[];
  timings?: LintTimings;
};

export type HyperframeLinterOptions = {
  filePath?: string;
  isSubComposition?: boolean;
  compSrcPath?: string;
  externalStyles?: Array<{
    href: string;
    content: string;
    file?: string;
    rootRelativePath?: string;
  }>;
  /**
   * Set to `true` when linting compositions destined for distributed / Lambda
   * rendering, where system-font capture (`allowSystemFontCapture`) is
   * disabled.  When `true`, the `system_font_will_alias` rule is elevated from
   * `"info"` to `"warning"` because the alias substitution will NOT happen at
   * render time — the font will silently fall back to whatever the OS provides.
   */
  distributed?: boolean;
  /** Who is running the lint: Studio raises the structure rules to errors, the CLI keeps them warnings. */
  host?: "studio" | "cli";
};

// A rule is a function: receives parsed context, returns zero or more findings.
// Rules may be async (e.g. when lazy-loading heavy dependencies like recast).
export type LintRule<TContext> = (
  ctx: TContext,
) => HyperframeLintFinding[] | Promise<HyperframeLintFinding[]>;