Merge branch 'main' into feature/esm-migration

Author: Karnaukhov-kh

.cursor/flows/ds-refactoring-flow/01-find-violations.mdc

@@ -19,7 +19,10 @@ Step 1: Find violations
    Store the result in a variable called scanResult.
 
 2. Perform first-level error handling:
-   - If the function call returns an error, respond with:
+   - If the function call returns an error or result containing "Missing ds.deprecatedCssClassesPath", respond with:
+     <commentary>⚠️ *Cannot proceed: Missing required configuration parameter* – The `ds.deprecatedCssClassesPath` parameter must be provided when starting the MCP server to use violation detection tools. Please restart the server with this parameter configured.</commentary>
+     Then stop execution.
+   - If the function call returns any other error, respond with:
      <commentary>🚨 *Tool execution failed* – [error message]</commentary>
      Then stop execution.
    - If scanResult.totalViolations is 0, respond with:
@@ -57,7 +60,10 @@ Once the user provides a subfolder choice, proceed as follows:
    - Store the result in a variable called fileScan.
 
 3. Perform error handling and validation:
-   - If the function call returns an error, respond with:
+   - If the function call returns an error containing "Missing ds.deprecatedCssClassesPath", respond with:
+     <commentary>⚠️ *Cannot proceed: Missing required configuration parameter* – The `ds.deprecatedCssClassesPath` parameter must be provided when starting the MCP server to use violation detection tools. Please restart the server with this parameter configured.</commentary>
+     Then stop execution.
+   - If the function call returns any other error, respond with:
      <commentary>🚨 *Tool execution failed* – [error message]</commentary>
      Then stop execution.
    - If fileScan.rows.length is 0, respond with:

.cursor/flows/ds-refactoring-flow/01b-find-all-violations.mdc

@@ -17,7 +17,10 @@ Step 1: Find violations
    Store the result in a variable called scanResult.
 
 2. Perform first-level error handling:
-   - If the function call returns an error, respond with:
+   - If the function call returns an error or result containing "Missing ds.deprecatedCssClassesPath", respond with:
+     <commentary>⚠️ *Cannot proceed: Missing required configuration parameter* – The `ds.deprecatedCssClassesPath` parameter must be provided when starting the MCP server to use violation detection tools. Please restart the server with this parameter configured.</commentary>
+     Then stop execution.
+   - If the function call returns any other error, respond with:
      <commentary>🚨 *Tool execution failed* – [error message]</commentary>
      Then stop execution.
    - If no violations are found, respond with:
@@ -54,7 +57,10 @@ Once the user provides a subfolder choice, proceed as follows:
    - Store the result in a variable called fileScan.
 
 3. Perform error handling and validation:
-   - If the function call returns an error, respond with:
+   - If the function call returns an error containing "Missing ds.deprecatedCssClassesPath", respond with:
+     <commentary>⚠️ *Cannot proceed: Missing required configuration parameter* – The `ds.deprecatedCssClassesPath` parameter must be provided when starting the MCP server to use violation detection tools. Please restart the server with this parameter configured.</commentary>
+     Then stop execution.
+   - If the function call returns any other error, respond with:
      <commentary>🚨 *Tool execution failed* – [error message]</commentary>
      Then stop execution.
    - If fileScan.rows.length is 0, respond with:

README.md

@@ -9,7 +9,7 @@ A Model Context Protocol (MCP) server that provides Angular project analysis and
 - **Dependency Mapping**: Map component dependencies across modules, templates, and styles
 - **ESLint Integration**: Lint Angular files with automatic ESLint configuration discovery
 - **Project Analysis**: Analyze buildable/publishable libraries and validate import paths
-- **Component Documentation**: Retrieve component data and documentation
+- **Component Documentation**: Retrieve component data and documentation, list available components
 
 ## Use Cases
 
