@fragments-sdk/classifier 0.2.0

package/src/vocabulary/prop-fingerprints.ts

@@ -0,0 +1,433 @@
+// PROP_FINGERPRINT data — `01-architecture.md` §9.5.
+//
+// Each canonical has a fingerprint of required + optional + anti props.
+// The signal scores: 0.3 if all required props are present; +0.05 per optional
+// match (capped at 0.3 total per spec); −0.15 per anti-fingerprint hit.
+
+import { canonicalId, type CanonicalId } from '../types.js';
+
+export type TypeMatcher = (typeText: string) => boolean;
+
+export interface RequiredPropTest {
+  // Names in `oneOf` are alternatives — any of them matching counts as the
+  // single required prop. Used for canonicals where libraries name the same
+  // prop differently (e.g. Checkbox: `onChange` OR `onCheckedChange`).
+  oneOf: ReadonlyArray<{ name: string; typeMatcher?: TypeMatcher }>;
+}
+
+export interface OptionalPropTest {
+  name: string;
+  typeMatcher?: TypeMatcher;
+}
+
+export interface AntiPropTest {
+  name: string;
+  typeMatcher?: TypeMatcher;
+}
+
+export interface PropFingerprint {
+  required: ReadonlyArray<RequiredPropTest>;
+  optional: ReadonlyArray<OptionalPropTest>;
+  anti: ReadonlyArray<AntiPropTest>;
+}
+
+const c = canonicalId;
+
+// Primitive type matchers — string predicates, no full type parsing per
+// brief §Open questions(2). Patterns are intentionally permissive.
+const isFunction: TypeMatcher = (text) => /=>/.test(text) || /^Function$/.test(text.trim());
+const isReactNode: TypeMatcher = (text) =>
+  /ReactNode|ReactElement|JSX\.Element|React\.(ReactNode|Children|ReactElement)/.test(text) ||
+  /string/.test(text);
+const isBoolean: TypeMatcher = (text) => /\bboolean\b/.test(text);
+const isString: TypeMatcher = (text) => /\bstring\b/.test(text);
+const isNumber: TypeMatcher = (text) => /\bnumber\b/.test(text);
+const isOpenChange: TypeMatcher = (text) => /\bopen\b.*=>|=>.*\bvoid\b|=>/.test(text);
+const isOptions: TypeMatcher = (text) => /\b(option|item)s?\b/i.test(text) || /\[\]/.test(text);
+const isDate: TypeMatcher = (text) => /\bDate\b/.test(text);
+
+export const PROP_FINGERPRINTS: ReadonlyMap<CanonicalId, PropFingerprint> = new Map([
+  [c('Button'), {
+    required: [
+      { oneOf: [{ name: 'onClick', typeMatcher: isFunction }] },
+      { oneOf: [{ name: 'children', typeMatcher: isReactNode }] },
+    ],
+    optional: [
+      { name: 'variant' },
+      { name: 'size' },
+      { name: 'disabled', typeMatcher: isBoolean },
+      { name: 'type' },
+      { name: 'loading', typeMatcher: isBoolean },
+      { name: 'startIcon' },
+      { name: 'endIcon' },
+      { name: 'leftIcon' },
+      { name: 'rightIcon' },
+    ],
+    anti: [
+      { name: 'value', typeMatcher: isString },
+      { name: 'onChange', typeMatcher: isFunction },
+      { name: 'checked', typeMatcher: isBoolean },
+    ],
+  }],
+
+  [c('IconButton'), {
+    required: [
+      { oneOf: [{ name: 'onClick', typeMatcher: isFunction }] },
+      { oneOf: [{ name: 'icon' }, { name: 'aria-label' }, { name: 'ariaLabel' }] },
+    ],
+    optional: [
+      { name: 'variant' },
+      { name: 'size' },
+      { name: 'disabled', typeMatcher: isBoolean },
+    ],
+    anti: [
+      { name: 'children' },
+      { name: 'value' },
+    ],
+  }],
+
+  [c('Checkbox'), {
+    required: [
+      { oneOf: [{ name: 'checked', typeMatcher: isBoolean }] },
+      { oneOf: [
+        { name: 'onChange', typeMatcher: isFunction },
+        { name: 'onCheckedChange', typeMatcher: isFunction },
+      ] },
+    ],
+    optional: [
+      { name: 'defaultChecked', typeMatcher: isBoolean },
+      { name: 'indeterminate', typeMatcher: isBoolean },
+      { name: 'disabled', typeMatcher: isBoolean },
+    ],
+    anti: [
+      { name: 'children', typeMatcher: isReactNode },
+    ],
+  }],
+
+  [c('Switch'), {
+    required: [
+      { oneOf: [{ name: 'checked', typeMatcher: isBoolean }] },
+      { oneOf: [
+        { name: 'onChange', typeMatcher: isFunction },
+        { name: 'onCheckedChange', typeMatcher: isFunction },
+      ] },
+    ],
+    optional: [
+      { name: 'defaultChecked', typeMatcher: isBoolean },
+      { name: 'disabled', typeMatcher: isBoolean },
+    ],
+    anti: [
+      { name: 'indeterminate' },
+    ],
+  }],
+
+  [c('Dialog'), {
+    required: [
+      { oneOf: [{ name: 'open', typeMatcher: isBoolean }] },
+      { oneOf: [
+        { name: 'onOpenChange', typeMatcher: isOpenChange },
+        { name: 'onClose', typeMatcher: isFunction },
+      ] },
+    ],
+    optional: [
+      { name: 'title' },
+      { name: 'description' },
+      { name: 'modal', typeMatcher: isBoolean },
+    ],
+    anti: [
+      { name: 'value' },
+      { name: 'onChange' },
+    ],
+  }],
+
+  [c('Tooltip'), {
+    required: [
+      { oneOf: [{ name: 'content' }, { name: 'title' }] },
+    ],
+    optional: [
+      { name: 'delayDuration', typeMatcher: isNumber },
+      { name: 'side' },
+      { name: 'placement' },
+    ],
+    anti: [
+      { name: 'open', typeMatcher: isBoolean },
+      { name: 'value' },
+    ],
+  }],
+
+  [c('Tabs'), {
+    required: [
+      { oneOf: [{ name: 'value', typeMatcher: isString }] },
+      { oneOf: [
+        { name: 'onValueChange', typeMatcher: isFunction },
+        { name: 'onChange', typeMatcher: isFunction },
+      ] },
+    ],
+    optional: [
+      { name: 'defaultValue', typeMatcher: isString },
+      { name: 'orientation' },
+    ],
+    anti: [
+      { name: 'checked' },
+    ],
+  }],
+
+  [c('Combobox'), {
+    required: [
+      { oneOf: [
+        { name: 'value', typeMatcher: isString },
+        { name: 'inputValue', typeMatcher: isString },
+      ] },
+      { oneOf: [
+        { name: 'onValueChange', typeMatcher: isFunction },
+        { name: 'onInputChange', typeMatcher: isFunction },
+        { name: 'onChange', typeMatcher: isFunction },
+      ] },
+      { oneOf: [
+        { name: 'options', typeMatcher: isOptions },
+        { name: 'items', typeMatcher: isOptions },
+      ] },
+    ],
+    optional: [
+      { name: 'placeholder', typeMatcher: isString },
+      { name: 'disabled', typeMatcher: isBoolean },
+    ],
+    anti: [],
+  }],
+
+  [c('Select'), {
+    required: [
+      { oneOf: [{ name: 'value', typeMatcher: isString }] },
+      { oneOf: [
+        { name: 'onValueChange', typeMatcher: isFunction },
+        { name: 'onChange', typeMatcher: isFunction },
+      ] },
+    ],
+    optional: [
+      { name: 'options', typeMatcher: isOptions },
+      { name: 'placeholder', typeMatcher: isString },
+      { name: 'disabled', typeMatcher: isBoolean },
+    ],
+    anti: [
+      { name: 'inputValue' },
+      { name: 'multiple', typeMatcher: isBoolean },
+    ],
+  }],
+
+  [c('Slider'), {
+    required: [
+      { oneOf: [{ name: 'value', typeMatcher: isNumber }] },
+      { oneOf: [
+        { name: 'onValueChange', typeMatcher: isFunction },
+        { name: 'onChange', typeMatcher: isFunction },
+      ] },
+    ],
+    optional: [
+      { name: 'min', typeMatcher: isNumber },
+      { name: 'max', typeMatcher: isNumber },
+      { name: 'step', typeMatcher: isNumber },
+    ],
+    anti: [
+      { name: 'checked' },
+    ],
+  }],
+
+  [c('Input'), {
+    required: [
+      { oneOf: [{ name: 'value', typeMatcher: isString }] },
+      { oneOf: [{ name: 'onChange', typeMatcher: isFunction }] },
+    ],
+    optional: [
+      { name: 'placeholder', typeMatcher: isString },
+      { name: 'type', typeMatcher: isString },
+      { name: 'disabled', typeMatcher: isBoolean },
+    ],
+    anti: [
+      { name: 'options' },
+      { name: 'open', typeMatcher: isBoolean },
+    ],
+  }],
+
+  [c('Textarea'), {
+    required: [
+      { oneOf: [{ name: 'value', typeMatcher: isString }] },
+      { oneOf: [{ name: 'onChange', typeMatcher: isFunction }] },
+      { oneOf: [{ name: 'rows', typeMatcher: isNumber }, { name: 'minRows', typeMatcher: isNumber }] },
+    ],
+    optional: [
+      { name: 'placeholder', typeMatcher: isString },
+      { name: 'disabled', typeMatcher: isBoolean },
+    ],
+    anti: [],
+  }],
+
+  [c('NumberInput'), {
+    required: [
+      { oneOf: [{ name: 'value', typeMatcher: isNumber }] },
+      { oneOf: [{ name: 'onChange', typeMatcher: isFunction }] },
+    ],
+    optional: [
+      { name: 'min', typeMatcher: isNumber },
+      { name: 'max', typeMatcher: isNumber },
+      { name: 'step', typeMatcher: isNumber },
+    ],
+    anti: [],
+  }],
+
+  [c('DatePicker'), {
+    required: [
+      { oneOf: [{ name: 'value', typeMatcher: isDate }, { name: 'date', typeMatcher: isDate }, { name: 'selected', typeMatcher: isDate }] },
+      { oneOf: [{ name: 'onChange', typeMatcher: isFunction }, { name: 'onDateChange', typeMatcher: isFunction }, { name: 'onSelect', typeMatcher: isFunction }] },
+    ],
+    optional: [
+      { name: 'minDate' },
+      { name: 'maxDate' },
+      { name: 'format', typeMatcher: isString },
+    ],
+    anti: [],
+  }],
+
+  [c('Card'), {
+    required: [
+      { oneOf: [{ name: 'children', typeMatcher: isReactNode }] },
+    ],
+    optional: [
+      { name: 'title' },
+      { name: 'footer' },
+    ],
+    anti: [
+      { name: 'value' },
+      { name: 'onChange' },
+      { name: 'onClick' },
+      { name: 'open' },
+      { name: 'checked' },
+    ],
+  }],
+
+  [c('Badge'), {
+    required: [
+      { oneOf: [{ name: 'children', typeMatcher: isReactNode }] },
+    ],
+    optional: [
+      { name: 'variant' },
+      { name: 'count', typeMatcher: isNumber },
+    ],
+    anti: [
+      { name: 'onClick' },
+      { name: 'value' },
+    ],
+  }],
+
+  [c('Avatar'), {
+    required: [
+      { oneOf: [{ name: 'src', typeMatcher: isString }, { name: 'name', typeMatcher: isString }, { name: 'alt', typeMatcher: isString }] },
+    ],
+    optional: [
+      { name: 'size' },
+      { name: 'fallback' },
+    ],
+    anti: [
+      { name: 'value' },
+      { name: 'onChange' },
+    ],
+  }],
+
+  [c('Progress'), {
+    required: [
+      { oneOf: [{ name: 'value', typeMatcher: isNumber }] },
+    ],
+    optional: [
+      { name: 'max', typeMatcher: isNumber },
+      { name: 'indeterminate', typeMatcher: isBoolean },
+    ],
+    anti: [
+      { name: 'onChange' },
+    ],
+  }],
+
+  [c('Alert'), {
+    required: [
+      { oneOf: [{ name: 'children', typeMatcher: isReactNode }, { name: 'message' }, { name: 'title' }] },
+    ],
+    optional: [
+      { name: 'severity' },
+      { name: 'variant' },
+      { name: 'icon' },
+    ],
+    anti: [
+      { name: 'value' },
+      { name: 'onChange' },
+      { name: 'onClick' },
+    ],
+  }],
+
+  [c('Toast'), {
+    required: [
+      { oneOf: [{ name: 'message' }, { name: 'title' }, { name: 'children' }] },
+      { oneOf: [{ name: 'duration', typeMatcher: isNumber }, { name: 'autoHideDuration', typeMatcher: isNumber }, { name: 'onClose', typeMatcher: isFunction }] },
+    ],
+    optional: [
+      { name: 'severity' },
+      { name: 'position' },
+    ],
+    anti: [],
+  }],
+
+  [c('Accordion'), {
+    required: [
+      { oneOf: [{ name: 'value' }, { name: 'expandedItems' }, { name: 'defaultValue' }] },
+    ],
+    optional: [
+      { name: 'type' },
+      { name: 'collapsible', typeMatcher: isBoolean },
+      { name: 'multiple', typeMatcher: isBoolean },
+    ],
+    anti: [
+      { name: 'open', typeMatcher: isBoolean },
+    ],
+  }],
+
+  [c('Drawer'), {
+    required: [
+      { oneOf: [{ name: 'open', typeMatcher: isBoolean }] },
+      { oneOf: [
+        { name: 'onOpenChange', typeMatcher: isOpenChange },
+        { name: 'onClose', typeMatcher: isFunction },
+      ] },
+    ],
+    optional: [
+      { name: 'side' },
+      { name: 'anchor' },
+      { name: 'placement' },
+    ],
+    anti: [],
+  }],
+
+  [c('Popover'), {
+    required: [
+      { oneOf: [{ name: 'open', typeMatcher: isBoolean }] },
+      { oneOf: [
+        { name: 'onOpenChange', typeMatcher: isOpenChange },
+        { name: 'anchorEl' },
+      ] },
+    ],
+    optional: [
+      { name: 'side' },
+      { name: 'placement' },
+    ],
+    anti: [
+      { name: 'modal', typeMatcher: isBoolean },
+    ],
+  }],
+]);
+
+// §9.5 polymorphic-prop penalty: when `as`/`component`/`polymorphicAs` is on
+// the component, every hypothesis loses 0.1.
+export const POLYMORPHIC_PROP_NAMES: ReadonlySet<string> = new Set([
+  'as',
+  'component',
+  'polymorphicAs',
+  'asChild',
+  // `asChild` is borderline (Radix uses it on real primitives), but combined
+  // with the heavy anti-correlation we still apply the small penalty.
+]);

