appmap 0.62.0 → 0.62.1

data/node_modules/@appland/cli/src/search/types.d.ts

@@ -0,0 +1,107 @@
+export interface SQL {
+  sql: string;
+  database_type: string;
+}
+
+export interface HTTPRoute {
+  method: string;
+  uri: string;
+}
+
+export interface HTTPRequest {
+  route: HTTPRoute;
+  parameterNames: string[];
+  statusCode: int;
+}
+ 
+export interface HTTPServerRequest {
+  path: string;
+  normalized_path: string;
+  headers: {string:string};
+}
+
+export interface Event {
+  id: integer;
+  type: string;
+  definedClass: string;
+  methodId: string;
+  labels: Set;
+  sql: SQL;
+  httpServerRequest: HTTPServerRequest;
+  sqlQuery: string;
+  isFunction: bool;
+  returnValue: any;
+  callEvent: Event;
+  returnEvent: Event;
+  codeObject: CodeObject;
+  isCall: function(): boolean;
+  isReturn: function(): boolean;
+}
+
+export interface SQLInfo {
+  tables: string[];
+  columns: string[];
+}
+
+export interface CodeObject {
+  id: string;
+  name: string;
+  type: string;
+  database_type: string;
+  children: CodeObject[];
+  parent: CodeObject;
+  location: string; // Functions only
+  static: boolean; // Functions only
+}
+
+export interface Trigram {
+  callerId: string;
+  codeObjectId: string;
+  calleeId: string;
+
+  id: string;
+}
+
+export interface CodeObjectMatcher {
+  match: function(CodeObject) : string;
+  pop: function() : void;
+}
+
+export interface CodeObjectMatch {
+  appmap: string;
+  codeObject: CodeObject;
+}
+
+export interface EventMatch {
+  appmap: string;
+  event: Event;
+  ancestors: Event[];
+  descendants: Event[];
+  caller: Event;
+  packageTrigrams: Trigram[];
+  classTrigrams: Trigram[];
+  functionTrigrams: Trigram[];
+}
+
+export interface CodeObjectMatchSpec {
+  tokens: Array<(codeObject: CodeObject) => boolean>;
+}
+
+export interface Filter {
+  name: string;
+  value: string;
+}
+
+export interface FunctionStats {
+  eventMatches: EventMatch[];
+  returnValues: string[];
+  httpServerRequests: string[];
+  sqlQueries: string[];
+  sqlTables: string[];
+  callers: Event[];
+  ancestors: Event[];
+  descendants: Event[];
+  packageTrigrams: Trigram[];
+  classTrigrams: Trigram[];
+  functionTrigrams: Trigram[];
+}

data/node_modules/@appland/cli/src/search/utils.js

@@ -0,0 +1,4 @@
+// Put this here because it doesn't work with ts-check
+const { buildAppMap } = require('@appland/models');
+
+module.exports = { buildAppMap };

data/node_modules/@appland/cli/src/swagger/README.md