@@ -67,6 +67,8 @@ Copy `.cursor/mcp.json.example` to the project you're working on. Copied file sh
 }
 ```
 
+> Note: `ds.storybookDocsRoot` and `ds.deprecatedCssClassesPath` are optional. The server will start without them. Tools that require these paths will return a clear error prompting you to provide the missing parameter.
+
 > **Note**: The example file contains configuration for `ESLint` official MCP which is required for the toolkit to work properly.
 
 ### Configuration Parameters
@@ -76,10 +78,20 @@ Copy `.cursor/mcp.json.example` to the project you're working on. Copied file sh
 | Parameter | Type | Description | Example |
 |-----------|------|-------------|---------|
 | `workspaceRoot` | Absolute path | Root directory of your Angular workspace | `/Users/dev/my-angular-app` |
-| `ds.storybookDocsRoot` | Relative path | Root directory containing Storybook documentation | `storybook/docs` |
-| `ds.deprecatedCssClassesPath` | Relative path | JavaScript file mapping deprecated CSS classes | `design-system/component-options.js` |
 | `ds.uiRoot` | Relative path | Directory containing UI components | `packages/ui` |
 
+#### Optional Parameters
+
+| Parameter | Type | Description | Example |
+|-----------|------|-------------|---------|
+| `ds.storybookDocsRoot` | Relative path | Root directory containing Storybook documentation used by documentation-related tools | `storybook/docs` |
+| `ds.deprecatedCssClassesPath` | Relative path | JavaScript file mapping deprecated CSS classes used by violation and deprecated CSS tools | `design-system/component-options.js` |
+
+When optional parameters are omitted:
+
+- `ds.storybookDocsRoot`: Tools will skip Storybook documentation lookups (e.g., `get-ds-component-data` will still return implementation/import data but may have no docs files).
+- `ds.deprecatedCssClassesPath`: Tools that require the mapping will fail fast with a clear error. Affected tools include: `get-deprecated-css-classes`, `report-deprecated-css`, `report-all-violations`, and `report-violations`.
+
 #### Deprecated CSS Classes File Format
 
 The `component-options.js` file should export an array of component configurations:
@@ -135,10 +147,35 @@ my-angular-workspace/
 
 ### Component Analysis
 
+- **`list-ds-components`**: List all available Design System components in the project with their file paths and metadata
+
 - **`get-ds-component-data`**: Return data for a component including implementation files, documentation files, and import path
 
 - **`build-component-usage-graph`**: Maps where given Angular components are imported (modules, specs, templates, styles) so refactors touch every file
 
+### Tool behavior with optional parameters
+
+The following tools work without optional params:
+
+- `get-project-dependencies`
+- `build-component-usage-graph`
+- `get-ds-component-data` (documentation section is empty if `ds.storybookDocsRoot` is not set)
+- Component contract tools:
+  - `build_component_contract`
+  - `diff_component_contract`
+  - `list_component_contracts`
+
+The following tools require optional params to work:
+
+- Requires `ds.deprecatedCssClassesPath`:
+  - `get-deprecated-css-classes`
+  - `report-deprecated-css`
+  - `report-all-violations`
+  - `report-violations`
+
+- Requires `ds.storybookDocsRoot` for docs lookup (skipped otherwise):
+  - `get-ds-component-data` (docs files discovery only)
+
 ### Component Contracts
 
 - **`build_component_contract`**: Generate a static surface contract for a component's template and SCSS

docs/component-refactoring-flow.md

@@ -9,7 +9,7 @@ This document describes a 3-step AI-assisted component refactoring process for i
 2. **Refactor Component** → Execute approved checklist items and implement changes
 3. **Validate Component** → Verify improvements through contract comparison and scoring
 
-The process includes two quality gates where human review and approval are required.
+The process includes two quality gates where human review and approval are required. When refactoring involves Design System components, the process can leverage selective data retrieval to access only the specific component information needed (implementation, documentation, or stories).
 
 ## Prerequisites
 
@@ -155,9 +155,15 @@ At this point, all checklist items have been processed. You must review the refa
 ### Tools used
 
 - `build_component_contract` - Creates component contracts for safe refactoring
-  - Parameters: `componentFile`, `dsComponentName` (set to "AUTO")
+  - Parameters: `saveLocation`, `typescriptFile` (required), `templateFile` (optional), `styleFile` (optional), `dsComponentName` (optional, set to "AUTO")
   - Returns: contract path with component's public API, DOM structure, and styles
   - Purpose: Establish baseline for validation comparison
+  - Note: Template and style files are optional for components with inline templates/styles
+
+- `get-ds-component-data` - Retrieves Design System component information when needed
+  - Parameters: `componentName`, `sections` (optional) - Array of sections to include: "implementation", "documentation", "stories", "all"
+  - Returns: Selective component data based on refactoring needs
+  - Purpose: Access DS component documentation and examples for proper implementation patterns
 
 ### Flow
 
@@ -229,12 +235,13 @@ The rule implements a comprehensive validation process:
 ### Tools used
 
 - `build_component_contract` - Creates post-refactor component contract
-  - Parameters: `componentFile`, `dsComponentName` (set to "AUTO")
+  - Parameters: `saveLocation`, `typescriptFile` (required), `templateFile` (optional), `styleFile` (optional), `dsComponentName` (optional)
   - Returns: updated contract path with refactored component state
   - Purpose: Capture final component state for comparison
+  - Note: Template and style files are optional for components with inline templates/styles
 
 - `diff_component_contract` - Compares baseline and updated contracts
-  - Parameters: `contractBeforePath`, `contractAfterPath`, `dsComponentName` (set to "AUTO")
+  - Parameters: `saveLocation`, `contractBeforePath`, `contractAfterPath`, `dsComponentName`
   - Returns: detailed diff analysis showing specific changes
   - Purpose: Identify and analyze all modifications made during refactoring
 

docs/contracts.md

@@ -65,11 +65,19 @@ Because contracts track every public-facing facet of a component, any refactor t
 Rules taking care about the contract building during the workflow, but if you need to build it "manually" say in the chat:
 
 ```
