@ontrails/warden 1.0.0-beta.45 → 1.0.0-beta.46

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @ontrails/warden
 
+## 1.0.0-beta.46
+
+### Minor Changes
+
+- [`fb0ba0a`](https://github.com/outfitter-dev/trails/commit/fb0ba0ab706bbdce470123e9a6fb2ef9f1822806): Convert the eight committed governed Regrade histories to canonical v3 receipts and remove the temporary schema-v2 compatibility path after migration.
+- [`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
+
+- [`54d259b`](https://github.com/outfitter-dev/trails/commit/54d259be81fb6c41d85be48a6cb2100c746a7126): Expose parser-native comment spans from `parseWithDiagnostics` so source-aware
+  tooling can distinguish exact JavaScript and TypeScript comment trivia without
+  reimplementing a lexer.
+
+  Use the shared spans in Warden's public-example rule while keeping leading
+  comment ownership fail-closed across JavaScript line terminators.
+
+- [`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
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/warden",
-  "version": "1.0.0-beta.45",
+  "version": "1.0.0-beta.46",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/outfitter-dev/trails.git",
@@ -32,20 +32,20 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/adapter-kit": "^1.0.0-beta.45",
-    "@ontrails/cli": "^1.0.0-beta.45",
-    "@ontrails/config": "^1.0.0-beta.45",
-    "@ontrails/permits": "^1.0.0-beta.45",
-    "@ontrails/source": "^1.0.0-beta.45",
-    "@ontrails/store": "^1.0.0-beta.45",
+    "@ontrails/adapter-kit": "^1.0.0-beta.46",
+    "@ontrails/cli": "^1.0.0-beta.46",
+    "@ontrails/config": "^1.0.0-beta.46",
+    "@ontrails/permits": "^1.0.0-beta.46",
+    "@ontrails/source": "^1.0.0-beta.46",
+    "@ontrails/store": "^1.0.0-beta.46",
     "oxc-resolver": "11.19.1",
     "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@ontrails/testing": "^1.0.0-beta.45"
+    "@ontrails/testing": "^1.0.0-beta.46"
   },
   "peerDependencies": {
-    "@ontrails/core": "^1.0.0-beta.45",
-    "@ontrails/topography": "^1.0.0-beta.45"
+    "@ontrails/core": "^1.0.0-beta.46",
+    "@ontrails/topography": "^1.0.0-beta.46"
   }
 }

package/src/index.ts

@@ -11,7 +11,7 @@
 export type {
   BuiltinWardenRuleName,
   GovernedVocabularyHistoryEvidence,
-  GovernedVocabularyHistoryFormObservation,
+  GovernedVocabularyHistoryFormJudgment,
   GovernedVocabularyHistoryIssue,
   ProjectAwareWardenRule,
   ProjectContext,

package/src/regrade-history.ts

@@ -1,345 +1,16 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join, relative } from 'node:path';
-import { createHash } from 'node:crypto';
-import { z } from 'zod';
 
 import {
   getGovernedVocabularyTransition,
-  governedVocabularyHistoryProvenanceSchema,
   listGovernedVocabularyTransitions,
 } from './rules/retired-vocabulary.js';
+import { resolveReceiptForWarden } from './regrade-receipt.js';
 import type {
   GovernedVocabularyHistoryEvidence,
   GovernedVocabularyHistoryIssue,
 } from './rules/types.js';
 
