mod.ts

import {
  extractToml,
  extractYaml,
  test as hasFrontMatter,
} from "@std/front-matter";
import { basename, extname, join, relative } from "@std/path";
import type { SiteConfig, StenoPlugin } from "@steno/steno";

/**
 * Basic info about one page carried into a generated term page's
 * `steno.globals.items` array — exactly what a Tau layout needs to render
 * `{#each items as item}` (title, url, description, date).
 */
export interface TermPageInfo {
  /** Page title (frontmatter `title`, or a humanized filename fallback). */
  title: string;
  /** Site-relative route, e.g. `/posts/hello-world`. */
  url: string;
  /** Page description, if set. */
  description?: string;
  /** Page date as an ISO-ish string, if set. */
  date?: string;
}

/** One real content page as fed into {@link buildTermIndex}. */
export interface TaxonomyPageInput extends TermPageInfo {
  /** Every value this page carries in the configured taxonomy field. */
  terms: string[];
}

/** One distinct term and every page that carries it. */
export interface TermEntry {
  /** Term exactly as it appears in frontmatter (e.g. `"Rust"`). */
  term: string;
  /** URL-safe slug derived from `term`, unique within the taxonomy. */
  slug: string;
  /** Pages carrying this term, in the order they were scanned. */
  pages: TermPageInfo[];
}

/** Per-taxonomy configuration. */
export interface TaxonomyConfig {
  /**
   * Taxonomy identifier. Used as the route prefix (`content/<name>/`) and as
   * the default frontmatter field read from each page. Must be a bare path
   * segment: letters, digits, `-`, `_` only.
   */
  name: string;
  /** Frontmatter field read from each page. Defaults to `name`. Accepts a single value or an array. */
  field?: string;
  /**
   * Whether term pages should be eligible for per-term feeds. See the
   * README's "Feeds" section — this does **not** generate feed XML itself;
   * it only stamps `steno.globals.term.feed` for a theme/layout to act on.
   */
  feed?: boolean;
  /** Splits a term's page listing into pages of this size. `undefined` disables pagination. */
  paginateBy?: number;
  /** Static per-term metadata (icon, color, description, ...), keyed by the exact term string. */
  termMeta?: Record<string, Record<string, unknown>>;
  /** Layout for a single term page. Defaults to `"taxonomy-term"`. */
  layout?: string;
  /** Layout for the taxonomy's listing page. Defaults to `"taxonomy-list"`. */
  listLayout?: string;
}

/** Options accepted by this plugin. */
export interface PluginTaxonomyOptions {
  /** One entry per taxonomy. Required, non-empty. */
  taxonomies: TaxonomyConfig[];
  /** Content root to scan and write into. Defaults to `config.contentDir` (`content/`). */
  contentDir?: string;
}

const MARKER_COMMENT = "<!-- generated by plugin-taxonomy, do not edit -->";
const MARKER_FILENAME = ".plugin-taxonomy-generated";
const NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;

/**
 * Slugifies a taxonomy term into a URL-safe path segment: lowercased,
 * diacritics stripped, anything that isn't `[a-z0-9]` collapsed to a single
 * `-`, leading/trailing `-` trimmed. Falls back to `"term"` if nothing
 * survives (e.g. a term that's entirely punctuation/emoji).
 */
export function slugifyTerm(term: string): string {
  const slug = term
    .normalize("NFKD")
    .replace(/[\u0300-\u036f]/g, "")
    .toLowerCase()
    .trim()
    .replace(/[^a-z0-9]+/g, "-")
    .replace(/^-+|-+$/g, "");
  return slug || "term";
}

/**
 * Builds a term → pages index from a flat list of scanned pages. Pure — no
 * filesystem access, so it's directly unit-testable with plain objects.
 *
 * Terms are sorted alphabetically; slugs are assigned in that order, and a
 * collision (two distinct terms slugifying to the same value, e.g. `"C++"`
 * and `"C--"` both → `"c"`) is resolved by appending `-2`, `-3`, ... to
 * whichever term loses the tie.
 */
export function buildTermIndex(pages: TaxonomyPageInput[]): TermEntry[] {
  const byTerm = new Map<string, TermPageInfo[]>();

  for (const page of pages) {
    for (const raw of page.terms) {
      const term = raw.trim();
      if (!term) continue;
      const list = byTerm.get(term) ?? [];
      list.push({
        title: page.title,
        url: page.url,
        description: page.description,
        date: page.date,
      });
      byTerm.set(term, list);
    }
  }

  const usedSlugs = new Set<string>();
  const entries: TermEntry[] = [];

  for (const term of [...byTerm.keys()].sort((a, b) => a.localeCompare(b))) {
    const base = slugifyTerm(term);
    let slug = base;
    let suffix = 2;
    while (usedSlugs.has(slug)) {
      slug = `${base}-${suffix++}`;
    }
    usedSlugs.add(slug);
    entries.push({ term, slug, pages: byTerm.get(term)! });
  }

  return entries;
}

