fix exported class map source dispatch

Author: Bill Leoutsakos

scripts/check-design-conformance-appearance.test.ts

@@ -157,9 +157,10 @@ test('a component rename does not hide removal of an appearance override', () =>
   ).toBe(false)
 })
 test('uppercase exported object styling and property edits are inspected', () => {
-  const a = "export const PANEL_CLASSES={layout:'p-2 [--control-reserve:64px]'} as const"
+  const a =
+    "export const PANEL_CLASSES={layout:'p-2 [--control-reserve:64px]'} as const;const A=()=> <div className={PANEL_CLASSES.layout}/>"
   expect(diff(a, a.replace('64px', '52px')).flagged).toBe(true)
-  expect(diff(a, a.replace('PANEL_CLASSES', 'ROW_CLASSES')).flagged).toBe(false)
+  expect(diff(a, a.replaceAll('PANEL_CLASSES', 'ROW_CLASSES')).flagged).toBe(false)
 })
 test('detached shared styles have specific evidence; import aliases pass', () => {
   const a =

scripts/check-design-conformance-command.test.ts

@@ -309,6 +309,165 @@ throw new Error('Product source must not execute')
   }
 )
 
+test.each([
+  [
+    'Boolean class map',
+    "{'bg-red-500':true}",
+    "{'bg-blue-500':true}",
+    'cn(paintStyles)',
+    'paintStyles',
+    true,
+    false,
+  ],
+  [
+    'truthy string class map',
+    "{'bg-red-500':'enabled'}",
+    "{'bg-blue-500':'enabled'}",
+    'cn(paintStyles)',
+    'paintStyles',
+    true,
+    false,
+  ],
+  [
+    'nested class map',
+    "{tone:{'bg-red-500':true}}",
+    "{tone:{'bg-blue-500':true}}",
+    'cn(paintStyles.tone)',
+    'paintStyles',
+    true,
+    false,
+  ],
+  [
+    'class map without styling suffix',
+    "{'bg-red-500':true}",
+    "{'bg-blue-500':true}",
+    'cn(palette)',
+    'palette',
+    true,
+    false,
+  ],
+  [
+    'falsy class map',
+    "{'bg-red-500':false,'rounded-lg':0,'p-2':null,'text-red-500':''}",
+    "{'bg-blue-500':false,'rounded-xl':0,'p-4':null,'text-blue-500':''}",
+    'cn(paintStyles)',
+    'paintStyles',
+    false,
+    false,
+  ],
+  [
+    'variant string value',
+    "{primary:'bg-red-500'}",
+    "{primary:'bg-blue-500'}",
+    'cn(paintStyles.primary)',
+    'paintStyles',
+    true,
+    false,
+  ],
+  [
+    'nested variant value',
+    "{tone:{primary:'bg-red-500'}}",
+    "{tone:{primary:'bg-blue-500'}}",
+    'cn(paintStyles.tone.primary)',
+    'paintStyles',
+    true,
+    false,
+  ],
+  [
+    'CVA variant table',
+    "{tone:{primary:'bg-red-500'}}",
+    "{tone:{primary:'bg-blue-500'}}",
+    "cva('',{variants:paintStyles})()",
+    'paintStyles',
+    true,
+    false,
+  ],
+  [
+    'exported string',
+    "'bg-red-500'",
+    "'bg-blue-500'",
+    'cn(paintStyles)',
+    'paintStyles',
+    true,
+    false,
+  ],
+  [
+    'data-only object',
+    "{message:'bg-red-500'}",
+    "{message:'bg-blue-500'}",
+    'JSON.stringify(paintStyles)',
+    'paintStyles',
+    false,
+    true,
+  ],
+  [
+    'shadowed data object',
+    "{message:'bg-red-500'}",
+    "{message:'bg-blue-500'}",
+    '<shadowed>',
+    'paintStyles',
+    false,
+    true,
+  ],
+  [
+    'unknown object consumer',
+    "{primary:'bg-red-500'}",
+    "{primary:'bg-blue-500'}",
+    'unknownClasses(paintStyles)',
+    'paintStyles',
+    false,
+    true,
+  ],
+] as const)(
+  'source-only exported styling changes follow unchanged class consumers through the real CLI: %s',
+  (_name, before, after, use, exported, notify, unchecked) => {
+    const { repo } = fixture()
+    const sourceFile = 'packages/emcn/src/lib/styles.ts'
+    const consumerFile = 'packages/emcn/src/components/consumer.tsx'
+    const write = (file: string, source: string) => {
+      mkdirSync(path.dirname(path.join(repo, file)), { recursive: true })
+      writeFileSync(path.join(repo, file), source)
+    }
+    write('packages/emcn/src/index.ts', `export {${exported}} from './lib/styles'`)
+    const shadow =
+      use === '<shadowed>'
+        ? ";declare function cva(value:unknown):unknown;function Local(){const paintStyles={'p-2':true};return cva(paintStyles)}"
+        : ''
+    write(sourceFile, `export const ${exported}=${before} as const${shadow}`)
+    write(
+      consumerFile,
+      `import {${exported}} from '../lib/styles';declare function cn(...v:unknown[]):string;declare function unknownClasses(v:unknown):string;declare function cva(base:string,config:unknown):()=>string;${use === '<shadowed>' ? "const Consumer=()=> {const paintStyles={'p-2':true};return <div className={cn(paintStyles)}/>}" : `const Consumer=()=> <div className={${use}}/>`}`
+    )
+    write(
+      ui,
+      `import {${exported},cn} from '@sim/emcn';const A=()=> <div className={cn(${exported})}/>`
+    )
+    const base = commit(repo)
+    write(sourceFile, `export const ${exported}=${after} as const${shadow}`)
+    const child = run(['--repo', repo, '--base', base, '--working-tree', '--format', 'json'])
+    expect([0, 1], child.stderr).toContain(child.status)
+    const report = JSON.parse(child.stdout) as Report
+    expect(report.status, child.stdout).toBe('completed')
+    expect(git(repo, ['diff', '--name-only', base]).toString().trim()).toBe(sourceFile)
+    expect(
+      report.findings.some(
+        (finding) => finding.file === sourceFile && finding.property === 'background-color'
+      ),
+      child.stdout
+    ).toBe(notify)
+    expect(
+      report.findings.filter((finding) => finding.file === sourceFile),
+      child.stdout
+    ).toHaveLength(notify ? 1 : 0)
+    expect(
+      report.unchecked.some(
+        (note) => note.file === sourceFile && /object.*class.*unchecked/i.test(note.reason)
+      ),
+      child.stdout
+    ).toBe(unchecked)
+  }
+)
+
 test.each([
   ['grid line integer', 'gridColumnStart', 'grid-column-start', '1', 1, ''],
   ['grid row integer', 'gridRowEnd', 'grid-row-end', '3', 3, ''],

scripts/design-conformance/conformance.ts

@@ -577,6 +577,7 @@ export class ConformanceLinter {
     const facts = extract(source, file, true, {
       conformance: true,
       resolve: system.resolve,
+      classUses: system.classUses,
       contract: (target) => componentContract(target, system.metadata),
     })
     const bytes = Buffer.byteLength(canonical(facts))

scripts/design-conformance/design-system.ts

@@ -27,7 +27,7 @@ import {
   utility,
   variablesIn,
 } from '#design-conformance/normalize'
-import { type SourceSummary, summarize } from '#design-conformance/source-summary'
+import { classUseIndex, type SourceSummary, summarize } from '#design-conformance/source-summary'
 import type { SystemInput } from '#design-conformance/system-snapshot'
 
 export interface Reference {
@@ -50,6 +50,7 @@ interface Module {
 export interface DesignSystem {
   metadata: GeneratedContracts
   recipes: Record<string, ReturnType<typeof extractCentralRecipes>>
+  classUses: ReturnType<typeof classUseIndex>
   summaries: { file: string; summary: SourceSummary }[]
   resolutionHash: string
   definitions: Record<string, Atom[]>
@@ -586,13 +587,15 @@ export async function designSystem(input: SystemInput): Promise<DesignSystem> {
   unchecked.push(
     ...metadata.diagnostics.map((d) => ({ file: d.file, line: d.line, reason: d.reason }))
   )
+  const summaries = input.snapshot.entries.flatMap((e) => {
+    const summary = info.get(moduleName(e.path))?.summary
+    return summary ? [{ file: e.path, summary }] : []
+  })
   return {
     metadata,
     recipes,
-    summaries: input.snapshot.entries.flatMap((e) => {
-      const summary = info.get(moduleName(e.path))?.summary
-      return summary ? [{ file: e.path, summary }] : []
-    }),
+    classUses: classUseIndex(summaries),
+    summaries,
     resolutionHash: hash(
       canonical([
         metadata.sourceHash,

scripts/design-conformance/extract.ts

@@ -33,7 +33,13 @@ import {
   renderedHtml,
   visibleHtmlText,
 } from '#design-conformance/rendered-html'
-import { modulePath, type Route, summarize } from '#design-conformance/source-summary'
+import {
+  type ClassUse,
+  classUseIndex,
+  modulePath,
+  type Route,
+  summarize,
+} from '#design-conformance/source-summary'
 
 const classHelpers = new Set(['cn', 'clsx', 'classNames', 'twMerge'])
 const media = new Set([
@@ -55,6 +61,7 @@ export function extract(
   file: string,
   appearance = true,
   options?: {
+    classUses?: (ref: string) => ClassUse[]
     conformance: boolean
     resolve: (ref: string) => Reference | undefined
     contract?: (target: string) => ComponentContract | undefined
@@ -401,7 +408,9 @@ export function extract(
       errorRecovery: false,
     })
     parsed = true
-    if (options?.conformance) facts.syntax = summarize(ast, file)
+    const summary = summarize(ast, file)
+    const localClassUses = classUseIndex([{ file, summary }])
+    if (options?.conformance) facts.syntax = summary
     const emitted = new Set<string>()
     const mediaNames = new Set(media)
     for (const statement of ast.program.body)
@@ -1365,9 +1374,12 @@ export function extract(
           for (const decl of d.get('declarations'))
             if (
               decl.get('id').isIdentifier() &&
-              /(?:Class|Classes|Tokens|Styles|_CLASS|_CLASSES|_TOKENS|_STYLES)$/.test(
+              (/(?:Class|Classes|Tokens|Styles|_CLASS|_CLASSES|_TOKENS|_STYLES)$/.test(
                 name(decl.get('id'))
-              )
+              ) ||
+                localClassUses(`${modulePath(file)}#${name(decl.get('id'))}`).length > 0 ||
+                (options?.classUses?.(`${modulePath(file)}#${name(decl.get('id'))}`).length ?? 0) >
+                  0)
             )
               within(
                 surface(
@@ -1380,8 +1392,48 @@ export function extract(
                   let init = decl.get('init') as NodePath
                   if (init.isTSAsExpression() || init.isTSSatisfiesExpression())
                     init = init.get('expression') as NodePath
-                  if (init.isObjectExpression()) variantValues(init)
-                  else classes(init)
+                  if (init.isObjectExpression()) {
+                    const ref = `${modulePath(file)}#${name(decl.get('id'))}`
+                    const uses = [...localClassUses(ref), ...(options?.classUses?.(ref) ?? [])]
+                    if (!uses.length) {
+                      note(
+                        init,
+                        'Exported object class-input classification is unchecked; supplied same-file/central consumers do not prove class-map keys or variant values'
+                      )
+                      return
+                    }
+                    for (const use of uses) {
+                      let selected: NodePath | undefined = init
+                      for (const key of use.path) {
+                        while (
+                          selected?.isTSAsExpression() ||
+                          selected?.isTSSatisfiesExpression() ||
+                          selected?.isTSNonNullExpression()
+                        )
+                          selected = selected.get('expression') as NodePath
+                        if (!selected?.isObjectExpression()) {
+                          selected = undefined
+                          break
+                        }
+                        const member = selected
+                          .get('properties')
+                          .filter(
+                            (p) =>
+                              p.isObjectProperty() && !p.node.computed && name(p.get('key')) === key
+                          )
+                          .at(-1)
+                        selected = member?.isObjectProperty() ? member.get('value') : undefined
+                      }
+                      if (!selected) {
+                        note(init, 'Exported object class-input member path is unchecked')
+                        continue
+                      }
+                      if (use.mode === 'variants')
+                        variantValues(selected, use.path.map((part) => `/${part}`).join(''))
+                      else
+                        classes(selected, new Set(), 0, use.path.map((part) => `/${part}`).join(''))
+                    }
+                  } else classes(init)
                 }
               )
       },