bug: template header spec (summary/usage/note) in README is unimplemented #157

Bug summary

The README documents a "Template Header Spec" letting authors annotate a template file with # @gitlab-component-helper: summary: …, usage:, and note: keyed comments (with # @gch: … as a short alias), promising that the Component Browser will surface those values in a Context section. None of this is implemented. The marker strings @gitlab-component-helper and @gch appear nowhere in the source tree outside the README itself, and no code path populates summary / usage / notes from a template file's header comments — catalog or local.

The plain top-of-file # some description comment fallback exists for the catalog path only and is not invoked for local: includes, which always show a literal Local include: \`` description regardless of any comments in the file.

Net effect: a user-facing feature described in the README does nothing for any template, and the local-include path has no header-comment surfacing at all.

Steps to reproduce

1. In a component-catalog project (one configured under gitlabComponentHelper.componentSources), create a template at templates/push-helm.yml with a header following the README spec:

   # @gitlab-component-helper: summary: Push a Helm chart to Sonic
   # @gitlab-component-helper: usage: include + set SONIC_TARGET_* variables
   # @gitlab-component-helper: note: Requires a protected ref for publish
   spec:
     inputs:
       chart_name: {}
   ---
   push-chart:
     script: echo "$[[ inputs.chart_name ]]"

2. Commit, push, and tag a release (e.g. 1.0.0) so the component is resolvable by the extension.

3. In a consumer .gitlab-ci.yml in a different workspace, reference the component:

   include:
     - component: $CI_SERVER_FQDN/my-group/my-components/push-helm@1.0.0

4. Hover the component: line, or open the Component Browser and select the component. Confirm the Context section (summary / usage / notes) does not render.

5. Repeat step 1 substituting the short-form marker (# @gch: summary: …).

6. Repeat step 1 substituting a plain top-of-file comment (# Push a Helm chart to Sonic).

7. Repeat the whole exercise with a local: include against a workspace template using the same header forms.

Expected behavior

Per the README, the Component Browser's Context section should display the parsed summary, usage, and notes values for any template whose header follows the spec. For local includes specifically (since they're documented as supported in the same way as catalog components elsewhere in the README), the same Context section should appear.

A plain leading # comment should at least surface as a description for local templates too, since it already does for the catalog path.

Actual behavior

• The strings @gitlab-component-helper and @gch are not referenced anywhere in src/. The marker tokens exist only in README.md:95-104.
• src/parsers/specParser.ts:65-71 — the only header-comment reader — extracts a single plain # comment as description, and explicitly excludes any comment containing "gitlab" or "ci". A # @gitlab-component-helper: summary: … line therefore fails the .includes('gitlab') filter and is silently dropped.
• The parser's output type ParsedSpec has only description / variables / isValidComponent — no summary, usage, or notes fields.
• ParsedCatalogComponent declares optional summary? / usage? / notes? / rawYaml? fields, but no code path writes them. The catalog fetchers (componentFetcher.ts, componentFetcherTemplates.ts, componentService.ts) never reference these field names.
• The catalog-fetched branch in src/providers/componentDetector.ts:619-621 and extension.ts:386-389 reads foundComponent.summary / .usage / .notes and propagates them onward — but the upstream object never had those fields populated, so the reads always resolve to undefined.
• The local-include path src/providers/localComponentResolver.ts:203-211 hardcodes description: \Local include: `${localPath}``and constructs nosummary/usage/notesat all. It never callsGitLabSpecParser.parse`, so even the plain-comment description fallback that exists for the catalog path doesn't run for local includes.
• The Component Browser HTML at componentBrowserProvider.ts:1394-1397 reads component.summary / component.usage / component.notes to decide whether to render the Context section, but hasContext resolves to false in practice because every upstream code path leaves those fields undefined.

Component context (if applicable)

Affects any template that follows the documented header spec — catalog or local — regardless of GitLab instance or component source.

Minimal .gitlab-ci.yml snippet

# @gitlab-component-helper: summary: Push a Helm chart to Sonic
# @gitlab-component-helper: usage: include + set SONIC_TARGET_* variables
# @gitlab-component-helper: note: Requires a protected ref for publish
spec:
  inputs:
    chart_name: {}
---
push-chart:
  script: echo "$[[ inputs.chart_name ]]"

Extension logs

N/A

Affected area

Other

Extension version

0.11.14

VS Code version

1.120.x

Node.js version

22.x

Operating system

macOS

Pre-submit checks

• I searched existing issues and did not find a duplicate.
• I can reproduce this on the latest version from main/beta.
• I included a minimal YAML snippet and relevant logs.