// ---------------------------------------------------------------------------
// Content-scanning helpers (fs-touching, not exported as "pure" API surface,
// but kept as small standalone functions for readability).
// ---------------------------------------------------------------------------

function readFrontMatter(text: string): Record<string, unknown> {
  if (!hasFrontMatter(text)) return {};
  try {
    if (text.startsWith("+++")) {
      return extractToml<Record<string, unknown>>(text).attrs;
    }
    return extractYaml<Record<string, unknown>>(text).attrs;
  } catch {
    return {};
  }
}

function humanize(stem: string): string {
  const spaced = stem.replace(/[-_]+/g, " ").trim();
  return spaced.replace(/\b\w/g, (letter) => letter.toUpperCase()) || stem;
}

function toRoute(relativePath: string, isIndex: boolean): string {
  const withoutExt = relativePath.slice(0, -extname(relativePath).length);
  const segments = withoutExt.split("/").filter(Boolean);
  if (isIndex) segments.pop();
  return "/" + segments.join("/") + (segments.length ? "/" : "");
}

function toIsoDate(value: unknown): string | undefined {
  if (value instanceof Date) return value.toISOString().slice(0, 10);
  if (typeof value === "string") return value;
  return undefined;
}

function readTerms(attrs: Record<string, unknown>, field: string): string[] {
  const value = attrs[field];
  if (Array.isArray(value)) return value.filter((v) => typeof v === "string");
  if (typeof value === "string") return [value];
  return [];
}

/** Recursively collects every real (non-generated) content page under `dir`. */
async function scanPages(
  dir: string,
  contentRoot: string,
  excludeDirs: Set<string>,
  field: string,
): Promise<TaxonomyPageInput[]> {
  let entries: Deno.DirEntry[] = [];
  try {
    entries = [...Deno.readDirSync(dir)];
  } catch {
    return [];
  }

  const pages: TaxonomyPageInput[] = [];

  for (const entry of entries) {
    if (entry.name.startsWith(".")) continue; // .steno/, dotfiles, our own marker file
    const fullPath = join(dir, entry.name);

    if (entry.isDirectory) {
      if (excludeDirs.has(fullPath)) continue; // a taxonomy's own generated output
      pages.push(...await scanPages(fullPath, contentRoot, excludeDirs, field));
      continue;
    }

    if (!entry.isFile || !entry.name.endsWith(".md")) continue;

    const text = await Deno.readTextFile(fullPath);
    const attrs = readFrontMatter(text);
    if (attrs.draft === true) continue;

    const relPath = relative(contentRoot, fullPath);
    const stem = basename(entry.name, extname(entry.name));
    const isIndex = stem === "index";
    const title = typeof attrs.title === "string"
      ? attrs.title
      : humanize(stem);
    const description = typeof attrs.description === "string"
      ? attrs.description
      : undefined;

    pages.push({
      title,
      url: toRoute(relPath, isIndex),
      description,
      date: toIsoDate(attrs.date),
      terms: readTerms(attrs, field),
    });
  }

  return pages;
}

function frontmatterBlock(fields: Record<string, unknown>): string {
  const lines = ["---"];
  for (const [key, value] of Object.entries(fields)) {
    if (value === undefined) continue;
    // JSON is a valid subset of YAML flow syntax, so this sidesteps needing
    // a YAML stringifier while still round-tripping cleanly through
    // @std/front-matter's YAML parser (arrays/objects included).
    lines.push(`${key}: ${JSON.stringify(value)}`);
  }
  lines.push("---", "");
  return lines.join("\n");
}

async function writeGeneratedFile(
  path: string,
  fields: Record<string, unknown>,
): Promise<void> {
  await Deno.mkdir(path.slice(0, path.lastIndexOf("/")), { recursive: true });
  await Deno.writeTextFile(
    path,
    frontmatterBlock(fields) + MARKER_COMMENT + "\n",
  );
}

/** Ensures `outputDir` is either absent or previously generated by this plugin, then empties it. */
async function resetGeneratedDir(
  outputDir: string,
  taxonomyName: string,
): Promise<void> {
  let stat: Deno.FileInfo;
  try {
    stat = await Deno.stat(outputDir);
  } catch {
    return; // doesn't exist yet — nothing to reset
  }

  if (!stat.isDirectory) {
    throw new Error(
      `taxonomy: content/${taxonomyName} exists and is not a directory. Rename it or choose a different taxonomies[].name.`,
    );
  }

  const markerPath = join(outputDir, MARKER_FILENAME);
  const isOurs = await Deno.stat(markerPath).then(() => true).catch(() =>
    false
  );
  if (!isOurs) {
    throw new Error(
      `taxonomy: refusing to overwrite content/${taxonomyName}/ — it already exists and wasn't generated by ` +
        `plugin-taxonomy (no ${MARKER_FILENAME} marker found inside it). Rename or remove that folder, or pick ` +
        `a different taxonomies[].name.`,
    );
  }

  await Deno.remove(outputDir, { recursive: true });
}

