component-usage-analysis

# 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:** ```bash grep -rn "{% include \"@<tier>/<component>" src/components/ ``` **Example for `elements/image`:** ```bash 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: ```twig {% 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](references/search-patterns.md) for detailed patterns. ### Step 3: Mock Reference Analysis Find all components whose mocks reference the target component. **Search pattern:** ```bash grep -rn '\$ref: <tier>/<component>#' src/components/ ``` **Example for `elements/image`:** ```bash 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:** ```bash 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