component-usage-analysis
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.
When & Why to Use This Skill
The Component Usage Analysis skill is a specialized developer tool designed for Drupal and Twig component libraries. It automates the detection of component dependencies and usage patterns, enabling developers to perform safe refactoring, audit property usage, and conduct impact analysis. By scanning Twig includes and mock references, it provides a comprehensive overview of how components interact, ensuring codebase stability during updates or removals.
Use Cases
- Safe Component Deletion: Verify if a component is truly unused by scanning all Twig templates and mock configurations before removal to prevent broken UI elements.
- Refactoring Impact Analysis: Predict which parts of the application will be affected when changing a component's data structure, property names, or Twig logic.
- Property Usage Auditing: Identify all parent components that pass specific properties (e.g., 'image_alt' or 'button_theme') to a child element to ensure consistent implementation.
- Dependency Mapping: Generate a clear report of how elements, patterns, and templates are nested within a complex Drupal library to understand architectural complexity.
- Mock Reference Verification: Ensure that component mocks and variants are correctly referencing existing components, maintaining the integrity of the design system's documentation.
| 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:
- Target component: Which component to analyse (e.g.,
elements/image) - Properties of interest: Specific properties to filter by (optional)
- 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:
- Note the file path (consuming component)
- Extract the
with {}block to identify which properties are passed - 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:
- Note the file path and variant name referenced
- Look up the referenced variant in the target's
mocks.yaml - 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:
Count total files:
find src/components -name "*.twig" | wc -l find src/components -name "mocks.yaml" | wc -lVerify search found expected files:
- Spot-check known usages
- Confirm count matches expectations
Check for alternative patterns:
- Embedded includes:
{% include "@elements/image/image.twig" %} - Variable includes:
{% include image_template %} - Embed blocks:
{% embed "@elements/image/image.twig" %}
- Embedded includes:
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?"
- Search for Twig includes passing
copyright - Search for mock references to variants with
copyright - Report which components would need updates
- Recommend: Update consumers first, then remove property
Scenario: Safe Component Removal
User: "Is elements/legacy-button used anywhere?"
- Search for Twig includes of the component
- Search for mock references
- Search for library references in templates
- If zero results across all searches → safe to remove
Scenario: Refactoring Impact
User: "I want to rename description to caption in elements/image"
- Find all usages passing
description - Provide list of files requiring updates
- 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