@estiva-app/ui 0.19.0 → 0.21.0

package/src/gates/gate-config.ts

@@ -0,0 +1,78 @@
+/// <reference types="node" />
+/**
+ * Where the UI Guardrails' rules apply, written once (docs/GATES.md §23).
+ *
+ * Until UIG-10 every repo wrote this itself: `eslint.gates.js` (the rules and
+ * where they apply) and `eslint.gates.config.js` (the gate: those rules alone)
+ * in Peek, in Ship's `web/`, and here pointed inward. The rules were always the
+ * package's; these two files were copies. Now they are two functions.
+ *
+ * Where: every `.ts` and `.tsx` under `src`, stories included (a story is what
+ * people read and copy), tests not (a test mounts markup to test it) —
+ * Katerina's rulings of 13 September; `.ts` since UIG-8. This package's own
+ * inward set reads `.tsx` only, as it always has.
+ *
+ * A place that keeps something says why, on the line above:
+ * `// @estiva-escape: <reason>`, or `{/* @estiva-escape: <reason> *\/}` as a
+ * JSX child. Never `eslint-disable`: the count refuses it.
+ */
+import type { ESLint, Linter } from 'eslint'
+import betterTailwindcss from 'eslint-plugin-better-tailwindcss'
+import { parser as typescriptParser } from 'typescript-eslint'
+import estiva from '../eslint/index'
+import { TOKEN_LINT_IGNORES } from './token-lint'
+
+export interface GateConfigOptions {
+  /** `app` (the default) runs `configs.recommended`; `package` runs this package's inward set. */
+  audience?: 'app' | 'package'
+  /**
+   * Plugins whose `eslint-disable` directives appear in the source, registered
+   * here with every rule off. ESLint refuses a directive for a rule it does not
+   * know, so without them the gate would fail on another lint's comments.
+   * The token lint's names are registered already.
+   */
+  quiet?: Record<string, ESLint.Plugin>
+  /** Folders the gate never reads, beside build output. */
+  ignores?: string[]
+}
+
+/**
+ * The rules and where they apply — one config object, to add beside
+ * everything else an app's `eslint.config.js` runs, so an editor shows a
+ * refusal where the element is typed.
+ */
+export function gateLint({ audience = 'app' }: Pick<GateConfigOptions, 'audience'> = {}): Linter.Config {
+  return {
+    ...(audience === 'package' ? estiva.configs.package : estiva.configs.recommended),
+    files: audience === 'package' ? ['src/**/*.tsx'] : ['src/**/*.{ts,tsx}'],
+    ignores: ['**/*.test.ts', '**/*.test.tsx'],
+    languageOptions: {
+      parser: typescriptParser,
+      parserOptions: { ecmaFeatures: { jsx: true } },
+    },
+  }
+}
+
+/**
+ * The gate: the rules on their own — `npm run lint:rules`, CI's job `gate`, and
+ * the config the editor hook lints a proposed write with. It fails on a gate
+ * rule and on nothing else, so a backlog in the full lint never blocks it.
+ */
+export function gateConfig({ audience = 'app', quiet = {}, ignores = [] }: GateConfigOptions = {}): Linter.Config[] {
+  return [
+    { ignores: [...TOKEN_LINT_IGNORES, ...ignores] },
+    {
+      plugins: {
+        ...quiet,
+        'better-tailwindcss': betterTailwindcss,
+        'token-values': betterTailwindcss,
+        'token-spacing': betterTailwindcss,
+      },
+      // Every other config's directives are unused here, because their rules are
+      // off here. Reporting them would be this config complaining about the
+      // others' business.
+      linterOptions: { reportUnusedDisableDirectives: 'off' },
+    },
+    gateLint({ audience }),
+  ]
+}

package/src/gates/gates.test.ts

