@atproto/lex-cli 0.10.1 → 0.10.3

package/src/codegen/server.ts

@@ -1,448 +0,0 @@
-import {
-  IndentationText,
-  Project,
-  SourceFile,
-  VariableDeclarationKind,
-} from 'ts-morph'
-import { type LexiconDoc, Lexicons } from '@atproto/lexicon'
-import { NSID } from '@atproto/syntax'
-import { type GeneratedAPI } from '../types.js'
-import { gen, lexiconsTs, utilTs } from './common.js'
-import {
-  genCommonImports,
-  genImports,
-  genRecord,
-  genUserType,
-  genXrpcInput,
-  genXrpcOutput,
-  genXrpcParams,
-} from './lex-gen.js'
-import {
-  type DefTreeNode,
-  lexiconsToDefTree,
-  schemasToNsidTokens,
-  toCamelCase,
-  toScreamingSnakeCase,
-  toTitleCase,
-} from './util.js'
-
-export async function genServerApi(
-  lexiconDocs: LexiconDoc[],
-): Promise<GeneratedAPI> {
-  const project = new Project({
-    useInMemoryFileSystem: true,
-    manipulationSettings: { indentationText: IndentationText.TwoSpaces },
-  })
-  const api: GeneratedAPI = { files: [] }
-  const lexicons = new Lexicons(lexiconDocs)
-  const nsidTree = lexiconsToDefTree(lexiconDocs)
-  const nsidTokens = schemasToNsidTokens(lexiconDocs)
-  for (const lexiconDoc of lexiconDocs) {
-    api.files.push(await lexiconTs(project, lexicons, lexiconDoc))
-  }
-  api.files.push(await utilTs(project))
-  api.files.push(await lexiconsTs(project, lexiconDocs))
-  api.files.push(await indexTs(project, lexiconDocs, nsidTree, nsidTokens))
-  return api
-}
-
-const indexTs = (
-  project: Project,
-  lexiconDocs: LexiconDoc[],
-  nsidTree: DefTreeNode[],
-  nsidTokens: Record<string, string[]>,
-) =>
-  gen(project, '/index.ts', async (file) => {
-    //= import {createServer as createXrpcServer, Server as XrpcServer} from '@atproto/xrpc-server'
-    file.addImportDeclaration({
-      moduleSpecifier: '@atproto/xrpc-server',
-      namedImports: [
-        { name: 'Auth', isTypeOnly: true },
-        { name: 'Options', alias: 'XrpcOptions', isTypeOnly: true },
-        { name: 'Server', alias: 'XrpcServer' },
-        { name: 'StreamConfigOrHandler', isTypeOnly: true },
-        { name: 'MethodConfigOrHandler', isTypeOnly: true },
-        { name: 'createServer', alias: 'createXrpcServer' },
-      ],
-    })
-    //= import {schemas} from './lexicons.js'
-    file
-      .addImportDeclaration({
-        moduleSpecifier: './lexicons.js',
-      })
-      .addNamedImport({
-        name: 'schemas',
-      })
-
-    // generate type imports
-    for (const lexiconDoc of lexiconDocs) {
-      if (
-        lexiconDoc.defs.main?.type !== 'query' &&
-        lexiconDoc.defs.main?.type !== 'subscription' &&
-        lexiconDoc.defs.main?.type !== 'procedure'
-      ) {
-        continue
-      }
-      file
-        .addImportDeclaration({
-          moduleSpecifier: `./types/${lexiconDoc.id.split('.').join('/')}.js`,
-        })
-        .setNamespaceImport(toTitleCase(lexiconDoc.id))
-    }
-
-    // generate token enums
-    for (const nsidAuthority in nsidTokens) {
-      // export const {THE_AUTHORITY} = {
-      //  {Name}: "{authority.the.name}"
-      // }
-      file.addVariableStatement({
-        isExported: true,
-        declarationKind: VariableDeclarationKind.Const,
-        declarations: [
-          {
-            name: toScreamingSnakeCase(nsidAuthority),
-            initializer: [
-              '{',
-              ...nsidTokens[nsidAuthority].map(
-                (nsidName) =>
-                  `${toTitleCase(nsidName)}: "${nsidAuthority}.${nsidName}",`,
-              ),
-              '}',
-            ].join('\n'),
-          },
-        ],
-      })
-    }
-
-    //= export function createServer(options?: XrpcOptions) { ... }
-    const createServerFn = file.addFunction({
-      name: 'createServer',
-      returnType: 'Server',
-      parameters: [
-        { name: 'options', type: 'XrpcOptions', hasQuestionToken: true },
-      ],
-      isExported: true,
-    })
-    createServerFn.setBodyText(`return new Server(options)`)
-
-    //= export class Server {...}
-    const serverCls = file.addClass({
-      name: 'Server',
-      isExported: true,
-    })
-    //= xrpc: XrpcServer = createXrpcServer(methodSchemas)
-    serverCls.addProperty({
-      name: 'xrpc',
-      type: 'XrpcServer',
-    })
-
-    // generate classes for the schemas
-    for (const ns of nsidTree) {
-      //= ns: NS
-      serverCls.addProperty({
-        name: ns.propName,
-        type: ns.className,
-      })
-
-      // class...
-      genNamespaceCls(file, ns)
-    }
-
-    //= constructor (options?: XrpcOptions) {
-    //=  this.xrpc = createXrpcServer(schemas, options)
-    //=  {namespace declarations}
-    //= }
-    serverCls
-      .addConstructor({
-        parameters: [
-          { name: 'options', type: 'XrpcOptions', hasQuestionToken: true },
-        ],
-      })
-      .setBodyText(
-        [
-          'this.xrpc = createXrpcServer(schemas, options)',
-          ...nsidTree.map(
-            (ns) => `this.${ns.propName} = new ${ns.className}(this)`,
-          ),
-        ].join('\n'),
-      )
-  })
-
-function genNamespaceCls(file: SourceFile, ns: DefTreeNode) {
-  //= export class {ns}NS {...}
-  const cls = file.addClass({
-    name: ns.className,
-    isExported: true,
-  })
-  //= _server: Server
-  cls.addProperty({
-    name: '_server',
-    type: 'Server',
-  })
-
-  for (const child of ns.children) {
-    //= child: ChildNS
-    cls.addProperty({
-      name: child.propName,
-      type: child.className,
-    })
-
-    // recurse
-    genNamespaceCls(file, child)
-  }
-
-  //= constructor(server: Server) {
-  //=  this._server = server
-  //=  {child namespace declarations}
-  //= }
-  const cons = cls.addConstructor()
-  cons.addParameter({
-    name: 'server',
-    type: 'Server',
-  })
-  cons.setBodyText(
-    [
-      `this._server = server`,
-      ...ns.children.map(
-        (ns) => `this.${ns.propName} = new ${ns.className}(server)`,
-      ),
-    ].join('\n'),
-  )
-
-  // methods
-  for (const userType of ns.userTypes) {
-    if (
-      userType.def.type !== 'query' &&
-      userType.def.type !== 'subscription' &&
-      userType.def.type !== 'procedure'
-    ) {
-      continue
-    }
-    const moduleName = toTitleCase(userType.nsid)
-    const name = toCamelCase(NSID.parse(userType.nsid).name || '')
-    const isSubscription = userType.def.type === 'subscription'
-    const method = cls.addMethod({
-      name,
-      typeParameters: [
-        {
-          name: 'A',
-          constraint: 'Auth',
-          default: 'void',
-        },
-      ],
-    })
-    method.addParameter({
-      name: 'cfg',
-      type: isSubscription
-        ? `StreamConfigOrHandler<
-          A,
-          ${moduleName}.QueryParams,
-          ${moduleName}.HandlerOutput,
-        >`
-        : `MethodConfigOrHandler<
-          A,
-          ${moduleName}.QueryParams,
-          ${moduleName}.HandlerInput,
-          ${moduleName}.HandlerOutput,
-        >`,
-    })
-    const methodType = isSubscription ? 'streamMethod' : 'method'
-    method.setBodyText(
-      [
-        // Placing schema on separate line, since the following one was being formatted
-        // into multiple lines and causing the ts-ignore to ignore the wrong line.
-        `const nsid = '${userType.nsid}' // @ts-ignore`,
-        `return this._server.xrpc.${methodType}(nsid, cfg)`,
-      ].join('\n'),
-    )
-  }
-}
-
-const lexiconTs = (project, lexicons: Lexicons, lexiconDoc: LexiconDoc) =>
-  gen(
-    project,
-    `/types/${lexiconDoc.id.split('.').join('/')}.ts`,
-    async (file) => {
-      const main = lexiconDoc.defs.main
-      if (main?.type === 'query' || main?.type === 'procedure') {
-        const streamingInput =
-          main?.type === 'procedure' &&
-          main.input?.encoding &&
-          !main.input.schema
-        const streamingOutput = main.output?.encoding && !main.output.schema
-        if (streamingInput || streamingOutput) {
-          //= import stream from 'node:stream'
-          file.addImportDeclaration({
-            moduleSpecifier: 'node:stream',
-            defaultImport: 'stream',
-          })
-        }
-      }
-
-      genCommonImports(file, lexiconDoc.id)
-
-      const imports: Set<string> = new Set()
-      for (const defId in lexiconDoc.defs) {
-        const def = lexiconDoc.defs[defId]
-        const lexUri = `${lexiconDoc.id}#${defId}`
-        if (defId === 'main') {
-          if (def.type === 'query' || def.type === 'procedure') {
-            genXrpcParams(file, lexicons, lexUri)
-            genXrpcInput(file, imports, lexicons, lexUri)
-            genXrpcOutput(file, imports, lexicons, lexUri, false)
-            genServerXrpcMethod(file, lexicons, lexUri)
-          } else if (def.type === 'subscription') {
-            genXrpcParams(file, lexicons, lexUri)
-            genXrpcOutput(file, imports, lexicons, lexUri, false)
-            genServerXrpcStreaming(file, lexicons, lexUri)
-          } else if (def.type === 'record') {
-            genRecord(file, imports, lexicons, lexUri)
-          } else {
-            genUserType(file, imports, lexicons, lexUri)
-          }
-        } else {
-          genUserType(file, imports, lexicons, lexUri)
-        }
-      }
-      genImports(file, imports, lexiconDoc.id)
-    },
-  )
-
-function genServerXrpcMethod(
-  file: SourceFile,
-  lexicons: Lexicons,
-  lexUri: string,
-) {
-  const def = lexicons.getDefOrThrow(lexUri, ['query', 'procedure'])
-
-  //= export interface HandlerInput {...}
-  if (def.type === 'procedure' && def.input?.encoding) {
-    const handlerInput = file.addInterface({
-      name: 'HandlerInput',
-      isExported: true,
-    })
-
-    handlerInput.addProperty({
-      name: 'encoding',
-      type: def.input.encoding
-        .split(',')
-        .map((v) => `'${v.trim()}'`)
-        .join(' | '),
-    })
-    handlerInput.addProperty({
-      name: 'body',
-      type: def.input.schema
-        ? def.input.encoding.includes(',')
-          ? 'InputSchema | stream.Readable'
-          : 'InputSchema'
-        : 'stream.Readable',
-    })
-  } else {
-    file.addTypeAlias({
-      isExported: true,
-      name: 'HandlerInput',
-      type: 'void',
-    })
-  }
-
-  // export interface HandlerSuccess {...}
-  let hasHandlerSuccess = false
-  if (def.output?.schema || def.output?.encoding) {
-    hasHandlerSuccess = true
-    const handlerSuccess = file.addInterface({
-      name: 'HandlerSuccess',
-      isExported: true,
-    })
-
-    if (def.output.encoding) {
-      handlerSuccess.addProperty({
-        name: 'encoding',
-        type: def.output.encoding
-          .split(',')
-          .map((v) => `'${v.trim()}'`)
-          .join(' | '),
-      })
-    }
-    if (def.output?.schema) {
-      if (def.output.encoding.includes(',')) {
-        handlerSuccess.addProperty({
-          name: 'body',
-          type: 'OutputSchema | Uint8Array | stream.Readable',
-        })
-      } else {
-        handlerSuccess.addProperty({ name: 'body', type: 'OutputSchema' })
-      }
-    } else if (def.output?.encoding) {
-      handlerSuccess.addProperty({
-        name: 'body',
-        type: 'Uint8Array | stream.Readable',
-      })
-    }
-    handlerSuccess.addProperty({
-      name: 'headers?',
-      type: '{ [key: string]: string }',
-    })
-  }
-
-  // export interface HandlerError {...}
-  const handlerError = file.addInterface({
-    name: 'HandlerError',
-    isExported: true,
-  })
-  handlerError.addProperties([
-    { name: 'status', type: 'number' },
-    { name: 'message?', type: 'string' },
-  ])
-  if (def.errors?.length) {
-    handlerError.addProperty({
-      name: 'error?',
-      type: def.errors.map((err) => `'${err.name}'`).join(' | '),
-    })
-  }
-
-  // export type HandlerOutput = ...
-  file.addTypeAlias({
-    isExported: true,
-    name: 'HandlerOutput',
-    type: `HandlerError | ${hasHandlerSuccess ? 'HandlerSuccess' : 'void'}`,
-  })
-}
-
-function genServerXrpcStreaming(
-  file: SourceFile,
-  lexicons: Lexicons,
-  lexUri: string,
-) {
-  const def = lexicons.getDefOrThrow(lexUri, ['subscription'])
-
-  file.addImportDeclaration({
-    moduleSpecifier: '@atproto/xrpc-server',
-    namedImports: [{ name: 'ErrorFrame' }],
-  })
-
-  file.addImportDeclaration({
-    moduleSpecifier: 'node:http',
-    namedImports: [{ name: 'IncomingMessage' }],
-  })
-
-  // export type HandlerError = ...
-  file.addTypeAlias({
-    name: 'HandlerError',
-    isExported: true,
-    type: `ErrorFrame<${arrayToUnion(def.errors?.map((e) => e.name))}>`,
-  })
-
-  // export type HandlerOutput = ...
-  file.addTypeAlias({
-    isExported: true,
-    name: 'HandlerOutput',
-    type: `HandlerError | ${def.message?.schema ? 'OutputSchema' : 'void'}`,
-  })
-}
-
-function arrayToUnion(arr?: string[]) {
-  if (!arr?.length) {
-    return 'never'
-  }
-  return arr.map((item) => `'${item}'`).join(' | ')
-}

