@ontrails/regrade 0.2.0

package/src/downstream/collect.ts

@@ -0,0 +1,240 @@
+import {
+  NotFoundError,
+  Result,
+  matchesAnyPathGlob,
+  trail,
+} from '@ontrails/core';
+import { collectSourceTree } from '@ontrails/source';
+import { z } from 'zod';
+
+/**
+ * Downstream source collection (TRL-844).
+ *
+ * Walks an explicit downstream-repo root and collects the deterministic set of
+ * candidate source files a regrade may operate on, alongside the entries it
+ * skipped and why. This is the engine substrate for the downstream Regrade
+ * work; it has no public CLI and reads only the root it is given.
+ *
+ * The interesting decision logic — which entries are collected, recursed into,
+ * or skipped with a reason — lives in the pure {@link classifyDownstreamEntry}
+ * helper so it can be exercised without touching the filesystem.
+ */
+
+/** Directory names never descended into during collection. */
+export const DEFAULT_IGNORED_DIRECTORIES: readonly string[] = Object.freeze([
+  '.git',
+  '.trails',
+  '.turbo',
+  'dist',
+  'node_modules',
+]);
+
+/** Source file extensions collected by default. */
+export const DEFAULT_SOURCE_EXTENSIONS: readonly string[] = Object.freeze([
+  '.ts',
+  '.tsx',
+]);
+
+/** Kind of a raw directory entry as reported by the filesystem walk. */
+export type DownstreamEntryKind = 'directory' | 'file' | 'other';
+
+/** A collected candidate source file. */
+export interface CollectedSource {
+  /** Root-relative POSIX path, used as the stable identity for the entry. */
+  readonly path: string;
+  /** Absolute path on disk. */
+  readonly absolutePath: string;
+}
+
+/** An entry that was inspected but not collected, with a machine-readable reason. */
+export interface SkippedSource {
+  /** Root-relative POSIX path of the skipped entry. */
+  readonly path: string;
+  /** Why the entry was skipped, e.g. `ignored-directory`. */
+  readonly reason: string;
+}
+
+/** Deterministic result of collecting downstream sources from a root. */
+export interface DownstreamSourceCollection {
+  /** The root the collection ran against. */
+  readonly root: string;
+  /** Collected candidate source files, sorted by `path`. */
+  readonly files: readonly CollectedSource[];
+  /** Skipped entries with reasons, sorted by `path`. */
+  readonly skipped: readonly SkippedSource[];
+}
+
+/** Options shared by the classifier and the filesystem walk. */
+export interface DownstreamCollectionOptions {
+  /** Directory names to skip. Defaults to {@link DEFAULT_IGNORED_DIRECTORIES}. */
+  readonly ignoredDirectories?: readonly string[];
+  /** Source extensions to collect. Defaults to {@link DEFAULT_SOURCE_EXTENSIONS}. */
+  readonly extensions?: readonly string[];
+  /** Root-relative path globs to skip before collection. */
+  readonly exclude?: readonly string[];
+  /** Root-relative path globs to collect. Omit to collect all matching files. */
+  readonly include?: readonly string[];
+}
+
+/** Outcome of classifying a single directory entry. */
+export type DownstreamEntryClassification =
+  | { readonly action: 'collect' }
+  | { readonly action: 'recurse' }
+  | { readonly action: 'skip'; readonly reason: string };
+
+const extensionOf = (name: string): string => {
+  const dot = name.lastIndexOf('.');
+  return dot <= 0 ? '' : name.slice(dot);
+};
+
+const normalizeExtension = (extension: string): string =>
+  extension === '' || extension.startsWith('.') ? extension : `.${extension}`;
+
+const collectionExtensions = (
+  extensions: readonly string[] | undefined
+): readonly string[] =>
+  extensions === undefined
+    ? DEFAULT_SOURCE_EXTENSIONS
+    : extensions.map(normalizeExtension);
+
+/**
+ * Decide what to do with a single directory entry. Pure: no filesystem access,
+ * so collection policy can be tested directly with synthetic entries.
+ */
+export const classifyDownstreamEntry = (
+  name: string,
+  kind: DownstreamEntryKind,
+  options: DownstreamCollectionOptions = {}
+): DownstreamEntryClassification => {
+  const ignoredDirectories =
+    options.ignoredDirectories ?? DEFAULT_IGNORED_DIRECTORIES;
+  const extensions = collectionExtensions(options.extensions);
+
+  if (kind === 'directory') {
+    return ignoredDirectories.includes(name)
+      ? { action: 'skip', reason: 'ignored-directory' }
+      : { action: 'recurse' };
+  }
+  if (kind === 'other') {
+    return { action: 'skip', reason: 'unsupported-entry' };
+  }
+  return extensions.length === 0 || extensions.includes(extensionOf(name))
+    ? { action: 'collect' }
+    : { action: 'skip', reason: 'unsupported-extension' };
+};
+
+const isImmutableRegradeHistoryDirectory = (path: string): boolean =>
+  path === '.trails/regrade/history' ||
+  path.endsWith('/.trails/regrade/history');
+
+/**
+ * Walk an explicit downstream root and collect candidate source files.
+ *
+ * Never throws: an unreadable root yields `null` (the trail maps that to a
+ * `NotFoundError`), and unreadable subdirectories are recorded as skipped
+ * entries. Output is deterministic — files and skipped entries are sorted by
+ * their root-relative POSIX path.
+ */
+export const collectDownstreamSources = (
+  root: string,
+  options: DownstreamCollectionOptions = {}
+): DownstreamSourceCollection | null =>
+  collectSourceTree(root, {
+    classify: ({ kind, name, path }) => {
+      if (matchesAnyPathGlob(path, options.exclude)) {
+        return { action: 'skip', reason: 'ignored-glob' };
+      }
+      if (kind === 'directory' && isImmutableRegradeHistoryDirectory(path)) {
+        return { action: 'skip', reason: 'immutable-regrade-history' };
+      }
+      const classification = classifyDownstreamEntry(name, kind, options);
+      if (
+        classification.action === 'collect' &&
+        options.include !== undefined &&
+        options.include.length > 0 &&
+        !matchesAnyPathGlob(path, options.include)
+      ) {
+        return { action: 'skip', reason: 'not-included-glob' };
+      }
+      return classification;
+    },
+  });
+
+export const collectDownstreamSourcesInput = z.object({
+  exclude: z
+    .array(z.string())
+    .optional()
+    .describe('Root-relative path globs to skip before collection'),
+  extensions: z
+    .array(z.string())
+    .optional()
+    .describe('Source file extensions to collect (defaults to .ts and .tsx)'),
+  ignoredDirectories: z
+    .array(z.string())
+    .optional()
+    .describe('Directory names to skip during collection'),
+  include: z
+    .array(z.string())
+    .optional()
+    .describe('Root-relative path globs to collect'),
+  root: z
+    .string()
+    .describe('Absolute path to the downstream repo root to scan'),
+});
+
+export const collectDownstreamSourcesOutput = z.object({
+  files: z
+    .array(
+      z.object({
+        absolutePath: z.string().describe('Absolute path on disk'),
+        path: z.string().describe('Root-relative POSIX path'),
+      })
+    )
+    .describe('Collected candidate source files, sorted by path'),
+  root: z.string().describe('Root the collection ran against'),
+  skipped: z
+    .array(
+      z.object({
+        path: z.string().describe('Root-relative POSIX path'),
+        reason: z.string().describe('Why the entry was skipped'),
+      })
+    )
+    .describe('Skipped entries with reasons, sorted by path'),
+});
+
+/**
+ * Engine trail that collects downstream source files from an explicit root.
+ *
+ * No examples are authored: the input is an absolute filesystem path, which
+ * cannot be encoded as a portable literal. Correctness is proven by the
+ * collector unit tests (synthetic classifier cases and temp-directory walks)
+ * and, from TRL-846, the committed Radio-shaped fixture.
+ */
+export const collectDownstreamSourcesTrail = trail(
+  'regrade.downstream.collect',
+  {
+    implementation: (input) => {
+      const collection = collectDownstreamSources(input.root, {
+        ...(input.extensions === undefined
+          ? {}
+          : { extensions: input.extensions }),
+        ...(input.exclude === undefined ? {} : { exclude: input.exclude }),
+        ...(input.include === undefined ? {} : { include: input.include }),
+        ...(input.ignoredDirectories === undefined
+          ? {}
+          : { ignoredDirectories: input.ignoredDirectories }),
+      });
+      if (collection === null) {
+        return Result.err(
+          new NotFoundError(
+            `Downstream root "${input.root}" could not be read as a directory.`
+          )
+        );
+      }
+      return Result.ok(collection);
+    },
+    input: collectDownstreamSourcesInput,
+    intent: 'read',
+    output: collectDownstreamSourcesOutput,
+  }
+);