Refactor RSS feed update process: enhance automation, add validation scripts, and improve documentation

Co-authored-by: Copilot <copilot@github.com>

Author: martrapp

.github/skills/update-rss/SKILL.md

@@ -11,34 +11,42 @@ disable-model-invocation: false
 - User asks to update the RSS feed
 
 ## Input
-none
+- No input required from the user beyond confirming that git is up to date.
+
+## High-value automation in this skill
+- Use scripts for the repetitive, easy-to-get-wrong parts of the workflow: mapping RSS entries back to source files, restoring selected `pubDate` values from `HEAD`, and re-sorting `<item>` blocks after those restores.
+- Keep the human review focused on classification only: decide whether each changed page is minor or substantive, then let the scripts apply the mechanical updates.
 
 ## Procedure
 0. Ask the user whether git is up to date. Stop immediately if the user says no. This is important because the process relies on commit dates for time stamps.
 
 1. Run `npm run build` to update last update dates for all pages. Stop immediately if the build fails.
 
-2. Run `node bin/rss-update.ts` to update the `public/rss.xml` file. The script also creates `src/content/docs/rss.md`, but that file is intentionally out of scope for this workflow and must be left untouched. Only `public/rss.xml` is reviewed and corrected manually. The script reassigns dates to all entries based on file modification times, even if the actual content changes are minor.
+2. Run `node bin/rss-update.ts` to update the `public/rss.xml` file. The script also updates `src/content/docs/rss.md`, and that generated file should be kept as produced by the script. Do not restore `src/content/docs/rss.md` to `HEAD`, and do not manually edit it in this workflow. Only `public/rss.xml` is reviewed and corrected manually. The script reassigns dates to all entries based on file modification times, even if the actual content changes are minor.
 
-3. Run `node .github/skills/update-rss/diff-rss.cjs` to identify which existing entries have changed `pubDate` values versus `HEAD`, and which are brand new.
+3. Run `node .github/skills/update-rss/diff-rss.ts` to identify which existing entries have changed `pubDate` values versus `HEAD`, and which are brand new. The output now includes the source content path for each entry, so do not derive the path manually from the URL unless the script reports an unresolved fallback path.
 
-4. For each entry listed as CHANGED: the `guid` value is the URL of the page; derive the source file path from it (e.g. `https://vtbag.dev/basics/api/` → `src/content/docs/basics/api.mdx`). Check whether the change since the old `pubDate` is minor:
+4. For each entry listed as CHANGED, use the source file path reported by `node .github/skills/update-rss/diff-rss.ts`. Check whether the change since the old `pubDate` is minor:
   - Find the commit that was current as of the committed `pubDate`: `git log --before="<committedPubDate>" -1 --format="%H" -- <sourceFile>`
   - Get the diff to the current file: `git --no-pager diff <hash> -- <sourceFile>`
   - A diff is **minor** if the page keeps the same user-facing purpose and technical takeaways, even when wording is expanded or reorganized for clarity.
   - Treat as **minor**: grammar/style fixes, formatting, link updates, readability rewrites, sentence/paragraph reshuffling, and examples or clarifications that do not change recommendations or factual claims.
   - A diff is **substantive** only if it changes what the reader should do or believe: new/removed features, changed compatibility/support statements, changed API semantics, changed recommended patterns, or added/removed constraints/caveats.
   - If uncertain, apply this test: if an experienced reader would keep the same implementation decisions after reading both versions, classify as **minor**.
-  - If the change is minor, replace the new `pubDate` in `public/rss.xml` with the old committed values. Do not make any matching edit in `src/content/docs/rss.md`.
+  - Keep a list of CHANGED entry `guid` values that you classify as **minor**.
   - If the change is substantive, keep the new `pubDate` as is.
 
 5. ADDED entries (new `guid` not in `HEAD`) always keep their new `pubDate` without review.
 
