@atproto/lex-builder 0.0.12 → 0.0.14

package/dist/ref-resolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"ref-resolver.js","sourceRoot":"","sources":["../src/ref-resolver.ts"],"names":[],"mappings":"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","sourcesContent":["import assert from 'node:assert'\nimport { join } from 'node:path'\nimport { SourceFile } from 'ts-morph'\nimport { LexiconDocument, LexiconIndexer } from '@atproto/lex-document'\nimport {\n  isGlobalIdentifier,\n  isJsKeyword,\n  isSafeLocalIdentifier,\n  isValidJsIdentifier,\n} from './ts-lang.js'\nimport {\n  asRelativePath,\n  memoize,\n  startsWithLower,\n  toCamelCase,\n  toPascalCase,\n  ucFirst,\n} from './util.js'\n\nexport type RefResolverOptions = {\n  importExt?: string\n}\n\nexport type ResolvedRef = {\n  varName: string\n  typeName: string\n}\n\n/**\n * Utility class to resolve lexicon references to TypeScript identifiers,\n * generating \"import\" statements as needed.\n */\nexport class RefResolver {\n  constructor(\n    private doc: LexiconDocument,\n    private file: SourceFile,\n    private indexer: LexiconIndexer,\n    private options: RefResolverOptions,\n  ) {}\n\n  public readonly resolve = memoize(\n    async (ref: string): Promise<ResolvedRef> => {\n      const [nsid, hash = 'main'] = ref.split('#')\n\n      if (nsid === '' || nsid === this.doc.id) {\n        return this.resolveLocal(hash)\n      } else {\n        // @NOTE: Normalize (#main fragment) to ensure proper memoization\n        const fullRef = `${nsid}#${hash}`\n        return this.resolveExternal(fullRef)\n      }\n    },\n  )\n\n  #defCounters = new Map<string, number>()\n  private nextSafeDefinitionIdentifier(name: string) {\n    // use camelCase version of the hash as base name\n    const nameSafe =\n      startsWithLower(name) && isValidJsIdentifier(name)\n        ? name\n        : toCamelCase(name).replace(/^[0-9]+/g, '') || 'def'\n\n    const count = this.#defCounters.get(nameSafe) ?? 0\n    this.#defCounters.set(nameSafe, count + 1)\n\n    // @NOTE We don't need to check against local declarations in the file here\n    // since we are using a naming system that should guarantee no other\n    // identifier has a <nameSafe>$<number> format (\"$\" cannot appear in\n    // hashes so only *we* are generating such identifiers).\n\n    const identifier = `${nameSafe}$${count}`\n\n    assert(\n      isValidJsIdentifier(identifier),\n      `Unable to generate safe identifier for: \"${name}\"`,\n    )\n\n    return identifier\n  }\n\n  /**\n   * @note The returned `typeName` and `varName` are *both* guaranteed to be\n   * valid TypeScript identifiers.\n   */\n  public readonly resolveLocal = memoize(\n    async (hash: string): Promise<ResolvedRef> => {\n      const hashes = Object.keys(this.doc.defs)\n\n      if (!hashes.includes(hash)) {\n        throw new Error(`Definition ${hash} not found in ${this.doc.id}`)\n      }\n\n      // Because we are using predictable \"public\" identifiers for type names,\n      // we need to ensure there are no conflicts between different definitions\n      // in the same lexicon document.\n      //\n      // @NOTE It should be possible to implement a way to generate\n      // non-conflicting type names for all public (type) identifiers in a\n      // project. However, this would add a lot of complexity to the code\n      // generation process, and the likelihood of such conflicts happening in\n      // practice is very low, so we opt for a simpler approach of just throwing\n      // an error if a conflict is detected.\n      const pub = getPublicIdentifiers(hash)\n      for (const otherHash of hashes) {\n        if (otherHash === hash) continue\n        const otherPub = getPublicIdentifiers(otherHash)\n        if (otherPub.typeName === pub.typeName) {\n          throw new Error(\n            `Conflicting type names for definitions #${hash} and #${otherHash} in ${this.doc.id}`,\n          )\n        }\n      }\n\n      // Try to keep and identifier that resembles the original hash as identifier\n      const safeIdentifier = asSafeDefinitionIdentifier(hash)\n\n      // If the safe identifier is not conflicting with other definition names,\n      // or reserved words, we can use it as-is. Otherwise, we need to generate\n      // a unique safe identifier.\n      const varName = safeIdentifier\n        ? !hashes.some((otherHash) => {\n            if (otherHash === hash) return false\n            const otherIdentifier = asSafeDefinitionIdentifier(otherHash)\n            return otherIdentifier === safeIdentifier\n          })\n          ? // Safe identifier can be used as-is as it does not conflict with\n            // other definition names\n            safeIdentifier\n          : // In order to keep identifiers stable, we use the safe identifier\n            // as base, and append a counter to avoid conflicts\n            this.nextSafeDefinitionIdentifier(safeIdentifier)\n        : // hash only contained unsafe characters, generate a safe one\n          this.nextSafeDefinitionIdentifier(hash)\n\n      const typeName = ucFirst(varName)\n      assert(isSafeLocalIdentifier(typeName), 'Expected safe type identifier')\n      assert(varName !== typeName, 'Variable and type name should be different')\n\n      return { varName, typeName }\n    },\n  )\n\n  /**\n   * @note Since this is a memoized function, and is used to generate the name\n   * of local variables, we should avoid returning different results for\n   * similar, but non strictly equal, inputs (eg. normalized / non-normalized).\n   * @see {@link resolve}\n   */\n  private readonly resolveExternal = memoize(\n    async (fullRef: string): Promise<ResolvedRef> => {\n      const [nsid, hash] = fullRef.split('#')\n      const moduleSpecifier = `${asRelativePath(\n        this.file.getDirectoryPath(),\n        join('/', ...nsid.split('.')),\n      )}.defs${this.options.importExt ?? '.js'}`\n\n      // Lets first make sure the referenced lexicon exists\n      const srcDoc = await this.indexer.get(nsid)\n      const srcDef = Object.hasOwn(srcDoc.defs, hash) ? srcDoc.defs[hash] : null\n      if (!srcDef) {\n        throw new Error(\n          `Missing def \"${hash}\" in \"${nsid}\" (referenced from ${this.doc.id})`,\n        )\n      }\n\n      const publicIds = getPublicIdentifiers(hash)\n\n      if (!isValidJsIdentifier(publicIds.typeName)) {\n        // If <typeName> is not a valid identifier, we cannot access the type\n        // using dot notation (<nsIdentifier>.<typeName>). Note that, unlike js\n        // variables, types cannot be accessed using string indexing (like:\n        // <nsIdentifier>['<typeName>']) because it generates TypeScript errors:\n        //\n        // > \"Cannot use namespace '<nsIdentifier>' as a type.\"\n\n        // Instead the generated code should look like:\n        // import { \"<unsafeTypeName>\" as <safeIdentifier> } from './<moduleSpecifier>'\n\n        // Because it requires more complex management of local variables names,\n        // and we don't expect this to actually happen with properly designed\n        // lexicons documents, we do not support this for now.\n\n        throw new Error(\n          'Import of definitions with unsafe type names is not supported',\n        )\n      }\n\n      // import * as <nsIdentifier> from './<moduleSpecifier>'\n      const nsIdentifier = this.getNsIdentifier(nsid, moduleSpecifier)\n\n      return {\n        varName: isValidJsIdentifier(publicIds.varName)\n          ? `${nsIdentifier}.${publicIds.varName}`\n          : `${nsIdentifier}[${JSON.stringify(publicIds.varName)}]`,\n        typeName: `${nsIdentifier}.${publicIds.typeName}`,\n      }\n    },\n  )\n\n  private getNsIdentifier(nsid: string, moduleSpecifier: string) {\n    const namespaceImportDeclaration =\n      this.file.getImportDeclaration(\n        (imp) =>\n          !imp.isTypeOnly() &&\n          imp.getModuleSpecifierValue() === moduleSpecifier &&\n          imp.getNamespaceImport() != null,\n      ) ||\n      this.file.addImportDeclaration({\n        moduleSpecifier,\n        namespaceImport: this.computeSafeNamespaceIdentifierFor(nsid),\n      })\n\n    return namespaceImportDeclaration.getNamespaceImport()!.getText()\n  }\n\n  #nsIdentifiersCounters = new Map<string, number>()\n  private computeSafeNamespaceIdentifierFor(nsid: string) {\n    const baseName = nsidToIdentifier(nsid) || 'NS'\n\n    let name = baseName\n    while (this.isConflictingIdentifier(name)) {\n      const count = this.#nsIdentifiersCounters.get(baseName) ?? 0\n      this.#nsIdentifiersCounters.set(baseName, count + 1)\n      name = `${baseName}$$${count}`\n    }\n\n    return name\n  }\n\n  private isConflictingIdentifier(name: string) {\n    return (\n      this.conflictsWithKeywords(name) ||\n      this.conflictsWithUtils(name) ||\n      this.conflictsWithLocalDefs(name) ||\n      this.conflictsWithLocalDeclarations(name) ||\n      this.conflictsWithImports(name)\n    )\n  }\n\n  private conflictsWithKeywords(name: string) {\n    return isJsKeyword(name) || isGlobalIdentifier(name)\n  }\n\n  private conflictsWithUtils(name: string) {\n    // Do not allow \"Main\" as imported ns identifier since it has a special\n    // meaning in the context of lexicon definitions.\n    if (name === 'Main') return true\n\n    // When \"useRecordExport\" returns true, an export named \"Record\" will be\n    // used in addition to the hash named export. So we need to make sure both\n    // names are not conflicting with local variables.\n    if (name === 'Record') return true\n\n    // Utility functions generated for lexicon schemas are prefixed with \"$\"\n    return name.startsWith('$')\n  }\n\n  private conflictsWithLocalDefs(name: string) {\n    return Object.keys(this.doc.defs).some((hash) => {\n      const identifier = toCamelCase(hash)\n\n      // A safe identifier will be generated, no risk of conflict.\n      if (!identifier) return false\n\n      // The imported name conflicts with a local definition name\n      if (identifier === name || `_${identifier}` === name) return true\n\n      // The imported name conflicts with the type name of a local definition\n      const typeName = ucFirst(identifier)\n      if (typeName === name || `_${typeName}` === name) return true\n\n      return false\n    })\n  }\n\n  private conflictsWithLocalDeclarations(name: string) {\n    return (\n      this.file.getVariableDeclarations().some((v) => v.getName() === name) ||\n      this.file\n        .getVariableStatements()\n        .some((vs) => vs.getDeclarations().some((d) => d.getName() === name)) ||\n      this.file.getTypeAliases().some((t) => t.getName() === name) ||\n      this.file.getInterfaces().some((i) => i.getName() === name) ||\n      this.file.getClasses().some((c) => c.getName() === name) ||\n      this.file.getFunctions().some((f) => f.getName() === name) ||\n      this.file.getEnums().some((e) => e.getName() === name)\n    )\n  }\n\n  private conflictsWithImports(name: string) {\n    return this.file.getImportDeclarations().some(\n      (imp) =>\n        // import name from '...'\n        imp.getDefaultImport()?.getText() === name ||\n        // import * as name from '...'\n        imp.getNamespaceImport()?.getText() === name ||\n        imp.getNamedImports().some(\n          (named) =>\n            // import { name } from '...'\n            // import { foo as name } from '...'\n            (named.getAliasNode()?.getText() ?? named.getName()) === name,\n        ),\n    )\n  }\n}\n\n/**\n * @see {@link https://atproto.com/specs/nsid NSID syntax spec}\n */\nfunction nsidToIdentifier(nsid: string) {\n  const parts = nsid.split('.')\n\n  // By default, try to keep only to the last two segments of the NSID as\n  // contextual information. If those do not form a safe identifier (typically\n  // because they start with a digit), try with more segments until we reach the\n  // full NSID.\n  for (let i = 2; i < parts.length; i++) {\n    const identifier = toPascalCase(parts.slice(-i).join('.'))\n    if (isSafeLocalIdentifier(identifier)) return identifier\n  }\n\n  return undefined\n}\n\n/**\n * Generates predictable public identifiers for a given definition hash.\n *\n * @note The returned `typeName` is guaranteed to be a valid TypeScript\n * identifier. `varName` may not be a valid identifier (eg. if the hash contains\n * unsafe characters), and may need to be accessed using string indexing.\n */\nexport function getPublicIdentifiers(hash: string): ResolvedRef {\n  const varName = hash\n\n  // @NOTE we try to circumvent the issue of unsafe type names described in\n  // `RefResolver.resolveExternal` by ensuring that type names are always safe\n  // identifiers, even if it means changing them from the original hash.\n  let typeName = toPascalCase(hash)\n\n  if (varName === typeName || !isValidJsIdentifier(typeName)) {\n    typeName = `TypeOf${typeName}`\n  }\n\n  assert(\n    isValidJsIdentifier(typeName),\n    `Unable to generate a predictable safe identifier for \"${hash}\"`,\n  )\n\n  return { varName, typeName }\n}\n\nfunction asSafeDefinitionIdentifier(name: string) {\n  if (\n    startsWithLower(name) &&\n    isSafeLocalIdentifier(name) &&\n    isSafeLocalIdentifier(ucFirst(name))\n  ) {\n    return name\n  }\n  const camel = toCamelCase(name)\n  if (isSafeLocalIdentifier(camel) && isSafeLocalIdentifier(ucFirst(camel))) {\n    return camel\n  }\n  return undefined\n}\n"]}
+{"version":3,"file":"ref-resolver.js","sourceRoot":"","sources":["../src/ref-resolver.ts"],"names":[],"mappings":";;;AAgZA,oDAkBC;;AAlaD,sEAAgC;AAChC,yCAAgC;AAGhC,6CAKqB;AACrB,uCAOkB;AAsClB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAa,WAAW;IAEZ;IACA;IACA;IACA;IAJV,YACU,GAAoB,EACpB,IAAgB,EAChB,OAAuB,EACvB,OAA2B;QAH3B,QAAG,GAAH,GAAG,CAAiB;QACpB,SAAI,GAAJ,IAAI,CAAY;QAChB,YAAO,GAAP,OAAO,CAAgB;QACvB,YAAO,GAAP,OAAO,CAAoB;IAClC,CAAC;IAEY,OAAO,GAAG,IAAA,iBAAO,EAC/B,KAAK,EAAE,GAAW,EAAwB,EAAE;QAC1C,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;QAE5C,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACxC,OAAO,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAA;QAChC,CAAC;aAAM,CAAC;YACN,iEAAiE;YACjE,MAAM,OAAO,GAAG,GAAG,IAAI,IAAI,IAAI,EAAE,CAAA;YACjC,OAAO,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAA;QACtC,CAAC;IACH,CAAC,CACF,CAAA;IAED,YAAY,GAAG,IAAI,GAAG,EAAkB,CAAA;IAChC,4BAA4B,CAAC,IAAY;QAC/C,iDAAiD;QACjD,MAAM,QAAQ,GACZ,IAAA,yBAAe,EAAC,IAAI,CAAC,IAAI,IAAA,gCAAmB,EAAC,IAAI,CAAC;YAChD,CAAC,CAAC,IAAI;YACN,CAAC,CAAC,IAAA,qBAAW,EAAC,IAAI,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,IAAI,KAAK,CAAA;QAExD,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;QAClD,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,GAAG,CAAC,CAAC,CAAA;QAE1C,2EAA2E;QAC3E,oEAAoE;QACpE,oEAAoE;QACpE,wDAAwD;QAExD,MAAM,UAAU,GAAG,GAAG,QAAQ,IAAI,KAAK,EAAE,CAAA;QAEzC,IAAA,qBAAM,EACJ,IAAA,gCAAmB,EAAC,UAAU,CAAC,EAC/B,4CAA4C,IAAI,GAAG,CACpD,CAAA;QAED,OAAO,UAAU,CAAA;IACnB,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACa,YAAY,GAAG,IAAA,iBAAO,EACpC,KAAK,EAAE,IAAY,EAAwB,EAAE;QAC3C,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QAEzC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,iBAAiB,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAA;QACnE,CAAC;QAED,wEAAwE;QACxE,yEAAyE;QACzE,gCAAgC;QAChC,EAAE;QACF,6DAA6D;QAC7D,oEAAoE;QACpE,mEAAmE;QACnE,wEAAwE;QACxE,0EAA0E;QAC1E,sCAAsC;QACtC,MAAM,GAAG,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAA;QACtC,KAAK,MAAM,SAAS,IAAI,MAAM,EAAE,CAAC;YAC/B,IAAI,SAAS,KAAK,IAAI;gBAAE,SAAQ;YAChC,MAAM,QAAQ,GAAG,oBAAoB,CAAC,SAAS,CAAC,CAAA;YAChD,IAAI,QAAQ,CAAC,QAAQ,KAAK,GAAG,CAAC,QAAQ,EAAE,CAAC;gBACvC,MAAM,IAAI,KAAK,CACb,2CAA2C,IAAI,SAAS,SAAS,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CACtF,CAAA;YACH,CAAC;QACH,CAAC;QAED,4EAA4E;QAC5E,MAAM,cAAc,GAAG,0BAA0B,CAAC,IAAI,CAAC,CAAA;QAEvD,yEAAyE;QACzE,yEAAyE;QACzE,4BAA4B;QAC5B,MAAM,OAAO,GAAG,cAAc;YAC5B,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE;gBACzB,IAAI,SAAS,KAAK,IAAI;oBAAE,OAAO,KAAK,CAAA;gBACpC,MAAM,eAAe,GAAG,0BAA0B,CAAC,SAAS,CAAC,CAAA;gBAC7D,OAAO,eAAe,KAAK,cAAc,CAAA;YAC3C,CAAC,CAAC;gBACF,CAAC,CAAC,iEAAiE;oBACjE,yBAAyB;oBACzB,cAAc;gBAChB,CAAC,CAAC,kEAAkE;oBAClE,mDAAmD;oBACnD,IAAI,CAAC,4BAA4B,CAAC,cAAc,CAAC;YACrD,CAAC,CAAC,6DAA6D;gBAC7D,IAAI,CAAC,4BAA4B,CAAC,IAAI,CAAC,CAAA;QAE3C,MAAM,QAAQ,GAAG,IAAA,iBAAO,EAAC,OAAO,CAAC,CAAA;QACjC,IAAA,qBAAM,EAAC,IAAA,kCAAqB,EAAC,QAAQ,CAAC,EAAE,+BAA+B,CAAC,CAAA;QACxE,IAAA,qBAAM,EAAC,OAAO,KAAK,QAAQ,EAAE,4CAA4C,CAAC,CAAA;QAE1E,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAA;IAC9B,CAAC,CACF,CAAA;IAED;;;;;OAKG;IACc,eAAe,GAAG,IAAA,iBAAO,EACxC,KAAK,EAAE,OAAe,EAAwB,EAAE;QAC9C,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;QACvC,MAAM,eAAe,GAAG,GAAG,IAAA,wBAAc,EACvC,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,EAC5B,IAAA,gBAAI,EAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAC9B,QAAQ,IAAI,CAAC,OAAO,CAAC,SAAS,IAAI,KAAK,EAAE,CAAA;QAE1C,qDAAqD;QACrD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QAC3C,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;QAC1E,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,gBAAgB,IAAI,SAAS,IAAI,sBAAsB,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,CACtE,CAAA;QACH,CAAC;QAED,MAAM,SAAS,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAA;QAE5C,IAAI,CAAC,IAAA,gCAAmB,EAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC7C,qEAAqE;YACrE,uEAAuE;YACvE,mEAAmE;YACnE,wEAAwE;YACxE,EAAE;YACF,uDAAuD;YAEvD,+CAA+C;YAC/C,+EAA+E;YAE/E,wEAAwE;YACxE,qEAAqE;YACrE,sDAAsD;YAEtD,MAAM,IAAI,KAAK,CACb,+DAA+D,CAChE,CAAA;QACH,CAAC;QAED,wDAAwD;QACxD,MAAM,YAAY,GAAG,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,eAAe,CAAC,CAAA;QAEhE,OAAO;YACL,OAAO,EAAE,IAAA,gCAAmB,EAAC,SAAS,CAAC,OAAO,CAAC;gBAC7C,CAAC,CAAC,GAAG,YAAY,IAAI,SAAS,CAAC,OAAO,EAAE;gBACxC,CAAC,CAAC,GAAG,YAAY,IAAI,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG;YAC3D,QAAQ,EAAE,GAAG,YAAY,IAAI,SAAS,CAAC,QAAQ,EAAE;SAClD,CAAA;IACH,CAAC,CACF,CAAA;IAEO,eAAe,CAAC,IAAY,EAAE,eAAuB;QAC3D,MAAM,0BAA0B,GAC9B,IAAI,CAAC,IAAI,CAAC,oBAAoB,CAC5B,CAAC,GAAG,EAAE,EAAE,CACN,CAAC,GAAG,CAAC,UAAU,EAAE;YACjB,GAAG,CAAC,uBAAuB,EAAE,KAAK,eAAe;YACjD,GAAG,CAAC,kBAAkB,EAAE,IAAI,IAAI,CACnC;YACD,IAAI,CAAC,IAAI,CAAC,oBAAoB,CAAC;gBAC7B,eAAe;gBACf,eAAe,EAAE,IAAI,CAAC,iCAAiC,CAAC,IAAI,CAAC;aAC9D,CAAC,CAAA;QAEJ,OAAO,0BAA0B,CAAC,kBAAkB,EAAG,CAAC,OAAO,EAAE,CAAA;IACnE,CAAC;IAED,sBAAsB,GAAG,IAAI,GAAG,EAAkB,CAAA;IAC1C,iCAAiC,CAAC,IAAY;QACpD,MAAM,QAAQ,GAAG,gBAAgB,CAAC,IAAI,CAAC,IAAI,IAAI,CAAA;QAE/C,IAAI,IAAI,GAAG,QAAQ,CAAA;QACnB,OAAO,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,sBAAsB,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;YAC5D,IAAI,CAAC,sBAAsB,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,GAAG,CAAC,CAAC,CAAA;YACpD,IAAI,GAAG,GAAG,QAAQ,KAAK,KAAK,EAAE,CAAA;QAChC,CAAC;QAED,OAAO,IAAI,CAAA;IACb,CAAC;IAEO,uBAAuB,CAAC,IAAY;QAC1C,OAAO,CACL,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC;YAChC,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC;YAC7B,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC;YACjC,IAAI,CAAC,8BAA8B,CAAC,IAAI,CAAC;YACzC,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAChC,CAAA;IACH,CAAC;IAEO,qBAAqB,CAAC,IAAY;QACxC,OAAO,IAAA,wBAAW,EAAC,IAAI,CAAC,IAAI,IAAA,+BAAkB,EAAC,IAAI,CAAC,CAAA;IACtD,CAAC;IAEO,kBAAkB,CAAC,IAAY;QACrC,uEAAuE;QACvE,iDAAiD;QACjD,IAAI,IAAI,KAAK,MAAM;YAAE,OAAO,IAAI,CAAA;QAEhC,wEAAwE;QACxE,0EAA0E;QAC1E,kDAAkD;QAClD,IAAI,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAA;QAElC,wEAAwE;QACxE,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAA;IAC7B,CAAC;IAEO,sBAAsB,CAAC,IAAY;QACzC,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;YAC9C,MAAM,UAAU,GAAG,IAAA,qBAAW,EAAC,IAAI,CAAC,CAAA;YAEpC,4DAA4D;YAC5D,IAAI,CAAC,UAAU;gBAAE,OAAO,KAAK,CAAA;YAE7B,2DAA2D;YAC3D,IAAI,UAAU,KAAK,IAAI,IAAI,IAAI,UAAU,EAAE,KAAK,IAAI;gBAAE,OAAO,IAAI,CAAA;YAEjE,uEAAuE;YACvE,MAAM,QAAQ,GAAG,IAAA,iBAAO,EAAC,UAAU,CAAC,CAAA;YACpC,IAAI,QAAQ,KAAK,IAAI,IAAI,IAAI,QAAQ,EAAE,KAAK,IAAI;gBAAE,OAAO,IAAI,CAAA;YAE7D,OAAO,KAAK,CAAA;QACd,CAAC,CAAC,CAAA;IACJ,CAAC;IAEO,8BAA8B,CAAC,IAAY;QACjD,OAAO,CACL,IAAI,CAAC,IAAI,CAAC,uBAAuB,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,IAAI,CAAC;YACrE,IAAI,CAAC,IAAI;iBACN,qBAAqB,EAAE;iBACvB,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,eAAe,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,IAAI,CAAC,CAAC;YACvE,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,IAAI,CAAC;YAC5D,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,IAAI,CAAC;YAC3D,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,IAAI,CAAC;YACxD,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,IAAI,CAAC;YAC1D,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,IAAI,CAAC,CACvD,CAAA;IACH,CAAC;IAEO,oBAAoB,CAAC,IAAY;QACvC,OAAO,IAAI,CAAC,IAAI,CAAC,qBAAqB,EAAE,CAAC,IAAI,CAC3C,CAAC,GAAG,EAAE,EAAE;QACN,yBAAyB;QACzB,GAAG,CAAC,gBAAgB,EAAE,EAAE,OAAO,EAAE,KAAK,IAAI;YAC1C,8BAA8B;YAC9B,GAAG,CAAC,kBAAkB,EAAE,EAAE,OAAO,EAAE,KAAK,IAAI;YAC5C,GAAG,CAAC,eAAe,EAAE,CAAC,IAAI,CACxB,CAAC,KAAK,EAAE,EAAE;YACR,6BAA6B;YAC7B,oCAAoC;YACpC,CAAC,KAAK,CAAC,YAAY,EAAE,EAAE,OAAO,EAAE,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,CAChE,CACJ,CAAA;IACH,CAAC;CACF;AA7RD,kCA6RC;AAED;;GAEG;AACH,SAAS,gBAAgB,CAAC,IAAY;IACpC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAE7B,uEAAuE;IACvE,4EAA4E;IAC5E,8EAA8E;IAC9E,aAAa;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,UAAU,GAAG,IAAA,sBAAY,EAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;QAC1D,IAAI,IAAA,kCAAqB,EAAC,UAAU,CAAC;YAAE,OAAO,UAAU,CAAA;IAC1D,CAAC;IAED,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAgB,oBAAoB,CAAC,IAAY;IAC/C,MAAM,OAAO,GAAG,IAAI,CAAA;IAEpB,yEAAyE;IACzE,4EAA4E;IAC5E,sEAAsE;IACtE,IAAI,QAAQ,GAAG,IAAA,sBAAY,EAAC,IAAI,CAAC,CAAA;IAEjC,IAAI,OAAO,KAAK,QAAQ,IAAI,CAAC,IAAA,gCAAmB,EAAC,QAAQ,CAAC,EAAE,CAAC;QAC3D,QAAQ,GAAG,SAAS,QAAQ,EAAE,CAAA;IAChC,CAAC;IAED,IAAA,qBAAM,EACJ,IAAA,gCAAmB,EAAC,QAAQ,CAAC,EAC7B,yDAAyD,IAAI,GAAG,CACjE,CAAA;IAED,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAA;AAC9B,CAAC;AAED,SAAS,0BAA0B,CAAC,IAAY;IAC9C,IACE,IAAA,yBAAe,EAAC,IAAI,CAAC;QACrB,IAAA,kCAAqB,EAAC,IAAI,CAAC;QAC3B,IAAA,kCAAqB,EAAC,IAAA,iBAAO,EAAC,IAAI,CAAC,CAAC,EACpC,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IACD,MAAM,KAAK,GAAG,IAAA,qBAAW,EAAC,IAAI,CAAC,CAAA;IAC/B,IAAI,IAAA,kCAAqB,EAAC,KAAK,CAAC,IAAI,IAAA,kCAAqB,EAAC,IAAA,iBAAO,EAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QAC1E,OAAO,KAAK,CAAA;IACd,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC","sourcesContent":["import assert from 'node:assert'\nimport { join } from 'node:path'\nimport { SourceFile } from 'ts-morph'\nimport { LexiconDocument, LexiconIndexer } from '@atproto/lex-document'\nimport {\n  isGlobalIdentifier,\n  isJsKeyword,\n  isSafeLocalIdentifier,\n  isValidJsIdentifier,\n} from './ts-lang.js'\nimport {\n  asRelativePath,\n  memoize,\n  startsWithLower,\n  toCamelCase,\n  toPascalCase,\n  ucFirst,\n} from './util.js'\n\n/**\n * Configuration options for the {@link RefResolver} class.\n */\nexport type RefResolverOptions = {\n  /**\n   * The file extension to use for import specifiers when resolving\n   * external references.\n   *\n   * @default '.js'\n   */\n  importExt?: string\n}\n\n/**\n * Represents a resolved lexicon reference as TypeScript identifiers.\n *\n * Contains the variable name (for runtime schema) and type name (for\n * TypeScript type) that can be used to reference a lexicon definition.\n */\nexport type ResolvedRef = {\n  /**\n   * The variable name for the runtime schema.\n   *\n   * For local definitions, this is a simple identifier.\n   * For external definitions, this may be a qualified name like `ns.varName`\n   * or bracket notation like `ns[\"varName\"]` for unsafe identifiers.\n   */\n  varName: string\n  /**\n   * The type name for the TypeScript type alias.\n   *\n   * Always a valid TypeScript identifier, either simple or qualified.\n   */\n  typeName: string\n}\n\n/**\n * Resolves lexicon references to TypeScript identifiers.\n *\n * This class handles the resolution of `ref` types in lexicon documents,\n * converting lexicon reference strings (like `com.example.foo#bar`) into\n * valid TypeScript identifiers. It automatically manages:\n *\n * - Local references within the same document\n * - External references to other lexicon documents\n * - Import statement generation for external references\n * - Conflict avoidance with keywords, globals, and existing declarations\n *\n * Results are memoized to ensure consistent identifiers for the same\n * reference throughout a file.\n *\n * @example\n * ```ts\n * const resolver = new RefResolver(doc, sourceFile, indexer, options)\n *\n * // Resolve a local reference\n * const local = await resolver.resolve('#myDef')\n *\n * // Resolve an external reference\n * const external = await resolver.resolve('com.example.other#def')\n * ```\n */\nexport class RefResolver {\n  constructor(\n    private doc: LexiconDocument,\n    private file: SourceFile,\n    private indexer: LexiconIndexer,\n    private options: RefResolverOptions,\n  ) {}\n\n  public readonly resolve = memoize(\n    async (ref: string): Promise<ResolvedRef> => {\n      const [nsid, hash = 'main'] = ref.split('#')\n\n      if (nsid === '' || nsid === this.doc.id) {\n        return this.resolveLocal(hash)\n      } else {\n        // @NOTE: Normalize (#main fragment) to ensure proper memoization\n        const fullRef = `${nsid}#${hash}`\n        return this.resolveExternal(fullRef)\n      }\n    },\n  )\n\n  #defCounters = new Map<string, number>()\n  private nextSafeDefinitionIdentifier(name: string) {\n    // use camelCase version of the hash as base name\n    const nameSafe =\n      startsWithLower(name) && isValidJsIdentifier(name)\n        ? name\n        : toCamelCase(name).replace(/^[0-9]+/g, '') || 'def'\n\n    const count = this.#defCounters.get(nameSafe) ?? 0\n    this.#defCounters.set(nameSafe, count + 1)\n\n    // @NOTE We don't need to check against local declarations in the file here\n    // since we are using a naming system that should guarantee no other\n    // identifier has a <nameSafe>$<number> format (\"$\" cannot appear in\n    // hashes so only *we* are generating such identifiers).\n\n    const identifier = `${nameSafe}$${count}`\n\n    assert(\n      isValidJsIdentifier(identifier),\n      `Unable to generate safe identifier for: \"${name}\"`,\n    )\n\n    return identifier\n  }\n\n  /**\n   * Resolves a local definition hash to TypeScript identifiers.\n   *\n   * This method generates safe, non-conflicting identifiers for definitions\n   * within the current document. It handles edge cases like:\n   * - Hash names that are JavaScript keywords\n   * - Hash names that conflict with global identifiers\n   * - Multiple hashes that would produce the same identifier\n   *\n   * @param hash - The definition hash (e.g., 'main', 'record', 'myType')\n   * @returns A promise resolving to the TypeScript identifiers\n   * @throws Error if the hash does not exist in the document\n   * @throws Error if conflicting type names are detected\n   *\n   * @note The returned `typeName` and `varName` are *both* guaranteed to be\n   * valid TypeScript identifiers.\n   */\n  public readonly resolveLocal = memoize(\n    async (hash: string): Promise<ResolvedRef> => {\n      const hashes = Object.keys(this.doc.defs)\n\n      if (!hashes.includes(hash)) {\n        throw new Error(`Definition ${hash} not found in ${this.doc.id}`)\n      }\n\n      // Because we are using predictable \"public\" identifiers for type names,\n      // we need to ensure there are no conflicts between different definitions\n      // in the same lexicon document.\n      //\n      // @NOTE It should be possible to implement a way to generate\n      // non-conflicting type names for all public (type) identifiers in a\n      // project. However, this would add a lot of complexity to the code\n      // generation process, and the likelihood of such conflicts happening in\n      // practice is very low, so we opt for a simpler approach of just throwing\n      // an error if a conflict is detected.\n      const pub = getPublicIdentifiers(hash)\n      for (const otherHash of hashes) {\n        if (otherHash === hash) continue\n        const otherPub = getPublicIdentifiers(otherHash)\n        if (otherPub.typeName === pub.typeName) {\n          throw new Error(\n            `Conflicting type names for definitions #${hash} and #${otherHash} in ${this.doc.id}`,\n          )\n        }\n      }\n\n      // Try to keep and identifier that resembles the original hash as identifier\n      const safeIdentifier = asSafeDefinitionIdentifier(hash)\n\n      // If the safe identifier is not conflicting with other definition names,\n      // or reserved words, we can use it as-is. Otherwise, we need to generate\n      // a unique safe identifier.\n      const varName = safeIdentifier\n        ? !hashes.some((otherHash) => {\n            if (otherHash === hash) return false\n            const otherIdentifier = asSafeDefinitionIdentifier(otherHash)\n            return otherIdentifier === safeIdentifier\n          })\n          ? // Safe identifier can be used as-is as it does not conflict with\n            // other definition names\n            safeIdentifier\n          : // In order to keep identifiers stable, we use the safe identifier\n            // as base, and append a counter to avoid conflicts\n            this.nextSafeDefinitionIdentifier(safeIdentifier)\n        : // hash only contained unsafe characters, generate a safe one\n          this.nextSafeDefinitionIdentifier(hash)\n\n      const typeName = ucFirst(varName)\n      assert(isSafeLocalIdentifier(typeName), 'Expected safe type identifier')\n      assert(varName !== typeName, 'Variable and type name should be different')\n\n      return { varName, typeName }\n    },\n  )\n\n  /**\n   * @note Since this is a memoized function, and is used to generate the name\n   * of local variables, we should avoid returning different results for\n   * similar, but non strictly equal, inputs (eg. normalized / non-normalized).\n   * @see {@link resolve}\n   */\n  private readonly resolveExternal = memoize(\n    async (fullRef: string): Promise<ResolvedRef> => {\n      const [nsid, hash] = fullRef.split('#')\n      const moduleSpecifier = `${asRelativePath(\n        this.file.getDirectoryPath(),\n        join('/', ...nsid.split('.')),\n      )}.defs${this.options.importExt ?? '.js'}`\n\n      // Lets first make sure the referenced lexicon exists\n      const srcDoc = await this.indexer.get(nsid)\n      const srcDef = Object.hasOwn(srcDoc.defs, hash) ? srcDoc.defs[hash] : null\n      if (!srcDef) {\n        throw new Error(\n          `Missing def \"${hash}\" in \"${nsid}\" (referenced from ${this.doc.id})`,\n        )\n      }\n\n      const publicIds = getPublicIdentifiers(hash)\n\n      if (!isValidJsIdentifier(publicIds.typeName)) {\n        // If <typeName> is not a valid identifier, we cannot access the type\n        // using dot notation (<nsIdentifier>.<typeName>). Note that, unlike js\n        // variables, types cannot be accessed using string indexing (like:\n        // <nsIdentifier>['<typeName>']) because it generates TypeScript errors:\n        //\n        // > \"Cannot use namespace '<nsIdentifier>' as a type.\"\n\n        // Instead the generated code should look like:\n        // import { \"<unsafeTypeName>\" as <safeIdentifier> } from './<moduleSpecifier>'\n\n        // Because it requires more complex management of local variables names,\n        // and we don't expect this to actually happen with properly designed\n        // lexicons documents, we do not support this for now.\n\n        throw new Error(\n          'Import of definitions with unsafe type names is not supported',\n        )\n      }\n\n      // import * as <nsIdentifier> from './<moduleSpecifier>'\n      const nsIdentifier = this.getNsIdentifier(nsid, moduleSpecifier)\n\n      return {\n        varName: isValidJsIdentifier(publicIds.varName)\n          ? `${nsIdentifier}.${publicIds.varName}`\n          : `${nsIdentifier}[${JSON.stringify(publicIds.varName)}]`,\n        typeName: `${nsIdentifier}.${publicIds.typeName}`,\n      }\n    },\n  )\n\n  private getNsIdentifier(nsid: string, moduleSpecifier: string) {\n    const namespaceImportDeclaration =\n      this.file.getImportDeclaration(\n        (imp) =>\n          !imp.isTypeOnly() &&\n          imp.getModuleSpecifierValue() === moduleSpecifier &&\n          imp.getNamespaceImport() != null,\n      ) ||\n      this.file.addImportDeclaration({\n        moduleSpecifier,\n        namespaceImport: this.computeSafeNamespaceIdentifierFor(nsid),\n      })\n\n    return namespaceImportDeclaration.getNamespaceImport()!.getText()\n  }\n\n  #nsIdentifiersCounters = new Map<string, number>()\n  private computeSafeNamespaceIdentifierFor(nsid: string) {\n    const baseName = nsidToIdentifier(nsid) || 'NS'\n\n    let name = baseName\n    while (this.isConflictingIdentifier(name)) {\n      const count = this.#nsIdentifiersCounters.get(baseName) ?? 0\n      this.#nsIdentifiersCounters.set(baseName, count + 1)\n      name = `${baseName}$$${count}`\n    }\n\n    return name\n  }\n\n  private isConflictingIdentifier(name: string) {\n    return (\n      this.conflictsWithKeywords(name) ||\n      this.conflictsWithUtils(name) ||\n      this.conflictsWithLocalDefs(name) ||\n      this.conflictsWithLocalDeclarations(name) ||\n      this.conflictsWithImports(name)\n    )\n  }\n\n  private conflictsWithKeywords(name: string) {\n    return isJsKeyword(name) || isGlobalIdentifier(name)\n  }\n\n  private conflictsWithUtils(name: string) {\n    // Do not allow \"Main\" as imported ns identifier since it has a special\n    // meaning in the context of lexicon definitions.\n    if (name === 'Main') return true\n\n    // When \"useRecordExport\" returns true, an export named \"Record\" will be\n    // used in addition to the hash named export. So we need to make sure both\n    // names are not conflicting with local variables.\n    if (name === 'Record') return true\n\n    // Utility functions generated for lexicon schemas are prefixed with \"$\"\n    return name.startsWith('$')\n  }\n\n  private conflictsWithLocalDefs(name: string) {\n    return Object.keys(this.doc.defs).some((hash) => {\n      const identifier = toCamelCase(hash)\n\n      // A safe identifier will be generated, no risk of conflict.\n      if (!identifier) return false\n\n      // The imported name conflicts with a local definition name\n      if (identifier === name || `_${identifier}` === name) return true\n\n      // The imported name conflicts with the type name of a local definition\n      const typeName = ucFirst(identifier)\n      if (typeName === name || `_${typeName}` === name) return true\n\n      return false\n    })\n  }\n\n  private conflictsWithLocalDeclarations(name: string) {\n    return (\n      this.file.getVariableDeclarations().some((v) => v.getName() === name) ||\n      this.file\n        .getVariableStatements()\n        .some((vs) => vs.getDeclarations().some((d) => d.getName() === name)) ||\n      this.file.getTypeAliases().some((t) => t.getName() === name) ||\n      this.file.getInterfaces().some((i) => i.getName() === name) ||\n      this.file.getClasses().some((c) => c.getName() === name) ||\n      this.file.getFunctions().some((f) => f.getName() === name) ||\n      this.file.getEnums().some((e) => e.getName() === name)\n    )\n  }\n\n  private conflictsWithImports(name: string) {\n    return this.file.getImportDeclarations().some(\n      (imp) =>\n        // import name from '...'\n        imp.getDefaultImport()?.getText() === name ||\n        // import * as name from '...'\n        imp.getNamespaceImport()?.getText() === name ||\n        imp.getNamedImports().some(\n          (named) =>\n            // import { name } from '...'\n            // import { foo as name } from '...'\n            (named.getAliasNode()?.getText() ?? named.getName()) === name,\n        ),\n    )\n  }\n}\n\n/**\n * @see {@link https://atproto.com/specs/nsid NSID syntax spec}\n */\nfunction nsidToIdentifier(nsid: string) {\n  const parts = nsid.split('.')\n\n  // By default, try to keep only to the last two segments of the NSID as\n  // contextual information. If those do not form a safe identifier (typically\n  // because they start with a digit), try with more segments until we reach the\n  // full NSID.\n  for (let i = 2; i < parts.length; i++) {\n    const identifier = toPascalCase(parts.slice(-i).join('.'))\n    if (isSafeLocalIdentifier(identifier)) return identifier\n  }\n\n  return undefined\n}\n\n/**\n * Generates predictable public identifiers for a given definition hash.\n *\n * This function creates the \"public\" names that will be exported from\n * generated files. The variable name uses the original hash, while the\n * type name is converted to PascalCase.\n *\n * @param hash - The definition hash (e.g., 'main', 'myType')\n * @returns The public identifiers for the definition\n *\n * @note The returned `typeName` is guaranteed to be a valid TypeScript\n * identifier. `varName` may not be a valid identifier (eg. if the hash contains\n * unsafe characters), and may need to be accessed using string indexing.\n */\nexport function getPublicIdentifiers(hash: string): ResolvedRef {\n  const varName = hash\n\n  // @NOTE we try to circumvent the issue of unsafe type names described in\n  // `RefResolver.resolveExternal` by ensuring that type names are always safe\n  // identifiers, even if it means changing them from the original hash.\n  let typeName = toPascalCase(hash)\n\n  if (varName === typeName || !isValidJsIdentifier(typeName)) {\n    typeName = `TypeOf${typeName}`\n  }\n\n  assert(\n    isValidJsIdentifier(typeName),\n    `Unable to generate a predictable safe identifier for \"${hash}\"`,\n  )\n\n  return { varName, typeName }\n}\n\nfunction asSafeDefinitionIdentifier(name: string) {\n  if (\n    startsWithLower(name) &&\n    isSafeLocalIdentifier(name) &&\n    isSafeLocalIdentifier(ucFirst(name))\n  ) {\n    return name\n  }\n  const camel = toCamelCase(name)\n  if (isSafeLocalIdentifier(camel) && isSafeLocalIdentifier(ucFirst(camel))) {\n    return camel\n  }\n  return undefined\n}\n"]}

