@ontrails/regrade 1.0.0-beta.29

package/CHANGELOG.md

@@ -0,0 +1,150 @@
+# @ontrails/regrade
+
+## 1.0.0-beta.29
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.29
+- @ontrails/warden@1.0.0-beta.29
+
+## 1.0.0-beta.28
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.28
+- @ontrails/warden@1.0.0-beta.28
+
+## 1.0.0-beta.27
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.27
+- @ontrails/warden@1.0.0-beta.27
+
+## 1.0.0-beta.26
+
+### Patch Changes
+
+- 4e75b85: Carry structured review details from Warden-backed term-rewrite diagnostics into Regrade review reports.
+- Updated dependencies [1307568]
+- Updated dependencies [ef09e46]
+- Updated dependencies [38cd9d6]
+- Updated dependencies [f8403c4]
+- Updated dependencies [371d19e]
+- Updated dependencies [ff48e41]
+  - @ontrails/core@1.0.0-beta.26
+  - @ontrails/warden@1.0.0-beta.26
+
+## 1.0.0-beta.25
+
+### Patch Changes
+
+- b991263: Retire the package-owned `regrade.downstream.report` trail wrapper so the Trails operator app owns the public Regrade surface while `@ontrails/regrade` exposes the reusable engine APIs and report schema.
+- c36aca9: Preserve existing Result error boundaries directly and widen Warden pass-through
+  coaching beyond trail blazes.
+- 6250729: Expands the public AST guard/accessor surface and migrates Warden/Regrade AST
+  consumers onto the typed helpers instead of rule-local node-field casts.
+- f757cd7: Publish Regrade's downstream report and AST rewrite APIs, and expose a dry-run
+  by default `trails regrade` operator command with explicit apply mode.
+- Updated dependencies [a9fdbc7]
+- Updated dependencies [f8fd6ca]
+- Updated dependencies [0fcc42b]
+- Updated dependencies [c36aca9]
+- Updated dependencies [f556559]
+- Updated dependencies [6250729]
+- Updated dependencies [d73c38e]
+- Updated dependencies [3befcf1]
+- Updated dependencies [a8e4dc3]
+- Updated dependencies [a4f9cf6]
+- Updated dependencies [9bcf34e]
+- Updated dependencies [00c0cf8]
+- Updated dependencies [b313c58]
+- Updated dependencies [f245fa0]
+- Updated dependencies [f1e6efa]
+- Updated dependencies [caff950]
+- Updated dependencies [df13faf]
+  - @ontrails/warden@1.0.0-beta.25
+  - @ontrails/core@1.0.0-beta.25
+
+## 1.0.0-beta.24
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.24
+- @ontrails/warden@1.0.0-beta.24
+
+## 1.0.0-beta.23
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.23
+- @ontrails/warden@1.0.0-beta.23
+
+## 1.0.0-beta.22
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.22
+- @ontrails/warden@1.0.0-beta.22
+
+## 1.0.0-beta.21
+
+### Patch Changes
+
+- Updated dependencies [99523f2]
+- Updated dependencies [5be032c]
+  - @ontrails/core@1.0.0-beta.21
+  - @ontrails/warden@1.0.0-beta.21
+
+## 1.0.0-beta.20
+
+### Patch Changes
+
+- Updated dependencies [851a2a3]
+- Updated dependencies [8bc0708]
+- Updated dependencies [6901776]
+  - @ontrails/core@1.0.0-beta.20
+  - @ontrails/warden@1.0.0-beta.20
+
+## 1.0.0-beta.19
+
+### Patch Changes
+
+- Updated dependencies [e41c382]
+- Updated dependencies [1eb5bdc]
+- Updated dependencies [f8d80b9]
+- Updated dependencies [846a597]
+- Updated dependencies [f0f7e2f]
+- Updated dependencies [223aaad]
+- Updated dependencies [3125f4d]
+- Updated dependencies [2494dc6]
+- Updated dependencies [120caf5]
+- Updated dependencies [2d53717]
+- Updated dependencies [16cb740]
+- Updated dependencies [8894ecb]
+- Updated dependencies [fdf7ec9]
+- Updated dependencies [d76be13]
+- Updated dependencies [84f56a5]
+- Updated dependencies [64fb15a]
+- Updated dependencies [431b04c]
+- Updated dependencies [5d88104]
+- Updated dependencies [f04a9ef]
+- Updated dependencies [1c975c3]
+- Updated dependencies [48d5ff4]
+- Updated dependencies [d5d518e]
+- Updated dependencies [216bf10]
+- Updated dependencies [678cb1c]
+- Updated dependencies [5874fd6]
+- Updated dependencies [619cb15]
+- Updated dependencies [4642268]
+- Updated dependencies [9bab0cf]
+- Updated dependencies [3ceeba8]
+- Updated dependencies [beafd03]
+- Updated dependencies [7b173e0]
+- Updated dependencies [6e50e7b]
+- Updated dependencies [48edf8d]
+- Updated dependencies [12ffa3b]
+- Updated dependencies [2f262f7]
+- Updated dependencies [58b01f2]
+  - @ontrails/core@1.0.0-beta.19
+  - @ontrails/warden@1.0.0-beta.19

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@ontrails/regrade",
+  "version": "1.0.0-beta.29",
+  "description": "Downstream migration reporting and safe rewrite helpers for Trails.",
+  "files": [
+    "src/**/*.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint ./src",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@ontrails/core": "^1.0.0-beta.29",
+    "@ontrails/warden": "^1.0.0-beta.29",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@ontrails/testing": "^1.0.0-beta.29",
+    "@ontrails/topographer": "^1.0.0-beta.29"
+  }
+}

