clawhub/scripts/docs-list.ts

#!/usr/bin/env bun

import { existsSync, readdirSync, readFileSync } from 'node:fs'
import { dirname, join, relative } from 'node:path'
import { fileURLToPath } from 'node:url'

const DOCS_DIR = resolveDocsDir()

const EXCLUDED_DIRS = new Set(['archive', 'research'])

function resolveDocsDir() {
  const env = process.env.DOCS_DIR?.trim()
  if (env) return env

  const fromCwd = join(process.cwd(), 'docs')
  if (existsSync(fromCwd)) return fromCwd

  const docsListFile = fileURLToPath(import.meta.url)
  const docsListDir = dirname(docsListFile)
  return join(docsListDir, '..', 'docs')
}

function compactStrings(values: unknown[]): string[] {
  const result: string[] = []
  for (const value of values) {
    if (value === null || value === undefined) continue
    const normalized = String(value).trim()
    if (normalized.length > 0) result.push(normalized)
  }
  return result
}

function walkMarkdownFiles(dir: string, base: string = dir): string[] {
  const entries = readdirSync(dir, { withFileTypes: true })
  const files: string[] = []
  for (const entry of entries) {
    if (entry.name.startsWith('.')) continue
    const fullPath = join(dir, entry.name)
    if (entry.isDirectory()) {
      if (EXCLUDED_DIRS.has(entry.name)) continue
      files.push(...walkMarkdownFiles(fullPath, base))
      continue
    }
    if (entry.isFile() && entry.name.endsWith('.md')) {
      files.push(relative(base, fullPath))
    }
  }
  return files.sort((a, b) => a.localeCompare(b))
}

function extractMetadata(fullPath: string): {
  summary: string | null
  readWhen: string[]
  error?: string
} {
  const content = readFileSync(fullPath, 'utf8')

  if (!content.startsWith('---')) {
    return { summary: null, readWhen: [], error: 'missing front matter' }
  }

  const endIndex = content.indexOf('\n---', 3)
  if (endIndex === -1) {
    return { summary: null, readWhen: [], error: 'unterminated front matter' }
  }

  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

  for (const rawLine of lines) {
    const line = rawLine.trim()

    if (line.startsWith('summary:')) {
      summaryLine = line
      collectingField = null
      continue
    }

    if (line.startsWith('read_when:')) {
      collectingField = 'read_when'
      const inline = line.slice('read_when:'.length).trim()
      if (inline.startsWith('[') && inline.endsWith(']')) {
        try {
          const parsed = JSON.parse(inline.replace(/'/g, '"')) as unknown
          if (Array.isArray(parsed)) {
            readWhen.push(...compactStrings(parsed))
          }
        } catch {
          // ignore malformed inline arrays
        }
      }
      continue
    }

    if (collectingField === 'read_when') {
      if (line.startsWith('- ')) {
        const hint = line.slice(2).trim()
        if (hint) readWhen.push(hint)
      } else if (line === '') {
        // ignore
      } else {
        collectingField = null
      }
    }
  }

  if (!summaryLine) {
    return { summary: null, readWhen, error: 'summary key missing' }
  }

  const summaryValue = summaryLine.slice('summary:'.length).trim()
  const normalized = summaryValue
    .replace(/^['"]|['"]$/g, '')
    .replace(/\s+/g, ' ')
    .trim()

  if (!normalized) {
    return { summary: null, readWhen, error: 'summary is empty' }
  }

  return { summary: normalized, readWhen }
}

console.log('Listing all markdown files in docs folder:')

const markdownFiles = walkMarkdownFiles(DOCS_DIR)

for (const relativePath of markdownFiles) {
  const fullPath = join(DOCS_DIR, relativePath)
  const { summary, readWhen, error } = extractMetadata(fullPath)
  if (summary) {
    console.log(`${relativePath} - ${summary}`)
    if (readWhen.length > 0) {
      console.log(`  Read when: ${readWhen.join('; ')}`)
    }
  } else {
    const reason = error ? ` - [${error}]` : ''
    console.log(`${relativePath}${reason}`)
  }
}

console.log(
  '\nReminder: keep docs up to date as behavior changes. When your task matches any "Read when" hint above, read that doc before coding, and suggest new coverage when it is missing.',
)