@ciscospark/jsdoctrinetest/src/extract.js

/*!
 * Copyright (c) 2015-2017 Cisco Systems, Inc. See LICENSE file.
 */

import parse from './parse';
import fs from 'fs';
import traverse from 'babel-traverse';
import doctrine from 'doctrine';
import {isProgram} from 'babel-types';
/**
 * transform function which operates on each discovered example block
 * @callback transformCallback
 * @param {Object} options
 * @param {ast} options.comment
 * @param {string} options.name
 * @param {string} options.filename
 * @param {string} options.type
 */

/**
 * Extracts comment blocks from the source code in the specified file
 * @param {transformCallback} transform
 * @param {string} filename
 * @returns {Array<ast>}
 */
export default function extract(transform, filename) {
  // eslint-disable-next-line no-sync
  const code = fs.readFileSync(filename, {encoding: 'utf8'});

  const ast = parse(code, {sourceFilename: filename});

  const results = [];

  let done = false;
  traverse(ast, {
    enter(path) {
      if (path.node.leadingComments) {
        path.node.leadingComments
          .filter(isJSDocComment)
          .forEach((comment) => {
            const result = doctrine.parse(comment.value, {
              unwrap: true,
              sloppy: true,
              recoverable: true,
              lineNumbers: true
            });

            if (result.tags) {
              result.tags.forEach((tag) => {
                if (tag.title === 'example') {
                  results.push(transform({
                    comment: tag.description,
                    name: getNodeName(path.node),
                    filename: path.node.loc.filename,
                    type: path.node.type
                  }));
                }
              });
            }
          });
      }
    },
    Program: {
      exit(path) {
        if (isProgram(path)) {
          if (done) {
            return;
          }
          path.pushContainer('body', results);
          done = true;
        }
      }
    }
  });

  return ast;
}

/**
 * Extracts the name from the specified node
 * @param {Node} node
 * @returns {string}
 */
function getNodeName(node) {
  if (node.id) {
    return node.id.name;
  }

  if (node.key) {
    return node.key.name;
  }

  throw new Error('Could not find name for node');
}
/**
 * Indicates if the specified comment block is a doc block
 * @param {CommentBlock} comment
 * @returns {Boolean}
 */
function isJSDocComment(comment) {
  const asterisks = comment.value.match(/^(\*+)/);
  if (comment.value.startsWith('/*') && comment.value.endsWith('*/')) {
    return false;
  }

  // eslint-disable-next-line
  return (comment.type === `CommentBlock` || // estree
    // eslint-disable-next-line
    comment.type === `Block`) // get-comments / traditional
    // eslint-disable-next-line
    && asterisks && asterisks[ 1 ].length === 1;
}