package/src/vocabulary/synonyms.ts

@@ -0,0 +1,130 @@
+// NAME_MATCH synonym table — `01-architecture.md` §5 (final paragraph) + §9.6.
+//
+// Each canonical entry has a synonym list of names that should match after
+// strip rules are applied. Matching is case-insensitive against the stripped
+// name. Synonyms are weight-bearing only when at least one other signal agrees
+// (enforced by the combiner via the §10.3 strict signal-count rule).
+
+import { canonicalId, type CanonicalId } from '../types.js';
+
+const c = canonicalId;
+
+export const NAME_STRIP_PREFIXES: ReadonlyArray<string> = [
+  'Mui',
+  'Chakra',
+  'Ant',
+  'Mantine',
+  'Radix',
+  'Base',
+];
+
+export const NAME_STRIP_SUFFIXES: ReadonlyArray<string> = [
+  'Base',
+  'Root',
+  'Primitive',
+  'Inner',
+  'Component',
+  'Impl',
+];
+
+// Variant suffixes are only stripped if the remainder is a canonical name
+// (handled in the signal logic, not unconditionally).
+export const NAME_VARIANT_SUFFIXES: ReadonlyArray<string> = [
+  'Primary',
+  'Secondary',
+  'Outline',
+  'Ghost',
+  'Solid',
+];
+
+// Synonyms map — keyed by canonical id, values are aliases (case-folded by
+// the signal at lookup time). The canonical id itself does NOT need to appear
+// in its own synonym list; the signal includes it implicitly.
+export const SYNONYMS: ReadonlyMap<CanonicalId, ReadonlyArray<string>> = new Map([
+  [c('Button'), ['Btn', 'BaseButton', 'PrimaryButton', 'ActionButton', 'CTAButton']],
+  [c('IconButton'), ['IconBtn', 'IconAction']],
+  [c('ToggleButton'), ['Toggle', 'ToggleBtn']],
+  [c('Input'), ['TextInput', 'TextField', 'TextBox', 'StringInput']],
+  [c('Textarea'), ['TextArea', 'MultilineInput', 'TextAreaInput']],
+  [c('NumberInput'), ['NumberField', 'NumericInput']],
+  [c('PasswordInput'), ['PasswordField']],
+  [c('Checkbox'), ['CheckBox', 'Check']],
+  [c('Radio'), ['RadioInput', 'RadioButton']],
+  [c('RadioGroup'), ['RadioButtonGroup', 'RadioList']],
+  [c('Switch'), ['Toggle', 'OnOff', 'SwitchInput']],
+  [c('Slider'), ['Range', 'RangeInput']],
+  [c('Select'), ['Dropdown', 'DropDown', 'SelectInput']],
+  [c('Combobox'), ['Autocomplete', 'AutoComplete', 'ComboBox', 'TypeAhead']],
+  [c('MultiSelect'), ['MultiSelectInput', 'TagsInput']],
+  [c('DatePicker'), ['DateInput', 'DateField']],
+  [c('TimePicker'), ['TimeInput']],
+  [c('Calendar'), ['DatePickerCalendar', 'CalendarGrid']],
+  [c('Form'), []],
+  [c('Field'), ['FormField', 'FieldGroup']],
+  [c('Label'), ['FormLabel']],
+  [c('FieldError'), ['ErrorMessage', 'FormError']],
+  [c('FieldHint'), ['HelperText', 'FormHelperText', 'Hint']],
+
+  [c('Dialog'), ['Modal', 'DialogModal']],
+  [c('AlertDialog'), ['ConfirmDialog', 'ConfirmModal']],
+  [c('Drawer'), ['SidePanel', 'SideDrawer']],
+  [c('Sheet'), ['BottomSheet']],
+  [c('Popover'), ['Pop', 'PopoverPanel']],
+  [c('Tooltip'), ['Tip', 'ToolTip']],
+  [c('HoverCard'), ['HoverPreview']],
+  [c('Toast'), ['Notification', 'Snackbar']],
+
+  [c('Tabs'), ['TabGroup', 'TabBar']],
+  [c('Accordion'), ['Collapse', 'Collapsible']],
+  [c('Disclosure'), ['Details']],
+  [c('Menu'), ['DropdownMenu', 'DropDownMenu', 'ActionMenu']],
+  [c('ContextMenu'), ['RightClickMenu']],
+  [c('MenuBar'), ['MenuStrip']],
+  [c('Breadcrumb'), ['Breadcrumbs', 'BreadCrumb']],
+  [c('Pagination'), ['Paginator', 'PageNav']],
+  [c('Stepper'), ['Steps', 'Wizard', 'StepIndicator']],
+  [c('NavigationMenu'), ['NavMenu', 'NavBar', 'Navigation']],
+
+  [c('Card'), ['Panel', 'Tile']],
+  [c('Badge'), ['Pill']],
+  [c('Chip'), ['Tag']],
+  [c('Tag'), ['Chip']],
+  [c('Avatar'), ['Profile', 'ProfilePicture', 'UserAvatar']],
+  [c('Alert'), ['Notice', 'Message']],
+  [c('Banner'), ['Notification', 'Notice']],
+  [c('Skeleton'), ['Placeholder', 'Loading']],
+  [c('Spinner'), ['Loader', 'LoadingSpinner']],
+  [c('Progress'), ['ProgressBar']],
+  [c('Separator'), ['Divider', 'Hr']],
+
+  [c('Table'), []],
+  [c('DataTable'), ['DataGrid']],
+  [c('List'), ['ItemList']],
+  [c('Tree'), ['TreeView']],
+  [c('ScrollArea'), ['ScrollBox', 'ScrollContainer']],
+
+  [c('Stack'), ['HStack', 'VStack', 'Flex']],
+  [c('Grid'), ['GridLayout']],
+  [c('Box'), ['View']],
+  [c('Container'), ['Wrapper']],
+]);
+
+// Reverse index: lowercased synonym → canonical(s) it points to. Built once.
+const REVERSE_SYNONYMS: ReadonlyMap<string, ReadonlyArray<CanonicalId>> = (() => {
+  const map = new Map<string, CanonicalId[]>();
+  for (const [canon, aliases] of SYNONYMS.entries()) {
+    const canonLower = (canon as string).toLowerCase();
+    if (!map.has(canonLower)) map.set(canonLower, []);
+    map.get(canonLower)!.push(canon);
+    for (const alias of aliases) {
+      const key = alias.toLowerCase();
+      if (!map.has(key)) map.set(key, []);
+      map.get(key)!.push(canon);
+    }
+  }
+  return map;
+})();
+
+export function lookupSynonym(name: string): ReadonlyArray<CanonicalId> {
+  return REVERSE_SYNONYMS.get(name.toLowerCase()) ?? [];
+}