@ontrails/warden 0.2.0

package/README.md

@@ -0,0 +1,200 @@
+# @ontrails/warden
+
+AST-based code convention rules for Trails. Built-in lint rules catch contract violations at development time, alongside lock drift detection and CI formatters.
+
+Structural checks (compose target existence, declared resource existence, recursive composition, example schema validation) live in `validateTopo()` from `@ontrails/core`. Warden handles the code-level rules that need AST analysis.
+
+For rule-home boundaries and authoring doctrine, see the [Warden guide](../../docs/warden.md) and [Warden Rules](../../docs/contributing/warden-rules.md).
+
+## Usage
+
+From the Trails CLI:
+
+```bash
+bunx trails warden # Run all checks
+```
+
+Or programmatically:
+
+```typescript
+import { runWarden, formatWardenReport } from '@ontrails/warden';
+
+const report = await runWarden({ topo: graph });
+console.log(formatWardenReport(report));
+```
+
+## Rules
+
+Built-in rules are registered in `wardenRules` and `wardenTopoRules`; use those registries or `wardenTopo.ids()` for the current rule list instead of copying a static table into docs.
+
+Rules cover several families:
+
+- implementation and `Result` contract checks
+- compose, fire, resource, and detour declaration drift
+- draft-state containment
+- source-static guardrails such as surface-type leakage
+- topo-aware checks that need the resolved graph or resource mock shape
+
+When adding or auditing rules, follow [Warden Rules](../../docs/contributing/warden-rules.md): name the invariant, import owner-held framework data, choose the narrowest Warden tier, and collapse families only when the data model, traversal, and diagnostic shape are shared.
+
+## Project-local rules
+
+Projects can carry local Warden rules in `.trails/rules.ts` or direct `.trails/rules/*.ts` files. `runWarden()` and `trails warden` load those files by default for lint runs, then run those rules alongside the built-in registries. Drift-only runs do not import project-local rule modules. Embedders that need only built-in or explicitly provided rules can pass `projectRules: false`.
+
+Warden does not recursively discover nested `.trails/rules` files. Use nested files as private helpers and re-export from a direct entrypoint when a local rule grows. Rule ids must be unique across every project-local module. The retired `trails/warden/rules` location reports a migration diagnostic instead of loading.
+
+Warden uses the shared Trails project-root resolver when a caller does not pass `rootDir` or `--root-dir`, so commands launched from nested directories still load the nearest root `trails.config.*` and its `.trails/rules*` files. An explicit root always wins over discovery.
+
+This is the right home for repo-specific migration checks or governance that has not earned a place in `@ontrails/warden` itself.
+
+## Scope
+
+Use `warden.scope.exclude` in `trails.config.*` to keep generated, scratch, or local planning paths outside Warden governance while leaving durable project paths in scope.
+
+```json
+{
+  "warden": {
+    "scope": {
+      "exclude": [".scratch/**", ".agents/notes/**"]
+    }
+  }
+}
+```
+
+For a single run, pass one or more root-relative globs:
+
+```bash
+warden --scope-exclude '.scratch/**' --scope-exclude '.agents/notes/**'
+```
+
+Scope is a governance boundary, not a migration scan boundary. Regrade uses its own `scope.exclude` / `--exclude` controls for migration plans.
+
+A rule module may export `rule`, `rules`, `sourceRule`, `sourceRules`, `topoRule`, or `topoRules`. Rules without explicit metadata receive default repo-local source-static or topo-aware metadata so short migration rules can run without extra ceremony. Project-aware source rules that provide `checkWithContext()` default to repo-local project-static metadata.
+
+```typescript
+export const rule = {
+  name: 'local-contract-check',
+  severity: 'error',
+  description: 'Local contract examples keep their migration marker.',
+  check(sourceCode, filePath) {
+    return sourceCode.includes('deprecatedMarker')
+      ? [
+          {
+            filePath,
+            line: 1,
+            message: 'Replace deprecatedMarker before release.',
+            rule: 'local-contract-check',
+            severity: 'error',
+          },
+        ]
+      : [];
+  },
+};
+```
+
+## Drift detection
+
+Warden integrates with `@ontrails/topography` to detect when the topo has changed without updating the lock file:
+
+```typescript
+import { checkDrift } from '@ontrails/warden';
+
+const drift = await checkDrift(process.cwd(), graph);
+if (drift.stale) {
+  console.log('lock file is stale -- regenerate with `trails compile`');
+}
+```
+
+## CI integration
+
+Add to lefthook for pre-push enforcement:
+
+```yaml
+pre-push:
+  commands:
+    warden:
+      run: bunx trails warden
+      tags: governance
+```
+
+CI formatters for structured output:
+
+```typescript
+import {
+  formatGitHubAnnotations,
+  formatJson,
+  formatSummary,
+} from '@ontrails/warden';
+```
+
+Reusable source-code parser helpers now live in `@ontrails/source`:
+
+```typescript
+import { findStringLiterals, parse, walk } from '@ontrails/source';
+```
+
+## Trail-based API
+
+Every built-in warden rule is also available as a composable trail. This makes rules queryable, testable, and invocable through any Trails surface.
+
+```typescript
+import {
+  runTopoAwareWardenTrails,
+  runWardenTrails,
+  wardenTopo,
+} from '@ontrails/warden';
+
+// Inspect the warden rule trails
+console.log(wardenTopo.ids()); // ['warden.rule.no-throw-in-implementation', ...]
+
+// Run all rule trails against a source file
+const diagnostics = await runWardenTrails(filePath, sourceCode, {
+  knownTrailIds: myApp.ids(),
+  knownResourceIds: myApp.resourceIds(),
+});
+
+// Run built-in topo-aware rule trails once against the resolved graph
+const topoDiagnostics = await runTopoAwareWardenTrails(myApp);
+```
+
+To wrap a custom rule as a trail, import `wrapRule` from the root package entrypoint:
+
+```typescript
+import { wrapRule } from '@ontrails/warden';
+```
+
+This is the same factory used internally to build all built-in rule trails.
+
+## API
+
+| Export | What it does |
+| --- | --- |
+| `runWarden(options?)` | Run all rules and drift checks, return a report |
+| `formatWardenReport(report)` | Human-readable report |
+| `checkDrift(rootDir, topo?, options?)` | Check if the lock file matches the current topo; pass `{ overlays }` from the app module so the comparison graph carries the overlay content compile embeds. Stale results name `driftedOverlayNamespaces` when overlays diverge |
+| `wardenRules` | Registry of all built-in rules |
+| `builtinWardenRuleMetadata` | Tier, scope, lifecycle, and invariant metadata for built-in rules |
+| `getWardenRuleMetadata(ruleOrName)` | Resolve inline or built-in metadata for a Warden rule |
+| `listWardenRuleMetadata()` | List built-in rule metadata entries |
+| `wardenTopo` | `Topo` of all built-in rule trails (one per rule) |
+| `runWardenTrails(filePath, sourceCode, options?)` | Dispatch file-scoped rule trails for a file, collect diagnostics |
+| `runTopoAwareWardenTrails(topo)` | Dispatch built-in topo-aware rule trails once for a resolved topo |
+| `loadProjectWardenRules(rootDir)` | Load rule modules from `.trails/rules.ts` or direct `.trails/rules/*.ts` children |
+| `formatGitHubAnnotations(report)` | GitHub Actions annotation format |
+| `formatJson(report)` | Machine-readable JSON |
+| `formatSummary(report)` | Compact summary line |
+| `wrapRule(rule)` | Wrap a custom rule as a trail (same factory used for all built-in rule trails) |
+
+Source-code parser helpers are owned by `@ontrails/source`, not the Warden root runtime barrel.
+
+`runWarden({ tier })` can narrow a run to `source-static`, `project-static`, `topo-aware`, `drift`, or `advisory`. Omit `tier` for the default full run.
+
+See the [API Reference](../../docs/api-reference.md) for the full list.
+
+## Installation
+
+These commands target stable `0.2.0`. Run them after that version is published to npm.
+
+```bash
+bun add --exact -d @ontrails/warden@0.2.0
+```

