@orbytes/astrolab 0.4.0-next.1 → 0.4.0-next.2

package/virtual.d.ts

@@ -6,7 +6,6 @@ declare module "virtual:orbytes-lab/config.mjs" {
     id: string;
     label: string;
     responsive: boolean;
-    cullable: boolean;
   }
   export interface LabConfig {
     directory: string;
@@ -18,11 +17,8 @@ declare module "virtual:orbytes-lab/config.mjs" {
     feedbucketKey: string | null;
     tiers: LabTier[];
     sectionsTier: string | null;
-    cullTier: string | null;
     responsiveDir: string | null;
-    cullDir: string | null;
     responsiveFile: string;
-    cullFile: string;
     /**
      * The pin board, when it is running: dev only, and only when the board is on and found a git
      * repository. Null in every build. Set by the pin half through the integration's shared state

package/bin/lab-cull.mjs

@@ -1,401 +0,0 @@
-#!/usr/bin/env node
-// Turns the lab's cull marks into deletions — and never from the browser.
-//
-//   You mark lab items for deletion in the sidebar; the dev-only API saves the marks to
-//   <directory>/cull.json. This script is the only thing that deletes: it reads the marks, works
-//   out what can go, prints the plan, and removes files only when told to.
-//
-//   orbytes-lab-cull                dry run — print the plan, remove nothing
-//   orbytes-lab-cull --json         the same plan as JSON
-//   orbytes-lab-cull --yes          perform it: `git rm` (staged, NOT committed), clear the
-//                                   processed marks, print the build-log line to paste
-//   orbytes-lab-cull --dir=src/lab  where the lab lives, when it is not the default
-//
-//   exit 0 plan clean · 2 blockers · 1 error
-//
-// IT RUNS IN THE CONSUMER'S REPO, NOT ITS OWN. The root is `process.cwd()` — never this file's
-// location, which since the lab became a package is somewhere under node_modules. Everything it
-// reads is derived from that root plus the shared defaults in ../defaults.mjs, so a path this
-// script protects and a path the integration writes cannot drift apart.
-//
-// What goes: each marked stories file, the .astro it exports as `component` (same directory or
-// below), then any file under the lab directory that ONLY the removal set imports — closed
-// repeatedly, so a vendored library goes when its last importer goes. Never, whatever the marks
-// say: decorators/, shell/, vendor/*/LICENSE, the lab's own head and home components, the mark
-// files, anything outside the lab directory — reported as "kept (protected)".
-//
-// Blockers refuse an entry outright: the entry is outside the cullable tier (section versions are
-// the version history and components are shared chrome, so neither is ever culled), the component
-// is LIVE (any page under src/pages/ mounts it, or mounts something that imports it — derived from
-// the pages themselves, nothing declared), the path is not a stories file on disk, or an unmarked
-// file still imports the component.
-// --yes refuses to run while any blocker stands.
-import { execFileSync } from "node:child_process";
-import { existsSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { dirname, join, relative, resolve, sep } from "node:path";
-import { resolveLabOptions } from "../defaults.mjs";
-import { pageComponentFiles, sitePages } from "../src/shell/live-files.mjs";
-import { readCull } from "../src/shell/marks.mjs";
-
-const SOURCE_EXT = new Set([".astro", ".ts", ".mts", ".tsx", ".js", ".mjs", ".jsx", ".css"]);
-
-const args = process.argv.slice(2);
-const YES = args.includes("--yes");
-const JSON_OUT = args.includes("--json");
-const DIR = args.find((a) => a.startsWith("--dir="))?.slice("--dir=".length);
-for (const a of args)
-  if (!["--yes", "--json"].includes(a) && !a.startsWith("--dir="))
-    die(`unknown flag ${a} — use --yes, --json and/or --dir=<lab directory>`);
-
-// The repo the command was run in, never this file's own location: as a package binary it lives
-// under node_modules, and deriving the root from there would delete nothing or the wrong thing.
-const ROOT = process.cwd();
-const CONFIG = resolveLabOptions(DIR ? { directory: DIR } : {});
-const CULL = CONFIG.cullFile;
-const LAB = `${CONFIG.directory}/`;
-
-function die(message) {
-  console.error("  FAIL " + message);
-  process.exit(1);
-}
-
-const abs = (rel) => join(ROOT, rel);
-const rel = (absolute) => relative(ROOT, absolute).split(sep).join("/");
-const read = (relFile) => readFileSync(abs(relFile), "utf8");
-const git = (...argv) => execFileSync("git", argv, { cwd: ROOT, stdio: ["ignore", "pipe", "pipe"] }).toString();
-
-// ---- protection ------------------------------------------------------------------------------
-// Everything outside the lab directory is protected by the first clause, so the site's own source
-// can never be swept up. Inside it, the shell the lab needs and the marks themselves are named.
-const PROTECTED_DIRS = [`${LAB}decorators/`, `${LAB}shell/`];
-const PROTECTED_FILES = new Set([
-  `${LAB}Home.astro`,
-  `${LAB}LabHead.astro`,
-  `${LAB}integration.mjs`,
-  CONFIG.responsiveFile,
-  CULL,
-]);
-const vendorLicense = new RegExp(
-  `^${LAB.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}vendor/.*/LICENSE(\\.\\w+)?$`,
-);
-const isProtected = (f) =>
-  !f.startsWith(LAB) ||
-  PROTECTED_DIRS.some((d) => f.startsWith(d)) ||
-  PROTECTED_FILES.has(f) ||
-  vendorLicense.test(f);
-
-// ---- the import graph over all of src/ ------------------------------------------------------
-const walk = (dir, out = []) => {
-  for (const entry of readdirSync(dir)) {
-    const full = join(dir, entry);
-    if (statSync(full).isDirectory()) walk(full, out);
-    else if (SOURCE_EXT.has(full.slice(full.lastIndexOf(".")))) out.push(full);
-  }
-  return out;
-};
-
-// Strips comments that could carry a stale `import … from "…"` line, then collects every
-// specifier: static imports and re-exports (multi-line, `type`, side-effect), dynamic import(),
-// and CSS @import. Bare packages and anything not starting ./ or ../ are ignored.
-const stripComments = (src) => src.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
-const SPECIFIER_PATTERNS = [
-  /\b(?:import|export)\s+(?:type\s+)?(?:[\w$*{}\s,]*?\s+from\s+)?["']([^"'\n]+)["']/g,
-  /\bimport\s*\(\s*["']([^"'\n]+)["']\s*\)/g,
-  /@import\s+(?:url\(\s*)?["']([^"'\n]+)["']/g,
-];
-const specifiersOf = (src) => {
-  const clean = stripComments(src);
-  const found = [];
-  for (const pattern of SPECIFIER_PATTERNS) for (const m of clean.matchAll(pattern)) found.push(m[1]);
-  return found;
-};
-
-// Relative specifier → existing file, or null for "not ours to follow" (bare package, /src/…
-// glob, alias), or undefined when a relative path resolves to nothing on disk.
-function resolveSpecifier(fromAbs, specifier) {
-  const clean = specifier.replace(/[?#].*$/, "");
-  if (!clean.startsWith("./") && !clean.startsWith("../")) return null;
-  const base = resolve(dirname(fromAbs), clean);
-  const candidates = [base];
-  for (const ext of [".ts", ".mts", ".tsx", ".mjs", ".js", ".astro"]) candidates.push(base + ext);
-  if (base.endsWith(".js")) candidates.push(base.slice(0, -3) + ".ts", base.slice(0, -3) + ".tsx");
-  if (base.endsWith(".mjs")) candidates.push(base.slice(0, -4) + ".mts");
-  for (const index of ["index.ts", "index.mts", "index.mjs", "index.js"]) candidates.push(join(base, index));
-  for (const c of candidates) if (existsSync(c) && statSync(c).isFile()) return c;
-  return undefined;
-}
-
-const imports = new Map(); // file → Set(files it imports)
-const importers = new Map(); // file → Set(files that import it)
-const unresolved = []; // { file, specifier } — relative paths that point at nothing
-for (const fileAbs of walk(abs("src"))) {
-  const file = rel(fileAbs);
-  const deps = new Set();
-  for (const specifier of specifiersOf(readFileSync(fileAbs, "utf8"))) {
-    const target = resolveSpecifier(fileAbs, specifier);
-    if (target === null) continue;
-    if (target === undefined) {
-      unresolved.push({ file, specifier });
-      continue;
-    }
-    const dep = rel(target);
-    deps.add(dep);
-    if (!importers.has(dep)) importers.set(dep, new Set());
-    importers.get(dep).add(file);
-  }
-  imports.set(file, deps);
-}
-const importersOf = (f) => importers.get(f) ?? new Set();
-
-// ---- LIVE: what any page mounts, and what those mount ---------------------------------------
-// "Live" has ONE definition, shared with the lab's own pill (../src/shell/live-files.mjs). This
-// block used to read src/pages/index.astro alone, which is correct for a one-page site and wrong
-// for every client build — the same defect the pill carried until 2026-09-06. A second copy of a
-// rule like this is how the two quietly disagree, so it imports the helper rather than repeat it.
-const pages = sitePages(ROOT);
-if (pages.length === 0) die("no pages found under src/pages — cannot tell what is live");
-const live = new Map(); // file → why
-for (const page of pages) {
-  for (const dep of pageComponentFiles(ROOT, page)) {
-    if (!live.has(dep)) live.set(dep, `imported by ${page}`);
-    for (const inner of imports.get(dep) ?? [])
-      if (!live.has(inner)) live.set(inner, `imported by ${dep}, which ${page} imports`);
-  }
-}
-
-// ---- the marks ---------------------------------------------------------------------------------
-if (!existsSync(abs(CULL))) {
-  finish({ marked: [], entries: [], removal: [], kept: [], protectedKept: [], blockers: [], notes: [`${CULL} does not exist — nothing is marked`] });
-}
-// Read through the same helper the mark API writes with, so the two cannot disagree about shape.
-const cull = readCull(ROOT, CONFIG);
-const marked = [...new Set(cull.marked.map((p) => String(p).replace(/^\.\//, "").replace(/\\/g, "/")))];
-
-// The `component:` identifier at the top level of `export default { … }`, ignoring nested
-// braces, then the `import X from "./X.astro"` that names it.
-function componentOf(storiesRel) {
-  const src = stripComments(read(storiesRel));
-  const start = src.search(/export\s+default\s*\{/);
-  if (start < 0) return { error: "no `export default { … }`" };
-  let depth = 0;
-  let topLevel = "";
-  for (let i = src.indexOf("{", start); i < src.length; i++) {
-    const ch = src[i];
-    if (ch === "{" || ch === "[") depth++;
-    else if (ch === "}" || ch === "]") {
-      depth--;
-      if (depth === 0) break;
-    } else if (depth === 1) topLevel += ch;
-  }
-  const name = topLevel.match(/\bcomponent\s*:\s*([A-Za-z_$][\w$]*)/)?.[1];
-  if (!name) return { error: "no `component: X` in the default export" };
-  const specifier = src.match(new RegExp(`\\bimport\\s+${name}\\s+from\\s+["']([^"'\\n]+\\.astro)["']`))?.[1];
-  if (!specifier) return { error: `no \`import ${name} from "…astro"\` to follow` };
-  const target = resolveSpecifier(abs(storiesRel), specifier);
-  if (!target) return { error: `component import "${specifier}" resolves to nothing` };
-  const inside = relative(dirname(abs(storiesRel)), target);
-  if (inside.startsWith("..")) return { error: `component "${specifier}" lives outside the stories file's directory` };
-  return { component: rel(target) };
-}
-
-const entries = []; // { stories, component?, blocker? }
-for (const stories of marked) {
-  const entry = { stories };
-  entries.push(entry);
-  if (!stories.startsWith(LAB) || !stories.endsWith(".stories.ts")) {
-    entry.blocker = `not a ${LAB}**/*.stories.ts path`;
-    continue;
-  }
-  // Ruled 2026-09-05: deletion is restricted to the explorations tier — section versions are the
-  // version history and components are shared chrome; neither is ever culled, whatever the marks say.
-  // Which tier that is comes from the consumer's `tiers` option, through the shared defaults.
-  if (!CONFIG.cullDir || !stories.startsWith(CONFIG.cullDir)) {
-    entry.blocker = `only the ${CONFIG.cullTier ?? "(none)"} tier can be culled — section versions and components stay`;
-    continue;
-  }
-  if (!existsSync(abs(stories)) || !statSync(abs(stories)).isFile()) {
-    entry.blocker = "file does not exist";
-    continue;
-  }
-  if (isProtected(stories)) {
-    entry.blocker = "protected path";
-    continue;
-  }
-  const parsed = componentOf(stories);
-  if (parsed.error) {
-    entry.blocker = parsed.error;
-    continue;
-  }
-  entry.component = parsed.component;
-  if (isProtected(entry.component)) entry.blocker = `component ${entry.component} is protected`;
-  else if (live.has(entry.component)) entry.blocker = `component ${entry.component} is LIVE — ${live.get(entry.component)}`;
-}
-
-// An unmarked importer outside the removal set blocks the entry. Blocking one entry shrinks the
-// set, which can expose another, so iterate to a fixed point.
-let changed = true;
-while (changed) {
-  changed = false;
-  const seeds = new Set(entries.filter((e) => !e.blocker).flatMap((e) => [e.stories, e.component]));
-  for (const entry of entries) {
-    if (entry.blocker) continue;
-    for (const seed of [entry.component, entry.stories]) {
-      const outside = [...importersOf(seed)].filter((i) => !seeds.has(i)).sort();
-      if (outside.length) {
-        entry.blocker = `${seed === entry.stories ? "stories file" : "component " + seed} is still imported by unmarked ${outside.join(", ")}`;
-        changed = true;
-        break;
-      }
-    }
-  }
-}
-
-// ---- closure: what only the removal set imports ------------------------------------------------
-// A `.d.ts` beside a `.js` of the same name is that file's type sidecar (the vendored
-// html-to-image ships one per module); nothing imports it, so it rides along with its .js.
-const companionsOf = (file) => {
-  const dts = file.replace(/\.m?js$/, ".d.ts");
-  return dts !== file && existsSync(abs(dts)) ? [dts] : [];
-};
-const removal = new Set(entries.filter((e) => !e.blocker).flatMap((e) => [e.stories, e.component]));
-const kept = new Map(); // file → importers outside the set
-const protectedKept = new Map(); // file → files in the set that import it
-changed = true;
-while (changed) {
-  changed = false;
-  for (const file of [...removal]) {
-    for (const dep of [...(imports.get(file) ?? []), ...companionsOf(file)]) {
-      if (removal.has(dep)) continue;
-      if (isProtected(dep)) {
-        if (!protectedKept.has(dep)) protectedKept.set(dep, new Set());
-        protectedKept.get(dep).add(file);
-        continue;
-      }
-      const outside = [...importersOf(dep)].filter((i) => !removal.has(i)).sort();
-      if (outside.length) kept.set(dep, outside);
-      else {
-        removal.add(dep);
-        kept.delete(dep);
-        changed = true;
-      }
-    }
-  }
-}
-
-// A vendored library whose every file goes leaves its LICENSE behind on purpose — say so.
-const notes = [];
-const vendorDir = abs(`${LAB}vendor`);
-if (existsSync(vendorDir))
-  for (const lib of readdirSync(vendorDir)) {
-    const libDir = join(vendorDir, lib);
-    if (!statSync(libDir).isDirectory()) continue;
-    const files = walkAll(libDir).map(rel);
-    const code = files.filter((f) => !isProtected(f));
-    if (code.length && code.every((f) => removal.has(f)))
-      notes.push(`${LAB}vendor/${lib}/ empties out — its LICENSE stays (protected); delete it by hand if the library is truly gone`);
-  }
-function walkAll(dir, out = []) {
-  for (const entry of readdirSync(dir)) {
-    const full = join(dir, entry);
-    statSync(full).isDirectory() ? walkAll(full, out) : out.push(full);
-  }
-  return out;
-}
-
-const plan = {
-  marked,
-  entries,
-  removal: [...removal].sort(),
-  kept: [...kept].map(([file, by]) => ({ file, importedBy: by })).sort((a, b) => a.file.localeCompare(b.file)),
-  protectedKept: [...protectedKept].map(([file, by]) => ({ file, importedBy: [...by].sort() })).sort((a, b) => a.file.localeCompare(b.file)),
-  blockers: entries.filter((e) => e.blocker).map((e) => ({ entry: e.stories, reason: e.blocker })),
-  notes,
-};
-
-// ---- perform -----------------------------------------------------------------------------------
-if (YES && plan.blockers.length === 0 && plan.removal.length) {
-  const tracked = new Set(git("ls-files", "-z", "--", ...plan.removal).split("\0").filter(Boolean));
-  const viaGit = plan.removal.filter((f) => tracked.has(f));
-  const viaDisk = plan.removal.filter((f) => !tracked.has(f));
-  if (viaGit.length) git("rm", "-q", "--", ...viaGit);
-  for (const f of viaDisk) rmSync(abs(f));
-
-  const processed = new Set(entries.filter((e) => !e.blocker).map((e) => e.stories));
-  const remaining = cull.marked.filter((p) => !processed.has(String(p).replace(/^\.\//, "").replace(/\\/g, "/")));
-  writeFileSync(abs(CULL), JSON.stringify({ marked: remaining, updated: new Date().toISOString() }, null, 2) + "\n");
-  const cullTracked = git("ls-files", "--", CULL).trim() !== "";
-  if (cullTracked) git("add", "--", CULL);
-
-  const now = new Date();
-  const date = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}`;
-  const names = entries.filter((e) => !e.blocker).map((e) => e.component.replace(/^.*\//, "").replace(/\.astro$/, ""));
-  plan.performed = {
-    gitRm: viaGit,
-    deletedUntracked: viaDisk,
-    marksCleared: processed.size,
-    marksRemaining: remaining.length,
-    cullJsonStaged: cullTracked,
-    buildLogLine: `#### ${date} · [WILL] Lab cull — ${names.length} item${names.length === 1 ? "" : "s"} removed: ${names.join(", ")}`,
-  };
-}
-
-finish(plan);
-
-// ---- report ------------------------------------------------------------------------------------
-function finish(p) {
-  const exitCode = p.blockers.length ? 2 : 0;
-  if (JSON_OUT) {
-    console.log(JSON.stringify({ ok: exitCode === 0, dryRun: !p.performed, ...p, unresolved }, null, 2));
-    process.exit(exitCode);
-  }
-
-  const list = (items, render = (x) => x) => items.forEach((i) => console.log("  " + render(i)));
-  const header = p.performed
-    ? "lab cull — performed"
-    : YES && p.blockers.length
-      ? "lab cull — REFUSED (blockers below; nothing removed)"
-      : YES
-        ? "lab cull — nothing to perform"
-        : "lab cull — dry run (pass --yes to perform)";
-  console.log(header);
-  console.log(`marked: ${p.marked.length} entr${p.marked.length === 1 ? "y" : "ies"} in ${CULL}`);
-  if (p.marked.length === 0) {
-    p.notes.forEach((n) => console.log("  " + n));
-    console.log("  ok   nothing marked — nothing to do");
-    process.exit(0);
-  }
-
-  console.log(`\nremove (${p.removal.length}):`);
-  list(p.removal);
-  console.log(`\nkept — still imported by unmarked files (${p.kept.length}):`);
-  list(p.kept, (k) => `${k.file}  ← ${k.importedBy.join(", ")}`);
-  console.log(`\nkept (protected) (${p.protectedKept.length}):`);
-  list(p.protectedKept, (k) => `${k.file}  ← ${k.importedBy.join(", ")}`);
-  console.log(`\nblockers (${p.blockers.length}):`);
-  p.blockers.forEach((b) => console.error(`  FAIL ${b.entry} — ${b.reason}`));
-  if (p.notes.length) {
-    console.log("\nnotes:");
-    list(p.notes);
-  }
-  if (unresolved.length) {
-    console.log(`\nunresolved relative imports (${unresolved.length}) — treated as nothing, check them:`);
-    list(unresolved, (u) => `${u.file} → "${u.specifier}"`);
-  }
-
-  console.log("");
-  if (p.performed) {
-    const r = p.performed;
-    console.log(`  ok   git rm (staged, not committed): ${r.gitRm.length} file${r.gitRm.length === 1 ? "" : "s"}`);
-    if (r.deletedUntracked.length) console.log(`  ok   deleted from disk (were untracked): ${r.deletedUntracked.join(", ")}`);
-    console.log(`  ok   ${CULL}: ${r.marksCleared} mark${r.marksCleared === 1 ? "" : "s"} cleared, ${r.marksRemaining} left${r.cullJsonStaged ? ", staged" : " (untracked, not staged)"}`);
-    console.log("\nBuild-log line — paste it, this script edits no log and commits nothing:\n");
-    console.log(r.buildLogLine);
-  } else if (exitCode === 2) {
-    console.log(YES ? "  FAIL refusing --yes while blockers stand — clear them (unmark, or unmark the importer too) and rerun" : "  FAIL plan has blockers — --yes would be refused");
-  } else if (p.removal.length) {
-    console.log(`  ok   plan is clean — ${p.removal.length} file${p.removal.length === 1 ? "" : "s"} would be removed`);
-  } else {
-    console.log("  ok   nothing to remove");
-  }
-  process.exit(exitCode);
-}