@agentskit/doc-bridge 1.2.6 → 1.4.0

package/src/index-builder/build-index.ts

@@ -9,6 +9,7 @@ import { renderCapabilitiesJson } from './capabilities.js'
 import { sha256NormalizedV1 } from './content-hash.js'
 import { renderLlmsTxt } from './llms-txt.js'
 import { scanHumanDocs } from './human-adapters/index.js'
+import { discoverNxProjects } from './plugins/nx.js'
 import { discoverPnpmPackages } from './plugins/pnpm-monorepo.js'
 import { scanAgentCorpus } from './scan-corpus.js'
 
@@ -66,7 +67,12 @@ export const buildDocBridgeIndex = (opts: BuildIndexOptions): BuildIndexResult =
     config.routing?.plugin === 'npm-workspaces' ||
     config.routing?.plugin === 'yarn-workspaces'
 
-  const discovered = shouldDiscover ? discoverPnpmPackages(root, config) : []
+  const discovered =
+    config.routing?.plugin === 'nx'
+      ? discoverNxProjects(root, config)
+      : shouldDiscover
+        ? discoverPnpmPackages(root, config)
+        : []
   const packages = collectPackages(config, discovered, corpus)
   const humanDocs = scanHumanDocs(root, config)
 

package/src/index-builder/human-adapters/index.ts

@@ -4,8 +4,11 @@ import { resolve, sep } from 'node:path'
 import type { DocBridgeConfigV1, HumanCorpusConfig } from '../../config/schema.js'
 import { docusaurusAdapter } from './docusaurus.js'
 import { fumadocsAdapter } from './fumadocs.js'
+import { nextraAdapter } from './nextra.js'
 import type { HumanAdapter, HumanDocMap, HumanDocRecord } from './core.js'
 import { plainMarkdownAdapter } from './plain-markdown.js'
+import { starlightAdapter } from './starlight.js'
+import { vitepressAdapter } from './vitepress.js'
 
 export type { HumanAdapter, HumanDocMap, HumanDocRecord } from './core.js'
 
