@satinhq/lint 0.0.0-stage → 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Satin contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,105 @@
-# Temporary Holding Version
+# @satinhq/lint
 
-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.
+Fidelity lint preset for Satin apps. Extend it from an app's `.oxlintrc.json`:
+
+```json
+{ "extends": ["../../packages/pwakit-lint/oxlint.json"] }
+```
+
+The preset exists to make Satin's invariants hard to violate. It bans browser-history routers and any `pushState` or `replaceState` property access in app code. The framework package does not extend the preset, so its future URL-projection module can own the single allowed `replaceState` call.
+
+Oxlint cannot inspect CSS or determine whether a style expression contains viewport geometry. Wire the companion check into each app's lint script:
+
+```json
+{
+  "scripts": {
+    "lint": "oxlint && node ../../packages/pwakit-lint/scripts/check-fidelity.mjs src"
+  }
+}
+```
+
+The companion check uses the TypeScript compiler AST for `.js`, `.jsx`, `.mjs`, `.ts`, and `.tsx`. It resolves local style/props members and spreads, React `createElement`/JSX-runtime aliases and simple wrappers, runtime imports and re-exports, known CSS-in-JS tags, and direct DOM style mutations. A tokenized CSS declaration parser covers `.css` without treating comments or strings as code.
+
+It rejects raw `vh` units, `env(safe-area-inset-*)`, raw `overflow: auto|scroll`, inline `overflow`/`overflowX`/`overflowY` scrolling, consumer-owned `-webkit-overflow-scrolling`, raw `<button>` controls, `onClick` activation, direct `navigator.serviceWorker.register(...)` calls, direct runtime imports from liquid-glass or OpenGlass package families, and full-width bottom-pinned geometry that omits `--satin-inset-bottom`. App scrolling must come from `ScrollView`; app activation must come from `Button` and `onPress`; service-worker registration must come from `runApp`; persistent glass chrome must come from Satin's `GlassEffect` and `TabView`. Framework CSS is outside the app lint target and owns the actual native overflow, pointer, service-worker update, and sibling scene/chrome policies. The dev runtime assertion independently scans computed layout so dynamic styles and nested raw scrollers cannot hide behind a declared ancestor.
+
+Static expression evaluation has a shared per-file work budget, including string combinations and object-spread branches. If the budget is exhausted, the CLI reports `static-evaluation-budget-exceeded` with “analysis incomplete” and exits 2. This is an analysis error, not a fidelity rule or a clean result; simplify the combinatorial expression before relying on the check. Fidelity violations continue to exit 1.
+
+The machine-readable manifest is exported without enabling any unsafe autofixes:
+
+```js
+import { ruleManifest } from '@satinhq/lint/rule-manifest'
+```
+
+Run `pnpm --filter @satinhq/lint test` for the rule and CLI suite.
+
+`no-raw-persistent-storage` flags direct app access to `localStorage` and `indexedDB`; use `defineDatabase` for durable app records. A legacy import bridge can opt out with a source-file comment `// satin-data-allow-raw-storage: <reason>`. Keep that file small because the comment exempts the whole file. Session-only UI state is outside this rule.
+
+<!-- measured-reference -->
+For an entry point using `defineApp` / `satinApp`, include its HTML in the checker
+command: `check-fidelity src index.html`. `no-handwritten-app-head` reserves the
+manifest, touch icon, viewport, appearance metadata and title for the generated
+head. Comments are ignored; attribute order, casing and quoting do not bypass it.
+Only pass definition-owned HTML entry points to this rule.
+<!-- End measured-reference -->
+
+measured-reference adds `no-page-zoom` for CSS/inline `zoom` and `touch-action: pinch-zoom`.
+Use the package's `Zoomable` role for component magnification. Startup-image tags
+are covered by `no-handwritten-app-head`, alongside viewport and manifest policy.
+
+`no-direct-react-root` reserves the initial commit for `mountSatin`. Runtime imports, re-exports and literal dynamic imports/requires of `react-dom/client` are rejected; type-only imports remain allowed.
+
+`no-custom-linear-easing` rejects custom `linear(...)` curves in CSS animation
+and transition declarations, inline timing styles, and statically resolved
+`animate` / `updateTiming` options. Use Satin motion or explicit property
+keyframes with ordinary `linear` easing. Dynamically constructed options are
+outside this static check; installed busy-thread recordings verify the runtime.
+
+`no-raw-text-input` rejects raw JSX and React factory `input`/`textarea` controls.
+Use `TextField`, `SecureField`, or `TextEditor`. For an intentional native control
+experiment, put a nonempty reason directly on that control, for example
+`data-satin-native-input="Date picker capability probe"`. This escape does not
+waive installed-PWA acceptance or the 16px minimum. `no-small-input-font` checks
+literal pixel sizes on input/textarea CSS selectors and field JSX inline styles.
+Computed, inherited, variable and dynamically generated sizes still require the
+runtime `input-font-size` assertion and installed focus recordings.
+
+## App contract checks
+
+The template `AGENTS.md` maps its hard rules to the rule manifest. The checker includes
+`no-browser-history` for browser history mutation/traversal, `no-app-reload` for
+location reloads, `no-global-touch-listener` for document/window touch listeners,
+and `no-global-selection-reset` for root/universal CSS selection declarations.
+History/reload checks resolve simple aliases, destructuring and literal computed
+properties and exclude shadowed local objects. Dynamic inter-module calls and
+computed policies still need review; this checker is not a sandbox.
+
+Intent cannot be linted: explain permission value, keep credentials server-side,
+choose meaningful destinations, validate notification routes, preserve measured
+motion, check icon licenses and record installed fidelity. The generated app
+ships build/typecheck scripts. The lint checker is workspace-only and is not
+installed by the starter. From a framework checkout, run it against the app
+source, CSS and HTML; no standalone registry installation is available.
+
+`no-hidden-focus-heading` rejects JSX headings with a `tabIndex` and a static
+`hidden`, `aria-hidden={true}`, `sr-only` or `visually-hidden` declaration. Focus
+must target a visible title or control with a real cursor frame. Dynamic CSS,
+clipping and viewport visibility require the runtime geometry check and installed
+VoiceOver acceptance; this static rule does not prove visibility.
+
+`no-fixed-document` rejects fixed positioning on html, body, :root and #root CSS selectors. Satin owns document layout so an installed translucent viewport can grow to the physical bottom. Component-local fixed overlays remain allowed. Dynamic selectors/styles still require the installed viewport and bottom-marker check.
+
+`no-internal-import` rejects value, type, dynamic and re-export access to `@satinhq/kit/internal`. The framework lab uses the explicit `--allow-internal` checker option; ordinary apps do not.
+
+`no-internal-import` follows locally resolvable require aliases (including object/destructuring aliases) and constant module strings. It does not resolve tsconfig/bundler path aliases, imports hidden behind other modules, computed runtime strings, reassignment/control-flow effects or arbitrary loader wrappers. Keep app package aliases pointed at public entry points; review configuration and wrapper modules separately. This syntax rule is an authoring guard, not a module-loading security boundary.
+
+Content components such as `Text` and `VStack` are the recommended default vocabulary for new content, but are optional. Custom React/HTML remains supported. No rule requires adoption; existing geometry and semantic-role invariants apply equally to either style.
+
+
+App source must not read `--satin-*` CSS variables. `no-private-css-variable`
+checks CSS values, inline styles and JavaScript strings. Use `Overlay`,
+`SafeAreaInset`, public component props, or `useSafeAreaInsets` instead. The
+framework lab can explicitly use `--allow-internal`; production apps must not.
+
+`no-global-focus-reset` rejects document-wide removal of focus outlines. Satin
+owns non-keyboard outline suppression on the active element; hardware-keyboard
+focus remains available. Element-scoped role policies are not global resets.

