Skip to content

AI-native design editor. Open-source Figma alternative.

2.6 KB
Raw Blame
import { existsSync, readdirSync, readFileSync } from 'node:fs'
import { join, relative, sep } from 'node:path'

export interface GuideMapOptions {
  repoRoot: string
  /** Directory names that are never scanned for guides; hidden directories are always skipped. */
  ignoredDirectories?: readonly string[]
}

export interface GuideMapResult {
  errors: string[]
  /** Nested guides found on disk, repo-relative with `/` separators, sorted. */
  guides: string[]
  /** Guide paths referenced from the root `AGENTS.md`, sorted. */
  listed: string[]
}

export const ROOT_GUIDE = 'AGENTS.md'
const DEFAULT_IGNORED_DIRECTORIES = ['dist', 'node_modules', 'scratch', 'target']
const GUIDE_REFERENCE = /`((?:[\w.-]+\/)+AGENTS\.md)`/g

function walkGuides(directory: string, repoRoot: string, ignored: ReadonlySet<string>): string[] {
  return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
    if (entry.name.startsWith('.') || ignored.has(entry.name)) return []
    const path = join(directory, entry.name)
    if (entry.isDirectory()) return walkGuides(path, repoRoot, ignored)
    if (!entry.isFile() || entry.name !== ROOT_GUIDE) return []
    const rel = relative(repoRoot, path).split(sep).join('/')
    return rel === ROOT_GUIDE ? [] : [rel]
  })
}

/** Guide paths written as inline code in Markdown, for example `packages/core/AGENTS.md`. */
export function listedGuides(markdown: string): string[] {
  const found = new Set<string>()
  for (const match of markdown.matchAll(GUIDE_REFERENCE)) found.add(match[1])
  return [...found].sort()
}

/**
 * Every nested `AGENTS.md` must be reachable from the root guide's map, and every guide the root
 * mentions must exist, so agents that only read the root file are routed to current guides.
 */
export function checkGuideMap(options: GuideMapOptions): GuideMapResult {
  const ignored = new Set(options.ignoredDirectories ?? DEFAULT_IGNORED_DIRECTORIES)
  const rootPath = join(options.repoRoot, ROOT_GUIDE)
  const errors: string[] = []
  if (!existsSync(rootPath)) {
    return { errors: [`Missing root ${ROOT_GUIDE}`], guides: [], listed: [] }
  }

  const guides = walkGuides(options.repoRoot, options.repoRoot, ignored).sort()
  const listed = listedGuides(readFileSync(rootPath, 'utf8'))
  const listedSet = new Set(listed)
  const guideSet = new Set(guides)

  for (const guide of guides) {
    if (!listedSet.has(guide)) errors.push(`${guide} is not listed in the root ${ROOT_GUIDE} map`)
  }
  for (const guide of listed) {
    if (!guideSet.has(guide)) errors.push(`Root ${ROOT_GUIDE} references missing guide ${guide}`)
  }

  return { errors, guides, listed }
}