@sarimarcus/content-sites-core 0.20.0 → 0.22.0

package/src/images/variants.ts

@@ -0,0 +1,179 @@
+// The local generator and the gate for committed image variants. sharp is loaded only here, from the
+// site's own install (Astro ships it), so CI never needs it.
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { availableParallelism } from 'node:os';
+import { join, relative, sep } from 'node:path';
+import {
+  EXCLUDED_DIR, MANIFEST_FILE, VARIANTS_DIR, variantFileName, variantRungs,
+  type VariantEntry, type VariantManifest,
+} from './index.ts';
+
+const SOURCE_EXT = /\.(webp|jpe?g|png|avif|tiff?)$/i;
+/** Matches the WebP settings the sharp service used, so variants look like what the site served before noop. */
+export const VARIANT_WEBP = { quality: 65, effort: 6 } as const;
+
+export interface SourceImage {
+  /** Path relative to src/assets, always with forward slashes. */
+  rel: string;
+  sha: string;
+  bytes: Buffer;
+}
+
+/** Whether a path under src/assets gets variants: a raster image outside any gallery directory. */
+export function isEligibleSource(rel: string): boolean {
+  return SOURCE_EXT.test(rel) && !EXCLUDED_DIR.test(rel) && !rel.split('/').some((seg) => seg.startsWith('.'));
+}
+
+export function listSources(siteRoot: string): string[] {
+  const assets = join(siteRoot, 'src', 'assets');
+  if (!existsSync(assets)) throw new Error(`no src/assets directory under ${siteRoot}`);
+  const out: string[] = [];
+  const walk = (dir: string) => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const abs = join(dir, e.name);
+      if (e.isDirectory()) walk(abs);
+      else out.push(relative(assets, abs).split(sep).join('/'));
+    }
+  };
+  walk(assets);
+  return out.filter(isEligibleSource).sort();
+}
+
+export const sourceSha = (bytes: Uint8Array): string => createHash('sha256').update(bytes).digest('hex').slice(0, 16);
+
+export function readSource(siteRoot: string, rel: string): SourceImage {
+  const bytes = readFileSync(join(siteRoot, 'src', 'assets', rel));
+  return { rel, bytes, sha: sourceSha(bytes) };
+}
+
+export function parseManifest(text: string | null, where: string): VariantManifest {
+  if (text === null) return {};
+  const parsed = JSON.parse(text);
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error(`${where} is not a variant manifest object`);
+  return parsed as VariantManifest;
+}
+
+export function readManifest(siteRoot: string): VariantManifest {
+  return parseManifest(workingTree(siteRoot).manifestText(), join(siteRoot, VARIANTS_DIR, MANIFEST_FILE));
+}
+
+/** What the gate reads: the working tree (the CLI) or a pushed commit (the site pre-push hook). */
+export interface VariantTree {
+  /** Eligible source paths relative to src/assets. */
+  sources(): string[];
+  sourceBytes(rel: string): Uint8Array;
+  manifestText(): string | null;
+  /** File names present in the variants directory. */
+  variantFiles(): string[];
+}
+
+export function workingTree(siteRoot: string): VariantTree {
+  const dir = join(siteRoot, VARIANTS_DIR);
+  return {
+    sources: () => listSources(siteRoot),
+    sourceBytes: (rel) => readFileSync(join(siteRoot, 'src', 'assets', rel)),
+    manifestText: () => (existsSync(join(dir, MANIFEST_FILE)) ? readFileSync(join(dir, MANIFEST_FILE), 'utf-8') : null),
+    variantFiles: () => (existsSync(dir) ? readdirSync(dir) : []),
+  };
+}
+
+async function pool<T>(items: T[], fn: (item: T) => Promise<void>): Promise<void> {
+  let next = 0;
+  const worker = async () => {
+    while (next < items.length) await fn(items[next++]);
+  };
+  await Promise.all(Array.from({ length: Math.min(items.length, availableParallelism()) }, worker));
+}
+
+export interface GenerateResult {
+  sources: number;
+  written: number;
+  kept: number;
+  pruned: number;
+}
+
+/** Write every missing variant, rebuild the manifest, and delete variants no source needs any more. */
+export async function generateVariants(siteRoot: string, log: (line: string) => void = () => {}): Promise<GenerateResult> {
+  const { default: sharp } = (await import('sharp')) as { default: any };
+  const dir = join(siteRoot, VARIANTS_DIR);
+  mkdirSync(dir, { recursive: true });
+  const previous = readManifest(siteRoot);
+  const manifest: VariantManifest = {};
+  const rels = listSources(siteRoot);
+  let written = 0;
+  let kept = 0;
+  await pool(rels, async (rel) => {
+    const source = readSource(siteRoot, rel);
+    const shared = manifest[source.sha];
+    if (shared) {
+      shared.src.push(rel);
+      return;
+    }
+    // Reserve the sha before any await, so a duplicate file in another worker joins this entry.
+    const entry: VariantEntry = { w: 0, h: 0, fmt: '', rungs: [], src: [rel] };
+    manifest[source.sha] = entry;
+    const known = previous[source.sha];
+    if (known) {
+      Object.assign(entry, { w: known.w, h: known.h, fmt: known.fmt, rungs: variantRungs(known.w, known.fmt) });
+    } else {
+      const meta = await sharp(source.bytes).metadata();
+      Object.assign(entry, { w: meta.width, h: meta.height, fmt: meta.format, rungs: variantRungs(meta.width, meta.format) });
+    }
+    for (const width of entry.rungs) {
+      const file = join(dir, variantFileName(source.sha, width));
+      if (existsSync(file)) {
+        kept++;
+        continue;
+      }
+      writeFileSync(file, await sharp(source.bytes).resize({ width }).webp(VARIANT_WEBP).toBuffer());
+      written++;
+      log(`+ ${variantFileName(source.sha, width)}  ${rel}`);
+    }
+  });
+  const wanted = new Set(Object.entries(manifest).flatMap(([sha, e]) => e.rungs.map((w) => variantFileName(sha, w))));
+  let pruned = 0;
+  for (const name of readdirSync(dir)) {
+    if (name === MANIFEST_FILE || wanted.has(name)) continue;
+    rmSync(join(dir, name));
+    pruned++;
+    log(`- ${name}`);
+  }
+  const sorted: VariantManifest = {};
+  for (const sha of Object.keys(manifest).sort()) sorted[sha] = { ...manifest[sha], src: manifest[sha].src.sort() };
+  writeFileSync(join(dir, MANIFEST_FILE), `${JSON.stringify(sorted, null, 2)}\n`);
+  return { sources: rels.length, written, kept, pruned };
+}
+
+export interface CheckResult {
+  sources: number;
+  variants: number;
+  problems: string[];
+  orphans: string[];
+}
+
+/** The gate: every eligible source is in the manifest and every rung it needs has a committed file. */
+export function checkVariants(tree: VariantTree): CheckResult {
+  const manifest = parseManifest(tree.manifestText(), `${VARIANTS_DIR}/${MANIFEST_FILE}`);
+  const present = new Set(tree.variantFiles());
+  const rels = tree.sources();
+  const problems: string[] = [];
+  const needed = new Set<string>();
+  let variants = 0;
+  for (const rel of rels) {
+    const sha = sourceSha(tree.sourceBytes(rel));
+    const entry = manifest[sha];
+    if (!entry) {
+      problems.push(`${rel}: not in ${VARIANTS_DIR}/${MANIFEST_FILE} (new or changed image)`);
+      continue;
+    }
+    for (const width of variantRungs(entry.w, entry.fmt)) {
+      const name = variantFileName(sha, width);
+      needed.add(name);
+      if (present.has(name)) variants++;
+      else problems.push(`${rel}: missing ${VARIANTS_DIR}/${name}`);
+    }
+  }
+  const orphans = [...present].filter((n) => n !== MANIFEST_FILE && !needed.has(n));
+  return { sources: rels.length, variants, problems, orphans };
+}

package/src/url/index.ts

@@ -5,3 +5,4 @@ export { normalizeHref, extractProseHrefs, dedupRelated } from './relatedDedup.t
 export { buildImageMap, keyBySlug } from './imageMap.ts';
 export { articleFeedItem } from './feed.ts';
 export type { FeedArticle, FeedItem } from './feed.ts';
+export { pageTypeOf } from './pageType.ts';

package/src/url/pageType.ts

@@ -0,0 +1,13 @@
+/**
+ * Page type: the first path segment, 'home' at the root.
+ *
+ * The single definition behind both the GA4 `page_type` param (runtime pathname, '/plan/x') and a site's GYG `cmp`
+ * segment (BUILD-time `Astro.url.pathname`, '/index.html' under build.format 'file'). The `.html`/`index`
+ * normalisation is what makes the two agree.
+ */
+export function pageTypeOf(pathname: string): string {
+  const first = pathname.split('/').filter(Boolean)[0];
+  if (!first) return 'home';
+  const bare = first.replace(/\.html$/, '');
+  return bare === 'index' || bare === '' ? 'home' : bare;
+}