Improved help messages and updated README

Author: Alessandro Romanelli

README.md

@@ -1,16 +1,64 @@
 # ExpressO
-An Express.js tool to statically analyze the backend, generating the specification for its routes using the OpenAPI standard.
+An Express.js CLI tool to statically analyze the backend, generating the specification for its routes using the OpenAPI standard.
 
 ## Context
 This software is developed in the context of the 2022 Spring semester for the Master Thesis in Software & Data Engineering.
 
 ## How to install
-`npm install expresso`, (optionally -g to install globally);
+`npm install -g expresso`
 
-## How to use
-There are several ways to use the tool:
-- `expresso generate`: will statically analyze your project and generate the corresponding `openapi.yaml` OpenAPI 3.0 specification;
-- `expresso monitor`: will generate the OpenAPI 3.0 specification and add middleware to your Express.js application to monitor route usage and infer payloads schemas;
-- `expresso test <custom_specification>`: will evaluate the generated specification against your provided specification and generate a report of mismatches.
+This will allow you to use the `expresso` command from anywhere.
 
-## Acknowledgements
+## Requirements
+The project for which you wish to generate the OpenAPI specification should:
+- be an Express.js project;
+- be able to complete the start-up without any errors;
+
+## Commands &mdash; How to use
+### Generate
+This command is used to generate the OpenAPI3.0 specification relative to an Express.js project by statically analyzing it.
+
+Usage: `expresso generate [--root] [--start] [--output] [--ext]`
+
+Description:
+
+| Command    | Alias | Description                                                                                                                   | Default              |
+|------------|-------|-------------------------------------------------------------------------------------------------------------------------------|----------------------|
+| `--root`   |       | Specifies the root of the Express.js project to generate an OpenAPI specification for, defaults to current working directory. | `process.cwd()`      |
+| `--start`  |       | The command line that will be used to start the project.                                                                      | `npm start`          |
+| `--output` | `-O`  | Specifies a path of where to output the OpenAPI specification.                                                                | `./expresso-openapi` |
+| `--ext`    | `-E`  | Specifies which format to use for the output between `json` and `yaml`.                                                       | `json`               |
+
+### Monitor
+This command is similar to `generate` but will continue monitoring the backend and periodically update the OpenAPI3.0 specification with metrics about the data coming through the routes.
+
+    Not implemented yet.
+
+### Test 
+This command takes as input another specification and compares it to the one that the tool is able to generate.
+
+    Not implemented yet.
+
+### Compare
+Usage: `expresso compare <fileA> <fileB> [--json]`
+
+Description:
+
+| Command  | Alias | Description                                                    | Default |
+|----------|-------|----------------------------------------------------------------|---------|
+| `--json` | `-J`  | Specifies to produce a JSON instead of a human readable report | `False` |
+
+## Limitations
+Currently, the tool only allows users to extract all the endpoints registered in the application and the corresponding response codes.
+This should suffice to generate the skeleton of a valid OpenAPI documentation.
+
+## Known Issues
+- The response mining has issues with local identifiers. Global constants are self explanatory but local variables (e.g: `status`) does not say anything about the type of response.
+
+## Contributors
+
+| Title | Full Name            | Association                       | Role       |
+|-------|----------------------|-----------------------------------|------------|
+|       | Alessandro Romanelli |                                   | Developer  |
+| Prof. | Cesare Pautasso      | Software Institute (Design Gorup) | Advisor    |
+|       | Souhaila Serbout     | Software Institute (Design Group) | Co-advisor |

src/cli/commands/compare.ts

@@ -9,6 +9,10 @@ export const parseCompareCommandLineArgs = (argv: string[]): CLIOptionsCompare =
   ];
 
   const parseOptions = commandLineArgs(parseCommandDefinitions, { stopAtFirstUnknown: true, argv });
+  if (parseOptions.help) return {
+    fileA: "", fileB: "", json: false, help: true
+  }
+
   if (!parseOptions.files || parseOptions.files.length < 2) {
     throw new Error('Must provide at least two file paths as arguments');
   }

src/lib/expresso/compare.ts

@@ -12,14 +12,13 @@ export const expressoCompare = async (options: CLIOptionsCompare): Promise<void>
 
   if (options.help)
     return console.log(
-      `Usage: expresso compare <fileA> <fileB> [options]
+      `Usage: expresso compare <fileA> <fileB> [--json]
 
 This command compare two user-provided specifications and generates a report of how much the OAPI specification of fileB covers what is specified in fileA.
 
 Available options:
 ${table(
   [
-    ['-H', '--help', 'Prints to console description and options for this command'],
     ['-J', '--json', 'Switches output from human-readable to JSON format'],
   ],
   tableOptions,

src/lib/expresso/generate.ts

@@ -12,18 +12,18 @@ const tableOptions = {
 export const expressoGenerate = async (options: CLIOptionsGenerate): Promise<void> => {
   if (options.help) {
     return console.log(
-      `Usage: expresso generate [root, start, output, ext]
+      `Usage: expresso generate [--root] [--start] [--output] [--ext]
 
 Options descriptions:
 ${table(
   [
     [
-      'root',
+      '--root',
       'the root of the Express.js project to generate an OpenAPI specification for, defaults to current working directory',
     ],
-    ['start', "command line that will be used to start the project, defaults to 'npm start'"],
-    ['output', "specify a path of where to output the OpenAPI specification, defaults to './expresso-openapi'"],
-    ['ext', "specify which format to use for the output, defaults to 'json'"],
+    ['--start', "command line that will be used to start the project, defaults to 'npm start'"],
+    ['--output', "specify a path of where to output the OpenAPI specification, defaults to './expresso-openapi'"],
+    ['--ext', "specify which format to use for the output, defaults to 'json'"],
   ],
   tableOptions,
 )}

src/lib/index.ts

@@ -3,12 +3,12 @@ import { expresso } from './expresso';
 import { ExpressProxy as Express, RouterProxy as Router } from './proxy';
 import * as real_express from 'express-original';
 
-// TODO: Different versions of express?
 module.exports = Express;
 
 for (const k of Object.keys(real_express)) {
-  Reflect.set(module.exports, k, Reflect.get(real_express, k));
+  module.exports[k] = Reflect.get(real_express, k);
 }
 
 module.exports.Router = Router;
 module.exports.expresso = expresso;
+

src/lib/proxy/model/Handler.ts

@@ -50,7 +50,6 @@ export class Handler {
       const fullPath = path.normalize(`${basePath}${p}`);
       Object.assign(endpoints, this._routers[p].getEndpoints(fullPath));
     }
-
     return endpoints;
   }
 

src/lib/replacer/index.ts

@@ -59,7 +59,8 @@ export const replaceExpress = async (basePath: string): Promise<boolean> => {
       path.resolve(npmLibFolder, 'node_modules/expresso-api'),
       path.resolve(basePath, '.expresso-runtime/node_modules/express'),
       {
-        recursive: true
+        recursive: true,
+        overwrite: true
       }
     )
 
@@ -82,6 +83,7 @@ export const replaceExpress = async (basePath: string): Promise<boolean> => {
       path.resolve(basePath, '.expresso-runtime/node_modules/express-original'),
       {
         recursive: true,
+        overwrite: true
       },
     );
     logger.info(`Created 'express' proxy within work copy`);