@ontrails/regrade 1.0.0-beta.39 → 1.0.0-beta.41

package/src/downstream/collect.ts

@@ -281,7 +281,7 @@ export const collectDownstreamSourcesOutput = z.object({
 export const collectDownstreamSourcesTrail = trail(
   'regrade.downstream.collect',
   {
-    blaze: (input) => {
+    implementation: (input) => {
       const collection = collectDownstreamSources(input.root, {
         ...(input.extensions === undefined
           ? {}

package/src/downstream/export-restructure.ts

@@ -18,7 +18,7 @@
  * emitted on a guess.
  */
 
-import type { AstNode, SourceEdit } from '@ontrails/warden/ast';
+import type { AstNode, SourceEdit } from '@ontrails/source';
 import {
   applySourceEdits,
   createSourceEdit,
@@ -60,7 +60,7 @@ import {
   parseWithDiagnostics,
   validateSourceEdits,
   walkWithParents,
-} from '@ontrails/warden/ast';
+} from '@ontrails/source';
 import type { WardenRule } from '@ontrails/warden';
 import {
   getWardenRuleMetadata,

package/src/downstream/report.ts

@@ -17,7 +17,8 @@ import {
   loadProjectWardenRules,
   wardenRules,
 } from '@ontrails/warden';
-import { readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
 import { z } from 'zod';
 
 import {
@@ -79,6 +80,16 @@ export interface RegradeClassContext {
   readonly path: string;
   /** Absolute path on disk, when the caller has one. */
   readonly absolutePath?: string;
+  /** Nearest owning package facts, when filesystem collection found a manifest. */
+  readonly package?: {
+    readonly dependencies: readonly string[];
+    /** Runtime-visible dependency declarations (dependencies, optional, peer). */
+    readonly runtimeDependencies?: readonly string[];
+    readonly manifestState?: 'invalid' | 'valid';
+    readonly name?: string;
+    /** Root-relative POSIX manifest path. */
+    readonly path: string;
+  };
 }
 
 /** Files a regrade class knows how to inspect. */
@@ -966,6 +977,7 @@ const buildRegradeEvaluation = (params: {
     readonly path: string;
     readonly source: string;
     readonly absolutePath?: string;
+    readonly package?: RegradeClassContext['package'];
   }[];
   readonly skipped: readonly SkippedSource[];
   readonly classes: readonly RegradeClass[];
@@ -987,6 +999,7 @@ const buildRegradeEvaluation = (params: {
         ...(file.absolutePath === undefined
           ? {}
           : { absolutePath: file.absolutePath }),
+        ...(file.package === undefined ? {} : { package: file.package }),
         path: file.path,
       },
       selected,
@@ -1055,6 +1068,7 @@ export const buildRegradeReport = (params: {
     readonly path: string;
     readonly source: string;
     readonly absolutePath?: string;
+    readonly package?: RegradeClassContext['package'];
   }[];
   readonly skipped: readonly SkippedSource[];
   readonly classes: readonly RegradeClass[];
@@ -1127,6 +1141,121 @@ const canReadDownstreamRoot = (root: string): boolean => {
   }
 };
 
+const PACKAGE_DEPENDENCY_FIELDS = [
+  'dependencies',
+  'devDependencies',
+  'optionalDependencies',
+  'peerDependencies',
+] as const;
+
+const RUNTIME_PACKAGE_DEPENDENCY_FIELDS = [
+  'dependencies',
+  'optionalDependencies',
+  'peerDependencies',
+] as const;
+
+const dependencyNames = (
+  manifest: Readonly<Record<string, unknown>>,
+  fields: readonly (typeof PACKAGE_DEPENDENCY_FIELDS)[number][]
+): readonly string[] =>
+  fields.flatMap((field) => {
+    const value = manifest[field];
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+      ? Object.keys(value)
+      : [];
+  });
+
+const packageContextFor = (
+  root: string,
+  absolutePath: string,
+  cache: Map<string, RegradeClassContext['package'] | undefined>
+): RegradeClassContext['package'] | undefined => {
+  const absoluteRoot = resolve(root);
+  let current = dirname(absolutePath);
+  const visited: string[] = [];
+  while (true) {
+    if (cache.has(current)) {
+      const cached = cache.get(current);
+      for (const directory of visited) {
+        cache.set(directory, cached);
+      }
+      return cached;
+    }
+    visited.push(current);
+    const fromRoot = relative(absoluteRoot, current);
+    if (fromRoot.startsWith('..') || resolve(current) !== current) {
+      break;
+    }
+    const manifestPath = join(current, 'package.json');
+    if (existsSync(manifestPath)) {
+      const manifestRelativePath = relative(
+        absoluteRoot,
+        manifestPath
+      ).replaceAll('\\', '/');
+      try {
+        const parsed = JSON.parse(
+          readFileSync(manifestPath, 'utf8')
+        ) as unknown;
+        if (
+          typeof parsed !== 'object' ||
+          parsed === null ||
+          Array.isArray(parsed)
+        ) {
+          const invalidContext = {
+            dependencies: [],
+            manifestState: 'invalid' as const,
+            path: manifestRelativePath,
+          };
+          for (const directory of visited) {
+            cache.set(directory, invalidContext);
+          }
+          return invalidContext;
+        }
+        const manifest = parsed as Record<string, unknown>;
+        const dependencies = dependencyNames(
+          manifest,
+          PACKAGE_DEPENDENCY_FIELDS
+        );
+        const runtimeDependencies = dependencyNames(
+          manifest,
+          RUNTIME_PACKAGE_DEPENDENCY_FIELDS
+        );
+        const packageContext = {
+          dependencies: [...new Set(dependencies)].toSorted(),
+          manifestState: 'valid' as const,
+          ...(typeof manifest['name'] === 'string'
+            ? { name: manifest['name'] }
+            : {}),
+          path: manifestRelativePath,
+          runtimeDependencies: [...new Set(runtimeDependencies)].toSorted(),
+        };
+        for (const directory of visited) {
+          cache.set(directory, packageContext);
+        }
+        return packageContext;
+      } catch {
+        const invalidContext = {
+          dependencies: [],
+          manifestState: 'invalid' as const,
+          path: manifestRelativePath,
+        };
+        for (const directory of visited) {
+          cache.set(directory, invalidContext);
+        }
+        return invalidContext;
+      }
+    }
+    if (current === absoluteRoot) {
+      break;
+    }
+    current = dirname(current);
+  }
+  for (const directory of visited) {
+    cache.set(directory, undefined);
+  }
+  return undefined;
+};
+
 const runRegradeEvaluation = (params: {
   readonly root: string;
   readonly classes: readonly RegradeClass[];
@@ -1169,10 +1298,20 @@ const runRegradeEvaluation = (params: {
 
   const files: { absolutePath: string; path: string; source: string }[] = [];
   const skipped: SkippedSource[] = [...collected.skipped];
+  const packageContextCache = new Map<
+    string,
+    RegradeClassContext['package'] | undefined
+  >();
   for (const file of collected.files) {
     try {
+      const packageContext = packageContextFor(
+        params.root,
+        file.absolutePath,
+        packageContextCache
+      );
       files.push({
         absolutePath: file.absolutePath,
+        ...(packageContext === undefined ? {} : { package: packageContext }),
         path: file.path,
         source: readFileSync(file.absolutePath, 'utf8'),
       });

package/src/downstream/vocabulary-registry.ts

@@ -11,6 +11,9 @@ const pluralizeVocabularyForm = (value: string): string =>
     ? `${value}es`
     : `${value}s`;
 
+const defaultSourceForms = (value: string): readonly string[] =>
+  /^[A-Za-z]+$/.test(value) ? [value, pluralizeVocabularyForm(value)] : [value];
+
 const preserveRulesFromTransition = (
   transition: GovernedVocabularyTransition
 ): readonly VocabularyPreserveRule[] =>
@@ -44,12 +47,7 @@ const defaultFormsAreRegistrySafe = (
     return false;
   }
 
-  const defaultForms = [
-    transition.from,
-    pluralizeVocabularyForm(transition.from),
-  ];
-
-  return defaultForms.every((form) => {
+  return defaultSourceForms(transition.from).every((form) => {
     const replacement = transition.safeRewriteForms[form];
     return replacement !== undefined && !transition.reviewForms.includes(form);
   });

package/src/downstream/vocabulary.ts

@@ -6,7 +6,14 @@ import {
   matchesAnyPathGlob,
 } from '@ontrails/core';
 import { createHash } from 'node:crypto';
-import { dirname, isAbsolute, join, normalize, relative } from 'node:path';
+import {
+  dirname,
+  extname,
+  isAbsolute,
+  join,
+  normalize,
+  relative,
+} from 'node:path';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { z } from 'zod';
 
@@ -213,30 +220,56 @@ const vocabularyDispositionCounts = (
   );
 };
 
-const isVocabularyTokenCharacter = (value: string): boolean =>
-  /[A-Za-z0-9_$-]/.test(value);
+const isVocabularyTokenCharacter = (
+  value: string,
+  routeLike: boolean
+): boolean => /[A-Za-z0-9_$-]/.test(value) || (routeLike && value === '/');
+
+const isVocabularyTokenCharacterAt = (
+  source: string,
+  index: number,
+  routeLike: boolean
+): boolean => {
+  if (index < 0 || index >= source.length) {
+    return false;
+  }
+  const value = source.at(index) ?? '';
+  if (isVocabularyTokenCharacter(value, routeLike)) {
+    return true;
+  }
+  if (!routeLike || value !== '.') {
+    return false;
+  }
+  return (
+    isVocabularyTokenCharacter(source.at(index - 1) ?? '', false) &&
+    isVocabularyTokenCharacter(source.at(index + 1) ?? '', false)
+  );
+};
 
 const hasWordBoundary = (
   source: string,
   start: number,
-  end: number
+  end: number,
+  form: string
 ): boolean => {
-  const before = start === 0 ? '' : (source.at(start - 1) ?? '');
-  const after = end >= source.length ? '' : (source.at(end) ?? '');
+  const routeLike = form.includes('/');
   return (
-    !isVocabularyTokenCharacter(before) && !isVocabularyTokenCharacter(after)
+    !isVocabularyTokenCharacterAt(source, start - 1, routeLike) &&
+    !isVocabularyTokenCharacterAt(source, end, routeLike)
   );
 };
 
 const expandVocabularyNeighborSpan = (
   source: string,
   start: number,
-  end: number
+  end: number,
+  form: string
 ): { readonly end: number; readonly start: number } => {
+  const routeLike = form.includes('/');
   let expandedStart = start;
   while (
     expandedStart > 0 &&
-    isVocabularyTokenCharacter(source.at(expandedStart - 1) ?? '')
+    isVocabularyTokenCharacterAt(source, expandedStart - 1, routeLike)
   ) {
     expandedStart -= 1;
   }
@@ -244,7 +277,7 @@ const expandVocabularyNeighborSpan = (
   let expandedEnd = end;
   while (
     expandedEnd < source.length &&
-    isVocabularyTokenCharacter(source.at(expandedEnd) ?? '')
+    isVocabularyTokenCharacterAt(source, expandedEnd, routeLike)
   ) {
     expandedEnd += 1;
   }
@@ -288,6 +321,24 @@ const contextDetailsForOffset = (
 const isMarkdownPath = (path: string): boolean =>
   path.endsWith('.md') || path.endsWith('.mdx');
 
+const packageRouteCodeExtensions = new Set([
+  '.cjs',
+  '.cts',
+  '.js',
+  '.jsx',
+  '.mjs',
+  '.mts',
+  '.ts',
+  '.tsx',
+]);
+
+const isPackageRouteCodeOccurrence = (path: string, form: string): boolean =>
+  packageRouteCodeExtensions.has(extname(path)) &&
+  /^@[^/]+\/[^/]+(?:\/.*)?$/.test(form);
+
+const isPackageManifestPath = (path: string): boolean =>
+  path === 'package.json' || path.endsWith('/package.json');
+
 const sourceLineBoundsForOffset = (
   source: string,
   start: number,
@@ -478,11 +529,13 @@ const defaultDeferredVocabularyForms = (from: string): readonly string[] => {
   ]).filter((form) => form !== from && form !== pluralize(from));
 };
 
-const defaultVocabularyForms = (from: string, to: string) =>
-  new Map<string, string>([
-    [from, to],
-    [pluralize(from), pluralize(to)],
-  ]);
+const defaultVocabularyForms = (from: string, to: string) => {
+  const forms = new Map<string, string>([[from, to]]);
+  if (isSimpleVocabularyWord(from) && isSimpleVocabularyWord(to)) {
+    forms.set(pluralize(from), pluralize(to));
+  }
+  return forms;
+};
 
 const normalizedOverrideEntries = (
   overrides: Readonly<Record<string, string>> | undefined
@@ -806,7 +859,7 @@ const exactDeferredFormOccurrencesForFile = (
         formIdentityForPlan(plan, form)
       );
       if (
-        !hasWordBoundary(file.source, start, end) ||
+        !hasWordBoundary(file.source, start, end, form) ||
         occurrenceOverlaps(occurrences, start, end) ||
         (!isAuthoredDefer && occurrenceOverlaps(targetFormSpans, start, end))
       ) {
@@ -840,7 +893,7 @@ const targetFormSpansForFile = (
       const start = match.index ?? 0;
       const end = start + match[0].length;
       if (
-        !hasWordBoundary(file.source, start, end) ||
+        !hasWordBoundary(file.source, start, end, form) ||
         occurrenceOverlaps(spans, start, end)
       ) {
         continue;
@@ -869,7 +922,7 @@ const occurrencesForFile = (
       const start = match.index ?? 0;
       const end = start + match[0].length;
       if (
-        !hasWordBoundary(file.source, start, end) ||
+        !hasWordBoundary(file.source, start, end, form) ||
         occurrenceOverlaps(deferredOccurrences, start, end)
       ) {
         continue;
@@ -889,10 +942,27 @@ const occurrencesForFile = (
       };
       const preserveRule = preserveRuleForOccurrence(baseOccurrence, plan);
       const markdownCodeContext = isMarkdownCodeContext(file, start, end);
-      const verdict = capturedVocabularyVerdict(
+      const packageRouteCodeContext = isPackageRouteCodeOccurrence(
+        file.path,
+        form
+      );
+      let verdict = capturedVocabularyVerdict(
         preserveRule,
         markdownCodeContext
       );
+      const packageManifestContext = isPackageManifestPath(file.path);
+      if (
+        preserveRule === undefined &&
+        (packageRouteCodeContext || packageManifestContext)
+      ) {
+        verdict = 'deferred';
+      }
+      let capturedReason = 'captured-form';
+      if (packageRouteCodeContext) {
+        capturedReason = 'package-route-ast-required';
+      } else if (packageManifestContext) {
+        capturedReason = 'package-manifest-structured-edit-required';
+      }
       candidates.push({
         absolutePath: baseOccurrence.absolutePath,
         column: baseOccurrence.column,
@@ -909,9 +979,12 @@ const occurrencesForFile = (
         reason: vocabularyOccurrenceReason(
           preserveRule,
           markdownCodeContext,
-          'captured-form'
+          capturedReason
         ),
-        ...(preserveRule === undefined && !markdownCodeContext
+        ...(preserveRule === undefined &&
+        !markdownCodeContext &&
+        !packageRouteCodeContext &&
+        !packageManifestContext
           ? { replacement: preserveCase(match[0], replacement) }
           : {}),
         start: baseOccurrence.start,
@@ -972,13 +1045,14 @@ const deferredOccurrencesForFile = (
     for (const match of file.source.matchAll(pattern)) {
       const matchStart = match.index ?? 0;
       const matchEnd = matchStart + match[0].length;
-      if (hasWordBoundary(file.source, matchStart, matchEnd)) {
+      if (hasWordBoundary(file.source, matchStart, matchEnd, form)) {
         continue;
       }
       const { end, start } = expandVocabularyNeighborSpan(
         file.source,
         matchStart,
-        matchEnd
+        matchEnd,
+        form
       );
       const matchedForm = file.source.slice(start, end);
       const lowerMatchedForm = matchedForm.toLowerCase();

package/src/literal-transform.ts

@@ -16,10 +16,10 @@ const childInput = z.object({
 });
 
 /**
- * Parent input schema with its raw-to-blaze transform attached.
+ * 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 blaze input
+ * pre-transform input (`z.input`) and its post-transform implementation input
  * (`z.infer`) without restating either shape by hand.
  */
 const regradeTransformInputToChild = regradeTransformInput.transform(
@@ -32,15 +32,15 @@ const regradeTransformInputToChild = regradeTransformInput.transform(
  * Raw, pre-transform input accepted by {@link regradeTransformInputToChild}.
  *
  * Trail examples and `testExamples()` feed this shape through validation; the
- * Zod transform then projects it into the blaze input.
+ * Zod transform then projects it into the implementation input.
  */
 type RegradeTransformRawInput = z.input<typeof regradeTransformInputToChild>;
 
 /**
- * Post-transform blaze input shape — the trail's inferred input type `I`.
+ * 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 blaze input), while examples and
+ * `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
@@ -49,7 +49,9 @@ type RegradeTransformRawInput = z.input<typeof regradeTransformInputToChild>;
  * 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 RegradeTransformBlazeInput = z.infer<typeof regradeTransformInputToChild>;
+type RegradeTransformImplementationInput = z.infer<
+  typeof regradeTransformInputToChild
+>;
 
 /**
  * Raw example input, statically checked as valid pre-transform input. If the
@@ -63,7 +65,7 @@ const codeStringExampleInput: RegradeTransformRawInput = {
 export const normalizeExportConstTrail = trail(
   'regrade.literal.normalize-export-const',
   {
-    blaze: (input) => {
+    implementation: (input) => {
       const nextSource = input.source.replaceAll('export const', 'export let');
       return Result.ok({
         changed: nextSource !== input.source,
@@ -81,17 +83,6 @@ export const normalizeExportConstTrail = trail(
 );
 
 export const literalRegradeTrail = trail('regrade.literal.run', {
-  blaze: async (input, ctx) => {
-    if (!ctx.compose) {
-      return Result.err(
-        new InternalError(
-          'Literal Regrade tracer requires compose-capable execution.'
-        )
-      );
-    }
-    const blazeInput = input as RegradeTransformBlazeInput;
-    return await ctx.compose(normalizeExportConstTrail, blazeInput.child);
-  },
   composes: [normalizeExportConstTrail],
   examples: [
     {
@@ -103,11 +94,26 @@ export const literalRegradeTrail = trail('regrade.literal.run', {
       // 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 RegradeTransformBlazeInput for why the two shapes diverge.
-      input: codeStringExampleInput as unknown as RegradeTransformBlazeInput,
+      // 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,
 });