@muloka/figma-console-mcp 0.5.2 → 0.5.4

package/dist/cloudflare/apps/design-system-dashboard/scoring/accessibility.js

@@ -0,0 +1,277 @@
+/**
+ * Accessibility Scorer (weight: 0.15)
+ *
+ * Checks accessibility-related signals in the design system.
+ * Evaluates color contrast ratios, state variant coverage,
+ * and semantic color naming patterns.
+ */
+import { clamp, getSeverity } from "./types.js";
+/** Maximum examples to include in a finding. */
+const MAX_EXAMPLES = 5;
+/** WCAG AA minimum contrast ratio for normal text. */
+const WCAG_AA_RATIO = 4.5;
+/** State-related variant values that indicate accessible component design. */
+const STATE_VARIANTS = [
+    "disabled",
+    "error",
+    "focus",
+    "hover",
+    "active",
+    "pressed",
+    "selected",
+];
+/** Semantic color token name patterns that indicate accessibility awareness. */
+const SEMANTIC_COLOR_NAMES = ["error", "warning", "success", "info", "danger"];
+/**
+ * Linearize an sRGB channel value for luminance calculation.
+ * Input: channel value in 0-1 range.
+ */
+function linearize(channel) {
+    return channel <= 0.04045
+        ? channel / 12.92
+        : ((channel + 0.055) / 1.055) ** 2.4;
+}
+/**
+ * Calculate relative luminance of a color.
+ * r, g, b are in 0-1 range (as Figma provides them).
+ */
+function luminance(r, g, b) {
+    return 0.2126 * linearize(r) + 0.7152 * linearize(g) + 0.0722 * linearize(b);
+}
+/**
+ * Calculate contrast ratio between two colors.
+ * Returns a ratio >= 1 (e.g., 4.5 for WCAG AA compliance).
+ */
+function contrastRatio(r1, g1, b1, r2, g2, b2) {
+    const lum1 = luminance(r1, g1, b1);
+    const lum2 = luminance(r2, g2, b2);
+    const lighter = Math.max(lum1, lum2);
+    const darker = Math.min(lum1, lum2);
+    return (lighter + 0.05) / (darker + 0.05);
+}
+/**
+ * Check if a value is a direct color (not an alias).
+ */
+function isDirectColor(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v.r === "number" &&
+        typeof v.g === "number" &&
+        typeof v.b === "number" &&
+        v.type !== "VARIABLE_ALIAS");
+}
+/**
+ * Extract resolved color values from variables.
+ * Returns an array of { name, r, g, b } objects for direct color values.
+ */
+function extractColorValues(variables) {
+    const colors = [];
+    for (const variable of variables) {
+        if (variable.resolvedType !== "COLOR" || !variable.valuesByMode)
+            continue;
+        for (const value of Object.values(variable.valuesByMode)) {
+            if (isDirectColor(value)) {
+                colors.push({
+                    name: variable.name,
+                    r: value.r,
+                    g: value.g,
+                    b: value.b,
+                });
+                break; // Use the first direct color value per variable
+            }
+        }
+    }
+    return colors;
+}
+/**
+ * Identify likely foreground/background color pairs and check contrast.
+ *
+ * Strategy: pair colors whose names suggest fg/bg relationships:
+ * - Names containing "background"/"bg"/"surface" are backgrounds
+ * - Names containing "text"/"foreground"/"fg"/"on" are foregrounds
+ * Falls back to pairing dark colors with light colors if no naming convention found.
+ */
+function scoreColorContrast(data) {
+    const colors = extractColorValues(data.variables);
+    if (colors.length < 2) {
+        return {
+            id: "a11y-color-contrast",
+            label: "Color contrast",
+            score: 100,
+            severity: "info",
+            tooltip: "Foreground/background color pairs should meet WCAG AA contrast ratio (4.5:1). Low contrast makes content unreadable for users with vision impairments.",
+            details: colors.length === 0
+                ? "No direct color values to evaluate."
+                : "Only one color found; need at least two to check contrast.",
+        };
+    }
+    const bgPattern = /background|bg|surface|canvas|base/i;
+    const fgPattern = /text|foreground|fg|on-|on\.|label|title|body|heading/i;
+    const backgrounds = colors.filter((c) => bgPattern.test(c.name));
+    const foregrounds = colors.filter((c) => fgPattern.test(c.name));
+    // If naming conventions are not used, use luminance-based heuristic
+    let pairs = [];
+    if (backgrounds.length > 0 && foregrounds.length > 0) {
+        // Pair foregrounds with backgrounds by naming proximity
+        for (const fg of foregrounds) {
+            for (const bg of backgrounds) {
+                pairs.push({ fg, bg });
+            }
+        }
+    }
+    else {
+        // Heuristic: separate into light (luminance > 0.5) and dark (luminance <= 0.5)
+        const lightColors = colors.filter((c) => luminance(c.r, c.g, c.b) > 0.5);
+        const darkColors = colors.filter((c) => luminance(c.r, c.g, c.b) <= 0.5);
+        for (const dark of darkColors) {
+            for (const light of lightColors) {
+                pairs.push({ fg: dark, bg: light });
+            }
+        }
+    }
+    if (pairs.length === 0) {
+        return {
+            id: "a11y-color-contrast",
+            label: "Color contrast",
+            score: 50,
+            severity: "warning",
+            tooltip: "Foreground/background color pairs should meet WCAG AA contrast ratio (4.5:1). Low contrast makes content unreadable for users with vision impairments.",
+            details: "Could not identify foreground/background color pairs to check contrast.",
+        };
+    }
+    // Limit pair evaluation to avoid performance issues with large token sets
+    const maxPairs = 50;
+    if (pairs.length > maxPairs) {
+        pairs = pairs.slice(0, maxPairs);
+    }
+    let passingPairs = 0;
+    const failingExamples = [];
+    for (const { fg, bg } of pairs) {
+        const ratio = contrastRatio(fg.r, fg.g, fg.b, bg.r, bg.g, bg.b);
+        if (ratio >= WCAG_AA_RATIO) {
+            passingPairs++;
+        }
+        else if (failingExamples.length < MAX_EXAMPLES) {
+            failingExamples.push(`${fg.name} / ${bg.name} (${ratio.toFixed(1)}:1)`);
+        }
+    }
+    const passRatio = passingPairs / pairs.length;
+    const score = clamp(passRatio * 100);
+    return {
+        id: "a11y-color-contrast",
+        label: "Color contrast",
+        score,
+        severity: getSeverity(score),
+        tooltip: "Foreground/background color pairs should meet WCAG AA contrast ratio (4.5:1). Low contrast makes content unreadable for users with vision impairments.",
+        details: `${passingPairs} of ${pairs.length} color pairs meet WCAG AA contrast ratio (${WCAG_AA_RATIO}:1).`,
+        examples: failingExamples.length > 0 ? failingExamples : undefined,
+    };
+}
+/**
+ * Score state variant coverage.
+ * Components should include state-related variants for accessibility.
+ */
+function scoreStateVariants(data) {
+    const components = data.components;
+    if (components.length === 0) {
+        return {
+            id: "a11y-state-variants",
+            label: "State variants",
+            score: 100,
+            severity: "info",
+            tooltip: "Interactive components should include state variants (disabled, error, focus, hover, active, pressed, selected) for accessible interactions.",
+            details: "No components to evaluate.",
+        };
+    }
+    // Check which state variants exist across all component names
+    const allNames = components.map((c) => c.name.toLowerCase()).join(" ");
+    const foundStates = STATE_VARIANTS.filter((state) => allNames.includes(state));
+    const ratio = foundStates.length / STATE_VARIANTS.length;
+    const score = clamp(ratio * 100);
+    const missingStates = STATE_VARIANTS.filter((state) => !allNames.includes(state));
+    return {
+        id: "a11y-state-variants",
+        label: "State variants",
+        score,
+        severity: getSeverity(score),
+        tooltip: "Interactive components should include state variants (disabled, error, focus, hover, active, pressed, selected) for accessible interactions.",
+        details: missingStates.length > 0
+            ? `Found ${foundStates.length} of ${STATE_VARIANTS.length} state variants. Missing: ${missingStates.join(", ")}.`
+            : `All ${STATE_VARIANTS.length} state variants are represented.`,
+    };
+}
+/**
+ * Score semantic color naming.
+ * The token set should include semantic color tokens for error/warning/success/info.
+ */
+function variableDataUnavailable(data) {
+    return (data.dataAvailability !== undefined && !data.dataAvailability.variables);
+}
+function scoreSemanticColorNaming(data) {
+    const colorVars = data.variables.filter((v) => v.resolvedType === "COLOR");
+    if (colorVars.length === 0) {
+        const unavailable = variableDataUnavailable(data);
+        return {
+            id: "a11y-semantic-colors",
+            label: "Semantic color naming",
+            score: 0,
+            severity: unavailable ? "info" : "fail",
+            tooltip: "The token set should include semantic color categories (error, warning, success, info, danger) to convey meaning beyond color alone.",
+            details: unavailable
+                ? `Variable data unavailable: ${data.dataAvailability?.variableError || "Requires Desktop Bridge or Enterprise plan."}`
+                : "No color variables found.",
+        };
+    }
+    const foundSemantic = [];
+    const missingSemantic = [];
+    const semanticExamples = [];
+    for (const name of SEMANTIC_COLOR_NAMES) {
+        const matching = colorVars.filter((v) => v.name.toLowerCase().includes(name));
+        if (matching.length > 0) {
+            foundSemantic.push(name);
+            semanticExamples.push(`${name}: ${matching
+                .slice(0, 2)
+                .map((v) => v.name)
+                .join(", ")}`);
+        }
+        else {
+            missingSemantic.push(name);
+        }
+    }
+    const ratio = foundSemantic.length / SEMANTIC_COLOR_NAMES.length;
+    const score = clamp(ratio * 100);
+    return {
+        id: "a11y-semantic-colors",
+        label: "Semantic color naming",
+        score,
+        severity: getSeverity(score),
+        tooltip: "The token set should include semantic color categories (error, warning, success, info, danger) to convey meaning beyond color alone.",
+        details: missingSemantic.length > 0
+            ? `Found ${foundSemantic.length} of ${SEMANTIC_COLOR_NAMES.length} semantic color categories. Missing: ${missingSemantic.join(", ")}.`
+            : "All semantic color categories (error, warning, success, info, danger) are present.",
+        examples: semanticExamples.length > 0
+            ? semanticExamples.slice(0, MAX_EXAMPLES)
+            : undefined,
+    };
+}
+/**
+ * Accessibility category scorer.
+ * Returns the average score across all accessibility checks.
+ */
+export function scoreAccessibility(data) {
+    const findings = [
+        scoreColorContrast(data),
+        scoreStateVariants(data),
+        scoreSemanticColorNaming(data),
+    ];
+    const score = clamp(findings.reduce((sum, f) => sum + f.score, 0) / findings.length);
+    return {
+        id: "accessibility",
+        label: "Accessibility",
+        shortLabel: "Accessibility",
+        score,
+        weight: 0.15,
+        findings,
+    };
+}

