@qijenchen/design-system 0.1.0-beta.13 → 0.1.0-beta.130

package/src/tokens/utility-registry.schema.json

@@ -0,0 +1,409 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://qijenchen.dev/schemas/design-system/utility-registry-v1.json",
+  "title": "Design-system utility policy registry",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "$schema",
+    "schemaVersion",
+    "_meta",
+    "enforcement",
+    "typography",
+    "radius",
+    "opacity",
+    "elevation",
+    "spacing",
+    "sizing",
+    "shadcn_alias",
+    "primitive_color_as_utility"
+  ],
+  "properties": {
+    "$schema": { "const": "./utility-registry.schema.json" },
+    "schemaVersion": { "const": 1 },
+    "_meta": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "purpose",
+        "owner",
+        "consumed_by",
+        "provider_view_policy",
+        "spec_sources",
+        "rationale",
+        "exceptions"
+      ],
+      "properties": {
+        "purpose": { "$ref": "#/$defs/nonEmptyString" },
+        "owner": {
+          "const": "packages/design-system/src/tokens/utility-registry.json"
+        },
+        "consumed_by": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/canonicalReference" }
+        },
+        "provider_view_policy": { "$ref": "#/$defs/nonEmptyString" },
+        "spec_sources": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/nonEmptyString" }
+        },
+        "rationale": { "$ref": "#/$defs/nonEmptyString" },
+        "exceptions": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "_added",
+            "anatomy_stories_inspector",
+            "token_stories_section_label",
+            "principles_stories_codepre",
+            "icon_as_text_and_numeric_in_circle"
+          ],
+          "properties": {
+            "_added": { "$ref": "#/$defs/nonEmptyString" },
+            "anatomy_stories_inspector": {
+              "allOf": [
+                { "$ref": "#/$defs/exceptionBase" },
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["scope", "allowed_utilities", "rationale", "audit_dim_53_fix"],
+                  "properties": {
+                    "scope": { "$ref": "#/$defs/nonEmptyString" },
+                    "allowed_utilities": { "$ref": "#/$defs/tokenArray" },
+                    "rationale": { "$ref": "#/$defs/nonEmptyString" },
+                    "audit_dim_53_fix": { "$ref": "#/$defs/nonEmptyString" }
+                  }
+                }
+              ]
+            },
+            "token_stories_section_label": { "$ref": "#/$defs/standardException" },
+            "principles_stories_codepre": { "$ref": "#/$defs/standardException" },
+            "icon_as_text_and_numeric_in_circle": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "scope",
+                "allowed_utilities",
+                "rule_one_liner",
+                "rationale",
+                "current_consumers",
+                "non_goal"
+              ],
+              "properties": {
+                "scope": { "$ref": "#/$defs/nonEmptyString" },
+                "allowed_utilities": { "$ref": "#/$defs/tokenArray" },
+                "rule_one_liner": { "$ref": "#/$defs/nonEmptyString" },
+                "rationale": { "$ref": "#/$defs/nonEmptyString" },
+                "current_consumers": {
+                  "type": "array",
+                  "minItems": 1,
+                  "uniqueItems": true,
+                  "items": { "$ref": "#/$defs/nonEmptyString" }
+                },
+                "non_goal": { "$ref": "#/$defs/nonEmptyString" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "enforcement": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "engine", "block", "warn"],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "engine": { "const": "utility-registry-rules-v1" },
+        "block": {
+          "type": "array",
+          "minItems": 18,
+          "maxItems": 18,
+          "items": { "$ref": "#/$defs/enforcementRule" }
+        },
+        "warn": {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 2,
+          "items": { "$ref": "#/$defs/enforcementRule" }
+        }
+      }
+    },
+    "typography": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["allow", "block"],
+      "properties": {
+        "allow": { "$ref": "#/$defs/tokenArray" },
+        "block": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "size_raw",
+            "weight_raw",
+            "leading_numeric",
+            "tracking_raw",
+            "tracking_raw_rationale",
+            "inline_style",
+            "rationale_path"
+          ],
+          "properties": {
+            "size_raw": { "$ref": "#/$defs/tokenArray" },
+            "weight_raw": { "$ref": "#/$defs/tokenArray" },
+            "leading_numeric": { "$ref": "#/$defs/nonEmptyString" },
+            "tracking_raw": { "$ref": "#/$defs/tokenArray" },
+            "tracking_raw_rationale": { "$ref": "#/$defs/nonEmptyString" },
+            "inline_style": { "$ref": "#/$defs/nonEmptyString" },
+            "rationale_path": { "$ref": "#/$defs/nonEmptyString" }
+          }
+        }
+      }
+    },
+    "radius": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["allow", "allow_note", "block"],
+      "properties": {
+        "allow": { "$ref": "#/$defs/tokenArray" },
+        "allow_note": { "$ref": "#/$defs/nonEmptyString" },
+        "block": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "out_of_range",
+            "ambiguous_default",
+            "arbitrary_value",
+            "inline_style",
+            "rationale_path"
+          ],
+          "properties": {
+            "out_of_range": { "$ref": "#/$defs/tokenArray" },
+            "ambiguous_default": { "$ref": "#/$defs/tokenArray" },
+            "arbitrary_value": { "$ref": "#/$defs/tokenArray" },
+            "inline_style": { "$ref": "#/$defs/nonEmptyString" },
+            "rationale_path": { "$ref": "#/$defs/nonEmptyString" }
+          }
+        }
+      }
+    },
+    "opacity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["allow", "block"],
+      "properties": {
+        "allow": { "$ref": "#/$defs/tokenArray" },
+        "block": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["numeric_tier", "arbitrary_value", "rationale_path", "philosophy"],
+          "properties": {
+            "numeric_tier": { "$ref": "#/$defs/tokenArray" },
+            "arbitrary_value": { "$ref": "#/$defs/nonEmptyString" },
+            "rationale_path": { "$ref": "#/$defs/nonEmptyString" },
+            "philosophy": { "$ref": "#/$defs/nonEmptyString" }
+          }
+        }
+      }
+    },
+    "elevation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["allow", "block"],
+      "properties": {
+        "allow": { "$ref": "#/$defs/tokenArray" },
+        "block": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["tailwind_size", "rationale_path", "philosophy"],
+          "properties": {
+            "tailwind_size": { "$ref": "#/$defs/tokenArray" },
+            "rationale_path": { "$ref": "#/$defs/nonEmptyString" },
+            "philosophy": { "$ref": "#/$defs/nonEmptyString" }
+          }
+        }
+      }
+    },
+    "spacing": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["allow_canonical", "canonical_micro_geometry", "warn"],
+      "properties": {
+        "allow_canonical": { "$ref": "#/$defs/nonEmptyString" },
+        "canonical_micro_geometry": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "gap_utilities",
+            "alignment_utilities",
+            "inline_display_utilities",
+            "phrasing_elements",
+            "list_container_elements",
+            "list_item_elements",
+            "list_roles",
+            "control_roles",
+            "field_group_elements",
+            "field_group_roles",
+            "field_control_elements",
+            "nearby_line_limit",
+            "rationale",
+            "rationale_path"
+          ],
+          "properties": {
+            "gap_utilities": { "$ref": "#/$defs/tokenArray" },
+            "alignment_utilities": { "$ref": "#/$defs/tokenArray" },
+            "inline_display_utilities": { "$ref": "#/$defs/tokenArray" },
+            "phrasing_elements": { "$ref": "#/$defs/tokenArray" },
+            "list_container_elements": { "$ref": "#/$defs/tokenArray" },
+            "list_item_elements": { "$ref": "#/$defs/tokenArray" },
+            "list_roles": { "$ref": "#/$defs/tokenArray" },
+            "control_roles": { "$ref": "#/$defs/tokenArray" },
+            "field_group_elements": { "$ref": "#/$defs/tokenArray" },
+            "field_group_roles": { "$ref": "#/$defs/tokenArray" },
+            "field_control_elements": { "$ref": "#/$defs/tokenArray" },
+            "nearby_line_limit": { "type": "integer", "minimum": 1, "maximum": 32 },
+            "rationale": { "$ref": "#/$defs/nonEmptyString" },
+            "rationale_path": { "$ref": "#/$defs/nonEmptyString" }
+          }
+        },
+        "warn": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["micro_gap", "rationale"],
+          "properties": {
+            "micro_gap": { "$ref": "#/$defs/tokenArray" },
+            "rationale": { "$ref": "#/$defs/nonEmptyString" }
+          }
+        }
+      }
+    },
+    "sizing": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["warn"],
+      "properties": {
+        "warn": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["fraction", "rationale"],
+          "properties": {
+            "fraction": { "$ref": "#/$defs/tokenArray" },
+            "rationale": { "$ref": "#/$defs/nonEmptyString" }
+          }
+        }
+      }
+    },
+    "shadcn_alias": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["block"],
+      "properties": {
+        "block": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["color_alias", "rationale", "rationale_path"],
+          "properties": {
+            "color_alias": { "$ref": "#/$defs/tokenArray" },
+            "rationale": { "$ref": "#/$defs/nonEmptyString" },
+            "rationale_path": { "$ref": "#/$defs/nonEmptyString" }
+          }
+        }
+      }
+    },
+    "primitive_color_as_utility": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["block"],
+      "properties": {
+        "block": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["primitive_class", "rationale"],
+          "properties": {
+            "primitive_class": { "$ref": "#/$defs/tokenArray" },
+            "rationale": { "$ref": "#/$defs/nonEmptyString" }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "nonEmptyString": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[^\\u0000-\\u001F\\u007F]+$"
+    },
+    "canonicalReference": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!\\.claude(?:/|$)|\\.agents(?:/|$)|\\.codex(?:/|$))(?!/)(?!.*(?:^|/)\\.\\.?/)(?!.*\\\\)[A-Za-z0-9_.@/#-]+(?: [A-Za-z0-9_.@/#()-]+)*$"
+    },
+    "tokenArray": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "^[^\\s\\u0000-\\u001F\\u007F]+$"
+      }
+    },
+    "exceptionBase": {
+      "type": "object"
+    },
+    "standardException": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["scope", "allowed_utilities", "rationale"],
+      "properties": {
+        "scope": { "$ref": "#/$defs/nonEmptyString" },
+        "allowed_utilities": { "$ref": "#/$defs/tokenArray" },
+        "rationale": { "$ref": "#/$defs/nonEmptyString" }
+      }
+    },
+    "enforcementRule": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "label", "tokenListPointer"],
+          "properties": {
+            "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+            "label": { "$ref": "#/$defs/nonEmptyString" },
+            "tokenListPointer": {
+              "enum": [
+                "/typography/block/size_raw",
+                "/typography/block/weight_raw",
+                "/typography/block/tracking_raw",
+                "/radius/block/out_of_range",
+                "/radius/block/ambiguous_default",
+                "/radius/block/arbitrary_value",
+                "/opacity/block/numeric_tier",
+                "/elevation/block/tailwind_size",
+                "/shadcn_alias/block/color_alias",
+                "/primitive_color_as_utility/block/primitive_class",
+                "/spacing/warn/micro_gap",
+                "/sizing/warn/fraction"
+              ]
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "label", "pattern"],
+          "properties": {
+            "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+            "label": { "$ref": "#/$defs/nonEmptyString" },
+            "pattern": { "$ref": "#/$defs/nonEmptyString" },
+            "excludeTokenListPointer": {
+              "enum": ["/radius/allow", "/opacity/allow"]
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/tools/README.md

@@ -0,0 +1,9 @@
+# Design-system migration tools
+
+This directory is shipped inside `@qijenchen/design-system`; it is the provider-neutral runtime for versioned API codemods and reviewed visual-baseline updates. Claude, Codex, hosted environments, and future models call the same package binaries and therefore do not own parallel migration logic.
+
+- `codemods/`: exact TypeScript AST binding, versioned migration plans, manual blockers, digest-bound check/apply, and rollback-safe pathname publication.
+- `visual-baseline/`: full PNG decode/CRC validation, content-addressed image statements, signed human or activated managed-broker review, and `apply-reviewed` without Git mutation.
+- `shared/`: no-link path validation and the common exclusive transaction/rollback primitive.
+
+The transaction claim is limited to cooperating writers that honor the same lock plus observed per-file pathname CAS. These tools do not claim parent-directory-swap resistance, storage power-loss durability, or protection from a non-cooperative writer that retains an old open file descriptor.

package/tools/codemods/cli.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync } from 'node:fs'
+import { relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  BETA_84_MIGRATION_ID,
+  applyCodemodProposal,
+  checkCodemodProposal,
+  planCodemod,
+} from './index.mjs'
+import { canonicalJson, writeAtomicFile } from '../shared/safe-filesystem.mjs'
+
+function fail(message) {
+  throw new Error(`design-system codemod CLI blocked:${message}`)
+}
+
+function parse(argv) {
+  const [migrationId, command, ...tokens] = argv
+  if (migrationId !== BETA_84_MIGRATION_ID) fail(`first argument must be ${BETA_84_MIGRATION_ID}`)
+  if (!['plan', 'check', 'apply'].includes(command)) fail('command must be plan, check, or apply')
+  const options = { migrationId, command, root: '.', sources: [], output: null, proposal: null, expectedDigest: null }
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index]
+    const next = () => {
+      const value = tokens[++index]
+      if (!value || value.startsWith('--')) fail(`${token} requires a value`)
+      return value
+    }
+    if (token === '--root') options.root = next()
+    else if (token === '--source') options.sources.push(next())
+    else if (token === '--output') options.output = next()
+    else if (token === '--proposal') options.proposal = next()
+    else if (token === '--expected-proposal-digest') options.expectedDigest = next()
+    else fail(`unknown option:${token}`)
+  }
+  return options
+}
+
+function relativeOutput(root, value) {
+  const absoluteRoot = resolve(root)
+  const absolute = resolve(absoluteRoot, value)
+  const path = relative(absoluteRoot, absolute)
+  if (!path || path === '..' || path.startsWith(`..${sep}`)) fail('output must be a file below --root')
+  return path.split(sep).join('/')
+}
+
+function readProposal(root, value) {
+  if (!value) fail('--proposal is required')
+  const absolute = resolve(root, value)
+  let proposal
+  try { proposal = JSON.parse(readFileSync(absolute, 'utf8')) } catch (error) { fail(`proposal is unavailable or invalid JSON:${error.message}`) }
+  return proposal
+}
+
+export function runCodemodCli(argv = process.argv.slice(2)) {
+  const options = parse(argv)
+  if (options.command === 'plan') {
+    if (options.proposal || options.expectedDigest) fail('plan does not accept apply/check evidence options')
+    const proposal = planCodemod({ repoRoot: options.root, sourceRoots: options.sources.length ? options.sources : ['.'] })
+    const body = Buffer.from(canonicalJson(proposal))
+    if (options.output) writeAtomicFile(resolve(options.root), relativeOutput(options.root, options.output), body, 'codemod proposal', fail)
+    else process.stdout.write(body)
+    if (proposal.blockers.length) {
+      process.stderr.write(`codemod blocked: ${proposal.blockers.length} manual blocker(s); proposal ${proposal.proposalDigest}\n`)
+      return 2
+    }
+    if (options.output) process.stdout.write(`${canonicalJson({ proposalDigest: proposal.proposalDigest, files: proposal.files.length, output: options.output })}`)
+    return 0
+  }
+  if (options.sources.length || options.output) fail(`${options.command} does not accept --source or --output`)
+  const proposal = readProposal(options.root, options.proposal)
+  const result = options.command === 'check'
+    ? checkCodemodProposal({ repoRoot: options.root, proposal })
+    : applyCodemodProposal({ repoRoot: options.root, proposal, expectedProposalDigest: options.expectedDigest })
+  process.stdout.write(canonicalJson(result))
+  return 0
+}
+
+function isMainModule(argvPath = process.argv[1]) {
+  if (!argvPath) return false
+  try {
+    return realpathSync(argvPath) === realpathSync(fileURLToPath(import.meta.url))
+  } catch {
+    return resolve(argvPath) === resolve(fileURLToPath(import.meta.url))
+  }
+}
+
+if (isMainModule()) {
+  try { process.exitCode = runCodemodCli() } catch (error) {
+    console.error(error.message)
+    process.exitCode = 1
+  }
+}