canicode 0.8.2 → 0.8.5

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
-import { GetFileResponse } from '@figma/rest-api-spec';
+import { GetFileResponse, Node } from '@figma/rest-api-spec';
 
-var version = "0.8.2";
+var version = "0.8.5";
 
 declare const SeveritySchema: z.ZodEnum<{
     blocking: "blocking";
@@ -265,7 +265,7 @@ interface Rule {
 /**
  * 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";
+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" | "missing-component-description" | "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
  */
@@ -590,6 +590,13 @@ declare const nestedInstanceOverride: Rule;
 declare const variantNotUsed: Rule;
 declare const componentPropertyUnused: Rule;
 declare const singleUseComponent: Rule;
+declare const missingComponentDescription: Rule;
+/**
+ * Reset deduplication state between analysis runs.
+ * Call this at the start of each analysis if the process is long-running
+ * (e.g. MCP server mode).
+ */
+declare function resetMissingComponentDescriptionState(): void;
 
 declare const defaultName: Rule;
 declare const nonSemanticName: Rule;
@@ -621,6 +628,16 @@ declare class FigmaUrlParseError extends Error {
 }
 declare function buildFigmaDeepLink(fileKey: string, nodeId: string): string;
 
+interface GetFileNodesResponse {
+    name: string;
+    lastModified: string;
+    version: string;
+    nodes: Record<string, {
+        document: Node;
+        components: GetFileResponse["components"];
+        styles: GetFileResponse["styles"];
+    }>;
+}
 interface FigmaClientOptions {
     token: string;
 }
@@ -641,7 +658,7 @@ declare class FigmaClient {
      * Download an image URL and return as base64
      */
     fetchImageAsBase64(imageUrl: string): Promise<string>;
-    getFileNodes(fileKey: string, nodeIds: string[]): Promise<GetFileResponse>;
+    getFileNodes(fileKey: string, nodeIds: string[]): Promise<GetFileNodesResponse>;
 }
 declare class FigmaClientError extends Error {
     statusCode?: number | undefined;
@@ -653,6 +670,11 @@ declare class FigmaClientError extends Error {
  * Transform Figma API response to analysis types
  */
 declare function transformFigmaResponse(fileKey: string, response: GetFileResponse): AnalysisFile;
+/**
+ * Transform Figma /v1/files/{key}/nodes response to analysis types.
+ * Returns the first node's subtree as the document.
+ */
+declare function transformFileNodesResponse(fileKey: string, response: GetFileNodesResponse): AnalysisFile;
 
 /**
  * Load Figma data from a JSON file
@@ -1133,4 +1155,4 @@ declare class ActivityLogger {
     getLogPath(): string;
 }
 
-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 as VERSION, absolutePositionInAutoLayout, ambiguousStructure, analyzeFile, buildConversionPrompt, buildFigmaDeepLink, buildResultJson, calculateScores, componentPropertyUnused, createRuleEngine, deepNesting, defaultName, defineRule, detachedInstance, emptyFrame, enrichWithDesignContext, 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 };
+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 GetFileNodesResponse, 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 as VERSION, absolutePositionInAutoLayout, ambiguousStructure, analyzeFile, buildConversionPrompt, buildFigmaDeepLink, buildResultJson, calculateScores, componentPropertyUnused, createRuleEngine, deepNesting, defaultName, defineRule, detachedInstance, emptyFrame, enrichWithDesignContext, extractRuleScores, fixedSizeInAutoLayout, fixedWidthInResponsiveContext, formatScoreSummary, generateCalibrationReport, getCategoryLabel, getConfigsWithPreset, getRuleOption, getSeverityLabel, gradeToClassName, groupUsage, hardcodeRisk, imageNoPlaceholder, inconsistentNamingConvention, inconsistentSiblingLayoutDirection, inconsistentSpacing, invisibleLayer, loadFigmaFileFromJson, magicNumberSpacing, missingComponent, missingComponentDescription, missingLayoutHint, missingMaxWidth, missingMinWidth, missingResponsiveBehavior, multipleFillColors, nestedInstanceOverride, noAutoLayout, noDevStatus, nonSemanticName, numericSuffixName, overflowHiddenAbuse, parseFigmaJson, parseFigmaUrl, parseMcpMetadataXml, prototypeLinkInDesign, rawColor, rawFont, rawOpacity, rawShadow, resetMissingComponentDescriptionState, ruleRegistry, runAnalysisAgent, runCalibration, runCalibrationAnalyze, runCalibrationEvaluate, runConversionAgent, runEvaluationAgent, runTuningAgent, singleUseComponent, supportsDepthWeight, textTruncationUnhandled, tooLongName, transformFigmaResponse, transformFileNodesResponse, variantNotUsed, zIndexDependentLayout };

package/dist/index.js

@@ -4,7 +4,7 @@ import { basename, resolve, dirname } from 'path';
 import { existsSync, mkdirSync } from 'fs';
 
 // package.json
-var version = "0.8.2";
+var version = "0.8.5";
 var SeveritySchema = z.enum([
   "blocking",
   "risk",
@@ -317,7 +317,7 @@ var RULE_CONFIGS = {
     }
   },
   // ============================================
-  // Component (6 rules)
+  // Component (7 rules)
   // ============================================
   "missing-component": {
     severity: "risk",
@@ -352,6 +352,11 @@ var RULE_CONFIGS = {
     score: -1,
     enabled: true
   },
+  "missing-component-description": {
+    severity: "missing-info",
+    score: -2,
+    enabled: true
+  },
   // ============================================
   // Naming (5 rules)
   // ============================================
@@ -1606,6 +1611,38 @@ var singleUseComponent = defineRule({
   definition: singleUseComponentDef,
   check: singleUseComponentCheck
 });
+var seenMissingDescriptionComponentIds = /* @__PURE__ */ new Set();
+var missingComponentDescriptionDef = {
+  id: "missing-component-description",
+  name: "Missing Component Description",
+  category: "component",
+  why: "Component descriptions in Figma are the primary channel for communicating intent, usage guidelines, and prop expectations to developers. Without them, developers must reverse-engineer purpose from visual appearance alone.",
+  impact: "Increases implementation ambiguity, especially for icon-only components, compound components with multiple variants, and components whose names are variant key strings that give no prose context.",
+  fix: "Open the component in Figma, select it, and add a description in the right-hand panel under the component's properties. Include: what the component is, when to use it, any accessibility or interaction notes, and the owning team or design token set if applicable."
+};
+var missingComponentDescriptionCheck = (node, context) => {
+  if (node.type !== "INSTANCE") return null;
+  const componentId = node.componentId;
+  if (!componentId) return null;
+  const componentMeta = context.file.components[componentId];
+  if (!componentMeta) return null;
+  if (componentMeta.description.trim() !== "") return null;
+  if (seenMissingDescriptionComponentIds.has(componentId)) return null;
+  seenMissingDescriptionComponentIds.add(componentId);
+  return {
+    ruleId: missingComponentDescriptionDef.id,
+    nodeId: node.id,
+    nodePath: context.path.join(" > "),
+    message: `Component "${componentMeta.name}" has no description. Descriptions help developers understand purpose and usage.`
+  };
+};
+var missingComponentDescription = defineRule({
+  definition: missingComponentDescriptionDef,
+  check: missingComponentDescriptionCheck
+});
+function resetMissingComponentDescriptionState() {
+  seenMissingDescriptionComponentIds.clear();
+}
 
 // src/core/rules/naming/index.ts
 var DEFAULT_NAME_PATTERNS = [
@@ -2353,6 +2390,20 @@ function transformNode(node) {
   }
   return base;
 }
+function transformFileNodesResponse(fileKey, response) {
+  const entries = Object.values(response.nodes);
+  const first = entries[0];
+  if (!first) throw new Error("No nodes returned from Figma API");
+  return {
+    fileKey,
+    name: response.name,
+    lastModified: response.lastModified,
+    version: response.version,
+    document: transformNode(first.document),
+    components: transformComponents(first.components),
+    styles: transformStyles(first.styles)
+  };
+}
 function transformComponents(components) {
   const result = {};
   for (const [id, component] of Object.entries(components)) {
@@ -3567,13 +3618,19 @@ function hasTextDescendant(node) {
 }
 var MIN_WIDTH = 200;
 var MIN_HEIGHT = 200;
+var FILTER_THRESHOLD = 500;
 var ELIGIBLE_NODE_TYPES = /* @__PURE__ */ new Set([
   "FRAME",
   "COMPONENT",
   "INSTANCE"
 ]);
 function filterConversionCandidates(summaries, documentRoot) {
-  return summaries.filter((summary) => {
+  const visibleSummaries = summaries.filter((summary) => {
+    const node = findNode(documentRoot, summary.nodeId);
+    return node ? node.visible !== false : false;
+  });
+  if (visibleSummaries.length <= FILTER_THRESHOLD) return visibleSummaries;
+  return visibleSummaries.filter((summary) => {
     const node = findNode(documentRoot, summary.nodeId);
     if (!node) return false;
     if (EXCLUDED_NODE_TYPES.has(node.type)) return false;
@@ -3809,6 +3866,6 @@ async function runCalibration(config, executor, options) {
   }
 }
 
-export { ActivityLogger, AnalysisFileSchema, AnalysisNodeSchema, AnalysisNodeTypeSchema, CATEGORIES, CATEGORY_LABELS, CalibrationConfigSchema, CalibrationStatusSchema, CategorySchema, CategoryScoreSchema, ConfidenceSchema, ConversionRecordSchema, DEPTH_WEIGHT_CATEGORIES, DifficultySchema, FigmaClient, FigmaClientError, FigmaFileLoadError, FigmaUrlInfoSchema, FigmaUrlParseError, IssueSchema, LayoutAlignSchema, LayoutModeSchema, LayoutPositioningSchema, MismatchCaseSchema, MismatchTypeSchema, NewRuleProposalSchema, NodeIssueSummarySchema, RULE_CONFIGS, ReportMetadataSchema, ReportSchema, RuleConfigSchema, RuleDefinitionSchema, RuleEngine, RuleRelatedStruggleSchema, SEVERITY_LABELS, SEVERITY_WEIGHT, SamplingStrategySchema, ScoreAdjustmentSchema, SeveritySchema, UncoveredStruggleSchema, version as VERSION, absolutePositionInAutoLayout, ambiguousStructure, analyzeFile, buildConversionPrompt, buildFigmaDeepLink, buildResultJson, calculateScores, componentPropertyUnused, createRuleEngine, deepNesting, defaultName, defineRule, detachedInstance, emptyFrame, enrichWithDesignContext, 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 };
+export { ActivityLogger, AnalysisFileSchema, AnalysisNodeSchema, AnalysisNodeTypeSchema, CATEGORIES, CATEGORY_LABELS, CalibrationConfigSchema, CalibrationStatusSchema, CategorySchema, CategoryScoreSchema, ConfidenceSchema, ConversionRecordSchema, DEPTH_WEIGHT_CATEGORIES, DifficultySchema, FigmaClient, FigmaClientError, FigmaFileLoadError, FigmaUrlInfoSchema, FigmaUrlParseError, IssueSchema, LayoutAlignSchema, LayoutModeSchema, LayoutPositioningSchema, MismatchCaseSchema, MismatchTypeSchema, NewRuleProposalSchema, NodeIssueSummarySchema, RULE_CONFIGS, ReportMetadataSchema, ReportSchema, RuleConfigSchema, RuleDefinitionSchema, RuleEngine, RuleRelatedStruggleSchema, SEVERITY_LABELS, SEVERITY_WEIGHT, SamplingStrategySchema, ScoreAdjustmentSchema, SeveritySchema, UncoveredStruggleSchema, version as VERSION, absolutePositionInAutoLayout, ambiguousStructure, analyzeFile, buildConversionPrompt, buildFigmaDeepLink, buildResultJson, calculateScores, componentPropertyUnused, createRuleEngine, deepNesting, defaultName, defineRule, detachedInstance, emptyFrame, enrichWithDesignContext, extractRuleScores, fixedSizeInAutoLayout, fixedWidthInResponsiveContext, formatScoreSummary, generateCalibrationReport, getCategoryLabel, getConfigsWithPreset, getRuleOption, getSeverityLabel, gradeToClassName, groupUsage, hardcodeRisk, imageNoPlaceholder, inconsistentNamingConvention, inconsistentSiblingLayoutDirection, inconsistentSpacing, invisibleLayer, loadFigmaFileFromJson, magicNumberSpacing, missingComponent, missingComponentDescription, missingLayoutHint, missingMaxWidth, missingMinWidth, missingResponsiveBehavior, multipleFillColors, nestedInstanceOverride, noAutoLayout, noDevStatus, nonSemanticName, numericSuffixName, overflowHiddenAbuse, parseFigmaJson, parseFigmaUrl, parseMcpMetadataXml, prototypeLinkInDesign, rawColor, rawFont, rawOpacity, rawShadow, resetMissingComponentDescriptionState, ruleRegistry, runAnalysisAgent, runCalibration, runCalibrationAnalyze, runCalibrationEvaluate, runConversionAgent, runEvaluationAgent, runTuningAgent, singleUseComponent, supportsDepthWeight, textTruncationUnhandled, tooLongName, transformFigmaResponse, transformFileNodesResponse, variantNotUsed, zIndexDependentLayout };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map