@ontrails/trails 0.2.0

package/src/regrade/plan-derivation.ts

@@ -0,0 +1,301 @@
+import {
+  createAstIdentifierRenameClass,
+  deriveFileRenameCandidates,
+  deriveVocabularyFormProposals,
+  runFileRenameRegrade,
+  runRegrade,
+} from '@ontrails/regrade';
+import type {
+  RegradeReport,
+  VocabularyPreserveInventoryEntry,
+  VocabularyRegradePlan,
+} from '@ontrails/regrade';
+
+import { isGeneratedRegradeArtifactPath } from './plan-artifact.js';
+import type {
+  RegradePlanArtifact,
+  RegradePlanDerivation,
+} from './plan-artifact.js';
+
+const provenanceForForm = (
+  source: RegradePlanDerivation['forms'][number]['source'],
+  fields: RegradePlanArtifact['provenance']['fields']
+): 'authored' | 'derived' => {
+  if (source === 'seed') {
+    return 'authored';
+  }
+  if (source === 'plan-override') {
+    return fields['overrides'] ?? 'derived';
+  }
+  if (source === 'plan-defer') {
+    return fields['deferForms'] ?? 'derived';
+  }
+  return 'derived';
+};
+
+const namespaceCensus = (
+  report: RegradeReport
+): RegradePlanDerivation['namespaces'] => {
+  const namespaces = new Map<
+    string,
+    { inScope: number; policyClassified: number }
+  >();
+  for (const occurrence of report.run?.ledger.occurrences ?? []) {
+    if (isGeneratedRegradeArtifactPath(occurrence.path)) {
+      continue;
+    }
+    const namespace = occurrence.path.split('/')[0] ?? occurrence.path;
+    const counts = namespaces.get(namespace) ?? {
+      inScope: 0,
+      policyClassified: 0,
+    };
+    if (occurrence.scopeTier === 'policy-classified') {
+      counts.policyClassified += 1;
+    } else {
+      counts.inScope += 1;
+    }
+    namespaces.set(namespace, counts);
+  }
+  return [...namespaces.entries()]
+    .map(([namespace, counts]) => ({
+      ...counts,
+      namespace,
+      provenance: 'derived' as const,
+    }))
+    .toSorted((left, right) => left.namespace.localeCompare(right.namespace));
+};
+
+const observedReviews = (
+  report: RegradeReport
+): RegradePlanDerivation['reviews'] => {
+  const reviews = new Map<string, RegradePlanDerivation['reviews'][number]>();
+  for (const occurrence of report.run?.ledger.occurrences ?? []) {
+    if (
+      isGeneratedRegradeArtifactPath(occurrence.path) ||
+      (occurrence.verdict !== 'deferred' &&
+        occurrence.disposition !== 'code-context-out-of-engine' &&
+        occurrence.disposition !== 'in-family-unresolved')
+    ) {
+      continue;
+    }
+    const key = `${occurrence.form}\0${occurrence.reason}`;
+    const current = reviews.get(key);
+    const evidence = {
+      column: occurrence.column,
+      line: occurrence.line,
+      path: occurrence.path,
+    };
+    reviews.set(key, {
+      evidence:
+        current === undefined ? [evidence] : [...current.evidence, evidence],
+      provenance: 'derived',
+      reason: occurrence.reason,
+      status: 'pending',
+      value: occurrence.form,
+    });
+  }
+  return [...reviews.values()]
+    .map((review) => ({
+      ...review,
+      evidence: review.evidence.toSorted((left, right) =>
+        left.path === right.path
+          ? (left.line ?? 0) - (right.line ?? 0)
+          : left.path.localeCompare(right.path)
+      ),
+    }))
+    .toSorted((left, right) => left.value.localeCompare(right.value));
+};
+
+const identifierReviews = (params: {
+  readonly plan: VocabularyRegradePlan;
+  readonly rootDir: string;
+}): RegradePlanDerivation['reviews'] => {
+  const { scope } = params.plan;
+  const sourceForms = [
+    ...new Map(
+      deriveVocabularyFormProposals(params.plan).map((form) => [
+        form.from,
+        form,
+      ])
+    ).values(),
+  ];
+  const collection = {
+    ...(scope?.exclude === undefined ? {} : { exclude: scope.exclude }),
+    extensions: scope?.extensions ?? ['.js', '.jsx', '.mjs', '.ts', '.tsx'],
+    ...(scope?.include === undefined ? {} : { include: scope.include }),
+  };
+  const entries: RegradeReport['entries'][number][] = [];
+  for (const form of sourceForms) {
+    const report = runRegrade({
+      classes: [
+        createAstIdentifierRenameClass({
+          from: form.from,
+          id: `derived-plan-identifiers:${form.from}->${form.to ?? params.plan.to}`,
+          match: 'identifier-segment',
+          reviewAllMatches: true,
+          to: form.to ?? params.plan.to,
+        }),
+      ],
+      collection,
+      root: params.rootDir,
+    });
+    if (report.isErr()) {
+      return [
+        {
+          evidence: [],
+          provenance: 'derived',
+          reason: `identifier-review-scan-failed: ${report.error.message}`,
+          status: 'pending',
+          value: form.from,
+        },
+      ];
+    }
+    entries.push(...(report.value?.entries ?? []));
+  }
+  return entries
+    .flatMap((entry) =>
+      (entry.reviewDetails ?? []).flatMap((detail) =>
+        detail.symbol === undefined
+          ? []
+          : [
+              {
+                evidence: [
+                  {
+                    ...(detail.span?.column === undefined
+                      ? {}
+                      : { column: detail.span.column }),
+                    ...(detail.span?.line === undefined
+                      ? {}
+                      : { line: detail.span.line }),
+                    path: entry.path,
+                  },
+                ],
+                provenance: 'derived' as const,
+                reason: detail.reason,
+                status: 'pending' as const,
+                value: detail.symbol,
+              },
+            ]
+      )
+    )
+    .toSorted((left, right) => left.value.localeCompare(right.value));
+};
+
+const mergeReviews = (
+  ...groups: readonly RegradePlanDerivation['reviews'][]
+): RegradePlanDerivation['reviews'] => {
+  const merged = new Map<string, RegradePlanDerivation['reviews'][number]>();
+  for (const review of groups.flat()) {
+    const key = `${review.value}\0${review.reason}`;
+    const current = merged.get(key);
+    merged.set(key, {
+      ...review,
+      evidence: [...(current?.evidence ?? []), ...review.evidence]
+        .filter(
+          (entry, index, evidence) =>
+            evidence.findIndex(
+              (candidate) =>
+                candidate.path === entry.path &&
+                candidate.line === entry.line &&
+                candidate.column === entry.column
+            ) === index
+        )
+        .toSorted((left, right) => left.path.localeCompare(right.path)),
+    });
+  }
+  return [...merged.values()].toSorted((left, right) =>
+    left.value === right.value
+      ? left.reason.localeCompare(right.reason)
+      : left.value.localeCompare(right.value)
+  );
+};
+
+const referenceClosure = (params: {
+  readonly candidates: ReturnType<typeof deriveFileRenameCandidates>;
+  readonly plan: VocabularyRegradePlan;
+  readonly rootDir: string;
+}): RegradePlanDerivation['referenceClosure'] => {
+  if (params.candidates.length === 0) {
+    return { entries: [], moves: [] };
+  }
+  const result = runFileRenameRegrade({
+    excludeGeneratedArtifacts: true,
+    renames: params.candidates,
+    root: params.rootDir,
+    ...(params.plan.scope === undefined ? {} : { scope: params.plan.scope }),
+  });
+  if (result.isErr()) {
+    return { entries: [], issue: result.error.message, moves: [] };
+  }
+  return {
+    entries: result.value.report.entries
+      .filter(
+        (
+          entry
+        ): entry is typeof entry & {
+          readonly outcome: 'needs-review' | 'rewrite';
+        } => entry.outcome === 'needs-review' || entry.outcome === 'rewrite'
+      )
+      .map((entry) => ({
+        outcome: entry.outcome,
+        path: entry.path,
+        provenance: 'derived' as const,
+        ...(entry.reason === undefined ? {} : { reason: entry.reason }),
+      }))
+      .toSorted((left, right) => left.path.localeCompare(right.path)),
+    moves: result.value.evidence.map(
+      ({ deferred, from, historical, preserved, rewritten, skipped, to }) => ({
+        deferred,
+        from,
+        historical,
+        preserved,
+        provenance: 'derived' as const,
+        rewritten,
+        skipped,
+        to,
+      })
+    ),
+  };
+};
+
+export const deriveRegradePlanDerivation = (params: {
+  readonly plan: VocabularyRegradePlan;
+  readonly preserveInventory: readonly VocabularyPreserveInventoryEntry[];
+  readonly provenance: RegradePlanArtifact['provenance'];
+  readonly report: RegradeReport;
+  readonly rootDir: string;
+}): RegradePlanDerivation => {
+  const candidates = deriveFileRenameCandidates({
+    plan: params.plan,
+    root: params.rootDir,
+  });
+  return {
+    fileRenames: candidates.map((candidate) => ({
+      ...candidate,
+      evidence: [...candidate.evidence],
+      provenance: 'derived' as const,
+      status: 'pending' as const,
+    })),
+    forms: deriveVocabularyFormProposals(params.plan).map((form) => ({
+      ...form,
+      provenance: provenanceForForm(form.source, params.provenance.fields),
+    })),
+    namespaces: namespaceCensus(params.report),
+    preserves: params.preserveInventory.map((entry) => ({
+      disposition: 'preserve-current-live-api' as const,
+      evidence: [...entry.evidence],
+      pattern: entry.pattern,
+      provenance: 'derived' as const,
+      ...(entry.reason === undefined ? {} : { reason: entry.reason }),
+    })),
+    referenceClosure: referenceClosure({
+      candidates,
+      plan: params.plan,
+      rootDir: params.rootDir,
+    }),
+    reviews: mergeReviews(
+      observedReviews(params.report),
+      identifierReviews({ plan: params.plan, rootDir: params.rootDir })
+    ),
+  };
+};

