@avelonjs/bailiff 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Yannelli
+
+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

@@ -0,0 +1,128 @@
+# @avelonjs/bailiff
+
+`@avelonjs/bailiff` is the architecture linter. It is an ESLint plugin plus a CLI wrapper so violations appear as editor squiggles and as `reeve bailiff` in CI. Reach for it when you want Avelon's directory map, driver boundary, and generated-file rule enforced rather than requested in a contributing guide.
+
+A template is advice. A linter is a decision.
+
+## Installation
+
+```sh
+bun add -d @avelonjs/bailiff eslint
+```
+
+Point ESLint at the recommended config. Every rule is on by default; you may downgrade one in `avelon.config.ts`, and `reeve doctor` prints the drift.
+
+```ts
+import bailiff from '@avelonjs/bailiff'
+
+export default [bailiff.configs.recommended]
+```
+
+## Basic Usage
+
+```ts
+import { runBailiff, explain } from '@avelonjs/bailiff'
+
+explain('no-orphan-query')
+
+const result = await runBailiff({ cwd: process.cwd(), fix: false })
+if (result.exitCode !== 0) {
+  throw new Error(result.output)
+}
+```
+
+```sh
+reeve bailiff
+reeve bailiff --fix
+reeve bailiff --explain no-orphan-query
+```
+
+`--fix` applies autofixes only. `--explain` prints the one-sentence reason for a rule and exits. A non-TTY stdout never opens a prompt.
+
+A default scan of `.` skips `node_modules`, `.next`, `dist`, `archive/`, and `spikes/`. Archive and throwaway spikes are not the product linter corpus. `@avelonjs/core` and `@avelonjs/orm` tests may import `bun:test`; runtime sources in those packages still may not import `bun:*`.
+
+## Rules
+
+Every rule ships with a documented reason and an autofix or a disable-with-reason escape hatch. A bare `// bailiff-disable-next-line` with no reason is itself an error.
+
+```ts
+// bailiff-disable-next-line no-raw-outside-drivers -- pgvector similarity, no IR support yet
+const rows = await DB.raw().rpc('match_documents', { embedding })
+```
+
+| Rule                       | Enforces                                                                                         | Level |
+| -------------------------- | ------------------------------------------------------------------------------------------------ | ----- |
+| `no-vendor-import`         | No vendor SDK imported outside a driver package or `avelon.config.ts`                            | error |
+| `no-cross-layer`           | Views cannot import Models. Controllers cannot import Controllers. Models cannot import `Http/`. | error |
+| `no-orphan-query`          | Database access only in Models, Actions, Errands, and seeds                                      | error |
+| `no-unwarded`              | `Scrivener.unwarded()` only in `app/Errands/` and `database/seeds/`                              | error |
+| `require-ward`             | Every model has a ward                                                                           | error |
+| `no-raw-outside-drivers`   | `driver.raw()` only in `app/Drivers/` or behind a reasoned disable                               | error |
+| `no-hand-edited-generated` | Generated paths keep the generator banner                                                        | error |
+| `no-bun-in-core`           | `@avelonjs/core` and `@avelonjs/orm` may not import `bun:*`                                          | error |
+| `no-model-across-boundary` | `view()` receives a serializer, not a model instance                                             | error |
+| `require-request`          | A write action validates through a Request                                                       | error |
+| `no-fake-transaction`      | Sequential writes wrapped in try/catch are not a transaction                                     | error |
+| `relation-depth`           | `.with()` chains cannot exceed driver `maxRelationDepth`                                         | error |
+| `no-lib-dumping`           | There is no `lib/`                                                                               | error |
+| `no-not-supported-error`   | Capability gaps are typed away, never thrown                                                     | error |
+| `attribute-schema-match`   | Model fillable attributes match `database/types.ts`                                              | error |
+| `controller-thinness`      | A controller action past ten statements suggests an Action                                       | warn  |
+| `no-any-public`            | `any` in an exported signature                                                                   | error |
+| `require-disable-reason`   | Every disable names a rule and a reason after `--`                                               | error |
+
+`no-any-public` autofixes `any` to `unknown`. The other error rules fail the build; you suppress one only with a reason that becomes a searchable list of everywhere the framework was not good enough.
+
+## Escape Hatches
+
+Every rule can be disabled inline, and every disable requires a reason. A linter with no escape hatch gets disabled wholesale. A disable with a reason is a roadmap.
+
+```ts
+// bailiff-disable-next-line no-unwarded -- backfill historical rows before wards existed
+const rows = await Scrivener.unwarded(Post).query().get()
+```
+
+## Method Reference
+
+| Method / export              | Signature                                                    | Description                                                                                       |
+| ---------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
+| `plugin`                     | `ESLint.Plugin`                                              | ESLint plugin object with `rules` and `configs`.                                                  |
+| `default`                    | `typeof plugin`                                              | Default export of the ESLint plugin.                                                              |
+| `plugin.configs.recommended` | `Linter.Config`                                              | Flat config that enables every Bailiff rule at its default severity.                              |
+| `recommended`                | `Linter.Config`                                              | Same recommended flat config, exported as a stable binding.                                       |
+| `rules`                      | `Record<RuleName, Rule.RuleModule>`                          | Rule implementations keyed without the plugin prefix.                                             |
+| `reasons`                    | `Readonly<Record<RuleName, string>>`                         | One-sentence reason for each rule.                                                                |
+| `ruleNames`                  | `RuleName[]`                                                 | Rule identifiers in documented order.                                                             |
+| `explain`                    | `(rule: string) => string \| undefined`                      | Returns the reason for a rule, or undefined when the name is unknown.                             |
+| `listRules`                  | `() => Readonly<Record<RuleName, 'error' \| 'warn'>>`        | Default severities, including `controller-thinness` as warn.                                      |
+| `runBailiff`                 | `(options?: BailiffRunOptions) => Promise<BailiffRunResult>` | CLI wrapper used by `reeve bailiff`.                                                              |
+| `parseBailiffArgs`           | `(argv: readonly string[]) => BailiffRunOptions`             | Parses `--fix`, `--explain`, and file operands.                                                   |
+| `defaultIgnores`             | `readonly string[]`                                          | Globs skipped by a default scan: `node_modules`, `.next`, `dist`, `archive/`, `spikes/`.          |
+| `classifyFile`               | `(filePath: string) => FileLayer`                            | Maps a path onto the architecture layer the rules enforce.                                        |
+| `isGeneratedPath`            | `(filePath: string) => boolean`                              | True for `app/(web)/`, `app/(api)/`, `framework/routing/*.generated.ts`, and `database/types.ts`. |
+| `isVendorSpecifier`          | `(specifier: string) => boolean`                             | True for known vendor SDKs such as `@supabase/supabase-js`.                                       |
+| `posixPath`                  | `(filePath: string) => string`                               | Normalizes separators so fixtures and Windows paths classify alike.                               |
+| `GENERATED_BANNER`           | `string`                                                     | Substring generated files must keep in a leading comment.                                         |
+| `RuleName`                   | `type`                                                       | Union of shipped rule identifiers.                                                                |
+| `FileLayer`                  | `type`                                                       | Architecture layer names used by path classification.                                             |
+| `BailiffRunOptions`          | `interface`                                                  | `cwd`, `fix`, `explain`, `files`, and optional ESLint override.                                   |
+| `BailiffRunResult`           | `interface`                                                  | `exitCode`, messages, formatted `output`, and counts.                                             |
+| `BailiffMessage`             | `interface`                                                  | One finding: file, rule, severity, message, line, column.                                         |
+
+## Testing
+
+Point `runBailiff` at a temp directory and assert `exitCode` plus `output`. Fixture files use conventional application paths so layer classification matches a real app.
+
+```ts
+import { runBailiff } from '@avelonjs/bailiff'
+
+const result = await runBailiff({
+  cwd: projectRoot,
+  files: ['app/Http/Controllers/PostController.ts'],
+})
+```
+
+```sh
+bun test
+bun run typecheck
+```

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@avelonjs/bailiff",
+  "version": "0.1.0",
+  "private": false,
+  "description": "ESLint plugin that enforces Avelon architecture rules.",
+  "license": "MIT",
+  "author": "Ryan Yannelli <ryanyannelli@gmail.com>",
+  "homepage": "https://github.com/yannelli/avelon",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yannelli/avelon.git",
+    "directory": "packages/bailiff"
+  },
+  "bugs": {
+    "url": "https://github.com/yannelli/avelon/issues"
+  },
+  "keywords": [
+    "avelon",
+    "typescript",
+    "eslint",
+    "linter"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@typescript-eslint/parser": "8.46.2",
+    "eslint": "9.39.1"
+  },
+  "peerDependencies": {
+    "eslint": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.14",
+    "typescript": "5.9.3"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,160 @@
+import { ESLint, type Linter } from 'eslint'
+import tsParser from '@typescript-eslint/parser'
+
+import { plugin, recommended } from './plugin'
+import { explain, reasons, ruleNames, type RuleName } from './reasons'
+
+/** Globs skipped by a default `reeve bailiff` scan of the working tree. */
+export const defaultIgnores = [
+  '**/node_modules/**',
+  '**/.next/**',
+  '**/dist/**',
+  '**/archive/**',
+  '**/spikes/**',
+] as const
+
+/** Options accepted by the Bailiff CLI wrapper. */
+export interface BailiffRunOptions {
+  /** Project root. Defaults to `process.cwd()`. */
+  cwd?: string
+  /** Apply ESLint autofixes. */
+  fix?: boolean
+  /** Print a rule reason and exit without linting. */
+  explain?: string
+  /** File globs. Defaults to `.` with `defaultIgnores` applied. */
+  files?: readonly string[]
+  /** Extra ESLint config merged after the recommended config. */
+  override?: Linter.Config
+}
+
+/** One reported Bailiff finding. */
+export interface BailiffMessage {
+  filePath: string
+  ruleId: string | null
+  severity: 0 | 1 | 2
+  message: string
+  line: number
+  column: number
+}
+
+/** Result of a Bailiff run, including the process exit code. */
+export interface BailiffRunResult {
+  exitCode: number
+  explanation?: string
+  messages: BailiffMessage[]
+  output: string
+  errorCount: number
+  warningCount: number
+}
+
+function formatMessages(messages: BailiffMessage[]): string {
+  if (messages.length === 0) return 'Bailiff is clean.\n'
+  return `${messages
+    .map(
+      (message) =>
+        `${message.filePath}:${message.line}:${message.column} ${message.ruleId ?? 'bailiff'} ${message.message}`,
+    )
+    .join('\n')}\n`
+}
+
+/** Lists every shipped rule and its default severity. */
+export function listRules(): Readonly<Record<RuleName, 'error' | 'warn'>> {
+  return Object.fromEntries(
+    ruleNames.map((name) => [name, name === 'controller-thinness' ? 'warn' : 'error']),
+  ) as Record<RuleName, 'error' | 'warn'>
+}
+
+/**
+ * Runs Bailiff. `--explain` prints a reason. `--fix` applies autofixes. A non-TTY caller never
+ * sees a prompt; this wrapper is the implementation behind `reeve bailiff`.
+ */
+export async function runBailiff(options: BailiffRunOptions = {}): Promise<BailiffRunResult> {
+  if (options.explain !== undefined) {
+    const reason = explain(options.explain)
+    if (reason === undefined) {
+      const output = `Unknown Bailiff rule '${options.explain}'. Known rules: ${ruleNames.join(', ')}.\n`
+      return { exitCode: 1, messages: [], output, errorCount: 1, warningCount: 0 }
+    }
+    const output = `${options.explain}: ${reason}\n`
+    return {
+      exitCode: 0,
+      explanation: reason,
+      messages: [],
+      output,
+      errorCount: 0,
+      warningCount: 0,
+    }
+  }
+
+  const cwd = options.cwd ?? process.cwd()
+  const eslint = new ESLint({
+    cwd,
+    overrideConfigFile: true,
+    fix: options.fix ?? false,
+    overrideConfig: [
+      {
+        ignores: [...defaultIgnores],
+      },
+      {
+        files: ['**/*.{ts,tsx,mts,cts,js,jsx}'],
+        languageOptions: {
+          parser: tsParser,
+          parserOptions: { ecmaVersion: 2022, sourceType: 'module' },
+        },
+      },
+      recommended,
+      ...(options.override === undefined ? [] : [options.override]),
+    ],
+  })
+
+  const targets = options.files === undefined ? ['.'] : [...options.files]
+  const results = await eslint.lintFiles(targets)
+  if (options.fix) await ESLint.outputFixes(results)
+
+  const messages: BailiffMessage[] = results.flatMap((result) =>
+    result.messages.map((message) => ({
+      filePath: result.filePath,
+      ruleId: message.ruleId,
+      severity: message.severity,
+      message: message.message,
+      line: message.line,
+      column: message.column,
+    })),
+  )
+  const errorCount = results.reduce((sum, result) => sum + result.errorCount, 0)
+  const warningCount = results.reduce((sum, result) => sum + result.warningCount, 0)
+  return {
+    exitCode: errorCount > 0 ? 1 : 0,
+    messages,
+    output: formatMessages(messages),
+    errorCount,
+    warningCount,
+  }
+}
+
+/** Parses `reeve bailiff` argv after the command name has been stripped. */
+export function parseBailiffArgs(argv: readonly string[]): BailiffRunOptions {
+  const files: string[] = []
+  const options: BailiffRunOptions = { files }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--fix') {
+      options.fix = true
+      continue
+    }
+    if (arg === '--explain') {
+      options.explain = argv[i + 1]
+      i += 1
+      continue
+    }
+    if (arg?.startsWith('--explain=')) {
+      options.explain = arg.slice('--explain='.length)
+      continue
+    }
+    if (arg !== undefined && !arg.startsWith('-')) files.push(arg)
+  }
+  if (files.length === 0) delete options.files
+  return options
+}
+
+export { reasons, ruleNames }

