Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

17.4 KB
Raw Blame
import fs from 'node:fs'
import path from 'node:path'
import { fileURLToPath } from 'node:url'

const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..')
const routerDir = path.join(repoRoot, 'openviking/server/routers')
const locales = ['zh', 'en']
const allApiDocs = locales.flatMap((locale) =>
  fs.readdirSync(path.join(repoRoot, 'docs', locale, 'api'))
    .filter((file) => file.endsWith('.md'))
    .map((file) => path.join(repoRoot, 'docs', locale, 'api', file))
)
const apiDocs = allApiDocs.filter(
  (file) => !path.basename(file).startsWith('01-') && !path.basename(file).startsWith('99-')
)
const overviewDocs = locales.map((locale) =>
  path.join(repoRoot, 'docs', locale, 'api', '01-overview.md')
)
const httpMethods = 'GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS|PROPFIND|MKCOL|MOVE'

function normalizePath(value) {
  const pathname = value.split('?')[0].replace(/\/$/, '') || '/'
  return pathname.replace(/\{[^}:]+(?::[^}]+)?\}/g, '{}')
}

function closingDelimiter(source, openingIndex, opening = '(', closing = ')') {
  let depth = 0
  let quote = ''
  let escaped = false
  for (let index = openingIndex; index < source.length; index++) {
    const character = source[index]
    if (quote) {
      if (escaped) escaped = false
      else if (character === '\\') escaped = true
      else if (character === quote) quote = ''
      continue
    }
    if (character === '"' || character === "'" || character === '`') {
      quote = character
      continue
    }
    if (character === opening) depth++
    else if (character === closing && --depth === 0) return index
  }
  return -1
}

function splitTopLevel(source) {
  const parts = []
  let start = 0
  const stack = []
  let quote = ''
  let escaped = false
  const pairs = { '(': ')', '[': ']', '{': '}' }
  for (let index = 0; index < source.length; index++) {
    const character = source[index]
    if (quote) {
      if (escaped) escaped = false
      else if (character === '\\') escaped = true
      else if (character === quote) quote = ''
      continue
    }
    if (character === '"' || character === "'" || character === '`') quote = character
    else if (pairs[character]) stack.push(pairs[character])
    else if (character === stack.at(-1)) stack.pop()
    else if (character === ',' && stack.length === 0) {
      parts.push(source.slice(start, index).trim())
      start = index + 1
    }
  }
  const tail = source.slice(start).trim()
  if (tail) parts.push(tail)
  return parts
}

const routes = new Map()
const middlewareQueryParameters = new Set(['profile'])
// Studio management routes are internal UI APIs, not part of the public HTTP reference.
const internalRouterFiles = new Set([
  'bot_studio.py',
  'console.py',
  'debug.py',
  'stats.py',
  'user_settings.py',
])
const routerFiles = fs.readdirSync(routerDir)
  .filter((name) => name.endsWith('.py') && !internalRouterFiles.has(name))
  .map((name) => path.join(routerDir, name))
// Gateway management is a public API owned by its ASGI application, including
// when that application is embedded in the server.
const gatewayManagement = path.join(repoRoot, 'openviking_gateway/management.py')
routerFiles.push(gatewayManagement)
// Both hosts mount the gateway application at MOUNT_PATH.
const gatewayMount = fs
  .readFileSync(path.join(repoRoot, 'openviking_gateway/config.py'), 'utf8')
  .match(/^MOUNT_PATH\s*=\s*["']([^"']+)["']/m)[1]