-const planBodySchema = z.discriminatedUnion('kind', [
-  z
-    .object({
-      caseSensitive: z.boolean().optional(),
-      from: z.string().min(1),
-      id: z.string().optional(),
-      kind: z.literal('vocabulary'),
-      to: z.string().min(1),
-    })
-    .passthrough(),
-  z
-    .object({
-      classIds: z.array(z.string().min(1)).min(1),
-      id: z.string().min(1),
-      kind: z.literal('class'),
-    })
-    .passthrough(),
-]);
-
-const planArtifactSchema = z
-  .object({
-    derivation: z.unknown().optional(),
-    expansion: z.unknown().optional(),
-    kind: z.literal('regrade-plan'),
-    path: z.string().min(1),
-    plan: planBodySchema,
-    provenance: z.object({
-      fields: z.record(z.string(), z.enum(['authored', 'derived'])),
-    }),
-    schemaVersion: z.literal(1),
-    sourceHash: z.string().min(1),
-    transitionId: z.string().min(1).optional(),
-  })
-  .strict();
-
-const historyRunSchema = z
-  .object({
-    completionReport: z.unknown().optional(),
-    completionReportHash: z.string().optional(),
-    lockHashAtRun: z.string().min(1),
-    plan: planArtifactSchema,
-    planContentHash: z.string().min(1),
-    provenance: governedVocabularyHistoryProvenanceSchema.optional(),
-    report: z.unknown(),
-  })
-  .strict();
-
-const historyArtifactSchema = z
-  .object({
-    id: z.string().min(1),
-    kind: z.literal('regrade-history'),
-    path: z.string().min(1),
-    runs: z.array(historyRunSchema).min(1),
-    schemaVersion: z.literal(2),
-  })
-  .strict();
-
-const reportEntrySchema = z
-  .object({
-    classId: z.string().optional(),
-    notes: z.array(z.string()).optional(),
-    outcome: z.enum(['needs-review', 'no-op', 'rewrite', 'skip']),
-    path: z.string(),
-    reason: z.string().optional(),
-    reviewDetails: z.unknown().optional(),
-  })
-  .passthrough();
-
-const vocabularyDispositionSchema = z.enum([
-  'code-context-out-of-engine',
-  'docs-only',
-  'explicit-preserve',
-  'forward-pointer',
-  'historical-by-policy',
-  'ignored-by-scope',
-  'in-family-modified',
-  'in-family-unresolved',
-  'out-of-family',
-  'preserve-current-live-api',
-]);
-
-const historyOccurrenceSchema = z
-  .object({
-    disposition: vocabularyDispositionSchema.optional(),
-    form: z.string(),
-    line: z.number().int().positive().optional(),
-    path: z.string(),
-    reason: z.string().optional(),
-    scopeTier: z.string().nullish(),
-    verdict: z.enum(['applied', 'deferred', 'modified', 'skipped']).optional(),
-  })
-  .passthrough()
-  .superRefine((occurrence, ctx) => {
-    const modernOccurrence =
-      occurrence.disposition !== undefined &&
-      occurrence.line !== undefined &&
-      occurrence.reason !== undefined &&
-      occurrence.verdict !== undefined;
-    if (
-      modernOccurrence &&
-      occurrence.scopeTier !== undefined &&
-      occurrence.scopeTier !== null &&
-      occurrence.scopeTier !== 'in-scope' &&
-      occurrence.scopeTier !== 'policy-classified'
-    ) {
-      ctx.addIssue({
-        code: 'custom',
-        message: 'Modern Regrade occurrences use a recognized scope tier.',
-        path: ['scopeTier'],
-      });
-    }
-  });
-
-const governedObservationSchema = historyOccurrenceSchema.safeExtend({
-  disposition: vocabularyDispositionSchema,
-  line: z.number().int().positive(),
-  reason: z.string(),
-  scopeTier: z.enum(['in-scope', 'policy-classified']).nullish(),
-  verdict: z.enum(['applied', 'deferred', 'modified', 'skipped']),
-});
-
-const reportSchema = z
-  .object({
-    apply: z.object({ applied: z.number() }).passthrough().optional(),
-    entries: z.array(reportEntrySchema),
-    matched: z.number(),
-    review: z.number(),
-    rewritten: z.number(),
-    root: z.string(),
-    run: z
-      .object({
-        ledger: z
-          .object({
-            cycle: z.unknown(),
-            forms: z.record(z.string(), z.unknown()),
-            occurrences: z.array(historyOccurrenceSchema),
-          })
-          .passthrough(),
-        report: z
-          .object({
-            fileRenames: z
-              .array(
-                z
-                  .object({
-                    deferred: z.number(),
-                    from: z.string(),
-                    historical: z.number().optional(),
-                    preserved: z.number().optional(),
-                    rewritten: z.number(),
-                    skipped: z.number().optional(),
-                    to: z.string(),
-                  })
-                  .passthrough()
-              )
-              .optional(),
-          })
-          .passthrough(),
-      })
-      .passthrough()
-      .optional(),
-    scan: z.object({
-      byDirectory: z.array(z.unknown()),
-      byExtension: z.array(z.unknown()),
-      files: z.object({
-        matched: z.number(),
-        scanned: z.number(),
-        skipped: z.number(),
-      }),
-      skippedByReason: z.record(z.string(), z.number()),
-    }),
-    scanned: z.number(),
-    selectedClassIds: z.array(z.string()),
-    skipped: z.number(),
-    skipsByReason: z.record(z.string(), z.number()),
-    unknownClassIds: z.array(z.string()),
-  })
-  .passthrough();
-
-const governedHistoryRunSchema = historyRunSchema.extend({
-  completionReport: reportSchema,
-  completionReportHash: z.string().regex(/^[0-9a-f]{64}$/),
-  lockHashAtRun: z.string().regex(/^[0-9a-f]{64}$/),
-  planContentHash: z.string().regex(/^[0-9a-f]{64}$/),
-  report: reportSchema,
-});
-
-type GovernedHistoryRun = z.infer<typeof governedHistoryRunSchema>;
-type HistoryRun = z.infer<typeof historyRunSchema>;
-
-const isPlainObject = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null && !Array.isArray(value);
-
-const canonicalizeJsonValue = (value: unknown): unknown => {
-  if (Array.isArray(value)) {
-    return value.map(canonicalizeJsonValue);
-  }
-  if (isPlainObject(value)) {
-    return Object.fromEntries(
-      Object.keys(value)
-        .toSorted()
-        .map((key) => [key, canonicalizeJsonValue(value[key])])
-    );
-  }
-  return value;
-};
-
-const hash = (value: string): string =>
-  createHash('sha256').update(value).digest('hex');
-
-const isGeneratedRegradeArtifact = (path: string): boolean =>
-  /(?:^|\/)\.trails\/regrade\/.+\.json$/u.test(path);
-
-const sourceHashFacts = (
-  report: z.infer<typeof reportSchema>,
-  policyMode: 'current' | 'legacy' = 'current',
-  fileEvidenceMode: 'current' | 'legacy' = 'current'
-): unknown => {
-  const ledger = report.run?.ledger;
-  const occurrences = ledger?.occurrences.filter(
-    (occurrence) =>
-      occurrence.scopeTier !== 'policy-classified' ||
-      (policyMode === 'current' && !isGeneratedRegradeArtifact(occurrence.path))
-  );
-  const forms = new Set(occurrences?.map((occurrence) => occurrence.form));
-  return {
-    entries: report.entries
-      .filter(
-        (entry) =>
-          entry.outcome === 'rewrite' || entry.outcome === 'needs-review'
-      )
-      .map(({ classId, notes, outcome, path, reason, reviewDetails }) => ({
-        ...(classId === undefined ? {} : { classId }),
-        ...(notes === undefined ? {} : { notes }),
-        outcome,
-        path,
-        ...(reason === undefined ? {} : { reason }),
-        ...(reviewDetails === undefined ? {} : { reviewDetails }),
-      })),
-    fileRenames: report.run?.report.fileRenames?.map((rename) => ({
-      deferred: rename.deferred,
-      from: rename.from,
-      ...(fileEvidenceMode === 'current'
-        ? {
-            historical: rename.historical ?? 0,
-            preserved: rename.preserved ?? 0,
-          }
-        : {}),
-      rewritten: rename.rewritten,
-      ...(fileEvidenceMode === 'current'
-        ? { skipped: rename.skipped ?? 0 }
-        : {}),
-      to: rename.to,
-    })),
-    ledger:
-      ledger === undefined || occurrences === undefined || forms === undefined
-        ? undefined
-        : {
-            cycle: ledger.cycle,
-            forms: Object.fromEntries(
-              Object.entries(ledger.forms).filter(([form]) => forms.has(form))
-            ),
-            occurrences,
-          },
-    selectedClassIds: report.selectedClassIds,
-  };
-};
-
-const sourceHashes = (report: z.infer<typeof reportSchema>): Set<string> => {
-  const facts = [
-    sourceHashFacts(report),
-    sourceHashFacts(report, 'current', 'legacy'),
-    sourceHashFacts(report, 'legacy'),
-    sourceHashFacts(report, 'legacy', 'legacy'),
-  ];
-  return new Set(
-    facts.flatMap((value) => [
-      hash(JSON.stringify(canonicalizeJsonValue(value))),
-      hash(JSON.stringify(value)),
-    ])
-  );
-};
-
-interface RawGovernedHistoryRun {
-  readonly completionReport?: z.infer<typeof reportSchema>;
-  readonly report: z.infer<typeof reportSchema>;
-}
-
-const rawEvidenceReports = (
-  run: GovernedHistoryRun,
-  rawRun: RawGovernedHistoryRun | undefined
-): {
-  readonly completionReport: z.infer<typeof reportSchema>;
-  readonly report: z.infer<typeof reportSchema>;
-} => ({
-  completionReport:
-    rawRun?.completionReport ?? rawRun?.report ?? run.completionReport,
-  report: rawRun?.report ?? run.report,
-});
-
-const validatesDeterministicEvidence = (
-  run: GovernedHistoryRun,
-  rawRun: RawGovernedHistoryRun | undefined,
-  transitionId: string
-): boolean => {
-  const { provenance } = run;
-  const { completionReport, report } = rawEvidenceReports(run, rawRun);
-  const provenanceValid =
-    provenance === undefined ||
-    (provenance.disposition ===
-      (run.report.review > 0 ? 'review-follow-up' : 'applied-clean') &&
-      provenance.kind === 'governed-vocabulary' &&
-      provenance.planContentHash === run.planContentHash &&
-      provenance.reviewPending === run.report.review &&
-      provenance.safeApplied ===
-        (run.report.apply?.applied ?? run.report.rewritten) &&
-      sourceHashes(completionReport).has(provenance.sourceHashAfter) &&
-      sourceHashes(report).has(provenance.sourceHashBefore) &&
-      provenance.transitionId === transitionId);
-  return (
-    hash(JSON.stringify(canonicalizeJsonValue(run.plan.plan))) ===
-      run.planContentHash &&
-    sourceHashes(report).has(run.lockHashAtRun) &&
-    sourceHashes(completionReport).has(run.completionReportHash) &&
-    provenanceValid
-  );
-};
-
 export interface GovernedVocabularyHistoryIndex {
   readonly byTransitionId: ReadonlyMap<
     string,
@@ -350,50 +21,6 @@ export interface GovernedVocabularyHistoryIndex {
 
 const normalizePath = (value: string): string => value.replaceAll('\\', '/');
 
-const latestRunFacts = (
-  run: HistoryRun | undefined
-): Pick<
-  GovernedVocabularyHistoryEvidence,
-  'caseSensitive' | 'latestFormObservations'
-> => {
-  if (run === undefined || run.plan.plan.kind !== 'vocabulary') {
-    return { caseSensitive: false, latestFormObservations: [] };
-  }
-  const report = reportSchema.safeParse(run.completionReport ?? run.report);
-  if (!report.success) {
-    return {
-      caseSensitive: run.plan.plan.caseSensitive === true,
-      latestFormObservations: [],
-    };
-  }
-  return {
-    caseSensitive: run.plan.plan.caseSensitive === true,
-    latestFormObservations: (report.data.run?.ledger.occurrences ?? []).flatMap(
-      (occurrence) => {
-        const observation = governedObservationSchema.safeParse(occurrence);
-        if (!observation.success) {
-          return [];
-        }
-        const { disposition, form, line, path, reason, scopeTier, verdict } =
-          observation.data;
-        return [
-          {
-            disposition,
-            form,
-            line,
-            path,
-            reason,
-            ...(scopeTier === undefined || scopeTier === null
-              ? {}
-              : { scopeTier }),
-            verdict,
-          },
-        ];
-      }
-    ),
-  };
-};
-
 type HistoryFileResult =
   | {
       readonly kind: 'evidence';
@@ -415,17 +42,23 @@ const historyIssue = (
   },
 });
 
-const governedTransitionForRun = (run: z.infer<typeof historyRunSchema>) => {
-  const { plan } = run.plan;
+type GovernedReceiptPlan =
+  | { readonly kind: 'class' }
+  | {
+      readonly from: string;
+      readonly id?: string | undefined;
+      readonly kind: 'vocabulary';
+      readonly to: string;
+    };
+
+const governedTransitionForPlan = (
+  plan: GovernedReceiptPlan,
+  transitionIds: readonly (string | undefined)[] = []
+) => {
   if (plan.kind !== 'vocabulary') {
     return;
   }
-  const transitionIds = [
-    plan.id,
-    run.provenance?.transitionId,
-    run.plan.transitionId,
-  ];
-  for (const transitionId of transitionIds) {
+  for (const transitionId of [plan.id, ...transitionIds]) {
     if (transitionId === undefined) {
       continue;
     }
@@ -443,50 +76,43 @@ const governedTransitionForRun = (run: z.infer<typeof historyRunSchema>) => {
   );
 };
 
-const loadHistoryFile = (rootDir: string, name: string): HistoryFileResult => {
-  const absolutePath = join(rootDir, '.trails', 'regrade', 'history', name);
-  const observedPath = normalizePath(relative(rootDir, absolutePath));
-  let json: unknown;
-  try {
-    json = JSON.parse(readFileSync(absolutePath, 'utf8'));
-  } catch {
-    return historyIssue(
-      observedPath,
-      'Committed Regrade history is not valid JSON.'
-    );
-  }
-  const parsed = historyArtifactSchema.safeParse(json);
-  if (!parsed.success) {
+const loadReceiptHistoryFile = (
+  json: unknown,
+  observedPath: string
+): HistoryFileResult => {
+  const resolved = resolveReceiptForWarden(json);
+  if (resolved.value === undefined) {
     return historyIssue(
       observedPath,
-      'Committed Regrade history has an invalid evidence shape.'
+      `Committed Regrade receipt has invalid deterministic evidence (${resolved.error ?? 'unknown error'}).`
     );
   }
-  if (normalizePath(parsed.data.path) !== observedPath) {
+  const { artifact, runs } = resolved.value;
+  if (normalizePath(artifact.path) !== observedPath) {
     return historyIssue(
       observedPath,
       'Committed Regrade history path does not match its observed file.'
     );
   }
-
-  const latestRun = parsed.data.runs.at(-1);
+  const latest = runs.at(-1);
   const transition =
-    latestRun === undefined ? undefined : governedTransitionForRun(latestRun);
+    latest === undefined
+      ? undefined
+      : governedTransitionForPlan(latest.plan, [artifact.id]);
   if (transition === undefined) {
     return { kind: 'ignore' };
   }
-  const allRunsMatchTransition = parsed.data.runs.every((run) => {
-    const runPlan = run.plan.plan;
+  const allRunsMatchTransition = runs.every(({ plan }) => {
     if (
-      runPlan.kind !== 'vocabulary' ||
-      governedTransitionForRun(run)?.id !== transition.id ||
-      runPlan.from !== transition.from
+      plan.kind !== 'vocabulary' ||
+      governedTransitionForPlan(plan, [artifact.id])?.id !== transition.id ||
+      plan.from !== transition.from
     ) {
       return false;
     }
     return transition.target.kind === 'single'
-      ? transition.target.to === runPlan.to
-      : transition.target.options.some((option) => option.to === runPlan.to);
+      ? transition.target.to === plan.to
+      : transition.target.options.some((option) => option.to === plan.to);
   });
   if (!allRunsMatchTransition) {
     return historyIssue(
@@ -495,71 +121,34 @@ const loadHistoryFile = (rootDir: string, name: string): HistoryFileResult => {
       transition.id
     );
   }
-  const governedRuns = parsed.data.runs.map((run) =>
-    governedHistoryRunSchema.safeParse(run)
-  );
-  const rawRuns = (
-    json as {
-      readonly runs: readonly RawGovernedHistoryRun[];
-    }
-  ).runs;
-  if (
-    transition.provenance.mode === 'regrade-history' &&
-    (governedRuns.some((run) => !run.success) ||
-      governedRuns.some(
-        (run, index) =>
-          run.success &&
-          !validatesDeterministicEvidence(
-            run.data,
-            rawRuns[index],
-            transition.id
-          )
-      ))
-  ) {
-    return historyIssue(
-      observedPath,
-      'Committed Regrade history has invalid deterministic run evidence.',
-      transition.id
-    );
-  }
-  if (
-    parsed.data.runs.some(
-      (run) =>
-        run.provenance !== undefined &&
-        run.provenance.transitionId !== transition.id
-    )
-  ) {
-    return historyIssue(
-      observedPath,
-      'Committed Regrade history provenance names a different governed transition.',
-      transition.id
-    );
-  }
-  if (
-    transition.provenance.mode === 'regrade-history' &&
-    parsed.data.runs.some((run) => run.provenance === undefined)
-  ) {
-    return historyIssue(
-      observedPath,
-      'Committed Regrade history lacks required governed provenance.',
-      transition.id
-    );
-  }
-  const provenance = parsed.data.runs.at(-1)?.provenance;
-  const facts = latestRunFacts(parsed.data.runs.at(-1));
   return {
     kind: 'evidence',
     value: {
-      ...facts,
-      id: parsed.data.id,
-      path: parsed.data.path,
-      ...(provenance === undefined ? {} : { provenance }),
-      runCount: parsed.data.runs.length,
+      caseSensitive: latest?.caseSensitive ?? false,
+      id: artifact.id,
+      latestFormJudgments: latest?.forms ?? [],
+      path: artifact.path,
+      runCount: runs.length,
       transitionId: transition.id,
     },
   };
 };
 
+const loadHistoryFile = (rootDir: string, name: string): HistoryFileResult => {
+  const absolutePath = join(rootDir, '.trails', 'regrade', 'history', name);
+  const observedPath = normalizePath(relative(rootDir, absolutePath));
+  let json: unknown;
+  try {
+    json = JSON.parse(readFileSync(absolutePath, 'utf8'));
+  } catch {
+    return historyIssue(
+      observedPath,
+      'Committed Regrade history is not valid JSON.'
+    );
+  }
+  return loadReceiptHistoryFile(json, observedPath);
+};
+
 export const loadGovernedVocabularyHistory = (
   rootDir: string
 ): GovernedVocabularyHistoryIndex => {