Filter: preserve inverse flag filtering with stripFlags

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## [1.29.5] - 2026-02-28
 
+- Filter: preserve inverse flag filtering with stripFlags (#193)
 - Types: Update Typescript typings (#194)
 
 ## [1.29.4] - 2026-02-23

openapi-format.js

@@ -794,10 +794,36 @@ async function openapiFilter(oaObj, options) {
     options.unusedDepth === 0 ||
     (stripUnused.length > 0 && unusedComp.meta.total > 0 && options.unusedDepth <= 10)
   ) {
-    options.unusedDepth++;
-    const resultObj = await openapiFilter(jsonObj, options);
+    const stripFlagsSet = new Set(stripFlags);
+    // If a flag is both inverse-kept and stripped in the same pass, recursive
+    // filtering would otherwise remove previously matched operations.
+    const hasInverseFlagsStripConflict = inverseFilterFlags.some(flag => stripFlagsSet.has(flag));
+    // Same conflict check for inverseFlagValues, based on the flag key of each object.
+    const hasInverseFlagValuesStripConflict = inverseFilterFlagValues.some(flagObj =>
+      stripFlagsSet.has(Object.keys(flagObj || {})[0])
+    );
+
+    // Recurse with inverse flag filters disabled only for this conflict case.
+    // This keeps the first-pass inverse selection intact while still allowing
+    // cleanup recursion (unused components, empty objects, etc.).
+    const recurseOptions =
+      hasInverseFlagsStripConflict || hasInverseFlagValuesStripConflict
+        ? {
+            ...options,
+            filterSet: {
+              ...(options.filterSet || {}),
+              inverseFlags: [],
+              inverseFlagValues: []
+            }
+          }
+        : options;
+
+    // Preserve recursion depth semantics regardless of whether we cloned options.
+    recurseOptions.unusedDepth = (recurseOptions.unusedDepth || 0) + 1;
+    const resultObj = await openapiFilter(jsonObj, recurseOptions);
     jsonObj = resultObj.data;
-    unusedComp = JSON.parse(JSON.stringify(options.unusedComp));
+    // Carry forward unused component tracking from the recurse options object.
+    unusedComp = JSON.parse(JSON.stringify(recurseOptions.unusedComp));
   }
 
   // Prepare totalComp for the final result

test/filtering.test.js

@@ -310,6 +310,16 @@ describe('openapi-format CLI filtering tests', () => {
     });
   });
 
