Add component manifest build step

[zamoore]

📌 Summary

If merged, this PR adds the generation of a components manifest file to the build process.

The manifest is being introduced as a single source of truth for the Helios MCP server, so component API metadata can be consumed consistently from one canonical artifact instead of being re-derived in multiple places. As a separate line of work, we’re also exploring using this same manifest as an input for docs generation in the future.

🛠️ Detailed description

parse-docs.js parses docs metadata from src/components.ts exports by mapping each exported component name (for example, HdsAccordion) to a matching signature interface name (HdsAccordionSignature) in the component family’s types.ts file. For each resolved signature, the parser extracts Args, Blocks, and Element, plus TSDoc metadata (description, @remarks, @defaultValue, @dependsOn, @splattributes) and normalizes it into dist/manifest/components.json. Type text is resolved through a detailed AST-based resolver that expands aliases/imported types, handles unions/intersections/tuples/arrays, supports indexed access and template-literal types, and detects enum-like string unions for values output. Yields also get special handling so contextual component yields are normalized to component.

Resolution is intentionally strict and deterministic: signature lookup is expected in a single nearest types.ts. If either the family types.ts or the expected *Signature interface is missing, that component is skipped and counted (non-fatal), which keeps the build stable while making gaps visible.

I'm recommending signatures live in types.ts (instead of inline in .gts) because ts-morph/type-checker semantics are significantly more reliable on plain TypeScript than on template-backed .gts files. In practice, signatures in .gts can degrade to partial/any type info, which causes empty args/blocks/element output. Centralizing signatures in types.ts preserves colocated component typing while giving consistent, maintainable doc generation.

Example

Input

export interface HdsAccordionSignature {
  Args: {
    /**
     * @defaultValue 'medium'
     */
    size?: HdsAccordionSizes;

    /**
     * @defaultValue 'card'
     */
    type?: HdsAccordionTypes;

    /**
     * Controls the state of all items within a group. Can be used to expand or collapse all items at once.
     * @defaultValue 'close'
     */
    forceState?: HdsAccordionForceStates;

    /**
     * The HTML tag that wraps the content of each Accordion Item "toggle" block.
     * @defaultValue 'div'
     */
    titleTag?: HdsAccordionItemTitleTags;
  };
  Blocks: {
    default: [
      {
        Item?: WithBoundArgs<
          typeof HdsAccordionItem,
          'titleTag' | 'size' | 'type' | 'forceState'
        >;
      },
    ];
  };
  Element: HTMLDivElement;
}

Output

{
  "HdsAccordion": {
    "name": "HdsAccordion",
    "args": [
      {
        "name": "forceState",
        "type": "enum",
        "required": false,
        "description": "Controls the state of all items within a group. Can be used to expand or collapse all items at once.",
        "remarks": "",
        "defaultValue": "'close'",
        "dependsOn": null,
        "values": [
          "open",
          "close"
        ]
      },
      {
        "name": "size",
        "type": "enum",
        "required": false,
        "description": "",
        "remarks": "",
        "defaultValue": "'medium'",
        "dependsOn": null,
        "values": [
          "small",
          "medium",
          "large"
        ]
      },
      {
        "name": "titleTag",
        "type": "enum",
        "required": false,
        "description": "The HTML tag that wraps the content of each Accordion Item \"toggle\" block.",
        "remarks": "",
        "defaultValue": "'div'",
        "dependsOn": null,
        "values": [
          "div",
          "h1",
          "h2",
          "h3",
          "h4",
          "h5",
          "h6"
        ]
      },
      {
        "name": "type",
        "type": "enum",
        "required": false,
        "description": "",
        "remarks": "",
        "defaultValue": "'card'",
        "dependsOn": null,
        "values": [
          "card",
          "flush"
        ]
      }
    ],
    "blocks": [
      {
        "name": "default",
        "description": "",
        "yields": [
          {
            "name": "Item",
            "type": "component",
            "description": "",
            "remarks": "",
            "sourcePath": "./item/index.gts"
          }
        ]
      }
    ],
    "element": "HTMLDivElement",
    "splattributes": false
  }
}

🔗 External links

Jira ticket: HDS-6428

---

💬 Please consider using conventional comments when reviewing this PR.

📋 PCI review checklist

• If applicable, I've documented a plan to revert these changes if they require more than reverting the pull request.
• If applicable, I've worked with GRC to document the impact of any changes to security controls.
  Examples of changes to controls include access controls, encryption, logging, etc.
• If applicable, I've worked with GRC to ensure compliance due to a significant change to the in-scope PCI environment.
  Examples include changes to operating systems, ports, protocols, services, cryptography-related components, PII processing code, etc.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hds-showcase	Ready	Preview	Jun 12, 2026 6:55pm
hds-website	Ready	Preview	Jun 12, 2026 6:55pm

[didoo]

I think some of the proposed changes may lead to breaking changes

[didoo]

[issue/blocker?] could it be that this change of paths will result in breaking changes for the consumers? they will have to update all their import paths as well, for the signatures, right?

https://github.com/search?q=%2Ffrom+%27%40hashicorp%5C%2Fdesign-system-components%5C%2Fcomponents%5C%2Fhds%2F+user%3Ahashicorp+repo%3Ahashicorp%2Fcloud-admin&type=code&ref=advsearch

[zamoore]

Here is an RFC outlining this proposed work

https://ibm.sharepoint.com/:w:/r/sites/hermes/_layouts/15/Doc.aspx?sourcedoc=%7BBE8FDF59-8101-4B6C-B08D-4A8BA5D9975D%7D&file=DS-Canonical%20Component%20API%20Data%20for%20MCP.docx&action=default&mobileredirect=true