-6. After all `pubDate` adjustments are done, ensure that the `<item>` entries in `public/rss.xml` are sorted by `pubDate` in descending order, with the newest entries first. If reverting a minor change makes an entry older than the items around it, move the whole `<item>` block to its correct position. Do not reorder `src/content/docs/rss.md`.
+6. After classifying all CHANGED entries, restore the old dates for the minor ones with the script instead of editing XML by hand:
+  - Inline GUIDs: `node .github/skills/update-rss/apply-rss-date-overrides.ts <guid> <guid> ...`
+  - Or use a file with one GUID per line: `node .github/skills/update-rss/apply-rss-date-overrides.ts --guid-file /tmp/minor-rss-guids.txt`
+  - The script restores `pubDate` values from `HEAD` only for the selected GUIDs and automatically re-sorts all `<item>` entries in `public/rss.xml` by descending `pubDate`.
+  - Do not make any matching edit in `src/content/docs/rss.md`, and do not restore that file to `HEAD`.
 
 7. Validate the final result:
-  - Run `node .github/skills/update-rss/diff-rss.cjs` again and confirm that only the intended substantive entries still appear under CHANGED.
-  - Run `node .github/skills/update-rss/check-rss-sort.cjs` and confirm it prints `RSS_SORT_OK`.
+  - Run `node .github/skills/update-rss/diff-rss.ts` again and confirm that only the intended substantive entries still appear under CHANGED.
+  - Run `node .github/skills/update-rss/check-rss-sort.ts` and confirm it prints `RSS_SORT_OK`.
 
 ## URL to source file mapping
 - `https://vtbag.dev/<path>/` → `src/content/docs/<path>.mdx` (or `.md`)

.github/skills/update-rss/apply-rss-date-overrides.ts

@@ -0,0 +1,108 @@
+import fs from 'node:fs';
+import {
+  itemsByGuid,
+  parseRss,
+  readHeadRssFile,
+  readRssFile,
+  replacePubDate,
+  serializeRss,
+  sortItemsByPubDate,
+} from './rss-utils.ts';
+
+function usage(): void {
+  console.log('Usage: node .github/skills/update-rss/apply-rss-date-overrides.ts [--guid-file <path>] [--dry-run] <guid> [<guid> ...]');
+}
+
+function parseArgs(argv: string[]): { dryRun: boolean; guids: string[] } {
+  const guids: string[] = [];
+  let guidFile: string | undefined;
+  let dryRun = false;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === '--guid-file') {
+      guidFile = argv[index + 1];
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--dry-run') {
+      dryRun = true;
+      continue;
+    }
+
+    if (arg === '--help' || arg === '-h') {
+      usage();
+      process.exit(0);
+    }
+
+    guids.push(arg);
+  }
+
+  if (guidFile) {
+    const fileGuids = fs.readFileSync(guidFile, 'utf8')
+      .split(/\r?\n/)
+      .map(line => line.trim())
+      .filter(Boolean);
+    guids.push(...fileGuids);
+  }
+
+  return {
+    dryRun,
+    guids: [...new Set(guids)],
+  };
+}
+
+const { dryRun, guids } = parseArgs(process.argv.slice(2));
+
+if (guids.length === 0) {
+  usage();
+  console.error('Provide at least one GUID to restore from HEAD.');
+  process.exit(1);
+}
+
+const parsedCurrent = parseRss(readRssFile());
+const currentByGuid = itemsByGuid(parsedCurrent.items);
+const committedByGuid = itemsByGuid(parseRss(readHeadRssFile()).items);
+const restored = [];
+
+for (const guid of guids) {
+  const currentItem = currentByGuid.get(guid);
+  if (!currentItem) {
+    console.error(`GUID missing in current RSS: ${guid}`);
+    process.exit(1);
+  }
+
+  const committedItem = committedByGuid.get(guid);
+  if (!committedItem?.pubDate) {
+    console.error(`GUID missing in HEAD RSS: ${guid}`);
+    process.exit(1);
+  }
+
+  currentItem.pubDate = committedItem.pubDate;
+  currentItem.xml = replacePubDate(currentItem.xml, committedItem.pubDate);
+  restored.push({
+    guid,
+    pubDate: committedItem.pubDate,
+    sourcePath: currentItem.sourcePath,
+    title: currentItem.title,
+  });
+}
+
+const sortedItems = sortItemsByPubDate(parsedCurrent.items);
+const nextXml = serializeRss({
+  prefix: parsedCurrent.prefix,
+  items: sortedItems,
+  suffix: parsedCurrent.suffix,
+});
+
+if (!dryRun) {
+  fs.writeFileSync('public/rss.xml', nextXml);
+}
+
+console.log(`${dryRun ? 'WOULD_RESTORE' : 'RESTORED'} ${restored.length}`);
+for (const entry of restored) {
+  console.log(`= ${entry.guid} | ${entry.pubDate} | ${entry.sourcePath ?? 'UNKNOWN_SOURCE'} | ${entry.title}`);
+}
+console.log(`${dryRun ? 'WOULD_SORT' : 'SORTED'} public/rss.xml`);

