@ontrails/regrade 1.0.0-beta.30 → 1.0.0-beta.39

package/CHANGELOG.md

@@ -1,5 +1,104 @@
 # @ontrails/regrade
 
+## 1.0.0-beta.39
+
+### Minor Changes
+
+- [`65b362f`](https://github.com/outfitter-dev/trails/commit/65b362f65fa2a75e2121d1a8b31882d52fa0376b): Regrade history consolidates per transition, append-only: `regrade apply` appends a run entry stamped `{ planContentHash, lockHashAtRun }` to `.trails/regrade/history/<transition>.json` instead of overwriting lockhash-named files, identical re-runs are recognized as replays, the artifact carries a stable internal transition `id`, and `regrade check <transition>` verifies each recorded run at its own stamped lock. The report `history.status` union widens to `applied | checked | replay`.
+- [`d3f7a25`](https://github.com/outfitter-dev/trails/commit/d3f7a25e66b6f0149ab2f33ac31ae1458860dce3): Regrade review entries carry structured review detail through Warden-backed and AST-backed classes: matched form, candidate replacement, machine-readable signals, preserve cautions, and a `judgment` field that distinguishes unresolved occurrence judgment from completed preserve/rewrite verdicts. Safe rewrite entries keep their existing report shape.
+
+### Patch Changes
+
+- [`b077fb7`](https://github.com/outfitter-dev/trails/commit/b077fb7ba6d9724cac6f0e59bc3fec9aec28984c): Add the export-restructure Regrade class family (TRL-1210). `export-restructure:cli-aliases` inverts legacy `cliAliases`/`trailsCliAliases` exports into `surfaceOverlay({ cli })` bindings inside the module's `trailsOverlays` export — adding the `@ontrails/core` import, deleting the legacy export, and routing anything it cannot prove safe (computed keys, spreads, in-module `aliases:` references) to `needs-review` with the exact target shape named. `export-restructure:mcp-trailheads` projects call-site MCP trailhead maps into `surfaceOverlay({ mcp })` group bindings: it rewrites in place when the same module exports `trailsOverlays`, and otherwise emits a classified `needs-review` handoff naming the module-overlay target while the call-site map stays as the richer-metadata override-in-context. Warden's fix-class union grows to `'export-restructure' | 'term-rewrite'`, `no-legacy-cli-alias-export` now advertises the `export-restructure` class, and `loadWardenRegradeClasses` supersedes `loadWardenTermRewriteClasses` (still exported) as the full Warden-routed class loader. Class-mode Regrade also gains the full plan lifecycle: `trails regrade plan --type class --class-ids ...` writes a `.trails/regrade/<slug>.json` plan carrying class ids, scope, and intent, `regrade check` re-runs the dry run and gates on outstanding rewrites or review, and `regrade apply` applies and graduates the plan to `.trails/regrade/history/<slug>-<hash>.json` — the same plan → check → apply → history evidence trail vocabulary regrades already had, now available to structural transforms. The class family ships for downstream apps bridging the pre-1.0 gap, so pre-cutover alias exports and trailhead maps migrate mechanically instead of by hand.
+
+## 1.0.0-beta.38
+
+## 1.0.0-beta.37
+
+### Patch Changes
+
+- [`09f15de`](https://github.com/outfitter-dev/trails/commit/09f15def8fcc8c28b0d604f436e6eeed46da8f37): Stage wide-net Regrade expansion candidates as structured plan review inventory with evidence, status, and pending counts.
+
+## 1.0.0-beta.36
+
+### Patch Changes
+
+- [`6e63e48`](https://github.com/outfitter-dev/trails/commit/6e63e483617b84cb6868d0c4d58d5b5a8d3b9ed2): Complete the v1 grouped surface-entry vocabulary cutover from facet to trailhead, including Regrade dogfood support for governed string literal renames and composed AST rewrite application.
+- [`26786a1`](https://github.com/outfitter-dev/trails/commit/26786a14acbe9ed03f69adbdac22968891e33df1): Persist vocabulary Regrade plan artifacts, expose plan/check/preview/apply flows across CLI and MCP, and write applied plan history for reviewed vocabulary migrations.
+
+## 1.0.0-beta.35
+
+### Patch Changes
+
+- [`3842160`](https://github.com/outfitter-dev/trails/commit/3842160ac4030807cb2dfca8e1da75e03febccf2): Teach vocabulary regrades to discover simple prose morphology as deferred
+  review inventory so authored plans surface forms like `blazed` and `blazing`.
+
+## 1.0.0-beta.34
+
+### Patch Changes
+
+- [`d67558b`](https://github.com/outfitter-dev/trails/commit/d67558bea3bfa363ed57e0f4091b6eccbf2a7710): Run governed AST symbol renames from the registry-backed `trails regrade` command path, including MCP parity, while preserving derived live API forms.
+
+## 1.0.0-beta.33
+
+### Patch Changes
+
+- [`0c40138`](https://github.com/outfitter-dev/trails/commit/0c40138efb962e779710daa172bdfd756d9d992f): Harden vocabulary regrades by deferring Markdown code contexts for review and
+  exposing structured preserve rules through the Trails `regrade` command.
+- [`7d65189`](https://github.com/outfitter-dev/trails/commit/7d65189cc33408755fe07a0b5679f1ed01123455): Expose derived live-API preserve inventory in vocabulary Regrade runs and have the Trails operator regrade surface derive current facet API preserves from live topo and MCP surface facts.
+- [`fc002d5`](https://github.com/outfitter-dev/trails/commit/fc002d5669f4303427e99f45f9998fd0b0172bdb): Add governed AST identifier rename helpers and Warden residue detection for
+  active vocabulary symbol transitions.
+- [`6ca0d8f`](https://github.com/outfitter-dev/trails/commit/6ca0d8f776801eee71ddd86cb88c198eaf5815fd): Add a typed governed-vocabulary transition registry that Warden owns and Regrade
+  can consume for migration planning.
+- [`04bb8a4`](https://github.com/outfitter-dev/trails/commit/04bb8a42af4ada51a74b1d8c83697db92035b5e9): Expose vocabulary Regrade occurrence dispositions and disposition summary counts alongside mechanical verdicts.
+
+  Accept explicit preserve-rule dispositions through the `trails regrade` CLI/MCP contract.
+
+## 1.0.0-beta.32
+
+### Patch Changes
+
+- f3c4fef: Export a shared `escapeRegExp` helper from core and migrate first-party callers off local copies.
+- fe72b84: Fold remaining Regrade and Warden scan-target surfaces onto the shared path-scope vocabulary.
+- Updated dependencies [3e5c0fc]
+- Updated dependencies [f3c4fef]
+- Updated dependencies [cb0a9d8]
+- Updated dependencies [21c6dda]
+- Updated dependencies [fe72b84]
+  - @ontrails/core@1.0.0-beta.32
+  - @ontrails/warden@1.0.0-beta.32
+
+## 1.0.0-beta.31
+
+### Patch Changes
+
+- e2f3d23: Default Regrade reports to actionable entries, add skip counts grouped by
+  reason, and expose an `includeEntries` option for full report inventories.
+- 9be2b7e: Load project-local Warden term-rewrite rules from the Regrade root so repo-owned
+  migration classes can run through `trails regrade`.
+- 47f782c: Add occurrence-level vocabulary regrade reports with plan, ledger,
+  and completion-gate facts. The Trails `regrade` operator command now supports
+  positional `<from> <to>` regrade runs and exposes the same capability through
+  the curated MCP surface.
+- ee9f3ae: Let Warden fix capabilities declare downstream scan targets and have Regrade
+  honor those targets for Warden-backed term-rewrite classes.
+
+  Dogfood the first safe facet-to-trailhead prose rewrite through project-local
+  Warden rules and Regrade.
+
+- 982a4d7: Add Regrade path-scope exclusion globs for vocabulary runs and expose them
+  through the `trails regrade` CLI/MCP contract.
+- 1540233: Add Regrade scan inventory summaries that group matched files by extension and
+  top-level path, with occurrence counts for vocabulary regrade reports.
+- a079073: Rename Regrade path-scope scan controls from `ignore` to `exclude` across CLI, MCP, and project config.
+- Updated dependencies [ee9f3ae]
+- Updated dependencies [a0126d9]
+- Updated dependencies [4cd5d4e]
+- Updated dependencies [6a26a08]
+- Updated dependencies [38907cc]
+  - @ontrails/warden@1.0.0-beta.31
+  - @ontrails/core@1.0.0-beta.31
+
 ## 1.0.0-beta.30
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/regrade",
-  "version": "1.0.0-beta.30",
+  "version": "1.0.0-beta.39",
   "description": "Downstream migration reporting and safe rewrite helpers for Trails.",
   "files": [
     "src/**/*.ts",
@@ -22,12 +22,12 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/core": "^1.0.0-beta.30",
-    "@ontrails/warden": "^1.0.0-beta.30",
+    "@ontrails/core": "^1.0.0-beta.39",
+    "@ontrails/warden": "^1.0.0-beta.39",
     "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@ontrails/testing": "^1.0.0-beta.30",
-    "@ontrails/topographer": "^1.0.0-beta.30"
+    "@ontrails/testing": "^1.0.0-beta.39",
+    "@ontrails/topographer": "^1.0.0-beta.39"
   }
 }

package/src/downstream/ast-rewrite.ts

@@ -6,12 +6,15 @@ import type {
 import {
   applySourceEdits,
   createSourceEdit,
+  getStringValue,
   identifierName,
+  isStringLiteral,
   offsetToLineColumn,
   parseWithDiagnostics,
   validateSourceEdits,
   walkWithScopeContext,
 } from '@ontrails/warden/ast';
+import type { GovernedVocabularyTransition } from '@ontrails/warden';
 
 import type {
   RegradeClass,
@@ -231,12 +234,45 @@ export interface AstIdentifierRenameClassOptions {
   readonly from: string;
   readonly id?: string;
   readonly reviewDeclarationTypes?: ReadonlySet<string>;
+  readonly shouldPreserve?: (
+    occurrence: AstIdentifierRenameOccurrence
+  ) => boolean;
+  readonly to: string;
+}
+
+export interface AstIdentifierRenameOccurrence {
+  readonly end: number;
+  readonly from: string;
+  readonly path: string;
+  readonly source: string;
+  readonly start: number;
+  readonly to: string;
+}
+
+export interface AstStringLiteralRenameClassOptions {
+  readonly describe?: string;
+  readonly from: string;
+  readonly id?: string;
+  readonly shouldPreserve?: (
+    occurrence: AstIdentifierRenameOccurrence
+  ) => boolean;
   readonly to: string;
 }
 
 const isIdentifierNamed = (node: AstNode, name: string): boolean =>
   node.type === 'Identifier' && identifierName(node) === name;
 
+const identifierTokenSpan = (
+  node: AstNode,
+  source: string,
+  name: string
+): { readonly end: number; readonly start: number } | null => {
+  const end = node.start + name.length;
+  return source.slice(node.start, end) === name
+    ? { end, start: node.start }
+    : null;
+};
+
 export const createAstIdentifierRenameClass = (
   options: AstIdentifierRenameClassOptions
 ): RegradeClass => {
@@ -253,14 +289,20 @@ export const createAstIdentifierRenameClass = (
         return null;
       }
 
-      const declaration = context.getDeclaration(options.from);
-      if (declaration && reviewDeclarationTypes.has(declaration.type)) {
+      const span = identifierTokenSpan(node, context.source, options.from);
+      if (span === null) {
         const location = offsetToLineColumn(context.source, node.start);
+        const caution = `Identifier "${options.from}" token span could not be verified; routed to review.`;
         return {
           detail: {
+            candidateReplacement: options.to,
             expectedTarget: `Rename identifier "${options.from}" to "${options.to}".`,
+            judgment: 'unresolved',
+            matchedForm: options.from,
             nodeKind: node.type,
-            reason: 'ast-identifier-review-declaration',
+            preserveCautions: [caution],
+            reason: 'ast-identifier-token-span-unverified',
+            signals: ['ast:identifier-rename'],
             span: {
               column: location.column,
               end: node.end,
@@ -271,16 +313,169 @@ export const createAstIdentifierRenameClass = (
             symbol: options.from,
           },
           kind: 'review',
-          note: `Identifier "${options.from}" resolves to ${declaration.type}; routed to review.`,
+          note: caution,
+          reason: 'ast-identifier-token-span-unverified',
+        };
+      }
+
+      if (
+        options.shouldPreserve?.({
+          end: span.end,
+          from: options.from,
+          path: context.path,
+          source: context.source,
+          start: span.start,
+          to: options.to,
+        }) === true
+      ) {
+        return null;
+      }
+
+      const declaration = context.getDeclaration(options.from);
+      if (declaration && reviewDeclarationTypes.has(declaration.type)) {
+        const location = offsetToLineColumn(context.source, span.start);
+        const caution = `Identifier "${options.from}" resolves to ${declaration.type}; routed to review.`;
+        return {
+          detail: {
+            candidateReplacement: options.to,
+            expectedTarget: `Rename identifier "${options.from}" to "${options.to}".`,
+            judgment: 'unresolved',
+            matchedForm: options.from,
+            nodeKind: node.type,
+            preserveCautions: [caution],
+            reason: 'ast-identifier-review-declaration',
+            signals: ['ast:identifier-rename'],
+            span: {
+              column: location.column,
+              end: span.end,
+              line: location.line,
+              start: span.start,
+            },
+            suggestedValidation: 'bun run typecheck',
+            symbol: options.from,
+          },
+          kind: 'review',
+          note: caution,
           reason: 'ast-identifier-review-declaration',
         };
       }
 
       return {
-        edit: createSourceEdit(node.start, node.end, options.to),
+        edit: createSourceEdit(span.start, span.end, options.to),
         kind: 'edit',
         note: `Renamed identifier "${options.from}" to "${options.to}".`,
       };
     },
   });
 };
+
+const stringLiteralValueSpan = (
+  node: AstNode,
+  source: string,
+  value: string
+): { readonly end: number; readonly start: number } | null => {
+  const raw = source.slice(node.start, node.end);
+  const relativeStart = raw.indexOf(value);
+  if (relativeStart === -1 || raw.includes(value, relativeStart + 1)) {
+    return null;
+  }
+  const start = node.start + relativeStart;
+  return { end: start + value.length, start };
+};
+
+export const createAstStringLiteralRenameClass = (
+  options: AstStringLiteralRenameClassOptions
+): RegradeClass =>
+  createAstRewriteClass({
+    describe:
+      options.describe ??
+      `Rename string literal "${options.from}" to "${options.to}".`,
+    id:
+      options.id ?? `ast-string-literal-rename:${options.from}->${options.to}`,
+    visit: (node, context) => {
+      if (!isStringLiteral(node) || getStringValue(node) !== options.from) {
+        return null;
+      }
+
+      const span = stringLiteralValueSpan(node, context.source, options.from);
+      if (span === null) {
+        const location = offsetToLineColumn(context.source, node.start);
+        const caution = `String literal "${options.from}" token span could not be verified; routed to review.`;
+        return {
+          detail: {
+            candidateReplacement: options.to,
+            expectedTarget: `Rename string literal "${options.from}" to "${options.to}".`,
+            judgment: 'unresolved',
+            matchedForm: options.from,
+            nodeKind: node.type,
+            preserveCautions: [caution],
+            reason: 'ast-string-literal-token-span-unverified',
+            signals: ['ast:string-literal-rename'],
+            span: {
+              column: location.column,
+              end: node.end,
+              line: location.line,
+              start: node.start,
+            },
+            suggestedValidation: 'bun run typecheck',
+            symbol: options.from,
+          },
+          kind: 'review',
+          note: caution,
+          reason: 'ast-string-literal-token-span-unverified',
+        };
+      }
+
+      if (
+        options.shouldPreserve?.({
+          end: span.end,
+          from: options.from,
+          path: context.path,
+          source: context.source,
+          start: span.start,
+          to: options.to,
+        }) === true
+      ) {
+        return null;
+      }
+
+      return {
+        edit: createSourceEdit(span.start, span.end, options.to),
+        kind: 'edit',
+        note: `Renamed string literal "${options.from}" to "${options.to}".`,
+      };
+    },
+  });
+
+export const createGovernedAstIdentifierRenameClasses = (
+  transition: GovernedVocabularyTransition,
+  options: {
+    readonly shouldPreserve?: (
+      occurrence: AstIdentifierRenameOccurrence
+    ) => boolean;
+  } = {}
+): readonly RegradeClass[] => [
+  ...transition.symbolRenames.map((rename) =>
+    createAstIdentifierRenameClass({
+      describe: `Rename governed symbol "${rename.from}" to "${rename.to}" for ${transition.id}.`,
+      from: rename.from,
+      id: `ast-symbol-rename:${transition.id}:${rename.from}->${rename.to}`,
+      reviewDeclarationTypes: new Set(rename.reviewDeclarationTypes),
+      ...(options.shouldPreserve === undefined
+        ? {}
+        : { shouldPreserve: options.shouldPreserve }),
+      to: rename.to,
+    })
+  ),
+  ...transition.stringLiteralRenames.map((rename) =>
+    createAstStringLiteralRenameClass({
+      describe: `Rename governed string literal "${rename.from}" to "${rename.to}" for ${transition.id}.`,
+      from: rename.from,
+      id: `ast-string-literal-rename:${transition.id}:${rename.from}->${rename.to}`,
+      ...(options.shouldPreserve === undefined
+        ? {}
+        : { shouldPreserve: options.shouldPreserve }),
+      to: rename.to,
+    })
+  ),
+];

package/src/downstream/collect.ts

@@ -1,4 +1,9 @@
-import { NotFoundError, Result, trail } from '@ontrails/core';
+import {
+  NotFoundError,
+  Result,
+  matchesAnyPathGlob,
+  trail,
+} from '@ontrails/core';
 import { readdirSync } from 'node:fs';
 import { join, posix, relative, resolve, sep } from 'node:path';
 import { z } from 'zod';
@@ -66,6 +71,10 @@ export interface DownstreamCollectionOptions {
   readonly ignoredDirectories?: readonly string[];
   /** Source extensions to collect. Defaults to {@link DEFAULT_SOURCE_EXTENSIONS}. */
   readonly extensions?: readonly string[];
+  /** Root-relative path globs to skip before collection. */
+  readonly exclude?: readonly string[];
+  /** Root-relative path globs to collect. Omit to collect all matching files. */
+  readonly include?: readonly string[];
 }
 
 /** Outcome of classifying a single directory entry. */
@@ -79,6 +88,16 @@ const extensionOf = (name: string): string => {
   return dot <= 0 ? '' : name.slice(dot);
 };
 
+const normalizeExtension = (extension: string): string =>
+  extension === '' || extension.startsWith('.') ? extension : `.${extension}`;
+
+const collectionExtensions = (
+  extensions: readonly string[] | undefined
+): readonly string[] =>
+  extensions === undefined
+    ? DEFAULT_SOURCE_EXTENSIONS
+    : extensions.map(normalizeExtension);
+
 /**
  * Decide what to do with a single directory entry. Pure: no filesystem access,
  * so collection policy can be tested directly with synthetic entries.
@@ -90,7 +109,7 @@ export const classifyDownstreamEntry = (
 ): DownstreamEntryClassification => {
   const ignoredDirectories =
     options.ignoredDirectories ?? DEFAULT_IGNORED_DIRECTORIES;
-  const extensions = options.extensions ?? DEFAULT_SOURCE_EXTENSIONS;
+  const extensions = collectionExtensions(options.extensions);
 
   if (kind === 'directory') {
     return ignoredDirectories.includes(name)
@@ -100,7 +119,7 @@ export const classifyDownstreamEntry = (
   if (kind === 'other') {
     return { action: 'skip', reason: 'unsupported-entry' };
   }
-  return extensions.includes(extensionOf(name))
+  return extensions.length === 0 || extensions.includes(extensionOf(name))
     ? { action: 'collect' }
     : { action: 'skip', reason: 'unsupported-extension' };
 };
@@ -177,13 +196,25 @@ export const collectDownstreamSources = (
     for (const entry of read.entries) {
       const absolutePath = join(current, entry.name);
       const path = toPosixRelative(absoluteRoot, absolutePath);
+      if (matchesAnyPathGlob(path, options.exclude)) {
+        skipped.push({ path, reason: 'ignored-glob' });
+        continue;
+      }
       const classification = classifyDownstreamEntry(
         entry.name,
         entry.kind,
         options
       );
       if (classification.action === 'collect') {
-        files.push({ absolutePath, path });
+        if (
+          options.include !== undefined &&
+          options.include.length > 0 &&
+          !matchesAnyPathGlob(path, options.include)
+        ) {
+          skipped.push({ path, reason: 'not-included-glob' });
+        } else {
+          files.push({ absolutePath, path });
+        }
       } else if (classification.action === 'recurse') {
         queue.push(absolutePath);
       } else {
@@ -198,6 +229,10 @@ export const collectDownstreamSources = (
 };
 
 export const collectDownstreamSourcesInput = z.object({
+  exclude: z
+    .array(z.string())
+    .optional()
+    .describe('Root-relative path globs to skip before collection'),
   extensions: z
     .array(z.string())
     .optional()
@@ -206,6 +241,10 @@ export const collectDownstreamSourcesInput = z.object({
     .array(z.string())
     .optional()
     .describe('Directory names to skip during collection'),
+  include: z
+    .array(z.string())
+    .optional()
+    .describe('Root-relative path globs to collect'),
   root: z
     .string()
     .describe('Absolute path to the downstream repo root to scan'),
@@ -247,6 +286,8 @@ export const collectDownstreamSourcesTrail = trail(
         ...(input.extensions === undefined
           ? {}
           : { extensions: input.extensions }),
+        ...(input.exclude === undefined ? {} : { exclude: input.exclude }),
+        ...(input.include === undefined ? {} : { include: input.include }),
         ...(input.ignoredDirectories === undefined
           ? {}
           : { ignoredDirectories: input.ignoredDirectories }),