@fragments-sdk/classifier 0.2.0

package/src/combiner.ts

@@ -0,0 +1,124 @@
+// Combiner entry point — `01-architecture.md` §10 + §10.5.
+//
+// Takes signal records (from the heuristic extractors and, in Phase 2,
+// the AI tier), groups them by canonical, applies independent-event
+// composition (§10.1), the disagreement penalty (§10.2), and the band
+// table (§10.3) including the tied/ambiguous demotion (§10.4).
+// Returns the verbatim §10.5 "show your work" payload.
+//
+// Pure: no I/O, no Convex, no `Date.now()`. Throws only on a malformed
+// input (signal weight outside `[0, 1]`).
+
+import type {
+  Classification,
+  ClassificationAlternate,
+  SignalRecord,
+} from './types.js';
+import { groupAndCompose, type GroupedHypothesis } from './combiner/group.js';
+import { rank } from './combiner/rank.js';
+import {
+  deriveBand,
+  HIGH_DISAGREEMENT_FLOOR,
+  STRONG_WEIGHT,
+  TIE_FIRES_FROM,
+  TIE_WINDOW,
+} from './combiner/band.js';
+
+export interface CombineMeta {
+  classifierVersion: string;
+  vocabVersion: string;
+}
+
+export function combine(
+  signals: SignalRecord[],
+  meta: CombineMeta,
+): Classification {
+  validate(signals);
+
+  if (signals.length === 0) {
+    return emptyClassification(meta);
+  }
+
+  const groups = groupAndCompose(signals);
+  const ranked = rank(groups);
+
+  if (!ranked.leading) {
+    return emptyClassification(meta);
+  }
+
+  const hasStrongSignal = ranked.leading.signals.some(
+    (s) => s.weight >= STRONG_WEIGHT,
+  );
+  const hasHighDisagreement = ranked.alternates.some(
+    (a) => a.confidence >= HIGH_DISAGREEMENT_FLOOR,
+  );
+  const isTied = detectTie(ranked.leading, ranked.alternates);
+
+  const band = deriveBand({
+    adjustedConfidence: ranked.adjustedLeadingConfidence,
+    distinctStrongTypes: ranked.leading.distinctStrongTypes.size,
+    totalLeadingSignalCount: ranked.leading.signals.length,
+    hasStrongSignal,
+    hasHighDisagreement,
+    isTied,
+  });
+
+  const alternates: ClassificationAlternate[] = ranked.alternates.map((a) => ({
+    canonical: a.canonical,
+    confidence: a.confidence,
+    signals: a.signals,
+  }));
+
+  return {
+    canonical: ranked.leading.canonical,
+    confidence: ranked.adjustedLeadingConfidence,
+    rawConfidence: ranked.rawLeadingConfidence,
+    band,
+    signals: ranked.leading.signals,
+    alternates,
+    classifierVersion: meta.classifierVersion,
+    vocabVersion: meta.vocabVersion,
+  };
+}
+
+function detectTie(
+  leading: GroupedHypothesis,
+  alternates: GroupedHypothesis[],
+): boolean {
+  if (alternates.length === 0) return false;
+  const top = alternates[0];
+  if (leading.confidence < TIE_FIRES_FROM) return false;
+  return Math.abs(leading.confidence - top.confidence) < TIE_WINDOW;
+}
+
+function validate(signals: SignalRecord[]): void {
+  for (const sig of signals) {
+    if (
+      typeof sig.weight !== 'number' ||
+      Number.isNaN(sig.weight) ||
+      sig.weight < 0 ||
+      sig.weight > 1
+    ) {
+      throw new Error(
+        `combine: signal weight must be a number in [0, 1], got ${sig.weight} for ${String(sig.canonical)} (${sig.type})`,
+      );
+    }
+  }
+}
+
+function emptyClassification(meta: CombineMeta): Classification {
+  return {
+    canonical: 'unknown',
+    confidence: 0,
+    rawConfidence: 0,
+    band: 'unknown',
+    signals: [],
+    alternates: [],
+    classifierVersion: meta.classifierVersion,
+    vocabVersion: meta.vocabVersion,
+  };
+}
+
+export type { GroupedHypothesis } from './combiner/group.js';
+export type { RankResult } from './combiner/rank.js';
+export type { BandInput } from './combiner/band.js';

