renderLuaLsAnnotations function

String renderLuaLsAnnotations(List<Library> libraries, { String packageName = 'lualike', String? packageVersion, })

Renders LuaLS-compatible annotation stubs for the documented libraries.

The output is valid Lua source intended to be indexed by LuaLS as a definition file. It uses ---@meta, table declarations, ---@param, and ---@return annotations so existing Lua language tooling can provide completion, hover text, and signature help without LuaLike owning an LSP.

Implementation

String renderLuaLsAnnotations(
  List<Library> libraries, {
  String packageName = 'lualike',
  String? packageVersion,
}) {
  final buf = StringBuffer()
    ..writeln('---@meta _')
    ..writeln('---Generated LuaLS annotations for $packageName.')
    ..writeln('---Do not execute this file; add it to LuaLS as a library.')
    ..writeln('---Generator: lualike.docs')
    ..writeln('---Schema: 2');
  if (packageVersion != null) {
    buf.writeln('---Package version: $packageVersion');
  }
  buf.writeln();

  final emittedTables = <String>{};
  for (final lib in libraries) {
    final docs = lib.getDocs();
    final tableDocs = lib.getTableDocs();
    final aliasDocs = lib.getAliasDocs();
    final enumDocs = lib.getEnumDocs();
    final valueDocs = lib.getValueDocs();

    if (docs.isEmpty &&
        tableDocs.isEmpty &&
        aliasDocs.isEmpty &&
        enumDocs.isEmpty &&
        valueDocs.isEmpty) {
      continue;
    }
    final libraryName = _libraryDocName(lib, docs);
    if (lib.name.isNotEmpty) {
      _emitLuaLsTable(buf, libraryName, emittedTables);
    }

    final useNamespace = lib.name.isNotEmpty;

    // Emit aliases
    for (final entry in aliasDocs.entries) {
      _emitLuaLsAliasDoc(buf, entry.value);
    }

    // Emit enums
    for (final entry in enumDocs.entries) {
      _emitLuaLsEnumDoc(buf, entry.value);
    }

    // Emit value/constant definitions
    for (final entry in valueDocs.entries) {
      final qualifiedName = useNamespace
          ? _qualifiedFunctionName(libraryName, entry.key)
          : entry.key;
      _emitLuaLsValueDoc(buf, qualifiedName, entry.value, emittedTables);
    }

    // Emit table schema class definitions
    for (final entry in tableDocs.entries) {
      final qualifiedName = useNamespace
          ? _qualifiedFunctionName(libraryName, entry.key)
          : entry.key;
      _emitLuaLsTableDoc(buf, qualifiedName, entry.value);
    }

    // Emit function definitions (skip names already defined as tables)
    for (final entry in docs.entries) {
      final qualifiedName = _qualifiedFunctionName(libraryName, entry.key);
      if (tableDocs.containsKey(entry.key) ||
          tableDocs.containsKey(qualifiedName)) {
        final globalName = useNamespace ? qualifiedName : entry.key;
        _emitLuaLsTypedGlobal(buf, globalName, emittedTables);
        continue;
      }
      _emitLuaLsFunction(
        buf,
        qualifiedName: qualifiedName,
        doc: entry.value,
        emittedTables: emittedTables,
      );
    }
  }

  return buf.toString();
}