@@ -0,0 +1,183 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { ESLint, type Linter } from 'eslint'
+import { afterAll, describe, expect, it } from 'vitest'
+import { writeGateCount } from './count'
+import { gateConfig, gateLint } from './gate-config'
+import { runHook } from './hook'
+import { helpers, runStatus } from './status'
+import { tokenLint, tokenValues } from './token-lint'
+
+/**
+ * The gate pieces, as an app and this package use them (UIG-10, docs/GATES.md
+ * §23). Their equality with what Peek, Ship and this package ran before the
+ * move was proved by comparing the configs and every lint message; these tests
+ * hold the behaviour from here on.
+ *
+ * A config *file* is needed where ESLint loads one (the count, the hook): it
+ * imports the built `dist/gates`, which `npm test` builds first (`pretest`):
+ * the release job runs the tests with no lint before them. The app folder sits inside this repository, so it resolves ESLint and
+ * the plugins from this repository's `node_modules`, as an app resolves its own.
+ */
+const root = process.cwd()
+const built = pathToFileURL(join(root, 'dist', 'gates', 'index.js')).href
+const scratch = mkdtempSync(join(root, 'node_modules', '.gates-test-'))
+afterAll(() => rmSync(scratch, { recursive: true, force: true }))
+
+function app(name: string, files: Record<string, string>) {
+  const dir = join(scratch, name)
+  mkdirSync(join(dir, 'src'), { recursive: true })
+  writeFileSync(join(dir, 'package.json'), JSON.stringify({ name, private: true, type: 'module' }))
+  writeFileSync(join(dir, 'eslint.gates.config.js'), `import { gateConfig } from '${built}'\nexport default gateConfig()\n`)
+  for (const [rel, text] of Object.entries(files)) {
+    mkdirSync(join(dir, rel, '..'), { recursive: true })
+    writeFileSync(join(dir, rel), text)
+  }
+  return dir
+}
+
+async function lintWith(config: Linter.Config[], code: string, filePath: string) {
+  const eslint = new ESLint({ cwd: root, overrideConfigFile: true, overrideConfig: config })
+  const [result] = await eslint.lintText(code, { filePath: join(root, filePath) })
+  return result.messages
+}
+
+const component = (body: string) => `export function Probe() {\n  return ${body}\n}\n`
+
+describe('tokenLint and tokenValues', () => {
+  it('refuse a hand-written text size and name the token, in the words for an app', async () => {
+    const messages = await lintWith([tokenLint(), tokenValues()], component('<div className="text-[14px]">x</div>'), 'src/Probe.tsx')
+    const error = messages.find((m) => m.ruleId === 'token-values/no-restricted-classes')
+    expect(error?.severity).toBe(2)
+    expect(error?.message).toContain('text-body-2')
+  })
+
+  it('speak to the package when the package runs them', async () => {
+    const app = await lintWith([tokenLint(), tokenValues()], component('<div className="bg-gray-100 rounded-[3px]">x</div>'), 'src/Probe.tsx')
+    const pkg = await lintWith([tokenLint({ audience: 'package' }), tokenValues({ audience: 'package' })], component('<div className="bg-gray-100 rounded-[3px]">x</div>'), 'src/Probe.tsx')
+    expect(app.map((m) => m.message).join('\n')).toContain('from the package')
+    expect(pkg.map((m) => m.message).join('\n')).toContain('tailwind-preset.js')
+    expect(pkg.map((m) => m.ruleId)).toEqual(app.map((m) => m.ruleId))
+  })
+
+  it('report a hand-written height as a warning, never an error', async () => {
+    const messages = await lintWith([tokenLint(), tokenValues()], component('<div className="h-[240px]">x</div>'), 'src/Probe.tsx')
+    expect(messages.filter((m) => m.ruleId?.startsWith('token-'))).toEqual([expect.objectContaining({ ruleId: 'token-spacing/no-restricted-classes', severity: 1 })])
+  })
+
+  it('leave a test file to its test', async () => {
+    const messages = await lintWith([tokenLint(), tokenValues()], component('<div style={{ color: "red" }}>x</div>'), 'src/Probe.test.tsx')
+    expect(messages.filter((m) => m.severity === 2)).toEqual([])
+  })
+})
+
+describe('gateConfig', () => {
+  it('refuses a raw button in an app, in a .tsx and in a story, naming Button', async () => {
+    for (const file of ['src/Probe.tsx', 'src/stories/Probe.stories.tsx']) {
+      const messages = await lintWith(gateConfig(), component('<button type="button">x</button>'), file)
+      expect(messages).toEqual([expect.objectContaining({ ruleId: 'estiva/no-raw-element', severity: 2, message: expect.stringContaining('Button') })])
+    }
+  })
+
+  it('reads .ts for an app (UIG-8), and .tsx only for the package', async () => {
+    const listener = "export function listen() {\n  window.addEventListener('keydown', () => {})\n}\n"
+    expect(await lintWith(gateConfig(), listener, 'src/lib/probe.ts')).toEqual([expect.objectContaining({ ruleId: 'estiva/no-rebuilt-behaviour' })])
+    expect(gateLint({ audience: 'package' }).files).toEqual(['src/**/*.tsx'])
+  })
+
+  it('leaves tests alone', async () => {
+    const messages = await lintWith(gateConfig(), component('<button type="button">x</button>'), 'src/Probe.test.tsx')
+    expect(messages.filter((m) => m.ruleId)).toEqual([])
+  })
+
+  it('knows the token lint and quiet plugins, so their directives do not break the gate', async () => {
+    const code = `// eslint-disable-next-line token-values/no-restricted-classes -- @estiva-escape: a size the probe keeps on purpose\n${component('<div className="text-[14px]">x</div>')}`
+    expect(await lintWith(gateConfig(), code, 'src/Probe.tsx')).toEqual([])
+    const quiet = { rules: { 'some-rule': { create: () => ({}) } } }
+    const directive = `// eslint-disable-next-line house/some-rule\n${component('<div>x</div>')}`
+    expect(await lintWith(gateConfig({ quiet: { house: quiet } }), directive, 'src/Probe.tsx')).toEqual([])
+  })
+})
+
+describe('writeGateCount', () => {
+  it('writes the count once, leaves it alone when nothing changed, and fails on a rule switched off', async () => {
+    const dir = app('count', {
+      'src/Kept.tsx': component('(\n    // @estiva-escape: a probe that keeps its element on purpose\n    <form />\n  )'),
+    })
+    const first = await writeGateCount({ root: dir, repo: 'probe' })
+    expect(first.changed).toBe(true)
+    const written = JSON.parse(readFileSync(join(dir, '.gates-count.json'), 'utf8'))
+    expect(written).toMatchObject({ schemaVersion: 1, repo: 'probe' })
+    expect(written.rules['estiva/no-raw-element']).toEqual({ errors: 0, warnings: 0, escapes: 1 })
+    expect(Object.keys(written.rules)).toEqual(['estiva/no-raw-element', 'estiva/no-rebuilt-behaviour', 'estiva/no-restyled-part'])
+
+    expect((await writeGateCount({ root: dir, repo: 'probe' })).changed).toBe(false)
+
+    writeFileSync(join(dir, 'src', 'Off.tsx'), 'export function Probe() {\n  // eslint-disable-next-line estiva/no-raw-element\n  return <form />\n}\n')
+    const off = await writeGateCount({ root: dir, repo: 'probe' })
+    expect(off.failures.join('\n')).toContain('src/Off.tsx:3  estiva/no-raw-element'.replace('/', process.platform === 'win32' ? '\\' : '/'))
+  })
+})
+
+describe('runHook', () => {
+  const dir = app('hook', { 'src/Page.tsx': 'export function Page() {\n  return <div>x</div>\n}\n' })
+  const write = (file_path: string, content: string) => ({ tool_name: 'Write', tool_input: { file_path, content } })
+
+  it('refuses a raw button with exit 2 and the message naming Button', async () => {
+    const result = await runHook({ root: dir, input: write('src/Probe.tsx', component('<button type="button">x</button>')) })
+    expect(result.code).toBe(2)
+    expect(result.message).toContain('src/Probe.tsx was not written: the UI Guardrails refuse it (eslint.gates.config.js).')
+    expect(result.message).toContain('Button')
+  })
+
+  it('applies an Edit to the file on disk before judging it', async () => {
+    const edit = { tool_name: 'Edit', tool_input: { file_path: 'src/Page.tsx', old_string: '<div>x</div>', new_string: '<a href="/x">x</a>' } }
+    expect((await runHook({ root: dir, input: edit })).code).toBe(2)
+    const fine = { tool_name: 'Edit', tool_input: { file_path: 'src/Page.tsx', old_string: '<div>x</div>', new_string: '<div>y</div>' } }
+    expect((await runHook({ root: dir, input: fine })).code).toBe(0)
+  })
+
+  it('lets through a test, a declaration file, and anything outside src', async () => {
+    for (const path of ['src/Probe.test.tsx', 'src/types.d.ts', 'scripts/probe.tsx']) {
+      expect((await runHook({ root: dir, input: write(path, component('<button type="button">x</button>')) })).code).toBe(0)
+    }
+  })
+
+  it('finds the app in a folder of its own, as Ship keeps it in web/', async () => {
+    const top = join(scratch, 'top')
+    mkdirSync(top, { recursive: true })
+    const web = app('top/web', {})
+    expect(web).toBe(join(top, 'web'))
+    const result = await runHook({ root: top, app: 'web', input: write('web/src/Probe.tsx', component('<button type="button">x</button>')) })
+    expect(result.code).toBe(2)
+    expect(result.message).toContain('web/src/Probe.tsx was not written: the UI Guardrails refuse it (web/eslint.gates.config.js).')
+  })
+})
+
+describe('gates:status', () => {
+  it('reads a CI job by its id, a committed hook, and a script', () => {
+    const dir = app('status-helpers', {
+      '.github/workflows/deploy.yml': 'jobs:\n  check:\n    steps:\n      - run: npm test\n  gate:\n    steps:\n      # - run: npm run lint:rules\n      - run: npm run lint:rules\n',
+      '.claude/settings.json': JSON.stringify({ hooks: { PreToolUse: [{ matcher: 'Edit|Write', hooks: [{ type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/node_modules/@estiva-app/ui/dist/gates/cli.js" hook' }] }] } }),
+    })
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'status-helpers', scripts: { 'gates:status': 'estiva-gates status' } }))
+    const h = helpers(dir)
+    expect(h.ciJob('gate', 'lint:rules').result).toBe('pass')
+    expect(h.ciJob('check', 'lint:rules').result).toBe('fail')
+    expect(h.hook('.claude/settings.json', 'gates').result).toBe('pass')
+    expect(h.script('package.json', 'gates:status').result).toBe('pass')
+  })
+
+  it('prints a repo on its own: its own rows, then its parts', async () => {
+    const dir = app('status-run', {
+      'scripts/gates-checks.mjs': "export default (h) => ({ repo: 'probe', tickets: [\n  { ref: 'UIG-2', title: 'Rails', owner: false, checks: [{ what: 'wired', run: () => h.PASS('yes') }] },\n  { ref: 'UIG-9', title: 'Allow-list', owner: false, checks: [{ what: 'a look is refused', run: () => h.FAIL('no') }] },\n] })\n",
+    })
+    const out = await runStatus({ root: dir })
+    expect(out).toContain('Tickets probe owns (0):')
+    expect(out).toContain('✅  UIG-2')
+    expect(out).toContain('⬜  UIG-9')
+    const json = JSON.parse(await runStatus({ root: dir, json: true }))
+    expect(json.engine).toMatch(/^@estiva-app\/ui@\d+\.\d+\.\d+$/)
+  })
+})

package/src/gates/hook.ts

@@ -0,0 +1,111 @@
+/// <reference types="node" />
+/**
+ * The editor gate: before Claude writes a `.ts` or `.tsx` under `src/`, lint the
+ * text it is about to write with the gate, and refuse the write on an error.
+ * Written once (docs/GATES.md §23): until UIG-10 Peek, Ship and this package
+ * each carried their own copy of this script.
+ *
+ * A `PreToolUse` hook in the repository's committed `.claude/settings.json`
+ * runs it. Claude Code documents exit 2 as blocking the tool call, with stderr
+ * handed back to Claude; exit 0 raises no objection. It reads
+ * `$CLAUDE_PROJECT_DIR`, the project root where the session started — a session
+ * started in a folder above or below the repository gets no hook (UIG-3,
+ * UIG-4 findings).
+ *
+ * It runs the gate's own config and reimplements nothing: a hook and a lint
+ * that could disagree would be worse than neither. Tests are not checked
+ * (Katerina, 13 September); stories are. This package's inward gate reads `.tsx`
+ * only, as its lint does.
+ *
+ * Input, from Claude Code on stdin: `tool_name` and `tool_input` — `file_path`
+ * and `content` for Write; `file_path`, `old_string`, `new_string` and
+ * `replace_all` for Edit. An Edit carries no whole file, so the edit is applied
+ * to the file on disk here. Anything it cannot read passes, and the tool itself
+ * reports its own failure.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import type { ESLint as ESLintClass } from 'eslint'
+import { countGates } from '../eslint/index'
+
+export interface HookOptions {
+  /** The repository's top folder. Defaults to `$CLAUDE_PROJECT_DIR`, then the tool call's `cwd`. */
+  root?: string
+  /** The folder that holds the app, relative to `root`: `web` in Ship, `.` elsewhere. */
+  app?: string
+  /** `package` gates `.tsx` only, as this package's inward lint does. */
+  audience?: 'app' | 'package'
+  /** The hook's input, when not read from stdin (tests). */
+  input?: unknown
+}
+
+export interface HookResult {
+  /** 0 lets the write through; 2 refuses it. */
+  code: 0 | 2
+  /** What goes to stderr when refused. */
+  message: string
+}
+
+interface ToolCall {
+  tool_name?: string
+  cwd?: string
+  tool_input?: { file_path?: unknown; content?: unknown; old_string?: unknown; new_string?: unknown; replace_all?: unknown }
+}
+
+const PASS: HookResult = { code: 0, message: '' }
+
+export async function runHook({ root, app = '.', audience = 'app', input }: HookOptions = {}): Promise<HookResult> {
+  let call: ToolCall
+  try {
+    call = (input ?? JSON.parse(readFileSync(0, 'utf8'))) as ToolCall
+  } catch {
+    return PASS
+  }
+  const args = call.tool_input ?? {}
+  if (typeof args.file_path !== 'string') return PASS
+
+  const top = root ?? process.env.CLAUDE_PROJECT_DIR ?? call.cwd ?? process.cwd()
+  const appDir = resolve(top, app)
+  const file = isAbsolute(args.file_path) ? args.file_path : resolve(call.cwd ?? top, args.file_path)
+  const rel = relative(appDir, file).split(sep).join('/')
+  const source = audience === 'package' ? /^src\/.+\.tsx$/ : /^src\/.+\.tsx?$/
+  if (rel.startsWith('../') || isAbsolute(rel) || !source.test(rel) || /\.test\.tsx?$/.test(rel) || /\.d\.ts$/.test(rel)) return PASS
+
+  const text = proposed(call.tool_name, args, file)
+  if (text === null) return PASS
+
+  // ESLint from the app's own install: in Ship the top folder has none.
+  const resolved = createRequire(join(appDir, 'package.json')).resolve('eslint')
+  const { ESLint } = (await import(pathToFileURL(resolved).href)) as { ESLint: typeof ESLintClass }
+  const config = join(appDir, 'eslint.gates.config.js')
+  const eslint = new ESLint({ cwd: appDir, overrideConfigFile: config })
+  const results = await eslint.lintText(text, { filePath: file })
+  // A rule's errors only. Code that does not parse yet (one edit of several) is
+  // the typecheck's to judge; the gate looks again at the edit that completes it.
+  const errors = results.flatMap((r) => r.messages.filter((m) => m.severity === 2 && m.ruleId))
+  const { disabled } = countGates(results)
+  if (errors.length === 0 && disabled.length === 0) return PASS
+
+  const shown = (p: string) => relative(top, p).split(sep).join('/')
+  const lines = [`${shown(file)} was not written: the UI Guardrails refuse it (${shown(config)}).`]
+  for (const m of errors) lines.push(`  ${m.line}:${m.column}  ${m.message}${m.ruleId ? `  (${m.ruleId})` : ''}`)
+  const keep = audience === 'package' ? 'Keep it only' : 'Keep the element only'
+  for (const d of disabled) lines.push(`  ${d.line}  an eslint-disable switches ${d.ruleId} off. ${keep} with its reason on the line above: // @estiva-escape: <reason>`)
+  return { code: 2, message: `${lines.join('\n')}\n` }
+}
+
+/** The file as it will be after this tool call, or null when that cannot be known. */
+function proposed(tool: string | undefined, args: NonNullable<ToolCall['tool_input']>, file: string): string | null {
+  if (tool === 'Write') return typeof args.content === 'string' ? args.content : null
+  if (tool !== 'Edit' || typeof args.old_string !== 'string' || typeof args.new_string !== 'string') return null
+  const { old_string: from, new_string: to } = args
+  const current = existsSync(file) ? readFileSync(file, 'utf8') : ''
+  // A checkout on Windows has CRLF on disk; an edit is written with LF.
+  for (const text of [current, current.replace(/\r\n/g, '\n')]) {
+    if (!text.includes(from)) continue
+    return args.replace_all === true ? text.split(from).join(to) : text.replace(from, () => to)
+  }
+  return null
+}

package/src/gates/index.ts

@@ -0,0 +1,30 @@
+/// <reference types="node" />
+/**
+ * `@estiva-app/ui/gates` — everything an app needs to run the UI Guardrails'
+ * gates, shipped once (docs/GATES.md §23, Katerina's ruling of 17 September).
+ *
+ * The rules were always here, in `@estiva-app/ui/eslint`. The pieces that
+ * switch them on were copied into every repo from UIG-3 on; UIG-10 moved them
+ * here, and an app imports them:
+ *
+ * - `tokenLint`, `tokenValues` — the token contract's lint settings (UIG-28).
+ * - `gateLint`, `gateConfig` — where the rules apply, and the gate that runs them alone.
+ * - `writeGateCount` — `.gates-count.json` (seam S3).
+ * - `runHook` — the editor gate a `PreToolUse` hook runs.
+ * - `runStatus`, `helpers` — gates:status and the helpers a checks file is written with.
+ *
+ * - `appChecks` — the gate checks every app runs, for its `scripts/gates-checks.mjs`.
+ * - `appFiles`, `createApp`, `themes` — a new app with every gate on (`create-estiva-app`).
+ *
+ * `estiva-gates` (`cli.ts`) runs the count, the hook and the status as one command.
+ *
+ * Built by build.mjs into `dist/gates/`, for Node. Nothing here reaches the
+ * components' browser bundle.
+ */
+export { TOKEN_LINT_IGNORES, tokenLint, tokenValues, type TokenAudience, type TokenLintOptions } from './token-lint'
+export { gateConfig, gateLint, type GateConfigOptions } from './gate-config'
+export { writeGateCount, type CountOptions, type CountResult } from './count'
+export { runHook, type HookOptions, type HookResult } from './hook'
+export { ENGINE, helpers, runStatus, type CheckResult, type GateCheck, type GateHelpers, type GateSpec, type GateTicket, type LintProbe, type StatusOptions, type TicketListEntry } from './status'
+export { APP_TICKET_TITLES, appChecks, type AppCheckOptions } from './app-checks'
+export { appFiles, askNpm, createApp, themes, type CreateAppOptions } from './create-app'