@usefragments/core 1.0.0

package/src/facts/types.ts

@@ -0,0 +1,614 @@
+/**
+ * Fact IR — discriminated union of governance facts.
+ *
+ * Facts are content-addressed records. Their ID is a deterministic hash of a
+ * canonical identity tuple (kind + identity fields), never the source location
+ * — moving a line in a source file does not perturb component or policy fact
+ * IDs. Usage facts include source location for evidence display, but their ID
+ * is derived only from structural identity (file + node path + element).
+ *
+ * This module owns only the types. Hashing lives in `./ids.ts`, builders in
+ * `./builders.ts`, the in-memory store in `./fact-index.ts`, and conversion
+ * from compiled fragments + governance config in `./compile.ts`.
+ */
+
+import type { GovernanceSeverity } from "../governance.js";
+
+// ---------------------------------------------------------------------------
+// Branded IDs
+// ---------------------------------------------------------------------------
+
+declare const componentIdBrand: unique symbol;
+declare const factIdBrand: unique symbol;
+
+export type ComponentId = string & { readonly [componentIdBrand]: void };
+export type FactId = string & { readonly [factIdBrand]: void };
+
+// ---------------------------------------------------------------------------
+// Source location (carried by usage facts; never part of fact identity)
+// ---------------------------------------------------------------------------
+
+export interface FactLocation {
+  file: string;
+  line: number;
+  column: number;
+  endLine?: number;
+  endColumn?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Component facts
+// ---------------------------------------------------------------------------
+
+interface BaseFact {
+  id: FactId;
+}
+
+export interface ComponentMetadataFact extends BaseFact {
+  kind: "component";
+  componentId: ComponentId;
+  name: string;
+  description?: string;
+  category?: string;
+  filePath?: string;
+}
+
+export interface ComponentCapabilityFact extends BaseFact {
+  kind: "component_capability";
+  componentId: ComponentId;
+  capability: string;
+}
+
+export interface PropMetadataFact extends BaseFact {
+  kind: "prop_metadata";
+  componentId: ComponentId;
+  prop: string;
+  type: string;
+  values?: string[];
+  required: boolean;
+  default?: unknown;
+  description?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Policy facts (component-scoped)
+// ---------------------------------------------------------------------------
+
+export interface PropValueAvoidedFact extends BaseFact {
+  kind: "prop_value_avoided";
+  componentId: ComponentId;
+  prop: string;
+  value: unknown;
+  because: string;
+  suggest?: string;
+  severity: GovernanceSeverity;
+}
+
+export interface PropValueForbiddenFact extends BaseFact {
+  kind: "prop_value_forbidden";
+  componentId: ComponentId;
+  prop: string;
+  value: unknown;
+  pathPattern?: string;
+  because: string;
+  replaceWith?: unknown;
+  severity: GovernanceSeverity;
+}
+
+export interface A11yNameRequiredFact extends BaseFact {
+  kind: "a11y_name_required";
+  componentId: ComponentId;
+  because: string;
+  severity: GovernanceSeverity;
+}
+
+// ---------------------------------------------------------------------------
+// Policy facts (global)
+// ---------------------------------------------------------------------------
+
+export interface ScaleFact extends BaseFact {
+  kind: "scale";
+  name: string;
+  unit: "px" | "rem";
+  rootFontSizePx?: number;
+  emBasePx?: number;
+}
+
+export interface ScaleValueFact extends BaseFact {
+  kind: "scale_value";
+  scale: string;
+  value: number;
+}
+
+export interface StyleRawColorForbiddenFact extends BaseFact {
+  kind: "style_raw_color_forbidden";
+  except: string[];
+  prefer: "token" | "css-variable";
+  severity: GovernanceSeverity;
+}
+
+export interface StyleRawDimensionForbiddenFact extends BaseFact {
+  kind: "style_raw_dimension_forbidden";
+  appliesTo: string[];
+  prefer: "token" | "css-variable";
+  severity: GovernanceSeverity;
+}
+
+export interface StylePropertyScaleFact extends BaseFact {
+  kind: "style_property_scale";
+  property: string;
+  scale: string;
+  severity: GovernanceSeverity;
+}
+
+export interface StyleFontSizeScaleFact extends BaseFact {
+  kind: "style_font_size_scale";
+  scale: string;
+  severity: GovernanceSeverity;
+}
+
+export interface StyleCssVarsMustBeDefinedFact extends BaseFact {
+  kind: "style_css_vars_must_be_defined";
+  severity: GovernanceSeverity;
+}
+
+/**
+ * A token name in the contract vocabulary (from the user's selected token source
+ * files). A DEDICATED channel — separate from `token_definition` — so the
+ * off-contract-drift rule (FUI2015) judges `var(--x)` against the CONTRACT
+ * vocabulary, while the raw-* rules + scale detection keep reading the project's
+ * local `token_definition` tokens unchanged.
+ */
+export interface ContractTokenFact extends BaseFact {
+  kind: "contract_token";
+  /** Custom-property name, normalized to `--`-prefixed form. */
+  name: string;
+}
+
+export interface JsxUnknownPropsForbiddenFact extends BaseFact {
+  kind: "jsx_unknown_props_forbidden";
+  severity: GovernanceSeverity;
+}
+
+export interface JsxInlineStyleForbiddenRawFact extends BaseFact {
+  kind: "jsx_inline_style_forbidden_raw";
+  property: string;
+  severity: GovernanceSeverity;
+}
+
+export interface JsxImportPathPreferredFact extends BaseFact {
+  kind: "jsx_import_path_preferred";
+  from: string;
+  to: string;
+  imported?: string;
+  because?: string;
+  severity: GovernanceSeverity;
+}
+
+export interface JsxComponentPreferredFact extends BaseFact {
+  kind: "jsx_component_preferred";
+  from: ComponentId;
+  to: ComponentId;
+  because?: string;
+  severity: GovernanceSeverity;
+}
+
+/**
+ * A design token from the system. Used by fixes (e.g., raw color → token
+ * substitution) and rules that need to know the token vocabulary. Identity is
+ * the token `name`; two scans of the same token registry produce the same ID.
+ */
+export interface TokenDefinitionFact extends BaseFact {
+  kind: "token_definition";
+  /** Token identifier, e.g., "fui-color-accent" or "--fui-color-accent". */
+  name: string;
+  /** Resolved value, e.g., "#2563eb". */
+  value: string;
+  /** Loose category bucket. Phase 6 only differentiates `color` from others. */
+  category?: "color" | "spacing" | "typography" | "radius" | "shadow" | "other";
+  /**
+   * How the token is referenced from authored styles, inferred from its source.
+   * Governs whether a "use the token" fix can be *applied* automatically: a
+   * `css-var`/`scss-var` reference resolves verbatim, but a `scss-map` member
+   * (`$colors-primary` minted from a Sass map) or a `dtcg` JSON token (no CSS
+   * custom property emitted) does not — those are surfaced as suggestions, not
+   * deterministic rewrites, so the fixer never writes non-compiling output.
+   * Absent on legacy/hand-built facts, which are treated as safe.
+   */
+  referenceFormat?: "css-var" | "scss-var" | "scss-map" | "dtcg";
+}
+
+export interface TailwindPaletteAllowFact extends BaseFact {
+  kind: "tailwind_palette_allow";
+  patterns: string[];
+  severity: GovernanceSeverity;
+}
+
+export interface TailwindPaletteDenyFact extends BaseFact {
+  kind: "tailwind_palette_deny";
+  patterns: string[];
+  severity: GovernanceSeverity;
+}
+
+export interface TailwindUnknownClassEnabledFact extends BaseFact {
+  kind: "tailwind_unknown_class_enabled";
+  severity: GovernanceSeverity;
+}
+
+export interface GovernanceRuleConfigFact extends BaseFact {
+  kind: "governance_rule_config";
+  ruleId: string;
+  enabled: boolean;
+  severity?: GovernanceSeverity;
+  options?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Usage facts (Phase 4 will populate these; types live here so the index and
+// rules can reference them already).
+// ---------------------------------------------------------------------------
+
+export interface UsageNodeFact extends BaseFact {
+  kind: "usage_node";
+  file: string;
+  /**
+   * Stable structural path: a `rootIndex:` token (the root tree's index within
+   * the file) then `/`-joined opaque segments, e.g. `"0:2/1"`. Segments are
+   * emitted by the framework adapter (`computeNodePath`) and compared whole —
+   * never parsed inside (see the usage-node-fact contract); `regionsByPrefix`
+   * relies on this grammar.
+   */
+  nodePath: string;
+  element: string;
+  /**
+   * Normalized ARIA role of the element when statically declared (a
+   * `role="status"` attribute or equivalent). Framework-neutral: every adapter
+   * populates it from its own markup (JSX attribute, Vue/Svelte template
+   * binding, …) so semantic rules can reason over roles without knowing the
+   * framework. Never part of fact identity.
+   */
+  role?: string;
+  /**
+   * Normalized interactivity signal: true when the element carries an
+   * interaction handler (click/key/pointer/…) or is intrinsically interactive.
+   * Framework-neutral — the adapter decides how to detect it. Never part of
+   * fact identity.
+   */
+  interactive?: boolean;
+  location: FactLocation;
+}
+
+export interface UsageComponentFact extends BaseFact {
+  kind: "usage_component";
+  nodeId: FactId;
+  componentId: ComponentId;
+}
+
+export interface UsageImportFact extends BaseFact {
+  kind: "usage_import";
+  file: string;
+  local: string;
+  imported: string;
+  source: string;
+  namespace?: boolean;
+  location: FactLocation;
+}
+
+export interface UsagePropResolvedFact extends BaseFact {
+  kind: "usage_prop_resolved";
+  nodeId: FactId;
+  prop: string;
+  resolution: "static" | "dynamic" | "spread" | "jsx";
+  value?: unknown;
+  location?: FactLocation;
+}
+
+export interface UsageInlineStyleFact extends BaseFact {
+  kind: "usage_inline_style";
+  nodeId: FactId;
+  property: string;
+  valueKind: "static" | "number" | "css-variable";
+  value: string;
+}
+
+export interface UsageTextChildFact extends BaseFact {
+  kind: "usage_text_child";
+  nodeId: FactId;
+  text: string;
+  index: number;
+}
+
+// ---------------------------------------------------------------------------
+// Tailwind className facts.
+//
+// `classname_literal` carries fully-bounded class tokens parsed out of a JSX
+// `className` attribute. `classname_dynamic` records a piece of the
+// attribute that could not be statically resolved (variables, unknown helper
+// calls, template interpolations, spread props, …). Both join back to the
+// parent JSX element via `nodeId`.
+//
+// Identity is `{nodeId, attr, origin/reason, originPath}` — `originPath`
+// disambiguates multiple sibling facts on a single element so the FactIndex
+// never sees a collision when one element produces many className facts.
+// ---------------------------------------------------------------------------
+
+export type ClassNameOrigin =
+  | "attribute"
+  | "clsx"
+  | "cn"
+  | "classnames"
+  | "twMerge"
+  | "tw"
+  | "cva-arg"
+  | "template";
+
+export interface ClassNameLiteralFact extends BaseFact {
+  kind: "classname_literal";
+  file: string;
+  nodeId: FactId;
+  attr: string;
+  classes: string[];
+  origin: ClassNameOrigin;
+  originPath: string;
+  location: FactLocation;
+}
+
+export type ClassNameDynamicReason =
+  | "identifier"
+  | "computed"
+  | "spread"
+  | "unknown_helper"
+  | "template_interpolation"
+  | "cva-arg";
+
+export interface ClassNameDynamicFact extends BaseFact {
+  kind: "classname_dynamic";
+  file: string;
+  nodeId: FactId;
+  attr: string;
+  reason: ClassNameDynamicReason;
+  snippet: string;
+  originPath: string;
+  location: FactLocation;
+}
+
+export type ClassNameFact = ClassNameLiteralFact | ClassNameDynamicFact;
+
+export type TailwindModifierKind =
+  | "media"
+  | "state"
+  | "dark"
+  | "aria"
+  | "data"
+  | "selector"
+  | "container"
+  | "unknown";
+
+export interface TailwindModifier {
+  raw: string;
+  kind: TailwindModifierKind;
+}
+
+export type TailwindValue =
+  | { kind: "token"; token: string; opacity?: string }
+  | { kind: "arbitrary"; raw: string }
+  | { kind: "css-variable"; ref: string }
+  | { kind: "none" };
+
+export interface TailwindClassFact extends BaseFact {
+  kind: "tailwind_class";
+  file: string;
+  /** Joins to the parent JSX element and originating classname_literal. */
+  nodeId: FactId;
+  /** Original class token, e.g. `dark:hover:!bg-red-500/50`. */
+  raw: string;
+  /** Stable path from the originating classname_literal plus class index. */
+  originPath: string;
+  prefix: string | null;
+  modifiers: TailwindModifier[];
+  important: boolean;
+  negative: boolean;
+  utility: string;
+  value: TailwindValue;
+  location: FactLocation;
+}
+
+export interface ThemeDeclarationFact extends BaseFact {
+  kind: "theme_declaration";
+  file: string;
+  name: string;
+  value: string;
+  declarationPath: string;
+  inline: boolean;
+  flavor: "default" | "inline" | "reference" | "static" | "unknown";
+  location: FactLocation;
+}
+
+export interface SuppressionDirectiveFact extends BaseFact {
+  kind: "suppression_directive";
+  file: string;
+  line: number;
+  column: number;
+  code: string;
+  reason: string;
+  expiresOn?: string;
+  attachedLine?: number;
+  attachedTo?: FactId;
+  /**
+   * Which authoring syntax produced the directive. Absent (legacy facts) means
+   * `@fragments-expect-error`; `"allow"` is the `fragments-allow FUI####: reason`
+   * flavor, which carries no expiry syntax and is reported to Cloud as a bypass
+   * event when it matches a finding.
+   */
+  directive?: "expect-error" | "allow";
+}
+
+export type TailwindResolvedKind =
+  | "color"
+  | "length"
+  | "shadow"
+  | "font-family"
+  | "font-size"
+  | "radius"
+  | "duration"
+  | "unknown";
+
+export type TailwindResolutionSource = "theme-css" | "default" | "unknown";
+
+export type TailwindResolvedValue =
+  | {
+      kind: Exclude<TailwindResolvedKind, "unknown">;
+      value: string;
+      source: Exclude<TailwindResolutionSource, "unknown">;
+      inline?: boolean;
+    }
+  | { kind: "unknown"; source: "unknown" };
+
+export interface TailwindTokenResolvedFact extends BaseFact {
+  kind: "tailwind_token_resolved";
+  utility: string;
+  token: string;
+  resolved: TailwindResolvedValue;
+}
+
+/**
+ * A raw declaration extracted from a CSS/SCSS file. Distinct from
+ * `usage_inline_style` because there is no JSX node — declarations live in a
+ * selector chain. Identity is `{ file, selector, declarationPath, property }`
+ * so the ID stays stable when other lines move.
+ */
+export interface StyleDeclarationFact extends BaseFact {
+  kind: "style_declaration";
+  file: string;
+  /** Full selector chain (e.g., ".button .icon") or "" for root-level. */
+  selector: string;
+  /** Stable structural index within the parent selector (e.g., "0", "0/2"). */
+  declarationPath: string;
+  property: string;
+  value: string;
+  location: FactLocation;
+  /**
+   * True when the declaration came from a configured token source file. Raw
+   * value rules use this to allow token registries to mint values while still
+   * flagging ad hoc custom properties in product code.
+   */
+  declaredTokenSource?: boolean;
+}
+
+export type UnsupportedStyleReason =
+  | "dynamic-template-expression"
+  | "dynamic-object-value"
+  | "object-spread"
+  | "unsupported-array-element";
+
+export interface StyleUnsupportedFact extends BaseFact {
+  kind: "style_unsupported";
+  file: string;
+  source: "css-in-js";
+  syntax: string;
+  selector: string;
+  declarationPath: string;
+  property?: string;
+  reason: UnsupportedStyleReason;
+  location: FactLocation;
+}
+
+// ---------------------------------------------------------------------------
+// Classifier facts
+// ---------------------------------------------------------------------------
+
+export interface CanonicalCandidateFact extends BaseFact {
+  kind: "canonical_candidate";
+  componentId: ComponentId;
+  canonical: string;
+  confidence: number;
+  band: "auto" | "suggested" | "possible" | "tie" | "unknown";
+  location?: FactLocation;
+  classifierVersion: string;
+  vocabVersion: string;
+  evidence: unknown[];
+  userConfirmed?: boolean;
+}
+
+export interface CanonicalMappingFact extends BaseFact {
+  kind: "canonical_mapping";
+  componentId: ComponentId;
+  canonical: string;
+  status: "confirmed" | "proposed" | "unknown";
+  confidence: number;
+  location?: FactLocation;
+}
+
+export interface StructuralConfidenceFact extends BaseFact {
+  kind: "structural_confidence";
+  componentId: ComponentId;
+  canonical: string;
+  confidence: number;
+  signalCount: number;
+  location?: FactLocation;
+}
+
+export interface CanonicalReplacementFact extends BaseFact {
+  kind: "canonical_replacement";
+  componentId: ComponentId;
+  canonical: string;
+  importPath?: string;
+  componentName?: string;
+  confidence: number;
+  location?: FactLocation;
+}
+
+// ---------------------------------------------------------------------------
+// Discriminated unions
+// ---------------------------------------------------------------------------
+
+export type ComponentLevelFact = ComponentMetadataFact | ComponentCapabilityFact | PropMetadataFact;
+
+export type PolicyFact =
+  | PropValueAvoidedFact
+  | PropValueForbiddenFact
+  | A11yNameRequiredFact
+  | ScaleFact
+  | ScaleValueFact
+  | StyleRawColorForbiddenFact
+  | StyleRawDimensionForbiddenFact
+  | StylePropertyScaleFact
+  | StyleFontSizeScaleFact
+  | StyleCssVarsMustBeDefinedFact
+  | ContractTokenFact
+  | JsxUnknownPropsForbiddenFact
+  | JsxInlineStyleForbiddenRawFact
+  | JsxImportPathPreferredFact
+  | JsxComponentPreferredFact
+  | TokenDefinitionFact
+  | TailwindPaletteAllowFact
+  | TailwindPaletteDenyFact
+  | TailwindUnknownClassEnabledFact
+  | GovernanceRuleConfigFact;
+
+export type UsageFact =
+  | UsageNodeFact
+  | UsageComponentFact
+  | UsageImportFact
+  | UsagePropResolvedFact
+  | UsageInlineStyleFact
+  | UsageTextChildFact
+  | StyleDeclarationFact
+  | StyleUnsupportedFact
+  | ClassNameLiteralFact
+  | ClassNameDynamicFact
+  | TailwindClassFact
+  | ThemeDeclarationFact
+  | SuppressionDirectiveFact
+  | TailwindTokenResolvedFact
+  | CanonicalCandidateFact
+  | CanonicalMappingFact
+  | StructuralConfidenceFact
+  | CanonicalReplacementFact;
+
+export type Fact = ComponentLevelFact | PolicyFact | UsageFact;
+
+export type FactKind = Fact["kind"];
+
+/** Narrows a Fact union by kind. */
+export type FactOfKind<K extends FactKind> = Extract<Fact, { kind: K }>;