populateLibraries.ts

import { readdir, readFile, writeFile } from "node:fs/promises";
import { join } from "node:path";

const UTF8: BufferEncoding = "utf8";
const MARKERS = {
  start: "<!-- START: Auto-generated by ./populateLibraries.ts -->",
  end: "<!-- END: Auto-generated by ./populateLibraries.ts -->",
} as const;

interface LibraryEntry {
  name: string;
  description: string;
}

interface FileUpdate {
  path: string;
  label: string;
  formatLine: (entry: LibraryEntry) => string;
}

interface PackageMetadata {
  description?: string;
}

const FILES: FileUpdate[] = [
  {
    path: join(__dirname, "README.md"),
    label: "README.md '## Libraries'",
    formatLine: (entry) =>
      `- [${entry.name}](./packages/${entry.name}/README.md): ${entry.description}`,
  },
  {
    path: join(__dirname, "packages", "ai-rules", "rules", "common", "coreLibraries.md"),
    label: "ai-rules coreLibraries.md",
    formatLine: (entry) => `- **${entry.name}**: ${entry.description}`,
  },
];

async function getLibraryEntries(): Promise<LibraryEntry[]> {
  const entries = await readdir(join(__dirname, "packages"), {
    withFileTypes: true,
  });
  const directories = entries.filter((dirent) => dirent.isDirectory());

  const results = await Promise.allSettled(
    directories.map(async (dirent) => {
      const path = join(__dirname, "packages", dirent.name, "package.json");
      const parsed = parsePackageMetadata(await readFile(path, UTF8));
      return { name: dirent.name, description: parsed.description ?? "" };
    }),
  );

  const rejected = results.filter(
    (result): result is PromiseRejectedResult => result.status === "rejected",
  );
  if (rejected.length > 0) {
    console.warn(
      `Skipped ${rejected.length} package.json file(s):`,
      rejected.map((r) => String(r.reason)),
    );
  }

  return results
    .filter(
      (result): result is PromiseFulfilledResult<LibraryEntry> => result.status === "fulfilled",
    )
    .map((result) => result.value);
}

function parsePackageMetadata(value: string): PackageMetadata {
  const parsed: unknown = JSON.parse(value);
  if (typeof parsed !== "object" || parsed === null) {
    return {};
  }

  if (!("description" in parsed)) {
    return {};
  }

  return typeof parsed.description === "string" ? { description: parsed.description } : {};
}

async function updateFile(file: FileUpdate, entries: readonly LibraryEntry[]): Promise<void> {
  const content = await readFile(file.path, UTF8);
  const lines = entries.map((entry) => file.formatLine(entry));

  const updated = content.replace(
    new RegExp(`${MARKERS.start}[\\s\\S]*${MARKERS.end}`),
    `${MARKERS.start}\n\n${lines.join("\n")}\n\n${MARKERS.end}`,
  );

  if (content === updated) {
    console.log(`No changes to ${file.label} section.`);
    return;
  }

  await writeFile(file.path, updated, UTF8);
}

async function updateLibraries(): Promise<void> {
  const entries = await getLibraryEntries();
  await Promise.all(
    FILES.map(async (file) => {
      await updateFile(file, entries);
    }),
  );
}

void updateLibraries();