semiotic 3.4.2 → 3.5.1

package/ai/chartSuggestions.cjs

@@ -0,0 +1,291 @@
+"use strict"
+
+const VALID_INTENTS = [
+  "comparison", "trend", "distribution", "relationship", "composition",
+  "geographic", "network", "hierarchy",
+]
+const MAX_SAMPLE_SIZE = 5
+
+function summarizeFields(data, keys) {
+  const numericFields = []
+  const stringFields = []
+  const dateFields = []
+  const geoFields = {}
+  const networkFields = {}
+  const hierarchyFields = {}
+
+  for (const key of keys) {
+    const values = data.map((d) => d[key]).filter((v) => v != null)
+    if (values.length === 0) continue
+
+    const first = values[0]
+    if (typeof first === "number") {
+      numericFields.push(key)
+    } else if (typeof first === "string") {
+      if (/^\d{4}[-/]\d{2}/.test(first) && !Number.isNaN(Date.parse(first))) {
+        dateFields.push(key)
+      } else {
+        stringFields.push(key)
+      }
+    }
+
+    const kl = key.toLowerCase()
+    if (kl === "lat" || kl === "latitude") geoFields.lat = key
+    if (kl === "lon" || kl === "lng" || kl === "longitude") geoFields.lon = key
+    if (kl === "source" || kl === "from") networkFields.source = key
+    if (kl === "target" || kl === "to") networkFields.target = key
+    if (kl === "value" || kl === "weight" || kl === "amount") networkFields.value = key
+    if (kl === "children" || kl === "values") hierarchyFields.children = key
+    if (kl === "parent") hierarchyFields.parent = key
+  }
+
+  return {
+    keys,
+    numericFields,
+    stringFields,
+    dateFields,
+    geoFields,
+    networkFields,
+    hierarchyFields,
+  }
+}
+
+function jsxString(value) {
+  return JSON.stringify(String(value))
+}
+
+function jsxExpression(value) {
+  return `{${value}}`
+}
+
+function uniqueNetworkNodes(data, sourceField, targetField) {
+  const ids = new Set()
+  for (const datum of data) {
+    const source = datum[sourceField]
+    const target = datum[targetField]
+    if (source != null) ids.add(source)
+    if (target != null) ids.add(target)
+  }
+  return Array.from(ids).map((id) => ({ id }))
+}
+
+function suggestCharts(args = {}) {
+  const data = args.data
+  const intent = args.intent
+
+  if (intent && !VALID_INTENTS.includes(intent)) {
+    return {
+      ok: false,
+      error: `Unknown intent "${intent}". Expected one of: ${VALID_INTENTS.join(", ")}.`,
+    }
+  }
+
+  if (!data || !Array.isArray(data) || data.length === 0) {
+    return {
+      ok: false,
+      error: "Pass { data: [{ ... }, ...] } with 1-5 sample data objects. Optionally include intent: 'comparison' | 'trend' | 'distribution' | 'relationship' | 'composition' | 'geographic' | 'network' | 'hierarchy'.",
+    }
+  }
+
+  if (data.length > MAX_SAMPLE_SIZE) {
+    return {
+      ok: false,
+      error: `Pass 1-${MAX_SAMPLE_SIZE} sample data objects; received ${data.length}. Use a representative sample instead of the full dataset.`,
+    }
+  }
+
+  const sample = data[0]
+  if (!sample || typeof sample !== "object" || Array.isArray(sample)) {
+    return {
+      ok: false,
+      error: "Data items must be objects with key-value pairs.",
+    }
+  }
+
+  const keys = Object.keys(sample)
+  const fields = summarizeFields(data, keys)
+  const suggestions = []
+
+  const { numericFields, stringFields, dateFields, geoFields, networkFields, hierarchyFields } = fields
+  const hasTime = dateFields.length > 0
+  const hasCat = stringFields.length > 0
+  const hasNum = numericFields.length > 0
+  const hasGeo = Boolean(geoFields.lat && geoFields.lon)
+  const hasNetwork = Boolean(networkFields.source && networkFields.target)
+  const hasHierarchy = Boolean(hierarchyFields.children || hierarchyFields.parent)
+
+  if (hasNetwork && (!intent || intent === "network")) {
+    const src = networkFields.source
+    const tgt = networkFields.target
+    if (networkFields.value) {
+      suggestions.push({
+        component: "SankeyDiagram",
+        confidence: "high",
+        reason: `Data has ${src}->${tgt} with ${networkFields.value} - ideal for flow visualization`,
+        props: { edges: jsxExpression("data"), sourceAccessor: jsxString(src), targetAccessor: jsxString(tgt), valueAccessor: jsxString(networkFields.value) },
+      })
+    }
+    const nodes = uniqueNetworkNodes(data, src, tgt)
+    suggestions.push({
+      component: "ForceDirectedGraph",
+      confidence: networkFields.value ? "medium" : "high",
+      reason: `Data has ${src}->${tgt} edges - force layout shows network structure. ForceDirectedGraph requires explicit nodes, derived here from unique source/target IDs.`,
+      setup: [`const nodes = ${JSON.stringify(nodes, null, 2)}`],
+      derivedData: { nodes },
+      props: { nodes: jsxExpression("nodes"), edges: jsxExpression("data"), nodeIDAccessor: jsxString("id"), sourceAccessor: jsxString(src), targetAccessor: jsxString(tgt) },
+    })
+  }
+
+  if (hasHierarchy && hierarchyFields.children && Array.isArray(sample[hierarchyFields.children]) && (!intent || intent === "hierarchy")) {
+    const childrenAccessor = hierarchyFields.children
+    suggestions.push({
+      component: "Treemap",
+      confidence: "high",
+      reason: `Data has nested ${childrenAccessor} structure - treemap shows hierarchical proportions. Use data[0] as the root node from the provided sample.`,
+      props: { data: jsxExpression("data[0]"), childrenAccessor: jsxString(childrenAccessor), ...(numericFields[0] ? { valueAccessor: jsxString(numericFields[0]) } : {}) },
+    })
+    suggestions.push({
+      component: "TreeDiagram",
+      confidence: "medium",
+      reason: `Tree layout shows hierarchical relationships. Use data[0] as the root node from the provided sample.`,
+      props: { data: jsxExpression("data[0]"), childrenAccessor: jsxString(childrenAccessor) },
+    })
+  }
+
+  if (hasGeo && (!intent || intent === "geographic")) {
+    const sizeField = numericFields.find((f) => f !== geoFields.lat && f !== geoFields.lon)
+    suggestions.push({
+      component: "ProportionalSymbolMap",
+      confidence: "high",
+      reason: `Data has ${geoFields.lat}/${geoFields.lon} coordinates - map shows spatial distribution`,
+      props: { points: jsxExpression("data"), xAccessor: jsxString(geoFields.lon), yAccessor: jsxString(geoFields.lat), ...(sizeField ? { sizeBy: jsxString(sizeField) } : {}) },
+    })
+  }
+
+  if (hasTime && hasNum && (!intent || intent === "trend")) {
+    const timeField = dateFields[0]
+    const valueField = numericFields[0]
+    suggestions.push({
+      component: "LineChart",
+      confidence: "high",
+      reason: `Data has dates (${timeField}) and numeric values (${valueField}) - line chart shows trends over time`,
+      props: { data: jsxExpression("data"), xAccessor: jsxString(timeField), yAccessor: jsxString(valueField), ...(hasCat ? { lineBy: jsxString(stringFields[0]), colorBy: jsxString(stringFields[0]) } : {}) },
+    })
+    if (hasCat) {
+      suggestions.push({
+        component: "StackedAreaChart",
+        confidence: "medium",
+        reason: `Multiple categories (${stringFields[0]}) over time - stacked area shows composition trends`,
+        props: { data: jsxExpression("data"), xAccessor: jsxString(timeField), yAccessor: jsxString(valueField), areaBy: jsxString(stringFields[0]), colorBy: jsxString(stringFields[0]) },
+      })
+    }
+  }
+
+  if (hasCat && hasNum && (!intent || intent === "comparison" || intent === "composition" || intent === "distribution")) {
+    const catField = stringFields[0]
+    const valField = numericFields[0]
+
+    if (!intent || intent === "comparison") {
+      suggestions.push({
+        component: "BarChart",
+        confidence: hasTime ? "medium" : "high",
+        reason: `Categorical field (${catField}) with values (${valField}) - bar chart for comparison`,
+        props: { data: jsxExpression("data"), categoryAccessor: jsxString(catField), valueAccessor: jsxString(valField) },
+      })
+    }
+
+    if (stringFields.length >= 2 && (!intent || intent === "composition")) {
+      suggestions.push({
+        component: "StackedBarChart",
+        confidence: "medium",
+        reason: `Two categorical fields (${stringFields.join(", ")}) - stacked bar shows composition within categories`,
+        props: { data: jsxExpression("data"), categoryAccessor: jsxString(catField), valueAccessor: jsxString(valField), stackBy: jsxString(stringFields[1]) },
+      })
+    }
+
+    if (!intent || intent === "distribution") {
+      suggestions.push({
+        component: "Histogram",
+        confidence: "medium",
+        reason: `Numeric distribution of ${valField} - histogram shows value spread`,
+        props: { data: jsxExpression("data"), categoryAccessor: jsxString(catField), valueAccessor: jsxString(valField) },
+      })
+    }
+
+    if (!intent || intent === "composition") {
+      const uniqueCats = new Set(data.map((d) => d[catField])).size
+      if (uniqueCats <= 8) {
+        suggestions.push({
+          component: "DonutChart",
+          confidence: "medium",
+          reason: `${uniqueCats} categories - donut chart shows proportional composition`,
+          props: { data: jsxExpression("data"), categoryAccessor: jsxString(catField), valueAccessor: jsxString(valField) },
+        })
+      }
+    }
+  }
+
+  if (numericFields.length >= 2 && (!intent || intent === "relationship")) {
+    const xField = numericFields[0]
+    const yField = numericFields[1]
+    suggestions.push({
+      component: "Scatterplot",
+      confidence: "high",
+      reason: `Two numeric fields (${xField}, ${yField}) - scatterplot shows relationships`,
+      props: { data: jsxExpression("data"), xAccessor: jsxString(xField), yAccessor: jsxString(yField), ...(hasCat ? { colorBy: jsxString(stringFields[0]) } : {}), ...(numericFields[2] ? { sizeBy: jsxString(numericFields[2]) } : {}) },
+    })
+
+    if (numericFields.length >= 3) {
+      suggestions.push({
+        component: "BubbleChart",
+        confidence: "medium",
+        reason: "Three numeric fields - bubble chart adds size dimension to scatter",
+        props: { data: jsxExpression("data"), xAccessor: jsxString(xField), yAccessor: jsxString(yField), sizeBy: jsxString(numericFields[2]) },
+      })
+    }
+  }
+
+  if (stringFields.length >= 2 && numericFields.length >= 1 && (!intent || intent === "relationship" || intent === "distribution" || intent === "composition")) {
+    const xField = stringFields[0]
+    const yField = stringFields[1]
+    const valueField = numericFields[0]
+    suggestions.push({
+      component: "Heatmap",
+      confidence: "medium",
+      reason: `Two categorical fields (${xField}, ${yField}) plus numeric values (${valueField}) - heatmap shows intensity across dimensions`,
+      props: { data: jsxExpression("data"), xAccessor: jsxString(xField), yAccessor: jsxString(yField), valueAccessor: jsxString(valueField) },
+    })
+  }
+
+  return {
+    ok: true,
+    intent,
+    fieldSummary: `Fields: ${keys.join(", ")} (${numericFields.length} numeric, ${stringFields.length} categorical, ${dateFields.length} date)`,
+    fields,
+    suggestions,
+  }
+}
+
+function formatSuggestionReport(result) {
+  if (!result.ok) return result.error
+
+  if (result.suggestions.length === 0) {
+    return `Could not confidently recommend a chart type.\n\n${result.fieldSummary}\n\nTry providing intent ('${VALID_INTENTS.join("', '")}') to narrow recommendations, or use getSchema to browse available components.`
+  }
+
+  const lines = result.suggestions.map((suggestion, i) => {
+    const propsStr = Object.entries(suggestion.props).map(([k, v]) => `${k}=${v}`).join(" ")
+    const setup = suggestion.setup ? `${suggestion.setup.join("\n")}\n` : ""
+    return `${i + 1}. **${suggestion.component}** (${suggestion.confidence} confidence)\n   ${suggestion.reason}\n\`\`\`tsx\n${setup}<${suggestion.component} ${propsStr} />\n\`\`\``
+  })
+
+  const themingTip = `\n---\n**Styling**: All charts respond to CSS custom properties on any ancestor element:\n\`\`\`css\n.my-theme {\n  --semiotic-bg: #fff;\n  --semiotic-text: #333;\n  --semiotic-text-secondary: #666;\n  --semiotic-grid: #e0e0e0;\n  --semiotic-border: #e0e0e0;\n  --semiotic-font-family: sans-serif;\n  --semiotic-tooltip-bg: rgba(0,0,0,0.85);\n  --semiotic-tooltip-text: white;\n  --semiotic-tooltip-radius: 6px;\n}\n\`\`\`\nOr use \`<ThemeProvider theme="dark">\` / \`<ThemeProvider theme={{ colors: {...}, typography: {...} }}>\`.\nFor accessibility, use \`colorScheme={COLOR_BLIND_SAFE_CATEGORICAL}\` (import from \`semiotic/themes\`) - 8-color palette safe for all forms of color blindness.`
+
+  return lines.join("\n\n") + themingTip
+}
+
+module.exports = {
+  VALID_INTENTS,
+  formatSuggestionReport,
+  suggestCharts,
+}