package/src/index.ts

@@ -0,0 +1,76 @@
+// @fragments-sdk/classifier — heuristic signal extractors for the
+// canonical-primitive map. The combiner (brief 04) consumes this barrel.
+
+export {
+  canonicalId,
+  type Band,
+  type CanonicalId,
+  type Classification,
+  type ClassificationAlternate,
+  type HeuristicSignalType,
+  type SignalExtractor,
+  type SignalRecord,
+  type SignalRegistry,
+  type SignalType,
+} from './types.js';
+
+export { combine, type CombineMeta } from './combiner.js';
+
+export { HEURISTIC_SIGNALS } from './signals/index.js';
+
+export {
+  VOCAB_V0,
+  VOCAB_V0_INDEX,
+  VOCAB_V0_VERSION,
+  isCanonicalId,
+  type CanonicalCategory,
+  type CanonicalEntry,
+} from './vocabulary/canonicals.js';
+
+export { LIBRARY_MAP, lookupLibraryImport } from './vocabulary/library-map.js';
+
+export {
+  NAME_STRIP_PREFIXES,
+  NAME_STRIP_SUFFIXES,
+  NAME_VARIANT_SUFFIXES,
+  SYNONYMS,
+  lookupSynonym,
+} from './vocabulary/synonyms.js';
+
+export {
+  POLYMORPHIC_PROP_NAMES,
+  PROP_FINGERPRINTS,
+  type PropFingerprint,
+} from './vocabulary/prop-fingerprints.js';
+
+export {
+  resolveCanonicalForHtmlElement,
+  formatRawHtmlElement,
+  type RawAttrLike,
+  type RawAttrMap,
+} from './canonical-vocab/resolve-by-html-element.js';
+
+export {
+  AI_PROMPT_VERSION,
+  AI_REASONING_CHAR_CAP,
+  AI_SIGNAL_WEIGHTS,
+  aiResponseToSignals,
+  applyVocabWhitelist,
+  buildAiPrompt,
+  deriveAiCacheKey,
+  hashSourceText,
+  parseAiResponse,
+  sanitizeForInjection,
+  scrubSecrets,
+  truncateSource,
+  type AiConfidence,
+  type AiParseResult,
+  type AiResponse,
+  type AiResponseAlternate,
+  type AiSignalInputs,
+  type BuiltPrompt,
+  type CacheKeyInputs,
+  type PromptInputs,
+  type SecretScrubResult,
+  type VocabularyPromptEntry,
+} from './ai/index.js';

package/src/signals/__tests__/aria-role.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+
+import ariaRole from '../aria-role.js';
+import { makeUcf, root } from '../../__tests__/fixtures.js';
+
+describe('ARIA_ROLE', () => {
+  it('fires Dialog on role="dialog"', () => {
+    const records = ariaRole(makeUcf({ ariaRoles: ['dialog'] }));
+    expect(records).toHaveLength(1);
+    expect(records[0].canonical).toBe('Dialog');
+    expect(records[0].weight).toBe(0.45);
+  });
+
+  it('does not fire on empty ariaRoles', () => {
+    expect(ariaRole(makeUcf({ ariaRoles: [] }))).toEqual([]);
+  });
+
+  it('suppresses Button when root tag is already <button> (no double-counting)', () => {
+    const records = ariaRole(
+      makeUcf({ ariaRoles: ['button'], rootElements: [root('button')] }),
+    );
+    expect(records).toEqual([]);
+  });
+
+  it('emits Button when role=button on a non-button element (e.g. <div role="button">)', () => {
+    const records = ariaRole(
+      makeUcf({ ariaRoles: ['button'], rootElements: [root('div')] }),
+    );
+    expect(records).toHaveLength(1);
+    expect(records[0].canonical).toBe('Button');
+  });
+
+  it('disambiguates listbox via aria-multiselectable=true → MultiSelect', () => {
+    const records = ariaRole(
+      makeUcf({ ariaRoles: ['listbox'], ariaAttributes: { 'aria-multiselectable': 'true' } }),
+    );
+    expect(records.map((r) => r.canonical)).toEqual(['MultiSelect']);
+  });
+
+  it('disambiguates listbox without aria-multiselectable → Select', () => {
+    const records = ariaRole(makeUcf({ ariaRoles: ['listbox'] }));
+    expect(records.map((r) => r.canonical)).toEqual(['Select']);
+  });
+
+  it('emits Toast + Alert for role="status" with reduced weight', () => {
+    const records = ariaRole(makeUcf({ ariaRoles: ['status'] }));
+    const canonicals = records.map((r) => r.canonical).sort();
+    expect(canonicals).toEqual(['Alert', 'Toast']);
+    for (const record of records) {
+      expect(record.weight).toBe(0.3);
+    }
+  });
+});