…hub/skills/update-rss/check-rss-sort.cjs …thub/skills/update-rss/check-rss-sort.ts.github/skills/update-rss/check-rss-sort.cjs renamed to .github/skills/update-rss/check-rss-sort.ts .github/skills/update-rss/check-rss-sort.cjs renamed to .github/skills/update-rss/check-rss-sort.ts

@@ -1,14 +1,12 @@
-const fs = require('fs');
+import { parseRss, readRssFile } from './rss-utils.ts';
 
-const xml = fs.readFileSync('public/rss.xml', 'utf8');
-const items = [...xml.matchAll(/<item>[\s\S]*?<\/item>/g)].map((match) => match[0]);
-let previousTimestamp = Infinity;
+const items = parseRss(readRssFile()).items;
+let previousTimestamp = Number.POSITIVE_INFINITY;
 let isSorted = true;
 
 for (const item of items) {
-  const guid = (item.match(/<guid[^>]*>([^<]+)<\/guid>/) || [])[1];
-  const pubDate = (item.match(/<pubDate>([^<]+)<\/pubDate>/) || [])[1];
-  const timestamp = Date.parse(pubDate);
+  const { guid, pubDate } = item;
+  const timestamp = Date.parse(pubDate ?? '');
 
   if (Number.isNaN(timestamp)) {
     console.log(`INVALID_DATE ${guid} | ${pubDate}`);

.github/skills/update-rss/diff-rss.cjs

@@ -0,0 +1,39 @@
+import {
+  itemsByGuid,
+  parseRss,
+  readHeadRssFile,
+  readRssFile,
+} from './rss-utils.ts';
+
+const committedEntries = itemsByGuid(parseRss(readHeadRssFile()).items);
+const currentEntries = itemsByGuid(parseRss(readRssFile()).items);
+const added = [];
+const changed = [];
+
+for (const [guid, entry] of currentEntries) {
+  if (!committedEntries.has(guid)) {
+    added.push({ guid, ...entry });
+    continue;
+  }
+
+  const committedEntry = committedEntries.get(guid);
+  if (committedEntry?.pubDate !== entry.pubDate) {
+    changed.push({
+      guid,
+      sourcePath: entry.sourcePath,
+      title: entry.title,
+      oldPubDate: committedEntry?.pubDate,
+      newPubDate: entry.pubDate,
+    });
+  }
+}
+
+console.log(`ADDED ${added.length}`);
+for (const entry of added) {
+  console.log(`+ ${entry.guid} | ${entry.pubDate} | ${entry.sourcePath ?? 'UNKNOWN_SOURCE'} | ${entry.title}`);
+}
+
+console.log(`CHANGED ${changed.length}`);
+for (const entry of changed) {
+  console.log(`* ${entry.guid} | ${entry.oldPubDate} => ${entry.newPubDate} | ${entry.sourcePath ?? 'UNKNOWN_SOURCE'} | ${entry.title}`);
+}

.github/skills/update-rss/diff-rss.ts

@@ -0,0 +1,112 @@
+import fs from 'node:fs';
+import { execSync } from 'node:child_process';
+
+export type RssItem = {
+  index: number;
+  xml: string;
+  guid?: string;
+  pubDate?: string;
+  title?: string;
+  sourcePath?: string;
+};
+
+export type ParsedRss = {
+  prefix: string;
+  items: RssItem[];
+  suffix: string;
+};
+
+export function readRssFile(filePath = 'public/rss.xml'): string {
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+export function readHeadRssFile(filePath = 'public/rss.xml'): string {
+  return execSync(`git show HEAD:${filePath}`, {
+    encoding: 'utf8',
+  });
+}
+
+export function extractTagValue(xml: string, tagName: string): string | undefined {
+  const match = xml.match(new RegExp(`<${tagName}[^>]*>([\\s\\S]*?)<\\/${tagName}>`));
+  return match ? match[1].trim() : undefined;
+}
+
+export function extractTitle(xml: string): string | undefined {
+  const cdataMatch = xml.match(/<title><!\[CDATA\[([\s\S]*?)\]\]><\/title>/);
+  if (cdataMatch) return cdataMatch[1];
+  return extractTagValue(xml, 'title');
+}
+
+export function guidToSourcePath(guid: string): string | undefined {
+  if (!guid.startsWith('https://vtbag.dev/')) return undefined;
+
+  const pathname = new URL(guid).pathname.replace(/\/+$/, '');
+  const relativePath = pathname === '' ? 'index' : pathname.slice(1);
+  const mdxPath = `src/content/docs/${relativePath}.mdx`;
+  const mdPath = `src/content/docs/${relativePath}.md`;
+
+  if (fs.existsSync(mdxPath)) return mdxPath;
+  if (fs.existsSync(mdPath)) return mdPath;
+
+  return `${mdxPath} | ${mdPath}`;
+}
+
+export function parseRss(xml: string): ParsedRss {
+  const itemMatches = [...xml.matchAll(/<item>[\s\S]*?<\/item>/g)];
+  const firstItem = itemMatches[0];
+  const lastItem = itemMatches.at(-1);
+  const prefix = firstItem ? xml.slice(0, firstItem.index) : xml;
+  const suffix = firstItem && lastItem
+    ? xml.slice(lastItem.index + lastItem[0].length)
+    : '';
+
+  const items = itemMatches.map((match, index) => {
+    const itemXml = match[0];
+    const guid = extractTagValue(itemXml, 'guid');
+    const pubDate = extractTagValue(itemXml, 'pubDate');
+    const title = extractTitle(itemXml);
+
+    return {
+      index,
+      xml: itemXml,
+      guid,
+      pubDate,
+      title,
+      sourcePath: guid ? guidToSourcePath(guid) : undefined,
+    } satisfies RssItem;
+  });
+
+  return { prefix, items, suffix };
+}
+
+export function itemsByGuid(items: RssItem[]): Map<string, RssItem> {
+  return new Map(items.filter(item => item.guid).map(item => [item.guid as string, item]));
+}
+
+export function replacePubDate(itemXml: string, pubDate: string): string {
+  return itemXml.replace(
+    /<pubDate>[\s\S]*?<\/pubDate>/,
+    `<pubDate>${pubDate}</pubDate>`,
+  );
+}
+
+export function sortItemsByPubDate(items: RssItem[]): RssItem[] {
+  return [...items].sort((left, right) => {
+    const rightTimestamp = Date.parse(right.pubDate ?? '');
+    const leftTimestamp = Date.parse(left.pubDate ?? '');
+
+    if (Number.isNaN(leftTimestamp) || Number.isNaN(rightTimestamp)) {
+      throw new Error('Cannot sort RSS items with invalid pubDate values.');
+    }
+
+    return rightTimestamp - leftTimestamp || left.index - right.index;
+  });
+}
+
+export function serializeRss({ prefix, items, suffix }: ParsedRss): string {
+  if (items.length === 0) return prefix + suffix;
+  const itemIndent = prefix.match(/(?:^|\n)([ \t]*)$/)?.[1] ?? '';
+  const [firstItem, ...remainingItems] = items;
+
+  return `${prefix}${firstItem.xml}${remainingItems.map(item => `\n\n${itemIndent}${item.xml}`).join('')}${suffix}`;
+}