Move linter rule page assembly from generate script to Astro components

This change refactors how linter rule pages are generated:

**Before:**
- Generate script consolidated individual linter rules into markdown files
- Rules were grouped by AEP number and wrapped in <details> elements
- Output was written to src/content/docs/tooling/*/rules/{aep}.md

**After:**
- Generate script writes individual rules as JSON to generated/linter-rules/
- New Astro component (LinterRules.astro) handles rendering rules
- Dynamic route pages ([aep].astro) read JSON and pass to component
- Produces identical HTML output using Starlight's layout

**Benefits:**
- Cleaner separation of concerns (data extraction vs. rendering)
- Easier to modify rule presentation without regenerating content
- Leverages Astro's component system and build process
- Maintains site structure generation for navigation

**Files Changed:**
- scripts/generate.ts: Use writeLinterRulesJSON() instead of consolidation
- scripts/src/linter.ts: Add writeLinterRulesJSON() and getUniqueAeps()
- src/components/LinterRules.astro: Component to render rule list
- src/pages/tooling/linter/rules/[aep].astro: Protobuf linter dynamic route
- src/pages/tooling/openapi-linter/rules/[aep].astro: OpenAPI linter dynamic route

Author: claude

scripts/generate.ts

@@ -2,19 +2,14 @@ import * as fs from "fs";
 import * as path from "path";
 
 import loadConfigFiles from "./src/config";
-import {
-  type AEP,
-  type ConsolidatedLinterRule,
-  type GroupFile,
-  type LinterRule,
-} from "./src/types";
+import { type AEP, type GroupFile, type LinterRule } from "./src/types";
 import { buildMarkdown, Markdown } from "./src/markdown";
 import { load, dump } from "js-yaml";
 import {
   assembleLinterRules,
   assembleOpenAPILinterRules,
-  consolidateLinterRule,
-  writeRule,
+  writeLinterRulesJSON,
+  getUniqueAeps,
 } from "./src/linter";
 import {
   logFileRead,
@@ -371,18 +366,14 @@ if (AEP_LINTER_LOC != "") {
     "",
   );
 
-  // Write out linter rules.
+  // Write out linter rules as JSON for Astro to consume
+  // The rules are now rendered by Astro components instead of being pre-consolidated
+  // See: src/pages/tooling/linter/rules/[aep].astro and src/components/LinterRules.astro
   let linter_rules = await assembleLinterRules(AEP_LINTER_LOC);
-  let consolidated_rules = consolidateLinterRule({ linterRules: linter_rules });
-  for (var rule of consolidated_rules) {
-    writeRule(rule);
-  }
+  writeLinterRulesJSON(linter_rules, "generated/linter-rules/protobuf.json");
 
   // Add to site structure
-  addLinterRules(
-    siteStructure,
-    consolidated_rules.map((r) => r.aep),
-  );
+  addLinterRules(siteStructure, getUniqueAeps(linter_rules));
   addToolingPage(siteStructure, { label: "Website", link: "tooling/website" });
 } else {
   console.warn("Proto linter repo is not found.");
@@ -405,25 +396,16 @@ if (AEP_OPENAPI_LINTER_LOC != "") {
       "OpenAPI Linter",
     );
 
-    // Consolidate rules (groups by AEP number)
-    const consolidatedOpenAPIRules = consolidateLinterRule({
-      linterRules: openapiLinterRules,
-    });
-
-    // Write rule markdown files
-    for (const rule of consolidatedOpenAPIRules) {
-      const outputPath = path.join(
-        "src/content/docs/tooling/openapi-linter/rules",
-        `${rule.aep}.md`,
-      );
-      writeRule(rule, outputPath);
-    }
+    // Write OpenAPI linter rules as JSON for Astro to consume
+    // The rules are now rendered by Astro components instead of being pre-consolidated
+    // See: src/pages/tooling/openapi-linter/rules/[aep].astro and src/components/LinterRules.astro
+    writeLinterRulesJSON(
+      openapiLinterRules,
+      "generated/linter-rules/openapi.json",
+    );
 
     // Add to site structure
-    addOpenAPILinterRules(
-      siteStructure,
-      consolidatedOpenAPIRules.map((r) => r.aep),
-    );
+    addOpenAPILinterRules(siteStructure, getUniqueAeps(openapiLinterRules));
 
     console.log("✅ OpenAPI linter integration complete\n");
   } else {

scripts/src/linter.ts

@@ -237,3 +237,37 @@ export function writeRule(rule: ConsolidatedLinterRule, outputPath?: string) {
     path.join(`src/content/docs/tooling/linter/rules/`, `${rule.aep}.md`);
   writeFile(filePath, rule.contents);
 }
+
+/**
+ * Writes linter rules as JSON data file for Astro to consume
+ * This allows Astro components to render the rules instead of pre-generating markdown
+ *
+ * @param rules - Array of linter rules to write
+ * @param outputPath - Path to write the JSON file
+ */
+export function writeLinterRulesJSON(
+  rules: LinterRule[],
+  outputPath: string,
+): void {
+  // Ensure the directory exists
+  const dir = path.dirname(outputPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  // Write the rules as JSON
+  writeFile(outputPath, JSON.stringify(rules, null, 2));
+  console.log(`✓ Wrote ${rules.length} linter rules to ${outputPath}`);
+}
+
+/**
+ * Gets unique AEP numbers from linter rules
+ * Used for site structure generation
+ *
+ * @param rules - Array of linter rules
+ * @returns Array of unique AEP numbers, sorted
+ */
+export function getUniqueAeps(rules: LinterRule[]): string[] {
+  const aeps = new Set(rules.map((r) => r.aep));
+  return Array.from(aeps).sort();
+}

src/components/LinterRules.astro

@@ -0,0 +1,81 @@
+---
+/**
+ * LinterRules Component
+ *
+ * Renders a list of linter rules in collapsible <details> elements.
+ * This replaces the consolidation logic previously done in the generate script.
+ *
+ * Props:
+ * - rules: Array of LinterRule objects to render
+ * - preamble: Optional preamble text to display before the rules
+ */
+
+export interface LinterRule {
+  title: string;
+  aep: string;
+  contents: string; // Markdown content with frontmatter
+  filename: string;
+  slug: string;
+  preamble?: string;
+}
+
+export interface Props {
+  rules: LinterRule[];
+  preamble?: string;
+}
+
+const { rules, preamble } = Astro.props;
+
+// Extract preamble from first rule if available, otherwise use provided preamble
+const displayPreamble = rules[0]?.preamble || preamble || "";
+
+// Helper function to strip frontmatter from content
+function stripFrontmatter(content: string): string {
+  return content.replace(/---[\s\S]*?---/m, "").trim();
+}
+---
+
+{displayPreamble && (
+  <div class="preamble" set:html={displayPreamble} />
+)}
+
+{
+  rules.map((rule) => (
+    <details>
+      <summary>{rule.title}</summary>
+      <div set:html={stripFrontmatter(rule.contents)} />
+    </details>
+  ))
+}
+
+<style>
+  .preamble {
+    margin-bottom: 1.5rem;
+  }
+
+  details {
+    margin-bottom: 1rem;
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 0.5rem;
+    padding: 0;
+  }
+
+  summary {
+    padding: 1rem;
+    cursor: pointer;
+    font-weight: 600;
+    user-select: none;
+  }
+
+  summary:hover {
+    background-color: var(--sl-color-gray-6);
+  }
+
+  details[open] summary {
+    border-bottom: 1px solid var(--sl-color-gray-5);
+  }
+
+  details > div {
+    padding: 1rem;
+  }
+</style>

src/pages/tooling/linter/rules/[aep].astro

@@ -0,0 +1,60 @@
+---
+/**
+ * Dynamic route for Protobuf Linter rule pages
+ * Replaces the consolidated markdown files previously generated by the script
+ */
+
+import StarlightPage from "@astrojs/starlight/components/StarlightPage.astro";
+import LinterRules from "../../../../components/LinterRules.astro";
+import * as fs from "fs";
+import * as path from "path";
+
+export async function getStaticPaths() {
+  // Read the linter rules JSON data
+  const linterRulesPath = path.join(
+    process.cwd(),
+    "generated/linter-rules/protobuf.json",
+  );
+
+  // Check if the file exists
+  if (!fs.existsSync(linterRulesPath)) {
+    console.warn("⚠️  Protobuf linter rules JSON not found, skipping...");
+    return [];
+  }
+
+  const allRules = JSON.parse(fs.readFileSync(linterRulesPath, "utf-8"));
+
+  // Group rules by AEP number
+  const rulesByAep = allRules.reduce((acc, rule) => {
+    if (!acc[rule.aep]) {
+      acc[rule.aep] = [];
+    }
+    acc[rule.aep].push(rule);
+    return acc;
+  }, {});
+
+  // Generate paths for each AEP
+  return Object.keys(rulesByAep).map((aep) => ({
+    params: { aep },
+    props: {
+      rules: rulesByAep[aep],
+      aep,
+    },
+  }));
+}
+
+const { rules, aep } = Astro.props;
+
+// Extract preamble from first rule if available
+const preamble = rules[0]?.preamble || "";
+---
+
+<StarlightPage
+  frontmatter={{
+    title: `AEP-${aep} Linter Rules`,
+    tableOfContents: { minHeadingLevel: 1 },
+  }}
+  headings={[]}
+>
+  <LinterRules rules={rules} preamble={preamble} />
+</StarlightPage>

src/pages/tooling/openapi-linter/rules/[aep].astro

@@ -0,0 +1,60 @@
+---
+/**
+ * Dynamic route for OpenAPI Linter rule pages
+ * Replaces the consolidated markdown files previously generated by the script
+ */
+
+import StarlightPage from "@astrojs/starlight/components/StarlightPage.astro";
+import LinterRules from "../../../../components/LinterRules.astro";
+import * as fs from "fs";
+import * as path from "path";
+
+export async function getStaticPaths() {
+  // Read the OpenAPI linter rules JSON data
+  const linterRulesPath = path.join(
+    process.cwd(),
+    "generated/linter-rules/openapi.json",
+  );
+
+  // Check if the file exists
+  if (!fs.existsSync(linterRulesPath)) {
+    console.warn("⚠️  OpenAPI linter rules JSON not found, skipping...");
+    return [];
+  }
+
+  const allRules = JSON.parse(fs.readFileSync(linterRulesPath, "utf-8"));
+
+  // Group rules by AEP number
+  const rulesByAep = allRules.reduce((acc, rule) => {
+    if (!acc[rule.aep]) {
+      acc[rule.aep] = [];
+    }
+    acc[rule.aep].push(rule);
+    return acc;
+  }, {});
+
+  // Generate paths for each AEP
+  return Object.keys(rulesByAep).map((aep) => ({
+    params: { aep },
+    props: {
+      rules: rulesByAep[aep],
+      aep,
+    },
+  }));
+}
+
+const { rules, aep } = Astro.props;
+
+// Extract preamble from first rule if available
+const preamble = rules[0]?.preamble || "";
+---
+
+<StarlightPage
+  frontmatter={{
+    title: `AEP-${aep} Linter Rules`,
+    tableOfContents: { minHeadingLevel: 1 },
+  }}
+  headings={[]}
+>
+  <LinterRules rules={rules} preamble={preamble} />
+</StarlightPage>