Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

5.8 KB
Raw Blame
/**
 * Source-root scanning for guard tests.
 *
 * A guard that walks one hard-coded directory narrows silently when the code it guards moves: the
 * walk still succeeds, it just visits fewer files, and every "found nothing wrong" assertion stays
 * green over a tree that no longer holds the thing it was written for. The theme work moves
 * components from `packages/web/src` into `packages/ui/src` one wave at a time, so a guard scans a
 * named set of roots and reports, per root, how many files it actually read — a root that yields
 * nothing (a typo, a renamed directory, a package that moved) is a failure, never an empty pass.
 *
 * Node-only (`node:fs`) and framework-free: the caller asserts with its own test runner.
 */
import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
import { basename, join, relative, sep } from "node:path";

/** Root name → absolute directory, e.g. `{ web: ".../packages/web/src", ui: ".../packages/ui/src" }`. */
export type SourceRoots = Readonly<Record<string, string>>;

/** What a guard scans unless it asks otherwise: source and the stylesheets that sit beside it. */
export const DEFAULT_SOURCE_EXTENSIONS: readonly string[] = [".ts", ".tsx", ".css"];

/** Directories never descended into: installed or generated trees are not source. */
const SKIPPED_DIRECTORIES = new Set(["node_modules", "dist", ".vite", "coverage"]);

export interface SourceFile {
  /** The root's key in the {@link SourceRoots} record, e.g. `"web"`. */
  readonly root: string;
  /** Path relative to its root, forward slashes on every platform: `components/ui/icons.tsx`. */
  readonly rel: string;
  /**
   * Path relative to the repository root, forward slashes: `packages/web/src/components/ui/icons.tsx`.
   * The name a guard reports and expects, because it stays unambiguous across roots.
   */
  readonly id: string;
  /** Absolute path, platform separators. */
  readonly path: string;
  /** The file name alone: `icons.tsx`. */
  readonly name: string;
  /** The file's text, read on first access and cached. */
  readonly text: string;
}

export interface RootReport {
  readonly name: string;
  readonly dir: string;
  readonly exists: boolean;
  /** Files with a scanned extension found under the root. */
  readonly files: number;
}

export interface SourceScan {
  /** Every scanned file across every root, sorted by {@link SourceFile.id}. */
  readonly files: readonly SourceFile[];
  /** One report per root, in the order the roots were given. */
  readonly roots: readonly RootReport[];
}

export interface ScanOptions {
  /** The repository root that {@link SourceFile.id} is relative to. */
  readonly repoRoot: string;
  /** File extensions to include, with the dot. Defaults to {@link DEFAULT_SOURCE_EXTENSIONS}. */
  readonly extensions?: readonly string[];
}

const toPosix = (path: string): string => path.split(sep).join("/");

// Plain fields rather than constructor parameter properties, so the module stays erasable-syntax
// TypeScript that Node can also run directly.
class ScannedFile implements SourceFile {
  readonly root: string;
  readonly rel: string;
  readonly id: string;
  readonly path: string;
  #text: string | undefined;

  constructor(root: string, rel: string, id: string, path: string) {
    this.root = root;
    this.rel = rel;
    this.id = id;
    this.path = path;
  }

  get name(): string {
    return basename(this.path);
  }

  get text(): string {
    this.#text ??= readFileSync(this.path, "utf8");
    return this.#text;
  }
}

function walk(dir: string, extensions: readonly string[], out: string[]): void {
  for (const entry of readdirSync(dir, { withFileTypes: true })) {
    const path = join(dir, entry.name);
    if (entry.isDirectory()) {
      if (!SKIPPED_DIRECTORIES.has(entry.name)) walk(path, extensions, out);
    } else if (entry.isFile() && extensions.some((ext) => entry.name.endsWith(ext))) {
      out.push(path);
    }
  }
}

/**
 * Walks every root and returns its files plus a per-root count. A root that does not exist is
 * reported (`exists: false`, `files: 0`) rather than thrown, so the guard's own "every root was
 * scanned" assertion is what fails — with the root's name in the message.
 */
export function scanSourceRoots(roots: SourceRoots, options: ScanOptions): SourceScan {
  const extensions = options.extensions ?? DEFAULT_SOURCE_EXTENSIONS;
  const files: SourceFile[] = [];
  const reports: RootReport[] = [];
  for (const [name, dir] of Object.entries(roots)) {
    const exists = existsSync(dir) && statSync(dir).isDirectory();
    const paths: string[] = [];
    if (exists) walk(dir, extensions, paths);
    for (const path of paths) {
      files.push(
        new ScannedFile(
          name,
          toPosix(relative(dir, path)),
          toPosix(relative(options.repoRoot, path)),
          path,
        ),
      );
    }
    reports.push({ name, dir, exists, files: paths.length });
  }
  files.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
  return { files, roots: reports };
}

/**
 * One line per root that yielded no files, naming the root, its directory and why — empty when
 * every root was scanned. Guards assert this equals `[]`.
 */
export function unscannedRoots(scan: SourceScan): string[] {
  return scan.roots
    .filter((root) => root.files === 0)
    .map((root) =>
      root.exists
        ? `${root.name} (${root.dir}): no source files found`
        : `${root.name} (${root.dir}): directory does not exist`,
    );
}

/** The scanned file with this repo-relative id, or `undefined`. */
export function findSourceFile(scan: SourceScan, id: string): SourceFile | undefined {
  return scan.files.find((file) => file.id === id);
}

/** Every scanned file with this file name, across all roots — the input to a "one home" check. */
export function filesNamed(scan: SourceScan, name: string): SourceFile[] {
  return scan.files.filter((file) => file.name === name);
}