@fragments-sdk/classifier 0.2.0

package/src/signals/__tests__/registry.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+
+import { HEURISTIC_SIGNALS } from '../index.js';
+import { makeUcf } from '../../__tests__/fixtures.js';
+
+describe('HEURISTIC_SIGNALS registry', () => {
+  it('exposes exactly the 8 heuristic signal types', () => {
+    expect(Object.keys(HEURISTIC_SIGNALS).sort()).toEqual([
+      'ARIA_ROLE',
+      'BARREL_EXPORT',
+      'HTML_ROOT',
+      'INPUT_TYPE',
+      'LIBRARY_REEXPORT',
+      'NAME_MATCH',
+      'PATH_HINT',
+      'PROP_FINGERPRINT',
+    ]);
+  });
+
+  it('every extractor returns [] (not null) on an inert UCF', () => {
+    const inert = makeUcf({ componentName: '', filePath: '' });
+    for (const [type, extractor] of Object.entries(HEURISTIC_SIGNALS)) {
+      const result = extractor(inert);
+      expect(Array.isArray(result), `${type} returned non-array`).toBe(true);
+    }
+  });
+});

package/src/signals/aria-role.ts

@@ -0,0 +1,94 @@
+// ARIA_ROLE — `01-architecture.md` §9.3.
+//
+// High-precision signal (weight 0.45). Native HTML semantics + explicit
+// `role=` attributes both surface here via UCF `ariaRoles`.
+
+import type { UniversalComponentFact } from '@fragments-sdk/extract';
+
+import { canonicalId, type CanonicalId, type SignalExtractor, type SignalRecord } from '../types.js';
+
+const WEIGHT = 0.45;
+const TOAST_ALERT_WEIGHT = 0.3;
+const c = canonicalId;
+
+interface AriaMapping {
+  canonicals: ReadonlyArray<CanonicalId>;
+  // §9.3: `button` only fires if HTML_ROOT was not already `button` —
+  // avoid double-counting. We approximate by suppressing when the UCF's
+  // root tag is `button`, since HTML_ROOT and ARIA_ROLE see the same UCF.
+  suppressIfRootTag?: string;
+  // `listbox` → Select OR MultiSelect, disambiguated by aria-multiselectable.
+  multiselectableSplit?: boolean;
+  // Lower-precision mapping (e.g. `status` → Toast).
+  weight?: number;
+}
+
+const ROLE_MAPPING: ReadonlyMap<string, AriaMapping> = new Map([
+  ['button', { canonicals: [c('Button')], suppressIfRootTag: 'button' }],
+  ['dialog', { canonicals: [c('Dialog')] }],
+  ['alertdialog', { canonicals: [c('AlertDialog')] }],
+  ['tooltip', { canonicals: [c('Tooltip')] }],
+  ['tab', { canonicals: [c('Tabs')] }],
+  ['tablist', { canonicals: [c('Tabs')] }],
+  ['menu', { canonicals: [c('Menu')] }],
+  ['menuitem', { canonicals: [c('Menu')] }],
+  ['menubar', { canonicals: [c('MenuBar')] }],
+  ['combobox', { canonicals: [c('Combobox')] }],
+  ['listbox', { canonicals: [c('Select'), c('MultiSelect')], multiselectableSplit: true }],
+  ['slider', { canonicals: [c('Slider')] }],
+  ['switch', { canonicals: [c('Switch')] }],
+  ['progressbar', { canonicals: [c('Progress')] }],
+  ['alert', { canonicals: [c('Alert')] }],
+  ['status', { canonicals: [c('Toast'), c('Alert')], weight: TOAST_ALERT_WEIGHT }],
+  ['radio', { canonicals: [c('Radio')] }],
+  ['radiogroup', { canonicals: [c('RadioGroup')] }],
+  ['checkbox', { canonicals: [c('Checkbox')] }],
+  ['textbox', { canonicals: [c('Input')] }],
+  ['spinbutton', { canonicals: [c('NumberInput')] }],
+  ['separator', { canonicals: [c('Separator')] }],
+  ['tree', { canonicals: [c('Tree')] }],
+  ['table', { canonicals: [c('Table')] }],
+  ['grid', { canonicals: [c('DataTable')] }],
+  ['list', { canonicals: [c('List')] }],
+  ['breadcrumb', { canonicals: [c('Breadcrumb')] }],
+  ['navigation', { canonicals: [c('NavigationMenu'), c('Breadcrumb'), c('Pagination')] }],
+  ['form', { canonicals: [c('Form')] }],
+]);
+
+function rootHasTag(ucf: UniversalComponentFact, tag: string): boolean {
+  return ucf.rootElements.some((root) => root.tag.toLowerCase() === tag);
+}
+
+const ariaRole: SignalExtractor = (
+  ucf: UniversalComponentFact,
+): SignalRecord[] => {
+  if (ucf.ariaRoles.length === 0) return [];
+  const out: SignalRecord[] = [];
+  const seen = new Set<CanonicalId>();
+  const isMultiSelectable = ucf.ariaAttributes['aria-multiselectable'] === 'true' || ucf.ariaAttributes['aria-multiselectable'] === true;
+
+  for (const role of ucf.ariaRoles) {
+    const mapping = ROLE_MAPPING.get(role.toLowerCase());
+    if (!mapping) continue;
+    if (mapping.suppressIfRootTag && rootHasTag(ucf, mapping.suppressIfRootTag)) continue;
+    for (const canonical of mapping.canonicals) {
+      // Listbox disambiguation: aria-multiselectable=true → MultiSelect only;
+      // false/absent → Select only.
+      if (mapping.multiselectableSplit) {
+        if (isMultiSelectable && canonical === c('Select')) continue;
+        if (!isMultiSelectable && canonical === c('MultiSelect')) continue;
+      }
+      if (seen.has(canonical)) continue;
+      seen.add(canonical);
+      out.push({
+        type: 'ARIA_ROLE',
+        canonical,
+        weight: mapping.weight ?? WEIGHT,
+        evidence: { role },
+      });
+    }
+  }
+  return out;
+};
+
+export default ariaRole;

