feat: exempt routine documentation from design review

Author: Bill Leoutsakos

bun.lock

@@ -88,7 +88,8 @@
       "list": "apps/docs/lib/openapi-specs.ts",
       "export": "OPENAPI_SPEC_FILES",
       "root": "apps/docs",
-      "renderer": "apps/docs/lib/openapi.ts"
+      "renderer": "apps/docs/lib/openapi.ts",
+      "contentOnly": true
     }
   ],
   "environmentAdapters": [
@@ -100,5 +101,62 @@
       "implementationModule": "apps/sim/lib/core/config/env-capabilities.ts",
       "implementationExport": "wireFallback"
     }
-  ]
+  ],
+  "documentationContent": {
+    "roots": ["apps/docs/content/", "apps/sim/content/"],
+    "frontmatterFields": [
+      "title",
+      "description",
+      "author",
+      "date",
+      "publishedAt",
+      "updatedAt",
+      "readingTime",
+      "tags",
+      "category",
+      "keywords"
+    ],
+    "components": [
+      {
+        "module": "fumadocs-ui/components/callout",
+        "names": ["Callout"],
+        "contentProps": ["type", "title"]
+      },
+      {
+        "module": "fumadocs-ui/components/card",
+        "names": ["Card", "Cards"],
+        "contentProps": ["title", "description", "href"]
+      },
+      {
+        "module": "fumadocs-ui/components/steps",
+        "names": ["Step", "Steps"],
+        "contentProps": ["title"]
+      },
+      {
+        "module": "fumadocs-ui/components/tabs",
+        "names": ["Tab", "Tabs"],
+        "contentProps": ["items", "value"]
+      },
+      {
+        "module": "@/components/ui/faq",
+        "names": ["FAQ"],
+        "contentProps": ["items"]
+      },
+      {
+        "module": "@/components/ui/block-info-card",
+        "names": ["BlockInfoCard"],
+        "contentProps": ["type"]
+      },
+      {
+        "module": "@/components/ui/command-table",
+        "names": ["CommandTable"],
+        "contentProps": []
+      },
+      {
+        "module": "@/components/ui/what-you-will-learn",
+        "names": ["WhatYouWillLearn"],
+        "contentProps": ["items"]
+      }
+    ]
+  }
 }

design-diff.config.json

@@ -188,6 +188,7 @@
     "unified": "11.0.5",
     "unist-util-visit": "5.1.0",
     "vitest": "^4.1.0",
