feat(angular-mcp-server): add violation grouping tool

README.md

@@ -186,7 +186,11 @@ my-angular-workspace/
 
 ### Component Analysis
 
-- **`report-violations`**: Report deprecated CSS usage in a directory with configurable grouping format
+- **`report-violations`**: Report deprecated CSS usage for a specific DS component in a directory. Supports optional file output with statistics (components, files, lines).
+
+- **`report-all-violations`**: Report all deprecated CSS usage across all DS components in a directory. Supports optional file output with statistics (components, files, lines).
+
+- **`group-violations`**: Creates balanced work distribution groups from violations reports using bin-packing algorithm. Maintains path exclusivity and directory boundaries for parallel development.
 
 - **`report-deprecated-css`**: Report deprecated CSS classes found in styling files
 

docs/tools.md

@@ -7,23 +7,29 @@ This document provides comprehensive guidance for AI agents working with Angular
 ### 🔍 Project Analysis Tools
 
 #### `report-violations`
-**Purpose**: Identifies deprecated DS CSS usage patterns in Angular projects
-**AI Usage**: Use as the first step in migration workflows to identify all violations before planning refactoring
+**Purpose**: Identifies deprecated DS CSS usage patterns for a specific DS component in Angular projects
+**AI Usage**: Use when you need to analyze violations for a specific component before planning refactoring
 **Key Parameters**:
 - `directory`: Target analysis directory (use relative paths like `./src/app`)
 - `componentName`: DS component class name (e.g., `DsButton`)
 - `groupBy`: `"file"` or `"folder"` for result organization
-**Output**: Structured violation reports grouped by file or folder
-**Best Practice**: Always run this before other migration tools to establish baseline
+- `saveAsFile`: Optional boolean - if `true`, saves report to `tmp/.angular-toolkit-mcp/violations-report/<componentName>/<directory>-violations.json`
+**Output**: 
+- Default: Structured violation reports grouped by file or folder
+- With `saveAsFile: true`: File path and statistics (components, files, lines)
+**Best Practice**: Use `saveAsFile: true` when you need to persist results for later processing or grouping workflows
 
 #### `report-all-violations`
 **Purpose**: Reports all deprecated DS CSS usage for every DS component within a directory
 **AI Usage**: Use for a fast, global inventory of violations across the codebase before narrowing to specific components
 **Key Parameters**:
 - `directory`: Target analysis directory (use relative paths like `./src/app`)
-- `groupBy`: `"file"` or `"folder"` for result organization (default: `"file"`)
-**Output**: Structured violation reports grouped by file or folder covering all DS components
-**Best Practice**: Use to discover all violations and establish the baseline for subsequent refactoring.
+- `groupBy`: `"component"` or `"file"` for result organization (default: `"component"`)
+- `saveAsFile`: Optional boolean - if `true`, saves report to `tmp/.angular-toolkit-mcp/violations-report/<directory>-violations.json`
+**Output**: 
+- Default: Structured violation reports grouped by component or file covering all DS components
+- With `saveAsFile: true`: File path and statistics (components, files, lines)
+**Best Practice**: Use `saveAsFile: true` to persist results for grouping workflows or large-scale migration planning. The saved file can be used as input for work distribution grouping tools.
 
 #### `get-project-dependencies`
 **Purpose**: Analyzes project structure, dependencies, and buildability
@@ -34,6 +40,21 @@ This document provides comprehensive guidance for AI agents working with Angular
 **Output**: Dependency analysis, buildable/publishable status, peer dependencies
 **Best Practice**: Use to understand project constraints before recommending changes
 
+#### `group-violations`
+**Purpose**: Creates balanced work distribution groups from violations reports for parallel development
+**AI Usage**: Use after `report-all-violations` to organize violations into balanced work groups for team distribution
+**Key Parameters**:
+- `fileName`: Name of violations JSON file in `tmp/.angular-toolkit-mcp/violations-report/` (e.g., `"packages-poker-core-lib-violations.json"`)
+- `minGroups`: Minimum number of groups (default: 3)
+- `maxGroups`: Maximum number of groups (default: 5)
+- `variance`: Acceptable variance percentage for balance (default: 20)
+**Output**: 
+- Work groups with balanced violation counts
+- Individual JSON and Markdown files per group
+- Metadata with validation results
+- Saved to `tmp/.angular-toolkit-mcp/violation-groups/<reportName>/`
+**Best Practice**: Use after saving violations with `saveAsFile: true`. The tool accepts both component-grouped and file-grouped reports. Groups maintain path exclusivity (each file in exactly one group) and preserve directory boundaries to enable parallel development without merge conflicts.
+
 #### `report-deprecated-css`
 **Purpose**: Scans styling files for deprecated CSS classes
 **AI Usage**: Complement violation reports with style-specific analysis
@@ -147,8 +168,9 @@ This document provides comprehensive guidance for AI agents working with Angular
 ### 1. Discovery & Analysis Workflow
 ```
 1. list-ds-components → Discover available DS components
-2. report-violations → Identify all violations
-3. get-project-dependencies → Analyze project structure
+2. report-all-violations (saveAsFile: true) → Identify all violations and save to file
+3. group-violations → Create balanced work distribution groups
+4. get-project-dependencies → Analyze project structure
 ```
 
 ### 2. Planning & Preparation Workflow

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

