@redocly/openapi-core 1.0.0-beta.74 → 1.0.0-beta.78

package/src/format/format.ts

@@ -46,7 +46,7 @@ function severityToNumber(severity: ProblemSeverity) {
   return severity === 'error' ? 1 : 2;
 }
 
-export type OutputFormat = 'codeframe' | 'stylish' | 'json';
+export type OutputFormat = 'codeframe' | 'stylish' | 'json' | 'checkstyle';
 
 export function getTotals(problems: (NormalizedProblem & { ignored?: boolean })[]): Totals {
   let errors = 0;
@@ -111,7 +111,7 @@ export function formatProblems(
         process.stderr.write(`${formatCodeframe(problem, i)}\n`);
       }
       break;
-    case 'stylish':
+    case 'stylish': {
       const groupedByFile = groupByFiles(problems);
       for (const [file, { ruleIdPad, locationPad: positionPad, fileProblems }] of Object.entries(
         groupedByFile,
@@ -126,6 +126,22 @@ export function formatProblems(
         process.stderr.write('\n');
       }
       break;
+    }
+    case 'checkstyle': {
+      const groupedByFile = groupByFiles(problems);
+
+      process.stdout.write('<?xml version="1.0" encoding="UTF-8"?>\n');
+      process.stdout.write('<checkstyle version="4.3">\n');
+
+      for (const [file, { fileProblems }] of Object.entries(groupedByFile)) {
+        process.stdout.write(`<file name="${xmlEscape(path.relative(cwd, file))}">\n`);
+        fileProblems.forEach(formatCheckstyle);
+        process.stdout.write(`</file>\n`);
+      }
+
+      process.stdout.write(`</checkstyle>\n`);
+      break;
+    }
   }
 
   if (totalProblems - ignoredProblems > maxProblems) {
@@ -204,6 +220,16 @@ export function formatProblems(
       locationPad,
     )}  ${severityName}  ${problem.ruleId.padEnd(ruleIdPad)}  ${problem.message}`;
   }
+
+  function formatCheckstyle(problem: OnlyLineColProblem) {
+    const { line, col } = problem.location[0].start;
+    const severity = problem.severity == 'warn' ? 'warning' : 'error';
+    const message = xmlEscape(problem.message);
+    const source = xmlEscape(problem.ruleId);
+    process.stdout.write(
+      `<error line="${line}" column="${col}" severity="${severity}" message="${message}" source="${source}" />\n`,
+    );
+  }
 }
 
 function formatFrom(cwd: string, location?: LocationObject) {
@@ -261,3 +287,22 @@ const groupByFiles = (problems: NormalizedProblem[]) => {
 
   return fileGroups;
 };
+
+function xmlEscape(s: string): string {
+  return s.replace(/[<>&"'\x00-\x1F\x7F\u0080-\uFFFF]/gu, (char) => {
+    switch (char) {
+      case '<':
+        return '&lt;';
+      case '>':
+        return '&gt;';
+      case '&':
+        return '&amp;';
+      case '"':
+        return '&quot;';
+      case "'":
+        return '&apos;';
+      default:
+        return `&#${char.charCodeAt(0)};`;
+    }
+  });
+}

package/src/index.ts

