@ontrails/regrade 1.0.0-beta.45 → 1.0.0-beta.47

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @ontrails/regrade
 
+## 1.0.0-beta.47
+
+### Patch Changes
+
+- [`90d394c`](https://github.com/outfitter-dev/trails/commit/90d394c005fdf6b898ba7052d0b56755af0f4954): Derive nested worktree, repository, and submodule collection boundaries in the
+  shared Source walker. Regrade and Warden now observe one directly targeted
+  working tree per run, and Regrade audit summaries expose boundary skip counts.
+
+## 1.0.0-beta.46
+
+### Minor Changes
+
+- [`701ab85`](https://github.com/outfitter-dev/trails/commit/701ab85bd237e5fcf03725c56b70adb3612d6c15): Expose in-memory prepared class and vocabulary evaluations with deterministic identity and source freshness checks.
+- [`c83d0b6`](https://github.com/outfitter-dev/trails/commit/c83d0b67ac928af1b44c1f2d2c4b36aa09a24a70): Inventory parser-native source comments and TSDoc as exact review-only entries
+  for governed classified vocabulary transitions across CLI, MCP, and audit.
+- [`97ccb5c`](https://github.com/outfitter-dev/trails/commit/97ccb5c168f7dc0f157f2518c78b226d67cfa008): Add the strict v3 Regrade run-receipt contract, canonical serializer, compact classified-form judgments, and cache-independent hash-reference resolution.
+- [`9a8b6e4`](https://github.com/outfitter-dev/trails/commit/9a8b6e4af394c76c11e6d0007e0f5f94d0be2cb3): Persist Regrade lifecycle runs as canonical v3 receipts with exact Git blob evidence and authored field provenance, and validate their compact classified-form projection independently in Warden.
+
+### Patch Changes
+
+- [`768cc79`](https://github.com/outfitter-dev/trails/commit/768cc79ca10947b8808b376e281e1a81131b4acc): Close missed projection vocabulary residue in Regrade internals and public
+  error-rendering guidance, and keep lifecycle-ambiguous governed identifiers in
+  the Warden review inventory instead of assigning them an unsafe automatic
+  target.
+
 ## 1.0.0-beta.45
 
 ## 1.0.0-beta.44

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/regrade",
-  "version": "1.0.0-beta.45",
+  "version": "1.0.0-beta.47",
   "description": "Downstream migration reporting and safe rewrite helpers for Trails.",
   "repository": {
     "type": "git",
@@ -27,13 +27,13 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/core": "^1.0.0-beta.45",
-    "@ontrails/source": "^1.0.0-beta.45",
-    "@ontrails/warden": "^1.0.0-beta.45",
+    "@ontrails/core": "^1.0.0-beta.47",
+    "@ontrails/source": "^1.0.0-beta.47",
+    "@ontrails/warden": "^1.0.0-beta.47",
     "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@ontrails/testing": "^1.0.0-beta.45",
-    "@ontrails/topography": "^1.0.0-beta.45"
+    "@ontrails/testing": "^1.0.0-beta.47",
+    "@ontrails/topography": "^1.0.0-beta.47"
   }
 }

package/src/downstream/collect.ts

@@ -4,8 +4,7 @@ import {
   matchesAnyPathGlob,
   trail,
 } from '@ontrails/core';
-import { readdirSync } from 'node:fs';
-import { join, posix, relative, resolve, sep } from 'node:path';
+import { collectSourceTree } from '@ontrails/source';
 import { z } from 'zod';
 
 /**
@@ -124,46 +123,10 @@ export const classifyDownstreamEntry = (
     : { action: 'skip', reason: 'unsupported-extension' };
 };
 
-const toPosixRelative = (root: string, absolutePath: string): string => {
-  const rel = relative(root, absolutePath);
-  return sep === posix.sep ? rel : rel.split(sep).join(posix.sep);
-};
-
 const isImmutableRegradeHistoryDirectory = (path: string): boolean =>
   path === '.trails/regrade/history' ||
   path.endsWith('/.trails/regrade/history');
 
-const direntKind = (dirent: {
-  isDirectory(): boolean;
-  isFile(): boolean;
-}): DownstreamEntryKind => {
-  if (dirent.isDirectory()) {
-    return 'directory';
-  }
-  return dirent.isFile() ? 'file' : 'other';
-};
-
-type DirectoryRead =
-  | {
-      readonly ok: true;
-      readonly entries: readonly {
-        readonly name: string;
-        readonly kind: DownstreamEntryKind;
-      }[];
-    }
-  | { readonly ok: false };
-
-const readDirectory = (absoluteDir: string): DirectoryRead => {
-  try {
-    const entries = readdirSync(absoluteDir, { withFileTypes: true }).map(
-      (dirent) => ({ kind: direntKind(dirent), name: dirent.name })
-    );
-    return { entries, ok: true };
-  } catch {
-    return { ok: false };
-  }
-};
-
 /**
  * Walk an explicit downstream root and collect candidate source files.
  *
@@ -175,69 +138,27 @@ const readDirectory = (absoluteDir: string): DirectoryRead => {
 export const collectDownstreamSources = (
   root: string,
   options: DownstreamCollectionOptions = {}
-): DownstreamSourceCollection | null => {
-  const absoluteRoot = resolve(root);
-  const rootRead = readDirectory(absoluteRoot);
-  if (!rootRead.ok) {
-    return null;
-  }
-
-  const files: CollectedSource[] = [];
-  const skipped: SkippedSource[] = [];
-  const queue: string[] = [absoluteRoot];
-
-  while (queue.length > 0) {
-    const current = queue.shift() as string;
-    const read = current === absoluteRoot ? rootRead : readDirectory(current);
-    if (!read.ok) {
-      skipped.push({
-        path: toPosixRelative(absoluteRoot, current),
-        reason: 'unreadable-directory',
-      });
-      continue;
-    }
-
-    for (const entry of read.entries) {
-      const absolutePath = join(current, entry.name);
-      const path = toPosixRelative(absoluteRoot, absolutePath);
+): DownstreamSourceCollection | null =>
+  collectSourceTree(root, {
+    classify: ({ kind, name, path }) => {
       if (matchesAnyPathGlob(path, options.exclude)) {
-        skipped.push({ path, reason: 'ignored-glob' });
-        continue;
+        return { action: 'skip', reason: 'ignored-glob' };
+      }
+      if (kind === 'directory' && isImmutableRegradeHistoryDirectory(path)) {
+        return { action: 'skip', reason: 'immutable-regrade-history' };
       }
+      const classification = classifyDownstreamEntry(name, kind, options);
       if (
-        entry.kind === 'directory' &&
-        isImmutableRegradeHistoryDirectory(path)
+        classification.action === 'collect' &&
+        options.include !== undefined &&
+        options.include.length > 0 &&
+        !matchesAnyPathGlob(path, options.include)
       ) {
-        skipped.push({ path, reason: 'immutable-regrade-history' });
-        continue;
+        return { action: 'skip', reason: 'not-included-glob' };
       }
-      const classification = classifyDownstreamEntry(
-        entry.name,
-        entry.kind,
-        options
-      );
-      if (classification.action === 'collect') {
-        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 {
-        skipped.push({ path, reason: classification.reason });
-      }
-    }
-  }
-
-  files.sort((a, b) => a.path.localeCompare(b.path));
-  skipped.sort((a, b) => a.path.localeCompare(b.path));
-  return { files, root: absoluteRoot, skipped };
-};
+      return classification;
+    },
+  });
 
 export const collectDownstreamSourcesInput = z.object({
   exclude: z

package/src/downstream/export-restructure.ts

@@ -1468,7 +1468,7 @@ const applyMcpTrailheadsClass = (
 };
 
 /**
- * Project call-site MCP trailhead maps into `surfaceOverlay({ mcp: { name:
+ * Convert call-site MCP trailhead maps into `surfaceOverlay({ mcp: { name:
  * [selectors] } })` group bindings. Because the map usually lives in a
  * different file than the app module, the default outcome is a classified
  * `needs-review` handoff naming the exact target shape; when the same file
@@ -1512,7 +1512,7 @@ export const exportRestructureClasses: readonly RegradeClass[] = Object.freeze([
 ]);
 
 /**
- * Project a Warden rule that advertises the `export-restructure` fix class
+ * Convert a Warden rule that advertises the `export-restructure` fix class
  * into its registered Regrade class. Warden owns detection and fix metadata;
  * Regrade owns the structural transform. Returns `null` for rules without an
  * `export-restructure` fix class or without a registered transform.

package/src/downstream/file-renames.ts

@@ -7,6 +7,7 @@ import {
   matchesAnyPathGlob,
 } from '@ontrails/core';
 import type { Result as TrailsResult } from '@ontrails/core';
+import { createHash } from 'node:crypto';
 import {
   existsSync,
   mkdirSync,
@@ -146,6 +147,7 @@ export interface FileRenameRegradeRun {
   readonly occurrencePaths: readonly string[];
   readonly policyOccurrencePaths: readonly string[];
   readonly report: RegradeReport;
+  readonly sourceStateHash: string;
 }
 
 const asError = (error: unknown): Error =>
@@ -154,6 +156,79 @@ const asError = (error: unknown): Error =>
 const normalizeRenamePath = (path: string): string =>
   posix.normalize(path.replaceAll('\\', '/'));
 
+const compareFileRenameCodeUnits = (left: string, right: string): number => {
+  if (left < right) {
+    return -1;
+  }
+  if (left > right) {
+    return 1;
+  }
+  return 0;
+};
+
+const fileRenameSourceStateHash = (params: {
+  readonly apply: boolean;
+  readonly collected: DownstreamSourceCollection;
+  readonly renames: readonly VocabularyFileRename[];
+  readonly resolved: readonly ResolvedFileRename[];
+}): TrailsResult<string, Error> => {
+  const unreadable = params.collected.skipped
+    .filter(
+      (entry) =>
+        entry.reason === 'unreadable-file' ||
+        entry.reason === 'unreadable-directory'
+    )
+    .map((entry) => entry.path);
+  if (unreadable.length > 0) {
+    return Result.err(
+      new ValidationError('File rename Regrade sources must all be readable.', {
+        context: { paths: unreadable },
+      })
+    );
+  }
+  const sourceFiles = new Map(
+    params.collected.files.map((file) => [file.path, file])
+  );
+  for (const [index, rename] of params.renames.entries()) {
+    const resolved = params.resolved[index];
+    if (resolved === undefined) {
+      return Result.err(
+        new InternalError('File rename Regrade endpoint was not resolved.')
+      );
+    }
+    const useTarget = params.apply || resolved.alreadyApplied;
+    const path = normalizeRenamePath(useTarget ? rename.to : rename.from);
+    sourceFiles.set(path, {
+      absolutePath: useTarget ? resolved.to : resolved.from,
+      path,
+    });
+  }
+  const sources: { readonly bytes: string; readonly path: string }[] = [];
+  for (const file of [...sourceFiles.values()].toSorted((left, right) =>
+    compareFileRenameCodeUnits(left.path, right.path)
+  )) {
+    try {
+      sources.push({
+        bytes: readFileSync(file.absolutePath).toString('base64'),
+        path: file.path,
+      });
+    } catch (error) {
+      return Result.err(
+        new ValidationError(
+          'File rename Regrade sources must all be readable.',
+          {
+            ...(error instanceof Error ? { cause: error } : {}),
+            context: { paths: [file.path] },
+          }
+        )
+      );
+    }
+  }
+  return Result.ok(
+    createHash('sha256').update(JSON.stringify({ sources })).digest('hex')
+  );
+};
+
 const openedPolicyDirectories = (
   scope: VocabularyRegradeScope | undefined
 ): readonly string[] =>
@@ -232,16 +307,16 @@ const preserveVocabularyCase = (
     : replacement;
 };
 
-const projectVocabularyText = (
+const deriveVocabularyText = (
   source: string,
   plan: VocabularyRegradePlan
 ): string => {
-  let projected = source;
+  let derived = source;
   const safeForms = vocabularyRewriteFormsForPlan(plan).toSorted(
     ([left], [right]) => right.length - left.length
   );
   for (const [from, to] of safeForms) {
-    projected = projected.replaceAll(
+    derived = derived.replaceAll(
       new RegExp(
         `(?<![A-Za-z0-9_$-])${escapeRegExp(from)}(?![A-Za-z0-9_$-])`,
         plan.caseSensitive === true ? 'gu' : 'giu'
@@ -250,7 +325,7 @@ const projectVocabularyText = (
         plan.caseSensitive === true ? to : preserveVocabularyCase(matched, to)
     );
   }
-  return projected;
+  return derived;
 };
 
 const astReferenceMappings = (
@@ -372,7 +447,7 @@ const referenceMappingsForPath = (
       rename.from,
       ...(vocabularyPlan === undefined
         ? []
-        : [projectVocabularyText(rename.from, vocabularyPlan)]),
+        : [deriveVocabularyText(rename.from, vocabularyPlan)]),
     ].filter((value, index, values) => values.indexOf(value) === index);
     for (const sourcePath of sourcePaths) {
       mappings.push(
@@ -1121,7 +1196,7 @@ const isGeneratedRegradeArtifactPath = (path: string): boolean =>
 const filterOpenedPolicyDirectories = (
   collected: DownstreamSourceCollection,
   opened: readonly string[],
-  projectedTargetPaths: ReadonlySet<string>,
+  derivedTargetPaths: ReadonlySet<string>,
   scope: VocabularyRegradeScope | undefined,
   renames: readonly VocabularyFileRename[],
   apply: boolean
@@ -1137,7 +1212,7 @@ const filterOpenedPolicyDirectories = (
     );
     return (
       !insideOpenedDirectory ||
-      projectedTargetPaths.has(normalizeRenamePath(file.path)) ||
+      derivedTargetPaths.has(normalizeRenamePath(file.path)) ||
       policyForPath(scopePath, scope) !== undefined
     );
   });
@@ -1199,22 +1274,22 @@ const collectionExcludeForFileRenames = (params: {
 const normalizeExtension = (extension: string): string =>
   extension === '' || extension.startsWith('.') ? extension : `.${extension}`;
 
-const collectionExtensionProjectionForFileRenames = (params: {
+const deriveCollectionExtensionsForFileRenames = (params: {
   readonly apply: boolean;
   readonly extensions: readonly string[];
   readonly renames: readonly VocabularyFileRename[];
 }): {
   readonly extensions: readonly string[];
-  readonly projectedTargetPaths: ReadonlySet<string>;
+  readonly derivedTargetPaths: ReadonlySet<string>;
 } => {
   const sourceExtensions = new Set(params.extensions.map(normalizeExtension));
   if (!params.apply || sourceExtensions.size === 0) {
     return {
+      derivedTargetPaths: new Set(),
       extensions: params.extensions,
-      projectedTargetPaths: new Set(),
     };
   }
-  const projectedTargetPaths = new Set(
+  const derivedTargetPaths = new Set(
     params.renames
       .filter((rename) =>
         sourceExtensions.has(
@@ -1224,18 +1299,18 @@ const collectionExtensionProjectionForFileRenames = (params: {
       .map((rename) => normalizeRenamePath(rename.to))
   );
   return {
+    derivedTargetPaths,
     extensions: [
       ...sourceExtensions,
-      ...new Set([...projectedTargetPaths].map((path) => extname(path))),
+      ...new Set([...derivedTargetPaths].map((path) => extname(path))),
     ],
-    projectedTargetPaths,
   };
 };
 
-const filterProjectedTargetExtensions = (
+const filterDerivedTargetExtensions = (
   collected: DownstreamSourceCollection,
   sourceExtensions: readonly string[],
-  projectedTargetPaths: ReadonlySet<string>
+  derivedTargetPaths: ReadonlySet<string>
 ): DownstreamSourceCollection => {
   const normalizedSourceExtensions = new Set(
     sourceExtensions.map(normalizeExtension)
@@ -1246,7 +1321,7 @@ const filterProjectedTargetExtensions = (
   const files = collected.files.filter(
     (file) =>
       normalizedSourceExtensions.has(extname(file.path)) ||
-      projectedTargetPaths.has(normalizeRenamePath(file.path))
+      derivedTargetPaths.has(normalizeRenamePath(file.path))
   );
   const selected = new Set(files.map((file) => file.path));
   return {
@@ -1264,7 +1339,7 @@ const filterProjectedTargetExtensions = (
 const withExactMovedTargets = (params: {
   readonly apply: boolean;
   readonly collected: DownstreamSourceCollection;
-  readonly projectedTargetPaths: ReadonlySet<string>;
+  readonly derivedTargetPaths: ReadonlySet<string>;
   readonly renames: readonly VocabularyFileRename[];
   readonly resolved: readonly ResolvedFileRename[];
   readonly scope: VocabularyRegradeScope | undefined;
@@ -1279,7 +1354,7 @@ const withExactMovedTargets = (params: {
     const path = normalizeRenamePath(rename.to);
     const sourcePath = sourcePathForMovedTarget(path, params.renames);
     if (
-      !params.projectedTargetPaths.has(path) ||
+      !params.derivedTargetPaths.has(path) ||
       (params.scope?.include !== undefined &&
         !matchesAnyPathGlob(sourcePath, params.scope.include)) ||
       (params.scope?.exclude !== undefined &&
@@ -1430,13 +1505,13 @@ export const runFileRenameRegrade = (params: {
   });
   const sourceExtensions =
     params.scope?.extensions ?? fileRenameSourceExtensions;
-  const extensionProjection = collectionExtensionProjectionForFileRenames({
+  const derivedExtensions = deriveCollectionExtensionsForFileRenames({
     apply,
     extensions: sourceExtensions,
     renames: params.renames,
   });
   const rawCollection = collectDownstreamSources(params.root, {
-    extensions: extensionProjection.extensions,
+    extensions: derivedExtensions.extensions,
     ...(exclude === undefined ? {} : { exclude }),
     ...(include === undefined ? {} : { include }),
     ignoredDirectories: DEFAULT_IGNORED_DIRECTORIES.filter(
@@ -1452,20 +1527,20 @@ export const runFileRenameRegrade = (params: {
   const exactTargetCollection = withExactMovedTargets({
     apply,
     collected: rawCollection,
-    projectedTargetPaths: extensionProjection.projectedTargetPaths,
+    derivedTargetPaths: derivedExtensions.derivedTargetPaths,
     renames: params.renames,
     resolved: validated.value,
     scope: params.scope,
   });
-  const extensionScopedCollection = filterProjectedTargetExtensions(
+  const extensionScopedCollection = filterDerivedTargetExtensions(
     exactTargetCollection,
     sourceExtensions,
-    extensionProjection.projectedTargetPaths
+    derivedExtensions.derivedTargetPaths
   );
   const scopedCollection = filterOpenedPolicyDirectories(
     extensionScopedCollection,
     opened,
-    extensionProjection.projectedTargetPaths,
+    derivedExtensions.derivedTargetPaths,
     params.scope,
     params.renames,
     apply
@@ -1480,6 +1555,17 @@ export const runFileRenameRegrade = (params: {
         }
       : scopedCollection;
 
+  const sourceStateHash = fileRenameSourceStateHash({
+    apply,
+    collected,
+    renames: params.renames,
+    resolved: validated.value,
+  });
+  if (sourceStateHash.isErr()) {
+    rollbackResolvedRenames(moved.value);
+    return sourceStateHash;
+  }
+
   const evidence = params.renames.map(() => emptyEvidence());
   const targetPaths = new Set(
     params.renames.map((rename) => normalizeRenamePath(rename.to))
@@ -1516,7 +1602,7 @@ export const runFileRenameRegrade = (params: {
     }
   }
 
-  const projectedEvidence = params.renames.map((rename, index) => ({
+  const derivedEvidence = params.renames.map((rename, index) => ({
     ...rename,
     ...(evidence[index] ?? emptyEvidence()),
   }));
@@ -1548,10 +1634,10 @@ export const runFileRenameRegrade = (params: {
             applied:
               validated.value.filter((rename) => !rename.alreadyApplied)
                 .length +
-              projectedEvidence.reduce((sum, item) => sum + item.rewritten, 0),
+              derivedEvidence.reduce((sum, item) => sum + item.rewritten, 0),
             filesChanged: changedFiles.size,
             review,
-            skipped: projectedEvidence.reduce(
+            skipped: derivedEvidence.reduce(
               (sum, item) => sum + item.skipped,
               0
             ),
@@ -1582,9 +1668,10 @@ export const runFileRenameRegrade = (params: {
 
   return Result.ok({
     changedPaths: [...changedFiles].toSorted(),
-    evidence: projectedEvidence,
+    evidence: derivedEvidence,
     occurrencePaths: referenceResult.value.occurrencePaths,
     policyOccurrencePaths: referenceResult.value.policyOccurrencePaths,
     report,
+    sourceStateHash: sourceStateHash.value,
   });
 };