package/src/signals/barrel-export.ts

@@ -0,0 +1,28 @@
+// BARREL_EXPORT — `01-architecture.md` §9.8.
+//
+// Weak signal (weight 0.08). Fires when the UCF reports `exportedFromBarrel:
+// true` AND the component is a primitive name (i.e. a synonym match exists).
+// Like NAME_MATCH and PATH_HINT, never load-bearing alone.
+
+import type { UniversalComponentFact } from '@fragments-sdk/extract';
+
+import type { SignalExtractor, SignalRecord } from '../types.js';
+import { lookupSynonym } from '../vocabulary/synonyms.js';
+
+const WEIGHT = 0.08;
+
+const barrelExport: SignalExtractor = (
+  ucf: UniversalComponentFact,
+): SignalRecord[] => {
+  if (!ucf.exportedFromBarrel) return [];
+  const canonicals = lookupSynonym(ucf.componentName);
+  if (canonicals.length === 0) return [];
+  return canonicals.map((canonical) => ({
+    type: 'BARREL_EXPORT',
+    canonical,
+    weight: WEIGHT,
+    evidence: { componentName: ucf.componentName },
+  }));
+};
+
+export default barrelExport;

package/src/signals/html-root.ts

@@ -0,0 +1,85 @@
+// HTML_ROOT — `01-architecture.md` §9.2.
+//
+// High-precision signal (weight 0.45). Maps native HTML root tags to their
+// canonical primitive. INPUT_TYPE handles `<input>` specifically; this signal
+// emits HTMLInputElement only when no `inputType` is recorded.
+
+import type { RootElementFact, UniversalComponentFact } from '@fragments-sdk/extract';
+
+import { canonicalId, type CanonicalId, type SignalExtractor, type SignalRecord } from '../types.js';
+
+const WEIGHT = 0.45;
+const c = canonicalId;
+
+// Strong → single canonical hypothesis. Ambiguous → multiple hypotheses, each
+// emitted as a separate record (the combiner resolves disagreement per §10.2).
+const TAG_MAPPING: ReadonlyMap<string, ReadonlyArray<CanonicalId>> = new Map([
+  ['button', [c('Button')]],
+  ['textarea', [c('Textarea')]],
+  ['select', [c('Select')]],
+  ['dialog', [c('Dialog')]],
+  ['details', [c('Disclosure')]],
+  ['progress', [c('Progress')]],
+  ['hr', [c('Separator')]],
+  ['table', [c('Table'), c('DataTable')]],
+  ['nav', [c('Breadcrumb'), c('Pagination'), c('NavigationMenu')]],
+  // ul / ol are intentionally excluded — too general (§9.2 final note); the
+  // NAME_MATCH signal must agree before List can fire.
+]);
+
+function tagFor(root: RootElementFact): string | undefined {
+  if (root.tag.startsWith('Custom:')) return undefined;
+  // INPUT_TYPE owns the `input` tag entirely.
+  if (root.tag === 'input') return undefined;
+  return root.tag.toLowerCase();
+}
+
+const htmlRoot: SignalExtractor = (
+  ucf: UniversalComponentFact,
+): SignalRecord[] => {
+  if (ucf.rootElements.length === 0) return [];
+
+  // Per §9.2 conditional-roots: if all branches map to the same canonical
+  // → full weight. If branches disagree → emit per-branch with confidence
+  // reduced by 1/branches (still per-branch, so one record per branch).
+  const branches = ucf.rootElements;
+  const tally = new Map<CanonicalId, number>();
+
+  for (const root of branches) {
+    const tag = tagFor(root);
+    if (!tag) continue;
+    const canonicals = TAG_MAPPING.get(tag);
+    if (!canonicals) continue;
+    for (const canon of canonicals) {
+      tally.set(canon, (tally.get(canon) ?? 0) + 1);
+    }
+  }
+
+  if (tally.size === 0) return [];
+
+  // Divergence factor: when branches disagree, scale the weight per §9.2.
+  // We approximate by `presentBranches / totalBranches` for each canonical.
+  const totalBranches = branches.length;
+  const out: SignalRecord[] = [];
+  for (const [canonical, hitBranches] of tally.entries()) {
+    const divergenceFactor = totalBranches > 0 ? hitBranches / totalBranches : 1;
+    const adjusted = WEIGHT * divergenceFactor;
+    out.push({
+      type: 'HTML_ROOT',
+      canonical,
+      weight: adjusted,
+      evidence: {
+        tag: branches.find((root) => {
+          const tag = tagFor(root);
+          if (!tag) return false;
+          return TAG_MAPPING.get(tag)?.includes(canonical);
+        })?.tag,
+        hitBranches,
+        totalBranches,
+      },
+    });
+  }
+  return out;
+};
+
+export default htmlRoot;

