Unit Hierarchy Information

Short introduction

This custom command returns Ada compilation units and their source files across the loaded GPR project tree. Clients can use the result to build a unit hierarchy without grouping units by project or source directory.

Change description

The command takes no arguments and is executed through workspace/executeCommand:

{
    "command": "als-unit-hierarchy-information",
    "arguments": []
}

The command is advertised in executeCommandProvider.commands in the initialize response. It returns null when no project tree is available. Otherwise, it returns UnitHierarchyInformation:

export interface UnitHierarchyProject {
    id: string;
    name: string;
    uri?: DocumentUri;
    "is-runtime": boolean;
    "is-externally-built": boolean;
}

export interface UnitHierarchyPart {
    kind: "specification" | "body" | "separate" | "unknown";
    uri: DocumentUri;
    "unit-index": number;
    project: UnitHierarchyProject;
    "separate-name"?: string;
    range?: Range;
    "selection-range"?: Range;
}

export interface UnitHierarchyUnit {
    "namespace-id": string;
    name: string;
    "simple-name": string;
    "parent-name": string;
    kind: "package" | "subprogram" | "unknown";
    "is-generic"?: boolean;
    "is-instantiation"?: boolean;
    "is-renaming"?: boolean;
    parts: UnitHierarchyPart[];
}

export interface UnitHierarchyInformation {
    "root-project": UnitHierarchyProject;
    namespaces: UnitHierarchyProject[];
    units: UnitHierarchyUnit[];
}

export type UnitHierarchyResponse = UnitHierarchyInformation | null;

DocumentUri and Range are the standard LSP types.

Units and namespaces

root-project describes the loaded root project. namespaces lists the project views that define separate compilation namespaces. An aggregate project can contain several namespaces, each with its own definition of the same unit name. Project IDs are opaque GPR2 view IDs.

Each unit is identified by its namespace-id and qualified name. Its namespace-id refers to an entry in namespaces. Shared dependencies can appear in more than one namespace, so clients should not merge definitions by name alone.

Names use GPR2’s canonical casing. For a unit named A.B.C, simple-name is C and parent-name is A.B. Root units have an empty parent-name. A parent can be missing from units if its source is unavailable; clients can still create the corresponding parent node from its name.

The list follows GPR2’s compilation-unit model. It includes packages and library subprograms, including generic declarations, instantiations, and renamings. Nested package declarations are not listed. The declaration flags distinguish generic units, instances, and renamings without changing their package or subprogram kind.

Source parts and navigation

parts contains the unit’s specification, body, and separates when available. Each part has its own source URI and owning project. GPR2 selects the visible parts according to the loaded project, including custom naming rules, project extensions, and runtime overrides.

unit-index is zero for a single-unit source. For multi-unit sources, it is the one-based position of the compilation unit within the file. Several parts can therefore have the same URI and different indices and ranges.

For a separate, separate-name is its name relative to the containing library unit. Separates are returned as parts of that unit rather than as nested package declarations.

range covers the declaration, and selection-range covers its defining name. Both use zero-based LSP lines and UTF-16 columns, with an excluded end position. Clients can use the selection range to navigate directly to a declaration, including declarations in multi-unit files.

If a declaration cannot be identified, kind is unknown. Declaration flags and navigation ranges may be absent, but the source and project metadata remain available. Parser recovery can still provide ranges for malformed source files.

Runtime and externally built units are included. Clients can identify or hide them using the is-runtime and is-externally-built flags on each part’s project. A project URI is omitted when the project view has no project file.