phantomas 2.0.0 → 2.4.0

package/lib/metadata/generate.js

@@ -1,283 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Generates metadata.json file that stores metadata about:
- *
- * - events
- * - metrics
- * - modules
- * - extensions
- */
-"use strict";
-
-var debug = require("debug")("generate"),
-  fs = require("fs"),
-  glob = require("glob"),
-  phantomas = require("../../"),
-  yaml = require("js-yaml"),
-  metadata = {
-    events: {},
-    extensions: {},
-    modules: {},
-    metrics: {},
-    metricsCount: 0,
-    modulesCount: 0,
-    extensionsCount: 0,
-    version: phantomas.version,
-  };
-
-function getMetricsCoveredByTests(spec) {
-  const debug = require("debug")("metricsCovered");
-
-  var covered = {};
-
-  spec.forEach((testCase) => {
-    debug(testCase.label || testCase.url);
-
-    Object.keys(testCase.metrics || {}).forEach((metric) => {
-      covered[metric] = true;
-    });
-
-    Object.keys(testCase.offenders || {}).forEach((metric) => {
-      covered[metric] = true;
-    });
-  });
-
-  return Object.keys(covered);
-}
-
-function getOptionsCoveredByTests(spec) {
-  var covered = {};
-
-  spec.forEach((testCase) => {
-    Object.keys(testCase.options || {}).forEach((option) => {
-      covered[option] = true;
-    });
-  });
-
-  return Object.keys(covered).sort();
-}
-
-function getModuleMetadata(moduleFile) {
-  var content = fs.readFileSync(moduleFile).toString(),
-    data = {
-      name: "",
-      description: "",
-      metrics: {},
-      events: {},
-    },
-    matches,
-    moduleName,
-    metricRegEx = /(setMetric|setMetricEvaluate|incrMetric)\(['"]([^'"]+)['"](\)|,)(.*@desc.*$)?/gm,
-    eventsRegEx = /emit\(['"]([^'"]+)['"]([^)]+).*@desc(.*)$/gm;
-
-  data.name = moduleName = moduleFile.split("/").pop().replace(/\.js$/, "");
-
-  const localPath = moduleFile.replace(
-    fs.realpathSync(__dirname + "/../../"),
-    ""
-  );
-  data.localPath = localPath;
-
-  //
-  // scan the source code
-  //
-
-  // look for metrics metadata
-  while ((matches = metricRegEx.exec(content)) !== null) {
-    var entry = {},
-      metricName = matches[2],
-      metricComment = matches[4],
-      metricUnit = "ms",
-      hasDesc = metricComment && metricComment.indexOf("@desc") > -1;
-
-    if (typeof data.metrics[metricName] !== "undefined") {
-      if (hasDesc) {
-        debug(
-          "Found duplicated definition of %s metric in %s module",
-          metricName,
-          moduleName
-        );
-      }
-      continue;
-    }
-
-    // parse @desc
-    if (hasDesc) {
-      metricComment = metricComment.split("@desc").pop().trim();
-      entry.desc = "";
-
-      ["unreliable", "optional", "offenders", "gecko"].forEach(function (
-        marker
-      ) {
-        if (metricComment.indexOf("@" + marker) > -1) {
-          entry[marker] = true;
-          metricComment = metricComment.replace("@" + marker, "").trim();
-        }
-      });
-
-      // detect units (defaults to ms)
-      if ((matches = metricComment.match(/\[([^\]]+)\]/)) !== null) {
-        metricUnit = matches[1];
-        metricComment = metricComment.replace(matches[0], "").trim();
-      } else if (
-        /^(number of|total number of|average specificity|total specificity|median of number|maximum number|maximum level)/.test(
-          metricComment
-        )
-      ) {
-        metricUnit = "number";
-      } else if (
-        /^(the size|size|length|total length) of/.test(metricComment)
-      ) {
-        metricUnit = "bytes";
-      }
-
-      // check if offenders are reported for this metric
-      if (content.indexOf("phantomas.addOffender('" + metricName + "'") > -1) {
-        entry.offenders = true;
-      }
-
-      entry.desc = metricComment;
-      entry.unit = metricUnit;
-    } else if (moduleName !== "scope") {
-      debug(
-        "Metadata missing for %s metric in %s module",
-        metricName,
-        moduleName
-      );
-    }
-
-    entry.module = moduleName;
-
-    // add a metric
-    data.metrics[metricName] = entry;
-  }
-
-  // look for events metadata
-  while ((matches = eventsRegEx.exec(content)) !== null) {
-    // console.log([moduleName, matches[1], matches[2], matches[3]]);
-
-    data.events[matches[1]] = {
-      file: localPath,
-      desc: matches[3].trim(),
-      arguments: matches[2].replace(/^[,\s]+/g, ""),
-    };
-  }
-
-  // parse modules and extensions initial commit block
-  matches = /^\/\*\*([^/]+)\*\//m.exec(content);
-  if (matches) {
-    var desc = matches[0]
-      .replace(/^[\s/]?\*+\s?/gm, "") // remove the beginning of block comment
-      .replace(/\/$/gm, "") // remove the ending of block comment
-      .replace(/^\s?setMetric.*$/gm, "") // remove setMetric annotations
-      .trim();
-
-    //console.log(localPath, moduleName, matches[0]);
-
-    data.description = desc;
-  }
-  //console.log(data); throw new Error('foo');
-
-  return data;
-}
-
-// read the YAML spec file
-const raw = fs
-    .readFileSync(__dirname + "/../../test/integration-spec.yaml")
-    .toString(),
-  spec = yaml.safeLoad(raw);
-
-// find all metrics covered by integration tests (take a look into integration-spec.yaml)
-const coveredMetrics = getMetricsCoveredByTests(spec);
-
-debug(
-  "Found %d metrics covered by integration-spec.yaml...",
-  coveredMetrics.length
-);
-
-// find all options covered by integration tests (take a look into integration-spec.yaml)
-const coveredOptions = getOptionsCoveredByTests(spec);
-
-debug(
-  "Found %d options covered by integration-spec.yaml: --%s",
-  coveredOptions.length,
-  coveredOptions.join(", --")
-);
-
-// find all modules
-var dir = phantomas.path;
-debug("Looking for modules in %s...", dir);
-
-[]
-  .concat(
-    glob.sync(dir + "/core/modules/**/*.js"),
-    glob.sync(dir + "/modules/**/*.js"),
-    glob.sync(dir + "/extensions/**/*.js"),
-    glob.sync(dir + "/lib/*.js")
-  )
-  .forEach(function (moduleFile) {
-    const data = getModuleMetadata(moduleFile);
-
-    // skip scope.js files when listing metrics
-    if (
-      moduleFile.indexOf("/scope.js") === -1 &&
-      moduleFile.indexOf("/lib/") === -1
-    ) {
-      Object.keys(data.metrics).forEach(function (metricName) {
-        metadata.metricsCount++;
-        metadata.metrics[metricName] = data.metrics[metricName];
-        metadata.metrics[metricName].testsCovered =
-          coveredMetrics.indexOf(metricName) > -1;
-      });
-    }
-
-    // modules ...
-    if (
-      moduleFile.indexOf("/scope.js") === -1 &&
-      moduleFile.indexOf("/modules/") > -1
-    ) {
-      metadata.modules[data.name] = {
-        file: data.localPath,
-        desc: data.description,
-        events: Object.keys(data.events),
-        metrics: Object.keys(data.metrics),
-      };
-
-      metadata.modulesCount++;
-    }
-
-    // ... and extensions
-    if (moduleFile.indexOf("/extensions/") > -1) {
-      metadata.extensions[data.name] = {
-        file: data.localPath,
-        desc: data.description,
-        options: [],
-      };
-
-      metadata.extensionsCount++;
-    }
-
-    Object.keys(data.events).forEach(function (eventName) {
-      metadata.events[eventName] = data.events[eventName];
-    });
-  });
-
-// store metadata
-var filename = __dirname + "/metadata.json",
-  content = JSON.stringify(metadata, null, "  ");
-
-debug("Storing metadata in %s...", filename);
-fs.writeFile(filename, content, function (err) {
-  if (err) {
-    debug("Storing failed: %s", err);
-  } else {
-    debug("Done");
-  }
-});
-
-debug(
-  "Metrics found: %d (tests coverage: %s%)",
-  metadata.metricsCount,
-  ((coveredMetrics.length / metadata.metricsCount) * 100).toFixed(2)
-);

package/lib/metadata/make_docs.js

@@ -1,185 +0,0 @@
-/**
- * Generates Markdown files in /docs directory
- */
-const debug = require("debug")("docs"),
-  phantomas = require("../.."),
-  fs = require("fs"),
-  metadata_file = __dirname + "/metadata.json",
-  docs_dir = fs.realpathSync(__dirname + "/../../docs"),
-  github_root = "https://github.com/macbre/phantomas/tree/devel";
-
-debug("Generating docs into %s ...", docs_dir);
-debug("Reading %s ...", metadata_file);
-
-const metadata = JSON.parse(fs.readFileSync(metadata_file));
-
-// console.log(metadata);
-
-const docs_notice =
-  "\n\n---\n> This file is auto-generated from code comments. Please run `npm run make-docs` to update it.";
-
-/**
- * events.md
- *
- * https://github.com/macbre/phantomas/issues/729
- */
-var events = `
-Events
-======
-
-`;
-
-Object.keys(metadata.events)
-  .sort()
-  .forEach((eventName) => {
-    const entry = metadata.events[eventName];
-
-    events += `
-### ${eventName}
-
-**Description**: ${entry.desc}
-
-**Arguments**: ${entry.arguments}
-
-[View source](${github_root}${entry.file})
-
-`.trim();
-
-    events += "\n\n\n";
-  });
-
-async function buildDocs() {
-  // now add some real life examples from loading an example URL from our tests
-  events += `## Examples`;
-
-  const promise = phantomas("http://0.0.0.0:8888/_make_docs.html");
-  var hasEvent = {};
-
-  [
-    "recv",
-    "send",
-    "request",
-    "response",
-    "milestone",
-    "metrics",
-    "consoleLog",
-    "jserror",
-  ].forEach((eventName) => {
-    promise.on(eventName, (...args) => {
-      if (hasEvent[eventName]) return;
-      hasEvent[eventName] = true;
-
-      const dumped = JSON.stringify(args, null, "  ");
-      debug("events.md: %s event triggered ...", eventName);
-
-      events += `
-
-### ${eventName}
-
-Arguments passed to the event:
-
-\`\`\`json
-${dumped}
-\`\`\`
-    `.trimRight();
-    });
-  });
-
-  // make results available when generating metrics.md - see the next step
-  const runResults = await promise;
-
-  debug("Report metrics: %j", runResults.getMetrics());
-  debug("Report offenders: %j", runResults.getAllOffenders());
-
-  debug("Saving events.md ...");
-  fs.writeFileSync(docs_dir + "/events.md", events.trim() + docs_notice);
-
-  /**
-   * metrics.md
-   *
-   * https://github.com/macbre/phantomas/issues/729
-   */
-
-  // get offender examples from integration-spec.yaml
-  const offenders = (() => {
-    const yaml = require("js-yaml"),
-      spec = yaml.safeLoad(
-        fs
-          .readFileSync(__dirname + "/../../test/integration-spec.yaml")
-          .toString()
-      );
-
-    var offenders = {};
-
-    spec.forEach((testCase) => {
-      Object.keys(testCase.offenders || {}).forEach((metricName) => {
-        if (!offenders[metricName]) {
-          offenders[metricName] = testCase.offenders[metricName][0];
-        }
-      });
-    });
-
-    // test coverage is not 100%, fill missing offenders using the "real" phantomas run from above
-    Object.keys(runResults.getMetrics()).forEach((metricName) => {
-      if (!offenders[metricName] && runResults.getOffenders(metricName)) {
-        offenders[metricName] = runResults.getOffenders(metricName)[0];
-      }
-    });
-
-    return offenders;
-  })();
-
-  // build Markdown file
-  var metrics = `
-Modules and metrics
-===================
-
-This file describes all [\`phantomas\` modules](https://github.com/macbre/phantomas/tree/devel/modules) (${metadata.modulesCount} of them) and ${metadata.metricsCount} metrics that they emit.
-
-When applicable, [offender](https://github.com/macbre/phantomas/issues/140) example is provided.
-
-`;
-
-  Object.keys(metadata.modules)
-    .sort()
-    .forEach((moduleName) => {
-      const entry = metadata.modules[moduleName];
-
-      metrics += `
-
-## [${moduleName}](${github_root}${entry.file})
-
-> ${entry.desc}
-`;
-
-      entry.metrics.sort().forEach((metricName) => {
-        const metric = metadata.metrics[metricName],
-          hasOffenders = metric.offenders ? ", with offenders" : "";
-
-        metrics += `
-##### \`${metricName}\`
-
-${metric.desc} (${metric.unit}${hasOffenders})
-`;
-
-        // add offender's example
-        if (hasOffenders && offenders[metricName]) {
-          const dumped = JSON.stringify(offenders[metricName], null, "  ");
-
-          metrics += `
-\`\`\`json
-${dumped}
-\`\`\`
-`;
-        }
-      });
-    });
-
-  debug("Saving metrics.md ...");
-  fs.writeFileSync(docs_dir + "/metrics.md", metrics.trim() + docs_notice);
-
-  // ---
-  debug("Done");
-}
-
-buildDocs();