package/bin/warden.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env bun
+/* oxlint-disable eslint-plugin-jest/require-hook -- CLI bin entrypoints execute at module scope */
+
+import { runWardenCommand } from '../src/command.js';
+
+const HELP = `Usage: warden [options]
+
+Run Trails Warden governance checks.
+
+Options:
+  --ci                         Apply CI defaults
+  --pre-push                   Apply pre-push defaults
+  --apps, -a <names>           Comma-delimited Trails app names
+  --config-path <path>         Path to trails.config.* file
+  --root-dir <path>            Project root to inspect
+  --fix                        Apply safe source fixes
+  --adapter-check              Include shared adapter authoring diagnostics
+  --depth <value>              source, project, topo, or all
+  --fail-on <value>            error or warning
+  --format <value>             summary, github, or json
+  --drafts <value>             include, exclude, or only
+  --scope-exclude <glob>       Root-relative path glob Warden should not govern
+  --lock <value>               auto, cached, refresh, or skip
+  --no-lock-mutation           Do not write lock artifacts
+  --strict                     Fail on warnings
+  -h, --help                   Display help for command
+`;
+
+const args = Bun.argv.slice(2);
+if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+  console.log(HELP);
+  process.exit(0);
+}
+
+const env = { ...process.env } as Record<string, string | undefined>;
+const result = await runWardenCommand({
+  args,
+  cwd: process.cwd(),
+  env,
+});
+
+if (result.output.length > 0) {
+  console.log(result.output);
+}
+
+const summaryPath = env['GITHUB_STEP_SUMMARY'];
+if (result.writeStepSummary && summaryPath !== undefined) {
+  await Bun.write(summaryPath, result.summary);
+}
+
+process.exit(result.exitCode);

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@ontrails/warden",
+  "version": "0.2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/outfitter-dev/trails.git",
+    "directory": "packages/warden"
+  },
+  "bin": {
+    "warden": "./bin/warden.ts"
+  },
+  "files": [
+    "bin/**/*.ts",
+    "src/**/*.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./resolve": "./src/resolve.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint ./src",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@ontrails/adapter-kit": "^0.2.0",
+    "@ontrails/cli": "^0.2.0",
+    "@ontrails/config": "^0.2.0",
+    "@ontrails/permits": "^0.2.0",
+    "@ontrails/source": "^0.2.0",
+    "@ontrails/store": "^0.2.0",
+    "oxc-resolver": "11.19.1",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@ontrails/testing": "^0.2.0"
+  },
+  "peerDependencies": {
+    "@ontrails/core": "^0.2.0",
+    "@ontrails/topography": "^0.2.0"
+  }
+}