-build_component_contract(<component-file.ts>, dsComponentName)
+build_component_contract(saveLocation, typescriptFile, templateFile?, styleFile?, dsComponentName?)
 ``` 
 
-> Replace `<component-file.ts>` with the path to your component and set `dsComponentName` to the design-system component (e.g., `DsBadge`). The tool analyses the template, TypeScript, and styles, then saves a timestamped `*.contract.json` to  
-> `.cursor/tmp/contracts/<ds-component-kebab>/`.
+> Replace the parameters with:
+> - `saveLocation`: Path where to save the contract file (supports absolute and relative paths)
+> - `typescriptFile`: Path to the TypeScript component file (.ts) — **Required**
+> - `templateFile`: *(Optional)* Path to the component template file (.html). Omit for inline templates
+> - `styleFile`: *(Optional)* Path to the component style file (.scss, .css, etc.). Omit for inline styles or components without styles
+> - `dsComponentName`: *(Optional)* Design system component name (e.g., `DsBadge`)
+> 
+> The tool analyses the template, TypeScript, and styles, then saves the contract to your specified location.
+> 
+> **Note**: Angular components can have inline templates and styles. If `templateFile` or `styleFile` are not provided, the tool will extract inline template/styles from the TypeScript file.
 
 ## When to Build a Contract
 
@@ -160,10 +168,13 @@ What happens when QA finds a bug or a reviewer requests changes **after** the in
 3. **Locate the original baseline contract** – this is the contract that was captured for the initial state (usually the very first timestamp in the folder).
 4. **Generate a diff** between the baseline and the latest contract:
    ```