package/reporters/csv.js

@@ -1,54 +0,0 @@
-/**
- * Results formatter for -R csv
- *
- * Options:
- *  no-header - omit CSV header
- *  timestamp - add the current timestamp as the first column
- *  url - add the URL as the first column
- *
- * @see https://github.com/touv/node-csv-string
- */
-"use strict";
-
-var CSV = require("csv-string");
-
-module.exports = function (results, reporterOptions) {
-  // public API
-  return {
-    render: function () {
-      var metrics = results.getMetricsNames(),
-        keys = [],
-        values = [],
-        ret = [];
-
-      metrics.forEach(function (metric) {
-        var value = results.getMetric(metric);
-
-        keys.push(metric);
-        values.push(value);
-      });
-
-      // -R csv:url
-      if (reporterOptions.url === true) {
-        values.unshift(results.getUrl());
-        keys.unshift("url");
-      }
-
-      // -R csv:timestamp
-      if (reporterOptions.timestamp === true) {
-        values.unshift(new Date().toJSON().substr(0, 19));
-        keys.unshift("timestamp");
-      }
-
-      // -R csv:no-header
-      if (reporterOptions["no-header"] !== true) {
-        ret.push(keys);
-      }
-
-      // add the values
-      ret.push(values);
-
-      return CSV.stringify(ret);
-    },
-  };
-};