for (const routerFile of routerFiles) {
  const file = path.basename(routerFile)
  const isGateway = routerFile === gatewayManagement
  const source = fs.readFileSync(routerFile, 'utf8')
  const prefixConstant = source.match(/^PREFIX\s*=\s*["']([^"']+)["']/m)?.[1]
  const routerPrefix =
    source.match(/router\s*=\s*APIRouter\([^)]*prefix=["']([^"']+)/s)?.[1] ??
    (source.match(/router\s*=\s*APIRouter\([^)]*prefix=PREFIX\b/s) ? prefixConstant : '') ?? ''
  const mountPrefix = file === 'bot.py' ? '/bot/v1' : isGateway ? gatewayMount : ''
  // Gateway upstreams and policies share the handlers that object_routes(kind) registers.
  const objectKinds = Array.from(source.matchAll(/object_routes\(\s*["']([^"']+)["']/g),
    (match) => match[1])
  const decorators = [
    ...Array.from(
      source.matchAll(/@router\.(get|post|put|patch|delete)\(\s*f?["']([^"']*)/g),
      (match) => ({
        index: match.index,
        methods: [match[1].toUpperCase()],
        // Unescape f-string braces.
        path: match[2].replaceAll('{{', '{').replaceAll('}}', '}'),
        sourceLength: match[0].length,
      })
    ),
    ...Array.from(
      source.matchAll(
        /@router\.api_route\(\s*["']([^"']*)["']\s*,\s*methods\s*=\s*\[([^\]]+)\]/g
      ),
      (match) => ({
        index: match.index,
        methods: Array.from(match[2].matchAll(/["']([A-Z]+)["']/g), (item) => item[1]),
        path: match[1],
        sourceLength: match[0].length,
      })
    ),
  ].sort((a, b) => a.index - b.index)

  for (const decorator of decorators) {
    const definition = source.indexOf('def ', decorator.index + decorator.sourceLength)
    const opening = source.indexOf('(', definition)
    const closing = closingDelimiter(source, opening)
    const signature = closing < 0 ? '' : source.slice(opening + 1, closing)
    const routePath = mountPrefix + routerPrefix + decorator.path
    const pathParameters = new Set(
      Array.from(routePath.matchAll(/\{([^}:]+)(?::[^}]+)?\}/g), (item) => item[1])
    )
    const query = new Map()
    for (const parameter of splitTopLevel(signature)) {
      const queryMatch = parameter.match(/^([A-Za-z_]\w*)\s*:[\s\S]*?=\s*Query\(([\s\S]*)\)$/)
      if (queryMatch) {
        const alias = queryMatch[2].match(/\balias\s*=\s*["']([^"']+)["']/)?.[1]
        query.set(alias ?? queryMatch[1], /^\s*\.\.\.(?:\s*,|\s*$)/.test(queryMatch[2]))
        continue
      }

      const defaultMatch = parameter.match(/^([A-Za-z_]\w*)\s*:[\s\S]*?=\s*([\s\S]+)$/)
      if (!defaultMatch || pathParameters.has(defaultMatch[1])) continue
      if (
        /^(?:Path|Depends|Body|Header|Cookie|File|Form|Security)\s*\(/.test(defaultMatch[2])
      ) continue
      query.set(defaultMatch[1], false)
    }
    // The caller dependency consumes account_id directly from query_params.
    if (isGateway) query.set('account_id', false)
    const concretePaths = routePath.includes('{kind}')
      ? objectKinds.map((kind) => routePath.replace('{kind}', kind))
      : [routePath]
    for (const concretePath of concretePaths) {
      const concreteParameters = new Set(
        Array.from(concretePath.matchAll(/\{([^}:]+)(?::[^}]+)?\}/g), (item) => item[1])
      )
      for (const method of decorator.methods) {
        routes.set(`${method} ${normalizePath(concretePath)}`, {
          query, pathParameters: concreteParameters,
        })
      }
    }
  }
}

const clientSource = fs.readFileSync(path.join(repoRoot, 'sdk/typescript/src/client.ts'), 'utf8')
const clientMethods = new Map()
for (const match of clientSource.matchAll(/^  (?:async )?([A-Za-z][A-Za-z0-9]*)\s*\(/gm)) {
  const opening = clientSource.indexOf('(', match.index)
  const closing = closingDelimiter(clientSource, opening)
  if (closing < 0) continue
  const parameters = splitTopLevel(clientSource.slice(opening + 1, closing))
  const required = parameters.filter((parameter) => {
    const declaration = parameter.split(':', 1)[0]
    return !declaration.includes('?') && !parameter.includes('=') && !parameter.startsWith('...')
  }).length
  clientMethods.set(match[1], {
    required,
    maximum: parameters.some((parameter) => parameter.startsWith('...'))
      ? Infinity
      : parameters.length,
    parameters
  })
}

const errors = []
let httpExamples = 0
let typescriptCalls = 0
const curlUrlPattern = String.raw`["']?https?:\/\/[^/\s"']+(\/[A-Za-z0-9_{}<>?=&./:-]+)`
const detailCoverage = new Map(locales.map((locale) => [locale, new Set()]))

function findRoute(method, documentedPath) {
  const normalizedPath = normalizePath(documentedPath)
  const exact = routes.get(`${method} ${normalizedPath}`)
  if (exact) return exact
  for (const [candidate, candidateContract] of routes) {
    const separator = candidate.indexOf(' ')
    const candidateMethod = candidate.slice(0, separator)
    const candidatePath = candidate.slice(separator + 1)
    if (candidateMethod !== method) continue
    const placeholderPattern = candidatePath.startsWith('/webdav/resources/{}')
      ? '.+'
      : '[^/]+'
    const pattern = candidatePath
      .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
      .replace(/\\\{\\\}/g, placeholderPattern)
    if (new RegExp(`^${pattern}$`).test(normalizedPath)) return candidateContract
  }
  return undefined
}

function tableReferences(source) {
  const references = []
  for (const line of source.split(/\r?\n/)) {
    if (!line.startsWith('|')) continue
    const cells = line.split('|').slice(1, -1).map((cell) => cell.trim())
    if (cells.length < 2) continue
    const methodCell = cells[0].replaceAll('`', '')
    const methods = Array.from(
      methodCell.matchAll(new RegExp(`\\b(${httpMethods})\\b`, 'g')),
      (match) => match[1]
    )
    const paths = Array.from(
      cells[1].matchAll(/`(\/[A-Za-z0-9_{}./:-]+)`/g),
      (match) => match[1]
    )
    for (const method of methods) {
      for (const documentedPath of paths) references.push([method, documentedPath])
    }
  }
  return references
}

function curlReferences(source) {
  const references = []
  for (const match of source.matchAll(/\bcurl\b[^\n]*(?:\r?\n[ \t]+(?:--|-H\b)[^\n]*)*/g)) {
    const command = match[0]
    const url = command.match(new RegExp(curlUrlPattern))
    if (!url) continue

    const explicitMethod = command.match(
      new RegExp(`(?:-X|--request)\\s+(${httpMethods})\\b`)
    )?.[1]
    const method = explicitMethod ?? 'GET'
    let documentedPath = url[1]
    const queryNames = Array.from(
      command.matchAll(/--data-urlencode\s+["']?([A-Za-z_]\w*)=/g),
      (item) => item[1]
    )
    if (queryNames.length) {
      const existingNames = new Set(
        (documentedPath.split('?')[1] ?? '')
          .split('&')
          .filter(Boolean)
          .map((item) => item.split('=')[0])
      )
      const missing = queryNames.filter((name) => !existingNames.has(name))
      if (missing.length) {
        documentedPath += `${documentedPath.includes('?') ? '&' : '?'}${missing
          .map((name) => `${name}={}`)
          .join('&')}`
      }
    }
    references.push([method, documentedPath])
  }
  return references
}

for (const file of apiDocs) {
  const source = fs.readFileSync(file, 'utf8')
  const relative = path.relative(repoRoot, file)
  const locale = relative.split(path.sep)[1]
  const httpReferences = [
    ...Array.from(
      source.matchAll(
        new RegExp(
          `\\b(${httpMethods})\\s+((?:\\/api\\/|\\/webdav\\/|\\/bot\\/|\\/(?:health|ready|metrics)\\b)` +
          `[A-Za-z0-9_{}?=&./:-]*)`,
          'g'
        )
      ),
      (match) => [match[1], match[2]]
    ),
    ...curlReferences(source),
    ...tableReferences(source),
  ]
  for (const [method, documentedPath] of httpReferences) {
    const normalizedPath = normalizePath(documentedPath)
    const route = `${method} ${normalizedPath}`
    detailCoverage.get(locale).add(route)
    httpExamples++
    const contract = findRoute(method, documentedPath)
    if (!contract) {
      errors.push(`${relative}: unknown HTTP route ${route}`)
      continue
    }
    const documentedPathParameters = new Set(
      Array.from(documentedPath.split('?')[0].matchAll(/\{([^}]+)\}/g), (item) => item[1])
    )
    if (documentedPathParameters.size) {
      for (const name of documentedPathParameters) {
        if (!contract.pathParameters.has(name)) {
          errors.push(`${relative}: ${route} has unknown path parameter ${name}`)
        }
      }
      for (const name of contract.pathParameters) {
        if (!documentedPathParameters.has(name)) {
          errors.push(`${relative}: ${route} is missing path parameter ${name}`)
        }
      }
    }
    const queryNames = new Set(
      (documentedPath.split('?')[1] ?? '')
        .split('&')
        .filter(Boolean)
        .map((item) => item.split('=')[0])
    )
    for (const name of queryNames) {
      if (!contract.query.has(name) && !middlewareQueryParameters.has(name)) {
        errors.push(`${relative}: ${route} has unknown query parameter ${name}`)
      }
    }
    for (const [name, required] of contract.query) {
      if (required && !queryNames.has(name)) {
        errors.push(`${relative}: ${route} is missing required query parameter ${name}`)
      }
    }
  }
  for (const block of source.matchAll(/```(?:typescript|ts)\n([\s\S]*?)\n```/g)) {
    for (const call of block[1].matchAll(/\bclient\.([A-Za-z][A-Za-z0-9]*)\s*\(/g)) {
      typescriptCalls++
      const contract = clientMethods.get(call[1])
      if (!contract) {
        errors.push(`${relative}: unknown TypeScript SDK method client.${call[1]}()`)
        continue
      }
      const opening = call.index + call[0].lastIndexOf('(')
      const closing = closingDelimiter(block[1], opening)
      if (closing < 0) {
        errors.push(`${relative}: could not parse TypeScript SDK call client.${call[1]}()`)
        continue
      }
      const args = splitTopLevel(block[1].slice(opening + 1, closing))
      const argumentCount = args.length
      if (argumentCount < contract.required || argumentCount > contract.maximum) {
        const expected = contract.required === contract.maximum
          ? String(contract.required)
          : `${contract.required}-${contract.maximum}`
        errors.push(
          `${relative}: client.${call[1]}() has ${argumentCount} arguments; expected ${expected}`
        )
      }
      for (let index = 0; index < Math.min(args.length, contract.parameters.length); index++) {
        const type = contract.parameters[index].match(/:\s*([^=]+?)(?:\s*=|$)/)?.[1]?.trim()
        if (type === 'string' && /^[{[]/.test(args[index])) {
          errors.push(`${relative}: client.${call[1]}() argument ${index + 1} must be a string`)
        }
      }
    }
  }
}

function routeIsCovered(route, coverage) {
  if (coverage.has(route)) return true
  const separator = route.indexOf(' ')
  const method = route.slice(0, separator)
  const routePath = route.slice(separator + 1)
  const pattern = routePath
    .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
    .replace(
      /\\\{\\\}/g,
      routePath.startsWith('/webdav/resources/{}') ? '.+' : '[^/]+'
    )
  for (const reference of coverage) {
    const referenceSeparator = reference.indexOf(' ')
    if (reference.slice(0, referenceSeparator) !== method) continue
    if (new RegExp(`^${pattern}$`).test(reference.slice(referenceSeparator + 1))) return true
  }
  return false
}

const overviewCoverage = new Map()
for (const file of overviewDocs) {
  const source = fs.readFileSync(file, 'utf8')
  const relative = path.relative(repoRoot, file)
  const locale = relative.split(path.sep)[1]
  const coverage = new Set()
  for (const row of source.matchAll(
    new RegExp(`^\\|\\s*(${httpMethods})(?:\\s*\\/\\s*(${httpMethods}))?\\s*\\|([^\\n]+)$`, 'gm')
  )) {
    const methods = [row[1], row[2]].filter(Boolean)
    const documentedPaths = Array.from(
      row[3].matchAll(/`(\/[A-Za-z0-9_{}./:-]+)`/g),
      (match) => match[1]
    )
    for (const method of methods) {
      for (const documentedPath of documentedPaths) {
        const route = `${method} ${normalizePath(documentedPath)}`
        coverage.add(route)
        if (!findRoute(method, documentedPath)) {
          errors.push(`${relative}: overview contains unknown HTTP route ${route}`)
        }
      }
    }
  }
  overviewCoverage.set(locale, coverage)
}

for (const locale of locales) {
  const overview = overviewCoverage.get(locale)
  const details = detailCoverage.get(locale)
  for (const route of routes.keys()) {
    if (!routeIsCovered(route, overview)) {
      errors.push(`docs/${locale}/api/01-overview.md: mounted route missing from overview: ${route}`)
    }
    if (!routeIsCovered(route, details)) {
      errors.push(`docs/${locale}/api: mounted route has no detailed HTTP reference: ${route}`)
    }
  }
  for (const route of overview) {
    if (!routeIsCovered(route, details)) {
      errors.push(`docs/${locale}/api: overview route has no detailed HTTP reference: ${route}`)
    }
  }
}

for (const file of allApiDocs) {
  const source = fs.readFileSync(file, 'utf8')
  const relative = path.relative(repoRoot, file)
  for (const match of source.matchAll(
    new RegExp(`^#{1,6}\\s+(Python SDK|TypeScript SDK|JavaScript SDK|Go SDK|HTTP API|CLI)[::]?\\s*$`, 'gm')
  )) {
    errors.push(
      `${relative}:${source.slice(0, match.index).split('\\n').length}: ` +
      `use a bold invocation label (${match[1]}) so examples render as tabs`
    )
  }
  for (const match of source.matchAll(
    /^\*\*(Python SDK|TypeScript SDK|JavaScript SDK|Go SDK|HTTP API|CLI)\*\*\s*[((]/gm
  )) {
    errors.push(
      `${relative}:${source.slice(0, match.index).split('\n').length}: ` +
      `put the ${match[1]} qualifier inside the bold label with ASCII parentheses`
    )
  }
  for (const match of source.matchAll(
    /^\*\*(Python SDK|TypeScript SDK|JavaScript SDK|Go SDK|HTTP API|CLI)\s*([^)]+)\*\*/gm
  )) {
    errors.push(
      `${relative}:${source.slice(0, match.index).split('\n').length}: ` +
      `use ASCII parentheses in the ${match[1]} invocation label`
    )
  }
}

if (errors.length) {
  console.error(errors.join('\n'))
  process.exitCode = 1
} else {
  console.log(
    `API reference check passed: ${httpExamples} HTTP examples with query contracts, ` +
    `${typescriptCalls} TypeScript SDK calls with signature contracts, ` +
    `${routes.size} mounted routes covered by overview and detail docs`
  )
}