@@ -13,6 +16,9 @@ const ADAPTERS: readonly HumanAdapter[] = [
   plainMarkdownAdapter,
   fumadocsAdapter,
   docusaurusAdapter,
+  vitepressAdapter,
+  starlightAdapter,
+  nextraAdapter,
 ]
 
 const humanConfigs = (config: DocBridgeConfigV1): HumanCorpusConfig[] => {

package/src/index-builder/human-adapters/nextra.ts

@@ -0,0 +1,43 @@
+import {
+  optionString,
+  parseFrontmatter,
+  routeSlug,
+  scanMarkdownDocs,
+  type HumanAdapter,
+  type HumanDocRecord,
+} from './core.js'
+
+const nextraRecordId = (relPath: string, raw: string): string => {
+  const frontmatter = parseFrontmatter(raw)
+  return frontmatter.package ?? frontmatter.module ?? frontmatter.id ?? (routeSlug(relPath) || 'index')
+}
+
+const isIndexPage = (path: string): boolean => /(^|[/\\])index\.mdx?$/i.test(path)
+
+const resolveRouteCollisions = (records: readonly HumanDocRecord[]): HumanDocRecord[] => {
+  const byUrl = new Map<string, { readonly record: HumanDocRecord; readonly indexPage: boolean }>()
+  for (const record of records) {
+    const normalized = { ...record, url: record.url || '/' }
+    const indexPage = isIndexPage(record.path)
+    const existing = byUrl.get(normalized.url)
+    if (!existing || indexPage || !existing.indexPage) {
+      byUrl.set(normalized.url, { record: normalized, indexPage })
+    }
+  }
+  return [...byUrl.values()].map(({ record }) => record)
+}
+
+export const nextraAdapter: HumanAdapter = {
+  plugin: 'nextra',
+  scan: ({ root, config }) => {
+    const contentDir = optionString(config.options, ['contentDir', 'docsDir', 'root'])
+    if (!contentDir) return []
+
+    return resolveRouteCollisions(
+      scanMarkdownDocs(root, contentDir, {
+        idForDoc: nextraRecordId,
+        urlPrefix: optionString(config.options, ['urlPrefix', 'contentDirBasePath']) ?? '/',
+      }),
+    )
+  },
+}

package/src/index-builder/human-adapters/starlight.ts

@@ -0,0 +1,40 @@
+import { slug as githubSlug } from 'github-slugger'
+
+import {
+  optionString,
+  parseFrontmatter,
+  routeSlug,
+  scanMarkdownDocs,
+  type HumanAdapter,
+} from './core.js'
+
+const isStarlightPage = (relPath: string, raw: string): boolean => {
+  if (relPath.split('/').some((part) => part.startsWith('.') || part.startsWith('_'))) return false
+  return parseFrontmatter(raw).draft !== 'true'
+}
+
+const starlightFileSlug = (relPath: string): string =>
+  routeSlug(relPath)
+    .split('/')
+    .map((part) => githubSlug(part))
+    .filter(Boolean)
+    .join('/')
+
+const starlightSlug = (relPath: string, raw: string): string => {
+  const slug = parseFrontmatter(raw).slug
+  return slug ? slug.replace(/^\/+|\/+$/g, '') : starlightFileSlug(relPath)
+}
+
+export const starlightAdapter: HumanAdapter = {
+  plugin: 'starlight',
+  scan: ({ root, config }) => {
+    const contentDir = optionString(config.options, ['contentDir', 'docsDir', 'root'])
+    if (!contentDir) return []
+
+    return scanMarkdownDocs(root, contentDir, {
+      includeRelPath: isStarlightPage,
+      slugForDoc: starlightSlug,
+      urlPrefix: config.options?.urlPrefix,
+    })
+  },
+}

package/src/index-builder/human-adapters/vitepress.ts

@@ -0,0 +1,43 @@
+import { minimatch } from 'minimatch'
+
+import { optionString, routeSlug, scanMarkdownDocs, type HumanAdapter } from './core.js'
+
+const isVitePressPage = (relPath: string): boolean =>
+  !relPath.split('/').some((part) => part === '.vitepress' || part.startsWith('.'))
+
+const srcExcludePatterns = (value: unknown): readonly string[] => {
+  if (value === undefined) return []
+  if (!Array.isArray(value) || value.length > 64) {
+    throw new Error('VitePress srcExclude must be an array of at most 64 glob patterns.')
+  }
+  return value.map((pattern) => {
+    if (typeof pattern !== 'string' || !pattern || pattern.length > 256 || pattern.includes('\0')) {
+      throw new Error('Each VitePress srcExclude pattern must be a non-empty string up to 256 characters.')
+    }
+    return pattern
+  })
+}
+
+const isExcluded = (relPath: string, patterns: readonly string[]): boolean =>
+  patterns.some((pattern) => minimatch(relPath, pattern, { dot: true }))
+
+const vitepressSlug = (relPath: string, cleanUrls: boolean): string => {
+  const slug = routeSlug(relPath)
+  if (cleanUrls || /(?:^|\/)index\.mdx?$/.test(relPath)) return slug
+  return `${slug}.html`
+}
+
+export const vitepressAdapter: HumanAdapter = {
+  plugin: 'vitepress',
+  scan: ({ root, config }) => {
+    const docsDir = optionString(config.options, ['docsDir', 'root', 'srcDir'])
+    if (!docsDir) return []
+    const srcExclude = srcExcludePatterns(config.options?.srcExclude)
+
+    return scanMarkdownDocs(root, docsDir, {
+      includeRelPath: (relPath) => isVitePressPage(relPath) && !isExcluded(relPath, srcExclude),
+      slugForDoc: (relPath) => vitepressSlug(relPath, config.options?.cleanUrls === true),
+      urlPrefix: config.options?.urlPrefix,
+    })
+  },
+}

package/src/index-builder/plugins/nx.ts

@@ -0,0 +1,161 @@
+import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs'
+import { basename, dirname, isAbsolute, relative, resolve, sep } from 'node:path'
+
+import type { DocBridgeConfigV1 } from '../../config/schema.js'
+import { detectPackageManager } from '../../lib/package-manager.js'
+import { toPosix } from '../../lib/paths.js'
+import { walkFiles } from '../../lib/walk.js'
+import type { DiscoveredPackage } from './pnpm-monorepo.js'
+
+const NX_SCAN_SKIP = new Set([
+  'node_modules',
+  '.git',
+  '.nx',
+  'dist',
+  'coverage',
+  '.doc-bridge',
+])
+const NX_PROJECT_NAME = /^(?:@[A-Za-z0-9._-]+\/)?[A-Za-z0-9][A-Za-z0-9._-]*$/
+
+type JsonRecord = Record<string, unknown>
+
+const isRecord = (value: unknown): value is JsonRecord =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const readJsonRecord = (path: string): JsonRecord | undefined => {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'))
+    return isRecord(parsed) ? parsed : undefined
+  } catch {
+    return undefined
+  }
+}
+
+const safeProjectPath = (
+  root: string,
+  manifestDir: string,
+  declaredRoot?: unknown,
+): string | undefined => {
+  const candidate = typeof declaredRoot === 'string' ? resolve(root, declaredRoot) : manifestDir
+  const rel = toPosix(relative(root, candidate)) || '.'
+  if (isAbsolute(rel) || rel === '..' || rel.startsWith('../')) return undefined
+  try {
+    if (!lstatSync(candidate).isDirectory()) return undefined
+    const canonicalRoot = realpathSync.native(root)
+    const canonicalCandidate = realpathSync.native(candidate)
+    const canonicalRel = relative(canonicalRoot, canonicalCandidate)
+    if (
+      isAbsolute(canonicalRel) ||
+      canonicalRel === '..' ||
+      canonicalRel.startsWith(`..${sep}`)
+    ) {
+      return undefined
+    }
+  } catch {
+    return undefined
+  }
+  return rel
+}
+
+const packageId = (name: string): string =>
+  name.startsWith('@') ? (name.split('/').at(-1) ?? name) : name
+
+const commandPrefix = (root: string): string => {
+  const manager = detectPackageManager(root)
+  if (manager === 'pnpm') return 'pnpm exec nx run'
+  if (manager === 'yarn') return 'yarn nx run'
+  if (manager === 'bun') return 'bunx nx run'
+  return 'npx nx run'
+}
+
+const inferredChecks = (
+  root: string,
+  config: DocBridgeConfigV1,
+  projectName: string,
+  targets: ReadonlySet<string>,
+): string[] | undefined => {
+  const prefix = commandPrefix(root)
+  const strict = (config.gates?.preset ?? 'minimal') !== 'minimal'
+  const checks = [
+    ...(targets.has('test') ? [`${prefix} ${projectName}:test`] : []),
+    ...(strict && targets.has('lint') ? [`${prefix} ${projectName}:lint`] : []),
+  ]
+  return checks.length ? checks : undefined
+}
+
+type RankedProject = DiscoveredPackage & {
+  readonly rank: number
+  readonly targets: readonly string[]
+}
+
+export const discoverNxProjects = (
+  root: string,
+  config: DocBridgeConfigV1,
+): DiscoveredPackage[] => {
+  if (!existsSync(resolve(root, 'nx.json'))) return []
+
+  const manifests = walkFiles(root, {
+    extensions: ['project.json', 'package.json'],
+    skipDirs: NX_SCAN_SKIP,
+    maxFiles: 10_000,
+  })
+  const projects = new Map<string, RankedProject>()
+
+  for (const manifest of manifests) {
+    const json = readJsonRecord(manifest)
+    if (!json) continue
+    const manifestDir = dirname(manifest)
+    const manifestName = basename(manifest)
+    const isProjectJson = manifestName === 'project.json'
+    if (!isProjectJson && manifestName !== 'package.json') continue
+    const nx = json.nx
+    if (!isProjectJson && !isRecord(nx)) continue
+
+    const path = safeProjectPath(root, manifestDir, isProjectJson ? json.root : undefined)
+    if (!path) continue
+    const projectPackage = isProjectJson
+      ? readJsonRecord(resolve(root, path, 'package.json'))
+      : undefined
+    const projectName =
+      typeof json.name === 'string'
+        ? json.name
+        : typeof projectPackage?.name === 'string'
+          ? projectPackage.name
+          : basename(path === '.' ? root : path)
+    if (!NX_PROJECT_NAME.test(projectName)) continue
+
+    const targets = new Set<string>()
+    const targetRecord = isProjectJson ? json.targets : isRecord(nx) ? nx.targets : undefined
+    if (isRecord(targetRecord)) {
+      for (const target of Object.keys(targetRecord)) targets.add(target)
+    }
+    if (!isProjectJson && isRecord(json.scripts)) {
+      for (const script of Object.keys(json.scripts)) targets.add(script)
+    }
+
+    const id = packageId(projectName)
+    const rank = isProjectJson ? 2 : 1
+    const existing = projects.get(id)
+    if (existing && existing.path !== path) {
+      throw new Error(
+        `Nx project identity collision for "${id}": "${existing.name ?? id}" at "${existing.path}" and "${projectName}" at "${path}". Use unique Nx project names.`,
+      )
+    }
+    const mergedTargets = [...new Set([...(existing?.targets ?? []), ...targets])]
+    const projectJsonWins = rank >= (existing?.rank ?? 0)
+    const resolvedName = projectJsonWins ? projectName : (existing?.name ?? projectName)
+    const checks = inferredChecks(root, config, resolvedName, new Set(mergedTargets))
+    projects.set(id, {
+      id,
+      path,
+      name: resolvedName,
+      ...(checks ? { checks } : {}),
+      rank: projectJsonWins ? rank : (existing?.rank ?? rank),
+      targets: mergedTargets,
+    })
+  }
+
+  return [...projects.values()]
+    .sort((a, b) => a.id.localeCompare(b.id))
+    .map(({ rank: _rank, targets: _targets, ...project }) => project)
+}