@@ -0,0 +1,75 @@
+# appmap-swagger
+
+`appmap-js swagger` generates [Swagger 3](https://swagger.io/specification/)
+(aka OpenAPI) YAML from [AppMap](https://appland.org/) data.
+
+AppMaps contain rich information about HTTP server requests. `appmap-js swagger`
+collects and organizes this information into the Swagger format.
+
+The more (and better) functional and integration tests you write, the more
+Swagger you get. And better yet, it's always accurate because it reflects the
+actual behavior of your code.
+
+Once you've generated Swagger, you can configure your web app to serve the
+Swagger API and UI. Then you can interact directly with your API, in the context
+of your app, through the Swagger UI. It's a powerful way to browse, understand,
+and debug your API.
+
+## Supported languages
+
+`appmap-js swagger` works with any language that has an AppMap client. Consult
+[appland.org](https://appland.org/) for a current list of clients, plus usage
+instructions and examples.
+
+## How it works
+
+1. Install the AppMap client for your programming language.
+2. Record AppMaps by running test cases.
+3. Run `appmap-js swagger` to generate Swagger `paths` and `components`. Swagger
+   YAML is printed to stdout.
+4. Merge the paths and components into a wrapper template using some custom code
+   in your project, or a standardized wrapper such as the `appmap:swagger` Rake
+   task.
+5. Open your Swagger docs using the Swagger API or Swagger UI.
+
+## Example
+
+To try out `appmap-js swagger`:
+
+1. Clone this repo
+2. `yarn install` to get dependencies.
+3. `cd packages/cli`
+4. `npx appmap-cli swagger --directory test/fixtures/appland`
+
+## Usage
+
+### List commands
+
+```sh-session
+$ npx appmap-cli help swagger
+appmap-swagger <command>
+
+Commands:
+  appmap-swagger generate  Generate Swagger from AppMaps in a directory
+
+Options:
+      --version  Show version number                         [boolean]
+  -v, --verbose  Run with verbose logging                    [boolean]
+      --help     Show help
+```
+
+### `appmap-swagger generate`
+
+```sh-session
+$ appmap-swagger generate --help
+appmap-swagger generate
+
+Generate Swagger from AppMaps in a directory
+
+Options:
+      --version    Show version number                       [boolean]
+  -v, --verbose    Run with verbose logging                  [boolean]
+      --help       Show help                                 [boolean]
+      --directory  directory to recursively inspect for AppMaps
+                                               [default: "tmp/appmap"]
+```

data/node_modules/@appland/cli/src/swagger/command.js

@@ -0,0 +1,42 @@
+const { promises: fsp } = require('fs');
+const { queue } = require('async');
+const { glob } = require('glob');
+const { parseHTTPServerRequests } = require('./util');
+const Model = require('./model');
+
+class SwaggerCommand {
+  constructor(directory) {
+    this.directory = directory;
+  }
+
+  async execute() {
+    this.count = 0;
+    this.model = new Model();
+    const q = queue(this.collectAppMap.bind(this), 5);
+    q.pause();
+    const files = await new Promise((resolve, reject) => {
+      glob(`${this.directory}/**/*.appmap.json`, (err, globFiles) => {
+        if (err) {
+          return reject(err);
+        }
+        return resolve(globFiles);
+      });
+    });
+    files.forEach((f) => q.push(f));
+    await new Promise((resolve, reject) => {
+      q.drain(resolve);
+      q.error(reject);
+      q.resume();
+    });
+    return this.model.swagger();
+  }
+
+  async collectAppMap(file) {
+    this.count += 1;
+    parseHTTPServerRequests(JSON.parse(await fsp.readFile(file)), (e) =>
+      this.model.addRequest(e)
+    );
+  }
+}
+
+module.exports = SwaggerCommand;

data/node_modules/@appland/cli/src/swagger/method.js

@@ -0,0 +1,173 @@
+const { EventNavigator } = require('@appland/models');
+const Response = require('./response');
+const Schema = require('./schema');
+const { messageToSwaggerSchema, bestPathInfo } = require('./util');
+
+const bodyParamMethods = new Set(['delete', 'put', 'post', 'patch']);
+
+function swaggerIn(event, name) {
+  const pathInfo = bestPathInfo(event.httpServerRequest);
+  // Trim format info from Rails paths, e.g. /foo/bar(.:format)
+  const tokens = pathInfo.split('/').map((token) => token.split('(')[0]);
+  // Recognize Rails-style normalized paths /org/:org_id and Swagger-style paths /org/{org_id}
+  if (tokens.includes(`:${name}`) || tokens.includes(`{${name}}`)) {
+    return 'path';
+  }
+  return 'query';
+}
+
+class Method {
+  constructor(securitySchemes) {
+    this.securitySchemes = securitySchemes;
+    this.responses = {};
+    this.events = [];
+  }
+
+  swagger() {
+    const responses = Object.keys(this.responses)
+      .sort()
+      .reduce((memo, response) => {
+        // eslint-disable-next-line no-param-reassign
+        memo[response] = this.responses[response].swagger();
+        return memo;
+      }, {});
+
+    let description;
+    const schemata = {};
+    const parameters = [];
+    let securitySchemeId;
+
+    const uniqueNames = new Set(['controller', 'action', '_method']);
+    this.events.forEach((event) => {
+      const messages = event.message || [];
+      if (!securitySchemeId) {
+        securitySchemeId = this.securitySchemes.addRequest(event);
+      }
+
+      let schema = null;
+      if (event.httpServerRequest.mime_type) {
+        const mimeType = event.httpServerRequest.mime_type.split(';')[0];
+        if (!schemata[mimeType]) {
+          schemata[mimeType] = new Schema();
+        }
+        schema = schemata[mimeType];
+      }
+
+      const actionName = messages
+        .filter((msg) => msg.name === 'action')
+        .map((msg) => msg.value)[0];
+      if (actionName) {
+        const bestCommentOrCodeObjectName = (() => {
+          const descendants = new EventNavigator(event).descendants();
+          let iter = descendants.next();
+          let controller = null;
+          while (!iter.done) {
+            const evt = iter.value;
+            if (
+              evt.event.codeObject.packageOf.indexOf('app/controllers') === 0 &&
+              evt.event.codeObject.name === actionName
+            ) {
+              controller = evt.event;
+              break;
+            }
+            iter = descendants.next();
+          }
+          if (!controller) {
+            return null;
+          }
+          const { comment } = controller.codeObject.data;
+          if (comment) {
+            const lines = comment
+              .split('\n')
+              .map((line) => line.replace(/^\s*#\s*/, '').trim())
+              .filter((line) => line && line.length > 0);
+            return lines.join('\n');
+          }
+          return controller.codeObject.name;
+        })();
+        if (!description) {
+          description = bestCommentOrCodeObjectName;
+        }
+      }
+
+      messages.forEach((message) => {
+        if (uniqueNames.has(message.name)) {
+          return;
+        }
+        uniqueNames.add(message.name);
+        const inLocation = swaggerIn(event, message.name);
+        if (
+          inLocation !== 'path' &&
+          event.httpServerRequest.request_method &&
+          bodyParamMethods.has(
+            event.httpServerRequest.request_method.toLowerCase()
+          )
+        ) {
+          if (schema) {
+            schema.addExample(message);
+          }
+        } else {
+          const parameter = {
+            name: message.name,
+            in: inLocation,
+            schema: messageToSwaggerSchema(message),
+          };
+          if (parameter.in === 'path') {
+            parameter.required = true;
+          }
+          parameters.push(parameter);
+        }
+      });
+    });
+
+    const response = {
+      responses,
+    };
+    if (description) {
+      response.description = description;
+    }
+    if (securitySchemeId) {
+      const securityObj = {};
+      securityObj[securitySchemeId] = [];
+      response.security = [securityObj];
+    }
+    if (Object.keys(schemata).length > 0) {
+      response.requestBody = { content: {} };
+      Object.keys(schemata)
+        .sort()
+        .forEach((contentType) => {
+          const schema = schemata[contentType].schema();
+          if (!schema) {
+            return;
+          }
+          response.requestBody.content[contentType] = { schema };
+        });
+    }
+    if (parameters.length > 0) {
+      response.parameters = parameters.sort((a, b) =>
+        a.name.localeCompare(b.name)
+      );
+    }
+    return response;
+  }
+
+  addRequest(event) {
+    if (!event.httpServerResponse) {
+      return;
+    }
+    // eslint-disable-next-line camelcase
+    const { status, status_code: statusCode } = event.httpServerResponse;
+    this.addResponse(status || statusCode, event);
+  }
+
+  addResponse(status, event) {
+    if (!this.responses[status]) {
+      this.responses[status] = new Response(status);
+    }
+    this.events.push(event);
+    const responseObj = this.responses[status];
+    responseObj.addRequest(event);
+  }
+}
+
+module.exports = Method;

data/node_modules/@appland/cli/src/swagger/model.js

@@ -0,0 +1,54 @@
+const Path = require('./path');
+const SecuritySchemes = require('./securitySchemes');
+const { bestPathInfo } = require('./util');
+
+class Model {
+  constructor() {
+    this.paths = {};
+    this.securitySchemes = new SecuritySchemes();
+  }
+
+  swagger() {
+    const paths = Object.keys(this.paths)
+      .sort()
+      .reduce((memo, path) => {
+        // eslint-disable-next-line no-param-reassign
+        memo[path] = this.paths[path].swagger();
+        return memo;
+      }, {});
+    const securitySchemes = this.securitySchemes.swagger();
+    return { paths, components: { securitySchemes } };
+  }
+
+  addRequest(event) {
+    this.addPath(Model.basePath(event), event);
+  }
+
+  addPath(path, event) {
+    if (!this.paths[path]) {
+      this.paths[path] = new Path(this.securitySchemes);
+    }
+    const pathObj = this.paths[path];
+    pathObj.addRequest(event);
+  }
+
+  static basePath(event) {
+    const { httpServerRequest } = event;
+    let pathInfo = bestPathInfo(httpServerRequest);
+    // eslint-disable-next-line prefer-destructuring
+    pathInfo = pathInfo.split('(')[0];
+    const path = pathInfo.split('/').map((entry) => {
+      if (entry.match(/^:(.*)/)) {
+        // eslint-disable-next-line no-param-reassign
+        entry = `{${entry.substring(1)}}`;
+      }
+      return entry;
+    });
+    if (path.length === 1 && path[0] === '') {
+      path.push('');
+    }
+    return path.join('/');
+  }
+}
+
+module.exports = Model;