Skip to content

feat: Implement azdo boards area project list command #143

Description

@tmeckel

Track implementation of the azdo boards area project list command.

Command Description

List the area path hierarchy for a given project within an Azure DevOps organization. Area paths (classification nodes) segment work by product or team ownership and are surfaced through the Work Item Tracking Classification Nodes REST API.

Command Signature

azdo boards area project list [organization/]<project>
  • Aliases: ls, l
  • Positional argument follows the standard [organization/]<project> split. Default organization is applied when omitted. Emit a helpful error if no organization is provided or configured.

Flags

  • --path, -p: Optional. Absolute area path (e.g. Area/SubTeam) to use as the root of the listing. When omitted, list from the project root.
  • --depth, -d: Optional integer (1–10) limiting the number of child levels to retrieve. Defaults to 3. Map directly to the $depth query parameter of the Classification Nodes REST API (Get the area tree with 2 levels of children).
  • --include-ids: Optional bool. When set, include the node ID/Identifier fields in table output.
  • --json / --jq / --template: Registered via util.AddJSONFlags so users can emit structured output. Default output renders as a table.

Behavior

  1. Resolve IOStreams and start the progress indicator before network operations. Stop it before emitting any output.
  2. Parse [organization/]<project> using shared helpers, retrieving the default organization when needed.
  3. Acquire a Work Item Tracking classification client via ctx.ClientFactory().WorkItemTracking(...). Prepare the request to classificationnodes/Areas:
    • If --path is provided, resolve it relative to the project root and call GetClassificationNode with structureGroup=Areas to fetch the subtree.
    • Otherwise, call GetClassificationNodes for the area tree with the provided $depth.
  4. Normalize the API response into a slice of rows containing at minimum: Name, fully-qualified Path, HasChildren, and Level. Include ID/Identifier when --include-ids is set. The Path value must always be the exact string users can pass to azdo boards work-item list --area (no truncation or formatting that would prevent copy/paste).
  5. When JSON export is requested, marshal a struct with json:"nodes" containing the ordered list. Each node entry must include path so automation can feed the value to --area without scraping table output.
  6. For table output, use ctx.Printer("list"), add appropriate columns (e.g. Name, Path, Has Children, Level, optional ID). Render rows depth-first with indentation prefixes (e.g. ├─, └─) based on level.
  7. Wrap errors with %w and surface helpful context (e.g. invalid path, missing project).

Testing

  • Table-driven tests exercising:
    • Root listing with default depth.
    • Listing limited by --depth.
    • Listing from a custom --path.
    • JSON export path ensuring path is present for every node.
    • Error surface when classification client returns an error.
  • Use mocks under internal/mocks for the classification client to return nested node structures.

References

Metadata

Metadata

Assignees

Labels

No labels
No labels

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions