feat: add parse options (#104)

* feat: add a few options to parse functions

add custom handlers for template and script

* feat: resolve.module implementation

* doc: add some documentation
fixes #102

Author: elevatebart

README.md

@@ -29,14 +29,31 @@ var vueDocs = require('vue-docgen-api')
 var componentInfo = vueDocs.parse(filePath)
 ```
 
-or with typescript/es6
+or with typescript
 
 ```ts
 import { parse } from 'vue-docgen-api'
-var componentInfo = parse(filePath)
+var componentInfo = parse(filePath);
+var componentInfo = vueDocs.parse(filePath, {
+  alias: {"@assets": path.resolve(__dirname, "src/assets")},
+  resolve: [path.resolve(__dirname, "src")],
+  addScriptHandler: [function(  
+    documentation: Documentation,
+    componentDefinition: NodePath,
+    astPath: bt.File,
+    opt: ParseOptions){
+      // handle custom code in script
+  }],
+  addTemplateHandler: [function(
+    documentation: Documentation,
+    templateAst: ASTElement,
+    options: TemplateParserOptions){
+      // handle custom directives here
+  }]
+})
 ```
 
-### parse(filePath)
+### parse(filePath:string, options?: DocGenOptions)
 
 | Parameter | Type   | Description   |
 | --------- | ------ | ------------- |

src/main.ts

@@ -1,20 +1,33 @@
 import { ComponentDoc, Documentation } from './Documentation'
-import { parseFile, parseSource as parseSourceLocal } from './parse'
+import { DocGenOptions, parseFile, ParseOptions, parseSource as parseSourceLocal } from './parse'
+export { ScriptHandler, TemplateHandler } from './parse'
+export { ComponentDoc, DocGenOptions, ParseOptions, Documentation }
 
-export { ComponentDoc }
-
-export function parse(filePath: string, aliases?: { [alias: string]: string }): ComponentDoc {
+export function parse(
+  filePath: string,
+  opts?: DocGenOptions | { [alias: string]: string },
+): ComponentDoc {
   const doc = new Documentation()
-  parseFile(doc, { filePath, aliases })
+  const options: ParseOptions = isOptionsObject(opts)
+    ? { ...opts, filePath }
+    : { filePath, alias: opts }
+  parseFile(doc, options)
   return doc.toObject()
 }
 
 export function parseSource(
   source: string,
   filePath: string,
-  aliases?: { [alias: string]: string },
+  opts?: DocGenOptions | { [alias: string]: string },
 ): ComponentDoc {
   const doc = new Documentation()
-  parseSourceLocal(doc, source, { filePath, aliases })
+  const options: ParseOptions = isOptionsObject(opts)
+    ? { ...opts, filePath }
+    : { filePath, alias: opts }
+  parseSourceLocal(doc, source, options)
   return doc.toObject()
 }
+
+function isOptionsObject(opts: any): opts is DocGenOptions {
+  return !!opts && !!opts.alias
+}

src/parse-script.ts

@@ -13,7 +13,7 @@ import { ParseOptions } from './parse'
 
 const ERROR_MISSING_DEFINITION = 'No suitable component definition found'
 
-type Handler = (
+export type Handler = (
   doc: Documentation,
   componentDefinition: NodePath,
   ast: bt.File,

src/parse.ts

@@ -2,19 +2,47 @@ import * as fs from 'fs'
 import * as path from 'path'
 import { parseComponent, SFCDescriptor } from 'vue-template-compiler'
 import { Documentation } from './Documentation'
-import parseScript from './parse-script'
-import parseTemplate from './parse-template'
-import handlers from './script-handlers'
+import parseScript, { Handler as ScriptHandler } from './parse-script'
+import parseTemplate, { Handler as TemplateHandler } from './parse-template'
+import scriptHandlers from './script-handlers'
 import templateHandlers from './template-handlers'
 import cacher from './utils/cacher'
 
 const ERROR_EMPTY_DOCUMENT = 'The passed source is empty'
 
-export interface ParseOptions {
+export { ScriptHandler, TemplateHandler }
+
+export interface ParseOptions extends DocGenOptions {
   filePath: string
+  /**
+   * In what language is the component written
+   * @default undefined - let the system decide
+   */
   lang?: 'ts' | 'js'
+}
+
+export interface DocGenOptions {
+  /**
+   * Which exported variables should be looked at
+   * @default undefined - means treat all dependencies
+   */
   nameFilter?: string[]
-  aliases?: { [alias: string]: string }
+  /**
+   * What alias should be replaced in requires and imports
+   */
+  alias?: { [alias: string]: string }
+  /**
+   * What directories should be searched when resolving modules
+   */
+  modules?: string[]
+  /**
+   * Handlers that will be added at the end of the script analysis
+   */
+  addScriptHandlers?: ScriptHandler[]
+  /**
+   * Handlers that will be added at the end of the template analysis
+   */
+  addTemplateHandlers?: TemplateHandler[]
 }
 
 /**
@@ -50,7 +78,13 @@ export function parseSource(documentation: Documentation, source: string, opt: P
 
   // get slots and props from template
   if (parts && parts.template) {
-    parseTemplate(parts.template, documentation, templateHandlers, opt.filePath)
+    const addTemplateHandlers: TemplateHandler[] = opt.addTemplateHandlers || []
+    parseTemplate(
+      parts.template,
+      documentation,
+      [...templateHandlers, ...addTemplateHandlers],
+      opt.filePath,
+    )
   }
 
   const scriptSource = parts ? (parts.script ? parts.script.content : undefined) : source
@@ -60,8 +94,8 @@ export function parseSource(documentation: Documentation, source: string, opt: P
       /\.tsx?$/i.test(path.extname(opt.filePath))
         ? 'ts'
         : 'js'
-
-    parseScript(scriptSource, documentation, handlers, opt)
+    const addScriptHandlers: ScriptHandler[] = opt.addScriptHandlers || []
+    parseScript(scriptSource, documentation, [...scriptHandlers, ...addScriptHandlers], opt)
   }
 
   if (!documentation.get('displayName')) {

src/script-handlers/extendsHandler.ts

@@ -31,7 +31,7 @@ export default function extendsHandler(
 
   const originalDirName = path.dirname(opt.filePath)
 
-  const pathResolver = makePathResolver(originalDirName, opt.aliases)
+  const pathResolver = makePathResolver(originalDirName, opt.alias)
 
   resolveImmediatelyExportedRequire(pathResolver, extendsFilePath)
 

src/script-handlers/mixinsHandler.ts

@@ -21,7 +21,7 @@ export default function mixinsHandler(
 ) {
   const originalDirName = path.dirname(opt.filePath)
 
-  const pathResolver = makePathResolver(originalDirName, opt.aliases)
+  const pathResolver = makePathResolver(originalDirName, opt.alias)
 
   // filter only mixins
   const mixinVariableNames = getMixinsVariableNames(componentDefinition)

src/utils/makePathResolver.ts

@@ -4,7 +4,11 @@ import resolvePathFrom from '../utils/resolvePathFrom'
 export default function makePathResolver(
   refDirName: string,
   aliases?: { [alias: string]: string },
+  modules?: string[],
 ): (filePath: string, originalDirNameOverride?: string) => string {
   return (filePath: string, originalDirNameOverride?: string): string =>
-    resolvePathFrom(resolveAliases(filePath, aliases || {}), originalDirNameOverride || refDirName)
+    resolvePathFrom(resolveAliases(filePath, aliases || {}), [
+      originalDirNameOverride || refDirName,
+      ...(modules || []),
+    ])
 }

src/utils/resolvePathFrom.ts

@@ -1,12 +1,12 @@
 const SUFFIXES = ['', '.js', '.ts', '.vue', '/index.js', '/index.ts']
 
-export default function resolvePathFrom(path: string, from: string): string {
+export default function resolvePathFrom(path: string, from: string[]): string {
   let finalPath = ''
   SUFFIXES.forEach(s => {
     if (!finalPath.length) {
       try {
         finalPath = require.resolve(`${path}${s}`, {
-          paths: [from],
+          paths: from,
         })
       } catch (e) {
         // eat the error

tests/components/mixin-resolved/button.vue

@@ -8,6 +8,7 @@
 
 <script>
 import { anotherMixin, myMixin } from '@mixins/index'
+import { multi, hidden } from 'multiMixin'
 
 export default {
   mixins: [anotherMixin, myMixin],

tests/components/mixin-resolved/resolved-mixin.test.ts

@@ -8,7 +8,10 @@ let docButton: ComponentDoc
 describe('tests button', () => {
   beforeAll(done => {
     docButton = parse(button, {
-      '@mixins': path.resolve(__dirname, '../../mixins'),
+      alias: {
+        '@mixins': path.resolve(__dirname, '../../mixins'),
+      },
+      modules: [path.resolve(__dirname, '../../mixins')],
     })
     done()
   })