add warnings and errors and change up api

Author: bourdakos1

example/src/app.js

@@ -1,14 +1,12 @@
-const path = require('path');
-
 const swaggerUi = require('swagger-ui-express');
 const express = require('express');
 
 const parseComments = require('../../dist/openapi-comment-parser');
 
-const swaggerDefinition = require('./swaggerDefinition');
 const petRouter = require('./routes/pet');
 const storeRouter = require('./routes/store');
 const userRouter = require('./routes/user');
+const definition = require('./openapi-definition');
 
 const app = express();
 const PORT = 3000;
@@ -17,10 +15,7 @@ const PORT = 3000;
 app.use(express.json());
 app.use(express.urlencoded({ extended: false }));
 
-const spec = parseComments({
-  definition: swaggerDefinition,
-  paths: [path.join(__dirname, '**/*.?(js|yaml|yml)')],
-});
+const spec = parseComments(definition);
 
 app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(spec));
 

example/src/swaggerDefinition.js example/src/openapi-definition.jsexample/src/swaggerDefinition.js renamed to example/src/openapi-definition.js

@@ -1,4 +1,4 @@
-const swaggerDefinition = {
+const definition = {
   openapi: '3.0.3',
   info: {
     title: 'Swagger Petstore',
@@ -42,4 +42,4 @@ const swaggerDefinition = {
   },
 };
 
-module.exports = swaggerDefinition;
+module.exports = definition;

package.json

@@ -36,12 +36,12 @@
     "build": "run-s clean bundle",
     "clean": "rimraf dist",
     "bundle": "rollup -c && cp src/exported.d.ts dist/openapi-comment-parser.d.ts",
-    "prepublishOnly": "npm run build",
-    "mid": "nodemon -e yaml,yml,js,mjs,json middleware/src/app.js"
+    "prepublishOnly": "npm run build"
   },
   "dependencies": {},
   "devDependencies": {
     "@rollup/plugin-commonjs": "^11.1.0",
+    "@rollup/plugin-json": "^4.0.3",
     "@rollup/plugin-node-resolve": "^7.1.3",
     "@rollup/plugin-sucrase": "^3.0.1",
     "@types/chai": "^4.2.11",
@@ -51,13 +51,16 @@
     "@types/sinon": "^9.0.4",
     "@types/sinon-chai": "^3.2.4",
     "body-parser": "1.19.0",
+    "caller-callsite": "^4.1.0",
     "chai": "4.2.0",
+    "chalk": "^4.0.0",
     "comment-parser": "^0.7.4",
     "eslint": "6.8.0",
     "eslint-config-airbnb-base": "14.1.0",
     "eslint-config-prettier": "6.10.1",
     "eslint-loader": "3.0.3",
     "eslint-plugin-import": "2.20.1",
+    "eslint-plugin-openapi-jsdoc": "^0.0.3",
     "eslint-plugin-prettier": "3.1.2",
     "globby": "^11.0.0",
     "js-yaml": "^3.13.1",

rollup.config.js

@@ -1,19 +1,22 @@
 import resolve from '@rollup/plugin-node-resolve';
 import commonjs from '@rollup/plugin-commonjs';
 import sucrase from '@rollup/plugin-sucrase';
+import json from '@rollup/plugin-json';
+
 import pkg from './package.json';
 
 export default [
   {
     input: 'src/index.ts',
     plugins: [
       resolve(), // so Rollup can find external packages
-      commonjs(), // so Rollup can convert external packages to ES modules
+      commonjs({ ignoreGlobal: true }), // so Rollup can convert external packages to ES modules
       sucrase({
         // so Rollup can convert TypeScript to JavaScript
         exclude: ['node_modules/**', '**/?(*.)test.ts'],
         transforms: ['typescript'],
       }),
+      json(),
     ],
     output: [
       { file: pkg.main, format: 'cjs' },

src/exported.d.ts

@@ -1,6 +1,9 @@
 export interface ParserOptions {
-	definition: BaseDefinition;
-	paths: string[];
+	root?: string;
+	extension?: string[];
+	include?: string[];
+	exclude?: string[];
+	excludeNodeModules?: boolean;
 	verbose?: boolean;
 }
 
@@ -262,7 +265,7 @@ export interface Map<T> {
 	[key: string]: T;
 }
 
-declare function parseComments({
-	definition,
-	paths,
-}: ParserOptions): OpenApiObject;
+declare function parseComments(
+	definition: BaseDefinition | string,
+	options: ParserOptions
+): OpenApiObject;

src/index.ts

@@ -1,41 +1,118 @@
+import path from 'path';
 import jsYaml from 'js-yaml';
+import callerCallsite from 'caller-callsite';
+import chalk from 'chalk';
+
+// @ts-ignore
+import { Linter } from 'eslint';
+// @ts-ignore
+import openapiEslintPlugin from 'eslint-plugin-openapi-jsdoc';
 
 import parseFile from './util/parseFile';
 import globList from './util/globList';
 import SpecBuilder from './SpecBuilder';
-import { ParserOptions, OpenApiObject } from './exported';
+import { ParserOptions, OpenApiObject, BaseDefinition } from './exported';
 import yamlLOC from './util/yamlLOC';
+import loadDefinition from './util/loadDefinition';
+import formatter from './util/formatter';
 
-function parseComments({
-	definition,
-	paths,
-	verbose = true,
-}: ParserOptions): OpenApiObject {
-	if (!definition && !paths) {
-		throw new Error('Provided options are incorrect.');
+function getCallerPath() {
+	const filename = callerCallsite()?.getFileName();
+	if (filename) {
+		return path.dirname(filename);
 	}
+	return '';
+}
+
+function parseComments(
+	definition: BaseDefinition | string,
+	{
+		root = getCallerPath(),
+		extension = ['.js', '.cjs', '.mjs', '.ts', '.tsx', '.jsx', '.yaml', '.yml'],
+		include = ['**'],
+		exclude = [
+			'coverage/**',
+			'packages/*/test{,s}/**',
+			'**/*.d.ts',
+			'test{,s}/**',
+			`test{,-*}.{js,cjs,mjs,ts,tsx,jsx,yaml,yml}`,
+			`**/*{.,-}test.{js,cjs,mjs,ts,tsx,jsx,yaml,yml}`,
+			'**/__tests__/**',
 
-	const spec = new SpecBuilder(definition);
+			/* Exclude common development tool configuration files */
+			'**/{ava,babel,nyc}.config.{js,cjs,mjs}',
+			'**/jest.config.{js,cjs,mjs,ts}',
+			'**/{karma,rollup,webpack}.config.js',
+			'**/.{eslint,mocha}rc.{js,cjs}',
 
-	const files = globList(paths);
+			// always ignore '**/node_modules/**'
+		],
+		excludeNodeModules = true,
+		verbose = true,
+	}: ParserOptions = {}
+): OpenApiObject {
+	if (!definition) {
+		throw new Error('A base OpenAPI definition is required.');
+	}
+
+	let definitionObject: BaseDefinition;
+	if (typeof definition === 'string') {
+		definitionObject = loadDefinition(definition);
+	} else {
+		definitionObject = definition;
+	}
+
+	const spec = new SpecBuilder(definitionObject);
+
+	const files = globList(root, extension, include, exclude, excludeNodeModules);
+
+	const linter = new Linter();
+	linter.defineRules({
+		...openapiEslintPlugin.rules,
+	});
 
 	let totalLOC = 0;
+	let allMessages: any[] = [];
 	files.forEach((file) => {
-		const parsedFile = parseFile(file, verbose);
+		const { parsedFile, messages } = parseFile(file, linter, verbose);
+		allMessages.push({ filePath: file, messages: messages });
 		const specs = parsedFile.map((item) => item.spec);
 		const loc = parsedFile.reduce((acc, cur) => (acc += cur.loc), 0);
 		totalLOC += loc;
 		spec.addData(specs);
 	});
 
 	if (verbose) {
-		const specAsYaml = jsYaml.safeDump(JSON.parse(JSON.stringify(spec)));
-		const originalLOC = yamlLOC(specAsYaml);
+		const errorTable = formatter(allMessages);
+		if (errorTable) {
+			console.log(errorTable);
+		}
+
+		// Only measure paths and components.
+		let pathsAsYaml = '';
+		if (spec.paths) {
+			pathsAsYaml = jsYaml.safeDump(JSON.parse(JSON.stringify(spec.paths)));
+		}
+		let componentAsYaml = '';
+		if (spec.components) {
+			componentAsYaml = jsYaml.safeDump(
+				JSON.parse(JSON.stringify(spec.components))
+			);
+		}
+		const originalLOC = yamlLOC(pathsAsYaml) + yamlLOC(componentAsYaml);
 		const locDiff = originalLOC - totalLOC;
 		const savings = (locDiff / originalLOC) * 100;
-		console.log(
-			`✨ You've saved ${locDiff} lines of extra YAML (${savings.toFixed(1)}%)`
-		);
+		if (locDiff > 0) {
+			console.log();
+			console.log(
+				`✨ You've saved ${chalk.bold(
+					locDiff
+				)} lines of extra YAML (${chalk.green.bold(
+					`\u25BC ${savings.toFixed(1)}%`
+				)})`
+			);
+			console.log();
+		}
 	}
 
 	return spec;

src/util/formatter.ts

@@ -0,0 +1,61 @@
+import chalk from 'chalk';
+
+function pluralize(word: string, count: number) {
+	return count === 1 ? word : `${word}s`;
+}
+
+function formatter(results: any[]) {
+	let output = '\n';
+	let errorCount = 0;
+	let warningCount = 0;
+
+	results.forEach((result) => {
+		const messages = result.messages;
+
+		if (messages.length === 0) {
+			return;
+		}
+
+		output += `${chalk.underline(result.filePath)}\n`;
+
+		const maxPositionWidth = messages.reduce((acc: number, message: any) => {
+			const position = `${message.line || 0}:${message.column || 0}`;
+			return Math.max(acc, position.length);
+		}, 0);
+
+		output += `${messages
+			.map((message: any) => {
+				let position = `${message.line || 0}:${message.column || 0}`;
+				position += ' '.repeat(maxPositionWidth - position.length);
+				let messageType;
+				if (message.severity === 2) {
+					messageType = chalk.red('error  ');
+					errorCount++;
+				} else {
+					messageType = chalk.yellow('warning');
+					warningCount++;
+				}
+				return `  ${chalk.dim(position)}  ${messageType}  ${message.message}`;
+			})
+			.join('\n')}\n\n`;
+	});
+
+	const total = errorCount + warningCount;
+
+	const problems = `${total} ${pluralize('problem', total)}`;
+	const errors = `${errorCount} ${pluralize('error', errorCount)}`;
+	const warnings = `${warningCount} ${pluralize('warning', warningCount)}`;
+
+	const summary = `\u2716 ${problems} (${errors}, ${warnings})`;
+
+	if (errorCount > 0) {
+		output += chalk.red.bold(summary);
+	} else {
+		output += chalk.yellow.bold(summary);
+	}
+
+	// Resets output color, for prevent change on top level
+	return total > 0 ? chalk.reset(output) : '';
+}
+
+export default formatter;

src/util/globList.ts

@@ -1,7 +1,34 @@
+import path from 'path';
 import { sync as glob } from 'globby';
 
-function convertGlobPaths(globs: string[]): string[] {
-	return globs.map((globString) => glob(globString)).flat();
+function convertGlobPaths(
+	root: string,
+	extension: string[],
+	include: string[],
+	exclude: string[],
+	excludeNodeModules: boolean
+): string[] {
+	const included = include
+		.map((globString) => glob(path.join(root, globString)))
+		.flat();
+
+	if (excludeNodeModules) {
+		exclude.push('**/node_modules/**');
+	}
+
+	const excluded = exclude
+		.map((globString) => glob(path.join(root, globString)))
+		.flat();
+
+	return included.filter((file) => {
+		if (excluded.includes(file)) {
+			return false;
+		}
+		if (extension.includes(path.extname(file))) {
+			return true;
+		}
+		return false;
+	});
 }
 
 export default convertGlobPaths;

src/util/loadDefinition.ts

@@ -0,0 +1,23 @@
+import fs from 'fs';
+import path from 'path';
+
+import jsYaml from 'js-yaml';
+
+import { BaseDefinition } from '../exported';
+
+function parseFile(file: string): BaseDefinition {
+	const ext = path.extname(file);
+	if (ext !== '.yaml' && ext !== '.yml' && ext !== '.json') {
+		throw new Error('OpenAPI definition path must be YAML or JSON.');
+	}
+
+	const fileContent = fs.readFileSync(file, { encoding: 'utf8' });
+
+	if (ext === '.yaml' || ext === '.yml') {
+		return jsYaml.safeLoad(fileContent);
+	} else {
+		return JSON.parse(fileContent);
+	}
+}
+
+export default parseFile;