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

package/src/fix.ts

@@ -0,0 +1,120 @@
+/**
+ * Safe-fix execution for `warden --fix` (TRL-833).
+ *
+ * Consumes the structured {@link WardenFix} metadata a rule attaches to its
+ * diagnostics (TRL-831) and applies only the edits marked `safe`. Findings
+ * whose fix is `review`-required, or that carry no edits, are never applied —
+ * they stay reported so a human (or a downstream regrade) resolves them.
+ *
+ * The applicator is pure: it takes a file's source plus that file's
+ * diagnostics and returns the patched source plus which diagnostics were
+ * applied or skipped. The CLI layer owns reading and writing files.
+ */
+
+import type { WardenDiagnostic, WardenFixEdit } from './rules/types.js';
+
+/** A safe edit resolved from a diagnostic, ready to apply to a source string. */
+interface ResolvedEdit {
+  readonly start: number;
+  readonly end: number;
+  readonly replacement: string;
+}
+
+/**
+ * Apply a set of edits to a source string, last-to-first.
+ *
+ * Edits are applied in descending start order so earlier offsets stay valid as
+ * later spans are spliced. Overlapping edits are a programming error in the
+ * rule that produced them; this throws rather than silently corrupt source.
+ */
+const applyEdits = (source: string, edits: readonly ResolvedEdit[]): string => {
+  for (const edit of edits) {
+    if (!Number.isSafeInteger(edit.start) || !Number.isSafeInteger(edit.end)) {
+      throw new RangeError(
+        `Fix edit [${String(edit.start)}, ${String(edit.end)}) must use safe integer offsets.`
+      );
+    }
+  }
+
+  const ordered = [...edits].toSorted(
+    (left, right) => right.start - left.start
+  );
+  let result = source;
+  let lastStart = Number.POSITIVE_INFINITY;
+  for (const edit of ordered) {
+    if (edit.start < 0 || edit.end > source.length || edit.start > edit.end) {
+      throw new RangeError(
+        `Fix edit [${edit.start}, ${edit.end}) is out of bounds for source of length ${source.length}.`
+      );
+    }
+    if (edit.end > lastStart) {
+      throw new RangeError(
+        `Fix edit [${edit.start}, ${edit.end}) overlaps a later edit starting at ${lastStart}.`
+      );
+    }
+    result =
+      result.slice(0, edit.start) + edit.replacement + result.slice(edit.end);
+    lastStart = edit.start;
+  }
+  return result;
+};
+
+/** Whether a diagnostic carries an applicable safe fix with concrete edits. */
+export const hasSafeFixEdits = (
+  diagnostic: WardenDiagnostic
+): diagnostic is WardenDiagnostic & {
+  readonly fix: { readonly edits: readonly WardenFixEdit[] };
+} =>
+  diagnostic.fix?.safety === 'safe' &&
+  diagnostic.fix.edits !== undefined &&
+  diagnostic.fix.edits.length > 0;
+
+/** Result of applying safe fixes to a single file's source. */
+export interface WardenFileFixResult {
+  /** Source after applying every safe edit; unchanged when none applied. */
+  readonly patched: string;
+  /** Whether any edit was applied (i.e. `patched` differs from input). */
+  readonly changed: boolean;
+  /** Diagnostics whose safe fix was applied. */
+  readonly applied: readonly WardenDiagnostic[];
+  /** Diagnostics left reported (review-required, or no safe edits). */
+  readonly skipped: readonly WardenDiagnostic[];
+}
+
+/**
+ * Apply the safe fixes among a file's diagnostics to its source.
+ *
+ * Pure and filesystem-free. Only `safety: 'safe'` fixes with edits are applied;
+ * everything else is returned in `skipped`. Edits from all applicable
+ * diagnostics are pooled and applied last-to-first in one pass.
+ */
+export const applySafeFixesToSource = (
+  source: string,
+  diagnostics: readonly WardenDiagnostic[]
+): WardenFileFixResult => {
+  const applied: WardenDiagnostic[] = [];
+  const skipped: WardenDiagnostic[] = [];
+  const edits: ResolvedEdit[] = [];
+
+  for (const diagnostic of diagnostics) {
+    if (hasSafeFixEdits(diagnostic)) {
+      applied.push(diagnostic);
+      for (const edit of diagnostic.fix.edits) {
+        edits.push({
+          end: edit.end,
+          replacement: edit.replacement,
+          start: edit.start,
+        });
+      }
+    } else {
+      skipped.push(diagnostic);
+    }
+  }
+
+  if (edits.length === 0) {
+    return { applied, changed: false, patched: source, skipped };
+  }
+
+  const patched = applyEdits(source, edits);
+  return { applied, changed: patched !== source, patched, skipped };
+};

