fix: correct singleton policy overrides and add policies filter

Bug fixes:
- ServicePolicy override no longer throws RangeError (nameParts: [])
- ApiPolicy/ProductPolicy singleton child overrides now use fixed name "policy"
- ApiOperationPolicy grandchild override uses correct 2-part nameParts
- Recursive override parser passes bare section kind for child lookup
- Tests updated to use verified descriptor nameParts from buildDescriptor

Parity additions:
- Added policies filter key for ServicePolicy (Toolkit parity)
- Strip apiRevision/isCurrent from API overrides (matches Toolkit)
- Workspace sub-filter docs marked as not yet implemented (#119)

957 tests pass, lint and TypeScript clean.

Closes #114

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Peter Hauge

docs/guides/filtering-resources.md

@@ -104,7 +104,9 @@ apis:
 
 ### Workspace sub-resource filters
 
-For workspaces, you can specify which workspace-scoped resources to extract:
+> **Note:** Workspace sub-resource filtering is parsed but not yet applied at runtime. Currently, including a workspace extracts all resources within it. This matches the Toolkit's configuration format for forward compatibility. See [#119](https://github.com/Azure/apiops-cli/issues/119) for tracking.
+
+The configuration format supports specifying which workspace-scoped resources to extract:
 
 ```yaml
 workspaces:
@@ -140,6 +142,7 @@ Supported workspace sub-filter keys: `apis`, `backends`, `diagnostics`, `groups`
 | `groups` | Groups | `developers`, `partners`, `admins` |
 | `subscriptions` | Subscriptions | `team-a-subscription` |
 | `schemas` | Global Schemas | `shared-error-schema` |
+| `policies` | Service-level Policies | `policy` |
 | `policyRestrictions` | Policy Restrictions | `no-external-calls` |
 | `documentations` | Documentation | `getting-started`, `changelog` |
 | `workspaces` | Workspaces | `team-a-workspace`, `team-b-workspace` |

src/lib/config-loader.ts

@@ -116,6 +116,7 @@ const FILTER_KEY_ALIASES: Record<FilterYamlKey, string> = {
   groups: 'groupNames',
   subscriptions: 'subscriptionNames',
   schemas: 'schemaNames',
+  policies: 'policyNames',
   policyRestrictions: 'policyRestrictionNames',
   documentations: 'documentationNames',
   workspaces: 'workspaceNames',
@@ -320,34 +321,42 @@ const OVERRIDE_CHILD_SECTIONS: Record<string, Set<string>> = {
  * Normalize one override section into OverrideSection format.
  * Supports Toolkit list format: `[{ name, properties, ...childSections }]`
  * Recursively parses nested child sections.
+ *
+ * @param section - The raw YAML value for this section
+ * @param displayPath - Full dotted path for error messages (e.g., "apis.my-api.operations")
+ * @param sectionKind - Bare section key for child lookup (e.g., "operations")
  */
 function normalizeOverrideSectionRecursive(
   section: unknown,
-  sectionName: string
+  displayPath: string,
+  sectionKind?: string
 ): OverrideSection | undefined {
+  // Use sectionKind for child lookup; fall back to displayPath for top-level calls
+  const lookupKey = sectionKind ?? displayPath;
+
   if (section === undefined || section === null) {
     return undefined;
   }
 
   if (!Array.isArray(section)) {
     throw new Error(
-      `Invalid overrides.${sectionName}: expected an array in toolkit format ` +
+      `Invalid overrides.${displayPath}: expected an array in toolkit format ` +
       `([ { name, properties } ]), got ${typeof section}.`
     );
   }
 
   const normalized: OverrideSection = {};
-  const childKeys = OVERRIDE_CHILD_SECTIONS[sectionName] ?? new Set<string>();
+  const childKeys = OVERRIDE_CHILD_SECTIONS[lookupKey] ?? new Set<string>();
 
   for (const item of section) {
     if (!isPlainObject(item)) {
-      logger.warn(`Ignoring invalid item in overrides.${sectionName}; expected object.`);
+      logger.warn(`Ignoring invalid item in overrides.${displayPath}; expected object.`);
       continue;
     }
 
     const name = item.name;
     if (typeof name !== 'string' || name.trim().length === 0) {
-      logger.warn(`Ignoring item in overrides.${sectionName}; "name" is required.`);
+      logger.warn(`Ignoring item in overrides.${displayPath}; "name" is required.`);
       continue;
     }
 
@@ -356,7 +365,7 @@ function normalizeOverrideSectionRecursive(
     if (item.properties !== undefined && item.properties !== null) {
       if (!isPlainObject(item.properties)) {
         logger.warn(
-          `Ignoring item '${name}' in overrides.${sectionName}; ` +
+          `Ignoring item '${name}' in overrides.${displayPath}; ` +
           `"properties" must be an object, got ${typeof item.properties}.`
         );
         continue;
@@ -369,7 +378,7 @@ function normalizeOverrideSectionRecursive(
       );
       if (Object.keys(fallbackFields).length > 0) {
         logger.debug(
-          `Item '${name}' in overrides.${sectionName} is missing 'properties'; using fields directly.`
+          `Item '${name}' in overrides.${displayPath} is missing 'properties'; using fields directly.`
         );
         properties = fallbackFields;
       } else {
@@ -382,7 +391,11 @@ function normalizeOverrideSectionRecursive(
     for (const childKey of childKeys) {
       const childValue: unknown = item[childKey];
       if (childValue !== undefined) {
-        const childSection = normalizeOverrideSectionRecursive(childValue, `${sectionName}.${name}.${childKey}`);
+        const childSection = normalizeOverrideSectionRecursive(
+          childValue,
+          `${displayPath}.${name}.${childKey}`,
+          childKey
+        );
         if (childSection !== undefined) {
           if (!children) children = {};
           children[childKey] = childSection;
@@ -396,11 +409,11 @@ function normalizeOverrideSectionRecursive(
     // Only add entry if it has properties or children
     if (Object.keys(properties).length > 0 || children) {
       if (normalized[name] !== undefined) {
-        logger.warn(`Duplicate name '${name}' in overrides.${sectionName}; later entry overwrites earlier one.`);
+        logger.warn(`Duplicate name '${name}' in overrides.${displayPath}; later entry overwrites earlier one.`);
       }
       normalized[name] = entry;
     } else {
-      logger.warn(`Ignoring item '${name}' in overrides.${sectionName}; no override properties or child sections.`);
+      logger.warn(`Ignoring item '${name}' in overrides.${displayPath}; no override properties or child sections.`);
     }
   }
 

src/models/config.ts

@@ -65,6 +65,7 @@ export interface FilterConfig {
   groups?: string[];
   subscriptions?: string[];
   schemas?: string[];
+  policies?: string[];
   policyRestrictions?: string[];
   documentations?: string[];
   workspaces?: string[];

src/services/filter-service.ts

@@ -7,7 +7,7 @@
  */
 
 import { FilterConfig, ApiSubFilter } from '../models/config.js';
-import { ResourceType } from '../models/resource-types.js';
+import { ResourceType, RESOURCE_TYPE_METADATA } from '../models/resource-types.js';
 import { ResourceDescriptor } from '../models/types.js';
 import { logger } from '../lib/logger.js';
 import { getNamePart } from '../lib/resource-path.js';
@@ -29,6 +29,7 @@ const FILTER_FIELD_MAP: Partial<Record<ResourceType, keyof FilterConfig>> = {
   [ResourceType.Group]: 'groups',
   [ResourceType.Subscription]: 'subscriptions',
   [ResourceType.GlobalSchema]: 'schemas',
+  [ResourceType.ServicePolicy]: 'policies',
   [ResourceType.PolicyRestriction]: 'policyRestrictions',
   [ResourceType.Documentation]: 'documentations',
   [ResourceType.Workspace]: 'workspaces',
@@ -92,7 +93,11 @@ export function shouldIncludeResource(
   // Check direct filter field for this resource type
   const directField = FILTER_FIELD_MAP[descriptor.type];
   if (directField) {
-    return matchesFilter(getNamePart(descriptor.nameParts, 0), filter[directField] as string[] | undefined);
+    // Singleton resources (e.g., ServicePolicy) have nameParts: [] — use fixed name from ARM path
+    const resourceName = descriptor.nameParts.length > 0
+      ? getNamePart(descriptor.nameParts, 0)
+      : getSingletonFilterName(descriptor.type);
+    return matchesFilter(resourceName, filter[directField] as string[] | undefined);
   }
 
   // Check parent-based filter for child resource types
@@ -114,15 +119,19 @@ export function shouldIncludeResource(
     }
   }
 
-  // ServicePolicy has no filter — always included
-  if (descriptor.type === ResourceType.ServicePolicy) {
-    return true;
-  }
-
   // Unknown types are included by default
   return true;
 }
 
+/**
+ * Get the fixed singleton name for a resource type from its ARM path.
+ * E.g., ServicePolicy → "policy"
+ */
+function getSingletonFilterName(type: ResourceType): string {
+  const meta = RESOURCE_TYPE_METADATA[type];
+  return meta.armPathSuffix.split('/').pop() ?? '';
+}
+
 /**
  * Check if an API child resource passes the API sub-resource filter.
  * If the parent API has no sub-filter entry, all children are included.

src/services/override-merger.ts

@@ -8,10 +8,10 @@
  */
 
 import { ResourceDescriptor } from '../models/types.js';
-import { ResourceType } from '../models/resource-types.js';
+import { ResourceType, RESOURCE_TYPE_METADATA } from '../models/resource-types.js';
 import { OverrideConfig, OverrideSection, OverrideEntry } from '../models/config.js';
 import { logger } from '../lib/logger.js';
-import { getNameFromNameParts } from '../lib/resource-path.js';
+import { getNameFromNameParts, isSingletonType } from '../lib/resource-path.js';
 
 /**
  * Map resource types to their top-level override config section key.
@@ -98,13 +98,15 @@ export function applyOverrides(
 
 /**
  * Apply override from a direct section match.
+ * For singleton resources (e.g., ServicePolicy with nameParts: []),
+ * uses the fixed singleton name from the ARM path (e.g., "policy").
  */
 function applyFromSection(
   descriptor: ResourceDescriptor,
   json: Record<string, unknown>,
   section: OverrideSection
 ): Record<string, unknown> {
-  const resourceName = getNameFromNameParts(descriptor.nameParts);
+  const resourceName = getSingletonOrNamePartName(descriptor);
   const entry = findEntryByName(section, resourceName);
 
   if (!entry) {
@@ -116,7 +118,25 @@ function applyFromSection(
   }
 
   // ARM resources have all overridable fields inside 'properties'
-  const wrappedOverride = { properties: entry.properties };
+  let overrideProperties = entry.properties;
+
+  // Strip apiRevision and isCurrent from API overrides — matches Toolkit behavior.
+  // These fields should not be overridden per environment.
+  if (descriptor.type === ResourceType.Api) {
+    const { apiRevision, isCurrent, ...rest } = overrideProperties;
+    if (apiRevision !== undefined || isCurrent !== undefined) {
+      logger.warn(
+        `Ignoring 'apiRevision' and/or 'isCurrent' in API override for '${resourceName}'; ` +
+        `these fields cannot be overridden (matching Toolkit behavior).`
+      );
+    }
+    overrideProperties = rest;
+    if (Object.keys(overrideProperties).length === 0) {
+      return { ...json };
+    }
+  }
+
+  const wrappedOverride = { properties: overrideProperties };
   const result = deepMerge(json, wrappedOverride);
 
   logger.debug(
@@ -129,7 +149,10 @@ function applyFromSection(
 
 /**
  * Apply nested child override (e.g., ApiDiagnostic under apis.children.diagnostics).
- * nameParts layout: [parentName, childName, ...]
+ *
+ * nameParts layout varies by resource type:
+ * - Named children (ApiDiagnostic, ApiOperation, ApiRelease): [parentName, childName]
+ * - Singleton children (ApiPolicy, ProductPolicy): [parentName] (child name is always "policy")
  */
 function applyNestedOverride(
   descriptor: ResourceDescriptor,
@@ -149,8 +172,11 @@ function applyNestedOverride(
   const childSection = parentEntry.children[mapping.childKey];
   if (!childSection) return { ...json };
 
-  // Child name is the second name part (e.g., the diagnostic name, operation name)
-  const childName = descriptor.nameParts[1];
+  // For singleton children (e.g., ApiPolicy), the name is fixed (e.g., "policy"),
+  // NOT in nameParts. For named children, it's nameParts[1].
+  const childName = isSingletonType(descriptor.type)
+    ? getSingletonName(descriptor.type)
+    : descriptor.nameParts[1];
   if (!childName) return { ...json };
 
   const childEntry = findEntryByName(childSection, childName);
@@ -171,8 +197,10 @@ function applyNestedOverride(
 
 /**
  * Apply grandchild (3-level) override.
- * E.g., ApiOperationPolicy: apis[apiName].children.operations[opName].children.policies[policyName]
- * nameParts layout: [parentName, childName, grandchildName]
+ * E.g., ApiOperationPolicy: apis[apiName].children.operations[opName].children.policies[policy]
+ *
+ * nameParts layout for ApiOperationPolicy: [apiName, operationName]
+ * The grandchild name is always the fixed singleton name (e.g., "policy").
  */
 function applyGrandchildOverride(
   descriptor: ResourceDescriptor,
@@ -201,7 +229,8 @@ function applyGrandchildOverride(
   const grandchildSection = childEntry.children[mapping.grandchildKey];
   if (!grandchildSection) return { ...json };
 
-  const grandchildName = descriptor.nameParts[2];
+  // Grandchild is always a singleton (e.g., "policy") — name is NOT in nameParts
+  const grandchildName = getSingletonName(descriptor.type);
   if (!grandchildName) return { ...json };
 
   const grandchildEntry = findEntryByName(grandchildSection, grandchildName);
@@ -220,6 +249,37 @@ function applyGrandchildOverride(
   return result;
 }
 
+/**
+ * Get the resource name for override lookup, handling singletons correctly.
+ * - Top-level singletons (ServicePolicy with nameParts: []) use the fixed singleton name
+ * - Named resources use the last element of nameParts
+ */
+function getSingletonOrNamePartName(descriptor: ResourceDescriptor): string {
+  if (descriptor.nameParts.length === 0) {
+    // Top-level singleton (e.g., ServicePolicy)
+    const name = getSingletonName(descriptor.type);
+    if (!name) {
+      throw new RangeError(
+        `getSingletonOrNamePartName: ${descriptor.type} has empty nameParts ` +
+        `but no known singleton name`
+      );
+    }
+    return name;
+  }
+  return getNameFromNameParts(descriptor.nameParts);
+}
+
+/**
+ * Get the fixed singleton name for a resource type from its ARM path.
+ * E.g., ServicePolicy → "policy", ApiPolicy → "policy", ApiWiki → "default"
+ * Returns undefined if the resource type is not a singleton.
+ */
+function getSingletonName(type: ResourceType): string | undefined {
+  if (!isSingletonType(type)) return undefined;
+  const meta = RESOURCE_TYPE_METADATA[type];
+  return meta.armPathSuffix.split('/').pop();
+}
+
 /**
  * Find an override entry by name using case-insensitive matching.
  */

src/templates/configs/filter-config.ts

@@ -81,6 +81,10 @@ export function generateFilterConfig(): string {
 # schemas:
 #   - pet-schema
 
+# Filter service-level policies
+# policies:
+#   - policy
+
 # Extract only specific policy restrictions
 # policyRestrictions:
 #   - global-policy-restriction

tests/unit/services/filter-service.test.ts

@@ -134,7 +134,7 @@ describe('filter-service', () => {
       expect(shouldIncludeResource(productApi, filter)).toBe(false);
     });
 
-    it('should always include ServicePolicy', () => {
+    it('should include ServicePolicy when policies filter is undefined', () => {
       const filter: FilterConfig = { apis: [] };
       const descriptor: ResourceDescriptor = {
         type: ResourceType.ServicePolicy,
@@ -143,6 +143,22 @@ describe('filter-service', () => {
       expect(shouldIncludeResource(descriptor, filter)).toBe(true);
     });
 
+    it('should filter ServicePolicy via policies key', () => {
+      // ServicePolicy has nameParts: [] — uses fixed singleton name "policy"
+      const descriptor: ResourceDescriptor = {
+        type: ResourceType.ServicePolicy,
+        nameParts: [],
+      };
+
+      // Include when listed
+      const includeFilter: FilterConfig = { policies: ['policy'] };
+      expect(shouldIncludeResource(descriptor, includeFilter)).toBe(true);
+
+      // Exclude when empty array
+      const excludeFilter: FilterConfig = { policies: [] };
+      expect(shouldIncludeResource(descriptor, excludeFilter)).toBe(false);
+    });
+
     it('should filter named values', () => {
       const filter: FilterConfig = { namedValues: ['my-secret'] };
       const included: ResourceDescriptor = {