package/ai/cli.js

@@ -5,6 +5,23 @@ const fs = require("fs")
 const path = require("path")
 
 const pkgRoot = path.resolve(__dirname, "..")
+const {
+  CATEGORY_ORDER,
+  componentIndexFromSchema,
+  findComponent,
+  metadataForComponent,
+  schemaEntries,
+} = require("./componentMetadata.cjs")
+const {
+  formatSuggestionReport,
+  suggestCharts,
+} = require("./chartSuggestions.cjs")
+const {
+  behaviorContractsFor,
+  dataRequiredForUsageMode,
+  formatDoctorBehaviorContracts,
+  normalizeUsageMode,
+} = require("./behaviorContracts.cjs")
 
 const FILES = {
   default: path.join(pkgRoot, "CLAUDE.md"),
@@ -13,67 +30,269 @@ const FILES = {
   "--examples": path.join(__dirname, "examples.md"),
 }
 
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err)
+}
+
 const HELP = `
 semiotic-ai — Dump Semiotic AI context to stdout
 
 Usage:
   npx semiotic-ai              Print CLAUDE.md (full reference)
-  npx semiotic-ai --schema     Print ai/schema.json (tool definitions)
+  npx semiotic-ai --list        List components, categories, imports, and renderability
+  npx semiotic-ai --list --json Print component index as JSON
+  npx semiotic-ai --schema     Print ai/schema.json (all tool definitions)
+  npx semiotic-ai --schema BarChart
+                                Print one component schema plus AI metadata
+  npx semiotic-ai --suggest     Recommend charts from { data, intent? } JSON
   npx semiotic-ai --compact    Print ai/system-prompt.md (compact prompt)
   npx semiotic-ai --examples   Print ai/examples.md (copy-paste examples)
-  npx semiotic-ai --doctor     Validate component + props JSON from stdin
+  npx semiotic-ai --doctor     Validate { component, props, usageMode? } JSON from stdin
   npx semiotic-ai --help       Show this help message
 `.trim()
 
 const flag = process.argv[2]
 