package/oxlint.json

@@ -0,0 +1,100 @@
+{
+  "plugins": [
+    "react",
+    "typescript",
+    "oxc"
+  ],
+  "rules": {
+    "react/rules-of-hooks": "error",
+    "react/only-export-components": [
+      "warn",
+      {
+        "allowConstantExport": true
+      }
+    ],
+    "no-restricted-imports": [
+      "error",
+      {
+        "paths": [
+          {
+            "name": "react-router",
+            "message": "Satin owns navigation. Use the satin Navigator; browser-history routers break the edge-swipe invariant."
+          },
+          {
+            "name": "react-router-dom",
+            "message": "Satin owns navigation. Use the satin Navigator; browser-history routers break the edge-swipe invariant."
+          },
+          {
+            "name": "@tanstack/react-router",
+            "message": "Satin owns navigation. Use the satin Navigator; browser-history routers break the edge-swipe invariant."
+          },
+          {
+            "name": "@remix-run/react",
+            "message": "Satin owns navigation. Remix document routing is incompatible with Satin's persistent in-memory screen stack."
+          },
+          {
+            "name": "@remix-run/router",
+            "message": "Satin owns navigation. Browser-history router cores break the edge-swipe invariant."
+          },
+          {
+            "name": "next/navigation",
+            "message": "Satin owns navigation. Next.js document routing is not a supported Satin runtime."
+          },
+          {
+            "name": "next/router",
+            "message": "Satin owns navigation. Next.js document routing is not a supported Satin runtime."
+          },
+          {
+            "name": "wouter",
+            "message": "Satin owns navigation. Browser-history routers break the edge-swipe invariant."
+          },
+          {
+            "name": "wouter/use-browser-location",
+            "message": "Satin owns navigation. Browser history cannot back the internal screen stack."
+          },
+          {
+            "name": "liquid-glass-web-react",
+            "message": "Satin owns glass composition. Use GlassBar or TabBar from satin."
+          },
+          {
+            "name": "liquid-glass-react",
+            "message": "Satin owns glass composition. Use GlassBar or TabBar from satin."
+          },
+          {
+            "name": "openglass",
+            "message": "Satin owns glass composition. Use GlassBar or TabBar from satin."
+          },
+          {
+            "name": "pixi.js",
+            "message": "Satin owns the page GPU context and glass renderer. Use framework glass primitives."
+          },
+          {
+            "name": "apple-liquid-glass-webgl",
+            "message": "Satin owns glass composition and WebGL is out of scope for measured-reference. Use GlassBar or TabBar from satin."
+          }
+        ]
+      }
+    ],
+    "no-restricted-properties": [
+      "error",
+      {
+        "object": "navigator",
+        "property": "vibrate",
+        "message": "Use Satin sensoryFeedback tap affordances. Imperative vibration is unavailable on the target runtime."
+      },
+      {
+        "property": "pushState",
+        "message": "Satin internal navigation never grows browser history. Use the satin Navigator."
+      },
+      {
+        "property": "replaceState",
+        "message": "Only Satin's framework-owned URL projection module may call history.replaceState."
+      },
+      {
+        "object": "navigator",
+        "property": "mediaSession",
+        "message": "Satin owns system media. Use useMediaPlayer for metadata and remote playback commands."
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@satinhq/lint",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-beta.0",
+  "type": "module",
+  "description": "Fidelity lint preset for Satin apps: bans the web idioms that break the native illusion.",
+  "exports": {
+    "./oxlint": "./oxlint.json",
+    "./check-fidelity": "./scripts/check-fidelity.mjs",
+    "./rule-manifest": "./src/rules.mjs"
+  },
+  "dependencies": {
+    "typescript": "7.0.2",
+    "oxc-parser": "0.153.0"
+  },
+  "devDependencies": {
+    "oxlint": "^1.79.0"
+  },
+  "license": "MIT",
+  "files": [
+    "oxlint.json",
+    "scripts",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "beta"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/satinhq/satin.git",
+    "directory": "packages/pwakit-lint"
+  },
+  "scripts": {
+    "typecheck": "true",
+    "lint": "oxlint scripts src tests",
+    "test": "node --test"
+  }
 }

package/scripts/check-fidelity.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+import { checkTargets, formatDiagnostic } from '../src/checker.mjs'
+
+const allowInternal = process.argv.includes('--allow-internal')
+const targets = process.argv.slice(2).filter(arg => arg !== '--allow-internal')
+if (targets.length === 0) {
+  console.error('Usage: check-fidelity <source file or directory> [...]')
+  process.exitCode = 2
+} else {
+  try {
+    const diagnostics = (await checkTargets(targets)).filter(
+      diagnostic =>
+        !allowInternal ||
+        !['no-internal-import', 'no-private-css-variable'].includes(diagnostic.ruleId),
+    )
+    for (const diagnostic of diagnostics) console.error(formatDiagnostic(diagnostic))
+
+    if (diagnostics.length > 0) {
+      console.error(`Satin fidelity check found ${diagnostics.length} violation(s).`)
+      process.exitCode = 1
+    }
+  } catch (error) {
+    if (error.code !== 'static-evaluation-budget-exceeded') throw error
+    console.error(error.message)
+    process.exitCode = 2
+  }
+}

package/scripts/check-modal-lifecycle.mjs

@@ -0,0 +1,49 @@
+import { parseSync } from 'oxc-parser'
+import { readdir, readFile } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+/** Modal entry belongs to one transaction; popover showPopover remains independent. */
+export function modalLifecycleViolations(source, filename) {
+  if (filename.endsWith('modal/lifecycle.ts') || /\.(test|fixture)\./.test(filename)) return []
+  const { program } = parseSync(filename, source, { lang: 'tsx', preserveParens: true })
+  const violations = []
+  function visit(node) {
+    if (!node || typeof node !== 'object') return
+    if (
+      node.type === 'CallExpression' &&
+      node.callee.type === 'MemberExpression' &&
+      !node.callee.computed &&
+      node.callee.property.name === 'showModal'
+    ) {
+      const line = source.slice(0, node.start).split('\n').length
+      violations.push(`${filename}:${line}: use the shared openModal transaction`)
+    }
+    for (const child of Object.values(node)) {
+      if (Array.isArray(child)) child.forEach(visit)
+      else if (child && typeof child === 'object') visit(child)
+    }
+  }
+  visit(program)
+  return violations
+}
+async function check(directory, root = directory) {
+  const violations = []
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const path = join(directory, entry.name)
+    if (entry.isDirectory()) violations.push(...(await check(path, root)))
+    else if (/\.tsx?$/.test(entry.name)) {
+      violations.push(
+        ...modalLifecycleViolations(await readFile(path, 'utf8'), relative(root, path)),
+      )
+    }
+  }
+  return violations
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const violations = await check(process.argv[2])
+  if (violations.length) {
+    console.error(violations.join('\n'))
+    process.exitCode = 1
+  }
+}

package/scripts/check-sidebar-artwork.mjs

@@ -0,0 +1,20 @@
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+
+// A vector-only boundary prevents the previous UIImage PNG export from
+// returning. Provenance still requires source review; this is not a license test.
+const source = await readFile(
+  resolve(process.argv[2] ?? 'src/navigation/SidebarSymbol.tsx'),
+  'utf8',
+)
+if (/data:image|base64|<image\b|<img\b|url\s*\(/i.test(source))
+  throw Error(
+    'SidebarSymbol must use the shared Symbol renderer, never embedded/exported image assets.',
+  )
+if (
+  !source.includes('<Symbol') ||
+  !source.includes('Framework7 Icons (MIT)') ||
+  /<svg|<path/.test(source)
+)
+  throw Error('SidebarSymbol must delegate to Symbol and retain its Framework7 MIT provenance.')
+console.log('Sidebar symbol vector/provenance boundary passed.')

package/scripts/check-webgpu-worker.mjs

@@ -0,0 +1,144 @@
+import { readFile } from 'node:fs/promises'
+import { resolve, dirname, extname } from 'node:path'
+import { syntax as ts, parseSourceFile } from '../src/native-typescript.mjs'
+// Follow runtime edges, including re-exports and dynamic imports. ImportType
+// nodes and mixed `type` specifiers are erased and must not enter this graph.
+const seen = new Set()
+async function visit(path) {
+  path = resolve(path)
+  if (seen.has(path) || extname(path) === '.json') return
+  seen.add(path)
+  const source = await readFile(path, 'utf8')
+  const ast = parseSourceFile(path, source).file
+  const edges = []
+  const property = node =>
+    ts.isPropertyAccessExpression(node)
+      ? node.name.text
+      : ts.isElementAccessExpression(node) &&
+          node.argumentExpression &&
+          ts.isStringLiteral(node.argumentExpression)
+        ? node.argumentExpression.text
+        : undefined
+  function inspect(node) {
+    if (ts.isTypeNode(node)) return
+    if (
+      ts.isCallExpression(node) &&
+      ['setTimeout', 'setInterval'].includes(node.expression.getText(ast)) &&
+      node.arguments[0]?.getText(ast) === 'tick'
+    )
+      throw Error(`${path}: glass tick must use the capped page frame clock, never a timer`)
+
+    const renderFunction =
+      ts.isFunctionDeclaration(node) && node.name?.text === 'render'
+        ? node
+        : ts.isVariableDeclaration(node) &&
+            ts.isIdentifier(node.name) &&
+            node.name.text === 'render' &&
+            node.initializer &&
+            (ts.isArrowFunction(node.initializer) || ts.isFunctionExpression(node.initializer))
+          ? node.initializer
+          : undefined
+    if (renderFunction?.body) {
+      const body = renderFunction.body
+      const guard = ts.isBlock(body) ? body.statements[0] : undefined
+      if (
+        !guard ||
+        !ts.isIfStatement(guard) ||
+        !ts.isBinaryExpression(guard.expression) ||
+        guard.expression.operatorToken.kind !== ts.SyntaxKind.BarBarToken ||
+        guard.expression.left.getText(ast) !== '!visible' ||
+        guard.expression.right.getText(ast) !== '!submissionAllowed()' ||
+        !ts.isReturnStatement(guard.thenStatement) ||
+        guard.thenStatement.expression
+      ) {
+        throw Error(
+          `${path}: render must reject hidden frames and closed submission gates before GPU work`,
+        )
+      }
+    }
+    if (
+      ts.isCaseClause(node) &&
+      ts.isStringLiteral(node.expression) &&
+      node.expression.text === 'init'
+    ) {
+      const guard = node.statements[0]
+      const rejects = (expression, value) =>
+        ts.isBinaryExpression(expression) &&
+        expression.operatorToken.kind === ts.SyntaxKind.ExclamationEqualsEqualsToken &&
+        ts.isPropertyAccessExpression(expression.left) &&
+        ts.isIdentifier(expression.left.expression) &&
+        expression.left.expression.text === 'request' &&
+        expression.left.name.text === 'appearance' &&
+        ts.isStringLiteral(expression.right) &&
+        expression.right.text === value
+      const condition = guard && ts.isIfStatement(guard) ? guard.expression : undefined
+      if (
+        !condition ||
+        !ts.isBinaryExpression(condition) ||
+        condition.operatorToken.kind !== ts.SyntaxKind.AmpersandAmpersandToken ||
+        !rejects(condition.left, 'light') ||
+        !rejects(condition.right, 'dark') ||
+        !ts.isThrowStatement(guard.thenStatement)
+      )
+        throw Error(`${path}: WebGPU init must reject unknown appearance before drawing`)
+    }
+    if (ts.isImportDeclaration(node)) {
+      const clause = node.importClause
+      const bindings = clause?.namedBindings
+      const erased =
+        clause?.isTypeOnly ||
+        (!clause?.name &&
+          bindings &&
+          ts.isNamedImports(bindings) &&
+          bindings.elements.length > 0 &&
+          bindings.elements.every(e => e.isTypeOnly))
+      if (!erased) edges.push(node.moduleSpecifier.text)
+    }
+    if (ts.isExportDeclaration(node) && node.moduleSpecifier && !node.isTypeOnly) {
+      const clause = node.exportClause
+      if (!clause || !ts.isNamedExports(clause) || !clause.elements.every(e => e.isTypeOnly))
+        edges.push(node.moduleSpecifier.text)
+    }
+    if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
+      if (
+        (ts.isIdentifier(node.expression) &&
+          ['window', 'document'].includes(node.expression.text)) ||
+        (ts.isIdentifier(node.expression) &&
+          node.expression.text === 'globalThis' &&
+          ['window', 'document'].includes(property(node)))
+      )
+        throw Error(`${path}: DOM access in glass worker`)
+    }
+    if (ts.isCallExpression(node)) {
+      if (node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+        if (!ts.isStringLiteral(node.arguments[0]))
+          throw Error(`${path}: nonliteral dynamic worker dependency`)
+        edges.push(node.arguments[0].text)
+      }
+      const name = property(node.expression)
+      if (name === 'requestDevice' && !path.endsWith('/webgpu/layers.ts'))
+        throw Error(`${path}: only LayerDevice may request a GPU device`)
+      if (name === 'createTexture' && !path.endsWith('/webgpu/frameGraph.ts'))
+        throw Error(`${path}: only FrameGraph may allocate glass textures`)
+      if (
+        name === 'getContext' &&
+        node.arguments[0] &&
+        ts.isStringLiteral(node.arguments[0]) &&
+        node.arguments[0].text.startsWith('webgl')
+      )
+        throw Error(`${path}: WebGL context in WebGPU worker`)
+    }
+    ts.forEachChild(node, inspect)
+  }
+  inspect(ast)
+  for (const specifier of edges) {
+    if (specifier === 'pixi.js' || specifier.startsWith('pixi.js/'))
+      throw Error(`${path}: Pixi dependency in WebGPU worker`)
+    if (specifier.startsWith('.')) await visit(resolve(dirname(path), specifier))
+    else throw Error(`${path}: external runtime worker dependency ${specifier}`)
+  }
+}
+await visit(process.argv[2] ?? 'src/glass/webgpu/entry.worker.ts')
+console.log(
+  `WebGPU worker ownership: ${seen.size} modules checked; no Pixi/DOM, one device owner, one texture graph.`,
+)

package/src/checker.mjs

@@ -0,0 +1,71 @@
+import { analyzeHtml } from './html-analysis.mjs'
+import { readdir, readFile, stat } from 'node:fs/promises'
+import { extname, resolve } from 'node:path'
+
+import { analyzeCss } from './css-analysis.mjs'
+import { ruleManifest } from './rules.mjs'
+import { analyzeTypeScript } from './typescript-analysis.mjs'
+
+export const SOURCE_EXTENSIONS = new Set(['.html', '.css', '.js', '.jsx', '.mjs', '.ts', '.tsx'])
+
+const ruleOrder = new Map(ruleManifest.map((rule, index) => [rule.id, index]))
+
+function lineAndColumn(source, offset) {
+  let line = 1
+  let lineStart = 0
+  for (let index = 0; index < offset; index += 1) {
+    if (source[index] !== '\n') continue
+    line += 1
+    lineStart = index + 1
+  }
+  return { line, column: offset - lineStart + 1 }
+}
+
+export async function sourceFiles(target) {
+  const metadata = await stat(target)
+  if (metadata.isFile()) return SOURCE_EXTENSIONS.has(extname(target)) ? [target] : []
+
+  const entries = await readdir(target, { withFileTypes: true })
+  const nested = await Promise.all(
+    entries
+      .filter(entry => entry.name !== 'dist' && entry.name !== 'node_modules')
+      .map(entry => sourceFiles(resolve(target, entry.name))),
+  )
+  return nested.flat()
+}
+
+export function analyzeSource(fileName, source) {
+  const violations =
+    extname(fileName) === '.html'
+      ? analyzeHtml(source)
+      : extname(fileName) === '.css'
+        ? analyzeCss(source)
+        : analyzeTypeScript(fileName, source)
+
+  return violations.toSorted(
+    (left, right) =>
+      (ruleOrder.get(left.ruleId) ?? Number.MAX_SAFE_INTEGER) -
+        (ruleOrder.get(right.ruleId) ?? Number.MAX_SAFE_INTEGER) || left.offset - right.offset,
+  )
+}
+
+export async function analyzeFile(file) {
+  const source = await readFile(file, 'utf8')
+  return analyzeSource(file, source).map(violation => ({
+    ...violation,
+    file,
+    ...lineAndColumn(source, violation.offset),
+  }))
+}
+
+export async function checkTargets(targets, cwd = process.cwd()) {
+  const files = (await Promise.all(targets.map(target => sourceFiles(resolve(cwd, target))))).flat()
+  const diagnostics = []
+
+  for (const file of files) diagnostics.push(...(await analyzeFile(file)))
+  return diagnostics
+}
+
+export function formatDiagnostic(diagnostic) {
+  return `${diagnostic.file}:${diagnostic.line}:${diagnostic.column} ${diagnostic.message}`
+}