package/src/signals/index.ts

@@ -0,0 +1,39 @@
+// Heuristic signal registry — `01-architecture.md` §11 Stage 3.
+//
+// The combiner (brief 04) iterates this map in parallel for each UCF. Adding
+// a signal is one entry in this record. The AI_SEMANTIC slot is reserved for
+// brief 07 — it is not part of the heuristic registry and the combiner pulls
+// it from a separate channel.
+
+import type { SignalRegistry } from '../types.js';
+
+import ariaRole from './aria-role.js';
+import barrelExport from './barrel-export.js';
+import htmlRoot from './html-root.js';
+import inputType from './input-type.js';
+import libraryReexport from './library-reexport.js';
+import nameMatch from './name-match.js';
+import pathHint from './path-hint.js';
+import propFingerprint from './prop-fingerprint.js';
+
+export const HEURISTIC_SIGNALS: SignalRegistry = {
+  LIBRARY_REEXPORT: libraryReexport,
+  HTML_ROOT: htmlRoot,
+  ARIA_ROLE: ariaRole,
+  INPUT_TYPE: inputType,
+  PROP_FINGERPRINT: propFingerprint,
+  NAME_MATCH: nameMatch,
+  PATH_HINT: pathHint,
+  BARREL_EXPORT: barrelExport,
+};
+
+export {
+  ariaRole,
+  barrelExport,
+  htmlRoot,
+  inputType,
+  libraryReexport,
+  nameMatch,
+  pathHint,
+  propFingerprint,
+};