package/src/index-builder/plugins/pnpm-monorepo.ts

@@ -9,6 +9,7 @@ export type DiscoveredPackage = {
   readonly id: string
   readonly path: string
   readonly name?: string
+  readonly checks?: readonly string[]
 }
 
 const parsePnpmWorkspace = (yaml: string): string[] => {

package/src/index-builder/watch-index.ts

@@ -13,6 +13,7 @@ export type WatchIndexOptions = {
 }
 
 const WATCH_PATTERN = /\.(md|mdx|json|ya?ml|mdc)$/i
+const NX_MANIFEST_PATTERN = /(^|[/\\])(project|package)\.json$/i
 
 const collectWatchRoots = (root: string, config: DocBridgeConfigV1, configPath?: string): string[] => {
   const roots = new Set<string>()
@@ -24,7 +25,7 @@ const collectWatchRoots = (root: string, config: DocBridgeConfigV1, configPath?:
     : []
   for (const source of humanSources) {
     const humanOpts = source.options ?? {}
-    for (const key of ['contentDir', 'docsDir', 'root']) {
+    for (const key of ['contentDir', 'docsDir', 'root', 'srcDir']) {
       const value = humanOpts[key]
       if (typeof value === 'string' && value.length) roots.add(resolve(root, value))
     }
@@ -74,6 +75,14 @@ export const watchDocBridgeIndex = (opts: WatchIndexOptions): Promise<number> =>
     })
   }
 
+  const nxRoot = resolve(opts.root)
+  if (opts.config.routing?.plugin === 'nx' && existsSync(nxRoot)) {
+    watch(nxRoot, { recursive: true }, (_event, filename) => {
+      if (!filename || !NX_MANIFEST_PATTERN.test(filename)) return
+      rebuild()
+    })
+  }
+
   const configDir = resolve(opts.root)
   if (existsSync(configDir)) {
     watch(configDir, (_event, filename) => {
@@ -91,4 +100,4 @@ export const watchDocBridgeIndex = (opts: WatchIndexOptions): Promise<number> =>
     process.once('SIGINT', onSignal)
     process.once('SIGTERM', onSignal)
   })
-}
+}

package/src/index.ts

@@ -155,6 +155,7 @@ export {
 export { PACKAGE_VERSION } from './version.js'
 
 export { collectPackages, buildLookup } from './index-builder/build-handoffs.js'
+export { discoverNxProjects } from './index-builder/plugins/nx.js'
 export { projectRootFromConfigPath } from './config/load-config.js'
 export { createDocBridgeRag } from './intelligence/rag.js'
 export { runChatOnce, startInkChat } from './intelligence/chat.js'

package/src/version.ts

@@ -1 +1 @@
-export const PACKAGE_VERSION = '1.2.6'
+export const PACKAGE_VERSION = '1.4.0'