package/src/index.ts

@@ -0,0 +1,20 @@
+export { default, plugin, recommended } from './plugin'
+export { rules } from './rules'
+export { reasons, ruleNames, explain, type RuleName } from './reasons'
+export {
+  runBailiff,
+  parseBailiffArgs,
+  listRules,
+  defaultIgnores,
+  type BailiffRunOptions,
+  type BailiffRunResult,
+  type BailiffMessage,
+} from './cli'
+export {
+  classifyFile,
+  isGeneratedPath,
+  isVendorSpecifier,
+  posixPath,
+  GENERATED_BANNER,
+  type FileLayer,
+} from './paths'

package/src/paths.ts

@@ -0,0 +1,179 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join, posix, relative, sep } from 'node:path'
+
+/** Layer a source file belongs to, used by architecture rules. */
+export type FileLayer =
+  | 'model'
+  | 'view'
+  | 'controller'
+  | 'action'
+  | 'errand'
+  | 'seed'
+  | 'page'
+  | 'component'
+  | 'driver'
+  | 'config'
+  | 'core'
+  | 'orm'
+  | 'generated'
+  | 'ward'
+  | 'lib'
+  | 'request'
+  | 'other'
+
+const GENERATED_MARKERS = [
+  '/app/(web)/',
+  '/app/(api)/',
+  '/framework/routing/',
+  '/database/types.ts',
+]
+
+const VENDOR_PACKAGES = [
+  '@supabase/supabase-js',
+  '@supabase/ssr',
+  '@supabase/auth-js',
+  'postgres',
+  'pg',
+  'resend',
+  'stripe',
+  'openai',
+  'next-auth',
+  '@auth/core',
+  '@clerk/nextjs',
+  '@clerk/backend',
+  'hono',
+]
+
+/** Normalizes a file path to posix so fixtures and Windows paths classify the same way. */
+export function posixPath(filePath: string): string {
+  return filePath.split(sep).join(posix.sep)
+}
+
+/** Returns true when `filePath` is framework-generated and must not be hand-edited. */
+export function isGeneratedPath(filePath: string): boolean {
+  const normalized = posixPath(filePath)
+  if (GENERATED_MARKERS.some((marker) => normalized.includes(marker))) return true
+  return /\/framework\/routing\/.*\.generated\.ts$/.test(normalized)
+}
+
+/** Returns true when the specifier is a known vendor SDK. */
+export function isVendorSpecifier(specifier: string): boolean {
+  if (specifier.startsWith('@supabase/')) return true
+  if (specifier.startsWith('@aws-sdk/')) return true
+  if (specifier.startsWith('@neondatabase/')) return true
+  return VENDOR_PACKAGES.includes(specifier)
+}
+
+/** Classifies a source file into the architecture layer Bailiff enforces. */
+export function classifyFile(filePath: string): FileLayer {
+  const normalized = posixPath(filePath)
+  if (/(?:^|\/)avelon\.config\.(ts|js|mts|cts)$/.test(normalized)) return 'config'
+  if (normalized.includes('/app/(web)/') || normalized.includes('/app/(api)/')) return 'page'
+  if (/\/page\.tsx$/.test(normalized) || /\/route\.ts$/.test(normalized)) return 'page'
+  if (isGeneratedPath(normalized)) return 'generated'
+  if (normalized.includes('/packages/core/') || /(?:^|\/)packages\/core\//.test(normalized)) {
+    return 'core'
+  }
+  if (normalized.includes('/packages/orm/')) return 'orm'
+  if (
+    normalized.includes('/packages/supabase/') ||
+    normalized.includes('/packages/postgres/') ||
+    normalized.includes('/packages/resend/') ||
+    normalized.includes('/app/Drivers/')
+  ) {
+    return 'driver'
+  }
+  if (normalized.includes('/app/Models/')) return 'model'
+  if (normalized.includes('/app/Http/Views/')) return 'view'
+  if (normalized.includes('/app/Http/Controllers/')) return 'controller'
+  if (normalized.includes('/app/Http/Requests/')) return 'request'
+  if (normalized.includes('/app/Actions/')) return 'action'
+  if (normalized.includes('/app/Errands/')) return 'errand'
+  if (normalized.includes('/database/seeds/')) return 'seed'
+  if (normalized.includes('/app/Wards/')) return 'ward'
+  if (/(?:^|\/)lib\//.test(normalized) || normalized.includes('/src/lib/')) return 'lib'
+  if (normalized.includes('/resources/views/') || /\/components\//.test(normalized)) {
+    return 'component'
+  }
+  if (normalized.endsWith('.tsx')) return 'component'
+  return 'other'
+}
+
+/** Layers where unwarded queries and raw database work are allowed. */
+export function allowsUnwarded(layer: FileLayer): boolean {
+  return layer === 'errand' || layer === 'seed'
+}
+
+/** Layers where application code may execute queries. */
+export function allowsQuery(layer: FileLayer): boolean {
+  return layer === 'model' || layer === 'action' || layer === 'errand' || layer === 'seed'
+}
+
+/** Layers where vendor SDKs may be imported. */
+export function allowsVendor(layer: FileLayer): boolean {
+  return layer === 'driver' || layer === 'config'
+}
+
+/** Returns true when the path is a test file rather than runtime source. */
+export function isTestFile(filePath: string): boolean {
+  const normalized = posixPath(filePath)
+  if (/(?:^|\/)tests?\//.test(normalized)) return true
+  return /\.(?:test|spec)\.(?:[cm]?[jt]sx?)$/.test(normalized)
+}
+
+/** Returns true when the file must not import bun:*. Tests may import bun:test. */
+export function bansBun(layer: FileLayer, filePath: string): boolean {
+  if (isTestFile(filePath)) return false
+  return layer === 'core' || layer === 'orm'
+}
+
+/** Resolves `database/types.ts` walking up from the linted file. */
+export function findSchemaTypes(filePath: string, cwd = process.cwd()): string | undefined {
+  let directory = dirname(filePath)
+  const root = posixPath(cwd)
+  for (let i = 0; i < 12; i += 1) {
+    const candidate = join(directory, 'database', 'types.ts')
+    if (existsSync(candidate)) return candidate
+    const parent = dirname(directory)
+    if (parent === directory) break
+    if (posixPath(relative(root, directory)).startsWith('..')) break
+    directory = parent
+  }
+  const fallback = join(cwd, 'database', 'types.ts')
+  return existsSync(fallback) ? fallback : undefined
+}
+
+/** Reads generated schema column names for a table when `database/types.ts` exists. */
+export function schemaColumns(filePath: string, table: string, cwd?: string): string[] | undefined {
+  const typesPath = findSchemaTypes(filePath, cwd)
+  if (typesPath === undefined) return undefined
+  const source = readFileSync(typesPath, 'utf8')
+  const escaped = table.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const block = new RegExp(`${escaped}\\s*:\\s*\\{([^}]+)\\}`, 'm').exec(source)
+  if (block === null) return undefined
+  const columns: string[] = []
+  const body = block[1]
+  if (body === undefined) return undefined
+  for (const match of body.matchAll(/^\s*([A-Za-z_][\w]*)\s*:/gm)) {
+    const name = match[1]
+    if (name !== undefined) columns.push(name)
+  }
+  return columns
+}
+
+/** Returns true when a matching ward file exists for a model class. */
+export function wardExists(filePath: string, modelName: string): boolean {
+  const normalized = posixPath(filePath)
+  const marker = '/app/Models/'
+  const index = normalized.lastIndexOf(marker)
+  if (index === -1) return true
+  const appRoot = filePath.slice(0, filePath.lastIndexOf(`${sep}Models${sep}`))
+  const candidates = [
+    join(appRoot, 'Wards', `${modelName}Ward.ts`),
+    join(dirname(dirname(filePath)), 'Wards', `${modelName}Ward.ts`),
+  ]
+  return candidates.some((candidate) => existsSync(candidate))
+}
+
+/** Banner generated files must keep as their first non-empty comment. */
+export const GENERATED_BANNER = 'Generated by'

package/src/plugin.ts

@@ -0,0 +1,33 @@
+import type { ESLint, Linter } from 'eslint'
+
+import { ruleNames } from './reasons'
+import { rules } from './rules'
+
+const plugin = {
+  meta: {
+    name: '@avelonjs/bailiff',
+    version: '0.0.0',
+  },
+  rules,
+  configs: {} as Record<string, Linter.Config>,
+} satisfies ESLint.Plugin & { configs: Record<string, Linter.Config> }
+
+const recommendedRules: Linter.RulesRecord = Object.fromEntries(
+  ruleNames.map((name) => [
+    `@avelonjs/bailiff/${name}`,
+    name === 'controller-thinness' ? 'warn' : 'error',
+  ]),
+)
+
+/** Flat ESLint config that enables every Bailiff rule at its default severity. */
+export const recommended: Linter.Config = {
+  name: '@avelonjs/bailiff/recommended',
+  plugins: { '@avelonjs/bailiff': plugin },
+  rules: recommendedRules,
+}
+
+plugin.configs.recommended = recommended
+
+/** ESLint plugin plus the recommended config that turns every rule on. */
+export default plugin
+export { plugin }

package/src/reasons.ts

@@ -0,0 +1,48 @@
+/** One-sentence reasons. A rule you cannot explain in one sentence does not belong. */
+export const reasons = {
+  'no-vendor-import':
+    'One vendor SDK import in application code makes the driver system decorative.',
+  'no-cross-layer':
+    'Views importing models, controllers importing controllers, or models importing Http/ collapse the directory map.',
+  'no-orphan-query':
+    'Database access belongs in models, actions, errands, and seeds, never in a page or component.',
+  'no-unwarded': 'Unwarded queries outside errands and seeds are how row access leaks.',
+  'require-ward': 'A model without a ward is a table anybody can read.',
+  'no-raw-outside-drivers':
+    'driver.raw() is the non-portable escape hatch and may live only in app/Drivers/.',
+  'no-hand-edited-generated':
+    'A hand-edit to generated output disappears at the next sync and takes the upgrade path with it.',
+  'no-bun-in-core':
+    '@avelonjs/core and @avelonjs/orm must stay runtime-portable, so bun:* imports are banned there.',
+  'no-model-across-boundary':
+    'A model instance passed to view() becomes a serialization failure at the adapter boundary.',
+  'require-request':
+    'Write actions validate through a Request so invalid input never reaches a model.',
+  'no-fake-transaction':
+    'Sequential writes wrapped in try/catch and named like a transaction are not atomic.',
+  'relation-depth':
+    '.with() chains past the configured driver maxRelationDepth will fail at the vendor, not at types.',
+  'no-lib-dumping':
+    'There is no lib/; a file has a home in the application tree or it does not exist.',
+  'no-not-supported-error':
+    'Throwing on a missing capability is a design failure; the capability map should have removed the method.',
+  'attribute-schema-match':
+    'Model fillable attributes must match database/types.ts so a column rename is a type error.',
+  'controller-thinness':
+    'A controller action past a handful of statements belongs in app/Actions/.',
+  'no-any-public':
+    'any in an exported signature is banned; unknown plus a narrowing function is the move.',
+  'require-disable-reason':
+    'A disable without a reason is how the linter gets turned off wholesale.',
+} as const
+
+/** Rule identifiers Bailiff ships. */
+export type RuleName = keyof typeof reasons
+
+/** Stable rule names in documented order. */
+export const ruleNames = Object.keys(reasons) as RuleName[]
+
+/** Returns the one-sentence reason for a rule, or undefined when the name is unknown. */
+export function explain(rule: string): string | undefined {
+  return reasons[rule as RuleName]
+}

package/src/rules.ts

@@ -0,0 +1,577 @@
+import type { Rule } from 'eslint'
+
+interface Node {
+  type: string
+}
+
+interface Comment {
+  value: string
+  loc?: { end: { line: number } } | null
+}
+
+import {
+  GENERATED_BANNER,
+  allowsQuery,
+  allowsUnwarded,
+  allowsVendor,
+  bansBun,
+  classifyFile,
+  isGeneratedPath,
+  isVendorSpecifier,
+  schemaColumns,
+  wardExists,
+  type FileLayer,
+} from './paths'
+import { reasons, type RuleName } from './reasons'
+import { disableComments, report } from './suppress'
+
+interface CallLike {
+  type: string
+  callee?: {
+    type: string
+    name?: string
+    property?: { type: string; name?: string }
+    object?: { type: string; name?: string; property?: { name?: string } }
+  }
+  arguments?: unknown[]
+}
+
+interface ImportLike {
+  type: string
+  source?: { type: string; value?: string | null }
+}
+
+function specifierOf(node: ImportLike): string | undefined {
+  if (node.source?.type !== 'Literal') return undefined
+  return typeof node.source.value === 'string' ? node.source.value : undefined
+}
+
+function callName(node: CallLike): string {
+  const callee = node.callee
+  if (callee === undefined) return ''
+  if (callee.type === 'Identifier') return callee.name ?? ''
+  if (callee.type === 'MemberExpression') {
+    const object =
+      callee.object?.type === 'Identifier'
+        ? (callee.object.name ?? '')
+        : (callee.object?.property?.name ?? '')
+    const property = callee.property?.type === 'Identifier' ? (callee.property.name ?? '') : ''
+    return `${object}.${property}`
+  }
+  return ''
+}
+
+function isWriteAction(name: string): boolean {
+  return name === 'store' || name === 'update' || name === 'destroy'
+}
+
+function statementCount(node: { body?: { type?: string; body?: unknown[] } }): number {
+  const body = node.body
+  if (body?.type === 'BlockStatement' && Array.isArray(body.body)) return body.body.length
+  return 1
+}
+
+function relationDepth(value: unknown, current = 1): number {
+  if (typeof value !== 'object' || value === null) return current
+  const record = value as {
+    type?: string
+    properties?: Array<{ key?: { name?: string }; value?: unknown }>
+  }
+  if (record.type !== 'ObjectExpression' || record.properties === undefined) return current
+  const nested = record.properties.find((property) => property.key?.name === 'relations')
+  if (nested === undefined) return current
+  const list = nested.value as { type?: string; elements?: unknown[] }
+  if (
+    list.type !== 'ArrayExpression' ||
+    list.elements === undefined ||
+    list.elements.length === 0
+  ) {
+    return current
+  }
+  return Math.max(...list.elements.map((element) => relationDepth(element, current + 1)))
+}
+
+function looksLikeTransactionName(name: string): boolean {
+  return /transaction/i.test(name)
+}
+
+function hasTryCatch(node: Node): boolean {
+  let found = false
+  walk(node, (child) => {
+    if ((child as { type?: string }).type === 'TryStatement') found = true
+  })
+  return found
+}
+
+const SKIP_WALK_KEYS = new Set([
+  'parent',
+  'loc',
+  'range',
+  'tokens',
+  'comments',
+  'leadingComments',
+  'trailingComments',
+])
+
+function walk(node: unknown, visit: (node: Node) => void, seen = new Set<unknown>()): void {
+  if (typeof node !== 'object' || node === null) return
+  if (seen.has(node)) return
+  seen.add(node)
+  const current = node as Node & { type?: string }
+  if (typeof current.type === 'string') visit(current)
+  for (const [key, value] of Object.entries(current)) {
+    if (SKIP_WALK_KEYS.has(key)) continue
+    if (Array.isArray(value)) {
+      for (const entry of value) walk(entry, visit, seen)
+    } else {
+      walk(value, visit, seen)
+    }
+  }
+}
+
+function hasSequentialWrites(node: Node): boolean {
+  const writes: string[] = []
+  walk(node, (child) => {
+    const name = callName(child as CallLike)
+    if (
+      /\.(create|update|insert|save|delete)$/.test(name) ||
+      name === 'create' ||
+      name === 'save'
+    ) {
+      writes.push(name)
+    }
+  })
+  return writes.length >= 2
+}
+
+function exportedAnyNodes(node: Node): Node[] {
+  const hits: Node[] = []
+  walk(node, (child) => {
+    if ((child as { type?: string }).type === 'TSAnyKeyword') hits.push(child)
+  })
+  return hits
+}
+
+function ruleModule(
+  name: RuleName,
+  create: (context: Rule.RuleContext, layer: FileLayer) => Rule.RuleListener,
+): Rule.RuleModule {
+  return {
+    meta: {
+      type: name === 'controller-thinness' ? 'suggestion' : 'problem',
+      docs: { description: reasons[name] },
+      schema: [],
+      messages: { default: '{{detail}}' },
+      ...(name === 'no-any-public' ? { fixable: 'code' as const } : {}),
+    },
+    create(context) {
+      const layer = classifyFile(context.filename)
+      return create(context, layer)
+    },
+  }
+}
+
+const noVendorImport = ruleModule('no-vendor-import', (context, layer) => ({
+  ImportDeclaration(node) {
+    const specifier = specifierOf(node as ImportLike)
+    if (specifier === undefined || !isVendorSpecifier(specifier) || allowsVendor(layer)) return
+    report(
+      context,
+      'no-vendor-import',
+      node as Rule.Node,
+      `Vendor SDK '${specifier}' may only be imported from a driver package or avelon.config.ts.`,
+    )
+  },
+}))
+
+const noCrossLayer = ruleModule('no-cross-layer', (context, layer) => ({
+  ImportDeclaration(node) {
+    const specifier = specifierOf(node as ImportLike) ?? ''
+    if (layer === 'view' && specifier.includes('/Models/')) {
+      report(
+        context,
+        'no-cross-layer',
+        node as Rule.Node,
+        'Views cannot import Models. Serialize through app/Http/Views/.',
+      )
+    }
+    if (
+      layer === 'controller' &&
+      specifier.includes('/Http/Controllers/') &&
+      !specifier.endsWith('/controller')
+    ) {
+      report(
+        context,
+        'no-cross-layer',
+        node as Rule.Node,
+        'Controllers cannot import other controllers.',
+      )
+    }
+    if (layer === 'model' && specifier.includes('/Http/')) {
+      report(
+        context,
+        'no-cross-layer',
+        node as Rule.Node,
+        'Models cannot import anything under Http/.',
+      )
+    }
+  },
+}))
+
+const noOrphanQuery = ruleModule('no-orphan-query', (context, layer) => ({
+  ImportDeclaration(node) {
+    if (allowsQuery(layer)) return
+    if (layer !== 'page' && layer !== 'component' && layer !== 'view') return
+    const specifier = specifierOf(node as ImportLike) ?? ''
+    if (specifier === '@avelonjs/orm' || specifier.includes('/Models/')) {
+      report(
+        context,
+        'no-orphan-query',
+        node as Rule.Node,
+        'Database access is not allowed in a component or page. Load data in a controller or action.',
+      )
+    }
+  },
+  MemberExpression(node) {
+    if (allowsQuery(layer) || (layer !== 'page' && layer !== 'component')) return
+    const expression = node as {
+      object?: { type?: string; name?: string }
+      property?: { type?: string; name?: string }
+    }
+    if (expression.object?.type === 'Identifier' && expression.object.name === 'DB') {
+      report(
+        context,
+        'no-orphan-query',
+        node as Rule.Node,
+        'Database access is not allowed in a component or page.',
+      )
+    }
+  },
+}))
+
+const noUnwarded = ruleModule('no-unwarded', (context, layer) => ({
+  CallExpression(node) {
+    if (allowsUnwarded(layer)) return
+    const name = callName(node as CallLike)
+    if (name === 'unwarded' || name.endsWith('.unwarded') || name === 'Scrivener.unwarded') {
+      report(
+        context,
+        'no-unwarded',
+        node as Rule.Node,
+        'Scrivener.unwarded() is allowed only in app/Errands/ and database/seeds/.',
+      )
+    }
+  },
+}))
+
+const requireWard = ruleModule('require-ward', (context, layer) => ({
+  ClassDeclaration(node) {
+    if (layer !== 'model') return
+    const id = (node as { id?: { name?: string } }).id?.name
+    if (id === undefined || id === 'Model') return
+    if (wardExists(context.filename, id)) return
+    report(
+      context,
+      'require-ward',
+      node as Rule.Node,
+      `Model ${id} is missing ${id}Ward. Every model has a ward.`,
+    )
+  },
+}))
+
+const noRawOutsideDrivers = ruleModule('no-raw-outside-drivers', (context, layer) => ({
+  CallExpression(node) {
+    if (allowsVendor(layer)) return
+    const name = callName(node as CallLike)
+    if (name === 'raw' || name.endsWith('.raw')) {
+      report(
+        context,
+        'no-raw-outside-drivers',
+        node as Rule.Node,
+        'driver.raw() is allowed only in app/Drivers/ or avelon.config.ts.',
+      )
+    }
+  },
+}))
+
+const noHandEditedGenerated = ruleModule('no-hand-edited-generated', (context) => ({
+  Program(node) {
+    if (!isGeneratedPath(context.filename)) return
+    const comments = context.sourceCode.getAllComments()
+    const header = comments
+      .slice(0, 3)
+      .map((comment: Comment) => comment.value)
+      .join('\n')
+    if (header.includes(GENERATED_BANNER)) return
+    report(
+      context,
+      'no-hand-edited-generated',
+      node as Rule.Node,
+      'Generated files must keep the generator banner. Hand-edits are discarded on the next sync.',
+    )
+  },
+}))
+
+const noBunInCore = ruleModule('no-bun-in-core', (context, layer) => ({
+  ImportDeclaration(node) {
+    if (!bansBun(layer, context.filename)) return
+    const specifier = specifierOf(node as ImportLike) ?? ''
+    if (specifier === 'bun' || specifier.startsWith('bun:')) {
+      report(
+        context,
+        'no-bun-in-core',
+        node as Rule.Node,
+        '@avelonjs/core and @avelonjs/orm may not import bun:*.',
+      )
+    }
+  },
+}))
+
+const noModelAcrossBoundary = ruleModule('no-model-across-boundary', (context) => ({
+  CallExpression(node) {
+    const callee = (node as CallLike).callee
+    if (callee?.type !== 'Identifier' || callee.name !== 'view') return
+    const args = (node as { arguments?: Array<{ type?: string; properties?: unknown[] }> })
+      .arguments
+    const props = args?.[1]
+    if (props?.type !== 'ObjectExpression' || !Array.isArray(props.properties)) return
+    for (const property of props.properties as Array<{
+      type?: string
+      value?: {
+        type?: string
+        name?: string
+        callee?: { type?: string; property?: { name?: string } }
+      }
+    }>) {
+      if (property.type !== 'Property') continue
+      const value = property.value
+      if (value?.type === 'Identifier') {
+        report(
+          context,
+          'no-model-across-boundary',
+          node as Rule.Node,
+          `Pass a serializer to view(), not the raw value '${value.name}'.`,
+        )
+      }
+      if (
+        value?.type === 'CallExpression' &&
+        value.callee?.type === 'MemberExpression' &&
+        value.callee.property?.name !== 'make' &&
+        value.callee.property?.name !== 'collection'
+      ) {
+        report(
+          context,
+          'no-model-across-boundary',
+          node as Rule.Node,
+          'Pass a serializer to view(), not a model instance.',
+        )
+      }
+    }
+  },
+}))
+
+const requireRequest = ruleModule('require-request', (context, layer) => ({
+  MethodDefinition(node) {
+    if (layer !== 'controller') return
+    const key = (node as { key?: { type?: string; name?: string } }).key
+    const name = key?.type === 'Identifier' ? key.name : undefined
+    if (name === undefined || !isWriteAction(name)) return
+    const value = (node as { value?: Node }).value
+    if (value === undefined) return
+    let validated = false
+    walk(value, (child) => {
+      const called = callName(child as CallLike)
+      if (called.endsWith('.validate') || called === 'validateRequest') validated = true
+    })
+    if (validated) return
+    report(
+      context,
+      'require-request',
+      node as Rule.Node,
+      `Write action ${name}() must validate through a Request.`,
+    )
+  },
+}))
+
+const noFakeTransaction = ruleModule('no-fake-transaction', (context) => ({
+  FunctionDeclaration(node) {
+    const name = (node as { id?: { name?: string } }).id?.name ?? ''
+    if (!looksLikeTransactionName(name)) return
+    if (!hasTryCatch(node as Node) || !hasSequentialWrites(node as Node)) return
+    report(
+      context,
+      'no-fake-transaction',
+      node as Rule.Node,
+      'Sequential writes wrapped in try/catch are not a transaction. Use DB.transaction or a driver rpc.',
+    )
+  },
+  MethodDefinition(node) {
+    const name = (node as { key?: { name?: string } }).key?.name ?? ''
+    if (!looksLikeTransactionName(name)) return
+    const value = (node as { value?: Node }).value
+    if (value === undefined || !hasTryCatch(value) || !hasSequentialWrites(value)) return
+    report(
+      context,
+      'no-fake-transaction',
+      node as Rule.Node,
+      'Sequential writes wrapped in try/catch are not a transaction. Use DB.transaction or a driver rpc.',
+    )
+  },
+}))
+
+const relationDepthRule = ruleModule('relation-depth', (context) => ({
+  CallExpression(node) {
+    const name = callName(node as CallLike)
+    if (!name.endsWith('.with') && name !== 'with') return
+    const args = (node as { arguments?: unknown[] }).arguments ?? []
+    const depth = Math.max(1, ...args.map((argument) => relationDepth(argument, 1)))
+    const max = 2
+    if (depth <= max) return
+    report(
+      context,
+      'relation-depth',
+      node as Rule.Node,
+      `.with() depth ${depth} exceeds the configured driver maxRelationDepth of ${max}.`,
+    )
+  },
+}))
+
+const noLibDumping = ruleModule('no-lib-dumping', (context, layer) => ({
+  Program(node) {
+    if (layer !== 'lib') return
+    report(
+      context,
+      'no-lib-dumping',
+      node as Rule.Node,
+      'There is no lib/. Put this file in app/, config/, database/, or resources/.',
+    )
+  },
+}))
+
+const noNotSupportedError = ruleModule('no-not-supported-error', (context) => ({
+  Identifier(node) {
+    if ((node as { name?: string }).name !== 'NotSupportedError') return
+    report(
+      context,
+      'no-not-supported-error',
+      node as Rule.Node,
+      'NotSupportedError is banned. Narrow the capability map instead of throwing.',
+    )
+  },
+}))
+
+const attributeSchemaMatch = ruleModule('attribute-schema-match', (context, layer) => ({
+  ClassDeclaration(node) {
+    if (layer !== 'model') return
+    const className = (node as { id?: { name?: string } }).id?.name
+    if (className === undefined) return
+    const body = (node as { body?: { body?: unknown[] } }).body?.body ?? []
+    let table = ''
+    let fillable: string[] = []
+    for (const member of body as Array<{
+      key?: { name?: string }
+      value?: { type?: string; value?: unknown; elements?: Array<{ value?: unknown }> }
+    }>) {
+      if (member.key?.name === 'table' && typeof member.value?.value === 'string') {
+        table = member.value.value
+      }
+      if (member.key?.name === 'fillable' && Array.isArray(member.value?.elements)) {
+        fillable = member.value.elements.flatMap((element) =>
+          typeof element.value === 'string' ? [element.value] : [],
+        )
+      }
+    }
+    if (table.length === 0 || fillable.length === 0) return
+    const columns = schemaColumns(context.filename, table, context.cwd)
+    if (columns === undefined) return
+    const unknown = fillable.filter((column) => !columns.includes(column))
+    if (unknown.length === 0) return
+    report(
+      context,
+      'attribute-schema-match',
+      node as Rule.Node,
+      `Model ${className} fillable columns [${unknown.join(', ')}] are missing from database/types.ts table '${table}'.`,
+    )
+  },
+}))
+
+const controllerThinness = ruleModule('controller-thinness', (context, layer) => ({
+  MethodDefinition(node) {
+    if (layer !== 'controller') return
+    const name = (node as { key?: { name?: string } }).key?.name ?? 'action'
+    const value = (node as { value?: { body?: { type?: string; body?: unknown[] } } }).value
+    if (value === undefined) return
+    const count = statementCount(value)
+    if (count <= 10) return
+    report(
+      context,
+      'controller-thinness',
+      node as Rule.Node,
+      `Controller action ${name}() has ${count} statements. Move the work to app/Actions/.`,
+    )
+  },
+}))
+
+const noAnyPublic = ruleModule('no-any-public', (context) => ({
+  ExportNamedDeclaration(node) {
+    for (const hit of exportedAnyNodes(node as Node)) {
+      report(
+        context,
+        'no-any-public',
+        hit as Rule.Node,
+        'any is not allowed in an exported signature. Use unknown.',
+        (fixer) => fixer.replaceText(hit as Rule.Node, 'unknown'),
+      )
+    }
+  },
+  ExportDefaultDeclaration(node) {
+    for (const hit of exportedAnyNodes(node as Node)) {
+      report(
+        context,
+        'no-any-public',
+        hit as Rule.Node,
+        'any is not allowed in an exported signature. Use unknown.',
+        (fixer) => fixer.replaceText(hit as Rule.Node, 'unknown'),
+      )
+    }
+  },
+}))
+
+const requireDisableReason = ruleModule('require-disable-reason', (context) => ({
+  Program(node) {
+    for (const comment of disableComments(context)) {
+      if (comment.reason !== undefined && comment.rule !== undefined) continue
+      const locNode = context.sourceCode
+        .getAllComments()
+        .find((entry) => entry.value.trim() === comment.raw)
+      report(
+        context,
+        'require-disable-reason',
+        (locNode ?? node) as Rule.Node,
+        'bailiff-disable-next-line requires a rule name and a reason after --.',
+      )
+    }
+  },
+}))
+
+/** ESLint rule map keyed without the plugin prefix. */
+export const rules: Record<RuleName, Rule.RuleModule> = {
+  'no-vendor-import': noVendorImport,
+  'no-cross-layer': noCrossLayer,
+  'no-orphan-query': noOrphanQuery,
+  'no-unwarded': noUnwarded,
+  'require-ward': requireWard,
+  'no-raw-outside-drivers': noRawOutsideDrivers,
+  'no-hand-edited-generated': noHandEditedGenerated,
+  'no-bun-in-core': noBunInCore,
+  'no-model-across-boundary': noModelAcrossBoundary,
+  'require-request': requireRequest,
+  'no-fake-transaction': noFakeTransaction,
+  'relation-depth': relationDepthRule,
+  'no-lib-dumping': noLibDumping,
+  'no-not-supported-error': noNotSupportedError,
+  'attribute-schema-match': attributeSchemaMatch,
+  'controller-thinness': controllerThinness,
+  'no-any-public': noAnyPublic,
+  'require-disable-reason': requireDisableReason,
+}

package/src/suppress.ts

@@ -0,0 +1,62 @@
+import type { Rule } from 'eslint'
+
+const DISABLE_PATTERN =
+  /(?:bailiff-disable-next-line|eslint-disable-next-line)(?:\s+((?:@avelonjs\/bailiff\/)?[\w-]+))?(?:\s+--\s*(.+))?/
+
+export interface DisableComment {
+  line: number
+  rule?: string
+  reason?: string
+  raw: string
+}
+
+/** Parses Bailiff and ESLint next-line disable comments. */
+export function parseDisable(text: string): Omit<DisableComment, 'line' | 'raw'> | undefined {
+  const match = DISABLE_PATTERN.exec(text)
+  if (match === null) return undefined
+  const rule = match[1]?.replace('@avelonjs/bailiff/', '')
+  const reason = match[2]?.trim()
+  return { rule, reason: reason === '' ? undefined : reason }
+}
+
+/** Collects disable comments from the current ESLint source. */
+export function disableComments(context: Rule.RuleContext): DisableComment[] {
+  return context.sourceCode.getAllComments().flatMap((comment) => {
+    const parsed = parseDisable(comment.value)
+    if (parsed === undefined) return []
+    const line = comment.loc?.end.line
+    if (line === undefined) return []
+    return [{ line, raw: comment.value.trim(), ...parsed }]
+  })
+}
+
+/** Returns true when a node is suppressed by a reasoned disable comment on the previous line. */
+export function isSuppressed(
+  context: Rule.RuleContext,
+  node: { loc?: { start: { line: number } } | null },
+  rule: string,
+): boolean {
+  const line = node.loc?.start.line
+  if (line === undefined) return false
+  return disableComments(context).some((comment) => {
+    if (comment.line !== line - 1 && comment.line !== line) return false
+    if (comment.reason === undefined) return false
+    return comment.rule === undefined || comment.rule === rule
+  })
+}
+
+/** Reports a violation unless a reasoned disable comment suppresses it. */
+export function report(
+  context: Rule.RuleContext,
+  rule: string,
+  node: Rule.Node,
+  message: string,
+  fix?: (fixer: Rule.RuleFixer) => Rule.Fix | Rule.Fix[] | null,
+): void {
+  if (isSuppressed(context, node, rule)) return
+  context.report({
+    node,
+    message,
+    ...(fix === undefined ? {} : { fix }),
+  })
+}