package/src/signals/__tests__/barrel-export.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+
+import barrelExport from '../barrel-export.js';
+import { makeUcf } from '../../__tests__/fixtures.js';
+
+describe('BARREL_EXPORT', () => {
+  it('fires when exportedFromBarrel + name matches a synonym', () => {
+    const records = barrelExport(
+      makeUcf({ componentName: 'Button', exportedFromBarrel: true }),
+    );
+    const button = records.find((r) => r.canonical === 'Button');
+    expect(button).toBeDefined();
+    expect(button!.weight).toBe(0.08);
+  });
+
+  it('does not fire when exportedFromBarrel is false', () => {
+    const records = barrelExport(
+      makeUcf({ componentName: 'Button', exportedFromBarrel: false }),
+    );
+    expect(records).toEqual([]);
+  });
+
+  it('does not fire when name has no canonical', () => {
+    const records = barrelExport(
+      makeUcf({ componentName: 'WeirdHelper', exportedFromBarrel: true }),
+    );
+    expect(records).toEqual([]);
+  });
+});

package/src/signals/__tests__/html-root.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+
+import htmlRoot from '../html-root.js';
+import { makeUcf, root } from '../../__tests__/fixtures.js';
+
+describe('HTML_ROOT', () => {
+  it('fires Button on a single <button> root', () => {
+    const records = htmlRoot(makeUcf({ rootElements: [root('button')] }));
+    expect(records).toHaveLength(1);
+    expect(records[0].canonical).toBe('Button');
+    expect(records[0].weight).toBe(0.45);
+  });
+
+  it('does not fire on a plain <div>', () => {
+    const records = htmlRoot(makeUcf({ rootElements: [root('div')] }));
+    expect(records).toEqual([]);
+  });
+
+  it('does not fire on Custom: roots (component-typed)', () => {
+    const records = htmlRoot(makeUcf({ rootElements: [root('Custom:Foo')] }));
+    expect(records).toEqual([]);
+  });
+
+  it('skips <input> entirely (INPUT_TYPE owns it)', () => {
+    const records = htmlRoot(
+      makeUcf({ rootElements: [root('input', { inputType: 'text' })] }),
+    );
+    expect(records).toEqual([]);
+  });
+
+  it('emits multiple hypotheses for ambiguous tags (<nav>)', () => {
+    const records = htmlRoot(makeUcf({ rootElements: [root('nav')] }));
+    const canonicals = records.map((r) => r.canonical).sort();
+    expect(canonicals).toEqual(['Breadcrumb', 'NavigationMenu', 'Pagination']);
+  });
+
+  it('reduces weight when conditional roots disagree', () => {
+    const records = htmlRoot(
+      makeUcf({ rootElements: [root('button'), root('div')] }),
+    );
+    expect(records).toHaveLength(1);
+    expect(records[0].canonical).toBe('Button');
+    // Button only fires on 1 of 2 branches → weight halved.
+    expect(records[0].weight).toBeCloseTo(0.225, 3);
+  });
+
+  it('keeps full weight when both branches agree', () => {
+    const records = htmlRoot(
+      makeUcf({ rootElements: [root('button'), root('button')] }),
+    );
+    expect(records).toHaveLength(1);
+    expect(records[0].canonical).toBe('Button');
+    expect(records[0].weight).toBe(0.45);
+  });
+});