function chunk<T>(items: T[], size: number): T[][] {
  const chunks: T[][] = [];
  for (let i = 0; i < items.length; i += size) {
    chunks.push(items.slice(i, i + size));
  }
  return chunks;
}

async function generateTaxonomy(
  contentRoot: string,
  taxonomy: TaxonomyConfig,
  allPages: TaxonomyPageInput[],
): Promise<void> {
  if (!NAME_PATTERN.test(taxonomy.name)) {
    throw new Error(
      `taxonomy: invalid taxonomies[].name "${taxonomy.name}" — must match ${NAME_PATTERN} (used as a content/ path segment).`,
    );
  }

  const outputDir = join(contentRoot, taxonomy.name);
  await resetGeneratedDir(outputDir, taxonomy.name);
  await Deno.mkdir(outputDir, { recursive: true });
  await Deno.writeTextFile(
    join(outputDir, MARKER_FILENAME),
    MARKER_COMMENT + "\n",
  );

  const entries = buildTermIndex(allPages);
  const listLayout = taxonomy.listLayout ?? "taxonomy-list";
  const termLayout = taxonomy.layout ?? "taxonomy-term";
  const perPage = taxonomy.paginateBy;

  const listTerms = entries.map((entry) => ({
    name: entry.term,
    slug: entry.slug,
    url: `/${taxonomy.name}/${entry.slug}/`,
    count: entry.pages.length,
    ...taxonomy.termMeta?.[entry.term],
  }));

  await writeGeneratedFile(join(outputDir, "index.md"), {
    title: humanize(taxonomy.name),
    layout: listLayout,
    steno: {
      globals: {
        taxonomy: taxonomy.name,
        terms: listTerms,
      },
    },
  });

  for (const entry of entries) {
    const pageChunks = perPage && perPage > 0
      ? chunk(entry.pages, perPage)
      : [entry.pages];
    const totalPages = pageChunks.length;

    for (let i = 0; i < pageChunks.length; i++) {
      const pageNum = i + 1;
      const filePath = pageNum === 1
        ? join(outputDir, `${entry.slug}.md`)
        : join(outputDir, entry.slug, "page", `${pageNum}.md`);

      await writeGeneratedFile(filePath, {
        title: entry.term,
        layout: termLayout,
        steno: {
          globals: {
            taxonomy: taxonomy.name,
            term: {
              name: entry.term,
              slug: entry.slug,
              count: entry.pages.length,
              feed: taxonomy.feed ?? false,
              ...taxonomy.termMeta?.[entry.term],
            },
            items: pageChunks[i],
            pagination: {
              page: pageNum,
              totalPages,
              perPage: perPage ?? entry.pages.length,
            },
          },
        },
      });
    }
  }
}

/**
 * Creates the plugin-taxonomy plugin.
 *
 * Steno's `StenoPlugin` contract has no hook for registering brand-new
 * routes directly — `afterPage`/`afterBuild` only ever see pages Steno
 * already rendered from real content files. This plugin uses the same
 * technique as the official `@steno/plugin-docs` plugin: in `beforeBuild`,
 * before Steno's own content discovery runs, it scans every real page under
 * `contentDir`, groups them by the configured frontmatter field, and writes
 * synthetic Markdown files into `contentDir/<name>/` — one per term plus a
 * listing index. Steno then discovers and renders them completely normally,
 * through the theme, with layouts, everything. See the README for the full
 * rationale and the exact shape written to `steno.globals`.
 *
 * ```yaml
 * plugins:
 *   - package: jsr:@you/plugin-taxonomy
 *     options:
 *       taxonomies:
 *         - name: tags
 *           feed: true
 *           paginateBy: 10
 *         - name: categories
 *           feed: true
 * ```
 */
export default function pluginTaxonomy(
  options: PluginTaxonomyOptions,
): StenoPlugin {
  if (!options?.taxonomies || options.taxonomies.length === 0) {
    throw new Error("taxonomy: options.taxonomies must be a non-empty array.");
  }
  for (const taxonomy of options.taxonomies) {
    if (!NAME_PATTERN.test(taxonomy.name)) {
      throw new Error(
        `taxonomy: invalid taxonomies[].name "${taxonomy.name}" — must match ${NAME_PATTERN} (used as a content/ path segment).`,
      );
    }
  }

  return {
    name: "plugin-taxonomy",

    async beforeBuild(config: SiteConfig) {
      const contentRoot = options.contentDir ?? config.contentDir ?? "content";
      const excludeDirs = new Set(
        options.taxonomies.map((t) => join(contentRoot, t.name)),
      );

      for (const taxonomy of options.taxonomies) {
        const field = taxonomy.field ?? taxonomy.name;
        const pages = await scanPages(
          contentRoot,
          contentRoot,
          excludeDirs,
          field,
        );
        await generateTaxonomy(contentRoot, taxonomy, pages);
      }
    },
  };
}