canicode 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,1104 @@
+import { z } from 'zod';
+import { GetFileResponse } from '@figma/rest-api-spec';
+
+declare const SeveritySchema: z.ZodEnum<{
+    blocking: "blocking";
+    risk: "risk";
+    "missing-info": "missing-info";
+    suggestion: "suggestion";
+}>;
+type Severity = z.infer<typeof SeveritySchema>;
+declare const SEVERITY_WEIGHT: Record<Severity, number>;
+declare const SEVERITY_LABELS: Record<Severity, string>;
+
+declare const CategorySchema: z.ZodEnum<{
+    layout: "layout";
+    token: "token";
+    component: "component";
+    naming: "naming";
+    "ai-readability": "ai-readability";
+    "handoff-risk": "handoff-risk";
+}>;
+type Category = z.infer<typeof CategorySchema>;
+declare const CATEGORIES: ("layout" | "token" | "component" | "naming" | "ai-readability" | "handoff-risk")[];
+declare const CATEGORY_LABELS: Record<Category, string>;
+
+/**
+ * Figma node types required for analysis
+ * See @figma/rest-api-spec for full API types
+ */
+declare const AnalysisNodeTypeSchema: z.ZodEnum<{
+    DOCUMENT: "DOCUMENT";
+    CANVAS: "CANVAS";
+    FRAME: "FRAME";
+    GROUP: "GROUP";
+    SECTION: "SECTION";
+    COMPONENT: "COMPONENT";
+    COMPONENT_SET: "COMPONENT_SET";
+    INSTANCE: "INSTANCE";
+    RECTANGLE: "RECTANGLE";
+    ELLIPSE: "ELLIPSE";
+    VECTOR: "VECTOR";
+    TEXT: "TEXT";
+    LINE: "LINE";
+    BOOLEAN_OPERATION: "BOOLEAN_OPERATION";
+    STAR: "STAR";
+    REGULAR_POLYGON: "REGULAR_POLYGON";
+    SLICE: "SLICE";
+    STICKY: "STICKY";
+    SHAPE_WITH_TEXT: "SHAPE_WITH_TEXT";
+    CONNECTOR: "CONNECTOR";
+    WIDGET: "WIDGET";
+    EMBED: "EMBED";
+    LINK_UNFURL: "LINK_UNFURL";
+    TABLE: "TABLE";
+    TABLE_CELL: "TABLE_CELL";
+}>;
+type AnalysisNodeType = z.infer<typeof AnalysisNodeTypeSchema>;
+declare const LayoutModeSchema: z.ZodEnum<{
+    NONE: "NONE";
+    HORIZONTAL: "HORIZONTAL";
+    VERTICAL: "VERTICAL";
+}>;
+type LayoutMode = z.infer<typeof LayoutModeSchema>;
+declare const LayoutAlignSchema: z.ZodEnum<{
+    MIN: "MIN";
+    CENTER: "CENTER";
+    MAX: "MAX";
+    STRETCH: "STRETCH";
+    INHERIT: "INHERIT";
+}>;
+type LayoutAlign = z.infer<typeof LayoutAlignSchema>;
+declare const LayoutPositioningSchema: z.ZodEnum<{
+    AUTO: "AUTO";
+    ABSOLUTE: "ABSOLUTE";
+}>;
+type LayoutPositioning = z.infer<typeof LayoutPositioningSchema>;
+/**
+ * Lightweight FigmaNode type for analysis
+ * Contains only properties needed by rules
+ */
+declare const BaseAnalysisNodeSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        DOCUMENT: "DOCUMENT";
+        CANVAS: "CANVAS";
+        FRAME: "FRAME";
+        GROUP: "GROUP";
+        SECTION: "SECTION";
+        COMPONENT: "COMPONENT";
+        COMPONENT_SET: "COMPONENT_SET";
+        INSTANCE: "INSTANCE";
+        RECTANGLE: "RECTANGLE";
+        ELLIPSE: "ELLIPSE";
+        VECTOR: "VECTOR";
+        TEXT: "TEXT";
+        LINE: "LINE";
+        BOOLEAN_OPERATION: "BOOLEAN_OPERATION";
+        STAR: "STAR";
+        REGULAR_POLYGON: "REGULAR_POLYGON";
+        SLICE: "SLICE";
+        STICKY: "STICKY";
+        SHAPE_WITH_TEXT: "SHAPE_WITH_TEXT";
+        CONNECTOR: "CONNECTOR";
+        WIDGET: "WIDGET";
+        EMBED: "EMBED";
+        LINK_UNFURL: "LINK_UNFURL";
+        TABLE: "TABLE";
+        TABLE_CELL: "TABLE_CELL";
+    }>;
+    visible: z.ZodDefault<z.ZodBoolean>;
+    layoutMode: z.ZodOptional<z.ZodEnum<{
+        NONE: "NONE";
+        HORIZONTAL: "HORIZONTAL";
+        VERTICAL: "VERTICAL";
+    }>>;
+    layoutAlign: z.ZodOptional<z.ZodEnum<{
+        MIN: "MIN";
+        CENTER: "CENTER";
+        MAX: "MAX";
+        STRETCH: "STRETCH";
+        INHERIT: "INHERIT";
+    }>>;
+    layoutPositioning: z.ZodOptional<z.ZodEnum<{
+        AUTO: "AUTO";
+        ABSOLUTE: "ABSOLUTE";
+    }>>;
+    primaryAxisAlignItems: z.ZodOptional<z.ZodString>;
+    counterAxisAlignItems: z.ZodOptional<z.ZodString>;
+    itemSpacing: z.ZodOptional<z.ZodNumber>;
+    paddingLeft: z.ZodOptional<z.ZodNumber>;
+    paddingRight: z.ZodOptional<z.ZodNumber>;
+    paddingTop: z.ZodOptional<z.ZodNumber>;
+    paddingBottom: z.ZodOptional<z.ZodNumber>;
+    absoluteBoundingBox: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>>;
+    componentId: z.ZodOptional<z.ZodString>;
+    componentPropertyDefinitions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    componentProperties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    styles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    fills: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    strokes: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    effects: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    boundVariables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    characters: z.ZodOptional<z.ZodString>;
+    style: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    devStatus: z.ZodOptional<z.ZodObject<{
+        type: z.ZodEnum<{
+            NONE: "NONE";
+            READY_FOR_DEV: "READY_FOR_DEV";
+            COMPLETED: "COMPLETED";
+        }>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    isAsset: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type AnalysisNode = z.infer<typeof BaseAnalysisNodeSchema> & {
+    children?: AnalysisNode[] | undefined;
+};
+declare const AnalysisNodeSchema: z.ZodType<AnalysisNode>;
+/**
+ * Figma file metadata for analysis
+ */
+declare const AnalysisFileSchema: z.ZodObject<{
+    fileKey: z.ZodString;
+    name: z.ZodString;
+    lastModified: z.ZodString;
+    version: z.ZodString;
+    document: z.ZodType<AnalysisNode, unknown, z.core.$ZodTypeInternals<AnalysisNode, unknown>>;
+    components: z.ZodRecord<z.ZodString, z.ZodObject<{
+        key: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodString;
+    }, z.core.$strip>>;
+    styles: z.ZodRecord<z.ZodString, z.ZodObject<{
+        key: z.ZodString;
+        name: z.ZodString;
+        styleType: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type AnalysisFile = z.infer<typeof AnalysisFileSchema>;
+
+/**
+ * Rule definition - static metadata (does not change)
+ */
+declare const RuleDefinitionSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    category: z.ZodEnum<{
+        layout: "layout";
+        token: "token";
+        component: "component";
+        naming: "naming";
+        "ai-readability": "ai-readability";
+        "handoff-risk": "handoff-risk";
+    }>;
+    why: z.ZodString;
+    impact: z.ZodString;
+    fix: z.ZodString;
+}, z.core.$strip>;
+type RuleDefinition = z.infer<typeof RuleDefinitionSchema>;
+/**
+ * Rule config - adjustable settings (can be modified via presets)
+ */
+declare const RuleConfigSchema: z.ZodObject<{
+    severity: z.ZodEnum<{
+        blocking: "blocking";
+        risk: "risk";
+        "missing-info": "missing-info";
+        suggestion: "suggestion";
+    }>;
+    score: z.ZodNumber;
+    depthWeight: z.ZodOptional<z.ZodNumber>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+type RuleConfig = z.infer<typeof RuleConfigSchema>;
+/**
+ * Context passed to rule check functions
+ */
+interface RuleContext {
+    file: AnalysisFile;
+    parent?: AnalysisNode | undefined;
+    depth: number;
+    maxDepth: number;
+    path: string[];
+    siblings?: AnalysisNode[] | undefined;
+}
+/**
+ * Rule violation result from check function
+ */
+interface RuleViolation {
+    ruleId: string;
+    nodeId: string;
+    nodePath: string;
+    message: string;
+}
+/**
+ * Rule check function signature
+ */
+type RuleCheckFn = (node: AnalysisNode, context: RuleContext, options?: Record<string, unknown>) => RuleViolation | null;
+/**
+ * Complete rule with definition, config, and check function
+ */
+interface Rule {
+    definition: RuleDefinition;
+    check: RuleCheckFn;
+}
+/**
+ * Rule ID type for type safety
+ */
+type RuleId = "no-auto-layout" | "absolute-position-in-auto-layout" | "fixed-width-in-responsive-context" | "missing-responsive-behavior" | "group-usage" | "fixed-size-in-auto-layout" | "missing-min-width" | "missing-max-width" | "deep-nesting" | "overflow-hidden-abuse" | "inconsistent-sibling-layout-direction" | "raw-color" | "raw-font" | "inconsistent-spacing" | "magic-number-spacing" | "raw-shadow" | "raw-opacity" | "multiple-fill-colors" | "missing-component" | "detached-instance" | "nested-instance-override" | "variant-not-used" | "component-property-unused" | "single-use-component" | "default-name" | "non-semantic-name" | "inconsistent-naming-convention" | "numeric-suffix-name" | "too-long-name" | "ambiguous-structure" | "z-index-dependent-layout" | "missing-layout-hint" | "invisible-layer" | "empty-frame" | "hardcode-risk" | "text-truncation-unhandled" | "image-no-placeholder" | "prototype-link-in-design" | "no-dev-status";
+/**
+ * Categories that support depthWeight
+ */
+declare const DEPTH_WEIGHT_CATEGORIES: Category[];
+/**
+ * Check if a category supports depth weighting
+ */
+declare function supportsDepthWeight(category: Category): boolean;
+
+declare const IssueSchema: z.ZodObject<{
+    nodeId: z.ZodString;
+    nodePath: z.ZodString;
+    figmaDeepLink: z.ZodString;
+    ruleId: z.ZodString;
+    message: z.ZodString;
+    severity: z.ZodEnum<{
+        blocking: "blocking";
+        risk: "risk";
+        "missing-info": "missing-info";
+        suggestion: "suggestion";
+    }>;
+}, z.core.$strip>;
+type Issue = z.infer<typeof IssueSchema>;
+
+declare const CategoryScoreSchema: z.ZodObject<{
+    category: z.ZodEnum<{
+        layout: "layout";
+        token: "token";
+        component: "component";
+        naming: "naming";
+        "ai-readability": "ai-readability";
+        "handoff-risk": "handoff-risk";
+    }>;
+    score: z.ZodNumber;
+    maxScore: z.ZodNumber;
+    issueCount: z.ZodObject<{
+        error: z.ZodNumber;
+        warning: z.ZodNumber;
+        info: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type CategoryScore = z.infer<typeof CategoryScoreSchema>;
+
+declare const ReportMetadataSchema: z.ZodObject<{
+    fileKey: z.ZodString;
+    fileName: z.ZodString;
+    analyzedAt: z.ZodString;
+    version: z.ZodString;
+}, z.core.$strip>;
+type ReportMetadata = z.infer<typeof ReportMetadataSchema>;
+declare const ReportSchema: z.ZodObject<{
+    metadata: z.ZodObject<{
+        fileKey: z.ZodString;
+        fileName: z.ZodString;
+        analyzedAt: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$strip>;
+    totalScore: z.ZodNumber;
+    categoryScores: z.ZodArray<z.ZodObject<{
+        category: z.ZodEnum<{
+            layout: "layout";
+            token: "token";
+            component: "component";
+            naming: "naming";
+            "ai-readability": "ai-readability";
+            "handoff-risk": "handoff-risk";
+        }>;
+        score: z.ZodNumber;
+        maxScore: z.ZodNumber;
+        issueCount: z.ZodObject<{
+            error: z.ZodNumber;
+            warning: z.ZodNumber;
+            info: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    issues: z.ZodArray<z.ZodObject<{
+        nodeId: z.ZodString;
+        nodePath: z.ZodString;
+        figmaDeepLink: z.ZodString;
+        ruleId: z.ZodString;
+        message: z.ZodString;
+        severity: z.ZodEnum<{
+            blocking: "blocking";
+            risk: "risk";
+            "missing-info": "missing-info";
+            suggestion: "suggestion";
+        }>;
+    }, z.core.$strip>>;
+    summary: z.ZodObject<{
+        totalNodes: z.ZodNumber;
+        analyzedNodes: z.ZodNumber;
+        errorCount: z.ZodNumber;
+        warningCount: z.ZodNumber;
+        infoCount: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type Report = z.infer<typeof ReportSchema>;
+
+/**
+ * Analysis issue with calculated score and metadata
+ */
+interface AnalysisIssue {
+    violation: RuleViolation;
+    rule: Rule;
+    config: RuleConfig;
+    depth: number;
+    maxDepth: number;
+    calculatedScore: number;
+}
+/**
+ * Analysis result from the rule engine
+ */
+interface AnalysisResult {
+    file: AnalysisFile;
+    issues: AnalysisIssue[];
+    maxDepth: number;
+    nodeCount: number;
+    analyzedAt: string;
+}
+/**
+ * Options for the rule engine
+ */
+interface RuleEngineOptions {
+    configs?: Record<RuleId, RuleConfig>;
+    enabledRules?: RuleId[];
+    disabledRules?: RuleId[];
+    targetNodeId?: string;
+}
+/**
+ * Rule engine for analyzing Figma files
+ */
+declare class RuleEngine {
+    private configs;
+    private enabledRuleIds;
+    private disabledRuleIds;
+    private targetNodeId;
+    constructor(options?: RuleEngineOptions);
+    /**
+     * Analyze a Figma file and return issues
+     */
+    analyze(file: AnalysisFile): AnalysisResult;
+    /**
+     * Get rules that should be run based on configuration
+     */
+    private getEnabledRules;
+    /**
+     * Recursively traverse the tree and run rules
+     */
+    private traverseAndCheck;
+}
+/**
+ * Create a rule engine with default configuration
+ */
+declare function createRuleEngine(options?: RuleEngineOptions): RuleEngine;
+/**
+ * Convenience function to analyze a file with default settings
+ */
+declare function analyzeFile(file: AnalysisFile, options?: RuleEngineOptions): AnalysisResult;
+
+/**
+ * Score breakdown for a single category
+ */
+interface CategoryScoreResult {
+    category: Category;
+    score: number;
+    maxScore: number;
+    percentage: number;
+    issueCount: number;
+    uniqueRuleCount: number;
+    weightedIssueCount: number;
+    densityScore: number;
+    diversityScore: number;
+    bySeverity: Record<Severity, number>;
+}
+/**
+ * Overall score report
+ */
+interface ScoreReport {
+    overall: {
+        score: number;
+        maxScore: number;
+        percentage: number;
+        grade: Grade;
+    };
+    byCategory: Record<Category, CategoryScoreResult>;
+    summary: {
+        totalIssues: number;
+        blocking: number;
+        risk: number;
+        missingInfo: number;
+        suggestion: number;
+        nodeCount: number;
+    };
+}
+/**
+ * Grade levels based on percentage
+ */
+type Grade = "S" | "A+" | "A" | "B+" | "B" | "C+" | "C" | "D" | "F";
+/**
+ * Convert grade to a CSS-safe class name suffix
+ * e.g. "A+" -> "Aplus", "B+" -> "Bplus", "C+" -> "Cplus"
+ */
+declare function gradeToClassName(grade: Grade): string;
+/**
+ * Calculate scores from analysis result using density + diversity scoring
+ *
+ * Density Score = 100 - (weighted issue count / node count) * 100
+ * Diversity Score = (1 - unique rules / total category rules) * 100
+ * Final Score = density * 0.7 + diversity * 0.3
+ */
+declare function calculateScores(result: AnalysisResult): ScoreReport;
+/**
+ * Format score report as a summary string
+ */
+declare function formatScoreSummary(report: ScoreReport): string;
+/**
+ * Get category label for display
+ */
+declare function getCategoryLabel(category: Category): string;
+/**
+ * Get severity label for display
+ */
+declare function getSeverityLabel(severity: Severity): string;
+
+/**
+ * Registry for all rules
+ */
+declare class RuleRegistry {
+    private rules;
+    /**
+     * Register a rule
+     */
+    register(rule: Rule): void;
+    /**
+     * Get a rule by ID
+     */
+    get(id: RuleId): Rule | undefined;
+    /**
+     * Get all registered rules
+     */
+    getAll(): Rule[];
+    /**
+     * Get rules by category
+     */
+    getByCategory(category: Category): Rule[];
+    /**
+     * Get enabled rules with their configs
+     */
+    getEnabled(configs?: Record<RuleId, RuleConfig>): Rule[];
+    /**
+     * Get config for a rule
+     */
+    getConfig(id: RuleId, configs?: Record<RuleId, RuleConfig>): RuleConfig;
+    /**
+     * Check if a rule is registered
+     */
+    has(id: RuleId): boolean;
+    /**
+     * Get count of registered rules
+     */
+    get size(): number;
+}
+/**
+ * Global rule registry instance
+ */
+declare const ruleRegistry: RuleRegistry;
+/**
+ * Helper to create and register a rule
+ */
+declare function defineRule(rule: Rule): Rule;
+
+/**
+ * Central configuration for all rules
+ * Edit scores/severity here without touching rule logic
+ */
+declare const RULE_CONFIGS: Record<RuleId, RuleConfig>;
+/**
+ * Preset types for different analysis modes
+ */
+type Preset = "relaxed" | "dev-friendly" | "ai-ready" | "strict";
+/**
+ * Get rule configs with preset applied
+ */
+declare function getConfigsWithPreset(preset: Preset): Record<RuleId, RuleConfig>;
+/**
+ * Get option value for a rule with type safety
+ */
+declare function getRuleOption<T>(ruleId: RuleId, optionKey: string, defaultValue: T): T;
+
+declare const noAutoLayout: Rule;
+declare const absolutePositionInAutoLayout: Rule;
+declare const fixedWidthInResponsiveContext: Rule;
+declare const missingResponsiveBehavior: Rule;
+declare const groupUsage: Rule;
+declare const fixedSizeInAutoLayout: Rule;
+declare const missingMinWidth: Rule;
+declare const missingMaxWidth: Rule;
+declare const deepNesting: Rule;
+declare const overflowHiddenAbuse: Rule;
+declare const inconsistentSiblingLayoutDirection: Rule;
+
+declare const rawColor: Rule;
+declare const rawFont: Rule;
+declare const inconsistentSpacing: Rule;
+declare const magicNumberSpacing: Rule;
+declare const rawShadow: Rule;
+declare const rawOpacity: Rule;
+declare const multipleFillColors: Rule;
+
+declare const missingComponent: Rule;
+declare const detachedInstance: Rule;
+declare const nestedInstanceOverride: Rule;
+declare const variantNotUsed: Rule;
+declare const componentPropertyUnused: Rule;
+declare const singleUseComponent: Rule;
+
+declare const defaultName: Rule;
+declare const nonSemanticName: Rule;
+declare const inconsistentNamingConvention: Rule;
+declare const numericSuffixName: Rule;
+declare const tooLongName: Rule;
+
+declare const ambiguousStructure: Rule;
+declare const zIndexDependentLayout: Rule;
+declare const missingLayoutHint: Rule;
+declare const invisibleLayer: Rule;
+declare const emptyFrame: Rule;
+
+declare const hardcodeRisk: Rule;
+declare const textTruncationUnhandled: Rule;
+declare const imageNoPlaceholder: Rule;
+declare const prototypeLinkInDesign: Rule;
+declare const noDevStatus: Rule;
+
+declare const FigmaUrlInfoSchema: z.ZodObject<{
+    fileKey: z.ZodString;
+    nodeId: z.ZodOptional<z.ZodString>;
+    fileName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type FigmaUrlInfo = z.infer<typeof FigmaUrlInfoSchema>;
+declare function parseFigmaUrl(url: string): FigmaUrlInfo;
+declare class FigmaUrlParseError extends Error {
+    constructor(message: string);
+}
+declare function buildFigmaDeepLink(fileKey: string, nodeId: string): string;
+
+interface FigmaClientOptions {
+    token: string;
+}
+declare class FigmaClient {
+    private token;
+    constructor(options: FigmaClientOptions);
+    static fromEnv(): FigmaClient;
+    getFile(fileKey: string): Promise<GetFileResponse>;
+    /**
+     * Get rendered images for specific nodes
+     * Returns a map of nodeId → image URL
+     */
+    getNodeImages(fileKey: string, nodeIds: string[], options?: {
+        format?: "png" | "svg" | "jpg";
+        scale?: number;
+    }): Promise<Record<string, string | null>>;
+    /**
+     * Download an image URL and return as base64
+     */
+    fetchImageAsBase64(imageUrl: string): Promise<string>;
+    getFileNodes(fileKey: string, nodeIds: string[]): Promise<GetFileResponse>;
+}
+declare class FigmaClientError extends Error {
+    statusCode?: number | undefined;
+    responseBody?: unknown | undefined;
+    constructor(message: string, statusCode?: number | undefined, responseBody?: unknown | undefined);
+}
+
+/**
+ * Transform Figma API response to analysis types
+ */
+declare function transformFigmaResponse(fileKey: string, response: GetFileResponse): AnalysisFile;
+
+/**
+ * Load Figma data from a JSON file
+ * For MVP testing and fixture support
+ */
+declare function loadFigmaFileFromJson(filePath: string): Promise<AnalysisFile>;
+/**
+ * Parse Figma data from a JSON string
+ */
+declare function parseFigmaJson(json: string, fileKey: string): AnalysisFile;
+declare class FigmaFileLoadError extends Error {
+    filePath?: string | undefined;
+    constructor(message: string, filePath?: string | undefined);
+}
+
+/**
+ * Parse MCP get_metadata XML output into an AnalysisFile.
+ *
+ * The XML represents a subtree of the Figma file. We wrap it in a
+ * DOCUMENT node and fill in minimal file metadata.
+ */
+declare function parseMcpMetadataXml(xml: string, fileKey: string, fileName?: string): AnalysisFile;
+
+declare const SamplingStrategySchema: z.ZodEnum<{
+    all: "all";
+    "top-issues": "top-issues";
+    random: "random";
+}>;
+type SamplingStrategy = z.infer<typeof SamplingStrategySchema>;
+declare const CalibrationStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    analyzing: "analyzing";
+    converting: "converting";
+    evaluating: "evaluating";
+    tuning: "tuning";
+    completed: "completed";
+    failed: "failed";
+}>;
+type CalibrationStatus = z.infer<typeof CalibrationStatusSchema>;
+declare const CalibrationConfigSchema: z.ZodObject<{
+    input: z.ZodString;
+    token: z.ZodOptional<z.ZodString>;
+    targetNodeId: z.ZodOptional<z.ZodString>;
+    maxConversionNodes: z.ZodDefault<z.ZodNumber>;
+    samplingStrategy: z.ZodDefault<z.ZodEnum<{
+        all: "all";
+        "top-issues": "top-issues";
+        random: "random";
+    }>>;
+    outputPath: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+type CalibrationConfig = z.infer<typeof CalibrationConfigSchema>;
+interface CalibrationRun {
+    config: CalibrationConfig;
+    status: CalibrationStatus;
+    startedAt: string;
+    completedAt?: string;
+    error?: string;
+}
+
+declare const NodeIssueSummarySchema: z.ZodObject<{
+    nodeId: z.ZodString;
+    nodePath: z.ZodString;
+    totalScore: z.ZodNumber;
+    issueCount: z.ZodNumber;
+    flaggedRuleIds: z.ZodArray<z.ZodString>;
+    severities: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+type NodeIssueSummary = z.infer<typeof NodeIssueSummarySchema>;
+interface AnalysisAgentInput {
+    analysisResult: AnalysisResult;
+}
+interface AnalysisAgentOutput {
+    analysisResult: AnalysisResult;
+    scoreReport: ScoreReport;
+    nodeIssueSummaries: NodeIssueSummary[];
+}
+interface NodeIssueDetail {
+    ruleId: RuleId;
+    severity: Severity;
+    calculatedScore: number;
+    message: string;
+}
+
+declare const DifficultySchema: z.ZodEnum<{
+    failed: "failed";
+    easy: "easy";
+    moderate: "moderate";
+    hard: "hard";
+}>;
+type Difficulty = z.infer<typeof DifficultySchema>;
+declare const RuleRelatedStruggleSchema: z.ZodObject<{
+    ruleId: z.ZodString;
+    description: z.ZodString;
+    actualImpact: z.ZodEnum<{
+        failed: "failed";
+        easy: "easy";
+        moderate: "moderate";
+        hard: "hard";
+    }>;
+}, z.core.$strip>;
+type RuleRelatedStruggle = z.infer<typeof RuleRelatedStruggleSchema>;
+declare const UncoveredStruggleSchema: z.ZodObject<{
+    description: z.ZodString;
+    suggestedCategory: z.ZodString;
+    estimatedImpact: z.ZodEnum<{
+        failed: "failed";
+        easy: "easy";
+        moderate: "moderate";
+        hard: "hard";
+    }>;
+}, z.core.$strip>;
+type UncoveredStruggle = z.infer<typeof UncoveredStruggleSchema>;
+declare const ConversionRecordSchema: z.ZodObject<{
+    nodeId: z.ZodString;
+    nodePath: z.ZodString;
+    generatedCode: z.ZodString;
+    difficulty: z.ZodEnum<{
+        failed: "failed";
+        easy: "easy";
+        moderate: "moderate";
+        hard: "hard";
+    }>;
+    notes: z.ZodString;
+    ruleRelatedStruggles: z.ZodArray<z.ZodObject<{
+        ruleId: z.ZodString;
+        description: z.ZodString;
+        actualImpact: z.ZodEnum<{
+            failed: "failed";
+            easy: "easy";
+            moderate: "moderate";
+            hard: "hard";
+        }>;
+    }, z.core.$strip>>;
+    uncoveredStruggles: z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+        suggestedCategory: z.ZodString;
+        estimatedImpact: z.ZodEnum<{
+            failed: "failed";
+            easy: "easy";
+            moderate: "moderate";
+            hard: "hard";
+        }>;
+    }, z.core.$strip>>;
+    durationMs: z.ZodNumber;
+}, z.core.$strip>;
+type ConversionRecord = z.infer<typeof ConversionRecordSchema>;
+interface ConversionExecutorResult {
+    generatedCode: string;
+    difficulty: Difficulty;
+    notes: string;
+    ruleRelatedStruggles: RuleRelatedStruggle[];
+    uncoveredStruggles: UncoveredStruggle[];
+}
+type ConversionExecutor = (nodeId: string, fileKey: string, flaggedRuleIds: string[]) => Promise<ConversionExecutorResult>;
+interface ConversionAgentInput {
+    fileKey: string;
+    nodes: Array<{
+        nodeId: string;
+        nodePath: string;
+        flaggedRuleIds: string[];
+    }>;
+}
+interface ConversionAgentOutput {
+    records: ConversionRecord[];
+    skippedNodeIds: string[];
+}
+
+declare const MismatchTypeSchema: z.ZodEnum<{
+    overscored: "overscored";
+    underscored: "underscored";
+    "missing-rule": "missing-rule";
+    validated: "validated";
+}>;
+type MismatchType = z.infer<typeof MismatchTypeSchema>;
+declare const MismatchCaseSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        overscored: "overscored";
+        underscored: "underscored";
+        "missing-rule": "missing-rule";
+        validated: "validated";
+    }>;
+    nodeId: z.ZodString;
+    nodePath: z.ZodString;
+    ruleId: z.ZodOptional<z.ZodString>;
+    currentScore: z.ZodOptional<z.ZodNumber>;
+    currentSeverity: z.ZodOptional<z.ZodEnum<{
+        blocking: "blocking";
+        risk: "risk";
+        "missing-info": "missing-info";
+        suggestion: "suggestion";
+    }>>;
+    actualDifficulty: z.ZodEnum<{
+        failed: "failed";
+        easy: "easy";
+        moderate: "moderate";
+        hard: "hard";
+    }>;
+    reasoning: z.ZodString;
+}, z.core.$strip>;
+type MismatchCase = z.infer<typeof MismatchCaseSchema>;
+interface EvaluationAgentInput {
+    nodeIssueSummaries: Array<{
+        nodeId: string;
+        nodePath: string;
+        flaggedRuleIds: string[];
+    }>;
+    conversionRecords: Array<{
+        nodeId: string;
+        nodePath: string;
+        difficulty: string;
+        ruleRelatedStruggles: Array<{
+            ruleId: string;
+            description: string;
+            actualImpact: string;
+        }>;
+        uncoveredStruggles: Array<{
+            description: string;
+            suggestedCategory: string;
+            estimatedImpact: string;
+        }>;
+    }>;
+    ruleScores: Record<string, {
+        score: number;
+        severity: string;
+    }>;
+}
+interface EvaluationAgentOutput {
+    mismatches: MismatchCase[];
+    validatedRules: string[];
+}
+
+declare const ConfidenceSchema: z.ZodEnum<{
+    high: "high";
+    medium: "medium";
+    low: "low";
+}>;
+type Confidence = z.infer<typeof ConfidenceSchema>;
+declare const ScoreAdjustmentSchema: z.ZodObject<{
+    ruleId: z.ZodString;
+    currentScore: z.ZodNumber;
+    proposedScore: z.ZodNumber;
+    currentSeverity: z.ZodEnum<{
+        blocking: "blocking";
+        risk: "risk";
+        "missing-info": "missing-info";
+        suggestion: "suggestion";
+    }>;
+    proposedSeverity: z.ZodOptional<z.ZodEnum<{
+        blocking: "blocking";
+        risk: "risk";
+        "missing-info": "missing-info";
+        suggestion: "suggestion";
+    }>>;
+    reasoning: z.ZodString;
+    confidence: z.ZodEnum<{
+        high: "high";
+        medium: "medium";
+        low: "low";
+    }>;
+    supportingCases: z.ZodNumber;
+}, z.core.$strip>;
+type ScoreAdjustment = z.infer<typeof ScoreAdjustmentSchema>;
+declare const NewRuleProposalSchema: z.ZodObject<{
+    suggestedId: z.ZodString;
+    category: z.ZodString;
+    description: z.ZodString;
+    suggestedSeverity: z.ZodEnum<{
+        blocking: "blocking";
+        risk: "risk";
+        "missing-info": "missing-info";
+        suggestion: "suggestion";
+    }>;
+    suggestedScore: z.ZodNumber;
+    reasoning: z.ZodString;
+    supportingCases: z.ZodNumber;
+}, z.core.$strip>;
+type NewRuleProposal = z.infer<typeof NewRuleProposalSchema>;
+interface TuningAgentInput {
+    mismatches: Array<{
+        type: string;
+        nodeId: string;
+        nodePath: string;
+        ruleId?: string | undefined;
+        currentScore?: number | undefined;
+        currentSeverity?: string | undefined;
+        actualDifficulty: string;
+        reasoning: string;
+    }>;
+    ruleScores: Record<string, {
+        score: number;
+        severity: string;
+    }>;
+}
+interface TuningAgentOutput {
+    adjustments: ScoreAdjustment[];
+    newRuleProposals: NewRuleProposal[];
+}
+
+/**
+ * Extract rule scores map from analysis result for downstream agents
+ */
+declare function extractRuleScores(result: AnalysisResult): Record<string, {
+    score: number;
+    severity: string;
+}>;
+/**
+ * Analysis Agent - Step 1 of calibration pipeline
+ *
+ * Wraps existing analyzeFile + calculateScores and adds
+ * nodeId-grouped issue summaries for downstream agents.
+ */
+declare function runAnalysisAgent(input: AnalysisAgentInput): AnalysisAgentOutput;
+
+/**
+ * Conversion Agent - Step 2 of calibration pipeline
+ *
+ * Attempts code conversion for each node via an injected executor.
+ * Uses dependency inversion: the executor handles actual LLM/MCP calls.
+ * Failures on individual nodes are captured, not thrown.
+ */
+declare function runConversionAgent(input: ConversionAgentInput, executor: ConversionExecutor): Promise<ConversionAgentOutput>;
+
+/**
+ * Prompt template for the conversion executor.
+ *
+ * The executor (typically an LLM session with Figma MCP access) receives
+ * this prompt to guide code generation and difficulty assessment.
+ */
+declare function buildConversionPrompt(nodeId: string, fileKey: string, flaggedRuleIds: string[]): string;
+
+/**
+ * Evaluation Agent - Step 3 of calibration pipeline
+ *
+ * Deterministic comparison of analysis results vs conversion results.
+ * No LLM required — pure algorithmic evaluation.
+ */
+declare function runEvaluationAgent(input: EvaluationAgentInput): EvaluationAgentOutput;
+
+/**
+ * Tuning Agent - Step 4 of calibration pipeline
+ *
+ * Deterministic aggregation algorithm. No LLM required.
+ * Aggregates mismatch cases into score adjustment proposals.
+ */
+declare function runTuningAgent(input: TuningAgentInput): TuningAgentOutput;
+
+interface CalibrationReportData {
+    fileKey: string;
+    fileName: string;
+    analyzedAt: string;
+    nodeCount: number;
+    issueCount: number;
+    convertedNodeCount: number;
+    skippedNodeCount: number;
+    scoreReport: ScoreReport;
+    mismatches: MismatchCase[];
+    validatedRules: string[];
+    adjustments: ScoreAdjustment[];
+    newRuleProposals: NewRuleProposal[];
+}
+/**
+ * Generate a CALIBRATION_REPORT.md from calibration pipeline results
+ */
+declare function generateCalibrationReport(data: CalibrationReportData): string;
+
+interface CalibrationRunOptions {
+    enableActivityLog?: boolean;
+}
+interface CalibrationRunResult {
+    status: CalibrationStatus;
+    scoreReport: ScoreReport;
+    nodeIssueSummaries: NodeIssueSummary[];
+    mismatches: MismatchCase[];
+    validatedRules: string[];
+    adjustments: ScoreAdjustment[];
+    newRuleProposals: NewRuleProposal[];
+    reportPath: string;
+    logPath?: string | undefined;
+    error?: string;
+}
+/**
+ * Run Step 1 only: analysis + save JSON output
+ */
+declare function runCalibrationAnalyze(config: CalibrationConfig): Promise<{
+    analysisOutput: ReturnType<typeof runAnalysisAgent> extends infer T ? T : never;
+    ruleScores: Record<string, {
+        score: number;
+        severity: string;
+    }>;
+    fileKey: string;
+}>;
+/**
+ * Run Steps 3+4: evaluation + tuning from pre-computed analysis and conversion data
+ */
+declare function runCalibrationEvaluate(analysisJson: {
+    nodeIssueSummaries: NodeIssueSummary[];
+    scoreReport: ScoreReport;
+    fileKey: string;
+    fileName: string;
+    analyzedAt: string;
+    nodeCount: number;
+    issueCount: number;
+}, conversionJson: {
+    records: Array<{
+        nodeId: string;
+        nodePath: string;
+        difficulty: string;
+        ruleRelatedStruggles: Array<{
+            ruleId: string;
+            description: string;
+            actualImpact: string;
+        }>;
+        uncoveredStruggles: Array<{
+            description: string;
+            suggestedCategory: string;
+            estimatedImpact: string;
+        }>;
+    }>;
+    skippedNodeIds: string[];
+}, ruleScores: Record<string, {
+    score: number;
+    severity: string;
+}>): {
+    evaluationOutput: EvaluationAgentOutput;
+    tuningOutput: TuningAgentOutput;
+    report: string;
+};
+/**
+ * Run the full calibration pipeline
+ *
+ * Sequence: validate -> load file -> analysis -> node selection -> conversion -> evaluation -> tuning -> report
+ */
+declare function runCalibration(config: CalibrationConfig, executor: ConversionExecutor, options?: CalibrationRunOptions): Promise<CalibrationRunResult>;
+
+interface ActivityStep {
+    step: string;
+    nodePath?: string;
+    result: string;
+    durationMs: number;
+}
+declare class ActivityLogger {
+    private logPath;
+    private initialized;
+    constructor(fixturePath?: string, logDir?: string);
+    /**
+     * Ensure the log directory and file header exist
+     */
+    private ensureInitialized;
+    /**
+     * Log a pipeline step
+     */
+    logStep(activity: ActivityStep): Promise<void>;
+    /**
+     * Log a summary at pipeline completion
+     */
+    logSummary(summary: {
+        totalDurationMs: number;
+        nodesAnalyzed: number;
+        nodesConverted: number;
+        mismatches: number;
+        adjustments: number;
+        status: string;
+    }): Promise<void>;
+    getLogPath(): string;
+}
+
+declare const VERSION = "0.1.0";
+
+export { ActivityLogger, type AnalysisAgentInput, type AnalysisAgentOutput, type AnalysisFile, AnalysisFileSchema, type AnalysisIssue, type AnalysisNode, AnalysisNodeSchema, type AnalysisNodeType, AnalysisNodeTypeSchema, type AnalysisResult, CATEGORIES, CATEGORY_LABELS, type CalibrationConfig, CalibrationConfigSchema, type CalibrationRun, type CalibrationStatus, CalibrationStatusSchema, type Category, CategorySchema, type CategoryScore, type CategoryScoreResult, CategoryScoreSchema, type Confidence, ConfidenceSchema, type ConversionAgentInput, type ConversionAgentOutput, type ConversionExecutor, type ConversionExecutorResult, type ConversionRecord, ConversionRecordSchema, DEPTH_WEIGHT_CATEGORIES, type Difficulty, DifficultySchema, type EvaluationAgentInput, type EvaluationAgentOutput, FigmaClient, FigmaClientError, type FigmaClientOptions, FigmaFileLoadError, type FigmaUrlInfo, FigmaUrlInfoSchema, FigmaUrlParseError, type Grade, type Issue, IssueSchema, type LayoutAlign, LayoutAlignSchema, type LayoutMode, LayoutModeSchema, type LayoutPositioning, LayoutPositioningSchema, type MismatchCase, MismatchCaseSchema, type MismatchType, MismatchTypeSchema, type NewRuleProposal, NewRuleProposalSchema, type NodeIssueDetail, type NodeIssueSummary, NodeIssueSummarySchema, type Preset, RULE_CONFIGS, type Report, type ReportMetadata, ReportMetadataSchema, ReportSchema, type Rule, type RuleCheckFn, type RuleConfig, RuleConfigSchema, type RuleContext, type RuleDefinition, RuleDefinitionSchema, RuleEngine, type RuleEngineOptions, type RuleId, type RuleRelatedStruggle, RuleRelatedStruggleSchema, type RuleViolation, SEVERITY_LABELS, SEVERITY_WEIGHT, type SamplingStrategy, SamplingStrategySchema, type ScoreAdjustment, ScoreAdjustmentSchema, type ScoreReport, type Severity, SeveritySchema, type TuningAgentInput, type TuningAgentOutput, type UncoveredStruggle, UncoveredStruggleSchema, VERSION, absolutePositionInAutoLayout, ambiguousStructure, analyzeFile, buildConversionPrompt, buildFigmaDeepLink, calculateScores, componentPropertyUnused, createRuleEngine, deepNesting, defaultName, defineRule, detachedInstance, emptyFrame, extractRuleScores, fixedSizeInAutoLayout, fixedWidthInResponsiveContext, formatScoreSummary, generateCalibrationReport, getCategoryLabel, getConfigsWithPreset, getRuleOption, getSeverityLabel, gradeToClassName, groupUsage, hardcodeRisk, imageNoPlaceholder, inconsistentNamingConvention, inconsistentSiblingLayoutDirection, inconsistentSpacing, invisibleLayer, loadFigmaFileFromJson, magicNumberSpacing, missingComponent, missingLayoutHint, missingMaxWidth, missingMinWidth, missingResponsiveBehavior, multipleFillColors, nestedInstanceOverride, noAutoLayout, noDevStatus, nonSemanticName, numericSuffixName, overflowHiddenAbuse, parseFigmaJson, parseFigmaUrl, parseMcpMetadataXml, prototypeLinkInDesign, rawColor, rawFont, rawOpacity, rawShadow, ruleRegistry, runAnalysisAgent, runCalibration, runCalibrationAnalyze, runCalibrationEvaluate, runConversionAgent, runEvaluationAgent, runTuningAgent, singleUseComponent, supportsDepthWeight, textTruncationUnhandled, tooLongName, transformFigmaResponse, variantNotUsed, zIndexDependentLayout };