package/src/signals/__tests__/input-type.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest';
+
+import inputType from '../input-type.js';
+import { makeUcf, root } from '../../__tests__/fixtures.js';
+
+describe('INPUT_TYPE', () => {
+  it('fires Checkbox on <input type="checkbox">', () => {
+    const records = inputType(
+      makeUcf({ rootElements: [root('input', { inputType: 'checkbox' })] }),
+    );
+    expect(records).toHaveLength(1);
+    expect(records[0].canonical).toBe('Checkbox');
+    expect(records[0].weight).toBe(0.6);
+  });
+
+  it('upgrades Checkbox → Switch when role="switch" is present', () => {
+    const records = inputType(
+      makeUcf({
+        rootElements: [root('input', { inputType: 'checkbox' })],
+        ariaRoles: ['switch'],
+      }),
+    );
+    expect(records).toHaveLength(1);
+    expect(records[0].canonical).toBe('Switch');
+    expect(records[0].weight).toBe(0.6);
+  });
+
+  it('fires PasswordInput on <input type="password">', () => {
+    const records = inputType(
+      makeUcf({ rootElements: [root('input', { inputType: 'password' })] }),
+    );
+    expect(records.map((r) => r.canonical)).toEqual(['PasswordInput']);
+  });
+
+  it('does not fire on a non-input root', () => {
+    expect(inputType(makeUcf({ rootElements: [root('button')] }))).toEqual([]);
+  });
+
+  it('does not fire on <input> with no inputType field', () => {
+    expect(
+      inputType(makeUcf({ rootElements: [root('input')] })),
+    ).toEqual([]);
+  });
+
+  it('maps date inputs to DatePicker', () => {
+    const records = inputType(
+      makeUcf({ rootElements: [root('input', { inputType: 'date' })] }),
+    );
+    expect(records[0].canonical).toBe('DatePicker');
+  });
+
+  it('maps range inputs to Slider', () => {
+    const records = inputType(
+      makeUcf({ rootElements: [root('input', { inputType: 'range' })] }),
+    );
+    expect(records[0].canonical).toBe('Slider');
+  });
+});

package/src/signals/__tests__/library-reexport.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest';
+
+import libraryReexport from '../library-reexport.js';
+import { importRecord, makeUcf, root } from '../../__tests__/fixtures.js';
+
+describe('LIBRARY_REEXPORT', () => {
+  it('fires on Radix Dialog Root used as a JSX root', () => {
+    const ucf = makeUcf({
+      imports: [
+        importRecord('@radix-ui/react-dialog', { imported: 'Root', local: 'DialogPrimitive' }),
+      ],
+      rootElements: [root('Custom:DialogPrimitive')],
+    });
+    const records = libraryReexport(ucf);
+    expect(records).toHaveLength(1);
+    expect(records[0].canonical).toBe('Dialog');
+    expect(records[0].weight).toBe(0.55);
+    expect(records[0].evidence).toMatchObject({
+      package: '@radix-ui/react-dialog',
+      importedName: 'Root',
+      localBinding: 'DialogPrimitive',
+    });
+  });
+
+  it('does not fire when the imported binding is not used as a root', () => {
+    const ucf = makeUcf({
+      imports: [
+        importRecord('@radix-ui/react-dialog', { imported: 'Root', local: 'DialogPrimitive' }),
+      ],
+      // The component renders a `div`, not the imported primitive.
+      rootElements: [root('div')],
+    });
+    expect(libraryReexport(ucf)).toEqual([]);
+  });
+
+  it('does not fire on an unknown package', () => {
+    const ucf = makeUcf({
+      imports: [importRecord('some-unknown-pkg', { imported: 'Root', local: 'Root' })],
+      rootElements: [root('Custom:Root')],
+    });
+    expect(libraryReexport(ucf)).toEqual([]);
+  });
+
+  it('de-duplicates when two imports point to the same canonical', () => {
+    const ucf = makeUcf({
+      imports: [
+        importRecord('@mui/material/Button', { imported: 'default', local: 'MuiButton' }),
+        importRecord('@chakra-ui/react', { imported: 'Button', local: 'ChakraBtn' }),
+      ],
+      rootElements: [root('Custom:MuiButton'), root('Custom:ChakraBtn')],
+    });
+    const records = libraryReexport(ucf);
+    expect(records).toHaveLength(1);
+    expect(records[0].canonical).toBe('Button');
+  });
+
+  it('handles default-export packages (MUI per-module)', () => {
+    const ucf = makeUcf({
+      imports: [
+        importRecord('@mui/material/Dialog', { imported: 'default', local: 'Dialog' }),
+      ],
+      rootElements: [root('Custom:Dialog')],
+    });
+    const records = libraryReexport(ucf);
+    expect(records).toHaveLength(1);
+    expect(records[0].canonical).toBe('Dialog');
+  });
+});

