@orbytes/astrolab 0.3.0 → 0.4.0-next.2

package/src/chrome/site-data.ts

@@ -0,0 +1,230 @@
+// The site's own pages and images, read off disk for the Pages and Assets views. Server-side only.
+//
+// Pages come from the same walk the live derivation uses (../shell/live-files.mjs), so the Pages
+// tree and the live pills can never disagree about what a page is or what it mounts.
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { root } from "astro:config/server";
+import { pageComponentFiles, pageRoute, sitePages, templateOf } from "../shell/live-files.mjs";
+import type { TreeNode } from "./model";
+import { hrefs } from "./model";
+
+export const rootDir = fileURLToPath(root);
+
+export interface SitePage {
+  /** repo-relative, e.g. src/pages/legal/terms.astro */
+  file: string;
+  /** "/", "/legal/terms", "/blog/[slug]" */
+  route: string;
+  /** the lab URL that shows it */
+  href: string;
+  label: string;
+  /** the first `title="…"` in its template — usually the layout's title prop */
+  title: string | null;
+  /** a route with a parameter cannot be shown without one of its generated paths */
+  dynamic: boolean;
+  /** the components it mounts, in document order (repo-relative) */
+  mounts: string[];
+}
+
+/** "terms-and-conditions" → "Terms and conditions"; the home page is "Home". */
+const labelOf = (route: string) => {
+  if (route === "/") return "Home";
+  const last = route.split("/").filter(Boolean).pop() ?? route;
+  if (last.startsWith("[")) return last;
+  const words = last.replace(/[-_]+/g, " ").trim();
+  return words.charAt(0).toUpperCase() + words.slice(1);
+};
+
+const titleOf = (file: string): string | null => {
+  try {
+    const template = templateOf(readFileSync(path.join(rootDir, file), "utf8"));
+    const m = template.match(/\btitle=["']([^"']{1,160})["']/);
+    return m ? m[1]! : null;
+  } catch {
+    return null;
+  }
+};
+
+export const sitePagesModel = (): SitePage[] =>
+  sitePages(rootDir).map((file) => {
+    const route = pageRoute(file);
+    return {
+      file,
+      route,
+      href: hrefs.page(route),
+      label: labelOf(route),
+      title: titleOf(file),
+      dynamic: route.includes("["),
+      mounts: pageComponentFiles(rootDir, file),
+    };
+  });
+
+/**
+ * The Pages tree, nested by folder the way the routes nest. A folder that has its own index page
+ * is both a group and a link (Figma: `Services` with `Page 1` and `Page 2` under it).
+ */
+export const pagesTree = (pages: SitePage[], currentRoute?: string): TreeNode[] => {
+  interface Branch {
+    node: TreeNode;
+    kids: Map<string, Branch>;
+  }
+  const top: Branch = { node: { id: "pages", label: "" }, kids: new Map() };
+  const nodeFor = (page: SitePage): TreeNode => ({
+    id: `page:${page.route}`,
+    label: page.label,
+    href: page.dynamic ? undefined : page.href,
+    icon: "page",
+    current: page.route === currentRoute,
+    disabled: page.dynamic,
+    title: page.dynamic
+      ? "A dynamic route — the lab needs one of its generated paths to show it"
+      : (page.title ?? page.route),
+    search: `${page.route} ${page.title ?? ""} ${page.file}`.toLowerCase(),
+    facets: page.dynamic ? "dynamic" : page.mounts.length ? "mounts" : "static",
+  });
+
+  const home = pages.find((page) => page.route === "/");
+  if (home) top.kids.set("", { node: nodeFor(home), kids: new Map() });
+
+  for (const page of pages) {
+    if (page.route === "/") continue;
+    const segments = page.route.split("/").filter(Boolean);
+    let branch = top;
+    let prefix = "";
+    for (const [i, segment] of segments.entries()) {
+      prefix += `/${segment}`;
+      let next = branch.kids.get(segment);
+      const isPage = i === segments.length - 1;
+      if (!next) {
+        next = {
+          node: isPage
+            ? nodeFor(page)
+            : { id: `dir:${prefix}`, label: labelOf(prefix), icon: "folder", search: prefix.toLowerCase() },
+          kids: new Map(),
+        };
+        branch.kids.set(segment, next);
+      } else if (isPage) {
+        // A folder we already made turns out to have its own index page: it becomes that page.
+        next.node = { ...nodeFor(page), id: next.node.id };
+      }
+      branch = next;
+    }
+  }
+
+  const build = (branch: Branch): TreeNode[] =>
+    [...branch.kids.values()].map(({ node, kids }) => {
+      if (!kids.size) return node;
+      const children = build({ node, kids });
+      return { ...node, icon: node.href ? "page" : "folder", children };
+    });
+  return build(top);
+};
+
+// ---- assets -------------------------------------------------------------------------------------
+
+export interface SiteAsset {
+  /** repo-relative */
+  file: string;
+  /** for anchors: `asset-src-assets-images-hero-aurora-webp` */
+  id: string;
+  name: string;
+  folder: string;
+  where: "src" | "public";
+  bytes: number;
+  ext: string;
+  /** repo-relative files that reference it */
+  usedBy: string[];
+}
+
+const IMAGE = /\.(png|jpe?g|webp|avif|gif|svg)$/i;
+const SOURCE = /\.(astro|[cm]?[jt]sx?|mdx?|css|scss|sass|less|json|html|ya?ml)$/i;
+const SKIP_DIRS = new Set(["node_modules", "dist", ".git", ".astro"]);
+
+const walk = (dir: string, test: RegExp, out: string[] = []): string[] => {
+  const abs = path.join(rootDir, dir);
+  if (!existsSync(abs)) return out;
+  for (const entry of readdirSync(abs, { withFileTypes: true })) {
+    if (entry.name.startsWith(".") || SKIP_DIRS.has(entry.name)) continue;
+    const rel = `${dir}/${entry.name}`;
+    if (entry.isDirectory()) walk(rel, test, out);
+    else if (test.test(entry.name)) out.push(rel);
+  }
+  return out;
+};
+
+/**
+ * Every image under src/ and public/, with who references it. "References" is textual: a source
+ * file under src/ that contains the image's `folder/name` (or, for a file at the top of its tree,
+ * its name). That covers an `import` of an src/ asset and a `/images/x.png` string for a public one,
+ * and it is exactly as good as a grep — a name built at runtime from parts is not seen. Good enough
+ * to find what nothing uses, which is the question this view answers.
+ */
+export const siteAssetsModel = (): SiteAsset[] => {
+  const files = [...walk("src", IMAGE), ...walk("public", IMAGE)];
+  const sources = walk("src", SOURCE).map((file) => ({
+    file,
+    text: (() => {
+      try {
+        return readFileSync(path.join(rootDir, file), "utf8");
+      } catch {
+        return "";
+      }
+    })(),
+  }));
+  return files
+    .map((file) => {
+      const name = path.posix.basename(file);
+      const parent = path.posix.basename(path.posix.dirname(file));
+      const where = file.startsWith("public/") ? "public" : "src";
+      const needle = parent && parent !== "src" && parent !== "public" ? `${parent}/${name}` : name;
+      let bytes = 0;
+      try {
+        bytes = statSync(path.join(rootDir, file)).size;
+      } catch {
+        /* vanished between the walk and the stat */
+      }
+      return {
+        file,
+        id: `asset-${file.replace(/[^a-z0-9]+/gi, "-").toLowerCase()}`,
+        name,
+        folder: path.posix.dirname(file),
+        where: where as SiteAsset["where"],
+        bytes,
+        ext: path.posix.extname(name).slice(1).toLowerCase(),
+        usedBy: sources.filter((s) => s.file !== file && s.text.includes(needle)).map((s) => s.file),
+      };
+    })
+    .sort((a, b) => a.file.localeCompare(b.file));
+};
+
+export const assetsTree = (assets: SiteAsset[]): TreeNode[] => {
+  const folders = new Map<string, SiteAsset[]>();
+  for (const asset of assets) {
+    const list = folders.get(asset.folder) ?? [];
+    list.push(asset);
+    folders.set(asset.folder, list);
+  }
+  return [...folders.entries()].map(([folder, list]) => ({
+    id: `assets:${folder}`,
+    label: folder.replace(/^(src|public)\/(assets\/)?/, "") || folder,
+    icon: "folder" as const,
+    title: folder,
+    count: list.length,
+    search: folder.toLowerCase(),
+    children: list.map((asset) => ({
+      id: asset.id,
+      label: asset.name,
+      href: `#${asset.id}`,
+      icon: "assets" as const,
+      dot: asset.usedBy.length ? undefined : ("muted" as const),
+      dotTitle: asset.usedBy.length ? undefined : "nothing references it",
+      facets: asset.usedBy.length ? "used" : "unused",
+      search: `${asset.file} ${asset.ext}`.toLowerCase(),
+    })),
+  }));
+};
+
+export const formatBytes = (bytes: number) =>
+  bytes < 1024 ? `${bytes} B` : bytes < 1024 * 1024 ? `${(bytes / 1024).toFixed(0)} KB` : `${(bytes / 1048576).toFixed(1)} MB`;

