workitem-normalizer

workitem-normalizer

Transforms raw Azure DevOps work item objects into the normalised InternalTicket format consumed by domain-router and dependency-mapper. Runs after iteration-fetcher, before tag-classifier.

InternalTicket Schema

{
  "id": "4721",
  "title": "Add login endpoint",
  "description": "Plain text, max 500 chars",
  "type": "User Story",
  "labels": ["api", "auth"],
  "components": ["MyProject", "Backend", "Auth"],
  "links": [
    { "type": "blocks", "targetId": "4722" }
  ],
  "priority": "2",
  "assignee": "[email protected]",
  "domainSignals": []
}

Field Mappings

InternalTicket field	ADO source
id	workItem.id as string (e.g. "4721")
title	fields["System.Title"]
description	fields["System.Description"] — HTML to plain text (see below), truncated to 500 chars
type	fields["System.WorkItemType"]
labels	fields["System.Tags"] split on "; " (semicolon + space), each segment trimmed. If null or empty, use []
components	fields["System.AreaPath"] split on \ — all segments included. If null or empty, use []
links	workItem.relations — see link normalisation below. If relations is null or empty, use []
priority	fields["Microsoft.VSTS.Common.Priority"] converted to string ("1", "2", "3", "4"). If null, use null
assignee	fields["System.AssignedTo"].uniqueName. If null or unassigned, use null
domainSignals	Empty array [] — populated by tag-classifier

HTML to Plain Text

ADO work item descriptions are HTML. Convert to plain text:

1. Strip all HTML tags (remove anything matching <[^>]+>)
2. Decode HTML entities:
   • & → &
   • < → <
   • > → >
   •   → (space)
   • ' → '
   • " → "
3. Collapse whitespace: replace sequences of spaces, tabs, and newlines with a single space
4. Trim leading and trailing whitespace
5. Truncate to 500 characters

If description is null or not a string, use "".

Link Normalisation

Map ADO rel values to internal link types:

ADO rel	Internal type
System.LinkTypes.Dependency-Forward	blocks
System.LinkTypes.Dependency-Reverse	is blocked by
System.LinkTypes.Related	relates to
All others	relates to

For each relation in workItem.relations:

• Extract the target work item ID from the last path segment of the url field (e.g. https://dev.azure.com/org/proj/_apis/wit/workitems/4722 → "4722")
• Skip relations whose url does not point to a work item (e.g. hyperlinks, commits)
• Emit one { type, targetId } object per valid relation

Output

Array of InternalTicket objects, one per raw ADO work item.

[
  {
    "id": "4721",
    "title": "Add login endpoint",
    "description": "Implement JWT-based auth on the /login endpoint using the existing user service.",
    "type": "User Story",
    "labels": ["api", "auth"],
    "components": ["MyProject", "Backend", "Auth"],
    "links": [
      { "type": "blocks", "targetId": "4722" }
    ],
    "priority": "2",
    "assignee": "[email protected]",
    "domainSignals": []
  }
]