Merge pull request #115 from Azure/fix/align-toolkit-config-format

Fully align filter and override config formats with APIOps Toolkit

Author: petehauge

.squad/decisions/decisions.md

@@ -67,3 +67,53 @@ All new `.ts` files in `src/` and `tests/` must include:
 - [Microsoft Open Source Program](https://opensource.microsoft.com/program)
 
 ---
+
+### 2026-07-16: Issue #114 Architectural Review — Filter & Override Toolkit Alignment
+**By:** ApiOpsLead  
+**Status:** Approved (Follow-up required)  
+**What:** Architecture review of issue #114 models, config loader, filter service, override merger, workspace extractor, transitive resolver.
+
+**Key Findings:**
+
+- **OverrideEntry recursive model:** Sound design, well-bounded recursion (max depth 3), no cycle risk.
+- **Toolkit parity:** All 14 override sections and 16 filter fields implemented. `Workspace` filter added correctly.
+- **Forward compatibility (§VII):** Clean extension points; 1–3 LOC cost per new section/relationship.
+- **Override merger traversal:** 🟡 ApiOperationPolicy double-nesting gap — YAML is 3-level (`apis → operations → policies`), but `applyNestedOverride` does 2-level traversal only. Practical impact low (rare use, operation properties typically empty).
+- **Filter service sub-filtering:** ✅ Correct semantics (case-insensitive matching, proper empty array handling).
+- **Workspace sub-filter consumption:** ✅ Parsed correctly, consumption path can follow in separate PR.
+
+**Verdict:** Approve. Architecture maps cleanly to Toolkit format with sound design and good extension points. ApiOperationPolicy gap is non-blocking — **file follow-up issue.**
+
+**Constitution compliance:** §II (APIM Native), §V (YAGNI), §VI (Testability), §VII (Forward Compatibility)
+
+---
+
+### 2026-07-16: Issue #114 Code Review — Standards & Testability
+**By:** CodeReviewer  
+**Status:** Request Changes (5 required items)  
+**What:** Standards review of 6 source files, 3 test files, 4 doc/template files for issue #114.
+
+**Required Changes (🟡):**
+
+| ID | Issue | File(s) | Principle |
+|----|-------|---------|-----------|
+| R1 | ApiOperationPolicy nested override lookup broken | override-merger.ts | §IV Idempotent Operations |
+| R2 | Filter name case sensitivity doc/code mismatch | filtering-resources.md | §III Configuration as Code |
+| R3 | Duplicate override names silently overwritten | config-loader.ts | §I CLI-First Design |
+| R4 | Workspace sub-filters parsed but never consumed | config.ts, config-loader.ts, workspace-extractor.ts | §V Simplicity/YAGNI |
+| R5 | Zero test coverage for nested override functionality | override-merger.test.ts, config-loader.test.ts | §VI Testability by Design |
+
+**Details:**
+- **R1:** Remove `ApiOperationPolicy` from `CHILD_OVERRIDE_MAP` or implement multi-level traversal for 3-deep nesting.
+- **R2:** `matchesFilter()` uses `.toLowerCase()` (case-insensitive); update docs from "case-sensitive" to "case-insensitive."
+- **R3:** Emit warning when duplicate `name` in override array; currently silently overwrites.
+- **R4:** Either remove workspace sub-filter parsing/model or implement consumption in filter-service/workspace-extractor.
+- **R5:** Add tests: ApiDiagnostic nested override, ApiOperation nested override, ProductPolicy nested override, config loader nested override parsing, config loader API sub-filter parsing, config loader workspace sub-filter parsing (if kept).
+
+**Positive Observations:** All 9 files have correct copyright headers. Zero `any` types. All imports use `.js` extensions. Forward compatibility preserved (§VII). Immutability maintained. Secret safety compliant (§VIII). Error handling is actionable. Idempotent design verified (§IV). Legacy alias support with deprecation warnings. Template quality high.
+
+**Verdict:** Well-structured implementation with good constitution compliance. R1–R5 must be resolved before merge. No blockers.
+
+**Constitution compliance:** §I, §III, §IV, §V, §VI, §VII, §VIII
+
+---

docs/ci-cd/azure-devops.md

@@ -43,7 +43,7 @@ The extract pipeline pulls configuration from your APIM instance, publishes the
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `CONFIGURATION_YAML_PATH` | string | `Extract All APIs` | Choose `Extract All APIs` for a full extract, or `configuration.extract.yaml` to use a [filter file](../guides/filtering-resources.md) |
+| `CONFIGURATION_YAML_PATH` | string | `Extract All APIs` | Choose `Extract All APIs` for a full extract, or `configuration.extractor.yaml` to use a [filter file](../guides/filtering-resources.md) |
 | `resourceGroup` | string | `$(APIM_RESOURCE_GROUP)` | Azure resource group containing your APIM instance |
 | `serviceName` | string | `$(APIM_SERVICE_NAME)` | Name of the APIM service instance |
 
@@ -55,7 +55,7 @@ flowchart TD
     B --> C[npm ci]
     C --> D{Configuration choice?}
     D -->|Extract All APIs| E[apiops extract --resource-group ... --service-name ...]
-    D -->|configuration.extract.yaml| F[apiops extract ... --filter configuration.extract.yaml]
+    D -->|configuration.extractor.yaml| F[apiops extract ... --filter configuration.extractor.yaml]
     E --> G[Publish pipeline artifact]
     F --> G
     G --> H[Create branch apim-extract-BuildId]
@@ -92,7 +92,7 @@ The key task is `AzureCLI@2`, which authenticates using your service connection:
         --subscription-id $(AZURE_SUBSCRIPTION_ID)
 ```
 
-When the filter option is selected, `--filter configuration.extract.yaml` is added to the command.
+When the filter option is selected, `--filter configuration.extractor.yaml` is added to the command.
 
 > **Why AzureCLI@2?** This task injects Azure credentials into the shell environment, allowing `apiops extract` to authenticate via `DefaultAzureCredential`. See [Authentication Guide](../guides/authentication.md).
 

docs/ci-cd/github-actions.md

@@ -44,7 +44,7 @@ The extract workflow pulls configuration from your APIM instance and creates a P
 | Input | Description | Options |
 |-------|-------------|---------|
 | `ENVIRONMENT` | Which APIM instance to extract from | `dev`, `prod` |
-| `CONFIGURATION_YAML_PATH` | Extract all APIs or use a filter file | `Extract All APIs`, `configuration.extract.yaml` |
+| `CONFIGURATION_YAML_PATH` | Extract all APIs or use a filter file | `Extract All APIs`, `configuration.extractor.yaml` |
 
 ### What It Does
 

docs/commands/extract.md

@@ -34,7 +34,7 @@ apiops extract \
   --subscription-id 00000000-0000-0000-0000-000000000000 \
   --resource-group my-rg \
   --service-name my-apim \
-  --filter ./configuration.extract.yaml
+  --filter ./configuration.extractor.yaml
 ```
 
 ### Extract without transitive dependencies
@@ -98,23 +98,23 @@ By default, `apiops extract` exports **all** resources from the APIM instance (3
 To extract only specific resources, pass a YAML filter file with `--filter`:
 
 ```yaml
-# configuration.extract.yaml
-apiNames:
+# configuration.extractor.yaml
+apis:
   - echo-api
   - petstore-api
-productNames:
+products:
   - starter
-backendNames:
+backends:
   - backend-api
-namedValueNames:
+namedValues:
   - api-key
-tagNames:
+tags:
   - production
-policyFragmentNames:
+policyFragments:
   - rate-limit-fragment
-loggerNames:
+loggers:
   - appinsights-logger
-diagnosticNames:
+diagnostics:
   - applicationinsights
 ```
 
@@ -124,22 +124,22 @@ All 16 supported filter keys:
 
 | Filter key | Resource type |
 |------------|---------------|
-| `apiNames` | APIs |
-| `backendNames` | Backends |
-| `productNames` | Products |
-| `namedValueNames` | Named values |
-| `loggerNames` | Loggers |
-| `diagnosticNames` | Diagnostics |
-| `tagNames` | Tags |
-| `policyFragmentNames` | Policy fragments |
-| `gatewayNames` | Gateways |
-| `versionSetNames` | API version sets |
-| `groupNames` | Groups |
-| `subscriptionNames` | Subscriptions |
-| `schemaNames` | Schemas |
-| `policyRestrictionNames` | Policy restrictions |
-| `documentationNames` | Documentation resources |
-| `workspaceNames` | Workspaces |
+| `apis` | APIs |
+| `backends` | Backends |
+| `products` | Products |
+| `namedValues` | Named values |
+| `loggers` | Loggers |
+| `diagnostics` | Diagnostics |
+| `tags` | Tags |
+| `policyFragments` | Policy fragments |
+| `gateways` | Gateways |
+| `versionSets` | API version sets |
+| `groups` | Groups |
+| `subscriptions` | Subscriptions |
+| `schemas` | Schemas |
+| `policyRestrictions` | Policy restrictions |
+| `documentations` | Documentation resources |
+| `workspaces` | Workspaces |
 
 ### Transitive dependencies
 

docs/commands/init.md

@@ -78,26 +78,27 @@ In interactive mode (the default when running in a terminal), `apiops init` prom
 
 | File | Purpose |
 |------|---------|
-| `.github/workflows/extract.yaml` | Pipeline to extract APIM artifacts |
-| `.github/workflows/publish.yaml` | Pipeline to publish artifacts to APIM |
-| `configuration.extract.yaml` | Sample filter configuration for extraction |
+| `.github/workflows/run-apim-extractor.yml` | Workflow to extract APIM artifacts |
+| `.github/workflows/run-apim-publisher.yml` | Workflow to publish artifacts to APIM |
+| `configuration.extractor.yaml` | Sample filter configuration for extraction |
 | `configuration.{env}.yaml` | Override templates per environment (e.g., `configuration.dev.yaml`, `configuration.prod.yaml`) |
 | `IDENTITY-SETUP-GITHUB.md` | Step-by-step guide for configuring federated credentials |
 
 ### Azure DevOps (`--ci azure-devops`)
 
 | File | Purpose |
 |------|---------|
-| `pipelines/extract.yaml` | Pipeline to extract APIM artifacts |
-| `pipelines/publish.yaml` | Pipeline to publish artifacts to APIM |
-| `configuration.extract.yaml` | Sample filter configuration for extraction |
+| `.azdo/pipelines/run-apim-extractor.yml` | Pipeline to extract APIM artifacts |
+| `.azdo/pipelines/run-apim-publisher.yml` | Pipeline to publish artifacts to APIM |
+| `configuration.extractor.yaml` | Sample filter configuration for extraction |
 | `configuration.{env}.yaml` | Override templates per environment |
 | `IDENTITY-SETUP-AZDO.md` | Step-by-step guide for configuring service connections |
 
 ### Both platforms
 
 | File | Purpose |
 |------|---------|
+| `.github/prompts/apiops-setup-identity.prompt.md` | Copilot prompt for identity setup |
 | `<artifact-dir>/` | Empty artifact directory (default: `./apim-artifacts`) |
 
 ## Package consumption modes