@avelonjs/cli 0.1.0

package/src/docs-check.ts

@@ -0,0 +1,415 @@
+import { existsSync } from 'node:fs'
+import { readdir, readFile } from 'node:fs/promises'
+import { dirname, extname, isAbsolute, join, relative } from 'node:path'
+import * as ts from 'typescript'
+
+import { writeln, type ReeveIO } from './io'
+
+/** One docs:check failure. */
+export interface DocsFinding {
+  /** Machine-readable kind. */
+  kind: 'missing-section' | 'unparsed-code-block' | 'missing-export' | 'missing-readme'
+  /** Human-readable explanation. */
+  message: string
+}
+
+/** Result of linting one package README. */
+export interface DocsCheckResult {
+  /** Package directory that was checked. */
+  root: string
+  /** True when there are no findings. */
+  ok: boolean
+  /** Failures, empty when `ok`. */
+  findings: readonly DocsFinding[]
+}
+
+const REQUIRED_SECTIONS = ['Installation', 'Basic Usage', 'Method Reference', 'Testing'] as const
+
+const PARSEABLE_LANGUAGES = new Set([
+  'ts',
+  'tsx',
+  'typescript',
+  'mts',
+  'cts',
+  'js',
+  'jsx',
+  'javascript',
+  'mjs',
+  'cjs',
+])
+
+interface WaiverSet {
+  sections: Set<string>
+  exports: Set<string>
+}
+
+/** Lints one package README against house-style rules. */
+export async function checkPackageDocs(root: string): Promise<DocsCheckResult> {
+  const findings: DocsFinding[] = []
+  const readmePath = join(root, 'README.md')
+  let readme: string
+  try {
+    readme = await readFile(readmePath, 'utf8')
+  } catch {
+    return {
+      root,
+      ok: false,
+      findings: [
+        {
+          kind: 'missing-readme',
+          message: `README.md is missing. A package without docs is incomplete.`,
+        },
+      ],
+    }
+  }
+
+  const waivers = parseWaivers(readme)
+  const headings = markdownHeadings(readme)
+  for (const section of REQUIRED_SECTIONS) {
+    if (headings.has(section) || waivers.sections.has(section.toLowerCase())) continue
+    findings.push({
+      kind: 'missing-section',
+      message: `Required section '${section}' is missing. Add the heading or an explicit waiver.`,
+    })
+  }
+
+  if (!hasIntroduction(readme)) {
+    findings.push({
+      kind: 'missing-section',
+      message:
+        'Introduction is missing. Put what the package does and when to reach for it under the title, in under five sentences.',
+    })
+  }
+
+  for (const block of markdownCodeBlocks(readme)) {
+    const finding = parseCodeBlock(block.language, block.code, block.index)
+    if (finding !== undefined) findings.push(finding)
+  }
+
+  const documented = documentedExports(readme)
+  const exported = await collectPackageExports(root)
+  for (const name of exported) {
+    if (isExportDocumented(name, documented) || waivers.exports.has(name)) continue
+    findings.push({
+      kind: 'missing-export',
+      message: `Public export '${name}' is missing from the Method Reference table.`,
+    })
+  }
+
+  return { root, ok: findings.length === 0, findings }
+}
+
+/** Runs `docs:check` for one directory or every workspace package. */
+export async function runDocsCheck(argv: readonly string[], io: ReeveIO): Promise<number> {
+  const workspace = argv.includes('--workspace')
+  const targets = argv.filter((arg) => !arg.startsWith('-'))
+  const roots = workspace
+    ? await workspacePackages(io.cwd)
+    : targets.length > 0
+      ? targets.map((target) => (isAbsolute(target) ? target : join(io.cwd, target)))
+      : await defaultRoots(io.cwd)
+
+  if (roots.length === 0) {
+    writeln(io, 'No packages to check.')
+    return 1
+  }
+
+  let failed = 0
+  for (const root of roots) {
+    const result = await checkPackageDocs(root)
+    const label = relative(io.cwd, root) || root
+    if (result.ok) {
+      writeln(io, `${label}: docs:check clean`)
+      continue
+    }
+    failed += 1
+    writeln(io, `${label}: docs:check failed`)
+    for (const finding of result.findings) writeln(io, `  ${finding.kind}: ${finding.message}`)
+  }
+  return failed === 0 ? 0 : 1
+}
+
+async function defaultRoots(cwd: string): Promise<string[]> {
+  if (await isPackageRoot(cwd)) return [cwd]
+  const nested = await workspacePackages(cwd)
+  return nested.length > 0 ? nested : [cwd]
+}
+
+async function workspacePackages(cwd: string): Promise<string[]> {
+  const dir = join(cwd, 'packages')
+  try {
+    const entries = await readdir(dir, { withFileTypes: true })
+    const roots: string[] = []
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue
+      const root = join(dir, entry.name)
+      if (await isPackageRoot(root)) roots.push(root)
+    }
+    return roots.sort()
+  } catch {
+    return []
+  }
+}
+
+async function isPackageRoot(root: string): Promise<boolean> {
+  try {
+    const raw = await readFile(join(root, 'package.json'), 'utf8')
+    const parsed: unknown = JSON.parse(raw)
+    return typeof parsed === 'object' && parsed !== null
+  } catch {
+    return false
+  }
+}
+
+function parseWaivers(readme: string): WaiverSet {
+  const sections = new Set<string>()
+  const exports = new Set<string>()
+  const pattern = /<!--\s*docs:check-waiver:\s*(section|export)\s+([^>]+?)\s*-->/gi
+  for (const match of readme.matchAll(pattern)) {
+    const kind = match[1]?.toLowerCase()
+    const name = match[2]?.trim()
+    if (kind === undefined || name === undefined) continue
+    if (kind === 'section') sections.add(name.toLowerCase())
+    else exports.add(name)
+  }
+  return { sections, exports }
+}
+
+function markdownHeadings(readme: string): Set<string> {
+  const headings = new Set<string>()
+  for (const line of readme.split(/\r?\n/)) {
+    const match = /^##\s+(.+?)\s*$/.exec(line)
+    const title = match?.[1]?.trim()
+    if (title !== undefined) headings.add(title)
+  }
+  return headings
+}
+
+function hasIntroduction(readme: string): boolean {
+  const withoutFence = readme.replace(/^```[\s\S]*?^```/gm, '')
+  const match = /^#\s+.+\n+([\s\S]*?)(?:\n##\s|\s*$)/.exec(withoutFence)
+  const intro = match?.[1]?.trim() ?? ''
+  return intro.length > 0 && !intro.startsWith('#')
+}
+
+interface CodeBlock {
+  language: string
+  code: string
+  index: number
+}
+
+function markdownCodeBlocks(readme: string): CodeBlock[] {
+  const blocks: CodeBlock[] = []
+  const pattern = /^```([^\n`]*)\n([\s\S]*?)^```/gm
+  let index = 0
+  for (const match of readme.matchAll(pattern)) {
+    index += 1
+    blocks.push({
+      language: (match[1] ?? '').trim().toLowerCase(),
+      code: match[2] ?? '',
+      index,
+    })
+  }
+  return blocks
+}
+
+function parseCodeBlock(language: string, code: string, index: number): DocsFinding | undefined {
+  if (language === 'json') {
+    try {
+      JSON.parse(code)
+      return undefined
+    } catch (error) {
+      return {
+        kind: 'unparsed-code-block',
+        message: `Code block ${String(index)} (json) does not parse: ${errorMessage(error)}`,
+      }
+    }
+  }
+  if (language.length === 0 || !PARSEABLE_LANGUAGES.has(language)) return undefined
+  const fileName = language === 'tsx' || language === 'jsx' ? 'example.tsx' : 'example.ts'
+  const transpile = ts.transpileModule(code, {
+    compilerOptions: {
+      module: ts.ModuleKind.ESNext,
+      target: ts.ScriptTarget.ES2022,
+      jsx: ts.JsxEmit.ReactJSX,
+    },
+    reportDiagnostics: true,
+    fileName,
+  })
+  const errors = (transpile.diagnostics ?? []).filter(
+    (diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error,
+  )
+  if (errors.length === 0) return undefined
+  return {
+    kind: 'unparsed-code-block',
+    message: `Code block ${String(index)} (${language}) does not parse: ${formatDiagnostic(errors[0])}`,
+  }
+}
+
+function formatDiagnostic(diagnostic: ts.Diagnostic | undefined): string {
+  if (diagnostic === undefined) return 'syntax error'
+  return ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n')
+}
+
+function documentedExports(readme: string): Set<string> {
+  const names = new Set<string>()
+  const start = readme.search(/^##\s+Method Reference\s*$/m)
+  if (start === -1) return names
+  const rest = readme.slice(start)
+  const endMatch = rest.slice(1).search(/^##\s+/m)
+  const table = endMatch === -1 ? rest : rest.slice(0, endMatch + 1)
+  for (const line of table.split(/\r?\n/)) {
+    if (!line.trim().startsWith('|')) continue
+    const cells = line
+      .trim()
+      .split('|')
+      .slice(1, -1)
+      .map((cell) => cell.trim())
+    const first = cells[0]
+    if (first === undefined || first.length === 0) continue
+    if (/^[-:]+$/.test(first.replace(/\s/g, ''))) continue
+    if (/^method/i.test(first)) continue
+    const token = first.replace(/^`+|`+$/g, '').trim()
+    if (token.length === 0) continue
+    names.add(token)
+  }
+  return names
+}
+
+function isExportDocumented(name: string, documented: Set<string>): boolean {
+  if (documented.has(name)) return true
+  for (const entry of documented) {
+    if (entry === name) return true
+    if (entry.startsWith(`${name}.`)) return true
+  }
+  return false
+}
+
+async function collectPackageExports(root: string): Promise<string[]> {
+  const entry = await packageEntry(root)
+  if (entry === undefined) return []
+  const names = new Set<string>()
+  await collectFromFile(entry, root, names, new Set())
+  return [...names].sort()
+}
+
+async function packageEntry(root: string): Promise<string | undefined> {
+  try {
+    const raw = await readFile(join(root, 'package.json'), 'utf8')
+    const parsed: unknown = JSON.parse(raw)
+    if (typeof parsed !== 'object' || parsed === null) return undefined
+    const exportsField = Reflect.get(parsed, 'exports')
+    const main = Reflect.get(parsed, 'main')
+    const fromExports = resolveExportField(exportsField)
+    const relative = fromExports ?? (typeof main === 'string' ? main : 'src/index.ts')
+    return join(root, relative)
+  } catch {
+    return undefined
+  }
+}
+
+function resolveExportField(exportsField: unknown): string | undefined {
+  if (typeof exportsField === 'string') return exportsField
+  if (typeof exportsField !== 'object' || exportsField === null) return undefined
+  const dot = Reflect.get(exportsField, '.')
+  if (typeof dot === 'string') return dot
+  if (typeof dot === 'object' && dot !== null) {
+    const importPath = Reflect.get(dot, 'import')
+    const defaultPath = Reflect.get(dot, 'default')
+    if (typeof importPath === 'string') return importPath
+    if (typeof defaultPath === 'string') return defaultPath
+  }
+  return undefined
+}
+
+async function collectFromFile(
+  file: string,
+  root: string,
+  names: Set<string>,
+  seen: Set<string>,
+): Promise<void> {
+  if (seen.has(file)) return
+  seen.add(file)
+  let sourceText: string
+  try {
+    sourceText = await readFile(file, 'utf8')
+  } catch {
+    return
+  }
+  const kind = extname(file) === '.tsx' ? ts.ScriptKind.TSX : ts.ScriptKind.TS
+  const source = ts.createSourceFile(file, sourceText, ts.ScriptTarget.Latest, true, kind)
+  for (const statement of source.statements) {
+    if (ts.isExportDeclaration(statement)) {
+      const moduleSpecifier = statement.moduleSpecifier
+      const resolved =
+        moduleSpecifier !== undefined && ts.isStringLiteral(moduleSpecifier)
+          ? resolveRelative(file, root, moduleSpecifier.text)
+          : undefined
+      if (statement.exportClause === undefined) {
+        if (resolved !== undefined) await collectFromFile(resolved, root, names, seen)
+        continue
+      }
+      if (ts.isNamespaceExport(statement.exportClause)) {
+        names.add(statement.exportClause.name.text)
+        continue
+      }
+      for (const element of statement.exportClause.elements) {
+        names.add(element.name.text)
+      }
+      continue
+    }
+    if (ts.isExportAssignment(statement)) {
+      names.add('default')
+      continue
+    }
+    const mods = ts.canHaveModifiers(statement) ? ts.getModifiers(statement) : undefined
+    const exported =
+      mods?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) === true
+    if (!exported) continue
+    if (ts.isFunctionDeclaration(statement) && statement.name !== undefined) {
+      names.add(statement.name.text)
+      continue
+    }
+    if (ts.isClassDeclaration(statement) && statement.name !== undefined) {
+      names.add(statement.name.text)
+      continue
+    }
+    if (ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement)) {
+      names.add(statement.name.text)
+      continue
+    }
+    if (ts.isEnumDeclaration(statement)) {
+      names.add(statement.name.text)
+      continue
+    }
+    if (ts.isVariableStatement(statement)) {
+      for (const declaration of statement.declarationList.declarations) {
+        if (ts.isIdentifier(declaration.name)) names.add(declaration.name.text)
+      }
+    }
+  }
+}
+
+function resolveRelative(fromFile: string, root: string, specifier: string): string | undefined {
+  if (!specifier.startsWith('.')) return undefined
+  const base = join(dirname(fromFile), specifier)
+  const candidates = [
+    base,
+    `${base}.ts`,
+    `${base}.tsx`,
+    `${base}.mts`,
+    `${base}.cts`,
+    join(base, 'index.ts'),
+    join(base, 'index.tsx'),
+  ]
+  for (const candidate of candidates) {
+    const rel = relative(root, candidate)
+    if (rel.startsWith('..')) continue
+    if (existsSync(candidate)) return candidate
+  }
+  return undefined
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}