package/reporters/plain.js

@@ -1,173 +0,0 @@
-/**
- * Results formatter for --format=plain
- *
- * Options:
- *  no-color - disable ANSI colors
- */
-"use strict";
-
-var colors = require("../lib/ansicolors"),
-  metrics = require("../lib/index").metadata.metrics,
-  fold = require("travis-fold"),
-  rpad = require("../core/pads").rpad,
-  OK = "✓",
-  ERR = "✗";
-
-function getMetricUnit(metricName) {
-  var entry = metrics[metricName];
-  return typeof entry !== "undefined" &&
-    entry.unit !== "number" &&
-    entry.unit !== "string"
-    ? entry.unit
-    : false;
-}
-
-module.exports = function (results, reporterOptions) {
-  var isMultiple = Array.isArray(results),
-    noColor = reporterOptions["no-color"] === true;
-
-  function formatSingleRunResults(results) {
-    var res = [];
-
-    if (noColor) {
-      colors.disable();
-    }
-
-    // header
-    res.push(
-      results.getGenerator() + " metrics for <" + results.getUrl() + ">:"
-    );
-    res.push("");
-
-    // metrics
-    fold.pushStart(res, "metrics");
-
-    results.getMetricsNames().forEach(function (metric) {
-      var line = " " + metric + ": " + results.getMetric(metric),
-        unit = getMetricUnit(metric);
-
-      if (unit !== false) {
-        line += " " + colors.brightBlack(unit);
-      }
-
-      // check asserts
-      if (results.hasAssertion(metric)) {
-        if (results.assert(metric)) {
-          line = colors.brightGreen(OK + line);
-        } else {
-          line =
-            rpad(ERR + line, 50) +
-            "Assertion failed! Expected to be less than or equal: " +
-            results.getAssertion(metric);
-          line = colors.brightRed(line);
-        }
-      } else {
-        line = "*" + line;
-      }
-
-      res.push(line);
-    });
-
-    fold.pushEnd(res, "metrics");
-    res.push("");
-
-    // offenders
-    var offenders = results.getAllOffenders();
-    fold.pushStart(res, "offenders");
-
-    Object.keys(offenders).forEach(function (metric) {
-      var LIMIT = 50,
-        offenders = results.getOffenders(metric),
-        len = offenders.length;
-
-      res.push(
-        colors.brightGreen(
-          "Offenders for " + metric + " (" + results.getMetric(metric) + "):"
-        )
-      );
-
-      // limit the ammount of offenders emitted
-      offenders.slice(0, LIMIT).forEach(function (msg) {
-        res.push(" * " + msg);
-      });
-
-      if (len > LIMIT) {
-        res.push(colors.brightBlack("(" + (len - LIMIT) + " more)"));
-      }
-
-      res.push("");
-    });
-
-    fold.pushEnd(res, "offenders");
-
-    return fold.wrap(results.getUrl(), res.join("\n").trim()) + "\n";
-  }
-
-  function formatMultipleRunResults(results) {
-    var AsciiTable = require("ascii-table"),
-      format = require("util").format,
-      stats = new (require("../lib/stats"))(),
-      runs = results.length,
-      table;
-
-    // table title and heading
-    table = new AsciiTable();
-    table.setTitle(
-      format(
-        "Report from %d run(s) for <%s> using %s",
-        runs,
-        results[0].getUrl(),
-        results[0].getGenerator()
-      )
-    );
-    table.setTitleAlignLeft();
-
-    var heading = [];
-    heading.push(AsciiTable.alignCenter("Metric", 30));
-
-    stats.getAvailableStats().forEach(function (name) {
-      heading.push(AsciiTable.alignCenter(name, 12));
-    });
-
-    table.setHeading(heading);
-
-    // metrics stats
-    for (var i = 0; i < runs; i++) {
-      stats.pushMetrics(results[i].getMetrics());
-    }
-
-    // generate rows (one for each metric)
-    stats.getMetrics().forEach(function (metricName) {
-      var row = [],
-        metricStats = stats.getMetricStats(metricName),
-        unit = getMetricUnit(metricName),
-        heading = metricName;
-
-      if (unit !== false) {
-        heading += " [" + unit + "]";
-      }
-
-      row.push(heading);
-
-      Object.keys(metricStats).forEach(function (stat) {
-        row.push(metricStats[stat]);
-      });
-
-      table.addRow(row);
-    });
-
-    return table.toString() + "\n";
-  }
-
-  // public API
-  return {
-    handlesMultiple: true,
-    render: function () {
-      if (!isMultiple) {
-        return formatSingleRunResults(results);
-      } else {
-        return formatMultipleRunResults(results);
-      }
-    },
-  };
-};