package/src/regrade/prepared-run.ts

@@ -0,0 +1,259 @@
+import { InternalError, Result, ValidationError } from '@ontrails/core';
+import type { Result as TrailsResult } from '@ontrails/core';
+import {
+  regradeReceiptContentHash,
+  regradeReceiptPlanContentHash,
+  regradeReceiptPlanSchema,
+} from '@ontrails/regrade';
+import type {
+  PreparedRegradeRunIdentity,
+  RegradeClass,
+} from '@ontrails/regrade';
+import { listGovernedVocabularyTransitions } from '@ontrails/warden';
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, extname, isAbsolute, join, relative, sep } from 'node:path';
+
+import { trailsPackageVersion } from '../versions.js';
+import { canonicalJsonStringify } from './plan-artifact.js';
+import type { RegradePlanArtifact } from './plan-artifact.js';
+
+const ignoredLockDirectories = new Set([
+  '.agents',
+  '.git',
+  '.turbo',
+  'dist',
+  'node_modules',
+]);
+
+const normalizePath = (path: string): string => path.split(sep).join('/');
+
+const compareCodeUnits = (left: string, right: string): number => {
+  if (left < right) {
+    return -1;
+  }
+  if (left > right) {
+    return 1;
+  }
+  return 0;
+};
+
+const loaderForModuleExtension = (
+  extension: string
+): 'js' | 'jsx' | 'ts' | 'tsx' => {
+  if (extension === '.tsx') {
+    return 'tsx';
+  }
+  if (extension === '.jsx') {
+    return 'jsx';
+  }
+  return ['.cts', '.mts', '.ts'].includes(extension) ? 'ts' : 'js';
+};
+
+const collectLockPaths = (rootDir: string): readonly string[] => {
+  const paths: string[] = [];
+  const visit = (directory: string): void => {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (!ignoredLockDirectories.has(entry.name)) {
+          visit(join(directory, entry.name));
+        }
+        continue;
+      }
+      if (entry.isFile() && entry.name === 'trails.lock') {
+        paths.push(join(directory, entry.name));
+      }
+    }
+  };
+  visit(rootDir);
+  return paths.toSorted(compareCodeUnits);
+};
+
+const lockStateHash = (
+  rootDir: string
+): TrailsResult<string, InternalError> => {
+  try {
+    const locks = collectLockPaths(rootDir).map((absolutePath) => ({
+      contentHash: createHash('sha256')
+        .update(readFileSync(absolutePath))
+        .digest('hex'),
+      path: normalizePath(relative(rootDir, absolutePath)),
+    }));
+    return Result.ok(regradeReceiptContentHash(locks));
+  } catch (error) {
+    return Result.err(
+      new InternalError('Failed to derive Regrade lock identity.', {
+        ...(error instanceof Error ? { cause: error } : {}),
+        context: { rootDir },
+      })
+    );
+  }
+};
+
+const projectRuleStateHash = (
+  rootDir: string
+): TrailsResult<string, InternalError> => {
+  try {
+    const root = realpathSync(rootDir);
+    const entryPaths: string[] = [];
+    const rulesFile = join(root, '.trails/rules.ts');
+    const rulesDirectory = join(root, '.trails/rules');
+    if (existsSync(rulesFile)) {
+      entryPaths.push(rulesFile);
+    }
+    if (existsSync(rulesDirectory)) {
+      for (const entry of readdirSync(rulesDirectory, {
+        withFileTypes: true,
+      })) {
+        if (
+          entry.isFile() &&
+          entry.name.endsWith('.ts') &&
+          !entry.name.endsWith('.test.ts') &&
+          !entry.name.startsWith('_')
+        ) {
+          entryPaths.push(join(rulesDirectory, entry.name));
+        }
+      }
+    }
+
+    const paths = new Set<string>();
+    const visitModule = (absolutePath: string): void => {
+      if (paths.has(absolutePath)) {
+        return;
+      }
+      paths.add(absolutePath);
+      const extension = extname(absolutePath);
+      if (
+        ![
+          '.cjs',
+          '.cts',
+          '.js',
+          '.jsx',
+          '.mjs',
+          '.mts',
+          '.ts',
+          '.tsx',
+        ].includes(extension)
+      ) {
+        return;
+      }
+      const imports = new Bun.Transpiler({
+        loader: loaderForModuleExtension(extension),
+      }).scanImports(readFileSync(absolutePath, 'utf8'));
+      for (const imported of imports) {
+        const resolved = Bun.resolveSync(imported.path, dirname(absolutePath));
+        const relativePath = relative(root, resolved);
+        if (
+          isAbsolute(resolved) &&
+          relativePath !== '..' &&
+          !relativePath.startsWith(`..${sep}`) &&
+          !relativePath.split(sep).includes('node_modules')
+        ) {
+          visitModule(resolved);
+        }
+      }
+    };
+    for (const entryPath of entryPaths) {
+      visitModule(entryPath);
+    }
+    return Result.ok(
+      regradeReceiptContentHash(
+        [...paths].toSorted(compareCodeUnits).map((absolutePath) => ({
+          contentHash: createHash('sha256')
+            .update(readFileSync(absolutePath))
+            .digest('hex'),
+          path: normalizePath(relative(rootDir, absolutePath)),
+        }))
+      )
+    );
+  } catch (error) {
+    return Result.err(
+      new InternalError('Failed to derive Regrade policy identity.', {
+        ...(error instanceof Error ? { cause: error } : {}),
+        context: { rootDir },
+      })
+    );
+  }
+};
+
+/**
+ * Build the command-local reuse identity from receipt-aligned facts.
+ *
+ * @example
+ * ```ts
+ * const identity = preparedRegradeRunIdentity({ artifact, rootDir: '.' });
+ * if (identity.isOk()) console.log(identity.value.planContentHash);
+ * ```
+ */
+export const preparedRegradeRunIdentity = (params: {
+  readonly artifact: RegradePlanArtifact;
+  readonly classIds?: readonly string[] | undefined;
+  readonly classes?: readonly RegradeClass[] | undefined;
+  readonly includeEntries: 'actionable' | 'all';
+  readonly rootDir: string;
+}): TrailsResult<PreparedRegradeRunIdentity, Error> => {
+  const parsedPlan = regradeReceiptPlanSchema.safeParse(params.artifact.plan);
+  if (!parsedPlan.success) {
+    return Result.err(
+      new InternalError('Failed to derive Regrade plan identity.', {
+        context: { issues: parsedPlan.error.issues },
+      })
+    );
+  }
+  const lockHash = lockStateHash(params.rootDir);
+  if (lockHash.isErr()) {
+    return lockHash;
+  }
+  const usesProjectRules = parsedPlan.data.kind === 'class';
+  const policyStateHash = usesProjectRules
+    ? projectRuleStateHash(params.rootDir)
+    : Result.ok(null);
+  if (policyStateHash.isErr()) {
+    return policyStateHash;
+  }
+  return Result.ok({
+    lockStateHash: lockHash.value,
+    planContentHash: regradeReceiptPlanContentHash({
+      plan: parsedPlan.data,
+      provenance: params.artifact.provenance,
+    }),
+    policyHash: regradeReceiptContentHash({
+      classIds: [...(params.classIds ?? [])].toSorted(),
+      classes: (params.classes ?? []).map((regradeClass) => ({
+        describe: regradeClass.describe,
+        id: regradeClass.id,
+        scanTargets: regradeClass.scanTargets ?? null,
+      })),
+      ...(policyStateHash.value === null
+        ? {}
+        : { projectRulesHash: policyStateHash.value }),
+      transitions: listGovernedVocabularyTransitions(),
+    }),
+    scopeHash: regradeReceiptContentHash({
+      includeEntries: params.includeEntries,
+      scope: params.artifact.plan.scope ?? null,
+    }),
+    toolVersion: trailsPackageVersion,
+  });
+};
+
+/** Reject an active plan that changed after its prepared evaluation. */
+export const validatePreparedRegradePlanArtifact = (params: {
+  readonly current: RegradePlanArtifact;
+  readonly currentPath: string;
+  readonly expected: RegradePlanArtifact;
+  readonly expectedPath: string;
+}): TrailsResult<void, ValidationError> => {
+  if (
+    params.currentPath !== params.expectedPath ||
+    canonicalJsonStringify(params.current) !==
+      canonicalJsonStringify(params.expected)
+  ) {
+    return Result.err(
+      new ValidationError('Regrade plan changed during apply preflight.', {
+        context: { plan: params.expected.path },
+      })
+    );
+  }
+  return Result.ok();
+};