@@ -10,7 +10,7 @@ import { resolveCrossPlatformPath } from '../../shared/utils/cross-platform-path
 import { createHash } from 'node:crypto';
 
 interface BuildComponentContractOptions extends BaseHandlerOptions {
-  saveLocation: string;
+  saveLocation?: string;
   templateFile?: string;
   styleFile?: string;
   typescriptFile: string;
@@ -36,6 +36,18 @@ export const buildComponentContractHandler = createHandler<
       typescriptFile,
     );
 
+    // Generate default save location if not provided
+    const { join } = await import('node:path');
+    const { basename } = await import('node:path');
+    const defaultSaveLocation = saveLocation
+      ? saveLocation
+      : join(
+          'tmp',
+          '.angular-toolkit-mcp',
+          'contracts',
+          `${basename(typescriptFile, '.ts')}-contract.json`,
+        );
+
     // If templateFile or styleFile are not provided, use the TypeScript file path
     // This indicates inline template/styles
     const effectiveTemplatePath = templateFile
@@ -55,7 +67,10 @@ export const buildComponentContractHandler = createHandler<
     const contractString = JSON.stringify(contract, null, 2);
     const hash = createHash('sha256').update(contractString).digest('hex');
 
-    const effectiveSaveLocation = resolveCrossPlatformPath(cwd, saveLocation);
+    const effectiveSaveLocation = resolveCrossPlatformPath(
+      cwd,
+      defaultSaveLocation,
+    );
 
     const { mkdir, writeFile } = await import('node:fs/promises');
     const { dirname } = await import('node:path');

packages/angular-mcp-server/src/lib/tools/ds/component-contract/builder/models/schema.ts

@@ -14,7 +14,7 @@ export const buildComponentContractSchema: ToolSchemaOptions = {
       saveLocation: {
         type: 'string',
         description:
-          'Path where to save the contract file. Supports both absolute and relative paths.',
+          'Path where to save the contract file. Supports both absolute and relative paths. If not provided, defaults to tmp/.angular-toolkit-mcp/contracts/<component-name>-contract.json',
       },
       templateFile: {
         type: 'string',
@@ -37,7 +37,7 @@ export const buildComponentContractSchema: ToolSchemaOptions = {
         default: '',
       },
     },
-    required: ['saveLocation', 'typescriptFile'],
+    required: ['typescriptFile'],
   },
   annotations: {
     title: 'Build Component Contract',

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

@@ -18,7 +18,7 @@ import { writeFile, mkdir } from 'node:fs/promises';
 import diff from 'microdiff';
 
 interface DiffComponentContractOptions extends BaseHandlerOptions {
-  saveLocation: string;
+  saveLocation?: string;
   contractBeforePath: string;
   contractAfterPath: string;
   dsComponentName?: string;
@@ -46,6 +46,18 @@ export const diffComponentContractHandler = createHandler<
     );
     const effectiveAfterPath = resolveCrossPlatformPath(cwd, contractAfterPath);
 
+    // Generate default save location if not provided
+    const { join, basename } = await import('node:path');
+    const defaultSaveLocation = saveLocation
+      ? saveLocation
+      : join(
+          'tmp',
+          '.angular-toolkit-mcp',
+          'contracts',
+          'diffs',
+          `${basename(contractBeforePath, '-contract.json')}-diff.json`,
+        );
+
     const contractBefore = await loadContract(effectiveBeforePath);
     const contractAfter = await loadContract(effectiveAfterPath);
 
@@ -68,7 +80,10 @@ export const diffComponentContractHandler = createHandler<
 
     const normalizedDiffData = normalizePathsInObject(diffData, workspaceRoot);
 
-    const effectiveSaveLocation = resolveCrossPlatformPath(cwd, saveLocation);
+    const effectiveSaveLocation = resolveCrossPlatformPath(
+      cwd,
+      defaultSaveLocation,
+    );
 
     const { dirname } = await import('node:path');
     await mkdir(dirname(effectiveSaveLocation), { recursive: true });

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

@@ -14,7 +14,7 @@ export const diffComponentContractSchema: ToolSchemaOptions = {
       saveLocation: {
         type: 'string',
         description:
-          'Path where to save the diff result file. Supports both absolute and relative paths.',
+          'Path where to save the diff result file. Supports both absolute and relative paths. If not provided, defaults to tmp/.angular-toolkit-mcp/contracts/diffs/<component-name>-diff.json',
       },
       contractBeforePath: {
         type: 'string',
@@ -32,7 +32,7 @@ export const diffComponentContractSchema: ToolSchemaOptions = {
         default: '',
       },
     },
-    required: ['saveLocation', 'contractBeforePath', 'contractAfterPath'],
+    required: ['contractBeforePath', 'contractAfterPath'],
   },
   annotations: {
     title: 'Diff Component Contract',

packages/angular-mcp-server/src/lib/tools/ds/ds.tools.ts

@@ -9,6 +9,7 @@ import { join } from 'node:path';
 import {
   reportViolationsTools,
   reportAllViolationsTools,
+  groupViolationsTools,
 } from './report-violations/index.js';
 
 export const componentCoverageToolsSchema: ToolSchemaOptions = {
@@ -137,4 +138,5 @@ export const dsTools = [
   ...componentCoverageTools,
   ...reportViolationsTools,
   ...reportAllViolationsTools,
+  ...groupViolationsTools,
 ];