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

package/src/rules/implementation-returns-result.ts

@@ -25,8 +25,11 @@ import {
   getNodeImported,
   getNodeInit,
   getNodeLocal,
+  getNodeLeft,
   getNodeName,
+  getNodeOperator,
   getNodeReturnType,
+  getNodeRight,
   getNodeSource,
   getNodeTypeAnnotation,
   getNodeValue,
@@ -97,12 +100,15 @@ export type ScopedHelperMap = ReadonlyMap<
 
 export type MutableScopedHelperMap = Map<ReadonlySet<string>, Set<string>>;
 
-type ScopedResultVariableMap = ReadonlyMap<
+export type ScopedResultVariableMap = ReadonlyMap<
   ReadonlySet<string>,
   ReadonlySet<string>
 >;
 
-type MutableScopedResultVariableMap = Map<ReadonlySet<string>, Set<string>>;
+export type MutableScopedResultVariableMap = Map<
+  ReadonlySet<string>,
+  Set<string>
+>;
 
 export const findNearestBindingScope = (
   name: string,
@@ -224,8 +230,8 @@ const unwrapReturnExpression = (node: AstNode): AstNode => {
   return current;
 };
 
-/** Check if a return argument is an allowed Result value. */
-const isAllowedReturnArgument = (
+/** Check whether an expression has visible Result-producing provenance. */
+export const isResultProducingExpression = (
   argument: AstNode,
   helperNames: ReadonlySet<string>,
   resultVars: ScopedResultVariableMap,
@@ -240,7 +246,7 @@ const isAllowedReturnArgument = (
     return (
       consequent !== undefined &&
       alternate !== undefined &&
-      isAllowedReturnArgument(
+      isResultProducingExpression(
         consequent,
         helperNames,
         resultVars,
@@ -248,7 +254,7 @@ const isAllowedReturnArgument = (
         scopes,
         scopedHelpers
       ) &&
-      isAllowedReturnArgument(
+      isResultProducingExpression(
         alternate,
         helperNames,
         resultVars,
@@ -369,6 +375,14 @@ const addScopedResultVariable = (
   resultVars.set(scope, new Set([name]));
 };
 
+const clearScopedResultVariable = (
+  resultVars: MutableScopedResultVariableMap,
+  scope: ReadonlySet<string>,
+  name: string
+): void => {
+  resultVars.get(scope)?.delete(name);
+};
+
 /** Record `const helper = (): Result<...> => ...` declarations for the current lexical scope. */
 export const trackScopedResultHelperDeclaration = (
   node: AstNode,
@@ -440,8 +454,14 @@ const trackResultVariable = (
     }
     if (
       hasResultVariableAnnotation(id, sourceCode, resultTypeNames) ||
-      isResultExpression(init) ||
-      isHelperCall(init, helperNames, namespaceHelpers, scopes, scopedHelpers)
+      isResultProducingExpression(
+        init,
+        helperNames,
+        resultVars,
+        namespaceHelpers,
+        scopes,
+        scopedHelpers
+      )
     ) {
       const bindingScope = findNearestBindingScope(name, scopes);
       if (bindingScope) {
@@ -451,6 +471,63 @@ const trackResultVariable = (
   }
 };
 
+export const collectDirectResultAssignments = (
+  body: AstNode
+): ReadonlySet<AstNode> => {
+  const assignments = new Set<AstNode>();
+  for (const statement of getNodeBodyStatements(body)) {
+    if (statement.type !== 'ExpressionStatement') {
+      continue;
+    }
+    const expression = getNodeExpression(statement);
+    if (expression?.type === 'AssignmentExpression') {
+      assignments.add(expression);
+    }
+  }
+  return assignments;
+};
+
+const trackResultAssignment = (
+  node: AstNode,
+  resultVars: MutableScopedResultVariableMap,
+  helperNames: ReadonlySet<string>,
+  namespaceHelpers: NamespaceHelperMap,
+  directAssignments: ReadonlySet<AstNode>,
+  scopes: readonly ReadonlySet<string>[],
+  scopedHelpers: ScopedHelperMap
+): void => {
+  const left = getNodeLeft(node);
+  const name = identifierName(left);
+  if (!name) {
+    return;
+  }
+  const bindingScope = findNearestBindingScope(name, scopes);
+  if (!bindingScope) {
+    return;
+  }
+  const right = getNodeRight(node);
+  const resultRhs =
+    getNodeOperator(node) === '=' &&
+    right &&
+    isResultProducingExpression(
+      right,
+      helperNames,
+      resultVars,
+      namespaceHelpers,
+      scopes,
+      scopedHelpers
+    );
+  if (
+    resultRhs &&
+    (isScopedResultVariableBinding(name, scopes, resultVars) ||
+      directAssignments.has(node))
+  ) {
+    addScopedResultVariable(resultVars, bindingScope, name);
+    return;
+  }
+  clearScopedResultVariable(resultVars, bindingScope, name);
+};
+
 // ---------------------------------------------------------------------------
 // Return statement checking
 // ---------------------------------------------------------------------------
@@ -470,6 +547,7 @@ const checkReturnStatements = (
   const resultVars: MutableScopedResultVariableMap = new Map();
   const scopedHelpers: MutableScopedHelperMap = new Map();
   const initialScopes = implScope.size > 0 ? [implScope] : [];
+  const directAssignments = collectDirectResultAssignments(blockBody);
 
   walkWithScopes(
     blockBody,
@@ -494,6 +572,18 @@ const checkReturnStatements = (
         );
       }
 
+      if (node.type === 'AssignmentExpression') {
+        trackResultAssignment(
+          node,
+          resultVars,
+          helperNames,
+          namespaceHelpers,
+          directAssignments,
+          currentScopes,
+          scopedHelpers
+        );
+      }
+
       if (node.type !== 'ReturnStatement') {
         return;
       }
@@ -505,7 +595,7 @@ const checkReturnStatements = (
       }
 
       if (
-        isAllowedReturnArgument(
+        isResultProducingExpression(
           argument,
           helperNames,
           resultVars,

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/no-redundant-result-error-wrap.ts

@@ -23,11 +23,11 @@ import {
 import type { AstNode, AstParentContext } from '@ontrails/source';
 import {
   collectAllResultHelperNames,
+  collectDirectResultAssignments,
   collectNamespaceHelperImports,
   collectResultTypeNames,
   findNearestBindingScope,
-  isHelperCall,
-  isResultExpression,
+  isResultProducingExpression,
   trackScopedResultHelperDeclaration,
 } from './implementation-returns-result.js';
 import { isTestFile } from './scan.js';
@@ -82,16 +82,6 @@ const getErrorSourceVariable = (node: AstNode | null): string | null => {
   return identifierName(member?.object);
 };
 
-const isResultProducingExpression = (
-  node: AstNode,
-  helperNames: ReadonlySet<string>,
-  namespaceHelpers: NamespaceHelperMap,
-  scopes: readonly ReadonlySet<string>[],
-  scopedHelpers: ScopedHelperMap
-): boolean =>
-  isResultExpression(node) ||
-  isHelperCall(node, helperNames, namespaceHelpers, scopes, scopedHelpers);
-
 type ResultProvenance = Map<ReadonlySet<string>, Set<string>>;
 
 const markResultVariable = (
@@ -158,6 +148,7 @@ const trackVariableDeclarator = (
     isResultProducingExpression(
       init,
       helperNames,
+      provenance,
       namespaceHelpers,
       scopes,
       scopedHelpers
@@ -175,11 +166,10 @@ const trackAssignmentExpression = (
   helperNames: ReadonlySet<string>,
   namespaceHelpers: NamespaceHelperMap,
   scopedHelpers: ScopedHelperMap,
+  directAssignments: ReadonlySet<AstNode>,
   scopes: readonly ReadonlySet<string>[]
 ): void => {
   const left = getNodeLeft(node);
-  const operator = getNodeOperator(node);
-  const right = getNodeRight(node);
   const name = identifierName(left);
   if (!name) {
     return;
@@ -188,16 +178,22 @@ const trackAssignmentExpression = (
   if (!scope) {
     return;
   }
-  if (
-    operator === '=' &&
+  const right = getNodeRight(node);
+  const resultRhs =
+    getNodeOperator(node) === '=' &&
     right &&
     isResultProducingExpression(
       right,
       helperNames,
+      provenance,
       namespaceHelpers,
       scopes,
       scopedHelpers
-    )
+    );
+  if (
+    resultRhs &&
+    (hasResultProvenance(provenance, scope, name) ||
+      directAssignments.has(node))
   ) {
     markResultVariable(provenance, scope, name);
     return;
@@ -258,6 +254,7 @@ const checkFunctionBody = (
   const scopedHelpers: MutableScopedHelperMap = new Map();
   const implScope = collectScopeFrameBindings(owner);
   const initialScopes = implScope.size > 0 ? [implScope] : [];
+  const directAssignments = collectDirectResultAssignments(body);
 
   walkWithScopes(
     body,
@@ -287,6 +284,7 @@ const checkFunctionBody = (
           helperNames,
           namespaceHelpers,
           scopedHelpers,
+          directAssignments,
           scopes
         );
         return;

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 [];
   }

package/src/rules/retired-vocabulary.ts

@@ -62,6 +62,7 @@ export const governedVocabularySymbolRenameSchema = z.object({
   from: z.string().min(1),
   match: z.enum(governedVocabularySymbolRenameMatchModes).default('exact'),
   reviewDeclarationTypes: z.array(z.string().min(1)).default([]),
+  safety: z.enum(['safe', 'review']).optional(),
   to: z.string().min(1),
 });
 
@@ -829,6 +830,9 @@ export const governedVocabularyTransitions =
         'cliProjection',
         'cliProjectionSchema',
         'collectLibraryProjection',
+        'collectionExtensionProjectionForFileRenames',
+        'extensionProjection',
+        'filterProjectedTargetExtensions',
         'projectActivationEdge',
         'projectActivationSource',
         'projectActivationSourceDeclaration',
@@ -860,6 +864,11 @@ export const governedVocabularyTransitions =
         'projectTrailVersions',
         'projectVersionDetours',
         'projectVersionRuntimeRefs',
+        'projectVocabularyText',
+        'projected',
+        'projectedEvidence',
+        'projectedFileInScopeCount',
+        'projectedTargetPaths',
         'SchemaProjector',
         'deriveShippedSurfaceProjectionInventory',
         'deriveTrailCliCommandProjection',
@@ -1190,6 +1199,15 @@ export const governedVocabularyTransitions =
           from: 'collectLibraryProjection',
           to: 'deriveTopoGraphLibrary',
         },
+        {
+          from: 'collectionExtensionProjectionForFileRenames',
+          to: 'deriveCollectionExtensionsForFileRenames',
+        },
+        { from: 'extensionProjection', to: 'derivedExtensions' },
+        {
+          from: 'filterProjectedTargetExtensions',
+          to: 'filterDerivedTargetExtensions',
+        },
         { from: 'projectActivationEdge', to: 'deriveActivationEdge' },
         { from: 'projectActivationSource', to: 'deriveActivationSource' },
         {
@@ -1233,6 +1251,18 @@ export const governedVocabularyTransitions =
           from: 'projectVersionRuntimeRefs',
           to: 'deriveVersionRuntimeRefs',
         },
+        { from: 'projectVocabularyText', to: 'deriveVocabularyText' },
+        {
+          from: 'projected',
+          safety: 'review',
+          to: 'derived',
+        },
+        { from: 'projectedEvidence', to: 'derivedEvidence' },
+        {
+          from: 'projectedFileInScopeCount',
+          to: 'derivedFileInScopeCount',
+        },
+        { from: 'projectedTargetPaths', to: 'derivedTargetPaths' },
         { from: 'SchemaProjector', to: 'SchemaDeriver' },
         {
           from: 'deriveShippedSurfaceProjectionInventory',

package/src/rules/types.ts

@@ -386,22 +386,25 @@ export interface ProjectContext {
 export interface GovernedVocabularyHistoryEvidence {
   readonly caseSensitive: boolean;
   readonly id: string;
-  readonly latestFormObservations: readonly GovernedVocabularyHistoryFormObservation[];
+  readonly latestFormJudgments: readonly GovernedVocabularyHistoryFormJudgment[];
   readonly path: string;
   readonly provenance?: GovernedVocabularyHistoryProvenance;
   readonly runCount: number;
   readonly transitionId: string;
 }
 
-/** One vocabulary-form observation preserved in committed Regrade history. */
-export interface GovernedVocabularyHistoryFormObservation {
+/** One compact vocabulary-form judgment preserved in committed Regrade history. */
+export interface GovernedVocabularyHistoryFormJudgment {
   readonly disposition: string;
   readonly form: string;
-  readonly line: number;
-  readonly path: string;
-  readonly reason: string;
-  readonly scopeTier?: 'in-scope' | 'policy-classified' | undefined;
-  readonly verdict: 'applied' | 'deferred' | 'modified' | 'skipped';
+  readonly reason?: string | undefined;
+  readonly representative?:
+    | {
+        readonly line: number;
+        readonly path: string;
+      }
+    | undefined;
+  readonly target?: string | undefined;
 }
 
 export interface GovernedVocabularyHistoryIssue {

package/src/trails/schema.ts

@@ -119,21 +119,24 @@ export const authoredMcpSurfaceBindingSetSchema = z.object({
     .describe('Trail ids registered in the owning app topo'),
 });
 
-const governedVocabularyHistoryObservationSchema = z.object({
+const governedVocabularyHistoryFormJudgmentSchema = z.object({
   disposition: z.string(),
   form: z.string(),
-  line: z.number().int().positive(),
-  path: z.string(),
-  reason: z.string(),
-  scopeTier: z.enum(['in-scope', 'policy-classified']).optional(),
-  verdict: z.enum(['applied', 'deferred', 'modified', 'skipped']),
+  reason: z.string().optional(),
+  representative: z
+    .object({
+      line: z.number().int().positive(),
+      path: z.string(),
+    })
+    .optional(),
+  target: z.string().optional(),
 });
 
 const governedVocabularyHistoryEvidenceSchema = z.object({
   caseSensitive: z.boolean(),
   id: z.string(),
-  latestFormObservations: z
-    .array(governedVocabularyHistoryObservationSchema)
+  latestFormJudgments: z
+    .array(governedVocabularyHistoryFormJudgmentSchema)
     .readonly(),
   path: z.string(),
   runCount: z.number().int().nonnegative(),