+function loadSchema() {
+  return JSON.parse(fs.readFileSync(FILES["--schema"], "utf-8"))
+}
+
+function componentIndex() {
+  return componentIndexFromSchema(loadSchema())
+}
+
+function printComponentList(asJSON) {
+  const index = componentIndex()
+  if (asJSON) {
+    console.log(JSON.stringify(index, null, 2))
+    return
+  }
+
+  console.log(`Semiotic components (${index.totalComponents} total, ${index.renderableComponents} renderable)`)
+  for (const category of CATEGORY_ORDER) {
+    const names = index.categories[category] || []
+    if (names.length === 0) continue
+    console.log(`\n${category}:`)
+    for (const name of names) {
+      const component = index.components.find((entry) => entry.name === name)
+      const marker = component.renderable ? "renderable" : "browser-only"
+      console.log(`  ${name} [${marker}] import ${component.importPath}`)
+    }
+  }
+}
+
+function printSingleComponentSchema(componentName) {
+  const schema = loadSchema()
+  const component = findComponent(schema, componentName)
+  if (!component) {
+    const available = schemaEntries(schema).map((entry) => entry.name).sort().join(", ")
+    console.error(`Unknown component: ${componentName}`)
+    console.error(`Available components: ${available}`)
+    process.exit(1)
+  }
+
+  const payload = {
+    ...component,
+    metadata: {
+      ...metadataForComponent(component),
+      usageModes: {
+        static: {
+          dataRequired: dataRequiredForUsageMode(component.name, "static"),
+          note: "Use for renderChart, MCP previews, SSR snapshots, and static JSX examples.",
+        },
+        push: {
+          dataRequired: dataRequiredForUsageMode(component.name, "push"),
+          note: "Use for ref-based React HOCs. Omit data and push via ref.current when supported.",
+        },
+      },
+    },
+    behaviorContracts: behaviorContractsFor({ component: component.name, props: {} }),
+  }
+  console.log(JSON.stringify(payload, null, 2))
+}
+
+// Both helpers are only called from `validatePropsWithSchema` below, which
+// filters `undefined` / `null` out of `value` before reaching them — so
+// neither guards null here. CodeQL flags the dead branches if they return.
+
+function schemaTypeMatches(value, expectedType) {
+  const expectedTypes = Array.isArray(expectedType) ? expectedType : [expectedType]
+  return expectedTypes.some((type) => {
+    if (type === "array") return Array.isArray(value)
+    if (type === "object") return typeof value === "object" && !Array.isArray(value)
+    return typeof value === type
+  })
+}
+
+function describeActualType(value) {
+  if (Array.isArray(value)) return "array"
+  return typeof value
+}
+
+function shouldSkipMissingRequiredProp(componentName, propName, usageMode) {
+  return propName === "data" && !dataRequiredForUsageMode(componentName, usageMode)
+}
+
+function filterUsageModeErrors(componentName, errors, usageMode) {
+  if (dataRequiredForUsageMode(componentName, usageMode)) return errors
+  return errors.filter((err) => err !== `"data" is required for ${componentName}.`)
+}
+
+function validatePropsWithSchema(componentName, props, usageMode = "static") {
+  const schema = loadSchema()
+  const component = findComponent(schema, componentName)
+  if (!component) {
+    const available = schemaEntries(schema).map((entry) => entry.name).sort().join(", ")
+    return {
+      valid: false,
+      errors: [`Unknown component "${componentName}". Available components: ${available}`],
+    }
+  }
+
+  const parameters = component.parameters || {}
+  const properties = parameters.properties || {}
+  const required = parameters.required || []
+  const errors = []
+
+  for (const propName of required) {
+    if (shouldSkipMissingRequiredProp(component.name, propName, usageMode)) continue
+    if (props[propName] === undefined || props[propName] === null) {
+      errors.push(`"${propName}" is required for ${component.name}.`)
+    }
+  }
+
+  for (const [propName, value] of Object.entries(props)) {
+    if (value === undefined || value === null) continue
+    const propSchema = properties[propName]
+    if (!propSchema) {
+      errors.push(`Unknown prop "${propName}" for ${component.name}.`)
+      continue
+    }
+
+    if (propSchema.type && !schemaTypeMatches(value, propSchema.type)) {
+      const expected = Array.isArray(propSchema.type) ? propSchema.type.join(" | ") : propSchema.type
+      errors.push(`"${propName}" should be ${expected}, got ${describeActualType(value)}.`)
+    }
+
+    if (propSchema.enum && typeof value === "string" && !propSchema.enum.includes(value)) {
+      errors.push(`"${propName}" value "${value}" is not valid. Expected one of: ${propSchema.enum.join(", ")}.`)
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  }
+}
+
+function printSchemaOnlyDoctorResult(component, props, usageMode) {
+  const result = validatePropsWithSchema(component, props, usageMode)
+  if (usageMode === "push") {
+    console.log(`  Usage mode: push (data prop may be omitted; use a ref to push data)`)
+  }
+  if (result.valid) {
+    console.log(`✓ ${component}: schema-only validation passed.`)
+  } else {
+    console.log(`✗ ${component}: schema-only validation failed.`)
+    for (const err of result.errors) {
+      console.log(`  • ${err}`)
+    }
+  }
+  printDoctorBehaviorContracts(component, props)
+}
+
+function printDoctorBehaviorContracts(component, props) {
+  const formatted = formatDoctorBehaviorContracts(
+    behaviorContractsFor({ component, props })
+  )
+  if (formatted) {
+    console.log("")
+    console.log(formatted)
+  }
+}
+
+function readJSONInput(usage) {
+  if (process.argv[3]) {
+    return process.argv.slice(3).join(" ")
+  }
+  if (!process.stdin.isTTY) {
+    return fs.readFileSync(0, "utf-8")
+  }
+
+  console.error(usage)
+  process.exit(1)
+}
+
 if (flag === "--help" || flag === "-h") {
   console.log(HELP)
   process.exit(0)
 }
 
-// --doctor: validate component + props from stdin or argv
-if (flag === "--doctor") {
-  let input = ""
-  if (process.argv[3]) {
-    // npx semiotic-ai --doctor '{"component":"LineChart","props":{...}}'
-    input = process.argv.slice(3).join(" ")
-  } else if (!process.stdin.isTTY) {
-    // echo '...' | npx semiotic-ai --doctor
-    input = fs.readFileSync("/dev/stdin", "utf-8")
-  } else {
-    console.error("Usage: npx semiotic-ai --doctor '{\"component\":\"LineChart\",\"props\":{\"data\":[...]}}'")
-    console.error("       echo '{...}' | npx semiotic-ai --doctor")
+if (flag === "--list") {
+  printComponentList(process.argv.includes("--json"))
+  process.exit(0)
+}
+
+if (flag === "--schema" && process.argv[3]) {
+  printSingleComponentSchema(process.argv[3])
+  process.exit(0)
+}
+
+if (flag === "--suggest") {
+  const input = readJSONInput("Usage: npx semiotic-ai --suggest '{\"data\":[{\"category\":\"A\",\"value\":10}],\"intent\":\"comparison\"}'")
+  try {
+    const args = JSON.parse(input)
+    const result = suggestCharts(args)
+    console.log(formatSuggestionReport(result))
+    process.exit(result.ok ? 0 : 1)
+  } catch (err) {
+    console.error(`Failed to parse input: ${errorMessage(err)}`)
     process.exit(1)
   }
+}
+
+// --doctor: validate component + props from stdin or argv
+if (flag === "--doctor") {
+  const input = readJSONInput("Usage: npx semiotic-ai --doctor '{\"component\":\"LineChart\",\"props\":{\"data\":[...]},\"usageMode\":\"static\"}'\n       echo '{\"component\":\"LineChart\",\"props\":{\"xAccessor\":\"x\",\"yAccessor\":\"y\"},\"usageMode\":\"push\"}' | npx semiotic-ai --doctor")
 
   try {
-    const { component, props } = JSON.parse(input)
+    const { component, props, usageMode: rawUsageMode } = JSON.parse(input)
     if (!component || !props) {
       console.error("Input must be JSON with { component, props } fields.")
       process.exit(1)
     }
+    const usageMode = normalizeUsageMode(rawUsageMode)
 
-    // Load diagnoseConfig from dist (falls back to validateProps)
+    // Load diagnoseConfig from dist (falls back to validateProps, then schema.json)
     const distPath = path.join(pkgRoot, "dist", "semiotic-ai.min.js")
     let diagnoseConfig, validateProps
     try {
-      const mod = require(distPath)
-      diagnoseConfig = mod.diagnoseConfig
-      validateProps = mod.validateProps
+      if (!process.env.SEMIOTIC_AI_SCHEMA_ONLY) {
+        const mod = require(distPath)
+        diagnoseConfig = mod.diagnoseConfig
+        validateProps = mod.validateProps
+      }
     } catch (e) {
-      console.error("Could not load semiotic/ai dist. Run 'npm run dist' first.")
-      process.exit(1)
+      // Dist is not available in a clean source checkout. Fall back to the
+      // packaged schema so the CLI still catches basic agent mistakes.
     }
 
     if (!diagnoseConfig && !validateProps) {
-      console.error("diagnoseConfig/validateProps not found in semiotic/ai exports.")
-      process.exit(1)
+      printSchemaOnlyDoctorResult(component, props, usageMode)
+      process.exit(0)
     }
 
     if (diagnoseConfig) {
       // Use the full anti-pattern detector
       const result = diagnoseConfig(component, props)
+      const diagnoses = usageMode === "push"
+        ? result.diagnoses.filter((d) => d.code !== "VALIDATION" || !shouldSkipMissingRequiredProp(component, "data", usageMode) || d.message !== `"data" is required for ${component}.`)
+        : result.diagnoses
+      const ok = diagnoses.every((d) => d.severity === "warning")
+
+      if (usageMode === "push") {
+        console.log(`  Usage mode: push (data prop may be omitted; use a ref to push data)`)
+      }
 
       // Show data shape summary
       if (props.data && Array.isArray(props.data) && props.data.length > 0) {
@@ -81,36 +300,42 @@ if (flag === "--doctor") {
         console.log(`  Data shape: ${props.data.length} items, keys: [${Object.keys(sample).join(", ")}]`)
       }
 
-      if (result.ok && result.diagnoses.length === 0) {
+      if (ok && diagnoses.length === 0) {
         console.log(`✓ ${component}: configuration looks good.`)
-      } else if (result.ok) {
+      } else if (ok) {
         console.log(`✓ ${component}: configuration OK with warnings:`)
-        for (const d of result.diagnoses) {
+        for (const d of diagnoses) {
           console.log(`  ⚠ [${d.code}] ${d.message}`)
           if (d.fix) console.log(`    Fix: ${d.fix}`)
         }
       } else {
         console.log(`✗ ${component}: issues detected.`)
-        for (const d of result.diagnoses) {
+        for (const d of diagnoses) {
           const icon = d.severity === "error" ? "✗" : "⚠"
           console.log(`  ${icon} [${d.code}] ${d.message}`)
           if (d.fix) console.log(`    Fix: ${d.fix}`)
         }
       }
+      printDoctorBehaviorContracts(component, props)
     } else {
       // Fallback to validateProps only
       const result = validateProps(component, props)
-      if (result.valid) {
+      const errors = filterUsageModeErrors(component, result.errors, usageMode)
+      if (usageMode === "push") {
+        console.log(`  Usage mode: push (data prop may be omitted; use a ref to push data)`)
+      }
+      if (errors.length === 0) {
         console.log(`✓ ${component}: props are valid.`)
       } else {
         console.log(`✗ ${component}: validation failed.`)
-        for (const err of result.errors) {
+        for (const err of errors) {
           console.log(`  • ${err}`)
         }
       }
+      printDoctorBehaviorContracts(component, props)
     }
   } catch (err) {
-    console.error(`Failed to parse input: ${err.message}`)
+    console.error(`Failed to parse input: ${errorMessage(err)}`)
     process.exit(1)
   }
   process.exit(0)