package/src/chrome/trees.ts

@@ -0,0 +1,257 @@
+// Level 2's trees, built from the lab index and the site's files. Server-side only.
+//
+// THE TREE STOPS AT THE COMPONENT (decided 2026-09-24). A component's stories are its variants,
+// chosen in the navbar, not rows here, so a leaf is one stories module and links to its first
+// story. Folders above it are the directories under the tier, with one fold: a directory holding
+// exactly one module and nothing else IS that module, so `Section01Hero › V1 › Section01Hero`
+// reads `Section01Hero › V1`.
+//
+// THE SECTIONS TIER IS DIFFERENT (decided 2026-09-24): its level 2 is the Sections tree
+// (./SectionsTree.astro) — one row per section with its slot on the page, the sections the site
+// mounts first, the rest grouped under them. See sectionsTree below.
+import type { LabItem, LabIndex } from "../shell/lab-index";
+import { livePillText } from "../shell/lab-index";
+import { sectionsTier, type TreeNode } from "./model";
+
+/**
+ * One stories module — a component — with its stories sorted by export name, not in file order:
+ * the core's getExports (src/core/utils/get-exports.ts) sorts them, and nothing after it re-orders.
+ */
+export interface LabComponent {
+  moduleId: string;
+  moduleName: string;
+  moduleFile: string;
+  componentFile: string | null;
+  directory: string;
+  tier: string;
+  section: string | null;
+  version: string | null;
+  stories: LabItem[];
+  live: boolean;
+  usedBy: string[];
+  responsive: LabItem["responsive"];
+  tags: string[];
+  summary: string | null;
+}
+
+export const componentsOf = (index: LabIndex): LabComponent[] => {
+  const byModule = new Map<string, LabComponent>();
+  for (const item of index.items) {
+    let mod = byModule.get(item.moduleId);
+    if (!mod) {
+      mod = {
+        moduleId: item.moduleId,
+        moduleName: item.moduleName,
+        moduleFile: item.moduleFile,
+        componentFile: item.componentFile,
+        directory: item.directory,
+        tier: item.tier,
+        section: item.section,
+        version: item.version,
+        stories: [],
+        live: false,
+        usedBy: item.usedBy,
+        responsive: item.responsive,
+        tags: item.tags,
+        summary: item.summary,
+      };
+      byModule.set(item.moduleId, mod);
+    }
+    mod.stories.push(item);
+    if (item.live) mod.live = true;
+  }
+  return [...byModule.values()];
+};
+
+/** What the dot, the filter and the search know about a component. */
+export const componentState = (mod: LabComponent) => {
+  const first = mod.stories[0]!;
+  const live = mod.live ? livePillText(mod.stories.find((s) => s.live) ?? first) : null;
+  const facets = [
+    mod.live ? "live" : mod.usedBy.length ? "used" : "unused",
+    mod.responsive ? (mod.responsive.done ? "responsive" : "unresponsive") : "",
+  ].filter(Boolean);
+  return {
+    dot: mod.live ? ("live" as const) : mod.usedBy.length ? ("used" as const) : undefined,
+    dotTitle: live ?? (mod.usedBy.length ? `used by ${mod.usedBy.length}` : undefined),
+    facets: facets.join(" "),
+    search: [
+      mod.moduleName,
+      mod.section,
+      mod.version,
+      mod.tier,
+      first.livePage,
+      ...facets,
+      ...mod.tags,
+      ...mod.stories.map((s) => s.storyName),
+    ]
+      .filter(Boolean)
+      .join(" ")
+      .toLowerCase(),
+  };
+};
+
+interface Dir {
+  name: string;
+  path: string;
+  dirs: Map<string, Dir>;
+  mods: LabComponent[];
+}
+
+/** Where a component is mounted — its primary mount (the home page's, when it is on it) — or null. */
+const mountOf = (mod: LabComponent): { n: number; of: number; page: string } | null => {
+  const story = mod.stories.find((s) => s.live && s.livePage);
+  return story ? { n: story.live!.slot, of: story.live!.of, page: story.livePage! } : null;
+};
+
+const byName = (a: string, b: string) => a.localeCompare(b, undefined, { numeric: true, sensitivity: "base" });
+
+/** A section module's version folder (`V1`), read from its directory when the index has none. */
+const versionOf = (mod: LabComponent): string | null => mod.version ?? mod.directory.split("/")[2] ?? null;
+
+/** Home page first, then the other pages by route, then top to bottom. */
+const bySlot = (a: { n: number; page: string }, b: { n: number; page: string }) =>
+  a.page === b.page ? a.n - b.n : a.page === "/" ? -1 : b.page === "/" ? 1 : byName(a.page, b.page);
+
+/**
+ * The Sections tree (decided 2026-09-24). One row per section, with a slot badge: the sections the
+ * site mounts come first, each badged with its slot; the rest follow under their own heading,
+ * badged with a dash. A section's versions sit under its row, unbadged, and are drawn only while
+ * you are on one of them — the tree still stops at the component. A version no page mounts is
+ * listed in the unslotted group as "Section · Version" even when a sibling version is mounted,
+ * because that is where you look for what is not on the site.
+ *
+ * Rows come out in slot order, which is also the order previous / next and the cards follow. Each
+ * root row carries its rank in both sort orders; the viewer's choice between them is theirs, kept
+ * in their browser and applied on the page (./SectionsTree.astro, ./shell-client.ts).
+ *
+ * Leaves keep the `mod:<moduleId>` id every other tree uses, so a caller walking the leaves for
+ * previous / next gets exactly the section versions, in order.
+ */
+const sectionsTree = (mods: LabComponent[], currentModuleId?: string): TreeNode[] => {
+  const groups = new Map<string, LabComponent[]>();
+  for (const mod of mods) {
+    const name = mod.section ?? mod.directory.split("/")[1] ?? mod.moduleName;
+    groups.set(name, [...(groups.get(name) ?? []), mod]);
+  }
+
+  const leaf = (mod: LabComponent, label: string, extra: Partial<TreeNode> = {}): TreeNode => {
+    const state = componentState(mod);
+    return {
+      id: `mod:${mod.moduleId}`,
+      label,
+      href: mod.stories[0]!.dashboardUrl,
+      current: mod.moduleId === currentModuleId,
+      facets: state.facets,
+      search: state.search,
+      title: label === mod.moduleName ? undefined : mod.moduleName,
+      ...extra,
+    };
+  };
+
+  const slotted: (TreeNode & { slot: NonNullable<TreeNode["slot"]> })[] = [];
+  const unslotted: TreeNode[] = [];
+  for (const [name, list] of groups) {
+    const versions = [...list].sort((a, b) => byName(versionOf(a) ?? a.moduleName, versionOf(b) ?? b.moduleName));
+    const mounted = versions
+      .map((mod) => ({ mod, mount: mountOf(mod) }))
+      .filter((v): v is { mod: LabComponent; mount: NonNullable<ReturnType<typeof mountOf>> } => v.mount !== null)
+      .sort((a, b) => bySlot(a.mount, b.mount));
+    const lead = mounted[0];
+    if (lead) {
+      if (versions.length === 1 && !versionOf(lead.mod)) {
+        // A section with no version folders is its own module: one row, badged, no children.
+        slotted.push({ ...leaf(lead.mod, name), slot: lead.mount, group: "slotted" });
+      } else {
+        const state = componentState(lead.mod);
+        slotted.push({
+          id: `sec:${lead.mod.tier}/${name}`,
+          label: name,
+          href: lead.mod.stories[0]!.dashboardUrl,
+          slot: lead.mount,
+          group: "slotted",
+          childrenWhenCurrent: true,
+          facets: state.facets,
+          search: [name, ...mounted.map((v) => componentState(v.mod).search)].join(" ").toLowerCase(),
+          children: mounted.map((v) => leaf(v.mod, versionOf(v.mod) ?? v.mod.moduleName)),
+        });
+      }
+    }
+    for (const mod of versions) {
+      if (mountOf(mod)) continue;
+      const version = versionOf(mod);
+      const label = version ? `${name} · ${version}` : mod.moduleName;
+      unslotted.push({ ...leaf(mod, label), slot: null, group: "unslotted" });
+    }
+  }
+
+  slotted.sort((a, b) => bySlot(a.slot, b.slot) || byName(a.label, b.label));
+  unslotted.sort((a, b) => byName(a.label, b.label));
+  // Ranks for the two sort orders. Unslotted rows always follow the heading between the groups,
+  // which sits at rank `slotted.length` in both.
+  const nameRank = new Map([...slotted].sort((a, b) => byName(a.label, b.label)).map((n, i) => [n.id, i]));
+  slotted.forEach((node, i) => (node.order = { slot: i, name: nameRank.get(node.id)! }));
+  unslotted.forEach((node, i) => (node.order = { slot: slotted.length + 1 + i, name: slotted.length + 1 + i }));
+  return [...slotted, ...unslotted];
+};
+
+/** The tree for one tier: its directories, folded, down to its components. */
+export const tierTree = (index: LabIndex, tier: string, currentModuleId?: string): TreeNode[] => {
+  const mods = componentsOf(index).filter((mod) => mod.tier === tier);
+  if (tier === sectionsTier) return sectionsTree(mods, currentModuleId);
+  const top: Dir = { name: tier, path: tier, dirs: new Map(), mods: [] };
+  for (const mod of mods) {
+    const segments = mod.directory.split("/").slice(1);
+    let dir = top;
+    for (const segment of segments) {
+      let next = dir.dirs.get(segment);
+      if (!next) {
+        next = { name: segment, path: `${dir.path}/${segment}`, dirs: new Map(), mods: [] };
+        dir.dirs.set(segment, next);
+      }
+      dir = next;
+    }
+    dir.mods.push(mod);
+  }
+
+  const leaf = (mod: LabComponent, label = mod.moduleName): TreeNode => {
+    const state = componentState(mod);
+    return {
+      id: `mod:${mod.moduleId}`,
+      label,
+      href: mod.stories[0]!.dashboardUrl,
+      icon: "component",
+      current: mod.moduleId === currentModuleId,
+      dot: state.dot,
+      dotTitle: state.dotTitle,
+      facets: state.facets,
+      search: state.search,
+      title: label === mod.moduleName ? undefined : mod.moduleName,
+    };
+  };
+
+  const nodesOf = (dir: Dir): TreeNode[] => {
+    const out: TreeNode[] = [];
+    for (const child of [...dir.dirs.values()].sort((a, b) => a.name.localeCompare(b.name))) {
+      if (child.dirs.size === 0 && child.mods.length === 1) {
+        out.push(leaf(child.mods[0]!, child.name));
+        continue;
+      }
+      const children = nodesOf(child);
+      const liveCount = children.filter((c) => c.dot === "live").length;
+      out.push({
+        id: `dir:${child.path}`,
+        label: child.name,
+        icon: "folder",
+        children,
+        dot: liveCount ? "live" : undefined,
+        dotTitle: liveCount ? `${liveCount} live` : undefined,
+        search: child.name.toLowerCase(),
+      });
+    }
+    for (const mod of dir.mods) out.push(leaf(mod));
+    return out;
+  };
+
+  return nodesOf(top);
+};