@ontrails/regrade 0.2.0

package/src/index.ts

@@ -0,0 +1,170 @@
+// Root package surface for `@ontrails/regrade`.
+export {
+  literalRegradeTopo,
+  literalRegradeTrail,
+} from './literal-transform.js';
+export {
+  buildRegradeReport,
+  applyPreparedRegradeRun,
+  createTermRewriteClass,
+  createWardenTermRewriteClass,
+  loadWardenTermRewriteClasses,
+  prepareRegradeRun,
+  regradeReportOutput,
+  runRegrade,
+  selectRegradeClasses,
+  validatePreparedRegradeRun,
+  wardenTermRewriteClasses,
+} from './downstream/report.js';
+export {
+  deriveFileRenameCandidates,
+  runFileRenameRegrade,
+} from './downstream/file-renames.js';
+export { verifyDownstreamPackageSource } from './downstream/package-source.js';
+/**
+ * Validate the package-source expectation shared by verifier and operator inputs.
+ *
+ * @example
+ * ```ts
+ * regradePackageSourceExpectationSchema.parse({
+ *   kind: 'published',
+ *   name: '@ontrails/core',
+ *   version: '0.2.0',
+ * });
+ * ```
+ */
+export { regradePackageSourceExpectationSchema } from './downstream/package-source-manifest.js';
+export type {
+  RegradePackageSourceError,
+  RegradePackageSourceEvidence,
+  RegradePackageSourceExpectation,
+} from './downstream/package-source.js';
+export type {
+  FileRenameCandidate,
+  FileRenameRegradeRun,
+} from './downstream/file-renames.js';
+export {
+  cliAliasesExportRestructureClass,
+  createWardenExportRestructureClass,
+  exportRestructureClasses,
+  loadWardenRegradeClasses,
+  mcpTrailheadsExportRestructureClass,
+} from './downstream/export-restructure.js';
+export {
+  VOCABULARY_TRANSITION_RECORD_SCHEMA_VERSION,
+  buildVocabularyTransitionRecord,
+  deriveVocabularyFormProposals,
+  applyPreparedVocabularyRegradeRun,
+  prepareVocabularyRegradeRun,
+  readVocabularyTransitionRecord,
+  runVocabularyRegrade,
+  transitionRecordReportWithSummary,
+  vocabularyDispositionValues,
+  vocabularyRegradePlanSchema,
+  vocabularyRegradeRunOutput,
+  vocabularyTransitionRecordPath,
+  vocabularyTransitionRecordSchema,
+  writeVocabularyTransitionRecord,
+} from './downstream/vocabulary.js';
+export {
+  listVocabularyRegradePlansFromRegistry,
+  listVocabularyRegradeAuditPlansFromRegistry,
+  vocabularyRegradePlanFromTransition,
+  vocabularyRegradePlanForInput,
+  vocabularyRegradeTransitionForInput,
+} from './downstream/vocabulary-registry.js';
+export type {
+  RegradeApplySummary,
+  PreparedRegradeRun,
+  PreparedRegradeRunIdentity,
+  RegradeClass,
+  RegradeClassContext,
+  RegradeClassResult,
+  RegradeReport,
+  RegradeReportEntry,
+  RegradeReportEntrySelection,
+  RegradeReviewDetail,
+  RegradeReviewJudgment,
+  RegradeReviewSpan,
+  RegradeScanTargets,
+  RegradeSelection,
+  RegradeWardenClassSet,
+} from './downstream/report.js';
+export type {
+  RegradeScanDirectoryBucket,
+  RegradeScanExtensionBucket,
+  RegradeScanSummary,
+} from './downstream/scan-summary.js';
+export type {
+  VocabularyDisposition,
+  PreparedVocabularyRegradeRun,
+  VocabularyFileRename,
+  VocabularyFileRenameEvidence,
+  VocabularyFormProposal,
+  VocabularyOccurrence,
+  VocabularyOccurrenceSourceKind,
+  VocabularyPreserveInventoryEntry,
+  VocabularyPreserveRule,
+  VocabularyRegradePlan,
+  VocabularyRegradeScope,
+  VocabularyRegradeRun,
+  VocabularyScopePolicy,
+  VocabularyScopeTier,
+  VocabularyRunGate,
+  VocabularyRunLedger,
+  VocabularyRunReport,
+  VocabularyTransitionRecord,
+  VocabularyTransitionRecordEnvironment,
+  VocabularyTransitionRecordSummary,
+  VocabularyVerdict,
+} from './downstream/vocabulary.js';
+export {
+  createAstIdentifierRenameClass,
+  createAstRewriteClass,
+  createGovernedAstIdentifierRenameClasses,
+} from './downstream/ast-rewrite.js';
+export type {
+  AstIdentifierRenameClassOptions,
+  AstRewriteClassOptions,
+  AstRewriteContext,
+  AstRewriteMatch,
+  AstRewriteVisitResult,
+} from './downstream/ast-rewrite.js';
+
+/**
+ * Compact, canonical evidence for an applied Regrade run.
+ *
+ * @example
+ * ```ts
+ * const serialized = serializeRegradeHistoryReceipt(receipt);
+ * if (serialized.isErr()) throw serialized.error;
+ * ```
+ */
+export {
+  REGRADE_HISTORY_RECEIPT_SCHEMA_VERSION,
+  canonicalRegradeJson,
+  regradeClassifiedStateHash,
+  regradeFormJudgmentSchema,
+  regradeHistoryReceiptSchema,
+  regradeReceiptContentHash,
+  regradeReceiptPlanContentHash,
+  regradeReceiptPlanSchema,
+  resolveRegradeHistoryReceipt,
+  serializeRegradeHistoryReceipt,
+} from './history-receipt.js';
+/**
+ * Type the authored and resolved sides of compact Regrade history.
+ *
+ * @example
+ * ```ts
+ * const receipt: RegradeHistoryReceipt = parsed;
+ * ```
+ */
+export type {
+  RegradeFormJudgment,
+  RegradeHistoryReceipt,
+  RegradeReceiptPlan,
+  RegradeReceiptPlanProvenance,
+  ResolvedRegradeHistoryReceipt,
+  ResolvedRegradeHistoryReceiptRun,
+} from './history-receipt.js';