+    "yaml": "2.9.0",
     "zod": "4.3.6"
   },
   "lint-staged": {

package.json

@@ -29,7 +29,7 @@ deterministic payload. Finding IDs are stable for the same input pair and engine
 ## Binary decisions and grouped report (schema 3)
 
 The public decisions are **`flag`** and **`exempt`**. Uncertainty produces `flag`, with
-the obstacle recorded in `limitations`. Schema and policy version `3.0.0`, engine version `0.3.0`, retain binary decisions
+the obstacle recorded in `limitations`. Schema version `3.0.0`, policy version `4.0.0`, engine version `0.4.0`, retain binary decisions
 and add bounded values and explicit report truncation metadata.
 
 Each finding groups evidence by **changed source file**. Several changed definitions in
@@ -112,6 +112,7 @@ scripts/design-diff/
   environment.ts                        Literal createEnv schema field comparison
   resolve.ts                            Bounded expression and import resolution
   inputs.ts                             Configured file-loaded documentation inputs
+  document-content.ts                   Routine documentation authoring exemptions
   infrastructure.ts                     Rendering lockfile dependency closure
   report.ts                             Value previews and bounded JSON serialization
   semantic.ts                           Full semantic hashes without repeated tree expansion
@@ -150,12 +151,35 @@ TSX/CSS files that an application build or Tailwind source scan could consume.
 | Shape/effects | Radius, border, shadow, opacity, filters | Flag |
 | Layout | Wrapping, flex/grid sizing, stretching | Flag |
 | Visibility | Hidden state, overflow, clipping, layering | Flag |
-| Content | Visible copy, JSX/HTML/MDX structure, images, SVG, fonts | Flag |
+| Content | Product copy, new product controls, custom MDX UI, images, SVG, fonts | Flag |
+| Routine documentation | Prose, headings, tables, code samples, known content components, API-reference data | No finding |
 | Motion | Keyframes, transitions, animation props | Flag |
 | Infrastructure | Renderer dependencies, lockfile, CSS processors, module mappings | Flag |
 | Movement | Coordinates, translation, margins, gaps, alignment | Flag unless the static proof succeeds |
 | Nonvisual/equivalent | Comments, erased types, supported formatting and constant extraction | No finding |
 
+Policy 4 exempts routine authoring in the `documentationContent.roots` directories. The parser
+projects out prose, Markdown tables, code samples and recognized frontmatter content fields.
+Configured Fumadocs/repository components are recognized by their import module and named export,
+including local import aliases. Only their declared content props with literal data are exempt;
+standard Callout types and tab labels are authoring options. Unknown widgets, appearance overrides,
+spreads, unresolved expressions, embedded images/media and unknown frontmatter fields remain in
+scope. YAML 2.9.0 uses its data-only core schema with custom tags disabled and aliases bounded;
+malformed or unsupported syntax produces a flag. Prose insertion does not renumber retained
+presentation definitions. A custom wrapper's opaque contents may still produce conservative flags.
+
+The exemption concerns document instances. Shared documentation components, templates, styles,
+rendering infrastructure and screenshot assets are still analyzed. Product UI is unchanged by this
+policy: adding a search field/modal/panel flags even when it reuses EMCN; local appearance overrides,
+shared tokens and existing movement checks are retained. Product status/error wording and HTML
+policy/pricing pages remain in scope. Published Markdown article prose uses the same authoring
+exemption; embedded covers and other media remain visual assets.
+
+The original 180-case manifest retains its policy-3 labels. New qualification rates must compare the
+same immutable source commits while reporting document-content exclusions separately; policy-3
+visual labels are not automatically policy-4 positives. Previous cloud smoke/evaluation runs do not
+validate this policy version.
+
 Babel parses JS/TS/JSX; PostCSS parses CSS; parse5 parses HTML; remark parses
 Markdown/MDX/frontmatter/GFM. CSS selector, conditional and declaration order are retained.
 JSX whitespace follows React's line handling. Class composition and JSX spread/attribute
@@ -202,8 +226,10 @@ unsupported dynamic schemas use ordinary conservative resolution. Whole-environm
 settings therefore do not contaminate the signup page solely through this known adapter.
 
 The configured Fumadocs `OPENAPI_SPEC_FILES` list is parsed from Git in each revision. Listed
-JSON inputs are compared semantically, retaining array order and attributing changes to both
-the spec and configured renderer. Malformed/missing configured inputs flag with a limitation.
+JSON inputs are validated as data. The configured `contentOnly` convention exempts valid API-reference
+descriptions, schemas, enum lists and specification-list changes. Malformed/missing configured inputs
+still flag with a limitation. JSON consumed elsewhere by product UI remains subject to normal tracing.
+Renderer and list implementation changes remain subject to normal source/infrastructure analysis.
 
 The graph reuses up to 32,768 import/export snapshots keyed by source blob, resolving their
 paths again for each revision. Each consumer resolver retains at most 32 parsed modules,
@@ -248,8 +274,9 @@ This engine is conservative, not a runtime equivalence prover:
 - Dynamic module/asset paths, inherited/conditional export maps outside the supported forms,
   generated source and arbitrary imperative renderers cannot be fully followed. Directly
   detected DOM/canvas operations and configured native rendering use uncertainty fallbacks.
-- MDX expressions and embedded HTML scripts are flagged, without running MDX components or
-  scripts. Plain HTML whitespace is preserved because CSS can make it meaningful.
+- Unresolved/custom MDX expressions and embedded HTML scripts are flagged, without running MDX
+  components or scripts. Literal content in documented authoring components is exempt. Plain HTML
+  whitespace outside the Markdown authoring exemption is preserved because CSS can make it meaningful.
 - Lockfiles compare recognized rendering dependencies and their resolved transitive closure.
   Unrelated tooling/backend updates are clean. Unknown rendering configs/plugins still flag.
   Inactive variants, unused assets and an apparently inert removed class can also be flagged.

scripts/design-diff/README.md

@@ -24,8 +24,8 @@ import type { Change, Config, Definition, Report } from '#design-diff/types'
 export function emptyReport(): Report {
   return {
     schemaVersion: '3.0.0',
-    engineVersion: '0.3.0',
-    policyVersion: '3.0.0',
+    engineVersion: '0.4.0',
+    policyVersion: '4.0.0',
     commits: null,
     status: 'failed',
     flagged: null,

scripts/design-diff/analyze.ts

@@ -205,8 +205,8 @@ export async function benchmark(args = process.argv.slice(2)): Promise<void> {
       result.reportSha256 = hash(bytes)
       if (
         report.schemaVersion !== '3.0.0' ||
-        report.engineVersion !== '0.3.0' ||
-        report.policyVersion !== '3.0.0'
+        report.engineVersion !== '0.4.0' ||
+        report.policyVersion !== '4.0.0'
       )
         throw new Error('Report version mismatch')
       if (JSON.stringify(report.commits) !== JSON.stringify(commits))

scripts/design-diff/benchmark.ts

@@ -0,0 +1,197 @@
+import * as t from '@babel/types'
+import { parseDocument } from 'yaml'
+import { canonicalJson, parseSyntax } from '#design-diff/ast'
+import type { Config, Data } from '#design-diff/types'
+
+type Node = Record<string, Data>
+
+const prose = new Set([
+  'text',
+  'inlineCode',
+  'code',
+  'break',
+  'thematicBreak',
+  'definition',
+  'footnoteReference',
+])
+const containers = new Set([
+  'root',
+  'paragraph',
+  'heading',
+  'blockquote',
+  'list',
+  'listItem',
+  'emphasis',
+  'strong',
+  'delete',
+  'link',
+  'linkReference',
+  'table',
+  'tableRow',
+  'tableCell',
+  'footnoteDefinition',
+])
+const proseTags = new Set([
+  'p',
+  'span',
+  'a',
+  'strong',
+  'em',
+  'b',
+  'i',
+  'code',
+  'pre',
+  'br',
+  'hr',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'ul',
+  'ol',
+  'li',
+  'blockquote',
+  'table',
+  'thead',
+  'tbody',
+  'tr',
+  'th',
+  'td',
+])
+
+function object(value: Data | undefined): value is Node {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}
+
+/** Only literal document data qualifies; calls, spreads and JSX never execute or disappear. */
+function literal(node: t.Node | null | undefined): boolean {
+  if (!node) return false
+  if (
+    t.isStringLiteral(node) ||
+    t.isNumericLiteral(node) ||
+    t.isBooleanLiteral(node) ||
+    t.isNullLiteral(node)
+  )
+    return true
+  if (t.isArrayExpression(node)) return node.elements.every(literal)
+  if (t.isObjectExpression(node))
+    return node.properties.every(
+      (property) => t.isObjectProperty(property) && !property.computed && literal(property.value)
+    )
+  if (t.isTemplateLiteral(node)) return node.expressions.every(literal)
+  if (t.isUnaryExpression(node) && ['-', '+', '!'].includes(node.operator))
+    return literal(node.argument)
+  if (t.isTSAsExpression(node) || t.isTSSatisfiesExpression(node)) return literal(node.expression)
+  return false
+}
+
+function literalExpression(value: string): boolean {
+  try {
+    const parsed = parseSyntax(`const value = (${value})`, 'document.tsx').program.body[0]
+    return t.isVariableDeclaration(parsed) && literal(parsed.declarations[0]?.init)
+  } catch {
+    return false
+  }
+}
+
+/** Project authoring content away while retaining custom presentation and unknown mechanisms. */
+export function documentPresentation(
+  nodes: Node[],
+  policy: NonNullable<Config['documentationContent']>
+): Node[] {
+  const bindings = new Map<string, { module: string; name: string; props: string[] }>()
+  const approvedImports = new Set<Node>()
+  for (const node of nodes) {
+    if (node.type !== 'mdxjsEsm' || typeof node.value !== 'string') continue
+    const statements = parseSyntax(node.value, 'document.tsx').program.body
+    let approved = true
+    for (const statement of statements) {
+      if (!t.isImportDeclaration(statement) || !statement.specifiers.length) {
+        approved = false
+        continue
+      }
+      for (const specifier of statement.specifiers) {
+        const name = t.isImportSpecifier(specifier)
+          ? t.isIdentifier(specifier.imported)
+            ? specifier.imported.name
+            : specifier.imported.value
+          : 'default'
+        const rule = policy.components.find(
+          (rule) => rule.module === statement.source.value && rule.names.includes(name)
+        )
+        if (!rule || !t.isImportSpecifier(specifier)) {
+          approved = false
+          continue
+        }
+        bindings.set(specifier.local.name, { module: rule.module, name, props: rule.contentProps })
+      }
+    }
+    if (approved) approvedImports.add(node)
+  }
+
+  const project = (node: Node): Node[] => {
+    const type = String(node.type)
+    if (prose.has(type)) return []
+    if (approvedImports.has(node)) return []
+    if (type === 'yaml' && typeof node.value === 'string') {
+      const document = parseDocument(node.value, {
+        schema: 'core',
+        customTags: [],
+        uniqueKeys: true,
+      })
+      if (document.errors.length || document.warnings.length)
+        throw new Error('Unsupported documentation frontmatter')
+      const value = document.toJS({ maxAliasCount: 0 }) as Data
+      if (!object(value)) throw new Error('Documentation frontmatter must be an object')
+      const retained = Object.fromEntries(
+        Object.entries(value).filter(([key]) => !policy.frontmatterFields.includes(key))
+      )
+      return Object.keys(retained).length ? [{ ...node, value: canonicalJson(retained) }] : []
+    }
+    if (/^mdx.*Expression$/.test(type) && typeof node.value === 'string') {
+      if (/^\s*\/\*[\s\S]*\*\/\s*$/.test(node.value) || literalExpression(node.value)) return []
+      return [node]
+    }
+    const children = Array.isArray(node.children)
+      ? node.children.flatMap((child) => (object(child) ? project(child) : []))
+      : []
+    if (containers.has(type)) return children.length ? [{ ...node, children }] : []
+    if (/^mdxJsx(?:Flow|Text)Element$/.test(type)) {
+      const name = typeof node.name === 'string' ? node.name : ''
+      const binding = bindings.get(name)
+      const intrinsic = proseTags.has(name)
+      if (!binding && !intrinsic && name) return [node]
+      const allowed = binding?.props ?? ['title', 'href', 'id', 'aria-label']
+      const attributes = Array.isArray(node.attributes)
+        ? node.attributes.filter((attribute) => {
+            if (
+              !object(attribute) ||
+              attribute.type !== 'mdxJsxAttribute' ||
+              typeof attribute.name !== 'string'
+            )
+              return true
+            if (!allowed.includes(attribute.name)) return true
+            if (typeof attribute.value === 'string' || attribute.value === null) return false
+            return (
+              !object(attribute.value) ||
+              typeof attribute.value.value !== 'string' ||
+              !literalExpression(attribute.value.value)
+            )
+          })
+        : []
+      if (!attributes.length && !children.length) return []
+      return [
+        {
+          ...node,
+          name: binding ? `${binding.module}#${binding.name}` : node.name,
+          attributes,
+          children,
+        },
+      ]
+    }
+    return [node]
+  }
+  return nodes.flatMap(project)
+}