@at-flux/astro-feature-flags 1.0.3 → 1.0.4

package/src/dev-outline-css.ts

@@ -8,6 +8,13 @@ import { affDevBootstrapRuntime } from "./dev-inline-runtimes";
 import type { ResolvedFeatureRuntime } from "./runtime";
 import { toToken } from "./runtime";
 
+/**
+ * Cascade layer for the declarations the app must be able to override without
+ * writing `!important`. Named rather than anonymous so the order statement in
+ * {@link affHeadInlineRuntime} can name it too.
+ */
+export const DEV_LAYER = "aff-dev";
+
 export type DevOutlineHiddenStrategy = "visibility" | "display";
 
 export interface DevOutlineCssOptions extends ElementBadgeLayoutOptions {
@@ -99,6 +106,28 @@ function featureColorVar(token: string, namespace: string): string {
  * Dev-only styles: `data-ff="token"` (or space-separated tokens) gates outlines/badges.
  * `html[data-ff-route="<token>"]` (dev) adds a fixed top-right route badge (label only).
  * Toolbar toggles: `data-ff-enabled-*`, `data-ff-outline-*`, `data-ff-badge-*`, `--<namespace>-c-*`.
+ *
+ * The badge is an absolutely positioned `::before`, so its host has to be a
+ * containing block, and the host also wants rounding for the outline to follow.
+ * Both of those are the app's business, not ours: a flagged element that the app
+ * positions itself, or rounds itself, must keep doing so. Marking a flagged
+ * element must not move it.
+ *
+ * So `position` and `border-radius` are emitted inside `:where()` *and* inside
+ * the `aff-dev` cascade layer. `:where()` alone is not enough: an unlayered rule
+ * beats a layered one before specificity is ever consulted, so a zero-specificity
+ * unlayered rule still overrides Tailwind's `.rounded-full` and `.absolute`,
+ * which live in `@layer utilities`. Layering ours is what lets the app win.
+ *
+ * Layer priority follows the order layers are first declared, so the layer only
+ * sorts below the app's own layers if `@layer aff-dev;` appears before them in
+ * document order. The sheet opens with that statement for the case where it
+ * lands first, and {@link affHeadInlineRuntime} also prepends a style element
+ * carrying it as the first child of `<head>`, which is what actually guarantees
+ * the order at runtime.
+ *
+ * Everything else here is dev chrome the app has no opinion about, and stays at
+ * its natural specificity.
  */
 export function createFeatureFlagStyles(
   runtime: ResolvedFeatureRuntime,
@@ -142,11 +171,15 @@ html {
 html:not([data-ff-outline-${token}="off"]) {
   --aff-outline-c-${token}: var(${v}, ${col});
 }
+@layer ${DEV_LAYER} {
+  :where(${selOutline}) {
+    position: relative;
+    border-radius: ${opts.borderRadius};
+  }
+}
 ${selOutline} {
-  position: relative;
   outline: ${opts.outlineWidth} solid var(--aff-outline-c-${token});
   outline-offset: ${opts.outlineOffset};
-  border-radius: ${opts.borderRadius};
 }
 html:not([data-ff-badge-${token}="off"]) ${selIsSingleBadge}::before {
   box-sizing: border-box;
@@ -230,11 +263,15 @@ html[data-ff-enabled-${token}="off"] ${selIs} {
 
   // Multi-token value on a single element: show combined badge text and a gradient outline.
   chunks.push(`
+@layer ${DEV_LAYER} {
+  :where([${nsAttr}*=" "]) {
+    position: relative;
+    border-radius: ${opts.borderRadius};
+  }
+}
 [${nsAttr}*=" "] {
-  position: relative;
   outline: none !important;
   outline-offset: 0 !important;
-  border-radius: ${opts.borderRadius};
 }
 html [${nsAttr}*=" "]::after {
   content: "";
@@ -408,7 +445,7 @@ html[data-ff-outline-${token}="off"] ${selIs}[${nsAttr}*=" "]::after {
 `);
   }
 
-  return "\n" + chunks.join("\n") + "\n";
+  return `\n@layer ${DEV_LAYER};\n` + chunks.join("\n") + "\n";
 }
 
 /**

package/src/index.ts

@@ -42,21 +42,38 @@ import {
   buildAffDevBootstrapScript,
   createFeatureFlagStyles,
   createProductionGateStyles,
+  DEV_LAYER,
 } from "./dev-outline-css";
 import { applyProductionHtmlCullToDist } from "./production-html-cull";
+import { applySitemapPruneToDist } from "./sitemap-prune";
 import { buildAffDevHeadInline } from "./dev-head-inject";
 import { routePrefixJsHelper } from "./route-prefix-js";
 
-export { createFeatureFlagStyles, createProductionGateStyles };
+export { createFeatureFlagStyles, createProductionGateStyles, DEV_LAYER };
 export {
   cullProductionHtml,
   applyProductionHtmlCullToDist,
 } from "./production-html-cull";
+export type { SitemapPruneResult } from "./sitemap-prune";
+export {
+  applySitemapPruneToDist,
+  pruneSitemapIndexXml,
+  pruneSitemapXml,
+  sitemapUrlCount,
+} from "./sitemap-prune";
 
 export interface AstroFeatureFlagsOptions extends ResolveFeatureRuntimeOptions {
   css?: DevOutlineCssOptions;
   /** When false, keeps static build output untouched (no route pruning / HTML cull). */
   staticMinify?: boolean;
+  /**
+   * When false, leaves generated sitemaps alone. On by default: a pruned route that is
+   * still advertised in `sitemap-0.xml` is a 404 handed to every crawler that reads it.
+   *
+   * Needs this integration to sit **after** `@astrojs/sitemap` in `integrations`, because
+   * Astro runs `astro:build:done` in array order.
+   */
+  pruneSitemap?: boolean;
 }
 
 /** Prefer `prod` if present; else first non-`dev` key (sorted); else `"prod"`. */
@@ -304,7 +321,12 @@ export {
 export default function astroFeatureFlags(
   options: AstroFeatureFlagsOptions = {},
 ): any {
-  const { css, staticMinify = true, ...flagOpts } = options;
+  const {
+    css,
+    staticMinify = true,
+    pruneSitemap = true,
+    ...flagOpts
+  } = options;
   const opts = withDefaultEnvironments(flagOpts);
   const mode = opts.mode ?? process.env.NODE_ENV ?? "development";
 
@@ -313,15 +335,23 @@ export default function astroFeatureFlags(
     mode,
   });
 
+  /**
+   * Set in `astro:config:setup`, read in `astro:build:done`, so that a sitemap this
+   * pass never saw can be reported as an ordering mistake rather than silently skipped.
+   */
+  let sitemapIntegrationPresent = false;
+
   return {
     name: "astro-feature-flags",
     hooks: {
       "astro:config:setup": ({
+        config,
         updateConfig,
         addDevToolbarApp,
         command,
         injectScript,
       }: {
+        config?: { integrations?: { name?: string }[] };
         updateConfig: (config: unknown) => void;
         addDevToolbarApp?: (opts: {
           id: string;
@@ -332,6 +362,9 @@ export default function astroFeatureFlags(
         command?: string;
         injectScript?: (stage: string, content: string) => void;
       }) => {
+        sitemapIntegrationPresent = (config?.integrations ?? []).some(
+          (integration) => integration?.name === "@astrojs/sitemap",
+        );
         const flagNames = Object.keys(runtime.flags);
         const flagTokens = flagNames.map((name) => toToken(name));
         const flagsByEnvironment = resolveFeatureFlagsByEnvironment(opts);
@@ -403,7 +436,13 @@ export default function astroFeatureFlags(
           },
         });
       },
-      "astro:build:done": ({ dir }: { dir: URL }) => {
+      "astro:build:done": ({
+        dir,
+        logger,
+      }: {
+        dir: URL;
+        logger?: { warn: (message: string) => void };
+      }) => {
         if (runtime.isDev || !staticMinify) return;
         const outDir = fileURLToPath(dir);
         const prunePaths = routePathsToPrune({
@@ -414,6 +453,13 @@ export default function astroFeatureFlags(
           rmSync(join(outDir, routePath), { recursive: true, force: true });
         }
         applyProductionHtmlCullToDist(outDir, runtime);
+        if (!pruneSitemap) return;
+        const sitemaps = applySitemapPruneToDist(outDir, runtime);
+        if (!sitemaps.found && sitemapIntegrationPresent && prunePaths.length) {
+          logger?.warn(
+            "@astrojs/sitemap is configured but no sitemap was on disk yet, so pruned routes may still be listed. Move astroFeatureFlags() after sitemap() in `integrations`.",
+          );
+        }
       },
     },
   };

package/src/sitemap-prune.ts

@@ -0,0 +1,171 @@
+import { readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import type { ResolvedFeatureRuntime } from "./runtime";
+import { shouldIncludeRoute } from "./runtime";
+
+/**
+ * `@astrojs/sitemap` names its output `sitemap-0.xml`, `sitemap-1.xml`, … alongside a
+ * `sitemap-index.xml`. Other generators write a plain `sitemap.xml`. Match the family.
+ */
+const SITEMAP_FILE = /^sitemap[\w.-]*\.xml$/i;
+
+function walkSitemapFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const ent of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, ent.name);
+    if (ent.isDirectory()) out.push(...walkSitemapFiles(p));
+    else if (ent.isFile() && SITEMAP_FILE.test(ent.name)) out.push(p);
+  }
+  return out;
+}
+
+/**
+ * `<loc>` is XML, so the five predefined entities and numeric references are all
+ * legal in it. `&amp;` is the one that actually turns up (a query string with two
+ * parameters), but a path that came through an escaper wholesale can carry the
+ * others, and an entity left undecoded turns into a pathname that matches no
+ * route and is silently kept.
+ */
+function decodeXmlEntities(value: string): string {
+  return value
+    .replace(/&#x([0-9a-f]+);/gi, (_, hex: string) =>
+      String.fromCodePoint(Number.parseInt(hex, 16)),
+    )
+    .replace(/&#(\d+);/g, (_, dec: string) =>
+      String.fromCodePoint(Number.parseInt(dec, 10)),
+    )
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, "&");
+}
+
+function locPathname(entry: string): string | null {
+  const loc = /<loc>\s*([\s\S]*?)\s*<\/loc>/i.exec(entry)?.[1];
+  if (!loc) return null;
+  const href = decodeXmlEntities(loc).trim();
+  try {
+    return new URL(href).pathname;
+  } catch {
+    return href.startsWith("/") ? href : null;
+  }
+}
+
+/**
+ * Drop every `<url>` whose `<loc>` points at a route this runtime prunes.
+ *
+ * The alternative is asking every site to duplicate the flag decision in its own
+ * `sitemap({ filter })`, which is what the docs used to say and what the site this
+ * package was written for got subtly wrong: a substring test culled `/blog/about-x/`
+ * along with `/about/`. Deciding it here, from the same runtime that deletes the
+ * files, means the two answers cannot drift.
+ *
+ * String surgery rather than an XML parse, so the untouched entries come back
+ * byte-identical and the diff of a rebuild stays readable.
+ */
+export function pruneSitemapXml(
+  xml: string,
+  runtime: ResolvedFeatureRuntime,
+): string {
+  return xml.replace(/[ \t]*<url>[\s\S]*?<\/url>\s*/gi, (entry) => {
+    const pathname = locPathname(entry);
+    if (!pathname) return entry;
+    const keep = shouldIncludeRoute({
+      pathname,
+      routeFlags: runtime.routeFlags,
+      flags: runtime.flags,
+      isDev: false,
+    });
+    return keep ? entry : "";
+  });
+}
+
+/** Number of `<url>` entries left in a urlset. */
+export function sitemapUrlCount(xml: string): number {
+  return (xml.match(/<url>/gi) ?? []).length;
+}
+
+/**
+ * Remove the `<sitemap>` entries of an index that point at files which no longer exist.
+ */
+export function pruneSitemapIndexXml(
+  xml: string,
+  removedFiles: readonly string[],
+): string {
+  if (!removedFiles.length) return xml;
+  const removed = new Set(removedFiles);
+  return xml.replace(/[ \t]*<sitemap>[\s\S]*?<\/sitemap>\s*/gi, (entry) => {
+    const pathname = locPathname(entry);
+    if (!pathname) return entry;
+    return removed.has(basename(pathname)) ? "" : entry;
+  });
+}
+
+export interface SitemapPruneResult {
+  /** Sitemap files rewritten with fewer entries. */
+  rewritten: string[];
+  /** Sitemap files deleted because nothing was left in them. */
+  removed: string[];
+  /** Whether any sitemap file was found at all. */
+  found: boolean;
+}
+
+/**
+ * Walk `outDir` (Astro `dist/`) and take the pruned routes out of every sitemap.
+ *
+ * Runs in `astro:build:done`, which means this integration has to sit **after**
+ * `@astrojs/sitemap` in `integrations` — Astro runs the hook in array order, and a
+ * sitemap written after this pass would keep its dead URLs.
+ */
+export function applySitemapPruneToDist(
+  outDir: string,
+  runtime: ResolvedFeatureRuntime,
+): SitemapPruneResult {
+  const result: SitemapPruneResult = {
+    rewritten: [],
+    removed: [],
+    found: false,
+  };
+  let files: string[];
+  try {
+    files = walkSitemapFiles(outDir);
+  } catch {
+    return result;
+  }
+  result.found = files.length > 0;
+
+  const indexes: string[] = [];
+  for (const file of files) {
+    const before = readFileSync(file, "utf8");
+    if (!/<urlset[\s>]/i.test(before)) {
+      if (/<sitemapindex[\s>]/i.test(before)) indexes.push(file);
+      continue;
+    }
+    const after = pruneSitemapXml(before, runtime);
+    if (after === before) continue;
+    if (sitemapUrlCount(after) === 0) {
+      rmSync(file, { force: true });
+      result.removed.push(file);
+    } else {
+      writeFileSync(file, after, "utf8");
+      result.rewritten.push(file);
+    }
+  }
+
+  const removedNames = result.removed.map((file) => basename(file));
+  for (const file of indexes) {
+    const before = readFileSync(file, "utf8");
+    const after = pruneSitemapIndexXml(before, removedNames);
+    if (after === before) continue;
+    if (!/<sitemap>/i.test(after)) {
+      rmSync(file, { force: true });
+      result.removed.push(file);
+    } else {
+      writeFileSync(file, after, "utf8");
+      result.rewritten.push(file);
+    }
+  }
+
+  return result;
+}