package/src/signals/__tests__/name-match.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+
+import nameMatch from '../name-match.js';
+import { makeUcf } from '../../__tests__/fixtures.js';
+
+describe('NAME_MATCH', () => {
+  it('fires Button on direct canonical name', () => {
+    const records = nameMatch(makeUcf({ componentName: 'Button' }));
+    const button = records.find((r) => r.canonical === 'Button');
+    expect(button).toBeDefined();
+    expect(button!.weight).toBe(0.15);
+  });
+
+  it('fires Button via synonym (PrimaryButton)', () => {
+    const records = nameMatch(makeUcf({ componentName: 'PrimaryButton' }));
+    expect(records.some((r) => r.canonical === 'Button')).toBe(true);
+  });
+
+  it('fires Button after stripping library prefix (MuiButton)', () => {
+    const records = nameMatch(makeUcf({ componentName: 'MuiButton' }));
+    expect(records.some((r) => r.canonical === 'Button')).toBe(true);
+  });
+
+  it('fires Button after stripping suffix (ButtonRoot)', () => {
+    const records = nameMatch(makeUcf({ componentName: 'ButtonRoot' }));
+    expect(records.some((r) => r.canonical === 'Button')).toBe(true);
+  });
+
+  it('does not fire on an unrelated name', () => {
+    const records = nameMatch(makeUcf({ componentName: 'Foo' }));
+    expect(records).toEqual([]);
+  });
+
+  it('weight is always 0.15 alone (never load-bearing)', () => {
+    const records = nameMatch(makeUcf({ componentName: 'Dialog' }));
+    for (const record of records) expect(record.weight).toBe(0.15);
+  });
+
+  it('Modal synonym maps to Dialog', () => {
+    const records = nameMatch(makeUcf({ componentName: 'Modal' }));
+    expect(records.some((r) => r.canonical === 'Dialog')).toBe(true);
+  });
+});

package/src/signals/__tests__/path-hint.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+
+import pathHint from '../path-hint.js';
+import { makeUcf } from '../../__tests__/fixtures.js';
+
+describe('PATH_HINT', () => {
+  it('fires on src/components/ui/button.tsx → Button', () => {
+    const records = pathHint(
+      makeUcf({
+        filePath: 'src/components/ui/button.tsx',
+        componentName: 'Button',
+      }),
+    );
+    const button = records.find((r) => r.canonical === 'Button');
+    expect(button).toBeDefined();
+    expect(button!.weight).toBe(0.1);
+  });
+
+  it('does not fire on src/pages/login.tsx', () => {
+    const records = pathHint(
+      makeUcf({ filePath: 'src/pages/login.tsx', componentName: 'Button' }),
+    );
+    expect(records).toEqual([]);
+  });
+
+  it('fires on primitives/ directory hint', () => {
+    const records = pathHint(
+      makeUcf({
+        filePath: 'src/primitives/dialog.tsx',
+        componentName: 'Modal',
+      }),
+    );
+    expect(records.some((r) => r.canonical === 'Dialog')).toBe(true);
+  });
+
+  it('falls back to component name when basename has no canonical', () => {
+    const records = pathHint(
+      makeUcf({
+        filePath: 'src/atoms/index.tsx',
+        componentName: 'Tooltip',
+      }),
+    );
+    expect(records.some((r) => r.canonical === 'Tooltip')).toBe(true);
+  });
+
+  it('handles dasherized basenames', () => {
+    const records = pathHint(
+      makeUcf({
+        filePath: 'src/ui/icon-button.tsx',
+        componentName: 'IconButton',
+      }),
+    );
+    expect(records.some((r) => r.canonical === 'IconButton')).toBe(true);
+  });
+});

