diff --git a/.babelrc b/.babelrc new file mode 100644 index 0000000..c13c5f6 --- /dev/null +++ b/.babelrc @@ -0,0 +1,3 @@ +{ + "presets": ["es2015"] +} diff --git a/.gitignore b/.gitignore index eda638e..28c2c2e 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,4 @@ node_modules out npm-debug.log /coverage -/test/fixture/esdoc +/test/fixture/esdoc* diff --git a/.travis.yml b/.travis.yml index 8e103bf..2243f80 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,8 +1,11 @@ language: node_js sudo: false node_js: - - "0.12" + - "6.3.1" + script: - - TRAVIS=1 npm run test-es5 + - npm run build + - npm run coverage:travis + install: - npm install diff --git a/README.md b/README.md index b187e18..b3f61fd 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,9 @@ Therefore, convert the import path by using following setting. { "name": "esdoc-importpath-plugin", "option": { + // appendPackageName and replaces will be ignored when setting the packageProp + "packageProp": "main", + "appendPackageName": true, "replaces": [ {"from": "^src/", "to": "lib/"} ] @@ -30,21 +33,49 @@ Therefore, convert the import path by using following setting. } ``` -``from`` is regular expression and ``to``is letter. In the internal ``from`` and ``to`` are used with ``String#replace(new RegExp (from), to)``. +### packageProp [string] + +Resolves property inside the `package.json' file. Generally set to either `main` or `name`. Anytime packageProp is set, the `option.replaces` transformation will be ignored. + +**note:** Prefer setting your project's `package.json` main property instead of using this override to better adhere to [npm docs's main spec](https://docs.npmjs.com/files/package.json#main). + +### appendPackageName [boolean] + +Appends the package name to the import path. + +### replaces [array] or [string] -When writing multi rules, it will also be carried out transformation many times. -For example, ``[{from: "^src/", to: "lib/"}, {from: "MyFooClass", to: "my-foo"}]`` converted as follows: +Replaces can be either an array or string. -- `` my-module/src/MyFooClass.js`` => `` my-module/lib/MyFooClass.js`` => ``my-module/lib/my-foo`` +#### replaces [string] -# Install and Usage -```sh -npm install esdoc-importpath-plugin +If replaces is a string, then the import path will always be that defined string. +```json +// esdocs.json +{ + "source": "./src", + "destination": "./doc", + "plugins": [ + { + "name": "esdoc-importpath-plugin", + "option": { + "replaces": "my-import-override", + } + } + ] +} ``` -setup ``plugin`` property in ``esdoc.json`` +#### replaces [array] +Otherwise, if replaces is an array, then each item in the replaces must be an object consisting of `from` and `to` properties. +``from`` is regular expression and ``to``is letter. In the internal ``from`` and ``to`` are used with ``String#replace(new RegExp (from), to)``. + +When writing multi rules, the `replaces` transformations will be executed in the exact order that is defined in the array. + +For example, ``my-module/src/MyFooClass.js`` => `` my-module/lib/MyFooClass.js`` => ``my-module/lib/my-foo`` with the following config: ```json +// esdocs.json { "source": "./src", "destination": "./doc", @@ -53,7 +84,8 @@ setup ``plugin`` property in ``esdoc.json`` "name": "esdoc-importpath-plugin", "option": { "replaces": [ - {"from": "^src/", "to": "lib"} + { from: "^src/", to: "lib/" }, + { from: "MyFooClass", to: "my-foo" } ] } } @@ -61,11 +93,33 @@ setup ``plugin`` property in ``esdoc.json`` } ``` -execute ESDoc +# Setup -```json -esdoc -c esdoc.json -``` +1. Install `esdoc-importpath-plugin`. + ```sh + $ npm install esdoc-importpath-plugin --save-dev + ``` +1. setup ``plugin`` property in ``esdoc.json`` + ```json + { + "source": "./src", + "destination": "./doc", + "plugins": [ + { + "name": "esdoc-importpath-plugin", + "option": { + "replaces": [ + {"from": "^src/", "to": "lib"} + ] + } + } + ] + } + ``` +1. Execute ESDoc + ```sh + $ esdoc -c esdoc.json + ``` # LICENSE MIT diff --git a/esdoc.json b/esdoc.json deleted file mode 100644 index 837d4fc..0000000 --- a/esdoc.json +++ /dev/null @@ -1,18 +0,0 @@ -{ - "source": "./src", - "destination": "./out/esdoc", - "test": { - "type": "mocha", - "source": "./test/src" - }, - "plugins": [ - { - "name": "./out/src/Plugin.js", - "option": { - "replaces": [ - {"from": "^src/", "to": "out/src/"} - ] - } - } - ] -} diff --git a/package.json b/package.json index c59ff68..376feda 100644 --- a/package.json +++ b/package.json @@ -10,16 +10,19 @@ "url": "https://github.com/esdoc/esdoc-importpath-plugin" }, "scripts": { - "build": "node ./script/build.js", - "test": "node ./script/test.js", - "test-es5": "node ./script/test-es5.js", + "build": "rm -rf out && mkdir -p out/src && babel -d out/src src", + "test": "rm -rf ./test/fixture/esdoc* && mocha -t 10000 -R spec --compilers js:babel-core/register --recursive ./test/src", + "coverage": "istanbul cover _mocha --report lcovonly -- -t 10000 --compilers js:babel-core/register --recursive ./test/src -R spec", + "coverage:travis": "npm run coverage -s && cat ./coverage/lcov.info | coveralls", "esdoc": "./node_modules/.bin/esdoc -c esdoc.json" }, "devDependencies": { - "babel": "^5.8.20", + "babel-cli": "^6.9.0", + "babel-core": "^6.13.2", + "babel-eslint": "^6.1.0", + "babel-preset-es2015": "^6.1.18", "coveralls": "~2.11.2", - "esdoc": "^0.2.0", - "espower-babel": "^3.2.0", + "esdoc": "^0.4.8", "fs-extra": "^0.22.1", "istanbul": "~0.3.16", "mocha": "~2.2.5", diff --git a/script/build.js b/script/build.js deleted file mode 100644 index 7ee2356..0000000 --- a/script/build.js +++ /dev/null @@ -1,11 +0,0 @@ -#!/usr/bin/env node -var sh = require('./sh'); - -sh.rm('./out/src'); -sh.mkdir('./out/src'); -sh.exec('./node_modules/.bin/babel --out-dir out/src src'); - -// build test -sh.rm('./out/test/src'); -sh.mkdir('./out/test/src'); -sh.exec('./node_modules/.bin/babel --out-dir out/test/src test/src'); diff --git a/script/sh.js b/script/sh.js deleted file mode 100644 index 4b9408f..0000000 --- a/script/sh.js +++ /dev/null @@ -1,35 +0,0 @@ -var fs = require('fs-extra'); -var path = require('path'); -var child_process = require('child_process'); - -function rm(path) { - fs.removeSync(path); -} - -function mkdir(path) { - fs.mkdirs(path); -} - -function exec(cmd) { - cmd = cmd.replace(/\//g, path.sep); - child_process.execSync(cmd, {stdio: 'inherit'}); -} - -function chmod(path, mode) { - fs.chmodSync(path, mode); -} - -function cp(src, dst) { - fs.copySync(src, dst); -} - -function cd(dst) { - process.chdir(dst); -} - -module.exports.rm = rm; -module.exports.mkdir = mkdir; -module.exports.exec = exec; -module.exports.chmod = chmod; -module.exports.cp = cp; -module.exports.cd = cd; diff --git a/script/test-es5.js b/script/test-es5.js deleted file mode 100755 index 23670c9..0000000 --- a/script/test-es5.js +++ /dev/null @@ -1,14 +0,0 @@ -#!/usr/bin/env node -var sh = require('./sh'); - -var mochaOption=" -t 10000 --recursive ./out/test/src -R spec"; - -sh.exec('node ./script/build.js'); - -if (process.env.TRAVIS) { - sh.exec('./node_modules/.bin/istanbul cover ./node_modules/mocha/bin/_mocha --report lcovonly -- ' + mochaOption + ' && cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js'); -} else if(process.argv.indexOf('--coverage') !== -1) { - sh.exec('./node_modules/.bin/istanbul cover ./node_modules/mocha/bin/_mocha -- ' + mochaOption); -} else { - sh.exec('./node_modules/.bin/mocha' + mochaOption); -} diff --git a/script/test.js b/script/test.js deleted file mode 100755 index ee0bfa9..0000000 --- a/script/test.js +++ /dev/null @@ -1,12 +0,0 @@ -#!/usr/bin/env node -var sh = require('./sh'); - -var mochaOption=" -t 10000 --require ./node_modules/babel/register.js --require ./test/espower-babel-loader.js --recursive ./test/src -R spec"; - -if (process.env.TRAVIS) { - sh.exec('./node_modules/.bin/istanbul cover ./node_modules/mocha/bin/_mocha --report lcovonly -- ' + mochaOption + ' && cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js'); -} else if(process.argv.indexOf('--coverage') !== -1) { - sh.exec('./node_modules/.bin/istanbul cover ./node_modules/mocha/bin/_mocha -- ' + mochaOption); -} else { - sh.exec('./node_modules/.bin/mocha' + mochaOption); -} diff --git a/src/Plugin.js b/src/Plugin.js index 64852d5..1d3b344 100644 --- a/src/Plugin.js +++ b/src/Plugin.js @@ -1,7 +1,7 @@ import fs from 'fs'; let option; -let packagePath = './package.json'; +let packageObj; /** * take option @@ -9,8 +9,17 @@ let packagePath = './package.json'; */ export function onStart(ev) { option = ev.data.option; - for (let item of option.replaces) { - item.from = new RegExp(item.from); + + if (Array.isArray(option.replaces)) { + option.appendPackageName = option.appendPackageName; + option.replaces = option.replaces.map((item) => { + return { + to: item.to, + from: new RegExp(item.from), + }; + }); + } else if (typeof option.replaces === 'string') { + option.name = option.replaces; } } @@ -19,7 +28,18 @@ export function onStart(ev) { * @param {Object} ev - handle event. */ export function onHandleConfig(ev) { - if (ev.data.config.package) packagePath = ev.data.config.package; + packageObj = ev.data.config.package; + if (typeof ev.data.config.package === 'string') { + try { + const packageJSON = fs.readFileSync(packageObj).toString(); + packageObj = JSON.parse(packageJSON); + } catch (e) { + // ignore + } + } + if (typeof option.packageProp === 'string' && packageObj) { + option.name = packageObj[option.packageProp]; + } } /** @@ -28,33 +48,31 @@ export function onHandleConfig(ev) { */ export function onHandleTag(ev) { // get package.json - let packageName = ''; - let mainPath = ''; - try { - const packageJSON = fs.readFileSync(packagePath).toString(); - const packageObj = JSON.parse(packageJSON); - packageName = packageObj.name; - if(packageObj.main) mainPath = packageObj.main; - } catch (e) { - // ignore - } - for (let tag of ev.data.tag) { - if (!tag.importPath) continue; + if (tag.importPath) { + tag.importPath = getImportPath(tag.importPath); + } + } +} - let importPath = tag.importPath; - if (packageName) importPath = importPath.replace(new RegExp(`^${packageName}/`), ''); +function getImportPath(tagImportPath) { + if (option.name) { + return option.name; + } - for (let item of option.replaces) { - importPath = importPath.replace(item.from, item.to); - } + // process the user's replace config. + let importPath = tagImportPath; + if (packageObj && packageObj.name) { + importPath = importPath.replace(new RegExp(`^${packageObj.name}/`), ''); + } + (option.replaces || []).forEach((item) => { + importPath = importPath.replace(item.from, item.to); + }); - if (importPath === mainPath) { - tag.importPath = packageName; - } else if (packageName) { - tag.importPath = `${packageName}/${importPath}`; - } else { - tag.importPath = importPath; - } + // add the package name to the beginning of the import path + if (option.appendPackageName) { + return `${packageObj.name}/${importPath}`; } + + return importPath; } diff --git a/test/espower-babel-loader.js b/test/espower-babel-loader.js deleted file mode 100644 index 554bb58..0000000 --- a/test/espower-babel-loader.js +++ /dev/null @@ -1,4 +0,0 @@ -require('espower-babel')({ - cwd: process.cwd(), - pattern: 'test/src/**/*Test.js' -}); diff --git a/test/fixture/esdoc.json b/test/fixture/esdoc.json deleted file mode 100644 index c03a7c8..0000000 --- a/test/fixture/esdoc.json +++ /dev/null @@ -1,16 +0,0 @@ -{ - "source": "./test/fixture/src", - "destination": "./test/fixture/esdoc", - "package": "./test/fixture/package.json", - "plugins": [ - { - "name": "./src/Plugin.js", - "option": { - "replaces": [ - {"from": "^src/", "to": "lib/"}, - {"from": "^lib/FooClass.js", "to": "lib/foo"} - ] - } - } - ] -} diff --git a/test/fixture/package.json b/test/fixture/package.json deleted file mode 100644 index 3ab9619..0000000 --- a/test/fixture/package.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "name": "esdoc-importpath-plugin", - "main": "lib/Index.js" -} diff --git a/test/fixture/src/MyClass.js b/test/fixture/src/MyClass.js deleted file mode 100644 index a313b29..0000000 --- a/test/fixture/src/MyClass.js +++ /dev/null @@ -1,2 +0,0 @@ -export default class MyClass { -} diff --git a/test/src/000init.js b/test/src/000init.js deleted file mode 100644 index 6d8f2b0..0000000 --- a/test/src/000init.js +++ /dev/null @@ -1,14 +0,0 @@ -import fs from 'fs-extra'; -import path from 'path'; -import ESDoc from 'esdoc/out/src/ESDoc.js'; -import publisher from 'esdoc/out/src/Publisher/publish.js'; - -const configFilePath = './test/fixture/esdoc.json'; -const configJSON = fs.readFileSync(configFilePath, {encode: 'utf8'}); -const config = JSON.parse(configJSON); - -const selfPath = path.relative('./', __filename); -if (selfPath.indexOf('out/test/src/') === 0) config.plugins[0].name = './out/src/Plugin.js'; - -fs.removeSync(config.destination); -ESDoc.generate(config, publisher); diff --git a/test/src/ImportPathTest.js b/test/src/ImportPathTest.js index 373a21b..5dc43e9 100644 --- a/test/src/ImportPathTest.js +++ b/test/src/ImportPathTest.js @@ -1,22 +1,121 @@ import fs from 'fs-extra'; import assert from 'power-assert'; +import ESDoc from 'esdoc/out/src/ESDoc.js'; +import defaultPublisher from 'esdoc/out/src/Publisher/publish.js'; + /** * @test {onHandleTag} */ describe('Import Path', ()=> { - it('simply convert', ()=> { - const html = fs.readFileSync('./test/fixture/esdoc/class/src/MyClass.js~MyClass.html').toString(); - assert(html.includes('>esdoc-importpath-plugin/lib/MyClass.js<')); + let id = 0; + function generateDocs(config, assertion) { + id += 1; + config.source = "./test/fixture/src"; + config.destination = `./test/fixture/esdoc_${ id }` + ESDoc.generate(config, defaultPublisher); + return fs.readFileSync(config.destination + '/class/src/FooClass.js~FooClass.html').toString(); + } + + it('should show only path to file', ()=> { + const html = generateDocs({ + "package": './test/src/pkg--calcium.json', + "plugins": [ + { + "name": "./src/Plugin.js", + "option": { + "appendPackageName": false, + } + } + ] + }); + assert(html.includes('>src/FooClass.js<')); + }); + + it('should append package name', ()=> { + const html = generateDocs({ + "package": './test/src/pkg--calcium.json', + "plugins": [ + { + "name": "./src/Plugin.js", + "option": { + "appendPackageName": true, + } + } + ] + }); + assert(html.includes('>calcium/src/FooClass.js<')); + }); + + it('should convert using custom replacement string', ()=> { + const html = generateDocs({ + "package": './test/src/pkg--hydrogen.json', + "plugins": [ + { + "name": "./src/Plugin.js", + "option": { + "replaces": "calcium", + } + } + ] + }); + assert(html.includes('>calcium<')); + }); + + it('should convert using custom replacement array', ()=> { + const html = generateDocs({ + "package": './test/src/pkg--calcium.json', + "plugins": [ + { + "name": "./src/Plugin.js", + "option": { + "appendPackageName": true, + "replaces": [ + {"from": "^src/", "to": "lib/"}, + {"from": "^lib/FooClass.js", "to": "lib/foo"} + ] + } + } + ] + }); + assert(html.includes('>calcium/lib/foo<')); }); - it('multiple convert', ()=>{ - const html = fs.readFileSync('./test/fixture/esdoc/class/src/FooClass.js~FooClass.html').toString(); - assert(html.includes('>esdoc-importpath-plugin/lib/foo<')); + it('should convert using package property name', ()=> { + const html = generateDocs({ + "package": './test/src/pkg--lysine.json', + "plugins": [ + { + "name": "./src/Plugin.js", + "option": { + packageProp: "name", + // ignores these replacements + "replaces": [ + {"from": "^src/", "to": "lib/"}, + ] + } + } + ] + }); + assert(html.includes('>lysine<')); }); - it('package name convert', ()=>{ - const html = fs.readFileSync('./test/fixture/esdoc/class/src/Index.js~Index.html').toString(); - assert(html.includes('>esdoc-importpath-plugin<')); + it('should convert using package main property', ()=>{ + const html = generateDocs({ + "package": './test/src/pkg--lysine.json', + "plugins": [ + { + "name": "./src/Plugin.js", + "option": { + packageProp: "main", + // ignores these replacements + "replaces": [ + {"from": "^src/", "to": "lib/"}, + ] + } + } + ] + }); + assert(html.includes('>lib/lysine.js<')); }); }); diff --git a/test/src/pkg--calcium.json b/test/src/pkg--calcium.json new file mode 100644 index 0000000..676a105 --- /dev/null +++ b/test/src/pkg--calcium.json @@ -0,0 +1,3 @@ +{ + "name": "calcium" +} \ No newline at end of file diff --git a/test/src/pkg--hydrogen.json b/test/src/pkg--hydrogen.json new file mode 100644 index 0000000..7c7aa21 --- /dev/null +++ b/test/src/pkg--hydrogen.json @@ -0,0 +1,3 @@ +{ + "name": "hydrogen" +} \ No newline at end of file diff --git a/test/src/pkg--lysine.json b/test/src/pkg--lysine.json new file mode 100644 index 0000000..937e7a0 --- /dev/null +++ b/test/src/pkg--lysine.json @@ -0,0 +1,4 @@ +{ + "name": "lysine", + "main": "lib/lysine.js" +} \ No newline at end of file