package/src/signals/input-type.ts

@@ -0,0 +1,63 @@
+// INPUT_TYPE — `01-architecture.md` §9.4.
+//
+// Highest-precision signal (weight 0.6). `<input type="X">` is unambiguous.
+// Suppressed only when `role="switch"` is present (then upgrades to Switch).
+
+import type { UniversalComponentFact } from '@fragments-sdk/extract';
+
+import { canonicalId, type CanonicalId, type SignalExtractor, type SignalRecord } from '../types.js';
+
+const WEIGHT = 0.6;
+const c = canonicalId;
+
+const INPUT_TYPE_MAPPING: ReadonlyMap<string, CanonicalId> = new Map([
+  ['text', c('Input')],
+  ['email', c('Input')],
+  ['url', c('Input')],
+  ['tel', c('Input')],
+  ['search', c('Input')],
+  ['password', c('PasswordInput')],
+  ['number', c('NumberInput')],
+  ['checkbox', c('Checkbox')],
+  ['radio', c('Radio')],
+  ['date', c('DatePicker')],
+  ['time', c('TimePicker')],
+  ['datetime-local', c('DatePicker')],
+  ['range', c('Slider')],
+]);
+
+const inputType: SignalExtractor = (
+  ucf: UniversalComponentFact,
+): SignalRecord[] => {
+  for (const root of ucf.rootElements) {
+    if (root.tag !== 'input') continue;
+    const inputTypeValue = root.inputType;
+    if (!inputTypeValue) continue;
+    const canonical = INPUT_TYPE_MAPPING.get(inputTypeValue.toLowerCase());
+    if (!canonical) continue;
+
+    // §9.4 suppression: `role="switch"` on a checkbox upgrades to Switch.
+    if (canonical === c('Checkbox') && ucf.ariaRoles.includes('switch')) {
+      return [
+        {
+          type: 'INPUT_TYPE',
+          canonical: c('Switch'),
+          weight: WEIGHT,
+          evidence: { inputType: inputTypeValue, role: 'switch' },
+        },
+      ];
+    }
+
+    return [
+      {
+        type: 'INPUT_TYPE',
+        canonical,
+        weight: WEIGHT,
+        evidence: { inputType: inputTypeValue },
+      },
+    ];
+  }
+  return [];
+};
+
+export default inputType;

package/src/signals/library-reexport.ts

@@ -0,0 +1,70 @@
+// LIBRARY_REEXPORT — `01-architecture.md` §9.1.
+//
+// High-precision signal (weight 0.55). Fires when a component imports a known
+// primitive from a recognised library AND uses the local binding as a JSX root.
+// False-positive guards:
+//   1. Importing without using the binding as a root → suppress.
+//   2. Sub-primitive policy: only root-aligned wrappers fire (the parent's
+//      compound-children classification handles e.g. `Dialog.Header`).
+
+import type {
+  ImportRecord,
+  RootElementFact,
+  UniversalComponentFact,
+} from '@fragments-sdk/extract';
+
+import type { CanonicalId, SignalExtractor, SignalRecord } from '../types.js';
+import { lookupLibraryImport } from '../vocabulary/library-map.js';
+
+const WEIGHT = 0.55;
+
+function rootUsesBinding(
+  rootElements: ReadonlyArray<RootElementFact>,
+  localBinding: string,
+): boolean {
+  // `Custom:Foo` for component-typed roots (per UCF schema §7.1). Bare-tag
+  // roots like 'div' never match.
+  return rootElements.some((root) => root.tag === `Custom:${localBinding}`);
+}
+
+function packageMatch(record: ImportRecord): string | undefined {
+  // Prefer resolvedPackage (handles monorepo aliases) but fall back to the
+  // module specifier — extractors may not always populate the resolved field.
+  return record.resolvedPackage ?? record.moduleSpecifier;
+}
+
+const libraryReexport: SignalExtractor = (
+  ucf: UniversalComponentFact,
+): SignalRecord[] => {
+  const out: SignalRecord[] = [];
+  // De-dupe: if two imports point at the same canonical, emit once. The
+  // strict-signal-count rule (§10.3) treats them as one signal regardless.
+  const seen = new Set<CanonicalId>();
+
+  for (const record of ucf.imports) {
+    const pkg = packageMatch(record);
+    if (!pkg) continue;
+    for (const { imported, local } of record.importedNames) {
+      const canonical = lookupLibraryImport(pkg, imported);
+      if (!canonical) continue;
+      // False-positive guard: must be used as a JSX root.
+      if (!rootUsesBinding(ucf.rootElements, local)) continue;
+      if (seen.has(canonical)) continue;
+      seen.add(canonical);
+      out.push({
+        type: 'LIBRARY_REEXPORT',
+        canonical,
+        weight: WEIGHT,
+        evidence: {
+          package: pkg,
+          importedName: imported,
+          localBinding: local,
+        },
+      });
+    }
+  }
+
+  return out;
+};
+
+export default libraryReexport;

