refactor(design): group analysis by responsibility

Author: Bill Leoutsakos

.github/workflows/test-build.yml

@@ -310,7 +310,7 @@ jobs:
       # The same base covers the complete push for migration and block-registry checks.
       - name: Resolve base ref for diff-based audits
         id: audit_base
-        run: bun --no-env-file scripts/design-conformance/ci.ts --resolve-refs
+        run: bun --no-env-file scripts/design-conformance/diff/ci.ts --resolve-refs
 
       - name: Check block registry invariants
         run: bun run apps/sim/scripts/check-block-registry.ts "${{ steps.audit_base.outputs.ref }}"
@@ -334,7 +334,7 @@ jobs:
           DESIGN_BASE: ${{ steps.audit_base.outputs.ref }}
           DESIGN_HEAD: ${{ steps.audit_base.outputs.head }}
           DESIGN_REPORT_PATH: ${{ runner.temp }}/design-conformance.json
-        run: bun --no-env-file scripts/design-conformance/ci.ts --base "$DESIGN_BASE" --head "$DESIGN_HEAD"
+        run: bun --no-env-file scripts/design-conformance/diff/ci.ts --base "$DESIGN_BASE" --head "$DESIGN_HEAD"
 
       - name: Save design conformance report
         if: always()

biome.json

@@ -167,7 +167,7 @@
       }
     },
     {
-      "includes": ["scripts/design-conformance/contracts.json"],
+      "includes": ["scripts/design-conformance/system/contracts.json"],
       "formatter": {
         "enabled": false
       }

package.json

@@ -218,7 +218,6 @@
     "postgres@3.4.9": "patches/postgres@3.4.9.patch"
   },
   "imports": {
-    "#design-conformance/*": "./scripts/design-conformance/*.ts",
-    "#control-analysis/*": "./scripts/design-conformance/control-*.ts"
+    "#design-conformance/*": "./scripts/design-conformance/*.ts"
   }
 }