package/src/codegen/util.ts

@@ -1,84 +0,0 @@
-import { type LexUserType, type LexiconDoc } from '@atproto/lexicon'
-import { NSID } from '@atproto/syntax'
-
-export interface DefTreeNodeUserType {
-  nsid: string
-  def: LexUserType
-}
-
-export interface DefTreeNode {
-  name: string
-  className: string
-  propName: string
-  children: DefTreeNode[]
-  userTypes: DefTreeNodeUserType[]
-}
-
-export function lexiconsToDefTree(lexicons: LexiconDoc[]): DefTreeNode[] {
-  const tree: DefTreeNode[] = []
-  for (const lexicon of lexicons) {
-    if (!lexicon.defs.main) {
-      continue
-    }
-    const node = getOrCreateNode(tree, lexicon.id.split('.').slice(0, -1))
-    node.userTypes.push({ nsid: lexicon.id, def: lexicon.defs.main })
-  }
-  return tree
-}
-
-function getOrCreateNode(tree: DefTreeNode[], path: string[]): DefTreeNode {
-  let node: DefTreeNode | undefined
-  for (let i = 0; i < path.length; i++) {
-    const segment = path[i]
-    node = tree.find((v) => v.name === segment)
-    if (!node) {
-      node = {
-        name: segment,
-        className: `${toTitleCase(path.slice(0, i + 1).join('-'))}NS`,
-        propName: toCamelCase(segment),
-        children: [],
-        userTypes: [],
-      } as DefTreeNode
-      tree.push(node)
-    }
-    tree = node.children
-  }
-  if (!node) throw new Error(`Invalid schema path: ${path.join('.')}`)
-  return node
-}
-
-export function schemasToNsidTokens(
-  lexiconDocs: LexiconDoc[],
-): Record<string, string[]> {
-  const nsidTokens: Record<string, string[]> = {}
-  for (const lexiconDoc of lexiconDocs) {
-    const nsidp = NSID.parse(lexiconDoc.id)
-    if (!nsidp.name) continue
-    for (const defId in lexiconDoc.defs) {
-      const def = lexiconDoc.defs[defId]
-      if (def.type !== 'token') continue
-      const authority = nsidp.segments.slice(0, -1).join('.')
-      nsidTokens[authority] ??= []
-      nsidTokens[authority].push(
-        nsidp.name + (defId === 'main' ? '' : `#${defId}`),
-      )
-    }
-  }
-  return nsidTokens
-}
-
-export function toTitleCase(v: string): string {
-  v = v.replace(/^([a-z])/gi, (_, g) => g.toUpperCase()) // upper-case first letter
-  v = v.replace(/[.#-]([a-z])/gi, (_, g) => g.toUpperCase()) // uppercase any dash, dot, or hash segments
-  return v.replace(/[.-]/g, '') // remove lefover dashes or dots
-}
-
-export function toCamelCase(v: string): string {
-  v = v.replace(/[.#-]([a-z])/gi, (_, g) => g.toUpperCase()) // uppercase any dash, dot, or hash segments
-  return v.replace(/[.-]/g, '') // remove lefover dashes or dots
-}
-
-export function toScreamingSnakeCase(v: string): string {
-  v = v.replace(/[.#-]+/gi, '_') // convert dashes, dots, and hashes into underscores
-  return v.toUpperCase() // and scream!
-}

package/src/index.ts

@@ -1,105 +0,0 @@
-#!/usr/bin/env node
-
-import path from 'node:path'
-import { Command } from 'commander'
-import yesno from 'yesno'
-import { genClientApi } from './codegen/client.js'
-import { genServerApi } from './codegen/server.js'
-import * as mdGen from './mdgen/index.js'
-import {
-  applyFileDiff,
-  genFileDiff,
-  genTsObj,
-  printFileDiff,
-  readAllLexicons,
-} from './util.js'
-
-const program = new Command()
-program.name('lex').description('Lexicon CLI').version('0.0.0')
-
-program
-  .command('gen-md')
-  .description('Generate markdown documentation')
-  .option('--yes', 'skip confirmation')
-  .argument('<outfile>', 'path of the file to write to', toPath)
-  .argument('<lexicons...>', 'paths of the lexicon files to include', toPaths)
-  .action(
-    async (outFile: string, lexiconPaths: string[], o: { yes?: true }) => {
-      if (!outFile.endsWith('.md')) {
-        console.error(
-          'Must supply the path to a .md file as the first parameter',
-        )
-        process.exit(1)
-      }
-      if (!o?.yes) await confirmOrExit()
-      console.log('Writing', outFile)
-      const lexicons = readAllLexicons(lexiconPaths)
-      await mdGen.process(outFile, lexicons)
-    },
-  )
-
-program
-  .command('gen-ts-obj')
-  .description('Generate a TS file that exports an array of lexicons')
-  .argument('<lexicons...>', 'paths of the lexicon files to include', toPaths)
-  .action((lexiconPaths: string[]) => {
-    const lexicons = readAllLexicons(lexiconPaths)
-    console.log(genTsObj(lexicons))
-  })
-
-program
-  .command('gen-api')
-  .description('Generate a TS client API')
-  .option('--yes', 'skip confirmation')
-  .argument('<outdir>', 'path of the directory to write to', toPath)
-  .argument('<lexicons...>', 'paths of the lexicon files to include', toPaths)
-  .action(async (outDir: string, lexiconPaths: string[], o: { yes?: true }) => {
-    const lexicons = readAllLexicons(lexiconPaths)
-    const api = await genClientApi(lexicons)
-    const diff = genFileDiff(outDir, api)
-    console.log('This will write the following files:')
-    printFileDiff(diff)
-    if (!o?.yes) await confirmOrExit()
-    applyFileDiff(diff)
-    console.log('API generated.')
-  })
-
-program
-  .command('gen-server')
-  .description('Generate a TS server API')
-  .option('--yes', 'skip confirmation')
-  .argument('<outdir>', 'path of the directory to write to', toPath)
-  .argument('<lexicons...>', 'paths of the lexicon files to include', toPaths)
-  .action(async (outDir: string, lexiconPaths: string[], o: { yes?: true }) => {
-    const lexicons = readAllLexicons(lexiconPaths)
-    const api = await genServerApi(lexicons)
-    const diff = genFileDiff(outDir, api)
-    console.log('This will write the following files:')
-    printFileDiff(diff)
-    if (!o?.yes) await confirmOrExit()
-    applyFileDiff(diff)
-    console.log('API generated.')
-  })
-
-program.parse()
-
-function toPath(v: string) {
-  return v ? path.resolve(v) : undefined
-}
-
-function toPaths(v: string, acc: string[]) {
-  acc = acc || []
-  acc.push(path.resolve(v))
-  return acc
-}
-
-async function confirmOrExit() {
-  const ok = await yesno({
-    question: 'Are you sure you want to continue? [y/N]',
-    defaultValue: false,
-  })
-  if (!ok) {
-    console.log('Aborted.')
-    process.exit(0)
-  }
-}

package/src/mdgen/index.ts

@@ -1,77 +0,0 @@
-import fs from 'node:fs'
-import { type LexiconDoc } from '@atproto/lexicon'
-
-const INSERT_START = [
-  '<!-- START lex generated content. Please keep comment here to allow auto update -->',
-  "<!-- DON'T EDIT THIS SECTION! INSTEAD RE-RUN lex TO UPDATE -->",
-]
-const INSERT_END = [
-  '<!-- END lex generated TOC please keep comment here to allow auto update -->',
-]
-
-export async function process(outFilePath: string, lexicons: LexiconDoc[]) {
-  let existingContent = ''
-  try {
-    existingContent = fs.readFileSync(outFilePath, 'utf8')
-  } catch {
-    // ignore - no existing content
-  }
-  const fileLines: StringTree = existingContent.split('\n')
-
-  // find previously generated content
-  let startIndex = fileLines.findIndex((line) => matchesStart(line))
-  let endIndex = fileLines.findIndex((line) => matchesEnd(line))
-  if (startIndex === -1) {
-    startIndex = fileLines.length
-  }
-  if (endIndex === -1) {
-    endIndex = fileLines.length
-  }
-
-  // generate & insert content
-  fileLines.splice(startIndex, endIndex - startIndex + 1, [
-    INSERT_START,
-    await genMdLines(lexicons),
-    INSERT_END,
-  ])
-
-  fs.writeFileSync(outFilePath, merge(fileLines), 'utf8')
-}
-
-async function genMdLines(lexicons: LexiconDoc[]): Promise<StringTree> {
-  const doc: StringTree = []
-  for (const lexicon of lexicons) {
-    console.log(lexicon.id)
-    const desc: StringTree = []
-    if (lexicon.description) {
-      desc.push(lexicon.description, ``)
-    }
-    doc.push([
-      `---`,
-      ``,
-      `## ${lexicon.id}`,
-      '',
-      desc,
-      '```json',
-      JSON.stringify(lexicon, null, 2),
-      '```',
-    ])
-  }
-  return doc
-}
-
-type StringTree = (StringTree | string | undefined)[]
-function merge(arr: StringTree): string {
-  return arr
-    .flat(10)
-    .filter((v) => typeof v === 'string')
-    .join('\n')
-}
-
-function matchesStart(line) {
-  return /<!-- START lex /.test(line)
-}
-
-function matchesEnd(line) {
-  return /<!-- END lex /.test(line)
-}