feat(): docs and cleanup

Author: Karnaukhov-kh

docs/component-refactoring-flow.md

@@ -234,12 +234,12 @@ 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`, `templateFile`, `styleFile`, `typescriptFile`, `dsComponentName`
   - Returns: updated contract path with refactored component state
   - Purpose: Capture final component state for comparison
 
 - `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,17 @@ 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, templateFile, styleFile, typescriptFile, 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)
+> - `templateFile`: Path to the component template file (.html or .ts for inline)
+> - `styleFile`: Path to the component style file (.scss, .css, etc.)
+> - `typescriptFile`: Path to the TypeScript component file (.ts)
+> - `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.
 
 ## When to Build a Contract
 
@@ -160,10 +166,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

@@ -566,7 +566,7 @@ 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`, `templateFile`, `styleFile`, `typescriptFile`, `dsComponentName`
   - Returns: JSON contract with public API, DOM structure, and styles
   - Purpose: Capture post-refactoring component state
 
@@ -576,9 +576,9 @@ This is your last chance to make changes before opening the pull request.
   - 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
 

docs/tools.md

@@ -113,20 +113,22 @@ This document provides comprehensive guidance for AI agents working with Angular
 **Purpose**: Creates static surface contracts for component templates and styles
 **AI Usage**: Generate contracts before refactoring to track breaking changes
 **Key Parameters**:
-- `directory`: Component directory
+- `saveLocation`: Path where to save the contract file (supports absolute and relative paths)
 - `templateFile`: Template file name (.html or .ts for inline)
 - `styleFile`: Style file name (.scss, .css, etc.)
 - `typescriptFile`: TypeScript component file (.ts)
+- `dsComponentName`: Optional design system component name
 **Output**: Component contract file with API surface
 **Best Practice**: Create contracts before major refactoring for comparison
 
 #### `diff_component_contract`
 **Purpose**: Compares before/after contracts to identify breaking changes
 **AI Usage**: Validate that refactoring doesn't introduce breaking changes
 **Key Parameters**:
-- `directory`: Component directory
+- `saveLocation`: Path where to save the diff result file (supports absolute and relative paths)
 - `contractBeforePath`: Path to pre-refactoring contract
 - `contractAfterPath`: Path to post-refactoring contract
+- `dsComponentName`: Optional design system component name
 **Output**: Diff analysis showing breaking changes
 **Best Practice**: Essential validation step after component modifications
 

packages/angular-mcp-server/src/lib/tools/ds/component-contract/builder/build-component-contract.tool.ts

@@ -43,13 +43,11 @@ export const buildComponentContractHandler = createHandler<
       effectiveTypescriptPath,
     );
 
-    // Custom save logic using the provided saveLocation
     const contractString = JSON.stringify(contract, null, 2);
     const hash = require('node:crypto').createHash('sha256').update(contractString).digest('hex');
 
     const effectiveSaveLocation = resolveCrossPlatformPath(cwd, saveLocation);
 
-    // Ensure directory exists
     const { mkdir, writeFile } = await import('node:fs/promises');
     const { dirname } = await import('node:path');
     await mkdir(dirname(effectiveSaveLocation), { recursive: true });

packages/angular-mcp-server/src/lib/tools/ds/component-contract/diff/diff-component-contract.tool.ts

@@ -58,13 +58,10 @@ export const diffComponentContractHandler = createHandler<
       summary: generateDiffSummary(processedResult, groupedChanges),
     };
 
-    // Normalize absolute paths to relative paths for portability
     const normalizedDiffData = normalizePathsInObject(diffData, workspaceRoot);
 
-    // Use the provided saveLocation
     const effectiveSaveLocation = resolveCrossPlatformPath(cwd, saveLocation);
 
-    // Ensure directory exists
     const { dirname } = await import('node:path');
     await mkdir(dirname(effectiveSaveLocation), { recursive: true });