|
| 1 | +# TypeSpec Customization Workflow |
| 2 | + |
| 3 | +The customization workflow is an AI-assisted process that applies TypeSpec decorators and code repairs to ensure SDK functionality. It uses a two-phase approach: **Phase A** applies `client.tsp` decorators (~80% of issues), **Phase B** applies code-level repairs when builds still fail (~10%), and the remaining ~10% receive manual guidance. |
| 4 | + |
| 5 | +## Entry Points |
| 6 | + |
| 7 | +The customization tool (`azure-sdk-mcp:azsdk_customized_code_update`) can be triggered from multiple sources: |
| 8 | + |
| 9 | +| Entry Point | Description | Example | |
| 10 | +|-------------|-------------|---------| |
| 11 | +| **Build failures** | Compilation errors, analyzer violations, linting failures after SDK generation | `error CS0246: The type or namespace name 'FooModel' could not be found` | |
| 12 | +| **Breaking changes** | Output from breaking changes analysis tools detecting renamed/removed properties, changed types | `Breaking changes detected: FooOptions.timeout property type changed from int to Duration` | |
| 13 | +| **User prompts** | Natural language requests to modify SDK behavior | "Rename FooClient to BarClient for .NET" | |
| 14 | +| **API review feedback** | Feedback from APIView or PR comments on SDK naming/structure | "Model name doesn't follow .NET casing conventions" | |
| 15 | +| **.NET analyzer errors** | AZC0030 (naming violations), AZC0012 (generic type names), etc. | `AZC0030: Model name ends with 'Parameters'` | |
| 16 | +| **Customization drift** | Existing customization code references renamed/removed TypeSpec entities | `cannot find symbol: method getField(String)` | |
| 17 | +| **Duplicate field conflicts** | TypeSpec adds a property that already exists in manual customization code | `variable operationId is already defined in class AnalyzeOperationDetails` | |
| 18 | + |
| 19 | +## When to Use |
| 20 | + |
| 21 | +- Build fails after `azure-sdk-mcp:azsdk_package_build_code` with compilation errors |
| 22 | +- Type name conflicts with reserved keywords or existing types |
| 23 | +- Breaking changes from spec updates (renamed/removed properties, changed types) |
| 24 | +- API surface changes that require `client.tsp` customizations |
| 25 | +- .NET analyzer violations (AZC0030, AZC0012, etc.) |
| 26 | +- Renaming clients, models, or operations for specific language SDKs |
| 27 | +- Hiding internal operations from public SDK APIs |
| 28 | +- Restructuring client architecture (e.g., creating subclients) |
| 29 | +- Customization files reference entities that no longer exist after TypeSpec regeneration |
| 30 | +- Duplicate fields between generated code and manual customization code |
| 31 | + |
| 32 | +## Customization Steps |
| 33 | + |
| 34 | +1. **Capture context** — Collect the build error output, user request, or API review feedback. |
| 35 | +2. **Apply customization** — Run `azure-sdk-mcp:azsdk_customized_code_update` with the error/request context. The tool handles the full workflow internally: |
| 36 | + - Classifies the request (TypeSpec fix, code patch, or manual guidance) |
| 37 | + - Applies `client.tsp` decorators (Phase A) |
| 38 | + - Regenerates the SDK automatically |
| 39 | + - Builds to validate |
| 40 | + - If build still fails and customization files exist, applies code patches (Phase B) |
| 41 | + - Regenerates again (Java) and rebuilds |
| 42 | +3. **Validate** — Run `azure-sdk-mcp:azsdk_package_run_check` and `azure-sdk-mcp:azsdk_package_run_tests` to verify no regressions. |
| 43 | +4. **Review changes** — The tool leaves all changes uncommitted. Review with `git status`/`git diff` across both repos. |
| 44 | + |
| 45 | +## Common Scenarios |
| 46 | + |
| 47 | +| Scenario | Phase | Customization | |
| 48 | +|----------|-------|--------------| |
| 49 | +| Type name conflict with reserved keyword | A | Rename via `@@clientName` in `client.tsp` | |
| 50 | +| Property renamed in new API version | A | Add `@@clientName` to preserve backward compatibility | |
| 51 | +| .NET analyzer error (AZC0030, AZC0012) | A | Apply scoped `@@clientName` decorators to fix naming violations | |
| 52 | +| Hide internal operation from SDK | A | Apply `@@access` decorator with language scope | |
| 53 | +| Create subclient architecture | A | Use `@client` and `@clientInitialization` decorators | |
| 54 | +| API review naming feedback | A | Apply scoped `@@clientName` for specific language | |
| 55 | +| Duplicate field from customization conflict | B | Remove duplicate `addField()` from customization class | |
| 56 | +| Customization references renamed property | B | Update references in `_patch.py`, `*Customization.java`, or partial classes | |
| 57 | +| Feature request with no TypeSpec solution | Manual | Tool provides guidance to create customization infrastructure | |
| 58 | + |
| 59 | +## Two-Phase Workflow |
| 60 | + |
| 61 | +**Phase A — TypeSpec Customizations:** |
| 62 | +Apply `client.tsp` decorators (e.g., `@@clientName`, `@@access`, `@client`), regenerate SDK, validate build. Handles ~80% of issues. |
| 63 | + |
| 64 | +**Phase B — Code Customizations:** |
| 65 | +Activates automatically when Phase A build fails AND customization files exist (Java: `*Customization.java`, Python: `*_patch.py`, .NET: partial classes). Applies mechanical code repairs: duplicate removal, reference updates, import fixes. Handles ~10% of issues. |
| 66 | + |
| 67 | +**Manual Guidance:** |
| 68 | +When neither phase resolves the issue, or no customization files exist, the tool returns structured guidance for manual implementation. |
| 69 | + |
| 70 | +## Retry Logic |
| 71 | + |
| 72 | +The tool handles retries internally with a two-pass classification approach: |
| 73 | +1. First pass: classify feedback → apply TypeSpec fixes → regenerate → build |
| 74 | +2. Second pass: re-classify remaining items with build error context → apply code patches → rebuild |
| 75 | +3. If the tool response indicates build still failing, you can re-run `azure-sdk-mcp:azsdk_customized_code_update` with the updated error output |
| 76 | +4. Max 2 attempts per phase (4 total iterations within the tool) |
0 commit comments