hanzo.ai/scripts/consumers.mjs

#!/usr/bin/env node
/**
 * Every rule this site's stylesheets declare has a consumer, as a number that
 * may only go down.
 *
 *   node scripts/consumers.mjs           # print the orphans
 *   node scripts/consumers.mjs --write   # record them in orphans.json
 *   node scripts/consumers.mjs --check   # fail on any new one
 *
 * WHY THIS EXISTS. Plain CSS is where styling lands when it is neither a gui prop
 * nor a token, and that is the right place for it — a utility vocabulary of our
 * own would just be Tailwind wearing our name. What a global stylesheet cannot do
 * is notice when a rule's LAST consumer leaves: it has no importer, so a class
 * outlives the component that wore it and nothing errors, nothing warns, and the
 * bytes ship forever.
 *
 * WHAT CHANGED WITH THE PREFIX. This gate used to find its subject by grepping
 * for `hz-`, and it found a wearer the same way — the string anywhere in a file.
 * Both halves moved to scripts/names.mjs, which reads the sheets for what they
 * DECLARE and reads a file for what it WEARS in class position. The second half
 * is not a tidy-up but the condition of the first: `run`, `more`, `title` and
 * `action` are ordinary words, and a raw grep for them matches prose, imports and
 * identifiers, so a gate that kept the old scan against the new names would have
 * reported every rule worn forever and passed because it COULD NOT FAIL.
 *
 * Reading class position instead costs a real reader, not a tighter regex, and
 * `rate-wide` is why. It is applied as `className={c.wide ? 'rate-wide' : …}` in
 * components/pricing/kit.tsx, and a reader that wants a quote right after the `=`
 * finds none — so the first version of this gate called a live rule an orphan,
 * which is the one mistake it must never make: the instruction it prints is to
 * delete the rule. names.mjs reads through the braces for that reason.
 *
 * Measured after the rename: 53 rules declared, 53 worn, none orphaned.
 *
 * NODE_MODULES IS A CONSUMER, and forgetting that is how this gate would be wrong.
 * `hz-mono`, `hz-tnum` and `hz-row` are @hanzo/ui's interface to its HOST: the
 * package writes the class and expects our sheet to carry the rule. They keep the
 * prefix precisely because they are the package's names, not ours. Scanning only
 * our own source reports them dead and invites a delete that breaks the component
 * library.
 *
 * A ratchet, not a deadline, for the same reason tailwind-floor.mjs is one: the
 * orphans that exist are a decision each, and a gate that demands they all go
 * today gets turned off. This one only refuses NEW ones.
 */
import { readFileSync, writeFileSync, readdirSync, statSync, existsSync } from 'node:fs'
import { join, extname } from 'node:path'
import { names, classes, SHEETS } from './names.mjs'

const LEDGER = 'orphans.json'
// Where a class can be WORN. node_modules is deliberate — see the header.
const CONSUMERS = ['app', 'components', 'lib', 'content', 'e2e', 'node_modules/@hanzo', 'node_modules/@hanzogui']
const WEARABLE = new Set(['.tsx', '.ts', '.jsx', '.js', '.mjs', '.md', '.mdx', '.html', '.css'])

const walk = (dir, out = []) => {
  let entries
  try { entries = readdirSync(dir) } catch { return out }
  for (const e of entries) {
    if (e === 'node_modules' && !dir.includes('node_modules')) continue
    const p = join(dir, e)
    let st
    try { st = statSync(p) } catch { continue }
    if (st.isDirectory()) walk(p, out)
    else if (WEARABLE.has(extname(p))) out.push(p)
  }
  return out
}

const defined = names()

const worn = new Set()
for (const root of CONSUMERS) {
  if (!existsSync(root)) continue
  for (const file of walk(root)) {
    if (SHEETS.some(s => file.endsWith(s))) continue
    let text
    try { text = readFileSync(file, 'utf8') } catch { continue }
    for (const c of classes(text)) worn.add(c)
  }
}

const orphans = [...defined].filter(c => !worn.has(c)).sort()

const write = process.argv.includes('--write')
const check = process.argv.includes('--check')
const prior = existsSync(LEDGER) ? JSON.parse(readFileSync(LEDGER, 'utf8')).orphans ?? [] : []

console.log(`rules: ${defined.size} defined, ${defined.size - orphans.length} worn, ${orphans.length} orphaned`)
for (const c of orphans) console.log(`  .${c}`)

if (write) {
  writeFileSync(LEDGER, JSON.stringify({ orphans, note: 'may only shrink — see scripts/consumers.mjs' }, null, 2) + '\n')
  console.log(`\n>> recorded ${orphans.length} in ${LEDGER}`)
} else if (check) {
  const fresh = orphans.filter(c => !prior.includes(c))
  const fixed = prior.filter(c => !orphans.includes(c))
  if (fresh.length) {
    console.error(`\n${fresh.length} rule(s) lost their last consumer:`)
    for (const c of fresh) console.error(`  .${c}  — delete the rule, or give it a caller`)
    process.exit(1)
  }
  if (fixed.length) {
    console.error(`\n${fixed.length} orphan(s) resolved — run --write so the ratchet holds the gain:`)
    for (const c of fixed) console.error(`  .${c}`)
    process.exit(1)
  }
  console.log('\n>> every rule has a consumer, or is a recorded orphan')
}