-   User: diff_component_contract(<baseline>.contract.json, <latest>.contract.json, dsComponentName)
+   User: diff_component_contract(saveLocation, contractBeforePath, contractAfterPath, dsComponentName)
    ```
-   The diff file will land under
-   `.cursor/tmp/contracts/<ds-component-kebab>/diffs/`.
+   > Replace the parameters with:
+   > - `saveLocation`: Path where to save the diff result file (supports absolute and relative paths)
+   > - `contractBeforePath`: Path to the baseline contract file
+   > - `contractAfterPath`: Path to the latest contract file
+   > - `dsComponentName`: Optional design system component name
 5. **Review the diff output using AI** – attach the diff and ask it to analyze it.
    * If only intentional changes appear, proceed to merge / re-test.
    * If unexpected API, DOM, or style changes surface, iterate on the fix and repeat steps 1-4.

docs/ds-refactoring-flow.md

@@ -199,7 +199,13 @@ Before proceeding to Phase 3, you must review the comprehensive migration plan.
 
 ### Tools used
 
+- `list-ds-components` - Lists all available Design System components in the project
+  - Parameters: `sections` (optional) - Array of sections to include: "implementation", "documentation", "stories", "all"
+  - Returns: Complete inventory of DS components with their file paths and metadata
+  - Provides: Overview of available components for comprehensive migration planning
+
 - `get-ds-component-data` - Retrieves comprehensive component information for all involved components
+  - Parameters: `componentName`, `sections` (optional) - Array of sections to include: "implementation", "documentation", "stories", "all"
   - Returns: Complete implementation files, documentation files, import paths for multiple components
   - Provides: Component source code, API documentation, usage examples across scope
 
@@ -285,7 +291,13 @@ Before proceeding to Phase 3, you must review the migration plan.
 
 ### Tools used
 
+- `list-ds-components` - Lists all available Design System components in the project
+  - Parameters: `sections` (optional) - Array of sections to include: "implementation", "documentation", "stories", "all"
+  - Returns: Complete inventory of DS components with their file paths and metadata
+  - Provides: Overview of available components for migration planning
+
 - `get-ds-component-data` - Retrieves comprehensive component information
+  - Parameters: `componentName`, `sections` (optional) - Array of sections to include: "implementation", "documentation", "stories", "all"
   - Returns: implementation files, documentation files, import paths
   - Provides: component source code, API documentation, usage examples
 
@@ -467,9 +479,10 @@ At this point, initial refactoring is complete.
 ### Tools used
 
 - `build_component_contract` - Creates component contracts for safe refactoring
-  - Parameters: `directory`, `templateFile`, `styleFile`, `typescriptFile`, `dsComponentName`
+  - Parameters: `saveLocation`, `typescriptFile` (required), `templateFile` (optional), `styleFile` (optional), `dsComponentName` (optional)
   - Returns: contract with public API, DOM structure, styles, and metadata
   - Generates: JSON contract files with SHA-256 hashes for validation
+  - Note: Template and style files are optional—extracts inline templates/styles from TypeScript when not provided
 
 ### Flow
 
@@ -554,19 +567,20 @@ This is your last chance to make changes before opening the pull request.
   - Features: Automatic ESLint config resolution, comprehensive rule coverage
 
 - `build_component_contract` - Creates contracts for refactored components
-  - Parameters: `directory`, `templateFile`, `styleFile`, `typescriptFile`, `dsComponentName`
+  - Parameters: `saveLocation`, `typescriptFile` (required), `templateFile` (optional), `styleFile` (optional), `dsComponentName` (optional)
   - Returns: JSON contract with public API, DOM structure, and styles
   - Purpose: Capture post-refactoring component state
+  - Note: Template and style files are optional for components with inline templates/styles
 
 - `list_component_contracts` - Lists available component contracts
   - Parameters: `directory`
   - Returns: Available contract files with timestamps and metadata
   - Purpose: Identify before/after contract pairs for comparison
 
 - `diff_component_contract` - Compares component contracts
-  - Parameters: `directory`, `contractBeforePath`, `contractAfterPath`, `dsComponentName`
+  - Parameters: `saveLocation`, `contractBeforePath`, `contractAfterPath`, `dsComponentName`
   - Returns: Detailed diff highlighting changes in API, DOM, and styles
-  - Saves: Diff files to `.cursor/tmp/contracts/<component>/diffs/`
+  - Saves: Diff files to the specified saveLocation path
 
 ### Flow