package/src/literal-transform.ts

@@ -0,0 +1,124 @@
+import { InternalError, Result, topo, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+export const regradeTransformInput = z.object({
+  source: z.string().describe('Source text to transform'),
+});
+
+export const regradeTransformOutput = z.object({
+  changed: z.boolean().describe('Whether the transform changed the source'),
+  nextSource: z.string().describe('Transformed source text'),
+  notes: z.array(z.string()).describe('Tracer notes for the transform run'),
+});
+
+const childInput = z.object({
+  source: z.string(),
+});
+
+/**
+ * Parent input schema with its raw-to-implementation transform attached.
+ *
+ * Naming the transformed schema lets examples and tests reference both its raw
+ * pre-transform input (`z.input`) and its post-transform implementation input
+ * (`z.infer`) without restating either shape by hand.
+ */
+const regradeTransformInputToChild = regradeTransformInput.transform(
+  ({ source }) => ({
+    child: { source },
+  })
+);
+
+/**
+ * Raw, pre-transform input accepted by {@link regradeTransformInputToChild}.
+ *
+ * Trail examples and `testExamples()` feed this shape through validation; the
+ * Zod transform then derives the implementation input.
+ */
+type RegradeTransformRawInput = z.input<typeof regradeTransformInputToChild>;
+
+/**
+ * Post-transform implementation input shape — the trail's inferred input type `I`.
+ *
+ * TRL-842: With a `.transform()` input schema, the trail's inferred input type
+ * `I` is the transform OUTPUT (the implementation input), while examples and
+ * `testExamples()` validate the raw pre-transform INPUT. Those two shapes are
+ * disjoint, so an authored example must carry raw input typed as the
+ * post-transform shape. A framework-level fix would thread a separate
+ * `z.input<>` raw-input type parameter through `TrailSpec`, `Trail`, and every
+ * `trail()` overload — a core-wide generics change beyond this tracer. Until
+ * then the divergence is captured by the two named types here and exercised by
+ * the runtime validation test in `__tests__/literal-transform.test.ts`.
+ */
+type RegradeTransformImplementationInput = z.infer<
+  typeof regradeTransformInputToChild
+>;
+
+/**
+ * Raw example input, statically checked as valid pre-transform input. If the
+ * input schema changes so this literal is no longer valid raw input, source
+ * typecheck fails here instead of silently relying on the cast below.
+ */
+const codeStringExampleInput: RegradeTransformRawInput = {
+  source: 'export const answer = 41;',
+};
+
+export const normalizeExportConstTrail = trail(
+  'regrade.literal.normalize-export-const',
+  {
+    implementation: (input) => {
+      const nextSource = input.source.replaceAll('export const', 'export let');
+      return Result.ok({
+        changed: nextSource !== input.source,
+        nextSource,
+        notes:
+          nextSource === input.source
+            ? ['No export const declaration found.']
+            : ['Rewrote export const declarations to export let.'],
+      });
+    },
+    input: childInput,
+    output: regradeTransformOutput,
+    visibility: 'internal',
+  }
+);
+
+export const literalRegradeTrail = trail('regrade.literal.run', {
+  composes: [normalizeExportConstTrail],
+  examples: [
+    {
+      expected: {
+        changed: true,
+        nextSource: 'export let answer = 41;',
+        notes: ['Rewrote export const declarations to export let.'],
+      },
+      // TRL-842: author the raw pre-transform value (validated as
+      // RegradeTransformRawInput) and widen through `unknown` to the trail's
+      // inferred post-transform input type. The runtime still parses raw input;
+      // see RegradeTransformImplementationInput for why the two shapes diverge.
+      input:
+        codeStringExampleInput as unknown as RegradeTransformImplementationInput,
+      name: 'code-string fixture',
+    },
+  ],
+  implementation: async (input, ctx) => {
+    if (!ctx.compose) {
+      return Result.err(
+        new InternalError(
+          'Literal Regrade tracer requires compose-capable execution.'
+        )
+      );
+    }
+    const implementationInput = input as RegradeTransformImplementationInput;
+    return await ctx.compose(
+      normalizeExportConstTrail,
+      implementationInput.child
+    );
+  },
+  input: regradeTransformInputToChild,
+  output: regradeTransformOutput,
+});
+
+export const literalRegradeTopo = topo('regrade-literal', {
+  literalRegradeTrail,
+  normalizeExportConstTrail,
+});