+  describe('yaml-filter-inverse-flags-stripFlags', () => {
+    it('yaml-filter-inverse-flags-stripFlags - should match expected output', async () => {
+      const testName = 'yaml-filter-inverse-flags-stripFlags';
+      const {result, outputBefore, outputAfter} = await testUtils.loadTest(testName);
+      expect(result.code).toBe(0);
+      expect(result.stdout).toContain('formatted successfully');
+      expect(outputAfter).toStrictEqual(outputBefore);
+    });
+  });
+
   describe('isUsedComp', () => {
     it('returns false for non-object input', () => {
       expect(isUsedComp(null, 'schemas')).toBe(false);

test/openapi-core.test.js

@@ -26,6 +26,70 @@ describe('openapi-format core API', () => {
     expect(result.data.tags).toEqual([{name: 'pets'}]);
   });
 
+  it('openapiFilter should keep inverseFlags-matched operations when stripFlags removes the same key', async () => {
+    const doc = {
+      openapi: '3.0.0',
+      info: {title: 'API', version: '1.0.0'},
+      paths: {
+        '/pets': {
+          get: {'x-public': true, responses: {200: {description: 'ok'}}},
+          post: {responses: {200: {description: 'ok'}}}
+        }
+      }
+    };
+
+    const onlyInverse = await openapiFilter(doc, {filterSet: {inverseFlags: ['x-public']}});
+    expect(onlyInverse.data.paths).toHaveProperty('/pets.get');
+
+    const inverseAndStrip = await openapiFilter(doc, {
+      filterSet: {inverseFlags: ['x-public'], stripFlags: ['x-public']}
+    });
+    expect(inverseAndStrip.data.paths).toHaveProperty('/pets.get');
+    expect(inverseAndStrip.data.paths['/pets'].get['x-public']).toBeUndefined();
+    expect(inverseAndStrip.data.paths['/pets'].post).toBeUndefined();
+  });
+
+  it('adding responses to unusedComponents should not remove still-referenced schemas', async () => {
+    const doc = {
+      openapi: '3.0.0',
+      info: {title: 'API', version: '1.0.0'},
+      paths: {
+        '/pets': {
+          get: {
+            'x-public': true,
+            responses: {
+              200: {description: 'ok', content: {'application/json': {schema: {$ref: '#/components/schemas/Pet'}}}}
+            }
+          },
+          post: {
+            responses: {
+              200: {description: 'ok', content: {'application/json': {schema: {$ref: '#/components/schemas/Pet'}}}}
+            }
+          }
+        }
+      },
+      components: {
+        schemas: {
+          Pet: {type: 'object'}
+        }
+      }
+    };
+
+    const base = {
+      inverseFlags: ['x-public'],
+      stripFlags: ['x-public'],
+      unusedComponents: ['schemas', 'parameters', 'examples', 'headers', 'requestBodies']
+    };
+    const withResponses = {...base, unusedComponents: [...base.unusedComponents, 'responses']};
+
+    const resultBase = await openapiFilter(doc, {filterSet: base});
+    const resultWithResponses = await openapiFilter(doc, {filterSet: withResponses});
+
+    expect(resultBase.data).toEqual(resultWithResponses.data);
+    expect(resultWithResponses.data.paths).toHaveProperty('/pets.get');
+    expect(resultWithResponses.data.components.schemas).toHaveProperty('Pet');
+  });
+
   it('openapiChangeCase should apply summary, description and securitySchemes ref casing', async () => {
     const doc = {
       openapi: '3.0.0',

test/test.js

@@ -16,7 +16,7 @@ const tests = !localTesting
   ? fs.readdirSync(__dirname).filter(file => {
       return fs.statSync(path.join(__dirname, file)).isDirectory() && !file.startsWith('_');
     })
-  : ['yaml-sort-component-props'];
+  : ['yaml-filter-inverse-flags-stripFlags'];
 
 describe('openapi-format tests', () => {
   let consoleLogSpy, consoleWarnSpy;

test/yaml-filter-inverse-flags-stripFlags/customFilter.yaml

@@ -0,0 +1,11 @@
+inverseFlags:
+  - x-public
+stripFlags:
+  - x-public
+unusedComponents:
+  - schemas
+  - parameters
+  - examples
+  - headers
+  - requestBodies
+  - responses

test/yaml-filter-inverse-flags-stripFlags/input.yaml

@@ -0,0 +1,32 @@
+openapi: 3.0.0
+info:
+  version: 1.0.0
+  title: Swagger Petstore
+paths:
+  /pets:
+    get:
+      operationId: findPets
+      x-public: true
+      responses:
+        '200':
+          description: pet response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Pet'
+    post:
+      operationId: addPet
+      responses:
+        '200':
+          description: pet response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Pet'
+components:
+  schemas:
+    Pet:
+      type: object
+      properties:
+        id:
+          type: integer

test/yaml-filter-inverse-flags-stripFlags/options.yaml

@@ -0,0 +1,4 @@
+verbose: true
+no-sort: true
+output: output.yaml
+filterFile: customFilter.yaml

test/yaml-filter-inverse-flags-stripFlags/output.yaml

@@ -0,0 +1,22 @@
+openapi: 3.0.0
+info:
+  version: 1.0.0
+  title: Swagger Petstore
+paths:
+  /pets:
+    get:
+      operationId: findPets
+      responses:
+        '200':
+          description: pet response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Pet'
+components:
+  schemas:
+    Pet:
+      type: object
+      properties:
+        id:
+          type: integer