Skip to content

Add tooling API to expose macro registry metadata #102

@rohal12

Description

@rohal12

Summary

Expose the macro registry for external tooling (LSP servers, linters, CLI checkers) so they can enumerate all registered macros and their metadata without relying on hardcoded definitions or config files.

Motivation

We're building a standalone Spindle LSP server (@rohal12/spindle-lsp) that provides diagnostics, completions, hover, and other IDE features for any editor (VS Code, Neovim, Claude Code, etc.).

Currently, the macro registry in registry.ts is a private Map with only getMacro(name) and isSubMacro(name) exposed. There's no way to:

  • Enumerate all registered macros (built-in + custom)
  • Retrieve macro metadata (block status, sub-macros, parameter definitions, storeVar flag)
  • Distinguish built-in macros from user-defined ones

This forces tooling to maintain a separate hardcoded macro list (macros.json) that can drift out of sync with the engine.

Proposed API

// New export from Spindle
interface MacroMetadata {
  name: string;
  block: boolean;
  subMacros: string[];
  storeVar?: boolean;
  interpolate?: boolean;
  merged?: boolean;
  source: 'builtin' | 'user';  // distinguish origin
  description?: string;         // optional doc string for tooling
  parameters?: ParameterDef[];  // optional typed parameter schema
}

// On Story API
Story.getMacroRegistry(): MacroMetadata[]

// Or as a standalone export for headless/Node.js use
import { getMacroRegistry } from '@rohal12/spindle/tooling';

Implementation Notes

  • Preserve metadata from defineMacro() config in the registry (currently interpolate, merged, storeVar are used during setup but not stored)
  • Add an optional description and parameters field to MacroDefinition so macro authors can provide tooling hints
  • Export a tooling entry point that doesn't require browser DOM, so the LSP can import it in Node.js
  • Consider a --dump-macros CLI flag on the compile script that outputs the registry as JSON

Use Cases

  1. LSP server - Auto-discover all macros for diagnostics, completions, hover docs
  2. CLI checker (spindle-lsp check) - Validate macro usage without a config file
  3. Documentation generation - Auto-generate macro reference from registry metadata

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions