@ontrails/warden 1.0.0-beta.18 → 1.0.0-beta.19

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # @ontrails/warden
 
+## 1.0.0-beta.19
+
+### Major Changes
+
+- 1eb5bdc: Rename first-class trail composition from the `cross` API family to the `compose` family across core contracts, testing helpers, topo projections, Warden rules, CLI scaffolds, and docs. `composes`, `ctx.compose`, `composeInput`, and `Compose*` type names are now the public authoring vocabulary; topo persistence migrates legacy composition rows and graph keys forward.
+
+### Minor Changes
+
+- 120caf5: Promote topo artifact commands to `trails compile` and `trails validate`.
+- 1c975c3: Define the Warden fix-metadata contract (`WardenFix`, `WardenFixCapability`, `WardenFixClass`, `WardenFixSafety`, `WardenFixEdit`) with optional `fix` metadata on diagnostics and rule metadata, projected through the guide, manifest, markdown, and agent guidance. Export `wardenFixClasses`/`wardenFixSafeties` value arrays and surface the rule `fix` capability in the `warden.guide` trail output schema. Dormant until a rule declares it.
+- d5d518e: Add `warden --fix` to apply safe source fixes. The executor applies only `safety: 'safe'` edits last-to-first, re-reading and rewriting affected files, while review-required, edit-less, and topo diagnostics stay reported but unapplied. The report surfaces applied, changed-file, and skipped counts.
+
+  Expose `fix` through the Trails app wrapper and mark the `warden` trail as write intent with explicit public access because `fix: true` mutates source files while the local governance command remains directly runnable.
+
+### Patch Changes
+
+- f8d80b9: Refresh current-facing compose vocabulary in package documentation after the composition cutover.
+- f0f7e2f: Avoid draft-marker false positives when a packed Warden install scans the Trails framework source tree from a different package location.
+- 64fb15a: Add Warden rules for trail version lifecycle guidance, version gaps, marker-safe schemas, pinned composes, examples, and pending force audit events.
+- 5d88104: Polish Trails blaze terminology across package docs and Warden guidance.
+- 48d5ff4: Attach term-rewrite fix metadata to the `no-legacy-layer-imports` rule, marking it review-required with no mechanical edits (the legacy layers were removed, not renamed) so `warden --fix` reports but never auto-applies the migration.
+- 216bf10: Fix a false `dead-internal-trail` warning by unioning file-local compose evidence with the project-context compose set, so same-file composition in scanned-but-unregistered packages is recognized.
+- 678cb1c: Expose the shared adapter readiness engine through Warden's opt-in
+  `--adapter-check` diagnostics and the local `trails adapter check` authoring
+  workflow.
+- 5874fd6: Preserve diagnostic fix metadata through Warden rule trail outputs.
+- 619cb15: Add a Warden rule (`no-destructured-compose`) that coaches trail blazes to call `ctx.compose(...)` directly instead of destructuring `compose` from the context.
+
+  Keep the generated `create` trail on the direct `ctx.compose(...)` shape so framework-authored trails follow the same composition guidance.
+
+- 4642268: Make the standalone `warden --help` entry point print CLI help instead of running Warden with an unknown-option diagnostic.
+- 9bab0cf: Follow schema aliases when detecting hidden optional wrappers in version marker
+  schemas.
+- 3ceeba8: Expand marker-schema-unsupported diagnostics to catch Zod schema constructs that
+  runtime marker derivation rejects.
+- beafd03: Add a warning for blazes that re-wrap an existing Result error with Result.err(result.error) instead of returning the original Result.
+- 7b173e0: Warn when a `resource('id', { ... })` definition declares neither a `mock` factory nor an explicit `unmockable` reason, so `testAll(app)` can provision it without production configuration (common pitfall #10).
+- 6e50e7b: Recognize Result-returning helper provenance when helpers use an imported Result type alias.
+- 48edf8d: Expose shared Warden source scan-target predicates so downstream consumers can
+  preserve the CLI runner's test and declaration-file filtering before invoking
+  Warden-owned rules directly.
+- 12ffa3b: Align Warden signal-rule trail examples so producer trails call `ctx.fire()` for their declared signals.
+- 2f262f7: Improve Warden diagnostics so names-only findings teach the canonical fix instead of only naming the violation.
+- 58b01f2: Warn when topo export modules open Trails surfaces at module top level.
+- Updated dependencies [bb81ffe]
+- Updated dependencies [e41c382]
+- Updated dependencies [a2f1825]
+- Updated dependencies [a2f1825]
+- Updated dependencies [1eb5bdc]
+- Updated dependencies [f8d80b9]
+- Updated dependencies [846a597]
+- Updated dependencies [223aaad]
+- Updated dependencies [3125f4d]
+- Updated dependencies [2494dc6]
+- Updated dependencies [4bc8a99]
+- Updated dependencies [120caf5]
+- Updated dependencies [2d53717]
+- Updated dependencies [16cb740]
+- Updated dependencies [8894ecb]
+- Updated dependencies [fdf7ec9]
+- Updated dependencies [92e709b]
+- Updated dependencies [d76be13]
+- Updated dependencies [84f56a5]
+- Updated dependencies [653d1fc]
+- Updated dependencies [431b04c]
+- Updated dependencies [2e76288]
+- Updated dependencies [5d88104]
+- Updated dependencies [f04a9ef]
+- Updated dependencies [fc00aeb]
+- Updated dependencies [ab1c77c]
+- Updated dependencies [4f43874]
+- Updated dependencies [678cb1c]
+  - @ontrails/adapter-kit@1.0.0-beta.19
+  - @ontrails/core@1.0.0-beta.19
+  - @ontrails/cli@1.0.0-beta.19
+  - @ontrails/store@1.0.0-beta.19
+  - @ontrails/topographer@1.0.0-beta.19
+  - @ontrails/permits@1.0.0-beta.19
+
 ## 1.0.0-beta.18
 
 ### Patch Changes

package/README.md

@@ -1,16 +1,10 @@
 # @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.
+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 (cross target existence, declared resource existence,
-recursive crossing, 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
-[Rule Design](../../docs/rule-design.md).
+For rule-home boundaries and authoring doctrine, see the [Warden guide](../../docs/warden.md) and [Warden Rules](../../docs/contributing/warden-rules.md).
 
 ## Usage
 
@@ -31,22 +25,17 @@ 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.
+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:
 
 - blaze and `Result` contract checks
-- cross, fire, resource, and detour declaration drift
+- 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 [Rule Design](../../docs/rule-design.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.
+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.
 
 ## Drift detection
 
@@ -57,7 +46,7 @@ import { checkDrift } from '@ontrails/warden';
 
 const drift = await checkDrift(process.cwd(), graph);
 if (drift.stale) {
-  console.log('lock file is stale -- regenerate with `trails topo compile`');
+  console.log('lock file is stale -- regenerate with `trails compile`');
 }
 ```
 
@@ -83,8 +72,7 @@ import {
 } from '@ontrails/warden';
 ```
 
-Parser helpers for rule authoring and repo-local tooling live on the dedicated
-AST entrypoint:
+Parser helpers for rule authoring and repo-local tooling live on the dedicated AST entrypoint:
 
 ```typescript
 import { findStringLiterals, parse, walk } from '@ontrails/warden/ast';
@@ -92,8 +80,7 @@ import { findStringLiterals, parse, walk } from '@ontrails/warden/ast';
 
 ## 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.
+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 {
@@ -115,8 +102,7 @@ const diagnostics = await runWardenTrails(filePath, sourceCode, {
 const topoDiagnostics = await runTopoAwareWardenTrails(myApp);
 ```
 
-To wrap a custom rule as a trail, import `wrapRule` from the root package
-entrypoint:
+To wrap a custom rule as a trail, import `wrapRule` from the root package entrypoint:
 
 ```typescript
 import { wrapRule } from '@ontrails/warden';
@@ -143,13 +129,9 @@ This is the same factory used internally to build all built-in rule trails.
 | `formatSummary(report)` | Compact summary line |
 | `wrapRule(rule)` | Wrap a custom rule as a trail (same factory used for all built-in rule trails) |
 
-AST parser helpers are exported from `@ontrails/warden/ast`, not the root
-runtime barrel. The stable authoring surface includes `parse`, `walk`,
-`walkScope`, `offsetToLine`, `findTrailDefinitions`, `findBlazeBodies`,
-`findContourDefinitions`, `isBlazeCall`, and string-literal helpers.
+AST parser helpers are exported from `@ontrails/warden/ast`, not the root runtime barrel. The stable authoring surface includes `parse`, `walk`, `walkScope`, `offsetToLine`, `findTrailDefinitions`, `findBlazeBodies`, `findContourDefinitions`, `isBlazeCall`, and string-literal helpers.
 
-`runWarden({ tier })` can narrow a run to `source-static`, `project-static`,
-`topo-aware`, `drift`, or `advisory`. Omit `tier` for the default full run.
+`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

@@ -3,9 +3,37 @@
 
 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
+  --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: Bun.argv.slice(2),
+  args,
   cwd: process.cwd(),
   env,
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/warden",
-  "version": "1.0.0-beta.18",
+  "version": "1.0.0-beta.19",
   "bin": {
     "warden": "./bin/warden.ts"
   },
@@ -28,19 +28,20 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/cli": "^1.0.0-beta.17",
-    "@ontrails/permits": "^1.0.0-beta.17",
-    "@ontrails/store": "^1.0.0-beta.17",
+    "@ontrails/adapter-kit": "^1.0.0-beta.19",
+    "@ontrails/cli": "^1.0.0-beta.19",
+    "@ontrails/permits": "^1.0.0-beta.19",
+    "@ontrails/store": "^1.0.0-beta.19",
     "oxc-parser": "^0.121.0",
     "oxc-resolver": "11.19.1",
     "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@ontrails/config": "^1.0.0-beta.17",
-    "@ontrails/testing": "^1.0.0-beta.17"
+    "@ontrails/config": "^1.0.0-beta.19",
+    "@ontrails/testing": "^1.0.0-beta.19"
   },
   "peerDependencies": {
-    "@ontrails/core": "^1.0.0-beta.17",
-    "@ontrails/topographer": "^1.0.0-beta.17"
+    "@ontrails/core": "^1.0.0-beta.19",
+    "@ontrails/topographer": "^1.0.0-beta.19"
   }
 }

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);
+};