@@ -47,4 +47,4 @@ export {
 export { getAstNodeByPointer, getLineColLocation } from './format/codeframes';
 export { formatProblems, OutputFormat, getTotals, Totals } from './format/format';
 export { lint, lint as validate, lintDocument, lintFromString, lintConfig } from './lint';
-export { bundle, bundleDocument } from './bundle';
+export { bundle, bundleDocument, mapTypeToComponent } from './bundle';

package/src/rules/__tests__/config.ts

@@ -1,10 +1,11 @@
-import { LintConfig, RuleConfig } from "../../config/config";
+import { DecoratorConfig, LintConfig, RuleConfig } from '../../config/config';
 import { defaultPlugin } from '../../config/builtIn';
 
-export function makeConfig(rules: Record<string, RuleConfig>) {
+export function makeConfig(rules: Record<string, RuleConfig>, decorators?:  Record<string, DecoratorConfig>) {
   return new LintConfig({
     plugins: [defaultPlugin],
     extends: [],
-    rules
+    rules,
+    decorators,
   });
-}
+}

package/src/rules/__tests__/hide-internals.test.ts

@@ -0,0 +1,234 @@
+import { outdent } from 'outdent';
+import { bundleDocument } from '../../bundle'
+import { BaseResolver } from '../../resolve';
+import { parseYamlToDocument, yamlSerializer } from '../../../__tests__/utils';
+import { makeConfig } from './config';
+
+describe('oas3 remove-x-internal', () => {
+  expect.addSnapshotSerializer(yamlSerializer);
+  const testDocument = parseYamlToDocument(
+    outdent`
+      openapi: 3.0.0
+      paths:
+        /pet:
+          removeit: true
+          get:
+            parameters:
+              - $ref: '#/components/parameters/x'
+      components:
+        parameters:
+          x:
+            name: x
+    `);
+
+  it('should use `internalFlagProperty` option to remove internal paths', async () => {
+    const { bundle: res } = await bundleDocument({
+      document: testDocument,
+      externalRefResolver: new BaseResolver(),
+      config: makeConfig({}, { 'remove-x-internal': { 'internalFlagProperty': 'removeit' } })
+    });
+    expect(res.parsed).toMatchInlineSnapshot(
+    `
+    openapi: 3.0.0
+    components:
+      parameters:
+        x:
+          name: x
+
+    `);
+  });
+
+  it('should clean types: Server, Operation, Parameter, PathItem, Example', async () => {
+    const testDoc = parseYamlToDocument(
+      outdent`
+        openapi: 3.1.0
+        servers:
+          - url: //petstore.swagger.io/v2
+            description: Default server
+            x-internal: true
+        paths:
+          /pet:
+            get:
+              x-internal: true
+              operationId: getPet
+              parameters:
+                - $ref: '#/components/parameters/x'
+            put:
+              parameters:
+                - name: Accept-Language
+                  x-internal: true
+                  in: header
+                  example: en-US
+                  required: false
+                - name: cookieParam
+                  x-internal: true
+                  in: cookie
+                  description: Some cookie
+                  required: true
+          /admin:
+            x-internal: true
+            post:
+              parameters:
+                - $ref: '#/components/parameters/y'
+          /store/order:
+            post:
+              operationId: placeOrder
+              responses:
+                '200':
+                  description: successful operation
+                  content:
+                    application/json:
+                      examples:
+                        response:
+                          x-internal: true
+                          value: OK
+        components:
+          parameters:
+            x:
+              name: x
+            y:
+              name: y
+      `);
+      const { bundle: res } = await bundleDocument({
+        document: testDoc,
+        externalRefResolver: new BaseResolver(),
+        config: makeConfig({}, { 'remove-x-internal': 'on' })
+      });
+      expect(res.parsed).toMatchInlineSnapshot(
+      `
+      openapi: 3.1.0
+      paths:
+        /pet:
+          put: {}
+        /store/order:
+          post:
+            operationId: placeOrder
+            responses:
+              '200':
+                description: successful operation
+                content:
+                  application/json: {}
+      components:
+        parameters:
+          x:
+            name: x
+          'y':
+            name: 'y'
+
+      `
+      );
+  });
+
+  it('should clean types: Schema, Response, RequestBody, MediaType, Callback', async () => {
+    const testDoc = parseYamlToDocument(
+      outdent`
+        openapi: 3.1.0
+        paths:
+          /pet:
+            post:
+              summary: test
+              requestBody:
+                x-internal: true
+                content:
+                  application/x-www-form-urlencoded:
+                    schema:
+                      type: object
+          /store/order:
+            post:
+              operationId: storeOrder
+              parameters:
+                - name: api_key
+                  schema:
+                    x-internal: true
+                    type: string
+              responses:
+                '200':
+                  x-internal: true
+                  content:
+                    application/json:
+                      examples:
+                        response:
+                          value: OK
+              requestBody:
+                content:
+                  application/x-www-form-urlencoded:
+                    x-internal: true
+                    schema:
+                      type: object
+              callbacks:
+                orderInProgress:
+                  x-internal: true
+                  '{$request.body#/callbackUrl}?event={$request.body#/eventName}':
+                    servers:
+                      - url: //callback-url.path-level/v1
+                        description: Path level server
+      `);
+      const { bundle: res } = await bundleDocument({
+        document: testDoc,
+        externalRefResolver: new BaseResolver(),
+        config: makeConfig({}, { 'remove-x-internal': 'on' })
+      });
+      expect(res.parsed).toMatchInlineSnapshot(
+      `
+      openapi: 3.1.0
+      paths:
+        /pet:
+          post:
+            summary: test
+        /store/order:
+          post:
+            operationId: storeOrder
+            parameters:
+              - name: api_key
+            requestBody: {}
+      components: {}
+
+      `);
+  });
+});
+
+describe('oas2 remove-x-internal', () => {
+  it('should clean types - base test', async () => {
+    const testDoc = parseYamlToDocument(
+      outdent`
+        swagger: '2.0'
+        host: api.instagram.com
+        paths:
+          '/geographies/{geo-id}/media/recent':
+            get:
+              parameters:
+                - description: The geography ID.
+                  x-internal: true
+                  in: path
+                  name: geo-id
+                  required: true
+                  type: string
+                - description: Max number of media to return.
+                  x-internal: true
+                  format: int32
+                  in: query
+                  name: count
+                  required: false
+                  type: integer
+              responses:
+                '200':
+                  x-internal: true
+                  description: List of recent media entries.
+      `);
+    const { bundle: res } = await bundleDocument({
+      document: testDoc,
+      externalRefResolver: new BaseResolver(),
+      config: makeConfig({}, { 'remove-x-internal': 'on' })
+    });
+    expect(res.parsed).toMatchInlineSnapshot(
+    `
+    swagger: '2.0'
+    host: api.instagram.com
+    paths:
+      /geographies/{geo-id}/media/recent:
+        get: {}
+
+    `
+    );
+  });
+});

package/src/rules/common/remove-x-internal.ts

@@ -0,0 +1,42 @@
+import { Oas3Decorator, Oas2Decorator } from '../../visitors';
+import { isEmptyArray, isEmptyObject, isPlainObject } from '../../utils';
+import { UserContext } from '../../walk';
+
+const DEFAULT_INTERNAL_PROPERTY_NAME = 'x-internal';
+
+export const RemoveXInternal: Oas3Decorator | Oas2Decorator = ({ internalFlagProperty }) => {
+  const hiddenTag = internalFlagProperty || DEFAULT_INTERNAL_PROPERTY_NAME;
+
+  function removeInternal(node: any, ctx: UserContext) {
+    const { parent, key } = ctx;
+    let didDelete = false;
+    if (Array.isArray(node)) {
+      for (let i = 0; i < node.length; i++) {
+        if (node[i] && node[i][hiddenTag]) {
+          node.splice(i, 1);
+          didDelete = true;
+          i--;
+        }
+      }
+    } else if (isPlainObject(node)) {
+      for (const key of Object.keys(node)) {
+        if ((node as any)[key][hiddenTag]) {
+          delete (node as any)[key];
+          didDelete = true;
+        }
+      }
+    }
+
+    if (didDelete && (isEmptyObject(node) || isEmptyArray(node))) {
+      delete parent[key];
+    }
+  }
+
+  return {
+    any: {
+      enter: (node, ctx) => {
+        removeInternal(node, ctx);
+      }
+    }
+  }
+}

package/src/rules/oas2/index.ts

@@ -1,3 +1,4 @@
+import { Oas2Decorator, Oas2Rule } from '../../visitors';
 import { OasSpec } from '../common/spec';
 import { NoInvalidSchemaExamples } from '../common/no-invalid-schema-examples';
 import { NoInvalidParameterExamples } from '../common/no-invalid-parameter-examples';
@@ -26,7 +27,6 @@ import { OperationSingularTag } from '../common/operation-singular-tag';
 import { OperationSecurityDefined } from '../common/operation-security-defined';
 import { NoUnresolvedRefs } from '../no-unresolved-refs';
 import { PathHttpVerbsOrder } from '../common/path-http-verbs-order';
-import { Oas2Decorator, Oas2Rule } from '../../visitors';
 import { RegistryDependencies } from '../common/registry-dependencies';
 import { NoIdenticalPaths } from '../common/no-identical-paths';
 import { OperationOperationId } from '../common/operation-operationId';
@@ -40,6 +40,7 @@ import { PathSegmentPlural } from '../common/path-segment-plural';
 import { OperationDescriptionOverride } from '../common/operation-description-override';
 import { TagDescriptionOverride } from '../common/tag-description-override';
 import { InfoDescriptionOverride } from '../common/info-description-override';
+import { RemoveXInternal } from '../common/remove-x-internal';
 
 export const rules = {
   spec: OasSpec as Oas2Rule,
@@ -88,4 +89,5 @@ export const decorators = {
   'operation-description-override': OperationDescriptionOverride as Oas2Decorator,
   'tag-description-override': TagDescriptionOverride as Oas2Decorator,
   'info-description-override': InfoDescriptionOverride as Oas2Decorator,
+  'remove-x-internal': RemoveXInternal as Oas2Decorator
 };

package/src/rules/oas2/remove-unused-components.ts

@@ -0,0 +1,74 @@
+import { Oas2Rule } from '../../visitors';
+import { Location } from '../../ref-utils';
+import { Oas2Components } from '../../typings/swagger';
+import { isEmptyObject } from '../../utils';
+
+export const RemoveUnusedComponents: Oas2Rule = () => {
+  let components = new Map<string, { used: boolean; componentType?: keyof Oas2Components; name: string }>();
+
+  function registerComponent(location: Location, componentType: keyof Oas2Components, name: string): void {
+    components.set(location.absolutePointer, {
+      used: components.get(location.absolutePointer)?.used || false,
+      componentType,
+      name,
+    });
+  }
+
+  return {
+    ref(ref, { type, resolve, key }) {
+      if (
+        ['Schema', 'Parameter', 'Response', 'SecurityScheme'].includes(type.name)
+      ) {
+        const resolvedRef = resolve(ref);
+        if (!resolvedRef.location) return;
+        components.set(resolvedRef.location.absolutePointer, {
+          used: true,
+          name: key.toString(),
+        });
+      }
+    },
+    DefinitionRoot: {
+      leave(root, ctx) {
+        const data = ctx.getVisitorData() as { removedCount: number };
+        data.removedCount = 0;
+
+        let rootComponents = new Set<keyof Oas2Components>();
+        components.forEach(usageInfo => {
+          const { used, name, componentType } = usageInfo;
+          if (!used && componentType) {
+            rootComponents.add(componentType);
+            delete root[componentType]![name];
+            data.removedCount++;
+          }
+        });
+        for (const component of rootComponents) {
+          if (isEmptyObject(root[component])) {
+            delete root[component];
+          }
+        }
+      },
+    },
+    NamedSchemas: {
+      Schema(schema, { location, key }) {
+        if (!schema.allOf) {
+          registerComponent(location, 'definitions', key.toString());
+        }
+      },
+    },
+    NamedParameters: {
+      Parameter(_parameter, { location, key }) {
+        registerComponent(location, 'parameters', key.toString());
+      },
+    },
+    NamedResponses: {
+      Response(_response, { location, key }) {
+        registerComponent(location, 'responses', key.toString());
+      },
+    },
+    NamedSecuritySchemes: {
+      SecurityScheme(_securityScheme, { location, key }) {
+        registerComponent(location, 'securityDefinitions', key.toString());
+      },
+    }
+  };
+};

package/src/rules/oas3/index.ts

@@ -49,6 +49,7 @@ import { InfoDescriptionOverride } from '../common/info-description-override';
 import { PathExcludesPatterns } from '../common/path-excludes-patterns';
 import { NoInvalidSchemaExamples } from '../common/no-invalid-schema-examples';
 import { NoInvalidParameterExamples } from '../common/no-invalid-parameter-examples';
+import { RemoveXInternal } from '../common/remove-x-internal';
 
 export const rules = {
   spec: OasSpec,
@@ -106,4 +107,5 @@ export const decorators = {
   'operation-description-override': OperationDescriptionOverride as Oas3Decorator,
   'tag-description-override': TagDescriptionOverride as Oas3Decorator,
   'info-description-override': InfoDescriptionOverride as Oas3Decorator,
+  'remove-x-internal': RemoveXInternal as Oas3Decorator
 };

package/src/rules/oas3/remove-unused-components.ts

@@ -0,0 +1,82 @@
+import { Oas3Rule } from '../../visitors';
+import { Location } from '../../ref-utils';
+import { Oas3Components } from '../../typings/openapi'
+import { isEmptyObject } from '../../utils';
+
+export const RemoveUnusedComponents: Oas3Rule = () => {
+  let components = new Map<string, { used: boolean; componentType?: keyof Oas3Components; name: string }>();
+
+  function registerComponent(location: Location, componentType: keyof Oas3Components, name: string): void {
+    components.set(location.absolutePointer, {
+      used: components.get(location.absolutePointer)?.used || false,
+      componentType,
+      name,
+    });
+  }
+
+  return {
+    ref(ref, { type, resolve, key }) {
+      if (
+        ['Schema', 'Header', 'Parameter', 'Response', 'Example', 'RequestBody'].includes(type.name)
+      ) {
+        const resolvedRef = resolve(ref);
+        if (!resolvedRef.location) return;
+        components.set(resolvedRef.location.absolutePointer, {
+          used: true,
+          name: key.toString(),
+        });
+      }
+    },
+    DefinitionRoot: {
+      leave(root, ctx) {
+        const data = ctx.getVisitorData() as { removedCount: number };
+        data.removedCount = 0;
+
+        components.forEach(usageInfo => {
+          const { used, componentType, name } = usageInfo;
+          if (!used && componentType) {
+            let componentChild = root.components![componentType];
+            delete componentChild![name];
+            data.removedCount++;
+            if (isEmptyObject(componentChild)) {
+              delete root.components![componentType];
+            }
+          }
+        });
+        if (isEmptyObject(root.components)) { delete root.components; }
+      },
+    },
+    NamedSchemas: {
+      Schema(schema, { location, key }) {
+        if (!schema.allOf) {
+          registerComponent(location, 'schemas', key.toString());
+        }
+      },
+    },
+    NamedParameters: {
+      Parameter(_parameter, { location, key }) {
+        registerComponent(location, 'parameters', key.toString());
+      },
+    },
+    NamedResponses: {
+      Response(_response, { location, key }) {
+        registerComponent(location, 'responses', key.toString());
+      },
+    },
+    NamedExamples: {
+      Example(_example, { location, key }) {
+        registerComponent(location, 'examples', key.toString());
+      },
+    },
+    NamedRequestBodies: {
+      RequestBody(_requestBody, { location, key }) {
+        registerComponent(location, 'requestBodies', key.toString());
+      },
+    },
+    NamedHeaders: {
+      Header(_header, { location, key }) {
+        registerComponent(location, 'headers', key.toString());
+      },
+    },
+  };
+};

package/src/types/oas2.ts

@@ -383,13 +383,10 @@ export const Oas2Types: Record<string, NodeType> = {
   Schema,
   Xml,
   SchemaProperties,
-
   NamedSchemas: mapOf('Schema'),
   NamedResponses: mapOf('Response'),
   NamedParameters: mapOf('Parameter'),
   NamedSecuritySchemes: mapOf('SecurityScheme'),
-
   SecurityScheme,
-
   XCodeSample,
 };

package/src/typings/swagger.ts

@@ -20,6 +20,13 @@ export interface Oas2Definition {
   externalDocs?: Oas2ExternalDocs;
 }
 
+export interface Oas2Components {
+  definitions?: { [name: string]: Record<string, Oas2Schema> };
+  securityDefinitions?: { [name: string]: Record<string, Oas2SecurityScheme> };
+  responses?: { [name: string]: Record<string, Oas2Response> };
+  parameters?: { [name: string]: Record<string, Oas2Parameter> };
+}
+
 export interface Oas2Info {
   title: string;
   version: string;

package/src/utils.ts

@@ -40,6 +40,14 @@ export function isPlainObject(value: any): value is object {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
+export function isEmptyObject(value: any): value is object {
+  return isPlainObject(value) && Object.keys(value).length === 0;
+}
+
+export function isEmptyArray(value: any) {
+  return Array.isArray(value) && value.length === 0;
+}
+
 export async function readFileFromUrl(url: string, config: HttpResolveConfig) {
   const headers: Record<string, string> = {};
   for (const header of config.headers) {

package/src/walk.ts

@@ -212,16 +212,14 @@ export function walkDocument<T>(opts: {
             if (!activatedOn.skipped) {
               visitedBySome = true;
               enteredContexts.add(context);
-              const ignoreNextVisitorsOnNode = visitWithContext(
+              const { ignoreNextVisitorsOnNode } = visitWithContext(
                 visit,
                 resolvedNode,
                 context,
                 ruleId,
                 severity,
               );
-              if (ignoreNextVisitorsOnNode) {
-                break;
-              }
+              if (ignoreNextVisitorsOnNode) break;
             }
           }
         }
@@ -358,16 +356,13 @@ export function walkDocument<T>(opts: {
           key,
           parentLocations: collectParentsLocations(context),
           oasVersion: ctx.oasVersion,
-          ignoreNextVisitorsOnNode: () => {
-            ignoreNextVisitorsOnNode = true;
-          },
+          ignoreNextVisitorsOnNode: () => { ignoreNextVisitorsOnNode = true; },
           getVisitorData: getVisitorDataFn.bind(undefined, ruleId),
         },
         collectParents(context),
         context,
       );
-
-      return ignoreNextVisitorsOnNode;
+      return { ignoreNextVisitorsOnNode };
     }
 
     function resolve<T>(