package/dist/cloudflare/apps/design-system-dashboard/scoring/component-metadata.js

@@ -0,0 +1,357 @@
+/**
+ * Component Metadata Scorer (weight: 0.20)
+ *
+ * Checks component quality and completeness within the design system.
+ * Evaluates description presence, description quality, property completeness,
+ * variant structure, and category organization.
+ *
+ * Scores against "scorable units" (component sets + standalone components)
+ * rather than raw variant count to avoid inflated totals.
+ */
+import { clamp, getSeverity } from "./types.js";
+/** Maximum examples to include in a finding. */
+const MAX_EXAMPLES = 5;
+/** Minimum description length to be considered "quality" documentation. */
+const MIN_QUALITY_DESC_LENGTH = 20;
+/**
+ * Build a lookup structure for matching components to variant groups.
+ * Collects component set node IDs for `containing_frame.containingComponentSet`
+ * matching (primary REST API path) and name prefixes as fallback.
+ */
+function buildComponentSetLookup(data) {
+    const nodeIds = new Set();
+    const namePrefixes = new Set();
+    for (const cs of data.componentSets) {
+        if (cs.node_id)
+            nodeIds.add(cs.node_id);
+        if (cs.name)
+            namePrefixes.add(cs.name + "/");
+    }
+    return { nodeIds, namePrefixes };
+}
+/**
+ * Check if a component belongs to a variant set.
+ *
+ * Detection order:
+ * 1. Plugin API: `componentSetId` (set on ComponentNode by Figma plugin runtime)
+ * 2. REST API: `containing_frame.containingComponentSet` (present on variants
+ *    returned by GET /v1/files/:key/components)
+ * 3. File JSON: `component_set_id` (snake_case field on COMPONENT nodes in file tree)
+ * 4. Name prefix: variant names starting with "SetName/" (some API formats)
+ * 5. Frame node ID: containing_frame.nodeId matching a known component set node
+ */
+function isComponentInSet(component, lookup) {
+    // Plugin API: direct componentSetId
+    if (component.componentSetId)
+        return true;
+    // REST API: containing_frame.containingComponentSet is set on variant components
+    if (component.containing_frame?.containingComponentSet)
+        return true;
+    // File JSON: snake_case variant of componentSetId
+    if (component.component_set_id)
+        return true;
+    // Name-based fallback: variant names may start with "SetName/"
+    if (component.name) {
+        for (const prefix of lookup.namePrefixes) {
+            if (component.name.startsWith(prefix))
+                return true;
+        }
+    }
+    // Frame node ID fallback
+    const frameNodeId = component.containing_frame?.nodeId;
+    if (frameNodeId && lookup.nodeIds.has(frameNodeId))
+        return true;
+    return false;
+}
+/**
+ * Classify components into standalone, variants, and component sets.
+ * Scoring evaluates `scorableUnits` (standalone + componentSets)
+ * instead of the raw component list which double-counts variants.
+ */
+export function classifyComponents(data) {
+    const lookup = buildComponentSetLookup(data);
+    const standalone = [];
+    const variants = [];
+    for (const comp of data.components) {
+        if (isComponentInSet(comp, lookup)) {
+            variants.push(comp);
+        }
+        else {
+            standalone.push(comp);
+        }
+    }
+    return {
+        standalone,
+        variants,
+        componentSets: data.componentSets,
+        scorableUnits: [...standalone, ...data.componentSets],
+    };
+}
+// ---------------------------------------------------------------------------
+// Scoring functions (operate on scorable units)
+// ---------------------------------------------------------------------------
+/**
+ * Score description presence across scorable units.
+ * Component sets and standalone components should have non-empty descriptions.
+ */
+function scoreDescriptionPresence(classification) {
+    const { scorableUnits } = classification;
+    if (scorableUnits.length === 0) {
+        return {
+            id: "component-desc-presence",
+            label: "Description presence",
+            score: 100,
+            severity: "info",
+            tooltip: "Components and component sets should have descriptions. Descriptions appear in Figma's asset panel and help designers find the right component.",
+            details: "No components to evaluate.",
+        };
+    }
+    const withDesc = scorableUnits.filter((c) => c.description && c.description.trim().length > 0);
+    const withoutDesc = scorableUnits.filter((c) => !c.description || c.description.trim().length === 0);
+    const ratio = withDesc.length / scorableUnits.length;
+    const score = clamp(ratio * 100);
+    return {
+        id: "component-desc-presence",
+        label: "Description presence",
+        score,
+        severity: getSeverity(score),
+        tooltip: "Components and component sets should have descriptions. Descriptions appear in Figma's asset panel and help designers find the right component.",
+        details: `${withDesc.length} of ${scorableUnits.length} components have descriptions (${Math.round(ratio * 100)}%).`,
+        examples: withoutDesc.length > 0
+            ? withoutDesc.slice(0, MAX_EXAMPLES).map((c) => c.name)
+            : undefined,
+        locations: withoutDesc.length > 0
+            ? withoutDesc.slice(0, MAX_EXAMPLES).map((c) => ({
+                name: c.name,
+                nodeId: c.node_id,
+                type: "component",
+            }))
+            : undefined,
+    };
+}
+/**
+ * Score description quality.
+ * Descriptions should be meaningful (>20 chars), not just the component name.
+ */
+function scoreDescriptionQuality(classification) {
+    const { scorableUnits } = classification;
+    const withDesc = scorableUnits.filter((c) => c.description && c.description.trim().length > 0);
+    if (withDesc.length === 0) {
+        return {
+            id: "component-desc-quality",
+            label: "Description quality",
+            score: 0,
+            severity: scorableUnits.length === 0 ? "info" : "fail",
+            tooltip: "Descriptions should be meaningful (20+ characters) and explain usage, not just repeat the name. Good descriptions reduce misuse.",
+            details: scorableUnits.length === 0
+                ? "No components to evaluate."
+                : "No components have descriptions to evaluate quality.",
+        };
+    }
+    const shortDescs = withDesc.filter((c) => c.description.trim().length < MIN_QUALITY_DESC_LENGTH);
+    const qualityCount = withDesc.length - shortDescs.length;
+    const ratio = qualityCount / withDesc.length;
+    const score = clamp(ratio * 100);
+    return {
+        id: "component-desc-quality",
+        label: "Description quality",
+        score,
+        severity: getSeverity(score),
+        tooltip: "Descriptions should be meaningful (20+ characters) and explain usage, not just repeat the name. Good descriptions reduce misuse.",
+        details: shortDescs.length > 0
+            ? `${shortDescs.length} of ${withDesc.length} descriptions are too short (<${MIN_QUALITY_DESC_LENGTH} chars). Provide usage guidance, not just names.`
+            : `All ${withDesc.length} descriptions provide meaningful documentation.`,
+        examples: shortDescs.length > 0
+            ? shortDescs.slice(0, MAX_EXAMPLES).map((c) => c.name)
+            : undefined,
+    };
+}
+/**
+ * Score property completeness.
+ * Standalone components should define properties for flexibility.
+ * Component sets inherently have properties via their variants.
+ */
+function scorePropertyCompleteness(classification) {
+    const { standalone, componentSets, scorableUnits } = classification;
+    if (scorableUnits.length === 0) {
+        return {
+            id: "component-property-completeness",
+            label: "Property completeness",
+            score: 100,
+            severity: "info",
+            tooltip: "Components should expose properties or use variant sets. Properties make components flexible and reduce the need for detaching instances.",
+            details: "No components to evaluate.",
+        };
+    }
+    // Component sets always count as having properties (they are variant groups)
+    // For standalone, check if they have any property definitions
+    const standaloneWithProps = standalone.filter((c) => c.componentPropertyDefinitions &&
+        Object.keys(c.componentPropertyDefinitions).length > 0);
+    const standaloneWithoutProps = standalone.filter((c) => !c.componentPropertyDefinitions ||
+        Object.keys(c.componentPropertyDefinitions).length === 0);
+    const withProperties = standaloneWithProps.length + componentSets.length;
+    const ratio = withProperties / scorableUnits.length;
+    const score = clamp(ratio * 100);
+    return {
+        id: "component-property-completeness",
+        label: "Property completeness",
+        score,
+        severity: getSeverity(score),
+        tooltip: "Components should expose properties or use variant sets. Properties make components flexible and reduce the need for detaching instances.",
+        details: `${withProperties} of ${scorableUnits.length} components have defined properties or variants (${Math.round(ratio * 100)}%).`,
+        examples: standaloneWithoutProps.length > 0
+            ? standaloneWithoutProps.slice(0, MAX_EXAMPLES).map((c) => c.name)
+            : undefined,
+        locations: standaloneWithoutProps.length > 0
+            ? standaloneWithoutProps.slice(0, MAX_EXAMPLES).map((c) => ({
+                name: c.name,
+                nodeId: c.node_id,
+                type: "component",
+            }))
+            : undefined,
+    };
+}
+/**
+ * Score variant structure.
+ * A higher ratio of component sets to total scorable units indicates
+ * good use of variant organization.
+ */
+function scoreVariantStructure(classification) {
+    const { standalone, componentSets, scorableUnits } = classification;
+    if (scorableUnits.length === 0) {
+        return {
+            id: "component-variant-structure",
+            label: "Variant structure",
+            score: 100,
+            severity: "info",
+            tooltip: "Related component variants should be organized into component sets. Sets make variant switching easy and reduce component sprawl.",
+            details: "No components to evaluate.",
+        };
+    }
+    const setCount = componentSets.length;
+    const ratio = setCount / scorableUnits.length;
+    const score = clamp(ratio * 100);
+    return {
+        id: "component-variant-structure",
+        label: "Variant structure",
+        score,
+        severity: getSeverity(score),
+        tooltip: "Related component variants should be organized into component sets. Sets make variant switching easy and reduce component sprawl.",
+        details: setCount > 0
+            ? `${setCount} of ${scorableUnits.length} components use variant sets (${Math.round(ratio * 100)}%). ${standalone.length} standalone component${standalone.length === 1 ? "" : "s"}.`
+            : "No components use variant structures. Consider organizing components into sets with variants.",
+        examples: standalone.length > 0 && setCount > 0
+            ? standalone.slice(0, MAX_EXAMPLES).map((c) => `${c.name} (standalone)`)
+            : undefined,
+    };
+}
+/**
+ * Score category organization.
+ * Components should use path separators (/) for logical grouping.
+ */
+function scoreCategoryOrganization(classification) {
+    const { scorableUnits } = classification;
+    if (scorableUnits.length === 0) {
+        return {
+            id: "component-category-org",
+            label: "Category organization",
+            score: 100,
+            severity: "info",
+            tooltip: 'Component names should use path separators (/) for grouping (e.g. Forms/Input). Organized naming improves asset panel navigation.',
+            details: "No components to evaluate.",
+        };
+    }
+    const withPath = scorableUnits.filter((c) => c.name?.includes("/"));
+    const withoutPath = scorableUnits.filter((c) => !c.name?.includes("/"));
+    const ratio = withPath.length / scorableUnits.length;
+    const score = clamp(ratio * 100);
+    return {
+        id: "component-category-org",
+        label: "Category organization",
+        score,
+        severity: getSeverity(score),
+        tooltip: 'Component names should use path separators (/) for grouping (e.g. Forms/Input). Organized naming improves asset panel navigation.',
+        details: withPath.length > 0
+            ? `${withPath.length} of ${scorableUnits.length} components use path-based grouping (${Math.round(ratio * 100)}%).`
+            : 'No components use path separators for grouping. Use "/" in names for organization (e.g., "Forms/Input").',
+        examples: withoutPath.length > 0
+            ? withoutPath.slice(0, MAX_EXAMPLES).map((c) => c.name)
+            : undefined,
+        locations: withoutPath.length > 0
+            ? withoutPath.slice(0, MAX_EXAMPLES).map((c) => ({
+                name: c.name,
+                nodeId: c.node_id,
+                type: "component",
+            }))
+            : undefined,
+    };
+}
+/** Matches Figma auto-generated layer names like "Frame 347", "Group 12", "Rectangle 5". */
+const GENERIC_NAME_RE = /^(Frame|Group|Rectangle|Ellipse|Line|Polygon|Vector|Text|Image|Slice|Component|Instance|Section|Boolean\s*Group)\s*\d*$/i;
+/**
+ * Score generic layer naming.
+ * Published components should have intentional names, not auto-generated ones.
+ */
+function scoreGenericNaming(classification) {
+    const { scorableUnits } = classification;
+    if (scorableUnits.length === 0) {
+        return {
+            id: "component-generic-naming",
+            label: "Layer naming",
+            score: 100,
+            severity: "info",
+            tooltip: "Published components should have intentional names. Auto-generated names like Frame 347 or Group 12 indicate layers that were never renamed.",
+            details: "No components to evaluate.",
+        };
+    }
+    const genericComps = scorableUnits.filter((c) => {
+        const segments = (c.name || "").split("/").map((s) => s.trim());
+        return segments.some((seg) => GENERIC_NAME_RE.test(seg));
+    });
+    const ratio = 1 - genericComps.length / scorableUnits.length;
+    const score = clamp(ratio * 100);
+    return {
+        id: "component-generic-naming",
+        label: "Layer naming",
+        score,
+        severity: getSeverity(score),
+        tooltip: "Published components should have intentional names. Auto-generated names like Frame 347 or Group 12 indicate layers that were never renamed.",
+        details: genericComps.length > 0
+            ? `${genericComps.length} of ${scorableUnits.length} components have auto-generated layer names (e.g. Frame, Group, Rectangle).`
+            : "All components have intentional names.",
+        examples: genericComps.length > 0
+            ? genericComps.slice(0, MAX_EXAMPLES).map((c) => c.name)
+            : undefined,
+        locations: genericComps.length > 0
+            ? genericComps.slice(0, MAX_EXAMPLES).map((c) => ({
+                name: c.name,
+                nodeId: c.node_id,
+                type: "component",
+            }))
+            : undefined,
+    };
+}
+/**
+ * Component Metadata category scorer.
+ * Returns the average score across all component metadata checks.
+ */
+export function scoreComponentMetadata(data) {
+    const classification = classifyComponents(data);
+    const findings = [
+        scoreDescriptionPresence(classification),
+        scoreDescriptionQuality(classification),
+        scorePropertyCompleteness(classification),
+        scoreVariantStructure(classification),
+        scoreCategoryOrganization(classification),
+        scoreGenericNaming(classification),
+    ];
+    const score = clamp(findings.reduce((sum, f) => sum + f.score, 0) / findings.length);
+    return {
+        id: "component-metadata",
+        label: "Component Metadata",
+        shortLabel: "Components",
+        score,
+        weight: 0.2,
+        findings,
+    };
+}