package/src/downstream/ast-rewrite.ts

@@ -0,0 +1,286 @@
+import type {
+  AstNode,
+  AstScopeContext,
+  SourceEdit,
+} from '@ontrails/warden/ast';
+import {
+  applySourceEdits,
+  createSourceEdit,
+  identifierName,
+  offsetToLineColumn,
+  parseWithDiagnostics,
+  validateSourceEdits,
+  walkWithScopeContext,
+} from '@ontrails/warden/ast';
+
+import type {
+  RegradeClass,
+  RegradeClassContext,
+  RegradeClassResult,
+  RegradeReviewDetail,
+} from './report.js';
+
+export interface AstRewriteContext extends AstScopeContext {
+  readonly path: string;
+  readonly source: string;
+}
+
+export type AstRewriteMatch =
+  | {
+      readonly edit: SourceEdit;
+      readonly kind: 'edit';
+      readonly note?: string;
+    }
+  | {
+      readonly detail?: RegradeReviewDetail;
+      readonly kind: 'review';
+      readonly note?: string;
+      readonly reason: string;
+    };
+
+export type AstRewriteVisitResult =
+  | AstRewriteMatch
+  | AstRewriteMatch[]
+  | null
+  | undefined;
+
+export interface AstRewriteClassOptions {
+  readonly describe: string;
+  readonly id: string;
+  readonly shouldScan?: (context: RegradeClassContext) => boolean;
+  readonly visit: (
+    node: AstNode,
+    context: AstRewriteContext
+  ) => AstRewriteVisitResult;
+}
+
+const defaultRegradeClassContext: RegradeClassContext = {
+  path: '<regrade-source>',
+};
+
+const toArray = (result: AstRewriteVisitResult): readonly AstRewriteMatch[] => {
+  if (result === undefined || result === null) {
+    return [];
+  }
+  return Array.isArray(result) ? result : [result];
+};
+
+const dedupeEdits = (edits: readonly SourceEdit[]): readonly SourceEdit[] => {
+  const seen = new Set<string>();
+  const unique: SourceEdit[] = [];
+
+  for (const edit of edits) {
+    const key = `${edit.start}:${edit.end}:${edit.replacement}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    unique.push(edit);
+  }
+
+  return unique;
+};
+
+const notesFor = (matches: readonly AstRewriteMatch[]): readonly string[] =>
+  matches.flatMap((match) => {
+    if (match.note) {
+      return [match.note];
+    }
+    if (match.kind === 'review') {
+      return [match.reason];
+    }
+    return [];
+  });
+
+const invalidEditsResult = (error: unknown): RegradeClassResult => ({
+  kind: 'needs-review',
+  notes: [
+    error instanceof Error
+      ? `AST rewrite edits could not be applied: ${error.message}`
+      : 'AST rewrite edits could not be applied.',
+  ],
+  reason: 'ast-rewrite-invalid-edits',
+});
+
+const astRewriteFailureResult = (
+  context: RegradeClassContext,
+  reason: string,
+  error: unknown
+): RegradeClassResult => ({
+  kind: 'needs-review',
+  notes: [
+    error instanceof Error
+      ? `AST rewrite failed for ${context.path}: ${error.message}`
+      : `AST rewrite failed for ${context.path}.`,
+  ],
+  reason,
+});
+
+const reviewDetailsFor = (
+  classId: string,
+  matches: readonly AstRewriteMatch[]
+): readonly RegradeReviewDetail[] | undefined => {
+  const details = matches.flatMap((match) => {
+    if (match.kind !== 'review' || match.detail === undefined) {
+      return [];
+    }
+    return [{ ...match.detail, classId: match.detail.classId ?? classId }];
+  });
+  return details.length === 0 ? undefined : details;
+};
+
+export const createAstRewriteClass = (
+  options: AstRewriteClassOptions
+): RegradeClass => ({
+  apply: (
+    source: string,
+    context: RegradeClassContext = defaultRegradeClassContext
+  ): RegradeClassResult => {
+    if (options.shouldScan) {
+      try {
+        if (!options.shouldScan(context)) {
+          return {
+            kind: 'skipped',
+            notes: ['Skipped by AST rewrite scan-target filtering.'],
+            reason: 'ast-rewrite-scan-target-filtered',
+          };
+        }
+      } catch (error: unknown) {
+        return astRewriteFailureResult(
+          context,
+          'ast-rewrite-scan-target-failed',
+          error
+        );
+      }
+    }
+
+    const parsed = parseWithDiagnostics(context.path, source);
+    if (!parsed.ast || parsed.diagnostics.length > 0) {
+      return {
+        kind: 'needs-review',
+        notes:
+          parsed.diagnostics.length > 0
+            ? parsed.diagnostics.map(
+                (diagnostic) =>
+                  `Could not safely parse ${context.path}: ${diagnostic.message}`
+              )
+            : [`Could not parse ${context.path} for AST rewrite.`],
+        reason: 'ast-rewrite-parse-failed',
+      };
+    }
+
+    const matches: AstRewriteMatch[] = [];
+    try {
+      walkWithScopeContext(parsed.ast, (node, scopeContext) => {
+        matches.push(
+          ...toArray(
+            options.visit(node, {
+              ...scopeContext,
+              path: context.path,
+              source,
+            })
+          )
+        );
+      });
+    } catch (error: unknown) {
+      return astRewriteFailureResult(
+        context,
+        'ast-rewrite-visitor-failed',
+        error
+      );
+    }
+
+    const reviewMatches = matches.filter((match) => match.kind === 'review');
+    if (reviewMatches.length > 0) {
+      const reviewDetails = reviewDetailsFor(options.id, reviewMatches);
+      return {
+        kind: 'needs-review',
+        notes: notesFor(reviewMatches),
+        reason: reviewMatches[0]?.reason ?? 'ast-rewrite-review-required',
+        ...(reviewDetails === undefined ? {} : { reviewDetails }),
+      };
+    }
+
+    const edits = dedupeEdits(
+      matches.flatMap((match) => (match.kind === 'edit' ? [match.edit] : []))
+    );
+    if (edits.length === 0) {
+      return {
+        kind: 'no-op',
+        notes: ['No AST rewrite matches found.'],
+      };
+    }
+
+    try {
+      validateSourceEdits(edits);
+      return {
+        kind: 'rewrite',
+        nextSource: applySourceEdits(source, edits),
+        notes: notesFor(matches),
+      };
+    } catch (error) {
+      return invalidEditsResult(error);
+    }
+  },
+  describe: options.describe,
+  id: options.id,
+});
+
+export interface AstIdentifierRenameClassOptions {
+  readonly describe?: string;
+  readonly from: string;
+  readonly id?: string;
+  readonly reviewDeclarationTypes?: ReadonlySet<string>;
+  readonly to: string;
+}
+
+const isIdentifierNamed = (node: AstNode, name: string): boolean =>
+  node.type === 'Identifier' && identifierName(node) === name;
+
+export const createAstIdentifierRenameClass = (
+  options: AstIdentifierRenameClassOptions
+): RegradeClass => {
+  const reviewDeclarationTypes =
+    options.reviewDeclarationTypes ?? new Set<string>();
+
+  return createAstRewriteClass({
+    describe:
+      options.describe ??
+      `Rename identifier "${options.from}" to "${options.to}".`,
+    id: options.id ?? `ast-identifier-rename:${options.from}->${options.to}`,
+    visit: (node, context) => {
+      if (!isIdentifierNamed(node, options.from)) {
+        return null;
+      }
+
+      const declaration = context.getDeclaration(options.from);
+      if (declaration && reviewDeclarationTypes.has(declaration.type)) {
+        const location = offsetToLineColumn(context.source, node.start);
+        return {
+          detail: {
+            expectedTarget: `Rename identifier "${options.from}" to "${options.to}".`,
+            nodeKind: node.type,
+            reason: 'ast-identifier-review-declaration',
+            span: {
+              column: location.column,
+              end: node.end,
+              line: location.line,
+              start: node.start,
+            },
+            suggestedValidation: 'bun run typecheck',
+            symbol: options.from,
+          },
+          kind: 'review',
+          note: `Identifier "${options.from}" resolves to ${declaration.type}; routed to review.`,
+          reason: 'ast-identifier-review-declaration',
+        };
+      }
+
+      return {
+        edit: createSourceEdit(node.start, node.end, options.to),
+        kind: 'edit',
+        note: `Renamed identifier "${options.from}" to "${options.to}".`,
+      };
+    },
+  });
+};