@ontrails/warden 1.0.0-beta.4 → 1.0.0-beta.41

package/README.md

@@ -1,18 +1,17 @@
 # @ontrails/warden
 
-AST-based code convention rules for Trails. 10 lint rules that catch contract violations at development time, plus surface lock drift detection and CI formatters.
+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 (follow target existence, recursive follow, example schema validation) live in `validateTopo()` from `@ontrails/core`. Warden handles the code-level rules that need AST analysis.
+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
-trails warden              # Run all checks
-trails warden --exit-code  # Non-zero exit on errors or drift
-trails warden --lint-only  # Skip drift detection
-trails warden --drift-only # Skip lint rules
+bunx trails warden # Run all checks
 ```
 
 Or programmatically:
@@ -20,35 +19,89 @@ Or programmatically:
 ```typescript
 import { runWarden, formatWardenReport } from '@ontrails/warden';
 
-const report = await runWarden(app, { exitCode: true });
+const report = await runWarden({ topo: graph });
 console.log(formatWardenReport(report));
 ```
 
 ## Rules
 
-| Rule | Severity | What it catches |
-| --- | --- | --- |
-| `no-throw-in-implementation` | error | `throw` inside run bodies |
-| `implementation-returns-result` | error | Run functions returning raw values instead of `Result` |
-| `context-no-surface-types` | error | Surface type imports (`Request`, `McpSession`) in trail files |
-| `no-sync-result-assumption` | error | Missing `await` on run results |
-| `valid-detour-refs` | error | Detour targets that do not exist in the topo |
-| `no-throw-in-detour-target` | error | `throw` inside detour target trails |
-| `no-direct-implementation-call` | warn | Direct `.run()` calls bypassing `ctx.follow()` |
-| `no-direct-impl-in-route` | warn | Direct `.run()` calls inside trail bodies with `follow` |
-| `prefer-schema-inference` | warn | Redundant field overrides already derivable from the schema |
-| `valid-describe-refs` | warn | `@see` refs in `.describe()` that do not resolve |
+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/schema` to detect when the topo has changed without updating `surface.lock`:
+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(app);
+const drift = await checkDrift(process.cwd(), graph);
 if (drift.stale) {
-  console.log('surface.lock is stale -- regenerate with `trails survey generate`');
+  console.log('lock file is stale -- regenerate with `trails compile`');
 }
 ```
 
@@ -60,27 +113,81 @@ Add to lefthook for pre-push enforcement:
 pre-push:
   commands:
     warden:
-      run: trails warden --exit-code
+      run: bunx trails warden
       tags: governance
 ```
 
 CI formatters for structured output:
 
 ```typescript
-import { formatGitHubAnnotations, formatJson, formatSummary } from '@ontrails/warden';
+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(app, options?)` | Run all rules and drift checks, return a report |
+| `runWarden(options?)` | Run all rules and drift checks, return a report |
 | `formatWardenReport(report)` | Human-readable report |
-| `checkDrift(app)` | Check if `surface.lock` matches the current topo |
+| `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.
 

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

@@ -1,9 +1,22 @@
 {
   "name": "@ontrails/warden",
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0-beta.41",
+  "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": {
@@ -13,13 +26,21 @@
     "lint": "oxlint ./src",
     "clean": "rm -rf dist *.tsbuildinfo"
   },
-  "devDependencies": {
-    "@oxc-project/types": "^0.122.0",
-    "oxc-parser": "^0.121.0",
+  "dependencies": {
+    "@ontrails/adapter-kit": "^1.0.0-beta.41",
+    "@ontrails/cli": "^1.0.0-beta.41",
+    "@ontrails/config": "^1.0.0-beta.41",
+    "@ontrails/permits": "^1.0.0-beta.41",
+    "@ontrails/source": "^1.0.0-beta.41",
+    "@ontrails/store": "^1.0.0-beta.41",
+    "oxc-resolver": "11.19.1",
     "zod": "^4.3.5"
   },
+  "devDependencies": {
+    "@ontrails/testing": "^1.0.0-beta.41"
+  },
   "peerDependencies": {
-    "@ontrails/core": "^1.0.0-beta.0",
-    "@ontrails/schema": "^1.0.0-beta.0"
+    "@ontrails/core": "^1.0.0-beta.41",
+    "@ontrails/topography": "^1.0.0-beta.41"
   }
 }

package/src/adapter-check.ts

@@ -0,0 +1,136 @@
+/**
+ * Warden projection 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);
+};