diff --git a/README.md b/README.md index 54697be..e967f31 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # GitHub Copilot modernization - Copilot CLI Plugin +[![Listed in Awesome Copilot](https://img.shields.io/badge/Listed_in-Awesome_Copilot-blue?logo=github)](https://awesome-copilot.github.com/plugins/#file=plugins%2Fgithub-copilot-modernization) + Autonomous application modernization using multi-agent orchestration for [GitHub Copilot CLI](https://github.com/github/copilot-cli). ## Overview diff --git a/plugins/github-copilot-modernization/README.md b/plugins/github-copilot-modernization/README.md index 54697be..e967f31 100644 --- a/plugins/github-copilot-modernization/README.md +++ b/plugins/github-copilot-modernization/README.md @@ -1,5 +1,7 @@ # GitHub Copilot modernization - Copilot CLI Plugin +[![Listed in Awesome Copilot](https://img.shields.io/badge/Listed_in-Awesome_Copilot-blue?logo=github)](https://awesome-copilot.github.com/plugins/#file=plugins%2Fgithub-copilot-modernization) + Autonomous application modernization using multi-agent orchestration for [GitHub Copilot CLI](https://github.com/github/copilot-cli). ## Overview diff --git a/plugins/github-copilot-modernization/agents/assessment-coordinator.agent.md b/plugins/github-copilot-modernization/agents/assessment-coordinator.agent.md index 13ba9fa..01c23d7 100644 --- a/plugins/github-copilot-modernization/agents/assessment-coordinator.agent.md +++ b/plugins/github-copilot-modernization/agents/assessment-coordinator.agent.md @@ -37,6 +37,7 @@ You coordinate the assessment phase by detecting the project language, invoking - `enableContainerization`: boolean - `targetOS`: Array of `windows` | `linux` - `minimumCveSeverity`: `low` | `medium` | `high` | `critical` + - `cveScanScope`: `direct` | `all` ## Language Detection diff --git a/plugins/github-copilot-modernization/agents/execution-coordinator.agent.md b/plugins/github-copilot-modernization/agents/execution-coordinator.agent.md index f02142e..e8ec6d8 100644 --- a/plugins/github-copilot-modernization/agents/execution-coordinator.agent.md +++ b/plugins/github-copilot-modernization/agents/execution-coordinator.agent.md @@ -60,6 +60,8 @@ When a worker agent returns (success OR failure): - `modernize-azure-java` - For Azure Service Bus, SQL, Redis, Key Vault, and other Azure migrations - `modernize-java-security` - For CVE fixes and vulnerability scanning in Java/Maven (in-place fixes only, NOT Azure service integrations) - `modernize-azure-dotnet` - For .NET Azure migrations and CVE fixes in NuGet +- `modernize-deployment` - For infrastructure and deployment tasks: Dockerfiles, Kubernetes/AKS/ACA, Bicep/IaC, CI/CD pipelines +- `modernize-azure-integration-tester` - For setupBaseline and integrationTest plan tasks - `modernize-rearchitecture` - For structural rewrites and rearchitecture (only when task does not match any known scenario) ## Delegation Workflow @@ -82,16 +84,16 @@ When a worker agent returns (success OR failure): │ • Deprecated API migration │ │ • Application Insights │ │ • Maven security plugin │ │ • Maven / Gradle config │ │ • Managed Identity │ │ • Jackson / Log4j CVE fix │ └──────────────────────────────┘ └──────────────────────────────┘ └──────────────────────────────┘ -┌──────────────────────────────┐ ┌──────────────────────────────┐ -│ modernize-azure-dotnet │ │ modernize-rearchitecture │ -│ │ │ │ -│ • .NET Azure migration │ │ • Structural rewrites when │ -│ • NuGet CVE vulnerability │ │ no known scenario matches │ -│ • ASP.NET to Azure │ │ • WinForms → React/Angular │ -│ • dotnet build / test │ │ • Monolith → Microservices │ -│ • .NET CVE advisory check │ │ • JSP → Modern SPA │ -│ • NuGet security audit │ │ • Module extraction (new dir)│ -└──────────────────────────────┘ └──────────────────────────────┘ +┌──────────────────────────────┐ ┌──────────────────────────────┐ ┌──────────────────────────────┐ +│ modernize-azure-dotnet │ │ modernize-deployment │ │ modernize-rearchitecture │ +│ │ │ │ │ │ +│ • .NET Azure migration │ │ • Dockerfile generation │ │ • Structural rewrites when │ +│ • NuGet CVE vulnerability │ │ • AKS/ACA deployment │ │ no known scenario matches │ +│ • ASP.NET to Azure │ │ • Bicep/ARM IaC generation │ │ • WinForms → React/Angular │ +│ • dotnet build / test │ │ • CI/CD pipeline generation │ │ • Monolith → Microservices │ +│ • .NET CVE advisory check │ │ • Docker Image Scanning │ │ • JSP → Modern SPA │ +│ • NuGet security audit │ │ • Region/SKU/Pricing checks │ │ • Module extraction (new dir)│ +└──────────────────────────────┘ └──────────────────────────────┘ └──────────────────────────────┘ ``` **How to delegate:** @@ -139,6 +141,8 @@ You have access to specialized migration agents for application modernization: - **modernize-azure-java**: Azure Service Bus, Azure SQL, Azure Redis, Azure Key Vault, and other Azure service migrations - **modernize-java-security**: CVE vulnerability scanning and fixes in Java/Maven dependencies (in-place fixes only) - **modernize-azure-dotnet**: .NET Azure migrations and CVE fixes in NuGet dependencies +- **modernize-deployment**: Infrastructure and deployment tasks (Dockerfiles, Kubernetes/AKS/ACA, Bicep/IaC, CI/CD pipelines) +- **modernize-azure-integration-tester**: Java setupBaseline and integrationTest plan tasks - **modernize-rearchitecture**: Structural rewrites only when the task does not match any known scenario These agents query the MCP knowledge base directly for migration patterns and best practices. @@ -295,25 +299,12 @@ Before delegating tasks, check if a rulebook exists and pass its context to all **You create ONE branch before delegating, and pass it to ALL workers. You do NOT generate or pass session IDs — workers handle their own session IDs.** -1. Generate timestamp with **second-level precision**: `YYYYMMDDHHMMSS` (e.g., `20260424153045`). This MUST include hours, minutes, AND seconds — never truncate to just the date or hour. - - **DO NOT guess the time.** Run a terminal command to get the real current time: - - PowerShell: `Get-Date -Format "yyyyMMddHHmmss"` - - Bash/Linux: `date +"%Y%m%d%H%M%S"` - - Use the exact output as the timestamp. Never fabricate a round number like `120000`. -2. Branch name depends on detected language: - - Java projects: `modernize/java-` - - .NET projects: `modernize/dotnet-` -3. **Handle uncommitted changes BEFORE creating the branch:** - - First, retrieve the policy: Try calling `appmod-get-vscode-config(configName: "uncommittedChangesAction")` to get the user's configured policy. If the tool is not available (e.g., in CLI mode), default to **"Always Stash"**. - - Use `appmod-version-control(action: "checkForUncommittedChanges", workspacePath: )` to check - - If uncommitted changes exist, handle them according to the retrieved policy: - - **Always Stash** (default): Use `appmod-version-control(action: "stashChanges", stashMessage: "Auto-stash: Save uncommitted changes before migration", workspacePath: )` - - **Always Commit**: Use `appmod-version-control(action: "commitChanges", commitMessage: "Auto-commit: Save uncommitted changes before migration", workspacePath: )` - - **Always Discard**: Use `appmod-version-control(action: "discardChanges", workspacePath: )` - - **Always Ask**: Inform the user about the uncommitted changes and ask how they would like to proceed (stash, commit, or discard). Wait for the user's response before taking action. - - Verify clean: Use `appmod-version-control(action: "checkForUncommittedChanges", workspacePath: )` to confirm working directory is clean -4. Create the branch via `appmod-version-control(action: "createBranch", branchName: "modernize/-", workspacePath: )` -5. Pass `BRANCH: modernize/-` in every delegation prompt +1. Detect project language (from `tasks.json` metadata or project indicators): `java` or `dotnet`. +2. **Handle uncommitted changes and create branch with a single call**: + `appmod-version-control(action: "prepareBranch", language: "java"|"dotnet", workspacePath: )` + The tool handles any uncommitted changes, auto-generates the branch name (`modernize/-`), and returns it in `details.branchName`. + - **Handle the response**: the call handles any uncommitted changes automatically per the host-configured policy and creates the branch. Use `details.branchName` as `BRANCH` for all delegation prompts. +3. Pass the resulting `BRANCH` value in every delegation prompt. **Workers MUST NOT handle uncommitted changes** — this is already done here before branch creation. @@ -324,12 +315,8 @@ Workers use the provided branch (skipping their own branch creation) but generat ### Mode 1: Planned Execution (planning-path provided) 1. **Create Branch** - - Generate timestamp by running a terminal command (do NOT guess): - - PowerShell: `Get-Date -Format "yyyyMMddHHmmss"` - - Bash/Linux: `date +"%Y%m%d%H%M%S"` - Detect language from `tasks.json` metadata or project indicators - - **Handle uncommitted changes** (per Branching Strategy step 3): try `appmod-get-vscode-config` for policy (default: Always Stash) → check → handle per policy → verify clean - - Create branch: `modernize/java-` (Java) or `modernize/dotnet-` (.NET) + - **Handle uncommitted changes and create branch** (per Branching Strategy step 2): call `appmod-version-control(action: "prepareBranch", language: ..., workspacePath: ...)` once. The tool resolves the host's uncommitted-changes policy automatically, handles any uncommitted changes, and returns the auto-generated branch name in `details.branchName`. - **Do NOT generate or pass a session ID.** Each worker generates its own. 2. **Load Plan** @@ -341,7 +328,7 @@ Workers use the provided branch (skipping their own branch creation) but generat 4. **Delegate Task Execution (LANGUAGE & DOMAIN-BASED)** **Language Detection Rule:** Check `tasks.json` → `metadata.language` field: - - `"java"` → Route to Java agents (modernize-java-upgrade, modernize-azure-java, or modernize-java-security) + - `"java"` → Route Java upgrade, migration, security, and integration test plan tasks to the appropriate Java agents. - `"dotnet"` → Route ALL tasks to `modernize-azure-dotnet` **ALL tasks must be delegated. Group related tasks to minimize delegations:** @@ -368,6 +355,56 @@ Workers use the provided branch (skipping their own branch creation) but generat **Remaining Tasks** (config fixes, Dockerfile, passwordless auth, etc.): - Bundle small remaining tasks into ONE delegation to `modernize-azure-java` as the fallback agent + **Integration Testing Plan Tasks**: + - Applies to Java plans that contain `setupBaseline` or `integrationTest` tasks. + - `setupBaseline` → ONE delegation to `modernize-azure-integration-tester` as an independent baseline task. + - `integrationTest` → ONE delegation to `modernize-azure-integration-tester` after all declared dependencies complete. + - These task types are owned by `modernize-azure-integration-tester`. + - The tester agent delegates setup baseline work to `create-test-baseline` and verification work to `verify-test-baseline`. + - For `setupBaseline`, include the snapshot contract in the delegation prompt: snapshot source to a temp location before analysis, build the baseline from the snapshot, then copy only frozen baseline artifacts back to the live project's `/test-cases/` folder. + - For both IT task types, require `.metadata/summary.json` updates using `skills/create-modernization-plan/summary-schema.json` and keep `goalStatus` out of `tasks.json`. + + **Example - Setup Baseline:** + + Delegate to `modernize-azure-integration-tester` subagent with prompt: + ``` + Execute setupBaseline task. + Call skill create-test-baseline to set up the frozen behavior baseline before any modernization changes. + This task may run in parallel with transform/upgrade tasks. Before analyzing the application, snapshot the project source folder to a temporary location. Build the baseline from that snapshot, not from the live workspace. Copy only the frozen baseline artifacts back to the live project's /test-cases/ folder. If snapshot creation fails, stop and mark/report this task as failed; do not build a baseline from the live workspace. + + TaskId: 000-setupBaseline + TaskType: setupBaseline + Description: Capture the pre-modernization behavior baseline. + Requirements: Create a test-cases.md baseline for the requested integration tests. + BRANCH: modernize/java- + Workspace: /path/to/app + Plan path: .github/modernize//plan.md + modernization-work-folder: .github/modernize/ + Summary contract: update .github/modernize//.metadata/tasks.json with task status and taskSummary. Append/update .github/modernize//.metadata/summary.json using skills/create-modernization-plan/summary-schema.json with id, type "setupBaseline", goalStatus.totalTestCases, passed, failed, allCasesPassed when known, testCasesFile, plus risks and followUps arrays. Do not put goalStatus in tasks.json. + The coordinator has already created and checked out this branch — you are already on it. Do not create or switch branches yourself; commit directly on the current HEAD. + ``` + + **Example - Integration Test:** + + Delegate to `modernize-azure-integration-tester` subagent with prompt: + ``` + Execute integrationTest task. + Call skill verify-test-baseline to rerun the frozen baseline against the new implementation and generate integration tests from that baseline. + Verify all declared dependencies have completed before generating integration tests. Use the frozen /test-cases/ artifacts as the source of truth. Do not regenerate or amend the baseline unless the verify-test-baseline re-freeze cycle explicitly requires it. Mark success only after the generated *PostMigrationIT tests actually run with non-zero execution evidence and pass. + + TaskId: 005-integrationTest + TaskType: integrationTest + Description: Verify the completed migration with integration tests. + Requirements: Reuse the frozen baseline and generate integration tests for the migrated implementation. + BRANCH: modernize/java- + Workspace: /path/to/app + Plan path: .github/modernize//plan.md + modernization-work-folder: .github/modernize/ + Summary contract: update .github/modernize//.metadata/tasks.json with task status and taskSummary. Append/update .github/modernize//.metadata/summary.json using skills/create-modernization-plan/summary-schema.json with id, type "integrationTest", goalStatus.totalTestCases, passed, failed, testCasesFile, plus risks and followUps arrays. Do not put goalStatus in tasks.json. + Infra blocker handling: use .github/modernize/env.md or ./infra/infra-config.md first. If real-resource connection info or infra/auth repair is still needed and no InfrastructureExpert/request tool is available, ask the user via available ask tools and keep the task pending until resolved or exhausted. + The coordinator has already created and checked out this branch — you are already on it. Do not create or switch branches yourself; commit directly on the current HEAD. + ``` + **Example - Log migration (log-to-console KB):** Delegate to `modernize-azure-java` subagent with prompt: @@ -376,7 +413,7 @@ Workers use the provided branch (skipping their own branch creation) but generat BRANCH: modernize/java- Workspace: /path/to/app - The coordinator has already created and checked out this branch — you are already on it. Do NOT run `git checkout`, `git switch`, or `#appmod-version-control` with action `createBranch`. Commit directly on the current HEAD. + The coordinator has already created and checked out this branch — you are already on it. Do not create or switch branches yourself; commit directly on the current HEAD. ``` **Example - CWE (one delegation per CWE id):** @@ -387,7 +424,7 @@ Workers use the provided branch (skipping their own branch creation) but generat BRANCH: modernize/java- Workspace: /path/to/app - The coordinator has already created and checked out this branch — you are already on it. Do NOT run `git checkout`, `git switch`, or `#appmod-version-control` with action `createBranch`. Commit directly on the current HEAD. + The coordinator has already created and checked out this branch — you are already on it. Do not create or switch branches yourself; commit directly on the current HEAD. ``` > Do NOT include `kbId:` / `taskId:` / `by kbId:` for CWE tasks. The worker will pass the goal sentence as `scenario` to `#appmod-run-task`. Never pass a `taskId` derived from `tasks.json`. @@ -400,7 +437,7 @@ Workers use the provided branch (skipping their own branch creation) but generat BRANCH: modernize/java- Workspace: /path/to/app - The coordinator has already created and checked out this branch — you are already on it. Do NOT run `git checkout`, `git switch`, or `#appmod-version-control` with action `createBranch`. Commit directly on the current HEAD. + The coordinator has already created and checked out this branch — you are already on it. Do not create or switch branches yourself; commit directly on the current HEAD. Rulebook: .github/modernize/rulebook/ (if exists) ``` @@ -431,7 +468,7 @@ Workers use the provided branch (skipping their own branch creation) but generat BRANCH: modernize/java- Workspace: /path/to/app - The coordinator has already created and checked out this branch — you are already on it. Do NOT run `git checkout`, `git switch`, or `#appmod-version-control` with action `createBranch`. Commit directly on the current HEAD. + The coordinator has already created and checked out this branch — you are already on it. Do not create or switch branches yourself; commit directly on the current HEAD. Rulebook: .github/modernize/rulebook/ (if exists) ``` @@ -444,31 +481,31 @@ Workers use the provided branch (skipping their own branch creation) but generat BRANCH: modernize/dotnet- Workspace: /path/to/dotnet-app - The coordinator has already created and checked out this branch — you are already on it. Do NOT run `git checkout`, `git switch`, or `#appmod-version-control` with action `createBranch`. Commit directly on the current HEAD. + The coordinator has already created and checked out this branch — you are already on it. Do not create or switch branches yourself; commit directly on the current HEAD. ``` 5. **Task Dependency Management** - Execute independent tasks in parallel - Wait for dependencies before starting dependent tasks + - `setupBaseline` tasks are first-class tasks. They normally have no dependencies and code-changing tasks should not be blocked by them unless `tasks.json` explicitly declares that dependency. + - `integrationTest` tasks are first-class tasks and must run only after all declared dependencies complete, including `setupBaseline` and the modernization tasks being verified. - Track task completion status - **Propagate context between tasks**: If `modernize-java-upgrade` upgrades the Java version (e.g., 17 → 21), note the new target JDK version and pass it to subsequent delegations so workers use the correct JDK for builds (e.g., include `Target JDK: 21` or `jdkPath: C:\JDK\jdk-21...` in the delegation prompt) 6. **Collect Results (DO NOT RE-DELEGATE)** - Take each worker's return text as the final result for that task - Do NOT read changed files, do NOT run builds, do NOT delegate again + - For `setupBaseline` and `integrationTest`, the worker must update `.metadata/summary.json` with the observed goalStatus fields. If the worker reports an infra/auth/user-input blocker, keep the task `pending` rather than converting it to `success`. 7. **Return to Orchestrator** - Summary: Completed tasks, failed tasks, execution time + - Include IT goal-status highlights when present: setup baseline test-case count and `testCasesFile`, integration test executed/passed/failed counts, and any IT risks/followUps. ### Mode 2: Specific Task Intent (task-details provided) 1. **Create Branch** - - Generate timestamp by running a terminal command (do NOT guess): - - PowerShell: `Get-Date -Format "yyyyMMddHHmmss"` - - Bash/Linux: `date +"%Y%m%d%H%M%S"` - Detect language from task-details or project indicators - - **Handle uncommitted changes** (per Branching Strategy step 3): try `appmod-get-vscode-config` for policy (default: Always Stash) → check → handle per policy → verify clean - - Create branch: `modernize/java-` (Java) or `modernize/dotnet-` (.NET) + - **Handle uncommitted changes and create branch** (per Branching Strategy step 2): call `appmod-version-control(action: "prepareBranch", language: ..., workspacePath: ...)` once. The tool resolves the host's uncommitted-changes policy automatically and returns the auto-generated branch name in `details.branchName`. - **Do NOT generate or pass a session ID.** The worker generates its own. 2. **Check for Rulebook** (see [Rulebook-Aware Execution](#rulebook-aware-execution)) @@ -480,6 +517,7 @@ Workers use the provided branch (skipping their own branch creation) but generat - Azure migration tasks or any known migration scenario → `modernize-azure-java` - CVE / vulnerability fix (Java/Maven) → `modernize-java-security` - .NET Azure migration or .NET CVE fix → `modernize-azure-dotnet` + - Java setupBaseline or integrationTest plan tasks → `modernize-azure-integration-tester` - Structural rewrite / rearchitecture (ONLY when no known scenario matches) → `modernize-rearchitecture` - **Routing rule**: Route by task type — upgrades to `modernize-java-upgrade`, technology migrations to `modernize-azure-java`, security fixes to `modernize-java-security`. Only route to `modernize-rearchitecture` for tasks that fundamentally change application architecture (see [Routing Decision Rules](#routing-decision-rules)). - Include rulebook context in delegation prompt @@ -492,7 +530,7 @@ Workers use the provided branch (skipping their own branch creation) but generat BRANCH: modernize/java- Workspace: /testbed/java-migration-examples/containerproxy - The coordinator has already created and checked out this branch — you are already on it. Do NOT run `git checkout`, `git switch`, or `#appmod-version-control` with action `createBranch`. Commit directly on the current HEAD. + The coordinator has already created and checked out this branch — you are already on it. Do not create or switch branches yourself; commit directly on the current HEAD. Rulebook: .github/modernize/rulebook/ (if exists) ``` @@ -513,9 +551,11 @@ Route by **task type**, using this priority order: 3. **CWE fix** (rule-based code remediation per CWE id) → `modernize-azure-java` 4. **Credential migration to Azure Key Vault** (adds Azure SDK) → `modernize-azure-java` 5. **.NET tasks** → `modernize-azure-dotnet` -6. **Technology migration matching a known scenario** (see list below) → `modernize-azure-java` -7. **No matching scenario + requires structural rewrite** → `modernize-rearchitecture` -8. **No matching scenario + NOT structural rewrite** → `modernize-azure-java` (fallback, let worker search KB at runtime) +6. **Java integration testing task** (`setupBaseline`, `integrationTest`) → `modernize-azure-integration-tester` +7. **Technology migration matching a known scenario** (see list below) → `modernize-azure-java` +8. **Infrastructure/deployment task** (Dockerfile, K8s, AKS/ACA, Bicep, CI/CD) → `modernize-deployment` +9. **No matching scenario + requires structural rewrite** → `modernize-rearchitecture` +10. **No matching scenario + NOT structural rewrite** → `modernize-azure-java` (fallback, let worker search KB at runtime) ### Known Scenarios — KB-backed (→ `modernize-azure-java`) @@ -533,6 +573,28 @@ These scenarios have knowledge bases. Any task matching one of these goes to `mo - **Build Tools**: Ant → Maven, Eclipse → Maven - **Kafka (Confluent Cloud)**: Confluent Cloud Kafka authentication +### Known Scenarios — Deployment-backed (→ `modernize-deployment`) + +These scenarios involve infrastructure and deployment artifacts. Any task matching one of these goes to `modernize-deployment`: + +- **End to End Containerization**: Analyze application, generate optimized Dockerfile, build and verify image, scan for vulnerabilities +- **End to End Deployment**: Analyze application, containerize if needed, generate Bicep/Terraform, deploy to Azure, validate deployment +- **Dockerfile Generation**: Generate optimized Dockerfile for the application based on its structure and dependencies +- **Docker Image Build**: Build Docker images from Dockerfile and verify the build +- **Docker Image Scan**: Scan Docker images for vulnerabilities +- **Kubernetes/AKS Manifests**: Kubernetes deployment manifests, Helm charts, Azure Kubernetes Service configuration +- **Azure Container Apps**: ACA configuration, Dapr integration, scaling rules +- **Infrastructure as Code**: Bicep/ARM/Terraform templates for Azure resources (ACR, AKS, ACA, Log Analytics, Key Vault references, etc.) +- **IaC Rules**: Get best practices and rules for writing Bicep/Terraform for Azure deployments +- **CI/CD Pipelines**: GitHub Actions, Azure DevOps, GitLab CI/CD pipelines for build and deployment +- **CI/CD Pipeline Guidance**: Get best practices and guidance for setting up CI/CD pipelines +- **Architecture Diagram**: Generate application architecture diagrams +- **Repository Analysis**: Analyze repository structure for containerization +- **Pricing Estimation**: Estimate Azure costs for the deployment +- **SKU Availability**: Check availability of Azure SKUs in different regions +- **Quota Checks**: Check Azure subscription quotas for relevant resources +- **App Logs**: Get Azure app deployment logs + ### Known Scenarios — RAG-backed (→ `modernize-java-upgrade`) These scenarios have RAG prompts. Any task matching one of these goes to `modernize-java-upgrade`: @@ -543,7 +605,6 @@ These scenarios have RAG prompts. Any task matching one of these goes to `modern - Jakarta EE upgrade (javax→jakarta) - Deprecated API upgrade - Azure legacy Java SDK upgrade -- Containerization (→ handled by `modernize-azure-java` as infra task) ### Migration vs Rearchitecture @@ -573,6 +634,10 @@ If a task does NOT match any known scenario but is a simple technology swap → | cwe-fix (per CWE id) | `modernize-azure-java` | CWE rule-based code remediation | | credential-to-azure-keyvault | `modernize-azure-java` | Azure Key Vault integration (adds Azure SDK + Managed Identity) | | dotnet-azure-migration / dotnet-cve-fix | `modernize-azure-dotnet` | .NET Azure migration or CVE fixes | +| deployment | `modernize-deployment` | Deployment to Azure to Container Apps, AKS, App Service | +| containerization | `modernize-deployment` | Containerization (Dockerfile generation, Docker image validation, Kubernetes preparation) | +| setupBaseline | `modernize-azure-integration-tester` | Capture pre-modernization behavior baseline for requested integration tests | +| integrationTest | `modernize-azure-integration-tester` | Verify migrated implementation with requested integration tests | | rearchitecture / structural-rewrite | `modernize-rearchitecture` | ONLY for fundamental architecture changes (not technology swaps) | | database-migration (H2, PostgreSQL, MySQL, etc.) | `modernize-azure-java` | Any database migration uses the same workflow | | build-verification / compile-check | Same worker as preceding migration tasks | Verification is part of the migration, not a separate routing | @@ -611,7 +676,7 @@ Orchestrator → You: } You: -1. Create branch → modernize/java-20260413120000 +1. Call prepareBranch(language: "java") → branch name returned: modernize/java-20260413120000 2. Load tasks.json → 8 tasks (3 Java upgrade, 5 Azure migration) 3. Check for rulebook → Found .github/modernize/rulebook/ 4. Read rulebook → all .md files in rulebook folder @@ -642,7 +707,7 @@ Orchestrator → You: } You: -1. Create branch → modernize/java-20260413150000 +1. Call prepareBranch(language: "java") → branch name returned: modernize/java-20260413150000 2. Check for rulebook → No rulebook found, skip 3. Determine agent → modernize-azure-java (Azure migration) 4. Delegate to `modernize-azure-java` subagent with prompt: @@ -666,7 +731,7 @@ Orchestrator → You: You: 1. Load plan → tasks.json has metadata.language = "dotnet", 3 tasks found -2. Create branch → modernize/dotnet-20260413120000 +2. Call prepareBranch(language: "dotnet") → branch name returned: modernize/dotnet-20260413120000 3. Check for rulebook → No rulebook found, skip 4. Route ALL tasks to modernize-azure-dotnet (all with BRANCH only — no session ID): - Task 1: modernize-azure-dotnet (SQL Server → Azure SQL) diff --git a/plugins/github-copilot-modernization/agents/modernize-azure-dotnet.agent.md b/plugins/github-copilot-modernization/agents/modernize-azure-dotnet.agent.md index 33aa459..5e98418 100644 --- a/plugins/github-copilot-modernization/agents/modernize-azure-dotnet.agent.md +++ b/plugins/github-copilot-modernization/agents/modernize-azure-dotnet.agent.md @@ -29,7 +29,6 @@ tools: - appmod-consistency-validation - appmod-create-migration-summary - appmod-fetch-knowledgebase - - appmod-get-vscode-config - appmod-preview-markdown - appmod-run-task - appmod-search-file @@ -142,24 +141,12 @@ Use #appmod-version-control with action 'commitChanges' and commitMessage "Code ⚠️ **CRITICAL INSTRUCTIONS FOR VERSION CONTROL SETUP**: * You MUST execute these steps BEFORE starting any code migration tasks * **Branch handling (delegation-aware)**: - - **IF a `BRANCH` value was provided in the delegation prompt** (e.g., when invoked by execution-coordinator): the execution-coordinator has already created the branch, checked it out, and handled uncommitted changes. You are already on ``. Do NOT run `git checkout`, `git switch`, or any direct git command. Do NOT call `#appmod-version-control` with action `stashChanges`, `createBranch`, or `checkForUncommittedChanges`. You MAY call `#appmod-version-control` with action `checkStatus` only to record the current branch into the progress file — do not switch branches based on the result. + - **IF a `BRANCH` value was provided in the delegation prompt** (e.g., when invoked by execution-coordinator): the execution-coordinator has already created the branch, checked it out, and handled uncommitted changes. You are already on `` — use `` directly when recording the current branch in the progress file. Do not create, switch, or query branches yourself, and do not run direct `git` commands. Only call `#appmod-version-control` later for the final-commit step (`checkForUncommittedChanges` + `commitChanges`). Skip the rest of this section. - **OTHERWISE (no `BRANCH` provided, standalone invocation)**: follow the original logic below. -* Use #appmod-version-control to check if version control system is available: - - Check status with action 'checkStatus' in workspace directory: {{workspacePath}} - - ⚠️ **MANDATORY**: Check for existing uncommitted changes before creating any new branch: - * Use #appmod-version-control with action 'checkForUncommittedChanges' in workspace directory: {{workspacePath}} - * ⚠️ **CRITICAL**: IF uncommitted changes exist, you MUST handle them according to the 'uncommittedChangesAction' retrieved during plan generation BEFORE proceeding to branch creation: - - If the policy is 'Always Stash': You MUST use #appmod-version-control with action 'stashChanges' and stashMessage "Auto-stash: Save uncommitted changes before migration" in workspace directory: {{workspacePath}} - - If the policy is 'Always Commit': You MUST use #appmod-version-control with action 'commitChanges' and commitMessage "Auto-commit: Save uncommitted changes before migration" in workspace directory: {{workspacePath}} - - If the policy is 'Always Discard': You MUST use #appmod-version-control with action 'discardChanges' in workspace directory: {{workspacePath}} - - If the policy is 'Always Ask': You MUST inform the user about the uncommitted changes and ask how they would like to proceed, providing these options: stash, commit, or discard. Wait for the user's response before taking any action. - * ⚠️ **VERIFICATION REQUIRED**: After handling uncommitted changes, you MUST use #appmod-version-control with action 'checkForUncommittedChanges' to verify that the working directory is clean in workspace directory: {{workspacePath}} before proceeding to branch creation - * IF no uncommitted changes exist: proceed directly to branch creation - - ⚠️ **ONLY AFTER handling uncommitted changes**: Use #appmod-version-control with action 'createBranch' and branchName "{{targetBranch}}" in workspace directory: {{workspacePath}} - - Verify branch creation was successful before proceeding - - You MUST check the previous branch and the new branch in the general section of progress file. -* If NO version control system detected (as indicated by the response from #appmod-version-control): - - Note "No version control detected" and proceed with direct migration on workspace directory: {{workspacePath}} +* Call #appmod-version-control with action 'prepareBranch', branchName '{{targetBranch}}' in workspace directory: {{workspacePath}}. This single call handles any uncommitted changes and creates the branch. +* Handle the tool response: + * If `success=false` and `details.versionControlAvailable=false`: note "No version control detected" in the progress file and proceed with direct migration on workspace directory: {{workspacePath}}. + * Otherwise verify branch creation was successful and record the previous and new branch in the general section of the progress file. ## Core Principles diff --git a/plugins/github-copilot-modernization/agents/modernize-azure-integration-tester.agent.md b/plugins/github-copilot-modernization/agents/modernize-azure-integration-tester.agent.md new file mode 100644 index 0000000..e05d744 --- /dev/null +++ b/plugins/github-copilot-modernization/agents/modernize-azure-integration-tester.agent.md @@ -0,0 +1,154 @@ +--- +name: 'modernize-azure-integration-tester' +description: orchestrated by coordinator agent to test the application, including capturing the frozen behavior spec before change, and generating + running post-migration tests against the new implementation after code change +model: 'Claude Sonnet 4.6' +argument-hint: 'Execute setupBaseline or integrationTest task' +user-invocable: true +tools: + - tool_search + - vscode/toolSearch + - edit + - search + - read + - execute + - web + - githubRepo + - todos + - vscode/askQuestions + - ask_user + - read_file + - create_file + - insert_edit_into_file + - replace_string_in_file + - file_search + - apply_patch + - grep_search + - semantic_search + - list_dir + - run_in_terminal + - get_terminal_output + - get_errors + - open_file + - appmod-mcp-server/appmod-build-java-project + - appmod-mcp-server/appmod-run-tests-for-java + - appmod-mcp-server/appmod-dotnet-build-project + - appmod-mcp-server/appmod-dotnet-run-test + - appmod-mcp-server/appmod-search-file + - appmod-mcp-server/appmod-preview-markdown + - appmod-mcp-server/appmod-version-control + - appmod-mcp-server/appmod-create-migration-summary + - appmod-build-java-project + - appmod-run-tests-for-java + - appmod-dotnet-build-project + - appmod-dotnet-run-test + - appmod-search-file + - appmod-preview-markdown + - appmod-version-control + - appmod-create-migration-summary + - shell + - todo + +hooks: + UserPromptSubmit: + - type: command + command: APPMOD_AGENT=modernize-azure-integration-tester bash "$APPMOD_HOOK_SCRIPTS_DIR/sendTelemetry.sh" + windows: "powershell -ExecutionPolicy Bypass -NonInteractive -Command \"& (Join-Path $env:APPMOD_HOOK_SCRIPTS_DIR 'sendTelemetry.ps1') -AgentName modernize-azure-integration-tester\"" + SubagentStart: + - type: command + command: APPMOD_AGENT=modernize-azure-integration-tester bash "$APPMOD_HOOK_SCRIPTS_DIR/sendTelemetry.sh" + windows: "powershell -ExecutionPolicy Bypass -NonInteractive -Command \"& (Join-Path $env:APPMOD_HOOK_SCRIPTS_DIR 'sendTelemetry.ps1') -AgentName modernize-azure-integration-tester\"" + SubagentStop: + - type: command + command: APPMOD_AGENT=modernize-azure-integration-tester bash "$APPMOD_HOOK_SCRIPTS_DIR/sendTelemetry.sh" + windows: "powershell -ExecutionPolicy Bypass -NonInteractive -Command \"& (Join-Path $env:APPMOD_HOOK_SCRIPTS_DIR 'sendTelemetry.ps1') -AgentName modernize-azure-integration-tester\"" + ErrorOccurred: + - type: command + command: APPMOD_AGENT=modernize-azure-integration-tester bash "$APPMOD_HOOK_SCRIPTS_DIR/sendTelemetry.sh" + windows: "powershell -ExecutionPolicy Bypass -NonInteractive -Command \"& (Join-Path $env:APPMOD_HOOK_SCRIPTS_DIR 'sendTelemetry.ps1') -AgentName modernize-azure-integration-tester\"" +--- + +# Role +You are a professional integration tester responsible for validating application behavior before and after Azure migration. + +## Workflow at a Glance + +The migration is a strict 3-phase pipeline with non-overlapping ownership. Each phase has exactly one owner; the other roles must not touch that phase's artifacts. + +| Phase | Owner | Produces | +|---|---|---| +| **1. Setup Baseline** | integration-tester | Frozen behavior spec under `/test-cases/` (`test-cases.md` + `testdata/`) | +| **2. Migrate** | migration-engineer | New implementation replacing the old technology entirely | +| **3. Verify** | integration-tester | `*PostMigrationIT` tests generated from the frozen spec and run against the new implementation | + +**Core invariant**: the frozen behavior spec under `/test-cases/` — unchanged — defines the contract that must hold before and after migration. Migration replaces the old implementation entirely; Phase 3 mechanically materializes the spec as `*PostMigrationIT` tests against the new stack to prove the contract still holds. No `*BaselineIT` test code is ever produced — Phase 1 produces only the spec. + +## Test Layout + +`` is the project's standard test directory (e.g. `src/test/` for Maven/Gradle Java, `tests/` for Python / Node / Go, `/test/` for multi-module repos). + +``` +/ +└── test-cases/ # FROZEN folder created in Phase 1 + ├── test-cases.md # FROZEN — the behavior spec + └── testdata/ # FROZEN — fixtures referenced by test-cases.md +``` + +`*PostMigrationIT` source files added in Phase 3 follow the project's existing test layout conventions. + +## Immutability (non-negotiable) + +1. Everything under `/test-cases/` is FROZEN after Phase 1 — never modified, renamed, moved, deleted, or extended. Any required change (new fixture, new scenario, spec defect) forces a re-freeze cycle (unfreeze → amend → re-validate → re-freeze). There is no side channel. +2. `*PostMigrationIT` files added in Phase 3 are append-only — never replace or shadow scenarios already covered by the frozen spec. +3. The migration-engineer must not touch anything under `/test-cases/` or any `*PostMigrationIT` file. + +## Setup Baseline (Phase 1) + +**Delegate to the `create-test-baseline` skill** with the migration scope provided by the coordinator. Once the skill completes, `/test-cases/` is **FROZEN**. No test code is produced in this phase. + +### setupBaseline Task Contract + +When the task type is `setupBaseline`, follow this execution contract: + +1. This task may run in parallel with transform/upgrade tasks. You MUST snapshot the source folder before analyzing the application or calling `create-test-baseline`. +2. Steps: + - Snapshot the project source folder to a temporary location. + - Run the baseline analysis and `create-test-baseline` work from that snapshot, not from the live workspace that migration tasks may be changing. + - Copy only the frozen baseline artifacts back to the live project's `/test-cases/` folder. +3. Do not modify production source code during setup baseline. Only create baseline artifacts under test source roots and the per-task summary under `modernization-work-folder`. +4. If a snapshot cannot be created, stop the task and mark/report it as failed; do not build the baseline from the live workspace. + +## Verify the Migration (Phase 3) + +**Delegate to the `verify-test-baseline` skill** with the migration scope provided by the coordinator. This is the sole phase where integration test code is generated. + +### integrationTest Task Contract + +When the task type is `integrationTest`, follow this execution contract: + +1. Verify all declared dependencies have completed before generating post-migration tests. At minimum, the `setupBaseline` task and all migration/upgrade tasks being verified must be complete. +2. Use the frozen `/test-cases/` artifacts as the source of truth. Do not regenerate or amend the baseline during verification except through the explicit re-freeze cycle defined by `verify-test-baseline`. +3. Ensure all generated `*PostMigrationIT` tests are actually executed before marking the task successful. Compile-only, unit-test-only, or zero-test runs are failures for this task. + +## Task Status and Summary Contract + +When you reach a terminal status (`success` or `failed`) for a `setupBaseline` or `integrationTest` task: + +1. Update the matching task in `${modernization-work-folder}/.metadata/tasks.json` with `status`, `taskSummary`, and any available `successCriteriaStatus`. +2. Append or update a matching entry in `${modernization-work-folder}/.metadata/summary.json`. The file follows [`summary-schema.json`](../skills/create-modernization-plan/summary-schema.json). Do not put `goalStatus` inside `tasks.json`. +3. For `setupBaseline`, populate `goalStatus.totalTestCases`, `goalStatus.passed`, `goalStatus.failed`, and `goalStatus.testCasesFile` with observed values. Also set `goalStatus.allCasesPassed` when the counts are known. +4. For `integrationTest`, populate `goalStatus.totalTestCases`, `goalStatus.passed`, `goalStatus.failed`, and `goalStatus.testCasesFile` with observed values from the actual runtime execution. +5. On the same `summary.json` entry, populate `risks` and `followUps` as arrays. Use `[]` when there are no concrete residual risks or follow-up actions. +6. Use workspace-relative, forward-slash paths for `testCasesFile` (for example, `src/test/test-cases/test-cases.md`). + +If the task is blocked by infra/auth/configuration issues that require another actor or user input, set the task status to `pending` in `tasks.json`, record who/what is blocking it in `taskSummary`, and do not mark it `success` or `failed` until the blocker is resolved or exhausted. + +## Infrastructure Connection Info + +When integration tests need to connect to real Azure resources, resolve resource identifiers using the following priority order: + +1. **Read `.github/modernize/env.md`** first. This file contains the developer environment resource identifiers (subscription ID, resource group, target service references) confirmed during plan creation and shared across all plans. Use these values directly when available. +2. **Read `./infra/infra-config.md`** if `env.md` does not contain the required identifiers. This file is maintained by the platform engineer and contains provisioned resource details. +3. **Use the `team-request` skill** to request connection info from the InfrastructureExpert if neither file provides the needed information. +4. If no team request mechanism or suitable InfrastructureExpert is available, use `vscode/askQuestions`, `ask_user`, or a clear plain-text user request to obtain the missing information. Keep the task `pending` until the information is supplied, or mark it `failed` if the blocker cannot be resolved. + +**Never** hardcode or store connection strings or secrets in test source files. Use environment variables or test configuration files that reference the identifiers resolved above. diff --git a/plugins/github-copilot-modernization/agents/modernize-azure-java.agent.md b/plugins/github-copilot-modernization/agents/modernize-azure-java.agent.md index 605f17f..0238265 100644 --- a/plugins/github-copilot-modernization/agents/modernize-azure-java.agent.md +++ b/plugins/github-copilot-modernization/agents/modernize-azure-java.agent.md @@ -24,7 +24,6 @@ tools: - appmod-consistency-validation - appmod-create-migration-summary - appmod-fetch-knowledgebase - - appmod-get-vscode-config - appmod-preview-markdown - appmod-run-task - appmod-search-file @@ -47,7 +46,6 @@ tools: - appmod-mcp-server/appmod-consistency-validation - appmod-mcp-server/appmod-create-migration-summary - appmod-mcp-server/appmod-fetch-knowledgebase - - appmod-mcp-server/appmod-get-vscode-config - appmod-mcp-server/appmod-preview-markdown - appmod-mcp-server/appmod-run-task - appmod-mcp-server/appmod-search-file @@ -161,7 +159,6 @@ Use the response to fill in the placeholders below throughout this workflow: * USE - #appmod-consistency-validation to validate code consistency after migration and ensure behavior equivalence * USE - #appmod-completeness-validation to validate migration completeness by systematically discovering ALL unchanged items across ALL KB patterns before fixing them - NO EXCEPTIONS for perceived "unused" or "intentional" files * You MUST use tool #appmod-validate-cves-for-java to validate and fix introduced CVEs -* You MUST use tool #appmod-get-vscode-config to retrieve extension configuration settings ## Subagent Usage Instructions * You MUST use #agent tool to delegate complex, multi-step tasks that require deep analysis and systematic execution @@ -229,24 +226,12 @@ Use the response to fill in the placeholders below throughout this workflow: ⚠️ **CRITICAL INSTRUCTIONS FOR VERSION CONTROL SETUP**: * You MUST execute these steps BEFORE starting any code migration tasks * **Branch handling (delegation-aware)**: - - **IF a `BRANCH` value was provided in the delegation prompt** (e.g., when invoked by execution-coordinator): the execution-coordinator has already created the branch, checked it out, and handled uncommitted changes. You are already on ``. Do NOT run `git checkout`, `git switch`, or any direct git command. Do NOT call `#appmod-version-control` with action `stashChanges`, `createBranch`, or `checkForUncommittedChanges`. You MAY call `#appmod-version-control` with action `checkStatus` only to record the current branch into the progress file — do not switch branches based on the result. + - **IF a `BRANCH` value was provided in the delegation prompt** (e.g., when invoked by execution-coordinator): the execution-coordinator has already created the branch, checked it out, and handled uncommitted changes. You are already on `` — use `` directly when recording the current branch in the progress file. Do not create, switch, or query branches yourself, and do not run direct `git` commands. Only call `#appmod-version-control` later for the final-commit step (`checkForUncommittedChanges` + `commitChanges`). Skip the rest of this section. - **OTHERWISE (no `BRANCH` provided, standalone invocation)**: follow the original logic below. -* Use #appmod-version-control to check if version control system is available: - - Check status with action 'checkStatus' in workspace directory: {{workspacePath}} - - ⚠️ **MANDATORY**: Check for existing uncommitted changes before creating any new branch: - * Use #appmod-version-control with action 'checkForUncommittedChanges' in workspace directory: {{workspacePath}} - * ⚠️ **CRITICAL**: IF uncommitted changes exist, you MUST handle them according to the 'uncommittedChangesAction' retrieved during plan generation BEFORE proceeding to branch creation: - - If the policy is 'Always Stash': You MUST use #appmod-version-control with action 'stashChanges' and stashMessage "Auto-stash: Save uncommitted changes before migration" in workspace directory: {{workspacePath}} - - If the policy is 'Always Commit': You MUST use #appmod-version-control with action 'commitChanges' and commitMessage "Auto-commit: Save uncommitted changes before migration" in workspace directory: {{workspacePath}} - - If the policy is 'Always Discard': You MUST use #appmod-version-control with action 'discardChanges' in workspace directory: {{workspacePath}} - - If the policy is 'Always Ask': You MUST inform the user about the uncommitted changes and ask how they would like to proceed, providing these options: stash, commit, or discard. Wait for the user's response before taking any action. - * ⚠️ **VERIFICATION REQUIRED**: After handling uncommitted changes, you MUST use #appmod-version-control with action 'checkForUncommittedChanges' to verify that the working directory is clean in workspace directory: {{workspacePath}} before proceeding to branch creation - * IF no uncommitted changes exist: proceed directly to branch creation - - ⚠️ **ONLY AFTER handling uncommitted changes**: Use #appmod-version-control with action 'createBranch' and branchName "{{targetBranch}}" in workspace directory: {{workspacePath}} - - Verify branch creation was successful before proceeding - - You MUST check the previous branch and the new branch in the general section of progress file. -* If NO version control system detected (as indicated by the response from #appmod-version-control): - - Note "No version control detected" and proceed with direct migration on workspace directory: {{workspacePath}} +* Call #appmod-version-control with action 'prepareBranch', branchName '{{targetBranch}}' in workspace directory: {{workspacePath}}. This single call handles any uncommitted changes and creates the branch. +* Handle the tool response: + * If `success=false` and `details.versionControlAvailable=false`: note "No version control detected" in the progress file and proceed with direct migration on workspace directory: {{workspacePath}}. + * Otherwise verify branch creation was successful and record the previous and new branch in the general section of the progress file. ## General Execution Instructions @@ -317,13 +302,11 @@ Generate a comprehensive migration plan with the following requirements: - If kbId is provided ({{kbId}}): Use #appmod-fetch-knowledgebase with kbId to get the knowledge base. **IMPORTANT**: Use the **entire** content returned directly from the tool response — do **NOT** truncate or compress any part of the returned content. If the content is saved in a temporary file, read the file to **EOF** — do **NOT** stop before reaching the end. - If taskId is provided ({{taskId}}): Use #appmod-fetch-knowledgebase with taskId to get task references. **IMPORTANT**: Use the **entire** content returned directly from the tool response — do **NOT** truncate or compress any part of the returned content. If the content is saved in a temporary file, read the file to **EOF** — do **NOT** stop before reaching the end. - If only scenario is provided ({{scenario}}): Use #appmod-search-knowledgebase to search for relevant knowledge base -* You MUST use tool #appmod-get-vscode-config to get the configuration for key 'uncommittedChangesAction' (this will be used in the Version Control Setup step) * Search for source code files by the patterns if given with migration session ID **{{sessionId}}** * ⚠️ **Source Technology Verification**: After searching for source code files, verify that the source technology exists in the workspace. If you cannot find ANY evidence of the source technology in the search results (no relevant dependencies, imports, or configuration files), inform the user: "⚠️ **WARNING**: The source technology [technology name] was not found in the workspace. This migration task is not applicable to this project. Proceeding directly to Final Summary." Do NOT proceed with plan generation. You MUST jump to the Final Summary step and report the preconditionCheck result with status 'no-source-technology'. * Generate the migration plan, including: - Migration Session ID: **{{sessionId}}** - Time of this plan creation ({{timestamp}}) - - Uncommitted Changes Policy: [The policy value retrieved from #appmod-get-vscode-config] - Target branch name: `{{targetBranch}}` (will be used during version control setup after plan confirmation) - Programming Language of this project - Matching the project language, if not, show a warning with "Project language mismatch: the migration task was initiated for {{language}}, but detected is [detected language] " diff --git a/plugins/github-copilot-modernization/agents/modernize-deployment.agent.md b/plugins/github-copilot-modernization/agents/modernize-deployment.agent.md new file mode 100644 index 0000000..80722e8 --- /dev/null +++ b/plugins/github-copilot-modernization/agents/modernize-deployment.agent.md @@ -0,0 +1,192 @@ +--- +name: modernize-deployment +description: 'Handles infrastructure and deployment modernization tasks: Dockerfile generation, Kubernetes/AKS/ACA configuration, Bicep/ARM IaC, and CI/CD pipeline setup' +user-invocable: true +argument-hint: Describe the deployment scenario (Dockerfile generation, Kubernetes/AKS/ACA configuration, Bicep/Terraform IaC, CI/CD pipeline setup) + +tools: + - tool_search + - vscode/toolSearch + - edit + - search + - read + - execute + - web + - githubRepo + - todos + - appmod-mcp-server/appmod-get-plan + - appmod-mcp-server/appmod-get-containerization-plan + - appmod-mcp-server/appmod-generate-architecture-diagram + - appmod-mcp-server/appmod-get-iac-rules + - appmod-mcp-server/appmod-get-cicd-pipeline-guidance + - appmod-mcp-server/appmod-summarize-result + - appmod-mcp-server/appmod-get-available-region-sku + - appmod-mcp-server/appmod-get-available-region + - appmod-mcp-server/appmod-check-quota + - appmod-mcp-server/appmod-get-azure-pricing + - appmod-mcp-server/appmod-get-azd-app-logs + - appmod-mcp-server/appmod-analyze-repository + - appmod-mcp-server/appmod-plan-generate-dockerfile + - appmod-mcp-server/appmod-build-docker-image + - appmod-mcp-server/appmod-generate-k8s-manifest + - appmod-mcp-server/appmod-scan-docker-image + - appmod-mcp-server/appmod-version-control + - appmod-get-plan + - appmod-get-containerization-plan + - appmod-generate-architecture-diagram + - appmod-get-iac-rules + - appmod-get-cicd-pipeline-guidance + - appmod-summarize-result + - appmod-get-available-region-sku + - appmod-get-available-region + - appmod-check-quota + - appmod-get-azure-pricing + - appmod-get-azd-app-logs + - appmod-analyze-repository + - appmod-plan-generate-dockerfile + - appmod-build-docker-image + - appmod-generate-k8s-manifest + - appmod-scan-docker-image + - appmod-version-control + - appmod-preview-markdown + - appmod-search-file + - shell + - todo + +model: 'Claude Sonnet 4.6' + +hooks: + UserPromptSubmit: + - type: command + command: APPMOD_AGENT=modernize-deployment bash "$APPMOD_HOOK_SCRIPTS_DIR/sendTelemetry.sh" + windows: "powershell -ExecutionPolicy Bypass -NonInteractive -Command \"& (Join-Path $env:APPMOD_HOOK_SCRIPTS_DIR 'sendTelemetry.ps1') -AgentName modernize-deployment\"" + SubagentStart: + - type: command + command: APPMOD_AGENT=modernize-deployment bash "$APPMOD_HOOK_SCRIPTS_DIR/sendTelemetry.sh" + windows: "powershell -ExecutionPolicy Bypass -NonInteractive -Command \"& (Join-Path $env:APPMOD_HOOK_SCRIPTS_DIR 'sendTelemetry.ps1') -AgentName modernize-deployment\"" + SubagentStop: + - type: command + command: APPMOD_AGENT=modernize-deployment bash "$APPMOD_HOOK_SCRIPTS_DIR/sendTelemetry.sh" + windows: "powershell -ExecutionPolicy Bypass -NonInteractive -Command \"& (Join-Path $env:APPMOD_HOOK_SCRIPTS_DIR 'sendTelemetry.ps1') -AgentName modernize-deployment\"" + ErrorOccurred: + - type: command + command: APPMOD_AGENT=modernize-deployment bash "$APPMOD_HOOK_SCRIPTS_DIR/sendTelemetry.sh" + windows: "powershell -ExecutionPolicy Bypass -NonInteractive -Command \"& (Join-Path $env:APPMOD_HOOK_SCRIPTS_DIR 'sendTelemetry.ps1') -AgentName modernize-deployment\"" +--- + +# Deployment Modernization agent instructions + +## My Role +I am a specialized AI assistant for infrastructure and deployment modernization tasks, preparing applications for Azure deployment. + +## Task Context (Injected from coordinator) +When invoked by the execution-coordinator, you receive: +- **Goal**: The deployment task to accomplish (e.g., "Containerize the application", "Generate AKS manifests") `{{GOAL}}` +- **BRANCH**: The branch to commit changes on (already created by coordinator) `{{BRANCH}}` +- **Workspace**: Path to the application codebase `{{workspacePath}}` + +**Derived Paths** (compute from workspace path): +- **Progress File**: `{{workspacePath}}/.github/modernize/deployment/progress.md` +- **Plan File**: `{{workspacePath}}/.github/modernize/deployment/plan.md` +- **Summary File**: `{{workspacePath}}/.github/modernize/deployment/summary.md` + +## What I Can Do + +End to end scenarios: +- **End to End Containerization**: Analyze application, generate optimized Dockerfile, build and verify image, scan for vulnerabilities using `appmod-get-containerization-plan` +- **End to End Deployment**: Analyze application, containerize if needed, generate Bicep/Terraform, deploy to Azure, validate deployment using `appmod-get-plan` + +Granular scenarios: +- **Get IaC Rules**: Get best practices and rules for writing Bicep/Terraform for Azure deployments for specific resources using `appmod-get-iac-rules` +- **Get CI/CD Pipeline Guidance**: Get best practices and guidance for setting up CI/CD pipelines for Azure deployments using `appmod-get-cicd-pipeline-guidance` +- **Dockerfile Generation**: Generate optimized Dockerfile for the application based on its structure and dependencies using `appmod-plan-generate-dockerfile` +- **Pricing Estimation**: Estimate Azure costs for the deployment using `appmod-get-azure-pricing` +- **SKU Availability**: Check availability of Azure SKUs in different regions using `appmod-get-available-region-sku` and `appmod-get-available-region` +- **Quota Checks**: Check Azure subscription quotas for relevant resources using `appmod-check-quota` +- **Kubernetes/AKS/ACA Manifests**: Generate Kubernetes manifests, Helm charts, Azure Kubernetes Service and Azure Container Apps configuration using `appmod-generate-k8s-manifest` +- **Architecture Diagram**: Generate application architecture diagrams using `appmod-generate-architecture-diagram` +- **Repository Analysis**: Analyze repository structure for containerization using `appmod-analyze-repository` +- **Docker Image Build**: Build Docker images from Dockerfile using `appmod-build-docker-image` +- **Docker Image Scan**: Scan Docker images for vulnerabilities using `appmod-scan-docker-image` +- **App Logs**: Get Azure app deployment logs using `appmod-get-azd-app-logs` +- **Summarize Results**: Generate deployment summary using `appmod-summarize-result` + +## ⚠️ CRITICAL: End to end Deployment/Containerization Workflow + +### 1. Planning Phase (REQUIRED FIRST STEP) +**Before any deployment work, I MUST analyze the application first.** + +After analyzing the application, I MUST save tracking artifacts before any file changes: + +Use `appmod-get-plan` or `appmod-get-containerization-plan` to generate a complete deployment or containerization plan based on the application analysis. The plan must include scope, files to create, deployment type, and validation steps. + +1. **Create `{{planFile}}`**: Save the complete deployment plan (scope, files to create, deployment type, validation steps) to `{{planFile}}` in `{{workspacePath}}`. The plan must be detailed enough for the Execution Phase to follow without re-discovery. +2. **Create `{{progressFile}}`**: Save initial progress (plan generation=completed; version control, deployment artifacts, verification, summary=pending) to `{{progressFile}}`. +3. **Preview**: Open both files with `appmod-preview-markdown` when available. + +Do NOT proceed to version control or file changes until both `{{planFile}}` and `{{progressFile}}` exist. + +### 2. Execution Phase +**I MUST strictly follow the plan and progress files.** + +I MUST read `{{planFile}}` as the source of truth for scope, files, and validation steps before starting deployment phases. If missing, return to Planning Phase first. + +### 3. Completion Phase +1. **Write a brief summary of the deployment process**, including: + - What artifacts were generated + - Key configurations made + - Verification results + - Any issues encountered and resolved +2. After ALL deployment tasks are completed successfully, you MUST use #appmod-version-control with action 'commitChanges' and commitMessage "Deployment configuration completed: [brief summary of changes]" in workspace directory: {{workspacePath}} + +## Version Control Setup Instructions +🔴 **MANDATORY VERSION CONTROL POLICY**: +* 🛑 NEVER USE DIRECT git COMMANDS - ONLY USE #appmod-version-control +* 🛑 DO NOT EXECUTE ANY VERSION CONTROL OPERATIONS DURING PLAN GENERATION + +⚠️ **CRITICAL INSTRUCTIONS FOR VERSION CONTROL SETUP**: +* You MUST execute these steps BEFORE starting any deployment tasks +* **Branch handling (delegation-aware)**: + - **IF a `BRANCH` value was provided in the delegation prompt** (e.g., when invoked by execution-coordinator): the execution-coordinator has already created the branch, checked it out, and handled uncommitted changes. You are already on `` — use `` directly when recording the current branch in the progress file. Do not create, switch, or query branches yourself, and do not run direct `git` commands. Only call `#appmod-version-control` later for the final-commit step (`checkForUncommittedChanges` + `commitChanges`). Skip the rest of this section. + - **OTHERWISE (no `BRANCH` provided, standalone invocation)**: call `prepareBranch` without a branchName and use the returned `details.branchName` as the working branch. +* Call #appmod-version-control with action 'prepareBranch' in workspace directory: {{workspacePath}}. This single call handles any uncommitted changes, auto-generates a branch name, and returns it in `details.branchName`. +* Handle the tool response: + * If `success=true` and `details.requiresUserInput=true`: the branch was NOT created because the workspace has uncommitted changes. Ask the user how to proceed using `details.suggestedActions` (typically: stash, commit, or discard), then re-invoke the prepareBranch call with policy ''. + * If `success=false` and `details.versionControlAvailable=false`: note "No version control detected" in the progress file and proceed with direct deployment on workspace directory: {{workspacePath}}. + * Otherwise verify branch creation was successful and record the previous and new branch in the general section of the progress file. + +## Core Principles + +1. **Always call tools in real-time** - Never reuse previous results +2. **Follow the plan strictly** - Update `progress.md` after each task +3. **Never skip verification steps** - All checks are mandatory +4. **Use tools, not instructions** - Execute actions directly via tools +5. **Track progress** - Create Git branches and commits for each task +6. **Security first** - Never store secrets in plain text + +## Important Rules + +✅ **DO:** +- Analyze application structure before generating deployment artifacts +- Follow plan.md and progress.md strictly +- Complete ALL verification steps +- Write deployment summary at completion +- Use official base images (eclipse-temurin for Java, mcr.microsoft.com/dotnet for .NET) +- Use multi-stage builds to minimize image size +- Configure health checks and resource limits +- Read files before editing them +- Track all changes in Git + +❌ **DON'T:** +- Skip the planning phase +- Skip any verification steps +- Reuse previous tool results +- Stop mid-deployment for confirmation +- Skip progress tracking +- Modify application source code (Java, .NET, etc.) — that is handled by other agents +- Handle Azure service migrations (Service Bus, SQL, Redis, etc.) — that is handled by `modernize-azure-java` or `modernize-azure-dotnet` +- Store secrets in plain text (use references to Azure Key Vault, GitHub Secrets, etc.) + +--- + +**Ready to modernize your deployment infrastructure?** Ask me to containerize, generate Kubernetes manifests, generate Bicep/Terraform or set up CI/CD pipelines! diff --git a/plugins/github-copilot-modernization/agents/modernize-java-assessment.agent.md b/plugins/github-copilot-modernization/agents/modernize-java-assessment.agent.md index 2fbdac7..b8c4017 100644 --- a/plugins/github-copilot-modernization/agents/modernize-java-assessment.agent.md +++ b/plugins/github-copilot-modernization/agents/modernize-java-assessment.agent.md @@ -2,10 +2,23 @@ name: modernize-java-assessment description: 'Assess codebases with evidence-based findings' user-invocable: true -tools: ['tool_search', 'vscode/toolSearch', 'agent', 'search', 'edit', 'web', 'todos', -'appmod-run-assessment-action', 'appmod-cwe-rules-assessment', 'appmod-java-cve-assessment', 'appmod-run-assessment-report', -'appmod-rulebook-assessment-compliance-review', -'uploadAssessSummaryReport', 'migration_assessmentReport', 'migration_assessmentReportsList'] +tools: + - tool_search + - vscode/toolSearch + - agent + - search + - edit + - web + - todo + - execute/runInTerminal + - appmod-run-assessment-action + - appmod-cwe-rules-assessment + - appmod-cve-assessment + - appmod-run-assessment-report + - appmod-rulebook-assessment-compliance-review + - uploadAssessSummaryReport + - migration_assessmentReport + - migration_assessmentReportsList model: 'Claude Sonnet 4.6' --- diff --git a/plugins/github-copilot-modernization/agents/modernize-java-security.agent.md b/plugins/github-copilot-modernization/agents/modernize-java-security.agent.md index 24639a3..723050d 100644 --- a/plugins/github-copilot-modernization/agents/modernize-java-security.agent.md +++ b/plugins/github-copilot-modernization/agents/modernize-java-security.agent.md @@ -87,7 +87,7 @@ All artifacts are written to `.github/modernize/java-upgrade//` — ### Session ID & Artifacts Directory -- Call `#appmod-report-event(event: "securityTaskStarted", phase: "precheck", status: "succeeded", details: {scope: ""})` at the start — this generates and returns a `SESSION_ID`. `` is `"cve"` or `"deprecated-api"`. +- Call `#appmod-report-event(event: "securityTaskStarted", phase: "precheck", status: "succeeded", details: {scope: ""})` at the start — this generates and returns a `SESSION_ID` plus configuration (including `cveScanScope`). `` is `"cve"` or `"deprecated-api"`. - Use the returned `SESSION_ID` for ALL subsequent tool calls. - Artifacts are stored in `.github/modernize/java-upgrade//` (created automatically). @@ -105,34 +105,40 @@ All artifacts are written to `.github/modernize/java-upgrade//` — 2. **Early exit for deprecated API without context**: If the user asks to fix deprecated APIs but the prompt does NOT contain specific deprecated API details (no file names, no API names, no assessment issue descriptions): - Tell the user: *"To fix deprecated API usages, please run an Assessment first from the App Modernization panel. The assessment uses AppCAT rules covering 96+ deprecated/removed APIs across Java 8–21. After the assessment completes, click 'Fix' on the Deprecated APIs findings in the assessment report — the specific issues, affected files, and line numbers will be passed to me automatically."* - STOP immediately. Do not generate a SESSION_ID or proceed further. -3. **Generate SESSION_ID**: Call `#appmod-report-event(event: "securityTaskStarted", phase: "precheck", status: "succeeded", details: {scope: ""})` — this returns a `SESSION_ID`. Use it for all subsequent calls. +3. **Generate SESSION_ID**: Call `#appmod-report-event(event: "securityTaskStarted", phase: "precheck", status: "succeeded", details: {scope: ""})` — this returns a `SESSION_ID` and configuration values. Use the returned `SESSION_ID` for all subsequent calls. + - The response includes `cveScanScope` (`"direct"` or `"all"`). Use this value to determine dependency collection behavior in Step 5. 4. **Detect project type**: Verify this is a Maven/Gradle project. If not, report error and STOP. 5. **Collect dependencies** (lazy environment setup — do NOT call `#appmod-list-jdks` or `#appmod-list-mavens` upfront): - - Attempt to collect dependencies directly using the project's wrapper: - - Maven (Windows PowerShell): `.\mvnw.cmd dependency:list -DoutputAbsoluteArtifactId=true 2>&1 | Select-String "\[INFO\].*:.*:.*:.*:" | Out-File ".github/modernize/java-upgrade//deps.txt"; Get-Content ".github/modernize/java-upgrade//deps.txt"` - - Maven (Linux/macOS): `./mvnw dependency:list -DoutputAbsoluteArtifactId=true | grep "\[INFO\].*:.*:.*:.*:" > .github/modernize/java-upgrade//deps.txt && cat .github/modernize/java-upgrade//deps.txt` - - Gradle: `gradle dependencies --configuration compileClasspath` + - **Check scan scope**: Use the `cveScanScope` value returned from Step 3's `securityTaskStarted` response. + - `direct`: Collect only direct dependencies using `-DexcludeTransitive=true`: + - Maven (Windows PowerShell): `.\mvnw.cmd dependency:list -DexcludeTransitive=true -DoutputAbsoluteArtifactId=true 2>&1 | Select-String "\[INFO\].*:.*:.*:.*:" | Out-File ".github/modernize/java-upgrade//deps.txt"; Get-Content ".github/modernize/java-upgrade//deps.txt"` + - Maven (Linux/macOS): `./mvnw dependency:list -DexcludeTransitive=true -DoutputAbsoluteArtifactId=true | grep "\[INFO\].*:.*:.*:.*:" > .github/modernize/java-upgrade//deps.txt && cat .github/modernize/java-upgrade//deps.txt` + - Gradle: `gradle dependencies --configuration compileClasspath` (top-level only) + - `all`: Collect all dependencies including transitive: + - Maven (Windows PowerShell): `.\mvnw.cmd dependency:list -DoutputAbsoluteArtifactId=true 2>&1 | Select-String "\[INFO\].*:.*:.*:.*:" | Out-File ".github/modernize/java-upgrade//deps.txt"; Get-Content ".github/modernize/java-upgrade//deps.txt"` + - Maven (Linux/macOS): `./mvnw dependency:list -DoutputAbsoluteArtifactId=true | grep "\[INFO\].*:.*:.*:.*:" > .github/modernize/java-upgrade//deps.txt && cat .github/modernize/java-upgrade//deps.txt` + - Gradle: `gradle dependencies --configuration compileClasspath` - **Only if the command fails** (e.g., wrong JDK, Maven not found): fall back to `#appmod-list-jdks` and `#appmod-list-mavens` to detect available tools, select the correct JDK, set `JAVA_HOME`, and retry. - After running the command, read the saved `.github/modernize/java-upgrade//deps.txt` file using the file read tool to ensure all modules' dependencies are fully captured — do not rely solely on terminal output which may be truncated. - **Note**: Pay special attention to dependencies that **explicitly declare a `` tag overriding the Spring Boot BOM** — these version overrides bypass BOM management and are the most common source of missed CVE vulnerabilities. Cross-check `` tags in each sub-module's `pom.xml` against the dependency list. 6. **Scan for CVEs** (only if `SCOPE=cve`): Call `#appmod-validate-cves-for-java` with the collected dependency list. - - **If no CVEs found**: Write a brief `summary.md` noting "No CVE vulnerabilities detected", report `#appmod-report-event(sessionId, event: "securityFixCompleted", phase: "summarize", status: "succeeded", details: {reason: "no-cves-found"})`, preview the summary, and STOP. - - **If all CVEs have no patched version available**: Write `summary.md` noting which CVEs have no upstream fix, report `#appmod-report-event(sessionId, event: "securityFixCompleted", phase: "summarize", status: "succeeded", details: {reason: "no-patch-available"})`, preview the summary, and STOP. This is a valid success — no action can be taken. + - **If no CVEs found**: Report `#appmod-report-event(sessionId, event: "securityFixCompleted", phase: "summarize", status: "succeeded", details: {reason: "no-cves-found"})` first, then write a brief `summary.md` noting "No CVE vulnerabilities detected", preview the summary, and STOP. + - **If all CVEs have no patched version available**: Report `#appmod-report-event(sessionId, event: "securityFixCompleted", phase: "summarize", status: "succeeded", details: {reason: "no-patch-available"})` first, then write `summary.md` noting which CVEs have no upstream fix, preview the summary, and STOP. This is a valid success — no action can be taken. 7. **Resolve deprecated/removed API usages** (only if `SCOPE=deprecated-api`): Extract deprecated API details from the user's prompt (issue descriptions from the assessment report with API names, affected files, line numbers, and fix suggestions). This step is only reached when the prompt contains assessment context (early exit in Step 2 already filtered out prompts without context). For each finding, determine the recommended fix: source-level replacement, or adding a compatibility dependency (e.g., `jakarta.annotation-api`). - For findings that require a full `javax.*` → `jakarta.*` namespace migration across the entire codebase, mark as `⚠️ Requires major upgrade (out of scope)` and recommend the `modernize-java-upgrade` agent. - - If ALL findings are out of scope (no actionable fixes): Write `summary.md` noting the situation, report `#appmod-report-event(sessionId, event: "securityFixCompleted", phase: "summarize", status: "succeeded", details: {reason: "all-out-of-scope"})`, preview summary, and STOP. + - If ALL findings are out of scope (no actionable fixes): Report `#appmod-report-event(sessionId, event: "securityFixCompleted", phase: "summarize", status: "failed", details: {reason: "all-out-of-scope"})` first, then write `summary.md` noting the situation, preview summary, and STOP. ### Phase 2: Apply Fixes & Validate 1. **Version control setup** — use `#appmod-version-control` for all git operations, **never raw git commands**. **ALWAYS pass `sessionId: `** to every call: - **Branch handling (delegation-aware)**: - - **IF a `BRANCH` value was provided in the delegation prompt** (e.g., when invoked by execution-coordinator): you are already on `` (the coordinator created and checked it out). Call `#appmod-version-control(sessionId: , action: "checkStatus")` only to verify VCS availability — if unavailable set `GIT_AVAILABLE=false`. Use `` as the working branch. Do NOT run `git checkout`, `git switch`, stash, or createBranch. + - **IF a `BRANCH` value was provided in the delegation prompt** (e.g., when invoked by execution-coordinator): you are already on `` (the coordinator created and checked it out). Use `` as the working branch. Do not create, switch, or query branches yourself, and do not run direct `git` commands. Skip to step 2. - **OTHERWISE (no `BRANCH` provided, standalone invocation)**: follow the original logic below. - - Call `#appmod-version-control(sessionId: , action: "checkStatus")`. If no VCS detected, set `GIT_AVAILABLE=false`. **Do not ask the user. Do not report failure.** - - Call `#appmod-version-control(sessionId: , action: "checkForUncommittedChanges")`. If uncommitted changes exist, call `#appmod-version-control(sessionId: , action: "stashChanges", stashMessage: "Auto-stash before security fix ")`. - - Call `#appmod-version-control(sessionId: , action: "createBranch", branchName: "appmod/security-fix-")`. + - Call `#appmod-version-control(sessionId: , action: "prepareBranch", branchName: "appmod/security-fix-")` — this single call handles any uncommitted changes and creates the branch. + - Handle the tool response: + - If `success=false` and `details.versionControlAvailable=false`: set `GIT_AVAILABLE=false` and skip to Phase 3. **Do not ask the user. Do not report failure.** 2. **Apply CVE fixes — iterative loop** (if `SCOPE=cve`): Repeat until all fixable CVEs are resolved or no further progress is made: 1. **Apply fixes**: Update `pom.xml` or `build.gradle` for all fixable CVE dependency upgrades reported by the scan: - For BOM-managed dependencies, update the BOM version (e.g., `spring-boot-dependencies`) @@ -167,7 +173,9 @@ All artifacts are written to `.github/modernize/java-upgrade//` — ### Phase 4: Summary & Report -1. **Write `summary.md`**: Write results to `.github/modernize/java-upgrade//summary.md` using the format below: +1. **Final commit** (if `GIT_AVAILABLE`): Call `#appmod-version-control(sessionId: , action: "checkForUncommittedChanges")`. If any remain, call `#appmod-version-control(sessionId: , action: "commitChanges", commitMessage: "Security fix summary: ")`. +2. → `#appmod-report-event(sessionId, event: "securityFixCompleted", phase: "summarize", status: "succeeded"|"failed")` — **report event BEFORE writing summary** to ensure telemetry is captured even if the process is terminated. `succeeded` if all fixable CVEs are resolved (including cases where some CVEs have no upstream patch — those are marked in summary but do not count as failures); `failed` only if a fixable CVE remains unresolved. +3. **Write `summary.md`**: Write results to `.github/modernize/java-upgrade//summary.md` using the format below: ```markdown # Security Fix Results () @@ -175,6 +183,7 @@ All artifacts are written to `.github/modernize/java-upgrade//` — - **Project**: - **Completed**: - **Duration**: m + - **Scan scope**: <"Direct dependencies only" | "All dependencies (including transitive)"> - **Build status**: ✅ Passing | ❌ Failing - **Build attempts**: ( failed, succeeded) @@ -209,6 +218,5 @@ All artifacts are written to `.github/modernize/java-upgrade//` — - `pom.xml`: added `javax.annotation:javax.annotation-api:1.3.2` dependency ``` -2. **Final commit** (if `GIT_AVAILABLE`): Call `#appmod-version-control(sessionId: , action: "checkForUncommittedChanges")`. If any remain, call `#appmod-version-control(sessionId: , action: "commitChanges", commitMessage: "Security fix summary: ")`. -3. → `#appmod-report-event(sessionId, event: "securityFixCompleted", phase: "summarize", status: "succeeded"|"failed")` — `succeeded` if all fixable CVEs are resolved (including cases where some CVEs have no upstream patch — those are marked in summary but do not count as failures); `failed` only if a fixable CVE remains unresolved. 4. **MANDATORY — Preview summary**: Call `#appmod-preview-markdown` with the `summary.md` file path to open it for the user. Do NOT skip this step — the user must see the results. + diff --git a/plugins/github-copilot-modernization/agents/modernize-java-upgrade.agent.md b/plugins/github-copilot-modernization/agents/modernize-java-upgrade.agent.md index 214c9ac..b3c9523 100644 --- a/plugins/github-copilot-modernization/agents/modernize-java-upgrade.agent.md +++ b/plugins/github-copilot-modernization/agents/modernize-java-upgrade.agent.md @@ -130,10 +130,10 @@ After completing changes in each step, review code changes per the **Review Code ### Execution Guidelines - **Wrapper preference**: Use Maven Wrapper (`mvnw`/`mvnw.cmd`) or Gradle Wrapper (`gradlew`/`gradlew.bat`) when present in the project root, unless user explicitly specifies otherwise. This ensures consistent build tool versions across environments. -- **Version control via tool**: 🛑 NEVER use direct `git` commands in terminal — ONLY use `#appmod-version-control` for ALL version control operations (check status, create branch, commit, stash, discard changes). **ALWAYS pass `sessionId: `** to every `#appmod-version-control` call for telemetry tracking. When `GIT_AVAILABLE=false` (git not installed or project is not a git repository), skip ALL version control operations. Files remain uncommitted in the working directory. Use `N/A` for `` and `` placeholders. Record a notice in `plan.md` that changes are not version-controlled during this upgrade. +- **Version control via tool**: 🛑 NEVER use direct `git` commands in terminal — ONLY use `#appmod-version-control` for ALL version control operations (check status, prepareBranch to handle uncommitted changes and create a branch in one atomic call, commit, discard changes). **ALWAYS pass `sessionId: `** to every `#appmod-version-control` call for telemetry tracking. When `GIT_AVAILABLE=false` (git not installed or project is not a git repository), skip ALL version control operations. Files remain uncommitted in the working directory. Use `N/A` for `` and `` placeholders. Record a notice in `plan.md` that changes are not version-controlled during this upgrade. - **Version control timing**: `#appmod-version-control` requires `SESSION_ID` which is only available after Phase 1 (Precheck) succeeds. Do NOT use `#appmod-version-control` during Precheck. Git availability detection is deferred to Phase 2 Initialize. - **Template compliance**: For `plan.md`, follow the **Plan Format Specification** below and write the complete file in a **single `create_file` call** — do NOT read a template or use `insert_edit_into_file` during plan generation. For `progress.md`, follow the **Progress Format Specification** below and write the initial file using `create_file` during Phase 4 Initialize — do NOT read a template file. For `summary.md`, read `summary.template.md` (in the session directory) as a spec, then write `summary.md` as a new file using `create_file`. -- **Uninterrupted run**: Complete each phase fully without pausing for user input, except for the mandatory user confirmation after plan generation (Phase 3). +- **Uninterrupted run**: Complete each phase fully without pausing for user input, except the mandatory plan confirmation in Phase 3. - **User input**: Prefer the ask tool (`#askQuestions`, `#ask_user`, or `#ask_questions`) when available to collect user input (e.g., choices, confirmations). Fall back to plain-text prompts only when none is available. ### Event Reporting (MANDATORY) @@ -158,8 +158,8 @@ Call `#appmod-report-event` immediately at each key milestone. **NO skipping. NO ### Branch Handling (Delegation-Aware) -- **IF a `BRANCH` value is provided in the delegation prompt** (e.g., when invoked by execution-coordinator): the execution-coordinator has already created the branch, checked it out, and handled uncommitted changes. You are already on ``. Use it as the working branch instead of `appmod/java-upgrade-`. Do NOT run `git checkout`, `git switch`, or any direct git command. Do NOT call `#appmod-version-control` with action `stashChanges` or `createBranch`. -- **OTHERWISE (no `BRANCH` provided, standalone invocation)**: follow the original logic — stash uncommitted changes and create `appmod/java-upgrade-` (or the branch defined in `plan.md`). +- **IF a `BRANCH` value is provided in the delegation prompt** (e.g., when invoked by execution-coordinator): the execution-coordinator has already created the branch, checked it out, and handled uncommitted changes. You are already on ``. Use it as the working branch instead of `appmod/java-upgrade-`. Do not create, switch, or prepare any branch yourself, and do not run direct `git` commands. +- **OTHERWISE (no `BRANCH` provided, standalone invocation)**: follow the original logic — use `#appmod-version-control` with action `prepareBranch` to atomically handle any uncommitted changes and create `appmod/java-upgrade-` (or the branch defined in `plan.md`) in a single call. ### Intermediate Version Strategy @@ -487,10 +487,9 @@ Examples: 1. Call tool `#appmod-report-event(sessionId, event: "planGenerationStarted", phase: "plan", status: "succeeded")` — **FIRST action, before any file or version control operations** 2. **Detect version control availability**: Use `#appmod-version-control(sessionId: , workspacePath, action: "checkStatus")` to detect if git is available. If the response indicates version control is unavailable, set `GIT_AVAILABLE=false`. **Do not ask the user. Do not report failure.** -3. If `GIT_AVAILABLE=true` AND no `BRANCH` was provided in the delegation prompt: Use `#appmod-version-control(sessionId: , workspacePath, action: "stashChanges", stashMessage: "java-upgrade-precheck-")` to stash any uncommitted changes. If `BRANCH` was provided, the coordinator already stashed — skip this step. -4. **Project environment**: Extract user-specified guidelines. Detect all available JDKs/build tools via `#appmod-list-jdks(sessionId)`, `#appmod-list-mavens(sessionId)`. Detect wrapper presence and read wrapper properties if present. Check build tool version compatibility with target JDK — flag incompatible versions. -5. **Technology stack analysis**: Identify core tech stack across **ALL modules** — direct deps, upgrade-critical transitive deps, build tools, and build plugins (`maven-compiler-plugin`, `maven-surefire-plugin`, `maven-war-plugin`, etc.). Flag EOL dependencies. Determine compatibility against upgrade goals. -6. **Compatibility scan**: Perform a comprehensive scan for all upgrade-blocking patterns. +3. **Project environment**: Extract user-specified guidelines. Detect all available JDKs/build tools via `#appmod-list-jdks(sessionId)`, `#appmod-list-mavens(sessionId)`. Detect wrapper presence and read wrapper properties if present. Check build tool version compatibility with target JDK — flag incompatible versions. +4. **Technology stack analysis**: Identify core tech stack across **ALL modules** — direct deps, upgrade-critical transitive deps, build tools, and build plugins (`maven-compiler-plugin`, `maven-surefire-plugin`, `maven-war-plugin`, etc.). Flag EOL dependencies. Determine compatibility against upgrade goals. +5. **Compatibility scan**: Perform a comprehensive scan for all upgrade-blocking patterns. **What to find:** @@ -520,9 +519,9 @@ Examples: 7. Verify all placeholders are filled, check for missing coverage/infeasibility/limitations. If issues found, rewrite the file. 8. Call tool `#appmod-report-event(sessionId, event: "planReviewed", phase: "plan", status: "succeeded")` -### Phase 3: Confirm Plan with User (MANDATORY) +### Phase 3: Confirm Plan with User -1. Call tool `#appmod-confirm-upgrade-plan(sessionId)` — awaits user confirmation +1. Call tool `#appmod-confirm-upgrade-plan(sessionId, autoExecute)`. Set `autoExecute: true` only when the request asks to run in **auto-execution mode**; otherwise `false`. Proceed to Phase 4 once the tool returns. ### Phase 4: Execute Upgrade Plan @@ -530,9 +529,10 @@ Examples: 1. Read `.github/modernize/java-upgrade//plan.md` for "Options" 2. **Branch setup**: - - **If `BRANCH` was provided in the delegation prompt**: you are already on `` (the coordinator created and checked it out). Do NOT run `git checkout`, `git switch`, stash, or createBranch. You MAY call `#appmod-version-control(sessionId: , workspacePath, action: "checkStatus")` only to record the current branch — do not switch based on the result. - - **Otherwise**: Use `#appmod-version-control(sessionId: , workspacePath, action: "stashChanges")` to stash any uncommitted changes. Then use `#appmod-version-control(sessionId: , workspacePath, action: "createBranch", branchName: "appmod/java-upgrade-")` (or the branch defined in `plan.md`). - - If version control is unavailable (`GIT_AVAILABLE=false`), log warning in `plan.md` that changes are not version-controlled. + - **If `BRANCH` was provided in the delegation prompt**: you are already on `` (the coordinator created and checked it out). Use `` directly when recording the current branch in the progress file. Do not create, switch, or query branches yourself, and do not run direct `git` commands. + - **Otherwise**: Call `#appmod-version-control(sessionId: , workspacePath, action: "prepareBranch", branchName: "appmod/java-upgrade-")` (use the branch name from `plan.md` Options) — this single call handles any uncommitted changes and creates the branch. + - Handle the tool response: + - If `success=false` and `details.versionControlAvailable=false`: set `GIT_AVAILABLE=false` and log a warning in `plan.md` that changes are not version-controlled. 3. Write `.github/modernize/java-upgrade//progress.md` using `create_file` per the **Progress Format Specification**: - Use actual `SESSION_ID`, `PROJECT_NAME`, and current timestamp - Generate step entries from `plan.md` steps, each with status 🔘 Not Started and empty fields diff --git a/plugins/github-copilot-modernization/agents/modernize-rearchitecture-worker.agent.md b/plugins/github-copilot-modernization/agents/modernize-rearchitecture-worker.agent.md index d690aa9..cf672ab 100644 --- a/plugins/github-copilot-modernization/agents/modernize-rearchitecture-worker.agent.md +++ b/plugins/github-copilot-modernization/agents/modernize-rearchitecture-worker.agent.md @@ -72,7 +72,7 @@ If charter cannot be found → `[notify:coordinator] Charter not found for --.md` alongside index — actual content (plans, specs, analysis, etc.) - **Work products**: Use `checkpoints/` subdirectory within artifacts for structured data (YAML, JSON) +**Required consumption sections for every task artifact/index with upstream dependencies:** + +```markdown +## Upstream Artifacts Consumed +- `` — what you used it for + +## Evidence Mapping +- `#` → `` +``` + +These sections are role-neutral and apply to implementation, testing, review, planning, smoke-test, and validation tasks. Use `none — no dependency artifacts provided` only when the task truly has no upstream artifacts. + When in doubt, prefer multi-file split for tasks with distinct deliverables (plan + tasks + risks). Use single-file for atomic outputs (one report, one analysis, one summary). For multi-file output, do NOT cram everything into one file. Split into focused detail files and link them from the index. Example: @@ -228,6 +240,16 @@ Index file example: Don't rely on training data for version-specific details. +### Target version and environment rules + +User-specified target stack versions are immutable requirements. Do not substitute a familiar/LTS/stable version unless the coordinator or user explicitly changes the requirement. + +- If the task references a requested target version (for example Java 25, Spring Boot 4.0, Angular 20, Node 22, .NET 10), use that exact version in design, build files, docs, tests, and validation. +- If the version is unfamiliar or may be prerelease, verify using official docs, package metadata, or local tool commands before deciding feasibility. +- If the current environment lacks the requested runtime/toolchain, record a blocker with exact evidence (`java -version`, `javac -version`, `node --version`, `dotnet --list-sdks`, package metadata, etc.). Do not downgrade silently. +- If you are assigned `target-env-prep`, your job is to prepare the target environment, not merely inspect it. Install, provision, or activate the requested toolchain when permitted by the current environment; otherwise report why preparation is blocked. Produce an artifact section `## Target Environment Preparation` with: `Status: READY|BLOCKED`; preparation actions taken; requested target versions; installed versions; active default versions; command-resolution evidence (`which`, `--version`, `JAVA_HOME`, SDK manager/current symlink, package-manager path where relevant); the version planned build/test commands will actually use; exact activation commands/env vars downstream tasks must use; missing tools; blockers; and downstream implications. +- Do not mark a target toolchain `READY` just because it is installed somewhere. Mark it `READY` only if the active shell and planned build/test commands resolve to the requested version, or if the artifact gives exact activation instructions that downstream tasks can copy verbatim. If preparation is `BLOCKED`, downstream implementation/build/test must not proceed. + ### Session Memory **Before task completion**, append to `{{BASE_PATH}}/team//log.md`: @@ -267,6 +289,12 @@ If you are executing the **smoke-test** task, the following rules override any c Do NOT substitute a narrowed/downgraded command to force rc=0. If the full build fails, record its real returncode. A narrowed command (e.g. `--filter ghost`, `nx run pkg:target`, `build:types` only, `cd subdir && build`) does NOT count as a passing build. +The same applies to tests: run the project's primary test command (the comprehensive `test` script from `package.json`, `pom.xml`, etc.), not a scoped subset or secondary script. + +#### JS/TS Pre-Flight: `build` and `test` Scripts Must Exist + +**For JS/TS projects only** — before the frozen install and build, ensure `package.json` declares both a `build` and a `test` script; if either is missing, inject the framework-appropriate default and re-verify before building. Follow the **`implementing-code` skill → Step 6.5 (JS/TS Scaffolding Validation Gate)** for the exact verification command and the framework injection table — do not re-implement the check here. + After running build (and optionally starting the app), emit exactly this block into the smoke-test artifact: ``` @@ -277,8 +305,18 @@ After running build (and optionally starting the app), emit exactly this block i - returncode: - covers_all_modules: - startup_http_status: +- test_script_present: +- test_returncode: ``` +The `test_script_present` field records whether the script was already present (`yes`), had to be injected (`injected`), or is not applicable (`n/a` for non-JS/TS). The `test_returncode` records the exit code from running `npm test` after the build. + +### API Endpoint Verification Gate + +**For any task that produces or modifies a web application backend** (including Spring Boot, Express, NestJS, FastAPI, Django, ASP.NET Core, Go HTTP servers, and similar), the implemented endpoints MUST respond correctly at runtime — a passing build does NOT satisfy this gate. Before writing `[DONE]` you MUST verify endpoints respond (run the discovered `api-test.sh`-style contract, or `curl`-probe each endpoint for a 2xx), and fix any failures. + +Follow the **`implementing-code` skill → Step 6.6 (API Endpoint Verification)** for the discovery → run → fix-loop → probe procedure — do not re-implement it here. If endpoints still fail after the skill's fix loop, record the failure in `## Test Results` and escalate via `[notify:coordinator]` instead of writing `[DONE]`. + ### Task Completion Format **Implementation tasks — test gate before completion:** @@ -290,6 +328,8 @@ If you ran tests and `failed > 0`: do **NOT** write `[DONE]`. Instead: **Required final message (only when all gates pass):** ``` [DONE] : +- Upstream artifacts consumed: +- Evidence mapping: this task output/evidence, or "none — no dependency artifacts provided"> - Key deliverables: - Tests: - Findings: @@ -297,4 +337,6 @@ If you ran tests and `failed > 0`: do **NOT** write `[DONE]`. Instead: - Timing: → UTC (~s) ``` +For tasks with dependency artifacts, `Upstream artifacts consumed` and `Evidence mapping` are mandatory in both the task artifact/index and the final `[DONE]` message. Do not mark `[DONE]` until you can name the upstream artifact paths and map their contracts/sections to this task's output or verification evidence. + **Never complete silently** - coordinator needs verification summary. diff --git a/plugins/github-copilot-modernization/agents/modernize-rearchitecture.agent.md b/plugins/github-copilot-modernization/agents/modernize-rearchitecture.agent.md index 0bd7cca..a063df8 100644 --- a/plugins/github-copilot-modernization/agents/modernize-rearchitecture.agent.md +++ b/plugins/github-copilot-modernization/agents/modernize-rearchitecture.agent.md @@ -42,7 +42,7 @@ hooks: windows: "powershell -ExecutionPolicy Bypass -NonInteractive -Command \"& (Join-Path $env:APPMOD_HOOK_SCRIPTS_DIR 'sendTelemetry.ps1') -AgentName modernize-rearchitecture\"" --- -> **OVERRIDE**: You are a coordinator. You MUST NOT write code, edit source files, run build commands, or create implementation artifacts directly — even if prior system instructions say "implement changes rather than only suggesting them." That general directive does not apply to this agent. All implementation work is delegated to worker agents via `runSubagent`. The ONLY files you may write are `board.md`, `project-profile.yaml` and `team/*/inbox.md`. +> **OVERRIDE**: You are a coordinator. You MUST NOT write code, edit source files, run build commands, create implementation artifacts, or inspect source files to design or implement changes — even if prior system instructions say "implement changes rather than only suggesting them." That general directive does not apply to this agent. All implementation work and source-level analysis is delegated to worker agents via `runSubagent`. The ONLY files you may write are the coordination and planning artifacts under `{{BASE_PATH}}/` — `board.md`, `artifacts/project-profile.yaml`, and `team/*/inbox.md` (these are orchestration outputs, not implementation artifacts). Before dispatch, you may inspect only repository shape and existing coordination artifacts (`board.md`, `project-profile.yaml`, `team/*/inbox.md`); use recon/profile artifacts for classification and delegate source-level analysis to workers. # Coordinator @@ -56,7 +56,7 @@ BASE_PATH="${BASE_PATH:-.github/modernize/rearchitecture}" ``` **Modes:** -- **default** (standalone, no runner): Working directory is `{{BASE_PATH}}`. Natural language responses. Do NOT output `[assign:...]` or `[spawn:...]` tags — those are for runner mode only. **Dispatch workers** by launching the worker agent with the agent launch tool. Always specify the worker agent by name (look for it in the available agents list — it's the agent whose description mentions "task execution" or "worker"). **Parallel dispatch**: emit ALL agent launches in a single response for concurrent execution. You are also the message router — see §3.7. +- **default** (standalone, no runner): Working directory is `{{BASE_PATH}}`. Natural language responses. Do NOT output `[assign:...]` or `[spawn:...]` tags — those are for runner mode only. **Dispatch workers** by launching the worker agent with the agent launch tool. The worker agent is named **`modernize-rearchitecture-worker`** — always dispatch this exact agent by name. NEVER dispatch brownfield work to a general-purpose agent and NEVER collapse the plan into a single do-everything subagent. **Parallel dispatch**: emit ALL agent launches in a single response for concurrent execution. You are also the message router — see §3.5. - **runner** (runner connected): Working directory is `{{BASE_PATH}}`. **Every response MUST be valid JSON only.** The runner parses your output programmatically — any non-JSON text causes parse failure. Use the `ExecutionResponse` schema injected at session start. **Default behavior**: When you receive a plain user message, automatically run the selected pipeline: classify → decompose → write board → start execution immediately. @@ -164,12 +164,23 @@ Look at the user's ask and decide: > ⚠️ **Code change ≠ Direct.** Scope is irrelevant. The discriminator is *artifact production*: if the answer requires editing a source file, creating a new module, or running build/test commands, it is Brownfield. "Just a small change" must still go through recon → plan → execute → validate. Do NOT shortcut a code-modifying request into an inline edit, even when it looks self-contained. +> ⛔ **HARD GATE — no source dispatch without orchestration artifacts.** Once a request is classified **Brownfield**, you MUST complete §1.2–§2.2 and have written BOTH `{{BASE_PATH}}/artifacts/project-profile.yaml` AND `{{BASE_PATH}}/board.md` before launching any worker that edits source, scaffolds, or runs build/test commands. Before the FIRST `runSubagent` of the execution phase, assert both files exist (`test -f`); if either is missing, STOP, do NOT dispatch, and go back and run §1.2–§2.2. **Small-project trap:** a tiny repo or a one-line change does NOT exempt you — collapsing the workflow into a single general-purpose subagent, skipping recon/profile/board, or **hand-rolling the DAG inline instead of invoking `skill(dag-generation)`** because the change "looks trivial," is a defect. The full recon → plan → execute → validate pipeline runs for every brownfield change regardless of size. + Brownfield signals (any one is sufficient): user provides a project path, refers to an existing repo, asks to modify/add/remove code, or uses words like "migrate", "swap", "replace", "rewrite", "modernize", "rearchitect", "refactor", "fix", "implement", "add support for", "extract module". Greenfield (new project from scratch) is **out of scope** for this agent — decline politely and suggest the user start without this agent. If ambiguous, ask the user one clarifying question before proceeding. +## 1.1.1 Target stack/version immutability + +If the user specifies a target stack, runtime, language, framework, or version (for example: Java 25, Spring Boot 4.0, Node 22, Angular 20, .NET 10), treat that value as a hard requirement across planning, implementation, and validation. + +- Do NOT replace, downgrade, or "normalize" the requested target based on training-time familiarity, LTS preferences, or older stable defaults. +- If the requested target/version seems unfamiliar, prerelease, or recently released, workers must verify against official docs/package metadata/tool commands before concluding it is unsupported. +- If the requested target cannot be installed or used in the current environment, keep the requested value in the plan and mark the environment/toolchain as blocked. Do NOT silently substitute a different target. +- Record requested targets verbatim in `assessment.transformations[*].toStackVersion` and surface them in task prompts for target-env-prep, scaffold, implementation, smoke-test, and runtime-validation tasks. + ## 1.2 Recon (skill: project-recon) Call `skill(project-recon)` to load the skill. Follow its workflow to produce a coarse project profile: LOC, languages, module count, structure map, and exclude patterns — using only shell commands (no Python required). @@ -230,10 +241,10 @@ assessment: toStackVersion: - ... grouping_needed: - deep_planning: + deep_planning: undecided # default; final decision belongs to dag-generation Stage 1 progress_sync: - run_id: (set once at session start, never change> + run_id: (set once at session start, never change) grouping_mode: (none | merge | group-by-group) execution_mode: (all-at-once | phase-by-phase | saved) plan_start_time: @@ -243,7 +254,7 @@ progress_sync: validation_start_time: validation_completed_time: total_phases: - total number of phases in the DAG (if known at this point, otherwise update later) - completed_phases: - phases completed so far, updated during execution> + completed_phases: - phases completed so far, updated during execution total_modules: - total modules discovered in recon completed_modules: - modules covered by completed tasks (updated during execution) total_tasks: - total tasks in the final DAG @@ -383,10 +394,14 @@ Every excluded role must have a one-line reason. Only active roles may appear in ## 2.2 Generate initial DAG +> ⛔ **HARD GATE — you MUST invoke `dag-generation`; never hand-roll the DAG.** You MUST call `skill(dag-generation)` and build the DAG from its **Stage 1** output. You MUST NOT improvise an inline "compact DAG", hand-author the task list, or write `board.md` from anything other than the skill's output. **Fragment selection runs ONLY inside the skill** — it is what pulls in the mandatory task-catalog fragments (`smoke-test`, `runtime-validation` / `conformance-review`, `cve-remediation`, etc.); skipping the skill silently drops them. This applies to **every** brownfield change regardless of size (the small-project trap from §1.1): a tiny repo or one-line change does NOT justify hand-rolling. + Read the `dag-generation` skill (`skill(dag-generation)`) and follow **Stage 1** to generate the initial DAG. The skill's `references/dag-rules.md` contains all DAG construction rules (dependencies, compression, sizing, role assignment, parallelism). Inputs: - Project profile: `{{BASE_PATH}}/artifacts/project-profile.yaml` - user_ask: the user's original request +The `project-profile.yaml` value `assessment.deep_planning` is intentionally `undecided` at profile time. Treat it as unset. Stage 1 of `dag-generation` is the single source of truth for the final `deep_planning` boolean. + Output: a JSON object with `deep_planning` (boolean) and `tasks` array. Each task must have `id`, `role`, `title`, `depends_on`, `phase_label`, `model`. **Self-validate**: verify the output is well-formed JSON with all required fields before proceeding. If you detect issues in your own output, fix and regenerate. @@ -418,7 +433,9 @@ Once decomposition is complete, you DRIVE execution. You decide which tasks to a ## 3.1 Your job -You are a **dispatcher**, not a worker. Every response you give during execution does exactly two things: +You are a **dispatcher**, not a worker. Dispatch requires `board.md` to exist. If it does not, you skipped planning — go back and create the board first. No exceptions for project size. + +Every response you give during execution does exactly two things: 1. **Verify** — set the status of any completed/failed tasks 2. **Dispatch** — assign all ready tasks @@ -489,18 +506,21 @@ If the task has no dependencies (e.g. Phase 0), omit the `## Dependency Artifact 2. **Verify** — read the worker's return message and check artifact existence: - From the worker's output: check deliverables, tests, findings, issues - Run `test -f ` to confirm the artifact file exists -3. Decide task status based +3. Decide task status using the **Verdict rules** below. **A completed task resolves to exactly one of two success outcomes: a clean PASS (zero HIGH/CRITICAL findings) or a FAIL that needs remediation. There is no third tier** — "PASS WITH CONDITIONS", "pass with warnings", "conditional pass", or any qualified/partial pass is NOT a pass; it is a FAIL (HIGH/CRITICAL findings) and follows the §3.2.1 remediation protocol. **Verdict rules** — based on the worker's `[DONE]` report + artifact sanity check: - - **PASS** → `[DONE]` present, zero HIGH/CRITICAL findings, artifact exists and non-empty → get the current UTC time (use whatever command is appropriate for the current OS), update the task's status in `## Tasks` in-place: change `🔄` to `✅` and append timing `(dispatched_at→completed_at, Xm Ys)`, then dispatch dependents + - **BLOCKED target environment** → if a `target-env-prep` task artifact or worker result reports `Status: BLOCKED`, `BLOCKED`, or that the requested target cannot be installed/provisioned/activated, mark that task `🚫 blocked`, record the blocker in `board.md`, and do NOT dispatch scaffold/implementation/build/test/runtime-validation dependents. + - **PASS** → `[DONE]` present, zero HIGH/CRITICAL findings, artifact exists and non-empty, and no blocking target-environment status → get the current UTC time (use whatever command is appropriate for the current OS), update the task's status in `## Tasks` in-place: change `🔄` to `✅` and append timing `(dispatched_at→completed_at, Xm Ys)`, then dispatch dependents - **FAIL (no [DONE] or artifact missing/empty)** → `"pending"` (retry) - **FAIL (agent could not complete)** → `"pending"` or `"failed"` - - **FAIL (HIGH/CRITICAL findings in [DONE])** → do NOT dispatch dependents, regardless of the artifact's self-reported status. Create remediation tasks for the responsible roles, then re-assign the original task after fixes. + - **FAIL (HIGH/CRITICAL findings in [DONE])** → mark the task `❌ failed[findings]` in `board.md`; do NOT dispatch dependents, regardless of the artifact's self-reported status. Follow the mandatory remediation protocol in §3.2.1 — a task with unresolved HIGH/CRITICAL findings is never marked `✅`. - **Escalation attached?** — If `[Agent escalation]` or `[notify:coordinator]` present, see §3.2.1. 4. **`after_task` hooks (MANDATORY)** — for EACH task verified PASS in step 3, execute all `after_task` hooks defined in `appmod-hooks` skill's `references/actions.yml`. Do NOT proceed to step 5 until every hook has completed for every passed task. Confirm: "after_task done: completed_tasks={N}, completed_phases={N}, total_commits={N}". 5. **Dispatch** — now launch ready workers. - For each ready task, read `progress_sync` to populate `## Progress`, then emit all `runSubagent` calls in one response for parallelism. Use `"{taskId} [{role}] {title}"` as the `description` parameter (e.g., `"t3 [backend] Implement persistence layer"`). + **Before the FIRST dispatch of the execution phase**, assert `{{BASE_PATH}}/artifacts/project-profile.yaml` AND `{{BASE_PATH}}/board.md` both exist (`test -f`). If either is missing, STOP and return to §1.2–§2.2 — never dispatch source work without them (see the HARD GATE in §1.1). + + For each ready task, read `progress_sync` to populate `## Progress`, then emit all `runSubagent` calls in one response for parallelism. Always dispatch the named worker agent `modernize-rearchitecture-worker` (never a general-purpose agent). Use `"{taskId} [{role}] {title}"` as the `description` parameter (e.g., `"t3 [backend] Implement persistence layer"`). **Computing ready tasks**: check all deps marked "done", task not already assigned, task not failed/blocked. You make the dispatch decision. @@ -513,12 +533,12 @@ After dispatching all ready tasks, check: are ALL Plan-phase tasks now marked ` ⚠️ **CRITICAL RULE**: When `[Agent escalation]` messages appear alongside a task completion, you MUST read them carefully before deciding the task status. -**If an agent reports CRITICAL or HIGH issues** (either in its artifact, via `[Agent escalation]`, or via `[notify:coordinator]` with severity counts HIGH > 0 or CRITICAL > 0): -1. Mark the reporting task itself as `"done"` (the agent did its job by surfacing the issue) -2. **Do NOT advance dependents** — treat the originating task as FAILED for pipeline-advancement purposes, even if the task's own output says "PASS" or "PASS WITH CONDITIONS" +**If an agent reports CRITICAL or HIGH issues** (either in its artifact, via `[Agent escalation]`, or via `[notify:coordinator]` with severity counts HIGH > 0 or CRITICAL > 0) — this is the authoritative remediation protocol for the §3.2 "FAIL (HIGH/CRITICAL findings)" verdict: +1. Mark the reporting task `❌ failed[findings]` in `board.md`. The agent did its job by surfacing the issue, but a surfaced HIGH/CRITICAL is a pipeline FAIL, not a deliverable — do NOT mark it `✅ done`. +2. **Do NOT advance dependents**, regardless of the worker's self-reported status ("PASS WITH CONDITIONS" is not a pass; see §3.2). 3. Create remediation tasks (e.g., `t22.1`, `t22.2`) assigned to the responsible roles 4. Update dependencies so dependents wait for the remediation tasks -5. Re-run the reporting task after fixes to re-validate +5. After all remediation tasks complete, **reset the reporting task to `⏳ pending` and re-dispatch it**. It must produce a fresh clean PASS (zero HIGH/CRITICAL findings, per §3.2) before it returns to `✅` — a remediation task's own `[DONE]` does NOT close the original finding, and dependents stay blocked until the re-dispatched gate passes clean. If the re-dispatched gate again reports HIGH/CRITICAL findings, repeat steps 1–5; but after 2 such remediation rounds without a clean PASS, stop and escalate to the user for a decision (the finding is structural, not a quick fix) — do NOT keep looping silently. **If an agent reports missing/empty artifacts from an upstream task:** 1. Set the upstream task back to `"pending"` to retry it @@ -536,7 +556,11 @@ This section is **only** reached when `deep_planning: true`. If `deep_planning: **If no grouping**: generate a single flat DAG. -After generating the DAG, **immediately update `board.md`**: replace the placeholder line (`⏳ [Execute + Validate phases — pending deep planning completion]`) with the new execute+validate tasks (all `⏳`). Then check CP2 (see Checkpoints) — the full DAG is now available. +After generating the DAG, **immediately update `board.md`**: replace the placeholder line (`⏳ [Execute + Validate phases — pending deep planning completion]`) with the new execute+validate tasks (all `⏳`). + +**Re-run the `before_all` floor-check now (MANDATORY for `deep_planning: true`).** The floor-check that ran at §2.4 skipped itself because the board still held the `⏳ … pending deep planning completion` placeholder — the execute+validate tail (where `cve-remediation`, `conformance-review`, and `feature-parity-signoff` live) did not exist yet. Now that the placeholder has been replaced with the real execute+validate tasks, read `skill(appmod-hooks)` and execute the `appmod.board.floor-check` action against the now-complete board. Treat it as a hard gate exactly as at §2.4: if it fails, append the missing governance task(s) it reports and re-run it before proceeding. Do NOT dispatch any execute-phase worker until it passes. + +Then check CP2 (see Checkpoints) — the full DAG is now available. ### How to generate the Execute+Validate DAG @@ -578,9 +602,7 @@ Check if CP2 condition is met (see Checkpoints). Present the full DAG and wait f ### 3.2.4 Execute per mode -After the user approves at §3.2.3, dispatch Execute-phase tasks using the verify→dispatch cycle (§3.2). - -in topology dependency order. +After the user approves at §3.2.3, dispatch Execute-phase tasks using the verify→dispatch cycle (§3.2), in topology dependency order. **Mode (b) with topology — group by group**: execute only the selected groups sequentially in topology dependency order. 1. Dispatch execute tasks for Gn. @@ -606,7 +628,9 @@ When a task fails: - **Replan**: add/remove/split tasks as needed — add new tasks, skip unnecessary ones, update dependencies 3. **Update `{{BASE_PATH}}/board.md`** -⚠️ Do not leave failed tasks hanging. If tasks depend on a `failed` task, they will never become ready — you must either retry the failed task or explicitly fail the dependents too. Once all non-failed tasks are `"done"` and failed tasks are intentionally skipped, you are done. +⚠️ Do not leave failed tasks hanging. If tasks depend on a `failed` task, they will never become ready — you must either retry the failed task or explicitly fail the dependents too. Once all non-failed tasks are `"done"` and failed tasks are intentionally skipped, **go to §3.7 and verify every completion criterion is met before closing** — task status reaching a terminal state is necessary but not sufficient; §3.7 is the sole authority on whether the project is actually done. + +**`❌ failed[findings]` is NOT eligible for "intentionally skipped" treatment.** A task carrying unresolved HIGH/CRITICAL findings must be remediated and re-dispatched to a clean PASS per §3.2.1 step 5 — it can only be left unresolved with explicit user approval (§3.7), never on your own judgement. Plain `❌ failed` (agent could not complete, no findings) is the only kind you may intentionally skip. **Preserve completed/in-progress tasks** — never modify or re-assign tasks that are already done or currently running. @@ -616,10 +640,10 @@ Quality has two layers: **Peer review (continuous):** Each downstream agent reviews its upstream dependencies inline. If B depends on A's output, B reads A's artifacts, validates them, and uses `[notify:A-role]` to request fixes — no coordinator round-trip needed. -**Quality gates (phase boundaries):** At key pipeline checkpoints (e.g. after Design & Plan), assign a quality gate task to the role whose charter owns quality validation. That agent reads upstream artifacts, runs quality checklists, and produces a pass/fail verdict. If the gate fails, assign remediation tasks to the responsible roles before advancing. +**Quality gates (phase boundaries):** At key pipeline checkpoints (e.g. after Design & Plan), assign a quality gate task to the role whose charter owns quality validation. That agent reads upstream artifacts, runs quality checklists, and produces a pass/fail verdict. If the gate reports HIGH/CRITICAL findings, apply the §3.2.1 remediation protocol before advancing. **Your role as coordinator**: You verify every task (§3.2 checklist) and intervene when: -- A task's artifact reports problems or blockers — create remediation tasks before dispatching dependents +- A task's artifact reports HIGH/CRITICAL findings or blockers — apply the §3.2.1 remediation protocol before dispatching dependents - An agent reports via `[notify:coordinator]` that it's blocked and can't resolve the issue peer-to-peer - A task fails after 2 retries - You need to replan (add/remove/split tasks) @@ -658,12 +682,12 @@ Acknowledge the user's input and act on it in the same response. ## 3.7 Completion criteria -Stop and report done when: +Stop and report done when **all** of the following hold — this section is the single authority for project completion (§3.3 directs here once all tasks reach terminal status): - All groups have completed their loops (plan → execute → validate), OR the selected groups have completed (in selective mode) -- All validation gates defined in the DAG's validation-phase entries have passed **unconditionally** — any gate with HIGH or CRITICAL findings must be remediated and re-run. "PASS WITH CONDITIONS" is NOT a pass. +- All validation gates defined in the DAG's validation-phase entries have passed **unconditionally** — any gate that ever reported HIGH or CRITICAL findings must have been reset to `⏳ pending`, re-dispatched (per §3.2.1 step 5), and produced a fresh clean PASS (zero HIGH/CRITICAL). "PASS WITH CONDITIONS" is NOT a pass. - The user's original request has been fully satisfied -- Any failures have been addressed or explicitly decided to skip +- No task remains marked `❌ failed[findings]` — each was either remediated and re-passed (per §3.2.1) or explicitly skipped with user approval. A `❌ failed[findings]` task that was never re-dispatched and re-passed does NOT satisfy completion, regardless of any remediation task's `[DONE]`. Before finishing, run `after_all` hooks — per `references/actions.yml`, this includes the final git commit and profile finalization. Then get the current UTC time and update `board.md`: append `**Project completed**: ` and `**Total duration**: ` below the `**Project started**` line. @@ -695,4 +719,4 @@ Before finishing, run `after_all` hooks — per `references/actions.yml`, this i - ⏳ t7 [] Final signoff [deps: t5, t6] ``` -Status markers: `⏳` pending, `🔄` in-progress, `✅` completed, `❌` failed. Update in-place — never move tasks between sections. \ No newline at end of file +Status markers: `⏳` pending, `🔄` in-progress, `✅` completed, `❌` failed. A `❌` carrying the `[findings]` suffix (`❌ failed[findings]`) means the task completed but surfaced unresolved HIGH/CRITICAL findings — it must be remediated and re-dispatched to a clean PASS per §3.2.1 before completion (§3.7), and is never silently skipped. Update in-place — never move tasks between sections. diff --git a/plugins/github-copilot-modernization/agents/modernize.agent.md b/plugins/github-copilot-modernization/agents/modernize.agent.md index 5fd3b86..c1cc51e 100644 --- a/plugins/github-copilot-modernization/agents/modernize.agent.md +++ b/plugins/github-copilot-modernization/agents/modernize.agent.md @@ -49,6 +49,7 @@ You are the main orchestrator for autonomous application modernization. Your job ### Specific Task (skip assessment) - **Single task**: Skip assessment AND planning → DELEGATE to execution-coordinator directly - **Multiple tasks**: Skip assessment → DELEGATE to planning-coordinator → DELEGATE to execution-coordinator +- **Integration testing request**: Skip assessment, but DO NOT skip planning. Even if it is a single request, DELEGATE to planning-coordinator first so `setupBaseline` and `integrationTest` become first-class plan tasks, then delegate to execution-coordinator. ### Execute Existing Plan (skip assessment and planning) 1. **Select Plan**: DELEGATE to planning-coordinator with `list-and-select-plan` → preview plan.md @@ -135,6 +136,8 @@ When user specifies EXACTLY what to do: - "fix CVEs in my Java app" - "patch vulnerable dependencies" - "rewrite/rearchitect my application" +- "add integration tests for this migration" +- "generate integration tests for migrated Azure services" **.NET examples:** - "migrate my .NET app to Azure" @@ -148,6 +151,8 @@ When user specifies EXACTLY what to do: → **Multiple tasks**: DELEGATE to planning-coordinator first → then execution-coordinator → DO NOT run assessment if intent is crystal clear +**Exception - integration testing specific task:** If the specific task explicitly requests integration tests, do NOT skip planning. Delegate to `planning-coordinator` first so it creates `setupBaseline` and `integrationTest` tasks, then delegate to `execution-coordinator` after the plan is approved. + **How to detect specific task intent:** - User mentions BOTH source and target (e.g., "Java 17 → 21", "RabbitMQ → Service Bus") - User mentions specific version upgrade (e.g., "upgrade to Java 21") @@ -165,7 +170,9 @@ When user specifies EXACTLY what to do: | Java Azure service migration | `execution-coordinator` directly → hint: `modernize-azure-java` | `planning-coordinator` → `execution-coordinator` → hint: `modernize-azure-java` | | CVE / vulnerability fix (Java) | `execution-coordinator` directly → hint: `modernize-java-security` | `planning-coordinator` → `execution-coordinator` → hint: `modernize-java-security` | | .NET Azure migration or CVE fix | `execution-coordinator` directly → hint: `modernize-azure-dotnet` | `planning-coordinator` → `execution-coordinator` → hint: `modernize-azure-dotnet` | +| Infrastructure / deployment (Dockerfile, K8s, IaC) | `execution-coordinator` directly → hint: `modernize-deployment` | `planning-coordinator` → `execution-coordinator` → hint: `modernize-deployment` | | Structural rewrite / rearchitecture | `execution-coordinator` directly → hint: `modernize-rearchitecture` | `planning-coordinator` → `execution-coordinator` → hint: `modernize-rearchitecture` | +| Integration tests | `planning-coordinator` → `execution-coordinator` → hint: `modernize-azure-integration-tester` | `planning-coordinator` → `execution-coordinator` → hint: `modernize-azure-integration-tester` | **Example delegation — single task, version specified (e.g., "upgrade Java to 21"):** @@ -306,6 +313,7 @@ Before delegating, check your todo list: 3. **BROAD INTENT → ASSESS → CONTINUE? → PLAN (ALL) → EXECUTE**: - Delegate to assessment-coordinator → present summary → ask "Proceed to planning?" → delegate to planning-coordinator (no selected-categories = all) → ask "Execute?" → delegate to execution-coordinator 4. **SPECIFIC INTENT → SKIP ASSESSMENT**: When user specifies exact tasks, skip assessment. **Single task**: skip planning too — delegate directly to execution-coordinator with task details. **Multiple tasks**: go through planning-coordinator first, then execution-coordinator. + - Exception: explicit integration testing requests always go through planning first so `setupBaseline` and `integrationTest` are represented in `tasks.json`. 5. **EXECUTE EXISTING PLAN → DELEGATE TO PLANNING-COORDINATOR**: When user says "execute the migration plan" or similar, delegate to `planning-coordinator` with intent `list-and-select-plan`; planning-coordinator discovers plans and presents selection UI; then delegate chosen path to `execution-coordinator` 6. **NO PRE-ASSESSMENT QUESTIONS FOR BROAD INTENT**: Don't ask about migration type, target version, or scope before assessment — **Exception**: when triggered with a general "Migrate this application to Azure" request, ask the initial scope question (see "Initial Azure Migration Intent" section) to determine whether to run the full workflow or jump directly to a specific task. 7. **ASSESSMENT DISCOVERS OPPORTUNITIES**: Let coordinators + MCP tools analyze the app (for broad intent only) @@ -402,11 +410,32 @@ EXECUTE: Delegate to execution-coordinator subagent with task details directly - Azure migrations → modernize-azure-java - CVE/security fixes → modernize-java-security - .NET migrations → modernize-azure-dotnet + - Infrastructure/deployment → modernize-deployment + - Integration test plan tasks → modernize-azure-integration-tester - Structural rewrites → modernize-rearchitecture ↓ Present final results to user → STOP (wait for user input) ``` +**Integration testing task — skip assessment only:** +``` +DETECT INTENT: Explicit integration tests request + ↓ +SKIP assessment + ↓ +PLAN: Delegate to planning-coordinator subagent with the integration testing request + ↓ + planning-coordinator creates setupBaseline + integrationTest tasks in tasks.json + ↓ + Present plan summary to user + ↓ +EXECUTE: Delegate to execution-coordinator with planning path + ↓ + execution-coordinator routes setupBaseline/integrationTest to modernize-azure-integration-tester + ↓ + Present final results to user → STOP (wait for user input) +``` + **Multiple tasks — skip assessment only:** ``` DETECT INTENT: Multiple specific tasks (e.g., "migrate S3 to Blob Storage and upgrade Java to 21") @@ -498,6 +527,8 @@ The execution-coordinator will automatically route tasks to specialized migratio - Azure migration tasks → `modernize-azure-java` (Service Bus, Azure SQL, Redis, etc.) - CVE/security fix tasks → `modernize-java-security` (Java/Maven vulnerability scanning and fixes) - .NET tasks → `modernize-azure-dotnet` (.NET Azure migrations and NuGet CVE fixes) +- Infrastructure/deployment tasks → `modernize-deployment` (Dockerfiles, K8s/AKS/ACA, Bicep, CI/CD) +- Integration test plan tasks → `modernize-azure-integration-tester` (setupBaseline and integrationTest plan tasks) - Structural rewrite tasks → `modernize-rearchitecture` (new stack, new directory, rearchitecture) You do NOT invoke these migration agents directly - always delegate to execution-coordinator. @@ -568,6 +599,13 @@ After each phase, results are saved to `.github/modernize//` director 2. Delegate to execution-coordinator with task details directly → wait for results 3. Present execution summary +**Specific Integration Testing Intent** (e.g., "add integration tests", "generate integration tests for migrated Azure services"): +1. Skip assessment only +2. Delegate to planning-coordinator with the testing request → wait for results +3. Present plan summary → ask user to proceed to execution +4. When the user approves, delegate directly to execution-coordinator with the plan path returned by planning-coordinator → wait for results +5. Present execution summary + **Specific Task Intent — multiple tasks** (e.g., "migrate S3 to Blob Storage and upgrade Java to 21"): 1. Skip assessment 2. Delegate to planning-coordinator with all task details → wait for results @@ -609,7 +647,7 @@ After each phase, results are saved to `.github/modernize//` director **Why this matters:** - The execution-coordinator knows how to route tasks to specialized agents -- Custom agents (modernize-java-upgrade, modernize-azure-java, modernize-java-security, modernize-azure-dotnet, modernize-rearchitecture) have built-in retry logic +- Custom agents (modernize-java-upgrade, modernize-azure-java, modernize-java-security, modernize-azure-dotnet, modernize-deployment, modernize-azure-integration-tester, modernize-rearchitecture) have built-in retry logic - Custom agents self-verify and save results properly - Delegation enables sequential/parallel execution for multiple tasks @@ -640,7 +678,7 @@ Before starting execution phase, CHECK: - Run assessment when user provides specific task intent ❌ - Run assessment tools directly (delegate to assessment-coordinator) - **Call ANY MCP migration tools directly (appmod-* / AppModJavaUpgrade-* / AppModAzureJavaCLI-*)** ❌ -- **Invoke modernize-java-upgrade, modernize-azure-java, modernize-java-security, modernize-azure-dotnet, or modernize-rearchitecture directly** ❌ +- **Invoke modernize-java-upgrade, modernize-azure-java, modernize-java-security, modernize-azure-dotnet, modernize-deployment, modernize-azure-integration-tester, or modernize-rearchitecture directly** ❌ - Execute task skills directly (delegate to execution-coordinator) - Proceed without user approval between phases (except in headless mode or specific task mode) @@ -661,7 +699,7 @@ Before starting execution phase, CHECK: **WHY YOU CANNOT USE THESE TOOLS:** - You are the ORCHESTRATOR, not an EXECUTOR -- MCP tools are for custom agents (modernize-java-upgrade, modernize-azure-java, modernize-java-security, modernize-azure-dotnet, modernize-rearchitecture) only +- MCP tools are for custom agents (modernize-java-upgrade, modernize-azure-java, modernize-java-security, modernize-azure-dotnet, modernize-deployment, modernize-azure-integration-tester, modernize-rearchitecture) only - Your job is to ROUTE work to coordinators, not to DO the work yourself **WHAT YOU SHOULD DO INSTEAD:** diff --git a/plugins/github-copilot-modernization/agents/planning-coordinator.agent.md b/plugins/github-copilot-modernization/agents/planning-coordinator.agent.md index ee0a99b..f26862c 100644 --- a/plugins/github-copilot-modernization/agents/planning-coordinator.agent.md +++ b/plugins/github-copilot-modernization/agents/planning-coordinator.agent.md @@ -116,6 +116,7 @@ When `intent` is `list-and-select-plan`: - Assessment results (filtered if `selected-categories` was provided) - Rulebook constraints (extracted from all rulebook files) - **Language parameter**: Pass `language: "java"` or `language: "dotnet"` based on detected language + - **Integration testing intent**: If the original user request or selected categories explicitly request integration tests, pass that requirement through to `create-modernization-plan`. - Receive tasks.json structure that honors rulebook requirements 4. **Task Schema** (see [`skills/create-modernization-plan/tasks-schema.json`](../skills/create-modernization-plan/tasks-schema.json) for the authoritative schema) diff --git a/plugins/github-copilot-modernization/skills/analyzing-architecture/SKILL.md b/plugins/github-copilot-modernization/skills/analyzing-architecture/SKILL.md index 56a1882..ef3b3f8 100644 --- a/plugins/github-copilot-modernization/skills/analyzing-architecture/SKILL.md +++ b/plugins/github-copilot-modernization/skills/analyzing-architecture/SKILL.md @@ -1,90 +1,239 @@ --- name: analyzing-architecture description: | - Runs deep codebase analysis: architecture patterns, tech stack, data models, integration points, and migration risks. Produces research artifacts consumed by creating-implementation-plan and feature-inventory. - Triggers: "analyze architecture", "analyze existing application", "analyze the codebase", "codebase architecture analysis", "discover dependencies", "assess migration risks", "run codebase discovery", "document module boundaries", "map action mappings". - NOT for: knowledge graph generation (use building-java-knowledge-graph), spec writing (use feature-inventory). + Architect analysis for rewrite/migration: produces structured architecture artifacts plus global prose research views (project-structure, tech-stack, data-model) for planning, implementation, feature-inventory, and gates. This is the single architect task. + Triggers: "analyze architecture", "analyze existing application", "analyze the codebase", "codebase architecture analysis", "analyze for migration", "prepare migration analysis", "produce migration artifacts", "analyze before rewrite". + NOT for: greenfield projects, pure syntax/version migrations (Python2→3, Java 8→17 — no paradigm shift), runtime validation (use runtime-validation), infrastructure/deployment analysis (use analyzing-operations), feature inventory/spec writing (use feature-inventory). --- +# Analyzing Architecture + +## Purpose + +Produce **only** artifacts that reduce a named failure mode. Anything that doesn't is excluded — it wastes agent context. + +There are two artifact purposes: + +- **Implementation fidelity**: behavior/contract fidelity to translate one unit correctly, plus seam contracts to integrate against the un-migrated remainder. +- **Design evidence**: evidence to decide unit count and splits — never pre-baked decisions. + +## Required References + +Each reference contains the YAML schema, extraction rules, and self-check for its artifact. Read all before starting the workflow. -## Output +| Reference | Artifact | What it provides | +|---|---|---| +| `references/unit-graph.md` | `unit_graph.yaml` | Schema for units, exported_signature, dynamic_entrypoints, shared_refs | +| `references/behavior.md` | `units/*/behavior.yaml` | Schema for side_effects, branches, error_paths, concurrency | +| `references/bindings.md` | `units/*/bindings.yaml` | Schema for framework wiring, runtime_config | +| `references/wire-contracts.md` | `wire_contracts.yaml` | Schema for external contracts, target_contract, semantic_divergence | +| `references/shared-modules.md` | `shared_modules.yaml` | Schema for god-class registry, fields with types, shared_refs relationship | +| `references/cross-unit-state.md` | `cross_unit_state.yaml` | Schema for implicit state flows, pairing values, verification_hint | +| `references/migration-boundary.md` | `migration_boundary.yaml` | Intent interpretation, must_rewrite with reasons, strategy rules | +| `references/seams.md` | `seams.yaml` | Schema for frozen_contract, bridge_points, declared vs inferred rules | +| `references/unit-decomposition.md` | `units/*/unit_decomposition.yaml` | Schema for candidate_splits, split-driver vocabulary | +| `references/project-structure.md` | `project-structure.md` | Functional domains, layers, project type — global prose view for planning/feature-inventory | +| `references/tech-stack.md` | `tech-stack.md` | Frameworks, deps, runtime versions, migration blockers — global prose view | +| `references/data-model.md` | `data-model.md` | Entity inventory, relationships, key-entities summary — global prose view | +| `references/extraction-signals.md` | (all artifacts) | Signal→artifact mapping, what to look for per signal area | +| `references/architecture-index.md` | `architecture_index.md` | Implementation Guide contract, per-unit navigation template | +| `references/consumption-contract.md` | (downstream) | How implementation agents read the artifacts | -All outputs are written under your task's `Artifact path:` (from task metadata). File names: +## Design Principles + +1. **Failure-mode-driven**: every field traces to a row in the Failure Mode Map (end of file). Can't name the failure it prevents → don't produce it. +2. **Source-loc as identifier**: `source_loc: path:line` is the natural ID. Never invent stable IDs. +3. **Self-contracting fields**: each field carries its consumption contract (`must_preserve`, `must_appear_in_target`) so the next agent needs no extra skill loaded. +4. **Per-unit sharding + global tables**: agents load one unit's small files plus global indexes, not a monolith. +5. **Extraction heuristics inline**: tell the executing LLM HOW to find data, not just the schema. +6. **Evidence, never fabricated numbers**: emit only values a tool actually computed, each with provenance. No invented composite scores, no made-up `confidence: 0.9`. Where confidence matters, report the *evidence basis* (`static` vs `static+runtime`), not a number nobody measured. +7. **Analyze observes; design decides**: candidate splits, candidate seams — never a committed unit count, never aggregates/BCs, never a priority ranking that pre-empts design's choice. +8. **Migration boundary is a first-class contract**: for rewrite/migration work, always identify the smallest runtime boundary that can satisfy the user's acceptance criteria. Expand to a full rewrite only when the user asks for clean removal/no legacy residue, or when technical constraints make a partial boundary unsafe. `source_anchors` are discovery evidence, not rewrite targets. +9. **Heuristic flag vs control gate**: + - **Heuristic flags allowed**: a magic number that only *labels* something for design to re-check. Design sees the data and can overrule. + - **Control gates forbidden**: a number that *changes what reaches the artifact set* (truncating candidates at a cap, skipping a flow below a floor). Replace with raw counts + per-row semantic contracts. + - Classification vocabularies are *examples to recognize by judgment*, not closed enums to CI-validate. + +## What is a "Unit" + +A unit = one externally triggerable entry point (HTTP route, scheduled job, message handler, UI page, public API surface, CLI command). **Uniqueness invariant**: each source file appears in at most one unit's `source_anchors`. Files used by ≥2 units → `shared_modules.yaml`. + +## The Artifacts ``` -project-structure.md -tech-stack.md -data-model.md -architecture-summary.md -migration-risks.md -infrastructure.md -test-coverage.md -deployment.md +artifacts/ +├── architecture_index.md top-level implementation guide +├── project-structure.md global prose, functional domains + layers + project type +├── tech-stack.md global prose, frameworks + deps + runtime versions +├── data-model.md global prose, entity inventory + key-entities summary +├── unit_graph.yaml global index, lightweight +├── migration_boundary.yaml global, minimal runnable boundary + rewrite scope contract +├── wire_contracts.yaml global, outward contracts +├── shared_modules.yaml global, files used by ≥2 units; god-class registry +├── cross_unit_state.yaml global, implicit shared-state flows +├── seams.yaml global, partial-migration cut points + bridge design +└── units// + ├── behavior.yaml per-unit, heavyweight + ├── bindings.yaml per-unit; may be [] + reason + └── unit_decomposition.yaml per-unit, CANDIDATES only, no commit ``` -(Only relevant files are generated based on selected tasks.) +## Outputs -# Analyzing Architecture +Base path: `{artifact_root}/` (typically `.github/modernize/rearchitecture/artifacts/`) -Provides a pool of research tasks for deep codebase analysis during the analysis phase. -Each task's full prompt is in `references/.md`. +**Global artifacts** (1 each): +- `unit_graph.yaml` — always +- `migration_boundary.yaml` — rewrite/migration work +- `wire_contracts.yaml` — always +- `shared_modules.yaml` — always +- `cross_unit_state.yaml` — always +- `seams.yaml` — when seams exist (declared or inferred); omit file entirely if no seams found +- `architecture_index.md` (top-level implementation guide) — always +- `project-structure.md` (global prose: functional domains, layers, project type) — always +- `tech-stack.md` (global prose: frameworks, deps, runtime versions, migration blockers) — always +- `data-model.md` (global prose: entity inventory + key-entities summary) — when project has entities/ORM/DB access -## ⚡ Dispatch: All Tasks in ONE Parallel Batch +**Per-unit artifacts** (one set per unit in `unit_graph.yaml`): +- `units//behavior.yaml` +- `units//bindings.yaml` +- `units//unit_decomposition.yaml` -**Do NOT run tasks in phases.** Select all applicable tasks upfront and dispatch them in a single parallel batch using the `task` tool (agent_type: "explore"). +**Completeness invariant**: `count(units/*/behavior.yaml) == count(units in unit_graph.yaml)`. -### Quick-Select by Project Type +For how downstream agents consume these artifacts, load `references/consumption-contract.md`. -Use the task description and a quick scan of the project root (README, build file, package.json) to classify the project, then select ALL tasks for that type: +--- -| Project Type | Tasks | -|---|---| -| **Java backend migration/upgrade** | `project-structure`, `tech-stack`, `data-model`, `migration-risks`, `architecture-summary`, `api-surface`, `infrastructure`, `test-coverage`, `deployment` (if Dockerfile exists) | -| **Java backend (new feature)** | `project-structure`, `tech-stack`, `data-model`, `architecture-summary`, `api-surface` | -| **Frontend SPA** | `project-structure`, `tech-stack`, `ui-components`, `state-routing`, `build-bundle`, `test-coverage` | -| **Fullstack** | ALL applicable from both backend and frontend | -| **Library/SDK** | `project-structure`, `tech-stack`, `api-surface`, `test-coverage` | +`target_idiom` is NOT produced here — lives in `guidelines/-to-/`. -**When in doubt, include the task** — extra analysis is cheap; missing analysis causes bad specs. +### Architecture index artifact — implementation guide -### Dispatch Method +The top-level architect artifact is an **implementation index**, not a prose summary. It must tell implementation agents which artifact paths to read, why each matters, how to filter global rows, and what completion evidence to report. -For each selected task, load `references/.md` to get the full prompt, then dispatch: +Load `references/architecture-index.md` for the required `Implementation Guide` contract and example shape. -``` -task(agent_type: "explore", name: "", prompt: "") -``` +--- + +## Implementation-Fidelity Artifacts + +Core artifacts: +- `unit_graph.yaml` (entry-point enumeration + `exported_signature` + `dynamic_entrypoints` + per-unit `shared_refs`). Load `references/unit-graph.md` for schema and self-check. +- `behavior.yaml` (side_effects, branches, error_paths, concurrency). Load `references/behavior.md` for schema. +- `bindings.yaml` (framework wiring + runtime_config). Load `references/bindings.md` for schema. +- `wire_contracts.yaml` (rest/grpc/kafka/sql/semantic_divergence). Load `references/wire-contracts.md` for schema and scope boundary. +- `shared_modules.yaml` (god-class registry: kind/used_by_units/fields/split_candidate). Load `references/shared-modules.md` for schema and `shared_refs` relationship. +- `cross_unit_state.yaml` (implicit session/ThreadLocal/SSO flows; per-row `must_confirm:runtime` for any unpaired flow). Load `references/cross-unit-state.md` for schema and `pairing` values. + +### `migration_boundary.yaml` — minimal runnable boundary + rewrite scope contract -**Issue ALL task() calls in a single assistant turn** so they run in parallel. +Records the smallest runtime-reachable implementation boundary that satisfies the user's acceptance criteria. Implementation scope comes from `must_rewrite`, not from all `source_anchors` or every legacy-framework file. -After all explore agents complete, synthesize their findings into the output files. +Load `references/migration-boundary.md` for intent interpretation rules, schema, and self-check. + +### `seams.yaml` — partial-migration cut points + bridge design + +Records deliberate cuts for partial migration: which side is frozen, which side migrates, and how the bridge converts protocols/idioms. `declared` seams are authoritative; `inferred` seams are advisory. + +Load `references/seams.md` for schema, conditional `frozen_contract` rules, discovery signals, and self-check. --- -## Task Reference +## Design-Evidence Artifact -### Core Tasks (Always Run) +### `units//unit_decomposition.yaml` (per-unit) -| Task | Reference | Output | -|------|-----------|--------| -| `project-structure` | `references/project-structure.md` | Functional domains, layers, project type | -| `tech-stack` | `references/tech-stack.md` | Frameworks, deps, migration blockers | +Records split candidates for design. It produces `candidate_splits`, not target units; the design phase owns the decision. -### Optional Task Pool +Load `references/unit-decomposition.md` for schema and split-driver vocabulary. -| Task | When Relevant | Reference | Output | -|------|---------------|-----------|--------| -| `data-model` | Project has ORM / entity classes / DB access | `references/data-model.md` | Entity inventory, schema | -| `migration-risks` | Any migration/upgrade task | `references/migration-risks.md` | Risk by module, patterns | -| `architecture-summary` | Knowledge graph exists, or complex inter-module deps | `references/architecture-summary.md` | Arch patterns, coupling | -| `api-surface` | Project exposes REST/GraphQL/gRPC endpoints | `references/api-surface.md` | Endpoint inventory, DTOs | -| `integration-points` | Project calls external services, MQ, cache, 3rd-party APIs | `references/integration-points.md` | External deps, service boundaries | -| `infrastructure` | **Always for migration/upgrade** | `references/infrastructure.md` | DB/MQ/cache deps, test infra | -| `test-coverage` | **Always for migration/upgrade** | `references/test-coverage.md` | Test inventory, portability, gaps | -| `deployment` | Project has Dockerfile/K8s/CI configs | `references/deployment.md` | Container, CI/CD, IaC | -| `ui-components` | Frontend with component-based framework | `references/ui-components.md` | Component tree, design system | -| `state-routing` | Frontend SPA with state management | `references/state-routing.md` | State, routes, data fetching | -| `build-bundle` | Frontend or Node.js with custom build config | `references/build-bundle.md` | Build tool, bundling, optimization | +--- + +## Workflow + +1. **Load context** — source/target framework, existing KG, `guidelines/-to-/`, and any **user-declared seams** (cut points the user specified). +1b. **Load extraction signals** — read `references/extraction-signals.md` and map discovered signals into the structured artifacts. +1c. **Produce global prose views** — alongside the structured per-unit artifacts, emit `project-structure.md` (functional domains, layers, project type), `tech-stack.md` (frameworks, deps, runtime versions, migration blockers), and `data-model.md` (entity inventory + key-entities summary) per their reference schemas. These global views are consumed by creating-implementation-plan, feature-inventory, and the spec-quality gate; the structured YAML artifacts do not replace them. +2. **Build `unit_graph.yaml`** (spine). Resolve `exported_signature` from public signatures only. Seed `shared_modules.yaml` same pass; flag god-class + reference-cliff candidates. +2b. **Build `migration_boundary.yaml`** — infer user intent, acceptance criteria, cleanup requirement, and the smallest runtime-reachable rewrite boundary. Populate `must_rewrite`, `copy_as_is`, `legacy_allowed_to_remain`, and `defer_cleanup`. Only choose `full_rewrite` when user intent or technical evidence requires it; do not equate `source_anchors` with rewrite targets. +3. **Per-unit files — IMMEDIATELY after unit_graph, before global tables.** For EVERY unit listed in `unit_graph.yaml`, create `units//behavior.yaml`, `units//bindings.yaml`, and `units//unit_decomposition.yaml`. Do not skip units. Do not create "representative samples". Do not defer to a later step. >~200 lines per file → re-examine the unit boundary. Populate `shared_refs` from subset whitelist. `unit_decomposition` sets `commit: false`. +3b. **Verify per-unit completeness before proceeding.** Run: count the units in `unit_graph.yaml` and count the `units/*/behavior.yaml` files. If they do not match, create the missing per-unit files NOW. Do not proceed to step 4 until every unit has all three files. +4. **Build `wire_contracts.yaml`** — outward edges; cross-ref unit_graph for external interfaces. +4b. **Build `cross_unit_state.yaml`** — scan medium patterns; pair across units only; per-row `must_confirm:runtime` on any unpaired flow. +4c. **Build `seams.yaml`** (skip if no declared or inferred seams exist) — emit every user-declared seam first (`source: declared`). Then add `inferred` seams from discovery signals. For each seam: record `frozen_side` + `frozen_side_rule` (always), and — where protocols differ — the `bridge_points` conversion design (mapping_rule + edge_cases + idempotency_retry + fallback). Add `frozen_contract` **only** when the migrating agent cannot read the frozen side's behavior from source (binary/private dependency, config/data-gated semantics, name-contradicts-behavior); when the frozen source is visible and self-explanatory, omit it — don't restate what the agent reads directly. Resolve declared/inferred conflicts toward declared. +4d. **Build the architecture index** — top-level architect artifact with an `Implementation Guide`. For each unit, list exact artifact paths, purpose of each file, how to filter global rows, and required completion evidence. Do not make it a prose-only summary. +5. **Self-check before completion** (hard — execute, do not skip): + - **Per-unit completeness gate (MUST execute):** Count units in `unit_graph.yaml` (`grep -c '^\s*- name:' artifacts/unit_graph.yaml`). Count per-unit behavior files (`ls artifacts/units/*/behavior.yaml | wc -l`). If counts do not match, list missing units and create their behavior.yaml, bindings.yaml, and unit_decomposition.yaml NOW. Do not report done until counts match. "Representative samples" or "most controllers follow identical patterns" is NOT acceptable — every unit gets all three files. + - Every unit in `unit_graph` has behavior/bindings/decomposition files. + - `migration_boundary.yaml` exists for rewrite/migration work; `must_rewrite` is the implementation scope; `source_anchors` are not treated as rewrite targets. + - The architecture index contains an `Implementation Guide` for every unit, with exact artifact paths, purpose, row-filter instructions, and completion evidence requirements. + - The architecture index explicitly states that it is not the full contract and implementation agents must follow the listed artifact paths before implementation. + - No `TBD` in `wire_contracts.yaml::target_contract`, `seams.yaml::frozen_contract` target form, or `seams.yaml::bridge_points[].mapping_rule`. + - No source file in `source_anchors` of multiple units. + - Every produced field maps to a Failure Mode Map row. + - `unit_decomposition.commit == false`. + - Every `shared_refs.used_fields ⊆ {f.name for f in shared_modules.fields}`. + - Every `cross_unit_state` flow with `pairing != matched` carries `must_confirm: runtime`. + - **Every `declared` seam present; every seam has a `frozen_side_rule`; `frozen_contract` present only where the frozen source is invisible/unrecoverable; every `protocol_shift != null` seam has ≥1 `bridge_point` with concrete `mapping_rule` (no `TBD`).** + +## Rules + +- No prose narrative artifacts. Reasoning lives in `notes:` / `rationale:`. +- No stable IDs. `source_loc: path:line` is the identifier. +- No tests / build / deploy / infra coverage. No standalone risk register. No `target_idiom.yaml`. +- Per-unit files capped at ~200 lines. Larger → split. +- `TBD` forbidden in wire contract `target_contract`, seam `frozen_contract` target form, and seam `mapping_rule`. +- `unit_decomposition.yaml` MUST set `commit: false`. +- Factual numbers (line numbers, counts, lists) recorded as-is. Quality/cohesion values MUST be tool-computed with provenance; inventing scores is a hard failure. +- A **`declared` seam is authoritative** — design may not overrule it; an `inferred` seam is a candidate. +- The **frozen side of a seam MUST NOT be refactored** in the migrating phase; the bridge adapts to it, not the reverse. +- **Implementation scope comes from `migration_boundary.yaml::must_rewrite`**, not from `unit_graph.source_anchors`, all files of the old framework, or inventory lists. `source_anchors` prove behavior exists; they do not mandate rewriting that file. +- Classification lists are vocabularies for judgment, not CI-enforced enums. +--- +## Failure Mode Map + +| # | Failure mode | Prevented by | +|---|---|---| +| 1 | Dropped side-effect | `behavior.yaml::side_effects[must_preserve]` | +| 2 | Dropped framework binding | `bindings.yaml::bindings[must_appear_in_target]` | +| 3 | Hallucinated target API | `guidelines/-to-/` (out of scope) | +| 4 | Broken caller (signature unsync) | `unit_graph.yaml::depends_on` + `exported_signature` | +| 5 | Dead-code removal of reflection/DI class | `unit_graph.yaml::dynamic_entrypoints` | +| 6 | Wire contract break | `wire_contracts.yaml::stability:frozen + target_contract` | +| 7 | Tx boundary lost | `behavior.yaml::concurrency.tx_boundary` | +| 8 | Cross-language semantic gotcha | `wire_contracts.yaml::semantic_divergence` | +| 9 | Missing runtime config | `bindings.yaml::runtime_config[must_appear_in_target]` | +| 10 | Significant branch dropped | `behavior.yaml::branches[must_preserve]` | +| 11 | Error contract drift | `behavior.yaml::error_paths[contract + must_preserve]` | +| 12 | Shared module duplicated/lost | `shared_modules.yaml::migration_strategy` | +| 13 | Concurrency model mismatch | `behavior.yaml::concurrency.model` | +| 14 | Implicit cross-unit state lost | `cross_unit_state.yaml::flows[must_preserve]` | +| 15 | Static pairing missed dynamic key / external writer | `cross_unit_state.yaml::pairing + must_confirm:runtime` | +| 16 | God-class field drift / hallucinated fields | `shared_modules.yaml::god_class + shared_refs.used_fields ⊆` | +| 17 | Premature commit to target unit count | `unit_decomposition.yaml::commit:false + candidate_splits` | +| 18 | Split candidate without driver/rationale | `unit_decomposition.yaml::candidate_splits[].drivers + rationale` | +| 19 | Fabricated score/confidence misleads design | Principle 6 + self-check: no composite_score | +| 20 | **Partial-migration cut breaks at the seam (an *unreadable* frozen-side semantic — binary dep, config-gated, or name-contradicts-behavior — never recorded)** | **`seams.yaml::frozen_contract[must_preserve]`, conditional: only when source is invisible/unrecoverable** | +| 21 | **Frozen side refactored, breaking un-migrated peers** | **`seams.yaml::frozen_side_rule`** | +| 22 | **Protocol-shift conversion left to the migrating agent's guess (wrong mapping/edge cases)** | **`seams.yaml::bridge_points[mapping_rule + edge_cases + idempotency_retry + fallback]`** | +| 23 | **User-specified cut point silently overruled by analyze** | **`seams.yaml::source:declared` authoritative rule** | +| 24 | **Inventory-driven over-rewrite: every discovered framework file or `source_anchor` becomes an implementation task, even though a smaller runtime boundary satisfies acceptance** | **`migration_boundary.yaml::{strategy,must_rewrite,legacy_allowed_to_remain}` + rule: source_anchors are not rewrite targets** | +| 25 | **User asked for clean/full rewrite but analyze silently leaves legacy runtime residue** | **`migration_boundary.yaml::{user_intent.cleanup_required,full_rewrite_reason}`** | + +## NOT Included + +- Test coverage map — tester / runtime-validation +- Build / packaging / deploy topology — `analyzing-operations` +- Performance baseline — cutover phase +- Standalone risk register — inline `notes` / `stability` +- Architecture summary prose — implementation agents need source-anchored contracts, not prose-only summaries +- Idiom mapping — `guidelines/-to-/` +- Function-level call graph beyond unit boundaries — `exported_signature` suffices +- **Cohesion metrics / co-access clusters (LCOM4/TCC)** — structural numbers did not change design decisions. God-class smells live on `shared_modules.yaml::split_candidate`. +- Pure syntax migration (Py2→3, Java 8→17) +- **Target unit count commitment** — design phase +- **Aggregate / BC / VO decisions, domain renames, migration sequencing** — design phase + human EventStorming +- **Composite/priority scores, decision gate ratios** — design weighs evidence with full context diff --git a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/api-surface.md b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/api-surface.md deleted file mode 100644 index 4f8045f..0000000 --- a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/api-surface.md +++ /dev/null @@ -1,10 +0,0 @@ -Analyze all API endpoints in the codebase. Focus on: -- REST endpoints (paths, HTTP methods, parameters, response types) -- GraphQL schemas/resolvers (if present) -- gRPC service definitions (if present) -- API versioning strategy -- Authentication/authorization on endpoints -- Request/response DTOs and serialization format -- OpenAPI/Swagger specs (if present) - -Output: `./api-surface.md` diff --git a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/architecture-index.md b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/architecture-index.md new file mode 100644 index 0000000..d88ca9a --- /dev/null +++ b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/architecture-index.md @@ -0,0 +1,62 @@ +# Architecture Index Artifact + +This reference is loaded from `SKILL.md` when producing the top-level architecture/index artifact for implementation agents. + +### Architecture index artifact — implementation guide + +The top-level architect artifact is an **implementation index**, not a prose summary. Its filename should be `architecture_index.md` in the artifact root. Implementation agents discover it by this name. + +It MUST include an `Implementation Guide` section. For every implementation unit, list: +- assigned unit name plus external trigger (route, API, message, job, CLI command, or public surface) +- exact artifact paths to read for that unit, expressed relative to the artifact root +- what each artifact is used for: behavior, bindings, wire contracts, shared modules, cross-unit state, seams, migration boundary, or split candidates +- how to filter global rows for the unit (for example by `used_by_units`, `flows`, `cut_between`, or equivalent fields) +- completion evidence required from the implementation agent: artifact paths read, implemented `must_preserve` items, unresolved/deferred contracts, and tests/build/runtime evidence + +The index MUST say explicitly: "This index is not the full contract. Do not implement from this file alone; follow the artifact paths below." + +Example shape (file names are illustrative; use the actual produced paths): + +```markdown +## Implementation Guide + +### Global artifacts +- `` + - who reads: all implementation workers + - use for: unit boundary, entrypoints, dependencies, exported signatures, shared refs + - how to consume: find your assigned unit; follow its source anchors, shared refs, and dynamic entrypoints +- `` + - who reads: all implementation workers + - use for: implementation scope (must_rewrite vs copy_as_is vs legacy_allowed_to_remain) + - how to consume: check must_rewrite for your unit's files; source_anchors are NOT rewrite targets +- `` + - who reads: workers touching external/API calls + - use for: request/response/error contracts, semantic divergence warnings + - how to read: filter rows where unit matches your assigned unit +- `` + - who reads: workers whose unit references shared code + - use for: migration strategy, field subset whitelist, god-class awareness + - how to read: filter rows where used_by_units includes your unit +- `` + - who reads: workers whose unit reads or writes implicit shared state + - use for: session/ThreadLocal/static state flows, must_confirm:runtime flags + - how to read: filter flows where writer.unit or reader.unit matches your unit +- `` (when present) + - who reads: workers whose unit touches a migration cut point + - use for: frozen side rules, bridge point mapping, declared vs inferred seam authority + - how to read: filter cuts where cut_between includes your unit + +### Unit: +- external trigger: +- must read: + - `` — use for side effects, branches, loading/error states, user-visible behavior + - `` — use for selectors, route/query/runtime bindings, framework wiring + - `` — use for optional split candidates only; do not treat as required target structure +- relevant global rows: + - `` rows tied to `` + - `` rows where used_by_units includes `` + - `` flows touching `` + - `` cuts touching `` +- before DONE report: artifacts_read, implemented_must_preserve, unresolved_or_deferred, verification evidence +``` + diff --git a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/architecture-summary.md b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/architecture-summary.md deleted file mode 100644 index b7aec20..0000000 --- a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/architecture-summary.md +++ /dev/null @@ -1,13 +0,0 @@ -If `setup_artifacts.knowledge_graph_dir` is null or the path does not exist, skip this step silently — do not report an error, continue with direct source analysis instead. - -Otherwise, read `knowledge-graph.json` from `setup_artifacts.knowledge_graph_dir`. Focus on: -- Key classes and their roles -- Inter-module dependencies -- Core architectural patterns (layering, DI, transaction scope) -- Tightly coupled areas (high fan-in/fan-out, classes with many dependencies) - -> ⚠️ **Document the existing architecture only.** Do not suggest target architecture or refactoring approaches. - -Distill into a concise markdown summary (do NOT reproduce the full JSON). - -Output: `./architecture-summary.md` diff --git a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/behavior.md b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/behavior.md new file mode 100644 index 0000000..43e21a6 --- /dev/null +++ b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/behavior.md @@ -0,0 +1,52 @@ +# behavior.yaml — Per-Unit Behavior Contract + +The heavyweight per-unit artifact. Records all externally observable behavior: side effects, conditional branches, error paths, and concurrency semantics. Implementation agents use this as the primary fidelity contract — every `must_preserve: true` item must appear in the target. + +Per-unit file: `units//behavior.yaml`. + +## Schema + +```yaml +unit: +side_effects: + - source_loc: "" + effect: "" + must_preserve: # true = must appear in target (Failure Mode 1) +branches: + - source_loc: "" + condition: "" + behavior: "" + must_preserve: # true = branch path must be preserved (Failure Mode 10) +error_paths: + - source_loc: "" + trigger: "" + outcome: "" + contract: "" + must_preserve: # true = error contract must be preserved (Failure Mode 11) +concurrency: + model: + # the concurrency model used by this unit (Failure Mode 13) + tx_boundary: # transaction scope (Failure Mode 7) + source_loc: "" + scope: "" + isolation: "" + must_preserve: +``` + +## Key Fields + +- **`side_effects[].must_preserve`**: when true, the effect must exist in target code. Prevents Failure Mode 1 (dropped side-effect). Common examples: audit log writes, notification sends, cache invalidations. +- **`branches[].must_preserve`**: when true, the conditional path must be replicated. Prevents Failure Mode 10 (significant branch dropped). Focus on user-visible branching — not every `if` statement. +- **`error_paths[].contract`**: the external-facing error contract (HTTP status code, error response shape, exception type thrown to callers). Prevents Failure Mode 11 (error contract drift). May be empty for internal-only error handling. +- **`concurrency.model`**: the threading/async model. Prevents Failure Mode 13 (concurrency model mismatch). Critical when migrating between sync and async frameworks. +- **`concurrency.tx_boundary`**: transaction scope — which operations are atomic. Prevents Failure Mode 7 (tx boundary lost). Record the actual scope, not just "uses transactions". + +## Size Cap + +Per-unit behavior files are capped at ~200 lines. If a unit's behavior exceeds this, re-examine the unit boundary — it may need splitting (see `unit_decomposition.yaml`). + +## Self-Check + +- Every unit in `unit_graph.yaml` has a `behavior.yaml` file. +- Every `must_preserve: true` item has a `source_loc`. +- `concurrency` block is present when the unit uses transactions, async patterns, or thread pools. diff --git a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/bindings.md b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/bindings.md new file mode 100644 index 0000000..be7d78e --- /dev/null +++ b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/bindings.md @@ -0,0 +1,50 @@ +# bindings.yaml — Per-Unit Framework Wiring & Runtime Config + +Records framework-specific wiring (annotations, XML config, DI registrations, route declarations) and externalized runtime configuration that must appear in the target. Per-unit file: `units//bindings.yaml`. + +## Schema + +```yaml +unit: +bindings: + - type: + name: "" + source_loc: "" + target: "" + must_appear_in_target: # true = implementation must wire this in target framework + notes: "" +runtime_config: + - key: "" + source_loc: "" # where it's read + source: + default_value: "" + must_appear_in_target: + notes: "" +``` + +## Key Fields + +- **`bindings[].must_appear_in_target`**: when true, the implementation agent must create equivalent wiring in the target framework. Prevents Failure Mode 2 (dropped framework binding). The *form* will differ (e.g., Struts XML → Spring Boot annotation), but the *effect* must be preserved. +- **`bindings[].type`**: what kind of framework wiring. Helps the implementation agent find the right target-framework equivalent. +- **`runtime_config[].must_appear_in_target`**: when true, this config must be externalized in the target. Prevents Failure Mode 9 (missing runtime config). + +## Scope Boundary + +- **Included**: framework annotations/decorators, XML/YAML config bindings, DI container registrations, route/filter/interceptor/listener declarations, property/env-var references. +- **Excluded**: business logic (→ `behavior.yaml`), external API contracts (→ `wire_contracts.yaml`), ORM entity mappings that are purely internal data access (unless they define a cross-service data contract). + +## Empty Bindings + +When a unit has no framework wiring (rare — usually means it's a pure domain unit), produce `bindings: []` with a `reason` field explaining why: + +```yaml +unit: pure_domain_calculator +bindings: [] +reason: "No framework annotations or DI wiring — pure computation with no framework coupling." +runtime_config: [] +``` + +## Self-Check + +- Every unit in `unit_graph.yaml` has a `bindings.yaml` file (even if `bindings: []`). +- Every `must_appear_in_target: true` binding has a non-empty `name` and `source_loc`. diff --git a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/build-bundle.md b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/build-bundle.md deleted file mode 100644 index 080d3be..0000000 --- a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/build-bundle.md +++ /dev/null @@ -1,9 +0,0 @@ -Analyze build tooling and bundling. Focus on: -- Build tool configuration (Webpack, Vite, Rollup, esbuild, Turbopack, etc.) -- Code splitting strategy -- Asset handling (images, fonts, SVGs) -- Environment-specific builds (dev/staging/prod) -- Build plugins and custom transformations -- Bundle size and optimization - -Output: `./build-bundle.md` diff --git a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/business-logic-extraction.md b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/business-logic-extraction.md deleted file mode 100644 index 4edaf20..0000000 --- a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/business-logic-extraction.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -name: Business Logic Extraction -description: Extract and catalog business logic from source codebase for rewrite migration mode. -mode: rewrite ---- - -## Overview - -This skill systematically identifies, extracts, and documents all business logic from a source codebase to enable accurate rewrite in a new technology stack. The goal is to ensure **functional equivalence** - the rewritten application produces the same business outcomes. - -## User Input - -```text -``` - -You **MUST** consider the user input before proceeding (if not empty). - -## When to Use - -- **Mode**: REWRITE only -- **Phase**: Planning Phase 0 (Research) — invoked by planning skill -- **Prerequisites**: Constitution defined, Knowledge graph available - -## Extraction Process - -### Step 1: Extract Business Logic Units - -For each business logic unit, document: - -```yaml -business_logic_unit: - id: "BL-001" - name: "Order Total Calculation" - category: "calculation" - source_location: "src/main/java/com/example/service/OrderService.java:45-78" - source_methods: ["calculateTotal", "applyDiscount", "calculateTax"] - - description: | - Calculates the total order amount including: - - Item subtotals - - Tax calculation based on region - - Discount application - - Shipping cost - - inputs: - - name: "orderItems" - type: "List" - description: "Items in the order with quantity and price" - - name: "customerRegion" - type: "String" - description: "Customer's geographic region for tax calculation" - - name: "discountCode" - type: "String" - optional: true - description: "Optional promotional discount code" - - outputs: - - name: "orderTotal" - type: "BigDecimal" - description: "Final order total after all calculations" - - name: "taxAmount" - type: "BigDecimal" - description: "Calculated tax amount" - - dependencies: - - "TaxService - for tax rate lookup" - - "DiscountService - for discount validation" - - business_rules: - - "Tax is calculated on subtotal before discount" - - "Maximum discount is 50% of subtotal" - - "Free shipping for orders over $100" - - # Behavioral specification: precise branch-level logic extracted from source code - # Each entry documents one conditional branch or behavioral path - behavioral_spec: - - condition: "orderItems.isEmpty()" - action: "return BigDecimal.ZERO" - branch_type: "early_return" - - condition: "discountCode != null && discountService.isValid(discountCode)" - action: "subtotal * (1 - discount.percentage / 100)" - constraint: "discountedAmount <= subtotal * 0.5" - - condition: "discountCode != null && !discountService.isValid(discountCode)" - action: "ignore discount, use full subtotal" - error_response: "none (silent ignore)" - - condition: "subtotal > 100.00" - action: "shipping = 0" - - condition: "subtotal <= 100.00" - action: "shipping = flatShippingRate" - - # Data validation rules from source code - validation_rules: - - field: "orderItems" - rules: ["NOT_NULL", "NOT_EMPTY"] - - field: "orderItems[].quantity" - rules: ["MIN: 1", "MAX: 999"] - - field: "orderItems[].price" - rules: ["NOT_NULL", "MIN: 0.01"] - - field: "discountCode" - rules: ["OPTIONAL", "PATTERN: ^[A-Z0-9]{6,12}$"] - - # Side effects produced by this logic - side_effects: - - "Audit log entry created for discount application" - - "Order total cached in session" - - edge_cases: - - "Empty order returns zero total" - - "Invalid discount code is ignored, not error" - - "International orders have different tax rules" - - test_scenarios: - - description: "Basic order with tax" - input: "3 items, US region, no discount" - expected_output: "subtotal + 8.5% tax" - - description: "Order with discount" - input: "3 items, discount code 'SAVE20'" - expected_output: "subtotal - 20% + tax" - - description: "Empty order" - input: "0 items" - expected_output: "BigDecimal.ZERO" - - description: "Excessive discount capped" - input: "1 item $10, discount 80%" - expected_output: "subtotal - 50% (capped) + tax" -``` - -### Step 4: Generate Business Logic Inventory - -Create `FEATURE_DIR/business-logic-inventory.md`: - -```markdown -# Business Logic Inventory - -**Source Application**: [APP_NAME] -**Extraction Date**: [DATE] -**Total Business Logic Units**: [COUNT] - -## Summary by Category - -| Category | Count | Complexity | -|----------|-------|------------| -| Validation | 12 | Low-Medium | -| Calculation | 8 | Medium-High | -| Workflow | 5 | High | -| Transformation | 15 | Low | -| Integration | 6 | Medium | -| Rules | 10 | Medium | - -## Business Logic Units - -### Validation Logic - -#### BL-001: Order Validation -- **Source**: `OrderService.java:23-45` -- **Purpose**: Validates order before processing -- **Inputs**: Order object -- **Outputs**: ValidationResult -- **Rules**: [list rules] -- **Rewrite Notes**: Use Jakarta Bean Validation - -[Continue for each unit...] - -## Cross-Cutting Concerns - -### Authentication/Authorization -- Location: [files] -- Pattern: [describe pattern] -- Rewrite approach: Use Spring Security - -### Transaction Management -- Location: [files] -- Pattern: [describe pattern] -- Rewrite approach: Use @Transactional - -### Error Handling -- Location: [files] -- Pattern: [describe pattern] -- Rewrite approach: Use @ControllerAdvice - -## Dependencies Map - -```mermaid -graph TD - A[OrderController] --> B[OrderService] - B --> C[TaxService] - B --> D[DiscountService] - B --> E[InventoryService] -``` - -## Rewrite Priority - -| Priority | Business Logic | Reason | -|----------|---------------|--------| -| P1 | Core workflows | Essential for MVP | -| P2 | Calculations | Business critical | -| P3 | Validations | Can use framework defaults initially | -| P4 | Integrations | Can be stubbed initially | -``` - -## Output Artifacts - -| Artifact | Path | Purpose | -|----------|------|---------| -| Business Logic Inventory | `FEATURE_DIR/business-logic-inventory.md` | Master list of all business logic | - -## Key Rules - -- **Completeness**: Every piece of business logic must be documented -- **No Implementation Details**: Focus on WHAT, not HOW (that's for target design) -- **Testability**: Each unit must have clear inputs, outputs, and test scenarios -- **Traceability**: Link to source code locations for reference during implementation -- **Source Methods**: Every BL unit MUST include `source_methods` listing the exact method names — these are used by the tasks skill to generate `[Source:]` annotations and by the implementation skill for source-anchored implementation -- **Behavioral Specification**: For each BL unit, extract `behavioral_spec` documenting every conditional branch, validation check, and error path from the source code. The implementation agent uses this to achieve branch-level parity. -- **Validation Rules**: Document `validation_rules` with exact field-level constraints extracted from source validation logic (annotations, XML validators, programmatic checks) -- **Side Effects**: Document all `side_effects` (database writes, notifications, cache updates, audit logs) so they are not lost during rewrite diff --git a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/consumption-contract.md b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/consumption-contract.md new file mode 100644 index 0000000..ff25f7a --- /dev/null +++ b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/consumption-contract.md @@ -0,0 +1,104 @@ +# Consumption Contract — How Downstream Agents Read Architecture Artifacts + +This reference defines how implementation/design/review agents consume the artifacts produced by `analyzing-architecture`. The architect produces; downstream reads by following this contract. + +## Artifact Root + +All paths below are relative to `{artifact_root}/` (typically `.github/modernize/rearchitecture/artifacts/`). + +## Reading Strategy by Role + +### Implementation agent (assigned unit X) + +**Must read before writing any code:** + +1. `unit_graph.yaml` — filter to unit X: + - `source_anchors` → source files to understand (NOT rewrite targets — see `migration_boundary.yaml::must_rewrite` for scope) + - `depends_on` + `exported_signature` → call sites to preserve; `stability: frozen` signatures must keep exact shape in target + - `dynamic_entrypoints` → do not dead-code-eliminate these + - `shared_refs` → per-unit subset of shared modules this unit uses; `used_fields` names must ⊆ `shared_modules[module].fields[].name` + +2. `migration_boundary.yaml` + - `must_rewrite` → the files/modules in implementation scope + - `copy_as_is` → leave untouched + - `legacy_allowed_to_remain` → acceptable residue + - Rule: implementation scope = `must_rewrite`, NOT `source_anchors` + +3. `shared_modules.yaml` — rows where `used_by_units` includes X: + - `migration_strategy` → how to handle (extract, wrap, split) + - `shared_refs.used_fields` → only these fields are your concern (subset whitelist) + - God-class entries → respect `split_candidate` guidance + +4. `units/X/behavior.yaml` + - `side_effects` where `must_preserve: true` → each must appear in target + - `branches` where `must_preserve: true` → each branch path preserved + - `error_paths` → preserve `contract` and `must_preserve` items + - `concurrency.tx_boundary` → replicate transaction scope + +5. `units/X/bindings.yaml` + - `bindings` where `must_appear_in_target: true` → wire in target framework + - `runtime_config` where `must_appear_in_target: true` → externalize config + +**Filter remaining global artifacts for unit X:** + +6. `wire_contracts.yaml` — rows where unit field matches X: + - `stability: frozen` → preserve exact contract shape + - `target_contract` → required target-side signature + - `semantic_divergence` → cross-language gotchas to handle + +7. `cross_unit_state.yaml` — flows where `writer.unit == X` or `reader.unit == X`: + - `must_preserve: true` → replicate the state-passing mechanism + - `pairing != matched` + `must_confirm: runtime` → flag for runtime verification + +8. `seams.yaml` — cuts touching X: + - `source: declared` → authoritative, do not change frozen side + - `frozen_side_rule` → which side you must not modify + - `bridge_points` → use `mapping_rule` for conversion; handle `edge_cases` + - `frozen_contract` (when present) → the frozen side's behavior you cannot read from source + +**Optional (do not treat as binding):** + +9. `units/X/unit_decomposition.yaml` + - `candidate_splits` — advisory only (`commit: false`) + - Design may have already resolved these; check design artifacts first + +### Design agent + +1. Read `unit_graph.yaml` (all units) — unit count, dependencies, boundaries +2. Read `units/*/unit_decomposition.yaml` — candidate splits + drivers +3. Read `shared_modules.yaml` — god-class entries inform split decisions +4. Read `seams.yaml` — declared seams constrain design choices +5. Design owns: final unit count, split decisions, sequencing, domain naming + +### Review / gate agent + +Verify completeness by checking: +- `ls units/*/behavior.yaml | wc -l` == unit count in `unit_graph.yaml` +- Every unit has `bindings.yaml` and `unit_decomposition.yaml` +- `migration_boundary.yaml` exists (for rewrite/migration work) +- Architecture index contains `Implementation Guide` with per-unit entries +- Architecture index states it is not the full contract +- No `TBD` in `wire_contracts.yaml::target_contract`, `seams.yaml::frozen_contract` target form, or `seams.yaml::bridge_points[].mapping_rule` +- No source file appears in `source_anchors` of multiple units +- Every `unit_decomposition.yaml` has `commit: false` +- Every `shared_refs[].used_fields ⊆ {f.name for f in shared_modules[module].fields}` +- Every `cross_unit_state` flow with `pairing != matched` carries `must_confirm: runtime` +- Every `declared` seam present; every seam has `frozen_side_rule` +- Every `protocol_shift != null` seam has ≥1 `bridge_point` with concrete `mapping_rule` (no TBD) + +## Relationship to Architecture Index + +The **architecture index** (produced artifact) is a run-specific navigation file: it lists exact paths and per-unit reading instructions for a specific codebase's artifacts. + +This **consumption contract** (reference file) defines the general field-level semantics: what each field means, which are hard contracts, how to filter global rows. Implementation agents use both: +1. Architecture index → find artifact paths for their assigned unit +2. Consumption contract → understand field semantics and consumption rules + +## Key Rules for Consumers + +1. **`source_anchors` ≠ rewrite targets.** Implementation scope comes from `migration_boundary.yaml::must_rewrite`. +2. **`must_preserve` / `must_appear_in_target` are hard contracts.** Missing one = failure mode triggered (see Failure Mode Map in SKILL.md). +3. **`commit: false` in unit_decomposition is real.** Do not treat candidate splits as decided structure. +4. **`declared` seams are authoritative.** Do not refactor the frozen side. +5. **Filter global artifacts to your unit.** Do not read all rows; use unit-name matching fields (`used_by_units`, `unit`, `writer.unit`/`reader.unit`, `cut_between`). +6. **Architecture index is a navigation aid, not the full contract.** Always follow the artifact paths it lists and read the actual YAML files. diff --git a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/cross-unit-state.md b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/cross-unit-state.md new file mode 100644 index 0000000..46561b5 --- /dev/null +++ b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/cross-unit-state.md @@ -0,0 +1,49 @@ +# cross_unit_state.yaml — Implicit Shared-State Flows + +Records implicit state passing between units: session attributes, ThreadLocal, SSO tokens, request-scoped data, static/singleton state, framework-managed context. These are invisible contracts that break silently when one side is migrated. + +## Schema + +```yaml +flows: + - name: "" + medium: + key: "" + writer: + unit: + source_loc: "" + reader: + unit: # different unit than writer + source_loc: "" + pairing: + # matched: both writer and reader found in analyzed units + # unmatched-reader: reader found but writer not in any analyzed unit + # unmatched-writer: writer found but reader not in any analyzed unit + # dynamic-key: key is constructed dynamically; static analysis cannot pair + # external-writer: state written by external system (SSO, reverse proxy, etc.) + must_preserve: + must_confirm: # required when pairing != matched + verification_hint: "" + notes: "" +``` + +## Key Fields + +- **`medium`**: how state is passed. Critical for migration — different target frameworks handle these differently (e.g., `threadlocal` may not exist in async/reactive targets). +- **`pairing`**: whether static analysis found both ends of the flow. + - `matched` — both sides identified, flow is fully understood. + - `unmatched-reader` / `unmatched-writer` — one end missing from analysis. Requires `must_confirm: runtime`. + - `dynamic-key` — key is computed at runtime, cannot statically pair. Requires `must_confirm: runtime`. + - `external-writer` — state injected by something outside the codebase (SSO provider, reverse proxy headers, etc.). Requires `must_confirm: runtime`. +- **`must_confirm: runtime`**: hard flag — this flow must be verified with runtime testing because static analysis cannot guarantee correctness. Prevents Failure Mode 15. +- **`must_preserve`**: when true, the state-passing mechanism must be replicated in the target. Prevents Failure Mode 14. + +## Filter Key + +Implementation agent for unit X reads flows where `writer.unit == X` or `reader.unit == X`. + +## Self-Check + +- Every flow with `pairing != matched` carries `must_confirm: runtime`. +- Every flow has valid `writer.unit` and `reader.unit` that exist in `unit_graph.yaml` (or are marked external). +- No duplicate flows (same writer + reader + key). diff --git a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/deployment.md b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/deployment.md deleted file mode 100644 index 4f1bcd6..0000000 --- a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/deployment.md +++ /dev/null @@ -1,9 +0,0 @@ -Analyze deployment configuration. Focus on: -- Dockerfiles and container configuration -- Kubernetes manifests / Helm charts -- CI/CD pipeline definitions (GitHub Actions, Jenkins, GitLab CI, etc.) -- Environment variables and secrets management -- Infrastructure as Code (Terraform, CloudFormation, etc.) -- Monitoring/logging configuration - -Output: `./deployment.md` diff --git a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/extraction-signals.md b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/extraction-signals.md new file mode 100644 index 0000000..86cd75a --- /dev/null +++ b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/extraction-signals.md @@ -0,0 +1,129 @@ +# Extraction Signals + +Use this reference as a signal checklist while producing the structured architecture artifacts. Do not produce prose inventory reports. + +## Signal → artifact map + +```text +signal area write findings into +---------------------- ------------------------------------------------------------ +project structure unit_graph.yaml, shared_modules.yaml, migration_boundary.yaml +state and routing unit_graph.yaml, bindings.yaml, cross_unit_state.yaml, behavior.yaml +UI components unit_graph.yaml, bindings.yaml, behavior.yaml, shared_modules.yaml +business logic behavior.yaml, wire_contracts.yaml, cross_unit_state.yaml +API surface wire_contracts.yaml +integration points wire_contracts.yaml, seams.yaml, cross_unit_state.yaml +data model wire_contracts.yaml, bindings.yaml, shared_modules.yaml, cross_unit_state.yaml +tech stack bindings.yaml, wire_contracts.yaml, migration_boundary.yaml +``` + +## Project structure signals + +Look for: +- top-level modules, packages, apps, and deployable boundaries +- framework entrypoints: `main`, routes, web descriptors, Vite/Next/GWT config, Struts/Spring config, CLI commands, scheduled jobs +- functional areas and domains +- layer structure when it affects unit boundaries +- generated, build, or vendor directories to exclude from source anchors + +Record entrypoints, routes/pages/jobs/CLI/API surfaces, module boundaries, dependencies, exported signatures, shared files/packages, and runtime-reachable files. + +## State and routing signals + +Look for: +- router config, URL patterns, route guards, redirects +- UI state stores, session/local storage, cookies, request/session attributes, thread/static/framework implicit state +- event handlers that trigger route or state changes +- dynamic route construction and framework conventions + +Record route declarations, route params, query params, UI event bindings, framework state bindings, cross-unit state flows, user-visible navigation behavior, redirects, loading/error states, and branch-specific outcomes. + +## UI component signals + +Look for: +- page/component tree only where it affects unit boundaries or shared module decisions +- event handlers and data flow +- forms, validation, error states, loading states +- visible text/selectors relied on by tests or users + +Record UI pages/components that are externally triggerable or unit boundaries, props/events/selectors/template bindings, framework directives, data-testid/test-visible selectors, runtime config, user actions, visible states, conditional rendering, validation/error/loading behavior, side effects, and shared UI utilities/components/hooks/stores. + +## Business logic signals + +Look for: +- externally triggered behavior in the unit's source anchors and directly called domain/service methods +- conditional paths, validation branches, early returns, redirect/navigation decisions +- writes, notifications, cache/session mutations, audit logs, external calls triggered by behavior +- exceptions, validation failures, fallback paths, user-visible errors, HTTP/status outcomes +- async jobs, polling, transactions, locks, retries, timeouts +- business state written by one unit and read by another + +Record each behavior with `source_loc`, `must_preserve`, and target evidence expectations where applicable. Prefer branch-level contracts over prose descriptions. Do not add rewrite priority, target framework suggestions, or implementation approach. + +Example shape inside `units//behavior.yaml`: + +```yaml +unit: order_checkout +branches: + - source_loc: src/order/CheckoutAction.java:42 + condition: "cart.isEmpty()" + behavior: "return to cart page with validation message" + must_preserve: true +side_effects: + - source_loc: src/order/CheckoutService.java:88 + effect: "creates audit log entry after successful payment authorization" + must_preserve: true +error_paths: + - source_loc: src/order/PaymentClient.java:117 + trigger: "payment gateway timeout" + outcome: "surface retryable checkout error; order remains pending" + must_preserve: true +``` + +## API surface signals + +Look for: +- REST/SOAP/GraphQL/gRPC routes, methods, params, request bodies, response bodies, status/error contracts +- public RPC/service methods, CLI inputs/outputs, web routes, form posts +- auth/authorization requirements that are part of the wire contract +- DTO serialization names and versioning rules +- existing OpenAPI/Swagger/proto/schema files + +For each contract, include source locations and whether the contract is frozen, must be preserved, or may change by user intent. + +## Integration point signals + +Look for: +- external HTTP/REST/SOAP client calls +- message producers and handlers: Kafka, RabbitMQ, SQS, JMS, etc. +- third-party SDKs: payment, email/SMS, OAuth, analytics +- file transfer/storage calls: S3, FTP/SFTP, NFS +- resilience behavior: timeout, retry, circuit breaker, idempotency, service discovery + +Record HTTP/SOAP/gRPC/message/file/SDK contracts, auth, payload shape, retry/error semantics, deliberate partial-migration cuts where one side is frozen, and implicit state created by integrations. + +Do not document deployable runtime resources here; build/deploy/runtime topology belongs outside architecture analysis. + +## Data model signals + +Look for: +- entity/DTO/model classes and their source locations +- table/collection names, key fields, relationships, enum/string-value contracts +- validation rules and serialization names that must appear in the target +- dynamic model access patterns: `get("field")`, maps, reflection + +Record persisted schemas, external data contracts, ORM annotations/XML mappings, validation annotations, serialization aliases, framework binding names, shared DTO/entity/base-model classes, and implicit data passed through session/request/thread/static state. + +Avoid domain redesign, aggregate decisions, bounded-context decisions, or target schema recommendations. + +## Tech stack signals + +Look for: +- framework/runtime versions and plugins +- routing/UI/server framework conventions +- build tooling and module packaging only when it affects runtime reachability or migration boundary +- serialization, ORM, messaging, auth, validation, and i18n libraries + +Record framework wiring, annotations, XML/config bindings, runtime config, dependency-injection hooks, protocol/framework-specific contracts, relevant source/target idiom guide, and build/runtime constraints that genuinely force boundary expansion. + +Do not recommend target stack choices here. Record only existing facts and constraints. diff --git a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/infrastructure.md b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/infrastructure.md deleted file mode 100644 index f66662f..0000000 --- a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/infrastructure.md +++ /dev/null @@ -1,11 +0,0 @@ -Analyze runtime resource dependencies and test infrastructure requirements. Focus on: -- **Database dependencies**: DB type, version, schema management tool (Flyway/Liquibase/manual), connection pool config -- **Messaging**: message queues, event buses (Kafka, RabbitMQ, ActiveMQ, etc.) -- **Caching**: Redis, Memcached, in-process caches -- **External services**: third-party APIs, payment gateways, email services, OAuth providers -- **File storage**: local filesystem assumptions, S3, NFS mounts -- **Test execution requirements**: Which dependencies require a real service to run integration tests? Which use in-memory/mock alternatives? Is Docker/Testcontainers currently used? - -> ⚠️ **Document the existing infrastructure only.** Do not recommend target infrastructure choices or test strategies. - -Output: `./infrastructure.md` diff --git a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/integration-points.md b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/integration-points.md deleted file mode 100644 index 50d1414..0000000 --- a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/integration-points.md +++ /dev/null @@ -1,10 +0,0 @@ -Analyze external integrations and service boundaries. Focus on: -- External HTTP/REST/SOAP client calls -- Message queue producers/consumers (Kafka, RabbitMQ, SQS, etc.) -- Cache usage (Redis, Memcached, in-memory) -- File storage (S3, local filesystem, FTP) -- Email/SMS/notification services -- Third-party SDK integrations -- Service discovery and circuit breaker patterns - -Output: `./integration-points.md` diff --git a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/migration-boundary.md b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/migration-boundary.md new file mode 100644 index 0000000..34dbc55 --- /dev/null +++ b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/migration-boundary.md @@ -0,0 +1,49 @@ +# Migration Boundary Artifact + +This reference defines `migration_boundary.yaml`, the rewrite scope contract consumed by planning and implementation. + +### `migration_boundary.yaml` — minimal runnable boundary + rewrite scope contract + +**Prevents**: inventory-driven over-rewrite — the implementation phase treats every discovered framework file or `source_anchor` as a rewrite target, even when acceptance can be satisfied by a smaller runtime-reachable cut. + +**Default policy**: choose the smallest runtime boundary that satisfies the user's acceptance criteria. Expand only when user intent or technical constraints require it. + +**Intent interpretation**: +- Distinguish **transformation acceptance** from **cleanup acceptance**. A migration/rewrite request defines the target behavior, runtime, interface, or deployment state; it does not automatically define a repository-hygiene goal. +- `rewrite/migrate/convert to `, `tests/e2e pass`, `preserve behavior` → `cleanup_required: false` and `strategy: minimal_runtime` by default. +- `cleanup_required: true` only when the user explicitly asks for removal or cleanliness (for example: remove the old stack, no legacy residue, no old runtime, clean rewrite, delete old implementation), or when cleanup is necessary to satisfy a concrete build/runtime/contract/packaging/deployment constraint. +- long-term maintainability/refactor language without clean-removal requirement → `strategy: phased`: first satisfy the target runtime/contract boundary, then defer cleanup. +- technical blockers may expand the boundary only with scoped evidence. Cite the specific mechanism that forces expansion: build graph, runtime loader, ABI/API contract, packaging rule, deployment topology, data ownership, or cutover constraint. Generic claims such as "old and new stacks cannot coexist" are insufficient. + +```yaml +user_intent: + raw_request: "Rewrite this Vue SPA to React 18; E2E tests pass." + inferred_acceptance: ["existing E2E tests pass", "preserve behavior"] + cleanup_required: false +strategy: minimal_runtime # minimal_runtime | full_rewrite | phased +runtime_reachable: # files reachable from the target runtime entrypoint after the cut + - src/client/main.js + - src/client/router/index.js +must_rewrite: # implementation scope; DAG consumes this list, not source_anchors + - path: src/client/main.js + reason: "target runtime entrypoint" + - path: src/client/App.vue + reason: "root component, Vue-specific SFC" + - path: src/client/router/index.js + reason: "Vue Router → React Router rewrite required" +copy_as_is: + - src/client/api/client.js + - src/client/utils/formatting.js +legacy_allowed_to_remain: # files may remain if not runtime-reachable and acceptance does not require cleanup + - src/client/views/LegacyView.vue + - src/client/components/LegacyWidget.vue +defer_cleanup: + - "Remove unused Vue SFCs after runtime cutover is verified." +full_rewrite_reason: null # required when strategy == full_rewrite +implementation_rule: > + Implementation tasks use must_rewrite plus copy_as_is as needed. + They MUST NOT infer rewrite scope from all source_anchors or all framework-specific files. +``` + +**Self-check**: `source_anchors` never used as rewrite scope; every `must_rewrite` row explains why it is runtime-reachable or required by acceptance; every `legacy_allowed_to_remain` row is either unreachable from the target entrypoint or explicitly deferred; `cleanup_required` is false unless explicitly requested by the user or forced by a concrete build/runtime/contract/packaging/deployment constraint; `full_rewrite_reason` present when `strategy: full_rewrite` and cites the specific forcing mechanism, not a generic coexistence claim. + diff --git a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/migration-risks.md b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/migration-risks.md deleted file mode 100644 index 383ac61..0000000 --- a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/migration-risks.md +++ /dev/null @@ -1,10 +0,0 @@ -Analyze the codebase for complexity and migration risk. Focus on: -- Business logic complexity per module (lines of code, cyclomatic complexity, coupling) -- Framework-specific patterns tightly intertwined with business logic (hard to extract) -- Session and auth patterns (how user state is managed, security enforcement points) -- Test coverage gaps in high-complexity areas -- Risk classification per module: LOW / MEDIUM / HIGH / CRITICAL - -> ⚠️ **Assess complexity and risk of the existing code only.** Do not suggest how to rewrite or refactor. - -Output: `./migration-risks.md` diff --git a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/seams.md b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/seams.md new file mode 100644 index 0000000..55fca86 --- /dev/null +++ b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/seams.md @@ -0,0 +1,58 @@ +# Seams Artifact + +This reference defines `seams.yaml`, the partial-migration cut-point and bridge-design contract. + +### `seams.yaml` — partial-migration cut points + bridge design + +**Prevents**: the dominant partial-migration failure — a migrated unit silently breaks where it meets the un-migrated remainder, because the *cut point*, *which side is frozen*, and the *conversion rule* were never recorded. wire_contracts records outward contracts and cross_unit_state records implicit state; **seams records the deliberate knife — where you cut, which side is frozen, and how the bridge converts across it.** + +**A seam is a one-place model of a cut.** Each seam answers: where is the cut, what is on each side, which side is frozen (must NOT be refactored), and — when the two sides speak different protocols/idioms — the exact conversion the bridge performs. + +**What a seam adds that reading the source does not.** Validated empirically (cargotracker routing closed-loop): when the frozen side's source is **visible**, any migrating agent that reads it recovers the behavioral contract on its own — re-stating it as a `frozen_contract` is redundant. The seam's irreducible value is the two things grep/read cannot give you: +- `frozen_side_rule` — the *decision* that this side is frozen and must NOT be refactored/recompiled. Not in the source; it's a phase boundary the architect declares. +- `bridge_points` — the *protocol/idiom conversion design* across the cut (param decomposition, response reconstruction, edge-case handling). A design commitment, not a fact extractable from either side. + +`frozen_contract` is therefore **conditional, not standard issue** (see field rule below). + +**Two sources — `declared` is authoritative, `inferred` is advisory**: +- `declared`: user/architect specified this cut point. Authoritative — design may NOT overrule it. +- `inferred`: analyze discovered a likely seam. Advisory — a candidate for design/user to confirm. +- On conflict (a declared seam contradicts an inferred one), `declared` wins; drop or fold the inferred row, note it. + +**Discovery signals for `inferred` seams** (recognize by judgment, provenance not a gate): protocol boundary (rpc↔rest, sync↔async), framework boundary (Struts action ↔ Spring controller), layer boundary where you intend to keep the old service, external-system edge, and the **reference cliff** in `shared_modules.yaml` (a shared module heavily used on one side, barely on the other). + +```yaml +seams: + - id: src/com/acme/inventory/InventoryService.java:1 # cut point = natural ID + description: "Order service migrated to REST; inventory stays on legacy gRPC, frozen." + source: declared # declared (authoritative) | inferred (advisory) + cut_between: + migrated_side: unit_order_create # being rewritten now + frozen_side: legacy_inventory # stays as-is this phase + protocol_shift: {from: grpc, to: rest} # null when same protocol — bridge is then a thin adapter + frozen_side_rule: "legacy_inventory MUST NOT be refactored or recompiled this phase." + frozen_contract: # CONDITIONAL — emit ONLY when the frozen side's source is NOT visible to the migrating agent, OR a semantic cannot be recovered from the source it can read (private/obfuscated binary dependency, behavior gated by config/data not in source, a contract the public name contradicts). When the frozen source IS visible and self-explanatory, OMIT this — the migrating agent reads it directly; restating it here is redundant context cost. Default to omitting. + - method: "reserve(orderId: string, items: Item[]) -> ReservationResult" + source_loc: InventoryService.java:88 + semantics: > + synchronous; throws InsufficientStockException(stockShortfall); + idempotent on orderId (re-reserve returns same ReservationResult). + must_preserve: true + bridge_points: # the conversion design — ARCHITECT commits it; migrating agent does not invent it + - at: "order_create → inventory call site, OrderController.java:142" + from_form: "gRPC InventoryService.Reserve(ReserveRequest{order_id, repeated Item})" + to_form: "POST /legacy/inventory/reservations body={orderId, items[]}" + mapping_rule: > + ReserveRequest.order_id → body.orderId; + repeated Item{sku,qty} → items[]{sku,qty}; + ReservationResult.reservation_id → 201 Location header. + edge_cases: + - "empty items → 400 (NOT gRPC INVALID_ARGUMENT passthrough)" + - "InsufficientStockException → 409 with {sku, shortfall}" + idempotency_retry: "orderId is the idempotency key; bridge dedupes; safe to retry the POST." + fallback: "bridge timeout → surface 504; do NOT auto-retry the write." + must_preserve: true +``` + +**Self-check**: every `declared` seam present; every seam has a `frozen_side_rule`; `frozen_contract` present **only** where the frozen source is invisible/unrecoverable (absent otherwise — its absence is correct, not a gap); every `protocol_shift != null` seam has ≥1 `bridge_point` with a concrete `mapping_rule` (no `TBD`); declared/inferred conflicts resolved in favor of declared. + diff --git a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/shared-modules.md b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/shared-modules.md new file mode 100644 index 0000000..2168a8e --- /dev/null +++ b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/shared-modules.md @@ -0,0 +1,52 @@ +# shared_modules.yaml — Cross-Unit Shared Code Registry + +Records source files/modules used by ≥2 units. Prevents duplication, god-class field drift, and hallucinated fields during migration. + +## Schema + +```yaml +modules: + - name: # logical name for the shared module + kind: + source_loc: "" + used_by_units: # which units reference this module + - + fields: # all public/accessible fields/methods with types + - name: + type: "" + god_class: # true when the module has too many responsibilities + split_candidate: # true when god_class or high fan-out suggests splitting + migration_strategy: + # extract: pull into its own module/package + # wrap: wrap behind an interface for the target + # split: break into cohesive pieces (when god_class/split_candidate) + # copy: copy as-is (stable utility) + # inline: inline into consuming units (small, single-purpose) + notes: "" +``` + +## Relationship to Per-Unit `shared_refs` + +Each unit's `shared_refs` in `unit_graph.yaml` is a **subset whitelist** of this file: +- `shared_refs[].module` must match a `name` in this file. +- `shared_refs[].used_fields` must be a subset of this file's `fields` for that module. + +This two-level design ensures: +1. The global file is the single source of truth for what the module contains. +2. Each unit declares only the fields it actually uses (preventing hallucinated field access). + +**Self-check constraint**: `∀ unit U, ∀ ref in U.shared_refs: ref.used_fields ⊆ {f.name for f in shared_modules[ref.module].fields}` + +## Key Fields + +- **`god_class`**: flags modules with too many responsibilities. Prevents Failure Mode 16 (god-class field drift). +- **`split_candidate`**: advisory flag for design phase. Does not trigger automatic splitting — design decides. +- **`migration_strategy`**: how to handle during migration. This is a recommendation, not a gate. +- **`used_by_units`**: the filter key. Implementation agent for unit X reads rows where `used_by_units` includes X. + +## Self-Check + +- Every module listed in any unit's `shared_refs` exists in this file. +- No module has `used_by_units` with only one unit (by definition, shared = ≥2). +- Every `god_class: true` module has `split_candidate: true`. +- `fields` lists are non-empty. diff --git a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/state-routing.md b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/state-routing.md deleted file mode 100644 index 2b050cf..0000000 --- a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/state-routing.md +++ /dev/null @@ -1,9 +0,0 @@ -Analyze frontend state and navigation. Focus on: -- State management solution (Redux, Vuex, Pinia, Zustand, MobX, etc.) -- Global vs local state patterns -- Route definitions and navigation structure -- Route guards / middleware -- Code splitting and lazy loading -- Data fetching patterns (REST hooks, GraphQL queries, SWR, React Query, etc.) - -Output: `./state-routing.md` diff --git a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/test-coverage.md b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/test-coverage.md deleted file mode 100644 index 1d73100..0000000 --- a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/test-coverage.md +++ /dev/null @@ -1,12 +0,0 @@ -Analyze the existing test suite. Focus on: -- **Test inventory**: Count and categorize tests (unit / integration / e2e / performance) -- **Coverage baseline**: Which packages/classes have tests? Which are untested? -- **Test framework**: JUnit 4/5, TestNG, Mockito, Spring Test, etc. -- **Integration test dependencies**: What real services do integration tests require? (DB, message broker, external APIs) -- **Test data strategy**: fixtures, DBUnit datasets, factory methods, inline mocks -- **Portability assessment**: Which tests are tightly coupled to the current framework? Which test only business logic independently of the web layer? -- **Gaps**: Business-critical areas with no test coverage - -> ⚠️ **Document the existing test suite only.** Do not recommend target test strategies or frameworks. - -Output: `./test-coverage.md` diff --git a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/ui-components.md b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/ui-components.md deleted file mode 100644 index 9cb97af..0000000 --- a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/ui-components.md +++ /dev/null @@ -1,9 +0,0 @@ -Analyze frontend component architecture. Focus on: -- Component tree and hierarchy -- Shared/reusable components vs page-specific ones -- Design system / component library usage (Material UI, Ant Design, etc.) -- Styling approach (CSS modules, Tailwind, styled-components, SCSS, etc.) -- Form handling patterns -- Accessibility patterns - -Output: `./ui-components.md` diff --git a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/unit-decomposition.md b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/unit-decomposition.md new file mode 100644 index 0000000..aacecf7 --- /dev/null +++ b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/unit-decomposition.md @@ -0,0 +1,34 @@ +# Unit Decomposition Artifact + +This reference defines `units//unit_decomposition.yaml`, the split-candidate artifact for design. + +### `units//unit_decomposition.yaml` (per-unit) + +**Prevents**: analyze prematurely committing to target unit count; design losing the rationale for split candidates. + +**Hard rule**: produces `candidate_splits`, NOT `target_units`. Whole file is design-owned (`commit: false`, self-checked); no per-row decision markers. + +**Split drivers — recognize these** (vocabulary; ≥1 per candidate, classify by judgment): +``` +protocol_split concern_split execution_model_split lifecycle_split +reuse_split data_ownership_split change_cadence_split nfr_split +``` + +```yaml +unit: order_processing +commit: false # HARD: self-checked. Whole file is candidates, not decisions. +candidate_splits: + - id: src/com/acme/order/OrderAction.java:42-120 + drivers: [concern_split, execution_model_split] + rationale: > # MANDATORY ≥40 chars; self-checked + handleRequest interleaves synchronous validation (42-78) with async inventory + reservation (80-120): two execution models, two failure semantics. + source_slice: {file: src/com/acme/order/OrderAction.java, lines: [42, 120]} + +# _meta only when candidate count is unusually high (smell, NOT a truncation trigger): +# _meta: {candidate_count: 11, note: "high split count — unit likely under-defined; revisit boundary"} +``` + +**No `composite_score`**: ranking candidates is design's job — it has cross-unit/strategic context analyze lacks. Emit **all** candidates with drivers+rationale. + +Cohesion machinery such as LCOM4/TCC, co-access clusters, and method-field matrices is not produced here. Structural numbers did not change design decisions. Candidate seams belong in `seams.yaml`; field-level cohesion concerns, when real, surface as `split_candidate` on `shared_modules.yaml`. diff --git a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/unit-graph.md b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/unit-graph.md new file mode 100644 index 0000000..ec34ab7 --- /dev/null +++ b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/unit-graph.md @@ -0,0 +1,54 @@ +# unit_graph.yaml — Global Unit Index + +The spine of all architecture artifacts. Every per-unit artifact set and every global-artifact filter key derives from this file. + +## Schema + +```yaml +units: + - name: # kebab-case, unique across the graph + trigger: # external trigger category + trigger_detail: "" + source_anchors: # files that prove this unit exists — NOT rewrite targets + - path: + line: # optional entry-point line + exported_signature: # public signatures other units depend on + - method: "" + source_loc: "" + stability: # frozen = exact shape required by callers + dynamic_entrypoints: # classes/methods reached only via reflection, DI, XML, or convention + - target: "" + mechanism: + source_loc: "" # where the dynamic reference is declared + depends_on: # other units this unit calls + - unit: + via: "" + shared_refs: # per-unit subset of shared_modules this unit uses + - module: # must exist in shared_modules.yaml + used_fields: # subset; names must ⊆ shared_modules[module].fields[].name + - +``` + +## Key Fields + +- **`name`**: the join key used by all per-unit directories (`units//`) and global-artifact row filters (`used_by_units`, `unit`, `writer.unit`/`reader.unit`, `cut_between`). +- **`source_anchors`**: evidence that a unit exists. Rule: `source_anchors ≠ rewrite targets`. Implementation scope comes from `migration_boundary.yaml::must_rewrite`. +- **`exported_signature`**: resolved from public method/route signatures only. Prevents Failure Mode 4 (broken caller / signature unsync). +- **`dynamic_entrypoints`**: anything reached via reflection, DI container scan, XML bean definition, naming convention, or annotation processing. Prevents Failure Mode 5 (dead-code removal of reflection/DI class). Include the `mechanism` so the implementation agent knows *how* the class is discovered. +- **`shared_refs`**: this is where per-unit shared-module usage lives. Each entry points to a module in `shared_modules.yaml` and lists the subset of fields this unit actually uses. Self-check constraint: `shared_refs[].used_fields ⊆ {f.name for f in shared_modules[module].fields}`. +- **`depends_on`**: inter-unit call edges. Combined with `exported_signature`, this lets the implementation agent preserve call-site contracts. + +## Uniqueness Invariant + +Each source file appears in at most one unit's `source_anchors`. Files used by ≥2 units belong in `shared_modules.yaml`. + +## Self-Check + +```bash +# unit count (used by per-unit completeness gate) +grep -c '^\s*- name:' artifacts/unit_graph.yaml + +# no duplicate source_anchors across units +grep 'path:' artifacts/unit_graph.yaml | sort | uniq -d +# expect: empty output +``` diff --git a/plugins/github-copilot-modernization/skills/analyzing-architecture/references/wire-contracts.md b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/wire-contracts.md new file mode 100644 index 0000000..f78a0e8 --- /dev/null +++ b/plugins/github-copilot-modernization/skills/analyzing-architecture/references/wire-contracts.md @@ -0,0 +1,46 @@ +# wire_contracts.yaml — External Interface Contracts + +Records outward-facing contracts: REST/SOAP/GraphQL/gRPC endpoints, message queues, SQL/data interfaces, and cross-language semantic traps. Implementation agents use this to preserve exact API shapes and catch semantic divergence. + +## Schema + +```yaml +contracts: + - name: "" + unit: # join key to unit_graph; may be "global" for app-wide contracts + type: + stability: + source_loc: "" + contract: # wire shape + method: "" # when applicable + path: "" + request: "" + response: "" + error: "" + auth: "" + target_contract: # required target-side form; TBD forbidden + method: "" + notes: "" + semantic_divergence: # cross-language / cross-framework gotchas + - field: "" + issue: "" + source_loc: "" +``` + +## Key Fields + +- **`unit`**: the filter key. Implementation agent for unit X reads only rows where `unit == X` (or `unit == global`). +- **`stability: frozen`**: this contract shape must be preserved exactly (Failure Mode 6). +- **`target_contract`**: the required target-side signature. `TBD` is forbidden — if the target form cannot be determined during analysis, the seam/bridge must handle it. +- **`semantic_divergence`**: cross-language gotchas (e.g., Java `null` vs Kotlin non-null, date format drift, enum ordinal vs name). Prevents Failure Mode 8. + +## Scope Boundary + +- **Included**: REST, SOAP, GraphQL, gRPC, message queues (Kafka/JMS/RabbitMQ/SQS), SQL contracts (stored procedures, cross-service queries), file/SDK integration contracts. +- **Excluded**: internal method calls within a unit (those are `behavior.yaml`), ORM entity mappings (those are `bindings.yaml` unless they define a cross-service data contract), deploy/infra topology. + +## Self-Check + +- Every `stability: frozen` row has a non-TBD `target_contract`. +- Every row has a valid `unit` that exists in `unit_graph.yaml` (or is `global`). +- `semantic_divergence` entries have `source_loc`. diff --git a/plugins/github-copilot-modernization/skills/api-service-contracts/SKILL.md b/plugins/github-copilot-modernization/skills/api-service-contracts/SKILL.md index 0b89114..1b109f9 100644 --- a/plugins/github-copilot-modernization/skills/api-service-contracts/SKILL.md +++ b/plugins/github-copilot-modernization/skills/api-service-contracts/SKILL.md @@ -11,6 +11,44 @@ Analyze the project to document all services, API endpoints, communication patte - `workspace-path` (optional): Path to the project to analyze (defaults to current directory) +## ⚠ Mermaid Safety Constraints — read BEFORE you write the ```mermaid block + +Mermaid sequenceDiagram is unforgiving in a few specific ways: one bad alias or one missing `end` crashes the **whole** diagram with `Syntax error in text`, not just the offending line. Stay strictly inside this subset for the sequence diagram in Step 7: + +1. **Chart kind.** `sequenceDiagram` only. Never `sequence-diagram`, never `sequence`. +2. **Participants.** Always declare with the alias form `participant as "Display Label"`. The id must match `[A-Za-z][A-Za-z0-9_]*`. Never omit the id — even a one-word participant should be `participant Client as "Client"`. This is the single biggest cause of past failures. +3. **Arrows.** + - `->>` synchronous request + - `-->>` synchronous response (or async return) + - `-)` async fire-and-forget + - Message text goes after `:` and is plain text — keep it short and on one line. +4. **Blocks.** `alt` / `else` / `opt` / `loop` / `par` / `critical` MUST be closed by `end` on its own line. Every open block must have a matching `end`. Missing `end` is the #2 cause of past failures. +5. **No line breaks anywhere.** The escape `\n` was removed in modern Mermaid. Aliases, message text, and `Note over` content must all be single-line. Split a long note into multiple consecutive `Note over` lines; split a long message into multiple arrows. This is the #1 cause of past failures. +6. **Banned characters inside participant aliases specifically** (message text is more permissive — only `\n` is banned there): + + | Banned in alias | Why it breaks | Replacement | + |---|---|---| + | `\n` (literal two chars) | escape removed | drop | + | `"` (a second double-quote) | closes the alias early | `'` (single quote) | + | `` ` `` (backtick) | breaks alias quoting | drop | + | smart quotes `"` `"` `'` `'` | not ASCII | regular `"` and `'` | + | `:` | confuses with message delimiter | rephrase, e.g. `"REST API (port 8080)"` not `"REST API: port 8080"` | + | `
` | not interpreted inside aliases | rephrase as shorter alias | + +7. **Quote the alias.** `participant Svc as "Order Service"` — never `participant Svc as Order Service` (unquoted multi-word aliases break). + +### Mandatory self-attestation + +Immediately before writing the ` ```mermaid ` opening fence in Step 7, emit this exact one-line HTML comment in the markdown (it does not render — it is for your own visible attestation): + +``` + +``` + +If you cannot truthfully emit that comment, fix the diagram first. + +--- + ## Scope Boundaries — Avoid Redundancy with Other Skills This skill is part of a set of four complementary assessment skills. To avoid content duplication across their output documents, observe these scope rules: @@ -103,18 +141,19 @@ For each service, identify which cross-cutting capabilities it uses and produce ### Step 7: Generate Service Communication Sequence Section -Create a **Mermaid `sequenceDiagram`** and produce the complete `## Service Communication Sequence` section: +Create a **Mermaid `sequenceDiagram`** and produce the complete `## Service Communication Sequence` section (re-read the Safety Constraints above before writing): - Show key actors: Client, API Gateway (if present), Controllers, Services, External Services, Message Brokers - Annotate synchronous calls with solid arrows and asynchronous calls with dashed arrows - Include request/response types where relevant - Show error handling paths for critical flows (circuit breaker, retry) - For gateway aggregation flows, show how multiple downstream calls are composed -Example: +Reference example (this block satisfies every Safety Constraint — match its shape): + ~~~mermaid sequenceDiagram - participant Client + participant Client as "Client" participant Gateway as "API Gateway" participant CustSvc as "Customers Service" participant VisitSvc as "Visits Service" @@ -183,36 +222,23 @@ A brief introduction (1-2 sentences) summarizing the API surface and communicati - Aggregate similar endpoints (e.g., CRUD operations on the same resource) into one table row if needed for brevity - For the service technology matrix, use checkmarks or short labels; omit columns where no service uses the capability -## Mermaid Syntax Rules - -The diagram must parse cleanly under **Mermaid >= 9.x**. Anything outside the legal subset crashes the entire diagram with `Syntax error in text`. - -- Use `sequenceDiagram` -- Avoid special characters (`@`, `#`, `$`, `%`, `&`) in participant labels — use plain text or quoted labels -- Use `->>` for synchronous calls and `-->>` for responses/async messages -- Use `participant` with alias syntax for readable labels: `participant Svc as "OrderService"` -- Use `alt`/`else`/`end` blocks to show circuit breaker fallback paths -- Do not use backticks inside node labels - -### Line breaks — HARD RULE - -- **NEVER use `\n` for line breaks inside participant aliases, messages, or notes.** The literal `\n` escape was removed in modern Mermaid and triggers "Syntax error in text". -- In participant aliases: keep them on a single line, e.g. `participant Svc as "Order Service"` — not `"Order\nService"`. -- In `Note over` / `Note right of`: keep the note on one line, or split into multiple `Note` statements. -- In message arrow labels: keep concise; if you need multiple facts, split into multiple arrows. -- ❌ `participant API as "REST API\n(SubsonicController)"` -- ✅ `participant API as "REST API (SubsonicController)"` +## Common failure patterns observed in past runs -### Self-check before emitting each ```mermaid block +Each row below is something the model actually produced that crashed the diagram. Use the ✅ form. -1. Search the block for the two characters `\n` — remove or split the line. Zero `\n` must remain. -2. Confirm every `alt`/`opt`/`loop`/`par` block is closed by `end`. -3. Confirm every quoted alias is on a single line. +| ❌ Past mistake | ✅ Safe form | Why the ❌ crashed | +|---|---|---| +| `participant API` (no alias) | `participant API as "API"` | Bare participants with later spaces in usage break | +| `participant API as "REST API\n(SubsonicController)"` | `participant API as "REST API (SubsonicController)"` | Literal `\n` in alias | +| `participant API as "REST API: port 8080"` | `participant API as "REST API (port 8080)"` | `:` in alias collides with message delimiter | +| `Note over Client,API: First fact\nSecond fact` | Two consecutive `Note over Client,API: ...` lines | `\n` in note text | +| `alt happy path` ... missing `end` | `alt happy path` ... `end` | Unclosed block | +| `participant Svc as Order Service` (no quotes) | `participant Svc as "Order Service"` | Multi-word alias must be quoted | ## Error Handling - **Unsupported project type**: Output a single line: `> ERROR: Unsupported project type. This skill supports Java, .NET, JavaScript, and TypeScript projects only.` -- **No API endpoints found**: Output: `> ERROR: No recognized API endpoints found at {workspace-path}. Verify the path is correct.` +- **No API endpoints found**: Output: `> ERROR: No recognized API endpoints found at workspace-path. Verify the path is correct.` - **Insufficient info**: Generate a best-effort document from available data. Add a note: `> Note: Some endpoints or communication patterns could not be fully identified.` ## Success Criteria @@ -224,4 +250,5 @@ The diagram must parse cleanly under **Mermaid >= 9.x**. Anything outside the le - Service technology matrix shows per-service capabilities - Communication patterns section describes sync/async patterns, resilience policies, and security posture (authentication, authorization, TLS — explicitly stating if none is configured) - Mermaid sequence diagram renders correctly showing primary request flow with aggregation and fallback +- The ```mermaid block is preceded by the `` attestation comment - File saved to `.github/modernize/assessment/engines/facts/api-service-contracts.md` diff --git a/plugins/github-copilot-modernization/skills/appmod-hooks/SKILL.md b/plugins/github-copilot-modernization/skills/appmod-hooks/SKILL.md index d4847f8..670b9ac 100644 --- a/plugins/github-copilot-modernization/skills/appmod-hooks/SKILL.md +++ b/plugins/github-copilot-modernization/skills/appmod-hooks/SKILL.md @@ -23,6 +23,7 @@ See `references/actions.yml` for the action registry. Actions use dotted namespa ## Execution Rules 1. Actions within a hook point execute **in order** (top to bottom in the registry) -2. An action that fails does NOT block subsequent actions — log the error and continue +2. An action that fails does NOT block subsequent actions — log the error and continue, unless the action explicitly declares itself a quality gate 3. `optional: false` actions MUST execute; `optional: true` actions execute only if their `condition` is met 4. The coordinator executes hook actions **itself** (shell commands for git, file writes for profile) — hooks are NOT delegated to workers +5. A quality-gate action failure blocks dependent dispatch: keep the task pending or create a remediation task, then re-run the hook after the artifact is updated diff --git a/plugins/github-copilot-modernization/skills/appmod-hooks/commands/appmod.board.floor-check.md b/plugins/github-copilot-modernization/skills/appmod-hooks/commands/appmod.board.floor-check.md new file mode 100644 index 0000000..f51f7dc --- /dev/null +++ b/plugins/github-copilot-modernization/skills/appmod-hooks/commands/appmod.board.floor-check.md @@ -0,0 +1,75 @@ +# appmod.board.floor-check + +Quality gate: before any worker is dispatched, ensure the board schedules the mandatory governance fragments that a hand-rolled board commonly drops. Enforces two fragments — **`cve-remediation`** (when the change touches a dependency manifest) and the **completeness / consistency check** (`conformance-review`, plus `feature-parity-signoff` when applicable), the latter **only when the user explicitly requests it**. + +## Purpose + +Fragment selection lives inside `skill(dag-generation)`. When the coordinator hand-rolls the board (common on small / lite projects with `deep_planning=false`), mandatory governance fragments are silently dropped even when warranted. This gate verifies the **outcome** — that the warranted governance task is on the board — **regardless of whether `dag-generation` was invoked**. + +It deliberately checks **only** the governance fragments the LLM tends to skip: + +- **`cve-remediation`** — warranted whenever the change emits or modifies a dependency manifest (implicit; the user need not ask). +- **completeness / consistency** (`conformance-review`, and `feature-parity-signoff` when applicable) — warranted whenever the user **explicitly requests** a completeness / consistency / feature-parity check (any change type: upgrade, migration, rewrite). + +It does NOT check implementation / smoke-test / runtime-validation tasks — those are trusted to the LLM. + +## When + +`before_all`, after the board is written and before the first worker dispatch. + +**Skip the whole gate (run nothing) when:** +- The board contains the deep-planning placeholder `⏳ [Execute + Validate phases — pending deep planning completion]`. The execute+validate tail (including `cve-remediation`, `conformance-review`, and `feature-parity-signoff`) is generated later in §3.2.2; this gate is **re-run there** — once §3.2.2 replaces the placeholder with the real execute+validate tasks, the coordinator re-invokes this floor-check against the now-complete board. So skipping here is safe: the arms are evaluated at §3.2.2, not lost. + +## Inputs available from coordinator context + +- `{{BASE_PATH}}/board.md` — the task list. +- `{{BASE_PATH}}/artifacts/project-profile.yaml` — `assessment.change_type`, `assessment.transformations`, `project` notes. +- The user's original request (`## User Input` in `board.md`). + +## Required behavior + +0. **Verify the board exists.** Confirm `{{BASE_PATH}}/board.md` is present and non-empty. At `before_all` it must already be written (it is the artifact the coordinator is about to dispatch from). If it is **missing or empty**, this is an upstream failure, not a pass condition — fail the gate and block dispatch with: `board.md is missing or empty at before_all; the board must be generated before any worker is dispatched.` Do NOT treat an absent board as "nothing warranted." + +Then run **both** arms below. Reuse each fragment's own `when` / `skip-when` / `override` from `skill(dag-generation)` → `references/task-catalog.md` (do NOT invent new criteria). + +### Arm A — `cve-remediation` (warranted by change nature) + +1. **Decide whether `cve-remediation` is warranted**: + - **Warranted (`when`)**: the planned change will **emit or modify a dependency manifest** (`pom.xml` / `build.gradle` / `*.csproj` / `packages.config` / `package.json` / lockfiles) — true for essentially every brownfield migration / upgrade / rewrite — OR the user mentions security / CVE / vulnerability, OR assessment/arch-analysis flagged vulnerable or EOL dependencies. Judge this from the change nature (`change_type`, `user_ask`, transformations), **not** from a `git diff` — at `before_all` no implementation has run yet, so the working tree shows no manifest change. + - **Not warranted (`skip-when`)**: no dependency manifest is produced or changed (pure config/docs/asset change, or a dependency-free single-file edit); OR the user explicitly opted out of security/CVE work. Do NOT treat **lite scope** as not-warranted — a lite-scope change that still touches a dependency manifest must be scanned (this is exactly the small/lite case this gate exists to catch). + - If **not** warranted → this arm passes silently. +2. **If warranted, check `board.md`** for a `cve-remediation` task. Match case-insensitively on task title / assignment: any task that indicates CVE scanning / vulnerability remediation — e.g. mentions `cve`, `vulnerab`, `dependency scan`, `remediat`, or explicitly invokes `skill(cve-remediation)`. + +### Arm B — completeness / consistency (warranted by explicit user request) + +3. **Decide whether a completeness / consistency check is warranted** — mirror the `dag-generation` "Explicit-request override": + - **Warranted (`when`)**: `user_ask` **explicitly** requests a completeness, consistency, or feature-parity check (e.g. "run a completeness check", "verify nothing was missed / dropped", "enforce consistency", "feature parity sign-off", "make sure the migration / upgrade / rewrite is complete and consistent"). This applies to **any** change type (upgrade, migration, rewrite) — it is the explicit user intent, not the project size or change type, that warrants it. + - **Not warranted**: the user did not explicitly ask for such a check. Implicit completeness is the LLM's to plan; this gate enforces only the **explicit** request. + - If **not** warranted → this arm passes silently. +4. **If warranted, check `board.md`** for a completeness/conformance validation task. Match case-insensitively: any task that indicates completeness / conformance / consistency / feature-parity validation — e.g. mentions `conformance`, `completeness`, `consistency`, `feature parity` / `feature-parity`, or explicitly runs the completeness gate (`skill(quality-gates)` → `references/gate-completeness.md`). When the change is a migration / rewrite that has a `feature-inventory` task, a `feature-parity-signoff` task also counts toward this arm. + +5. **For each warranted arm: present → pass; absent → fail** (see Failure semantics). + +## Pass criteria + +The gate passes when, for **each** arm, either the fragment is not warranted, or the board already contains the corresponding task. + +## Failure semantics + +This action is a **quality gate**. On failure (any warranted arm missing its task) the coordinator MUST NOT dispatch any worker. Append the missing task(s) to `board.md` (do NOT re-run `dag-generation`), then **re-run this floor-check**; dispatch may proceed once it passes. + +**Arm A — append `cve-remediation`** in the Implementation phase (fragment is `after: [implementation]`, `scope: per-group`, implementer/backend role). The task MUST instruct the worker to **use `skill(cve-remediation)`**, so the skill's existing scan→fix→verify workflow is reused — do NOT hand-roll an ad-hoc CVE check. Example board line: + + ```text + - ⏳ t [backend] Scan dependency manifests for CVEs and remediate via skill(cve-remediation) [deps: ] + ``` + +**Arm B — append `conformance-review`** in the Validate phase (fragment is `after: [runtime-validation, test-strategy]`, `scope: global`, teamlead role). The task MUST run the completeness gate (`skill(quality-gates)` → `references/gate-completeness.md`), which performs the change-type-aware consistency check (migration / rewrite → functional-equivalence; upgrade → upgrade-consistency). Example board line: + + ```text + - ⏳ t [teamlead] Completeness & consistency check via skill(quality-gates) gate-completeness [deps: ] + ``` + + When the change is a migration / rewrite with a `feature-inventory` task, also ensure a `feature-parity-signoff` task is present (pm role: verify the feature-inventory checklist is fully covered — no missing endpoints, UI flows, or business rules). + +> Rationale for "append, don't re-plan": the board is trusted for everything else (implementation / smoke-test / validation are the LLM's to plan). This gate surgically restores only the governance tasks that hand-rolled boards drop, rather than regenerating the whole DAG. diff --git a/plugins/github-copilot-modernization/skills/appmod-hooks/commands/appmod.dependency.consumption-check.md b/plugins/github-copilot-modernization/skills/appmod-hooks/commands/appmod.dependency.consumption-check.md new file mode 100644 index 0000000..bfb4774 --- /dev/null +++ b/plugins/github-copilot-modernization/skills/appmod-hooks/commands/appmod.dependency.consumption-check.md @@ -0,0 +1,53 @@ +# appmod.dependency.consumption-check + +Verify that a completed task with dependency artifacts reports how those upstream artifacts were consumed. + +## Purpose + +`dependencyArtifacts` are not just ordering edges. They are input contracts from upstream work. A task that receives dependency artifacts must either consume them or explicitly explain why they were not applicable. + +This action is role-neutral: architecture analysis, feature inventory, API design, test strategy, security findings, UX design, data-model plans, and any other upstream artifact are all treated the same. + +## When + +`after_task`, after the coordinator has verified the worker returned `[DONE]` and the task artifact exists/non-empty, but before dispatching dependent tasks. + +## Inputs available from coordinator context + +- Current task metadata, including the `## Dependency Artifacts` list used for dispatch. +- Current task artifact path, typically `{{BASE_PATH}}/artifacts/-.md`. +- Worker return message, if available. + +## Required behavior + +1. If the current task had **no dependency artifacts**, skip silently. +2. If the only dependency artifact is global clarification context (`clarification.md`), skip silently. The clarification file is a global scenario record, not a task-to-task input contract. +3. Otherwise read the completed task artifact and verify it contains dependency-consumption evidence. +4. Accept any section heading or YAML key whose meaning is "which upstream inputs were consumed / how they map to this output / why an input was not used." Match **case-insensitively and format-insensitively**: ignore Markdown heading markers (`#`/`##`), separator style (spaces, hyphens, underscores), and Title-vs-lower case. The headings the worker spec instructs workers to emit are the canonical forms and MUST match: + - `## Upstream Artifacts Consumed` (canonical — worker output) + - `## Evidence Mapping` (canonical — worker output) + + Equivalent forms that also satisfy the gate (non-exhaustive — judge by meaning, not by literal string): `upstream_artifacts_consumed`, `evidence_mapping`, `Dependencies consumed`, `Dependency artifacts consumed`, `Inputs consumed`, `Constraints applied`, `Dependencies not used`, `Inputs not used`. Do not fail an artifact that expresses consumption/evidence/not-used under a reasonable synonym just because its exact wording is absent from this list. +5. If none are present, mark the hook as failed and return a remediation message: + +```text +Dependency consumption evidence missing. +This task received dependency artifacts but its output does not state which upstream inputs were consumed, which constraints were applied, or why inputs were not used. +Re-run the task or add a remediation task that updates the artifact with: +- Dependency artifacts consumed: -> +- Constraints applied: +- Dependencies not used: -> +``` + +## Pass criteria + +The hook passes when either: + +- no task-specific dependency artifacts were provided; or +- the completed task artifact contains at least one accepted consumption/evidence section/key. + +## Failure semantics + +This action is a quality gate. On failure, the coordinator must not dispatch dependent tasks. Reopen the task as pending or create a remediation task for the same role to update the artifact and, if needed, the implementation/tests. + +Do not judge whether the consumption is semantically correct. This hook only enforces that the worker makes dependency usage explicit. Semantic correctness belongs to review/validation tasks. diff --git a/plugins/github-copilot-modernization/skills/appmod-hooks/references/actions.yml b/plugins/github-copilot-modernization/skills/appmod-hooks/references/actions.yml index 7e3ad62..2414bfd 100644 --- a/plugins/github-copilot-modernization/skills/appmod-hooks/references/actions.yml +++ b/plugins/github-copilot-modernization/skills/appmod-hooks/references/actions.yml @@ -2,7 +2,11 @@ # Each action points to a command file via `file:`. # Namespace: appmod.. -before_all: [] +before_all: + - id: appmod.board.floor-check + file: commands/appmod.board.floor-check.md + description: "Quality gate: ensure board.md schedules the warranted governance fragments — cve-remediation (when a dependency manifest changes) and conformance-review/feature-parity-signoff (when the user explicitly requests a completeness/consistency check); blocks first dispatch and appends the missing task(s) on failure" + optional: false before_task: - id: appmod.profile.read @@ -11,6 +15,11 @@ before_task: optional: false after_task: + - id: appmod.dependency.consumption-check + file: commands/appmod.dependency.consumption-check.md + description: "Gate completed tasks with dependency artifacts: worker output must state upstream artifacts consumed, constraints applied, or explicit not-used rationale" + optional: false + - id: appmod.profile.sync file: commands/appmod.profile.sync.md description: "Update progress_sync: increment completed_tasks, check phase completion, set timestamps, commit if phase done" diff --git a/plugins/github-copilot-modernization/skills/architecture-diagram/SKILL.md b/plugins/github-copilot-modernization/skills/architecture-diagram/SKILL.md index dffa82d..bec869a 100644 --- a/plugins/github-copilot-modernization/skills/architecture-diagram/SKILL.md +++ b/plugins/github-copilot-modernization/skills/architecture-diagram/SKILL.md @@ -11,11 +11,49 @@ This skill generates a two-layer architecture visualization: a high-level applic - `workspace-path` (optional): Path to the project to analyze (defaults to current directory) +## ⚠ Mermaid Safety Constraints — read BEFORE you write any ```mermaid block + +Mermaid is unforgiving: one illegal character anywhere in a block crashes the **whole** diagram with `Syntax error in text`, not just the offending line. There is no partial rendering. Stay strictly inside this subset: + +1. **Chart kind.** Only `flowchart TD` (Step 1) or `flowchart LR` (Step 2). Never `graph TD`, never mixed. +2. **Subgraph form.** Always `subgraph ["display label"]`. The id must match `[A-Za-z][A-Za-z0-9_]*` (no spaces, no punctuation). NEVER use the anonymous form `subgraph "label"` — it crashes whenever the label contains `(`, `)`, `:`, `/`, `-`, etc., and the parser error appears on an unrelated line. +3. **Node form.** Only one of: `Id["label"]` (rectangle), `Id(("label"))` (circle), `Id[("label")]` (cylinder for data stores). Pick one shape per node — do not stack brackets. +4. **Arrow form.** Solid `-->`, dotted `-.->`. If you put a label on an arrow it MUST be double-quoted: `-->|"label"|`. Never bare `-->|label|`. +5. **No line breaks in labels.** The escape `\n` was removed in modern Mermaid and is the #1 cause of failures. Use `
` in flowcharts when you really must break a line. Strongly prefer single-line ≤ 60-char labels — put detail in the Inventory / Stack tables instead. +6. **Banned characters inside any label or subgraph title.** Use the ASCII replacement: + + | Banned | Why it breaks | Replacement | + |---|---|---| + | `\n` (literal two chars) | escape removed | `
` or drop | + | `—` (em-dash, U+2014) | parser treats as edge | `-` (ASCII hyphen) | + | `–` (en-dash, U+2013) | parser treats as edge | `-` | + | `{` `}` (e.g. `{id}`) | opens an entity block | drop braces — write `id` or `:id` | + | `"` inside a label | closes the label early | `'` (single quote) | + | `\|` inside a label | breaks edge-label parser | rephrase | + | `@` `#` `$` `%` `&` | unsafe in many positions | rephrase or drop | + | `(` `)` outside a `["..."]` quoted label | unbalanced parens crash | only inside the quoted label | + | smart quotes `"` `"` `'` `'` | not ASCII | regular `"` and `'` | + +7. **Unique node IDs across the whole file.** If Layer 1 has `DB`, Layer 2 cannot also have `DB`. Use `DB1` and `DB2` (or `AppDb`, `ComponentDb`). +8. **`subgraph` must be closed by a matching `end` on its own line.** No `end`, no diagram. + +### Mandatory self-attestation + +Immediately before writing each ` ```mermaid ` opening fence, emit this exact one-line HTML comment in the markdown (the comment will not render — it is for your own visible attestation that you have re-checked the block): + +``` +|"label"|, all subgraphs closed by end, ids unique --> +``` + +If you cannot truthfully emit that comment, fix the diagram first. + +--- + ## Execution Steps ### Step 1: Generate Application Architecture Section -Analyze the project and produce the complete `## Application Architecture` section in one pass: +Analyze the project and produce the complete `## Application Architecture` section in one pass. **Analysis:** - Examine build files (Java: pom.xml, build.gradle; .NET: *.csproj, *.sln; JS/TS: package.json, tsconfig.json) @@ -23,7 +61,7 @@ Analyze the project and produce the complete `## Application Architecture` secti - Scan key source files to extract: framework, major dependencies, data access patterns, external integrations, technology stack - Identify application layers (UI, Business Logic, Data Access), data storage technologies, and external service dependencies -**Diagram — Mermaid `flowchart TD`:** +**Diagram — Mermaid `flowchart TD`** (re-read the Safety Constraints above before writing): - Application layers with technology info (use `subgraph` for grouping) - Data storage components (specific names like "PostgreSQL", "Redis") - External service integrations @@ -31,8 +69,9 @@ Analyze the project and produce the complete `## Application Architecture` secti **Do NOT include**: individual classes/methods or migration directions. -Example: +Reference example (this block satisfies every Safety Constraint — match its shape): +|"label"|, all subgraphs closed by end, ids unique --> ~~~mermaid flowchart TD subgraph Client["Client Layer"] @@ -63,13 +102,15 @@ flowchart TD ~~~ **Textual explanations (write immediately after the diagram):** -- **Technology Stack Summary table**: Layer | Technology | Version | Purpose (e.g., Presentation | ASP.NET MVC 5 | 5.2.7 | Server-side web framework) +- **Technology Stack Summary table**: Layer | Technology | Version | Purpose - **Data Storage & External Services**: A short paragraph describing what databases, caches, message brokers, or external APIs are used and how they fit into the architecture -- **Key Architectural Decisions**: 1-3 bullet points on notable patterns (e.g., "Uses repository pattern with EF6 for data access", "Autofac provides DI with module-based registration") +- **Key Architectural Decisions**: 1-3 bullet points on notable patterns (e.g., "Uses repository pattern with EF6", "Autofac DI with module-based registration") + +> ⚠ Move detail OUT of node labels and INTO this table. A diagram with short labels and a rich table renders; a diagram with long labels does not. ### Step 2: Generate Component Relationships Section -Analyze component interactions and produce the complete `## Component Relationships` section in one pass: +Analyze component interactions and produce the complete `## Component Relationships` section in one pass. **Analysis:** - Identify key component types by framework conventions: @@ -84,31 +125,33 @@ Analyze component interactions and produce the complete `## Component Relationsh - Map data access patterns (service-to-repository, DbContext usage) - Detect cross-cutting concerns (middleware, interceptors, filters) -**Diagram — Mermaid `flowchart LR`:** +**Diagram — Mermaid `flowchart LR`** (re-read the Safety Constraints above before writing): - Components grouped by architectural layer using `subgraph` (Presentation, Business Logic, Data Access, Infrastructure) - Interaction arrows with brief labels - Cross-cutting concerns +- **Use IDs that do NOT collide with Step 1's diagram** (e.g., prefix with `c` for Component: `cWeb`, `cService`). **Do NOT include**: method signatures, private helpers, or external dependencies (covered by dependency-map skill). -Example: +Reference example (satisfies every Safety Constraint): +|"label"|, all subgraphs closed by end, ids unique --> ~~~mermaid flowchart LR - subgraph Presentation + subgraph PresentationLayer["Presentation"] UserCtrl["UserController"] OrderCtrl["OrderController"] end - subgraph Business["Business Logic"] + subgraph BusinessLayer["Business Logic"] UserSvc["UserService"] OrderSvc["OrderService"] NotifSvc["NotificationService"] end - subgraph DataAccess["Data Access"] + subgraph DataAccessLayer["Data Access"] UserRepo["UserRepository"] OrderRepo["OrderRepository"] end - subgraph Infra["Infrastructure"] + subgraph InfraLayer["Infrastructure"] AuthFilter["AuthenticationFilter"] LogMiddleware["LoggingMiddleware"] end @@ -121,11 +164,11 @@ flowchart LR OrderSvc -->|"queries"| OrderRepo AuthFilter -.->|"intercepts"| UserCtrl AuthFilter -.->|"intercepts"| OrderCtrl - LogMiddleware -.->|"wraps"| Presentation + LogMiddleware -.->|"wraps"| PresentationLayer ~~~ **Textual explanation (write immediately after the diagram):** -- **Component Inventory table**: Component | Layer | Type | Responsibility (e.g., CatalogController | Presentation | MVC Controller | Handles catalog browsing and CRUD) +- **Component Inventory table**: Component | Layer | Type | Responsibility ### Step 3: Save Output @@ -163,39 +206,27 @@ A brief introduction (1-2 sentences). ## Scaling Rules -- If the project has **more than 30 components**, aggregate by package/namespace (e.g., show `com.example.orders` as one node instead of listing every class) -- Keep each diagram under **40 nodes** to ensure readability and GitHub rendering compatibility -- For multi-module projects, focus on inter-module boundaries in Layer 1 and key components within the most important modules in Layer 2 - -## Mermaid Syntax Rules - -The diagram must parse cleanly under **Mermaid >= 9.x** (the version used by GitHub, VS Code, Obsidian, and every modern renderer). Anything outside the legal subset crashes the entire diagram with `Syntax error in text`, not just the offending line. - -- Use `flowchart TD` for Layer 1 and `flowchart LR` for Layer 2 -- Avoid special characters (`@`, `#`, `$`, `%`, `&`) in node labels — use plain text -- Always quote arrow labels with double quotes: `-->|"label"|` -- Use `subgraph` for grouping, with a display name in quotes if it contains spaces -- Verify all node IDs are unique across the entire diagram - -### Line breaks in node labels — HARD RULE +- If the project has **more than 30 components**, aggregate by package/namespace (e.g., show `com.example.orders` as one node instead of listing every class) — this also keeps labels short and safe. +- Keep each diagram under **40 nodes** to ensure readability and GitHub rendering compatibility. +- For multi-module projects, focus on inter-module boundaries in Layer 1 and key components within the most important modules in Layer 2. -- **NEVER use `\n` for line breaks inside node labels.** The literal `\n` escape was removed in modern Mermaid and is the #1 cause of "Syntax error in text" — every node containing `\n` will fail to render. -- **Use `
` instead** for an explicit line break: `Node["First line
Second line"]`. -- If a label is long, prefer a single concise phrase over multi-line. Move details into the Component Inventory / Technology Stack tables that follow the diagram. -- ❌ `MediaLib["Media Library\n(MediaScannerService\nMediaFileService)"]` -- ✅ `MediaLib["Media Library
MediaScannerService
MediaFileService"]` -- ✅ `MediaLib["Media Library"]` (and list the sub-components in the inventory table) +## Common failure patterns observed in past runs -### Self-check before emitting each ```mermaid block +Each row below is something the model actually produced and crashed the diagram. Use the ✅ form. -1. Search the block for the two characters `\n` — if found, replace each with `
` (or remove). Zero `\n` must remain. -2. Confirm every node ID is unique and every `subgraph` is closed by `end`. -3. Confirm every arrow label is double-quoted. +| ❌ Past mistake | ✅ Safe form | Why the ❌ crashed | +|---|---|---| +| `subgraph "Spring Boot Application (port 8080)"` | `subgraph SpringApp["Spring Boot Application (port 8080)"]` | Anonymous subgraph + parentheses in title | +| `HC["HomeController\n GET / — gallery page"]` | `HC["HomeController GET /"]` (move detail to table) | Literal `\n` + em-dash | +| `PHOTOS_TABLE["PHOTOS table\n id (UUID PK)\n photo_data (BLOB)"]` | `PHOTOS_TABLE["PHOTOS"]` (columns belong in a table) | `\n` and overlong label | +| `PFC["PhotoFileController\n GET /photo/{id}"]` | `PFC["PhotoFileController GET /photo/:id"]` | `\n` + `{id}` | +| `Spring["Spring Boot\n2.7.18"]` | `Spring["Spring Boot 2.7.18"]` | `\n` | +| `A -->|fetches users| B` | `A -->|"fetches users"| B` | Bare (unquoted) arrow label | ## Error Handling - **Unsupported project type**: Output a single line: `> ERROR: Unsupported project type. This skill supports Java, .NET, JavaScript, and TypeScript projects only.` -- **No source code found**: Output: `> ERROR: No recognized source files found at {workspace-path}. Verify the path is correct.` +- **No source code found**: Output: `> ERROR: No recognized source files found at workspace-path. Verify the path is correct.` - **Insufficient info**: Generate a best-effort diagram from available data. Add a note inside the diagram: `Note["Some components could not be identified"]` ## Success Criteria @@ -204,4 +235,5 @@ The diagram must parse cleanly under **Mermaid >= 9.x** (the version used by Git - Layer 1 is accompanied by Technology Stack Summary table, Data Storage & External Services paragraph, and Key Architectural Decisions - Layer 2 Mermaid diagram renders correctly showing component interactions grouped by architectural layer - Layer 2 is accompanied by Component Inventory table +- Every ```mermaid block is preceded by the `` attestation comment - File saved to `.github/modernize/assessment/engines/facts/architecture-diagram.md` diff --git a/plugins/github-copilot-modernization/skills/assessment-report-converter/SKILL.md b/plugins/github-copilot-modernization/skills/assessment-report-converter/SKILL.md new file mode 100644 index 0000000..1749b91 --- /dev/null +++ b/plugins/github-copilot-modernization/skills/assessment-report-converter/SKILL.md @@ -0,0 +1,371 @@ +--- +name: assessment-report-converter +description: | + Convert an arbitrary CSV report (e.g. a Black Duck export or a custom migration-issue inventory) into + a schema-valid assessment `report.json` the modernization pipeline can consume — so it appears in the + assessment UI and migration solutions resolve automatically. + This skill is LLM-driven: you read and interpret the CSV yourself and author `report.json` by hand against + the schema. A small helper script only does deterministic lookups (migration solutions, the ruleId for a + solution) and validates the finished report. There is NO "convert everything" script and NO assumed column layout. + Triggers: "convert csv to assessment report", "import csv report", "turn this spreadsheet into a report.json", + "Black Duck csv to report", "build report.json from csv", "migrate a third-party assessment export". + NOT for: AppCAT-style analysis from source (use `assessment`), generating a modernization plan + (use `create-modernization-plan`), or editing a report.json the pipeline already produced. +--- + +# Assessment Report Converter (CSV → report.json) + +## What this skill does + +You take a **row-oriented CSV** of migration issues and produce a canonical **`report.json`** conforming to the +assessment report schema. Once written to the versioned reports directory, the +report is picked up by the assessment UI and by the solution-resolution logic — exactly like a native AppCAT report. + +**This is an LLM-driven conversion, not a fixed mapping script.** CSV layouts vary between tools and change over time, +so *you* read the file, decide what each column means, classify every row, and author `report.json`. You do **not** +rely on hard-coded column names. + +A small helper script — [scripts/report_tools.sh](scripts/report_tools.sh) (bash + jq) or its PowerShell twin +[scripts/report_tools.ps1](scripts/report_tools.ps1) (PowerShell 7+) — provides only the deterministic pieces +you should never guess: + +- **`list-solutions`** — discover the available migration solutions. +- **`rules-for-solution`** — get the canonical `ruleId`(s) for a chosen solution. +- **`upgrade-solutions`** — the canonical JDK / Spring Boot / Spring Framework / Jakarta EE upgrade solutions + ruleIds. +- **`validate`** — structural + consistency validation of the finished `report.json`. + +```mermaid +flowchart LR + A[Read CSV] --> B[Understand columns] --> C[Find projects] --> D{Audit each row} + D -->|CVE / CWE| E[Security finding] + D -->|Needs upgrade| F[Upgrade incident] + D -->|Other| G[Solution → ruleId → incident] + E --> H[Assemble report] + F --> H + G --> H + H --> I[Validate] --> J[Save report.json] --> K[Summarize] +``` + +## Input parameters + +- `csv-path` (mandatory): Path to the source CSV file. +- `workspace-path` (optional): Output root. Defaults to the current directory. The report is written to + `{workspace-path}/.github/modernize/reports/report-{reportId}/report.json`. +- `producer` (optional): A label identifying the source tool, stored in `report.producer` (e.g. `"Black Duck"`). + Defaults to `"CSV import"`. + +## When to use this skill + +Use this when you have a **CSV** — not an AppCAT `report.json` — and you want it to behave like a real assessment +report: a Black Duck / third-party export, or a hand-maintained spreadsheet of migration issues. Do **not** use it to +run analysis from source code (that is the `assessment` skill). + +## The helper script + +The helper ships as two interchangeable implementations of the same CLI — use whichever fits the machine: +[scripts/report_tools.sh](scripts/report_tools.sh) (**bash + jq**) and +[scripts/report_tools.ps1](scripts/report_tools.ps1) (**PowerShell 7+**, no extra dependencies). Both behave +identically and never read the CSV. Run them from the `scripts/` directory. + +```bash +# bash + jq +./report_tools.sh list-solutions [--query KW] [--type Formula|Chat] [--ids-only] +./report_tools.sh rules-for-solution +./report_tools.sh upgrade-solutions +./report_tools.sh validate +``` + +```powershell +# PowerShell 7+ +pwsh ./report_tools.ps1 list-solutions [--query KW] [--type Formula|Chat] [--ids-only] +pwsh ./report_tools.ps1 rules-for-solution +pwsh ./report_tools.ps1 upgrade-solutions +pwsh ./report_tools.ps1 validate +``` + +- `list-solutions` prints the matching solutions from [scripts/solution-mapping.json](scripts/solution-mapping.json) as + whole JSON objects (each always has `solutionId`, `name`, `type`, and `tooltip`; some also carry `effort` / `prompt`); + `--query` filters by substring on id/name/tooltip. +- `rules-for-solution` prints `{ solutionId, ruleCount, rules: [{ruleId, sourceCategory}], preferredRuleId }`. An empty + list means the solution has **no** rule (e.g. a security-only solution) — do not invent a ruleId. +- `upgrade-solutions` prints, per component (`jdk`, `spring-boot`, `spring-framework`, `jakarta-ee`), the `solutionId` + and its resolved `preferredRuleId`. +- `validate` runs structural + cross-field consistency checks + (incident→rule references, required `domain`/`category` rule fields, enum values, security-finding shape and dedupe, and + `metadata.domains`↔content consistency). Exit code is `0` valid, `1` invalid, `2` when the report can't be read/parsed. + It accepts a `--schema ` flag for CLI compatibility but ignores it — the checks are self-contained. + +## Reference material + +Detailed reference material is consolidated in the [Reference](#reference) section at the end of this file. The workflow +below links to the relevant part at the step where you need it — you do not have to open any separate files: + +- [Report structure](#report-structure) — the top-level `report.json` shape and the authoring conventions the schema can't express (the schema owns the field shape). +- [Assessment domains](#assessment-domains) — the `metadata.domains` values and when to include each. +- [Security severity mapping](#security-severity-mapping) — normalizing a source CVE/CWE severity to the security `mandatory|potential|optional` scale. +- [Rule classification](#rule-classification) — the required `domain` / `category` rule fields that group and render a rule's incidents. + +## Workflow + +### Step 1 — Understand the report structure (do this first) + +Read the authoritative schema [scripts/assessment-report.schema.json](scripts/assessment-report.schema.json) — it is +the source of truth for the field shape. The report is a single root object `{ version, producer, metadata, projects, +rules, security? }`, and `additionalProperties` is `false` almost everywhere (there is **no** `summary` object). The +[report structure reference](#report-structure) adds the authoring conventions the schema can't express. +You must know the required fields before authoring anything. + +### Step 2 — Read and understand the CSV + +Read the CSV file directly (headers + a representative sample of rows). Then **interpret the columns by meaning**, +since names and order vary by tool. Identify whichever of these the CSV actually carries (any may be absent): + +- a **project / module / service** identifier, +- an **application** name, +- an issue **title** and **description**, +- a **severity / criticality / priority**, +- a **category / domain / type**, +- a **CVE / CWE** identifier, +- an **affected component / package / library** and its **version**, +- a **file** path and **line**, +- an **effort / story-point** estimate, +- a **reference / URL**. + +When a concept is missing, leave the corresponding report field empty or at its default — never fabricate data. + +### Step 3 — Determine the projects + +Work out **how many projects** the CSV describes and group rows accordingly: + +- If a project/module/service column exists, group rows by it — one project per distinct value, using that value + as `project.path`. +- If the CSV has **no project information**, create a **single project** with `path` `"."` and minimal properties + (`appName` `""`; leave optional `jdkVersion` / `frameworks` / `languages` / `tools` off or empty). +- Populate `project.properties` **only** from what the CSV actually provides; otherwise keep them empty. Only `appName` + is required. + +Every incident you create later belongs to exactly one of these projects. + +### Step 4 — Audit each row, within its project + +Classify every row into exactly one of three branches and attach the result to the row's project. Every rule you add to +`rules{}` must set its `domain` and `category` **fields** (that is what groups and renders its incidents) — see +[rule classification](#rule-classification). Incidents do **not** require any label. + +1. **CVE / CWE → security finding (directly).** + When a row carries a `CVE-…` / `CWE-…` identifier (or unambiguously describes one), add a security finding + to `report.security[]`. Capture **as much of the column as possible**: `id` (the CVE/CWE token), `title`, `category`, + `severity` (the security scale `mandatory | potential | optional` — normalize the source severity per + [security issue severity mapping](#security-severity-mapping)), `description`, `evidence.files` + (affected paths), `evidence.explanation`, and optional `storyPoint`. **Merge by id** — one finding per CVE/CWE; + accumulate evidence files and keep the strongest severity (`mandatory` > `potential` > `optional`). Security + findings are **not** incidents; they live only in `report.security[]` (there is no summary to count them in). + +2. **Needs a major-component version upgrade → upgrade incident.** + If the row implies upgrading a major component — **JDK**, **Spring Boot**, **Spring Framework**, or **Java EE / + Jakarta EE** (e.g. a CVE against `spring-boot`, an out-of-support runtime, an explicit "upgrade JDK") — run + the `upgrade-solutions` command, pick the component, and use its `preferredRuleId`. Add that rule to `rules{}` + (`severity: "mandatory"`, `domain: "java-upgrade"`, a `category`, a reasonable `effort`) and add an **incident** to the + project — one upgrade rule per component per project, one incident per triggering row. A CVE that + implies an upgrade produces **both** a security finding (branch 1) **and** an upgrade incident — that is what makes the + upgrade resolve as a migration solution. + +3. **Any other issue → solution → ruleId → incident.** + Find the migration solution that fits the issue with + the `list-solutions --query ` command, then get its canonical ruleId with + `rules-for-solution ` (use `preferredRuleId`). Add that rule to `rules{}` (with `domain`, + `category`, `severity`, `effort`) and an incident to the project. If no solution fits, you may still record the issue + with a clear **synthetic** ruleId (it just won't + carry an automatic Formula solution) — or leave it for the "remaining" list in your summary. Either way, report it. + +#### Process rows in parallel + +Classifying a row is independent work, so for large CSVs do it concurrently rather than one row at a time: + +- **Batch the rows** (e.g. 20–50 per batch, or one batch per project) and dispatch the batches **in parallel** — launch + several `Explore`/worker subagents at once, each auditing its batch into a partial result (security findings, upgrade + hits, and ordinary incidents with their resolved ruleIds). Ask each worker to return structured JSON; it does **not** + write files. +- **Share the deterministic lookups.** Run the `upgrade-solutions` command and the `list-solutions` / + `rules-for-solution` queries **once up front** (results are stable) and pass them to the workers, so parallel batches + don't repeat the same lookups or race on them. +- **Keep workers side-effect free**, then **merge sequentially** in one place so shared state stays correct: + - **Security findings** — merge by `id` (one finding per CVE/CWE; union `evidence.files`, keep the strongest severity). + - **Upgrade rules** — collapse to one rule per `(project, component)`; keep every triggering incident. + - **`incidentId`s** — assign `"/"` **after** the merge, never inside a worker (so ids are deterministic + regardless of batch order). +- If the CSV is small, just process the rows sequentially — the parallel split only pays off at scale. + +### Step 5 — Assemble the report and finalize metadata + +There is **no** `summary` object to compute — assemble the top-level document and fill `metadata`: + +- `projects[]` = your projects, each with `properties` (only `appName` required) and its `incidents[]`. +- `rules{}` = every distinct rule you referenced, keyed by ruleId, each with `id`, `title`, `severity`, `effort`, + `domain`, and `category`. +- `report.security[]` = the deduped findings (omit or leave empty when there are none). +- `metadata.domains` = the assessment domains your report actually has content for, consistent with your `rule.domain` + values — see [assessment domains](#assessment-domains). +- `metadata.mode` (optional) = `"full"` when any security finding exists, else `"issue-only"`. +- `metadata.status` = `"completed"`; `metadata.targetIds` = the target ids in scope (may be empty). +- `metadata.id` (and the report-directory id) = `analysisStartTime` formatted `yyyyMMddHHmmss` (UTC); use the current UTC + time when the CSV has no timestamp. + +### Step 6 — Write and validate + +Write `report.json` to the versioned location ([Output location](#output-location)), then validate and fix until clean: + +```bash +# bash + jq +./report_tools.sh validate "/.github/modernize/reports/report-/report.json" +# …or PowerShell 7+ +pwsh ./report_tools.ps1 validate "/.github/modernize/reports/report-/report.json" +``` + +Resolve every reported consistency error before finishing. + +### Step 7 — Summarize for the user + +Report a concise conversion summary: + +- **Converted rows** — number of security findings (CVE/CWE), upgrade incidents (with components), and ordinary issue + incidents (with the solutions they mapped to); plus the project / rule / incident counts and the report path + id. +- **Remaining rows** — rows you could not confidently map, and *why* (no matching solution, ambiguous column, missing id). +- **Suggestions** — concrete next steps (e.g. pick a specific solution for a remaining row, add a project column to the + CSV, supply severities), so the user can close the gaps. + +## Output location + +- `{workspace-path}/.github/modernize/reports/report-{reportId}/report.json` +- `reportId` = the report's `metadata.id` from Step 5 (`analysisStartTime` as `yyyyMMddHHmmss`, UTC). +- Consider copying the original CSV next to `report.json` as `source.csv` for provenance. + +## Success criteria + +- ✅ `report.json` is written to the versioned reports directory and the `validate` command reports **VALID**. +- ✅ Projects reflect the CSV (one per module/service, or a single project with `appName: ""` when none is given). +- ✅ CVE/CWE rows are `security[]` findings (deduped by id) with a `mandatory|potential|optional` severity; `mode` is `full`. +- ✅ Rows implying a JDK / Spring Boot / Spring Framework / Jakarta EE upgrade add a mandatory upgrade incident whose + `ruleId` came from the `upgrade-solutions` command. +- ✅ Other issues map to a solution's canonical `ruleId` (via `list-solutions` + `rules-for-solution`) wherever one fits. +- ✅ Every rule carries `domain` and `category` fields; every incident's `ruleId` resolves to a rule in `rules{}`; CVE/CWE + findings stay in `security[]`, not `incidents[]`. +- ✅ `metadata.domains` matches the report's content and the emitted `rule.domain` values (enforced by `validate`). +- ✅ The user gets a summary of converted rows, remaining rows, and suggestions. + +## Troubleshooting + +- **`validate` reports a consistency error** (e.g. an incident `ruleId` with no matching rule, or a + `domains`/`security` mismatch) — the message names the exact field; fix that field. +- **Don't add fields the schema doesn't allow** (e.g. a `summary` object, or `issues`/`storyPoints` on a project). The + helper's `validate` is lenient about extra keys, but the app's importer enforces `additionalProperties: false` and will + reject the report — this schema has no summary. Keep to the documented shape. +- **A row has a CVE/CWE *and* needs an upgrade** — emit both: a `security[]` finding **and** an upgrade incident. They are + not duplicates; the finding documents the vulnerability, the incident drives the upgrade solution. +- **No solution fits an issue** — `list-solutions --query` returns nothing useful. Record the issue with a synthetic, + descriptive `ruleId` (no Formula will attach) or list it under "remaining" with a suggestion. +- **`rules-for-solution` returns an empty list** — that solution has no rule (often security-only). Don't fabricate a + ruleId; handle the issue via the security-finding path or pick a different solution. +- **Wrong severity enum** — rule/incident severity is the 4-value `mandatory|potential|optional|information` enum; + security-finding severity uses the same scale **minus `information`** (`mandatory|potential|optional`, since a finding + is always at least optional). Don't use the old `critical|high|medium|low|info` values. + +## Reference + +Consolidated reference material. The workflow above links here at the step where each part is needed. + +### Report structure + +You author a single `report.json` conforming to the authoritative schema +[scripts/assessment-report.schema.json](scripts/assessment-report.schema.json). The schema is one root object +(draft-07, its sub-types live under `definitions`) with the top-level shape `{ version, producer, metadata, projects, +rules, security? }`. Read the schema for the exact required fields, types, and enums per object — it is the source of +truth and the `validate` command checks it, so this section does **not** restate the field list. `additionalProperties` +is `false` almost everywhere, so **do not invent fields** (there is no `summary` object, and projects have no `issues` / +`storyPoints`). + +**Authoring rules of thumb** — the conventions and cross-field rules the schema can't fully express: + +- `version` is the string `"1.0.0"` (the schema accepts any string; this is the value to use). +- Rule/incident `severity` is the enum `mandatory | potential | optional | information`. Map source severities by meaning + (e.g. critical/blocker → `mandatory`, major/medium → `potential`, minor/low → `optional`, info → `information`). +- **Classification is done with rule fields, not labels.** Each `rules{}` entry sets `domain` + (`cloud-readiness | java-upgrade | security`) and `category` (a free string heading) directly — see + [Rule classification](#rule-classification). `rules{}.labels` and `incidents[].labels` are optional free-form arrays; + you normally leave them out. +- Security-finding `severity` uses the report criticality scale `mandatory | potential | optional` (the rule `Severity` + values minus `information` — a security finding is always at least optional) — normalize per + [Security severity mapping](#security-severity-mapping). +- `metadata.domains` records which assessment domains the report has content for — see + [Assessment domains](#assessment-domains). It must be consistent with the `rule.domain` values you emit. +- `incidentId` convention: `"/"` (n is a per-rule counter). +- `locationKind` = `"source-file"` when a file path is present, else `"unknown"`. +- `status` is normally `"completed"`. +- `metadata.mode` is optional; use `"full"` when the report has security findings, else `"issue-only"`. + +### Assessment domains + +`metadata.domains` is a `string[]` recording which assessment **domains** produced the report. Allowed values are +`cloud-readiness`, `java-upgrade`, and `security`. + +| Domain | Meaning | When to include it for a CSV conversion | +|--------|---------|------------------------------------------| +| `cloud-readiness` | Azure cloud-migration issues | any ordinary issue → solution incident (branch 3) | +| `java-upgrade` | JDK / Spring Boot / Spring Framework / Jakarta EE upgrades | any upgrade incident (branch 2) | +| `security` | CVE / CWE vulnerability findings | `report.security[]` is non-empty (branch 1) | + +- The native Java default is `["cloud-readiness", "java-upgrade"]`. +- Set `metadata.domains` to **exactly the domains your report has content for** — don't list `security` with no + findings, or `java-upgrade` with no upgrade incidents. `validate` flags a `security`/`report.security` mismatch in + either direction. +- `metadata.domains` must be consistent with the `rule.domain` **field** on your rules — every `rule.domain` value you + emit should appear in `metadata.domains`. + +### Security severity mapping + +A security finding's `severity` uses the report criticality scale — `mandatory | potential | optional`. This is the rule +`Severity` enum **minus `information`** (a security finding is always at least optional). The extension renders these +values directly, so there is no separate security severity scale and no conversion step. + +**Map the source CVE/CWE severity by meaning to the nearest value** (case-insensitive): + +| Source severity (CSV, case-insensitive) | Report `security[].severity` | +|-----------------------------------------|------------------------------| +| `critical` / `blocker` | `mandatory` | +| `high` | `mandatory` | +| `medium` / `moderate` | `potential` | +| `low` | `optional` | +| anything else / unknown / missing | `optional` | + +- When merging duplicate findings by `id`, keep the **strongest** severity (`mandatory` > `potential` > `optional`). +- Security findings live in `report.security[]` only; there is no `summary` object to key by severity. `validate` checks + each finding's `severity` is one of the three values and that findings are unique by `id`. +- Include the `security` domain in `metadata.domains` whenever `report.security[]` is non-empty (and only then). + +### Rule classification + +In this schema a rule is classified with **fields on the rule object**, not with labels. Every `rules{}` entry is +**required** to carry a `domain` and a `category` (the `validate` command enforces both, and the schema rejects a +rule that is missing them). + +| Field | Value | Effect | +|-------|-------|--------| +| `domain` | `cloud-readiness` \| `java-upgrade` \| `security` | Groups the rule under that domain tab. Use the same domain you list in `metadata.domains`. **Required.** | +| `category` | the issue category heading (e.g. `postgresql`, `java-version-upgrade`, `deprecated-apis`) | Shown as the group heading. **Required.** | + +**Choosing `category` (and the source label).** Each mapped rule also has a `sourceCategory` in the solution mapping, +which you get from `rules-for-solution ` (`rules[].sourceCategory`). The UI builds the group heading as +`category` when it **equals** `sourceCategory` (or `sourceCategory` is empty / `null`), otherwise as +`category (sourceCategory)`. So: + +- When a rule's `sourceCategory` is **non-null**, set its `category` to **exactly that value** — e.g. + `mi-postgresql` → rule `azure-database-postgresql-02000`, `sourceCategory: "postgresql"` → `category: "postgresql"`, + which renders as one clean **Postgresql** heading (mismatching it, e.g. `category: "database"`, would render the + doubled **Database (Postgresql)**). +- When `sourceCategory` is **`null`** (e.g. the JDK-upgrade rules), choose a sensible `category` yourself + (e.g. `upgrade`) — it renders as-is. + +**Labels are optional.** `rules{}.labels` and `incidents[].labels` are optional free-form `string[]`s in the schema. +Classification no longer depends on them, so you normally leave them out. The engine may still emit context labels +(`target=`, `os=`, `capability=`) on native reports, but when hand-authoring a CSV conversion you do not need any label +to make content render — the required `domain`/`category` **fields** do that. diff --git a/plugins/github-copilot-modernization/skills/assessment-report-converter/scripts/assessment-report.schema.json b/plugins/github-copilot-modernization/skills/assessment-report-converter/scripts/assessment-report.schema.json new file mode 100644 index 0000000..a2a9d57 --- /dev/null +++ b/plugins/github-copilot-modernization/skills/assessment-report-converter/scripts/assessment-report.schema.json @@ -0,0 +1,201 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://aka.ms/ghcp-appmod/assessment-report.schema.json", + "title": "Assessment Report (Unified)", + "description": "Canonical assessment report contract consumed by the GitHub Copilot App Modernization extension. Assessment providers should emit a single JSON document conforming to this schema (typically named report.json) under each report folder.", + "type": "object", + "required": ["version", "producer", "metadata", "projects", "rules"], + "additionalProperties": false, + "properties": { + "version": { + "type": "string", + "description": "Schema version of this document (semver). Use \"1.0.0\" for the initial release." + }, + "producer": { + "type": "string", + "description": "Human-readable name of the tool that generated this report." + }, + "metadata": { + "type": "object", + "description": "Top-level report identity and analysis configuration.", + "required": ["id", "name", "status", "analysisStartTime", "domains", "targetIds"], + "additionalProperties": false, + "properties": { + "id": { "type": "string", "description": "Stable report identifier; also used as the on-disk folder name." }, + "name": { "type": "string", "description": "Display title shown in the report header (e.g. \"Report_202604161657\")." }, + "status": { + "type": "string", + "enum": ["pending", "running", "completed", "failed", "cancelled"], + "description": "Lifecycle status. The UI shows progress while not in a terminal state." + }, + "analysisStartTime": { "type": "string", "format": "date-time" }, + "analysisEndTime": { "type": "string", "format": "date-time" }, + "mode": { + "type": "string", + "enum": ["issue-only", "full"], + "description": "Analysis coverage mode." + }, + "domains": { + "type": "array", + "description": "Assessment domains included in this report. Drives the Issue Summary donuts and the per-domain tables.", + "items": { "type": "string", "enum": ["cloud-readiness", "java-upgrade", "security"] }, + "uniqueItems": true + }, + "targetIds": { + "type": "array", + "description": "Internal target identifiers (e.g. \"azure-appservice\", \"openjdk21\", \"containerization\").", + "items": { "type": "string" } + }, + "targetDisplayNames": { + "type": "array", + "description": "Display labels matching targetIds 1:1 (e.g. \"Azure App Service\"). Shown in the Target Service dropdown.", + "items": { "type": "string" } + }, + "capabilities": { + "type": "array", + "description": "Selected analysis capabilities (e.g. \"openjdk21\", \"containerization\").", + "items": { "type": "string" } + }, + "os": { + "type": "array", + "description": "Target OS list for containerization scenarios.", + "items": { "type": "string" } + }, + "privacyMode": { "type": "string" }, + "privacyModeHelpUrl": { "type": "string", "format": "uri" } + } + }, + "projects": { + "type": "array", + "description": "One entry per analyzed project/module. The first entry drives the Application Information panel for single-project (Java) reports; .NET reports merge incidents across all entries.", + "items": { "$ref": "#/definitions/Project" } + }, + "rules": { + "type": "object", + "description": "Catalog of rules referenced by incidents, keyed by ruleId. Centralizing rule metadata avoids duplication on each incident.", + "additionalProperties": { "$ref": "#/definitions/Rule" } + }, + "security": { + "type": "array", + "description": "Security-domain findings. Required only when metadata.domains contains \"security\".", + "items": { "$ref": "#/definitions/SecurityFinding" } + } + }, + "definitions": { + "Severity": { + "type": "string", + "enum": ["mandatory", "potential", "optional", "information"] + }, + "Link": { + "type": "object", + "required": ["url", "title"], + "additionalProperties": false, + "properties": { + "url": { "type": "string", "format": "uri" }, + "title": { "type": "string" } + } + }, + "TargetOverride": { + "type": "object", + "description": "Per-target override of effort and/or severity for a single incident.", + "additionalProperties": false, + "properties": { + "effort": { "type": "integer", "minimum": 0 }, + "severity": { "$ref": "#/definitions/Severity" } + } + }, + "Project": { + "type": "object", + "required": ["path", "properties", "incidents"], + "additionalProperties": false, + "properties": { + "path": { "type": "string", "description": "Workspace-relative project root." }, + "properties": { + "type": "object", + "required": ["appName"], + "additionalProperties": false, + "properties": { + "appName": { "type": "string" }, + "jdkVersion": { "type": "string" }, + "tools": { "type": "array", "items": { "type": "string" } }, + "frameworks": { "type": "array", "items": { "type": "string" } }, + "languages": { "type": "array", "items": { "type": "string" } } + } + }, + "incidents": { + "type": "array", + "items": { "$ref": "#/definitions/Incident" } + } + } + }, + "Incident": { + "type": "object", + "description": "A single occurrence of a rule violation or insight.", + "required": ["ruleId", "incidentId", "location", "locationKind"], + "additionalProperties": false, + "properties": { + "ruleId": { "type": "string" }, + "incidentId": { "type": "string" }, + "location": { "type": "string" }, + "locationKind": { "type": "string" }, + "line": { "type": "integer", "minimum": 1 }, + "column": { "type": "integer", "minimum": 1 }, + "message": { "type": "string" }, + "snippet": { "type": "string" }, + "targets": { + "type": "object", + "additionalProperties": { "$ref": "#/definitions/TargetOverride" } + }, + "labels": { + "type": "array", + "items": { "type": "string" } + } + } + }, + "Rule": { + "type": "object", + "required": ["id", "title", "severity", "effort", "domain", "category"], + "additionalProperties": false, + "properties": { + "id": { "type": "string" }, + "title": { "type": "string" }, + "description": { "type": "string" }, + "severity": { "$ref": "#/definitions/Severity" }, + "effort": { "type": "integer", "minimum": 0 }, + "domain": { + "type": "string", + "enum": ["cloud-readiness", "java-upgrade", "security"] + }, + "category": { "type": "string" }, + "labels": { + "type": "array", + "items": { "type": "string" } + }, + "containerization": { "type": "boolean" }, + "links": { "type": "array", "items": { "$ref": "#/definitions/Link" } } + } + }, + "SecurityFinding": { + "type": "object", + "required": ["id", "title", "category", "severity", "description", "evidence"], + "additionalProperties": false, + "properties": { + "id": { "type": "string" }, + "title": { "type": "string" }, + "category": { "type": "string" }, + "severity": { "type": "string", "enum": ["mandatory", "potential", "optional"] }, + "description": { "type": "string" }, + "storyPoint": { "type": "integer", "minimum": 0 }, + "evidence": { + "type": "object", + "required": ["files", "explanation"], + "additionalProperties": false, + "properties": { + "files": { "type": "array", "items": { "type": "string" } }, + "explanation": { "type": "string" } + } + } + } + } + } +} \ No newline at end of file diff --git a/plugins/github-copilot-modernization/skills/assessment-report-converter/scripts/report_tools.ps1 b/plugins/github-copilot-modernization/skills/assessment-report-converter/scripts/report_tools.ps1 new file mode 100644 index 0000000..ff120f0 --- /dev/null +++ b/plugins/github-copilot-modernization/skills/assessment-report-converter/scripts/report_tools.ps1 @@ -0,0 +1,494 @@ +#!/usr/bin/env pwsh +# +# Helper tools for the `assessment-report-converter` skill (PowerShell). +# +# This skill is LLM-driven: the agent reads the CSV, understands its columns, +# classifies every row, and authors report.json by hand against the schema. This +# script does NOT parse CSVs and makes NO assumptions about CSV columns. It only +# provides the deterministic lookups and validation the agent needs: +# +# list-solutions [--query KW] [--type Formula|Chat] [--ids-only] +# Print known migration solutions from solution-mapping.json, optionally +# filtered by a keyword/type. Use this to pick the right migration +# solution for an ordinary issue. +# +# rules-for-solution SOLUTION_ID +# Print the ruleId(s) mapped to a solutionId (with sourceCategory). Put a +# returned ruleId on the incident and in rules{} so the solution resolves +# downstream. An empty list means the solution has no rule. +# +# upgrade-solutions +# Print the canonical major-component upgrade solutions (jdk / spring-boot +# / spring-framework / jakarta-ee), each resolved to its ruleId. +# +# validate REPORT_JSON [--schema PATH] +# Validate a finished report.json. Runs structural + cross-field +# consistency checks (required fields, enums, every incident.ruleId exists +# in rules{}, security findings unique by id, domain/security consistency). +# --schema is accepted for CLI compatibility but ignored — these checks +# are self-contained and do not load an external JSON Schema. +# +# This is a PowerShell port of report_tools.sh; the two must stay behaviourally +# identical (same output data, same exit codes: 0 valid, 1 invalid, 2 error). + +Set-StrictMode -Version Latest +$ErrorActionPreference = 'Stop' + +$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path +$MappingPath = Join-Path $ScriptDir 'solution-mapping.json' + +# Enums — mirror the `enum` arrays in assessment-report.schema.json. The schema +# is the source of truth; the skill tests fail if the two drift apart. +$RULE_SEVERITY_ENUM = @('mandatory', 'potential', 'optional', 'information') +$SECURITY_SEVERITY_ENUM = @('mandatory', 'potential', 'optional') +$STATUS_ENUM = @('pending', 'running', 'completed', 'failed', 'cancelled') +$MODE_ENUM = @('issue-only', 'full') +$DOMAIN_ENUM = @('cloud-readiness', 'java-upgrade', 'security') + +function Die([string]$msg) { + [Console]::Error.WriteLine("ERROR: $msg") + exit 2 +} + +function Read-Mapping { + if (-not (Test-Path -LiteralPath $MappingPath)) { + Die "solution-mapping.json not found next to this script ($MappingPath)." + } + try { + return (Get-Content -LiteralPath $MappingPath -Raw -Encoding UTF8 | ConvertFrom-Json) + } catch { + Die "solution-mapping.json is not valid JSON ($MappingPath)." + } +} + +function Test-IsObject($v) { $v -is [System.Management.Automation.PSCustomObject] } +function Test-IsArray($v) { ($v -is [System.Array]) -or ($v -is [System.Collections.ArrayList]) } +function Test-IsNumber($v) { + ($v -is [int] -or $v -is [long] -or $v -is [double] -or $v -is [decimal] -or $v -is [single]) -and ($v -isnot [bool]) +} +function Test-Uint($v) { (Test-IsNumber $v) -and ([double]$v -eq [math]::Floor([double]$v)) -and ([double]$v -ge 0) } +function Test-PosInt($v) { (Test-IsNumber $v) -and ([double]$v -eq [math]::Floor([double]$v)) -and ([double]$v -ge 1) } + +function Has($obj, [string]$key) { + if (-not (Test-IsObject $obj)) { return $false } + return ($null -ne $obj.PSObject.Properties[$key]) +} +function Get-Prop($obj, [string]$key) { + if (-not (Has $obj $key)) { return $null } + $val = $obj.$key + # Wrap only arrays with the unary comma so the pipeline doesn't unroll them + # (a single-element array would otherwise collapse to a scalar). Scalars are + # returned as-is so fields like ruleId/sourceCategory keep their scalar shape + # and string casts/comparisons behave the same as the bash implementation. + if (Test-IsArray $val) { return ,$val } + return $val +} + +# jq `tojson` for a scalar used inside a message (strings become double-quoted, +# $null becomes null, numbers/bools render bare). +function Fmt($v) { + if ($null -eq $v) { return 'null' } + if ($v -is [bool]) { if ($v) { return 'true' } else { return 'false' } } + if ($v -is [string]) { return ($v | ConvertTo-Json -Compress) } + if (Test-IsNumber $v) { return ([string]$v) } + return ($v | ConvertTo-Json -Compress -Depth 20) +} + +# Render an array (possibly empty / single element) as a JSON array string. +function ConvertTo-JsonArray($arr) { + $items = New-Object System.Collections.Generic.List[object] + if ($null -ne $arr) { foreach ($x in $arr) { $items.Add($x) } } + if ($items.Count -eq 0) { return '[]' } + return ($items.ToArray() | ConvertTo-Json -Depth 20 -AsArray) +} + +# --------------------------------------------------------------------------- # +# Shared helper: ordered {ruleId, sourceCategory} list for a solution id. +# --------------------------------------------------------------------------- # +function Get-RulesForSolution($mapping, [string]$solutionId) { + $out = New-Object System.Collections.Generic.List[object] + $rules = Get-Prop $mapping 'rules' + if (Test-IsArray $rules) { + foreach ($entry in $rules) { + if ((Get-Prop $entry 'solution') -eq $solutionId) { + $out.Add([ordered]@{ + ruleId = (Get-Prop $entry 'ruleId') + sourceCategory = (Get-Prop $entry 'sourceCategory') + }) + } + } + } + return $out +} + +# --------------------------------------------------------------------------- # +# Subcommand: list-solutions +# --------------------------------------------------------------------------- # +function Invoke-ListSolutions([string[]]$rest) { + $query = '' + $typeFilter = '' + $idsOnly = $false + for ($i = 0; $i -lt $rest.Count; $i++) { + switch -Wildcard ($rest[$i]) { + '--query' { $query = $rest[++$i]; break } + '--query=*' { $query = $rest[$i].Substring(8); break } + '--type' { $typeFilter = $rest[++$i]; break } + '--type=*' { $typeFilter = $rest[$i].Substring(7); break } + '--ids-only' { $idsOnly = $true; break } + default { Die "list-solutions: unexpected argument '$($rest[$i])'" } + } + } + $mapping = Read-Mapping + $solutions = Get-Prop $mapping 'solutions' + if (-not (Test-IsArray $solutions)) { $solutions = @() } + + $q = ($query).Trim().ToLowerInvariant() + $t = ($typeFilter).Trim().ToLowerInvariant() + + $selected = New-Object System.Collections.Generic.List[object] + foreach ($sol in $solutions) { + if ($t -ne '') { + $solType = ([string](Get-Prop $sol 'type')).ToLowerInvariant() + if ($solType -ne $t) { continue } + } + if ($q -ne '') { + $parts = @('solutionId', 'name', 'tooltip') | ForEach-Object { [string](Get-Prop $sol $_) } + $haystack = ($parts -join ' ').ToLowerInvariant() + if (-not $haystack.Contains($q)) { continue } + } + $selected.Add($sol) + } + + if ($idsOnly) { + foreach ($sol in $selected) { [Console]::Out.WriteLine([string](Get-Prop $sol 'solutionId')) } + return 0 + } + + [Console]::Out.WriteLine((ConvertTo-JsonArray $selected)) + if ($q -ne '') { + [Console]::Error.WriteLine("# $($selected.Count) solution(s) matching $(Fmt $query)") + } else { + [Console]::Error.WriteLine("# $($selected.Count) solution(s)") + } + return 0 +} + +# --------------------------------------------------------------------------- # +# Subcommand: rules-for-solution +# --------------------------------------------------------------------------- # +function Invoke-RulesForSolution([string[]]$rest) { + if ($rest.Count -lt 1) { Die 'rules-for-solution: SOLUTION_ID is required.' } + $solutionId = $rest[0] + $mapping = Read-Mapping + $rules = @(Get-RulesForSolution $mapping $solutionId) + $preferred = $null + if ($rules.Count -gt 0) { $preferred = $rules[0].ruleId } + + $result = [ordered]@{ + solutionId = $solutionId + ruleCount = $rules.Count + rules = @($rules) + preferredRuleId = $preferred + } + [Console]::Out.WriteLine(($result | ConvertTo-Json -Depth 20)) + if ($rules.Count -eq 0) { + [Console]::Error.WriteLine("# no rule maps to $(Fmt $solutionId) (likely a security-only solution; do not invent a ruleId)") + } + return 0 +} + +# --------------------------------------------------------------------------- # +# Subcommand: upgrade-solutions +# --------------------------------------------------------------------------- # +function Invoke-UpgradeSolutions([string[]]$rest) { + $components = [ordered]@{ + 'jdk' = @{ solution = 'java-version-upgrade'; label = 'Java runtime (JDK / Java SE)'; fallback = 'azure-java-version-01000' } + 'spring-boot' = @{ solution = 'spring-boot-upgrade'; label = 'Spring Boot'; fallback = 'spring-boot-to-azure-spring-boot-version-01000' } + 'spring-framework' = @{ solution = 'spring-framework-upgrade'; label = 'Spring Framework'; fallback = 'spring-framework-version-01000' } + 'jakarta-ee' = @{ solution = 'jakarta-ee-upgrade'; label = 'Java EE / Jakarta EE'; fallback = 'jakarta-ee-version-01000' } + } + + $mapping = $null + if (Test-Path -LiteralPath $MappingPath) { + try { $mapping = Get-Content -LiteralPath $MappingPath -Raw -Encoding UTF8 | ConvertFrom-Json } catch { $mapping = $null } + } + + $out = [ordered]@{} + foreach ($component in $components.Keys) { + $spec = $components[$component] + $sid = $spec.solution + $ruleIds = @() + if ($null -ne $mapping) { + $ruleIds = @(Get-RulesForSolution $mapping $sid | ForEach-Object { $_.ruleId }) + } + $preferred = if ($ruleIds.Count -gt 0) { $ruleIds[0] } else { $spec.fallback } + $out[$component] = [ordered]@{ + label = $spec.label + solutionId = $sid + ruleIds = $ruleIds + preferredRuleId = $preferred + } + } + [Console]::Out.WriteLine(($out | ConvertTo-Json -Depth 20)) + return 0 +} + +# --------------------------------------------------------------------------- # +# Subcommand: validate (structural + cross-field checks only) +# --------------------------------------------------------------------------- # +function Get-StructuralErrors($report) { + $errors = New-Object System.Collections.Generic.List[string] + + function AddMissing($obj, [string[]]$keys, [string]$where) { + if (-not (Test-IsObject $obj)) { $errors.Add("${where}: expected an object"); return } + foreach ($k in $keys) { + if (-not (Has $obj $k)) { $errors.Add("${where}: missing required field $(Fmt $k)") } + } + } + + if (-not (Test-IsObject $report)) { + $errors.Add('report: expected a JSON object') + return ,$errors + } + + # ---- report required ---- + AddMissing $report @('version', 'producer', 'metadata', 'projects', 'rules') 'report' + + # ---- metadata ---- + $meta = Get-Prop $report 'metadata' + if (-not (Test-IsObject $meta)) { + $errors.Add('metadata: expected an object') + } else { + AddMissing $meta @('id', 'name', 'status', 'analysisStartTime', 'domains', 'targetIds') 'metadata' + if (Has $meta 'status') { + $status = Get-Prop $meta 'status' + if ($STATUS_ENUM -notcontains $status) { + $errors.Add("metadata.status: invalid value $(Fmt $status) (must be one of $($STATUS_ENUM -join ' | '))") + } + } + if (Has $meta 'mode') { + $mode = Get-Prop $meta 'mode' + if ($MODE_ENUM -notcontains $mode) { + $errors.Add("metadata.mode: invalid value $(Fmt $mode) (must be one of $($MODE_ENUM -join ' | '))") + } + } + if (Has $meta 'domains') { + $domains = Get-Prop $meta 'domains' + if (-not (Test-IsArray $domains)) { + $errors.Add('metadata.domains: expected an array') + } else { + foreach ($d in $domains) { + if ($DOMAIN_ENUM -notcontains $d) { + $errors.Add("metadata.domains: invalid value $(Fmt $d) (must be one of $($DOMAIN_ENUM -join ' | '))") + } + } + } + } + } + + # ---- rules (object keyed by ruleId) ---- + $ruleIds = @() + $rules = Get-Prop $report 'rules' + if (-not (Test-IsObject $rules)) { + $errors.Add('rules: expected an object keyed by ruleId') + } else { + foreach ($prop in $rules.PSObject.Properties) { + $rid = $prop.Name + $rule = $prop.Value + $ruleIds += $rid + AddMissing $rule @('id', 'title', 'severity', 'effort', 'domain', 'category') "rules[$rid]" + # Run the value checks independently of missing-field checks (guarded by + # Has), so a rule that is both missing a field AND carries an invalid + # value reports both — matching report_tools.sh, which concatenates. + if (Test-IsObject $rule) { + if ((Has $rule 'severity') -and ($RULE_SEVERITY_ENUM -notcontains (Get-Prop $rule 'severity'))) { + $errors.Add("rules[$rid].severity: invalid value $(Fmt (Get-Prop $rule 'severity')) (must be one of $($RULE_SEVERITY_ENUM -join ' | '))") + } + if ((Has $rule 'effort') -and (-not (Test-Uint (Get-Prop $rule 'effort')))) { + $errors.Add("rules[$rid].effort: must be an integer >= 0") + } + if ((Has $rule 'domain') -and ($DOMAIN_ENUM -notcontains (Get-Prop $rule 'domain'))) { + $errors.Add("rules[$rid].domain: invalid value $(Fmt (Get-Prop $rule 'domain')) (must be one of $($DOMAIN_ENUM -join ' | '))") + } + } + } + } + + # ---- projects + incidents ---- + $projects = Get-Prop $report 'projects' + if (-not (Test-IsArray $projects)) { + $errors.Add('projects: expected an array') + } else { + for ($pi = 0; $pi -lt @($projects).Count; $pi++) { + $project = @($projects)[$pi] + $pw = "projects[$pi]" + AddMissing $project @('path', 'properties', 'incidents') $pw + if (-not (Test-IsObject $project)) { continue } + + $props = Get-Prop $project 'properties' + if ($null -eq $props) { $props = [PSCustomObject]@{} } + AddMissing $props @('appName') "$pw.properties" + + $incidents = Get-Prop $project 'incidents' + if ((Has $project 'incidents') -and (-not (Test-IsArray $incidents))) { + $errors.Add("$pw.incidents: expected an array") + } elseif (Test-IsArray $incidents) { + for ($ii = 0; $ii -lt @($incidents).Count; $ii++) { + $inc = @($incidents)[$ii] + $iw = "$pw.incidents[$ii]" + AddMissing $inc @('ruleId', 'incidentId', 'location', 'locationKind') $iw + if (Test-IsObject $inc) { + if ((Has $inc 'ruleId') -and ($ruleIds -notcontains (Get-Prop $inc 'ruleId'))) { + $errors.Add("$iw.ruleId $(Fmt (Get-Prop $inc 'ruleId')) has no matching entry in rules{}") + } + if ((Has $inc 'line') -and (-not (Test-PosInt (Get-Prop $inc 'line')))) { + $errors.Add("$iw.line: must be an integer >= 1") + } + if ((Has $inc 'column') -and (-not (Test-PosInt (Get-Prop $inc 'column')))) { + $errors.Add("$iw.column: must be an integer >= 1") + } + } + } + } + } + } + + # ---- security findings ---- + $security = Get-Prop $report 'security' + if ($null -eq $security) { $security = @() } + if (-not (Test-IsArray $security)) { + $errors.Add('security: expected an array') + $security = @() + } + $ids = New-Object System.Collections.Generic.List[object] + for ($si = 0; $si -lt @($security).Count; $si++) { + $finding = @($security)[$si] + $sw = "security[$si]" + AddMissing $finding @('id', 'title', 'category', 'severity', 'description', 'evidence') $sw + if (Test-IsObject $finding) { + # Collect every object finding's id (even ones missing other fields) so + # duplicate detection matches report_tools.sh's group_by(.id). + $ids.Add((Get-Prop $finding 'id')) + if ((Has $finding 'severity') -and ($SECURITY_SEVERITY_ENUM -notcontains (Get-Prop $finding 'severity'))) { + $errors.Add("$sw.severity: invalid value $(Fmt (Get-Prop $finding 'severity')) (must be one of $($SECURITY_SEVERITY_ENUM -join ' | ') — normalize the source CVE/CWE severity)") + } + # Mirror bash `($finding.evidence // {})`: a missing evidence defaults to + # {} so its own required sub-fields are reported, rather than only + # "expected an object". + $ev = Get-Prop $finding 'evidence' + if ($null -eq $ev) { $ev = [PSCustomObject]@{} } + if (-not (Test-IsObject $ev)) { + $errors.Add("$sw.evidence: expected an object") + } else { + AddMissing $ev @('files', 'explanation') "$sw.evidence" + if ((Has $ev 'files') -and (-not (Test-IsArray (Get-Prop $ev 'files')))) { + $errors.Add("$sw.evidence.files: must be an array") + } + } + } + } + # duplicate ids (one message per duplicated id, in first-seen order) + $seen = @{} + $dupReported = @{} + foreach ($id in $ids) { + $key = if ($null -eq $id) { "`0null`0" } else { [string]$id } + if ($seen.ContainsKey($key)) { + if (-not $dupReported.ContainsKey($key)) { + $errors.Add("security id $(Fmt $id) is duplicated (merge findings by id)") + $dupReported[$key] = $true + } + } else { + $seen[$key] = $true + } + } + + # ---- domain <-> security consistency ---- + $domains2 = Get-Prop $meta 'domains' + if (-not (Test-IsArray $domains2)) { $domains2 = @() } + $secArr = Get-Prop $report 'security' + if (-not (Test-IsArray $secArr)) { $secArr = @() } + if (($domains2 -contains 'security') -and (@($secArr).Count -eq 0)) { + $errors.Add('metadata.domains includes "security" but report.security is empty') + } + if ((@($secArr).Count -gt 0) -and ($domains2 -notcontains 'security')) { + $errors.Add('report.security has findings but metadata.domains does not include "security"') + } + + return ,$errors +} + +function Invoke-Validate([string[]]$rest) { + $report = '' + $schema = '' + for ($i = 0; $i -lt $rest.Count; $i++) { + switch -Wildcard ($rest[$i]) { + '--schema' { $schema = $rest[++$i]; break } + '--schema=*' { $schema = $rest[$i].Substring(9); break } + '-*' { Die "validate: unexpected option '$($rest[$i])'" } + default { + if ($report -eq '') { $report = $rest[$i] } + else { Die "validate: unexpected argument '$($rest[$i])'" } + } + } + } + $null = $schema # accepted for compatibility; unused + if ($report -eq '') { Die 'validate: REPORT_JSON path is required.' } + if (-not (Test-Path -LiteralPath $report)) { Die "cannot read report: $report" } + try { + $data = Get-Content -LiteralPath $report -Raw -Encoding UTF8 | ConvertFrom-Json + } catch { + Die "report is not valid JSON: $report" + } + + $errors = Get-StructuralErrors $data + + [Console]::Out.WriteLine("Report: $report") + [Console]::Out.WriteLine(('-' * 60)) + if ($errors.Count -eq 0) { + [Console]::Out.WriteLine('structural + consistency checks: OK') + } else { + [Console]::Out.WriteLine("structural + consistency checks: $($errors.Count) error(s)") + foreach ($line in $errors) { [Console]::Out.WriteLine(" - $line") } + } + [Console]::Out.WriteLine(('-' * 60)) + if ($errors.Count -eq 0) { + [Console]::Out.WriteLine('RESULT: VALID') + return 0 + } else { + [Console]::Out.WriteLine('RESULT: INVALID') + return 1 + } +} + +# --------------------------------------------------------------------------- # +# CLI dispatch +# --------------------------------------------------------------------------- # +function Show-Usage { + [Console]::Error.WriteLine(@' +Usage: report_tools.ps1 [args] + +Commands: + list-solutions [--query KW] [--type Formula|Chat] [--ids-only] + rules-for-solution SOLUTION_ID + upgrade-solutions + validate REPORT_JSON [--schema PATH] +'@) + exit 2 +} + +$argv = @($args) +if ($argv.Count -lt 1) { Show-Usage } +$command = $argv[0] +$rest = @() +if ($argv.Count -gt 1) { $rest = $argv[1..($argv.Count - 1)] } + +switch ($command) { + 'list-solutions' { exit (Invoke-ListSolutions $rest) } + 'rules-for-solution' { exit (Invoke-RulesForSolution $rest) } + 'upgrade-solutions' { exit (Invoke-UpgradeSolutions $rest) } + 'validate' { exit (Invoke-Validate $rest) } + '-h' { Show-Usage } + '--help' { Show-Usage } + 'help' { Show-Usage } + default { Die "unknown command '$command' (see --help)" } +} diff --git a/plugins/github-copilot-modernization/skills/assessment-report-converter/scripts/report_tools.sh b/plugins/github-copilot-modernization/skills/assessment-report-converter/scripts/report_tools.sh new file mode 100644 index 0000000..09c282d --- /dev/null +++ b/plugins/github-copilot-modernization/skills/assessment-report-converter/scripts/report_tools.sh @@ -0,0 +1,349 @@ +#!/usr/bin/env bash +# +# Helper tools for the `assessment-report-converter` skill (bash + jq). +# +# This skill is LLM-driven: the agent reads the CSV, understands its columns, +# classifies every row, and authors report.json by hand against the schema. This +# script does NOT parse CSVs and makes NO assumptions about CSV columns. It only +# provides the deterministic lookups and validation the agent needs: +# +# list-solutions [--query KW] [--type Formula|Chat] [--ids-only] +# Print known migration solutions from solution-mapping.json, optionally +# filtered by a keyword/type. Use this to pick the right migration +# solution for an ordinary issue. +# +# rules-for-solution SOLUTION_ID +# Print the ruleId(s) mapped to a solutionId (with sourceCategory). Put a +# returned ruleId on the incident and in rules{} so the solution resolves +# downstream. An empty list means the solution has no rule. +# +# upgrade-solutions +# Print the canonical major-component upgrade solutions (jdk / spring-boot +# / spring-framework / jakarta-ee), each resolved to its ruleId. +# +# validate REPORT_JSON [--schema PATH] +# Validate a finished report.json. Runs structural + cross-field +# consistency checks (required fields, enums, every incident.ruleId exists +# in rules{}, security findings unique by id, domain/security consistency). +# --schema is accepted for CLI compatibility but ignored — these checks +# are self-contained and do not load an external JSON Schema. +# +# Requires: bash + jq. + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +MAPPING_PATH="$SCRIPT_DIR/solution-mapping.json" + +# Enums — mirror the `enum` arrays in assessment-report.schema.json. The schema +# is the source of truth; the skill tests fail if the two drift apart. +RULE_SEVERITY_ENUM='["mandatory","potential","optional","information"]' +SECURITY_SEVERITY_ENUM='["mandatory","potential","optional"]' +STATUS_ENUM='["pending","running","completed","failed","cancelled"]' +MODE_ENUM='["issue-only","full"]' +DOMAIN_ENUM='["cloud-readiness","java-upgrade","security"]' + +die() { echo "ERROR: $*" >&2; exit 2; } + +require_jq() { + command -v jq >/dev/null 2>&1 || die "jq is required but was not found on PATH (install jq)." +} + +load_mapping() { + [ -f "$MAPPING_PATH" ] || die "solution-mapping.json not found next to this script ($MAPPING_PATH)." +} + +hr() { printf '%.0s-' $(seq 1 60); echo; } + +# --------------------------------------------------------------------------- # +# Subcommand: list-solutions +# --------------------------------------------------------------------------- # +cmd_list_solutions() { + local query="" type_filter="" ids_only=0 + while [ $# -gt 0 ]; do + case "$1" in + --query) query="${2:-}"; shift 2 ;; + --query=*) query="${1#*=}"; shift ;; + --type) type_filter="${2:-}"; shift 2 ;; + --type=*) type_filter="${1#*=}"; shift ;; + --ids-only) ids_only=1; shift ;; + *) die "list-solutions: unexpected argument '$1'" ;; + esac + done + load_mapping + + local q; q="$(printf '%s' "$query" | tr '[:upper:]' '[:lower:]' | sed -e 's/^ *//' -e 's/ *$//')" + local t; t="$(printf '%s' "$type_filter" | tr '[:upper:]' '[:lower:]' | sed -e 's/^ *//' -e 's/ *$//')" + + local selected + selected="$(jq --arg q "$q" --arg t "$t" ' + (.solutions // []) + | map(select( + (($t == "") or ((.type // "" | ascii_downcase) == $t)) + and + (($q == "") or + (([.solutionId, .name, .tooltip] | map(. // "" | tostring) | join(" ") | ascii_downcase) | contains($q))) + )) + ' "$MAPPING_PATH")" + + if [ "$ids_only" -eq 1 ]; then + printf '%s' "$selected" | jq -r '.[].solutionId // ""' + return 0 + fi + + printf '%s\n' "$selected" | jq '.' + local count; count="$(printf '%s' "$selected" | jq 'length')" + if [ -n "$q" ]; then + printf '# %s solution(s) matching "%s"\n' "$count" "$query" >&2 + else + printf '# %s solution(s)\n' "$count" >&2 + fi +} + +# --------------------------------------------------------------------------- # +# Subcommand: rules-for-solution +# --------------------------------------------------------------------------- # +cmd_rules_for_solution() { + [ $# -ge 1 ] || die "rules-for-solution: SOLUTION_ID is required." + local solution_id="$1" + load_mapping + + jq --arg sid "$solution_id" ' + [ (.rules // [])[] | select(.solution == $sid) | {ruleId: .ruleId, sourceCategory: .sourceCategory} ] as $rules + | { + solutionId: $sid, + ruleCount: ($rules | length), + rules: $rules, + preferredRuleId: ($rules[0].ruleId // null) + } + ' "$MAPPING_PATH" + + local count; count="$(jq --arg sid "$solution_id" '[ (.rules // [])[] | select(.solution == $sid) ] | length' "$MAPPING_PATH")" + if [ "$count" -eq 0 ]; then + printf '# no rule maps to "%s" (likely a security-only solution; do not invent a ruleId)\n' "$solution_id" >&2 + fi +} + +# --------------------------------------------------------------------------- # +# Subcommand: upgrade-solutions +# --------------------------------------------------------------------------- # +cmd_upgrade_solutions() { + local mapping_json="{}" + if [ -f "$MAPPING_PATH" ]; then + mapping_json="$(cat "$MAPPING_PATH")" + fi + + jq -n --argjson mapping "$mapping_json" ' + def rules_for($sid): [ ($mapping.rules // [])[] | select(.solution == $sid) | .ruleId ]; + { + "jdk": {solution: "java-version-upgrade", label: "Java runtime (JDK / Java SE)", fallback: "azure-java-version-01000"}, + "spring-boot": {solution: "spring-boot-upgrade", label: "Spring Boot", fallback: "spring-boot-to-azure-spring-boot-version-01000"}, + "spring-framework": {solution: "spring-framework-upgrade", label: "Spring Framework", fallback: "spring-framework-version-01000"}, + "jakarta-ee": {solution: "jakarta-ee-upgrade", label: "Java EE / Jakarta EE", fallback: "jakarta-ee-version-01000"} + } + | to_entries + | map( + .value.solution as $sid + | rules_for($sid) as $ids + | { + key: .key, + value: { + label: .value.label, + solutionId: $sid, + ruleIds: $ids, + preferredRuleId: ($ids[0] // .value.fallback) + } + } + ) + | from_entries + ' +} + +# --------------------------------------------------------------------------- # +# Subcommand: validate (structural + cross-field checks only) +# --------------------------------------------------------------------------- # +cmd_validate() { + local report="" schema="" + while [ $# -gt 0 ]; do + case "$1" in + --schema) schema="${2:-}"; shift 2 ;; + --schema=*) schema="${1#*=}"; shift ;; + -*) die "validate: unexpected option '$1'" ;; + *) if [ -z "$report" ]; then report="$1"; shift; else die "validate: unexpected argument '$1'"; fi ;; + esac + done + : "${schema:-}" # accepted for compatibility; unused + [ -n "$report" ] || die "validate: REPORT_JSON path is required." + [ -f "$report" ] || die "cannot read report: $report" + jq empty "$report" >/dev/null 2>&1 || die "report is not valid JSON: $report" + + local errors + errors="$(jq -r \ + --argjson sev "$RULE_SEVERITY_ENUM" \ + --argjson ssev "$SECURITY_SEVERITY_ENUM" \ + --argjson status "$STATUS_ENUM" \ + --argjson mode "$MODE_ENUM" \ + --argjson domain "$DOMAIN_ENUM" ' + def missing($obj; $keys; $where): + if ($obj | type) != "object" then ["\($where): expected an object"] + else [ $keys[] as $k | select(($obj | has($k)) | not) | "\($where): missing required field \($k|tojson)" ] + end; + def is_uint($v): ($v | type) == "number" and ($v == ($v | floor)) and ($v >= 0); + def is_pos_int($v): ($v | type) == "number" and ($v == ($v | floor)) and ($v >= 1); + + . as $r + | if ($r | type) != "object" then ["report: expected a JSON object"] + else + # ---- report required ---- + missing($r; ["version","producer","metadata","projects","rules"]; "report") + + + # ---- metadata ---- + ( ($r.metadata) as $meta + | if ($meta | type) != "object" then ["metadata: expected an object"] + else + missing($meta; ["id","name","status","analysisStartTime","domains","targetIds"]; "metadata") + + (if ($meta | has("status")) and (($status | index($meta.status)) == null) + then ["metadata.status: invalid value \($meta.status|tojson) (must be one of \($status|join(" | ")))"] else [] end) + + (if ($meta | has("mode")) and (($mode | index($meta.mode)) == null) + then ["metadata.mode: invalid value \($meta.mode|tojson) (must be one of \($mode|join(" | ")))"] else [] end) + + (if ($meta | has("domains")) and (($meta.domains | type) != "array") + then ["metadata.domains: expected an array"] + elif ($meta | has("domains")) + then [ $meta.domains[] as $d | select(($domain | index($d)) == null) | "metadata.domains: invalid value \($d|tojson) (must be one of \($domain|join(" | ")))" ] + else [] end) + end ) + + + # ---- rules ---- + ( ($r.rules) as $rules + | if ($rules | type) != "object" then ["rules: expected an object keyed by ruleId"] + else + [ $rules | to_entries[] + | .key as $rid | .value as $rule + | (missing($rule; ["id","title","severity","effort","domain","category"]; "rules[\($rid)]") + + (if ($rule | type) == "object" then + (if ($rule | has("severity")) and (($sev | index($rule.severity)) == null) + then ["rules[\($rid)].severity: invalid value \($rule.severity|tojson) (must be one of \($sev|join(" | ")))"] else [] end) + + (if ($rule | has("effort")) and (is_uint($rule.effort) | not) + then ["rules[\($rid)].effort: must be an integer >= 0"] else [] end) + + (if ($rule | has("domain")) and (($domain | index($rule.domain)) == null) + then ["rules[\($rid)].domain: invalid value \($rule.domain|tojson) (must be one of \($domain|join(" | ")))"] else [] end) + else [] end)) + ] | add // [] + end ) + + + # ---- projects + incidents ---- + ( ($r.rules // {} | keys) as $ruleIds + | ($r.projects) as $projects + | if ($projects | type) != "array" then ["projects: expected an array"] + else + [ $projects | to_entries[] + | .key as $pi | .value as $project + | "projects[\($pi)]" as $pw + | (missing($project; ["path","properties","incidents"]; $pw) + + (if ($project | type) == "object" then + (missing(($project.properties // {}); ["appName"]; "\($pw).properties")) + + (if ($project | has("incidents")) and (($project.incidents | type) != "array") + then ["\($pw).incidents: expected an array"] + elif (($project.incidents // []) | type) == "array" then + [ ($project.incidents // []) | to_entries[] + | .key as $ii | .value as $inc + | "\($pw).incidents[\($ii)]" as $iw + | (missing($inc; ["ruleId","incidentId","location","locationKind"]; $iw) + + (if ($inc | type) == "object" then + (if ($inc | has("ruleId")) and (($ruleIds | index($inc.ruleId)) == null) + then ["\($iw).ruleId \($inc.ruleId|tojson) has no matching entry in rules{}"] else [] end) + + (if ($inc | has("line")) and (is_pos_int($inc.line) | not) then ["\($iw).line: must be an integer >= 1"] else [] end) + + (if ($inc | has("column")) and (is_pos_int($inc.column) | not) then ["\($iw).column: must be an integer >= 1"] else [] end) + else [] end)) + ] | add // [] + else [] end) + else [] end)) + ] | add // [] + end ) + + + # ---- security findings ---- + ( ($r.security // []) as $security0 + | if ($security0 | type) != "array" then ["security: expected an array"] + else + ([ $security0 | to_entries[] + | .key as $si | .value as $finding + | "security[\($si)]" as $sw + | (missing($finding; ["id","title","category","severity","description","evidence"]; $sw) + + (if ($finding | type) == "object" then + (if ($finding | has("severity")) and (($ssev | index($finding.severity)) == null) + then ["\($sw).severity: invalid value \($finding.severity|tojson) (must be one of \($ssev|join(" | ")) — normalize the source CVE/CWE severity)"] else [] end) + + (($finding.evidence // {}) as $ev + | if ($ev | type) != "object" then ["\($sw).evidence: expected an object"] + else missing($ev; ["files","explanation"]; "\($sw).evidence") + + (if ($ev | has("files")) and (($ev.files | type) != "array") then ["\($sw).evidence.files: must be an array"] else [] end) + end) + else [] end)) + ] | add // []) + + ( [ $security0[] | select(type=="object") ] + | group_by(.id) | [ .[] | select(length > 1) | .[0].id ] + | map("security id \(.|tojson) is duplicated (merge findings by id)") ) + end ) + + + # ---- domain <-> security consistency ---- + ( ($r.metadata.domains // []) as $domains + | ($r.security // []) as $sec + | (if (($domains | type) == "array") and ($domains | index("security")) and (($sec|length) == 0) + then ["metadata.domains includes \"security\" but report.security is empty"] else [] end) + + (if (($sec|length) > 0) and (($domains | index("security")) == null) + then ["report.security has findings but metadata.domains does not include \"security\""] else [] end) ) + end + | .[] + ' "$report")" + + echo "Report: $report" + hr + if [ -z "$errors" ]; then + echo "structural + consistency checks: OK" + else + local n; n="$(printf '%s\n' "$errors" | grep -c .)" + echo "structural + consistency checks: $n error(s)" + printf '%s\n' "$errors" | while IFS= read -r line; do + [ -n "$line" ] && echo " - $line" + done + fi + hr + if [ -z "$errors" ]; then + echo "RESULT: VALID" + return 0 + else + echo "RESULT: INVALID" + return 1 + fi +} + +# --------------------------------------------------------------------------- # +# CLI dispatch +# --------------------------------------------------------------------------- # +usage() { + cat >&2 <<'EOF' +Usage: report_tools.sh [args] + +Commands: + list-solutions [--query KW] [--type Formula|Chat] [--ids-only] + rules-for-solution SOLUTION_ID + upgrade-solutions + validate REPORT_JSON [--schema PATH] +EOF + exit 2 +} + +main() { + require_jq + [ $# -ge 1 ] || usage + local command="$1"; shift + case "$command" in + list-solutions) cmd_list_solutions "$@" ;; + rules-for-solution) cmd_rules_for_solution "$@" ;; + upgrade-solutions) cmd_upgrade_solutions "$@" ;; + validate) cmd_validate "$@" ;; + -h|--help|help) usage ;; + *) die "unknown command '$command' (see --help)" ;; + esac +} + +main "$@" diff --git a/plugins/github-copilot-modernization/skills/assessment-report-converter/scripts/solution-mapping-schema.json b/plugins/github-copilot-modernization/skills/assessment-report-converter/scripts/solution-mapping-schema.json new file mode 100644 index 0000000..c3c3cd4 --- /dev/null +++ b/plugins/github-copilot-modernization/skills/assessment-report-converter/scripts/solution-mapping-schema.json @@ -0,0 +1,362 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "required": [ + "solutions", + "rules" + ], + "definitions": { + "solutionId": { + "type": "string", + "enum": [ + "scan-and-resolve-cwe-vulnerabilities", + "scan-and-resolve-cve-vulnerabilities", + "activemq-servicebus", + "amqp-rabbitmq-servicebus", + "java-ee-amqp-rabbitmq-servicebus", + "ibm-mq-jms-to-azure-service-bus", + "javax.email-send-to-azure-communication-service-email", + "jax-rpc-to-jax-ws", + "java-version-upgrade", + "deprecated-api-upgrade", + "spring-framework-upgrade", + "spring-boot-upgrade", + "jakarta-ee-upgrade", + "confluent-cloud-kafka", + "kafka-to-eventhubs", + "other-cache-solutions-to-azure-managed-cache", + "log-to-console", + "mi-azure-sql", + "mi-cassandra", + "mi-mariadb", + "mi-mongodb", + "mi-mysql", + "mi-postgresql", + "AWS-secrets-manager-to-azure-key-vault", + "certificate-management-to-azure-key-vault", + "local-files-to-mounted-azure-storage", + "on-premises-user-authentication-to-microsoft-entra-id", + "plaintext-credential-to-azure-keyvault", + "s3-to-azure-blob-storage", + "spring-jms-rabbitmq-servicebus", + "sqs-to-servicebus", + "bare/redesign-java-gui-app", + "bare/apm-to-application-insights", + "bare/encoding-standards", + "bare/local-resource-access", + "bare/remote-communication", + "bare/remote-communication/java-socket", + "bare/remote-communication/corba", + "bare/remote-communication/hardcode-ip", + "bare/remote-communication/secure-protocols", + "bare/remote-communication/hardcoded-urls", + "bare/appserver-api-migration-to-standard-java", + "bare/os-compatibility", + "bare/java-native-code", + "bare/jakataee-to-azure", + "bare/jakataee-to-azure/rmi", + "bare/jakataee-to-azure/jca", + "bare/configuration-management/environment-variables", + "bare/configuration-management/external-configuration", + "bare/configuration-management/windows-registry", + "bare/spring-migration", + "bare/eap-migration/jboss-eap", + "bare/azure-service-connector", + "bare/aws-region-configuration-to-azure", + "bare/spring-cloud-vault-migration", + "bare/aws-credentials-to-azure", + "bare/openliberty-migration/openliberty-database", + "bare/openliberty-migration/openliberty-filesystem", + "bare/openliberty-migration/openliberty-jms", + "bare/openliberty-migration/openliberty-logging", + "bare/database-migration/database-reliability", + "bare/oraclejdk-to-openjdk/resource-management-apis", + "bare/oraclejdk-to-openjdk/imageio", + "bare/jakarta-auth-migration", + "bare/jakarta-websocket-migration", + "bare/jakarta-jaxrs-migration", + "bare/jakarta-nosql-migration", + "bare/jakarta-persistence-migration", + "bare/jakarta-data-migration", + "bare/jboss-eap-to-azure-app-service", + "bare/jboss-eap-to-aks", + "bare/jboss-eap-to-azure-container-apps", + "bare/weblogic-to-azure-app-service", + "bare/weblogic-to-aks", + "bare/weblogic-to-azure-container-apps", + "bare/websphere-to-azure-app-service", + "bare/websphere-to-aks", + "bare/websphere-to-azure-container-apps", + "azure-legacy-java-sdk-upgrade", + "oracle-to-postgresql", + "eclipse-project-to-maven-project", + "ant-project-to-maven-project", + "containerization-copilot-agent", + "google-gcr-to-azure-acr", + "spring-cloud-config-to-azure-app-configuration", + "sybase-ase-to-azure-postgresql", + "sybase-ase-to-azure-sql-database", + "google-firestore-to-azure-cosmos-db", + "google-cloud-bigtable-to-azure-cosmos-db", + "google-cloud-spanner-to-azure-postgresql", + "apache-pulsar-to-azure-event-hubs", + "ibm-db2-to-azure-postgresql", + "firebird-to-azure-postgresql", + "sqlite-to-azure-postgresql", + "google-cloud-functions-to-azure-functions", + "aws-lambda-to-azure-functions", + "quartz-scheduler-to-azure-functions", + "spring-batch-to-azure-durable-functions", + "google-cloud-storage-to-azure-blob-storage", + "amazon-sns-to-azure-service-bus", + "tibco-ems-jms-to-azure-service-bus", + "solace-pubsub-to-azure-service-bus", + "amazon-kinesis-to-azure-event-hubs", + "google-cloud-pub-sub-to-azure-service-bus", + "bare/aws-bedrock-to-azure-ai", + "bare/weak-cryptography", + "bare/insecure-tls", + "bare/hardcoded-credentials", + "bare/insecure-random", + "bare/thirdparty-generic" + ], + "description": "Canonical solution identifier used by this schema for both Formula and Chat solutions. Many IDs map to existing formula/kb folder names for compatibility, but this field should be treated as an opaque stable ID. Add new solution IDs to this enum before referencing them in rules or solution entries." + }, + "solutionEntry": { + "type": "object", + "required": [ + "solutionId", + "name", + "type", + "tooltip" + ], + "properties": { + "solutionId": { + "$ref": "#/definitions/solutionId" + }, + "name": { + "type": "string", + "minLength": 1 + }, + "type": { + "enum": [ + "Formula", + "Chat" + ], + "description": "The type of the solution. Formula: formulas were built for this solution or a prompt is sent to the Agent mode for code migration. Chat: a prompt is sent to the Chat mode for more guidance." + }, + "description": { + "type": [ + "string" + ] + }, + "effort": { + "enum": [ + "LOW", + "MEDIUM", + "HIGH" + ], + "description": "The estimated effort to do the migration." + }, + "prompt": { + "type": [ + "string" + ], + "description": "The prompt that is sent to Copilot Chat or Agent mode for assistance." + }, + "variants": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/definitions/solutionId" + } + }, + "tooltip": { + "type": "string", + "description": "A tooltip is shown in the UI to provide more information about the solution." + }, + "experimental": { + "type": "boolean", + "description": "Whether the solution is experimental and to use the scenario name instead of kbId format when invoking this solution. When true, the solution will be invoked using the scenario name instead of 'by kbId: ' format." + } + }, + "if": { + "properties": { + "type": { + "const": "Chat" + } + }, + "required": [ + "type" + ] + }, + "then": { + "required": [ + "prompt" + ] + }, + "else": { + "not": { + "required": [ + "prompt" + ] + } + }, + "additionalProperties": false + } + }, + "properties": { + "$schema": { + "type": "string", + "description": "URI reference to the schema" + }, + "solutions": { + "type": "array", + "items": { + "$ref": "#/definitions/solutionEntry" + }, + "description": "List of solutions that are available for the rules. The solutionId is used to reference the solution in the rules." + }, + "rules": { + "type": "array", + "description": "List of rules that are used to assess the application.", + "items": { + "type": "object", + "required": [ + "ruleId" + ], + "properties": { + "ruleId": { + "type": "string", + "minLength": 1, + "description": "The rule ID in AppCat. Should be unique across all rules." + }, + "sourceCategory": { + "enum": [ + "activemq", + "activemq-artemis", + "ant", + "apm-dynatrace", + "apm-elastic", + "apm-newrelic", + "aws-credentials", + "aws-region-configuration", + "aws-s3", + "aws-secrets-manager", + "aws-sqs", + "cassandra", + "corba", + "rmi", + "jca", + "environment-variables", + "hardcode-ip", + "secure-protocols", + "hardcoded-urls", + "eclipse", + "external-configuration", + "windows-registry", + "http-session", + "jms-ibm-mq", + "java-mail", + "java-socket", + "javafx", + "javax-swing", + "jboss-eap", + "jni-native-code", + "kafka", + "local-file-system", + "localhost", + "logstash", + "mariadb", + "microsoft-sql", + "mongodb", + "mysql", + "oauth2", + "openid", + "opensaml", + "postgresql", + "quartz-scheduler", + "redis", + "saml", + "webform-auth", + "splunk", + "spring-amqp-rabbitmq", + "java-ee-amqp-rabbitmq", + "spring-cloud", + "spring-boot", + "spring-framework", + "java-ee/jakarta-ee", + "spring-cloud-vault", + "spring-jms-rabbitmq", + "spring-security", + "tanzu-application-service", + "zipkin", + "openliberty-database", + "openliberty-filesystem", + "openliberty-jms", + "openliberty-logging", + "oracle", + "google-pubsub", + "google-gcr", + "sybase-ase", + "google-firestore", + "google-cloud-bigtable", + "google-cloud-spanner", + "apache-pulsar", + "ibm-db2", + "firebird", + "sqlite", + "google-cloud-functions", + "aws-lambda", + "spring-batch", + "google-cloud-storage", + "amazon-sns", + "tibco-ems-jms", + "solace-pubsubplus", + "amazon-kinesis", + "aws-bedrock", + "jakarta-auth", + "jakarta-websocket", + "jakarta-jaxrs", + "jakarta-nosql", + "jakarta-persistence", + "jakarta-data", + "weblogic-to-azure-app-service", + "weblogic-to-aks", + "weblogic-to-azure-container-apps", + "jboss-eap-to-azure-app-service", + "jboss-eap-to-aks", + "jboss-eap-to-azure-container-apps", + "websphere-to-azure-app-service", + "websphere-to-aks", + "websphere-to-azure-container-apps" + ], + "description": "The source category of the rule. This is mainly used to determine the solution when category is not enough." + }, + "solution": { + "oneOf": [ + { + "$ref": "#/definitions/solutionId" + } + ], + "description": "The solution that is used to handle this rule." + }, + "prompt": { + "type": [ + "string" + ], + "description": "The prompt that is sent to Copilot for assistance, before we have a solution." + }, + "notes": { + "type": [ + "string" + ], + "description": "Implementation notes for the rule. Provides future direction for the rule." + } + }, + "additionalProperties": false + } + } + }, + "additionalProperties": false +} diff --git a/plugins/github-copilot-modernization/skills/assessment-report-converter/scripts/solution-mapping.json b/plugins/github-copilot-modernization/skills/assessment-report-converter/scripts/solution-mapping.json new file mode 100644 index 0000000..7e45499 --- /dev/null +++ b/plugins/github-copilot-modernization/skills/assessment-report-converter/scripts/solution-mapping.json @@ -0,0 +1,2393 @@ +{ + "$schema": "./solution-mapping-schema.json", + "solutions": [ + { + "solutionId": "bare/thirdparty-generic", + "name": "Get migration guidance from Copilot", + "type": "Chat", + "prompt": "Analyze this migration issue in the context of the affected code and application architecture. Provide a clear explanation of the underlying problem, the Azure-ready remediation strategy, and any relevant tradeoffs or prerequisites. Then outline a practical, step-by-step implementation plan, including the code, configuration, dependency, and validation changes needed to complete the migration safely.", + "tooltip": "No specific solution matched this issue. Chat with Copilot for tailored migration guidance." + }, + { + "solutionId": "scan-and-resolve-cwe-vulnerabilities", + "name": "Scan and resolve CWE vulnerabilities", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Security vulnerability detected. Ask Copilot to scan and resolve it." + }, + { + "solutionId": "scan-and-resolve-cve-vulnerabilities", + "name": "Resolve CVE issues by upgrading to secure, vulnerability-free versions", + "type": "Formula", + "effort": "MEDIUM", + "tooltip": "Scan and fix CVE vulnerabilities." + }, + { + "solutionId": "activemq-servicebus", + "name": "Migrate from Active Artemis to Azure Service Bus", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from ActiveMQ Artemis to Azure Service Bus for messaging." + }, + { + "solutionId": "java-ee-amqp-rabbitmq-servicebus", + "name": "Migrate from RabbitMQ(AMQP) to Azure Service Bus for Java EE/Jakarta EE", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from RabbitMQ with AMQP to Azure Service Bus for messaging in Java EE/Jakarta EE applications." + }, + { + "solutionId": "amqp-rabbitmq-servicebus", + "name": "Migrate from RabbitMQ(AMQP) to Azure Service Bus", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from RabbitMQ with AMQP to Azure Service Bus for messaging." + }, + { + "solutionId": "ibm-mq-jms-to-azure-service-bus", + "name": "Migrate IBM MQ to Azure Service Bus via JMS", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from IBM JMS to Azure Service Bus for messaging.", + "experimental": true + }, + { + "solutionId": "javax.email-send-to-azure-communication-service-email", + "name": "Migrate to Azure Communication Service", + "type": "Formula", + "effort": "LOW", + "tooltip": "Migrate from Javax Email to Azure Communication Service for sending emails." + }, + { + "solutionId": "jax-rpc-to-jax-ws", + "name": "Migrate from JAX-RPC to JAX-WS", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from JAX-RPC to JAX-WS for web services. JAX-RPC is deprecated and JAX-WS is the recommended alternative." + }, + { + "solutionId": "java-version-upgrade", + "name": "Upgrade Java Version", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Upgrade to the latest stable version of Java for improved security, performance, and compatibility." + }, + { + "solutionId": "deprecated-api-upgrade", + "name": "Upgrade Deprecated APIs", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Upgrade deprecated APIs to their recommended alternatives for improved security, performance, and compatibility." + }, + { + "solutionId": "spring-boot-upgrade", + "name": "Upgrade Spring Boot Version", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Upgrade to the latest stable version of Spring Boot for improved security, performance, and compatibility." + }, + { + "solutionId": "spring-framework-upgrade", + "name": "Upgrade Spring Framework Version", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Upgrade to the latest stable version of Spring Framework for improved security, performance, and compatibility." + }, + { + "solutionId": "jakarta-ee-upgrade", + "name": "Upgrade Jakarta EE Version", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Upgrade to the latest stable version of Jakarta EE for improved security, performance, and compatibility." + }, + { + "solutionId": "confluent-cloud-kafka", + "name": "Migrate from Kafka to Kafka on Confluent Cloud", + "type": "Formula", + "effort": "HIGH", + "variants": [ + "kafka-to-eventhubs" + ], + "tooltip": "Migrate from Kafka to Apache Kafka on Confluent Cloud with managed identity for secure, credential-free authentication." + }, + { + "solutionId": "kafka-to-eventhubs", + "name": "Migrate from Kafka to Azure Event Hubs for Apache Kafka", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from Kafka to Azure Event Hubs for Apache Kafka with managed identity for secure, credential-free authentication." + }, + { + "solutionId": "other-cache-solutions-to-azure-managed-cache", + "name": "Migrate Other Cache Solutions to Azure Managed Redis", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from other cache solutions (like Apache Commons JCS, Ehcache, Hazelcast, Infinispan, or local Redis/session) to Azure Managed Redis." + }, + { + "solutionId": "log-to-console", + "name": "Migrate to Console Logging", + "type": "Formula", + "effort": "MEDIUM", + "tooltip": "Migrate from file-based logging to console logging to support cloud-native apps and integration with Azure Monitor." + }, + { + "solutionId": "mi-azure-sql", + "name": "Secure Azure SQL Database with Managed Identity", + "type": "Formula", + "effort": "MEDIUM", + "tooltip": "Secure Azure SQL Database with Managed Identity." + }, + { + "solutionId": "mi-cassandra", + "name": "Secure Azure Cosmos DB for Cassandra with Service Connector", + "type": "Formula", + "effort": "LOW", + "tooltip": "Secure Azure Cosmos DB for Cassandra with Service Connector for a fully managed, scalable database with Cassandra API support." + }, + { + "solutionId": "mi-mariadb", + "name": "Migrate to Azure Database for MariaDB (Spring)", + "type": "Formula", + "effort": "MEDIUM", + "tooltip": "Migrate from MariaDB to Azure Database for MariaDB with managed identity for secure, credential-free authentication." + }, + { + "solutionId": "mi-mongodb", + "name": "Secure Azure DocumentDB (with MongoDB Compatibility) with Microsoft Entra ID Authentication", + "type": "Formula", + "effort": "LOW", + "tooltip": "Secure Azure DocumentDB (with MongoDB Compatibility) with Microsoft Entra ID authentication." + }, + { + "solutionId": "mi-mysql", + "name": "Migrate to Azure Database for MySQL", + "type": "Formula", + "effort": "MEDIUM", + "tooltip": "Migrate from MySQL to Azure Database for MySQL with managed identity for secure, credential-free authentication." + }, + { + "solutionId": "mi-postgresql", + "name": "Secure Azure Database for PostgreSQL with Managed Identity", + "type": "Formula", + "effort": "MEDIUM", + "tooltip": "Secure Azure Database for PostgreSQL with Managed Identity." + }, + { + "solutionId": "AWS-secrets-manager-to-azure-key-vault", + "name": "Migrate from AWS Secrets Manager to Azure Key Vault", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from AWS Secrets Manager to Azure Key Vault to securely manage and access sensitive information in Azure." + }, + { + "solutionId": "certificate-management-to-azure-key-vault", + "name": "Migrate from KeyStore to Azure Key Vault", + "type": "Formula", + "effort": "LOW", + "tooltip": "Migrate from a local KeyStore to Azure Key Vault for secure storage and access to certificates and keys." + }, + { + "solutionId": "local-files-to-mounted-azure-storage", + "name": "Migrate to Azure Storage Account File Share mounts", + "type": "Formula", + "effort": "LOW", + "tooltip": "Migrate from local file system to Azure Storage Account File Share mounts for scalable and secure file storage." + }, + { + "solutionId": "on-premises-user-authentication-to-microsoft-entra-id", + "name": "Migrate from on-premises user authentication to Microsoft Entra ID", + "description": "TODO: need to further check if this aligns with the solution", + "type": "Formula", + "effort": "MEDIUM", + "tooltip": "Migrate from on-premises user authentication systems to Microsoft Entra ID for secure and scalable user management in Azure." + }, + { + "solutionId": "plaintext-credential-to-azure-keyvault", + "name": "Migrate from Plaintext Credentials to Azure Key Vault", + "type": "Formula", + "effort": "LOW", + "tooltip": "Migrate from plaintext credentials in the code to Azure Key Vault for storage and access to sensitive information." + }, + { + "solutionId": "s3-to-azure-blob-storage", + "name": "Migrate from AWS S3 to Azure Blob Storage", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from AWS S3 to Azure Blob Storage for scalable and secure object storage in Azure." + }, + { + "solutionId": "spring-jms-rabbitmq-servicebus", + "name": "Migrate from RabbitMQ(JMS) to Azure Service Bus", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from RabbitMQ with JMS to Azure Service Bus for a managed messaging service with JMS API support." + }, + { + "solutionId": "sqs-to-servicebus", + "name": "Migrate from AWS Simple Queue Service to Azure Service Bus", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from AWS Simple Queue Service to Azure Service Bus for a managed messaging service with advanced features." + }, + { + "solutionId": "oracle-to-postgresql", + "name": "Migrate from Oracle DB to PostgreSQL", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from Oracle DB to PostgreSQL" + }, + { + "solutionId": "bare/redesign-java-gui-app", + "name": "Redesign Java GUI application to migrate it to Azure", + "type": "Chat", + "prompt": "The application uses desktop GUI framework which requires desktop runtime and is not cloud-native, consider containerizing for Azure deployment or redesigning as a web application.", + "tooltip": "Redesign the Java app's graphical user interface (GUI) using Java Swing or JavaFX to migrate it to Azure." + }, + { + "solutionId": "bare/apm-to-application-insights", + "name": "Migrate APM to application insights", + "type": "Chat", + "prompt": "The app uses an application performance monitoring (APM) platform. To migrating Java app to Azure, use Azure Monitor or Application Insights for built-in tracing and auto-instrumentation support in Azure services.", + "tooltip": "The app uses an application performance monitoring (APM) platform. Chat with Copilot to learn how to migrate APM to Azure Monitor or Application Insights." + }, + { + "solutionId": "bare/encoding-standards", + "name": "Check Encoding in the Code", + "type": "Chat", + "prompt": "The code uses UTF-8 by default. If it's not appropriate for your code, use a different character set.", + "tooltip": "The code uses UTF-8 by default. Chat with Copilot to learn how to check and update the encoding." + }, + { + "solutionId": "bare/local-resource-access", + "name": "Migrate the Local Resource to Azure", + "type": "Chat", + "prompt": "The application is using some resource or service from localhost. When you migrate the application to Azure, you also need to migrate the dependent resource or service to Azure.", + "tooltip": "The app uses some resource or service from localhost. Chat with Copilot to learn how to migrate the local resource to Azure." + }, + { + "solutionId": "bare/remote-communication", + "name": "Use Loosely coupled protocols in Cloud Environment", + "type": "Chat", + "prompt": "The app uses legacy protocols. Please use loosely coupled protocols like REST, gRPC, etc.", + "tooltip": "The app uses legacy protocols. Chat with Copilot to learn how to use loosely coupled protocols like REST, gRPC, etc." + }, + { + "solutionId": "bare/remote-communication/java-socket", + "name": "Use Java Socket Communication in Cloud Environment", + "type": "Chat", + "prompt": "The application uses Java socket communication, which depends on fixed IP addresses and ports, making it unsuitable for cloud environments where service endpoints are dynamic and scaling is required. Replace socket-based communication with cloud-friendly, loosely coupled alternatives such as RESTful APIs, gRPC, JMS messaging, Azure Service Bus, etc.", + "tooltip": "The app uses legacy protocols. Chat with Copilot to learn how to use loosely coupled protocols like REST, gRPC, etc." + }, + { + "solutionId": "bare/remote-communication/corba", + "name": "Check CORBA usage", + "type": "Chat", + "prompt": "The application uses CORBA which is tightly coupled and not suitable for cloud environments. Replace with REST APIs, gRPC, or Azure Service Bus for messaging. Use Azure API Management for API gateway capabilities.", + "tooltip": "The app uses CORBA for remote communication. Chat with Copilot to learn how to review and update it when migrating to Azure." + }, + { + "solutionId": "bare/remote-communication/hardcode-ip", + "name": "Check hardcoded IP address", + "type": "Chat", + "prompt": "The application uses hardcoded IP addresses. When migrating to Azure cloud, review and update any hardcoded IP addresses as needed, or migrate the dependent services accordingly.", + "tooltip": "The app uses hardcoded IP addresses. Chat with Copilot to learn how to review and update them when migrating to Azure." + }, + { + "solutionId": "bare/remote-communication/secure-protocols", + "name": "Use Secure Protocols", + "type": "Chat", + "prompt": "The application uses insecure protocols. When migrating to Azure cloud, review and update any insecure protocols to secure protocols such as HTTPS and SFTP (over HTTP and FTP).", + "tooltip": "The app uses insecure protocols. Chat with Copilot to learn how to switch to secure ones like HTTPS or SFTP." + }, + { + "solutionId": "bare/remote-communication/hardcoded-urls", + "name": "Check hardcoded URLs", + "type": "Chat", + "prompt": "The application uses hardcoded URLs. When migrating to Azure cloud, review and update any hardcoded URLs as needed, or migrate the dependent services accordingly.", + "tooltip": "The app uses hardcoded URLs. Chat with Copilot to learn how to review and update them when migrating to Azure." + }, + { + "solutionId": "bare/os-compatibility", + "name": "Redesign OS Specific Code", + "type": "Chat", + "prompt": "The app uses a Windows Dynamic-Link Library (DLL). Redesign the code to avoid using OS specific code.", + "tooltip": "The app uses a Windows Dynamic-Link Library (DLL). Chat with Copilot to learn how to redesign the code to avoid using OS specific code." + }, + { + "solutionId": "bare/java-native-code", + "name": "Build Native Process into Container Image", + "type": "Chat", + "prompt": "The application uses Java native libraries (JNI, JNA) which may not be compatible with cloud container environments. Identify these dependencies and either containerize them with matching base images or replace them with platform-independent libraries, cloud-native solutions, or Azure managed services.", + "tooltip": "The app uses Java native libraries (JNI, JNA). Chat with Copilot to learn how to build them into containers or find Azure alternatives." + }, + { + "solutionId": "bare/jakataee-to-azure", + "name": "Deploy JakartaEE App to Azure", + "type": "Chat", + "prompt": "The Application relies on Jakarta EE APIs. Azure provides support for Jakarta EE applications from different vendors, including Red Hat OpenShift, IBM WebSphere Liberty, and Oracle WebLogic Server.", + "tooltip": "The app uses Jakarta EE APIs. Chat with Copilot to learn how to deploy them to Azure using supported vendors." + }, + { + "solutionId": "bare/jakataee-to-azure/rmi", + "name": "Check Java Remote Method Invocation(RMI)", + "type": "Chat", + "prompt": "The application uses Java RMI which is tightly coupled and not cloud-ready, replace it with HTTP-based RESTful APIs for standard communication or Azure Service Bus for messaging scenarios.", + "tooltip": "The app uses Java RMI. Chat with Copilot to learn how to replace it with cloud-ready alternatives." + }, + { + "solutionId": "bare/jakataee-to-azure/jca", + "name": "Check Java Connector Architecture(JCA)", + "type": "Chat", + "prompt": "The application uses Java Connector Architecture(JCA) which is tightly coupled and not suitable for cloud scalability, replace with appropriate Azure managed services like Azure Service Bus, Azure Event Hub, etc.", + "tooltip": "The app uses Java Connector Architecture(JCA). Chat with Copilot to learn how to replace it with cloud-ready alternatives." + }, + { + "solutionId": "bare/configuration-management/environment-variables", + "name": "Configure System Environment Variables", + "type": "Chat", + "prompt": "The application uses environment variables or system properties. When migrating to Azure, they need to be passed according to the target hosting service's setup. If they contain sensitive information, it's better to store in KeyVault. If some configurations are shared, Azure App Configuration service may be an option to store them.", + "tooltip": "The app uses environment variables or system properties. Chat with Copilot to learn how to configure system environment variables when migrating to Azure." + }, + { + "solutionId": "bare/configuration-management/external-configuration", + "name": "Manage External Configuration", + "type": "Chat", + "prompt": "The app stores settings in external files other than web.config. When migrating to Azure, they need to be passed according to the target hosting services's setup. If they contain sensitive information, it's better to store in KeyVault. If some configurations are shared, Azure App Configuration service may be an option to store them.", + "tooltip": "The app stores settings in external files. Chat with Copilot to learn how to manage external configuration when migrating to Azure." + }, + { + "solutionId": "bare/configuration-management/windows-registry", + "name": "Manage Windows Registry Configuration", + "type": "Chat", + "prompt": "The application writes application settings into OS-specific storage such as Windows Registry. When migrating to Azure, these application settings should not be defined in such storage. If they contain sensitive information, it's better to store in KeyVault. If some configurations are shared, Azure App Configuration service may be an option to store them.", + "tooltip": "The app stores settings in OS-specific storage like the Windows Registry. Chat with Copilot to learn managing Windows Registry configuration when migrating to Azure." + }, + { + "solutionId": "quartz-scheduler-to-azure-functions", + "name": "Migrate from Quartz Scheduler to Azure Functions", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from Quartz Scheduler to Azure Functions for serverless, event-driven task scheduling in Azure.", + "experimental": true + }, + { + "solutionId": "bare/spring-migration", + "name": "Deploy Spring Cloud App To Azure", + "type": "Chat", + "prompt": "The application has Spring Boot or Spring Cloud dependencies. Azure Container Apps offers managed components for Spring Cloud, so it may be an option for Spring Cloud migration. Special attention is required for some environment related settings, such as server.port, Config Server or Eureka bindings.", + "tooltip": "The app uses Spring Boot or Spring Cloud. Chat with Copilot to learn how to deploy Spring Cloud apps to Azure using Azure Container Apps." + }, + { + "solutionId": "bare/eap-migration/jboss-eap", + "name": "Deploy JBoss EAP to Azure", + "type": "Chat", + "prompt": "The app uses JBoss EAP related code, configs, dependencies, and/or environment settings. JBoss EAP is a Java EE application server available on Azure.", + "tooltip": "The app uses JBoss EAP related code, configs, dependencies, and/or environment settings. Chat with Copilot to learn how to deploy JBoss EAP apps to Azure using supported vendors." + }, + { + "solutionId": "bare/azure-service-connector", + "name": "Use Azure Service Connector", + "type": "Chat", + "prompt": "The app uses VMware Tanzu Application Service (TAS) service bindings. In Azure, use Azure Service Connect to link to Azure services.", + "tooltip": "The app uses VMware Tanzu Application Service (TAS) service bindings. Chat with Copilot to learn how to use Azure Service Connector to connect to Azure services." + }, + { + "solutionId": "bare/aws-region-configuration-to-azure", + "name": "Migrate from AWS Region Configuration to Azure Region Configuration", + "type": "Chat", + "prompt": "The app has AWS region settings. Identify the AWS service to migrate, find Azure alternatives, and check their region availability. Provide the links to Azure docs page for latest region availability.", + "tooltip": "The app has AWS region settings. Chat with Copilot to learn how to migrate from AWS region configuration to Azure region configuration." + }, + { + "solutionId": "bare/spring-cloud-vault-migration", + "name": "Migrate from Spring Cloud Vault to Azure Key Vault", + "type": "Chat", + "prompt": "The application integrates with Spring Cloud Vault. To migrate a Java application that uses Spring Cloud Vault to Azure, you should identify all secrets and the backing secret store, then migrate them to Azure Key Vault. Use the Azure Key Vault Spring Boot Starter for secret injection. You may need to rename some secrets and update references in the application code.", + "tooltip": "The app integrates with Spring Cloud Vault. Chat with Copilot to learn how to migrate from Spring Cloud Vault to Azure Key Vault." + }, + { + "solutionId": "bare/aws-credentials-to-azure", + "name": "Migrate from AWS Access Key ID/Secret to Azure Credentials", + "type": "Chat", + "prompt": "The application contains AWS credential configuration. We need to find out what AWS service we want to migrate, find the candidate alternatives on Azure, do the code changes according to the source service and target service. Secrets should be stored in Azure Key Vault. The best practice is to use DefaultAzureCredential to authenticate to Azure and access the target service.", + "tooltip": "The app has AWS credential configuration. Chat with Copilot to learn how to migrate from AWS access key ID/secret to Azure credentials." + }, + { + "solutionId": "bare/openliberty-migration/openliberty-database", + "name": "Migrate from Open Liberty Database to Azure Database Services", + "type": "Chat", + "prompt": "The application uses Open Liberty database configurations and datasources. When migrating to Azure, identify the specific database type (MySQL, PostgreSQL, SQL Server) and migrate to the appropriate Azure Database service. Use connection pooling optimized for cloud environments and configure Azure Key Vault to securely store connection strings. Implement DefaultAzureCredential for managed identity authentication to eliminate hard-coded credentials. Consider using Azure App Configuration for centralized connection management across environments.", + "tooltip": "The app uses Open Liberty database configurations and datasources. Chat with Copilot to learn how to migrate from Open Liberty database to Azure Database Services." + }, + { + "solutionId": "bare/openliberty-migration/openliberty-filesystem", + "name": "Migrate from Open Liberty Filesystem to Azure Storage", + "type": "Chat", + "prompt": "The application uses Open Liberty filesystem for data storage or configuration. When migrating to Azure, replace local filesystem dependencies with Azure Blob Storage or Azure Files depending on access patterns. For read-heavy shared configuration, consider Azure Blob Storage with CDN. For applications requiring file system mounting, use Azure Files with SMB protocol. Implement the Azure Storage SDK with DefaultAzureCredential for secure access, and store any access keys in Azure Key Vault. Consider data access patterns when selecting storage tier and replication options.", + "tooltip": "The app uses Open Liberty filesystem for data storage or configuration. Chat with Copilot to learn how to migrate from Open Liberty filesystem to Azure Storage." + }, + { + "solutionId": "bare/openliberty-migration/openliberty-jms", + "name": "Migrate from Open Liberty JMS to Azure Service Bus", + "type": "Chat", + "prompt": "The application uses Open Liberty Java Message Service (JMS) for messaging. When migrating to Azure, Azure Service Bus is the recommended alternative. Analyze current JMS usage patterns (queues, topics, message selectors) to map to Service Bus concepts. Use the JMS over AMQP provider with the Azure Service Bus SDK for Java. Implement DefaultAzureCredential for authentication, store connection strings in Azure Key Vault, and adjust client-side configurations for cloud reliability patterns like retry policies and circuit breakers.", + "tooltip": "The app uses Open Liberty Java Message Service (JMS) for messaging. Chat with Copilot to learn how to migrate from Open Liberty JMS to Azure Service Bus." + }, + { + "solutionId": "bare/openliberty-migration/openliberty-logging", + "name": "Migrate from Open Liberty Logging to Azure Monitor", + "type": "Chat", + "prompt": "The application uses Open Liberty logging configurations. When migrating to Azure, implement a cloud-native logging strategy using Azure Monitor and Application Insights. Configure the Application Insights Java agent for auto-instrumentation or use the Application Insights SDK for more customization. For structured logging, consider Log Analytics workspace integration. Update logging configurations to use console output (stdout/stderr) instead of files when deployed to Azure App Service or Azure Container Apps. Implement correlation IDs across services for distributed tracing and use Azure Monitor Workbooks for custom dashboards.", + "tooltip": "The app uses Open Liberty logging configurations. Chat with Copilot to learn how to migrate from Open Liberty logging to Azure Monitor." + }, + { + "solutionId": "bare/oraclejdk-to-openjdk/resource-management-apis", + "name": "Update Resource Management APIs for migration from Oracle JDK to OpenJDK", + "type": "Chat", + "prompt": "The application uses Resource Management APIs. When migrating to OpenJDK, OpenJDK does not support the resource management API for Java, review and update the resource management API usage to ensure compatibility with OpenJDK. Specifically, identify and replace the use of classes and methods from the `jdk.management.resource` package with alternative approaches for resource monitoring and management.", + "tooltip": "The app uses Resource Management APIs. Chat with Copilot to learn how to update Resource Management APIs for migration from Oracle JDK to OpenJDK." + }, + { + "solutionId": "bare/oraclejdk-to-openjdk/imageio", + "name": "Replace ImageIO usage for migration from Oracle JDK to OpenJDK", + "type": "Chat", + "prompt": "The application uses Oracle JDK JPEG image encoder/decoder usage. When migrating to OpenJDK, review and update the image encoder/decoder usage to ensure compatibility with OpenJDK. Specifically, identify and replace the use of classes and methods from the `com.sun.image.codec.jpeg` package with `javax.imageio.ImageIO`.", + "tooltip": "The application uses Oracle JDK JPEG image encoder/decoder usage. Chat with Copilot to learn how to replace ImageIO usage for migration from Oracle JDK to OpenJDK." + }, + { + "solutionId": "bare/database-migration/database-reliability", + "name": "Update database configurations for cloud readiness and resilience", + "type": "Chat", + "prompt": "The application uses database. When migrating to Azure, review and update the database configurations to ensure readiness for Azure cloud deployment. Specifically, identify any on-premise specific settings that are incompatible or suboptimal for Azure; recommend updates to support high availability, automatic failover, and geo-redundancy; ensure connection strings support retry policies, transient fault handling, and use managed identity authentication if possible; detect hardcoded paths, IPs, or dependencies that may need reconfiguration.", + "tooltip": "The app uses database. Chat with Copilot to learn how to update database configurations for cloud readiness and resilience." + }, + { + "solutionId": "bare/jakarta-auth-migration", + "name": "Migrate Jakarta EE Authentication to Microsoft Entra ID", + "type": "Chat", + "prompt": "The application uses Jakarta Authentication and Authorization APIs. When migrating to Azure, how should I modernize the authentication to integrate with Microsoft Entra ID? Please provide: 1. Code examples for replacing Jakarta Authentication with OAuth 2.0/OIDC. 2. Microsoft Entra ID configuration steps (App Registration, permissions) 3. Best practices for container-based authentication on Azure. 4. Authorization strategy (RBAC vs application claims). Include configuration samples and highlight key migration considerations.", + "tooltip": "The app uses Jakarta Authentication and Authorization APIs. Chat with Copilot to learn how to migrate Jakarta EE Authentication to Microsoft Entra ID." + }, + { + "solutionId": "bare/jakarta-websocket-migration", + "name": "Migrate Jakarta EE WebSocket", + "type": "Chat", + "prompt": "The application uses Jakarta WebSocket APIs. When migrating to Azure, please advise on: 1. Best Azure service for hosting WebSocket applications (self-hosted vs Azure Web PubSub)? 2. Code examples for migrating @ServerEndpoint to Azure-compatible patterns. 3. Required Azure configurations: session affinity, TLS, connection timeouts. 4. How to integrate Microsoft Entra ID authentication for WebSocket connections? 5. Load balancing and scalability considerations for real-time connections. Include code samples, configuration examples, and migration trade-offs.", + "tooltip": "The app uses Jakarta WebSocket APIs. Chat with Copilot to learn how to migrate Jakarta EE WebSocket." + }, + { + "solutionId": "bare/jakarta-jaxrs-migration", + "name": "Migrate Jakarta JAX-RS to Azure", + "type": "Chat", + "prompt": "My Java application uses Jakarta JAX-RS APIs (jakarta.ws.rs.* or javax.ws.rs.*) on a Jakarta EE/MicroProfile runtime. I need to migrate to Azure. Please advise on: 1. Deployment options - Azure App Service, AKS, or Container Apps for JAX-RS applications? 2. Configuration externalization - migrating to Azure App Configuration and Key Vault with code examples. 3. API security - securing JAX-RS endpoints with Microsoft Entra ID, OAuth 2.0/OIDC filters, and JWT validation in JAX-RS filters and interceptors. 4. Observability - integrating Azure Application Insights for telemetry and distributed tracing. 5. Production readiness - HTTPS configuration, Managed Identity, auto-scaling, and health checks. Include code examples, Azure configuration samples, and migration checklist.", + "tooltip": "The application uses Jakarta JAX-RS APIs for RESTful services. Chat with Copilot to learn how to migrate to Azure App Service, AKS, or Container Apps with proper security and monitoring." + }, + { + "solutionId": "bare/jakarta-nosql-migration", + "name": "Migrate Jakarta NoSQL to Azure", + "type": "Chat", + "prompt": "My application uses Jakarta NoSQL APIs (jakarta.nosql.*). I need to migrate to Azure. Please advise on: 1. Should I migrate to Azure Cosmos DB native SDKs? Which Cosmos DB API (NoSQL, MongoDB, Cassandra, Gremlin, Table) matches my data model? 2. How to update data access layer from Jakarta NoSQL to Cosmos DB SDK with code examples? 3. Configuration - connection strings, authentication (Managed Identity), and security. 4. Network security - VNet integration, private endpoints, and firewall rules. 5. Performance - throughput settings, consistency levels, and optimization. Include before/after code examples and Azure configuration.", + "tooltip": "The application uses Jakarta NoSQL APIs. Chat with Copilot to learn how to migrate to Azure Cosmos DB." + }, + { + "solutionId": "bare/jakarta-persistence-migration", + "name": "Migrate Jakarta JPA to Azure", + "type": "Chat", + "prompt": "My application uses Jakarta JPA APIs (jakarta.persistence.* or javax.persistence.*) with Hibernate/EclipseLink. I need to migrate to Azure. Please advise on: 1. Which Azure database - PostgreSQL, MySQL, or SQL Database? 2. Updating persistence.xml/properties for Azure connections, dialect, and connection pools. 3. Storing credentials in Azure Key Vault with Managed Identity examples. 4. Network security - VNet integration, private endpoints, and firewall rules. 5. Deployment on Azure App Service, AKS, or Container Apps. Include configuration examples and Spring Data JPA guidance.", + "tooltip": "The application uses Jakarta JPA APIs. Chat with Copilot to learn how to migrate to Azure database services." + }, + { + "solutionId": "bare/jakarta-data-migration", + "name": "Migrate Jakarta Data to Azure", + "type": "Chat", + "prompt": "My application uses Jakarta Data APIs (jakarta.data.*) for repository-based data access. I need to migrate to Azure. Please advise on: 1. For relational workloads: Azure PostgreSQL/MySQL/SQL Database; for NoSQL: Azure Cosmos DB - which fits my use case? 2. Ensuring Jakarta Data providers (Eclipse JNoSQL, Micronaut Data) work with Azure. 3. Updating repository configuration for Azure with connection URLs and credentials. 4. Network security - VNet integration, private endpoints, and firewall rules. 5. Using Azure Key Vault for credential management. 6. Deployment on Azure App Service, AKS, or Container Apps. Include configuration examples.", + "tooltip": "The application uses Jakarta Data APIs. Chat with Copilot to learn how to migrate to Azure databases." + }, + { + "solutionId": "bare/jboss-eap-to-azure-app-service", + "name": "Migrate JBoss EAP to Azure App Service", + "type": "Chat", + "prompt": "My application uses JBoss EAP and I need to migrate to Azure App Service. Please advise on: 1. Preparing JBoss EAP application for Azure App Service deployment. 2. Configuring JBoss EAP runtime (version, startup settings) and updating build files. 3. Managing configuration with Azure App Configuration and Key Vault. 4. Deployment options - Maven/Gradle plugins or CI/CD. 5. Setting up monitoring with Application Insights. Include configuration examples.", + "tooltip": "The application uses JBoss EAP. Chat with Copilot to learn how to migrate to JBoss EAP on Azure App Service." + }, + { + "solutionId": "bare/jboss-eap-to-aks", + "name": "Migrate JBoss EAP to Azure Kubernetes Service", + "type": "Chat", + "prompt": "My application uses JBoss EAP and I need to migrate to AKS. Please advise on two options: Option 1 - Lift-and-Shift: Using Red Hat JBoss EAP container images, Dockerfile examples, and Kubernetes manifests (Deployment, Service, ConfigMap). Option 2 - Refactor: Migrating to Spring Boot/Quarkus/Micronaut with code refactoring patterns. For both: include networking, scaling, Azure Key Vault integration, and monitoring. Help me choose the right approach with code examples.", + "tooltip": "The application uses JBoss EAP. Chat with Copilot to learn migration to AKS: lift-and-shift or refactor to cloud-native." + }, + { + "solutionId": "bare/jboss-eap-to-azure-container-apps", + "name": "Migrate JBoss EAP to Azure Container Apps", + "type": "Chat", + "prompt": "My application uses JBoss EAP and I need to migrate to Azure Container Apps. Please advise on two options: Option 1 - Lift-and-Shift: Using Red Hat JBoss EAP container images and Dockerfile examples. Option 2 - Refactor: Migrating to Spring Boot/Quarkus/Micronaut with refactoring patterns. For both: include Container Apps configuration (scaling, traffic splitting), Azure Key Vault, ingress, and Application Insights. Help me choose with code examples.", + "tooltip": "The application uses JBoss EAP. Chat with Copilot to learn migration to Container Apps: lift-and-shift or refactor." + }, + { + "solutionId": "bare/weblogic-to-azure-app-service", + "name": "Migrate WebLogic to JBoss EAP on Azure App Service", + "type": "Chat", + "prompt": "My application uses WebLogic Server and I need to migrate to JBoss EAP on Azure App Service. Please advise on: 1. Key differences between WebLogic and JBoss EAP. 2. Migrating weblogic.xml and descriptors to JBoss equivalents. 3. Updating build files to replace WebLogic dependencies. 4. Configuring JBoss EAP runtime on App Service. 5. Data sources, JNDI, and JMS setup. Include configuration examples and checklist.", + "tooltip": "The application uses WebLogic Server. Chat with Copilot to learn how to migrate to JBoss EAP on Azure App Service." + }, + { + "solutionId": "bare/weblogic-to-aks", + "name": "Migrate WebLogic to Azure Kubernetes Service", + "type": "Chat", + "prompt": "My application uses WebLogic Server and I need to migrate to AKS. Please advise on: 1. Migration approach - WebLogic on AKS or refactor to cloud-native? 2. Using Oracle WebLogic Kubernetes Operator. 3. Containerizing WebLogic with Dockerfile examples. 4. Kubernetes manifests for WebLogic domains and clusters. 5. Networking, secrets with Azure Key Vault, and monitoring. Include code examples and architecture guidance.", + "tooltip": "The application uses WebLogic Server. Chat with Copilot to learn how to migrate to Azure Kubernetes Service." + }, + { + "solutionId": "bare/weblogic-to-azure-container-apps", + "name": "Migrate WebLogic to Azure Container Apps", + "type": "Chat", + "prompt": "My application uses WebLogic Server and I need to migrate to Azure Container Apps. Please advise on two options: Option 1 - Lift-and-Shift: WebLogic container images and Dockerfile examples. Option 2 - Refactor: Migrating to Spring Boot/Quarkus/Micronaut. For both: include Container Apps configuration, Azure Key Vault, autoscaling, and monitoring. Help me choose with code examples.", + "tooltip": "The application uses WebLogic Server. Chat with Copilot to learn migration to Container Apps: lift-and-shift or refactor." + }, + { + "solutionId": "bare/websphere-to-azure-app-service", + "name": "Migrate WebSphere to JBoss EAP on Azure App Service", + "type": "Chat", + "prompt": "My application uses WebSphere and I need to migrate to JBoss EAP on Azure App Service. Please advise on: 1. Key differences between WebSphere and JBoss EAP. 2. Migrating WebSphere descriptors (ibm-web-ext.xml, ibm-application-bnd.xml) to JBoss equivalents. 3. Replacing WebSphere dependencies (com.ibm.websphere.*) in build files. 4. Configuring JBoss EAP runtime on App Service. 5. Data sources, JNDI, and messaging setup. Include configuration examples and checklist.", + "tooltip": "The application uses WebSphere. Chat with Copilot to learn how to migrate to JBoss EAP on Azure App Service." + }, + { + "solutionId": "bare/websphere-to-aks", + "name": "Migrate WebSphere to Azure Kubernetes Service", + "type": "Chat", + "prompt": "My application uses WebSphere and I need to migrate to AKS. Please advise on: 1. Migration approach - WebSphere Liberty on AKS or refactor to cloud-native? 2. Using IBM WebSphere Liberty Operator for Kubernetes. 3. Containerizing WebSphere applications with Dockerfile examples. 4. Kubernetes manifests for WebSphere Liberty deployment. 5. Networking, secrets with Azure Key Vault, and monitoring. Include code examples and architecture guidance.", + "tooltip": "The application uses WebSphere. Chat with Copilot to learn how to migrate to Azure Kubernetes Service." + }, + { + "solutionId": "bare/websphere-to-azure-container-apps", + "name": "Migrate WebSphere to Azure Container Apps", + "type": "Chat", + "prompt": "My application uses WebSphere and I need to migrate to Azure Container Apps. Please advise on two options: Option 1 - Lift-and-Shift: IBM WebSphere Liberty container images and Dockerfile examples. Option 2 - Refactor: Migrating to Spring Boot/Quarkus/Micronaut. For both: include Container Apps configuration, Azure Key Vault, autoscaling, and monitoring. Help me choose with code examples.", + "tooltip": "The application uses WebSphere. Chat with Copilot to learn migration to Container Apps: lift-and-shift or refactor." + }, + { + "solutionId": "bare/appserver-api-migration-to-standard-java", + "name": "Migrate Proprietary App Server APIs to Standard Java/Jakarta EE", + "type": "Chat", + "prompt": "The application uses proprietary application server APIs (WebLogic, WebSphere, JBoss EAP, or JBoss Seam) that must be migrated to standard Java/Jakarta EE equivalents. This is an application server portability migration — not a simple JDK deprecated API fix — and typically involves significant code changes across imports, annotations, deployment descriptors, and build dependencies.\n\nPlease analyze the detected issues and provide file-level migration guidance based on these patterns:\n\n1. **CommonJ Timer/Work Manager (WebLogic or WebSphere)**: Replace `commonj.timers.*` with `java.util.concurrent.ScheduledExecutorService`; replace `commonj.work.*` with `java.util.concurrent.ExecutorService` or Jakarta Concurrency `ManagedExecutorService` (`jakarta.enterprise.concurrent`).\n\n2. **Vendor-specific JMS (WebLogic/WebSphere JMS)**: Replace `weblogic.jms.*` or `com.ibm.websphere.jms.*` with standard Jakarta JMS (`jakarta.jms.*`). Update connection factory lookups to use standard JNDI; remove vendor-specific extensions for destinations, connection pooling, and message handling.\n\n3. **WebLogic Servlet/Lifecycle**: Replace `weblogic.application.ApplicationLifecycleListener` with standard `jakarta.servlet.ServletContextListener` or `@WebListener`. Replace WebLogic-specific servlet classes with standard Servlet API equivalents.\n\n4. **WebLogic WebServices**: Migrate from `weblogic.wsee.*` proprietary annotations and descriptors to standard JAX-WS (`jakarta.xml.ws.*`) or JAX-RS (`jakarta.ws.rs.*`). Remove WebLogic-specific web service deployment descriptors.\n\n5. **WebLogic Webapp Descriptors**: Replace `weblogic.xml` and vendor-specific deployment descriptors with standard `web.xml` or annotation-based configuration.\n\n6. **JBoss EAP Cross-Version Migration**: Replace deprecated JBoss-internal classes (logging, transactions, classloading) with standard Java/Jakarta EE equivalents or updated JBoss APIs.\n\n7. **JBoss Seam → CDI**: Replace Seam annotations (`@Name`, `@In`, `@Out`, `@Factory`) with CDI equivalents (`@Named`, `@Inject`, `@Produces`). Refactor Seam interceptors, page flows, and bijection to CDI interceptors, decorators, and standard scopes.\n\n8. **CDI Deprecated API**: Update deprecated CDI methods (e.g., `Bean#isNullable()`, `BeanManager.fireEvent()`) to current Jakarta CDI replacements.\n\n9. **JBoss Deprecated Dependencies**: Replace deprecated JBoss-specific dependencies with their standard Java/Jakarta EE or community-maintained equivalents.\n\nGeneral approach: (a) Scan for vendor-specific package imports to build an inventory. (b) Map each proprietary class to its standard equivalent. (c) Refactor incrementally per module — update imports, class references, method signatures and descriptors. (d) Remove vendor SDK dependencies from pom.xml/build.gradle and add standard Jakarta EE API dependencies. (e) Validate with integration tests, especially messaging, lifecycle hooks, and web service endpoints.", + "tooltip": "The app uses proprietary app server APIs (WebLogic, WebSphere, JBoss). Chat with Copilot to learn how to migrate to standard Java/Jakarta EE equivalents." + }, + { + "solutionId": "eclipse-project-to-maven-project", + "name": "Migrate from Eclipse Project to Maven Project", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate current project from eclipse project to maven project" + }, + { + "solutionId": "ant-project-to-maven-project", + "name": "Migrate from Ant Project to Maven Project", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate current project from Ant project to Maven project" + }, + { + "solutionId": "containerization-copilot-agent", + "name": "Containerize Java Application for Container Readiness", + "type": "Formula", + "effort": "HIGH", + "tooltip": "The app does not have a Dockerfile and/or is not container-ready. Use Agent Mode with Copilot to create and execute a containerization plan." + }, + { + "solutionId": "google-cloud-pub-sub-to-azure-service-bus", + "name": "Migrate from Google Pub/Sub to Azure Service Bus", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from Google Pub/Sub to Azure Service Bus for reliable and secure messaging in Azure.", + "experimental": true + }, + { + "solutionId": "google-gcr-to-azure-acr", + "name": "Migrate from Google GCR to Azure ACR", + "type": "Chat", + "prompt": "The application uses Google Container Registry (GCR) for container image storage. To migrate to Azure, use Azure Container Registry (ACR) as the alternative container registry service. Set up an ACR instance, configure authentication using Azure Active Directory and DefaultAzureCredential, and update deployment pipelines to push/pull images from ACR. Consider using Azure Container Apps or Azure Kubernetes Service (AKS) for hosting containerized applications.", + "tooltip": "Migrate from Google GCR to Azure ACR for reliable and secure container registry in Azure." + }, + { + "solutionId": "spring-cloud-config-to-azure-app-configuration", + "name": "Migrate from Spring Cloud Config to Azure App Configuration", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from Spring Cloud Config to Azure App Configuration for scalable and secure configuration management in Azure.", + "experimental": true + }, + { + "solutionId": "sybase-ase-to-azure-postgresql", + "name": "Migrate from Sybase ASE to Azure PostgreSQL", + "type": "Formula", + "effort": "HIGH", + "variants": [ + "sybase-ase-to-azure-sql-database" + ], + "tooltip": "Migrate from Sybase ASE to Azure PostgreSQL for scalable and secure database management in Azure.", + "experimental": true + }, + { + "solutionId": "sybase-ase-to-azure-sql-database", + "name": "Migrate from Sybase ASE to Azure SQL Database", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from Sybase ASE to Azure SQL Database for scalable and secure database management in Azure." + }, + { + "solutionId": "google-firestore-to-azure-cosmos-db", + "name": "Migrate from Google Firestore to Azure Cosmos DB", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from Google Firestore to Azure Cosmos DB for scalable and secure NoSQL database management in Azure.", + "experimental": true + }, + { + "solutionId": "google-cloud-bigtable-to-azure-cosmos-db", + "name": "Migrate from Google Cloud Bigtable to Azure Cosmos DB", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from Google Cloud Bigtable to Azure Cosmos DB for scalable and secure NoSQL database management in Azure.", + "experimental": true + }, + { + "solutionId": "google-cloud-spanner-to-azure-postgresql", + "name": "Migrate from Google Cloud Spanner to Azure PostgreSQL", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from Google Cloud Spanner to Azure PostgreSQL for scalable and secure database management in Azure.", + "experimental": true + }, + { + "solutionId": "apache-pulsar-to-azure-event-hubs", + "name": "Migrate from Apache Pulsar to Azure Event Hubs", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from Apache Pulsar to Azure Event Hubs for scalable and secure event streaming in Azure.", + "experimental": true + }, + { + "solutionId": "ibm-db2-to-azure-postgresql", + "name": "Migrate from IBM DB2 to Azure PostgreSQL", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from IBM DB2 to Azure PostgreSQL for scalable and secure database management in Azure.", + "experimental": true + }, + { + "solutionId": "firebird-to-azure-postgresql", + "name": "Migrate from Firebird to Azure PostgreSQL", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from Firebird to Azure PostgreSQL for scalable and secure database management in Azure.", + "experimental": true + }, + { + "solutionId": "sqlite-to-azure-postgresql", + "name": "Migrate from SQLite to Azure PostgreSQL", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from SQLite to Azure PostgreSQL for scalable and secure database management in Azure.", + "experimental": true + }, + { + "solutionId": "google-cloud-functions-to-azure-functions", + "name": "Migrate from Google Cloud Functions to Azure Functions", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from Google Cloud Functions to Azure Functions for scalable and secure serverless compute in Azure.", + "experimental": true + }, + { + "solutionId": "aws-lambda-to-azure-functions", + "name": "Migrate from AWS Lambda to Azure Functions", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from AWS Lambda to Azure Functions for scalable and secure serverless compute in Azure.", + "experimental": true + }, + { + "solutionId": "spring-batch-to-azure-durable-functions", + "name": "Migrate from Spring Batch to Azure Durable Functions", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from Spring Batch to Azure Durable Functions for scalable and secure serverless compute in Azure.", + "experimental": true + }, + { + "solutionId": "google-cloud-storage-to-azure-blob-storage", + "name": "Migrate from Google Cloud Storage to Azure Blob Storage", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from Google Cloud Storage to Azure Blob Storage for scalable and secure object storage in Azure.", + "experimental": true + }, + { + "solutionId": "amazon-sns-to-azure-service-bus", + "name": "Migrate from Amazon SNS to Azure Service Bus", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from Amazon SNS to Azure Service Bus for scalable and secure messaging in Azure.", + "experimental": true + }, + { + "solutionId": "tibco-ems-jms-to-azure-service-bus", + "name": "Migrate from TIBCO EMS JMS to Azure Service Bus", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from TIBCO EMS JMS to Azure Service Bus for scalable and secure messaging in Azure.", + "experimental": true + }, + { + "solutionId": "solace-pubsub-to-azure-service-bus", + "name": "Migrate from Solace PubSub+ to Azure Service Bus", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from Solace PubSub+ to Azure Service Bus for scalable and secure messaging in Azure.", + "experimental": true + }, + { + "solutionId": "amazon-kinesis-to-azure-event-hubs", + "name": "Migrate from Amazon Kinesis to Azure Event Hubs", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Migrate from Amazon Kinesis to Azure Event Hubs for scalable and secure event streaming in Azure.", + "experimental": true + }, + { + "solutionId": "azure-legacy-java-sdk-upgrade", + "name": "Upgrade from Legacy Azure SDKs for Java to the latest", + "type": "Formula", + "effort": "HIGH", + "tooltip": "Upgrade to the latest stable version of Azure SDKs for Java that follow current Azure SDK guidelines." + }, + { + "solutionId": "bare/weak-cryptography", + "name": "Replace Weak Cryptographic Algorithms", + "type": "Chat", + "prompt": "The application uses weak or broken cryptographic algorithms (such as MD5, SHA-1, DES, RC4, ECB mode, or Blowfish) that do not meet EU Cyber Resilience Act requirements. Replace weak hash algorithms with SHA-256 or SHA-3. Replace broken encryption (DES, RC4, Blowfish, ECB mode) with AES-GCM or ChaCha20-Poly1305. For password hashing, use bcrypt, Argon2, scrypt, or PBKDF2 instead of plain message digests.", + "tooltip": "The app uses weak cryptographic algorithms. Chat with Copilot to learn how to upgrade to modern, secure alternatives." + }, + { + "solutionId": "bare/insecure-tls", + "name": "Fix Insecure TLS/SSL Configuration", + "type": "Chat", + "prompt": "The application uses insecure TLS/SSL configurations, such as deprecated protocol versions (SSLv3, TLS 1.0, TLS 1.1), disabled certificate validation, disabled hostname verification, or weak cipher suites. Upgrade to TLS 1.2 or TLS 1.3, remove trust-all certificate patterns, ensure proper hostname verification, and use only strong cipher suites (AEAD modes like GCM or ChaCha20-Poly1305). For Spring Boot, set server.ssl.enabled-protocols=TLSv1.2,TLSv1.3.", + "tooltip": "The app has insecure TLS/SSL settings. Chat with Copilot to learn how to upgrade to secure TLS configurations." + }, + { + "solutionId": "bare/hardcoded-credentials", + "name": "Remove Hardcoded Credentials", + "type": "Chat", + "prompt": "The application contains hardcoded credentials (passwords, API keys, secrets, cryptographic keys, or default passwords) in source code or configuration files, violating EU Cyber Resilience Act secure-by-default requirements. Move all secrets to Azure Key Vault or a secrets management service. Use environment variables or externalized configuration for sensitive values. Use managed identities for service-to-service authentication. Ensure configuration files with secrets are excluded from version control.", + "tooltip": "The app has hardcoded credentials. Chat with Copilot to learn how to externalize secrets using Azure Key Vault or environment variables." + }, + { + "solutionId": "bare/insecure-random", + "name": "Use Cryptographically Secure Random Number Generation", + "type": "Chat", + "prompt": "The application uses insecure random number generators (java.util.Random, Math.random(), or ThreadLocalRandom) which are predictable and not suitable for security-sensitive operations such as token generation, session IDs, nonces, or encryption keys. Replace with java.security.SecureRandom for all security-relevant random number generation. SecureRandom provides a cryptographically strong random number generator (CSPRNG) backed by the OS entropy source.", + "tooltip": "The app uses insecure random number generators. Chat with Copilot to learn how to switch to SecureRandom for security-sensitive operations." + }, + { + "solutionId": "bare/aws-bedrock-to-azure-ai", + "name": "Migrate from AWS Bedrock to Azure OpenAI Service", + "type": "Chat", + "prompt": "The application uses AWS Bedrock SDK for generative AI capabilities. Consider migrating to Azure OpenAI Service or Azure AI Foundry. Replace AWS Bedrock SDK dependencies with the Azure OpenAI client library (com.azure:azure-ai-openai). Update application code to replace AWS Bedrock API calls with Azure OpenAI equivalents. Replace AWS IAM-based authentication with Azure AD managed identity or API key authentication using DefaultAzureCredential. Update configuration to replace AWS Bedrock settings (endpoint, model IDs, region) with Azure OpenAI configurations (endpoint, deployment name, API version). If using streaming APIs, refactor from AWS reactive streams pattern to Azure OpenAI's iterative streaming model.", + "tooltip": "The app uses AWS Bedrock for AI services. Chat with Copilot to learn how to migrate to Azure OpenAI Service or Azure AI Foundry." + } + ], + "rules": [ + { + "ruleId": "apm-00001", + "sourceCategory": "apm-newrelic", + "solution": "bare/apm-to-application-insights" + }, + { + "ruleId": "apm-00002", + "sourceCategory": "apm-elastic", + "solution": "bare/apm-to-application-insights" + }, + { + "ruleId": "apm-00003", + "sourceCategory": "apm-dynatrace", + "solution": "bare/apm-to-application-insights" + }, + { + "ruleId": "auth-00000", + "sourceCategory": "saml", + "solution": "on-premises-user-authentication-to-microsoft-entra-id" + }, + { + "ruleId": "auth-01000", + "sourceCategory": "opensaml", + "solution": "on-premises-user-authentication-to-microsoft-entra-id" + }, + { + "ruleId": "auth-02000", + "sourceCategory": "spring-security", + "solution": "on-premises-user-authentication-to-microsoft-entra-id" + }, + { + "ruleId": "auth-03000", + "sourceCategory": "oauth2", + "solution": "on-premises-user-authentication-to-microsoft-entra-id" + }, + { + "ruleId": "auth-04000", + "sourceCategory": "openid", + "solution": "on-premises-user-authentication-to-microsoft-entra-id" + }, + { + "ruleId": "webform-auth-00000", + "sourceCategory": "webform-auth", + "solution": "on-premises-user-authentication-to-microsoft-entra-id" + }, + { + "ruleId": "java-ldap-to-msft-entra-id-01000", + "solution": "on-premises-user-authentication-to-microsoft-entra-id" + }, + { + "ruleId": "azure-aws-config-credential-01000", + "sourceCategory": "aws-credentials", + "solution": "bare/aws-credentials-to-azure" + }, + { + "ruleId": "azure-aws-config-region-02000", + "sourceCategory": "aws-region-configuration", + "solution": "bare/aws-region-configuration-to-azure" + }, + { + "ruleId": "azure-aws-config-s3-03000", + "sourceCategory": "aws-s3", + "solution": "s3-to-azure-blob-storage" + }, + { + "ruleId": "azure-aws-config-s3-03001", + "sourceCategory": "aws-s3", + "solution": "s3-to-azure-blob-storage" + }, + { + "ruleId": "azure-aws-config-s3-03002", + "sourceCategory": "aws-s3", + "solution": "s3-to-azure-blob-storage" + }, + { + "ruleId": "azure-aws-config-secret-manager-05000", + "sourceCategory": "aws-secrets-manager", + "solution": "AWS-secrets-manager-to-azure-key-vault" + }, + { + "ruleId": "azure-aws-config-sqs-04000", + "sourceCategory": "aws-sqs", + "solution": "sqs-to-servicebus" + }, + { + "ruleId": "azure-aws-config-sqs-04001", + "sourceCategory": "aws-sqs", + "solution": "sqs-to-servicebus" + }, + { + "ruleId": "azure-aws-config-sqs-04002", + "sourceCategory": "aws-sqs", + "solution": "sqs-to-servicebus" + }, + { + "ruleId": "azure-aws-config-sqs-04003", + "sourceCategory": "aws-sqs", + "solution": "sqs-to-servicebus" + }, + { + "ruleId": "azure-aws-config-sqs-04004", + "sourceCategory": "aws-sqs", + "solution": "sqs-to-servicebus" + }, + { + "ruleId": "azure-cache-redis-01000", + "sourceCategory": "redis", + "solution": "other-cache-solutions-to-azure-managed-cache" + }, + { + "ruleId": "azure-database-config-mongodb-02000", + "sourceCategory": "mongodb", + "solution": "mi-mongodb" + }, + { + "ruleId": "azure-database-microsoft-cassandra-04000", + "sourceCategory": "cassandra", + "solution": "mi-cassandra" + }, + { + "ruleId": "azure-database-microsoft-mariadb-06000", + "sourceCategory": "mariadb", + "solution": "mi-mariadb" + }, + { + "ruleId": "azure-database-microsoft-mongodb-05000", + "sourceCategory": "mongodb", + "solution": "mi-mongodb" + }, + { + "ruleId": "azure-database-microsoft-sql-03000", + "sourceCategory": "microsoft-sql", + "solution": "mi-azure-sql" + }, + { + "ruleId": "azure-database-mysql-01000", + "sourceCategory": "mysql", + "solution": "mi-mysql" + }, + { + "ruleId": "azure-database-postgresql-02000", + "sourceCategory": "postgresql", + "solution": "mi-postgresql" + }, + { + "ruleId": "azure-java-version-01000", + "solution": "java-version-upgrade" + }, + { + "ruleId": "azure-java-version-02000", + "solution": "java-version-upgrade" + }, + { + "ruleId": "azure-keystore-certificates-01000", + "solution": "certificate-management-to-azure-key-vault" + }, + { + "ruleId": "azure-keystore-certificates-02000", + "solution": "certificate-management-to-azure-key-vault" + }, + { + "ruleId": "dockerfile-00000", + "solution": "containerization-copilot-agent" + }, + { + "ruleId": "dockerfile-00010", + "solution": "containerization-copilot-agent" + }, + { + "ruleId": "dockerfile-00020", + "solution": "containerization-copilot-agent" + }, + { + "ruleId": "dockerfile-00030", + "solution": "containerization-copilot-agent" + }, + { + "ruleId": "azure-message-queue-activemq-01000", + "sourceCategory": "activemq-artemis", + "solution": "activemq-servicebus" + }, + { + "ruleId": "azure-message-queue-amqp-02000", + "sourceCategory": "spring-amqp-rabbitmq", + "solution": "amqp-rabbitmq-servicebus" + }, + { + "ruleId": "azure-message-queue-config-artemis-01000", + "sourceCategory": "activemq-artemis", + "solution": "activemq-servicebus" + }, + { + "ruleId": "azure-message-queue-config-kafka-01000", + "sourceCategory": "kafka", + "solution": "confluent-cloud-kafka" + }, + { + "ruleId": "azure-message-queue-config-rabbitmq-01000", + "sourceCategory": "spring-amqp-rabbitmq", + "solution": "amqp-rabbitmq-servicebus" + }, + { + "ruleId": "azure-message-queue-rabbitmq-01000", + "sourceCategory": "spring-amqp-rabbitmq", + "solution": "amqp-rabbitmq-servicebus" + }, + { + "ruleId": "azure-message-queue-java-ee-rabbitmq-amqp-01000", + "sourceCategory": "java-ee-amqp-rabbitmq", + "solution": "java-ee-amqp-rabbitmq-servicebus" + }, + { + "ruleId": "azure-message-queue-spring-jms-rabbitmq-01000", + "sourceCategory": "spring-jms-rabbitmq", + "solution": "spring-jms-rabbitmq-servicebus" + }, + { + "ruleId": "azure-message-queue-ibm-jms-01000", + "sourceCategory": "jms-ibm-mq", + "solution": "ibm-mq-jms-to-azure-service-bus" + }, + { + "ruleId": "azure-password-01000", + "solution": "plaintext-credential-to-azure-keyvault" + }, + { + "ruleId": "azure-system-config-01000", + "sourceCategory": "environment-variables", + "solution": "bare/configuration-management/environment-variables" + }, + { + "ruleId": "external-config-00000", + "sourceCategory": "external-configuration", + "solution": "bare/configuration-management/external-configuration" + }, + { + "ruleId": "windows-registry-00000", + "sourceCategory": "windows-registry", + "solution": "bare/configuration-management/windows-registry" + }, + { + "ruleId": "azure-tas-binding-01000", + "sourceCategory": "tanzu-application-service", + "solution": "bare/azure-service-connector" + }, + { + "ruleId": "clustering-00000", + "sourceCategory": "http-session", + "solution": "other-cache-solutions-to-azure-managed-cache" + }, + { + "ruleId": "eap-to-azure-appservice-datasource-driver-01000", + "sourceCategory": "jboss-eap", + "solution": "bare/eap-migration/jboss-eap" + }, + { + "ruleId": "eap-to-azure-appservice-pom-001", + "sourceCategory": "jboss-eap", + "solution": "bare/eap-migration/jboss-eap" + }, + { + "ruleId": "embedded-cache-01000", + "solution": "other-cache-solutions-to-azure-managed-cache" + }, + { + "ruleId": "embedded-cache-02000", + "solution": "other-cache-solutions-to-azure-managed-cache" + }, + { + "ruleId": "embedded-cache-03000", + "solution": "other-cache-solutions-to-azure-managed-cache" + }, + { + "ruleId": "embedded-cache-04000", + "solution": "other-cache-solutions-to-azure-managed-cache" + }, + { + "ruleId": "embedded-cache-05000", + "solution": "other-cache-solutions-to-azure-managed-cache" + }, + { + "ruleId": "embedded-cache-06000", + "solution": "other-cache-solutions-to-azure-managed-cache" + }, + { + "ruleId": "embedded-cache-07000", + "solution": "other-cache-solutions-to-azure-managed-cache" + }, + { + "ruleId": "embedded-cache-08000", + "solution": "other-cache-solutions-to-azure-managed-cache" + }, + { + "ruleId": "embedded-cache-09000", + "solution": "other-cache-solutions-to-azure-managed-cache" + }, + { + "ruleId": "embedded-cache-10000", + "solution": "other-cache-solutions-to-azure-managed-cache" + }, + { + "ruleId": "embedded-cache-11000", + "solution": "other-cache-solutions-to-azure-managed-cache" + }, + { + "ruleId": "embedded-cache-12000", + "solution": "other-cache-solutions-to-azure-managed-cache" + }, + { + "ruleId": "embedded-cache-13000", + "solution": "other-cache-solutions-to-azure-managed-cache" + }, + { + "ruleId": "embedded-cache-14000", + "solution": "other-cache-solutions-to-azure-managed-cache" + }, + { + "ruleId": "embedded-cache-15000", + "solution": "other-cache-solutions-to-azure-managed-cache" + }, + { + "ruleId": "embedded-cache-16000", + "sourceCategory": "redis", + "solution": "other-cache-solutions-to-azure-managed-cache" + }, + { + "ruleId": "hardcoded-ip-address", + "sourceCategory": "hardcode-ip", + "solution": "bare/remote-communication/hardcode-ip" + }, + { + "ruleId": "unsecure-network-protocol-00000", + "sourceCategory": "secure-protocols", + "solution": "bare/remote-communication/secure-protocols" + }, + { + "ruleId": "hardcoded-urls-00001", + "sourceCategory": "hardcoded-urls", + "solution": "bare/remote-communication/hardcoded-urls" + }, + { + "ruleId": "hardcoded-urls-00002", + "sourceCategory": "hardcoded-urls", + "solution": "bare/remote-communication/hardcoded-urls" + }, + { + "ruleId": "java-corba-00000", + "sourceCategory": "corba", + "solution": "bare/remote-communication/corba" + }, + { + "ruleId": "java-removals-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-removals-00010", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-rmi-00000", + "sourceCategory": "rmi", + "solution": "bare/jakataee-to-azure/rmi" + }, + { + "ruleId": "java-rmi-00001", + "sourceCategory": "rmi", + "solution": "bare/jakataee-to-azure/rmi" + }, + { + "ruleId": "java-rpc-00000", + "solution": "jax-rpc-to-jax-ws" + }, + { + "ruleId": "jca-00000", + "sourceCategory": "jca", + "solution": "bare/jakataee-to-azure/jca" + }, + { + "ruleId": "jni-native-code-00000", + "sourceCategory": "jni-native-code", + "solution": "bare/java-native-code" + }, + { + "ruleId": "jni-native-code-00001", + "sourceCategory": "jni-native-code", + "solution": "bare/java-native-code" + }, + { + "ruleId": "azure-file-system-02000", + "sourceCategory": "local-file-system", + "solution": "local-files-to-mounted-azure-storage" + }, + { + "ruleId": "azure-file-system-03000", + "sourceCategory": "local-file-system", + "solution": "local-files-to-mounted-azure-storage" + }, + { + "ruleId": "local-storage-00001", + "sourceCategory": "local-file-system", + "solution": "local-files-to-mounted-azure-storage" + }, + { + "ruleId": "local-storage-00002", + "sourceCategory": "local-file-system", + "solution": "local-files-to-mounted-azure-storage" + }, + { + "ruleId": "local-storage-00003", + "sourceCategory": "local-file-system", + "solution": "local-files-to-mounted-azure-storage" + }, + { + "ruleId": "local-storage-00004", + "sourceCategory": "local-file-system", + "solution": "local-files-to-mounted-azure-storage" + }, + { + "ruleId": "local-storage-00005", + "sourceCategory": "local-file-system", + "solution": "local-files-to-mounted-azure-storage" + }, + { + "ruleId": "local-storage-00006", + "sourceCategory": "local-file-system", + "solution": "local-files-to-mounted-azure-storage" + }, + { + "ruleId": "localhost-http-00001", + "sourceCategory": "localhost", + "solution": "bare/local-resource-access" + }, + { + "ruleId": "localhost-jdbc-00002", + "sourceCategory": "localhost", + "solution": "bare/local-resource-access" + }, + { + "ruleId": "localhost-ws-00003", + "sourceCategory": "localhost", + "solution": "bare/local-resource-access" + }, + { + "ruleId": "localhost-00004", + "sourceCategory": "localhost", + "solution": "bare/local-resource-access" + }, + { + "ruleId": "logging-0000", + "solution": "log-to-console" + }, + { + "ruleId": "logging-0001", + "solution": "log-to-console" + }, + { + "ruleId": "logging-0002", + "solution": "log-to-console" + }, + { + "ruleId": "logging-0004", + "sourceCategory": "splunk", + "solution": "log-to-console" + }, + { + "ruleId": "logging-0005", + "sourceCategory": "zipkin", + "solution": "bare/apm-to-application-insights" + }, + { + "ruleId": "lombok-incompatibility-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "mail-00000", + "sourceCategory": "java-mail", + "solution": "javax.email-send-to-azure-communication-service-email" + }, + { + "ruleId": "os-specific-00002", + "solution": "bare/os-compatibility" + }, + { + "ruleId": "removed-packages-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "removed-packages-00010", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "session-00001", + "sourceCategory": "http-session", + "solution": "other-cache-solutions-to-azure-managed-cache" + }, + { + "ruleId": "socket-communication-00000", + "sourceCategory": "java-socket", + "solution": "bare/remote-communication/java-socket" + }, + { + "ruleId": "socket-communication-00001", + "sourceCategory": "java-socket", + "solution": "bare/remote-communication/java-socket" + }, + { + "ruleId": "spring-boot-to-azure-config-server-01000", + "sourceCategory": "spring-cloud", + "solution": "spring-cloud-config-to-azure-app-configuration" + }, + { + "ruleId": "spring-boot-to-azure-eureka-01000", + "sourceCategory": "spring-cloud", + "solution": "bare/spring-migration" + }, + { + "ruleId": "spring-boot-to-azure-eureka-02000", + "sourceCategory": "spring-cloud", + "solution": "bare/spring-migration" + }, + { + "ruleId": "spring-boot-to-azure-eureka-03000", + "sourceCategory": "spring-cloud", + "solution": "bare/spring-migration" + }, + { + "ruleId": "spring-boot-to-azure-key-vault-01000", + "sourceCategory": "spring-cloud-vault", + "solution": "bare/spring-cloud-vault-migration" + }, + { + "ruleId": "spring-boot-to-azure-openfeign-01000", + "sourceCategory": "spring-cloud", + "solution": "bare/spring-migration" + }, + { + "ruleId": "spring-boot-to-azure-port-01000", + "sourceCategory": "spring-cloud", + "solution": "bare/spring-migration" + }, + { + "ruleId": "spring-boot-to-azure-restricted-config-01000", + "sourceCategory": "spring-cloud", + "solution": "bare/spring-migration" + }, + { + "ruleId": "spring-boot-to-azure-spring-boot-version-01000", + "sourceCategory": "spring-boot", + "solution": "spring-boot-upgrade" + }, + { + "ruleId": "spring-boot-to-azure-spring-cloud-version-01000", + "sourceCategory": "spring-cloud", + "solution": "spring-boot-upgrade" + }, + { + "ruleId": "spring-boot-to-azure-spring-cloud-version-02000", + "sourceCategory": "spring-cloud", + "solution": "spring-boot-upgrade" + }, + { + "ruleId": "spring-framework-version-01000", + "sourceCategory": "spring-framework", + "solution": "spring-framework-upgrade" + }, + { + "ruleId": "jakarta-ee-version-01000", + "sourceCategory": "java-ee/jakarta-ee", + "solution": "jakarta-ee-upgrade" + }, + { + "ruleId": "utf-8-by-default-00000", + "solution": "bare/encoding-standards" + }, + { + "ruleId": "utf-8-by-default-00010", + "solution": "bare/encoding-standards" + }, + { + "ruleId": "utf-8-by-default-00020", + "solution": "bare/encoding-standards" + }, + { + "ruleId": "utf-8-by-default-00030", + "solution": "bare/encoding-standards" + }, + { + "ruleId": "web-10000", + "sourceCategory": "javax-swing", + "solution": "bare/redesign-java-gui-app" + }, + { + "ruleId": "web-11000", + "sourceCategory": "javafx", + "solution": "bare/redesign-java-gui-app" + }, + { + "ruleId": "oracle2openjdk-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "oracle2openjdk-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "oracle2openjdk-00002", + "solution": "bare/oraclejdk-to-openjdk/resource-management-apis" + }, + { + "ruleId": "oracle2openjdk-00003", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "oracle2openjdk-00004", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "oracle2openjdk-00005", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "oracle2openjdk-00006", + "solution": "bare/oraclejdk-to-openjdk/imageio" + }, + { + "ruleId": "java-8-deprecate-apt-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-8-deprecate-callback-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-8-deprecate-corba-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-8-deprecate-javafx-builder-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-8-deprecate-log-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-8-deprecate-odbc-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-8-deprecate-pack-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-8-deprecate-pack-00002", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-8-deprecate-security-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-8-deprecate-security-00002", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-8-deprecate-security-manager-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-8-deprecate-security-manager-00002", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-8-deprecate-stream-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-8-deprecate-thread-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-10-deprecate-dom-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-10-deprecate-javafx-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-10-deprecate-runtime-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-10-deprecate-security-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-10-deprecate-security-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-10-deprecate-security-00002", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-10-deprecate-security-00003", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-10-deprecate-security-00004", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-11-deprecate-awt-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-11-deprecate-corba-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-11-deprecate-javaee-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-11-deprecate-javaee-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-11-deprecate-pack-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-11-deprecate-peer-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-11-deprecate-property-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-11-deprecate-property-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-11-deprecate-security-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-11-deprecate-security-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-11-deprecate-stream-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-11-deprecate-thread-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-11-deprecate-unsafe-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-11-deprecate-unsafe-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-9-deprecate-agent-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-9-deprecate-dom-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-9-deprecate-javafx-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-9-deprecate-log-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-9-deprecate-pack-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-9-deprecate-peer-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-9-deprecate-property-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-9-deprecate-property-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-9-deprecate-reflect-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-9-deprecate-reflect-00010", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-9-deprecate-security-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-9-deprecate-security-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-9-deprecate-security-00002", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-9-deprecate-tracing-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-9-deprecate-unsafe-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-9-deprecate-unsafe-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-9-deprecate-url-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-removals-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-removals-00010", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-12-deprecate-finalize-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-12-deprecate-finalize-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-12-deprecate-security-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-13-deprecate-runtime-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-13-deprecate-security-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-14-deprecate-pack-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-14-deprecate-property-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-14-deprecate-property-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-14-deprecate-security-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-14-deprecate-thread-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-15-deprecate-property-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-15-deprecate-signer-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-15-deprecate-ssl-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-15-deprecate-ssl-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-16-deprecate-security-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-16-deprecate-thread-group-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-17-deprecate-applet-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-17-deprecate-security-manager-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-17-deprecate-security-manager-00010", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-17-deprecate-security-manager-00020", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-17-deprecate-security-manager-00030", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-17-deprecate-security-manager-00040", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-17-deprecate-security-manager-00050", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-17-deprecate-security-manager-00060", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-17-deprecate-security-manager-00070", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-17-deprecate-socket-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-17-deprecate-unsafe-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "lombok-incompatibility-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "removed-packages-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "removed-packages-00010", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-18-deprecate-finalize-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-18-deprecate-finalize-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-18-deprecate-property-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-18-deprecate-runtime-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-18-deprecate-security-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-18-deprecate-socket-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-18-deprecate-thread-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-18-deprecate-unsafe-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-19-deprecate-locale-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-19-deprecate-param-spec-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-19-deprecate-param-spec-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-19-deprecate-class-00010", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-19-deprecate-thread-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-19-deprecate-thread-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-19-deprecate-thread-00002", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-20-deprecate-jmx-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-20-deprecate-net-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-20-deprecate-thread-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-20-deprecate-thread-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-20-deprecate-thread-00002", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-21-deprecate-dynamic-agents-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-21-deprecate-file-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-21-deprecate-file-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-21-deprecate-jmx-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-21-deprecate-jmx-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-21-deprecate-property-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-21-deprecate-property-00001", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-21-deprecate-signer-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "java-21-deprecate-thread-00000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "openliberty-database-00001", + "sourceCategory": "openliberty-database", + "solution": "bare/openliberty-migration/openliberty-database" + }, + { + "ruleId": "openliberty-database-00002", + "sourceCategory": "openliberty-database", + "solution": "bare/openliberty-migration/openliberty-database" + }, + { + "ruleId": "openliberty-database-00003", + "sourceCategory": "openliberty-database", + "solution": "bare/openliberty-migration/openliberty-database" + }, + { + "ruleId": "openliberty-database-00004", + "sourceCategory": "openliberty-database", + "solution": "bare/openliberty-migration/openliberty-database" + }, + { + "ruleId": "openliberty-database-00005", + "sourceCategory": "openliberty-database", + "solution": "bare/openliberty-migration/openliberty-database" + }, + { + "ruleId": "openliberty-database-00006", + "sourceCategory": "openliberty-database", + "solution": "bare/openliberty-migration/openliberty-database" + }, + { + "ruleId": "openliberty-database-00007", + "sourceCategory": "openliberty-database", + "solution": "bare/openliberty-migration/openliberty-database" + }, + { + "ruleId": "openliberty-database-00008", + "sourceCategory": "openliberty-database", + "solution": "bare/openliberty-migration/openliberty-database" + }, + { + "ruleId": "openliberty-database-00009", + "sourceCategory": "openliberty-database", + "solution": "bare/openliberty-migration/openliberty-database" + }, + { + "ruleId": "openliberty-filesystem-00001", + "sourceCategory": "openliberty-filesystem", + "solution": "bare/openliberty-migration/openliberty-filesystem" + }, + { + "ruleId": "openliberty-filesystem-00002", + "sourceCategory": "openliberty-filesystem", + "solution": "bare/openliberty-migration/openliberty-filesystem" + }, + { + "ruleId": "openliberty-filesystem-00003", + "sourceCategory": "openliberty-filesystem", + "solution": "bare/openliberty-migration/openliberty-filesystem" + }, + { + "ruleId": "openliberty-filesystem-00004", + "sourceCategory": "openliberty-filesystem", + "solution": "bare/openliberty-migration/openliberty-filesystem" + }, + { + "ruleId": "openliberty-jms-00001", + "sourceCategory": "openliberty-jms", + "solution": "bare/openliberty-migration/openliberty-jms" + }, + { + "ruleId": "openliberty-jms-00002", + "sourceCategory": "openliberty-jms", + "solution": "bare/openliberty-migration/openliberty-jms" + }, + { + "ruleId": "openliberty-jms-00003", + "sourceCategory": "openliberty-jms", + "solution": "bare/openliberty-migration/openliberty-jms" + }, + { + "ruleId": "openliberty-jms-00004", + "sourceCategory": "openliberty-jms", + "solution": "bare/openliberty-migration/openliberty-jms" + }, + { + "ruleId": "openliberty-jms-00005", + "sourceCategory": "openliberty-jms", + "solution": "bare/openliberty-migration/openliberty-jms" + }, + { + "ruleId": "openliberty-jms-00006", + "sourceCategory": "openliberty-jms", + "solution": "bare/openliberty-migration/openliberty-jms" + }, + { + "ruleId": "openliberty-logging-00001", + "sourceCategory": "openliberty-logging", + "solution": "bare/openliberty-migration/openliberty-logging" + }, + { + "ruleId": "openliberty-logging-00002", + "sourceCategory": "openliberty-logging", + "solution": "bare/openliberty-migration/openliberty-logging" + }, + { + "ruleId": "azure-database-microsoft-oracle-07000", + "sourceCategory": "oracle", + "solution": "oracle-to-postgresql" + }, + { + "ruleId": "database-reliability-01000", + "solution": "bare/database-migration/database-reliability" + }, + { + "ruleId": "eclipse-00002", + "sourceCategory": "eclipse", + "solution": "eclipse-project-to-maven-project" + }, + { + "ruleId": "ant-build-tool-00001", + "sourceCategory": "ant", + "solution": "ant-project-to-maven-project" + }, + { + "ruleId": "google-pubsub-to-azure-service-bus-01000", + "sourceCategory": "google-pubsub", + "solution": "google-cloud-pub-sub-to-azure-service-bus" + }, + { + "ruleId": "google-gcr-to-azure-acr-01000", + "sourceCategory": "google-gcr", + "solution": "google-gcr-to-azure-acr" + }, + { + "ruleId": "sybase-ase-to-azure-database-01000", + "sourceCategory": "sybase-ase", + "solution": "sybase-ase-to-azure-postgresql" + }, + { + "ruleId": "google-firestore-to-azure-cosmosdb-01000", + "sourceCategory": "google-firestore", + "solution": "google-firestore-to-azure-cosmos-db" + }, + { + "ruleId": "google-cloud-bigtable-to-azure-cosmosdb-01000", + "sourceCategory": "google-cloud-bigtable", + "solution": "google-cloud-bigtable-to-azure-cosmos-db" + }, + { + "ruleId": "google-cloud-spanner-to-azure-postgresql-01000", + "sourceCategory": "google-cloud-spanner", + "solution": "google-cloud-spanner-to-azure-postgresql" + }, + { + "ruleId": "apache-pulsar-to-azure-eventhubs-01000", + "sourceCategory": "apache-pulsar", + "solution": "apache-pulsar-to-azure-event-hubs" + }, + { + "ruleId": "ibm-db2-to-azure-postgresql-01000", + "sourceCategory": "ibm-db2", + "solution": "ibm-db2-to-azure-postgresql" + }, + { + "ruleId": "firebird-to-azure-postgresql-01000", + "sourceCategory": "firebird", + "solution": "firebird-to-azure-postgresql" + }, + { + "ruleId": "sqlite-to-azure-postgresql-01000", + "sourceCategory": "sqlite", + "solution": "sqlite-to-azure-postgresql" + }, + { + "ruleId": "google-cloud-functions-to-azure-functions-01000", + "sourceCategory": "google-cloud-functions", + "solution": "google-cloud-functions-to-azure-functions" + }, + { + "ruleId": "aws-lambda-to-azure-functions-01000", + "sourceCategory": "aws-lambda", + "solution": "aws-lambda-to-azure-functions" + }, + { + "ruleId": "quartz-scheduler-to-azure-functions-01000", + "sourceCategory": "quartz-scheduler", + "solution": "quartz-scheduler-to-azure-functions" + }, + { + "ruleId": "spring-batch-to-azure-durable-functions-01000", + "sourceCategory": "spring-batch", + "solution": "spring-batch-to-azure-durable-functions" + }, + { + "ruleId": "google-cloud-storage-to-azure-blob-storage-01000", + "sourceCategory": "google-cloud-storage", + "solution": "google-cloud-storage-to-azure-blob-storage" + }, + { + "ruleId": "amazon-sns-to-azure-servicebus-01000", + "sourceCategory": "amazon-sns", + "solution": "amazon-sns-to-azure-service-bus" + }, + { + "ruleId": "tibco-ems-jms-to-azure-servicebus-jms-01000", + "sourceCategory": "tibco-ems-jms", + "solution": "tibco-ems-jms-to-azure-service-bus" + }, + { + "ruleId": "solace-pubsubplus-to-azure-servicebus-01000", + "sourceCategory": "solace-pubsubplus", + "solution": "solace-pubsub-to-azure-service-bus" + }, + { + "ruleId": "amazon-kinesis-to-azure-eventhubs-01000", + "sourceCategory": "amazon-kinesis", + "solution": "amazon-kinesis-to-azure-event-hubs" + }, + { + "ruleId": "jakarta-auth-00001", + "sourceCategory": "jakarta-auth", + "solution": "bare/jakarta-auth-migration" + }, + { + "ruleId": "jakarta-database-00001", + "sourceCategory": "jakarta-nosql", + "solution": "bare/jakarta-nosql-migration" + }, + { + "ruleId": "jakarta-database-00002", + "sourceCategory": "jakarta-persistence", + "solution": "bare/jakarta-persistence-migration" + }, + { + "ruleId": "jakarta-database-00003", + "sourceCategory": "jakarta-data", + "solution": "bare/jakarta-data-migration" + }, + { + "ruleId": "jakarta-service-00001", + "sourceCategory": "jakarta-websocket", + "solution": "bare/jakarta-websocket-migration" + }, + { + "ruleId": "jakarta-service-00002", + "sourceCategory": "jakarta-jaxrs", + "solution": "bare/jakarta-jaxrs-migration" + }, + { + "ruleId": "websphere-to-azure-app-service", + "sourceCategory": "websphere-to-azure-app-service", + "solution": "bare/websphere-to-azure-app-service" + }, + { + "ruleId": "websphere-to-aks", + "sourceCategory": "websphere-to-aks", + "solution": "bare/websphere-to-aks" + }, + { + "ruleId": "websphere-to-azure-container-apps", + "sourceCategory": "websphere-to-azure-container-apps", + "solution": "bare/websphere-to-azure-container-apps" + }, + { + "ruleId": "weblogic-to-azure-app-service", + "sourceCategory": "weblogic-to-azure-app-service", + "solution": "bare/weblogic-to-azure-app-service" + }, + { + "ruleId": "weblogic-to-aks", + "sourceCategory": "weblogic-to-aks", + "solution": "bare/weblogic-to-aks" + }, + { + "ruleId": "weblogic-to-azure-container-apps", + "sourceCategory": "weblogic-to-azure-container-apps", + "solution": "bare/weblogic-to-azure-container-apps" + }, + { + "ruleId": "jboss-eap-to-azure-app-service", + "sourceCategory": "jboss-eap-to-azure-app-service", + "solution": "bare/jboss-eap-to-azure-app-service" + }, + { + "ruleId": "jboss-eap-to-aks", + "sourceCategory": "jboss-eap-to-aks", + "solution": "bare/jboss-eap-to-aks" + }, + { + "ruleId": "jboss-eap-to-azure-container-apps", + "sourceCategory": "jboss-eap-to-azure-container-apps", + "solution": "bare/jboss-eap-to-azure-container-apps" + }, + { + "ruleId": "jakarta-cdi-00002", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "jakarta-cdi-00003", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "jboss-dependencies-00006", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "jboss-eap5-7-java-03000", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "jboss-eap5-7-java-08000", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "jboss-eap4and5to6and7-java-01000", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "jboss-eap5and6to7-java-08000", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "base64-01000", + "solution": "deprecated-api-upgrade" + }, + { + "ruleId": "seam-java-00010", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "seam-java-00040", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "seam-java-00070", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "seam-java-00030", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "seam-java-00080", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "commonj-weblogic-02000", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "commonj-weblogic-03000", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "commonj-weblogic-05000", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "commonj-weblogic-06000", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "commonj-weblogic-07000", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "weblogic-jms-eap7-01000", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "weblogic-portability-lifecycle-01000", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "weblogic-portability-servlet-01000", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "weblogic-webservices-eap7-01000", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "weblogic-webapp-eap7-07000", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "commonj-websphere-02000", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "commonj-websphere-03000", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "commonj-websphere-05000", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "commonj-websphere-06000", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "commonj-websphere-07000", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "websphere-jms-eap7-01000", + "solution": "bare/appserver-api-migration-to-standard-java" + }, + { + "ruleId": "azure-java-sdk-legacy-migration-01000", + "solution": "azure-legacy-java-sdk-upgrade" + }, + { + "ruleId": "cra-weak-crypto-md5-01000", + "solution": "bare/weak-cryptography" + }, + { + "ruleId": "cra-weak-crypto-sha1-02000", + "solution": "bare/weak-cryptography" + }, + { + "ruleId": "cra-weak-crypto-des-03000", + "solution": "bare/weak-cryptography" + }, + { + "ruleId": "cra-weak-crypto-rc4-04000", + "solution": "bare/weak-cryptography" + }, + { + "ruleId": "cra-weak-crypto-ecb-05000", + "solution": "bare/weak-cryptography" + }, + { + "ruleId": "cra-weak-crypto-blowfish-06000", + "solution": "bare/weak-cryptography" + }, + { + "ruleId": "cra-weak-crypto-password-hash-07000", + "solution": "bare/weak-cryptography" + }, + { + "ruleId": "cra-insecure-tls-protocol-01000", + "solution": "bare/insecure-tls" + }, + { + "ruleId": "cra-insecure-tls-config-02000", + "solution": "bare/insecure-tls" + }, + { + "ruleId": "cra-insecure-tls-trust-all-03000", + "solution": "bare/insecure-tls" + }, + { + "ruleId": "cra-insecure-tls-hostname-verify-04000", + "solution": "bare/insecure-tls" + }, + { + "ruleId": "cra-insecure-tls-cipher-suite-05000", + "solution": "bare/insecure-tls" + }, + { + "ruleId": "cra-hardcoded-credential-password-01000", + "solution": "bare/hardcoded-credentials" + }, + { + "ruleId": "cra-hardcoded-credential-apikey-02000", + "solution": "bare/hardcoded-credentials" + }, + { + "ruleId": "cra-hardcoded-credential-config-03000", + "solution": "bare/hardcoded-credentials" + }, + { + "ruleId": "cra-hardcoded-credential-default-pwd-04000", + "solution": "bare/hardcoded-credentials" + }, + { + "ruleId": "cra-hardcoded-credential-crypto-key-05000", + "solution": "bare/hardcoded-credentials" + }, + { + "ruleId": "cra-insecure-random-01000", + "solution": "bare/insecure-random" + }, + { + "ruleId": "cra-insecure-random-math-02000", + "solution": "bare/insecure-random" + }, + { + "ruleId": "cra-insecure-random-threadlocal-03000", + "solution": "bare/insecure-random" + }, + { + "ruleId": "aws-bedrock-to-azure-ai-06000", + "sourceCategory": "aws-bedrock", + "solution": "bare/aws-bedrock-to-azure-ai" + }, + { + "ruleId": "aws-bedrock-to-azure-ai-06001", + "sourceCategory": "aws-bedrock", + "solution": "bare/aws-bedrock-to-azure-ai" + }, + { + "ruleId": "aws-bedrock-to-azure-ai-06002", + "sourceCategory": "aws-bedrock", + "solution": "bare/aws-bedrock-to-azure-ai" + } + ] +} diff --git a/plugins/github-copilot-modernization/skills/assessment-report-converter/tests/test_report_tools.py b/plugins/github-copilot-modernization/skills/assessment-report-converter/tests/test_report_tools.py new file mode 100644 index 0000000..9467fa3 --- /dev/null +++ b/plugins/github-copilot-modernization/skills/assessment-report-converter/tests/test_report_tools.py @@ -0,0 +1,571 @@ +#!/usr/bin/env python3 +"""CLI tests for the assessment-report-converter helper scripts. + +The skill ships two interchangeable implementations of the same helper CLI: + + * ``scripts/report_tools.sh`` — bash + jq + * ``scripts/report_tools.ps1`` — PowerShell 7+ + +Both MUST behave identically (same output data, same exit codes: 0 valid, +1 invalid, 2 read/parse error). This harness drives whichever interpreters are +available on the machine and runs the full assertion battery against each one, +skipping an interpreter that is not installed. There is no Python implementation +any more, so every check goes through a subprocess. + +Run from anywhere with stdlib only:: + + python -m unittest discover -s skills/assessment-report-converter/tests -v + +On Linux/CI ``bash``+``jq`` and ``pwsh`` are both present. On Windows ``bash`` +is the WSL launcher (paths are converted to ``/mnt/...``) and ``pwsh`` is +PowerShell 7. These tests are developer-only and are excluded from the shipped +plugin via ``copilot-cli-plugin/.syncignore``. +""" + +import json +import os +import shutil +import subprocess +import tempfile +import unittest + +HERE = os.path.dirname(os.path.abspath(__file__)) +SCRIPTS_DIR = os.path.abspath(os.path.join(HERE, "..", "scripts")) +SH_PATH = os.path.join(SCRIPTS_DIR, "report_tools.sh") +PS1_PATH = os.path.join(SCRIPTS_DIR, "report_tools.ps1") +SCHEMA_PATH = os.path.join(SCRIPTS_DIR, "assessment-report.schema.json") +IS_WIN = os.name == "nt" + + +# --------------------------------------------------------------------------- # +# Path helper (Windows -> WSL) +# --------------------------------------------------------------------------- # +def _win_to_wsl(path): + """Convert C:\\a\\b to /mnt/c/a/b without spawning wslpath.""" + drive, rest = os.path.splitdrive(os.path.abspath(path)) + return "/mnt/" + drive[0].lower() + rest.replace("\\", "/") + + +def _shq(value): + return "'" + value.replace("'", "'\\''") + "'" + + +# --------------------------------------------------------------------------- # +# Interpreter runners — each exposes .run(*args) and .path(p) +# --------------------------------------------------------------------------- # +class _Runner: + name = "?" + + def run(self, *args): + raise NotImplementedError + + def path(self, p): + return p + + +class BashRunner(_Runner): + name = "bash" + + def __init__(self): + self.script = _win_to_wsl(SH_PATH) if IS_WIN else SH_PATH + + @staticmethod + def available(): + if not shutil.which("bash"): + return False + probe = subprocess.run( + ["bash", "-lc", "command -v jq >/dev/null 2>&1 && echo JQ_OK"], + capture_output=True, text=True, + ) + return "JQ_OK" in probe.stdout + + def path(self, p): + return _win_to_wsl(p) if IS_WIN else p + + def run(self, *args): + if IS_WIN: + inner = " ".join(["bash", _shq(self.script)] + [_shq(a) for a in args]) + return subprocess.run(["bash", "-lc", inner], capture_output=True, text=True) + return subprocess.run(["bash", self.script, *args], capture_output=True, text=True) + + +class PwshRunner(_Runner): + name = "pwsh" + + def __init__(self): + # Require PowerShell 7+ (`pwsh`): the script uses `ConvertTo-Json -AsArray`, + # which Windows PowerShell 5.1 (`powershell.exe`) does not support. + self.exe = shutil.which("pwsh") + + @staticmethod + def available(): + return bool(shutil.which("pwsh")) + + def run(self, *args): + return subprocess.run( + [self.exe, "-NoProfile", "-File", PS1_PATH, *args], + capture_output=True, text=True, + ) + + +def _discover_runners(): + runners = [] + if BashRunner.available(): + runners.append(BashRunner()) + if PwshRunner.available(): + runners.append(PwshRunner()) + return runners + + +RUNNERS = _discover_runners() + + +# --------------------------------------------------------------------------- # +# Mock data +# --------------------------------------------------------------------------- # +def valid_report(): + """A minimal report that passes the structural + consistency checks. + + Tests deep-copy this via json round-trip and mutate a single field to + exercise one failure at a time, so every negative test stays isolated. + """ + return { + "version": "1.0.0", + "producer": "CSV import", + "metadata": { + "id": "report-test-001", + "name": "Test Report", + "status": "completed", + "analysisStartTime": "2026-01-01T00:00:00Z", + "mode": "full", + "domains": ["java-upgrade", "security"], + "targetIds": ["azure-appservice"], + }, + "projects": [ + { + "path": "app", + "properties": {"appName": "demo-app"}, + "incidents": [ + { + "ruleId": "spring-boot-upgrade", + "incidentId": "inc-1", + "location": "pom.xml", + "locationKind": "file", + "line": 12, + "column": 3, + } + ], + } + ], + "rules": { + "spring-boot-upgrade": { + "id": "spring-boot-upgrade", + "title": "Upgrade Spring Boot to a supported version", + "severity": "mandatory", + "effort": 5, + "domain": "java-upgrade", + "category": "spring-boot", + } + }, + "security": [ + { + "id": "CVE-2024-0001", + "title": "Vulnerable dependency", + "category": "dependency-vulnerability", + "severity": "mandatory", + "description": "A vulnerable library version is in use.", + "storyPoint": 3, + "evidence": { + "files": ["pom.xml"], + "explanation": "commons-x 1.0 is affected.", + }, + } + ], + } + + +def _clone(report): + return json.loads(json.dumps(report)) + + +def _load_schema(): + with open(SCHEMA_PATH, "r", encoding="utf-8") as fh: + return json.load(fh) + + +# --------------------------------------------------------------------------- # +# Subprocess helpers +# --------------------------------------------------------------------------- # +def _run_validate(runner, report_obj): + """Write report_obj to a temp file, validate it, return (rc, stdout, errors).""" + fd, path = tempfile.mkstemp(suffix=".json") + with os.fdopen(fd, "w", encoding="utf-8") as fh: + json.dump(report_obj, fh) + try: + cp = runner.run("validate", runner.path(path)) + finally: + os.remove(path) + errors = [line[4:] for line in cp.stdout.splitlines() if line.startswith(" - ")] + return cp.returncode, cp.stdout, errors + + +@unittest.skipUnless(RUNNERS, "no report_tools interpreter (bash+jq or pwsh) available") +class _MultiInterpreterCase(unittest.TestCase): + """Base class: subclasses iterate their body over every available runner.""" + + def for_each_runner(self): + for runner in RUNNERS: + yield runner + + +# --------------------------------------------------------------------------- # +# Deterministic lookups (against the real solution-mapping.json) +# --------------------------------------------------------------------------- # +class TestLookups(_MultiInterpreterCase): + def test_upgrade_solutions_resolves_all_components(self): + for runner in self.for_each_runner(): + with self.subTest(interp=runner.name): + cp = runner.run("upgrade-solutions") + self.assertEqual(cp.returncode, 0, cp.stderr) + data = json.loads(cp.stdout) + for component in ("jdk", "spring-boot", "spring-framework", "jakarta-ee"): + self.assertIn(component, data) + self.assertTrue(data[component]["preferredRuleId"], + f"{component} needs a ruleId") + + def test_list_solutions_ids_only(self): + for runner in self.for_each_runner(): + with self.subTest(interp=runner.name): + cp = runner.run("list-solutions", "--type", "Formula", "--ids-only") + self.assertEqual(cp.returncode, 0, cp.stderr) + ids = [line for line in cp.stdout.splitlines() if line.strip()] + self.assertGreater(len(ids), 0) + + def test_list_solutions_query_filters(self): + for runner in self.for_each_runner(): + with self.subTest(interp=runner.name): + cp = runner.run("list-solutions", "--query", "spring") + self.assertEqual(cp.returncode, 0, cp.stderr) + selected = json.loads(cp.stdout) + self.assertTrue(selected, "expected at least one 'spring' solution") + for sol in selected: + haystack = " ".join( + str(sol.get(k, "")) for k in ("solutionId", "name", "tooltip") + ).lower() + self.assertIn("spring", haystack) + + def test_list_solutions_no_match_is_empty_array(self): + for runner in self.for_each_runner(): + with self.subTest(interp=runner.name): + cp = runner.run("list-solutions", "--query", "zzz-no-such-solution") + self.assertEqual(cp.returncode, 0, cp.stderr) + self.assertEqual(json.loads(cp.stdout), []) + + def test_rules_for_known_solution(self): + for runner in self.for_each_runner(): + with self.subTest(interp=runner.name): + cp = runner.run("rules-for-solution", "spring-boot-upgrade") + self.assertEqual(cp.returncode, 0, cp.stderr) + data = json.loads(cp.stdout) + self.assertEqual(data["solutionId"], "spring-boot-upgrade") + self.assertGreater(data["ruleCount"], 0) + self.assertTrue(data["preferredRuleId"]) + self.assertEqual(data["rules"][0]["ruleId"], data["preferredRuleId"]) + + def test_rules_for_unknown_solution_is_empty(self): + for runner in self.for_each_runner(): + with self.subTest(interp=runner.name): + cp = runner.run("rules-for-solution", "does-not-exist") + self.assertEqual(cp.returncode, 0, cp.stderr) + data = json.loads(cp.stdout) + self.assertEqual(data["ruleCount"], 0) + self.assertEqual(data["rules"], []) + self.assertIsNone(data["preferredRuleId"]) + + +# --------------------------------------------------------------------------- # +# validate — structural + cross-field checks (one failure per test) +# --------------------------------------------------------------------------- # +class TestValidate(_MultiInterpreterCase): + def assertHasError(self, errors, needle): + self.assertTrue( + any(needle in e for e in errors), + f"expected an error containing {needle!r}; got: {errors}", + ) + + def _assert_invalid_with(self, mutate, needle): + for runner in self.for_each_runner(): + with self.subTest(interp=runner.name): + report = valid_report() + mutate(report) + rc, stdout, errors = _run_validate(runner, report) + self.assertEqual(rc, 1, stdout) + self.assertIn("RESULT: INVALID", stdout) + self.assertHasError(errors, needle) + + def test_valid_report_is_valid(self): + for runner in self.for_each_runner(): + with self.subTest(interp=runner.name): + rc, stdout, errors = _run_validate(runner, valid_report()) + self.assertEqual(rc, 0, stdout) + self.assertIn("RESULT: VALID", stdout) + self.assertEqual(errors, []) + + def test_report_must_be_object(self): + for runner in self.for_each_runner(): + with self.subTest(interp=runner.name): + rc, stdout, errors = _run_validate(runner, ["not", "an", "object"]) + self.assertEqual(rc, 1, stdout) + self.assertHasError(errors, "expected a JSON object") + + def test_missing_top_level_field(self): + self._assert_invalid_with(lambda r: r.pop("rules"), + 'missing required field "rules"') + + def test_invalid_metadata_status(self): + def m(r): + r["metadata"]["status"] = "done" + self._assert_invalid_with(m, "metadata.status") + + def test_invalid_metadata_mode(self): + def m(r): + r["metadata"]["mode"] = "partial" + self._assert_invalid_with(m, "metadata.mode") + + def test_invalid_domain_enum(self): + def m(r): + r["metadata"]["domains"] = ["performance"] + self._assert_invalid_with(m, "metadata.domains: invalid value") + + def test_rule_invalid_severity(self): + def m(r): + r["rules"]["spring-boot-upgrade"]["severity"] = "critical" + self._assert_invalid_with(m, "severity: invalid value") + + def test_rule_negative_effort(self): + def m(r): + r["rules"]["spring-boot-upgrade"]["effort"] = -1 + self._assert_invalid_with(m, "effort: must be an integer >= 0") + + def test_rule_invalid_domain(self): + def m(r): + r["rules"]["spring-boot-upgrade"]["domain"] = "networking" + self._assert_invalid_with(m, "domain: invalid value") + + def test_rule_missing_field(self): + def m(r): + del r["rules"]["spring-boot-upgrade"]["category"] + self._assert_invalid_with(m, 'missing required field "category"') + + def test_project_properties_missing_appname(self): + def m(r): + r["projects"][0]["properties"] = {} + self._assert_invalid_with(m, 'properties: missing required field "appName"') + + def test_incident_missing_field(self): + def m(r): + del r["projects"][0]["incidents"][0]["locationKind"] + self._assert_invalid_with(m, 'missing required field "locationKind"') + + def test_incident_ruleid_referential_integrity(self): + def m(r): + r["projects"][0]["incidents"][0]["ruleId"] = "ghost-rule" + self._assert_invalid_with(m, "has no matching entry in rules{}") + + def test_incident_line_below_one(self): + def m(r): + r["projects"][0]["incidents"][0]["line"] = 0 + self._assert_invalid_with(m, "line: must be an integer >= 1") + + def test_security_invalid_severity(self): + def m(r): + r["security"][0]["severity"] = "information" # not in the 3-value security scale + self._assert_invalid_with(m, "severity: invalid value") + + def test_security_duplicate_id(self): + def m(r): + r["security"].append(_clone(r["security"][0])) + self._assert_invalid_with(m, "is duplicated") + + def test_security_evidence_missing_field(self): + def m(r): + del r["security"][0]["evidence"]["explanation"] + self._assert_invalid_with(m, 'evidence: missing required field "explanation"') + + def test_domains_declares_security_but_none_present(self): + def m(r): + r["security"] = [] + self._assert_invalid_with(m, "report.security is empty") + + def test_security_present_but_domain_not_declared(self): + def m(r): + r["metadata"]["domains"] = ["java-upgrade"] + self._assert_invalid_with(m, 'does not include "security"') + + def test_missing_file_exit_two(self): + ghost = os.path.join(tempfile.gettempdir(), "no-such-report-xyz.json") + for runner in self.for_each_runner(): + with self.subTest(interp=runner.name): + cp = runner.run("validate", runner.path(ghost)) + self.assertEqual(cp.returncode, 2, cp.stdout + cp.stderr) + + def test_malformed_json_exit_two(self): + fd, path = tempfile.mkstemp(suffix=".json") + with os.fdopen(fd, "w", encoding="utf-8") as fh: + fh.write("{ not: valid json ") + try: + for runner in self.for_each_runner(): + with self.subTest(interp=runner.name): + cp = runner.run("validate", runner.path(path)) + self.assertEqual(cp.returncode, 2, cp.stdout + cp.stderr) + finally: + os.remove(path) + + +# --------------------------------------------------------------------------- # +# Schema-sync guard (behavioral): the scripts hard-code the schema's enums. If +# the schema drifts, these tests fail so both scripts are updated to match — the +# schema is the source of truth. We probe `validate` with a universe of tokens +# and assert the set the script *accepts* for each field equals the schema enum. +# --------------------------------------------------------------------------- # +class TestSchemaEnumSync(_MultiInterpreterCase): + @classmethod + def setUpClass(cls): + cls.schema = _load_schema() + cls.defs = cls.schema.get("definitions", {}) + cls.meta_props = cls.schema["properties"]["metadata"]["properties"] + + def _accepted(self, runner, universe, mutate, needle): + """Return the subset of `universe` the script does NOT flag with needle.""" + accepted = set() + for value in universe: + report = valid_report() + mutate(report, value) + _, _, errors = _run_validate(runner, report) + if not any(needle in e for e in errors): + accepted.add(value) + return accepted + + def test_rule_severity_enum_matches_schema(self): + schema_enum = set(self.defs["Severity"]["enum"]) + universe = schema_enum | {"critical", "high", "low", "info"} + for runner in self.for_each_runner(): + with self.subTest(interp=runner.name): + accepted = self._accepted( + runner, universe, + lambda r, v: r["rules"]["spring-boot-upgrade"].__setitem__("severity", v), + "rules[spring-boot-upgrade].severity: invalid value", + ) + self.assertEqual(accepted, schema_enum) + + def test_security_severity_enum_matches_schema(self): + schema_enum = set(self.defs["SecurityFinding"]["properties"]["severity"]["enum"]) + # "information" is valid for rules but NOT for security — a good discriminator. + universe = schema_enum | {"information", "critical", "high"} + for runner in self.for_each_runner(): + with self.subTest(interp=runner.name): + accepted = self._accepted( + runner, universe, + lambda r, v: r["security"][0].__setitem__("severity", v), + "security[0].severity: invalid value", + ) + self.assertEqual(accepted, schema_enum) + + def test_status_enum_matches_schema(self): + schema_enum = set(self.meta_props["status"]["enum"]) + universe = schema_enum | {"done", "open", "closed"} + for runner in self.for_each_runner(): + with self.subTest(interp=runner.name): + accepted = self._accepted( + runner, universe, + lambda r, v: r["metadata"].__setitem__("status", v), + "metadata.status: invalid value", + ) + self.assertEqual(accepted, schema_enum) + + def test_mode_enum_matches_schema(self): + schema_enum = set(self.meta_props["mode"]["enum"]) + universe = schema_enum | {"partial", "quick"} + for runner in self.for_each_runner(): + with self.subTest(interp=runner.name): + accepted = self._accepted( + runner, universe, + lambda r, v: r["metadata"].__setitem__("mode", v), + "metadata.mode: invalid value", + ) + self.assertEqual(accepted, schema_enum) + + def test_domain_enum_matches_schema(self): + schema_enum = set(self.meta_props["domains"]["items"]["enum"]) + # Rule.domain must share the same vocabulary. + self.assertEqual(set(self.defs["Rule"]["properties"]["domain"]["enum"]), schema_enum) + universe = schema_enum | {"performance", "networking"} + + def mutate(r, v): + r["metadata"]["domains"] = [v] + + for runner in self.for_each_runner(): + with self.subTest(interp=runner.name): + accepted = self._accepted( + runner, universe, mutate, + "metadata.domains: invalid value", + ) + self.assertEqual(accepted, schema_enum) + + +# --------------------------------------------------------------------------- # +# Cross-interpreter parity: bash and pwsh must report identical validate errors. +# --------------------------------------------------------------------------- # +@unittest.skipUnless(len(RUNNERS) >= 2, "need both bash and pwsh for parity check") +class TestInterpreterParity(unittest.TestCase): + def _errors(self, runner, report): + _, _, errors = _run_validate(runner, report) + return errors + + def test_valid_report_identical(self): + report = valid_report() + base = self._errors(RUNNERS[0], report) + for other in RUNNERS[1:]: + self.assertEqual(self._errors(other, report), base) + + def test_multi_error_report_identical(self): + report = valid_report() + report["metadata"]["status"] = "done" # status enum + report["rules"]["spring-boot-upgrade"]["severity"] = "critical" # rule severity + report["projects"][0]["incidents"][0]["ruleId"] = "ghost-rule" # dangling ref + report["security"][0]["severity"] = "information" # security severity + base = self._errors(RUNNERS[0], report) + self.assertTrue(base) + for other in RUNNERS[1:]: + self.assertEqual(set(self._errors(other, report)), set(base)) + + def test_missing_field_plus_invalid_value_identical(self): + # An object that is BOTH missing a required field AND carries an invalid + # value must report both errors on every interpreter. This exercises the + # path where a naive validator could short-circuit after the missing-field + # error and skip the value checks (bash concatenates; pwsh must too). + report = valid_report() + + rule = report["rules"]["spring-boot-upgrade"] + del rule["category"] # missing required field + rule["domain"] = "networking" # + invalid enum on the same object + + finding = report["security"][0] + del finding["title"] # missing required field + finding["severity"] = "critical" # + invalid enum on the same object + del finding["evidence"] # missing object whose sub-fields must still be reported + + base = self._errors(RUNNERS[0], report) + # Every interpreter must surface the missing-field AND the value errors. + self.assertIn('rules[spring-boot-upgrade]: missing required field "category"', base) + self.assertTrue(any("rules[spring-boot-upgrade].domain: invalid value" in e for e in base)) + self.assertIn('security[0]: missing required field "title"', base) + self.assertTrue(any("security[0].severity: invalid value" in e for e in base)) + self.assertIn('security[0]: missing required field "evidence"', base) + self.assertTrue(any("security[0].evidence: missing required field" in e for e in base)) + for other in RUNNERS[1:]: + self.assertEqual(set(self._errors(other, report)), set(base)) + + +if __name__ == "__main__": + unittest.main(verbosity=2) diff --git a/plugins/github-copilot-modernization/skills/business-workflows/SKILL.md b/plugins/github-copilot-modernization/skills/business-workflows/SKILL.md index 9a4b01e..2458426 100644 --- a/plugins/github-copilot-modernization/skills/business-workflows/SKILL.md +++ b/plugins/github-copilot-modernization/skills/business-workflows/SKILL.md @@ -11,6 +11,44 @@ Analyze the project to document business processes end-to-end, domain entities, - `workspace-path` (optional): Path to the project to analyze (defaults to current directory) +## ⚠ Mermaid Safety Constraints — read BEFORE you write the ```mermaid block + +Mermaid sequenceDiagram is unforgiving in a few specific ways: one bad alias or one missing `end` crashes the **whole** diagram with `Syntax error in text`, not just the offending line. Stay strictly inside this subset for the sequence diagram: + +1. **Chart kind.** `sequenceDiagram` only. Never `sequence-diagram`, never `sequence`. +2. **Participants.** Always declare with the alias form `participant as "Display Label"`. The id must match `[A-Za-z][A-Za-z0-9_]*`. Never omit the id — even a one-word participant should be `participant Owner as "Owner"`. This is the single biggest cause of past failures. +3. **Arrows.** + - `->>` synchronous request + - `-->>` synchronous response + - `-)` async fire-and-forget + - Message text goes after `:` and is plain text — keep it short and on one line. +4. **Blocks.** `alt` / `else` / `opt` / `loop` / `par` / `critical` MUST be closed by `end` on its own line. Every open block must have a matching `end`. Missing `end` is the #2 cause of past failures. +5. **No line breaks anywhere.** The escape `\n` was removed in modern Mermaid. Aliases, message text, and `Note over` content must all be single-line. Split a long note into multiple consecutive `Note over` lines; split a long message into multiple arrows. This is the #1 cause of past failures. +6. **Banned characters inside participant aliases specifically** (message text is more permissive — only `\n` is banned there): + + | Banned in alias | Why it breaks | Replacement | + |---|---|---| + | `\n` (literal two chars) | escape removed | drop | + | `"` (a second double-quote) | closes the alias early | `'` (single quote) | + | `` ` `` (backtick) | breaks alias quoting | drop | + | smart quotes `"` `"` `'` `'` | not ASCII | regular `"` and `'` | + | `:` | confuses with message delimiter | rephrase, e.g. `"Order Service (v2)"` not `"Order Service: v2"` | + | `
` | not interpreted inside aliases | rephrase as shorter alias | + +7. **Quote the alias.** `participant Svc as "Order Service"` — never `participant Svc as Order Service` (unquoted multi-word aliases break). + +### Mandatory self-attestation + +Immediately before writing the ` ```mermaid ` opening fence, emit this exact one-line HTML comment in the markdown (it does not render — it is for your own visible attestation): + +``` + +``` + +If you cannot truthfully emit that comment, fix the diagram first. + +--- + ## Scope Boundaries — Avoid Redundancy with Other Skills This skill is part of a set of four complementary assessment skills. To avoid content duplication across their output documents, observe these scope rules: @@ -78,11 +116,12 @@ Create a **Mermaid `sequenceDiagram`** showing the primary business workflow end - Use `alt`/`else` blocks to show circuit breaker fallback paths that affect business outcomes - Show cross-service data aggregation flows -Example: +Reference example (this block satisfies every Safety Constraint — match its shape): + ~~~mermaid sequenceDiagram - participant Owner + participant Owner as "Owner" participant Gateway as "API Gateway" participant CustSvc as "Customer Service" participant VisitSvc as "Visit Service" @@ -172,35 +211,23 @@ A brief introduction (1-2 sentences) summarizing the application's business doma - For multi-module projects, focus on the primary end-to-end business workflow that spans modules - Aggregate minor CRUD operations and show only workflows that involve business logic beyond simple create/read/update/delete -## Mermaid Syntax Rules - -The diagram must parse cleanly under **Mermaid >= 9.x**. Anything outside the legal subset crashes the entire diagram with `Syntax error in text`. - -- Use `sequenceDiagram` -- Avoid special characters (`@`, `#`, `$`, `%`, `&`) in participant labels — use plain text or quoted labels -- Use `->>` for synchronous calls and `-->>` for responses -- Use `participant` with alias syntax for readable labels: `participant Svc as "OrderService"` -- Use `Note over` for annotations about business decisions or fallback behavior -- Use `alt`/`else`/`end` blocks for decision points and circuit breaker fallbacks -- Do not use backticks inside participant labels - -### Line breaks — HARD RULE - -- **NEVER use `\n` for line breaks inside participant aliases, messages, or notes.** The literal `\n` escape was removed in modern Mermaid and triggers "Syntax error in text". -- Keep aliases on a single line: `participant Tx as "Transcoding Service"` — not `"Transcoding\nService"`. -- For multi-fact notes, emit multiple `Note over` statements instead of `\n`-separated text. -- ❌ `Note over Client,API: First fact\nSecond fact` -- ✅ Two consecutive `Note over Client,API: ...` lines. +## Common failure patterns observed in past runs -### Self-check before emitting each ```mermaid block +Each row below is something the model actually produced that crashed the diagram. Use the ✅ form. -1. Search the block for the two characters `\n` — remove or split. Zero `\n` must remain. -2. Confirm every `alt`/`opt`/`loop`/`par` block is closed by `end`. +| ❌ Past mistake | ✅ Safe form | Why the ❌ crashed | +|---|---|---| +| `participant Owner` (no alias) | `participant Owner as "Owner"` | Bare participants can break when used later with spaces | +| `participant Tx as "Transcoding\nService"` | `participant Tx as "Transcoding Service"` | Literal `\n` in alias | +| `participant API as "REST API: v2"` | `participant API as "REST API (v2)"` | `:` in alias collides with message delimiter | +| `Note over Client,API: First fact\nSecond fact` | Two consecutive `Note over Client,API: ...` lines | `\n` in note text | +| `alt happy path` ... missing `end` | `alt happy path` ... `end` | Unclosed block | +| `participant Svc as Order Service` (unquoted) | `participant Svc as "Order Service"` | Multi-word alias must be quoted | ## Error Handling - **Unsupported project type**: Output a single line: `> ERROR: Unsupported project type. This skill supports Java, .NET, JavaScript, and TypeScript projects only.` -- **No business logic found**: Output: `> ERROR: No recognized business logic or workflows found at {workspace-path}. The project may be a library or framework without business processes.` +- **No business logic found**: Output: `> ERROR: No recognized business logic or workflows found at workspace-path. The project may be a library or framework without business processes.` - **Insufficient info**: Generate a best-effort document from available data. Add a note: `> Note: Some workflows or business rules could not be fully traced.` ## Success Criteria @@ -211,4 +238,5 @@ The diagram must parse cleanly under **Mermaid >= 9.x**. Anything outside the le - Cross-service data flows describe aggregation/composition patterns with fallback behavior - Mermaid sequence diagram renders correctly showing end-to-end business workflow with `alt`/`else` blocks for fallbacks - Business rules section summarizes validation, decision logic, state transitions, and constraints +- The ```mermaid block is preceded by the `` attestation comment - File saved to `.github/modernize/assessment/engines/facts/business-workflows.md` diff --git a/plugins/github-copilot-modernization/skills/create-modernization-plan/SKILL.md b/plugins/github-copilot-modernization/skills/create-modernization-plan/SKILL.md index 5b33d17..0c92d02 100644 --- a/plugins/github-copilot-modernization/skills/create-modernization-plan/SKILL.md +++ b/plugins/github-copilot-modernization/skills/create-modernization-plan/SKILL.md @@ -52,7 +52,7 @@ Given the user input, do this: 1) Follow the structure of the selected template to generate the plan 2) Follow the rules defined in the template to fill in the sections with relevant information based on the analysis of user input and content of mentioned files 3) Save the plan in folder ${modernization-work-folder} with the filename plan.md. If a plan already exists, overwrite it. - 4) Generate a separate tasks.json file following the tasks-schema.json schema with setupBaseline, infrastructure, upgrade, transform, containerization, and deployment tasks + 4) Generate a separate tasks.json file following the tasks-schema.json schema with setupBaseline, infrastructure, upgrade, transform, integration test, containerization, and deployment tasks 5) Save the tasks in folder ${modernization-work-folder}/.metadata/ with the filename tasks.json. If tasks.json already exists, overwrite it. **Clarification Outcomes in Plan**: Incorporate all clarification answers from steps 3–4 into `plan.md` and `tasks.json`: @@ -77,10 +77,28 @@ Given the user input, do this: - You MUST NOT use the pattern name as the skill name in the generated plan and tasks.json. - If there are similar skills defined in project skill `.github/skills/` versus other skills, MUST use the one defined in project. - Skills must be fully matched. For migration scenarios, both the source product and target product must match the task intent. - - Each task should be independently testable + - Each task should be independently testable with integration tests - Do not add tests for unimpacted code or existing functionality unless user requested - **IMPORTANT**: Do NOT read individual skill files at this stage; Do Not include the skill detail in the tasks. + **Integration Test Task Rules**: Add an integration test task when EITHER of these conditions is met: + 1. The user explicitly requests integration testing (e.g., "add integration tests", "generate integration tests", "test the migration") + 2. The user answers the Integration Testing questionnaire question with any option OTHER than "No — skip integration testing entirely" (including when a default option is inferred because an environment is provided/provisioned) + + When an integration test task is included: + - Add an integration test task with type "integrationTest" after all transform/upgrade tasks but before containerization tasks + - This integration test task should: + - Have id format: "{sequence}-integrationTest" where sequence is the next number after the last migration task (e.g., if last migration is 001, use "002-integrationTest") + - Have description: "Build integration tests for migrated Azure services and run post-migration verification" + - Have dependencies on ALL of: setupBaseline task ID, infrastructure task ID (if present), and ALL transform/upgrade task IDs. The integrationTest task is the convergence point that waits for all parallel work to complete. + - Do NOT store resource IDs, subscription IDs, or connection strings in the task plan. If user provides infra info (resource ID, subscription ID, connection strings), record it in `./infra/infra-config.md`. + + **Baseline Task Rules**: A setupBaseline task is **mandatory whenever an integrationTest task is included** in the plan. + - **Parallel execution**: The setupBaseline task and infrastructure task run in **parallel** with no dependencies between them. The setupBaseline task snapshots the source folder and operates on the snapshot, so it is not affected by concurrent code changes or infra provisioning. Set `snapshotFolder` to the project's main source directory (relative to project root). + - **Transform/upgrade tasks run sequentially**: Upgrade and transform tasks MUST be chained with dependencies (each depends on the previous one) to avoid file conflicts from concurrent code modifications. However, they run in parallel with setupBaseline and infrastructure since they modify different concerns. + - **Dependencies**: The setupBaseline task should have NO dependencies (empty `dependencies` array or omit it). Upgrade/transform tasks depend on the previous upgrade/transform task in sequence. Only the `integrationTest` verification task depends on ALL of: setupBaseline, infrastructure (if present), and all transform/upgrade tasks completing. + - **Purpose**: setupBaseline produces the frozen test specification (test-cases, testdata) and the **infra-decision-table** — the real/mock strategy for every external dependency used by integration tests. This decision is frozen into the baseline bundle and reused as-is by the verification phase. + **Java Upgrade Task Guidelines**: Only add an upgrade task if the user explicitly requests it. You must refer to the ./java-upgrade-guideline.md for specific rules and guidelines when creating Java upgrade tasks. **.NET Upgrade Task Guidelines**: You must refer to the ./dotnet-upgrade-guideline.md for specific rules and guidelines when creating .NET upgrade tasks. diff --git a/plugins/github-copilot-modernization/skills/create-modernization-plan/questionnaire.md b/plugins/github-copilot-modernization/skills/create-modernization-plan/questionnaire.md index 8a87b16..042ac16 100644 --- a/plugins/github-copilot-modernization/skills/create-modernization-plan/questionnaire.md +++ b/plugins/github-copilot-modernization/skills/create-modernization-plan/questionnaire.md @@ -11,6 +11,33 @@ Should the plan include environment/infrastructure provisioning? * Yes — provision new infrastructure * Custom — use an existing externally managed environment specified by the user instead of provisioning or repo-defined configuration (ask for resource group, subscription, environment name, or config path) +## Integration Testing + +Should the plan include integration testing to verify migrated services? + +- (Default when infrastructure is provided/provisioned) Yes — Real mode: use provisioned infrastructure from `infra/` or user-provided environment +- (Default when no infrastructure is provided) Yes — Mock mode: use mocked dependencies +- Yes — TestContainer mode: use containerized emulators/dependencies for supported services and mock unsupported dependencies +- Yes — Mixed mode: user-specified per dependency (ask for dependency list and mode per dependency) +- No — skip integration testing entirely + +### Integration Test Resource Info (only ask when Real mode is selected AND user chose to use existing infrastructure) + +If the user selected Real mode testing with an existing environment (i.e., "Custom" environment in the Environment Setup section above), ask for one of the following resource information: + +* Azure Resource ID — the full Azure resource ID (e.g., `/subscriptions/{sub-id}/resourceGroups/{rg}/providers/...`) for the target resource(s) the tests will run against +* Subscription ID and Resource Group — the resource group containing the test infrastructure + +Record these in `./infra/infra-config.md`. + +### Subscription ID for Provisioning (only ask when user chose to provision new test infrastructure) + +If the user selected "Yes" in the Environment Setup section (provision new infrastructure), ask: + +* Azure Subscription ID — the subscription where test infrastructure should be provisioned + +Record this in the infrastructure task's `environmentConfiguration` field. The InfrastructureExpert agent will use it during provisioning and persist the resulting resource info to its private user profile. + ## Security & CVE Remediation Should the plan include a security scan and CVE remediation task? This task runs after all upgrade and transform tasks and before deployment to identify and fix known vulnerabilities. diff --git a/plugins/github-copilot-modernization/skills/create-modernization-plan/summary-schema.json b/plugins/github-copilot-modernization/skills/create-modernization-plan/summary-schema.json new file mode 100644 index 0000000..edd0880 --- /dev/null +++ b/plugins/github-copilot-modernization/skills/create-modernization-plan/summary-schema.json @@ -0,0 +1,136 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Run Summary", + "description": "Schema for .metadata/summary.json — the post-run goal-status document produced by the team while finalizing tasks. Each entry corresponds to one task in tasks.json (joined by 'id'). The CLI reads this file to render the post-run summary tables (per-task goal/result, overall application status, reference documents).", + "type": "object", + "additionalProperties": false, + "required": ["version", "taskSummaries"], + "properties": { + "$schema": { "type": "string", "description": "Optional schema URI." }, + "version": { "type": "string", "description": "Schema version. Use \"1.0\"." }, + "taskSummaries": { + "type": "array", + "description": "One entry per task in tasks.json that has reached a terminal state. Joined to tasks.json by 'id'.", + "items": { "$ref": "#/$defs/runSummaryEntry" } + } + }, + "$defs": { + "runSummaryEntry": { + "type": "object", + "additionalProperties": false, + "required": ["id", "type", "goalStatus"], + "description": "A per-task goal-status entry. The shape of 'goalStatus' is selected by 'type'.", + "properties": { + "id": { "type": "string", "description": "Task id matching the corresponding task in tasks.json." }, + "type": { + "type": "string", + "enum": ["setupBaseline", "upgrade", "transform", "security", "integrationTest", "infrastructure", "containerization", "deployment"], + "description": "Task type discriminator matching the corresponding task type in tasks.json." + }, + "goalStatus": { + "description": "Structured goal status object. Use the per-type shape selected by 'type' from the matching $defs entry below." + }, + "risks": { + "type": "array", + "maxItems": 3, + "items": { "type": "string", "maxLength": 200 }, + "description": "Up to 3 short, concrete residual risks introduced or left behind by this task (e.g., 'Spring upgrade still uses deprecated WebSecurityConfigurerAdapter'). Omit or use [] when there are none. Do not invent risks to fill space; do not include generic platitudes." + }, + "followUps": { + "type": "array", + "maxItems": 3, + "items": { "type": "string", "maxLength": 200 }, + "description": "Up to 3 short, actionable items the user/team should do next (e.g., 'Pin docker base image digest', 'Add IT coverage for OAuth refresh path'). Omit or use [] when there are none." + } + }, + "allOf": [ + { "if": { "properties": { "type": { "const": "setupBaseline" } } }, "then": { "properties": { "goalStatus": { "$ref": "#/$defs/setupBaselineGoalStatus" } } } }, + { "if": { "properties": { "type": { "const": "upgrade" } } }, "then": { "properties": { "goalStatus": { "$ref": "#/$defs/upgradeGoalStatus" } } } }, + { "if": { "properties": { "type": { "const": "transform" } } }, "then": { "properties": { "goalStatus": { "$ref": "#/$defs/transformGoalStatus" } } } }, + { "if": { "properties": { "type": { "const": "security" } } }, "then": { "properties": { "goalStatus": { "$ref": "#/$defs/securityGoalStatus" } } } }, + { "if": { "properties": { "type": { "const": "integrationTest" } } }, "then": { "properties": { "goalStatus": { "$ref": "#/$defs/integrationTestGoalStatus" } } } }, + { "if": { "properties": { "type": { "const": "infrastructure" } } }, "then": { "properties": { "goalStatus": { "$ref": "#/$defs/infrastructureGoalStatus" } } } }, + { "if": { "properties": { "type": { "const": "containerization" } } }, "then": { "properties": { "goalStatus": { "$ref": "#/$defs/containerizationGoalStatus" } } } }, + { "if": { "properties": { "type": { "const": "deployment" } } }, "then": { "properties": { "goalStatus": { "$ref": "#/$defs/deploymentGoalStatus" } } } } + ] + }, + "setupBaselineGoalStatus": { + "type": "object", + "additionalProperties": false, + "description": "Goal status for a setupBaseline task. Populate when the task reaches a terminal state so the post-run summary can render concrete counts and link to the produced test-cases.md.", + "properties": { + "totalTestCases": { "type": "integer", "description": "Total number of test cases captured in the baseline spec." }, + "passed": { "type": "integer", "description": "Number of baseline test cases that passed at the end of the run." }, + "failed": { "type": "integer", "description": "Number of baseline test cases that failed at the end of the run." }, + "allCasesPassed": { "type": "boolean", "description": "Convenience boolean: whether all captured test cases passed at the end of the run. Equivalent to failed == 0 when passed/failed are both populated." }, + "testCasesFile": { "type": "string", "description": "Workspace-relative path to the produced test-cases.md file, forward-slash separated (e.g., 'src/test/test-cases/test-cases.md')." } + } + }, + "upgradeGoalStatus": { + "type": "object", + "additionalProperties": false, + "description": "Goal status for an upgrade task. Populate when the task reaches a terminal state.", + "properties": { + "fromVersion": { "type": "string", "description": "Source version observed before the upgrade, e.g., 'Java 8', '.NET 6'." }, + "targetVersion": { "type": "string", "description": "Target version reached, e.g., 'Java 17', '.NET 8'." } + } + }, + "transformGoalStatus": { + "type": "object", + "additionalProperties": false, + "description": "Goal status for a transform task. Populate when the task reaches a terminal state.", + "properties": { + "migrationFrom": { "type": "string", "description": "Source component being replaced, e.g., 'RabbitMQ', 'AWS S3'." }, + "migrationTo": { "type": "string", "description": "Azure destination component, e.g., 'Azure Service Bus', 'Azure Blob Storage'." } + } + }, + "securityGoalStatus": { + "type": "object", + "additionalProperties": false, + "description": "Goal status for a security task. Populate when the task reaches a terminal state.", + "properties": { + "cvesFixed": { "type": "integer", "description": "Number of CVEs fixed during this task." }, + "cvesRemaining": { "type": "integer", "description": "Number of CVEs that remain unfixed after this task." } + } + }, + "integrationTestGoalStatus": { + "type": "object", + "additionalProperties": false, + "description": "Goal status for an integrationTest task. Populate when the task reaches a terminal state.", + "properties": { + "totalTestCases": { "type": "integer", "description": "Total number of integration test cases executed." }, + "passed": { "type": "integer", "description": "Number of integration test cases that passed." }, + "failed": { "type": "integer", "description": "Number of integration test cases that failed." }, + "testCasesFile": { "type": "string", "description": "Workspace-relative path to the consumed test-cases.md file, forward-slash separated." } + } + }, + "infrastructureGoalStatus": { + "type": "object", + "additionalProperties": false, + "description": "Goal status for an infrastructure task. Populate when the task reaches a terminal state.", + "properties": { + "provisioned": { "type": "boolean", "description": "Whether Azure resources were successfully provisioned." }, + "resourceGroup": { "type": "string", "description": "Name of the Azure resource group used for provisioning." } + } + }, + "containerizationGoalStatus": { + "type": "object", + "additionalProperties": false, + "description": "Goal status for a containerization task. Populate when the task reaches a terminal state.", + "properties": { + "imageBuilt": { "type": "boolean", "description": "Whether the container image was successfully built." }, + "imageTag": { "type": "string", "description": "Built container image tag, e.g., 'myapp:1.0.0'." } + } + }, + "deploymentGoalStatus": { + "type": "object", + "additionalProperties": false, + "description": "Goal status for a deployment task. Populate when the task reaches a terminal state.", + "properties": { + "deployed": { "type": "boolean", "description": "Whether the application was successfully deployed to the target Azure service." }, + "resourceGroup": { "type": "string", "description": "Name of the Azure resource group the application was deployed into." }, + "accessUrl": { "type": "string", "description": "Public URL or endpoint the user can use to access the deployed application." } + } + } + } +} diff --git a/plugins/github-copilot-modernization/skills/create-modernization-plan/tasks-schema.json b/plugins/github-copilot-modernization/skills/create-modernization-plan/tasks-schema.json index ad2c378..2ed3b4c 100644 --- a/plugins/github-copilot-modernization/skills/create-modernization-plan/tasks-schema.json +++ b/plugins/github-copilot-modernization/skills/create-modernization-plan/tasks-schema.json @@ -21,10 +21,12 @@ "oneOf": [ { "$ref": "#/$defs/transformTask" }, { "$ref": "#/$defs/upgradeTask" }, + { "$ref": "#/$defs/integrationTestTask" }, { "$ref": "#/$defs/containerizationTask" }, { "$ref": "#/$defs/deploymentTask" }, { "$ref": "#/$defs/securityTask" }, - { "$ref": "#/$defs/infrastructureTask" } + { "$ref": "#/$defs/infrastructureTask" }, + { "$ref": "#/$defs/setupBaselineTask" } ] } }, @@ -267,6 +269,22 @@ } ] }, + "integrationTestTask": { + "allOf": [ + { "$ref": "#/$defs/taskBase" }, + { + "type": "object", + "additionalProperties": false, + "required": ["type"], + "properties": { + "type": { + "const": "integrationTest", + "description": "Integration test task template - Generate and run integration tests for migrated Azure services. Only include when user explicitly requests integration testing. This task runs after all transform/upgrade tasks but before containerization." + } + } + } + ] + }, "securityTask": { "allOf": [ { "$ref": "#/$defs/taskBase" }, @@ -318,6 +336,28 @@ } } ] + }, + "setupBaselineTask": { + "allOf": [ + { "$ref": "#/$defs/taskBase" }, + { + "type": "object", + "additionalProperties": false, + "required": ["type"], + "properties": { + "type": { + "const": "setupBaseline", + "description": "Setup baseline task template - Establish the modernization baseline by capturing the current state of the application before any changes are made." + }, + "snapshotFolder": { + "type": "string", + "description": "Project source folder to snapshot before baseline analysis, relative to the project root." + }, + "successCriteria": { "$ref": "#/$defs/successCriteria" }, + "successCriteriaStatus": { "$ref": "#/$defs/successCriteriaStatus" } + } + } + ] } } } diff --git a/plugins/github-copilot-modernization/skills/create-test-baseline/SKILL.md b/plugins/github-copilot-modernization/skills/create-test-baseline/SKILL.md new file mode 100644 index 0000000..087f04c --- /dev/null +++ b/plugins/github-copilot-modernization/skills/create-test-baseline/SKILL.md @@ -0,0 +1,176 @@ +--- +name: create-test-baseline +description: Create a test baseline for the project to be modernized. The baseline will be used for later verification of modernization tasks. +--- + +# Goal + +Produce a precise, executable-quality **specification** of the application's externally observable behavior that must be preserved across migration. The output is `test-cases/test-cases.md` plus the `test-cases/testdata/` fixtures it references — **no test code is generated in this phase**. The `verify-test-baseline` skill consumes this spec to generate `*PostMigrationIT` tests against the new implementation. + +## User Input + +- **migration-scope**: The scope of the migration, e.g. "migrate from AWS S3 to Azure Blob Storage", "upgrade from Java 8 to Java 11" etc. +- **taskid**: Identifier for this baseline run, used to namespace the summary report. +- **modernization-work-folder**: Folder under which the summary report is written. + +## Principles + +- The spec describes behavior at **external boundaries only** — HTTP endpoints, CLI commands, public API surfaces, published/consumed events, message queues, scheduled tasks, webhooks. No service-specific SDK types, no backend implementation details. +- The spec must be **precise enough to be transformed into test code mechanically**. Vague phrases ("should return a reasonable error", "behaves as expected") are defects, not descriptions. +- All payload data is **externalized** under `test-cases/testdata/` as files. The spec references them by path (relative to `test-cases/`). No inline byte literals, no hand-built JSON strings in the spec. +- `test-cases/test-cases.md` and `test-cases/testdata/` are **FROZEN** after this skill completes — never modified, renamed, moved, or deleted by subsequent phases. +- **No `*BaselineIT` test code is produced.** The migration uses a replace strategy: any code that exercises the old implementation would either import old SDKs (which get deleted) or substitute internal services for the real entry point (which defeats the purpose). All executable tests are produced in the verify phase against the new implementation. +- **The module is the test-case boundary.** In a multi-module project, each module that is in scope produces its own independent `test-cases.md` under that module's test source root. A module's `test-cases.md` MUST contain only test cases whose entry points belong to that module. Never place test cases for one module inside another module's `test-cases.md` (e.g. API-gateway module test cases must not appear in a backend-services module's spec). +- **Skip modules with no migration-relevant resource access.** If a module's code does not directly interact with any resource being migrated (e.g. it never calls Azure/AWS/GCP SDKs, never accesses a database or message broker that is part of the migration scope), do not create `test-cases/` for that module. A module that only serves as a thin HTTP frontend delegating to another module's backend services — without touching any migrated resource itself — does not need test cases. +- **Mock cross-module and non-migration-related dependencies.** When a module's entry point calls a service provided by another module (e.g. a shared service in a sibling module) or an external service unrelated to the migration scope, mark that dependency as **mock** in the infra decision table. The `verify-test-baseline` skill handles the actual mock implementation. +- **Respect existing integration tests.** Scan for existing IT / integration / E2E tests before writing new test cases. Do not duplicate coverage they already provide — reference them and fill gaps only. New test cases MUST follow the same conventions (naming, framework, assertions, fixtures, helpers) observed in existing tests. + +## Output Layout + +Frozen baseline artifacts live under a dedicated `test-cases/` subdirectory of the project's **test source root** — the standard directory the build tool already uses for tests (e.g. `src/test/` for Maven/Gradle Java modules, `tests/` for Python / Node / Go projects, `/test/` for multi-module repos). In a multi-module repo, place artifacts under each module's own test source root. Do NOT invent a new top-level folder. + +The per-run summary report lives under the modernization work folder, not the test source root. + +``` +/ +└── test-cases/ # FROZEN — entire folder is the baseline spec bundle + ├── test-cases.md # FROZEN — the full behavioral spec + ├── infra-decision-table.md # FROZEN — mock/real/testcontainer decision per external dependency (Step 2) + └── testdata/ # FROZEN — fixtures referenced by test-cases.md + ├── inputs/ # raw input files (images, JSON payloads, CSV, etc.) + ├── expectations/ # golden outputs at the application boundary + └── ... # other data as needed (configuration, seed data, etc.) + +${modernization-work-folder}/${taskid}/ +└── baseline-summary.md # NEW — per-run summary (Step 6) +``` + +All paths inside `test-cases.md` (e.g. `testdata/inputs/sample.jpg`) are interpreted **relative to `/test-cases/`**, the folder that contains `test-cases.md`. + +## Workflow + +### Step 1: Inventory External Boundaries and Orchestration Entry Points + +Scan the production source for everything that constitutes an external boundary or orchestration entry point. Record each one with file path, symbol, and **owning module** so it can be cross-checked in Step 2. + +**What qualifies as an entry point** (principle, not a closed list): + +An entry point is any code location invoked by something **outside the application's own call graph** — the network, the OS, the runtime scheduler, a message broker, an external SDK consumer, etc. If the application does not call it itself, it is an entry point. + +Typical examples (use as hints, not as an exhaustive checklist — apply the principle above to whatever the codebase actually uses): + +- Network-facing handlers (HTTP / REST / gRPC / GraphQL controllers, routers, webhook receivers) +- Process-level entries (CLI commands, `main` methods, background workers) +- Runtime-invoked callbacks (scheduled / cron jobs, framework-triggered lifecycle hooks) +- Broker-driven consumers (message-queue listeners, streaming / pub-sub subscribers) +- Container-invoked enterprise bean entry points (EJB remote/local business methods, message-driven beans) +- Published library / SDK methods — public methods that are never called from within the same module (i.e. only invoked by external consumers) + +Every orchestration entry point in the migration scope MUST be covered by at least one **end-to-end** test case that triggers it with realistic input and verifies the final observable outcome. Test cases that exercise only helpers called *within* an entry point do NOT count toward this requirement. + +**Multi-module scoping:** Group entry points by owning module. For each module, determine whether it directly accesses any resource being migrated (databases, message brokers, cloud storage, caches, etc. that are in the migration scope). Modules whose code never directly interacts with a migration-relevant resource are **out of scope** — do not produce test cases for them. Record the per-module decision (in-scope / out-of-scope with reason) so it is auditable in the baseline summary. + +### Step 2: Inventory Existing Integration Tests + +Scan the project's test source roots for existing IT / integration / E2E tests. Map each existing test to the entry points inventoried in Step 1 and note which coverage categories (happy-path, boundary, special-input, failure) it covers. + +Also extract the project's testing conventions: naming patterns, test framework and assertion style, fixture/test-data organization, helper utilities, and infrastructure setup (Testcontainers, embedded servers, mocks, etc.). These conventions are binding — the `verify-test-baseline` skill MUST follow them when generating test code. + +Include the existing test inventory and extracted conventions in the baseline summary (Step 7). + +### Step 3: Write `test-cases.md` + +For each **in-scope module** (as determined in Step 1), produce `/test-cases/test-cases.md` using [test-cases-template.md](test-cases-template.md). Each module gets its own independent spec file containing only test cases for entry points that belong to that module. + +**Existing test alignment rules:** +- If an existing test already covers an entry point + category, mark it as `covered-by-existing` in the spec with the test's fully qualified name. Do NOT duplicate it. +- New test cases fill coverage gaps only and MUST follow the conventions extracted in Step 2. + +**Module isolation rules:** +- A module's `test-cases.md` MUST NOT contain test cases for entry points defined in other modules. +- When an entry point in module A calls a service in module B, note the cross-module dependency in the test case's `Preconditions` field (e.g. "Service B returns X"). The infra decision table marks it as **mock**; the `verify-test-baseline` skill handles the actual mock implementation. +- External services unrelated to the migration scope (third-party APIs, internal microservices outside the project) are noted as dependencies and marked **mock** in the infra decision table. + +For each entry point, cover the **four coverage buckets**: + +1. **Happy path** — typical valid input, normal outcome. +2. **Boundary values** — empty, max-size, page boundaries, off-by-one cases. +3. **Special inputs** — unicode, reserved characters, missing referenced resources, idempotency keys. +4. **Failure mapping** — simulated backend / dependency failure → application-level response. + +Use **2–5 representative records per entity** (table row, queue message, container object, etc.). + +**Every test case MUST have all required fields populated** — see "Required field checklist" below. Missing or vague fields make the spec unverifiable and must be filled in before freezing. + +### Step 4: Externalize Test Data + +For every payload referenced in `test-cases.md`, create a file under `/test-cases/testdata/` and reference it from the spec as `testdata/...` (i.e. relative to `/test-cases/`). + +**Requirements:** +- Organize by purpose: `inputs/`, `expectations/`, `configuration/`, `seed-data/`. +- If existing tests already use fixture files, prefer reusing them or following the same directory structure and naming conventions. Copy or reference existing fixtures under `testdata/` rather than inventing a parallel layout. +- No inline byte literals, hardcoded keys, or hand-built JSON strings in `test-cases.md`. Every `Input` and `Expected Output` block either references a file or contains a small structured value (status code, exit code, scalar string) that does not warrant a file. +- File names should be descriptive and stable: `sample.jpg`, `upload-request.json`, `error-not-found.json`. + +### Step 5: Build Infra Decision Table (mock vs real vs testcontainer) + +With the full set of test cases and their referenced dependencies now visible, decide which external dependencies the post-migration tests will exercise as **real** resources, **testcontainer** resources, or **mock** at the SDK / HTTP boundary. This decision is recorded once here and is reused as-is by `verify-test-baseline` — verification does not re-decide. + +**Inputs:** +- The exhaustive list of external dependencies actually touched by the test cases written in Step 3 (cross-checked against the entry-point inventory from Step 1). +- The mock/real/testcontainer decisions already made by existing tests (from Step 2). Prefer consistency with existing tests unless there is a clear reason to diverge. +- The repo-root `infra/` directory (`*.md`, `*.yml`, `*.yaml`) **if it exists**. If the user has scheduled an infrastructure-provisioning task before baseline setup, run it first so that `infra/` reflects the resources that will actually be available at verification time. + +**Mandatory user confirmation before drafting rows:** +- Confirm the integration-test environment mode with the user: `real`, `mock`, `testcontainer`, or `mixed` (per dependency). Reuse the answer from the planning questionnaire when available; if missing and an interactive question tool is available, ask explicitly before generating the table. + +**Rules:** +- If the confirmed mode is `mock`: mark every dependency **mock** regardless of `infra/` presence. +- If the confirmed mode is `real`: dependency present in `infra/` (provisioned endpoint + credentials) → **real**. +- If the confirmed mode is `real` and a dependency is not present in `infra/`, mark it **mock** at the SDK / HTTP boundary and record that it is not provisioned. +- If the confirmed mode is `testcontainer`: dependency with a supported emulator/containerized dependency strategy → **testcontainer**. +- If the confirmed mode is `testcontainer` and a dependency has no viable emulator/container strategy, mark it **mock** and record `no-testcontainer-emulator` as the reason. +- If the confirmed mode is `mixed`: the mode is per dependency — ask the user for the decision per row, then apply the `real`, `testcontainer`, or `mock` rules above for each dependency individually. +- If `infra/` does not exist at all and mode is not `testcontainer`, mark every external dependency as **mock** and record `infra-missing` as the reason. +- **Cross-module service dependencies** (e.g. module A calling a service API in module B) → always **mock**. Each module's tests are self-contained; inter-module calls are mocked at the service interface boundary. +- **External services unrelated to the migration scope** (third-party APIs, internal services outside the project, legacy systems not being migrated) → always **mock**, regardless of `infra/` presence. + +**Confirm with the user before saving.** Draft the full table in chat first, then — if an interactive user-question tool is available in the current environment (e.g. `ask_user`, `vscode_askQuestions`, or any equivalent surfaced by the host) — use it to present the draft and ask the user to confirm or correct each row's `Decision` and `Auth Method`. Apply any corrections, then write the file. If no such tool is available, skip the prompt and proceed to save (do not block the workflow). + +**Output:** save to `/test-cases/infra-decision-table.md` using [infra-decision-table-template.md](infra-decision-table-template.md). One row per dependency, all columns required. The template defines the canonical column set, allowed values, decision rules, and banned phrasings. + +This file is part of the frozen baseline bundle (see Step 7) and is consumed as-is by `verify-test-baseline`. Do not proceed to Step 6 until the table is saved. + +### Step 6: Validate the Spec (Required Field Checklist) + +Before declaring the baseline frozen, validate `test-cases.md` against this checklist. Each test case MUST satisfy every item, or it is not ready to freeze. + +| # | Field | Validation rule | +|---|---|---| +| 1 | `ID` | Unique, format `TC--` (e.g. `TC-WEB-001`, `TC-WKR-002`). | +| 2 | `Category` | One of: `happy-path`, `boundary`, `special-input`, `failure`. | +| 3 | `Entry Point Type` | A short, consistent label describing the invocation mechanism (e.g. `HTTP`, `CLI`, `Scheduled`, `Message-queue listener`). The same mechanism must use the same label across all cases. | +| 4 | `Entry Point` | Exact identifier from production code: HTTP method+path, fully qualified method, CLI command, queue/topic name, service interface + method signature. No vague references. | +| 5 | `Trigger` | Concrete, technology-agnostic description of how the entry point is invoked: payload reference, headers, argv, message body. Sufficient for a code generator to construct the call. | +| 6 | `Preconditions` | All required application / resource state before the trigger, with references to `testdata/` for any seed data. Use `none` if truly none. | +| 7 | `Expected Response` | The synchronous return at the entry point: status code + body file reference for HTTP, exit code + stdout/stderr file references for CLI, return value for methods. Use `none (fire-and-forget)` for async listeners with no synchronous response. | +| 8 | `Resource Verification` | At least one bullet, OR explicit `none` with justification. Each bullet names a specific resource (object key, row PK, queue name + message shape) and the observable state. Stated in resource-neutral terms so the same check applies pre- and post-migration. | +| 9 | `Negative Verification` | For failure / skip / no-op cases, list what MUST NOT happen (e.g. "no new row in `image_metadata`"). Mandatory whenever `Category` is `failure` or behavior is "skip". | +| 10 | `Data References` | All file paths under `testdata/` cited in the case actually exist. | + +**Banned phrasings** (auto-reject): +- "should return a reasonable error" → must state exact status + body. +- "behaves as expected" / "works correctly" → must state observable outcome. +- "approximately N items" → must state exact count or a precise range with bound semantics. +- "etc." in expected outputs → enumerate completely. +- Hand-waved resource checks ("data is persisted") → must name the resource and the field-level state. + +**Entry-point coverage check**: every orchestration entry point cataloged in Step 1 appears as the `Entry Point` of at least one `happy-path` test case AND at least one `failure` test case. An entry point counts as covered if it is covered by an **existing test** (referenced as `covered-by-existing` in Step 3) OR by a **new test case** in `test-cases.md`. Both sources count toward the coverage requirement. + +Any validation failure → fix the spec. Do not freeze with defects. + +### Step 7: Freeze and Output + +1. Declare the entire `/test-cases/` folder **FROZEN**. Subsequent phases must not modify anything inside it; any required change forces a re-freeze cycle (unfreeze → amend → re-validate → re-freeze). +2. Create `${modernization-work-folder}/${taskid}/baseline-summary.md` summarizing: per-module scoping decisions, entry-point inventory, existing test inventory and extracted conventions (from Step 2), test case counts (existing-covered vs. new) by category per module, `testdata/` file list, the Step 5 infra decision table, and confirmation that the Step 6 checklist passed. +3. Commit the changes. \ No newline at end of file diff --git a/plugins/github-copilot-modernization/skills/create-test-baseline/infra-decision-table-template.md b/plugins/github-copilot-modernization/skills/create-test-baseline/infra-decision-table-template.md new file mode 100644 index 0000000..58d9a05 --- /dev/null +++ b/plugins/github-copilot-modernization/skills/create-test-baseline/infra-decision-table-template.md @@ -0,0 +1,102 @@ +# Infra Decision Table + +> This document is part of the **frozen baseline bundle**. It records, for every external dependency the migrated application talks to, whether the post-migration tests will exercise it as a **real** provisioned resource, a **testcontainer**-backed emulator/dependency, or a **mock** at the SDK / HTTP boundary. The decision is made once here and reused as-is by the `verify-test-baseline` skill. + +## Metadata + +| Field | Value | +|-------|-------| +| Project | [Application name] | +| Module | [e.g. `web`, `worker`] | +| Migration Scope | [e.g. migrate from AWS S3 + SQS to Azure Blob Storage + Service Bus] | +| Integration Test Environment | [real \| mock \| testcontainer \| mixed] | +| Created At | [YYYY-MM-DD] | +| `infra/` Snapshot | [git SHA or "infra-missing" if no infra folder] | +| Status | baseline (frozen) | + +## Decision Table + +One row per external dependency. The dependency list is derived from the target stack and the entry-point inventory in `test-cases.md` (Step 1 of `create-test-baseline`). No dependency the application talks to may be omitted. + +| Dependency | Infra Match | Decision | Auth Method | Reason | +|---|---|---|---|---| +| [Dependency name + identifier, e.g. `Azure Blob Storage (sthve4rw7qkv7k4)`] | [`Yes — ` \| `No`] | [`real` \| `testcontainer` \| `mock`] | [see allowed values below] | [Single sentence; see rules below] | + +### Required column values + +- **Dependency** — Name the concrete resource the application binds to, including its identifier when applicable (account / namespace / database / topic name). Generic categories alone (e.g. "object storage") are not acceptable. +- **Infra Match** — Exactly one of: + - `Yes — ` when a provisioned endpoint + credentials are documented in `infra/`. + - `No` when no matching resource exists in `infra/` (or `infra/` does not exist at all). +- **Decision** — Exactly one of `real`, `testcontainer`, or `mock`. No conditional values, no per-test-case overrides in this column. +- **Auth Method** — How the application authenticates to this dependency at runtime. Exactly one of: + - `managed-identity` — workload identity issued by the hosting cloud platform. + - `service-principal` — client-id with secret/certificate/federated credential. + - `username-password` — DB/basic auth user credential. + - `connection-string` — secret-bearing connection string. + - `emulator-connection-string` — local emulator/container connection string (testcontainer mode). + - `sas-token` — scoped shared access token/signature. + - `api-key` — static key or out-of-band bearer token. + - `mtls` — mutual TLS/client certificate. + - `anonymous` — no authentication. + - `n/a` — only when `Decision = mock`. + + Rules: use `managed-identity` only for deployments on identity-issuing cloud hosts; record the **post-migration** auth method only. +- **Reason** — One sentence. Must justify the Decision against the Infra Match per the rules below. + +### Testcontainer support reference + +**Has emulator — can use `testcontainer`:** + +| Dependency type | Emulator image | Dependencies | Auth method | +|---|---|---|---| +| Azure Blob / Queue / Table Storage | `mcr.microsoft.com/azure-storage/azurite` | None | `emulator-connection-string` | +| Azure Service Bus | `mcr.microsoft.com/azure-messaging/servicebus-emulator` | Companion MSSQL container + JSON config file | `emulator-connection-string` | +| Azure Event Hubs | `mcr.microsoft.com/azure-messaging/eventhubs-emulator` | Companion Azurite container + JSON config file | `emulator-connection-string` | +| Azure Cosmos DB | `mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator` | None (requires SSL trust-store setup) | `connection-string` (endpoint + emulator key) | +| Azure SQL Database | `mcr.microsoft.com/mssql/server` | None | `username-password` | +| PostgreSQL / MySQL | `postgres`, `mysql` | None | `username-password` | +| Redis / MongoDB / RabbitMQ / Kafka | standard community images | None | varies | + +> **Cosmos DB:** If SSL trust-store setup is too complex, mark `mock` with reason `no-testcontainer-emulator`. +> **Service Bus / Event Hubs:** AMQP send/receive only — management/REST APIs are not supported by the emulators. + +**No emulator — must use `mock`:** + +| Dependency type | +|---| +| Azure Key Vault | +| Azure App Configuration | +| Azure Active Directory / Entra ID | +| Azure AI / Cognitive Services | +| Third-party / external HTTP APIs | + +### Decision rules (must match Step 5 of `create-test-baseline`) + +- If `Integration Test Environment = mock`: every row's Decision MUST be `mock` regardless of `Infra Match`. +- If `Integration Test Environment = real`: `Infra Match = Yes` → Decision MUST be `real`. +- If `Integration Test Environment = real` and `Infra Match = No` while `infra/` exists: Decision MUST be `mock`. Reason should state that the dependency is not provisioned. +- If `Integration Test Environment = testcontainer`: use `testcontainer` when a viable emulator/container strategy exists for that dependency. +- If `Integration Test Environment = testcontainer` and no viable emulator/container strategy exists: Decision MUST be `mock` and Reason should include `no-testcontainer-emulator`. +- If `Integration Test Environment = mixed`: apply the `real`, `testcontainer`, or `mock` rules above per row according to the user-specified per-dependency decision. +- `infra/` does not exist at all and mode is not `testcontainer` → every row's Decision is `mock` and the Reason is `infra-missing`. Set the `infra/` Snapshot field to `infra-missing`. +- `Auth Method = n/a` is allowed **only** when `Decision = mock`. `real` and `testcontainer` rows must declare a concrete auth method. + +### Banned phrasings (auto-reject) + +- Decision values other than `real` / `testcontainer` / `mock` (e.g. `mostly real`, `real-with-fallback`, `tbd`). +- Auth Method values outside the allowed list above. Free-form descriptions (e.g. "DefaultAzureCredential", "whatever the SDK picks") are not acceptable — pick the concrete underlying credential type instead. +- Auth Method = `n/a` on a `real` or `testcontainer` row. +- Reasons that do not reference decision evidence (`infra/`, `infra-missing`, or testcontainer emulator/container evidence). +- Per-test-case carve-outs ("real for happy-path, mock for failure"). Failure-injection conflicts are handled in `verify-test-baseline` Step 4 via a re-freeze, not by splitting a row here. +- Missing or empty cells. + +## Worked Example (reference; do not copy verbatim) + +| Dependency | Infra Match | Decision | Auth Method | Reason | +|---|---|---|---|---| +| Azure Blob Storage (`sthve4rw7qkv7k4`, container `assets`) | Yes — `infra/env-config.md` | real | managed-identity | Provisioned storage account with container `assets` in resource group `rg-app-demo`. | +| Azure Service Bus (`sbemulatorns`, queue `image-processing`) | No | testcontainer | emulator-connection-string | Using Service Bus emulator container configuration for local verification; no matching provisioned namespace selected for this run. | +| Azure Service Bus (`sbhve4rw7qkv7k4`, queue `image-processing`) | Yes — `infra/env-config.md` | real | managed-identity | Provisioned namespace with queue `image-processing` in resource group `rg-app-demo`. | +| Azure Database for PostgreSQL (`pg6kt67kwkpeqji2`, database `app`) | Yes — `infra/env-config.md` | real | managed-identity | Provisioned flexible server with database `app`; migration moves from password to managed identity. | +| Third-party email API (`api.example-mail.com`) | No | mock | n/a | No provisioned credentials in `infra/`; mock at the HTTP boundary, seed from `testdata/`. | diff --git a/plugins/github-copilot-modernization/skills/create-test-baseline/test-cases-template.md b/plugins/github-copilot-modernization/skills/create-test-baseline/test-cases-template.md new file mode 100644 index 0000000..24ddd12 --- /dev/null +++ b/plugins/github-copilot-modernization/skills/create-test-baseline/test-cases-template.md @@ -0,0 +1,176 @@ +# Test Cases + +> This document is the **frozen behavioral specification** of a single module's external surface for the migration in scope. It is the source of truth that the `verify-test-baseline` skill uses to generate `*PostMigrationIT` tests against the new implementation. No test code is generated in the baseline phase. +> +> **Scoping rule:** This file MUST contain only test cases whose entry points belong to the module named below. Test cases for entry points in other modules belong in those modules' own `test-cases.md`. Modules that do not directly access any migration-relevant resource are out of scope and do not get a `test-cases.md` at all. + +## Metadata + +| Field | Value | +|-------|-------| +| Project | [Application name] | +| Module | [e.g. `web`, `worker` — the single module this file covers] | +| Migration Scope | [e.g. migrate from AWS S3 + SQS to Azure Blob Storage + Service Bus] | +| Created At | [YYYY-MM-DD] | +| Status | baseline (frozen) | +| Testing Conventions | [e.g. JUnit 5, AssertJ; naming: `should__when_`; one test class per controller] | + +## Existing Test Coverage + +List entry points already covered by existing integration tests. These are NOT duplicated as new test cases below. + +| Entry Point | Existing Test (FQ name) | Categories Covered | +|---|---|---| +| `POST /api/files/upload` | `com.example.FileControllerIT#should_upload_file_successfully` | happy-path | +| … | … | … | + +> Remove this section if no existing integration tests exist. + +## Entry-Point Inventory + +List every external boundary / orchestration entry point covered below. Cross-checked by Step 6 of the create-test-baseline skill. + +| Entry Point | Type | Source (file:symbol) | Covered by | +|---|---|---|---| +| `POST /api/files/upload` | HTTP | `web/.../FileController.java:upload` | existing: `FileControllerIT`, TC-WEB-002 | +| `processImage(ImageProcessingMessage)` on queue `image-processing` | Message-queue listener | `worker/.../ImageProcessor.java:processImage` | TC-WKR-001, TC-WKR-004 | +| … | … | … | … | + +Entry-point types: `HTTP`, `CLI`, `Scheduled`, `In-process event`, `Message-queue listener`, `Webhook`, `Streaming`, `Public method`. + +## Test Case Format + +Every test case MUST populate **all required fields below**. Use the worked example as the canonical shape. Any vague phrasing (see "Banned phrasings" in the skill) is a defect and must be fixed before freezing. + +--- + +### Worked Example — TC-WKR-001 (reference; do not copy verbatim) + +| Field | Value | +|-------|-------| +| ID | TC-WKR-001 | +| Category | happy-path | +| Entry Point Type | Message-queue listener | +| Entry Point | Listener bound to queue `image-processing`, consuming `ImageProcessingMessage` | +| Description | A valid JPEG referenced by an incoming message is downloaded, a 600px-bounded thumbnail is produced, and metadata is updated. | + +**Trigger** + +Publish one message to queue `image-processing` with body: + +```json +{ + "key": "-sample.jpg", + "contentType": "image/jpeg", + "storageType": "", + "size": 12345 +} +``` + +(`size` = byte length of `testdata/inputs/sample.jpg`.) + +**Preconditions** + +- Object with key `-sample.jpg` exists in the storage container, content byte-identical to `testdata/inputs/sample.jpg`, content-type `image/jpeg`. +- A row exists in `image_metadata` with `key = -sample.jpg`, `thumbnail_key` NULL. + +**Expected Response** + +`none (fire-and-forget)` — the listener acknowledges the message after successful processing; no synchronous response is observable. + +**Resource Verification** + +- An object with key `-sample_thumbnail.jpg` exists in the storage container with content-type `image/jpeg`. +- That thumbnail object is a readable image whose `max(width, height) <= 600`, and the aspect ratio matches the original (`testdata/inputs/sample.jpg`) within ±1 pixel. +- The row in `image_metadata` with `key = -sample.jpg` has `thumbnail_key = -sample_thumbnail.jpg` and `thumbnail_url` non-null. +- No additional rows are created in `image_metadata`. + +**Negative Verification** + +- No message is published to any downstream queue. +- No row is created in `image_metadata` with `key != -sample.jpg`. + +**Data References** + +- `testdata/inputs/sample.jpg` + +--- + +## Test Cases + +### [TC-XXX-NNN] [Operation Name] — [Category Title] + +| Field | Value | +|-------|-------| +| ID | TC-XXX-NNN | +| Category | [happy-path \| boundary \| special-input \| failure] | +| Entry Point Type | [HTTP \| CLI \| Scheduled \| In-process event \| Message-queue listener \| Webhook \| Streaming \| Public method] | +| Entry Point | [Exact identifier from production code — HTTP method+path, FQ method, CLI command, queue/topic name] | +| Description | [One sentence: what externally observable behavior this case pins down] | + +**Trigger** + +[Concrete invocation. For HTTP: method, path, headers, body (reference a `testdata/inputs/*.json` file when non-trivial). For CLI: full argv and stdin. For listener: queue/topic name and message body. Sufficient detail for a code generator to construct the call without further interpretation.] + +**Preconditions** + +- [Each prerequisite as a bullet. Reference `testdata/seed-data/*` for any seeded state. Use `none` only if literally nothing.] + +**Expected Response** + +[Synchronous return at the entry point. HTTP: status + body file reference. CLI: exit code + stdout/stderr references. Method: return value. Listener: `none (fire-and-forget)` is acceptable.] + +**Resource Verification** + +- [Each post-condition as a bullet. Name the resource (object key, table+PK, queue name + message shape) and the observable state. Resource-neutral phrasing.] +- [`none` allowed only when the operation provably touches no external resource; explain why in one phrase.] + +**Negative Verification** + +- [Required for `failure` cases and any "skip / no-op" behavior. State what MUST NOT happen, naming the resource.] +- [Omit this section ONLY for pure `happy-path` cases where no plausible side-effect-leak risk exists.] + +**Data References** + +- [Every `testdata/...` path referenced above, listed here for the freeze audit.] + +--- + +### [TC-XXX-NNN+1] … + +(Repeat for every test case. Cover all four categories per entry point.) + +--- + +## Required Field Checklist (Freeze Gate) + +Before marking this document frozen, every test case above MUST satisfy every row. Tick when validated. + +- [ ] **ID** unique, formatted `TC--`. +- [ ] **Category** is one of `happy-path`, `boundary`, `special-input`, `failure`. +- [ ] **Entry Point Type** matches one of the catalog types. +- [ ] **Entry Point** is an exact production-code identifier (no vague references). +- [ ] **Trigger** is concrete enough to construct the call mechanically (payload referenced by file, headers/argv enumerated, queue/topic named). +- [ ] **Preconditions** enumerated (or `none`); all referenced seed data exists under `testdata/`. +- [ ] **Expected Response** specifies exact status / exit code / return shape (or `none (fire-and-forget)`). +- [ ] **Resource Verification** has at least one bullet OR explicit `none` with justification; each bullet names a specific resource and the observable state. +- [ ] **Negative Verification** present for every `failure` case and every "skip / no-op" outcome. +- [ ] **Data References** complete; every path exists under `testdata/`. + +## Coverage Gate + +- [ ] Every entry point in the **Entry-Point Inventory** appears as the `Entry Point` of at least one `happy-path` case. +- [ ] Every entry point in the **Entry-Point Inventory** appears as the `Entry Point` of at least one `failure` case. +- [ ] Each entry point covers all four buckets where applicable: `happy-path`, `boundary`, `special-input`, `failure`. +- [ ] Entity examples use 2–5 representative records (no single-row, no exhaustive enumeration). + +## Banned Phrasings (Auto-Reject) + +If any of the following appears in a test case, it is a defect — fix before freezing: + +- "should return a reasonable error" → state exact status + body. +- "behaves as expected" / "works correctly" → state observable outcome. +- "approximately N items" → state exact count or precise range with bound semantics. +- "etc." / "and so on" in expected outputs → enumerate completely. +- "data is persisted" / "state is updated" without naming the resource and field-level state. +- Service-specific SDK types (`S3Object`, `BlobClient`, `SqsMessage`, …) in any field — describe in resource-neutral terms instead. diff --git a/plugins/github-copilot-modernization/skills/cve-remediation/SKILL.md b/plugins/github-copilot-modernization/skills/cve-remediation/SKILL.md new file mode 100644 index 0000000..c321498 --- /dev/null +++ b/plugins/github-copilot-modernization/skills/cve-remediation/SKILL.md @@ -0,0 +1,367 @@ +--- +name: cve-remediation +description: | + Scan dependency manifests against known CVEs and remediate by upgrading vulnerable + dependencies to patched versions, then rebuild and re-scan to confirm. Self-contained + scan→fix→verify loop for any project with a dependency manifest. + + Use when: a cve-remediation task is dispatched; dependency set changed (version bump, + new framework); assessment flagged vulnerable or EOL dependencies; or user asked to + "fix CVEs", "patch vulnerabilities", or "dependency security". + + Triggers: "cve", "remediate cve", "fix cves", "patch vulnerable dependencies", + "vulnerability scanning", "dependency security", "vulnerable dependencies", + "security advisories", "npm audit", "pnpm audit", "maven audit", "gradle audit", + "dependency scan", "vulnerability remediation". + + NOT for: security audit of auth/input/secrets/OWASP code paths (use security-review). +--- + +# CVE Remediation + +This skill is the implementer-owned scan→fix→verify loop for dependency CVEs. It is +dispatched as an **execute-phase** task to an implementer role (backend), runs +**per group**, and produces patched dependency manifests plus an audit trail. + +## Ownership & boundaries + +- **This is implementer work, not audit work.** The `security` role audits and escalates + but does NOT fix. This skill performs the *fix* (editing dependency manifests), so it is + owned by the implementer who owns those manifests — not by the `security` role. +- **The rebuild/re-scan is a self-check, not a quality gate.** It is the implementer + confirming their own change took — analogous to compiling after editing code. It must + NOT masquerade as the project's security gate, and it stays within the **Implementation** + phase label. The independent gates (`smoke-test`, `runtime-validation`, and the + coordinator's verdict rules) remain separate and unchanged. +- **Scope is per-group.** Each in-scope group has its own dependency manifests; remediate + the manifests belonging to the dispatched group. + +## Scanning: tool-first with LLM fallback + +CVE scanning is performed by the shared **`appmod-cve-assessment`** tool, which all +modernization surfaces (VS Code extension, IntelliJ plugin, Copilot CLI plugin, MCP server) +expose. It queries the GitHub Security Advisories API for a set of package ecosystems and +writes structured findings to a result file. Using the shared tool keeps scanning +consistent across products and emits the standard telemetry. + +- **Primary — `appmod-cve-assessment` tool** (preferred whenever it applies). Consult the + tool's own `ecosystem` parameter for the ecosystems it currently accepts — treat that + schema as the source of truth rather than assuming a fixed list, since it may grow over + time. +- **Fallback — LLM-only scan** when the tool path does **not** apply. This covers **two** + cases, both signalled by the tool itself: + 1. **Tool unavailable** — `appmod-cve-assessment` is not registered in the current + runtime (e.g. a standalone Copilot CLI / rearchitecture runtime without the tool wired + up). + 2. **Ecosystem not accepted** — the tool rejects the project's ecosystem (its + `ecosystem` parameter does not accept it / input validation fails). Whichever + ecosystems the tool does not yet cover fall here automatically. + + In either case the model identifies known CVEs for the listed dependency versions from + its own knowledge and writes the **same findings schema** (see Step 3). This is + best-effort — model knowledge has a training cutoff and may miss recent advisories — so + prefer the tool whenever it applies. + +Map the project's package manager to the ecosystem identifier the tool accepts (for example, +Maven and Gradle both resolve to the same JVM identifier). If the tool does not accept any +identifier for the project's ecosystem, go straight to the LLM-only fallback. + +## Artifact path + +The coordinator provides an artifact path for this task. Throughout this skill, +`{{ARTIFACT_PATH}}` refers to that directory. Write all reports and the fix summary there. + +## Workflow + +### Step 1: Precheck — detect project type and build tool + +Before running any build or dependency commands, verify that the required build tool is +available. + +1. **Detect the project type** by examining the group's project root: + + | File(s) found | Project type | Tool ecosystem id (common mapping) | + |---|---|---| + | `pom.xml` | Maven (Java) | maven | + | `build.gradle` or `build.gradle.kts` | Gradle (Java) | maven | + | `*.sln` | .NET solution | nuget | + | `*.csproj` | C# project | nuget | + | `packages.config` | Legacy .NET | nuget | + | `package.json` | Node.js (npm/pnpm/yarn) | npm | + | any other manifest (e.g. `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Gemfile`, `composer.json`) | other | whatever the tool accepts, else LLM-only fallback (Step 2c) | + + > The ecosystem ids above are the **common** mappings at the time of writing. The tool's + > `ecosystem` parameter is authoritative — if it accepts an identifier for the project's + > ecosystem, use the tool; otherwise use the LLM-only fallback. + +2. **Resolve the build command** — prefer project-local wrappers over global tools: + + | Project type | Check order (prefer first match) | Fallback | + |---|---|---| + | Maven | `./mvnw` (Unix) or `mvnw.cmd` (Windows) | `mvn` on PATH | + | Gradle | `./gradlew` (Unix) or `gradlew.bat` (Windows) | `gradle` on PATH | + | .NET | `dotnet --version` | — | + | Node.js | `npm` / `pnpm` / `yarn` (only needed to *apply* fixes) | — | + +3. **If the required tool is not found**, stop and report the error. Do not proceed. + +### Step 2: Scan dependencies against CVE databases + +The scan also serves as **detection**: a clean result (an empty findings array) means the +group has no known dependency CVEs and the task exits cheaply. + +#### Step 2a: Collect dependency coordinates and locations + +Extract the dependency coordinates for the group, capturing for each one the +workspace-relative file path and 1-based line number where it is declared. Prefer +**resolved** versions (which include transitive dependencies — the common source of CVEs) +and fall back to manifest-declared versions when a resolver is unavailable. + +| Ecosystem | Coordinate format | Where to read | +|---|---|---| +| `maven` | `groupId:artifactId:version` | `mvn dependency:list` / `gradle dependencies` (resolved), else `pom.xml` / `build.gradle` / `gradle.properties` | +| `nuget` | `PackageName@version` | `dotnet list package` (resolved), else `*.csproj` / `Directory.Packages.props` / `packages.config` | +| `npm` | `package-name@version` (e.g. `express@4.18.2`, `@angular/core@16.0.0`) | lockfile (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock` — resolved, includes transitives), else `package.json` | + +> These are the common ecosystems and their coordinate formats. For the authoritative +> coordinate format expected by each ecosystem the tool accepts, consult the tool's +> `dependencies` / `ecosystem` parameter descriptions. For an ecosystem the tool does not +> accept (LLM-only fallback), use that ecosystem's natural coordinate form (e.g. +> `package==version` for Python) read from its manifest or lockfile. + +#### Step 2b: Scan with the `appmod-cve-assessment` tool (primary) + +Call `appmod-cve-assessment` with: + +- `cveResultFilePath` — an **absolute** path of `{{ARTIFACT_PATH}}/cve-report-N.json` + (start at `1`, increment each scan to preserve history). +- `ecosystem` — the identifier the tool accepts for the project's package ecosystem (see + the tool's `ecosystem` parameter for the accepted values). +- `dependencies` — the coordinate array from Step 2a. +- `dependencyLocations` — `{ coordinate, filePath, lineNumber }` for each dependency. + +The tool fetches CVEs, writes the findings JSON to `cveResultFilePath`, and returns a +summary message. For very large dependency sets, scan in batches, writing each batch to its +own numbered report. **If the tool is unavailable, or it rejects the `ecosystem` as not +accepted, switch to the LLM-only fallback (Step 2c).** + +#### Step 2c: LLM-only scan (fallback — tool unavailable OR ecosystem not accepted) + +Use this path when the tool cannot do the scan — either because `appmod-cve-assessment` is +**not available** in the current runtime, or because the tool **does not accept** the +project's ecosystem (its `ecosystem` parameter rejects it). Perform the scan from model +knowledge instead: for each coordinate + version, identify known CVEs and write the **same +findings schema** (see Step 3) to `{{ARTIFACT_PATH}}/cve-report-N.json`. Note in the fix +summary that the LLM fallback was used (and why), since it is best-effort and may miss +recent advisories. + +**Large projects**: if scanning is slow, run it in a **background (async) terminal** and, +while it runs, review and fix vulnerabilities already known from earlier runs. Address any +newly discovered issues once it completes. + +### Step 3: Review the report and identify vulnerable dependencies + +Parse the latest `cve-report-N.json` and examine each finding: + +1. Read the report file and parse the JSON (an array of findings; `[]` means no CVEs). +2. Group by `severity`: **critical** > **high** > **medium** > **low**. +3. For each finding note: the affected dependency + current version and the upgrade target + — both are in the `evidence.explanation` (the `Affected dependencies` and + `Recommended fix` lines) — plus the CVE identifier (`id`) and `name`. +4. Prioritize critical and high severity for immediate remediation. + +Report schema (one object per CVE): +```json +[ + { + "id": "CVE-2022-22965", + "name": "Spring Framework RCE via Data Binding on JDK 9+", + "status": "FOUND", + "category": "CVE", + "severity": "critical", + "storyPoint": 1, + "evidence": { + "files": ["pom.xml:20"], + "explanation": "[CVE-2022-22965](https://github.com/advisories/GHSA-36p3-wjmg-h94x): Spring Framework RCE via Data Binding on JDK 9+\n\nSeverity: CRITICAL\n\nAffected dependencies:\n - org.springframework:spring-core@5.3.9\n\nRecommended fix:\n - Upgrade org.springframework:spring-core to 5.3.18 or later" + } + } +] +``` + +> A finding whose `explanation` contains **no** `Recommended fix` line has no upstream patch +> available (unfixable). An empty array (`[]`) means no known CVEs were found. + +### Step 4: Update vulnerable dependencies to secure versions + +For each vulnerable dependency, update to a secure version (the upgrade target from the +`Recommended fix` line) using the appropriate method. + +**Fix principles** (consistent with the security agent): +- **Direct upgrade, not a framework upgrade.** Bump the affected dependency **directly** to + the patched version — no stepping through intermediate versions. CVE remediation is a + targeted patch, not a version migration. +- **Respect a pinned target version.** If the user's request pins a target version/line for + a dependency (e.g. "upgrade Spring Framework to 6.2.18"), remediate **within** it — a + patch bump within that line to clear a CVE is fine. Only when no in-range patch exists do + you leave it — record it as a follow-up (Step 7.3) rather than forcing a major jump. +- **Minimal changes.** Change only what is needed to clear the CVE. Do not refactor, + reformat, or make unrelated edits. +- **Batch related fixes.** When a single upgrade clears several CVEs (e.g. a shared + BOM/parent), apply it once for all of them. + +#### Java — Maven (pom.xml) +1. Find the version (may be in ``, ``, or inline ``). +2. Update to the patched version (or the latest stable if the patched version is also outdated). +3. If the version is inherited from a parent POM (e.g. Spring Boot starter parent), update the parent version instead. + +> **Where CVEs hide — check BOM overrides first.** Pay special attention to dependencies +> that explicitly declare a `` tag *overriding* a managed BOM (e.g. the Spring Boot +> dependencies BOM). These inline overrides bypass BOM management and are the most common +> source of missed CVE vulnerabilities — bumping the BOM/parent version alone will not patch +> them. Cross-check the `` tags in each sub-module's `pom.xml` against the +> vulnerable dependencies and update the override (or remove it to fall back to the managed +> version) as needed. + +#### Java — Gradle (build.gradle) +1. Find the version in `build.gradle` or `gradle.properties`. +2. Update the version string to the patched version. +3. If using a BOM or platform dependency, update the BOM version. + +#### .NET (csproj) +1. Find ``. +2. Update the `Version` attribute to the patched version. +3. If versions are managed centrally via `Directory.Packages.props`, update them there instead. +4. Alternatively: `dotnet add package PackageName --version X.Y.Z`. + +#### Node.js — npm / pnpm / yarn (package.json) +1. Find the version in `package.json` under `dependencies` or `devDependencies`. +2. Update the range to the patched version (e.g. `"^4.17.21"`), then **regenerate the + lockfile** so the resolved transitive versions update too: + - npm: `npm install pkg@X.Y.Z` (or edit `package.json` then `npm install`) + - pnpm: `pnpm add pkg@X.Y.Z` (or edit then `pnpm install`) + - yarn: `yarn add pkg@X.Y.Z` (or edit then `yarn install`) +3. **Transitive dependencies** (the common case for npm CVEs) are pulled in by other + packages and have no direct entry in `package.json`. Force a patched version with an + override instead of a direct edit: + - npm: add an `"overrides"` block (`{ "overrides": { "pkg": "X.Y.Z" } }`) + - pnpm: add `"pnpm": { "overrides": { "pkg": "X.Y.Z" } }` + - yarn (Berry): add a `"resolutions"` block + Then re-run the install command to regenerate the lockfile. + +### Step 5: Re-scan to confirm issues are resolved (self-check) + +Re-run the Step 2 scan and write the output with the next sequential number. Then compare +the new report against the previous one and **exit the loop** when ANY of these hold: + +- **Clean** — the report is an empty array (`[]`). Success. +- **Only unfixable CVEs remain** — every remaining finding has no `Recommended fix` line in + its `explanation` (no upstream patch available). Success; record these in the summary as + accepted/unfixable. +- **No progress** — after a fix attempt the **same** fixable CVEs persist — compare by CVE + **id**, not by raw count. A fix that resolves the targeted CVE but surfaces a *different, + newly-disclosed* CVE is **progress, not a stall**: bump to the highest recommended + **released** version and keep going. Treat it as no-progress (and stop) only when the same + CVE id keeps reappearing despite a fix, **or** when the only way forward is a recommended + version that is **not yet released** (no installable artifact) — record those as + accepted/stuck in the summary. Stop here rather than looping forever. + +> **Fixable vs. unfixable — important.** A CVE is *unfixable* **only** when it has no +> `Recommended fix` line (no patched version exists upstream). A CVE that requires a +> **major-version upgrade** still has a patched version, so it is **fixable** — leaving it +> means remediation is **incomplete** (the *No progress* / deferred path, surfaced as a +> Step 7 follow-up), **not** the *Only unfixable* success. Treat the run as fully successful +> only when **no fixable CVEs remain**. This matches the security agent's rule: do not claim +> success while patchable CVEs are still outstanding. + +Otherwise — if the count dropped but fixable CVEs (those with a `Recommended fix`) still +remain — return to Step 4, fix the newly reported CVEs, and re-scan, incrementing the report +number each time. This loop is the implementer's own confirmation — not a separate gate. + +### Step 6: Build and test after updates + +Use the build command resolved in Step 1. + +```shell +./mvnw clean verify # Maven +./gradlew clean build # Gradle +dotnet build && dotnet test # .NET +npm install && npm test # Node.js (npm) — use pnpm/yarn equivalents as appropriate +``` + +Verify the build completes, existing tests pass, and the app starts (if applicable). If the +build fails due to breaking API changes from an upgrade, apply the necessary code fixes and +re-run the build. **Cap this at 3 fix attempts** — if the build still fails, stop, keep the +dependency changes that scanned clean, and document the build issue in the summary (Step 7) +rather than looping. Keep this within the Implementation phase — it is a build recheck, not +a new phase. + +### Step 7: Document the changes + +1. Write a summary of CVEs fixed (CVE/GHSA ID, dependency + version, patched version, + severity, brief description) to `{{ARTIFACT_PATH}}/cve-fix-summary.md`. Note whether the + scan used the `appmod-cve-assessment` tool or the LLM-only fallback. +2. Run a final scan and write it as the final report + (`{{ARTIFACT_PATH}}/final-cve-report.json`). All intermediate numbered reports are + preserved for audit history. +3. If any fix requires a **major** version upgrade (breaking-change risk), record it as a + follow-up item in the summary rather than forcing it silently — and surface it to the + coordinator so dependent tasks and reviews are aware. + +--- + +## Environment Setup + +### Prerequisites + +1. **Build tool** (one of): `mvn` / `mvnw`, `gradle` / `gradlew`, or `dotnet` — to apply + fixes and rebuild. +2. **Node.js package manager** (`npm` / `pnpm` / `yarn`) — only needed to apply Node.js fixes. +3. **GitHub token** (optional, recommended for the tool path — raises the GitHub Security + Advisories rate limit from 60 to 5000 req/hr): export `GITHUB_TOKEN` (or `GITHUB_PAT`). + The `appmod-cve-assessment` tool reads it from the environment when present. + +--- + +## Error Handling + +| Error | Cause | Solution | +|-------|-------|----------| +| `appmod-cve-assessment` not available | Tool not registered in the current runtime | Use the **LLM-only fallback** (Step 2c) | +| Tool rejects the `ecosystem` | The tool does not accept this project's ecosystem | Use the **LLM-only fallback** (Step 2c) | +| Rate limit / HTTP 403 from the tool | Too many advisory API calls without auth | Set `GITHUB_TOKEN` / `GITHUB_PAT` in the environment | +| Empty / malformed coordinate rejected | Wrong coordinate format | maven: `groupId:artifactId:version`; nuget: `PackageName@version`; npm: `package-name@version` | +| `Maven/Gradle not found` | Build tool not in PATH | Install or ensure the wrapper (`mvnw`/`gradlew`) exists | +| `dotnet CLI not found` | .NET SDK not installed | Install .NET SDK | +| `No supported project files found` | Unrecognized project type | Ensure the root has pom.xml, build.gradle, *.sln, *.csproj, packages.config, or package.json | + +--- + +## Troubleshooting + +### List dependencies manually (to build the coordinate list for Step 2a) + +```bash +# Maven +mvn dependency:list -DoutputFile=deps.txt -q +grep -E "^ [a-zA-Z]" deps.txt | sed 's/^ //' | awk -F: '{print $1":"$2":"$4}' > coordinates.txt + +# Gradle +./gradlew dependencies --configuration compileClasspath > deps.txt + +# .NET +dotnet list package > deps.txt + +# Node.js (npm) — from package-lock.json (lockfileVersion 2/3) +jq -r '.packages | to_entries[] | select(.key|startswith("node_modules/")) | select(.value.version) | "\(.key|sub(".*node_modules/";""))@\(.value.version)"' package-lock.json | sort -u > coordinates.txt +``` + +Feed the resulting coordinates (with their file/line locations) into the +`appmod-cve-assessment` tool, or — when the tool is unavailable — into the LLM-only +fallback scan. + +### Rate limit errors + +Set a GitHub token in the environment so the tool authenticates its advisory API calls: +```bash +export GITHUB_TOKEN=$(gh auth token) +``` diff --git a/plugins/github-copilot-modernization/skills/dag-generation/SKILL.md b/plugins/github-copilot-modernization/skills/dag-generation/SKILL.md index 703782e..4f11dd6 100644 --- a/plugins/github-copilot-modernization/skills/dag-generation/SKILL.md +++ b/plugins/github-copilot-modernization/skills/dag-generation/SKILL.md @@ -33,6 +33,8 @@ Select fragments from the task catalog and produce a DAG. 1. **Project profile** — read from `{{BASE_PATH}}/artifacts/project-profile.yaml` (project.loc, project.languages, project.modules, assessment.change_type, assessment.grouping_needed) 2. **user_ask** — natural-language migration target (passed by coordinator) +If `user_ask` names an explicit target stack or version, preserve it verbatim in every selected task. Do not replace, downgrade, or reinterpret the requested version based on model familiarity or LTS defaults. + ### Decision Procedure #### Step 1: Determine deep_planning @@ -57,6 +59,8 @@ Read `references/task-catalog.md`. For each fragment, decide include/exclude bas - Project profile (LOC, modules) - `deep_planning` decision from Step 1 (drives `implementation-plan` selection) +Always include `target-env-prep` when the target runtime/framework/language/tooling differs from source or when the user specifies an explicit target version. This is an environment preparation task: it must install/provision/activate the requested target when possible, produce a preparation artifact, and run before scaffold/implementation/build/test tasks. It normally has no dependency on architecture/source analysis and should run in parallel with those tasks. This is true even for small projects and even when `deep_planning: false`. + Respect `when` / `skip-when` conditions and `after` ordering from the catalog. **⛔ Skip-when enforcement (mandatory post-selection gate):** @@ -65,6 +69,9 @@ After initial selection, sweep every selected fragment and check its `skip-when` This gate catches cases where the initial selection included fragments that looked relevant but conflict with the deep_planning decision or project scale. +**✅ Explicit-request override (runs AFTER skip-when enforcement — highest precedence):** +If `user_ask` explicitly requests a completeness, consistency, or feature-parity check (e.g. "run a completeness check", "verify nothing was missed", "enforce consistency", "feature parity sign-off"), force-include the completeness/conformance validation fragment (`conformance-review`, and `feature-parity-signoff` when applicable) **even if its `skip-when` condition matched and removed it above**. User intent overrides the size/type heuristic. This override is **one-directional** — it can only ADD a gate the heuristics dropped, never remove one they selected. It must run after the skip-when sweep, otherwise the sweep would strip the fragment back out (e.g. `skip-when: same-stack upgrade`). + Fragment selection is an internal decision — do NOT output the selection rationale to the user. The DAG itself is the user-facing result. #### Step 3: Generate DAG diff --git a/plugins/github-copilot-modernization/skills/dag-generation/references/dag-rules.md b/plugins/github-copilot-modernization/skills/dag-generation/references/dag-rules.md index b3615c2..c659894 100644 --- a/plugins/github-copilot-modernization/skills/dag-generation/references/dag-rules.md +++ b/plugins/github-copilot-modernization/skills/dag-generation/references/dag-rules.md @@ -37,8 +37,9 @@ Each task-catalog fragment has a `scope` field (`per-group` or `global`). 2. If no implementation plan, derive execute tasks from architecture analysis + pipeline fragments. 3. **Minimum dependency principle**: before adding edge D→T, verify T needs an artifact D produces. No deps based on phase grouping or role association. Do NOT make a task depend on ALL tasks in a prior group when it only needs output from ONE of them. 4. **Correct dependencies**: if a task consumes another's output, it MUST depend on it. UI pages calling APIs MUST depend on the API tasks, not just the scaffold. A task reading database tables MUST depend on the migration task. -5. **Scaffold gate (rewrite only)**: when the change_type is rewrite and a scaffold task creates the new project structure, any task that writes source code files MUST depend on the scaffold task. Does not apply to upgrade or extract. -6. **Output-to-consumer mapping**: for each role, identify what it produces and who needs that output. Only create a task if its output is consumed by another role, or if it's the final deliverable. +5. **Target environment preparation gate**: when `target-env-prep` is selected, emit it as a standalone execute-phase task before scaffold/implementation/build/test tasks. It is a preparation task, not analysis. By default it has no dependency on analysis/design tasks: it needs the user-specified target stack and local environment only, so it should run in parallel with architecture/source analysis unless the task explicitly needs an upstream artifact. Every scaffold, implementation, build, test, runtime-validation, or other target-stack task MUST depend on it. If its artifact reports `BLOCKED`, no dependent implementation/build/test task is ready. +6. **Scaffold gate (rewrite only)**: when the change_type is rewrite and a scaffold task creates the new project structure, any task that writes source code files MUST depend on the scaffold task. Does not apply to upgrade or extract. +7. **Output-to-consumer mapping**: for each role, identify what it produces and who needs that output. Only create a task if its output is consumed by another role, or if it's the final deliverable. ## Parallelism diff --git a/plugins/github-copilot-modernization/skills/dag-generation/references/task-catalog.md b/plugins/github-copilot-modernization/skills/dag-generation/references/task-catalog.md index 8ac0b0a..34baec2 100644 --- a/plugins/github-copilot-modernization/skills/dag-generation/references/task-catalog.md +++ b/plugins/github-copilot-modernization/skills/dag-generation/references/task-catalog.md @@ -67,9 +67,17 @@ LLM uses this to select task fragments for DAG generation. Each fragment is `{de > **Implementation tasks are NOT selected from this catalog.** When `implementation-plan` is selected in the plan phase, the worker producing that plan decomposes the implementation into concrete tasks — the coordinator dispatches from that breakdown. When `implementation-plan` is skipped (small projects), the coordinator decomposes implementation tasks itself based on plan-phase outputs. The fragments below are **auxiliary** execute-phase tasks that may be selected alongside implementation tasks. +### target-env-prep +- **desc**: Prepare the target toolchain/environment before implementation, not merely check readiness. Install, provision, or activate the requested runtime/framework/language/build/test prerequisites when the current environment permits it (examples: JDK for Java/Spring Boot upgrades, Node.js/npm for Angular/React/WinForms-to-web migrations, .NET SDK for .NET target versions, Python/Go/Ruby toolchains, browser/E2E prerequisites when required). Distinguish **installed** toolchains from the **active** default toolchain and from the toolchain that planned build/test commands will actually use. Produce exact preparation actions taken, installed versions, active versions, command-resolution evidence, activation commands/env vars for downstream tasks, missing tools, and blockers if the requested target cannot be prepared in the current environment. +- **scope**: global +- **when**: Always selected for any migration/upgrade/rewrite that names or implies a target runtime, SDK, language, framework, package manager, build tool, browser tool, database/container dependency, or target version. Examples: Java/JDK upgrades (including Spring Boot targets), WinForms-to-Angular/React migrations (Node.js/npm), .NET target framework changes (.NET SDK), Python/Go/Ruby runtime changes, browser/E2E validation targets, and any user-specified version such as JDK 25 or Spring Boot 4.0. Select even for small projects and even when `deep_planning: false`. +- **skip when**: Metadata/documentation-only changes; pure code refactor that does not change runtime/build/test toolchain. +- **hard rules**: Preserve user-specified target versions verbatim. Do not downgrade or substitute target stack versions based on familiarity or LTS defaults. This must be a standalone execute-phase task before scaffold/implementation/build/test work; do not merge it into analysis or architecture tasks. Do not make target-env-prep depend on architecture/source-analysis tasks unless it explicitly needs an upstream artifact; it normally runs in parallel with them. Downstream scaffold/implementation/build/test tasks must depend on the target-env-prep artifact and may proceed only when it reports `READY` with concrete command evidence. If the requested target cannot be installed, provisioned, or activated in the current environment, mark `BLOCKED`, keep the requested target in downstream plans, and stop before implementation instead of silently substituting a different target. A target is not prepared merely because it is installed somewhere; it is prepared only when the active shell and planned build/test commands resolve to the requested version, or when the artifact gives exact activation commands/env vars that downstream tasks must use. + ### scaffold - **desc**: Set up target project structure + infrastructure (build files, CI skeleton, base config). For cross-stack migrations that produce a new codebase; not needed for in-place modifications. - **scope**: global +- **after**: target-env-prep - **when**: Cross-stack rewrite producing new project structure - **skip when**: In-place modification; same-stack upgrade @@ -86,6 +94,13 @@ LLM uses this to select task fragments for DAG generation. Each fragment is `{de - **when**: User requests CI/CD or deployment; new infrastructure needed - **skip when**: No deployment/infra requirements specified; user only asks for code migration +### cve-remediation +- **desc**: Scan dependency manifests against known CVEs (GitHub Security Advisories for Maven/Gradle, NuGet Vulnerability API for .NET) and remediate by upgrading vulnerable dependencies to patched versions; rebuild and re-scan to confirm the remediation took. Self-contained scan→fix→verify loop owned by the implementer — the scan also serves as detection, so a clean project exits cheaply. Reports findings to `cve-fix-summary` + a scan-report history. The internal rebuild/re-scan is the implementer's own self-check, NOT a separate quality gate, and stays within the Implementation phase label. +- **scope**: per-group +- **after**: [implementation] +- **when**: The migrated/generated code emits or modifies a dependency manifest (pom.xml/build.gradle/*.csproj/packages.config). This INCLUDES cross-stack rewrites that adopt a brand-new framework — do NOT assume a fresh stack is CVE-free: agents routinely pin stale or even EOL framework versions (e.g. a Struts→Spring rewrite landing on Spring Boot 2.7, or a Java EE→Spring rewrite landing on Spring Boot 3.2), whose transitive trees carry known advisories. The scan is the only objective check that catches this, and it exits cheaply when the tree is clean. Also always selected when the user mentions security/CVE/vulnerability, or assessment/arch-analysis flagged vulnerable or EOL dependencies. +- **skip when**: No dependency manifest is produced or changed (e.g. pure config/docs/asset change, or a single-file dependency-free edit); OR the user explicitly opted out of security/CVE work. Do NOT skip merely because the target framework is "new" or "latest" — that assumption is unreliable and is exactly what this scan exists to verify. Do NOT skip merely because the project is lite scope — a lite-scope change that still touches a dependency manifest must be scanned. + --- ## Validate Phase @@ -99,6 +114,7 @@ LLM uses this to select task fragments for DAG generation. Each fragment is `{de ### security-review - **desc**: Security audit — auth flows, input validation, secrets handling, dependency vulnerabilities, OWASP concerns. - **scope**: global +- **after**: cve-remediation - **when**: App has auth/security flows; user requests security audit; public-facing API - **skip when**: No auth/security in source app; user didn't request security review @@ -129,6 +145,7 @@ LLM uses this to select task fragments for DAG generation. Each fragment is `{de - **after**: feature-inventory, runtime-validation - **when**: feature-inventory was selected - **skip when**: feature-inventory was skipped +- **override**: force-included if `user_ask` explicitly requests a completeness/consistency/feature-parity check (see dag-generation SKILL "Explicit-request override"), regardless of skip-when. ### conformance-review - **desc**: Validate that tests executed according to strategy, all quality gates passed, and no regressions remain. @@ -136,6 +153,7 @@ LLM uses this to select task fragments for DAG generation. Each fragment is `{de - **after**: runtime-validation, test-strategy - **when**: Multiple validation steps exist; need final rollup - **skip when**: Only runtime-validation in validate phase (conformance adds no value as separate step) +- **override**: force-included if `user_ask` explicitly requests a completeness/consistency check (see dag-generation SKILL "Explicit-request override"), regardless of skip-when. --- @@ -154,12 +172,12 @@ Select tasks based on `change_type` (upgrade | extract | rewrite), `user_ask`, a These illustrate the expected scale of fragment selection across different project profiles. They are NOT templates to copy — derive your selection from the project's actual characteristics. The point is calibrating your judgment: a 1K LOC upgrade should not produce the same ceremony as a 200K LOC rewrite. -- **1.4K LOC, 1 module, rewrite (cross-stack migration)**: ~4 fragments. Most ceremony is overhead — single worker holds full context, features are obvious from code, target architecture is straightforward. deep_planning MUST be false. Skip coordination fragments (constitution, implementation-plan, quality-gate-plan, test-strategy), inventory fragments (feature-inventory, feature-parity-signoff), and detailed review fragments (arch-design, arch-review, security-review) unless the project has specific complexity signals (auth flows, data model changes, etc.). +- **1.4K LOC, 1 module, rewrite (cross-stack migration)**: ~5 fragments. Most ceremony is overhead — single worker holds full context, features are obvious from code, target architecture is straightforward. deep_planning MUST be false. Skip coordination fragments (constitution, implementation-plan, quality-gate-plan, test-strategy), inventory fragments (feature-inventory, feature-parity-signoff), and detailed review fragments (arch-design, arch-review, security-review) unless the project has specific complexity signals (auth flows, data model changes, etc.). Include cve-remediation — even a small cross-stack rewrite adopts a new dependency manifest that must be scanned. -- **12K LOC, single module, upgrade (version bump)**: ~3 fragments. Same-stack upgrade needs analysis, an implementation plan to sequence changes, and runtime validation. No new architecture, no feature changes, no DB changes. +- **12K LOC, single module, upgrade (version bump)**: ~4 fragments. Same-stack upgrade needs analysis, an implementation plan to sequence changes, cve-remediation (the version bump alters the dependency set, so re-scan and patch), and runtime validation. No new architecture, no feature changes, no DB changes. -- **50K LOC, 3 modules, rewrite (cross-stack)**: ~13 fragments. Multiple modules and cross-stack migration justify full ceremony — coordination, inventory, architecture, implementation planning, reviews, and validation. +- **50K LOC, 3 modules, rewrite (cross-stack)**: ~14 fragments. Multiple modules and cross-stack migration justify full ceremony — coordination, inventory, architecture, implementation planning, cve-remediation (the new stack adopts dependencies that must be CVE-scanned), reviews, and validation. -- **200K LOC, 8 modules, extract (module separation)**: ~14 fragments. Large-scale extraction with new service boundaries needs nearly all fragments except feature inventory (scope is one module with known API). +- **200K LOC, 8 modules, extract (module separation)**: ~15 fragments. Large-scale extraction with new service boundaries needs nearly all fragments except feature inventory (scope is one module with known API); cve-remediation applies because the extracted modules carry their dependency sets forward. -- **80K LOC, upgrade (dependency bump only)**: ~1 fragment. Pure dependency update — only runtime-validation needed to gate the build. +- **80K LOC, upgrade (dependency bump only)**: ~2 fragments. Pure dependency update — cve-remediation (the bump is exactly the dependency-set change that warrants a CVE scan; a clean scan is a cheap no-op) plus runtime-validation to gate the build. diff --git a/plugins/github-copilot-modernization/skills/data-architecture/SKILL.md b/plugins/github-copilot-modernization/skills/data-architecture/SKILL.md index 618a3f6..230d9dc 100644 --- a/plugins/github-copilot-modernization/skills/data-architecture/SKILL.md +++ b/plugins/github-copilot-modernization/skills/data-architecture/SKILL.md @@ -11,6 +11,61 @@ Analyze the project to document database configuration, entity models, data owne - `workspace-path` (optional): Path to the project to analyze (defaults to current directory) +## ⚠ Mermaid Safety Constraints — read BEFORE you write the ```mermaid block + +Mermaid `erDiagram` has a stricter grammar than flowchart. One bad attribute line or one stray `{` crashes the **whole** diagram with `Syntax error in text`. Stay strictly inside this subset: + +1. **Chart kind.** `erDiagram` only. +2. **Attribute grammar — exact shape.** Every attribute line inside an entity body MUST match: + + ``` + [] [""] + ``` + + - `` / ``: single tokens, plain text (letters, digits, underscore). No spaces, no backticks, no `@#$%&`. + - ``: optional. **Exactly one of** `PK`, `FK`, `UK` — never two, never combined. Compound tokens like `PK_FK`, `PKFK`, `PK/FK` crash the parser. + - ``: optional, must be a double-quoted string on one line. Free text, but obey rule 4. +3. **Relationships.** ` -- : "label"`. Each side independently picks `||` (exactly one), `|o`/`o|` (zero or one), `}o`/`o{` (zero or many), or `}|`/`|{` (one or many). The open side of `o`/`}`/`{` faces inward toward `--`. Always quote the label. +4. **Banned characters inside any quoted description or relationship label:** + + | Banned | Why it breaks | Replacement | + |---|---|---| + | `\n` (literal two chars) | escape removed | drop, or shorten | + | `{` `}` | opens an entity block | use `<...>` for placeholders, e.g. `"Redis key /basket/"` | + | `"` (a second double-quote) | closes description early | `'` (single quote) | + | `` ` `` (backtick) | not part of grammar | drop | + | `—` `–` (em/en dash) | parser may treat as edge | `-` (ASCII hyphen) | + | smart quotes `"` `"` `'` `'` | not ASCII | regular `"` and `'` | + | `@` `#` `$` `%` `&` | unsafe in names/descriptions | rephrase or drop | + +5. **Composite PK that is also FK.** Mark every column as `PK` only and note the FK role inside the quoted description. The FK relationship is already shown by the cardinality arrow — duplicating it as a second key marker crashes the parser. + +### Canonical attribute examples (copy these shapes) + +``` +int Id PK +string Name +int OwnerId FK +int InstructorId PK "also FK to Person (shared PK)" +int CourseId PK "composite PK; FK to Course" +int StudentId PK "composite PK; FK to Person" +string Email UK "unique" +decimal Budget "money column" +bytes RowVersion "concurrency token" +``` + +### Mandatory self-attestation + +Immediately before writing the ` ```mermaid ` opening fence, emit this exact one-line HTML comment in the markdown (it does not render — it is for your own visible attestation): + +``` + +``` + +If you cannot truthfully emit that comment, fix the diagram first. + +--- + ## Scope Boundaries — Avoid Redundancy with Other Skills This skill is part of a set of four complementary assessment skills. To avoid content duplication across their output documents, observe these scope rules: @@ -69,8 +124,9 @@ Identify: - Include relationship labels - Annotate which service owns each entity group (use comments or subgraph labels) -Example: +Reference example (this block satisfies every Safety Constraint — match its shape): + ~~~mermaid erDiagram Owner ||--o{ Pet : "has" @@ -198,68 +254,23 @@ A brief introduction (1-2 sentences) summarizing the data layer. - Collapse join tables into relationship annotations rather than showing them as separate entities - In the repository methods table, focus on non-CRUD custom methods; omit standard inherited methods -## Mermaid Syntax Rules - -Use `erDiagram`. The diagram must parse cleanly under the official Mermaid grammar — anything outside it crashes the whole diagram, not just the offending line. Stay inside the minimal legal subset below. - -### Attribute grammar - -Every attribute line inside an entity body MUST follow exactly this shape: - -``` - [] [""] -``` - -- `` and ``: single tokens, plain text (letters, digits, underscore). No spaces, no backticks, no `@#$%&`. -- ``: optional. **Exactly one of** `PK`, `FK`, `UK` — never two, never combined. Compound tokens like `PK_FK`, `PKFK`, `PK/FK` are not part of the grammar. -- ``: optional, must be a double-quoted string. The description is free text BUT must not contain `{`, `}`, or unescaped double quotes. - -### Canonical attribute examples (copy these shapes) - -``` -int Id PK -string Name -int OwnerId FK -int InstructorId PK "also FK to Person (shared PK)" -int CourseId PK "composite PK; FK to Course" -int StudentId PK "composite PK; FK to Person" -string Email UK "unique" -decimal Budget "money column" -bytes RowVersion "concurrency token" -``` - -Rule of thumb for **composite primary keys whose columns are also foreign keys** (join tables like `CourseAssignment`, shared-PK one-to-one tables like `OfficeAssignment`): mark every column as `PK` only, and note the FK role in the quoted description. The FK relationship itself is already conveyed by the cardinality arrows between entities — duplicating it as a second key marker is what crashes the parser. - -### Relationships - -- Cardinality is written as `--`, where each side independently picks one of: - - `||` — exactly one - - `|o` / `o|` — zero or one - - `}o` / `o{` — zero or many - - `}|` / `|{` — one or many - The "open" side of `o`/`}`/`{` always faces inward (toward the `--`). All resulting combinations are legal, e.g. `||--o{` (one-to-many), `||--||` (one-to-one), `}o--o{` (many-to-many), `}o--||` (many-to-one), `|o--o{` (zero-or-one to many), `||--o|` (one to zero-or-one). -- Always quote the label: `Owner ||--o{ Pet : "has"`. -- The label is free text but must not contain `{`, `}`, or unescaped double quotes. - -### Hard prohibitions (these crash the whole diagram, not just one line) - -1. **No `{` or `}` inside any quoted description or label.** Mermaid's ER parser treats `{` as the entity-body opener even inside quotes. Use `<...>` for placeholders, or rephrase in plain words. - - ❌ `string Key PK "Redis key /basket/{BuyerId}"` - - ✅ `string Key PK "Redis key /basket/"` -2. **No more than one key marker per attribute.** See the grammar above. -3. **No backticks, no special characters (`@#$%&`) in entity names, attribute names, or types.** -4. **No `\n` anywhere in the diagram.** The literal `\n` escape was removed in modern Mermaid (>= 9.x) and triggers "Syntax error in text". Keep every quoted description on a single line; if you need to express more, shorten the prose or split it across multiple attributes. - - ❌ `string Roles "comma-separated\nROLE_USER, ROLE_ADMIN"` - - ✅ `string Roles "comma-separated; ROLE_USER, ROLE_ADMIN"` +## Common failure patterns observed in past runs -### Self-check before emitting the diagram +Each row below is something the model actually produced that crashed the diagram. Use the ✅ form. -Before writing the ```` ```mermaid ```` block, walk every attribute line and verify it matches ` [] [""]` with **at most one** key token. Walk every quoted string and verify it contains no `{` or `}`. If a description needs to express two key roles (e.g., composite PK that is also FK), encode the second role as plain text inside the quoted description — never as a second token before the quote. +| ❌ Past mistake | ✅ Safe form | Why the ❌ crashed | +|---|---|---| +| `int OwnerId PK_FK` | `int OwnerId PK "FK to Owner"` | Compound key marker is not in grammar | +| `int OwnerId PK FK` | `int OwnerId PK "also FK to Owner"` | Two key markers on one line | +| `string Key PK "Redis key /basket/{BuyerId}"` | `string Key PK "Redis key /basket/"` | `{` opens an entity block even inside quotes | +| `string Roles "comma-separated\nROLE_USER, ROLE_ADMIN"` | `string Roles "comma-separated; ROLE_USER, ROLE_ADMIN"` | Literal `\n` | +| `string user-name` | `string userName` | `-` not allowed in attribute name | +| `Owner ||--o{ Pet : has` | `Owner ||--o{ Pet : "has"` | Relationship label must be quoted | ## Error Handling - **Unsupported project type**: Output a single line: `> ERROR: Unsupported project type. This skill supports Java, .NET, JavaScript, and TypeScript projects only.` -- **No data access layer found**: Output: `> ERROR: No recognized data access patterns or entities found at {workspace-path}. Verify the path is correct.` +- **No data access layer found**: Output: `> ERROR: No recognized data access patterns or entities found at workspace-path. Verify the path is correct.` - **Insufficient info**: Generate a best-effort diagram from available data. Add a note: `> Note: Some entities or relationships could not be fully identified.` ## Success Criteria @@ -271,4 +282,5 @@ Before writing the ```` ```mermaid ```` block, walk every attribute line and ver - Caching strategy section describes cache providers, patterns, and rationale - Data ownership boundaries describe shared vs isolated stores and cross-service data access patterns - Data Classification & Sensitivity table identifies PII/PHI/PCI fields and documents presence or absence of controls +- The ```mermaid block is preceded by the `` attestation comment - File saved to `.github/modernize/assessment/engines/facts/data-architecture.md` diff --git a/plugins/github-copilot-modernization/skills/dependency-map/SKILL.md b/plugins/github-copilot-modernization/skills/dependency-map/SKILL.md index 6b74fab..b347373 100644 --- a/plugins/github-copilot-modernization/skills/dependency-map/SKILL.md +++ b/plugins/github-copilot-modernization/skills/dependency-map/SKILL.md @@ -13,6 +13,44 @@ This skill focuses exclusively on **declared external dependencies** (libraries, - `workspace-path` (optional): Path to the project to analyze (defaults to current directory) +## ⚠ Mermaid Safety Constraints — read BEFORE you write the ```mermaid block + +Mermaid is unforgiving: one illegal character anywhere in the block crashes the **whole** diagram with `Syntax error in text`, not just the offending line. Stay strictly inside this subset: + +1. **Chart kind.** `flowchart LR` only. +2. **Subgraph form.** Always `subgraph ["display label"]` (id matches `[A-Za-z][A-Za-z0-9_]*`, no spaces, no punctuation). NEVER use the anonymous form `subgraph "label"` — it crashes whenever the label contains `(`, `)`, `/`, `-`, etc. +3. **Node form.** Use `Id["label"]` for libraries; pick one shape per node — do not stack brackets. +4. **Arrow form.** Solid `-->`, dotted `-.->` for transitive/indirect. Arrow labels MUST be double-quoted: `-->|"persistence"|`. Never bare `-->|persistence|`. +5. **No line breaks in labels.** The escape `\n` was removed in modern Mermaid and is the #1 cause of failures. Keep labels on one line (e.g., `"Spring Boot 2.7.18"` not `"Spring Boot\n2.7.18"`). +6. **Banned characters inside any label or subgraph title.** Use the ASCII replacement: + + | Banned | Why it breaks | Replacement | + |---|---|---| + | `\n` (literal two chars) | escape removed | drop, or `
` | + | `—` (em-dash, U+2014) | parser treats as edge | `-` (ASCII hyphen) | + | `–` (en-dash, U+2013) | parser treats as edge | `-` | + | `{` `}` | opens an entity block | drop braces | + | `"` inside a label | closes the label early | `'` (single quote) | + | `\|` inside a label | breaks edge-label parser | rephrase | + | `@` `#` `$` `%` `&` | unsafe | rephrase or drop | + | `(` `)` outside `["..."]` | unbalanced parens crash | only inside the quoted label | + | smart quotes `"` `"` `'` `'` | not ASCII | regular `"` and `'` | + +7. **Unique node IDs across the whole diagram.** No two nodes/subgraphs may share an id. +8. **`subgraph` must be closed by a matching `end` on its own line.** + +### Mandatory self-attestation + +Immediately before writing the ` ```mermaid ` opening fence, emit this exact one-line HTML comment in the markdown (it does not render — it is for your own visible attestation): + +``` +|"label"|, all subgraphs closed by end, ids unique --> +``` + +If you cannot truthfully emit that comment, fix the diagram first. + +--- + ## Execution Steps ### Step 1: Generate Dependencies Section @@ -53,15 +91,16 @@ Rules: - If a dependency doesn't fit any category, put it under "Utilities" - Collect test-scoped dependencies separately for the Test Dependencies section (Step 2) -**Diagram — Mermaid `flowchart LR`:** +**Diagram — Mermaid `flowchart LR`** (re-read the Safety Constraints above before writing): - Application as the central left-side node -- One `subgraph` per functional category -- Each dependency as a node showing name and version: `Lib["Library Name v1.2.3"]` +- One `subgraph` per functional category, using the `subgraph Id["display label"]` form +- Each dependency as a node showing name and version: `Lib["Library Name 1.2.3"]` (single line, no `\n`) - Arrows from Application to each category subgraph - If a BOM/parent POM manages versions, show it as a separate node linked to the dependencies it governs -Example: +Reference example (this block satisfies every Safety Constraint — match its shape): +|"label"|, all subgraphs closed by end, ids unique --> ~~~mermaid flowchart LR App["MyApplication"] @@ -74,7 +113,7 @@ flowchart LR Hibernate["Hibernate 5.6"] PgDriver["PostgreSQL Driver 42.6"] end - subgraph Messaging + subgraph Messaging["Messaging"] Kafka["Kafka Client 3.4"] end subgraph Cache["Caching"] @@ -154,35 +193,22 @@ Total test-scope dependencies: N - Keep the diagram under **40 nodes** to ensure readability and GitHub rendering compatibility - For multi-module projects (e.g., multi-module Maven/Gradle, multi-project .sln), show shared dependencies once and module-specific dependencies grouped by module -## Mermaid Syntax Rules - -The diagram must parse cleanly under **Mermaid >= 9.x**. Anything outside the legal subset crashes the entire diagram with `Syntax error in text`. - -- Use `flowchart LR` -- Avoid special characters (`@`, `#`, `$`, `%`, `&`) in node labels — use plain text -- Always quote arrow labels with double quotes: `-->|"label"|` -- Use `subgraph` for grouping, with a display name in quotes if it contains spaces -- Use `-.->` (dotted arrow) for transitive/indirect relationships -- Verify all node IDs are unique across the entire diagram - -### Line breaks in node labels — HARD RULE - -- **NEVER use `\n` for line breaks inside node labels.** The literal `\n` escape was removed in modern Mermaid and is the #1 cause of "Syntax error in text". -- **Use `
` instead**: `Node["First line
Second line"]`. -- Prefer single-line labels; move detail into the inventory table. -- ❌ `Spring["Spring Boot\n2.5.12"]` -- ✅ `Spring["Spring Boot
2.5.12"]` or `Spring["Spring Boot 2.5.12"]` +## Common failure patterns observed in past runs -### Self-check before emitting each ```mermaid block +Each row below is something the model actually produced that crashed the diagram. Use the ✅ form. -1. Search the block for the two characters `\n` — replace each with `
`. Zero `\n` must remain. -2. Confirm every node ID is unique and every `subgraph` is closed by `end`. -3. Confirm every arrow label is double-quoted. +| ❌ Past mistake | ✅ Safe form | Why the ❌ crashed | +|---|---|---| +| `subgraph "Database / ORM"` | `subgraph DB["Database / ORM"]` | Anonymous subgraph + `/` in title | +| `Spring["Spring Boot\n2.5.12"]` | `Spring["Spring Boot 2.5.12"]` | Literal `\n` | +| `App -->\|persistence\| DB` | `App -->\|"persistence"\| DB` | Bare arrow label | +| `Lib["Spring Boot — 2.5"]` | `Lib["Spring Boot - 2.5"]` | em-dash inside label | +| `Lib["foo {bar}"]` | `Lib["foo bar"]` | `{}` inside label | ## Error Handling - **Unsupported project type**: Output a single line: `> ERROR: Unsupported project type. This skill supports Java, .NET, JavaScript, and TypeScript projects only.` -- **No build files found**: Output: `> ERROR: No recognized build files found at {workspace-path}. Verify the path is correct.` +- **No build files found**: Output: `> ERROR: No recognized build files found at workspace-path. Verify the path is correct.` - **Incomplete dependency info**: Generate a best-effort diagram from available data. Add a note inside the diagram: `Note["Some dependencies could not be fully resolved"]` ## Success Criteria @@ -193,4 +219,5 @@ The diagram must parse cleanly under **Mermaid >= 9.x**. Anything outside the le - Version & Compatibility Risks paragraph highlights outdated or end-of-life dependencies - Notable Observations lists 2-4 noteworthy findings - Test Dependencies section lists detected test frameworks with versions and total count +- The ```mermaid block is preceded by the `` attestation comment - File saved to `.github/modernize/assessment/engines/facts/dependency-map.md` diff --git a/plugins/github-copilot-modernization/skills/implementing-code/SKILL.md b/plugins/github-copilot-modernization/skills/implementing-code/SKILL.md index 3cd86a0..733def5 100644 --- a/plugins/github-copilot-modernization/skills/implementing-code/SKILL.md +++ b/plugins/github-copilot-modernization/skills/implementing-code/SKILL.md @@ -63,6 +63,40 @@ From the task breakdown artifact, find tasks that match your current assignment: Unmet dependency not in current batch → report as blocked. +### Step 5.5: Discover Required API Endpoints (web applications only) + +**Before writing any implementation code**, check whether an endpoint contract test script exists in the project root: + +```bash +for script in api-test.sh api-check.sh smoke.sh health-check.sh test-api.sh; do + test -f "./$script" && echo "found: $script" && break +done +``` + +**If a script is found:** +1. Read its full contents to extract every endpoint it exercises: URL paths, HTTP methods, expected status codes, and expected response shape. +2. Treat every such endpoint as a **mandatory acceptance criterion** for this batch — equivalent to an explicit REQ in the feature spec. Missing even one will cause the post-build evaluation to fail. +3. Cross-check each endpoint against the matched task list. If any script endpoint is absent from the task breakdown, add it as an implicit sub-task in your execution plan (e.g., `T_API_dashboard: Implement GET /api/dashboard`). +4. Record the discovered endpoint list at the top of `batch-report.yaml` under `required_endpoints`: + ```yaml + required_endpoints: + - method: GET + path: /api/dashboard + source: api-test.sh + status: pending # updated to "implemented" when the endpoint is wired up and verified + - method: GET + path: /api/items + source: api-test.sh + status: pending + ``` + +**If no script is found:** +- Check `clarification.md` (if present) for any explicitly listed required API endpoints. +- Check the feature spec for API contract sections. +- If neither source provides an endpoint list, proceed without this step. + +This discovery step ensures that evaluation scripts are treated as first-class requirements from the start of implementation — not discovered only at post-build verification when fixes are costly. + ### Step 6: Execute **Ordering:** @@ -98,6 +132,99 @@ For tasks marked `[GUIDELINE:skill-name]`: - Halt on non-parallel task failure - For `[P]` tasks: continue successful ones, report failures +### Step 6.5: JS/TS Scaffolding Validation Gate (JS/TS projects only) + +**After any scaffolding step that generates or modifies a `package.json`**, execute this gate before proceeding to the next task. This gate is MANDATORY for all JavaScript and TypeScript projects. + +#### 6.5.1 — Verify required npm scripts + +Check that `package.json` contains BOTH a `build` script AND a `test` script: + +```bash +node -e " + const pkg = require('./package.json'); + const missing = ['build','test'].filter(s => !pkg.scripts || !pkg.scripts[s]); + if (missing.length) { console.error('MISSING scripts:', missing.join(', ')); process.exit(1); } + console.log('scripts OK: build=' + pkg.scripts.build + ', test=' + pkg.scripts.test); +" +``` + +**If either script is missing**, inject it immediately — do NOT defer: + +| Framework | Missing `test` script | Missing `build` script | +|-----------|----------------------|----------------------| +| Angular (`@angular/core` in deps) | `"test": "ng test --watch=false --browsers=ChromeHeadless"` | `"build": "ng build"` | +| React / Vite | `"test": "vitest run"` or `"test": "react-scripts test --watchAll=false"` | `"build": "vite build"` | +| React / CRA | `"test": "react-scripts test --watchAll=false --ci"` | `"build": "react-scripts build"` | +| Vue / Vite | `"test": "vitest run"` | `"build": "vite build"` | +| Next.js | `"test": "jest --ci"` | `"build": "next build"` | +| NestJS / Node | `"test": "jest --ci"` | `"build": "nest build"` | +| Generic TS | `"test": "jest --ci"` | `"build": "tsc"` | + +After injecting, confirm the script was written and re-verify with the check above. + +#### 6.5.2 — Run the test script + +After confirming both scripts exist, execute: + +```bash +npm test +``` + +(or `yarn test` / `pnpm test` if the project uses those package managers) + +- **Exit code 0**: gate passes — proceed. +- **Exit code != 0**: enter a remediation loop (max 3 iterations): + 1. Read the failure output to identify the root cause (missing browser binary, missing test files, misconfigured jest config, etc.) + 2. Fix the cause (install missing dev dependency, create a minimal placeholder test, fix config) + 3. Re-run `npm test` + 4. If still failing after 3 iterations, record the failure in `batch-report.yaml` under `warnings` with severity HIGH and continue — do NOT block the entire batch: + ```yaml + warnings: + - severity: HIGH + message: "npm test failed after 3 remediation attempts — " + ``` + +> **Why this gate exists**: Eval harnesses run `npm test` unconditionally. A scaffolded project without a `test` script causes an immediate fatal error (`npm error Missing script: "test"`) that masks all other results. Catching this at scaffolding time costs ~5 seconds; missing it causes total batch failure. + +### Step 6.6: API Endpoint Verification (web-application backends only) + +For any batch that produces or modifies a web-application backend (Spring Boot, Express, NestJS, FastAPI, Django, ASP.NET Core, Go HTTP servers, and similar), verify endpoints **respond correctly at runtime** before the batch is considered complete. A passing build proves only compilation, not that routes are wired up. + +#### 6.6.1 — Run the discovered endpoint contract (if any) + +If Step 5.5 found an endpoint contract script (`api-test.sh`, `api-check.sh`, …), start the application if not already running, then execute it: + +```bash +bash ./api-test.sh # or whichever script Step 5.5 recorded +echo "api-test exit code: $?" +``` + +- **Exit code 0** → all endpoint assertions pass → proceed. +- **Exit code != 0** → enter the fix loop (max 3 iterations): + 1. Read the output to identify which endpoints returned errors (missing route, wrong status code, unexpected body). + 2. Implement or correct the backend endpoint(s): add the missing controller/handler, fix route mapping, return the expected response shape. + 3. Re-run the script. Repeat until exit code is 0 or 3 iterations are exhausted. + 4. If still failing after 3 iterations, record the failure in `batch-report.yaml` under `warnings` with severity HIGH and escalate via `[notify:coordinator]` — do NOT mark the affected endpoints `implemented`. + +#### 6.6.2 — Manual probe (no script found) + +If no endpoint contract script exists, probe every REST endpoint the batch implemented after starting the application: + +```bash +curl -sf -o /dev/null -w "%{http_code}" http://localhost: +``` + +Every implemented endpoint MUST return a 2xx status code. A 404 or 500 means the route is not wired correctly — fix before completing the batch. Record probe results in the batch report under `endpoint_probes`: + +```yaml +endpoint_probes: + - method: GET + path: /api/dashboard + status: 200 + result: PASS +``` + ### Step 7: Write Checkpoint After ALL tasks in this batch complete, write `checkpoints/tasks-to-impl.yaml` using `templates/tasks-to-impl-checkpoint-template.yaml`. This is REQUIRED — completeness gate reads it to verify traceability. @@ -106,6 +233,13 @@ After ALL tasks in this batch complete, write `checkpoints/tasks-to-impl.yaml` u Generate batch result report per `references/batch-report-format.md` (YAML format). +**If `required_endpoints` was populated in Step 5.5**, update each entry's `status` to `"implemented"` once the corresponding endpoint is wired up and verified to respond correctly. Any entry still `"pending"` at report time is a gap — record it under `warnings` with severity HIGH: +```yaml +warnings: + - severity: HIGH + message: "Endpoint GET /api/dashboard was required by api-test.sh but not implemented in this batch" +``` + ## Resources ### References diff --git a/plugins/github-copilot-modernization/skills/implementing-code/references/batch-report-format.md b/plugins/github-copilot-modernization/skills/implementing-code/references/batch-report-format.md index 7fd6865..5db0054 100644 --- a/plugins/github-copilot-modernization/skills/implementing-code/references/batch-report-format.md +++ b/plugins/github-copilot-modernization/skills/implementing-code/references/batch-report-format.md @@ -18,6 +18,21 @@ files_changed: - file: "path/to/another-file" change_type: "modified" description: "Brief description of change" +# Role-neutral upstream artifact consumption (required when dependency artifacts exist) +upstream_artifacts_consumed: + T001: + - artifact: "artifacts/t1-architect-wire-contracts.md" + used_for: "HTTP endpoint contracts and JSON response keys" + - artifact: "artifacts/units/request_action/behavior.yaml" + used_for: "request form branches and save side effects" +evidence_mapping: + T001: + - upstream: "artifacts/t1-architect-wire-contracts.md#POST /saverequest" + output: "src/main/java/.../RequestController.java#saveRequest" + evidence: "RequestControllerTest#saveRequest_*" + - upstream: "artifacts/units/request_action/behavior.yaml#branches" + output: "src/main/java/.../RequestController.java" + evidence: "branch tests pass" # Source-anchored traceability (rewrite mode only) source_references: T001: @@ -62,6 +77,8 @@ test_results: | `completed_tasks` | Yes | List of task IDs successfully completed | | `blocked_tasks` | Yes | Tasks that couldn't run due to unmet dependencies | | `files_changed` | Yes | Per-task list of files created/modified/deleted | +| `upstream_artifacts_consumed` | When dependency artifacts exist | Upstream artifacts read by each task and what each was used for | +| `evidence_mapping` | When dependency artifacts exist | Upstream artifact contract/row/section → this task's output and verification evidence | | `source_references` | Rewrite mode | Source-anchored traceability: files read, branches/validations/errors/side-effects preserved | | `traceability` | Yes | REQ → Plan → Task → Files mapping | | `protocol_violation` | Yes | Whether any constitution principle was violated | diff --git a/plugins/github-copilot-modernization/skills/modernization-integration-tests/SKILL.md b/plugins/github-copilot-modernization/skills/modernization-integration-tests/SKILL.md index 6f0688c..2874f08 100644 --- a/plugins/github-copilot-modernization/skills/modernization-integration-tests/SKILL.md +++ b/plugins/github-copilot-modernization/skills/modernization-integration-tests/SKILL.md @@ -11,40 +11,38 @@ user-invocable: true disable-model-invocation: false --- -# Integration Tests for Modernized Java Applications - ## Language Support **This skill supports Java projects only.** If the source code is not Java (e.g., .NET, Python, Node.js), skip test generation and report that integration tests are not supported for this language. ## User Input - **layer** (Optional): Which layer to test (1, 2, 3, or 4). Default: 1 -- **azure-config** (Optional, Layer 3 only): Azure environment configuration -- **modernization-work-folder** (Optional): Directory path for generating plan and summary files. Default: `.github/integration-tests` +- **azure-config** (Optional, Layer 3 only): Azure environment configuration. If not provided, read from `./infra/infra-config.md` or use request tool to obtain configuration. +- **modernization-work-folder** (Optional): Directory path for generating plan and summary files. Default: `.github` - **test-root** (Optional): The root directory for integration tests. Default: current working directory. All application modules found in the directory are included in integration tests. ## Available references ### Layer 1: Local Integration Tests -**Read references/layer1-local-integration.md first**, then create TestContainers-based integration test classes. +**Read [references/layer1-local-integration.md](references/layer1-local-integration.md) first**, then create TestContainers-based integration test classes. ### Layer 2: Smoke Tests -**Read references/layer2-smoke-tests.md first.** Layer 2 uses shell-based smoke tests with docker-compose, NOT JUnit test classes. Follow the exact multi-commit workflow (artifacts → auth → restore) documented in the reference file. +**Read [references/layer2-smoke-tests.md](references/layer2-smoke-tests.md) first.** Layer 2 uses shell-based smoke tests with docker-compose, NOT JUnit test classes. Follow the exact multi-commit workflow (artifacts → auth → restore) documented in the reference file. ### Layer 3: Azure Integration Tests -**Read references/layer3-azure-integration.md first**, then create integration test classes that connect to real Azure services. +**Read [references/layer3-azure-integration.md](references/layer3-azure-integration.md) first**, then create integration test classes that connect to real Azure services. ### Layer 4: Behavioral Comparison -**Read references/layer4-behavioral-comparison.md first**, then create comparison tests that validate behavior matches between old and new implementations. +**Read [references/layer4-behavioral-comparison.md](references/layer4-behavioral-comparison.md) first**, then create comparison tests that validate behavior matches between old and new implementations. ### TestContainers Coding References -- **Azure Service Bus with TestContainers Coding Reference**, see references/azure-servicebus-testcontainers.md -- **Azure Storage with TestContainers Coding Reference**, see references/azure-storage-testcontainers.md +- **Azure Service Bus with TestContainers Coding Reference**, see [references/azure-servicebus-testcontainers.md](references/azure-servicebus-testcontainers.md) +- **Azure Storage with TestContainers Coding Reference**, see [references/azure-storage-testcontainers.md](references/azure-storage-testcontainers.md) ## Workflow 1. Analyze the project to identify modules that need to be tested and any existing integration tests. If git history is available, analyze past commits to understand which components were modified during modernization and prioritize testing those areas. -2. Create an integration test plan file at `{modernization-work-folder}/integration-test-plan.md` that outlines: +2. Create an integration test plan file at `{modernization-work-folder}/integration-tests/integration-test-plan.md` that outlines: - Testing strategy and approach for the detected app modules - Testing strategy and approach for each layer - Identified components requiring integration testing @@ -58,7 +56,7 @@ disable-model-invocation: false - Fix test code if the failure is due to unrealistic test scenarios, incorrect test setup. - Execute tests again after fixes 6. **Only proceed when all tests run and pass**, or exit after 20 attempts -7. Create an integration test summary file at `{modernization-work-folder}/integration-test-summary.md` that documents: +7. Create an integration test summary file at `{modernization-work-folder}/integration-tests/integration-test-summary.md` that documents: - All integration tests added (with file paths and descriptions) - Test coverage improvements achieved - Final test execution results @@ -67,7 +65,7 @@ disable-model-invocation: false ## Integration Tests Writing Principles **CRITICAL - Read Reference Docs First:** -- **Before starting ANY layer**, read the corresponding reference file in references/ directory +- **Before starting ANY layer**, read the corresponding reference file in [references/](./references/) directory Analyze the project if integration tests have covered all components, if not **DO ADD** new integration tests by the following principles: @@ -85,7 +83,7 @@ Analyze the project if integration tests have covered all components, if not **D - **DO NOT** add extra modules for integration tests, write integration tests in the existing modules. - **DO commit** changes separately for each layer with meaningful commit messages. Do not combine changes from different layers into a single commit. - **Layer 1, 3, 4**: Single commit per layer (e.g., `Add Layer 1 local integration tests`). Generate runner scripts and include them in the same commit. - - **Layer 2**: Multi-commit sequence as defined in references/layer2-smoke-tests.md (artifacts → auth → restore). **CRITICAL: Layer 2 does NOT create test classes - it uses shell-based smoke tests with docker-compose.** Runner scripts are part of the artifacts commit. + - **Layer 2**: Multi-commit sequence as defined in [layer2-smoke-tests.md](./references/layer2-smoke-tests.md) (artifacts → auth → restore). **CRITICAL: Layer 2 does NOT create test classes - it uses shell-based smoke tests with docker-compose.** Runner scripts are part of the artifacts commit. ### Test Isolation Convention @@ -97,13 +95,13 @@ When multiple layers coexist in the same project, tests must be distinguishable. | Layer | Class Name Suffix | Example Class Name | |-------|-------------------|--------------------| | 1 | `L1Test` | `BlobStorageL1Test`, `OrderServiceL1Test` | -| 2 | N/A - No test classes | Layer 2 uses shell-based smoke tests, not test classes. See references/layer2-smoke-tests.md | +| 2 | N/A - No test classes | Layer 2 uses shell-based smoke tests, not test classes. See [layer2-smoke-tests.md](./references/layer2-smoke-tests.md) | | 3 | `L3Test` | `AzureSqlL3Test`, `BlobStorageL3Test` | | 4 | `L4Test` | `OrderApiL4Test`, `UserServiceL4Test` | #### Tagging / Category Convention -Test classes for Layers 1, 3, 4 **MUST** be annotated with a layer-specific tag so the runner script can filter precisely. **Layer 2 does not use test classes** (see references/layer2-smoke-tests.md). +Test classes for Layers 1, 3, 4 **MUST** be annotated with a layer-specific tag so the runner script can filter precisely. **Layer 2 does not use test classes** (see [layer2-smoke-tests.md](./references/layer2-smoke-tests.md)). | Layer | JUnit 5 | JUnit 4 | |-------|---------|---------| @@ -169,7 +167,7 @@ When integration tests fail during execution, use this framework to determine wh **Business Logic Violations** - Error indicates source code violates business rules (e.g., negative inventory allowed) - Multiple similar tests fail with same pattern -**Specification Compliance** +**Specification Compliance** - Source code doesn't implement required functionality properly - Error messages show missing or incorrect behavior **Cross-Component Integration Issues** @@ -185,7 +183,7 @@ When integration tests fail during execution, use this framework to determine wh **Test Implementation Issues** - Unrealistic test data or scenarios -- Incorrect test setup (wrong mocks, invalid configurations) +- Incorrect test setup (wrong mocks, invalid configurations) - Testing implementation details rather than behavior - Race conditions or timing issues in test logic **Environmental Problems** @@ -212,12 +210,12 @@ When integration tests fail during execution, use this framework to determine wh ``` Test Failure │ - ├─ Does test model realistic business scenario? + ├─ Does test model realistic business scenario? │ ├─ No → Fix Test Code │ └─ Yes ↓ │ ├─ Does source code violate business rules? - │ ├─ Yes → Fix Source Code + │ ├─ Yes → Fix Source Code │ └─ No ↓ │ ├─ Is test setup and environment correct? @@ -257,7 +255,7 @@ After all tests are written, executed, and fixed to pass, generate a fixed runne ### Runner Script Filtering -**Layers 1, 3, 4** use tag/category filters to execute test classes. **Layer 2 uses shell commands** (see references/layer2-runner-script-templates.md). +**Layers 1, 3, 4** use tag/category filters to execute test classes. **Layer 2 uses shell commands** (see [layer2-runner-script-templates.md](./references/layer2-runner-script-templates.md)). | Layer | Maven | Gradle | |-------|-------|--------| @@ -308,7 +306,7 @@ exit $TEST_EXIT ## Completion Criteria -1. **Integration Test Plan**: Create and output a plan file at `{modernization-work-folder}/integration-test-plan.md` that includes: +1. **Integration Test Plan**: Create and output a plan file at `{modernization-work-folder}/integration-tests/integration-test-plan.md` that includes: - Analysis of existing test coverage gaps - Identified components requiring integration testing - Testing strategy and approach for each component @@ -321,10 +319,10 @@ exit $TEST_EXIT 6. **Version Control**: Commit changes separately for each layer with meaningful commit messages. Do not combine changes from different layers into a single commit. - **Layer 1, 3, 4**: Single commit per layer including test classes and runner scripts (e.g., `Add Layer 1 local integration tests`) - - **Layer 2**: Multi-commit sequence as defined in references/layer2-smoke-tests.md (minimum 3 commits: artifacts → auth → restore). Runner scripts are part of the artifacts commit. + - **Layer 2**: Multi-commit sequence as defined in [layer2-smoke-tests.md](./references/layer2-smoke-tests.md) (minimum 3 commits: artifacts → auth → restore). Runner scripts are part of the artifacts commit. - **Git ignore respect**: Use standard `git add` commands. Do not force-add files. If files in `{modernization-work-folder}` are ignored by the project's `.gitignore`, respect that. -7. **Integration Test Summary**: Create and output a summary file at `{modernization-work-folder}/integration-test-summary.md` that documents: +7. **Integration Test Summary**: Create and output a summary file at `{modernization-work-folder}/integration-tests/integration-test-summary.md` that documents: - All integration tests added (with file paths and descriptions) - Test coverage improvements achieved - Issues identified and resolved (both in source code and test code) @@ -332,13 +330,3 @@ exit $TEST_EXIT - Paths to generated runner scripts and the fixed commands to execute them - Source code changes made during testing and their purpose 8. **Runner Scripts**: Generate standardized runner scripts at `{modernization-work-folder}/integration-tests/run-layer{N}-tests.sh` and `.ps1` (see Standardized Runner Scripts section). The scripts must embed all project-specific commands so users always run the same fixed command. Include runner scripts in the layer's commit (for Layer 2, in the artifacts commit). - -**Resources:** -- references/layer1-local-integration.md -- references/layer2-smoke-tests.md -- references/layer3-azure-integration.md -- references/layer4-behavioral-comparison.md -- references/azure-auth-strategies.md -- references/azure-servicebus-testcontainers.md -- references/azure-storage-testcontainers.md -- references/layer2-runner-script-templates.md diff --git a/plugins/github-copilot-modernization/skills/quality-gates/references/gate-completeness.md b/plugins/github-copilot-modernization/skills/quality-gates/references/gate-completeness.md index 0e59a07..39fd368 100644 --- a/plugins/github-copilot-modernization/skills/quality-gates/references/gate-completeness.md +++ b/plugins/github-copilot-modernization/skills/quality-gates/references/gate-completeness.md @@ -2,6 +2,8 @@ **Load**: constitution, feature spec, plan.md, implementation files, all 3 checkpoints (spec-to-plan.yaml, plan-to-tasks.yaml, tasks-to-impl.yaml) +> **Lite-path note (`deep_planning: false`):** small projects run without a planning phase, so `plan.md`, the feature spec, and the `spec-to-plan` / `plan-to-tasks` checkpoints are legitimately never produced. When they are absent because the lite path skipped `implementation-plan`, treat them as **N/A — not missing/CRITICAL**, and validate against the task list and implementation evidence instead. This note applies throughout the Checklist and Process below. + ## Build Verdict (blocking — evaluate FIRST) Judge build status ONLY from the `## Smoke Test Verdict` block in the smoke-test artifact. @@ -14,13 +16,13 @@ A worker's prose ("build passed") or self-applied label is NOT evidence. Read `b ## Checklist -- [ ] All plan items have corresponding implementation files → *CRITICAL if missing* +- [ ] All plan items have corresponding implementation files → *CRITICAL if missing (lite path with no plan.md: verify implementation evidence against the task list / `tasks-to-impl.yaml` instead)* - [ ] Build succeeds, tests pass — build half: see **Build Verdict** section above; tests half: verify test results in implementation artifacts → *CRITICAL if failure* - [ ] Constitution followed in implementation → *CRITICAL if violated* - [ ] All P1 requirements fulfilled → *CRITICAL if unmet* - [ ] Every implementation task artifact includes `## Test Results` with pass/fail/skip counts and test command → *CRITICAL if missing or failed > 0* - [ ] Testing strategy executed as planned: primary validation stack used; fallback only with documented blocker evidence → *CRITICAL if primary stack skipped without documented failure evidence (exact command + exact error output + explanation why it cannot be resolved). "H2 already worked" or "setup was complex" are not valid blockers. Partial strategy execution (e.g., integration but no E2E when E2E was planned) is also CRITICAL unless a documented, reproducible technical blocker prevented execution.* -- [ ] Functional equivalence verified *(brownfield only: migration and rewrite)* → *CRITICAL if unverified* +- [ ] Consistency verified *(brownfield; change-type-aware)* → *CRITICAL if unverified*: migration / rewrite → functional equivalence (`references/functional-equivalence.md`); upgrade → upgrade-consistency, i.e. no residual old version/API, no mixed old/new across modules (`references/upgrade-consistency.md`) ## Constitution Hardstop Rule @@ -32,12 +34,16 @@ A worker's prose ("build passed") or self-applied label is NOT evidence. Read `b - `checkpoints/spec-to-plan.yaml` - `checkpoints/plan-to-tasks.yaml` - `checkpoints/tasks-to-impl.yaml` + + **Lite-path tolerance (`deep_planning: false`):** when `implementation-plan` was not selected, `spec-to-plan.yaml` and `plan-to-tasks.yaml` are never written — treat them as **N/A, not CRITICAL**, and verify only `tasks-to-impl.yaml` (or equivalent implementation evidence). Do NOT fail the gate for plan-phase checkpoints that the lite path legitimately never creates. 2. Check plan.md Requirement Mapping table Implementation Evidence column 3. Verify all referenced implementation files exist 4. Evaluate build per the **Build Verdict** section (blocking — must be done before advancing); verify tests per implementation task artifacts 5. Verify constitution compliance in code 6. Confirm P1 requirements are implemented -7. For brownfield (migration and rewrite): verify functional equivalence per `references/functional-equivalence.md` +7. Verify the change-type-appropriate consistency check (brownfield): + - migration / rewrite → functional equivalence per `references/functional-equivalence.md` + - upgrade → upgrade-consistency per `references/upgrade-consistency.md` (target version reached everywhere, no residual old API, no mixed old/new versions, deprecated symbols replaced) 8. Verify testing strategy conformance: - Compare planned validation stack (from plan.md testing strategy) against actual test evidence - If primary stack was specified (e.g. Playwright, Testcontainers), confirm it was **actually attempted** (look for dependency in pom.xml/package.json, test files using those tools, or documented installation attempt with error) diff --git a/plugins/github-copilot-modernization/skills/quality-gates/references/upgrade-consistency.md b/plugins/github-copilot-modernization/skills/quality-gates/references/upgrade-consistency.md new file mode 100644 index 0000000..8ff047b --- /dev/null +++ b/plugins/github-copilot-modernization/skills/quality-gates/references/upgrade-consistency.md @@ -0,0 +1,85 @@ +--- +name: Upgrade Consistency Verification +description: Verify that a same-stack upgrade (version bump / SDK or dependency swap) was applied completely and consistently — no residual old version, no mixed old/new usage, every call site migrated. +mode: upgrade +--- + +## Overview + +This is the **consistency arm** of the completeness gate for `change_type: upgrade` +(version bumps, SDK swaps, dependency updates, same-stack modernization — e.g. an +Azure SDK major-version upgrade). Unlike a cross-stack rewrite, an upgrade does not +need *functional equivalence* of rewritten business logic; what matters is that the +upgrade was applied **completely and consistently** across the whole codebase, leaving +no partial-migration state behind. + +A small/simple upgrade is exactly where this check matters most: the multi-agent +ceremony is light, so it is easy to bump a dependency in one module and silently leave +the old API in use elsewhere. + +## When to Use + +- **Mode**: `change_type: upgrade` (same-stack version bump / dependency or SDK swap) +- **Phase**: Completeness Check — invoked by the completeness gate (`gate-completeness.md` step 7) +- **Prerequisites**: Implementation complete; build/smoke-test evidence available +- **Inputs**: the user-specified target (library + version), the project profile + (`assessment.transformations` fromStack/toStack and versions), and the changed files + +## Consistency Definition + +An upgrade is **consistent** when: +- The target library/SDK is at the requested version **everywhere** it is declared +- No source file still imports, references, or calls the **old** API/package/namespace +- No module is left on the **old** version (no mixed old/new across the build) +- Every deprecated/removed symbol from the old version has been replaced +- Configuration, properties, and build/dependency metadata match the new version +- The full build and tests are green (per the **Build Verdict** in `gate-completeness.md`) + +## Checklist (all CRITICAL unless noted) + +- [ ] **Target version reached** — every declaration of the upgraded artifact is at the + requested target version. No declaration left at the old version. → *CRITICAL* +- [ ] **No residual old API** — no remaining imports / package references / namespace + usages / API calls belonging to the old version anywhere in source. Grep the old + package/namespace and confirm zero in-scope hits (excluding generated/vendored code). → *CRITICAL* +- [ ] **No mixed old/new versions** — a single coherent version across all modules and + the dependency/BOM graph; no module still resolves the old version transitively + where it is used directly. → *CRITICAL* +- [ ] **Deprecated/removed symbols replaced** — every symbol removed or deprecated by the + target version has a migrated replacement; none left calling a removed API. → *CRITICAL* +- [ ] **Config & metadata updated** — properties, config files, and build descriptors + reference the new version's expected keys/coordinates, not the old ones. → *HIGH* +- [ ] **Build & tests green** — full root-level build passes and tests pass per the + Build Verdict; no module excluded to make the upgrade "pass". → *CRITICAL* +- [ ] **Target version preserved** — the delivered version matches the user-requested + target verbatim; it was not downgraded or substituted to an LTS/familiar default. → *CRITICAL* + +## Verification Strategy + +1. Read the requested target (library + version) from `user_ask` and + `assessment.transformations` (fromStack/fromStackVersion → toStack/toStackVersion). +2. **Version sweep** — enumerate every place the artifact's version is declared + (e.g. `pom.xml`/`build.gradle`/BOM, `package.json`, lockfiles, `.csproj`). Confirm + all are at the target version; record any left at the old version. +3. **Residual-old sweep** — search the source tree for the old package / namespace / + import / API symbols. Any in-scope hit is a partial migration → CRITICAL. +4. **Mixed-version check** — resolve the effective dependency graph; flag any module + that still uses the old version directly while others use the new one. +5. **Deprecation check** — for symbols removed/deprecated between source and target + versions, confirm each usage was migrated to the replacement. +6. **Config/metadata check** — verify config keys, coordinates, and build descriptors + match the new version. +7. **Build/test confirmation** — confirm the Build Verdict is PASS and tests passed. + +## Report + +Write findings into `migration-summary.md` (the completeness gate's report). Include a +short table of: declarations swept (old→new), residual-old hits (file:line), mixed-version +modules, unmigrated deprecated symbols, and the build/test verdict. + +## Verdict + +- **PASS**: target version reached everywhere, zero residual-old usage, no mixed + versions, deprecated symbols replaced, build/tests green, requested version preserved. +- **FAIL**: any residual old API, any module left on the old version, any unmigrated + removed/deprecated symbol, a downgraded/substituted target, or a non-green/scoped build. diff --git a/plugins/github-copilot-modernization/skills/runtime-validation/SKILL.md b/plugins/github-copilot-modernization/skills/runtime-validation/SKILL.md index 773ec0c..b24c99a 100644 --- a/plugins/github-copilot-modernization/skills/runtime-validation/SKILL.md +++ b/plugins/github-copilot-modernization/skills/runtime-validation/SKILL.md @@ -146,7 +146,9 @@ Beyond Docker and Node.js, verify these additional prerequisites when they apply ### 1.3.2 Legacy Test Asset Inventory -Before finalising the testing strategy, check whether legacy E2E or integration tests are available. They may come from two sources — check both: +Before finalising the testing strategy, identify the project's **canonical test command** — the top-level command used in CI (e.g., `yarn test:unit`, `mvn test`, `pnpm test`, `npm test`). Find it in the root `package.json` scripts, `pom.xml`, or `build.gradle`. Run it first and record the baseline passing count. All new tests written during migration must be reachable by this same command — do not introduce a separate test tool that bypasses it. If a new framework is added (e.g., vitest alongside Jest), it must be wired into the canonical command so both run together. + +Then check whether legacy E2E or integration tests are available. They may come from two sources — check both: **Source 1 — User-provided tests** The user may directly supply test files or paste test code in their request. These take priority over anything discovered on disk. Accept them as-is and skip the file-scan for the journeys they already cover. @@ -407,10 +409,30 @@ Proceed directly to writing new tests from the testing strategy's critical journ When tests fail: 1. Capture test output + application logs -2. Correlate errors to identify root cause -3. **If source code bug** → escalate to responsible role via `[notify:role]`. Do NOT modify production code. -4. **If test code issue** → fix and retry -5. Max 3 fix iterations → escalate remaining via `[notify:coordinator]` +2. **Capture the test command's exit code** (`$?` on Unix/macOS/Linux, `$LASTEXITCODE` on PowerShell). Record it in the evidence block. A non-zero exit code means the tier is FAIL even if some tests passed. +3. Correlate errors to identify root cause +4. **If source code bug** → escalate to responsible role via `[notify:role]`. Do NOT modify production code. +5. **If test code issue** → fix and retry +6. Max 3 fix iterations → escalate remaining via `[notify:coordinator]` + +**Exit-code gate (MANDATORY):** After every test command completes, evaluate: +- `rc == 0` → tier may be PASS (verify pass/fail counts are consistent) +- `rc != 0` → tier is **FAIL**, regardless of reported pass count. Enter fix loop. If after 3 iterations the exit code is still non-zero, write `overall: FAIL` and escalate immediately: + ``` + [notify:coordinator] CRITICAL: Test command exited rc= after 3 fix iterations — task cannot complete. + Command: + Exit code: + Failing tests: + Counts: + ``` + Do NOT write `[DONE]` while any tier has `rc != 0` without a matching waiver. + +**Waiver exception:** The ONLY condition under which `rc != 0` does not block the DONE signal is when ALL of the following hold: +1. A named waiver artifact (e.g., `known-defects.md`) was produced by a prior task and is listed in this task's `## Dependency Artifacts`. +2. Every failing test is listed by name in that artifact with a note that the defect predates this migration. +3. No new failures are present beyond those listed in the waiver. + +If all three conditions hold, record the waiver artifact name in the verdict block and proceed. Otherwise, FAIL. ### 2.4 Step 4: Evidence & Verdict @@ -424,11 +446,15 @@ environment: infra-tier: PRIMARY(Docker-based)|FALLBACK(embedded/in-memory) — browser-tier: PRIMARY(Playwright)|FALLBACK(MockMvc)|SKIPPED — startup: PASS|FAIL — , , -integration: PASS|FAIL|UNVERIFIED — , -e2e: PASS|FAIL|PARTIAL|UNVERIFIED — , , +integration: PASS|FAIL|UNVERIFIED — , , , +e2e: PASS|FAIL|PARTIAL|UNVERIFIED — , , , , overall: PASS|FAIL|NEEDS_SIGNOFF — ``` +> **`exit_code` is REQUIRED in every tier line.** A tier is FAIL if `exit_code != 0`, regardless of the pass/fail counts. Do not omit `exit_code`. +> +> **PASS verdict requires `exit_code: 0`.** If any tier has `exit_code != 0` and no named waiver artifact covers all failing tests by name, `overall` MUST be `FAIL`. A partial-pass count (e.g., "59/61 passed") with `exit_code: 2` is still `FAIL`. + Also produce `runtime-validation-report.md`: ```markdown @@ -438,11 +464,11 @@ Also produce `runtime-validation-report.md`: **Target**: [project path] ## Summary -| Step | Status | Details | -|------|--------|---------| -| Startup | ✓ PASS | Started in 8.3s, /actuator/health → 200 | -| Integration Tests | ✓ PASS | 3 test files, 12 tests, all green | -| E2E Tests | N/A | No browser UI — skipped per testing strategy | +| Step | Status | Exit Code | Details | +|------|--------|-----------|---------| +| Startup | ✓ PASS | n/a | Started in 8.3s, /actuator/health → 200 | +| Integration Tests | ✓ PASS | 0 | 3 test files, 12 tests, all green | +| E2E Tests | N/A | n/a | No browser UI — skipped per testing strategy | **Overall**: PASS diff --git a/plugins/github-copilot-modernization/skills/team-request/SKILL.md b/plugins/github-copilot-modernization/skills/team-request/SKILL.md new file mode 100644 index 0000000..903018f --- /dev/null +++ b/plugins/github-copilot-modernization/skills/team-request/SKILL.md @@ -0,0 +1,33 @@ +--- +name: team-request +description: How team members request infrastructure connection info and handle secrets in team mode +--- + +# Team requests + +This skill is automatically loaded for all team members in team mode. It defines the requests that team members can make to each other. + +## Requesting Infrastructure Connection Info + +When your task requires connection to real Azure resources (databases, queues, storage, etc.), use the `request` tool to ask the **InfrastructureExpert** for connection values. + +**What the InfrastructureExpert provides:** +- Connection strings (e.g., for databases, message queues, storage) +- Endpoint URLs with managed identity configuration +- Confirmation of resource changes you requested + +**Workflow:** +1. Before performing work that requires real resource connections, call: + ``` + request(from: "", to: "", taskId: "", message: "I need the connection string for the PostgreSQL database") + ``` +2. The response contains ONLY the connection values — no subscription/RG/resource IDs. +3. Use the returned values to configure your code or tests. + +**Requesting resource changes:** +If you need a resource modification (e.g., create a test database, add a firewall rule, create a queue, assign a role), use the `request` tool with a message describing the change. Do NOT attempt to run `az` commands yourself for resource provisioning. + +Example: +``` +request(from: "ITTester", to: "InfraExpert", taskId: "003-integrationTest", message: "Create a test database named 'app_test' on the PostgreSQL server and return the connection string with managed identity auth") +``` diff --git a/plugins/github-copilot-modernization/skills/verify-test-baseline/SKILL.md b/plugins/github-copilot-modernization/skills/verify-test-baseline/SKILL.md new file mode 100644 index 0000000..0a587dd --- /dev/null +++ b/plugins/github-copilot-modernization/skills/verify-test-baseline/SKILL.md @@ -0,0 +1,300 @@ +--- +name: verify-test-baseline +description: Generate and run post-migration tests from the frozen baseline specification. +--- + +# Goal + +Generate executable `*PostMigrationIT` tests from the frozen baseline specification and run them against the migrated application. + +The baseline phase produces **no test code** — it produces a precise specification, including the test-cases, infra-decision-table, and testdata. This skill is the sole place where integration test code is generated. + +When the baseline decision table includes `testcontainer` rows, verification MUST run those dependencies against containerized emulators/services (not cloud resources and not mocks). + +## User Input + +- **taskid** — Identifier for this verification run. +- **modernization-work-folder** — Folder under which the verification summary and decision table are written. + +## Terminology + +**Event-sourced subscriber** — any entry point invoked by an external event source rather than by a synchronous caller: message-queue listeners, event-bus / event-hub / event-grid handlers, storage-event triggers (e.g. blob-created or object-deleted handlers), DB change-feed / CDC handlers, inbound-email handlers, file-system watchers. Throughout this document, "event-sourced subscriber" refers to this entire family; the only legitimate trigger for such an entry point is a real event produced on the declared source via its SDK or wire protocol. + +**Testcontainer dependency** — an external dependency marked `testcontainer` in `infra-decision-table.md`; verification must instantiate and use a containerized emulator/service for that dependency via the project's Testcontainers stack. + +## TestContainer References + +When any dependency is marked `testcontainer`, read and apply these references before writing tests: + +- [azure-auth-strategies.md](../modernization-integration-tests/references/azure-auth-strategies.md) +- [azure-servicebus-testcontainers.md](../modernization-integration-tests/references/azure-servicebus-testcontainers.md) +- [azure-storage-testcontainers.md](../modernization-integration-tests/references/azure-storage-testcontainers.md) + +## Principles + +- The spec is the source of truth. If a test case cannot be generated from its fields as-written, the defect is in the spec — coordinate a re-freeze (Step 8), do not invent details in the generated test. +- Post-migration tests are **additions**, never replacements. +- **Strict 1:1 mapping.** Exactly one test method per `TC-*` in `test-cases.md`. No extra tests, no missing tests. Test method count == TC count. **Banned extras include:** infrastructure connectivity tests ("can connect to DB", "can create SDK client"), SDK sanity tests ("can send/receive message", "can read secret"), backing-store CRUD tests that have no entry point in the inventory, and authentication/credential validation tests. If it is not a `TC-*`, it must not exist. +- **TC-ID traceability.** Every test method MUST include its `TC-*` ID in the method name itself (e.g. `tcEjb001_collectLocationHappyPath`, `tc_ejb_001_collect_location_happy_path`). A comment or display name alone is insufficient — the method name is the primary index for auditing coverage. +- **Trigger fidelity over convenience.** The trigger is the contract. Any test whose trigger is not the declared `Entry Point` — for example, one that invokes a cloud SDK, a repository, an internal service, or a private helper instead — is invalid and must be regenerated, even if it passes. If the spec declares an application method as the entry point, the test MUST call that method through its public interface — not re-implement the logic inline using lower-level APIs (e.g. direct DB writes, manual computations). If the spec declares a message-queue listener as the entry point, the test MUST send a message to the queue — not call the listener's handler or an internal service directly. +- **Assertion completeness.** A test must assert every bullet under `Expected Response`, `Resource Verification`, and `Negative Verification`. Existence-only or no-throw-only checks (asserting only that a resource exists, that a call did not throw, or that a value is non-null) are insufficient on their own. +- **No production-bug workarounds.** If a test fails because the migrated code is wrong, hand the work back to the migration engineer per Step 7. Do not patch the test to bypass the broken entry point, and do not loosen / rewrite assertions to accept the buggy response. "Documenting the current behavior" by changing expected response codes, status, or payload to match what the broken code returns is a workaround — not a fix. +- **No hardcoded environment topology.** Generated tests must not hardcode environment-specific resource identifiers (account names, namespaces, queue/topic names, hostnames, connection strings, tenant/subscription IDs, database hosts, secrets). Resolve these from test-only configuration wired to `infra/` outputs and environment variables. +- **No Azure resource writes.** This skill MUST NOT create, update, delete, or otherwise modify Azure resources. Any `az` CLI command that performs a write operation (e.g. `az role assignment create`, `az storage account create`, `az keyvault set-policy`, `az group create`, `az resource update`, `az ad app create`) is forbidden. Read-only `az` commands (e.g. `az account show`, `az role assignment list`, `az resource list`) are permitted for diagnostic purposes only. If a missing role assignment, resource, or configuration is identified, hand over to the Infra Expert per Step 7 — do not provision or reconfigure Azure resources from within this skill. + +## Layout + +Inputs (frozen, produced by the setupBaseline task) live under each in-scope module's **test source root** — the directory the build tool already uses for tests (e.g. `src/test/` for Maven/Gradle Java, `tests/` for Python / Node / Go, `/test/` for multi-module repos). In a multi-module project, each module that was determined to be in-scope during the baseline phase has its own independent `test-cases/` folder. Modules that were marked out-of-scope (no migration-relevant resource access) will not have a `test-cases/` folder — skip them. + +``` +/ +└── test-cases/ # FROZEN folder — created in Phase 1 + ├── test-cases.md # FROZEN — the behavior spec (scoped to this module only) + ├── infra-decision-table.md # FROZEN — mock/real/testcontainer decision per external dependency + └── testdata/ # FROZEN — fixtures referenced by test-cases.md +``` + +Outputs of this skill: + +- `${modernization-work-folder}/${taskid}/post-migration-plan.md` — the TC→test planning table written in Step 4 (created/overwritten on each run). +- `*PostMigrationIT` source files — follow the project's existing test layout conventions. +- `${modernization-work-folder}/${taskid}/verification-summary.md` — final report (Step 9). + +Reused inputs from the baseline phase: + +- `/test-cases/infra-decision-table.md` — mock/real/testcontainer decision per external dependency, produced by `create-test-baseline`. This skill consumes it as-is. + +## Workflow + +### Step 1 — Verify Baseline Integrity + +For each in-scope module, locate `/test-cases/` and confirm `test-cases.md`, `infra-decision-table.md`, and `testdata/` are byte-identical to the baseline commit. Any drift → request revert. If `test-cases.md` is missing entirely for a module that was marked in-scope, abort: the setupBaseline task was supposed to run first — surface this as a plan-ordering bug, do not proceed. Modules without a `test-cases/` folder were determined out-of-scope during the baseline phase (no migration-relevant resource access) — skip them. + +### Step 2 — Load Infra Decision Table from Baseline (mandatory gate) + +The mock/real/testcontainer decision for every external dependency is made in the baseline phase, not here. Verification reuses it as-is. + +1. Load `/test-cases/infra-decision-table.md` produced by `create-test-baseline`. If it is missing, abort and surface this as a plan-ordering bug — do not regenerate it here. +2. Sanity-check the table against runtime prerequisites: + - every row marked **real** must still have a matching provisioned resource in `infra/`. + - every row marked **testcontainer** must still have a viable emulator/container strategy (image, config, dependency containers, and test framework support) in the repo and test runtime. + If prerequisites drift (resource removed, endpoint changed, credential type changed, missing emulator config, unsupported testcontainers version), surface the drift → Step 8 (re-freeze cycle); do not silently downgrade decision modes here. +3. Treat the loaded table as the source of truth for all subsequent steps. + +Do not proceed until the table is loaded and the sanity check passes. + +### Step 3 — Validate Spec Readiness + +Before generating code, audit `test-cases.md` against the **Required Field Checklist** defined in Step 5 of the `create-test-baseline` skill. + +- Every test case has all required fields populated (ID, Category, Entry Point Type, Entry Point, Trigger, Preconditions, Expected Response, Resource Verification, Negative Verification where required, Data References). +- No banned phrasings remain. +- Every `testdata/...` path referenced exists. +- The Entry-Point Inventory matches what is exercised by the cases. + +Any defect → Step 8 (re-freeze cycle). Do not paper over spec defects in generated code. + +### Step 4 — Plan Post-Migration Tests + +Inputs: `test-cases.md`, the infra decision table loaded in Step 2. + +1. **Mirror the spec, exactly once.** For each `TC-*` in `test-cases.md`, plan exactly one test method. No extra tests. No collapsing two TCs into one. No splitting one TC across multiple test methods (sub-steps go inside the single method body). +2. **Map each entry point to its concrete trigger mechanism on the new stack.** The `Trigger` field is technology-agnostic; resolve it to the actual mechanism that exists in the migrated codebase. Always trigger via the same outside-in path the entry point is invoked from in production. Pick the most realistic public driver the test framework offers: + - HTTP / network handlers → framework's HTTP test client. + - CLI commands → CLI runner / process invocation. + - Library APIs → call the published API directly. + - EJB entry points (remote/local business interfaces) → invoke through the container-managed EJB interface/proxy used by external callers; do not call bean implementation classes directly. + - **Event-sourced subscribers** (see Terminology) → produce a real event on the declared source via its SDK or wire protocol (publish a message to the queue/topic, upload/delete the blob, insert/update the watched DB row, send an SMTP message, write the watched file). The application is the subscriber; the only realistic trigger is a real event on the source it subscribes to. + - Scheduled jobs / cron → framework's "run now" hook (e.g. scheduler `triggerJob`, manual invocation of the scheduled-task dispatcher). This is framework-driven, not SDK-driven. + + When in doubt, prefer the mechanism a real external caller or event source would use over a test-only shortcut. +3. **Reject in-spec but infeasible decision-mode cases early.** If a test case requires failure injection on a dependency marked **real** or **testcontainer** (e.g. "storage unavailable", "backend throws IOException", "corrupt object content") and there is no way to trigger that condition from the declared entry point under that mode, do not silently skip and do not silently switch modes — surface the conflict → Step 8 (re-freeze) so the infra-decision-table is amended or the case is reformulated. +4. **Close entry-point coverage gaps.** Scan production code for orchestration entry points. For each one not present in the Entry-Point Inventory of `test-cases.md`, surface the gap → Step 8 (re-freeze) so the spec is updated first. Do not silently add post-migration-only cases. +5. **Produce a planning table (mandatory artifact).** Before writing any code, emit the TC→test mapping table and **save it to `${modernization-work-folder}/${taskid}/post-migration-plan.md`** (create or overwrite). The file MUST contain one row per `TC-*`; rows whose `Trigger Mechanism` is anything other than the declared entry point's outside-in driver, or whose `Fixtures Loaded` is empty while `Data References` is non-empty, must be revised before proceeding. The same table is later linked from the Step 9 verification summary. + + | TC ID | Test Location (class/file → method) | Declared Entry Point | Trigger Mechanism (concrete) | Fixtures Loaded (from `Data References`) | Non-mock Deps Touched (`real`/`testcontainer`) | Config Source | Cleanup Path | + |---|---|---|---|---|---|---|---| + | TC-XXX-001 | _e.g._ `FooPostMigrationIT.uploadHappyPath` | _e.g._ `POST /foo/upload` | _e.g._ HTTP test client multipart POST to `/foo/upload` | `testdata/inputs/sample.jpg`, `testdata/expectations/upload-success.json` | _e.g._ Blob (`testcontainer`), Queue (`real`) | _e.g._ `application-integrationtest.yml` + env vars mapped from `infra/` outputs and Testcontainers runtime properties | _e.g._ `POST /foo/delete/{key}` | + + The row above is illustrative; use the test-class / method / driver naming conventions of the migrated project's language and framework. + `Config Source` is mandatory and must name where each non-mock dependency endpoint/identifier comes from. Any row that implies inline literals in test code must be revised before generation. + +#### Forbidden trigger patterns (rejected by the Step 5 pre-generation audit) + +- HTTP entry point in spec, but the test calls a cloud / storage / messaging SDK directly as the trigger _(e.g. invoking a blob client's upload method, a queue sender client's send method, an object-store put-object call)_. +- HTTP entry point in spec, but the test calls an internal application service, handler, repository, or sender component directly as the trigger. +- EJB entry point in spec, but the test calls the bean implementation class directly (or reflection-invokes its methods) instead of invoking through the container-managed EJB interface/proxy. +- Event-sourced subscriber entry point in spec (see Terminology), but the test calls the subscriber's internal handler method directly _(e.g. invoking the processing service method that the listener delegates to, or feeding a hand-built mocked message/event context into the handler, including via reflection on a private method)_ instead of producing a real event on the declared source. +- Scheduled job entry point in spec, but the test calls the job's run method directly instead of using the framework's scheduled-task invocation hook. +- Backing store (DB, cache, blob container, search index, etc.) used as the *trigger* of a test when no entry point in the inventory exposes that store. Backing stores are not entry points; they may only appear in **Preconditions / Resource Verification**, never as the trigger. +- Any private helper in the test that re-implements production parsing or key-derivation logic _(e.g. a local copy of an "extract original key from thumbnail key" routine)_ — assert against the spec's declared post-state, not against a re-derived expectation. +- Any test helper that re-implements the entry point's **business logic** _(e.g. manually writing to a DB and computing a classification value inline, instead of calling the application method that does both)_. The test must call the actual entry point and verify its output — not simulate what the entry point would do. +- Any test class that tests SDK/infrastructure capabilities (DB connectivity, message broker send/receive, secret retrieval, credential validation) without mapping to a `TC-*` in the spec. These are not post-migration integration tests. + +### Step 5 — Generate Post-Migration Tests + +#### Pre-generation trigger audit (mandatory gate) + +Before writing any test code, emit a **trigger-line pseudocode table** for every planned test method. For each row, write the single line of code (or pseudocode) that will serve as the trigger, then self-check it against the Forbidden trigger patterns in Step 4. The table format: + +| TC ID | Trigger pseudocode | Entry Point Type (from spec) | Violates Step 4 forbidden patterns? | +|---|---|---|---| +| TC-XXX-001 | `serviceBusSender.sendMessage(queue, messageBody)` | Message-queue listener | No — publishes real event to declared source | + +Any row whose last column is anything other than `No` MUST be revised until it passes. Do not proceed to code generation with any unresolved row. + +#### Trigger rules + +- **Trigger only via the declared entry point.** The constraint applies to the **trigger** of the test, not to setup/teardown. See the Forbidden trigger patterns in Step 4 for the concrete anti-patterns that must be rejected. +- **Seeding preconditions and resource verification may use SDKs directly.** When a test case's `Preconditions` or `Resource Verification` requires state on a real or testcontainer-backed resource (object in a container, row in a table, message on a queue) and the application exposes no public entry point to create or read that state, the test setup / verification step MAY call the resource's SDK directly. Seed data comes from `testdata/`. This is setup/observation, not the trigger. +- **Async event-sourced tests** must wait on the **observable post-condition** using the language/framework's idiomatic async-wait helper that polls until the condition holds or a timeout elapses _(e.g. an `Awaitility`-style polling helper in JVM languages, `WaitFor` / polling loops in .NET, `pytest`-style retry helpers in Python)_. Never use a fixed-duration sleep, and never assert immediately after emitting the event. + +#### Assertion rules + +- **Every bullet in the spec is an assertion.** Walk `Expected Response`, `Resource Verification`, and `Negative Verification` bullet-by-bullet. Each bullet maps to at least one assertion in the test body. Missing any bullet → regenerate. +- **Load every fixture in `Data References`.** Each path under `Data References` must be loaded by the test through the language's normal resource-loading mechanism _(e.g. classpath resource stream in JVM, embedded resource / file read in .NET, file open in Python/Node/Go)_ and used either as input or as the expected value for an assertion. Unused fixtures are a planning bug — either the test under-asserts, or the spec lists a fixture it doesn't need (→ Step 8). +- **No existence-only / no-throw-only tests.** Assertions that only check resource existence, only check that a call did not throw, or only check non-null do not satisfy `Resource Verification`. Assert content, fields, sizes, statuses, redirect targets, message bodies, and DB column values exactly as the spec states. +- **Negative verification is mandatory where the spec lists it.** For every bullet under `Negative Verification` _(e.g. "no new row inserted", "no message published", "no thumbnail created")_, the test must perform the observation that proves the negative — not just skip it. + +#### Test isolation rules + +- **One TC = one independent test method.** No shared mutable state across test methods in the same class/module. No ordered-execution chains where one method's success is required for the next _(e.g. JUnit `@Order`, NUnit `[Order]`, xUnit `IClassFixture` for ordering, pytest fixture ordering tricks)_. No skip-when-previous-test-passed coupling _(e.g. `Assumptions.assumeTrue(previousState != null)`, `Skip.If(...)`)_. Every test sets up its own preconditions and tears them down. +- **Random keys per test run.** Use a fresh unique suffix (GUID / random string / timestamp+nonce) for every created entity; never deterministic names, since real resources are shared across parallel runs and re-runs. + +#### Stack & dependency rules + +- **Boot the full application stack** — no sliced/partial test contexts when any dependency is "real" or `testcontainer`. +- **Real dependencies stay real.** Do not stub, fake, or mock anything marked "real" in the decision table at any layer. +- **Testcontainer dependencies stay testcontainer-backed.** Do not replace `testcontainer` rows with mocks or cloud resources; instantiate and wire the required emulator/service containers. +- **Mocked dependencies** (only those marked "mock"): mock at SDK / HTTP boundary, seed from `testdata/`, assert on outbound requests as well as return values. +- **Cross-module service dependencies** (marked "mock" in the decision table): mock at the service interface boundary so each module's tests are self-contained. The test verifies the module's own behavior given controlled responses from the mocked cross-module dependency. Do not let cross-module calls fall through to a real sibling module. +- **Non-migration-scope external services** (marked "mock" in the decision table): mock at the SDK / HTTP boundary. These include third-party APIs, internal services outside the project, and legacy systems not being migrated. +- **Test-only configuration** points to: + - real endpoints from `infra/` for `real` rows, and + - dynamic container endpoints/connection strings for `testcontainer` rows, + via the project's standard mechanism (Spring profile, `.env`, `appsettings.IntegrationTest.json`, env vars). Activated for these tests only; do not modify production config. + +#### Auth rules + +- **Auth requirements depend on the infra decision table.** + - `real` rows: cloud credentials are required. + - `testcontainer` rows: cloud credentials are NOT required; use emulator/container credentials or anonymous/local auth. + - `mock` rows: no cloud credentials required. +- **Pre-flight auth check** in test setup, applied per real dependency the test touches. + - **Local runs (non-Azure host).** Managed Identity is unavailable — the test MUST authenticate as the developer's `az login` principal (e.g. via `DefaultAzureCredential` / `AzureCliCredential`). Do not fabricate a managed-identity client ID, do not point at IMDS, and do not require a service-principal secret for local runs. + - **CI / Azure-hosted runs.** Use the configured Managed Identity when available, otherwise the CI service-principal env vars (`AZURE_CLIENT_ID` / `AZURE_TENANT_ID` / `AZURE_CLIENT_SECRET` or federated credentials). + - **The pre-flight check is a fail-fast gate, not a silent-skip.** If credentials for a real dependency are missing or insufficient, the test MUST fail loudly (assertion failure / explicit error) so Step 7 picks it up as an **Infra issue** and escalates. Do NOT implement "gracefully abort / mark as skipped / return early" patterns _(e.g. `Assumptions.assumeTrue(credentialsAvailable)`, `Skip.If(...)`, JUnit `@EnabledIfEnvironmentVariable`, early `return` in `@BeforeAll`, try/catch that swallows the auth exception)_ — those let the verification phase complete with zero real assertions executed against the migrated stack. + - **All-mock and all-testcontainer tests do not skip on missing cloud credentials.** If a test's dependencies include no `real` rows, it must run unconditionally; a missing `az login` is not a valid reason to skip. + +#### Cleanup rules + +- **Cleanup via entry points first.** Prefer the application's own delete entry point for cleanup so test credentials need no extra data-plane permissions. Fall back to SDK cleanup only when no delete entry point exists. Run cleanup in `finally` / teardown; ignore "not found". Never use SDK cleanup as a workaround for a broken application delete path — if the application's delete entry point fails, that is a production bug (Step 7), not a cleanup-strategy choice. For mocked dependencies, cleanup is reset of in-memory state — still required so tests stay independent. + +### Step 6 — Validate and Run + +Before running, run the **pre-run validation checklist** against generated code. Any `No` → regenerate (Step 5) or escalate to Step 8. Do not proceed to execution with a failing checklist. + +**Coverage & mapping** + +- [ ] Test method count equals `TC-*` count in `test-cases.md` (no extras, no missing). **Zero test classes may exist that are not mapped to at least one TC-*.** Infrastructure-only, SDK-sanity, or connectivity test classes are forbidden. +- [ ] Every `TC-*` is referenced by exactly one test method whose **method name contains the TC-ID** (e.g. `tcEjb001_...`). A comment or `@DisplayName` alone is insufficient. +- [ ] No test class / module exists for an entry point absent from the Entry-Point Inventory (no DB-only / cache-only / SDK-only test class when those are backing stores rather than entry points). +- [ ] `${modernization-work-folder}/${taskid}/post-migration-plan.md` exists and has one row per `TC-*`. + +**Trigger correctness (per test)** + +- [ ] The line that invokes the system under test matches the declared `Entry Point` and does not match any pattern in Step 4 "Forbidden trigger patterns". +- [ ] For event-sourced subscriber entry points (see Terminology): the trigger produces a real event on the declared source via its SDK or wire protocol; an async-wait helper polls for the post-condition; no direct call to the subscriber's handler method (including via reflection) and no hand-fabricated message/event context. + +**Assertion completeness (per test)** + +- [ ] Every bullet under `Expected Response` is asserted. +- [ ] Every bullet under `Resource Verification` is asserted. +- [ ] Every bullet under `Negative Verification` is asserted (where the spec lists it). +- [ ] Every path in `Data References` is loaded by the test. +- [ ] No test relies solely on existence / non-null / no-throw assertions. + +**Isolation** + +- [ ] No shared mutable state across test methods. +- [ ] No ordered-execution chains where later tests depend on earlier tests succeeding. +- [ ] All created entities use random suffixes. + +**Infra alignment** + +- [ ] No mocks/stubs/fakes for any "real" or `testcontainer` dependency. +- [ ] Full application stack boots when any dependency is "real" or `testcontainer`. +- [ ] Test-only configuration exists and points at real endpoints in `infra/` for `real` rows and container endpoints for `testcontainer` rows. +- [ ] No hardcoded environment-specific topology in generated test source; all dependency identifiers/endpoints are supplied via test-only config and/or env vars. +- [ ] No generated "global cleanup" or "queue drain" step that alters shared resources beyond the TC-scoped setup/cleanup required by the spec. +- [ ] No test case requires failure injection (e.g. "storage unavailable", "backend throws IOException") on a dependency marked **real** or `testcontainer` without the ability to trigger that condition from the declared entry point. Any such case should have been surfaced in Step 4.3 and sent to Step 8 (re-freeze). + +Run all `*PostMigrationIT` tests. Required: **100% pass**, and the run MUST be a real execution that reached the application. For each TC, dependencies must follow the decision table exactly: `real` rows hit real provisioned resources, `testcontainer` rows hit instantiated containers/emulators, and `mock` rows are served by configured test doubles. + +**Execution is mandatory — compile/unit-test success is not verification.** + +- Invoke the project's integration-test phase explicitly _(e.g. Maven `mvn verify` / `mvn failsafe:integration-test`, Gradle `./gradlew integrationTest`, `dotnet test` against the IT project, `pytest tests/integration`, `go test -tags=integration ./...`)_. Confirm from the runner's output that each `*PostMigrationIT` method was actually executed (e.g. Failsafe `Tests run: N` ≥ TC count, not `Tests run: 0`). A green build that ran 0 IT methods is **not** a pass. +- The following do **not** count as runtime verification and MUST NOT be used as justification to mark the task `success`: + - `mvn compile` / `mvn test-compile` / type-check only. + - The unit-test phase (`mvn test`, `dotnet test` without the IT project, `pytest` without the integration marker) — by convention `*IT` / integration tests are excluded from this phase. + - Static review of the generated test files ("no `@MockBean` present", "assertions look right") without running them. +- **Blocker routing depends on dependency mode.** + - Real-dependency blockers (no credentials, no network reachability, missing role assignment, infra not provisioned) are Infra issues per Step 7 and go to the Infra Expert. + - Testcontainer blockers (Docker unavailable, image pull denied, emulator dependency container missing, unsupported testcontainers version) are test setup issues, must be reported as runtime errors, and do **not** go to the Infra Expert. + These blockers are **not** a valid reason to skip TCs whose dependencies are all **mock**: those tests must still execute and pass before the task can be `success`. +- **Accidental-real-call guard for mock TCs.** A test whose decision-table row is `mock` but which silently falls back to a real network call (because the mock wasn't wired, or because the SDK uses default credentials when no stub is present) is a **test bug**, not a pass — fix the mock wiring; do not declare success on the strength of an unintended real call. +- **Accidental-mode-mismatch guard for testcontainer TCs.** A test whose decision-table row is `testcontainer` but which silently falls back to a real cloud call or a mock is a **test bug**, not a pass — fix container wiring. + +**Task status outcome (mandatory mapping).** Pick exactly one based on the actual runtime result — never on "compile passed" or "unit tests passed". Runtime coverage checks apply to TCs whose decision-table rows are **real** and/or **testcontainer**: + +| Situation | Status | +|---|---| +| Every `*PostMigrationIT` ran AND 100% pass; real-dep TCs hit real resources, testcontainer-dep TCs hit configured containers/emulators, and mock-dep TCs were served by the configured doubles | `success` | +| Verification is paused waiting on a hand-off (Infra agent, migration developer for production bug, re-freeze cycle); will resume | `pending` (with summary of who/what is blocking) | +| `*PostMigrationIT` executed and at least one failed, AND the cause is a production bug or a test bug that cannot be reconciled with the spec, AND no further hand-off is in progress | `failed` | +| Real-dep TCs could not be started or completed and the blocker cannot be resolved (Infra Expert unavailable/declined, or infra drift cannot be fixed in this run), OR testcontainer-dep TCs could not be started or completed and required container runtime/emulator setup cannot be restored in this run | `failed` | +| Mock-dep TCs were not executed for any reason, OR verification produced no real execution evidence at all (zero `*PostMigrationIT` methods executed, runner reported `Tests run: 0`, or only compile/unit phases ran) | `failed` | + +The status `success` is permitted only when the Runtime Execution Evidence required by Step 9 can be filled in with real numbers for every TC. If you would have to write "integration tests were not executed because..." for any TC in the summary, the status is **not** `success` — it is `pending` (real-dep infra handoff active, or testcontainer setup still unresolved) or `failed` (handoff exhausted, mock-dep TCs unrun, or no path forward). + +### Step 7 — Classify and Route Failures + +This section is the single reference point for failure classification. Steps 5 and 6 route here when a runtime or generation-time failure occurs. + +The spec is the source of truth. Before deciding it is a test bug, prove the test contradicts the spec. The default classification of any disagreement between spec and runtime behavior is **production bug**. + +- **Test bug** (the generated test does not faithfully implement what the spec says) → fix the test. Examples: wrong fixture loaded, wrong assertion value relative to the spec, wrong trigger mechanism, missing async wait. The signal: the spec says X, the test asserts Y, the runtime returns X. +- **Production bug** (the runtime contradicts the spec) → **stop, do not patch the test.** Hand back to the migration developer (see handover protocol below). +- **Spec gap** (case requires failure injection that real infra cannot produce, fixture missing, entry point unlisted) → Step 8 (re-freeze). Do not silently downgrade a "real" dependency to a mock to make a test pass. +- **Infra issue (real dependencies only)** — auth/configuration/network/endpoint problem on a real resource (e.g. missing role assignment, endpoint unreachable, infra not provisioned) → hand over to the Infra Expert (see handover protocol below). Do not attempt infra changes from inside the test skill. +- **Testcontainer setup issue** — container-runtime/emulator problem for a `testcontainer` dependency (e.g. Docker daemon unavailable, image pull failure, emulator config missing, unsupported testcontainers version) → report as an error, fix in this skill; if unresolved, use `ask_user`. Do not route these to the Infra Expert. + +**Handover protocol (production bug / infra issue):** + +Hand over per the teams SOP. The hand-back message must include: + +| Classification | Recipient | Message must include | +|---|---|---| +| Production bug | Migration developer | Which `TC-*` failed, the declared expected behavior from the spec, the observed behavior from the run, and the suspected production cause | +| Infra issue (real dependencies only) | Infra Expert | Which `*PostMigrationIT` could not run, the exact error or missing prerequisite, and the real resource(s) involved (resource group/account/namespace/server names) | + +**Prohibited responses (both):** do not patch the test to work around the problem — no trigger rewrites, no loosened assertions, no auth-setup changes beyond Step 5. Do not loop indefinitely or flip to `success`. + +**Exhausted hand-off:** if the recipient is unavailable or does not exist in `teams-roles.json`, fall back to `ask_user`. If `ask_user` is also unavailable or the user declines to act → close the task as `failed` per the status mapping in Step 6. + +### Step 8 — Re-Freeze Cycle for Spec Defects + +Whenever any of the following occurs — the Step 3 audit fails; Step 4 finds an uncovered entry point, an infeasible-as-real failure-injection case, or a planning gap that cannot be expressed against the current spec; Step 6 finds a generated test cannot be reconciled with the spec; or any new fixture / scenario is needed — **coordinate a baseline re-freeze**: unfreeze the contents of `test-cases/` → amend (`test-cases.md`, `testdata/`, and/or `infra-decision-table.md`) → re-run the create-test-baseline freeze gate → re-freeze. There is no side channel for adding fixtures or cases in Phase 3. + +### Step 9 — Report + +Create `${modernization-work-folder}/${taskid}/verification-summary.md` summarizing decisions, results, and gaps. This is the only **report** artifact — do not emit additional report / status markdown files. (The planning table from Step 4 and the `*PostMigrationIT` source files from Step 5 are separate required outputs and continue to exist.) + +The summary MUST include a **Runtime Execution Evidence** section with: + +- The exact command(s) used to run the integration tests (e.g. `mvn -pl web,worker verify`). +- The runner's tests-run / failures / errors / skipped counts per module, copied from the actual output. +- A one-line confirmation that the count of executed `*PostMigrationIT` methods equals the count of `TC-*` planned in Step 4. +- A per-TC breakdown of **real vs testcontainer vs mock dependencies actually used** at runtime, matched against the Step 2 decision table. For real-dep TCs: the authentication mode used (`az login` principal name, MI client ID, or CI SP) and the target resource identifiers (resource group + account/namespace/server) that were actually contacted. For testcontainer-dep TCs: container image(s), mapped endpoints, and emulator auth strategy used. For mock-dep TCs: the test-double mechanism used (e.g. `@MockBean`, WireMock stub, in-memory fake) so it is auditable that no accidental real call occurred. + +If this section cannot be populated with real execution data for every TC (real-dep TCs with real-resource evidence, testcontainer-dep TCs with container runtime evidence, mock-dep TCs with mock-wiring evidence), the task is not eligible to be marked `success` — go back to Step 6 and resolve the real-dependency Infra issue or the testcontainer setup issue (per Step 7), or fix the missing execution first.