Expose an owned headless semantic export API

[aaaaaandrew]

Use case

Non-editor tools sometimes need PHPantom's parser and resolver over a supplied set of source documents without starting an LSP transport or exposing PHPantom's arena-backed internal types.

The existing headless analyze command is diagnostic-oriented. A semantic export API would instead return declarations, references, calls, ranges, and resolution diagnostics for downstream code-intelligence tools.

Proposed behavior

Expose an optional API that accepts source documents and returns owned semantic records:

struct SourceDocument {
    uri: String,
    source: String,
}

struct ExportBatch {
    documents: Vec<ExportDocument>,
    diagnostics: Vec<ExportDiagnostic>,
}

export_documents(sources):
    create one shared project context
    parse and register every document
    populate cross-document symbol indexes
    export each document into owned DTOs
    sort outputs deterministically
    return the batch

The exported DTOs should contain no parser arenas, borrowed source ranges, or internal ClassInfo values. Callers can then serialize or process results after the PHPantom backend is dropped.

Required properties

• Caller-supplied sources; no mandatory filesystem discovery.
• No network access during export.
• Shared cross-document name and member resolution.
• Owned declarations, references, calls, ranges, and diagnostics.
• Deterministic output independent of hash-map iteration order.
• Malformed files produce document-level diagnostics rather than aborting the entire batch.
• Optional build mode that does not download stubs for offline consumers.

Non-goals

• Defining a specific downstream index format.
• Managing worker limits or process isolation.
• Running an LSP transport.
• Loading package-manager metadata on the caller's behalf.

[AJenbo]

Could you elaborate on the non-editor tools :)