@fragments-sdk/classifier 0.2.0

package/LICENSE

@@ -0,0 +1,84 @@
+Functional Source License, Version 1.1, MIT Future License
+
+Licensor:  Conan McNicholl
+Software:  Fragments SDK (@fragments-sdk/cli, @fragments-sdk/mcp, @fragments-sdk/context)
+
+IMPORTANT: The @fragments-sdk/ui package is licensed separately under the MIT License.
+See libs/ui/LICENSE for details.
+
+---
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The individual or entity listed above.
+
+### The Software
+
+The software identified above, including all source code, object code,
+documentation, and other files provided by the Licensor.
+
+### Grant of Rights
+
+Subject to the conditions below, the Licensor grants you a non-exclusive,
+worldwide, royalty-free license to use, copy, modify, create derivative works,
+and redistribute the Software, in each case subject to the limitations below.
+
+### Limitation — Competing Use
+
+You may not use the Software in, or to provide, a Commercial Product or Service
+that competes with the Software or with any product or service that the Licensor
+provides using the Software. A "Commercial Product or Service" is any product or
+service offered to third parties for a fee or other consideration.
+
+For clarity, the following uses are always permitted regardless of this limitation:
+
+  - Using the Software for your own internal business purposes
+  - Using the Software to build and deploy your own applications
+  - Using the Software for personal, educational, or evaluation purposes
+  - Providing professional services (consulting, integration) to your clients
+    that involve configuring or extending the Software
+
+The following are examples of Competing Use that are NOT permitted:
+
+  - Offering a hosted developer tools service that repackages or exposes
+    the functionality of the Software
+  - Selling or distributing a product that is a substitute for any product
+    or service offered by the Licensor
+  - Building and offering an MCP server, CLI tool, or code intelligence
+    platform that is substantially derived from the Software
+
+### Change Date and License
+
+On the second anniversary of each version's release date, the Licensor grants
+you the rights under the terms of the MIT License for that version.
+The "MIT License" means the license identified by SPDX as "MIT" and published
+at https://opensource.org/licenses/MIT.
+
+### No Warranties
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+### Limitation of Liability
+
+IN NO EVENT SHALL THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+### General
+
+If any provision of this License is held to be unenforceable, that provision
+shall be reformed only to the extent necessary to make it enforceable, and the
+remaining provisions shall continue in full force and effect.
+
+This License does not grant permission to use the trade names, trademarks,
+service marks, or product names of the Licensor, except as required for
+reasonable and customary use in describing the origin of the Software.
+
+---
+
+For more information about the Functional Source License, see https://fsl.software/

package/dist/index.d.ts

@@ -0,0 +1,184 @@
+import { UniversalComponentFact } from '@fragments-sdk/extract';
+
+type CanonicalId = string & {
+    readonly __brand: 'CanonicalId';
+};
+declare function canonicalId(value: string): CanonicalId;
+type SignalType = 'LIBRARY_REEXPORT' | 'HTML_ROOT' | 'ARIA_ROLE' | 'INPUT_TYPE' | 'PROP_FINGERPRINT' | 'NAME_MATCH' | 'PATH_HINT' | 'BARREL_EXPORT' | 'AI_SEMANTIC';
+type HeuristicSignalType = Exclude<SignalType, 'AI_SEMANTIC'>;
+interface SignalRecord {
+    type: SignalType;
+    canonical: CanonicalId;
+    weight: number;
+    evidence: Record<string, unknown>;
+}
+type SignalExtractor = (ucf: UniversalComponentFact) => SignalRecord[];
+type SignalRegistry = Record<HeuristicSignalType, SignalExtractor>;
+type Band = 'auto' | 'suggested' | 'possible' | 'unknown';
+interface ClassificationAlternate {
+    canonical: CanonicalId;
+    confidence: number;
+    signals: SignalRecord[];
+}
+interface Classification {
+    canonical: CanonicalId | 'unknown';
+    confidence: number;
+    rawConfidence: number;
+    band: Band;
+    signals: SignalRecord[];
+    alternates: ClassificationAlternate[];
+    classifierVersion: string;
+    vocabVersion: string;
+}
+
+interface CombineMeta {
+    classifierVersion: string;
+    vocabVersion: string;
+}
+declare function combine(signals: SignalRecord[], meta: CombineMeta): Classification;
+
+declare const HEURISTIC_SIGNALS: SignalRegistry;
+
+type CanonicalCategory = 'inputs' | 'overlays' | 'navigation' | 'feedback' | 'data' | 'layout';
+interface CanonicalEntry {
+    id: CanonicalId;
+    category: CanonicalCategory;
+    primaryHtmlElement?: string;
+    primaryAriaRole?: string;
+}
+declare const VOCAB_V0_VERSION = "vocab_v0";
+declare const VOCAB_V0: ReadonlyArray<CanonicalEntry>;
+declare const VOCAB_V0_INDEX: ReadonlyMap<string, CanonicalEntry>;
+declare function isCanonicalId(value: string): value is CanonicalId;
+
+interface LibraryMapEntry {
+    canonical: CanonicalId;
+}
+type LibraryMap = ReadonlyMap<string, ReadonlyMap<string, LibraryMapEntry>>;
+declare const LIBRARY_MAP: LibraryMap;
+declare function lookupLibraryImport(pkg: string, importedName: string): CanonicalId | undefined;
+
+declare const NAME_STRIP_PREFIXES: ReadonlyArray<string>;
+declare const NAME_STRIP_SUFFIXES: ReadonlyArray<string>;
+declare const NAME_VARIANT_SUFFIXES: ReadonlyArray<string>;
+declare const SYNONYMS: ReadonlyMap<CanonicalId, ReadonlyArray<string>>;
+declare function lookupSynonym(name: string): ReadonlyArray<CanonicalId>;
+
+type TypeMatcher = (typeText: string) => boolean;
+interface RequiredPropTest {
+    oneOf: ReadonlyArray<{
+        name: string;
+        typeMatcher?: TypeMatcher;
+    }>;
+}
+interface OptionalPropTest {
+    name: string;
+    typeMatcher?: TypeMatcher;
+}
+interface AntiPropTest {
+    name: string;
+    typeMatcher?: TypeMatcher;
+}
+interface PropFingerprint {
+    required: ReadonlyArray<RequiredPropTest>;
+    optional: ReadonlyArray<OptionalPropTest>;
+    anti: ReadonlyArray<AntiPropTest>;
+}
+declare const PROP_FINGERPRINTS: ReadonlyMap<CanonicalId, PropFingerprint>;
+declare const POLYMORPHIC_PROP_NAMES: ReadonlySet<string>;
+
+/**
+ * Tag → canonical resolver shared by:
+ *  - `swap_to_canonical` MCP tool (`packages/mcp/src/tools/swap-to-canonical.ts`)
+ *  - PR-review advisor (`apps/cloud/src/lib/pr-advisor/cluster-by-file.ts`)
+ *
+ * Both surfaces must produce identical canonical resolutions for the same
+ * input — kept in one module so a tag added in one place is automatically
+ * available to the other.
+ *
+ * Generic containers (`div`, `span`, `form`, `label`) are intentionally
+ * absent: a swap suggestion for layout markup would drown the user in
+ * noise, since every codebase uses layout primitives liberally.
+ */
+interface RawAttrLike {
+    value: string;
+    dynamic: boolean;
+}
+type RawAttrMap = Map<string, RawAttrLike>;
+declare function resolveCanonicalForHtmlElement(tagName: string, attrs: RawAttrMap): string | null;
+/** Render a raw element to a short label (`<button>` / `<input type="checkbox">`). */
+declare function formatRawHtmlElement(tagName: string, attrs: RawAttrMap): string;
+
+declare const AI_PROMPT_VERSION = "aiprompt_v1";
+declare const AI_REASONING_CHAR_CAP = 200;
+declare const AI_SIGNAL_WEIGHTS: {
+    readonly high: 0.4;
+    readonly medium: 0.25;
+    readonly low: 0.1;
+};
+
+interface SecretScrubResult {
+    text: string;
+    redactionCount: number;
+    redactionsByType: Record<string, number>;
+}
+declare function scrubSecrets(input: string): SecretScrubResult;
+declare function sanitizeForInjection(input: string): string;
+
+interface PromptInputs {
+    ucf: UniversalComponentFact;
+    source: string;
+    callSites: ReadonlyArray<string>;
+    vocabulary: ReadonlyArray<VocabularyPromptEntry>;
+}
+interface VocabularyPromptEntry {
+    id: string;
+    category: CanonicalEntry['category'];
+    definition: string;
+}
+interface BuiltPrompt {
+    system: string;
+    user: string;
+}
+declare function buildAiPrompt(inputs: PromptInputs): BuiltPrompt;
+declare function truncateSource(input: string, maxLines?: number): string;
+
+type AiConfidence = 'high' | 'medium' | 'low' | 'unknown';
+interface AiResponseAlternate {
+    canonical: string;
+    reason: string;
+}
+interface AiResponse {
+    canonical: string;
+    confidence: AiConfidence;
+    reasoning: string;
+    alternates: AiResponseAlternate[];
+}
+type AiParseResult = {
+    ok: true;
+    value: AiResponse;
+} | {
+    ok: false;
+    reason: string;
+};
+declare function parseAiResponse(raw: string): AiParseResult;
+declare function applyVocabWhitelist(response: AiResponse, allowedCanonicals: ReadonlySet<string>): AiResponse;
+
+interface AiSignalInputs {
+    response: AiResponse;
+    allowedCanonicals: ReadonlySet<string>;
+    modelId: string;
+    promptVersion: string;
+}
+declare function aiResponseToSignals(inputs: AiSignalInputs): SignalRecord[];
+
+interface CacheKeyInputs {
+    ucfId: string;
+    sourceTextHash: string;
+    promptVersion: string;
+    modelId: string;
+}
+declare function deriveAiCacheKey(inputs: CacheKeyInputs): string;
+declare function hashSourceText(input: string): string;
+
+export { AI_PROMPT_VERSION, AI_REASONING_CHAR_CAP, AI_SIGNAL_WEIGHTS, type AiConfidence, type AiParseResult, type AiResponse, type AiResponseAlternate, type AiSignalInputs, type Band, type BuiltPrompt, type CacheKeyInputs, type CanonicalCategory, type CanonicalEntry, type CanonicalId, type Classification, type ClassificationAlternate, type CombineMeta, HEURISTIC_SIGNALS, type HeuristicSignalType, LIBRARY_MAP, NAME_STRIP_PREFIXES, NAME_STRIP_SUFFIXES, NAME_VARIANT_SUFFIXES, POLYMORPHIC_PROP_NAMES, PROP_FINGERPRINTS, type PromptInputs, type PropFingerprint, type RawAttrLike, type RawAttrMap, SYNONYMS, type SecretScrubResult, type SignalExtractor, type SignalRecord, type SignalRegistry, type SignalType, VOCAB_V0, VOCAB_V0_INDEX, VOCAB_V0_VERSION, type VocabularyPromptEntry, aiResponseToSignals, applyVocabWhitelist, buildAiPrompt, canonicalId, combine, deriveAiCacheKey, formatRawHtmlElement, hashSourceText, isCanonicalId, lookupLibraryImport, lookupSynonym, parseAiResponse, resolveCanonicalForHtmlElement, sanitizeForInjection, scrubSecrets, truncateSource };