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

package/src/regrade-receipt.ts

@@ -0,0 +1,484 @@
+import { createHash } from 'node:crypto';
+import { posix } from 'node:path';
+import { z } from 'zod';
+
+const sha256Schema = z.string().regex(/^[0-9a-f]{64}$/);
+const gitObjectIdSchema = z.string().regex(/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/);
+const countSchema = z.number().int().nonnegative();
+const vocabularyDispositionValues = [
+  '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',
+] as const;
+
+const scopeSchema = z
+  .object({
+    exclude: z.array(z.string()).optional(),
+    extensions: z.array(z.string()).optional(),
+    include: z.array(z.string()).optional(),
+  })
+  .strict();
+
+const vocabularyScopeSchema = scopeSchema.extend({
+  ignoredDirectories: z.array(z.string()).optional(),
+  policyClassified: z
+    .array(
+      z
+        .object({
+          disposition: z.enum(vocabularyDispositionValues),
+          expectMatches: z.boolean().optional(),
+          paths: z.array(z.string().min(1)).min(1),
+          reason: z.string().min(1),
+        })
+        .strict()
+    )
+    .optional(),
+  teachingSurfaces: z.array(z.string().min(1)).optional(),
+});
+
+const vocabularyPlanSchema = z
+  .object({
+    caseSensitive: z.boolean().optional(),
+    deferForms: z.array(z.string().min(1)).optional(),
+    fileRenames: z
+      .array(
+        z.object({ from: z.string().min(1), to: z.string().min(1) }).strict()
+      )
+      .optional(),
+    from: z.string().min(1),
+    id: z.string().optional(),
+    intent: z.string().optional(),
+    kind: z.literal('vocabulary'),
+    overrides: z.record(z.string().min(1), z.string().min(1)).optional(),
+    preserve: z
+      .array(
+        z
+          .object({
+            disposition: z.enum(vocabularyDispositionValues).optional(),
+            forms: z.array(z.string().min(1)).optional(),
+            paths: z.array(z.string()).optional(),
+            pattern: z.string(),
+            reason: z.string().optional(),
+          })
+          .strict()
+      )
+      .optional(),
+    scope: vocabularyScopeSchema.optional(),
+    to: z.string().min(1),
+  })
+  .strict();
+
+const classPlanSchema = z
+  .object({
+    classIds: z.array(z.string().min(1)).min(1),
+    id: z.string().min(1),
+    intent: z.string().optional(),
+    kind: z.literal('class'),
+    name: z.string().min(1).optional(),
+    scope: scopeSchema.optional(),
+  })
+  .strict();
+
+const planSchema = z.discriminatedUnion('kind', [
+  vocabularyPlanSchema,
+  classPlanSchema,
+]);
+
+const planProvenanceSchema = z
+  .object({
+    fields: z.record(z.string(), z.enum(['authored', 'derived'])),
+  })
+  .strict();
+
+const formJudgmentSchema = z
+  .object({
+    disposition: z.enum(['mapped', 'out-of-family', 'preserved', 'unresolved']),
+    form: z.string().min(1),
+    reason: z.string().min(1).optional(),
+    representative: z
+      .object({ line: z.number().int().positive(), path: z.string().min(1) })
+      .strict()
+      .optional(),
+    target: z.string().min(1).optional(),
+  })
+  .strict();
+
+const completionSchema = z
+  .object({
+    counts: z
+      .object({
+        dispositions: z.record(z.string().min(1), countSchema),
+        matched: countSchema,
+        preserved: countSchema,
+        review: countSchema,
+        rewritten: countSchema,
+        skippedByReason: z.record(z.string().min(1), countSchema),
+        unknown: countSchema,
+      })
+      .strict(),
+    gate: z
+      .object({
+        reasons: z.array(z.string().min(1)),
+        remaining: countSchema,
+        status: z.enum(['green', 'open']),
+      })
+      .strict(),
+    metrics: z
+      .object({
+        filesChanged: countSchema,
+        formsMapped: countSchema,
+        occurrencesRewritten: countSchema,
+      })
+      .strict(),
+  })
+  .strict();
+
+const runSchema = z
+  .object({
+    classifiedState: z.discriminatedUnion('kind', [
+      z
+        .object({
+          caseSensitive: z.boolean(),
+          forms: z.array(formJudgmentSchema),
+          kind: z.literal('embedded'),
+          stateHash: sha256Schema,
+        })
+        .strict(),
+      z
+        .object({ kind: z.literal('reference'), stateHash: sha256Schema })
+        .strict(),
+    ]),
+    completion: completionSchema,
+    evidence: z
+      .object({
+        changedFiles: z.array(
+          z
+            .object({
+              afterBlobHash: gitObjectIdSchema,
+              afterPath: z.string().min(1),
+              beforeBlobHash: gitObjectIdSchema,
+              beforePath: z.string().min(1),
+            })
+            .strict()
+        ),
+        detailEvidenceHash: sha256Schema,
+        lockStateHash: sha256Schema,
+        policyHash: sha256Schema,
+        sourceRevision: gitObjectIdSchema,
+        sourceStateHash: sha256Schema,
+        toolVersion: z.string().min(1),
+      })
+      .strict(),
+    intent: z.discriminatedUnion('kind', [
+      z
+        .object({
+          kind: z.literal('embedded'),
+          plan: planSchema,
+          planContentHash: sha256Schema,
+          provenance: planProvenanceSchema,
+        })
+        .strict(),
+      z
+        .object({ kind: z.literal('reference'), planContentHash: sha256Schema })
+        .strict(),
+    ]),
+    project: z.object({ root: z.literal('.') }).strict(),
+    runId: z.string().min(1),
+    runKind: z.enum(['original', 'adjust', 'proof']),
+    timestamp: z.iso.datetime(),
+    transitionId: z.string().min(1),
+  })
+  .strict();
+
+const receiptSchema = z
+  .object({
+    conversion: z
+      .object({
+        convertedAt: z.iso.datetime(),
+        fromSchemaVersion: z.literal(2),
+        sourceContentHash: sha256Schema,
+        toolVersion: z.string().min(1),
+      })
+      .strict()
+      .optional(),
+    id: z.string().min(1),
+    kind: z.literal('regrade-history'),
+    path: z.string().min(1),
+    runs: z.array(runSchema).min(1),
+    schemaVersion: z.literal(3),
+  })
+  .strict();
+
+type Receipt = z.output<typeof receiptSchema>;
+type Plan = z.output<typeof planSchema>;
+type FormJudgment = z.output<typeof formJudgmentSchema>;
+
+export interface WardenResolvedReceipt {
+  readonly artifact: Receipt;
+  readonly runs: readonly {
+    readonly caseSensitive: boolean;
+    readonly forms: readonly FormJudgment[];
+    readonly plan: Plan;
+  }[];
+}
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const canonicalize = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+  if (!isPlainObject(value)) {
+    return value;
+  }
+  return Object.fromEntries(
+    Object.keys(value)
+      .toSorted()
+      .map((key) => [key, canonicalize(value[key])])
+  );
+};
+
+const contentHash = (value: unknown): string =>
+  createHash('sha256')
+    .update(JSON.stringify(canonicalize(value)))
+    .digest('hex');
+
+const compareCodeUnits = (left: string, right: string): number => {
+  if (left < right) {
+    return -1;
+  }
+  if (left > right) {
+    return 1;
+  }
+  return 0;
+};
+
+const stateHash = (state: {
+  readonly caseSensitive: boolean;
+  readonly forms: readonly FormJudgment[];
+}): string =>
+  contentHash({
+    caseSensitive: state.caseSensitive,
+    forms: [...state.forms].toSorted(
+      (left, right) =>
+        compareCodeUnits(left.form, right.form) ||
+        compareCodeUnits(left.disposition, right.disposition)
+    ),
+  });
+
+const validRootRelativePath = (value: string): boolean =>
+  value.length > 0 &&
+  value !== '.' &&
+  !posix.isAbsolute(value) &&
+  !/^[A-Za-z]:[\\/]/u.test(value) &&
+  !value.startsWith('\\\\') &&
+  !value.includes('\\') &&
+  !value.includes('\u0000') &&
+  posix.normalize(value) === value &&
+  !value.startsWith('./') &&
+  value !== '..' &&
+  !value.startsWith('../') &&
+  !value.includes('/../');
+
+const planPaths = (plan: Plan): readonly string[] => {
+  const common = [
+    ...(plan.scope?.include ?? []),
+    ...(plan.scope?.exclude ?? []),
+  ];
+  if (plan.kind === 'class') {
+    return common;
+  }
+  return [
+    ...common,
+    ...(plan.scope?.ignoredDirectories ?? []),
+    ...(plan.scope?.teachingSurfaces ?? []),
+    ...(plan.scope?.policyClassified ?? []).flatMap((item) => item.paths),
+    ...(plan.fileRenames ?? []).flatMap((rename) => [rename.from, rename.to]),
+    ...(plan.preserve ?? []).flatMap((item) => item.paths ?? []),
+  ];
+};
+
+const proofIsMinimal = (run: Receipt['runs'][number]): boolean => {
+  const { counts, gate, metrics } = run.completion;
+  return (
+    run.intent.kind === 'reference' &&
+    run.classifiedState.kind === 'reference' &&
+    run.evidence.changedFiles.length === 0 &&
+    gate.status === 'green' &&
+    gate.remaining === 0 &&
+    gate.reasons.length === 0 &&
+    counts.matched === 0 &&
+    counts.preserved === 0 &&
+    counts.review === 0 &&
+    counts.rewritten === 0 &&
+    counts.unknown === 0 &&
+    Object.keys(counts.dispositions).length === 0 &&
+    Object.keys(counts.skippedByReason).length === 0 &&
+    metrics.filesChanged === 0 &&
+    metrics.formsMapped === 0 &&
+    metrics.occurrencesRewritten === 0
+  );
+};
+
+type ReceiptRun = Receipt['runs'][number];
+interface ResolvedState {
+  readonly caseSensitive: boolean;
+  readonly forms: readonly FormJudgment[];
+}
+type Resolution<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly error: string; readonly ok: false };
+
+const validateRunEvidence = (run: ReceiptRun): string | undefined => {
+  const beforePaths = new Set<string>();
+  const afterPaths = new Set<string>();
+  for (const file of run.evidence.changedFiles) {
+    if (
+      !validRootRelativePath(file.beforePath) ||
+      !validRootRelativePath(file.afterPath) ||
+      beforePaths.has(file.beforePath) ||
+      afterPaths.has(file.afterPath) ||
+      (file.beforePath === file.afterPath &&
+        file.beforeBlobHash === file.afterBlobHash)
+    ) {
+      return 'invalid changed-file evidence';
+    }
+    beforePaths.add(file.beforePath);
+    afterPaths.add(file.afterPath);
+  }
+  if (
+    run.completion.metrics.filesChanged !== run.evidence.changedFiles.length
+  ) {
+    return 'changed-file count mismatch';
+  }
+  const { counts, gate, metrics } = run.completion;
+  const hasUnresolvedCounts = counts.review > 0 || counts.unknown > 0;
+  const gateIsCoherent =
+    gate.status === 'green'
+      ? gate.remaining === 0 &&
+        gate.reasons.length === 0 &&
+        !hasUnresolvedCounts
+      : gate.reasons.length > 0;
+  if (counts.rewritten !== metrics.occurrencesRewritten || !gateIsCoherent) {
+    return 'incoherent completion facts';
+  }
+  return undefined;
+};
+
+const resolvePlan = (
+  run: ReceiptRun,
+  plans: Map<string, Plan>
+): Resolution<Plan> => {
+  if (run.intent.kind === 'reference') {
+    const plan = plans.get(run.intent.planContentHash);
+    return plan === undefined
+      ? { error: 'broken plan reference', ok: false }
+      : { ok: true, value: plan };
+  }
+  if (
+    contentHash({
+      plan: run.intent.plan,
+      provenance: run.intent.provenance,
+    }) !== run.intent.planContentHash ||
+    planPaths(run.intent.plan).some((path) => !validRootRelativePath(path))
+  ) {
+    return { error: 'invalid embedded plan', ok: false };
+  }
+  plans.set(run.intent.planContentHash, run.intent.plan);
+  return { ok: true, value: run.intent.plan };
+};
+
+const resolveState = (
+  run: ReceiptRun,
+  states: Map<string, ResolvedState>
+): Resolution<ResolvedState> => {
+  if (run.classifiedState.kind === 'reference') {
+    const state = states.get(run.classifiedState.stateHash);
+    return state === undefined
+      ? { error: 'broken classified state reference', ok: false }
+      : { ok: true, value: state };
+  }
+  const { caseSensitive, forms } = run.classifiedState;
+  const identities = new Set(
+    forms.map((form) => (caseSensitive ? form.form : form.form.toLowerCase()))
+  );
+  if (
+    identities.size !== forms.length ||
+    forms.some(
+      (form) =>
+        (form.disposition === 'mapped') !== (form.target !== undefined) ||
+        (form.representative !== undefined &&
+          !validRootRelativePath(form.representative.path))
+    )
+  ) {
+    return { error: 'invalid classified form state', ok: false };
+  }
+  const state = { caseSensitive, forms };
+  if (stateHash(state) !== run.classifiedState.stateHash) {
+    return { error: 'classified state hash mismatch', ok: false };
+  }
+  states.set(run.classifiedState.stateHash, state);
+  return { ok: true, value: state };
+};
+
+/** Validate and resolve only the compact receipt facts consumed by Warden. */
+export const resolveReceiptForWarden = (
+  value: unknown
+): { readonly error?: string; readonly value?: WardenResolvedReceipt } => {
+  const parsed = receiptSchema.safeParse(value);
+  if (!parsed.success) {
+    return { error: 'invalid evidence shape' };
+  }
+  const artifact = parsed.data;
+  if (
+    !validRootRelativePath(artifact.path) ||
+    !/^\.trails\/regrade\/history\/[^/]+\.json$/u.test(artifact.path)
+  ) {
+    return { error: 'invalid receipt path' };
+  }
+
+  const plans = new Map<string, Plan>();
+  const states = new Map<string, ResolvedState>();
+  const runIds = new Set<string>();
+  const runs: WardenResolvedReceipt['runs'][number][] = [];
+
+  for (const run of artifact.runs) {
+    if (run.transitionId !== artifact.id || runIds.has(run.runId)) {
+      return { error: 'invalid transition or duplicate run identity' };
+    }
+    runIds.add(run.runId);
+    if (run.runKind === 'proof' && !proofIsMinimal(run)) {
+      return { error: 'invalid proof receipt' };
+    }
+    if (run.runKind !== 'proof' && run.intent.kind !== 'embedded') {
+      return { error: 'non-proof receipt must embed intent' };
+    }
+
+    const evidenceError = validateRunEvidence(run);
+    if (evidenceError !== undefined) {
+      return { error: evidenceError };
+    }
+    const plan = resolvePlan(run, plans);
+    if (!plan.ok) {
+      return { error: plan.error };
+    }
+    const state = resolveState(run, states);
+    if (!state.ok) {
+      return { error: state.error };
+    }
+    runs.push({
+      caseSensitive: state.value.caseSensitive,
+      forms: state.value.forms,
+      plan: plan.value,
+    });
+  }
+  return { value: { artifact, runs } };
+};