package/src/formatters.ts

@@ -36,7 +36,7 @@ export const formatGitHubAnnotations = (report: WardenReport): string => {
     lines.push(`::error::drift: ${report.drift.blockedReason}`);
   } else if (report.drift?.stale) {
     lines.push(
-      '::error::drift: trails.lock is stale (regenerate with `trails topo compile`)'
+      '::error::drift: trails.lock is stale (regenerate with `trails compile`)'
     );
   }
 
@@ -60,6 +60,7 @@ export const formatJson = (report: WardenReport): string => {
     {
       diagnostics: report.diagnostics,
       drift: report.drift,
+      fixes: report.fixes,
       passed: report.passed,
       summary,
     },
@@ -146,7 +147,17 @@ const driftSection = (drift: WardenReport['drift']): readonly string[] => {
   return [
     '',
     '### Drift',
-    '- trails.lock is stale (regenerate with `trails topo compile`)',
+    '- trails.lock is stale (regenerate with `trails compile`)',
+  ];
+};
+
+/** Render safe-fix counts when a fix pass was requested. */
+const fixSummaryLine = (fixes: WardenReport['fixes']): readonly string[] => {
+  if (fixes === undefined) {
+    return [];
+  }
+  return [
+    `**Fixes:** ${String(fixes.applied)} applied, ${String(fixes.filesChanged)} files changed, ${String(fixes.skipped)} skipped`,
   ];
 };
 
@@ -164,6 +175,7 @@ export const formatSummary = (report: WardenReport): string => {
     '## Warden Report',
     '',
     `**Result: ${result}** | ${String(report.errorCount)} errors, ${String(report.warnCount)} warnings`,
+    ...fixSummaryLine(report.fixes),
     ...severitySection('Errors', errors),
     ...severitySection('Warnings', warnings),
     ...driftSection(report.drift),

package/src/guide.ts

@@ -1,4 +1,5 @@
 import type {
+  WardenFixCapability,
   WardenGuidance,
   WardenGuidanceLink,
   WardenRuleConcern,
@@ -27,6 +28,7 @@ export interface WardenRuleGuideEntry {
   readonly depth: WardenDepth;
   readonly description: string;
   readonly docs: readonly WardenGuidanceLink[];
+  readonly fix?: WardenFixCapability | undefined;
   readonly guidance?: WardenGuidance | undefined;
   readonly id: string;
   readonly invariant: string;
@@ -55,6 +57,7 @@ interface WardenAgentRuleGuide {
     readonly tier: WardenRuleTier;
   };
   readonly concern: WardenRuleConcern;
+  readonly fix?: WardenFixCapability | undefined;
   readonly guidance?: WardenGuidance | undefined;
   readonly id: string;
   readonly invariant: string;
@@ -87,6 +90,7 @@ export const buildWardenGuideManifest = (): WardenGuideManifest => {
         depth: metadata.depth,
         description: rule?.description ?? '',
         docs,
+        fix: metadata.fix,
         guidance: metadata.guidance,
         id,
         invariant: metadata.invariant,
@@ -153,6 +157,12 @@ const renderRuleMarkdown = (rule: WardenRuleGuideEntry): readonly string[] => {
     lines.push(`- Retire when: ${rule.lifecycle.retireWhen}`);
   }
 
+  if (rule.fix) {
+    lines.push(
+      `- Fix: \`${rule.fix.class}\` (${rule.fix.safety === 'safe' ? 'safe, applied by `warden --fix`' : 'review-required'})`
+    );
+  }
+
   if (rule.guidance) {
     lines.push('', `Guidance: ${rule.guidance.summary}`);
     renderOptionalList(lines, 'Steps', rule.guidance.steps);
@@ -210,6 +220,7 @@ export const buildWardenAgentGuide = (
       tier: rule.tier,
     },
     concern: rule.concern,
+    fix: rule.fix,
     guidance: rule.guidance,
     id: rule.id,
     invariant: rule.invariant,

package/src/index.ts

@@ -14,6 +14,11 @@ export type {
   ProjectContext,
   TopoAwareWardenRule,
   WardenDiagnostic,
+  WardenFix,
+  WardenFixCapability,
+  WardenFixClass,
+  WardenFixEdit,
+  WardenFixSafety,
   WardenGuidance,
   WardenGuidanceLink,
   WardenRule,
@@ -31,6 +36,8 @@ export {
   builtinWardenRuleMetadata,
   getWardenRuleMetadata,
   listWardenRuleMetadata,
+  wardenFixClasses,
+  wardenFixSafeties,
   wardenRuleConcerns,
   wardenRuleLifecycleStates,
   wardenRuleScopes,
@@ -41,6 +48,12 @@ export {
 
 // Rule-scoped cache controls for long-lived consumers (watch mode, LSPs).
 export { clearImplementationReturnsResultCache } from './rules/implementation-returns-result.js';
+export {
+  isWardenDevPermitTestScanTarget,
+  isWardenInfrastructureScanTarget,
+  isWardenSourceScanTarget,
+  isWardenTestScanTarget,
+} from './rules/scan.js';
 
 // CLI runner
 export type {
@@ -51,6 +64,12 @@ export type {
 } from './cli.js';
 export { formatWardenReport, runWarden } from './cli.js';
 
+// Adapter authoring checks
+export {
+  adapterCheckRuleName,
+  runWardenAdapterChecks,
+} from './adapter-check.js';
+
 // CLI command surface
 export type {
   ParsedWardenCommand,
@@ -145,31 +164,38 @@ export {
   circularRefsTrail,
   contourExistsTrail,
   contextNoSurfaceTypesTrail,
-  crossDeclarationsTrail,
+  composesDeclarationsTrail,
   deadInternalTrailTrail,
+  deprecationWithoutGuidanceTrail,
   diagnosticSchema,
   draftFileMarkingTrail,
   draftVisibleDebtTrail,
   errorMappingCompletenessTrail,
   exampleValidTrail,
   firesDeclarationsTrail,
+  forkWithoutPreservedBlazeTrail,
   implementationReturnsResultTrail,
   incompleteAccessorForStandardOpTrail,
   incompleteCrudTrail,
   intentPropagationTrail,
   layerFieldNameDriftTrail,
+  markerSchemaUnsupportedTrail,
   missingVisibilityTrail,
   missingReconcileTrail,
   noDevPermitInSourceTrail,
+  noDestructuredComposeTrail,
   noDirectImplementationCallTrail,
   noLegacyLayerImportsTrail,
   noNativeErrorResultTrail,
+  noRedundantResultErrorWrapTrail,
   noSyncResultAssumptionTrail,
   noThrowInDetourRecoverTrail,
   noThrowInImplementationTrail,
+  noTopLevelSurfaceTrail,
   onReferencesExistTrail,
   orphanedSignalTrail,
   ownerProjectionParityTrail,
+  pendingForceTrail,
   permitGovernanceTrail,
   preferSchemaInferenceTrail,
   projectAwareRuleInput,
@@ -184,6 +210,7 @@ export {
   resourceDeclarationsTrail,
   resourceIdGrammarTrail,
   resourceExistsTrail,
+  resourceMockCoverageTrail,
   scheduledDestroyIntentTrail,
   signalGraphCoachingTrail,
   staticResourceAccessorPreferenceTrail,
@@ -192,6 +219,9 @@ export {
   unreachableDetourShadowingTrail,
   validDetourContractTrail,
   validDescribeRefsTrail,
+  versionGapTrail,
+  versionPinnedComposeTrail,
+  versionWithoutExamplesTrail,
   wardenExportSymmetryTrail,
   wardenRulesUseAstTrail,
   webhookRouteCollisionTrail,

package/src/rules/ast.ts

@@ -2,10 +2,11 @@
  * Shared AST utilities for warden rules.
  *
  * Uses oxc-parser for native-speed TypeScript parsing. Provides a lightweight
- * walker and helpers for finding trail implementation bodies.
+ * walker and helpers for finding blaze bodies.
  */
 
-import { resolve } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { DRAFT_ID_PREFIX, intentValues } from '@ontrails/core';
@@ -260,6 +261,60 @@ export const FRAMEWORK_DRAFT_PREFIX_CONSTANT_NAMES: ReadonlySet<string> =
  */
 const FRAMEWORK_DRAFT_PREFIX_LITERAL = DRAFT_ID_PREFIX;
 
+interface PackageJsonWithName {
+  readonly name: string;
+}
+
+const FRAMEWORK_DRAFT_PREFIX_PACKAGES: ReadonlySet<string> = new Set([
+  '@ontrails/core',
+  '@ontrails/warden',
+]);
+
+const isPackageJsonWithName = (value: unknown): value is PackageJsonWithName =>
+  typeof value === 'object' &&
+  value !== null &&
+  typeof (value as { name?: unknown }).name === 'string';
+
+const readPackageJsonName = (packageJsonPath: string): string | null => {
+  try {
+    const parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    return isPackageJsonWithName(parsed) ? parsed.name : null;
+  } catch {
+    return null;
+  }
+};
+
+const frameworkDraftPackageRoot = (filePath: string): string | null => {
+  const resolvedPath = resolve(filePath);
+  if (basename(resolvedPath) !== 'draft.ts') {
+    return null;
+  }
+
+  const sourceDir = dirname(resolvedPath);
+  if (basename(sourceDir) !== 'src') {
+    return null;
+  }
+
+  const packageRoot = dirname(sourceDir);
+  if (!existsSync(join(packageRoot, 'package.json'))) {
+    return null;
+  }
+
+  return packageRoot;
+};
+
+/** Fallback exemption when framework files are consumed from a different install path. */
+const isFrameworkDraftPrefixSourceFile = (filePath: string): boolean => {
+  const root = frameworkDraftPackageRoot(filePath);
+  if (!root) {
+    return false;
+  }
+  const packageName = readPackageJsonName(join(root, 'package.json'));
+  return (
+    packageName !== null && FRAMEWORK_DRAFT_PREFIX_PACKAGES.has(packageName)
+  );
+};
+
 /**
  * Absolute paths of the two framework files allowed to declare the
  * draft-prefix constants. Anchored against the rule module's own URL so the
@@ -285,8 +340,8 @@ const FRAMEWORK_DRAFT_CONSTANT_FILES: ReadonlySet<string> = new Set([
  * constants.
  *
  * Exemption is gated on all three of:
- *   1. The file's absolute path matches one of the two framework files that
- *      actually define these constants.
+ *   1. The file is one of the two known framework draft files, or its package
+ *      root `package.json` name is `@ontrails/core` or `@ontrails/warden`.
  *   2. The declaration name is `DRAFT_ID_PREFIX` or `DRAFT_FILE_PREFIX`.
  *   3. The string literal value is exactly `'_draft.'`.
  *
@@ -299,7 +354,11 @@ export const collectFrameworkDraftPrefixConstantOffsets = (
 ): ReadonlySet<number> => {
   const offsets = new Set<number>();
 
-  if (!FRAMEWORK_DRAFT_CONSTANT_FILES.has(resolve(filePath))) {
+  const resolvedPath = resolve(filePath);
+  if (
+    !FRAMEWORK_DRAFT_CONSTANT_FILES.has(resolvedPath) &&
+    !isFrameworkDraftPrefixSourceFile(resolvedPath)
+  ) {
     return offsets;
   }
 
@@ -919,7 +978,7 @@ const visitForHoisted = (
 
 /**
  * Collect `var` declarations and `function` declarations hoisted to the
- * nearest function scope from anywhere inside `root`, without crossing a
+ * nearest function scope from anywhere inside `root`, without composing a
  * nested function or static-block boundary.
  */
 const collectHoistedVarAndFunctionBindings = (
@@ -1100,7 +1159,7 @@ export const walkWithScopes = (
   walkNode(root, true);
 };
 
-const isShadowed = (
+export const isShadowed = (
   receiverName: string,
   scopeStack: readonly ReadonlySet<string>[]
 ): boolean => {
@@ -1296,7 +1355,7 @@ const isNamespacedCallAllowed = (
  *
  * When `context` is `undefined`, this falls back to permissive matching
  * (any `ns.trail(...)` shape resolves). Inline resolution paths that do
- * not have the surrounding AST available (e.g. `crosses: [core.trail(...)]`
+ * not have the surrounding AST available (e.g. `composes: [core.trail(...)]`
  * or `on: [core.signal(...)]`) rely on this fallback. Scope-aware call
  * sites always pass a context, so this only affects inline contexts where
  * a best-effort name match is the intended behavior.
@@ -1790,7 +1849,7 @@ const extractImportSpecifierAlias = (
   }
 
   // Default imports bind the default export of the source module to the local
-  // name. We cannot statically recover the exported name without cross-file
+  // name. We cannot statically recover the exported name without compose-file
   // analysis, so the local name is the best identifier we have for resolving
   // against `knownContourIds`. Treat the alias as an identity mapping; the
   // downstream resolver will fall through to `knownContourIds` on the binding
@@ -2655,14 +2714,14 @@ export const collectNamedTrailIds = (
   return ids;
 };
 
-/** Extract the raw `crosses: [...]` array elements from a trail config. */
-export const getCrossElements = (config: AstNode): readonly AstNode[] => {
-  const crossesProp = findConfigProperty(config, 'crosses');
-  if (!crossesProp) {
+/** Extract the raw `composes: [...]` array elements from a trail config. */
+export const getComposeElements = (config: AstNode): readonly AstNode[] => {
+  const composesProp = findConfigProperty(config, 'composes');
+  if (!composesProp) {
     return [];
   }
 
-  const arrayNode = crossesProp.value;
+  const arrayNode = composesProp.value;
   if (!arrayNode || (arrayNode as AstNode).type !== 'ArrayExpression') {
     return [];
   }
@@ -2674,12 +2733,12 @@ export const getCrossElements = (config: AstNode): readonly AstNode[] => {
 };
 
 /**
- * Resolve a single `crosses: [...]` element to its target trail ID.
+ * Resolve a single `composes: [...]` element to its target trail ID.
  *
  * Handles string literals, identifier references (via `namedTrailIds` map or
  * `const NAME = '...'` resolution), and inline `trail(...)` call expressions.
  */
-export const deriveCrossElementId = (
+export const deriveComposeElementId = (
   element: AstNode,
   sourceCode: string,
   namedTrailIds: ReadonlyMap<string, string>
@@ -2701,23 +2760,23 @@ export const deriveCrossElementId = (
 
 /**
  * Collect all trail IDs referenced by a single trail definition's
- * `crosses: [...]` array, deduplicated.
+ * `composes: [...]` array, deduplicated.
  */
-export const extractDefinitionCrossTargetIds = (
+export const extractDefinitionComposeTargetIds = (
   config: AstNode,
   sourceCode: string,
   namedTrailIds: ReadonlyMap<string, string>
 ): readonly string[] => [
   ...new Set(
-    getCrossElements(config).flatMap((element) => {
-      const id = deriveCrossElementId(element, sourceCode, namedTrailIds);
+    getComposeElements(config).flatMap((element) => {
+      const id = deriveComposeElementId(element, sourceCode, namedTrailIds);
       return id ? [id] : [];
     })
   ),
 ];
 
-/** Collect all trail IDs referenced by declared `crosses: [...]` arrays. */
-export const collectCrossTargetTrailIds = (
+/** Collect all trail IDs referenced by declared `composes: [...]` arrays. */
+export const collectComposeTargetTrailIds = (
   ast: AstNode,
   sourceCode: string
 ): ReadonlySet<string> => {
@@ -2729,7 +2788,7 @@ export const collectCrossTargetTrailIds = (
       continue;
     }
 
-    for (const id of extractDefinitionCrossTargetIds(
+    for (const id of extractDefinitionComposeTargetIds(
       def.config,
       sourceCode,
       namedTrailIds
@@ -2788,7 +2847,7 @@ export interface StoreTableDefinition {
   /**
    * Stable composite key for this table in the form `${storeBinding}:${name}`,
    * falling back to the bare `name` when the store is anonymous. Use this for
-   * cross-rule / cross-file keying so two stores with the same table name
+   * compose-rule / compose-file keying so two stores with the same table name
    * never collide.
    */
   readonly key: string;
@@ -2804,7 +2863,7 @@ export interface StoreTableDefinition {
  * binding. Centralized so rule keying stays stable.
  *
  * @remarks
- * The key is intentionally file-local (no module path prefix). Cross-file
+ * The key is intentionally file-local (no module path prefix). Compose-file
  * aggregation in `ProjectContext` merges keys from all files, so two files
  * with `const db = store({ notes: ... })` both produce `db:notes` — this is
  * the desired behavior because the warden checks for *pattern completeness*

package/src/rules/circular-refs.ts

@@ -82,7 +82,7 @@ const buildCircularReferenceDiagnostic = (
 ): WardenDiagnostic => ({
   filePath,
   line,
-  message: `Contour "${contourName}" participates in circular contour references: ${cyclePath.join(' -> ')}.`,
+  message: `Contour "${contourName}" participates in circular contour references: ${cyclePath.join(' -> ')}. Break the cycle by removing one contour reference, or extract the shared shape into a new contour neither side depends on.`,
   rule: 'circular-refs',
   severity: 'warn',
 });