@ztd-me/frontend-checks 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# @ztd-me/frontend-checks
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Native CSS and Playwright accessibility checks. Requires Node >=22.14 and Playwright Test ^1.62.0. Version `0.1.0` is prepared for public npm publication through automatic staging and owner 2FA promotion. See [publishing](docs/publishing.md) and [CLI integration](https://github.com/zeithrold/tools/blob/main/docs/frontend-tooling.md). Consumers retain `@ztd-me/eslint@0.1.1` and its strict standards.
+
+After promotion and verified public installation:
+
+```sh
+pnpm add -D --save-exact @ztd-me/frontend-checks@0.1.0 @playwright/test@1.62.0
+pnpm exec playwright install chromium
+```
+
+Retain the consuming project's release-age, trust and build policy. Wait if a newly promoted release is not yet eligible. The `0.0.0-stage` placeholder for a new package is not a usable helper release.
+
+## CSS
+
+```js
+// css-check.config.mjs
+export default {
+  files: ['src/**/*.css'],
+  tokenFiles: ['node_modules/tailwindcss/theme.css'],
+  externalCustomProperties: [],
+}
+```
+
+```sh
+pnpm exec ztd-css ./css-check.config.mjs
+```
+
+The config module is reviewed project code and executes during import. `checkCss(options)` is also exported from `@ztd-me/frontend-checks/css`. Every supplied glob must match; missing files and syntax/configuration errors fail. JSON findings print to stdout; a nonzero exit fails the gate. Under `zt check`, the CLI also writes `css.json` to `ZT_ARTIFACTS_DIR`.
+
+Stylelint 17.15 / standard 40 provide native CSS validation; only documented Tailwind directives and `--alpha`/`--spacing` functions receive syntax allowances. Undefined `var()` references fail across the supplied files/declaration sources, even with fallbacks. Exact runtime-generated variables can be declared in `externalCustomProperties`; document their owner in the project contract. Imports are not resolved automatically. Neither Sass/Less nor embedded Vue styles are parsed by this CSS-only entrypoint.
+
+Hex, named and CSS color-function paint literals outside custom-property definitions fail. Token definitions retain each project's values. `transparent`, `currentColor`, inheritance and URLs are allowed. This check covers declarations, not Tailwind arbitrary-value classes, inline JS styles or every possible CSS color expression. An inventory definition is not proof of cascade/theme availability; render the relevant states. No autofix rewrites token values.
+
+## Playwright
+
+```js
+import { defineConfig } from '@playwright/test'
+import { verificationArtifacts } from '@ztd-me/frontend-checks/playwright'
+
+const artifacts = verificationArtifacts()
+export default defineConfig({
+  ...artifacts,
+  webServer: existingWebServer,
+  projects: existingProjects,
+  use: { ...artifacts.use, baseURL: existingBaseURL },
+})
+```
+
+```js
+import { test } from '@playwright/test'
+import { assertAccessible, captureState } from '@ztd-me/frontend-checks/playwright'
+
+test('translated dialog', async ({ page }, info) => {
+  await page.goto('/settings')
+  // Establish the real dialog state using project locators and interactions.
+  await assertAccessible(page, info, { label: 'settings-dialog' })
+  await captureState(page, info, 'settings-dialog')
+})
+```
+
+`assertAccessible` uses Axe 4.13 and defaults to WCAG 2 A/AA, 2.1 AA and 2.2 AA tags. It attaches the complete scan before asserting zero violations. Optional `include` scopes a supplemental scan; optional nonempty `tags` changes the selected coverage and must be justified locally. Full-page and keyboard/focus tests remain necessary. Projects own routes, states, browser matrices, service mocks and the built-Worker server. This helper does not provision or start them.
+
+`verificationArtifacts(root?)` provides HTML/JSON reports, test attachments, failure traces/screenshots/videos. The root defaults to `ZT_ARTIFACTS_DIR`, otherwise `.zt/browser`. Merge with existing config; preserve native server/projects/use settings. `captureState` attaches a named PNG for review without maintaining screenshot baselines.
+
+## Verification
+
+```sh
+pnpm install --frozen-lockfile
+pnpm exec playwright install chromium
+pnpm run check
+```
+
+Tests execute native CSS parsing/lint, real Chromium Axe/keyboard/dialog behavior, a deliberate accessibility failure, typed imports, fresh tarball installation/CLI use, and stage authorization/duplicate guards. The workspace keeps release-age/trust policy and only the previously approved exact ESLint 0.1.1 / semver 6.3.1 exceptions. Fresh consumers use strict 24-hour release age with no exceptions. After promotion, `test:registry` verifies registry integrity against the reviewed tarball and repeats consumer import/type/CLI/browser checks; a metadata lookup alone is insufficient.

package/docs/publishing.md

@@ -0,0 +1,40 @@
+# Public stage-only release
+
+`@ztd-me/frontend-checks@0.1.0` is prepared for authorized public publication. `.github/workflows/publish-frontend.yml` runs automatically on relevant pushes to `main`. It uses pnpm 11.22.0, frozen installation, strict lint, declarations, CSS fixtures, Chromium tests and fresh packed-consumer checks on Node 22 and 24. The Node 24 job packs the tested bytes and records the immutable source SHA and checksums. A separate job verifies those checksums and source identity before staging that exact tarball. It never directly publishes or promotes a version.
+
+The existing repository `NPM_TOKEN` secret is the authorized route. It must permit Read and write (stage only) for this package under `@ztd-me`, with Bypass 2FA disabled. Its actual scope for this new package cannot be inferred from its success publishing ESLint. If permission is missing, the package owner must supply the narrowly authorized access; the workflow fails without creating credentials or expanding rights. Organization administration rights alone do not grant package publication rights. The token is bound to the registry in memory in the stage step only; installation, checks and packing receive no token.
+
+Before upload, the shared stage guard checks public versions and the authenticated pending-stage list. Only pnpm's structured public-metadata HTTP 404 is interpreted as a package without published versions. Missing tokens, stage-list authorization failures, network failures and malformed responses remain blockers. An existing stage is preserved and its ID recorded rather than uploading a duplicate. An ambiguous upload outcome requires owner reconciliation before retry. No manual workflow trigger, authentication selector or OIDC fallback is configured.
+
+## Owner review and promotion
+
+1. Review and merge the tested draft PR to `main` using the repository's normal owner-controlled review process.
+2. Let the automatic workflow finish. Check the Actions source SHA, `frontend-package-<SHA>` artifact, `SHA256SUMS` and `frontend-stage-result-<SHA>` receipt. Review the pending stage's package name, version and contents against that exact artifact.
+3. Promote the stage in npm's website with the owner's 2FA, or use an already-authenticated `pnpm stage approve <stage-id>` session and complete proof of presence. Do not share the credential or OTP in chat.
+4. Verify the public registry bytes and fresh consumer as described below before dispatching consumer migrations.
+
+First-package staging creates a public `0.0.0-stage` placeholder so package settings can be accessed. This placeholder does not make `0.1.0` installable. A successful stage receipt is also not a completed public release.
+
+## Exact registry verification
+
+From the reviewed source checkout, download the automatic release run's exact `frontend-package-<SHA>` artifact and verify `SHA256SUMS` and `source-commit.txt`. Once the owner has promoted `0.1.0`, run:
+
+```sh
+pnpm exec playwright install chromium
+pnpm run test:registry 0.1.0 /path/to/verified/package.tgz
+```
+
+The script checks the exact public package/version and registry SHA-512 integrity against the reviewed tarball, then creates a fresh pnpm consumer. It installs the exact registry version, reruns frozen installation, imports both `/css` and `/playwright`, invokes `ztd-css`, checks TypeScript declarations with strict settings and executes a deliberately failing browser Axe scan that must retain the violation evidence. Browser infrastructure errors cannot satisfy that assertion.
+
+The consumer uses `minimumReleaseAge: 1440`, `minimumReleaseAgeStrict: true` and `trustPolicy: no-downgrade` without exceptions. A newly promoted release may require waiting 24 hours before this check is eligible. Wait and retry if the policy blocks it; do not lower policy or add an exception to force publication verification. Consumers retain their own approved policies and pin the verified version:
+
+```sh
+pnpm add -D --save-exact @ztd-me/frontend-checks@0.1.0 @playwright/test@1.62.0
+pnpm install --frozen-lockfile
+```
+
+## Optional future Trusted Publisher
+
+An npm trust grant would be package-specific: GitHub owner `zeithrold`, repository `tools`, workflow filename `publish-frontend.yml`, no environment, stage publishing only. The owner must configure it separately; this release does not create one. OIDC supports stage upload but cannot authenticate the pending-stage lookup. Switching requires a reviewed guard redesign and job-scoped `id-token: write`, rather than removing the token from the current job or adding a fallback path. Owner proof of presence still controls promotion.
+
+References: [pnpm stage](https://pnpm.io/cli/stage), [npm staged publishing](https://docs.npmjs.com/staged-publishing/), [token permissions](https://docs.npmjs.com/creating-and-viewing-access-tokens/), [Trusted Publishers](https://docs.npmjs.com/trusted-publishers/).

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@ztd-me/frontend-checks",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "type": "module",
+  "license": "UNLICENSED",
+  "description": "Native CSS and Playwright accessibility checks for zt frontend profiles",
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "exports": {
+    "./css": {
+      "types": "./src/css.d.ts",
+      "import": "./src/css.mjs"
+    },
+    "./playwright": {
+      "types": "./src/playwright.d.ts",
+      "import": "./src/playwright.mjs"
+    }
+  },
+  "bin": {
+    "ztd-css": "./src/css-cli.mjs"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "docs"
+  ],
+  "dependencies": {
+    "@axe-core/playwright": "4.13.0",
+    "fast-glob": "3.3.3",
+    "postcss": "8.5.27",
+    "postcss-value-parser": "4.2.0",
+    "stylelint": "17.15.0",
+    "stylelint-config-standard": "40.0.0",
+    "color-name": "2.0.0"
+  },
+  "peerDependencies": {
+    "@playwright/test": "^1.62.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.12.0",
+    "@playwright/test": "1.62.0",
+    "eslint": "10.11.0",
+    "typescript": "6.0.3",
+    "@ztd-me/eslint": "0.1.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zeithrold/tools.git",
+    "directory": "packages/frontend-checks"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "lint": "eslint src scripts test playwright.config.mjs eslint.config.js --max-warnings 0",
+    "typecheck": "tsc -p test/types/tsconfig.json",
+    "test": "node --test test/*.test.mjs",
+    "test:browser": "playwright test",
+    "test:pack": "node scripts/pack-smoke.mjs",
+    "check": "pnpm run lint && pnpm run typecheck && pnpm test && pnpm run test:browser && pnpm run test:pack",
+    "test:registry": "node scripts/registry-smoke.mjs"
+  }
 }

package/src/css-cli.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import process from 'node:process'
+import { pathToFileURL } from 'node:url'
+import { checkCss } from './css.mjs'
+
+async function main() {
+  if (process.argv.length !== 3) {
+    throw new Error('usage: ztd-css ./css-check.config.mjs; see README for the config schema')
+  }
+  const loaded = await import(pathToFileURL(path.resolve(process.argv[2])).href)
+  const report = await checkCss(loaded.default)
+  const data = `${JSON.stringify(report, null, 2)}\n`
+  if (process.env.ZT_ARTIFACTS_DIR) {
+    await writeFile(path.join(process.env.ZT_ARTIFACTS_DIR, 'css.json'), data)
+  }
+  process.stdout.write(data)
+  if (report.status !== 'passed') {
+    process.exitCode = 1
+  }
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error.message}\n`)
+  process.exitCode = 1
+})

package/src/css-config.mjs

@@ -0,0 +1,32 @@
+import { createRequire } from 'node:module'
+import standard from 'stylelint-config-standard'
+
+const require = createRequire(import.meta.url)
+
+export const cssConfig = {
+  ...standard,
+  extends: require.resolve('stylelint-config-standard'),
+  rules: {
+    ...standard.rules,
+    'at-rule-no-unknown': [
+      true,
+      {
+        ignoreAtRules: [
+          'theme',
+          'utility',
+          'variant',
+          'custom-variant',
+          'apply',
+          'reference',
+          'source',
+          'config',
+          'plugin',
+        ],
+      },
+    ],
+    'function-no-unknown': [
+      true,
+      { ignoreFunctions: ['--alpha', '--spacing'] },
+    ],
+  },
+}

package/src/css-tokens.mjs

@@ -0,0 +1,77 @@
+import colors from 'color-name'
+import valueParser from 'postcss-value-parser'
+
+const colorFunctions = /^(?:rgb|rgba|hsl|hsla|hwb|lab|lch|oklab|oklch|color)$/i
+const colorProperties = /^color$|color$|^background(?:$|-)|^border(?:$|-)|^outline(?:$|-)|shadow$|^fill$|^stroke$/i
+
+function references(value) {
+  const names = []
+  valueParser(value).walk((node) => {
+    if (node.type !== 'function' || node.value !== 'var') {
+      return
+    }
+    const first = node.nodes.find(child => child.type !== 'space' && child.type !== 'comment')
+    if (first?.type === 'word' && first.value.startsWith('--')) {
+      names.push(first.value)
+    }
+  })
+  return names
+}
+
+function hasLiteralColor(value) {
+  let found = false
+  valueParser(value).walk((node) => {
+    if (node.type === 'function' && node.value === 'url') {
+      return false
+    }
+    if (node.type === 'function' && colorFunctions.test(node.value)) {
+      found = true
+    }
+    const literalWord = node.type === 'word'
+      && (/^#[\da-f]{3,8}$/i.test(node.value) || Object.hasOwn(colors, node.value.toLowerCase()))
+    if (literalWord) {
+      found = true
+    }
+  })
+  return found
+}
+
+// This is a closed declaration inventory, not a proof of the runtime cascade.
+export function tokenWarnings(sources, definitions, options) {
+  const known = new Set(options.externalCustomProperties ?? [])
+  for (const root of [
+    ...sources,
+    ...definitions,
+  ]) {
+    root.walkDecls((declaration) => {
+      if (declaration.prop.startsWith('--') && !declaration.prop.includes('*')) {
+        known.add(declaration.prop)
+      }
+    })
+    root.walkAtRules('property', rule => known.add(rule.params.trim()))
+  }
+  const warnings = []
+  for (const root of sources) {
+    root.walkDecls((declaration) => {
+      const issue = (rule, text) => warnings.push({
+        file: root.source.input.file,
+        line: declaration.source.start.line,
+        column: declaration.source.start.column,
+        rule,
+        text,
+      })
+      for (const name of references(declaration.value)) {
+        if (!known.has(name)) {
+          issue('ztd/defined-custom-property', `Undefined custom property ${name}; include its declaration source`)
+        }
+      }
+      if (declaration.prop.startsWith('--') || !colorProperties.test(declaration.prop)) {
+        return
+      }
+      if (hasLiteralColor(declaration.value)) {
+        issue('ztd/semantic-color', 'Move literal colors into project-owned semantic custom properties')
+      }
+    })
+  }
+  return warnings
+}

package/src/css.d.ts

@@ -0,0 +1,22 @@
+export interface CssOptions {
+  files: string[]
+  cwd?: string
+  /** External CSS declaration sources. Imports are not resolved implicitly. */
+  tokenFiles?: string[]
+  /** Exact runtime-provided names, reviewed in the project design contract. */
+  externalCustomProperties?: string[]
+}
+export interface CssWarning {
+  file: string
+  line: number
+  column: number
+  rule: string
+  text: string
+}
+export interface CssReport {
+  schemaVersion: 1
+  status: 'passed' | 'failed'
+  files: string[]
+  warnings: CssWarning[]
+}
+export function checkCss(options: CssOptions): Promise<CssReport>

package/src/css.mjs

@@ -0,0 +1,53 @@
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import process from 'node:process'
+import glob from 'fast-glob'
+import postcss from 'postcss'
+import stylelint from 'stylelint'
+import { cssConfig } from './css-config.mjs'
+import { tokenWarnings } from './css-tokens.mjs'
+
+async function sources(patterns, cwd) {
+  const matches = await Promise.all(patterns.map(async (pattern) => {
+    const selected = await glob(pattern, { cwd, absolute: true, onlyFiles: true, followSymbolicLinks: false })
+    if (!selected.length) {
+      throw new Error(`CSS pattern matched no files: ${pattern}`)
+    }
+    return selected
+  }))
+  const files = [
+    ...new Set(matches.flat()),
+  ]
+  return Promise.all(files.sort().map(async (file) => {
+    const code = await readFile(file, 'utf8')
+    return postcss.parse(code, { from: file })
+  }))
+}
+
+function validate(options) {
+  if (!options || !Array.isArray(options.files) || !options.files.length) {
+    throw new TypeError('CSS files must be a nonempty explicit array of paths/globs')
+  }
+}
+
+export async function checkCss(options) {
+  validate(options)
+  const cwd = path.resolve(options.cwd ?? process.cwd())
+  const roots = await sources(options.files, cwd)
+  const definitions = await sources(options.tokenFiles ?? [], cwd)
+  const lint = await stylelint.lint({ files: roots.map(root => root.source.input.file), config: cssConfig, cwd })
+  const warnings = lint.results.flatMap(result => result.warnings.map(warning => ({
+    file: result.source,
+    line: warning.line,
+    column: warning.column,
+    rule: warning.rule,
+    text: warning.text,
+  })))
+  warnings.push(...tokenWarnings(roots, definitions, options))
+  return {
+    schemaVersion: 1,
+    status: lint.errored || warnings.length ? 'failed' : 'passed',
+    files: roots.map(root => root.source.input.file),
+    warnings,
+  }
+}

package/src/playwright.d.ts

@@ -0,0 +1,11 @@
+import type { Page, TestInfo, PlaywrightTestConfig } from '@playwright/test'
+import type { AxeBuilder } from '@axe-core/playwright'
+export interface AccessibilityOptions {
+  label?: string
+  /** Restricts the scan; full-page scans remain necessary for page-level checks. */
+  include?: string
+  tags?: string[]
+}
+export function assertAccessible(page: Page, testInfo: TestInfo, options?: AccessibilityOptions): ReturnType<AxeBuilder['analyze']>
+export function captureState(page: Page, testInfo: TestInfo, label: string): Promise<void>
+export function verificationArtifacts(root?: string): Pick<PlaywrightTestConfig, 'outputDir' | 'reporter' | 'use'>

package/src/playwright.mjs

@@ -0,0 +1,50 @@
+import assert from 'node:assert/strict'
+import process from 'node:process'
+import AxeBuilder from '@axe-core/playwright'
+
+/** Scan after each relevant UI state is established, not only the initial route. */
+export async function assertAccessible(page, testInfo, options = {}) {
+  if (options.tags && !options.tags.length) {
+    throw new TypeError('Accessibility tags must not be empty')
+  }
+  let builder = new AxeBuilder({ page }).withTags(options.tags ?? [
+    'wcag2a',
+    'wcag2aa',
+    'wcag21aa',
+    'wcag22aa',
+  ])
+  if (options.include) {
+    builder = builder.include(options.include)
+  }
+  const results = await builder.analyze()
+  await testInfo.attach(`a11y-${options.label ?? 'state'}`, {
+    body: JSON.stringify(results, null, 2),
+    contentType: 'application/json',
+  })
+  assert.equal(results.violations.length, 0, JSON.stringify(results.violations, null, 2))
+  return results
+}
+
+/** Screenshots are captured evidence; this helper does not maintain baselines. */
+export async function captureState(page, testInfo, label) {
+  await testInfo.attach(label, { body: await page.screenshot({ fullPage: true }), contentType: 'image/png' })
+}
+
+/** Apply these paths to the project's existing config; retain its webServer/projects. */
+export function verificationArtifacts(root = process.env.ZT_ARTIFACTS_DIR ?? '.zt/browser') {
+  return {
+    outputDir: `${root}/test-results`,
+    reporter: [
+      ['list'],
+      [
+        'html',
+        { outputFolder: `${root}/playwright-report`, open: 'never' },
+      ],
+      [
+        'json',
+        { outputFile: `${root}/playwright.json` },
+      ],
+    ],
+    use: { trace: 'retain-on-failure', screenshot: 'only-on-failure', video: 'retain-on-failure' },
+  }
+}