package/src/rules/governed-symbol-residue.ts

@@ -286,6 +286,10 @@ const reviewReasonFor = (
     }
   }
 
+  if (match.rename.safety === 'review') {
+    return 'requires semantic classification';
+  }
+
   if (shorthandIdentifiers.has(match.from)) {
     return 'participates in an authored shorthand property';
   }

package/src/rules/governed-vocabulary-permutation-watch.ts

@@ -1,6 +1,6 @@
 import type {
   GovernedVocabularyHistoryEvidence,
-  GovernedVocabularyHistoryFormObservation,
+  GovernedVocabularyHistoryFormJudgment,
   ProjectAwareWardenRule,
   ProjectContext,
   WardenDiagnostic,
@@ -14,18 +14,19 @@ const formIdentity = (
 ): string => (evidence.caseSensitive ? form : form.toLowerCase());
 
 const isUnknownPermutation = (
-  observation: GovernedVocabularyHistoryFormObservation
+  judgment: GovernedVocabularyHistoryFormJudgment
 ): boolean =>
-  observation.reason === 'unclassified-neighbor' &&
-  observation.verdict === 'deferred' &&
-  (observation.scopeTier === undefined || observation.scopeTier === 'in-scope');
+  judgment.disposition === 'unresolved' &&
+  judgment.reason === 'unclassified-neighbor';
 
 const compareObservation = (
-  left: GovernedVocabularyHistoryFormObservation,
-  right: GovernedVocabularyHistoryFormObservation
+  left: GovernedVocabularyHistoryFormJudgment,
+  right: GovernedVocabularyHistoryFormJudgment
 ): number =>
-  left.path.localeCompare(right.path) ||
-  left.line - right.line ||
+  (left.representative?.path ?? '').localeCompare(
+    right.representative?.path ?? ''
+  ) ||
+  (left.representative?.line ?? 1) - (right.representative?.line ?? 1) ||
   left.form.localeCompare(right.form);
 
 const diagnosticsForHistory = (
@@ -33,26 +34,26 @@ const diagnosticsForHistory = (
 ): readonly WardenDiagnostic[] => {
   const unknownByIdentity = new Map<
     string,
-    GovernedVocabularyHistoryFormObservation
+    GovernedVocabularyHistoryFormJudgment
   >();
 
-  for (const observation of evidence.latestFormObservations) {
-    if (!isUnknownPermutation(observation)) {
+  for (const judgment of evidence.latestFormJudgments) {
+    if (!isUnknownPermutation(judgment)) {
       continue;
     }
-    const identity = formIdentity(observation.form, evidence);
+    const identity = formIdentity(judgment.form, evidence);
     const current = unknownByIdentity.get(identity);
-    if (current === undefined || compareObservation(observation, current) < 0) {
-      unknownByIdentity.set(identity, observation);
+    if (current === undefined || compareObservation(judgment, current) < 0) {
+      unknownByIdentity.set(identity, judgment);
     }
   }
 
   return [...unknownByIdentity.entries()]
     .toSorted(([left], [right]) => left.localeCompare(right))
-    .map(([, observation]) => ({
-      filePath: observation.path,
-      line: observation.line,
-      message: `Governed transition '${evidence.transitionId}' recorded unknown vocabulary form '${observation.form}' in committed Regrade history '${evidence.path}' (${evidence.id}). Add the form and run an incremental plan, or classify it as out-of-family or preserved.`,
+    .map(([, judgment]) => ({
+      filePath: judgment.representative?.path ?? evidence.path,
+      line: judgment.representative?.line ?? 1,
+      message: `Governed transition '${evidence.transitionId}' recorded unknown vocabulary form '${judgment.form}' in committed Regrade history '${evidence.path}' (${evidence.id}). Add the form and run an incremental plan, or classify it as out-of-family or preserved.`,
       rule: RULE_NAME,
       severity: 'warn' as const,
     }));

package/src/rules/index.ts

@@ -81,7 +81,7 @@ import { webhookRouteCollision } from './webhook-route-collision.js';
 
 export type {
   GovernedVocabularyHistoryEvidence,
-  GovernedVocabularyHistoryFormObservation,
+  GovernedVocabularyHistoryFormJudgment,
   GovernedVocabularyHistoryIssue,
   WardenFix,
   WardenFixCapability,

package/src/rules/public-export-example-coverage.ts

@@ -44,8 +44,9 @@ import {
   getNodeValue,
   offsetToLine,
   parse,
+  parseWithDiagnostics,
 } from '@ontrails/source';
-import type { AstNode } from '@ontrails/source';
+import type { AstNode, SourceComment } from '@ontrails/source';
 import type { WardenDiagnostic, WardenRule } from './types.js';
 
 const RULE_NAME = 'public-export-example-coverage';
@@ -379,44 +380,19 @@ const declarationNameMatches = (
   return false;
 };
 
-/**
- * Comment texts found in an inter-statement trivia gap. The gap between two
- * top-level statements contains only whitespace and comments, so a small
- * line/block comment scan recovers the same comment set TypeScript's
- * `getLeadingCommentRanges` returns for the statement's full start.
- */
-const collectCommentTexts = (gapText: string): readonly string[] => {
-  const comments: string[] = [];
-  let index = 0;
-  while (index < gapText.length - 1) {
-    if (gapText[index] === '/' && gapText[index + 1] === '/') {
-      const lineEnd = gapText.indexOf('\n', index);
-      const stop = lineEnd === -1 ? gapText.length : lineEnd;
-      comments.push(gapText.slice(index, stop));
-      index = stop + 1;
-    } else if (gapText[index] === '/' && gapText[index + 1] === '*') {
-      const blockEnd = gapText.indexOf('*/', index + 2);
-      const stop = blockEnd === -1 ? gapText.length : blockEnd + 2;
-      comments.push(gapText.slice(index, stop));
-      index = stop;
-    } else {
-      index += 1;
-    }
-  }
-  return comments;
-};
-
 const EXAMPLE_TAG_PATTERN = /@example\b/;
+const LINE_TERMINATOR_PATTERN = /[\n\r\u2028\u2029]/u;
 
 /**
  * True when the exported declaration named `importedName` in `sourceText`
- * carries a leading comment containing `@example`. Leading comments are
- * recovered from the trivia gap between the preceding top-level statement's
- * end (or file start) and the matching export statement's start.
+ * carries a leading comment containing `@example`. Parser-native comments in
+ * the trivia gap between the preceding top-level statement's end (or file
+ * start) and the matching export statement are considered leading.
  */
 const hasLeadingExampleForExport = (
   sourceText: string,
   ast: AstNode,
+  comments: readonly SourceComment[],
   importedName: string
 ): boolean => {
   const body = programBody(ast);
@@ -429,9 +405,16 @@ const hasLeadingExampleForExport = (
       continue;
     }
     const previous = body[statementIndex - 1];
-    const gapText = sourceText.slice(previous?.end ?? 0, statement.start);
-    return collectCommentTexts(gapText).some((comment) =>
-      EXAMPLE_TAG_PATTERN.test(comment)
+    const gapStart = previous?.end ?? 0;
+    return comments.some(
+      (comment) =>
+        gapStart <= comment.start &&
+        comment.end <= statement.start &&
+        (previous === undefined ||
+          LINE_TERMINATOR_PATTERN.test(
+            sourceText.slice(gapStart, comment.start)
+          )) &&
+        EXAMPLE_TAG_PATTERN.test(comment.value)
     );
   }
   return false;
@@ -468,8 +451,8 @@ const coverageDiagnosticsForSpecifier = (
       ),
     ];
   }
-  const sourceAst = parse(sourcePath, sourceText);
-  if (!sourceAst) {
+  const parsedSource = parseWithDiagnostics(sourcePath, sourceText);
+  if (!parsedSource.ast || parsedSource.diagnostics.length > 0) {
     return [
       diagnostic(
         sourceCode,
@@ -481,7 +464,12 @@ const coverageDiagnosticsForSpecifier = (
     ];
   }
   if (
-    hasLeadingExampleForExport(sourceText, sourceAst, specifier.importedName)
+    hasLeadingExampleForExport(
+      sourceText,
+      parsedSource.ast,
+      parsedSource.comments,
+      specifier.importedName
+    )
   ) {
     return [];
   }