package/dist/ts-lang.d.ts

@@ -1,6 +1,50 @@
+/**
+ * Checks if a word is a JavaScript reserved keyword.
+ *
+ * @param word - The identifier to check
+ * @returns `true` if the word is a reserved keyword
+ */
 export declare function isJsKeyword(word: string): boolean;
+/**
+ * Checks if a word is a global identifier that should be avoided.
+ *
+ * This includes JavaScript globals, TypeScript built-in types, and
+ * identifiers commonly used in the generated code.
+ *
+ * @param word - The identifier to check
+ * @returns `true` if the word is a global identifier
+ */
 export declare function isGlobalIdentifier(word: string): boolean;
+/**
+ * Checks if a name is safe to use as a local identifier.
+ *
+ * A safe local identifier is a valid JavaScript identifier that does not
+ * conflict with global identifiers.
+ *
+ * @param name - The identifier to check
+ * @returns `true` if the name is safe to use locally
+ */
 export declare function isSafeLocalIdentifier(name: string): boolean;
+/**
+ * Checks if a name is a valid JavaScript identifier.
+ *
+ * Valid identifiers start with a letter, underscore, or dollar sign,
+ * followed by any combination of letters, digits, underscores, or dollar
+ * signs. Reserved keywords are not valid identifiers.
+ *
+ * @param name - The string to check
+ * @returns `true` if the name is a valid identifier
+ */
 export declare function isValidJsIdentifier(name: string): boolean;