package/src/signals/name-match.ts

@@ -0,0 +1,92 @@
+// NAME_MATCH — `01-architecture.md` §9.6.
+//
+// Weak signal (weight 0.15). NEVER load-bearing alone — must combine with at
+// least one structural signal (HTML_ROOT / ARIA_ROLE / LIBRARY_REEXPORT /
+// PROP_FINGERPRINT) before reaching `auto`. The 0.15 weight already enforces
+// that via §10.3 strict signal-count rule (NAME_MATCH is not "strong").
+
+import type { UniversalComponentFact } from '@fragments-sdk/extract';
+
+import type { CanonicalId, SignalExtractor, SignalRecord } from '../types.js';
+import {
+  NAME_STRIP_PREFIXES,
+  NAME_STRIP_SUFFIXES,
+  NAME_VARIANT_SUFFIXES,
+  lookupSynonym,
+} from '../vocabulary/synonyms.js';
+
+const WEIGHT = 0.15;
+
+function stripPrefix(name: string): string {
+  for (const prefix of NAME_STRIP_PREFIXES) {
+    if (name.startsWith(prefix) && name.length > prefix.length) {
+      return name.slice(prefix.length);
+    }
+  }
+  return name;
+}
+
+function stripSuffix(name: string): string {
+  for (const suffix of NAME_STRIP_SUFFIXES) {
+    if (name.endsWith(suffix) && name.length > suffix.length) {
+      return name.slice(0, -suffix.length);
+    }
+  }
+  return name;
+}
+
+function stripVariantIfCanonical(name: string): string {
+  for (const variant of NAME_VARIANT_SUFFIXES) {
+    if (name.endsWith(variant) && name.length > variant.length) {
+      const remainder = name.slice(0, -variant.length);
+      if (lookupSynonym(remainder).length > 0) return remainder;
+    }
+  }
+  return name;
+}
+
+function stripVariantIfPrefixCanonical(name: string): string {
+  for (const variant of NAME_VARIANT_SUFFIXES) {
+    if (name.startsWith(variant) && name.length > variant.length) {
+      const remainder = name.slice(variant.length);
+      if (lookupSynonym(remainder).length > 0) return remainder;
+    }
+  }
+  return name;
+}
+
+const nameMatch: SignalExtractor = (
+  ucf: UniversalComponentFact,
+): SignalRecord[] => {
+  // Try the component name AND the innermost wrapped target — `forwardRef`'d
+  // components are often named at the wrapper level too. We attempt both.
+  const candidates = new Set<string>();
+  candidates.add(ucf.componentName);
+  for (const wrapper of ucf.wrappedBy) candidates.add(wrapper);
+
+  const out: SignalRecord[] = [];
+  const seen = new Set<CanonicalId>();
+
+  for (const raw of candidates) {
+    if (!raw) continue;
+    let stripped = stripPrefix(raw);
+    stripped = stripSuffix(stripped);
+    stripped = stripVariantIfCanonical(stripped);
+    stripped = stripVariantIfPrefixCanonical(stripped);
+
+    for (const canonical of lookupSynonym(stripped)) {
+      if (seen.has(canonical)) continue;
+      seen.add(canonical);
+      out.push({
+        type: 'NAME_MATCH',
+        canonical,
+        weight: WEIGHT,
+        evidence: { componentName: raw, stripped },
+      });
+    }
+  }
+
+  return out;
+};
+
+export default nameMatch;