package/src/signals/__tests__/prop-fingerprint.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest';
+
+import propFingerprint from '../prop-fingerprint.js';
+import { makeUcf, prop } from '../../__tests__/fixtures.js';
+
+describe('PROP_FINGERPRINT', () => {
+  it('fires Button on { onClick, children } (§9.5 reference)', () => {
+    const records = propFingerprint(
+      makeUcf({
+        props: [
+          prop('onClick', '(event: MouseEvent) => void'),
+          prop('children', 'ReactNode'),
+        ],
+      }),
+    );
+    const button = records.find((r) => r.canonical === 'Button');
+    expect(button).toBeDefined();
+    expect(button!.weight).toBe(0.3);
+  });
+
+  it('boosts Button weight with optional matches (variant, size, disabled)', () => {
+    const records = propFingerprint(
+      makeUcf({
+        props: [
+          prop('onClick', '() => void'),
+          prop('children', 'ReactNode'),
+          prop('variant', 'string'),
+          prop('size', 'string'),
+          prop('disabled', 'boolean'),
+        ],
+      }),
+    );
+    const button = records.find((r) => r.canonical === 'Button');
+    expect(button).toBeDefined();
+    // Base 0.3 + 3 optionals × 0.05 = 0.45
+    expect(button!.weight).toBeCloseTo(0.45, 3);
+  });
+
+  it('fires Dialog on { open, onOpenChange } (§10.1 example)', () => {
+    const records = propFingerprint(
+      makeUcf({
+        props: [
+          prop('open', 'boolean'),
+          prop('onOpenChange', '(open: boolean) => void'),
+        ],
+      }),
+    );
+    const dialog = records.find((r) => r.canonical === 'Dialog');
+    expect(dialog).toBeDefined();
+    expect(dialog!.weight).toBe(0.3);
+  });
+
+  it('does not fire Button on input-shaped props (negative case)', () => {
+    const records = propFingerprint(
+      makeUcf({
+        props: [
+          prop('value', 'string'),
+          prop('onChange', '(value: string) => void'),
+        ],
+      }),
+    );
+    const button = records.find((r) => r.canonical === 'Button');
+    expect(button).toBeUndefined();
+  });
+
+  it('penalizes hypotheses when polymorphic prop `as` is present', () => {
+    const recordsBase = propFingerprint(
+      makeUcf({
+        props: [prop('onClick', '() => void'), prop('children', 'ReactNode')],
+      }),
+    );
+    const recordsPoly = propFingerprint(
+      makeUcf({
+        props: [
+          prop('onClick', '() => void'),
+          prop('children', 'ReactNode'),
+          prop('as', 'ElementType'),
+        ],
+      }),
+    );
+    const baseWeight = recordsBase.find((r) => r.canonical === 'Button')!.weight;
+    const polyWeight = recordsPoly.find((r) => r.canonical === 'Button')!.weight;
+    expect(polyWeight).toBeCloseTo(baseWeight - 0.1, 3);
+  });
+
+  it('fires Checkbox on { checked, onCheckedChange }', () => {
+    const records = propFingerprint(
+      makeUcf({
+        props: [
+          prop('checked', 'boolean'),
+          prop('onCheckedChange', '(checked: boolean) => void'),
+        ],
+      }),
+    );
+    const checkbox = records.find((r) => r.canonical === 'Checkbox');
+    expect(checkbox).toBeDefined();
+  });
+
+  it('emits no records when no canonical fingerprint is satisfied', () => {
+    const records = propFingerprint(
+      makeUcf({ props: [prop('foo', 'unknown')] }),
+    );
+    expect(records).toEqual([]);
+  });
+});