chore: remove unimplemented --spec-format option

The --spec-format CLI option for extract was spec'd but never
implemented. Since issue #9 has been closed without implementation,
this commit removes all references from:

- Source code (extract-command.ts, config.ts)
- Tests (extract-command.test.ts)
- Documentation (README.md, docs/commands/extract.md)
- Specs (cli-commands.md, data-model.md, spec.md, research.md, tasks.md)

Historical references in .squad/ decision records are preserved
as they document what was intentionally not implemented.

Closes #9

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

Author: Peter Hauge

README.md

@@ -47,7 +47,6 @@ Extract APIM service configuration to local artifact files.
 | `--output <dir>` | `./apim-artifacts` | Output directory |
 | `--filter <path>` | | Extract only matching resources |
 | `--no-transitive` | | Skip transitive dependencies |
-| `--spec-format <format>` | | Override API spec format |
 
 ```bash
 apiops extract --help
@@ -58,12 +57,11 @@ apiops extract \
   --service-name <name> \
   --output ./apim-artifacts
 
-# Extract a filtered subset of resources and override the API spec format
+# Extract a filtered subset of resources
 apiops extract \
   --resource-group <rg> \
   --service-name <name> \
-  --filter ./filter.yaml \
-  --spec-format openapi-v3-yaml
+  --filter ./filter.yaml
 
 # Authenticate explicitly with a service principal
 apiops extract \

docs/commands/extract.md

@@ -66,7 +66,6 @@ apiops extract \
 | `--output <dir>` | string | `./apim-artifacts` | No | Output directory path |
 | `--filter <path>` | string | — | No | Filter configuration YAML file |
 | `--no-transitive` | boolean | false (transitive ON) | No | Disable transitive dependency inclusion |
-| `--spec-format <format>` | string | — | No | API spec format: `openapi-v2-json`, `openapi-v3-json`, `openapi-v3-yaml` |
 
 ### Global flags
 

specs/contracts/cli-commands.md

@@ -35,7 +35,6 @@ Extract APIM configuration to local artifact files.
 | `--output <dir>` | string | no | `./apim-artifacts` | Output directory path |
 | `--filter <path>` | string | no | — | Filter configuration YAML file |
 | `--no-transitive` | boolean | no | `false` | Disable transitive dependency inclusion |
-| `--spec-format <format>` | string | no | — | API specification format (`openapi-v2-json`, `openapi-v3-json`, `openapi-v3-yaml`); native format used when omitted or conversion not possible |
 
 **stdout**: Per-resource status lines (one per extracted resource)  
 **stderr**: Structured log messages (JSON when `--verbose`)  

specs/data-model.md

@@ -150,7 +150,6 @@ interface ExtractConfig {
   outputDir: string;
   filter?: FilterConfig;
   includeTransitive: boolean;   // Default: true; false when --no-transitive
-  specFormat?: string;          // From --spec-format; undefined = native format
   verbose: boolean;
   otelConfigPath?: string;
 }

specs/research.md

@@ -254,7 +254,6 @@ program.command('extract')
   .option('--output <dir>', 'Output directory', './apim-artifacts')
   .option('--filter <path>', 'Filter configuration YAML file')
   .option('--no-transitive', 'Disable transitive dependency inclusion')
-  .option('--spec-format <format>', 'API specification format')
   .action(extractAction)
 
 program.command('publish')

specs/spec.md

@@ -35,9 +35,7 @@ A platform engineer wants to capture the current state of an Azure API Managemen
 
 3. **Given** the user only wants a subset of resources, **When** the user provides a filter configuration file via `--filter filter.yaml`, **Then** only the resources matching the allowlist in the configuration file are extracted, along with any resources those filtered resources transitively depend on (e.g., backends, named values, loggers referenced in policies). The user can suppress transitive inclusion with `--no-transitive`.
 
-4. **Given** an APIM instance with APIs using different specification formats (OpenAPI v2/v3, GraphQL, SOAP/WSDL), **When** the user runs extract with a `--spec-format` option, **Then** API specifications are exported in the requested format where format conversion is possible, and in their native format otherwise.
-
-5. **Given** an APIM instance, **When** the user runs `apiops extract --format json`, **Then** machine-readable JSON progress output is written to stdout (resource counts, file paths written) suitable for CI/CD pipeline consumption.
+4. **Given** an APIM instance, **When** the user runs `apiops extract --format json`, **Then** machine-readable JSON progress output is written to stdout (resource counts, file paths written) suitable for CI/CD pipeline consumption.
 
 7. **Given** an APIM instance with APIs that have multiple revisions (e.g., `orders-api;rev=1`, `orders-api;rev=2`), **When** the user runs `apiops extract`, **Then** all revisions are extracted as sub-folders under the API directory, preserving revision numbers and metadata.
 

specs/tasks.md

@@ -68,7 +68,7 @@
 - [ ] T025 [US1] Implement transitive dependency resolver in src/services/transitive-resolver.ts (scan policies for named value refs \{\{name\}\}, backend refs set-backend-service, policy fragment refs include-fragment; scan apiInformation.json for apiVersionSetId; fixed-point expansion; --no-transitive bypass per research.md R4)
 - [ ] T026 [US1] Implement secret redaction in src/services/secret-redactor.ts (detect properties.secret === true on named values, replace properties.value with redaction marker per research.md R5)
 - [ ] T027 [US1] Implement workspace-scoped extraction in src/services/workspace-extractor.ts (list workspaces, extract workspace-scoped resources under workspaces/{name}/ using same resource-extractor with workspace context prefix per FR-010)
-- [ ] T028 [US1] Register extract command in src/cli/extract-command.ts (Commander subcommand with --resource-group, --service-name, --output, --filter, --no-transitive, --spec-format flags; wire to extract-service per contracts/cli-commands.md)
+- [ ] T028 [US1] Register extract command in src/cli/extract-command.ts (Commander subcommand with --resource-group, --service-name, --output, --filter, --no-transitive flags; wire to extract-service per contracts/cli-commands.md)
 - [ ] T029 [US1] Implement JSON output mode for extract in src/cli/extract-command.ts (--format json: machine-readable JSON to stdout with resource counts and file paths per FR-013)
 
 **Checkpoint**: `apiops extract` works end-to-end for all 33 resource types with filtering, parallelism, and secret redaction
@@ -158,7 +158,6 @@
 
 - [ ] T055 [P] Implement OTel integration in src/lib/otel-setup.ts (load --otel config YAML, initialize NodeSDK with OTLP exporter, create spans per resource type/resource, metrics for counts/duration per research.md R9)
 - [ ] T056 [P] Add --api-version global flag support in src/cli/index.ts and src/clients/apim-client.ts (override default 2024-05-01 per FR-012)
-- [ ] T057 [P] Implement --spec-format option for extract in src/services/api-extractor.ts (request specific format from APIM export API where conversion supported; fallback to native with warning per FR-011)
 - [ ] T058 Run quickstart.md validation (execute each quickstart command against a test APIM instance, verify expected outputs)
 - [ ] T059 Add bin entry to package.json and shebang to src/cli/index.ts for global npm install (`npx apiops` / `npm install -g`)
 
@@ -248,4 +247,4 @@ T029: JSON output mode         → src/cli/extract-command.ts
 4. Add US3 (CI/CD) → Test in GitHub Actions pipeline
 5. Add US4 (Init) → Test scaffold generation in empty repo
 6. Add US5 (Extensibility) → Verify new command pattern
-7. Polish → OTel, spec-format, quickstart validation
+7. Polish → OTel, quickstart validation

src/cli/extract-command.ts

@@ -3,7 +3,7 @@
 /**
  * Extract command CLI registration
  * Commander subcommand with --resource-group, --service-name, --output,
- * --filter, --no-transitive, --spec-format flags.
+ * --filter, --no-transitive flags.
  * Includes --format json: machine-readable JSON output mode.
  */
 
@@ -26,7 +26,6 @@ interface ExtractOptions {
   output: string;
   filter?: string;
   transitive: boolean;
-  specFormat?: string;
 }
 
 /**
@@ -40,7 +39,6 @@ export function createExtractCommand(): Command {
     .option('--output <dir>', 'Output directory path', './apim-artifacts')
     .option('--filter <path>', 'Filter configuration YAML file')
     .option('--no-transitive', 'Disable transitive dependency inclusion')
-    .option('--spec-format <format>', 'API specification format (openapi-v2-json, openapi-v3-json, openapi-v3-yaml)')
     .action(async (options: ExtractOptions, command: Command) => {
       const globalOpts = command.optsWithGlobals<{
         logLevel?: string;
@@ -109,7 +107,6 @@ async function executeExtract(
     outputDir: options.output,
     filter: filterConfig,
     includeTransitive: options.transitive,
-    specFormat: options.specFormat,
     logLevel: parseLogLevel(globalOpts.logLevel ?? 'info'),
   };
 

src/models/config.ts

@@ -13,7 +13,6 @@ export interface ExtractConfig {
   outputDir: string;
   filter?: FilterConfig;
   includeTransitive: boolean;
-  specFormat?: string;
   logLevel: LogLevel;
   otelConfigPath?: string;
 }

tests/unit/cli/extract-command.test.ts

@@ -52,13 +52,6 @@ describe('extract-command', () => {
       expect(noTransOpt).toBeDefined();
     });
 
-    it('should have --spec-format option', () => {
-      const cmd = createExtractCommand();
-      const opts = cmd.options;
-      const specOpt = opts.find((o) => o.long === '--spec-format');
-      expect(specOpt).toBeDefined();
-    });
-
     it('should have a description', () => {
       const cmd = createExtractCommand();
       expect(cmd.description()).toBeTruthy();