package/src/signals/path-hint.ts

@@ -0,0 +1,94 @@
+// PATH_HINT — `01-architecture.md` §9.7.
+//
+// Weak signal (weight 0.10). Fires when the file path has a directory segment
+// suggesting "primitive" intent. Never load-bearing alone (same caveat as
+// NAME_MATCH).
+
+import type { UniversalComponentFact } from '@fragments-sdk/extract';
+
+import type { SignalExtractor, SignalRecord } from '../types.js';
+import { lookupSynonym } from '../vocabulary/synonyms.js';
+
+const WEIGHT = 0.1;
+
+const PRIMITIVE_DIR_HINTS: ReadonlyArray<string> = [
+  'primitives',
+  'atoms',
+  'base',
+  'core',
+  'ui',
+  'elements',
+  'foundations',
+];
+
+// `components/ui` is treated as a single hint (§9.7).
+const COMPOSED_HINTS: ReadonlyArray<RegExp> = [
+  /[\\/]components[\\/]ui[\\/]/i,
+];
+
+function pathSegments(filePath: string): ReadonlyArray<string> {
+  return filePath.toLowerCase().split(/[\\/]+/).filter((s) => s.length > 0);
+}
+
+function hasPrimitiveDirHint(filePath: string): string | undefined {
+  const lower = filePath.toLowerCase();
+  for (const composed of COMPOSED_HINTS) {
+    if (composed.test(filePath)) return composed.source;
+  }
+  const segments = pathSegments(lower);
+  for (const segment of segments) {
+    if (PRIMITIVE_DIR_HINTS.includes(segment)) return segment;
+  }
+  return undefined;
+}
+
+// Path hint can suggest a specific canonical when the basename matches one
+// (e.g. `src/components/ui/button.tsx` → Button). We deduplicate against the
+// vocab index. If no specific canonical is implicated, we emit nothing —
+// PATH_HINT alone is too weak to be useful without a target hypothesis.
+function basenameCanonicals(filePath: string) {
+  const segments = pathSegments(filePath);
+  const basename = segments[segments.length - 1] ?? '';
+  // Strip common extensions.
+  const stem = basename.replace(/\.(tsx?|jsx?|vue|svelte)$/i, '');
+  // dasherized → PascalCase candidate.
+  const pascal = stem
+    .split(/[-_]/)
+    .filter(Boolean)
+    .map((word) => word[0].toUpperCase() + word.slice(1))
+    .join('');
+  if (!pascal) return [];
+  return lookupSynonym(pascal).map((canonical) => ({ canonical, stem }));
+}
+
+const pathHint: SignalExtractor = (
+  ucf: UniversalComponentFact,
+): SignalRecord[] => {
+  const dirHint = hasPrimitiveDirHint(ucf.filePath);
+  if (!dirHint) return [];
+
+  const candidates = basenameCanonicals(ucf.filePath);
+
+  // No specific canonical from basename → emit a generic hint per known
+  // canonical that matches the component name (so the signal reinforces an
+  // existing hypothesis rather than nominating arbitrary canonicals).
+  if (candidates.length === 0) {
+    const componentNameLookup = lookupSynonym(ucf.componentName);
+    if (componentNameLookup.length === 0) return [];
+    return componentNameLookup.map((canonical) => ({
+      type: 'PATH_HINT',
+      canonical,
+      weight: WEIGHT,
+      evidence: { dirHint, componentName: ucf.componentName },
+    }));
+  }
+
+  return candidates.map(({ canonical, stem }) => ({
+    type: 'PATH_HINT',
+    canonical,
+    weight: WEIGHT,
+    evidence: { dirHint, basename: stem },
+  }));
+};
+
+export default pathHint;