package/src/adapter-check.ts

@@ -0,0 +1,136 @@
+/**
+ * Warden rendering for shared adapter readiness checks.
+ *
+ * Adapter facts stay in @ontrails/adapter-kit. Warden only maps those facts
+ * into governance diagnostics and severity.
+ */
+
+import { checkAdapters } from '@ontrails/adapter-kit';
+import type { AdapterCheckDiagnostic } from '@ontrails/adapter-kit';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type { WardenDiagnostic } from './rules/types.js';
+
+export const adapterCheckRuleName = 'adapter-check';
+const adapterCheckRootCode = 'adapter-check-root';
+
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const toWardenDiagnostic = (
+  diagnostic: AdapterCheckDiagnostic
+): WardenDiagnostic => ({
+  code: diagnostic.code,
+  filePath: diagnostic.packageJsonPath,
+  line: 1,
+  message: diagnostic.message,
+  rule: adapterCheckRuleName,
+  severity: 'warn',
+});
+
+const toRootDiagnostic = (
+  message: string,
+  filePath: string
+): WardenDiagnostic => ({
+  code: adapterCheckRootCode,
+  filePath,
+  line: 1,
+  message,
+  rule: adapterCheckRuleName,
+  severity: 'error',
+});
+
+const workspacePatternsFromManifest = (
+  manifest: Readonly<Record<string, unknown>>
+): readonly string[] => {
+  const { workspaces } = manifest;
+  if (Array.isArray(workspaces)) {
+    return workspaces.filter(
+      (pattern): pattern is string => typeof pattern === 'string'
+    );
+  }
+
+  const packages = isRecord(workspaces) ? workspaces['packages'] : undefined;
+  return Array.isArray(packages)
+    ? packages.filter(
+        (pattern): pattern is string => typeof pattern === 'string'
+      )
+    : [];
+};
+
+const validateAdapterCheckRoot = (
+  rootDir: string
+): readonly WardenDiagnostic[] => {
+  if (!existsSync(rootDir)) {
+    return [
+      toRootDiagnostic(
+        `adapter.check rootDir does not exist: "${rootDir}"`,
+        rootDir
+      ),
+    ];
+  }
+
+  if (!statSync(rootDir).isDirectory()) {
+    return [
+      toRootDiagnostic(
+        `adapter.check rootDir must be a directory: "${rootDir}"`,
+        rootDir
+      ),
+    ];
+  }
+
+  const packageJsonPath = join(rootDir, 'package.json');
+  if (!existsSync(packageJsonPath)) {
+    return [
+      toRootDiagnostic(
+        `adapter.check rootDir must contain a package.json workspace manifest: "${packageJsonPath}"`,
+        packageJsonPath
+      ),
+    ];
+  }
+
+  let manifest: unknown;
+  try {
+    manifest = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+  } catch (error) {
+    const reason = error instanceof Error ? `: ${error.message}` : '';
+    return [
+      toRootDiagnostic(
+        `adapter.check could not read root package.json: "${packageJsonPath}"${reason}`,
+        packageJsonPath
+      ),
+    ];
+  }
+
+  if (!isRecord(manifest)) {
+    return [
+      toRootDiagnostic(
+        `adapter.check root package.json must contain a JSON object: "${packageJsonPath}"`,
+        packageJsonPath
+      ),
+    ];
+  }
+
+  if (workspacePatternsFromManifest(manifest).length === 0) {
+    return [
+      toRootDiagnostic(
+        `adapter.check root package.json must declare workspace packages: "${packageJsonPath}"`,
+        packageJsonPath
+      ),
+    ];
+  }
+
+  return [];
+};
+
+export const runWardenAdapterChecks = (
+  rootDir: string
+): readonly WardenDiagnostic[] => {
+  const rootDiagnostics = validateAdapterCheckRoot(rootDir);
+  if (rootDiagnostics.length > 0) {
+    return rootDiagnostics;
+  }
+
+  return checkAdapters(rootDir).diagnostics.map(toWardenDiagnostic);
+};