@ontrails/trails 1.0.0-beta.30 → 1.0.0-beta.32

package/src/trails/regrade.ts

@@ -2,19 +2,41 @@
  * `regrade` trail -- Run downstream migration checks and safe rewrites.
  */
 
-import { NotFoundError, Result, trail, validateOutput } from '@ontrails/core';
-import type { Result as TrailsResult } from '@ontrails/core';
 import {
+  InternalError,
+  NotFoundError,
+  Result,
+  ValidationError,
+  pathScopeSchema,
+  trail,
+  validateOutput,
+} from '@ontrails/core';
+import type { PathScope, Result as TrailsResult } from '@ontrails/core';
+import {
+  loadWardenTermRewriteClasses,
   regradeReportOutput,
   runRegrade,
-  wardenTermRewriteClasses,
+  runVocabularyRegrade,
 } from '@ontrails/regrade';
-import type { RegradeReport } from '@ontrails/regrade';
+import type { RegradeReport, VocabularyRegradePlan } from '@ontrails/regrade';
 import { z } from 'zod';
 
+import { loadRegradeConfig } from '../regrade/config.js';
 import { resolveTrailRootDir } from './root-dir.js';
 
-const regradeInputSchema = z.object({
+const regradePathScopeInputSchema = pathScopeSchema.extend({
+  exclude: pathScopeSchema.shape.exclude.describe(
+    'Root-relative path globs to exclude during Regrade collection'
+  ),
+  extensions: pathScopeSchema.shape.extensions.describe(
+    'Source file extensions to scan during Regrade collection'
+  ),
+  include: pathScopeSchema.shape.include.describe(
+    'Root-relative path patterns to include in vocabulary regrade mode'
+  ),
+});
+
+const regradeInputSchema = regradePathScopeInputSchema.extend({
   apply: z
     .boolean()
     .default(false)
@@ -23,19 +45,217 @@ const regradeInputSchema = z.object({
     .array(z.string())
     .optional()
     .describe('Regrade class ids to run (defaults to all built-in classes)'),
+  configPath: z
+    .string()
+    .optional()
+    .describe('Path to a Trails config file with regrade defaults'),
+  from: z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Source vocabulary term for a vocabulary regrade'),
+  includeEntries: z
+    .enum(['actionable', 'all'])
+    .default('actionable')
+    .describe(
+      'Report entry detail to include; counts always cover the full run'
+    ),
+  intent: z
+    .string()
+    .optional()
+    .describe('Human-authored migration intent for a vocabulary regrade'),
+  overrides: z
+    .record(z.string().min(1), z.string().min(1))
+    .optional()
+    .describe('Explicit source-form to target-form mappings'),
+  preserve: z
+    .array(z.string().min(1))
+    .optional()
+    .describe(
+      'Regex or literal contexts to preserve during a vocabulary regrade'
+    ),
   rootDir: z.string().optional().describe('Workspace root directory'),
+  to: z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Target vocabulary term for a vocabulary regrade'),
 });
 
+const hasVocabularyInput = (input: z.output<typeof regradeInputSchema>) =>
+  input.from !== undefined ||
+  input.include !== undefined ||
+  input.intent !== undefined ||
+  input.overrides !== undefined ||
+  input.preserve !== undefined ||
+  input.to !== undefined;
+
+const classModeCollection = (
+  input: z.output<typeof regradeInputSchema>,
+  configScope?: RegradeConfigScope | undefined
+):
+  | {
+      readonly exclude?: readonly string[];
+      readonly extensions?: readonly string[];
+    }
+  | undefined => {
+  if (
+    configScope?.exclude === undefined &&
+    configScope?.extensions === undefined &&
+    input.exclude === undefined &&
+    input.extensions === undefined
+  ) {
+    return undefined;
+  }
+
+  return {
+    ...(configScope?.exclude === undefined
+      ? {}
+      : { exclude: configScope.exclude }),
+    ...(configScope?.extensions === undefined
+      ? {}
+      : { extensions: configScope.extensions }),
+    ...(input.exclude === undefined ? {} : { exclude: input.exclude }),
+    ...(input.extensions === undefined ? {} : { extensions: input.extensions }),
+  };
+};
+
+interface RegradeConfigScope {
+  readonly exclude?: PathScope['exclude'] | undefined;
+  readonly extensions?: PathScope['extensions'] | undefined;
+  readonly include?: PathScope['include'] | undefined;
+}
+
+const vocabularyScopeFromConfig = (
+  scope: RegradeConfigScope | undefined
+): VocabularyRegradePlan['scope'] | undefined =>
+  scope === undefined
+    ? undefined
+    : {
+        ...(scope.exclude === undefined ? {} : { exclude: scope.exclude }),
+        ...(scope.extensions === undefined
+          ? {}
+          : { extensions: scope.extensions }),
+        ...(scope.include === undefined ? {} : { include: scope.include }),
+      };
+
+const buildVocabularyPlan = (
+  input: z.output<typeof regradeInputSchema>,
+  configScope?: VocabularyRegradePlan['scope']
+): TrailsResult<VocabularyRegradePlan, ValidationError> => {
+  if (input.from === undefined || input.to === undefined) {
+    return Result.err(
+      new ValidationError('A vocabulary regrade requires both `from` and `to`.')
+    );
+  }
+  if (input.classIds !== undefined) {
+    return Result.err(
+      new ValidationError(
+        '`classIds` selects class-mode Regrade and cannot be combined with vocabulary-regrade `from`/`to`.'
+      )
+    );
+  }
+
+  return Result.ok({
+    from: input.from,
+    id: `vocabulary:${input.from}->${input.to}`,
+    kind: 'vocabulary',
+    ...(input.intent === undefined ? {} : { intent: input.intent }),
+    ...(input.overrides === undefined ? {} : { overrides: input.overrides }),
+    ...(input.preserve === undefined
+      ? {}
+      : {
+          preserve: input.preserve.map((pattern) => ({
+            pattern,
+            reason: 'preserved-by-operator-input',
+          })),
+        }),
+    scope: {
+      ...configScope,
+      ...(input.exclude === undefined ? {} : { exclude: input.exclude }),
+      ...(input.extensions === undefined
+        ? {}
+        : { extensions: input.extensions }),
+      ...(input.include === undefined ? {} : { include: input.include }),
+    },
+    to: input.to,
+  });
+};
+
 export const regradeTrail = trail('regrade', {
-  blaze: (input, ctx) => {
+  args: ['from', 'to'],
+  blaze: async (input, ctx) => {
     const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
     if (rootDirResult.isErr()) {
       return rootDirResult;
     }
 
+    const configResult = await loadRegradeConfig({
+      ...(input.configPath === undefined
+        ? {}
+        : { configPath: input.configPath }),
+      env: ctx.env,
+      rootDir: rootDirResult.value,
+    });
+    if (configResult.isErr()) {
+      return configResult;
+    }
+    const configScope = configResult.value.config?.scope;
+
+    if (hasVocabularyInput(input)) {
+      const planResult = buildVocabularyPlan(
+        input,
+        vocabularyScopeFromConfig(configScope)
+      );
+      if (planResult.isErr()) {
+        return planResult;
+      }
+      const reportResult: TrailsResult<RegradeReport | null, Error> =
+        runVocabularyRegrade({
+          apply: input.apply,
+          includeEntries: input.includeEntries,
+          plan: planResult.value,
+          root: rootDirResult.value,
+        });
+      if (reportResult.isErr()) {
+        return reportResult;
+      }
+      const report = reportResult.value;
+      if (report === null) {
+        return Result.err(
+          new NotFoundError(
+            `Regrade root "${rootDirResult.value}" could not be read as a directory.`
+          )
+        );
+      }
+      const validated: TrailsResult<
+        z.output<typeof regradeReportOutput>,
+        Error
+      > = validateOutput(regradeReportOutput, report);
+      if (validated.isErr()) {
+        return validated;
+      }
+      return Result.ok(validated.value);
+    }
+
+    const classSet = await loadWardenTermRewriteClasses(rootDirResult.value);
+    if (classSet.diagnostics.length > 0) {
+      return Result.err(
+        new InternalError('Failed to load Regrade project Warden rules.', {
+          context: {
+            diagnostics: classSet.diagnostics,
+            rootDir: rootDirResult.value,
+          },
+        })
+      );
+    }
+
+    const collection = classModeCollection(input, configScope);
     const reportResult: TrailsResult<RegradeReport | null, Error> = runRegrade({
       apply: input.apply,
-      classes: wardenTermRewriteClasses,
+      classes: classSet.classes,
+      ...(collection === undefined ? {} : { collection }),
+      includeEntries: input.includeEntries,
       root: rootDirResult.value,
       ...(input.classIds === undefined
         ? {}

package/src/trails/revise.ts

@@ -44,7 +44,7 @@ export const reviseTrail = trail('revise', {
   }),
   intent: 'write',
   output: z.object({
-    file: z.string(),
+    filePath: z.string(),
     trailId: z.string(),
     updated: z.boolean(),
     warnings: z.array(z.string()).optional(),

package/src/trails/survey.ts

@@ -30,12 +30,12 @@ import { writeIsolatedExampleJsonFile } from '../local-state-io.js';
 
 import { withFreshAppLease, withOperatorRootDir } from './operator-context.js';
 import {
-  buildCurrentTopoBrief,
-  buildCurrentTopoList,
-  buildCurrentTopoMatches,
-  buildCurrentTrailDetail,
-  buildCurrentResourceDetail,
-  buildCurrentSignalDetail,
+  deriveCurrentTopoBrief,
+  deriveCurrentTopoList,
+  deriveCurrentTopoMatches,
+  deriveCurrentTrailDetail,
+  deriveCurrentResourceDetail,
+  deriveCurrentSignalDetail,
   readSurfaceLayerNamesFromContext,
 } from './topo-read-support.js';
 import {
@@ -511,7 +511,7 @@ const buildSurveyLookup = (
     | undefined,
   surfaceLayerNames?: Partial<SurfaceLayerNames> | undefined
 ): Result<object, Error> => {
-  const matches = buildCurrentTopoMatches(app, entityId, {
+  const matches = deriveCurrentTopoMatches(app, entityId, {
     cliAliases,
     rootDir,
     surfaceLayerNames,
@@ -528,7 +528,7 @@ const buildSurveyTrailDetail = (
     | undefined,
   surfaceLayerNames?: Partial<SurfaceLayerNames> | undefined
 ): Result<object, Error> => {
-  const detail = buildCurrentTrailDetail(app, id, {
+  const detail = deriveCurrentTrailDetail(app, id, {
     cliAliases,
     rootDir,
     surfaceLayerNames,
@@ -543,7 +543,7 @@ const buildSurveyResourceDetail = (
   id: string,
   rootDir: string
 ): Result<object, Error> => {
-  const detail = buildCurrentResourceDetail(app, id, { rootDir });
+  const detail = deriveCurrentResourceDetail(app, id, { rootDir });
   return detail === undefined
     ? Result.err(new NotFoundError(`Resource not found: ${id}`))
     : Result.ok(detail);
@@ -554,7 +554,7 @@ const buildSurveySignalDetail = (
   id: string,
   rootDir: string
 ): Result<object, Error> => {
-  const detail = buildCurrentSignalDetail(app, id, { rootDir });
+  const detail = deriveCurrentSignalDetail(app, id, { rootDir });
   return detail === undefined
     ? Result.err(new NotFoundError(`Signal not found: ${id}`))
     : Result.ok(detail);
@@ -600,7 +600,7 @@ const surveyHandlers: Record<SurveyMode, SurveyHandler> = {
           surfaceLayerNames
         ),
   overview: (app, _input, rootDir) =>
-    Result.ok(buildCurrentTopoList(app, { rootDir })),
+    Result.ok(deriveCurrentTopoList(app, { rootDir })),
 };
 
 const envelopeSurveyValue = (
@@ -824,7 +824,7 @@ export const surveyTrail = trail('survey', {
 export const surveyBriefTrail = trail('survey.brief', {
   blaze: async (input, ctx) =>
     withResolvedSurveyApp(input, ctx.cwd, (app, rootDir) =>
-      Result.ok(buildCurrentTopoBrief(app, { rootDir }))
+      Result.ok(deriveCurrentTopoBrief(app, { rootDir }))
     ),
   description: 'Summarize topo capabilities',
   examples: [