scripts/check-design-conformance.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 /** Checks committed styling against central design contracts. See design-conformance/README.md. */
 try {
-  const { main } = await import('#design-conformance/command')
+  const { main } = await import('#design-conformance/diff/command')
   process.exitCode = await main()
 } catch (error) {
   process.stderr.write(

scripts/design-conformance/README.md

@@ -24,11 +24,15 @@ CI uses immutable event base/head revisions. It publishes file/line warnings, a
 
 ## Files and source facts
 
-- `contracts.json`: general design rules, scope, exclusions, static-analysis limits, adopted utility policy and explicitly central external recipes. It has no component registration or handwritten component inheritance.
+- `system/contracts.json`: general design rules, scope, exclusions, static-analysis limits, adopted utility policy and explicitly central external recipes. It has no component registration or handwritten component inheritance.
 - `packages/emcn/src/design-ownership.json`: the small, explicit list of exceptional permissions and protections. It is read from each source revision, validated against discovered public exports and slots, and included in the scan's effective ownership inventory.
-- `generated-contracts.ts`: one TypeScript compatibility program per source snapshot discovers public APIs, aliases and compound exports. Babel traces implementation classes, CVA/imported recipes, slots and forwarding. Existing CSS/Tailwind analysis identifies owned properties and global token definitions, contexts and aliases. Bounded caches share the result. Snapshot hosts can read pinned dependency types but cannot read current workspace implementations while inspecting historical source.
+- `system/generated-contracts.ts`: one TypeScript compatibility program per source snapshot discovers public APIs, aliases and compound exports. Babel traces implementation classes, CVA/imported recipes, slots and forwarding. Existing CSS/Tailwind analysis identifies owned properties and global token definitions, contexts and aliases. Bounded caches share the result. Snapshot hosts can read pinned dependency types but cannot read current workspace implementations while inspecting historical source.
 - `scan.json`: external versioned report containing findings, unchecked diagnostics, inspection failures, product uses, and compact EMCN export/variant/default/slot/relationship facts. Component and icon namespaces remain distinct. Token definitions and recipe bodies are analyzed from source but are not duplicated in the report's metadata.
-- `conformance.ts`, `extract.ts`, `normalize.ts`, `source-summary.ts`, `control-*.ts`: shared styling, composition, control, artwork and provenance analysis. `command.ts` and `reporting.ts` handle local comparisons; `ci.ts` handles warning-only CI publication.
+- `shared/`: source readers, revision identity, report types, CSS normalization and rendered-HTML helpers used across the analyzers.
+- `system/`: central EMCN and global-style facts, generated export/slot metadata, recipes and policy.
+- `styling/`: class, CSS, artwork and component-ownership extraction and conformance rules.
+- `controls/`: rendered UI inventory, value and colour tracing, local-control review and product scope.
+- `diff/`: base/head comparison, local command, reporting and warning-only CI publication.
 - `scripts/design-scan/`: whole-tree inventory and external reports using that same analysis.
 - `scripts/design-studio/refresh.mjs`, `tools/design-studio/`: explicit local refresh and separate local-only Next app. The deployed Sim app has no Studio route.
 

…s/design-conformance/control-analysis.ts …/design-conformance/controls/analysis.tsscripts/design-conformance/control-analysis.ts renamed to scripts/design-conformance/controls/analysis.ts scripts/design-conformance/control-analysis.ts renamed to scripts/design-conformance/controls/analysis.ts

@@ -1,11 +1,11 @@
 import {
   type ColourAssignmentReport,
   ColourAssignments,
-} from '#control-analysis/colour-assignments'
-import { type ControlInventory, inspectControls } from '#control-analysis/inventory'
-import type { ControlSource } from '#control-analysis/model'
-import { ReviewCollector, type ReviewReport } from '#control-analysis/review'
-import type { GeneratedContracts } from '#design-conformance/generated-contracts'
+} from '#design-conformance/controls/colour-assignments'
+import { type ControlInventory, inspectControls } from '#design-conformance/controls/inventory'
+import type { ControlSource } from '#design-conformance/controls/model'
+import { ReviewCollector, type ReviewReport } from '#design-conformance/controls/review'
+import type { GeneratedContracts } from '#design-conformance/system/generated-contracts'
 
 /** Shared control analysis for the diff check and complete scan. */
 export function inspectControlAnalysis(

…n-conformance/colour-assignments.test.ts …ance/controls/colour-assignments.test.tsscripts/design-conformance/colour-assignments.test.ts renamed to scripts/design-conformance/controls/colour-assignments.test.ts scripts/design-conformance/colour-assignments.test.ts renamed to scripts/design-conformance/controls/colour-assignments.test.ts

@@ -1,7 +1,7 @@
 import { expect, test } from 'vitest'
-import { inspectControlAnalysis } from '#control-analysis/analysis'
-import { withoutVerifiedColourUsages } from '#control-analysis/colour-assignments'
-import type { ControlSource } from '#control-analysis/model'
+import { inspectControlAnalysis } from '#design-conformance/controls/analysis'
+import { withoutVerifiedColourUsages } from '#design-conformance/controls/colour-assignments'
+import type { ControlSource } from '#design-conformance/controls/model'
 
 const css = 'apps/sim/components/sample.css'
 const ui = 'apps/sim/components/sample.tsx'

…onformance/control-colour-assignments.ts …nformance/controls/colour-assignments.tsscripts/design-conformance/control-colour-assignments.ts renamed to scripts/design-conformance/controls/colour-assignments.ts scripts/design-conformance/control-colour-assignments.ts renamed to scripts/design-conformance/controls/colour-assignments.ts

@@ -7,13 +7,23 @@ import type {
   ControlSource,
   Diagnostic,
   InventoryFinding,
-} from '#control-analysis/model'
-import { compare, regular } from '#control-analysis/model'
-import { productScope } from '#control-analysis/scope'
-import { type Expr, expression, type StaticInputs, unknown } from '#control-analysis/static-inputs'
-import { centralFile } from '#design-conformance/contracts'
-import { canonical, type Finding, hash, TOKEN_FILE } from '#design-conformance/model'
-import { paintDeclarations, rawColours, utility, variablesIn } from '#design-conformance/normalize'
+} from '#design-conformance/controls/model'
+import { compare, regular } from '#design-conformance/controls/model'
+import { productScope } from '#design-conformance/controls/scope'
+import {
+  type Expr,
+  expression,
+  type StaticInputs,
+  unknown,
+} from '#design-conformance/controls/static-inputs'
+import { canonical, type Finding, hash, TOKEN_FILE } from '#design-conformance/shared/model'
+import {
+  paintDeclarations,
+  rawColours,
+  utility,
+  variablesIn,
+} from '#design-conformance/shared/normalize'
+import { centralFile } from '#design-conformance/system/contracts'
 
 interface Site {
   file: string

…ipts/design-conformance/coverage.test.ts …gn-conformance/controls/coverage.test.tsscripts/design-conformance/coverage.test.ts renamed to scripts/design-conformance/controls/coverage.test.ts scripts/design-conformance/coverage.test.ts renamed to scripts/design-conformance/controls/coverage.test.ts

@@ -1,12 +1,12 @@
 /** biome-ignore-all lint/suspicious/noTemplateCurlyInString: Fixtures contain proposed source text. */
 import { expect, test } from 'vitest'
-import { inspectControlAnalysis } from '#control-analysis/analysis'
-import type { ControlSource } from '#control-analysis/model'
-import { ReviewCollector } from '#control-analysis/review'
-import { productScope } from '#control-analysis/scope'
-import { extract } from '#design-conformance/extract'
-import { generateContracts } from '#design-conformance/generated-contracts'
-import { GitSource } from '#design-conformance/worktree-source'
+import { inspectControlAnalysis } from '#design-conformance/controls/analysis'
+import type { ControlSource } from '#design-conformance/controls/model'
+import { ReviewCollector } from '#design-conformance/controls/review'
+import { productScope } from '#design-conformance/controls/scope'
+import { GitSource } from '#design-conformance/shared/worktree-source'
+import { extract } from '#design-conformance/styling/extract'
+import { generateContracts } from '#design-conformance/system/generated-contracts'
 
 const globals = 'apps/sim/app/_styles/globals.css'
 const ui = 'apps/sim/components/example.tsx'

…design-conformance/control-imperative.ts …esign-conformance/controls/imperative.tsscripts/design-conformance/control-imperative.ts renamed to scripts/design-conformance/controls/imperative.ts scripts/design-conformance/control-imperative.ts renamed to scripts/design-conformance/controls/imperative.ts

@@ -2,7 +2,7 @@ import type { Binding, NodePath } from '@babel/traverse'
 import traverseModule from '@babel/traverse'
 import * as t from '@babel/types'
 import { type DefaultTreeAdapterMap, parseFragment } from 'parse5'
-import type { ControlInput } from '#control-analysis/inventory'
+import type { ControlInput } from '#design-conformance/controls/inventory'
 
 const traverse =
   typeof traverseModule === 'function'