@usefragments/core 1.0.0

package/src/facts/fact-index.ts

@@ -0,0 +1,394 @@
+/**
+ * In-memory index over Fact records.
+ *
+ * Rules consume the index, never raw fact arrays. The query surface is
+ * intentionally narrow: components.byId / propsOf / propOf / capabilitiesOf,
+ * and policy.<predicate>(componentId, opts?). This keeps Phase 5 rules pure
+ * and content-addressed.
+ */
+
+import type {
+  A11yNameRequiredFact,
+  ComponentCapabilityFact,
+  ComponentId,
+  ComponentMetadataFact,
+  Fact,
+  FactId,
+  FactKind,
+  FactOfKind,
+  GovernanceRuleConfigFact,
+  JsxComponentPreferredFact,
+  JsxImportPathPreferredFact,
+  JsxInlineStyleForbiddenRawFact,
+  JsxUnknownPropsForbiddenFact,
+  PropMetadataFact,
+  PropValueAvoidedFact,
+  PropValueForbiddenFact,
+  ScaleFact,
+  ScaleValueFact,
+  StyleCssVarsMustBeDefinedFact,
+  StyleFontSizeScaleFact,
+  StylePropertyScaleFact,
+  StyleRawColorForbiddenFact,
+  StyleRawDimensionForbiddenFact,
+  TailwindPaletteAllowFact,
+  TailwindPaletteDenyFact,
+  TailwindUnknownClassEnabledFact,
+  TokenDefinitionFact,
+} from "./types.js";
+import { canonicalJson } from "./ids.js";
+import { canonicalizeOwnedComponentId, canonicalizeOwnedImport } from "../package-identity.js";
+import { ownedComponentIdsEqual, ownedImportsEqual } from "../package-identity-match.js";
+
+export interface FactEvidence {
+  factId: FactId;
+  fact: Fact;
+}
+
+interface FactWithComponent {
+  componentId: ComponentId;
+}
+
+function hasComponentId(fact: Fact): fact is Fact & FactWithComponent {
+  return "componentId" in fact && typeof (fact as FactWithComponent).componentId === "string";
+}
+
+function logicalComponentId(componentId: ComponentId): ComponentId {
+  return canonicalizeOwnedComponentId(componentId) as ComponentId;
+}
+
+function logicalFactForComparison(fact: Fact): Record<string, unknown> {
+  if (fact.kind === "jsx_import_path_preferred") {
+    return {
+      ...fact,
+      from: canonicalizeOwnedImport(fact.from),
+      to: canonicalizeOwnedImport(fact.to),
+    };
+  }
+  if (fact.kind === "jsx_component_preferred") {
+    return {
+      ...fact,
+      from: logicalComponentId(fact.from),
+      to: logicalComponentId(fact.to),
+    };
+  }
+  if (fact.kind === "usage_import") {
+    return { ...fact, source: canonicalizeOwnedImport(fact.source) };
+  }
+  if (hasComponentId(fact)) {
+    return { ...fact, componentId: logicalComponentId(fact.componentId) };
+  }
+  return { ...fact };
+}
+
+function uniqueByLogicalIdentity<T>(items: readonly T[], keyOf: (item: T) => string): T[] {
+  const seen = new Set<string>();
+  return items.filter((item) => {
+    const key = keyOf(item);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+/**
+ * Match a literal path against a simple glob pattern. `*` matches any run of
+ * non-separator characters; `**` matches any run of characters including
+ * separators.
+ */
+export function matchesGlob(path: string, pattern: string): boolean {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  const expanded = escaped
+    .replace(/\*\*/g, "::DOUBLE::")
+    .replace(/\*/g, "[^/]*")
+    .replace(/::DOUBLE::/g, ".*");
+  return new RegExp(`^${expanded}$`).test(path);
+}
+
+export class FactIndex {
+  private readonly facts = new Map<FactId, Fact>();
+  private readonly idsByKind = new Map<FactKind, Set<FactId>>();
+  private readonly idsByComponent = new Map<ComponentId, Set<FactId>>();
+
+  add(fact: Fact): void {
+    const existing = this.facts.get(fact.id);
+    if (existing) {
+      if (
+        canonicalJson(logicalFactForComparison(existing)) !==
+        canonicalJson(logicalFactForComparison(fact))
+      ) {
+        console.warn(
+          `FactIndex: conflicting facts for id ${fact.id} — keeping first fact, skipping ${describeFactForConflict(fact)}`
+        );
+      }
+      return;
+    }
+    this.facts.set(fact.id, fact);
+
+    let byKind = this.idsByKind.get(fact.kind);
+    if (!byKind) {
+      byKind = new Set();
+      this.idsByKind.set(fact.kind, byKind);
+    }
+    byKind.add(fact.id);
+
+    if (hasComponentId(fact)) {
+      const componentId = logicalComponentId(fact.componentId);
+      let byComponent = this.idsByComponent.get(componentId);
+      if (!byComponent) {
+        byComponent = new Set();
+        this.idsByComponent.set(componentId, byComponent);
+      }
+      byComponent.add(fact.id);
+    }
+  }
+
+  addMany(facts: Iterable<Fact>): void {
+    for (const fact of facts) this.add(fact);
+  }
+
+  get(id: FactId): Fact | undefined {
+    return this.facts.get(id);
+  }
+
+  has(id: FactId): boolean {
+    return this.facts.has(id);
+  }
+
+  size(): number {
+    return this.facts.size;
+  }
+
+  all(): Fact[] {
+    return [...this.facts.values()];
+  }
+
+  byKind<K extends FactKind>(kind: K): Array<FactOfKind<K>> {
+    const ids = this.idsByKind.get(kind);
+    if (!ids) return [];
+    const out: FactOfKind<K>[] = [];
+    for (const id of ids) {
+      const fact = this.facts.get(id);
+      if (fact && fact.kind === kind) out.push(fact as FactOfKind<K>);
+    }
+    return out;
+  }
+
+  /**
+   * Resolve evidence for a list of fact IDs. Throws if any ID is missing —
+   * findings must never reference facts that aren't in the index.
+   */
+  evidence(ids: readonly FactId[]): FactEvidence[] {
+    const missing: FactId[] = [];
+    const out: FactEvidence[] = [];
+    for (const id of ids) {
+      const fact = this.facts.get(id);
+      if (!fact) {
+        missing.push(id);
+        continue;
+      }
+      out.push({ factId: id, fact });
+    }
+    if (missing.length) {
+      throw new Error(`FactIndex.evidence: missing facts in index: ${missing.join(", ")}`);
+    }
+    return out;
+  }
+
+  // ---------------------------------------------------------------------
+  // Component queries
+  // ---------------------------------------------------------------------
+
+  components = {
+    list: (): ComponentMetadataFact[] =>
+      uniqueByLogicalIdentity(this.byKind("component"), (fact) =>
+        canonicalJson({
+          ...logicalFactForComparison(fact),
+          id: undefined,
+        })
+      ),
+    byId: (componentId: ComponentId): ComponentMetadataFact | undefined =>
+      this.byComponentOfKind<ComponentMetadataFact>(componentId, "component")[0],
+    propsOf: (componentId: ComponentId): PropMetadataFact[] =>
+      this.byComponentOfKind<PropMetadataFact>(componentId, "prop_metadata"),
+    propOf: (componentId: ComponentId, prop: string): PropMetadataFact | undefined =>
+      this.components.propsOf(componentId).find((p) => p.prop === prop),
+    capabilitiesOf: (componentId: ComponentId): ComponentCapabilityFact[] =>
+      this.byComponentOfKind<ComponentCapabilityFact>(componentId, "component_capability"),
+  };
+
+  // ---------------------------------------------------------------------
+  // Policy queries
+  // ---------------------------------------------------------------------
+
+  policy = {
+    forbiddenPropValues: (
+      componentId: ComponentId,
+      opts: { prop?: string; path?: string; value?: unknown } = {}
+    ): PropValueForbiddenFact[] => {
+      const all = this.byComponentOfKind<PropValueForbiddenFact>(
+        componentId,
+        "prop_value_forbidden"
+      );
+      return all.filter((fact) => {
+        if (opts.prop !== undefined && fact.prop !== opts.prop) return false;
+        if (opts.value !== undefined && fact.value !== opts.value) return false;
+        if (opts.path !== undefined && fact.pathPattern) {
+          if (!matchesGlob(opts.path, fact.pathPattern)) return false;
+        }
+        return true;
+      });
+    },
+
+    avoidedPropValues: (
+      componentId: ComponentId,
+      opts: { prop?: string; value?: unknown } = {}
+    ): PropValueAvoidedFact[] => {
+      const all = this.byComponentOfKind<PropValueAvoidedFact>(componentId, "prop_value_avoided");
+      return all.filter((fact) => {
+        if (opts.prop !== undefined && fact.prop !== opts.prop) return false;
+        if (opts.value !== undefined && fact.value !== opts.value) return false;
+        return true;
+      });
+    },
+
+    a11yNameRequired: (componentId: ComponentId): A11yNameRequiredFact | undefined =>
+      this.byComponentOfKind<A11yNameRequiredFact>(componentId, "a11y_name_required")[0],
+
+    scales: (): ScaleFact[] => this.byKind("scale"),
+
+    scale: (name: string): ScaleFact | undefined =>
+      this.byKind("scale").find((s) => s.name === name),
+
+    scaleValues: (name: string): ScaleValueFact[] =>
+      this.byKind("scale_value").filter((v) => v.scale === name),
+
+    rawColorPolicy: (): StyleRawColorForbiddenFact | undefined =>
+      this.byKind("style_raw_color_forbidden")[0],
+
+    rawDimensionPolicy: (): StyleRawDimensionForbiddenFact | undefined =>
+      this.byKind("style_raw_dimension_forbidden")[0],
+
+    propertyScale: (property: string): StylePropertyScaleFact | undefined =>
+      this.byKind("style_property_scale").find((p) => p.property === property),
+
+    fontSizeScale: (): StyleFontSizeScaleFact | undefined =>
+      this.byKind("style_font_size_scale")[0],
+
+    cssVarsMustBeDefined: (): StyleCssVarsMustBeDefinedFact | undefined =>
+      this.byKind("style_css_vars_must_be_defined")[0],
+
+    tailwindPaletteAllow: (): TailwindPaletteAllowFact | undefined =>
+      this.byKind("tailwind_palette_allow")[0],
+
+    tailwindPaletteDeny: (): TailwindPaletteDenyFact | undefined =>
+      this.byKind("tailwind_palette_deny")[0],
+
+    tailwindUnknownClassEnabled: (): TailwindUnknownClassEnabledFact | undefined =>
+      this.byKind("tailwind_unknown_class_enabled")[0],
+
+    ruleConfig: (ruleId: string): GovernanceRuleConfigFact | undefined =>
+      this.byKind("governance_rule_config").find((fact) => fact.ruleId === ruleId),
+
+    jsxUnknownPropsForbidden: (): JsxUnknownPropsForbiddenFact | undefined =>
+      this.byKind("jsx_unknown_props_forbidden")[0],
+
+    jsxInlineStyleForbiddenRaw: (
+      opts: { property?: string } = {}
+    ): JsxInlineStyleForbiddenRawFact[] => {
+      const all = this.byKind("jsx_inline_style_forbidden_raw");
+      return opts.property === undefined ? all : all.filter((f) => f.property === opts.property);
+    },
+
+    jsxImportPathPreferred: (
+      opts: { from?: string; imported?: string } = {}
+    ): JsxImportPathPreferredFact[] => {
+      const all = uniqueByLogicalIdentity(this.byKind("jsx_import_path_preferred"), (fact) =>
+        canonicalJson({
+          from: canonicalizeOwnedImport(fact.from),
+          to: canonicalizeOwnedImport(fact.to),
+          imported: fact.imported,
+          because: fact.because,
+          severity: fact.severity,
+        })
+      );
+      return all.filter((fact) => {
+        if (opts.from !== undefined && !ownedImportsEqual(fact.from, opts.from)) return false;
+        if (opts.imported !== undefined && fact.imported !== opts.imported) return false;
+        return true;
+      });
+    },
+
+    jsxComponentPreferred: (opts: { from?: ComponentId } = {}): JsxComponentPreferredFact[] => {
+      const all = uniqueByLogicalIdentity(this.byKind("jsx_component_preferred"), (fact) =>
+        canonicalJson({
+          from: canonicalizeOwnedComponentId(fact.from),
+          to: canonicalizeOwnedComponentId(fact.to),
+          because: fact.because,
+          severity: fact.severity,
+        })
+      );
+      return opts.from === undefined
+        ? all
+        : all.filter((fact) => ownedComponentIdsEqual(fact.from, opts.from!));
+    },
+  };
+
+  // ---------------------------------------------------------------------
+  // Token registry queries
+  // ---------------------------------------------------------------------
+
+  tokens = {
+    list: (): TokenDefinitionFact[] => this.byKind("token_definition"),
+    byCategory: (category: TokenDefinitionFact["category"]): TokenDefinitionFact[] =>
+      this.byKind("token_definition").filter((t) => t.category === category),
+  };
+
+  // ---------------------------------------------------------------------
+  // Internals
+  // ---------------------------------------------------------------------
+
+  private byComponentOfKind<F extends Fact>(componentId: ComponentId, kind: FactKind): F[] {
+    const ids = this.idsByComponent.get(logicalComponentId(componentId));
+    if (!ids) return [];
+    const out: F[] = [];
+    const seen = new Set<string>();
+    for (const id of ids) {
+      const fact = this.facts.get(id);
+      if (fact && fact.kind === kind) {
+        const logicalFact = hasComponentId(fact)
+          ? {
+              ...fact,
+              id: undefined,
+              componentId: logicalComponentId(fact.componentId),
+            }
+          : { ...fact, id: undefined };
+        const key = canonicalJson(logicalFact);
+        if (seen.has(key)) continue;
+        seen.add(key);
+        out.push(fact as F);
+      }
+    }
+    return out;
+  }
+}
+
+function describeFactForConflict(fact: Fact): string {
+  const parts = [`kind=${fact.kind}`];
+  const maybeLocation = "location" in fact ? fact.location : undefined;
+  if (maybeLocation && typeof maybeLocation === "object") {
+    const loc = maybeLocation as { file?: unknown; line?: unknown; column?: unknown };
+    if (typeof loc.file === "string") {
+      const line = typeof loc.line === "number" ? `:${loc.line}` : "";
+      const column = typeof loc.column === "number" ? `:${loc.column}` : "";
+      parts.push(`location=${loc.file}${line}${column}`);
+    }
+  }
+  if ("nodePath" in fact && typeof fact.nodePath === "string") {
+    parts.push(`nodePath=${fact.nodePath}`);
+  }
+  if ("element" in fact && typeof fact.element === "string") {
+    parts.push(`element=${fact.element}`);
+  }
+  return parts.join(" ");
+}