+/**
+ * Converts a name to a valid namespace export identifier.
+ *
+ * If the name is a valid JavaScript identifier, it is returned as-is.
+ * Otherwise, it is returned as a quoted string for use in export statements
+ * like `export { foo as "unsafe-name" }`.
+ *
+ * @param name - The export name
+ * @returns The name as a valid export identifier
+ */
 export declare function asNamespaceExport(name: string): string;
 //# sourceMappingURL=ts-lang.d.ts.map

package/dist/ts-lang.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ts-lang.d.ts","sourceRoot":"","sources":["../src/ts-lang.ts"],"names":[],"mappings":"AA+EA,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,WAEvC;AAkDD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,WAE9C;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,WAEjD;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,WAM/C;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,UAE7C"}
+{"version":3,"file":"ts-lang.d.ts","sourceRoot":"","sources":["../src/ts-lang.ts"],"names":[],"mappings":"AAkFA;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,WAEvC;AAkDD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,WAE9C;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,WAEjD;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,WAM/C;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,UAE7C"}

package/dist/ts-lang.js

@@ -6,7 +6,10 @@ exports.isSafeLocalIdentifier = isSafeLocalIdentifier;
 exports.isValidJsIdentifier = isValidJsIdentifier;
 exports.asNamespaceExport = asNamespaceExport;
 /**
- * JavaScript keywords
+ * Set of JavaScript reserved keywords and future reserved words.
+ *
+ * These identifiers cannot be used as variable or type names in generated code.
+ *
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar}
  */
 const JS_KEYWORDS = new Set([
@@ -83,6 +86,12 @@ const JS_KEYWORDS = new Set([
     'with',
     'yield',
 ]);
+/**
+ * Checks if a word is a JavaScript reserved keyword.
+ *
+ * @param word - The identifier to check
+ * @returns `true` if the word is a reserved keyword
+ */
 function isJsKeyword(word) {
     return JS_KEYWORDS.has(word);
 }
@@ -133,17 +142,55 @@ const GLOBAL_IDENTIFIERS = new Set([
     'Capitalize',
     'Uncapitalize',
 ]);
+/**
+ * Checks if a word is a global identifier that should be avoided.
+ *
+ * This includes JavaScript globals, TypeScript built-in types, and
+ * identifiers commonly used in the generated code.
+ *
+ * @param word - The identifier to check
+ * @returns `true` if the word is a global identifier
+ */
 function isGlobalIdentifier(word) {
     return GLOBAL_IDENTIFIERS.has(word);
 }
+/**
+ * Checks if a name is safe to use as a local identifier.
+ *
+ * A safe local identifier is a valid JavaScript identifier that does not
+ * conflict with global identifiers.
+ *
+ * @param name - The identifier to check
+ * @returns `true` if the name is safe to use locally
+ */
 function isSafeLocalIdentifier(name) {
     return !isGlobalIdentifier(name) && isValidJsIdentifier(name);
 }
+/**
+ * Checks if a name is a valid JavaScript identifier.
+ *
+ * Valid identifiers start with a letter, underscore, or dollar sign,
+ * followed by any combination of letters, digits, underscores, or dollar
+ * signs. Reserved keywords are not valid identifiers.
+ *
+ * @param name - The string to check
+ * @returns `true` if the name is a valid identifier
+ */
 function isValidJsIdentifier(name) {
     return (name.length > 0 &&
         !isJsKeyword(name) &&
         /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name));
 }
+/**
+ * Converts a name to a valid namespace export identifier.
+ *
+ * If the name is a valid JavaScript identifier, it is returned as-is.
+ * Otherwise, it is returned as a quoted string for use in export statements
+ * like `export { foo as "unsafe-name" }`.
+ *
+ * @param name - The export name
+ * @returns The name as a valid export identifier
+ */
 function asNamespaceExport(name) {
     return isValidJsIdentifier(name) ? name : JSON.stringify(name);
 }

package/dist/ts-lang.js.map

@@ -1 +1 @@
-{"version":3,"file":"ts-lang.js","sourceRoot":"","sources":["../src/ts-lang.ts"],"names":[],"mappings":";;AA+EA,kCAEC;AAkDD,gDAEC;AAED,sDAEC;AAED,kDAMC;AAED,8CAEC;AArJD;;;GAGG;AACH,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC;IAC1B,UAAU;IACV,WAAW;IACX,IAAI;IACJ,OAAO;IACP,OAAO;IACP,SAAS;IACT,OAAO;IACP,MAAM;IACN,MAAM;IACN,OAAO;IACP,MAAM;IACN,OAAO;IACP,OAAO;IACP,UAAU;IACV,UAAU;IACV,SAAS;IACT,QAAQ;IACR,IAAI;IACJ,QAAQ;IACR,MAAM;IACN,MAAM;IACN,MAAM;IACN,QAAQ;IACR,SAAS;IACT,OAAO;IACP,OAAO;IACP,SAAS;IACT,OAAO;IACP,KAAK;IACL,MAAM;IACN,UAAU;IACV,KAAK;IACL,MAAM;IACN,IAAI;IACJ,YAAY;IACZ,QAAQ;IACR,IAAI;IACJ,YAAY;IACZ,KAAK;IACL,WAAW;IACX,KAAK;IACL,MAAM;IACN,QAAQ;IACR,KAAK;IACL,MAAM;IACN,IAAI;IACJ,SAAS;IACT,SAAS;IACT,WAAW;IACX,QAAQ;IACR,QAAQ;IACR,KAAK;IACL,OAAO;IACP,QAAQ;IACR,OAAO;IACP,QAAQ;IACR,cAAc;IACd,MAAM;IACN,OAAO;IACP,QAAQ;IACR,WAAW;IACX,MAAM;IACN,KAAK;IACL,QAAQ;IACR,WAAW;IACX,OAAO;IACP,KAAK;IACL,MAAM;IACN,UAAU;IACV,OAAO;IACP,MAAM;IACN,OAAO;CACR,CAAC,CAAA;AAEF,SAAgB,WAAW,CAAC,IAAY;IACtC,OAAO,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AAC9B,CAAC;AAED,0EAA0E;AAC1E,wBAAwB;AACxB,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC;IACjC,0CAA0C;IAC1C,GAAG;IACH,aAAa;IACb,MAAM;IACN,YAAY;IACZ,MAAM;IACN,QAAQ;IACR,WAAW;IACX,WAAW;IACX,YAAY;IACZ,SAAS;IACT,QAAQ;IACR,SAAS;IACT,gBAAgB;IAChB,KAAK;IACL,QAAQ;IACR,SAAS;IACT,SAAS;IACT,OAAO;IACP,MAAM;IACN,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,WAAW;IACX,SAAS;IACT,MAAM;IACN,mBAAmB;IACnB,QAAQ;IACR,SAAS;IACT,UAAU;IACV,MAAM;IACN,MAAM;IACN,SAAS;IACT,SAAS;IACT,cAAc;IACd,YAAY;IACZ,UAAU;IACV,UAAU;IACV,WAAW;IACX,WAAW;IACX,YAAY;IACZ,cAAc;CACf,CAAC,CAAA;AAEF,SAAgB,kBAAkB,CAAC,IAAY;IAC7C,OAAO,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AACrC,CAAC;AAED,SAAgB,qBAAqB,CAAC,IAAY;IAChD,OAAO,CAAC,kBAAkB,CAAC,IAAI,CAAC,IAAI,mBAAmB,CAAC,IAAI,CAAC,CAAA;AAC/D,CAAC;AAED,SAAgB,mBAAmB,CAAC,IAAY;IAC9C,OAAO,CACL,IAAI,CAAC,MAAM,GAAG,CAAC;QACf,CAAC,WAAW,CAAC,IAAI,CAAC;QAClB,4BAA4B,CAAC,IAAI,CAAC,IAAI,CAAC,CACxC,CAAA;AACH,CAAC;AAED,SAAgB,iBAAiB,CAAC,IAAY;IAC5C,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;AAChE,CAAC","sourcesContent":["/**\n * JavaScript keywords\n * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar}\n */\nconst JS_KEYWORDS = new Set([\n  'abstract',\n  'arguments',\n  'as',\n  'async',\n  'await',\n  'boolean',\n  'break',\n  'byte',\n  'case',\n  'catch',\n  'char',\n  'class',\n  'const',\n  'continue',\n  'debugger',\n  'default',\n  'delete',\n  'do',\n  'double',\n  'else',\n  'enum',\n  'eval',\n  'export',\n  'extends',\n  'false',\n  'final',\n  'finally',\n  'float',\n  'for',\n  'from',\n  'function',\n  'get',\n  'goto',\n  'if',\n  'implements',\n  'import',\n  'in',\n  'instanceof',\n  'int',\n  'interface',\n  'let',\n  'long',\n  'native',\n  'new',\n  'null',\n  'of',\n  'package',\n  'private',\n  'protected',\n  'public',\n  'return',\n  'set',\n  'short',\n  'static',\n  'super',\n  'switch',\n  'synchronized',\n  'this',\n  'throw',\n  'throws',\n  'transient',\n  'true',\n  'try',\n  'typeof',\n  'undefined',\n  'using',\n  'var',\n  'void',\n  'volatile',\n  'while',\n  'with',\n  'yield',\n])\n\nexport function isJsKeyword(word: string) {\n  return JS_KEYWORDS.has(word)\n}\n\n// Only important to list var/type names that are likely to be used in the\n// generated code files.\nconst GLOBAL_IDENTIFIERS = new Set([\n  // import { l } from \"@atproto/lex-schema\"\n  'l',\n  // JS Globals\n  'self',\n  'globalThis',\n  // ESM\n  'import',\n  // CommonJS\n  '__dirname',\n  '__filename',\n  'require',\n  'module',\n  'exports',\n  // TS Primitives\n  'any',\n  'bigint',\n  'boolean',\n  'declare',\n  'never',\n  'null',\n  'number',\n  'object',\n  'string',\n  'symbol',\n  'undefined',\n  'unknown',\n  'void',\n  // TS Utility types\n  'Record',\n  'Partial',\n  'Readonly',\n  'Pick',\n  'Omit',\n  'Exclude',\n  'Extract',\n  'InstanceType',\n  'ReturnType',\n  'Required',\n  'ThisType',\n  'Uppercase',\n  'Lowercase',\n  'Capitalize',\n  'Uncapitalize',\n])\n\nexport function isGlobalIdentifier(word: string) {\n  return GLOBAL_IDENTIFIERS.has(word)\n}\n\nexport function isSafeLocalIdentifier(name: string) {\n  return !isGlobalIdentifier(name) && isValidJsIdentifier(name)\n}\n\nexport function isValidJsIdentifier(name: string) {\n  return (\n    name.length > 0 &&\n    !isJsKeyword(name) &&\n    /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name)\n  )\n}\n\nexport function asNamespaceExport(name: string) {\n  return isValidJsIdentifier(name) ? name : JSON.stringify(name)\n}\n"]}
+{"version":3,"file":"ts-lang.js","sourceRoot":"","sources":["../src/ts-lang.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Set of JavaScript reserved keywords and future reserved words.\n *\n * These identifiers cannot be used as variable or type names in generated code.\n *\n * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar}\n */\nconst JS_KEYWORDS = new Set([\n  'abstract',\n  'arguments',\n  'as',\n  'async',\n  'await',\n  'boolean',\n  'break',\n  'byte',\n  'case',\n  'catch',\n  'char',\n  'class',\n  'const',\n  'continue',\n  'debugger',\n  'default',\n  'delete',\n  'do',\n  'double',\n  'else',\n  'enum',\n  'eval',\n  'export',\n  'extends',\n  'false',\n  'final',\n  'finally',\n  'float',\n  'for',\n  'from',\n  'function',\n  'get',\n  'goto',\n  'if',\n  'implements',\n  'import',\n  'in',\n  'instanceof',\n  'int',\n  'interface',\n  'let',\n  'long',\n  'native',\n  'new',\n  'null',\n  'of',\n  'package',\n  'private',\n  'protected',\n  'public',\n  'return',\n  'set',\n  'short',\n  'static',\n  'super',\n  'switch',\n  'synchronized',\n  'this',\n  'throw',\n  'throws',\n  'transient',\n  'true',\n  'try',\n  'typeof',\n  'undefined',\n  'using',\n  'var',\n  'void',\n  'volatile',\n  'while',\n  'with',\n  'yield',\n])\n\n/**\n * Checks if a word is a JavaScript reserved keyword.\n *\n * @param word - The identifier to check\n * @returns `true` if the word is a reserved keyword\n */\nexport function isJsKeyword(word: string) {\n  return JS_KEYWORDS.has(word)\n}\n\n// Only important to list var/type names that are likely to be used in the\n// generated code files.\nconst GLOBAL_IDENTIFIERS = new Set([\n  // import { l } from \"@atproto/lex-schema\"\n  'l',\n  // JS Globals\n  'self',\n  'globalThis',\n  // ESM\n  'import',\n  // CommonJS\n  '__dirname',\n  '__filename',\n  'require',\n  'module',\n  'exports',\n  // TS Primitives\n  'any',\n  'bigint',\n  'boolean',\n  'declare',\n  'never',\n  'null',\n  'number',\n  'object',\n  'string',\n  'symbol',\n  'undefined',\n  'unknown',\n  'void',\n  // TS Utility types\n  'Record',\n  'Partial',\n  'Readonly',\n  'Pick',\n  'Omit',\n  'Exclude',\n  'Extract',\n  'InstanceType',\n  'ReturnType',\n  'Required',\n  'ThisType',\n  'Uppercase',\n  'Lowercase',\n  'Capitalize',\n  'Uncapitalize',\n])\n\n/**\n * Checks if a word is a global identifier that should be avoided.\n *\n * This includes JavaScript globals, TypeScript built-in types, and\n * identifiers commonly used in the generated code.\n *\n * @param word - The identifier to check\n * @returns `true` if the word is a global identifier\n */\nexport function isGlobalIdentifier(word: string) {\n  return GLOBAL_IDENTIFIERS.has(word)\n}\n\n/**\n * Checks if a name is safe to use as a local identifier.\n *\n * A safe local identifier is a valid JavaScript identifier that does not\n * conflict with global identifiers.\n *\n * @param name - The identifier to check\n * @returns `true` if the name is safe to use locally\n */\nexport function isSafeLocalIdentifier(name: string) {\n  return !isGlobalIdentifier(name) && isValidJsIdentifier(name)\n}\n\n/**\n * Checks if a name is a valid JavaScript identifier.\n *\n * Valid identifiers start with a letter, underscore, or dollar sign,\n * followed by any combination of letters, digits, underscores, or dollar\n * signs. Reserved keywords are not valid identifiers.\n *\n * @param name - The string to check\n * @returns `true` if the name is a valid identifier\n */\nexport function isValidJsIdentifier(name: string) {\n  return (\n    name.length > 0 &&\n    !isJsKeyword(name) &&\n    /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name)\n  )\n}\n\n/**\n * Converts a name to a valid namespace export identifier.\n *\n * If the name is a valid JavaScript identifier, it is returned as-is.\n * Otherwise, it is returned as a quoted string for use in export statements\n * like `export { foo as \"unsafe-name\" }`.\n *\n * @param name - The export name\n * @returns The name as a valid export identifier\n */\nexport function asNamespaceExport(name: string) {\n  return isValidJsIdentifier(name) ? name : JSON.stringify(name)\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto/lex-builder",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "license": "MIT",
   "description": "TypeScript schema builder for AT Lexicons",
   "keywords": [
@@ -39,8 +39,8 @@
     "prettier": "^3.2.5",
     "ts-morph": "^27.0.0",
     "tslib": "^2.8.1",
-    "@atproto/lex-document": "0.0.11",
-    "@atproto/lex-schema": "0.0.10"
+    "@atproto/lex-document": "^0.0.13",
+    "@atproto/lex-schema": "^0.0.12"
   },
   "devDependencies": {
     "@ts-morph/common": "^0.28.0",

package/src/filter.ts

@@ -1,10 +1,65 @@
+/**
+ * Options for building a filter function to include/exclude lexicon documents.
+ */
 export type BuildFilterOptions = {
+  /**
+   * Pattern(s) for lexicon NSIDs to include.
+   *
+   * Supports glob patterns with `*` as a wildcard that matches one or more
+   * characters. If not specified, all lexicons are included by default.
+   *
+   * @example
+   * ```ts
+   * { include: 'app.bsky.*' }           // Include all app.bsky lexicons
+   * { include: ['com.atproto.*', 'app.bsky.*'] }  // Include multiple patterns
+   * ```
+   */
   include?: string | string[]
+  /**
+   * Pattern(s) for lexicon NSIDs to exclude.
+   *
+   * Supports glob patterns with `*` as a wildcard. Exclusions are applied
+   * after inclusions.
+   *
+   * @example
+   * ```ts
+   * { exclude: '*.internal.*' }         // Exclude internal lexicons
+   * { exclude: ['*.test', '*.mock'] }   // Exclude test and mock lexicons
+   * ```
+   */
   exclude?: string | string[]
 }
 
+/**
+ * A function that tests whether a lexicon NSID should be included.
+ *
+ * @param input - The lexicon NSID to test
+ * @returns `true` if the NSID passes the filter, `false` otherwise
+ */
 export type Filter = (input: string) => boolean
 
+/**
+ * Builds a filter function from include/exclude patterns.
+ *
+ * The returned filter returns `true` for NSIDs that match any include pattern
+ * (or all NSIDs if no include patterns are specified) AND do not match any
+ * exclude pattern.
+ *
+ * @param options - The filter options containing include/exclude patterns
+ * @returns A filter function that can be applied to lexicon NSIDs
+ *
+ * @example
+ * ```ts
+ * const filter = buildFilter({
+ *   include: 'app.bsky.*',
+ *   exclude: '*.internal.*',
+ * })
+ *
+ * filter('app.bsky.feed.post')     // true
+ * filter('app.bsky.internal.foo')  // false
+ * filter('com.atproto.repo')       // false (not included)
+ * ```
+ */
 export function buildFilter(options: BuildFilterOptions): Filter {
   const include = createMatcher(options.include, () => true)
   const exclude = createMatcher(options.exclude, () => false)

package/src/formatter.ts

@@ -12,16 +12,49 @@ const DEFAULT_BANNER = `/*
  * THIS FILE WAS GENERATED BY "@atproto/lex". DO NOT EDIT.
  */`
 
+/**
+ * Options for configuring the code formatter.
+ */
 export type FormatterOptions = {
-  /** @default false */
+  /**
+   * Whether to format the generated code with Prettier.
+   *
+   * - `false`: No formatting (default)
+   * - `true`: Format with default Prettier options
+   * - `PrettierOptions`: Format with custom Prettier configuration
+   *
+   * @default false
+   */
   pretty?: boolean | PrettierOptions
+  /**
+   * A banner comment to prepend to each generated file.
+   *
+   * @default '/* THIS FILE WAS GENERATED BY "@atproto/lex". DO NOT EDIT. *\/'
+   */
   banner?: string
 }
 
+/**
+ * Formats generated TypeScript code with optional Prettier formatting
+ * and banner comments.
+ *
+ * @example
+ * ```ts
+ * const formatter = new Formatter({ pretty: true })
+ * const formatted = await formatter.format(generatedCode)
+ * ```
+ */
 export class Formatter {
+  /** The banner comment to prepend to formatted code. */
   readonly banner: string
+  /** Prettier options, or `null` if formatting is disabled. */
   readonly prettierOptions: PrettierOptions | null
 
+  /**
+   * Creates a new Formatter instance.
+   *
+   * @param options - Formatting configuration options
+   */
   constructor(options: FormatterOptions = {}) {
     this.banner = options?.banner ?? DEFAULT_BANNER
 
@@ -31,6 +64,14 @@ export class Formatter {
         : options?.pretty || null
   }
 
+  /**
+   * Formats the given code string.
+   *
+   * Applies Prettier formatting if enabled, and prepends the banner comment.
+   *
+   * @param code - The TypeScript code to format
+   * @returns The formatted code with banner
+   */
   async format(code: string) {
     const bannerPadding =
       this.banner && !this.banner.endsWith('\n') ? '\n\n' : ''

package/src/index.ts

@@ -11,10 +11,43 @@ import {
 export * from './lex-builder.js'
 export * from './lexicon-directory-indexer.js'
 
+/**
+ * Combined options for building a TypeScript project from Lexicon documents.
+ *
+ * This type merges all configuration options needed for the complete build
+ * process, including builder configuration, loading options, and save options.
+ *
+ * @see {@link LexBuilderOptions} for builder configuration
+ * @see {@link LexBuilderLoadOptions} for lexicon loading options
+ * @see {@link LexBuilderSaveOptions} for output save options
+ */
 export type TsProjectBuildOptions = LexBuilderOptions &
   LexBuilderLoadOptions &
   LexBuilderSaveOptions
 
+/**
+ * Builds TypeScript schemas from Lexicon documents.
+ *
+ * This is the main entry point for programmatic usage of the lex-builder
+ * package. It creates a new {@link LexBuilder} instance, loads lexicon
+ * documents from the specified directory, and saves the generated TypeScript
+ * files to the output directory.
+ *
+ * @param options - Combined build options including source directory, output
+ *   directory, and generation settings
+ *
+ * @example
+ * ```ts
+ * import { build } from '@atproto/lex-builder'
+ *
+ * await build({
+ *   lexicons: './lexicons',
+ *   out: './src/generated',
+ *   pretty: true,
+ *   clear: true,
+ * })
+ * ```
+ */
 export async function build(options: TsProjectBuildOptions) {
   const builder = new LexBuilder(options)
   await builder.load(options)

package/src/lex-builder.ts

@@ -13,6 +13,14 @@ import {
 } from './lexicon-directory-indexer.js'
 import { asNamespaceExport } from './ts-lang.js'
 
+/**
+ * Configuration options for the {@link LexBuilder} class.
+ *
+ * Extends {@link LexDefBuilderOptions} with additional settings for
+ * controlling the generated TypeScript project structure.
+ *
+ * @see {@link LexDefBuilderOptions} for definition generation options
+ */
 export type LexBuilderOptions = LexDefBuilderOptions & {
   /**
    * Whether to generate an index file at the root exporting all top-level
@@ -22,19 +30,80 @@ export type LexBuilderOptions = LexDefBuilderOptions & {
    * @default false
    */
   indexFile?: boolean
+  /**
+   * The file extension to use for import specifiers in the generated code.
+   *
+   * @default '.js'
+   */
   importExt?: string
+  /**
+   * The file extension to use for generated TypeScript files.
+   *
+   * @default '.ts'
+   */
   fileExt?: string
 }
 
+/**
+ * Options for loading lexicon documents into the builder.
+ *
+ * Combines directory indexing options with filtering options to control
+ * which lexicon documents are processed.
+ *
+ * @see {@link LexiconDirectoryIndexerOptions} for directory scanning options
+ * @see {@link BuildFilterOptions} for include/exclude filtering
+ */
 export type LexBuilderLoadOptions = LexiconDirectoryIndexerOptions &
   BuildFilterOptions
 
+/**
+ * Options for saving generated TypeScript files.
+ *
+ * Combines formatting options with output directory configuration.
+ */
 export type LexBuilderSaveOptions = FormatterOptions & {
+  /**
+   * The output directory path where generated TypeScript files will be written.
+   */
   out: string
+  /**
+   * Whether to clear the output directory before writing files.
+   *
+   * When `true`, the entire output directory is deleted before writing new files.
+   *
+   * @default false
+   */
   clear?: boolean
+  /**
+   * Whether to allow overwriting existing files.
+   *
+   * When `false`, an error is thrown if any output file already exists.
+   *
+   * @default false
+   */
   override?: boolean
 }
 
+/**
+ * Main builder class for generating TypeScript schemas from Lexicon documents.
+ *
+ * The LexBuilder orchestrates the entire code generation process:
+ * 1. Loading and indexing lexicon documents from the filesystem
+ * 2. Generating TypeScript type definitions and runtime schemas
+ * 3. Creating namespace export trees for convenient imports
+ * 4. Saving formatted output files
+ *
+ * @example
+ * ```ts
+ * const builder = new LexBuilder({ indexFile: true, pretty: true })
+ *
+ * // Load lexicons from a directory
+ * await builder.load({ lexicons: './lexicons' })
+ *
+ * // Save generated TypeScript to output directory
+ * await builder.save({ out: './src/generated', clear: true })
+ * ```
+ */
 export class LexBuilder {
   readonly #imported = new Set<string>()
   readonly #project = new Project({

package/src/lex-def-builder.ts

@@ -38,14 +38,50 @@ import {
 } from './ref-resolver.js'
 import { asNamespaceExport } from './ts-lang.js'
 
+/**
+ * Configuration options for the {@link LexDefBuilder} class.
+ *
+ * @see {@link RefResolverOptions} for reference resolution options
+ */
 export type LexDefBuilderOptions = RefResolverOptions & {
+  /**
+   * The module specifier to use for importing the lexicon schema library.
+   *
+   * @default '@atproto/lex-schema'
+   */
   lib?: string
+  /**
+   * Whether to allow legacy blob references in the generated schemas.
+   *
+   * When `true`, blob types will accept both modern `BlobRef` and legacy
+   * `LegacyBlobRef` formats.
+   *
+   * @default false
+   */
   allowLegacyBlobs?: boolean
+  /**
+   * Whether to add `#__PURE__` annotations to function calls.
+   *
+   * These annotations help bundlers with tree-shaking by marking
+   * side-effect-free function calls.
+   *
+   * @default false
+   */
   pureAnnotations?: boolean
 }
 
 /**
- * Utility class to build a TypeScript source file from a lexicon document.
+ * Builds TypeScript type definitions and runtime schemas from a single
+ * Lexicon document.
+ *
+ * This class is responsible for generating the `.defs.ts` files that contain:
+ * - Type aliases for each lexicon definition
+ * - Runtime schema validators using `@atproto/lex-schema`
+ * - Utility functions for type checking and validation
+ * - Proper import statements for cross-references
+ *
+ * Each lexicon definition type (record, object, query, procedure, etc.)
+ * is handled with specialized code generation logic.
  */
 export class LexDefBuilder {
   private readonly refResolver: RefResolver

package/src/lexicon-directory-indexer.ts

@@ -6,8 +6,21 @@ import {
   lexiconDocumentSchema,
 } from '@atproto/lex-document'
 
+/**
+ * Options for the {@link LexiconDirectoryIndexer}.
+ *
+ * @see {@link ReadLexiconsOptions} for available options
+ */
 export type LexiconDirectoryIndexerOptions = ReadLexiconsOptions
 
+/**
+ * Indexes lexicon documents from a filesystem directory.
+ *
+ * This class recursively scans a directory for JSON files, parses them as
+ * lexicon documents, and provides an iterable interface for processing them.
+ * It extends {@link LexiconIterableIndexer} to support both iteration and
+ * lookup by NSID.
+ */
 export class LexiconDirectoryIndexer extends LexiconIterableIndexer {
   constructor(options: LexiconDirectoryIndexerOptions) {
     super(readLexicons(options))