component-usage-analysis

name	component-usage-analysis
description	Analyse component dependencies and usage patterns in a Drupal/Twig component library. Use when user asks to find where a component is used, check if a component can be safely removed, audit component dependencies, find components using specific properties, or analyse impact of refactoring a component.

Component Usage Analysis

Analyse component dependencies and usage patterns to support safe refactoring and removal.

Trigger Phrases

• "Find all usages of <component>"
• "Which components use <component>?"
• "Check if <component> can be safely removed"
• "Find components using <component> with property X"
• "Audit dependencies for <component>"
• "What would break if I change <component>?"

Configuration

This skill assumes the component library structure:

apps/component-library/
├── src/components/
│   ├── elements/
│   ├── patterns/
│   ├── template-components/
│   └── templates/

Analysis Methodology

Step 1: Identify the Target

Clarify with the user:

1. Target component: Which component to analyse (e.g., elements/image)
2. Properties of interest: Specific properties to filter by (optional)
3. Analysis goal: Usage audit, removal check, or refactoring impact

Step 2: Twig Include Analysis

Find all components that include the target via Twig.

Search pattern:

grep -rn "{% include \"@<tier>/<component>" src/components/

Example for elements/image:

grep -rn '{% include "@elements/image' src/components/

For each match:

1. Note the file path (consuming component)
2. Extract the with {} block to identify which properties are passed
3. Record whether target properties are present

Extracting the with block:

Twig includes may span multiple lines:

{% include "@elements/image/image.twig" with {
    src: item.image.src,
    alt: item.image.alt,
    description: item.image.description
} %}

Use multi-line search or examine files directly when the with block is complex.

See references/search-patterns.md for detailed patterns.

Step 3: Mock Reference Analysis

Find all components whose mocks reference the target component.

Search pattern:

grep -rn '\$ref: <tier>/<component>#' src/components/

Example for elements/image:

grep -rn '\$ref: elements/image#' src/components/

For each match:

1. Note the file path and variant name referenced
2. Look up the referenced variant in the target's mocks.yaml
3. Check if the variant includes the properties of interest

Cross-referencing variants:

If a mock uses $ref: elements/image#with-caption, check elements/image/mocks.yaml to see what properties that variant defines.

Step 4: Categorise Results

Group findings into categories based on the analysis goal:

For property-specific analysis:

• Uses WITH property X: Components that pass/use the property
• Uses WITHOUT property X: Components that use the target but don't use property X

For removal analysis:

• Direct Twig includes: Would break immediately
• Mock references only: May need mock updates but won't break rendering
• No dependencies: Safe to remove

For refactoring analysis:

• Affected by change: Components using the property/feature being changed
• Unaffected: Components using the target but not the changed aspect

Step 5: Verification

Ensure comprehensive coverage before reporting:

1. Count total files:

   find src/components -name "*.twig" | wc -l
   find src/components -name "mocks.yaml" | wc -l
   

2. Verify search found expected files:

   • Spot-check known usages
   • Confirm count matches expectations

3. Check for alternative patterns:

   • Embedded includes: {% include "@elements/image/image.twig" %}
   • Variable includes: {% include image_template %}
   • Embed blocks: {% embed "@elements/image/image.twig" %}

4. Report confidence level:

   • High: All patterns checked, counts verified
   • Medium: Primary patterns checked
   • Low: Quick scan only

Output Format

Provide results in a clear structure:

## Component Usage Analysis: <component>

### Summary
- Total usages found: X
- Twig includes: Y
- Mock references: Z

### Uses WITH <property>
1. `patterns/card/card.twig` - passes description in with block
2. `patterns/teaser/mocks.yaml` - references variant with description

### Uses WITHOUT <property>
1. `patterns/hero/hero.twig` - only passes src, alt
2. `template-components/header/mocks.yaml` - references minimal variant

### Verification
- Searched X .twig files
- Searched Y mocks.yaml files
- Confidence: High

Common Scenarios

Scenario: Removing a Property

User: "Can I remove the copyright property from elements/image?"

1. Search for Twig includes passing copyright
2. Search for mock references to variants with copyright
3. Report which components would need updates
4. Recommend: Update consumers first, then remove property

Scenario: Safe Component Removal

User: "Is elements/legacy-button used anywhere?"

1. Search for Twig includes of the component
2. Search for mock references
3. Search for library references in templates
4. If zero results across all searches → safe to remove

Scenario: Refactoring Impact

User: "I want to rename description to caption in elements/image"

1. Find all usages passing description
2. Provide list of files requiring updates
3. Estimate scope of change

Notes

• Always verify comprehensively before recommending removal
• Check both Twig files AND mocks.yaml files
• Consider indirect dependencies (component A uses B which uses C)
• Report confidence level with results