From 769b286cf2f41ebd0234fb8a493bf35da7931595 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sun, 18 Jan 2026 19:15:59 +0000
Subject: [PATCH] fix: make docs list node-safe

---
 docs/debug/node-issue.md |  7 +++++++
 scripts/docs-list.js     | 35 ++++++++++++++++++++++-------------
 2 files changed, 29 insertions(+), 13 deletions(-)

diff --git a/docs/debug/node-issue.md b/docs/debug/node-issue.md
index d061170d1..575337c65 100644
--- a/docs/debug/node-issue.md
+++ b/docs/debug/node-issue.md
@@ -1,3 +1,10 @@
+---
+summary: Node + tsx "__name is not a function" crash notes and workarounds
+read_when:
+  - Debugging Node-only dev scripts or watch mode failures
+  - Investigating tsx/esbuild loader crashes in Clawdbot
+---
+
 # Node + tsx "__name is not a function" crash
 
 ## Summary
diff --git a/scripts/docs-list.js b/scripts/docs-list.js
index 194ea43ec..1daabf0d7 100755
--- a/scripts/docs-list.js
+++ b/scripts/docs-list.js
@@ -14,8 +14,12 @@ const DOCS_DIR = join(process.cwd(), 'docs');
 
 const EXCLUDED_DIRS = new Set(['archive', 'research']);
 
-function compactStrings(values: unknown[]): string[] {
-  const result: string[] = [];
+/**
+ * @param {unknown[]} values
+ * @returns {string[]}
+ */
+function compactStrings(values) {
+  const result = [];
   for (const value of values) {
     if (value === null || value === undefined) {
       continue;
@@ -28,9 +32,14 @@ function compactStrings(values: unknown[]): string[] {
   return result;
 }
 
-function walkMarkdownFiles(dir: string, base: string = dir): string[] {
+/**
+ * @param {string} dir
+ * @param {string} base
+ * @returns {string[]}
+ */
+function walkMarkdownFiles(dir, base = dir) {
   const entries = readdirSync(dir, { withFileTypes: true });
-  const files: string[] = [];
+  const files = [];
   for (const entry of entries) {
     if (entry.name.startsWith('.')) {
       continue;
@@ -48,11 +57,11 @@ function walkMarkdownFiles(dir: string, base: string = dir): string[] {
   return files.sort((a, b) => a.localeCompare(b));
 }
 
-function extractMetadata(fullPath: string): {
-  summary: string | null;
-  readWhen: string[];
-  error?: string;
-} {
+/**
+ * @param {string} fullPath
+ * @returns {{ summary: string | null; readWhen: string[]; error?: string }}
+ */
+function extractMetadata(fullPath) {
   const content = readFileSync(fullPath, 'utf8');
 
   if (!content.startsWith('---')) {
@@ -67,9 +76,9 @@ function extractMetadata(fullPath: string): {
   const frontMatter = content.slice(3, endIndex).trim();
   const lines = frontMatter.split('\n');
 
-  let summaryLine: string | null = null;
-  const readWhen: string[] = [];
-  let collectingField: 'read_when' | null = null;
+  let summaryLine = null;
+  const readWhen = [];
+  let collectingField = null;
 
   for (const rawLine of lines) {
     const line = rawLine.trim();
@@ -85,7 +94,7 @@ function extractMetadata(fullPath: string): {
       const inline = line.slice('read_when:'.length).trim();
       if (inline.startsWith('[') && inline.endsWith(']')) {
         try {
-          const parsed = JSON.parse(inline.replace(/'/g, '"')) as unknown;
+          const parsed = JSON.parse(inline.replace(/'/g, '"'));
           if (Array.isArray(parsed)) {
             readWhen.push(...compactStrings(parsed));
           }