From 140a67d3f705f22e469bb1311ffa0eed9409c830 Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Fri, 15 Nov 2019 00:06:08 -0800 Subject: [PATCH 01/20] Add new project tsdoc-config --- api-demo/package.json | 2 +- eslint-plugin/package.json | 2 +- rush.json | 5 +++ tsdoc-config/.eslintrc.js | 7 +++++ tsdoc-config/.npmignore | 25 +++++++++++++++ tsdoc-config/.npmrc | 2 ++ tsdoc-config/.prettierrc.json | 6 ++++ tsdoc-config/LICENSE | 22 +++++++++++++ tsdoc-config/build.js | 37 ++++++++++++++++++++++ tsdoc-config/package.json | 58 +++++++++++++++++++++++++++++++++++ tsdoc-config/tsconfig.json | 35 +++++++++++++++++++++ 11 files changed, 199 insertions(+), 2 deletions(-) create mode 100644 tsdoc-config/.eslintrc.js create mode 100644 tsdoc-config/.npmignore create mode 100644 tsdoc-config/.npmrc create mode 100644 tsdoc-config/.prettierrc.json create mode 100644 tsdoc-config/LICENSE create mode 100644 tsdoc-config/build.js create mode 100644 tsdoc-config/package.json create mode 100644 tsdoc-config/tsconfig.json diff --git a/api-demo/package.json b/api-demo/package.json index 78941c86..e5763988 100644 --- a/api-demo/package.json +++ b/api-demo/package.json @@ -6,7 +6,7 @@ "license": "MIT", "dependencies": { "@microsoft/tsdoc": "0.12.15", - "@types/node": "10.7.1", + "@types/node": "10.17.5", "colors": "~1.3.3" }, "devDependencies": { diff --git a/eslint-plugin/package.json b/eslint-plugin/package.json index 792ec009..a08a4f1a 100644 --- a/eslint-plugin/package.json +++ b/eslint-plugin/package.json @@ -32,7 +32,7 @@ "@rushstack/eslint-config": "0.4.0", "@types/eslint": "6.1.3", "@types/estree": "0.0.39", - "@types/node": "10.7.1", + "@types/node": "10.17.5", "eslint": "^6.0.0", "rimraf": "~2.6.3", "typescript": "~3.5.3" diff --git a/rush.json b/rush.json index d409d1f6..b771afd9 100644 --- a/rush.json +++ b/rush.json @@ -376,6 +376,11 @@ "projectFolder": "tsdoc", "shouldPublish": true }, + { + "packageName": "@microsoft/tsdoc-config", + "projectFolder": "tsdoc-config", + "shouldPublish": false + }, { "packageName": "eslint-plugin-tsdoc", "projectFolder": "eslint-plugin", diff --git a/tsdoc-config/.eslintrc.js b/tsdoc-config/.eslintrc.js new file mode 100644 index 00000000..d7953bb2 --- /dev/null +++ b/tsdoc-config/.eslintrc.js @@ -0,0 +1,7 @@ +// This is a workaround for https://github.com/eslint/eslint/issues/3458 +require("@rushstack/eslint-config/patch-eslint6"); + +module.exports = { + extends: [ "@rushstack/eslint-config" ], + parserOptions: { tsconfigRootDir: __dirname }, +}; diff --git a/tsdoc-config/.npmignore b/tsdoc-config/.npmignore new file mode 100644 index 00000000..859b06bb --- /dev/null +++ b/tsdoc-config/.npmignore @@ -0,0 +1,25 @@ +# Ignore everything by default +** + +# Use negative patterns to bring back the specific things we want to publish +!/bin/** +!/lib/** +!/dist/** +!ThirdPartyNotice.txt + +# Ignore certain files in the above folder +/dist/*.stats.* +/lib/**/test/* +/lib/**/__tests__/* + +# NOTE: These don't need to be specified, because NPM includes them automatically. +# +# package.json +# README (and its variants) +# CHANGELOG (and its variants) +# LICENSE / LICENCE + +## Project specific definitions +# ----------------------------- + +# (Add your exceptions here) diff --git a/tsdoc-config/.npmrc b/tsdoc-config/.npmrc new file mode 100644 index 00000000..f6a02f2d --- /dev/null +++ b/tsdoc-config/.npmrc @@ -0,0 +1,2 @@ +registry=https://registry.npmjs.org/ +always-auth=false diff --git a/tsdoc-config/.prettierrc.json b/tsdoc-config/.prettierrc.json new file mode 100644 index 00000000..93bc364d --- /dev/null +++ b/tsdoc-config/.prettierrc.json @@ -0,0 +1,6 @@ +{ + "$schema": "http://json.schemastore.org/prettierrc", + "printWidth": 120, + "tabWidth": 2, + "singleQuote": true +} diff --git a/tsdoc-config/LICENSE b/tsdoc-config/LICENSE new file mode 100644 index 00000000..8e281a14 --- /dev/null +++ b/tsdoc-config/LICENSE @@ -0,0 +1,22 @@ +Copyright (c) Microsoft Corporation. All rights reserved. + +MIT License + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/tsdoc-config/build.js b/tsdoc-config/build.js new file mode 100644 index 00000000..2e71804d --- /dev/null +++ b/tsdoc-config/build.js @@ -0,0 +1,37 @@ +'use strict'; + +const child_process = require('child_process'); +const path = require('path'); + +const production = process.argv.indexOf('--production') >= 0; +const baseDir = __dirname; + +process.chdir(baseDir); + +process.exitCode = 1; +try { + child_process.execSync(path.join(baseDir, 'node_modules/.bin/rimraf') + + ' ./lib/', { stdio: 'inherit' }); + + console.log('-- TYPESCRIPT --\n'); + child_process.execSync(path.join(baseDir, 'node_modules/.bin/tsc'), { stdio: 'inherit' }); + + console.log('-- ESLINT --\n'); + child_process.execSync(path.join(baseDir, 'node_modules/.bin/eslint') + + ' -f unix \"src/**/*.{ts,tsx}\"', + { stdio: 'inherit' }); + + if (production) { + console.log('-- JEST --\n'); + + // Map stderr-->stdout because Jest weirdly writes to stderr during a successful run, + // which the build tools (rightly so) interpret as an issue that should fail the build + child_process.execSync(path.join(baseDir, 'node_modules/.bin/jest'), { + stdio: [ 0, 1, 1 ] + }); + } + + process.exitCode = 0; +} catch (e) { + console.log('ERROR: ' + e.message); +} diff --git a/tsdoc-config/package.json b/tsdoc-config/package.json new file mode 100644 index 00000000..87ed716c --- /dev/null +++ b/tsdoc-config/package.json @@ -0,0 +1,58 @@ +{ + "name": "@microsoft/tsdoc-config", + "version": "0.12.15", + "description": "A loader for the tsdoc-config.json file", + "keywords": [ + "TypeScript", + "documentation", + "doc", + "comments", + "JSDoc", + "parser", + "standard" + ], + "repository": { + "type": "git", + "url": "https://github.com/Microsoft/tsdoc" + }, + "homepage": "https://github.com/Microsoft/tsdoc", + "main": "lib/index.js", + "typings": "lib/index.d.ts", + "license": "MIT", + "dependencies": { + "ajv": "~6.10.2", + "resolve": "~1.12.0" + }, + "devDependencies": { + "@rushstack/eslint-config": "0.4.0", + "@types/jest": "24.0.16", + "@types/resolve": "0.0.8", + "@types/node": "10.17.5", + "eslint": "^6.0.0", + "jest": "~24.8.0", + "prettier": "~1.18.2", + "rimraf": "~2.6.3", + "ts-jest": "~24.0.2", + "typescript": "~3.5.3" + }, + "scripts": { + "build": "node ./build.js", + "test": "jest", + "watch": "jest --watch", + "lint": "eslint -f unix \"src/**/*.{ts,tsx}\"" + }, + "jest": { + "moduleFileExtensions": [ + "ts", + "tsx", + "js", + "jsx" + ], + "transform": { + "^.+\\.tsx?$": "ts-jest" + }, + "testMatch": [ + "/src/**/*.test.ts" + ] + } +} diff --git a/tsdoc-config/tsconfig.json b/tsdoc-config/tsconfig.json new file mode 100644 index 00000000..e0c14521 --- /dev/null +++ b/tsdoc-config/tsconfig.json @@ -0,0 +1,35 @@ +{ + "$schema": "http://json.schemastore.org/tsconfig", + + "compilerOptions": { + "target": "es5", + "forceConsistentCasingInFileNames": true, + "module": "commonjs", + "declaration": true, + "sourceMap": true, + "experimentalDecorators": true, + "types": [ + "jest" + ], + "lib": [ + "es5", + "scripthost", + "es2015.collection", + "es2015.promise", + "es2015.iterable" + ], + + "noImplicitAny": true, + "noImplicitReturns": true, + "noImplicitThis": true, + "noUnusedLocals": true, + "strictFunctionTypes": true, + "strictNullChecks": true, + "strictPropertyInitialization": true, + + "outDir": "lib" + }, + "include": [ + "src/**/*.ts" + ] +} From 38730453e7291a01cf49c1d539753b337ef3a6ac Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Fri, 15 Nov 2019 00:06:49 -0800 Subject: [PATCH 02/20] rush update --full --- common/config/rush/common-versions.json | 1 + common/config/rush/pnpm-lock.yaml | 372 +++++++++++++----------- 2 files changed, 211 insertions(+), 162 deletions(-) diff --git a/common/config/rush/common-versions.json b/common/config/rush/common-versions.json index a99727d5..f85eb092 100644 --- a/common/config/rush/common-versions.json +++ b/common/config/rush/common-versions.json @@ -21,6 +21,7 @@ * instead of the latest version. */ // "some-library": "1.2.3" + "@types/jest-diff": "20.0.1" }, /** diff --git a/common/config/rush/pnpm-lock.yaml b/common/config/rush/pnpm-lock.yaml index 7ac2691f..b83c8f9f 100644 --- a/common/config/rush/pnpm-lock.yaml +++ b/common/config/rush/pnpm-lock.yaml @@ -3,15 +3,19 @@ dependencies: '@rush-temp/api-demo': 'file:projects/api-demo.tgz' '@rush-temp/eslint-plugin-tsdoc': 'file:projects/eslint-plugin-tsdoc.tgz' '@rush-temp/tsdoc': 'file:projects/tsdoc.tgz' + '@rush-temp/tsdoc-config': 'file:projects/tsdoc-config.tgz' '@rush-temp/tsdoc-playground': 'file:projects/tsdoc-playground.tgz' '@rushstack/eslint-config': 0.4.0 '@types/eslint': 6.1.3 '@types/estree': 0.0.39 '@types/jest': 24.0.16 - '@types/node': 10.7.1 + '@types/jest-diff': 20.0.1 + '@types/node': 10.17.5 '@types/react': 16.9.11 '@types/react-dom': 16.9.3 + '@types/resolve': 0.0.8 '@types/webpack-env': 1.14.1 + ajv: 6.10.2 clean-webpack-plugin: 3.0.0 colors: 1.3.3 css-loader: 3.1.0 @@ -27,6 +31,7 @@ dependencies: prettier: 1.18.2 promise: 8.0.3 raw-loader: 0.5.1 + resolve: 1.12.0 rimraf: 2.6.3 sass-loader: 7.1.0 style-loader: 0.23.1 @@ -46,16 +51,16 @@ packages: dev: false resolution: integrity: sha512-27d4lZoomVyo51VegxI20xZPuSHusqbQag/ztrBC7wegWoQ1nLREPVSKSW8byhTlzTKyNE4ifaTA6lCp7JjpFw== - /@babel/core/7.7.0: + /@babel/core/7.7.2: dependencies: '@babel/code-frame': 7.5.5 - '@babel/generator': 7.7.0 + '@babel/generator': 7.7.2 '@babel/helpers': 7.7.0 - '@babel/parser': 7.7.0 + '@babel/parser': 7.7.3 '@babel/template': 7.7.0 - '@babel/traverse': 7.7.0 - '@babel/types': 7.7.1 - convert-source-map: 1.6.0 + '@babel/traverse': 7.7.2 + '@babel/types': 7.7.2 + convert-source-map: 1.7.0 debug: 4.1.1 json5: 2.1.1 lodash: 4.17.15 @@ -66,27 +71,27 @@ packages: engines: node: '>=6.9.0' resolution: - integrity: sha512-Bb1NjZCaiwTQC/ARL+MwDpgocdnwWDCaugvkGt6cxfBzQa8Whv1JybBoUEiBDKl8Ni3H3c7Fykwk7QChUsHRlg== - /@babel/generator/7.7.0: + integrity: sha512-eeD7VEZKfhK1KUXGiyPFettgF3m513f8FoBSWiQ1xTvl1RAopLs42Wp9+Ze911I6H0N9lNqJMDgoZT7gHsipeQ== + /@babel/generator/7.7.2: dependencies: - '@babel/types': 7.7.1 + '@babel/types': 7.7.2 jsesc: 2.5.2 lodash: 4.17.15 source-map: 0.5.7 dev: false resolution: - integrity: sha512-1wdJ6UxHyL1XoJQ119JmvuRX27LRih7iYStMPZOWAjQqeAabFg3dYXKMpgihma+to+0ADsTVVt6oRyUxWZw6Mw== + integrity: sha512-WthSArvAjYLz4TcbKOi88me+KmDJdKSlfwwN8CnUYn9jBkzhq0ZEPuBfkAWIvjJ3AdEV1Cf/+eSQTnp3IDJKlQ== /@babel/helper-function-name/7.7.0: dependencies: '@babel/helper-get-function-arity': 7.7.0 '@babel/template': 7.7.0 - '@babel/types': 7.7.1 + '@babel/types': 7.7.2 dev: false resolution: integrity: sha512-tDsJgMUAP00Ugv8O2aGEua5I2apkaQO7lBGUq1ocwN3G23JE5Dcq0uh3GvFTChPa4b40AWiAsLvCZOA2rdnQ7Q== /@babel/helper-get-function-arity/7.7.0: dependencies: - '@babel/types': 7.7.1 + '@babel/types': 7.7.2 dev: false resolution: integrity: sha512-tLdojOTz4vWcEnHWHCuPN5P85JLZWbm5Fx5ZsMEMPhF3Uoe3O7awrbM2nQ04bDOUToH/2tH/ezKEOR8zEYzqyw== @@ -96,15 +101,15 @@ packages: integrity: sha512-CYAOUCARwExnEixLdB6sDm2dIJ/YgEAKDM1MOeMeZu9Ld/bDgVo8aiWrXwcY7OBh+1Ea2uUcVRcxKk0GJvW7QA== /@babel/helper-split-export-declaration/7.7.0: dependencies: - '@babel/types': 7.7.1 + '@babel/types': 7.7.2 dev: false resolution: integrity: sha512-HgYSI8rH08neWlAH3CcdkFg9qX9YsZysZI5GD8LjhQib/mM0jGOZOVkoUiiV2Hu978fRtjtsGsW6w0pKHUWtqA== /@babel/helpers/7.7.0: dependencies: '@babel/template': 7.7.0 - '@babel/traverse': 7.7.0 - '@babel/types': 7.7.1 + '@babel/traverse': 7.7.2 + '@babel/types': 7.7.2 dev: false resolution: integrity: sha512-VnNwL4YOhbejHb7x/b5F39Zdg5vIQpUUNzJwx0ww1EcVRt41bbGRZWhAURrfY32T5zTT3qwNOQFWpn+P0i0a2g== @@ -116,16 +121,16 @@ packages: dev: false resolution: integrity: sha512-7dV4eu9gBxoM0dAnj/BCFDW9LFU0zvTrkq0ugM7pnHEgguOEeOz1so2ZghEdzviYzQEED0r4EAgpsBChKy1TRQ== - /@babel/parser/7.7.0: + /@babel/parser/7.7.3: dev: false engines: node: '>=6.0.0' hasBin: true resolution: - integrity: sha512-GqL+Z0d7B7ADlQBMXlJgvXEbtt5qlqd1YQ5fr12hTSfh7O/vgrEIvJxU2e7aSVrEUn75zTZ6Nd0s8tthrlZnrQ== - /@babel/plugin-syntax-object-rest-spread/7.2.0_@babel+core@7.7.0: + integrity: sha512-bqv+iCo9i+uLVbI0ILzKkvMorqxouI+GbV13ivcARXn9NNEabi2IEz912IgNpT/60BNXac5dgcfjb94NjsF33A== + /@babel/plugin-syntax-object-rest-spread/7.2.0_@babel+core@7.7.2: dependencies: - '@babel/core': 7.7.0 + '@babel/core': 7.7.2 '@babel/helper-plugin-utils': 7.0.0 dev: false peerDependencies: @@ -135,36 +140,36 @@ packages: /@babel/template/7.7.0: dependencies: '@babel/code-frame': 7.5.5 - '@babel/parser': 7.7.0 - '@babel/types': 7.7.1 + '@babel/parser': 7.7.3 + '@babel/types': 7.7.2 dev: false resolution: integrity: sha512-OKcwSYOW1mhWbnTBgQY5lvg1Fxg+VyfQGjcBduZFljfc044J5iDlnDSfhQ867O17XHiSCxYHUxHg2b7ryitbUQ== - /@babel/traverse/7.7.0: + /@babel/traverse/7.7.2: dependencies: '@babel/code-frame': 7.5.5 - '@babel/generator': 7.7.0 + '@babel/generator': 7.7.2 '@babel/helper-function-name': 7.7.0 '@babel/helper-split-export-declaration': 7.7.0 - '@babel/parser': 7.7.0 - '@babel/types': 7.7.1 + '@babel/parser': 7.7.3 + '@babel/types': 7.7.2 debug: 4.1.1 globals: 11.12.0 lodash: 4.17.15 dev: false resolution: - integrity: sha512-ea/3wRZc//e/uwCpuBX2itrhI0U9l7+FsrKWyKGNyvWbuMcCG7ATKY2VI4wlg2b2TA39HHwIxnvmXvtiKsyn7w== - /@babel/types/7.7.1: + integrity: sha512-TM01cXib2+rgIZrGJOLaHV/iZUAxf4A0dt5auY6KNZ+cm6aschuJGqKJM3ROTt3raPUdIDk9siAufIFEleRwtw== + /@babel/types/7.7.2: dependencies: esutils: 2.0.3 lodash: 4.17.15 to-fast-properties: 2.0.0 dev: false resolution: - integrity: sha512-kN/XdANDab9x1z5gcjDc9ePpxexkt+1EQ2MQUiM4XnMvQfvp87/+6kY4Ko2maLXH+tei/DgJ/ybFITeqqRwDiA== + integrity: sha512-YTf6PXoh3+eZgRCBzzP25Bugd2ngmpQVrk7kXX0i5N9BO7TFBtIgZYs7WtxtOGs8e6A4ZI7ECkbBCEHeXocvOA== /@cnakazawa/watch/1.0.3: dependencies: - exec-sh: 0.3.2 + exec-sh: 0.3.4 minimist: 1.2.0 dev: false engines: @@ -246,7 +251,7 @@ packages: '@jest/types': 24.9.0 chalk: 2.4.2 exit: 0.1.2 - glob: 7.1.5 + glob: 7.1.6 istanbul-lib-coverage: 2.0.5 istanbul-lib-instrument: 3.3.0 istanbul-lib-report: 2.0.8 @@ -299,11 +304,11 @@ packages: integrity: sha512-6qqsU4o0kW1dvA95qfNog8v8gkRN9ph6Lz7r96IvZpHdNipP2cBcb07J1Z45mz/VIS01OHJ3pY8T5fUY38tg4A== /@jest/transform/24.9.0: dependencies: - '@babel/core': 7.7.0 + '@babel/core': 7.7.2 '@jest/types': 24.9.0 babel-plugin-istanbul: 5.2.0 chalk: 2.4.2 - convert-source-map: 1.6.0 + convert-source-map: 1.7.0 fast-json-stable-stringify: 2.0.0 graceful-fs: 4.2.3 jest-haste-map: 24.9.0 @@ -378,8 +383,8 @@ packages: integrity: sha512-/+CRPXpBDpo2RK9C68N3b2cOvO0Cf5B9aPijHsoDQTHivnGSObdOF2BRQOYjojWTDy6nQvMjmqRXIxH55VjxxA== /@types/babel__core/7.1.3: dependencies: - '@babel/parser': 7.7.0 - '@babel/types': 7.7.1 + '@babel/parser': 7.7.3 + '@babel/types': 7.7.2 '@types/babel__generator': 7.6.0 '@types/babel__template': 7.0.2 '@types/babel__traverse': 7.0.7 @@ -388,20 +393,20 @@ packages: integrity: sha512-8fBo0UR2CcwWxeX7WIIgJ7lXjasFxoYgRnFHUj+hRvKkpiBJbxhdAPTCY6/ZKM0uxANFVzt4yObSLuTiTnazDA== /@types/babel__generator/7.6.0: dependencies: - '@babel/types': 7.7.1 + '@babel/types': 7.7.2 dev: false resolution: integrity: sha512-c1mZUu4up5cp9KROs/QAw0gTeHrw/x7m52LcnvMxxOZ03DmLwPV0MlGmlgzV3cnSdjhJOZsj7E7FHeioai+egw== /@types/babel__template/7.0.2: dependencies: - '@babel/parser': 7.7.0 - '@babel/types': 7.7.1 + '@babel/parser': 7.7.3 + '@babel/types': 7.7.2 dev: false resolution: integrity: sha512-/K6zCpeW7Imzgab2bLkLEbz0+1JlFSrUMdw7KoIIu+IUdu51GWaBZpd3y1VXGVXzynvGa4DaIaxNZHiON3GXUg== /@types/babel__traverse/7.0.7: dependencies: - '@babel/types': 7.7.1 + '@babel/types': 7.7.2 dev: false resolution: integrity: sha512-CeBpmX1J8kWLcDEnI3Cl2Eo6RfbGvzUctA+CjZUhOKDFbLfcr7fc4usEqLNWetrlJd7RhAkyYe2czXop4fICpw== @@ -428,7 +433,7 @@ packages: dependencies: '@types/events': 3.0.0 '@types/minimatch': 3.0.3 - '@types/node': 10.7.1 + '@types/node': 10.17.5 dev: false resolution: integrity: sha512-1Bh06cbWJUHMC97acuD6UMG29nMt0Aqz1vF3guLfG+kHHJhy3AyohZFFxYk2f7Q1SQIrNwvncxAE0N/9s70F2w== @@ -467,10 +472,10 @@ packages: dev: false resolution: integrity: sha512-tHq6qdbT9U1IRSGf14CL0pUlULksvY9OZ+5eEgl1N7t+OA3tGvNpxJCzuKQlsNgCVwbAs670L1vcVQi8j9HjnA== - /@types/node/10.7.1: + /@types/node/10.17.5: dev: false resolution: - integrity: sha512-EGoI4ylB/lPOaqXqtzAyL8HcgOuCtH2hkEaLmkueOYufsTFWBn4VCvlCDC2HW8Q+9iF+QVC3sxjDKQYjHQeZ9w== + integrity: sha512-RElZIr/7JreF1eY6oD5RF3kpmdcreuQPjg5ri4oQ5g9sq7YWU8HkfB3eH8GwAwxf5OaCh0VPi7r4N/yoTGelrA== /@types/node/8.5.8: dev: false resolution: @@ -492,6 +497,12 @@ packages: dev: false resolution: integrity: sha512-UBT4GZ3PokTXSWmdgC/GeCGEJXE5ofWyibCcecRLUVN2ZBpXQGVgQGtG2foS7CrTKFKlQVVswLvf7Js6XA/CVQ== + /@types/resolve/0.0.8: + dependencies: + '@types/node': 10.17.5 + dev: false + resolution: + integrity: sha512-auApPaJf3NPfe18hSoJkp8EbZzer2ISk7o8mCC3M9he/a04+gbMF97NkpD2S8riMGvm4BMRI59/SZQSaLTKpsQ== /@types/source-list-map/0.1.2: dev: false resolution: @@ -516,7 +527,7 @@ packages: integrity: sha512-0Ki9jAAhKDSuLDXOIMADg54Hu60SuBTEsWaJGGy5cV+SSUQ63J2a+RrYYGrErzz39fXzTibhKrAQJAb8M7PNcA== /@types/webpack-sources/0.1.5: dependencies: - '@types/node': 10.7.1 + '@types/node': 10.17.5 '@types/source-list-map': 0.1.2 source-map: 0.6.1 dev: false @@ -525,7 +536,7 @@ packages: /@types/webpack/4.39.8: dependencies: '@types/anymatch': 1.3.1 - '@types/node': 10.7.1 + '@types/node': 10.17.5 '@types/tapable': 1.0.4 '@types/uglify-js': 3.0.4 '@types/webpack-sources': 0.1.5 @@ -632,7 +643,7 @@ packages: integrity: sha512-+cV53HuYFeeyrNW8x/rgPmbVrzzp/rpRmwbJnNtwn4K8mroL1BdjxwQh7X9cUHp9rm4BBiEWmD3cSBjKG7d5mw== /@typescript-eslint/typescript-estree/2.3.3: dependencies: - glob: 7.1.5 + glob: 7.1.6 is-glob: 4.0.1 lodash.unescape: 4.0.1 semver: 6.3.0 @@ -777,17 +788,17 @@ packages: dev: false resolution: integrity: sha512-NuHqBY1PB/D8xU6s/thBgOAiAP7HOYDQ32+BFZILJ8ivkUkAHQnWfn6WhL79Owj1qmUnoN/YPhktdIoucipkAQ== - /abab/2.0.2: + /abab/2.0.3: dev: false resolution: - integrity: sha512-2scffjvioEmNz0OyDSLGWDfKCVwaKc6l9Pm9kOIREU13ClXZvHpg/nRL5xyjSSSLhOnXqft2HpsAzNEEA8cFFg== + integrity: sha512-tsFzPpcttalNjFBCFMqsKYQcWxxen1pgJR56by//QwvJc4/OUS3kPOOttx2tSIfjsylB0pYu7f5D3K1RCxUnUg== /abbrev/1.1.1: dev: false resolution: integrity: sha512-nne9/IiQ/hzIhY6pdDnbBtz7DjPTKrY00P/zvPSm5pOFkl6xuGrGnXn/VtTNNfNtAfZ9/1RtehkszU9qcTii0Q== /accepts/1.3.7: dependencies: - mime-types: 2.1.24 + mime-types: 2.1.25 negotiator: 0.6.2 dev: false engines: @@ -912,6 +923,12 @@ packages: node: '>=6' resolution: integrity: sha512-1apePfXM1UOSqw0o9IiFAovVz9M5S1Dg+4TrDwfMewQ6p/rmMueb7tWZjQ1rx4Loy1ArBggoqGpfqqdI4rondg== + /ansi-regex/5.0.0: + dev: false + engines: + node: '>=8' + resolution: + integrity: sha512-bY6fj56OUQ0hU1KjFNDQuJFezqKdrAyFdIevADiqrWHwSlbmBNMHp5ak2f40Pm8JTFyM2mqxkG6ngkHO11f/lg== /ansi-styles/2.2.1: dev: false engines: @@ -1107,14 +1124,14 @@ packages: dev: false resolution: integrity: sha1-Y/1D99weO7fONZR9uP42mj9Yx0s= - /babel-jest/24.9.0_@babel+core@7.7.0: + /babel-jest/24.9.0_@babel+core@7.7.2: dependencies: - '@babel/core': 7.7.0 + '@babel/core': 7.7.2 '@jest/transform': 24.9.0 '@jest/types': 24.9.0 '@types/babel__core': 7.1.3 babel-plugin-istanbul: 5.2.0 - babel-preset-jest: 24.9.0_@babel+core@7.7.0 + babel-preset-jest: 24.9.0_@babel+core@7.7.2 chalk: 2.4.2 slash: 2.0.0 dev: false @@ -1143,10 +1160,10 @@ packages: node: '>= 6' resolution: integrity: sha512-2EMA2P8Vp7lG0RAzr4HXqtYwacfMErOuv1U3wrvxHX6rD1sV6xS3WXG3r8TRQ2r6w8OhvSdWt+z41hQNwNm3Xw== - /babel-preset-jest/24.9.0_@babel+core@7.7.0: + /babel-preset-jest/24.9.0_@babel+core@7.7.2: dependencies: - '@babel/core': 7.7.0 - '@babel/plugin-syntax-object-rest-spread': 7.2.0_@babel+core@7.7.0 + '@babel/core': 7.7.2 + '@babel/plugin-syntax-object-rest-spread': 7.2.0_@babel+core@7.7.2 babel-plugin-jest-hoist: 24.9.0 dev: false engines: @@ -1248,7 +1265,7 @@ packages: /bonjour/3.5.0: dependencies: array-flatten: 2.1.2 - deep-equal: 1.1.0 + deep-equal: 1.1.1 dns-equal: 1.0.0 dns-txt: 2.0.2 multicast-dns: 6.2.3 @@ -1328,7 +1345,7 @@ packages: /browserify-des/1.0.2: dependencies: cipher-base: 1.0.4 - des.js: 1.0.0 + des.js: 1.0.1 inherits: 2.0.4 safe-buffer: 5.2.0 dev: false @@ -1385,14 +1402,14 @@ packages: dev: false resolution: integrity: sha1-JuYe0UIvtw3ULm42cp7VHYVf6Nk= - /buffer/4.9.1: + /buffer/4.9.2: dependencies: base64-js: 1.3.1 ieee754: 1.1.13 isarray: 1.0.0 dev: false resolution: - integrity: sha1-bRu2AbB6TvztlwlBMgkwJ8lbwpg= + integrity: sha512-xq+q3SRMOxGivLhBNaUdC64hDTQwejJ+H0T/NB1XMtTVEwNTrfFF3gAxiyW0Bu/xWEGhjVKgUcMhCrUy2+uCWg== /builtin-status-codes/3.0.0: dev: false resolution: @@ -1414,7 +1431,7 @@ packages: bluebird: 3.7.1 chownr: 1.1.3 figgy-pudding: 3.5.1 - glob: 7.1.5 + glob: 7.1.6 graceful-fs: 4.2.3 infer-owner: 1.0.4 lru-cache: 5.1.1 @@ -1802,12 +1819,12 @@ packages: node: '>= 0.6' resolution: integrity: sha512-hIP3EEPs8tB9AT1L+NUqtwOAps4mk2Zob89MWXMHjHWg9milF/j4osnnQLXBCBFBk/tvIG/tUc9mOUJiPBhPXA== - /convert-source-map/1.6.0: + /convert-source-map/1.7.0: dependencies: safe-buffer: 5.1.2 dev: false resolution: - integrity: sha512-eFu7XigvxdZ1ETfbgPBohgyQ/Z++C0eEhTor0qRwBw9unw+L0/6V8wkSuGgzdThkiS5lSpdptOQPD8Ak40a+7A== + integrity: sha512-4FJkXzKXEDB1snCFZlLP4gpC3JILicCpGbzG9f9G7tGqGCzETQ2hWPrcinA9oU4wtf2biUaEH5065UnMeR33oA== /cookie-signature/1.0.6: dev: false resolution: @@ -2001,7 +2018,7 @@ packages: integrity: sha1-hTz6D3y+L+1d4gMmuN1YEDX24vA= /data-urls/1.1.0: dependencies: - abab: 2.0.2 + abab: 2.0.3 whatwg-mimetype: 2.3.0 whatwg-url: 7.1.0 dev: false @@ -2037,7 +2054,7 @@ packages: node: '>=0.10' resolution: integrity: sha1-6zkTMzRYd1y4TNGh+uBiEGu4dUU= - /deep-equal/1.1.0: + /deep-equal/1.1.1: dependencies: is-arguments: 1.0.4 is-date-object: 1.0.1 @@ -2047,7 +2064,7 @@ packages: regexp.prototype.flags: 1.2.0 dev: false resolution: - integrity: sha512-ZbfWJq/wN1Z273o7mUSjILYqehAktR2NVoSrOukDkU9kg2v/Uv89yU4Cvz8seJeAmtN5oqiefKq8FPuXOboqLw== + integrity: sha512-yd9c5AdiqVcR+JjcwUQb9DkhJc8ngNr0MahEBGvDiJw8puWab2yZlh+nkasOnZP+EGTAP6rRp2JzJhJZzvNF8g== /deep-is/0.1.3: dev: false resolution: @@ -2124,13 +2141,13 @@ packages: node: '>= 0.6' resolution: integrity: sha1-m81S4UwJd2PnSbJ0xDRu0uVgtak= - /des.js/1.0.0: + /des.js/1.0.1: dependencies: inherits: 2.0.4 minimalistic-assert: 1.0.1 dev: false resolution: - integrity: sha1-wHTS4qpqipoH29YfmhXCzYPsjsw= + integrity: sha512-Q0I4pfFrv2VPd34/vfLrFOoRmlYj3OV50i7fskps1jZWK1kApMWWT9G6RRUeYedLcBDIhnSDaUvJMb3AhUlaEA== /destroy/1.0.4: dev: false resolution: @@ -2204,13 +2221,13 @@ packages: dev: false resolution: integrity: sha512-gd3ypIPfOMr9h5jIKq8E3sHOTCjeirnl0WK5ZdS1AW0Odt0b1PaWaHdJ4Qk4klv+YB9aJBS7mESXjFoDQPu6DA== - /dom-serializer/0.2.1: + /dom-serializer/0.2.2: dependencies: domelementtype: 2.0.1 entities: 2.0.0 dev: false resolution: - integrity: sha512-sK3ujri04WyjwQXVoK4PU3y8ula1stq10GJZpqHIUgoGZdsGzAGu65BnU3d08aTVSvO7mGPZUc0wTEDL+qGE0Q== + integrity: sha512-2/xPb3ORsQ42nHYiSunXkDjPLBaEj/xTwUO4B7XCZQTRk7EBtTOPaygh10YAAh2OI1Qrp6NWfpAhzswj0ydt9g== /domain-browser/1.2.0: dev: false engines: @@ -2240,14 +2257,14 @@ packages: integrity: sha512-JiK04h0Ht5u/80fdLMCEmV4zkNh2BcoMFBmZ/91WtYZ8qVXSKjiw7fXMgFPnHcSZgOo3XdinHvmnDUeMf5R4wA== /domutils/1.5.1: dependencies: - dom-serializer: 0.2.1 + dom-serializer: 0.2.2 domelementtype: 1.3.1 dev: false resolution: integrity: sha1-3NhIiib1Y9YQeeSMn3t+Mjc2gs8= /domutils/1.7.0: dependencies: - dom-serializer: 0.2.1 + dom-serializer: 0.2.2 domelementtype: 1.3.1 dev: false resolution: @@ -2276,12 +2293,13 @@ packages: dev: false resolution: integrity: sha1-WQxhFWsK4vTwJVcyoViyZrxWsh0= - /ejs/2.7.1: + /ejs/2.7.2: dev: false engines: node: '>=0.10.0' + requiresBuild: true resolution: - integrity: sha512-kS/gEPzZs3Y1rRsbGX4UOSjtP/CeJP0CxSNZHYxGfVM/VgLcv0ZqM7C45YyTj2DI2g7+P9Dd24C+IMIg6D0nYQ== + integrity: sha512-rHGwtpl67oih3xAHbZlpw5rQAt+YV1mSCu2fUZ9XNrfaGEhom7E+AUiMci+ByP4aSfuAWx7hE0BPuJLMrpXwOw== /elliptic/6.5.1: dependencies: bn.js: 4.11.8 @@ -2363,13 +2381,13 @@ packages: integrity: sha512-7dFHNmqeFSEt2ZBsCriorKnn3Z2pj+fd9kmI6QoWw4//DL+icEBfc0U7qJCisqrTsKTjw4fNFy2pW9OqStD84g== /es-abstract/1.16.0: dependencies: - es-to-primitive: 1.2.0 + es-to-primitive: 1.2.1 function-bind: 1.1.1 has: 1.0.3 has-symbols: 1.0.0 is-callable: 1.1.4 is-regex: 1.0.4 - object-inspect: 1.6.0 + object-inspect: 1.7.0 object-keys: 1.1.1 string.prototype.trimleft: 2.1.0 string.prototype.trimright: 2.1.0 @@ -2378,7 +2396,7 @@ packages: node: '>= 0.4' resolution: integrity: sha512-xdQnfykZ9JMEiasTAJZJdMWCQ1Vm00NBw79/AWi7ELfZuuPCSOMDZbT9mkOfSctVtfhb+sAAzrm+j//GjjLHLg== - /es-to-primitive/1.2.0: + /es-to-primitive/1.2.1: dependencies: is-callable: 1.1.4 is-date-object: 1.0.1 @@ -2387,7 +2405,7 @@ packages: engines: node: '>= 0.4' resolution: - integrity: sha512-qZryBOJjV//LaxLTV6UC//WewneB3LcXOL9NP++ozKVXsIIIpm/2c13UDiD9Jp2eThsecw9m3jPqDwTyobcdbg== + integrity: sha512-QCOllgZJtaUo9miYBcLChTUaHNjJF3PYs1VidD7AwiEj1kYxKeQTctLAezAOH5ZKRH0g2IgPn6KwB4IT8iRpvA== /escape-html/1.0.3: dev: false resolution: @@ -2403,7 +2421,7 @@ packages: esprima: 3.1.3 estraverse: 4.3.0 esutils: 2.0.3 - optionator: 0.8.2 + optionator: 0.8.3 dev: false engines: node: '>=4.0' @@ -2512,7 +2530,7 @@ packages: glob-parent: 5.1.0 globals: 11.12.0 ignore: 4.0.6 - import-fresh: 3.1.0 + import-fresh: 3.2.1 imurmurhash: 0.1.4 inquirer: 7.0.0 is-glob: 4.0.1 @@ -2523,7 +2541,7 @@ packages: minimatch: 3.0.4 mkdirp: 0.5.1 natural-compare: 1.4.0 - optionator: 0.8.2 + optionator: 0.8.3 progress: 2.0.3 regexpp: 2.0.1 semver: 6.3.0 @@ -2621,10 +2639,10 @@ packages: dev: false resolution: integrity: sha512-/f2Go4TognH/KvCISP7OUsHn85hT9nUkxxA9BEWxFn+Oj9o8ZNLm/40hdlgSLyuOimsrTKLUMEorQexp/aPQeA== - /exec-sh/0.3.2: + /exec-sh/0.3.4: dev: false resolution: - integrity: sha512-9sLAvzhI5nc8TpuQUh4ahMdCrWT00wPWz7j47/emR5+2qEfoZP5zzUXvx+vdx+H6ohhnsYC31iX04QLYJK8zTg== + integrity: sha512-sEFIkc61v75sWeOe72qyrqg2Qg0OuLESziUDk/O/z2qgS15y2gWVFrI6f2Qn/qw/0/NCfCEsmNA4zOjkwEZT1A== /execa/1.0.0: dependencies: cross-spawn: 6.0.5 @@ -3000,7 +3018,7 @@ packages: dependencies: asynckit: 0.4.0 combined-stream: 1.0.8 - mime-types: 2.1.24 + mime-types: 2.1.25 dev: false engines: node: '>= 0.12' @@ -3051,6 +3069,7 @@ packages: - node-pre-gyp dependencies: nan: 2.14.0 + deprecated: 'One of your dependencies needs to upgrade to fsevents v2: 1) Proper nodejs v10+ support 2) No more fetching binaries from AWS, smaller package size' dev: false engines: node: '>=4.0' @@ -3149,7 +3168,7 @@ packages: node: '>= 6' resolution: integrity: sha512-qjtRgnIVmOfnKUE3NJAQEdk+lKrxfw8t5ke7SXtfMTHcjsBfOfWXCQfdb30zfDoZQ2IRSIiidmjtbHZPZ++Ihw== - /glob/7.1.5: + /glob/7.1.6: dependencies: fs.realpath: 1.0.0 inflight: 1.0.6 @@ -3159,7 +3178,7 @@ packages: path-is-absolute: 1.0.1 dev: false resolution: - integrity: sha512-J9dlskqUXK1OeTOYBEn5s8aMukWMwWfs+rPTn/jn50Ux4MNXVhubL1wu/j2t+H4NVI+cXEcCaYellqaPVGXNqQ== + integrity: sha512-LwaxwyZ72Lk7vZINtNNrywX0ZuLyStrdDtabefZKAY5ZGJhVtgdznluResxNmPitE0SAO+O26sWTHeKSI2wMBA== /global-modules/1.0.0: dependencies: global-prefix: 1.0.2 @@ -3209,7 +3228,7 @@ packages: /globby/6.1.0: dependencies: array-union: 1.0.2 - glob: 7.1.5 + glob: 7.1.6 object-assign: 4.1.1 pify: 2.3.0 pinkie-promise: 2.0.1 @@ -3220,7 +3239,7 @@ packages: integrity: sha1-9abXDoOV4hyFj7BInWTfAkJNUGw= /globule/1.2.1: dependencies: - glob: 7.1.5 + glob: 7.1.6 lodash: 4.17.15 minimatch: 3.0.4 dev: false @@ -3282,7 +3301,7 @@ packages: node: '>=0.4.7' hasBin: true optionalDependencies: - uglify-js: 3.6.7 + uglify-js: 3.6.9 resolution: integrity: sha512-nvfrjqvt9xQ8Z/w0ijewdD/vvWDTOweBUm96NTr66Wfvo1mJenBLwcYmPs3TIBP5ruzYGD7Hx/DaM9RmhroGPw== /har-schema/2.0.0: @@ -3603,7 +3622,7 @@ packages: node: '>= 4' resolution: integrity: sha512-cyFDKrqc/YdcWFniJhzI42+AzS+gNwmUzOSFcRCQYwySuBBBy/KjuxWLZ/FHEH6Moq1NizMOBWyTcv8O4OZIMg== - /import-fresh/3.1.0: + /import-fresh/3.2.1: dependencies: parent-module: 1.0.1 resolve-from: 4.0.0 @@ -3611,7 +3630,7 @@ packages: engines: node: '>=6' resolution: - integrity: sha512-PpuksHKGt8rXfWEr9m9EHIpgyyaltBy8+eF6GJM0QCAxMgxCfucMF3mjecK2QsJr0amJW7gTqh5/wht0z2UhEQ== + integrity: sha512-6e1q1cnWP2RXD9/keSkxHScg508CdXqXWgWBaETNhyuBFz+kUZlKboh+ISK+bU++DmbHimVBrOz/zzPe0sZ3sQ== /import-local/2.0.0: dependencies: pkg-dir: 3.0.0 @@ -3684,7 +3703,7 @@ packages: mute-stream: 0.0.8 run-async: 2.3.0 rxjs: 6.5.3 - string-width: 4.1.0 + string-width: 4.2.0 strip-ansi: 5.2.0 through: 2.3.8 dev: false @@ -4034,11 +4053,11 @@ packages: integrity: sha512-8aXznuEPCJvGnMSRft4udDRDtb1V3pkQkMMI5LI+6HuQz5oQ4J2UFn1H82raA3qJtyOLkkwVqICBQkjnGtn5mA== /istanbul-lib-instrument/3.3.0: dependencies: - '@babel/generator': 7.7.0 - '@babel/parser': 7.7.0 + '@babel/generator': 7.7.2 + '@babel/parser': 7.7.3 '@babel/template': 7.7.0 - '@babel/traverse': 7.7.0 - '@babel/types': 7.7.1 + '@babel/traverse': 7.7.2 + '@babel/types': 7.7.2 istanbul-lib-coverage: 2.0.5 semver: 6.3.0 dev: false @@ -4098,7 +4117,7 @@ packages: jest-config: 24.9.0 jest-util: 24.9.0 jest-validate: 24.9.0 - prompts: 2.2.1 + prompts: 2.3.0 realpath-native: 1.1.0 yargs: 13.3.0 dev: false @@ -4109,12 +4128,12 @@ packages: integrity: sha512-+VLRKyitT3BWoMeSUIHRxV/2g8y9gw91Jh5z2UmXZzkZKpbC08CSehVxgHUwTpy+HwGcns/tqafQDJW7imYvGg== /jest-config/24.9.0: dependencies: - '@babel/core': 7.7.0 + '@babel/core': 7.7.2 '@jest/test-sequencer': 24.9.0 '@jest/types': 24.9.0 - babel-jest: 24.9.0_@babel+core@7.7.0 + babel-jest: 24.9.0_@babel+core@7.7.2 chalk: 2.4.2 - glob: 7.1.5 + glob: 7.1.6 jest-environment-jsdom: 24.9.0 jest-environment-node: 24.9.0 jest-get-type: 24.9.0 @@ -4215,7 +4234,7 @@ packages: integrity: sha512-kfVFmsuWui2Sj1Rp1AJ4D9HqJwE4uwTlS/vO+eRUaMmd54BFpli2XhMQnPC2k4cHFVbB2Q2C+jtI1AGLgEnCjQ== /jest-jasmine2/24.9.0: dependencies: - '@babel/traverse': 7.7.0 + '@babel/traverse': 7.7.2 '@jest/environment': 24.9.0 '@jest/test-result': 24.9.0 '@jest/types': 24.9.0 @@ -4355,7 +4374,7 @@ packages: '@types/yargs': 13.0.3 chalk: 2.4.2 exit: 0.1.2 - glob: 7.1.5 + glob: 7.1.6 graceful-fs: 4.2.3 jest-config: 24.9.0 jest-haste-map: 24.9.0 @@ -4384,7 +4403,7 @@ packages: integrity: sha512-DxYipDr8OvfrKH3Kel6NdED3OXxjvxXZ1uIY2I9OFbGg+vUkkg7AGvi65qbhbWNPvDckXmzMPbK3u3HaDO49bQ== /jest-snapshot/24.9.0: dependencies: - '@babel/types': 7.7.1 + '@babel/types': 7.7.2 '@jest/types': 24.9.0 chalk: 2.4.2 expect: 24.9.0 @@ -4493,7 +4512,7 @@ packages: integrity: sha1-peZUwuWi3rXyAdls77yoDA7y9RM= /jsdom/11.12.0: dependencies: - abab: 2.0.2 + abab: 2.0.3 acorn: 5.7.3 acorn-globals: 4.3.4 array-equal: 1.0.0 @@ -4751,12 +4770,12 @@ packages: dev: false resolution: integrity: sha512-8xOcRHvCjnocdS5cpwXQXVzmmh5e5+saE2QGoeQmbKmRS6J3VQppPOIt0MnmE+4xlZoumy0GPG0D0MVIQbNA1A== - /loglevel/1.6.4: + /loglevel/1.6.6: dev: false engines: node: '>= 0.6.0' resolution: - integrity: sha512-p0b6mOGKcGa+7nnmKbpzR6qloPbrgLcnio++E+14Vo/XffOGwZtRpUhr8dTH/x2oCMmEoIU0Zwm3ZauhvYD17g== + integrity: sha512-Sgr5lbboAUBo3eXCSPL4/KoVz3ROKquOjcctxmHIt+vol2DrqTQe3SwkKKuYhEiWB5kYa13YyopJ69deJ1irzQ== /loose-envify/1.4.0: dependencies: js-tokens: 4.0.0 @@ -4939,7 +4958,7 @@ packages: /micromatch/4.0.2: dependencies: braces: 3.0.2 - picomatch: 2.1.0 + picomatch: 2.1.1 dev: false engines: node: '>=8' @@ -4953,26 +4972,20 @@ packages: hasBin: true resolution: integrity: sha512-115fLhvZVqWwHPbClyntxEVfVDfl9DLLTuJvq3g2O/Oxi8AiNouAHvDSzHS0viUJc+V5vm3eq91Xwqn9dp4jRA== - /mime-db/1.40.0: - dev: false - engines: - node: '>= 0.6' - resolution: - integrity: sha512-jYdeOMPy9vnxEqFRRo6ZvTZ8d9oPb+k18PKoYNYUe2stVEBPPwsln/qWzdbmaIvnhZ9v2P+CuecK+fpUfsV2mA== /mime-db/1.42.0: dev: false engines: node: '>= 0.6' resolution: integrity: sha512-UbfJCR4UAVRNgMpfImz05smAXK7+c+ZntjaA26ANtkXLlOe947Aag5zdIcKQULAiF9Cq4WxBi9jUs5zkA84bYQ== - /mime-types/2.1.24: + /mime-types/2.1.25: dependencies: - mime-db: 1.40.0 + mime-db: 1.42.0 dev: false engines: node: '>= 0.6' resolution: - integrity: sha512-WaFHS3MCl5fapm3oLxU4eYDw77IQM2ACcxQ9RIxfaC3ooc6PFuBMGZZsYpvoXS5D5QTWPieo1jjLdAm3TBP3cQ== + integrity: sha512-5KhStqB5xpTAeGqKBAMgwaYMnQik7teQN4IAzC7npDv6kzeU6prfkR67bc87J1kWMPGkoaZSq1npmexMgkmEVg== /mime/1.6.0: dev: false engines: @@ -5159,7 +5172,7 @@ packages: /node-gyp/3.8.0: dependencies: fstream: 1.0.12 - glob: 7.1.5 + glob: 7.1.6 graceful-fs: 4.2.3 mkdirp: 0.5.1 nopt: 3.0.6 @@ -5184,7 +5197,7 @@ packages: dependencies: assert: 1.5.0 browserify-zlib: 0.2.0 - buffer: 4.9.1 + buffer: 4.9.2 console-browserify: 1.2.0 constants-browserify: 1.0.0 crypto-browserify: 3.12.0 @@ -5231,7 +5244,7 @@ packages: cross-spawn: 3.0.1 gaze: 1.1.3 get-stdin: 4.0.1 - glob: 7.1.5 + glob: 7.1.6 in-publish: 2.0.0 lodash: 4.17.15 meow: 3.7.0 @@ -5333,10 +5346,10 @@ packages: node: '>=0.10.0' resolution: integrity: sha1-fn2Fi3gb18mRpBupde04EnVOmYw= - /object-inspect/1.6.0: + /object-inspect/1.7.0: dev: false resolution: - integrity: sha512-GJzfBZ6DgDAmnuaM3104jR4s1Myxr3Y3zfIyN4z3UdqN69oSRacNK8UhnobDdC+7J2AHCjGwxQubNJfE70SXXQ== + integrity: sha512-a7pEHdh1xKIAgTySUGgLMx/xwDZskN1Ud6egYYN3EdRW4ZMPNEDUTF+hwy2LUC+Bl+SyLXANnwz/jyh/qutKUw== /object-is/1.0.1: dev: false engines: @@ -5470,19 +5483,19 @@ packages: dev: false resolution: integrity: sha1-2j6nRob6IaGaERwybpDrFaAZZoY= - /optionator/0.8.2: + /optionator/0.8.3: dependencies: deep-is: 0.1.3 fast-levenshtein: 2.0.6 levn: 0.3.0 prelude-ls: 1.1.2 type-check: 0.3.2 - wordwrap: 1.0.0 + word-wrap: 1.2.3 dev: false engines: node: '>= 0.8.0' resolution: - integrity: sha1-NkxeQJ0/TWMB1sC0wFu6UBgK62Q= + integrity: sha512-+IW9pACdk3XWmmTXG8m3upGUJst5XRGzxMRjXzAuJ1XnIFNvfhjjIuYkDvysnPQ7qzqVzLt78BCruntqRhWQbA== /original/1.0.2: dependencies: url-parse: 1.4.7 @@ -5754,12 +5767,12 @@ packages: dev: false resolution: integrity: sha1-Ywn04OX6kT7BxpMHrjZLSzd8nns= - /picomatch/2.1.0: + /picomatch/2.1.1: dev: false engines: node: '>=8.6' resolution: - integrity: sha512-uhnEDzAbrcJ8R3g2fANnSuXZMBtkpSjxTTgn2LeSiQlfmq72enQJWdQllXW24MBLYnA1SBD2vfvx2o0Zw3Ielw== + integrity: sha512-OYMyqkKzK7blWO/+XZYP6w8hH0LDvkBvdvKukti+7kqYFCiEAk+gI3DWnryapc0Dau05ugGTy0foQ6mqn4AHYA== /pify/2.3.0: dev: false engines: @@ -5912,7 +5925,7 @@ packages: '@jest/types': 24.9.0 ansi-regex: 4.1.0 ansi-styles: 3.2.1 - react-is: 16.11.0 + react-is: 16.12.0 dev: false engines: node: '>= 6' @@ -5944,20 +5957,20 @@ packages: dev: false resolution: integrity: sha512-HeRDUL1RJiLhyA0/grn+PTShlBAcLuh/1BJGtrvjwbvRDCTLLMEz9rOGCV+R3vHY4MixIuoMEd9Yq/XvsTPcjw== - /prompts/2.2.1: + /prompts/2.3.0: dependencies: kleur: 3.0.3 - sisteransi: 1.0.3 + sisteransi: 1.0.4 dev: false engines: node: '>= 6' resolution: - integrity: sha512-VObPvJiWPhpZI6C5m60XOzTfnYg/xc/an+r9VYymj9WJW3B/DIH+REzjpAACPf8brwPeP+7vz3bIim3S+AaMjw== + integrity: sha512-NfbbPPg/74fT7wk2XYQ7hAIp9zJyZp5Fu19iRbORqqy1BhtrkZ0fPafBU+7bmn8ie69DpT0R6QpJIN2oisYjJg== /prop-types/15.7.2: dependencies: loose-envify: 1.4.0 object-assign: 4.1.1 - react-is: 16.11.0 + react-is: 16.12.0 dev: false resolution: integrity: sha512-8QQikdH7//R2vurIJSutZ1smHYTcLpRWEOlHnzcWHmBYrOGUysKwSsrC89BCiFj3CbrfJ/nXFdJepOVrY1GCHQ== @@ -6091,10 +6104,10 @@ packages: dev: false resolution: integrity: sha1-DD0L6u2KAclm2Xh793goElKpeao= - /react-is/16.11.0: + /react-is/16.12.0: dev: false resolution: - integrity: sha512-gbBVYR2p8mnriqAwWx9LbuUrShnAuSCNnuPGyc7GJrMVQtPDAh8iLpv7FRuMPFb56KkaVZIYSz1PrjI9q0QPCw== + integrity: sha512-rPCkf/mWBtKc97aLL9/txD8DZdemK0vkA3JMLShjlJB3Pj3s+lpf1KaBzMfQrAmhMQB0n1cU/SUGgKKBCe837Q== /read-pkg-up/1.0.1: dependencies: find-up: 1.1.2 @@ -6283,7 +6296,7 @@ packages: is-typedarray: 1.0.0 isstream: 0.1.2 json-stringify-safe: 5.0.1 - mime-types: 2.1.24 + mime-types: 2.1.25 oauth-sign: 0.9.0 performance-now: 2.1.0 qs: 6.5.2 @@ -6380,7 +6393,7 @@ packages: integrity: sha1-G0KmJmoh8HQh0bC1S33BZ7AcATs= /rimraf/2.6.3: dependencies: - glob: 7.1.5 + glob: 7.1.6 dev: false hasBin: true resolution: @@ -6443,7 +6456,7 @@ packages: '@cnakazawa/watch': 1.0.3 anymatch: 2.0.0 capture-exit: 2.0.0 - exec-sh: 0.3.2 + exec-sh: 0.3.4 execa: 1.0.0 fb-watchman: 2.0.0 micromatch: 3.1.10 @@ -6457,7 +6470,7 @@ packages: integrity: sha512-hhbzAgTIX8O7SHfp2c8/kREfEn4qO/9q8C9beyY6+tvZ87EpoZ3i1RIEvp27YBswnNbY9mWd6paKVmKbAgLfZA== /sass-graph/2.2.4: dependencies: - glob: 7.1.5 + glob: 7.1.6 lodash: 4.17.15 scss-tokenizer: 0.2.3 yargs: 7.1.0 @@ -6582,7 +6595,7 @@ packages: debug: 2.6.9 escape-html: 1.0.3 http-errors: 1.6.3 - mime-types: 2.1.24 + mime-types: 2.1.25 parseurl: 1.3.3 dev: false engines: @@ -6667,10 +6680,10 @@ packages: dev: false resolution: integrity: sha1-tf3AjxKH6hF4Yo5BXiUTK3NkbG0= - /sisteransi/1.0.3: + /sisteransi/1.0.4: dev: false resolution: - integrity: sha512-SbEG75TzH8G7eVXFSN5f9EExILKfly7SUvVY5DhhYLvfhKqhDFY0OzevWa/zwak0RLRfWS5AvfMWpd9gJvr5Yg== + integrity: sha512-/ekMoM4NJ59ivGSfKapeG+FWtrmWvA1p6FBZwXrqojw90vJu8lBmrTxCMuBCydKtkaUe2zt4PlxeTKpjwMbyig== /slash/2.0.0: dev: false engines: @@ -6962,16 +6975,16 @@ packages: node: '>=6' resolution: integrity: sha512-vafcv6KjVZKSgz06oM/H6GDBrAtz8vdhQakGjFIvNrHA6y3HCF1CInLy+QLq8dTJPQ1b+KDUqDFctkdRW44e1w== - /string-width/4.1.0: + /string-width/4.2.0: dependencies: emoji-regex: 8.0.0 is-fullwidth-code-point: 3.0.0 - strip-ansi: 5.2.0 + strip-ansi: 6.0.0 dev: false engines: node: '>=8' resolution: - integrity: sha512-NrX+1dVVh+6Y9dnQ19pR0pP4FiEIlUvdTGn8pw6CKTNq5sgib2nIhmUNT5TAmhWmvKr3WcxBcP3E8nWezuipuQ== + integrity: sha512-zUz5JD+tgqtuDjMhwIg5uFVV3dtqZ9yQJlZVfq4I01/K5Paj5UHj7VyrQOJvzawSVlKpObApbfD0Ed6yJc+1eg== /string.prototype.trimleft/2.1.0: dependencies: define-properties: 1.1.3 @@ -7026,6 +7039,14 @@ packages: node: '>=6' resolution: integrity: sha512-DuRs1gKbBqsMKIZlrffwlug8MHkcnpjs5VPmL1PAh+mA30U0DTotfDZ0d2UUsXpPmPmMMJ6W773MaA3J+lbiWA== + /strip-ansi/6.0.0: + dependencies: + ansi-regex: 5.0.0 + dev: false + engines: + node: '>=8' + resolution: + integrity: sha512-AuvKTrTfQNYNIctbR1K/YGTR1756GycPsg7b9bdV9Duqur4gv6aKqHXah67Z8ImS7WEz5QVcOtlfW2rZEugt6w== /strip-bom/2.0.0: dependencies: is-utf8: 0.2.1 @@ -7129,7 +7150,7 @@ packages: schema-utils: 1.0.0 serialize-javascript: 1.9.1 source-map: 0.6.1 - terser: 4.3.9 + terser: 4.4.0 webpack-sources: 1.4.3 worker-farm: 1.7.0 dev: false @@ -7139,7 +7160,7 @@ packages: webpack: ^4.0.0 resolution: integrity: sha512-ZXmmfiwtCLfz8WKZyYUuuHf3dMYEjg8NrjHMb0JqHVHVOSkzp3cW2/XG1fP3tRhqEqSzMwzzRQGtAPbs4Cncxg== - /terser/4.3.9: + /terser/4.4.0: dependencies: commander: 2.20.3 source-map: 0.6.1 @@ -7149,10 +7170,10 @@ packages: node: '>=6.0.0' hasBin: true resolution: - integrity: sha512-NFGMpHjlzmyOtPL+fDw3G7+6Ueh/sz4mkaUYa4lJCxOPTNzd0Uj0aZJOmsDYoSQyfuVoWDMSWTPU3huyOm2zdA== + integrity: sha512-oDG16n2WKm27JO8h4y/w3iqBGAOSCtq7k8dRmrn4Wf9NouL0b2WpMHGChFGZq4nFAQy1FsNJrVQHfurXOSTmOA== /test-exclude/5.2.3: dependencies: - glob: 7.1.5 + glob: 7.1.6 minimatch: 3.0.4 read-pkg-up: 4.0.0 require-main-filename: 2.0.0 @@ -7292,7 +7313,7 @@ packages: integrity: sha1-WIeWa7WCpFA6QetST301ARgVphM= /true-case-path/1.0.3: dependencies: - glob: 7.1.5 + glob: 7.1.6 dev: false resolution: integrity: sha512-m6s2OdQe5wgpFMC+pAJ+q9djG82O2jcHPOI6RNg1yy9rCYR+WD6Nbpl32fDpfC56nirdRy+opFa/Vk7HYhqaew== @@ -7424,7 +7445,7 @@ packages: /type-is/1.6.18: dependencies: media-typer: 0.3.0 - mime-types: 2.1.24 + mime-types: 2.1.25 dev: false engines: node: '>= 0.6' @@ -7461,7 +7482,7 @@ packages: hasBin: true resolution: integrity: sha512-Y2VsbPVs0FIshJztycsO2SfPk7/KAF/T72qzv9u5EpQ4kB2hQoHlhNQTsNyy6ul7lQtqJN/AoWeS23OzEiEFxw== - /uglify-js/3.6.7: + /uglify-js/3.6.9: dependencies: commander: 2.20.3 source-map: 0.6.1 @@ -7471,7 +7492,7 @@ packages: hasBin: true optional: true resolution: - integrity: sha512-4sXQDzmdnoXiO+xvmTzQsfIiwrjUCSA95rSP4SEd8tDb51W2TiDOlL76Hl+Kw0Ie42PSItCW8/t6pBNCF2R48A== + integrity: sha512-pcnnhaoG6RtrvHJ1dFncAe8Od6Nuy30oaJ82ts6//sGSXOP5UjBMEthiProjXmMNHOfd93sqlkztifFMcb+4yw== /union-value/1.0.1: dependencies: arr-union: 3.1.0 @@ -7664,7 +7685,7 @@ packages: bfj: 6.1.2 chalk: 2.4.2 commander: 2.20.3 - ejs: 2.7.1 + ejs: 2.7.2 express: 4.17.1 filesize: 3.6.1 gzip-size: 5.1.1 @@ -7766,7 +7787,7 @@ packages: internal-ip: 4.3.0 ip: 1.1.5 killable: 1.0.1 - loglevel: 1.6.4 + loglevel: 1.6.6 opn: 5.5.0 p-retry: 3.0.1 portfinder: 1.0.25 @@ -7807,7 +7828,7 @@ packages: internal-ip: 4.3.0 ip: 1.1.5 killable: 1.0.1 - loglevel: 1.6.4 + loglevel: 1.6.6 opn: 5.5.0 p-retry: 3.0.1 portfinder: 1.0.25 @@ -7943,16 +7964,18 @@ packages: dev: false resolution: integrity: sha512-QGkOQc8XL6Bt5PwnsExKBPuMKBxnGxWWW3fU55Xt4feHozMUhdUMaBCk290qpm/wG5u/RSKzwdAC4i51YigihA== + /word-wrap/1.2.3: + dev: false + engines: + node: '>=0.10.0' + resolution: + integrity: sha512-Hz/mrNwitNRh/HUAtM/VT/5VH+ygD6DV7mYKZAtHOrbs8U7lvPS6xf7EJKMF0uW1KJCl0H701g3ZGus+muE5vQ== /wordwrap/0.0.3: dev: false engines: node: '>=0.4.0' resolution: integrity: sha1-o9XabNXAvAAI03I0u68b7WMFkQc= - /wordwrap/1.0.0: - dev: false - resolution: - integrity: sha1-J1hIEIkUVqQXHI0CJkQa3pDLyus= /worker-farm/1.7.0: dependencies: errno: 0.1.7 @@ -8137,7 +8160,7 @@ packages: 'file:projects/api-demo.tgz': dependencies: '@rushstack/eslint-config': 0.4.0_eslint@6.6.0+typescript@3.5.3 - '@types/node': 10.7.1 + '@types/node': 10.17.5 colors: 1.3.3 eslint: 6.6.0 rimraf: 2.6.3 @@ -8145,7 +8168,7 @@ packages: dev: false name: '@rush-temp/api-demo' resolution: - integrity: sha512-mSCF+G3RFczZmA9m5C60zXoPvNzclVw6zG6bkrsykLXyYRBq5UeeqFGk1eVaNmW+YuG8oBzGdh7y55dzhRrVlw== + integrity: sha512-uAp6Qmz1Q6iPFs4nNmdZrbLsvfy8Vi5xG4+BCxgK+SHatvX/HDwF8hxj1lk6XnR1D76MyYsnvwo8KS7D2XUneQ== tarball: 'file:projects/api-demo.tgz' version: 0.0.0 'file:projects/eslint-plugin-tsdoc.tgz': @@ -8153,16 +8176,36 @@ packages: '@rushstack/eslint-config': 0.4.0_eslint@6.6.0+typescript@3.5.3 '@types/eslint': 6.1.3 '@types/estree': 0.0.39 - '@types/node': 10.7.1 + '@types/node': 10.17.5 eslint: 6.6.0 rimraf: 2.6.3 typescript: 3.5.3 dev: false name: '@rush-temp/eslint-plugin-tsdoc' resolution: - integrity: sha512-h8jfbTIl/FIRhDr2m0g8vJUO9LlCMwjVWOu9rdDluMuykzr4y7ss/RiDYAMtbPOEj3nqNRNzPkqfP9e4RrjDDA== + integrity: sha512-ztdKpdWIiSYJNviBZW/beauYYtwrfsRpduFUWBMG81EKrh8mN13WVZTh0G2+YQSEatmzIna2cPD3egcNJ6givg== tarball: 'file:projects/eslint-plugin-tsdoc.tgz' version: 0.0.0 + 'file:projects/tsdoc-config.tgz': + dependencies: + '@rushstack/eslint-config': 0.4.0_eslint@6.6.0+typescript@3.5.3 + '@types/jest': 24.0.16 + '@types/node': 10.17.5 + '@types/resolve': 0.0.8 + ajv: 6.10.2 + eslint: 6.6.0 + jest: 24.8.0 + prettier: 1.18.2 + resolve: 1.12.0 + rimraf: 2.6.3 + ts-jest: 24.0.2_jest@24.8.0 + typescript: 3.5.3 + dev: false + name: '@rush-temp/tsdoc-config' + resolution: + integrity: sha512-10+gPFDqzNHYRVY75ntY1F7VW8d98NM3LlbuPhR1JVF215K/TsRSoRjtR6BNMQkL56TpWgGxHl9OYk5IuVk4Rg== + tarball: 'file:projects/tsdoc-config.tgz' + version: 0.0.0 'file:projects/tsdoc-playground.tgz': dependencies: '@microsoft/set-webpack-public-path-plugin': 2.1.135 @@ -8194,7 +8237,7 @@ packages: dev: false name: '@rush-temp/tsdoc-playground' resolution: - integrity: sha512-gW+aFPVBOT2qyGswaOg6z6F7YB580yCStKn5NtDWBKJ5x4LYhhIwAcIpgU6F4uzPoUqrY3nAVwIX+cHvV59ptw== + integrity: sha512-H1npMtUKE8arLOtLDkw2DVH1hRuik4GF5c0Tq2lcT+ENYYZYPdaoH3ZKyGBAJjPTzStGk+ZFT6AtfenfrF8Vsg== tarball: 'file:projects/tsdoc-playground.tgz' version: 0.0.0 'file:projects/tsdoc.tgz': @@ -8218,15 +8261,19 @@ specifiers: '@rush-temp/api-demo': 'file:./projects/api-demo.tgz' '@rush-temp/eslint-plugin-tsdoc': 'file:./projects/eslint-plugin-tsdoc.tgz' '@rush-temp/tsdoc': 'file:./projects/tsdoc.tgz' + '@rush-temp/tsdoc-config': 'file:./projects/tsdoc-config.tgz' '@rush-temp/tsdoc-playground': 'file:./projects/tsdoc-playground.tgz' '@rushstack/eslint-config': 0.4.0 '@types/eslint': 6.1.3 '@types/estree': 0.0.39 '@types/jest': 24.0.16 - '@types/node': 10.7.1 + '@types/jest-diff': 20.0.1 + '@types/node': 10.17.5 '@types/react': 16.9.11 '@types/react-dom': 16.9.3 + '@types/resolve': 0.0.8 '@types/webpack-env': ~1.14.0 + ajv: ~6.10.2 clean-webpack-plugin: ~3.0.0 colors: ~1.3.3 css-loader: ~3.1.0 @@ -8242,6 +8289,7 @@ specifiers: prettier: ~1.18.2 promise: ~8.0.3 raw-loader: ~0.5.1 + resolve: ~1.12.0 rimraf: ~2.6.3 sass-loader: ~7.1.0 style-loader: ~0.23.1 From 1ffa92ed130f1dae074bf4ee8405f5757e9a6a6a Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Fri, 15 Nov 2019 00:59:50 -0800 Subject: [PATCH 03/20] Implement ConfigLoader.tryLoadFromPackageFolder() --- tsdoc-config/.vscode/launch.json | 26 ++++++ tsdoc-config/src/ConfigLoader.ts | 79 +++++++++++++++++++ tsdoc-config/src/TSDocConfigFile.ts | 17 ++++ .../src/__tests__/ConfigLoader.test.ts | 33 ++++++++ .../assets/p1/folder/tsdoc-config.json | 3 + .../src/__tests__/assets/p1/package.json | 5 ++ .../src/__tests__/assets/p2/folder/index.d.ts | 1 + .../assets/p2/folder/tsdoc-config.json | 3 + .../src/__tests__/assets/p2/package.json | 5 ++ .../src/__tests__/assets/p3/folder/index.js | 1 + .../assets/p3/folder/tsdoc-config.json | 3 + .../src/__tests__/assets/p3/package.json | 5 ++ .../src/__tests__/assets/p4/package.json | 4 + .../src/__tests__/assets/p4/tsdoc-config.json | 3 + tsdoc-config/src/index.ts | 1 + tsdoc-config/tsconfig.json | 3 +- 16 files changed, 191 insertions(+), 1 deletion(-) create mode 100644 tsdoc-config/.vscode/launch.json create mode 100644 tsdoc-config/src/ConfigLoader.ts create mode 100644 tsdoc-config/src/TSDocConfigFile.ts create mode 100644 tsdoc-config/src/__tests__/ConfigLoader.test.ts create mode 100644 tsdoc-config/src/__tests__/assets/p1/folder/tsdoc-config.json create mode 100644 tsdoc-config/src/__tests__/assets/p1/package.json create mode 100644 tsdoc-config/src/__tests__/assets/p2/folder/index.d.ts create mode 100644 tsdoc-config/src/__tests__/assets/p2/folder/tsdoc-config.json create mode 100644 tsdoc-config/src/__tests__/assets/p2/package.json create mode 100644 tsdoc-config/src/__tests__/assets/p3/folder/index.js create mode 100644 tsdoc-config/src/__tests__/assets/p3/folder/tsdoc-config.json create mode 100644 tsdoc-config/src/__tests__/assets/p3/package.json create mode 100644 tsdoc-config/src/__tests__/assets/p4/package.json create mode 100644 tsdoc-config/src/__tests__/assets/p4/tsdoc-config.json create mode 100644 tsdoc-config/src/index.ts diff --git a/tsdoc-config/.vscode/launch.json b/tsdoc-config/.vscode/launch.json new file mode 100644 index 00000000..66f5f056 --- /dev/null +++ b/tsdoc-config/.vscode/launch.json @@ -0,0 +1,26 @@ +{ + // Use IntelliSense to learn about possible attributes. + // Hover to view descriptions of existing attributes. + // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 + "version": "0.2.0", + "configurations": [ + { + "type": "node", + "request": "launch", + "name": "Jest All", + "program": "${workspaceFolder}/node_modules/jest/bin/jest", + "args": ["--runInBand"], + "console": "integratedTerminal", + "internalConsoleOptions": "neverOpen" + }, + { + "type": "node", + "request": "launch", + "name": "Jest Current File", + "program": "${workspaceFolder}/node_modules/jest/bin/jest", + "args": ["${relativeFile}"], + "console": "integratedTerminal", + "internalConsoleOptions": "neverOpen" + } + ] +} \ No newline at end of file diff --git a/tsdoc-config/src/ConfigLoader.ts b/tsdoc-config/src/ConfigLoader.ts new file mode 100644 index 00000000..2c5aa5cd --- /dev/null +++ b/tsdoc-config/src/ConfigLoader.ts @@ -0,0 +1,79 @@ +import * as fs from 'fs'; +import * as path from 'path'; +import { TSDocConfigFile } from './TSDocConfigFile'; + +interface IPackageJson { + name?: string; + version?: string; + main?: string; + typings?: string; + types?: string; + tsdocConfig?: string; +} + +export class ConfigLoader { + public static readonly JSON_FILE_NAME: string = 'tsdoc-config.json'; + + private static _getExpectedPathForPackage(packageJson: IPackageJson): string { + // Rule 1: If package.json contains the field "tsdocConfig" then that takes precedence + // then that takes precedence. This convention will be rarely needed, since the later + // generally produce a good result. + if (packageJson.tsdocConfig) { + return packageJson.tsdocConfig; + } + + // Rule 2: If package.json contains a field such as "types" or "typings", then look + // for the file in that folder + // + // Rule 3: If package.json contains a field such as "main", then we would look + // for the file in that folder. + // + // Rule 4: Other wise look in the package.json folder, since the default entry point + // is './index.js' + + let entryPointPath: string = 'index.js'; + if (packageJson.types) { + entryPointPath = packageJson.types; + } else if (packageJson.typings) { + entryPointPath = packageJson.typings; + } else if (packageJson.main) { + entryPointPath = packageJson.main; + } + const entryPointFolder: string = path.dirname(entryPointPath); + + return path.join(entryPointFolder, ConfigLoader.JSON_FILE_NAME); + } + + /** + * Given a `packageFolder` path, probe for tsdoc-config.json and return the + * path to this file. + * @returns the absolute path, or `undefined` if not found + */ + private static _tryGetValidPath(packageFolder: string): string | undefined { + const packageJsonPath: string = path.join(packageFolder, 'package.json'); + if (!fs.existsSync(packageJsonPath)) { + throw new Error('package.json was not found under the path: ' + packageFolder); + } + const packageJsonContent: string = fs.readFileSync(packageJsonPath).toString(); + const packageJson: IPackageJson = JSON.parse(packageJsonContent); + const configFilePath: string = ConfigLoader._getExpectedPathForPackage(packageJson); + const configFileAbsolutePath: string = path.resolve(packageFolder, configFilePath); + + if (fs.existsSync(configFileAbsolutePath)) { + return configFileAbsolutePath; + } + + return undefined; + } + + public static tryLoadFromPackageFolder(packageFolder: string): TSDocConfigFile | undefined { + + const rootConfigFilePath: string | undefined = ConfigLoader._tryGetValidPath(packageFolder); + + if (!rootConfigFilePath) { + return undefined; + } + + return TSDocConfigFile.load(rootConfigFilePath); + } +} diff --git a/tsdoc-config/src/TSDocConfigFile.ts b/tsdoc-config/src/TSDocConfigFile.ts new file mode 100644 index 00000000..7fd9cc13 --- /dev/null +++ b/tsdoc-config/src/TSDocConfigFile.ts @@ -0,0 +1,17 @@ +interface ITSDocConfigFileData { + filePath: string; +} + +export class TSDocConfigFile { + public readonly filePath: string; + + private constructor(data: ITSDocConfigFileData) { + this.filePath = data.filePath; + } + + public static load(filePath: string): TSDocConfigFile { + return new TSDocConfigFile({ + filePath + }); + } +} diff --git a/tsdoc-config/src/__tests__/ConfigLoader.test.ts b/tsdoc-config/src/__tests__/ConfigLoader.test.ts new file mode 100644 index 00000000..9424ccba --- /dev/null +++ b/tsdoc-config/src/__tests__/ConfigLoader.test.ts @@ -0,0 +1,33 @@ +import * as path from 'path'; + +import { TSDocConfigFile } from '../TSDocConfigFile'; +import { ConfigLoader } from '../ConfigLoader'; + +function getRelativePath(testPath: string): string { + return path.relative(__dirname, testPath).split('\\').join('/'); +} + +test('Resolve p1', () => { + const configFile: TSDocConfigFile | undefined = ConfigLoader.tryLoadFromPackageFolder( + path.join(__dirname, 'assets/p1')); + expect(configFile).toBeDefined(); + expect(getRelativePath(configFile!.filePath)).toEqual('assets/p1/folder/tsdoc-config.json'); +}); +test('Resolve p2', () => { + const configFile: TSDocConfigFile | undefined = ConfigLoader.tryLoadFromPackageFolder( + path.join(__dirname, 'assets/p2')); + expect(configFile).toBeDefined(); + expect(getRelativePath(configFile!.filePath)).toEqual('assets/p2/folder/tsdoc-config.json'); +}); +test('Resolve p3', () => { + const configFile: TSDocConfigFile | undefined = ConfigLoader.tryLoadFromPackageFolder( + path.join(__dirname, 'assets/p3')); + expect(configFile).toBeDefined(); + expect(getRelativePath(configFile!.filePath)).toEqual('assets/p3/folder/tsdoc-config.json'); +}); +test('Resolve p4', () => { + const configFile: TSDocConfigFile | undefined = ConfigLoader.tryLoadFromPackageFolder( + path.join(__dirname, 'assets/p4')); + expect(configFile).toBeDefined(); + expect(getRelativePath(configFile!.filePath)).toEqual('assets/p4/tsdoc-config.json'); +}); diff --git a/tsdoc-config/src/__tests__/assets/p1/folder/tsdoc-config.json b/tsdoc-config/src/__tests__/assets/p1/folder/tsdoc-config.json new file mode 100644 index 00000000..db3b1772 --- /dev/null +++ b/tsdoc-config/src/__tests__/assets/p1/folder/tsdoc-config.json @@ -0,0 +1,3 @@ +{ + "tsdocVersion": "0.12" +} diff --git a/tsdoc-config/src/__tests__/assets/p1/package.json b/tsdoc-config/src/__tests__/assets/p1/package.json new file mode 100644 index 00000000..64901a8a --- /dev/null +++ b/tsdoc-config/src/__tests__/assets/p1/package.json @@ -0,0 +1,5 @@ +{ + "name": "p1", + "version": "1.0.0", + "tsdocConfig": "./folder/tsdoc-config.json" +} diff --git a/tsdoc-config/src/__tests__/assets/p2/folder/index.d.ts b/tsdoc-config/src/__tests__/assets/p2/folder/index.d.ts new file mode 100644 index 00000000..8b1a3937 --- /dev/null +++ b/tsdoc-config/src/__tests__/assets/p2/folder/index.d.ts @@ -0,0 +1 @@ +// empty diff --git a/tsdoc-config/src/__tests__/assets/p2/folder/tsdoc-config.json b/tsdoc-config/src/__tests__/assets/p2/folder/tsdoc-config.json new file mode 100644 index 00000000..db3b1772 --- /dev/null +++ b/tsdoc-config/src/__tests__/assets/p2/folder/tsdoc-config.json @@ -0,0 +1,3 @@ +{ + "tsdocVersion": "0.12" +} diff --git a/tsdoc-config/src/__tests__/assets/p2/package.json b/tsdoc-config/src/__tests__/assets/p2/package.json new file mode 100644 index 00000000..4267e1e5 --- /dev/null +++ b/tsdoc-config/src/__tests__/assets/p2/package.json @@ -0,0 +1,5 @@ +{ + "name": "p2", + "version": "1.0.0", + "typings": "./folder/index.d.ts" +} \ No newline at end of file diff --git a/tsdoc-config/src/__tests__/assets/p3/folder/index.js b/tsdoc-config/src/__tests__/assets/p3/folder/index.js new file mode 100644 index 00000000..8b1a3937 --- /dev/null +++ b/tsdoc-config/src/__tests__/assets/p3/folder/index.js @@ -0,0 +1 @@ +// empty diff --git a/tsdoc-config/src/__tests__/assets/p3/folder/tsdoc-config.json b/tsdoc-config/src/__tests__/assets/p3/folder/tsdoc-config.json new file mode 100644 index 00000000..db3b1772 --- /dev/null +++ b/tsdoc-config/src/__tests__/assets/p3/folder/tsdoc-config.json @@ -0,0 +1,3 @@ +{ + "tsdocVersion": "0.12" +} diff --git a/tsdoc-config/src/__tests__/assets/p3/package.json b/tsdoc-config/src/__tests__/assets/p3/package.json new file mode 100644 index 00000000..1d960b8e --- /dev/null +++ b/tsdoc-config/src/__tests__/assets/p3/package.json @@ -0,0 +1,5 @@ +{ + "name": "p3", + "version": "1.0.0", + "main": "./folder/index.js" +} diff --git a/tsdoc-config/src/__tests__/assets/p4/package.json b/tsdoc-config/src/__tests__/assets/p4/package.json new file mode 100644 index 00000000..42d069b0 --- /dev/null +++ b/tsdoc-config/src/__tests__/assets/p4/package.json @@ -0,0 +1,4 @@ +{ + "name": "p4", + "version": "1.0.0" +} diff --git a/tsdoc-config/src/__tests__/assets/p4/tsdoc-config.json b/tsdoc-config/src/__tests__/assets/p4/tsdoc-config.json new file mode 100644 index 00000000..db3b1772 --- /dev/null +++ b/tsdoc-config/src/__tests__/assets/p4/tsdoc-config.json @@ -0,0 +1,3 @@ +{ + "tsdocVersion": "0.12" +} diff --git a/tsdoc-config/src/index.ts b/tsdoc-config/src/index.ts new file mode 100644 index 00000000..7b0b16da --- /dev/null +++ b/tsdoc-config/src/index.ts @@ -0,0 +1 @@ +export { TSDocConfigFile } from './TSDocConfigFile'; diff --git a/tsdoc-config/tsconfig.json b/tsdoc-config/tsconfig.json index e0c14521..92fe72e1 100644 --- a/tsdoc-config/tsconfig.json +++ b/tsdoc-config/tsconfig.json @@ -9,7 +9,8 @@ "sourceMap": true, "experimentalDecorators": true, "types": [ - "jest" + "jest", + "node" ], "lib": [ "es5", From 6d42f80a64adfd76b953c62dfc7161b55282c94f Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Fri, 15 Nov 2019 01:08:29 -0800 Subject: [PATCH 04/20] Bring over @ecraig12345's schema from https://github.com/microsoft/rushstack/pull/1628 --- .../src/schemas/tsdoc-config.schema.json | 59 +++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 tsdoc-config/src/schemas/tsdoc-config.schema.json diff --git a/tsdoc-config/src/schemas/tsdoc-config.schema.json b/tsdoc-config/src/schemas/tsdoc-config.schema.json new file mode 100644 index 00000000..c069b4b2 --- /dev/null +++ b/tsdoc-config/src/schemas/tsdoc-config.schema.json @@ -0,0 +1,59 @@ +{ + "title": "TSDoc Configuration", + "description": "Describes the TSDoc configuration for a TypeScript project", + "type": "object", + "properties": { + "$schema": { + "description": "Part of the JSON Schema standard, this optional keyword declares the URL of the schema that the file conforms to. Editors may download the schema and use it to perform syntax highlighting.", + "type": "string" + }, + + "tsdocVersion": { + "description": "The target version of the TSDoc spec", + "type": "string", + "pattern": "^[0-9]+\\.[0-9]+$" + }, + + "extends": { + "description": "Optionally specifies another JSON config files that this file extends from. This provides a way for standard settings to be shared across multiple projects.", + "type": "array", + "items": { + "type": "string" + } + }, + + "tagDefinitions": { + "description": "Additional tags to support when parsing documentation comments with TSDoc.", + "type": "array", + "items": { + "$ref": "#/definitions/tsdocTagDefinition" + } + } + }, + "required": [ "tsdocVersion" ], + "additionalProperties": false, + + "definitions": { + "tsdocTagDefinition": { + "description": "Configuration for a custom supported TSDoc tag.", + "type": "object", + "properties": { + "tagName": { + "description": "Name of the custom tag. TSDoc tag names start with an at-sign (@) followed by ASCII letters using camelCase capitalization.", + "type": "string" + }, + "syntaxKind": { + "description": "Syntax kind of the custom tag. \"inline\" means that this tag can appear inside other documentation sections (example: {@link}). \"block\" means that this tag starts a new documentation section (example: @remarks). \"modifier\" means that this tag's presence indicates an aspect of the associated API item (example: @internal).", + "type": "string", + "enum": ["inline", "block", "modifier"] + }, + "allowMultiple": { + "description": "If true, then this tag may appear multiple times in a doc comment. By default, a tag may only appear once.", + "type": "boolean" + } + }, + "required": ["tagName", "syntaxKind"], + "additionalProperties": false + } + } +} From 107100b853dc3a9f45a9cdfa80ca18e71f4e8d8e Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Fri, 15 Nov 2019 01:19:19 -0800 Subject: [PATCH 05/20] Implement schema validation --- tsdoc-config/src/TSDocConfigFile.ts | 40 +++++++++++++++++++++++++++-- 1 file changed, 38 insertions(+), 2 deletions(-) diff --git a/tsdoc-config/src/TSDocConfigFile.ts b/tsdoc-config/src/TSDocConfigFile.ts index 7fd9cc13..76f330b3 100644 --- a/tsdoc-config/src/TSDocConfigFile.ts +++ b/tsdoc-config/src/TSDocConfigFile.ts @@ -1,17 +1,53 @@ +import * as fs from 'fs'; +import * as path from 'path'; +import * as Ajv from 'ajv'; + interface ITSDocConfigFileData { filePath: string; } +const ajv: Ajv.Ajv = new Ajv({ verbose: true }); + +function initializeSchemaValidator(): Ajv.ValidateFunction { + const jsonSchemaContent: string = fs.readFileSync(path.join(__dirname, 'schemas/tsdoc-config.schema.json')) + .toString(); + const jsonSchema: object = JSON.parse(jsonSchemaContent); + + return ajv.compile(jsonSchema); +} + +// Warning: AJV has a fairly strange API. Each time this function is called, the function object's +// properties get overwritten with the results of the latest validation. Thus we need to be careful +// to read the properties before a subsequent call may occur. +const tsdocSchemaValidator: Ajv.ValidateFunction = initializeSchemaValidator(); + +interface IConfigJson { +} + export class TSDocConfigFile { + public readonly filePath: string; private constructor(data: ITSDocConfigFileData) { this.filePath = data.filePath; } - public static load(filePath: string): TSDocConfigFile { + public static load(jsonFilePath: string): TSDocConfigFile { + const fullJsonFilePath: string = path.resolve(jsonFilePath); + + const configJsonContent: string = fs.readFileSync(fullJsonFilePath).toString(); + + const configJson: IConfigJson = JSON.parse(configJsonContent); + const success: boolean = tsdocSchemaValidator(configJson) as boolean; + + if (!success) { + const description: string = ajv.errorsText(tsdocSchemaValidator.errors); + throw new Error('Error parsing config file: ' + description + + '\nError in file: ' + jsonFilePath); + } + return new TSDocConfigFile({ - filePath + filePath: fullJsonFilePath }); } } From 7db88effcbac5f24bf72d9688cd40b15005f97d7 Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Fri, 15 Nov 2019 01:34:09 -0800 Subject: [PATCH 06/20] Implement TSDocConfigFile state --- tsdoc-config/package.json | 1 + tsdoc-config/src/TSDocConfigFile.ts | 50 ++++++++++++--- .../src/__tests__/ConfigLoader.test.ts | 63 ++++++++++++++++--- .../src/__tests__/assets/p5/package.json | 4 ++ .../src/__tests__/assets/p5/tsdoc-config.json | 21 +++++++ 5 files changed, 121 insertions(+), 18 deletions(-) create mode 100644 tsdoc-config/src/__tests__/assets/p5/package.json create mode 100644 tsdoc-config/src/__tests__/assets/p5/tsdoc-config.json diff --git a/tsdoc-config/package.json b/tsdoc-config/package.json index 87ed716c..f080d58f 100644 --- a/tsdoc-config/package.json +++ b/tsdoc-config/package.json @@ -20,6 +20,7 @@ "typings": "lib/index.d.ts", "license": "MIT", "dependencies": { + "@microsoft/tsdoc": "0.12.15", "ajv": "~6.10.2", "resolve": "~1.12.0" }, diff --git a/tsdoc-config/src/TSDocConfigFile.ts b/tsdoc-config/src/TSDocConfigFile.ts index 76f330b3..bd6ef76a 100644 --- a/tsdoc-config/src/TSDocConfigFile.ts +++ b/tsdoc-config/src/TSDocConfigFile.ts @@ -1,11 +1,8 @@ +import { TSDocTagDefinition, TSDocTagSyntaxKind } from '@microsoft/tsdoc'; import * as fs from 'fs'; import * as path from 'path'; import * as Ajv from 'ajv'; -interface ITSDocConfigFileData { - filePath: string; -} - const ajv: Ajv.Ajv = new Ajv({ verbose: true }); function initializeSchemaValidator(): Ajv.ValidateFunction { @@ -21,15 +18,52 @@ function initializeSchemaValidator(): Ajv.ValidateFunction { // to read the properties before a subsequent call may occur. const tsdocSchemaValidator: Ajv.ValidateFunction = initializeSchemaValidator(); +interface ITagConfigJson { + tagName: string; + syntaxKind: 'inline' | 'block' | 'modifier'; + allowMultiple?: boolean; +} + interface IConfigJson { + tsdocVersion: string; + extends?: string[]; + tagDefinitions: ITagConfigJson[]; } export class TSDocConfigFile { public readonly filePath: string; - private constructor(data: ITSDocConfigFileData) { - this.filePath = data.filePath; + public readonly tsdocVersion: string; + + public readonly extends: ReadonlyArray; + + public readonly tagDefinitions: ReadonlyArray; + + private constructor(filePath: string, configJson: IConfigJson) { + this.filePath = filePath; + this.tsdocVersion = configJson.tsdocVersion; + this.extends = configJson.extends || []; + const tagDefinitions: TSDocTagDefinition[] = []; + + for (const jsonTagDefinition of configJson.tagDefinitions || []) { + let syntaxKind: TSDocTagSyntaxKind; + switch (jsonTagDefinition.syntaxKind) { + case 'inline': syntaxKind = TSDocTagSyntaxKind.InlineTag; break; + case 'block': syntaxKind = TSDocTagSyntaxKind.BlockTag; break; + case 'modifier': syntaxKind = TSDocTagSyntaxKind.ModifierTag; break; + default: + // The JSON schema should have caught this error + throw new Error('Unexpected tag kind'); + } + tagDefinitions.push(new TSDocTagDefinition({ + tagName: jsonTagDefinition.tagName, + syntaxKind: syntaxKind, + allowMultiple: jsonTagDefinition.allowMultiple + })); + } + + this.tagDefinitions = tagDefinitions; } public static load(jsonFilePath: string): TSDocConfigFile { @@ -46,8 +80,6 @@ export class TSDocConfigFile { + '\nError in file: ' + jsonFilePath); } - return new TSDocConfigFile({ - filePath: fullJsonFilePath - }); + return new TSDocConfigFile(fullJsonFilePath, configJson); } } diff --git a/tsdoc-config/src/__tests__/ConfigLoader.test.ts b/tsdoc-config/src/__tests__/ConfigLoader.test.ts index 9424ccba..8f625363 100644 --- a/tsdoc-config/src/__tests__/ConfigLoader.test.ts +++ b/tsdoc-config/src/__tests__/ConfigLoader.test.ts @@ -4,30 +4,75 @@ import { TSDocConfigFile } from '../TSDocConfigFile'; import { ConfigLoader } from '../ConfigLoader'; function getRelativePath(testPath: string): string { - return path.relative(__dirname, testPath).split('\\').join('/'); + return path + .relative(__dirname, testPath) + .split('\\') + .join('/'); } -test('Resolve p1', () => { +test('Load p1', () => { const configFile: TSDocConfigFile | undefined = ConfigLoader.tryLoadFromPackageFolder( - path.join(__dirname, 'assets/p1')); + path.join(__dirname, 'assets/p1') + ); expect(configFile).toBeDefined(); expect(getRelativePath(configFile!.filePath)).toEqual('assets/p1/folder/tsdoc-config.json'); }); -test('Resolve p2', () => { +test('Load p2', () => { const configFile: TSDocConfigFile | undefined = ConfigLoader.tryLoadFromPackageFolder( - path.join(__dirname, 'assets/p2')); + path.join(__dirname, 'assets/p2') + ); expect(configFile).toBeDefined(); expect(getRelativePath(configFile!.filePath)).toEqual('assets/p2/folder/tsdoc-config.json'); }); -test('Resolve p3', () => { +test('Load p3', () => { const configFile: TSDocConfigFile | undefined = ConfigLoader.tryLoadFromPackageFolder( - path.join(__dirname, 'assets/p3')); + path.join(__dirname, 'assets/p3') + ); expect(configFile).toBeDefined(); expect(getRelativePath(configFile!.filePath)).toEqual('assets/p3/folder/tsdoc-config.json'); }); -test('Resolve p4', () => { +test('Load p4', () => { const configFile: TSDocConfigFile | undefined = ConfigLoader.tryLoadFromPackageFolder( - path.join(__dirname, 'assets/p4')); + path.join(__dirname, 'assets/p4') + ); expect(configFile).toBeDefined(); expect(getRelativePath(configFile!.filePath)).toEqual('assets/p4/tsdoc-config.json'); }); +test('Load p5', () => { + const configFile: TSDocConfigFile | undefined = ConfigLoader.tryLoadFromPackageFolder( + path.join(__dirname, 'assets/p5') + ); + expect(configFile).toMatchInlineSnapshot( + { filePath: expect.any(String) }, + ` + Object { + "extends": Array [], + "filePath": Any, + "tagDefinitions": Array [ + TSDocTagDefinition { + "allowMultiple": true, + "standardization": "None", + "syntaxKind": 0, + "tagName": "@myInlineTag", + "tagNameWithUpperCase": "@MYINLINETAG", + }, + TSDocTagDefinition { + "allowMultiple": false, + "standardization": "None", + "syntaxKind": 1, + "tagName": "@myBlockTag", + "tagNameWithUpperCase": "@MYBLOCKTAG", + }, + TSDocTagDefinition { + "allowMultiple": false, + "standardization": "None", + "syntaxKind": 2, + "tagName": "@myModifierTag", + "tagNameWithUpperCase": "@MYMODIFIERTAG", + }, + ], + "tsdocVersion": "0.12", + } + ` + ); +}); diff --git a/tsdoc-config/src/__tests__/assets/p5/package.json b/tsdoc-config/src/__tests__/assets/p5/package.json new file mode 100644 index 00000000..42d069b0 --- /dev/null +++ b/tsdoc-config/src/__tests__/assets/p5/package.json @@ -0,0 +1,4 @@ +{ + "name": "p4", + "version": "1.0.0" +} diff --git a/tsdoc-config/src/__tests__/assets/p5/tsdoc-config.json b/tsdoc-config/src/__tests__/assets/p5/tsdoc-config.json new file mode 100644 index 00000000..dd6cd0c8 --- /dev/null +++ b/tsdoc-config/src/__tests__/assets/p5/tsdoc-config.json @@ -0,0 +1,21 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/tsdoc-config.schema.json", + "tsdocVersion": "0.12", + "extends": [], + "tagDefinitions": [ + { + "tagName": "@myInlineTag", + "syntaxKind": "inline", + "allowMultiple": true + }, + { + "tagName": "@myBlockTag", + "syntaxKind": "block" + }, + { + "tagName": "@myModifierTag", + "syntaxKind": "modifier", + "allowMultiple": false + } + ] +} From cae36e8de0618517585e2d3ffdc48827957196de Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Fri, 15 Nov 2019 01:43:50 -0800 Subject: [PATCH 07/20] Replace "tsdocVersion" with "$schema" --- tsdoc-config/src/ConfigLoader.ts | 6 +++- tsdoc-config/src/TSDocConfigFile.ts | 31 ++++++++++++++++--- .../src/__tests__/ConfigLoader.test.ts | 2 +- .../assets/p1/folder/tsdoc-config.json | 2 +- .../assets/p2/folder/tsdoc-config.json | 2 +- .../assets/p3/folder/tsdoc-config.json | 2 +- .../src/__tests__/assets/p4/tsdoc-config.json | 2 +- .../src/__tests__/assets/p5/tsdoc-config.json | 3 +- tsdoc-config/src/index.ts | 1 + .../src/schemas/tsdoc-config.schema.json | 8 +---- 10 files changed, 40 insertions(+), 19 deletions(-) diff --git a/tsdoc-config/src/ConfigLoader.ts b/tsdoc-config/src/ConfigLoader.ts index 2c5aa5cd..886d6ef6 100644 --- a/tsdoc-config/src/ConfigLoader.ts +++ b/tsdoc-config/src/ConfigLoader.ts @@ -11,6 +11,10 @@ interface IPackageJson { tsdocConfig?: string; } +/** + * Use this class to load the `tsdoc-config.json` file. + * @public + */ export class ConfigLoader { public static readonly JSON_FILE_NAME: string = 'tsdoc-config.json'; @@ -74,6 +78,6 @@ export class ConfigLoader { return undefined; } - return TSDocConfigFile.load(rootConfigFilePath); + return TSDocConfigFile.loadFromFile(rootConfigFilePath); } } diff --git a/tsdoc-config/src/TSDocConfigFile.ts b/tsdoc-config/src/TSDocConfigFile.ts index bd6ef76a..4b2a35bc 100644 --- a/tsdoc-config/src/TSDocConfigFile.ts +++ b/tsdoc-config/src/TSDocConfigFile.ts @@ -25,24 +25,38 @@ interface ITagConfigJson { } interface IConfigJson { + $schema: string; tsdocVersion: string; extends?: string[]; tagDefinitions: ITagConfigJson[]; } +/** + * Represents an individual `tsdoc-config.json` file. + * + * @public + */ export class TSDocConfigFile { - + /** + * The full path of the file. + */ public readonly filePath: string; - public readonly tsdocVersion: string; + /** + * The `$schema` field from the `tsdoc-config.json` file. + */ + public readonly tsdocSchema: string; + /** + * Module paths for other config files that this file extends from. + */ public readonly extends: ReadonlyArray; public readonly tagDefinitions: ReadonlyArray; private constructor(filePath: string, configJson: IConfigJson) { this.filePath = filePath; - this.tsdocVersion = configJson.tsdocVersion; + this.tsdocSchema = configJson.$schema; this.extends = configJson.extends || []; const tagDefinitions: TSDocTagDefinition[] = []; @@ -66,7 +80,16 @@ export class TSDocConfigFile { this.tagDefinitions = tagDefinitions; } - public static load(jsonFilePath: string): TSDocConfigFile { + /** + * Loads the contents of a single JSON input file. + * + * @remarks + * + * This method does not process the `extends` field of `tsdoc-config.json`. + * For full functionality, including discovery of the file path, use the {@link ConfigLoader} + * API instead. + */ + public static loadFromFile(jsonFilePath: string): TSDocConfigFile { const fullJsonFilePath: string = path.resolve(jsonFilePath); const configJsonContent: string = fs.readFileSync(fullJsonFilePath).toString(); diff --git a/tsdoc-config/src/__tests__/ConfigLoader.test.ts b/tsdoc-config/src/__tests__/ConfigLoader.test.ts index 8f625363..b75f0e12 100644 --- a/tsdoc-config/src/__tests__/ConfigLoader.test.ts +++ b/tsdoc-config/src/__tests__/ConfigLoader.test.ts @@ -71,7 +71,7 @@ test('Load p5', () => { "tagNameWithUpperCase": "@MYMODIFIERTAG", }, ], - "tsdocVersion": "0.12", + "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json", } ` ); diff --git a/tsdoc-config/src/__tests__/assets/p1/folder/tsdoc-config.json b/tsdoc-config/src/__tests__/assets/p1/folder/tsdoc-config.json index db3b1772..244bc3a6 100644 --- a/tsdoc-config/src/__tests__/assets/p1/folder/tsdoc-config.json +++ b/tsdoc-config/src/__tests__/assets/p1/folder/tsdoc-config.json @@ -1,3 +1,3 @@ { - "tsdocVersion": "0.12" + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json" } diff --git a/tsdoc-config/src/__tests__/assets/p2/folder/tsdoc-config.json b/tsdoc-config/src/__tests__/assets/p2/folder/tsdoc-config.json index db3b1772..244bc3a6 100644 --- a/tsdoc-config/src/__tests__/assets/p2/folder/tsdoc-config.json +++ b/tsdoc-config/src/__tests__/assets/p2/folder/tsdoc-config.json @@ -1,3 +1,3 @@ { - "tsdocVersion": "0.12" + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json" } diff --git a/tsdoc-config/src/__tests__/assets/p3/folder/tsdoc-config.json b/tsdoc-config/src/__tests__/assets/p3/folder/tsdoc-config.json index db3b1772..244bc3a6 100644 --- a/tsdoc-config/src/__tests__/assets/p3/folder/tsdoc-config.json +++ b/tsdoc-config/src/__tests__/assets/p3/folder/tsdoc-config.json @@ -1,3 +1,3 @@ { - "tsdocVersion": "0.12" + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json" } diff --git a/tsdoc-config/src/__tests__/assets/p4/tsdoc-config.json b/tsdoc-config/src/__tests__/assets/p4/tsdoc-config.json index db3b1772..244bc3a6 100644 --- a/tsdoc-config/src/__tests__/assets/p4/tsdoc-config.json +++ b/tsdoc-config/src/__tests__/assets/p4/tsdoc-config.json @@ -1,3 +1,3 @@ { - "tsdocVersion": "0.12" + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json" } diff --git a/tsdoc-config/src/__tests__/assets/p5/tsdoc-config.json b/tsdoc-config/src/__tests__/assets/p5/tsdoc-config.json index dd6cd0c8..c83d2c79 100644 --- a/tsdoc-config/src/__tests__/assets/p5/tsdoc-config.json +++ b/tsdoc-config/src/__tests__/assets/p5/tsdoc-config.json @@ -1,6 +1,5 @@ { - "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/tsdoc-config.schema.json", - "tsdocVersion": "0.12", + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json", "extends": [], "tagDefinitions": [ { diff --git a/tsdoc-config/src/index.ts b/tsdoc-config/src/index.ts index 7b0b16da..965232c5 100644 --- a/tsdoc-config/src/index.ts +++ b/tsdoc-config/src/index.ts @@ -1 +1,2 @@ export { TSDocConfigFile } from './TSDocConfigFile'; +export { ConfigLoader } from './ConfigLoader'; diff --git a/tsdoc-config/src/schemas/tsdoc-config.schema.json b/tsdoc-config/src/schemas/tsdoc-config.schema.json index c069b4b2..f6cc9df2 100644 --- a/tsdoc-config/src/schemas/tsdoc-config.schema.json +++ b/tsdoc-config/src/schemas/tsdoc-config.schema.json @@ -8,12 +8,6 @@ "type": "string" }, - "tsdocVersion": { - "description": "The target version of the TSDoc spec", - "type": "string", - "pattern": "^[0-9]+\\.[0-9]+$" - }, - "extends": { "description": "Optionally specifies another JSON config files that this file extends from. This provides a way for standard settings to be shared across multiple projects.", "type": "array", @@ -30,7 +24,7 @@ } } }, - "required": [ "tsdocVersion" ], + "required": [ "$schema" ], "additionalProperties": false, "definitions": { From 3c5bd9810973907ee9ff396d16c6aabb2ef57b84 Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Fri, 15 Nov 2019 02:04:51 -0800 Subject: [PATCH 08/20] Load configs referenced by "extends" --- tsdoc-config/src/ConfigLoader.ts | 30 ++++++- tsdoc-config/src/TSDocConfigFile.ts | 23 ++++- .../src/__tests__/ConfigLoader.test.ts | 83 +++++++++++++++++-- .../src/__tests__/assets/p5/package.json | 2 +- .../assets/p6/base1/tsdoc-config.json | 9 ++ .../assets/p6/base2/tsdoc-config.json | 9 ++ .../src/__tests__/assets/p6/package.json | 4 + .../src/__tests__/assets/p6/tsdoc-config.json | 13 +++ 8 files changed, 162 insertions(+), 11 deletions(-) create mode 100644 tsdoc-config/src/__tests__/assets/p6/base1/tsdoc-config.json create mode 100644 tsdoc-config/src/__tests__/assets/p6/base2/tsdoc-config.json create mode 100644 tsdoc-config/src/__tests__/assets/p6/package.json create mode 100644 tsdoc-config/src/__tests__/assets/p6/tsdoc-config.json diff --git a/tsdoc-config/src/ConfigLoader.ts b/tsdoc-config/src/ConfigLoader.ts index 886d6ef6..8854fcbf 100644 --- a/tsdoc-config/src/ConfigLoader.ts +++ b/tsdoc-config/src/ConfigLoader.ts @@ -1,5 +1,6 @@ import * as fs from 'fs'; import * as path from 'path'; +import * as resolve from 'resolve'; import { TSDocConfigFile } from './TSDocConfigFile'; interface IPackageJson { @@ -70,14 +71,41 @@ export class ConfigLoader { return undefined; } + private static _loadAndExtend(configFilePath: string, alreadyVisitedPaths: Set): TSDocConfigFile { + const hashKey: string = fs.realpathSync(configFilePath); + if (alreadyVisitedPaths.has(hashKey)) { + throw new Error('Circular reference encountered for "extends" field of ' + configFilePath); + } + alreadyVisitedPaths.add(hashKey); + + const configFile: TSDocConfigFile = TSDocConfigFile.loadFromFile(configFilePath); + + const configFileFolder: string = path.dirname(configFile.filePath); + + for (const extendsField of configFile.extendsPaths) { + const resolvedExtendsPath: string = resolve.sync(extendsField, { basedir: configFileFolder }); + if (!fs.existsSync(resolvedExtendsPath)) { + throw new Error('Unable to resolve "extends" field of ' + configFilePath); + } + + const baseConfigFile: TSDocConfigFile = ConfigLoader._loadAndExtend(resolvedExtendsPath, alreadyVisitedPaths); + configFile.addExtendsFile(baseConfigFile); + } + + return configFile; + } + public static tryLoadFromPackageFolder(packageFolder: string): TSDocConfigFile | undefined { const rootConfigFilePath: string | undefined = ConfigLoader._tryGetValidPath(packageFolder); if (!rootConfigFilePath) { + // There is no tsdoc-config.json for this project return undefined; } - return TSDocConfigFile.loadFromFile(rootConfigFilePath); + const alreadyVisitedPaths: Set = new Set(); + + return ConfigLoader._loadAndExtend(rootConfigFilePath, alreadyVisitedPaths); } } diff --git a/tsdoc-config/src/TSDocConfigFile.ts b/tsdoc-config/src/TSDocConfigFile.ts index 4b2a35bc..db6c6a9e 100644 --- a/tsdoc-config/src/TSDocConfigFile.ts +++ b/tsdoc-config/src/TSDocConfigFile.ts @@ -37,6 +37,8 @@ interface IConfigJson { * @public */ export class TSDocConfigFile { + private readonly _extendsFiles: TSDocConfigFile[] = []; + /** * The full path of the file. */ @@ -48,16 +50,17 @@ export class TSDocConfigFile { public readonly tsdocSchema: string; /** - * Module paths for other config files that this file extends from. + * The `extends` field from the `tsdoc-config.json` file. For the parsed file contents, + * use the `extendsFiles` property instead. */ - public readonly extends: ReadonlyArray; + public readonly extendsPaths: ReadonlyArray; public readonly tagDefinitions: ReadonlyArray; private constructor(filePath: string, configJson: IConfigJson) { this.filePath = filePath; this.tsdocSchema = configJson.$schema; - this.extends = configJson.extends || []; + this.extendsPaths = configJson.extends || []; const tagDefinitions: TSDocTagDefinition[] = []; for (const jsonTagDefinition of configJson.tagDefinitions || []) { @@ -80,6 +83,13 @@ export class TSDocConfigFile { this.tagDefinitions = tagDefinitions; } + /** + * Other config files that this file extends from. + */ + public get extendsFiles(): ReadonlyArray { + return this._extendsFiles; + } + /** * Loads the contents of a single JSON input file. * @@ -105,4 +115,11 @@ export class TSDocConfigFile { return new TSDocConfigFile(fullJsonFilePath, configJson); } + + /** + * Adds an item to `TSDocConfigFile.extendsFiles`. + */ + public addExtendsFile(otherFile: TSDocConfigFile): void { + this._extendsFiles.push(otherFile); + } } diff --git a/tsdoc-config/src/__tests__/ConfigLoader.test.ts b/tsdoc-config/src/__tests__/ConfigLoader.test.ts index b75f0e12..c548e7b0 100644 --- a/tsdoc-config/src/__tests__/ConfigLoader.test.ts +++ b/tsdoc-config/src/__tests__/ConfigLoader.test.ts @@ -10,6 +10,23 @@ function getRelativePath(testPath: string): string { .join('/'); } +expect.addSnapshotSerializer({ + // eslint-disable-next-line @typescript-eslint/no-explicit-any + test(value: any) { + return value instanceof TSDocConfigFile; + }, + // eslint-disable-next-line @typescript-eslint/no-explicit-any + print(value: any, serialize: (value: any) => string, indent: (str: string) => string): any { + return serialize({ + tsdocSchema: value.tsdocSchema, + filePath: getRelativePath(value.filePath), + extendsPaths: value.extendsPaths, + extendsFiles: value.extendsFiles, + tagDefinitions: value.tagDefinitions + }); + } +}); + test('Load p1', () => { const configFile: TSDocConfigFile | undefined = ConfigLoader.tryLoadFromPackageFolder( path.join(__dirname, 'assets/p1') @@ -42,12 +59,11 @@ test('Load p5', () => { const configFile: TSDocConfigFile | undefined = ConfigLoader.tryLoadFromPackageFolder( path.join(__dirname, 'assets/p5') ); - expect(configFile).toMatchInlineSnapshot( - { filePath: expect.any(String) }, - ` + expect(configFile).toMatchInlineSnapshot(` Object { - "extends": Array [], - "filePath": Any, + "extendsFiles": Array [], + "extendsPaths": Array [], + "filePath": "assets/p5/tsdoc-config.json", "tagDefinitions": Array [ TSDocTagDefinition { "allowMultiple": true, @@ -73,6 +89,61 @@ test('Load p5', () => { ], "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json", } - ` + `); +}); +test('Load p6', () => { + const configFile: TSDocConfigFile | undefined = ConfigLoader.tryLoadFromPackageFolder( + path.join(__dirname, 'assets/p6') ); + expect(configFile).toMatchInlineSnapshot(` + Object { + "extendsFiles": Array [ + Object { + "extendsFiles": Array [], + "extendsPaths": Array [], + "filePath": "assets/p6/base1/tsdoc-config.json", + "tagDefinitions": Array [ + TSDocTagDefinition { + "allowMultiple": false, + "standardization": "None", + "syntaxKind": 2, + "tagName": "@base1", + "tagNameWithUpperCase": "@BASE1", + }, + ], + "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json", + }, + Object { + "extendsFiles": Array [], + "extendsPaths": Array [], + "filePath": "assets/p6/base2/tsdoc-config.json", + "tagDefinitions": Array [ + TSDocTagDefinition { + "allowMultiple": false, + "standardization": "None", + "syntaxKind": 2, + "tagName": "@base2", + "tagNameWithUpperCase": "@BASE2", + }, + ], + "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json", + }, + ], + "extendsPaths": Array [ + "./base1/tsdoc-config.json", + "./base2/tsdoc-config.json", + ], + "filePath": "assets/p6/tsdoc-config.json", + "tagDefinitions": Array [ + TSDocTagDefinition { + "allowMultiple": false, + "standardization": "None", + "syntaxKind": 2, + "tagName": "@root", + "tagNameWithUpperCase": "@ROOT", + }, + ], + "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json", + } + `); }); diff --git a/tsdoc-config/src/__tests__/assets/p5/package.json b/tsdoc-config/src/__tests__/assets/p5/package.json index 42d069b0..c168e58f 100644 --- a/tsdoc-config/src/__tests__/assets/p5/package.json +++ b/tsdoc-config/src/__tests__/assets/p5/package.json @@ -1,4 +1,4 @@ { - "name": "p4", + "name": "p5", "version": "1.0.0" } diff --git a/tsdoc-config/src/__tests__/assets/p6/base1/tsdoc-config.json b/tsdoc-config/src/__tests__/assets/p6/base1/tsdoc-config.json new file mode 100644 index 00000000..fc433ac6 --- /dev/null +++ b/tsdoc-config/src/__tests__/assets/p6/base1/tsdoc-config.json @@ -0,0 +1,9 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json", + "tagDefinitions": [ + { + "tagName": "@base1", + "syntaxKind": "modifier" + } + ] +} diff --git a/tsdoc-config/src/__tests__/assets/p6/base2/tsdoc-config.json b/tsdoc-config/src/__tests__/assets/p6/base2/tsdoc-config.json new file mode 100644 index 00000000..9ba3e523 --- /dev/null +++ b/tsdoc-config/src/__tests__/assets/p6/base2/tsdoc-config.json @@ -0,0 +1,9 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json", + "tagDefinitions": [ + { + "tagName": "@base2", + "syntaxKind": "modifier" + } + ] +} diff --git a/tsdoc-config/src/__tests__/assets/p6/package.json b/tsdoc-config/src/__tests__/assets/p6/package.json new file mode 100644 index 00000000..0018f065 --- /dev/null +++ b/tsdoc-config/src/__tests__/assets/p6/package.json @@ -0,0 +1,4 @@ +{ + "name": "p6", + "version": "1.0.0" +} diff --git a/tsdoc-config/src/__tests__/assets/p6/tsdoc-config.json b/tsdoc-config/src/__tests__/assets/p6/tsdoc-config.json new file mode 100644 index 00000000..d8655d26 --- /dev/null +++ b/tsdoc-config/src/__tests__/assets/p6/tsdoc-config.json @@ -0,0 +1,13 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json", + "extends": [ + "./base1/tsdoc-config.json", + "./base2/tsdoc-config.json" + ], + "tagDefinitions": [ + { + "tagName": "@root", + "syntaxKind": "modifier" + } + ] +} From 156311854482354c366f2985f0cb8a81945e3b1e Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Fri, 15 Nov 2019 02:06:46 -0800 Subject: [PATCH 09/20] Implement applyToParserConfiguration() --- tsdoc-config/src/TSDocConfigFile.ts | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/tsdoc-config/src/TSDocConfigFile.ts b/tsdoc-config/src/TSDocConfigFile.ts index db6c6a9e..3f07ee7c 100644 --- a/tsdoc-config/src/TSDocConfigFile.ts +++ b/tsdoc-config/src/TSDocConfigFile.ts @@ -1,4 +1,8 @@ -import { TSDocTagDefinition, TSDocTagSyntaxKind } from '@microsoft/tsdoc'; +import { + TSDocTagDefinition, + TSDocTagSyntaxKind, + TSDocConfiguration +} from '@microsoft/tsdoc'; import * as fs from 'fs'; import * as path from 'path'; import * as Ajv from 'ajv'; @@ -122,4 +126,21 @@ export class TSDocConfigFile { public addExtendsFile(otherFile: TSDocConfigFile): void { this._extendsFiles.push(otherFile); } + + /** + * Applies the settings from this config file to a TSDoc parser configuration. + * Any `extendsFile` settings will also applied. + */ + public applyToParserConfiguration(configuration: TSDocConfiguration): void { + // First apply the base config files + for (const extendsFile of this.extendsFiles) { + extendsFile.applyToParserConfiguration(configuration); + } + + // The apply this one + for (const tagDefinition of this.tagDefinitions) { + configuration.addTagDefinition(tagDefinition); + configuration.setSupportForTag(tagDefinition, true); + } + } } From 4e71b249e7099731c7965f11316fdad326d72304 Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Sat, 16 Nov 2019 10:38:55 -0800 Subject: [PATCH 10/20] Redesign API based on recent discussion --- tsdoc-config/src/ConfigLoader.ts | 111 --------------- tsdoc-config/src/TSDocConfigFile.ts | 90 ++++++++++-- ...Loader.test.ts => TSDocConfigFile.test.ts} | 133 +++++++++--------- .../assets/p1/folder/tsdoc-config.json | 3 - .../src/__tests__/assets/p1/package.json | 5 - .../src/__tests__/assets/p1/tsconfig.json | 2 + .../tsdoc-config.json => p1/tsdocconfig.json} | 2 +- .../src/__tests__/assets/p2/folder/index.d.ts | 1 - .../src/__tests__/assets/p2/package.json | 5 - .../src/__tests__/assets/p2/tsconfig.json | 2 + .../tsdoc-config.json => p2/tsdocconfig.json} | 2 +- .../base1/tsdocconfig-base1.json} | 2 +- .../base2/tsdocconfig-base2.json} | 2 +- .../src/__tests__/assets/p3/folder/index.js | 1 - .../src/__tests__/assets/p3/package.json | 5 - .../src/__tests__/assets/p3/tsconfig.json | 2 + .../src/__tests__/assets/p3/tsdocconfig.json | 13 ++ .../example-lib/dist/tsdocconfig-example.json | 9 ++ .../node_modules/example-lib}/package.json | 2 +- .../src/__tests__/assets/p4/package.json | 5 +- .../src/__tests__/assets/p4/tsconfig.json | 2 + .../src/__tests__/assets/p4/tsdoc-config.json | 3 - .../tsdoc-config.json => p4/tsdocconfig.json} | 5 +- .../src/__tests__/assets/p5/tsdoc-config.json | 20 --- .../src/__tests__/assets/p6/package.json | 4 - tsdoc-config/src/index.ts | 1 - tsdoc/.npmignore | 2 + .../schemas/tsdocconfig.schema.json | 0 28 files changed, 185 insertions(+), 249 deletions(-) delete mode 100644 tsdoc-config/src/ConfigLoader.ts rename tsdoc-config/src/__tests__/{ConfigLoader.test.ts => TSDocConfigFile.test.ts} (50%) delete mode 100644 tsdoc-config/src/__tests__/assets/p1/folder/tsdoc-config.json delete mode 100644 tsdoc-config/src/__tests__/assets/p1/package.json create mode 100644 tsdoc-config/src/__tests__/assets/p1/tsconfig.json rename tsdoc-config/src/__tests__/assets/{p2/folder/tsdoc-config.json => p1/tsdocconfig.json} (69%) delete mode 100644 tsdoc-config/src/__tests__/assets/p2/folder/index.d.ts delete mode 100644 tsdoc-config/src/__tests__/assets/p2/package.json create mode 100644 tsdoc-config/src/__tests__/assets/p2/tsconfig.json rename tsdoc-config/src/__tests__/assets/{p3/folder/tsdoc-config.json => p2/tsdocconfig.json} (69%) rename tsdoc-config/src/__tests__/assets/{p6/base1/tsdoc-config.json => p3/base1/tsdocconfig-base1.json} (84%) rename tsdoc-config/src/__tests__/assets/{p6/base2/tsdoc-config.json => p3/base2/tsdocconfig-base2.json} (84%) delete mode 100644 tsdoc-config/src/__tests__/assets/p3/folder/index.js delete mode 100644 tsdoc-config/src/__tests__/assets/p3/package.json create mode 100644 tsdoc-config/src/__tests__/assets/p3/tsconfig.json create mode 100644 tsdoc-config/src/__tests__/assets/p3/tsdocconfig.json create mode 100644 tsdoc-config/src/__tests__/assets/p4/node_modules/example-lib/dist/tsdocconfig-example.json rename tsdoc-config/src/__tests__/assets/{p5 => p4/node_modules/example-lib}/package.json (50%) create mode 100644 tsdoc-config/src/__tests__/assets/p4/tsconfig.json delete mode 100644 tsdoc-config/src/__tests__/assets/p4/tsdoc-config.json rename tsdoc-config/src/__tests__/assets/{p6/tsdoc-config.json => p4/tsdocconfig.json} (65%) delete mode 100644 tsdoc-config/src/__tests__/assets/p5/tsdoc-config.json delete mode 100644 tsdoc-config/src/__tests__/assets/p6/package.json rename tsdoc-config/src/schemas/tsdoc-config.schema.json => tsdoc/schemas/tsdocconfig.schema.json (100%) diff --git a/tsdoc-config/src/ConfigLoader.ts b/tsdoc-config/src/ConfigLoader.ts deleted file mode 100644 index 8854fcbf..00000000 --- a/tsdoc-config/src/ConfigLoader.ts +++ /dev/null @@ -1,111 +0,0 @@ -import * as fs from 'fs'; -import * as path from 'path'; -import * as resolve from 'resolve'; -import { TSDocConfigFile } from './TSDocConfigFile'; - -interface IPackageJson { - name?: string; - version?: string; - main?: string; - typings?: string; - types?: string; - tsdocConfig?: string; -} - -/** - * Use this class to load the `tsdoc-config.json` file. - * @public - */ -export class ConfigLoader { - public static readonly JSON_FILE_NAME: string = 'tsdoc-config.json'; - - private static _getExpectedPathForPackage(packageJson: IPackageJson): string { - // Rule 1: If package.json contains the field "tsdocConfig" then that takes precedence - // then that takes precedence. This convention will be rarely needed, since the later - // generally produce a good result. - if (packageJson.tsdocConfig) { - return packageJson.tsdocConfig; - } - - // Rule 2: If package.json contains a field such as "types" or "typings", then look - // for the file in that folder - // - // Rule 3: If package.json contains a field such as "main", then we would look - // for the file in that folder. - // - // Rule 4: Other wise look in the package.json folder, since the default entry point - // is './index.js' - - let entryPointPath: string = 'index.js'; - if (packageJson.types) { - entryPointPath = packageJson.types; - } else if (packageJson.typings) { - entryPointPath = packageJson.typings; - } else if (packageJson.main) { - entryPointPath = packageJson.main; - } - const entryPointFolder: string = path.dirname(entryPointPath); - - return path.join(entryPointFolder, ConfigLoader.JSON_FILE_NAME); - } - - /** - * Given a `packageFolder` path, probe for tsdoc-config.json and return the - * path to this file. - * @returns the absolute path, or `undefined` if not found - */ - private static _tryGetValidPath(packageFolder: string): string | undefined { - const packageJsonPath: string = path.join(packageFolder, 'package.json'); - if (!fs.existsSync(packageJsonPath)) { - throw new Error('package.json was not found under the path: ' + packageFolder); - } - const packageJsonContent: string = fs.readFileSync(packageJsonPath).toString(); - const packageJson: IPackageJson = JSON.parse(packageJsonContent); - const configFilePath: string = ConfigLoader._getExpectedPathForPackage(packageJson); - const configFileAbsolutePath: string = path.resolve(packageFolder, configFilePath); - - if (fs.existsSync(configFileAbsolutePath)) { - return configFileAbsolutePath; - } - - return undefined; - } - - private static _loadAndExtend(configFilePath: string, alreadyVisitedPaths: Set): TSDocConfigFile { - const hashKey: string = fs.realpathSync(configFilePath); - if (alreadyVisitedPaths.has(hashKey)) { - throw new Error('Circular reference encountered for "extends" field of ' + configFilePath); - } - alreadyVisitedPaths.add(hashKey); - - const configFile: TSDocConfigFile = TSDocConfigFile.loadFromFile(configFilePath); - - const configFileFolder: string = path.dirname(configFile.filePath); - - for (const extendsField of configFile.extendsPaths) { - const resolvedExtendsPath: string = resolve.sync(extendsField, { basedir: configFileFolder }); - if (!fs.existsSync(resolvedExtendsPath)) { - throw new Error('Unable to resolve "extends" field of ' + configFilePath); - } - - const baseConfigFile: TSDocConfigFile = ConfigLoader._loadAndExtend(resolvedExtendsPath, alreadyVisitedPaths); - configFile.addExtendsFile(baseConfigFile); - } - - return configFile; - } - - public static tryLoadFromPackageFolder(packageFolder: string): TSDocConfigFile | undefined { - - const rootConfigFilePath: string | undefined = ConfigLoader._tryGetValidPath(packageFolder); - - if (!rootConfigFilePath) { - // There is no tsdoc-config.json for this project - return undefined; - } - - const alreadyVisitedPaths: Set = new Set(); - - return ConfigLoader._loadAndExtend(rootConfigFilePath, alreadyVisitedPaths); - } -} diff --git a/tsdoc-config/src/TSDocConfigFile.ts b/tsdoc-config/src/TSDocConfigFile.ts index 3f07ee7c..ae5ff660 100644 --- a/tsdoc-config/src/TSDocConfigFile.ts +++ b/tsdoc-config/src/TSDocConfigFile.ts @@ -4,16 +4,16 @@ import { TSDocConfiguration } from '@microsoft/tsdoc'; import * as fs from 'fs'; +import * as resolve from 'resolve'; import * as path from 'path'; import * as Ajv from 'ajv'; const ajv: Ajv.Ajv = new Ajv({ verbose: true }); function initializeSchemaValidator(): Ajv.ValidateFunction { - const jsonSchemaContent: string = fs.readFileSync(path.join(__dirname, 'schemas/tsdoc-config.schema.json')) - .toString(); + const jsonSchemaPath: string = resolve.sync('@microsoft/tsdoc/schemas/tsdocconfig.schema.json', { basedir: __dirname }); + const jsonSchemaContent: string = fs.readFileSync(jsonSchemaPath).toString(); const jsonSchema: object = JSON.parse(jsonSchemaContent); - return ajv.compile(jsonSchema); } @@ -36,25 +36,30 @@ interface IConfigJson { } /** - * Represents an individual `tsdoc-config.json` file. + * Represents an individual `tsdocconfig.json` file. * * @public */ export class TSDocConfigFile { + public static readonly FILENAME: string = 'tsdocconfig.json'; + public static readonly CURRENT_SCHEMA_URL: string = 'https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json'; + private readonly _extendsFiles: TSDocConfigFile[] = []; /** - * The full path of the file. + * The full path of the file that was attempted to load. */ public readonly filePath: string; + public readonly fileNotFound: boolean = false; + /** - * The `$schema` field from the `tsdoc-config.json` file. + * The `$schema` field from the `tsdocconfig.json` file. */ public readonly tsdocSchema: string; /** - * The `extends` field from the `tsdoc-config.json` file. For the parsed file contents, + * The `extends` field from the `tsdocconfig.json` file. For the parsed file contents, * use the `extendsFiles` property instead. */ public readonly extendsPaths: ReadonlyArray; @@ -99,11 +104,11 @@ export class TSDocConfigFile { * * @remarks * - * This method does not process the `extends` field of `tsdoc-config.json`. - * For full functionality, including discovery of the file path, use the {@link ConfigLoader} + * This method does not process the `extends` field of `tsdocconfig.json`. + * For full functionality, including discovery of the file path, use the {@link TSDocConfigFileSet} * API instead. */ - public static loadFromFile(jsonFilePath: string): TSDocConfigFile { + private static _loadSingleFile(jsonFilePath: string): TSDocConfigFile { const fullJsonFilePath: string = path.resolve(jsonFilePath); const configJsonContent: string = fs.readFileSync(fullJsonFilePath).toString(); @@ -117,9 +122,70 @@ export class TSDocConfigFile { + '\nError in file: ' + jsonFilePath); } + if (configJson.$schema !== TSDocConfigFile.CURRENT_SCHEMA_URL) { + throw new Error('Expecting JSON "$schema" field to be ' + TSDocConfigFile.CURRENT_SCHEMA_URL + + '\nError in file: ' + jsonFilePath); + } + return new TSDocConfigFile(fullJsonFilePath, configJson); } + private static _findConfigPathForFolder(folderPath: string): string { + if (folderPath) { + let foundFolder: string = folderPath; + for (;;) { + const tsconfigFilePath: string = path.join(foundFolder, 'tsconfig.json'); + if (fs.existsSync(tsconfigFilePath)) { + // Success + return path.join(foundFolder, TSDocConfigFile.FILENAME); + } + + const previousFolder: string = foundFolder; + foundFolder = path.dirname(foundFolder); + + if (!foundFolder || foundFolder === previousFolder) { + // Failed + break; + } + } + } + return ''; + } + + private static _loadWithExtends(configFilePath: string, alreadyVisitedPaths: Set): TSDocConfigFile { + const hashKey: string = fs.realpathSync(configFilePath); + if (alreadyVisitedPaths.has(hashKey)) { + throw new Error('Circular reference encountered for "extends" field of ' + configFilePath); + } + alreadyVisitedPaths.add(hashKey); + + const configFile: TSDocConfigFile = TSDocConfigFile._loadSingleFile(configFilePath); + + const configFileFolder: string = path.dirname(configFile.filePath); + + for (const extendsField of configFile.extendsPaths) { + const resolvedExtendsPath: string = resolve.sync(extendsField, { basedir: configFileFolder }); + if (!fs.existsSync(resolvedExtendsPath)) { + throw new Error('Unable to resolve "extends" field of ' + configFilePath); + } + + const baseConfigFile: TSDocConfigFile = TSDocConfigFile._loadWithExtends(resolvedExtendsPath, alreadyVisitedPaths); + configFile.addExtendsFile(baseConfigFile); + } + + return configFile; + } + + /** + * For the given folder, discover the relevant tsdocconfig.json files (if any), and load them. + * @param folderPath - the path to a folder where the search should start + */ + public static loadForFolder(folderPath: string): TSDocConfigFile { + const rootConfigPath: string = TSDocConfigFile._findConfigPathForFolder(folderPath); + const alreadyVisitedPaths: Set = new Set(); + return TSDocConfigFile._loadWithExtends(rootConfigPath, alreadyVisitedPaths); + } + /** * Adds an item to `TSDocConfigFile.extendsFiles`. */ @@ -131,10 +197,10 @@ export class TSDocConfigFile { * Applies the settings from this config file to a TSDoc parser configuration. * Any `extendsFile` settings will also applied. */ - public applyToParserConfiguration(configuration: TSDocConfiguration): void { + public configureParser(configuration: TSDocConfiguration): void { // First apply the base config files for (const extendsFile of this.extendsFiles) { - extendsFile.applyToParserConfiguration(configuration); + extendsFile.configureParser(configuration); } // The apply this one diff --git a/tsdoc-config/src/__tests__/ConfigLoader.test.ts b/tsdoc-config/src/__tests__/TSDocConfigFile.test.ts similarity index 50% rename from tsdoc-config/src/__tests__/ConfigLoader.test.ts rename to tsdoc-config/src/__tests__/TSDocConfigFile.test.ts index c548e7b0..7d914ac3 100644 --- a/tsdoc-config/src/__tests__/ConfigLoader.test.ts +++ b/tsdoc-config/src/__tests__/TSDocConfigFile.test.ts @@ -1,7 +1,6 @@ import * as path from 'path'; import { TSDocConfigFile } from '../TSDocConfigFile'; -import { ConfigLoader } from '../ConfigLoader'; function getRelativePath(testPath: string): string { return path @@ -27,81 +26,40 @@ expect.addSnapshotSerializer({ } }); +function testLoadingFolder(assetPath: string): TSDocConfigFile { + return TSDocConfigFile.loadForFolder(path.join(__dirname, assetPath)); +} + test('Load p1', () => { - const configFile: TSDocConfigFile | undefined = ConfigLoader.tryLoadFromPackageFolder( - path.join(__dirname, 'assets/p1') - ); - expect(configFile).toBeDefined(); - expect(getRelativePath(configFile!.filePath)).toEqual('assets/p1/folder/tsdoc-config.json'); + expect(testLoadingFolder('assets/p1')).toMatchInlineSnapshot(` + Object { + "extendsFiles": Array [], + "extendsPaths": Array [], + "filePath": "assets/p1/tsdocconfig.json", + "tagDefinitions": Array [], + "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", + } + `); }); test('Load p2', () => { - const configFile: TSDocConfigFile | undefined = ConfigLoader.tryLoadFromPackageFolder( - path.join(__dirname, 'assets/p2') - ); - expect(configFile).toBeDefined(); - expect(getRelativePath(configFile!.filePath)).toEqual('assets/p2/folder/tsdoc-config.json'); -}); -test('Load p3', () => { - const configFile: TSDocConfigFile | undefined = ConfigLoader.tryLoadFromPackageFolder( - path.join(__dirname, 'assets/p3') - ); - expect(configFile).toBeDefined(); - expect(getRelativePath(configFile!.filePath)).toEqual('assets/p3/folder/tsdoc-config.json'); -}); -test('Load p4', () => { - const configFile: TSDocConfigFile | undefined = ConfigLoader.tryLoadFromPackageFolder( - path.join(__dirname, 'assets/p4') - ); - expect(configFile).toBeDefined(); - expect(getRelativePath(configFile!.filePath)).toEqual('assets/p4/tsdoc-config.json'); -}); -test('Load p5', () => { - const configFile: TSDocConfigFile | undefined = ConfigLoader.tryLoadFromPackageFolder( - path.join(__dirname, 'assets/p5') - ); - expect(configFile).toMatchInlineSnapshot(` + expect(testLoadingFolder('assets/p2')).toMatchInlineSnapshot(` Object { "extendsFiles": Array [], "extendsPaths": Array [], - "filePath": "assets/p5/tsdoc-config.json", - "tagDefinitions": Array [ - TSDocTagDefinition { - "allowMultiple": true, - "standardization": "None", - "syntaxKind": 0, - "tagName": "@myInlineTag", - "tagNameWithUpperCase": "@MYINLINETAG", - }, - TSDocTagDefinition { - "allowMultiple": false, - "standardization": "None", - "syntaxKind": 1, - "tagName": "@myBlockTag", - "tagNameWithUpperCase": "@MYBLOCKTAG", - }, - TSDocTagDefinition { - "allowMultiple": false, - "standardization": "None", - "syntaxKind": 2, - "tagName": "@myModifierTag", - "tagNameWithUpperCase": "@MYMODIFIERTAG", - }, - ], - "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json", + "filePath": "assets/p2/tsdocconfig.json", + "tagDefinitions": Array [], + "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", } `); }); -test('Load p6', () => { - const configFile: TSDocConfigFile | undefined = ConfigLoader.tryLoadFromPackageFolder( - path.join(__dirname, 'assets/p6') - ); - expect(configFile).toMatchInlineSnapshot(` +test('Load p3', () => { + expect(testLoadingFolder('assets/p3')).toMatchInlineSnapshot(` Object { "extendsFiles": Array [ Object { "extendsFiles": Array [], "extendsPaths": Array [], - "filePath": "assets/p6/base1/tsdoc-config.json", + "filePath": "assets/p3/base1/tsdocconfig-base1.json", "tagDefinitions": Array [ TSDocTagDefinition { "allowMultiple": false, @@ -111,12 +69,12 @@ test('Load p6', () => { "tagNameWithUpperCase": "@BASE1", }, ], - "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json", + "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", }, Object { "extendsFiles": Array [], "extendsPaths": Array [], - "filePath": "assets/p6/base2/tsdoc-config.json", + "filePath": "assets/p3/base2/tsdocconfig-base2.json", "tagDefinitions": Array [ TSDocTagDefinition { "allowMultiple": false, @@ -126,14 +84,51 @@ test('Load p6', () => { "tagNameWithUpperCase": "@BASE2", }, ], - "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json", + "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", + }, + ], + "extendsPaths": Array [ + "./base1/tsdocconfig-base1.json", + "./base2/tsdocconfig-base2.json", + ], + "filePath": "assets/p3/tsdocconfig.json", + "tagDefinitions": Array [ + TSDocTagDefinition { + "allowMultiple": false, + "standardization": "None", + "syntaxKind": 2, + "tagName": "@root", + "tagNameWithUpperCase": "@ROOT", + }, + ], + "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", + } + `); +}); +test('Load p4', () => { + expect(testLoadingFolder('assets/p4')).toMatchInlineSnapshot(` + Object { + "extendsFiles": Array [ + Object { + "extendsFiles": Array [], + "extendsPaths": Array [], + "filePath": "assets/p4/node_modules/example-lib/dist/tsdocconfig-example.json", + "tagDefinitions": Array [ + TSDocTagDefinition { + "allowMultiple": false, + "standardization": "None", + "syntaxKind": 2, + "tagName": "@example", + "tagNameWithUpperCase": "@EXAMPLE", + }, + ], + "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", }, ], "extendsPaths": Array [ - "./base1/tsdoc-config.json", - "./base2/tsdoc-config.json", + "example-lib/dist/tsdocconfig-example.json", ], - "filePath": "assets/p6/tsdoc-config.json", + "filePath": "assets/p4/tsdocconfig.json", "tagDefinitions": Array [ TSDocTagDefinition { "allowMultiple": false, @@ -143,7 +138,7 @@ test('Load p6', () => { "tagNameWithUpperCase": "@ROOT", }, ], - "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json", + "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", } `); }); diff --git a/tsdoc-config/src/__tests__/assets/p1/folder/tsdoc-config.json b/tsdoc-config/src/__tests__/assets/p1/folder/tsdoc-config.json deleted file mode 100644 index 244bc3a6..00000000 --- a/tsdoc-config/src/__tests__/assets/p1/folder/tsdoc-config.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json" -} diff --git a/tsdoc-config/src/__tests__/assets/p1/package.json b/tsdoc-config/src/__tests__/assets/p1/package.json deleted file mode 100644 index 64901a8a..00000000 --- a/tsdoc-config/src/__tests__/assets/p1/package.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "name": "p1", - "version": "1.0.0", - "tsdocConfig": "./folder/tsdoc-config.json" -} diff --git a/tsdoc-config/src/__tests__/assets/p1/tsconfig.json b/tsdoc-config/src/__tests__/assets/p1/tsconfig.json new file mode 100644 index 00000000..2c63c085 --- /dev/null +++ b/tsdoc-config/src/__tests__/assets/p1/tsconfig.json @@ -0,0 +1,2 @@ +{ +} diff --git a/tsdoc-config/src/__tests__/assets/p2/folder/tsdoc-config.json b/tsdoc-config/src/__tests__/assets/p1/tsdocconfig.json similarity index 69% rename from tsdoc-config/src/__tests__/assets/p2/folder/tsdoc-config.json rename to tsdoc-config/src/__tests__/assets/p1/tsdocconfig.json index 244bc3a6..2c333f97 100644 --- a/tsdoc-config/src/__tests__/assets/p2/folder/tsdoc-config.json +++ b/tsdoc-config/src/__tests__/assets/p1/tsdocconfig.json @@ -1,3 +1,3 @@ { - "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json" + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json" } diff --git a/tsdoc-config/src/__tests__/assets/p2/folder/index.d.ts b/tsdoc-config/src/__tests__/assets/p2/folder/index.d.ts deleted file mode 100644 index 8b1a3937..00000000 --- a/tsdoc-config/src/__tests__/assets/p2/folder/index.d.ts +++ /dev/null @@ -1 +0,0 @@ -// empty diff --git a/tsdoc-config/src/__tests__/assets/p2/package.json b/tsdoc-config/src/__tests__/assets/p2/package.json deleted file mode 100644 index 4267e1e5..00000000 --- a/tsdoc-config/src/__tests__/assets/p2/package.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "name": "p2", - "version": "1.0.0", - "typings": "./folder/index.d.ts" -} \ No newline at end of file diff --git a/tsdoc-config/src/__tests__/assets/p2/tsconfig.json b/tsdoc-config/src/__tests__/assets/p2/tsconfig.json new file mode 100644 index 00000000..2c63c085 --- /dev/null +++ b/tsdoc-config/src/__tests__/assets/p2/tsconfig.json @@ -0,0 +1,2 @@ +{ +} diff --git a/tsdoc-config/src/__tests__/assets/p3/folder/tsdoc-config.json b/tsdoc-config/src/__tests__/assets/p2/tsdocconfig.json similarity index 69% rename from tsdoc-config/src/__tests__/assets/p3/folder/tsdoc-config.json rename to tsdoc-config/src/__tests__/assets/p2/tsdocconfig.json index 244bc3a6..2c333f97 100644 --- a/tsdoc-config/src/__tests__/assets/p3/folder/tsdoc-config.json +++ b/tsdoc-config/src/__tests__/assets/p2/tsdocconfig.json @@ -1,3 +1,3 @@ { - "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json" + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json" } diff --git a/tsdoc-config/src/__tests__/assets/p6/base1/tsdoc-config.json b/tsdoc-config/src/__tests__/assets/p3/base1/tsdocconfig-base1.json similarity index 84% rename from tsdoc-config/src/__tests__/assets/p6/base1/tsdoc-config.json rename to tsdoc-config/src/__tests__/assets/p3/base1/tsdocconfig-base1.json index fc433ac6..9860f535 100644 --- a/tsdoc-config/src/__tests__/assets/p6/base1/tsdoc-config.json +++ b/tsdoc-config/src/__tests__/assets/p3/base1/tsdocconfig-base1.json @@ -1,5 +1,5 @@ { - "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json", + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", "tagDefinitions": [ { "tagName": "@base1", diff --git a/tsdoc-config/src/__tests__/assets/p6/base2/tsdoc-config.json b/tsdoc-config/src/__tests__/assets/p3/base2/tsdocconfig-base2.json similarity index 84% rename from tsdoc-config/src/__tests__/assets/p6/base2/tsdoc-config.json rename to tsdoc-config/src/__tests__/assets/p3/base2/tsdocconfig-base2.json index 9ba3e523..6156064f 100644 --- a/tsdoc-config/src/__tests__/assets/p6/base2/tsdoc-config.json +++ b/tsdoc-config/src/__tests__/assets/p3/base2/tsdocconfig-base2.json @@ -1,5 +1,5 @@ { - "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json", + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", "tagDefinitions": [ { "tagName": "@base2", diff --git a/tsdoc-config/src/__tests__/assets/p3/folder/index.js b/tsdoc-config/src/__tests__/assets/p3/folder/index.js deleted file mode 100644 index 8b1a3937..00000000 --- a/tsdoc-config/src/__tests__/assets/p3/folder/index.js +++ /dev/null @@ -1 +0,0 @@ -// empty diff --git a/tsdoc-config/src/__tests__/assets/p3/package.json b/tsdoc-config/src/__tests__/assets/p3/package.json deleted file mode 100644 index 1d960b8e..00000000 --- a/tsdoc-config/src/__tests__/assets/p3/package.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "name": "p3", - "version": "1.0.0", - "main": "./folder/index.js" -} diff --git a/tsdoc-config/src/__tests__/assets/p3/tsconfig.json b/tsdoc-config/src/__tests__/assets/p3/tsconfig.json new file mode 100644 index 00000000..2c63c085 --- /dev/null +++ b/tsdoc-config/src/__tests__/assets/p3/tsconfig.json @@ -0,0 +1,2 @@ +{ +} diff --git a/tsdoc-config/src/__tests__/assets/p3/tsdocconfig.json b/tsdoc-config/src/__tests__/assets/p3/tsdocconfig.json new file mode 100644 index 00000000..e0c0fd9a --- /dev/null +++ b/tsdoc-config/src/__tests__/assets/p3/tsdocconfig.json @@ -0,0 +1,13 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", + "extends": [ + "./base1/tsdocconfig-base1.json", + "./base2/tsdocconfig-base2.json" + ], + "tagDefinitions": [ + { + "tagName": "@root", + "syntaxKind": "modifier" + } + ] +} diff --git a/tsdoc-config/src/__tests__/assets/p4/node_modules/example-lib/dist/tsdocconfig-example.json b/tsdoc-config/src/__tests__/assets/p4/node_modules/example-lib/dist/tsdocconfig-example.json new file mode 100644 index 00000000..460126fb --- /dev/null +++ b/tsdoc-config/src/__tests__/assets/p4/node_modules/example-lib/dist/tsdocconfig-example.json @@ -0,0 +1,9 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", + "tagDefinitions": [ + { + "tagName": "@example", + "syntaxKind": "modifier" + } + ] +} diff --git a/tsdoc-config/src/__tests__/assets/p5/package.json b/tsdoc-config/src/__tests__/assets/p4/node_modules/example-lib/package.json similarity index 50% rename from tsdoc-config/src/__tests__/assets/p5/package.json rename to tsdoc-config/src/__tests__/assets/p4/node_modules/example-lib/package.json index c168e58f..a8922fbb 100644 --- a/tsdoc-config/src/__tests__/assets/p5/package.json +++ b/tsdoc-config/src/__tests__/assets/p4/node_modules/example-lib/package.json @@ -1,4 +1,4 @@ { - "name": "p5", + "name": "example-lib", "version": "1.0.0" } diff --git a/tsdoc-config/src/__tests__/assets/p4/package.json b/tsdoc-config/src/__tests__/assets/p4/package.json index 42d069b0..bcbfb778 100644 --- a/tsdoc-config/src/__tests__/assets/p4/package.json +++ b/tsdoc-config/src/__tests__/assets/p4/package.json @@ -1,4 +1,7 @@ { "name": "p4", - "version": "1.0.0" + "version": "1.0.0", + "dependencies": { + "example-lib": "1.0.0" + } } diff --git a/tsdoc-config/src/__tests__/assets/p4/tsconfig.json b/tsdoc-config/src/__tests__/assets/p4/tsconfig.json new file mode 100644 index 00000000..2c63c085 --- /dev/null +++ b/tsdoc-config/src/__tests__/assets/p4/tsconfig.json @@ -0,0 +1,2 @@ +{ +} diff --git a/tsdoc-config/src/__tests__/assets/p4/tsdoc-config.json b/tsdoc-config/src/__tests__/assets/p4/tsdoc-config.json deleted file mode 100644 index 244bc3a6..00000000 --- a/tsdoc-config/src/__tests__/assets/p4/tsdoc-config.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json" -} diff --git a/tsdoc-config/src/__tests__/assets/p6/tsdoc-config.json b/tsdoc-config/src/__tests__/assets/p4/tsdocconfig.json similarity index 65% rename from tsdoc-config/src/__tests__/assets/p6/tsdoc-config.json rename to tsdoc-config/src/__tests__/assets/p4/tsdocconfig.json index d8655d26..06239971 100644 --- a/tsdoc-config/src/__tests__/assets/p6/tsdoc-config.json +++ b/tsdoc-config/src/__tests__/assets/p4/tsdocconfig.json @@ -1,8 +1,7 @@ { - "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json", + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", "extends": [ - "./base1/tsdoc-config.json", - "./base2/tsdoc-config.json" + "example-lib/dist/tsdocconfig-example.json" ], "tagDefinitions": [ { diff --git a/tsdoc-config/src/__tests__/assets/p5/tsdoc-config.json b/tsdoc-config/src/__tests__/assets/p5/tsdoc-config.json deleted file mode 100644 index c83d2c79..00000000 --- a/tsdoc-config/src/__tests__/assets/p5/tsdoc-config.json +++ /dev/null @@ -1,20 +0,0 @@ -{ - "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc-config.schema.json", - "extends": [], - "tagDefinitions": [ - { - "tagName": "@myInlineTag", - "syntaxKind": "inline", - "allowMultiple": true - }, - { - "tagName": "@myBlockTag", - "syntaxKind": "block" - }, - { - "tagName": "@myModifierTag", - "syntaxKind": "modifier", - "allowMultiple": false - } - ] -} diff --git a/tsdoc-config/src/__tests__/assets/p6/package.json b/tsdoc-config/src/__tests__/assets/p6/package.json deleted file mode 100644 index 0018f065..00000000 --- a/tsdoc-config/src/__tests__/assets/p6/package.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "name": "p6", - "version": "1.0.0" -} diff --git a/tsdoc-config/src/index.ts b/tsdoc-config/src/index.ts index 965232c5..7b0b16da 100644 --- a/tsdoc-config/src/index.ts +++ b/tsdoc-config/src/index.ts @@ -1,2 +1 @@ export { TSDocConfigFile } from './TSDocConfigFile'; -export { ConfigLoader } from './ConfigLoader'; diff --git a/tsdoc/.npmignore b/tsdoc/.npmignore index 859b06bb..6468dc4a 100644 --- a/tsdoc/.npmignore +++ b/tsdoc/.npmignore @@ -23,3 +23,5 @@ # ----------------------------- # (Add your exceptions here) + +!/schemas/** diff --git a/tsdoc-config/src/schemas/tsdoc-config.schema.json b/tsdoc/schemas/tsdocconfig.schema.json similarity index 100% rename from tsdoc-config/src/schemas/tsdoc-config.schema.json rename to tsdoc/schemas/tsdocconfig.schema.json From 3e6e6b04a07a675a4ea9bdf43ba7b49a861da6bb Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Sat, 16 Nov 2019 22:53:55 -0800 Subject: [PATCH 11/20] Update eslint-plugin to use tsdoc-config --- eslint-plugin/package.json | 3 ++- eslint-plugin/src/index.ts | 51 +++++++++++++++++++++++--------------- 2 files changed, 33 insertions(+), 21 deletions(-) diff --git a/eslint-plugin/package.json b/eslint-plugin/package.json index a08a4f1a..0407a720 100644 --- a/eslint-plugin/package.json +++ b/eslint-plugin/package.json @@ -26,7 +26,8 @@ "test": "node lib/tests/index.js" }, "dependencies": { - "@microsoft/tsdoc": "0.12.15" + "@microsoft/tsdoc": "0.12.15", + "@microsoft/tsdoc-config": "0.12.15" }, "devDependencies": { "@rushstack/eslint-config": "0.4.0", diff --git a/eslint-plugin/src/index.ts b/eslint-plugin/src/index.ts index 8602978e..0e126497 100644 --- a/eslint-plugin/src/index.ts +++ b/eslint-plugin/src/index.ts @@ -8,14 +8,17 @@ import { TSDocTagSyntaxKind, ParserContext } from "@microsoft/tsdoc"; +import { + TSDocConfigFile +} from '@microsoft/tsdoc-config'; import * as eslint from "eslint"; import * as ESTree from "estree"; -const messageIds: {[x: string]: string} = {}; +const tsdocMessageIds: {[x: string]: string} = {}; const defaultTSDocConfiguration: TSDocConfiguration = new TSDocConfiguration() defaultTSDocConfiguration.allTsdocMessageIds.forEach((messageId: string) => { - messageIds[messageId] = `${messageId}: {{ unformattedText }}`; + tsdocMessageIds[messageId] = `${messageId}: {{unformattedText}}`; }); interface IPlugin { @@ -28,7 +31,7 @@ const plugin: IPlugin = { // from the NPM package name, and then appending this string. "syntax": { meta: { - messages: messageIds, + messages: tsdocMessageIds, type: "problem", docs: { description: "Validates that TypeScript documentation comments conform to the TSDoc standard", @@ -41,24 +44,32 @@ const plugin: IPlugin = { create: (context: eslint.Rule.RuleContext) => { const tsdocConfiguration: TSDocConfiguration = new TSDocConfiguration(); - // Create a lax configuration that allows every standard tag regardless of standardization group - tsdocConfiguration.setSupportForTags(StandardTags.allDefinitions, true); + const sourceFilePath: string = context.getFilename(); + const tsdocConfigFile: TSDocConfigFile = TSDocConfigFile.loadForFolder(sourceFilePath); + + if (!tsdocConfigFile.fileNotFound) { + tsdocConfigFile.configureParser(tsdocConfiguration); + } else { + // If we weren't able to find a tsdoc-config.json file, then by default we will use a lax configuration + // that allows every standard tag regardless of standardization group. + tsdocConfiguration.setSupportForTags(StandardTags.allDefinitions, true); - // Also add the three AEDoc tags - tsdocConfiguration.addTagDefinitions([ - new TSDocTagDefinition({ - tagName: '@betaDocumentation', - syntaxKind: TSDocTagSyntaxKind.ModifierTag - }), - new TSDocTagDefinition({ - tagName: '@internalRemarks', - syntaxKind: TSDocTagSyntaxKind.BlockTag - }), - new TSDocTagDefinition({ - tagName: '@preapproved', - syntaxKind: TSDocTagSyntaxKind.ModifierTag - }) - ], true); + // Also allow the three AEDoc tags. + tsdocConfiguration.addTagDefinitions([ + new TSDocTagDefinition({ + tagName: '@betaDocumentation', + syntaxKind: TSDocTagSyntaxKind.ModifierTag + }), + new TSDocTagDefinition({ + tagName: '@internalRemarks', + syntaxKind: TSDocTagSyntaxKind.BlockTag + }), + new TSDocTagDefinition({ + tagName: '@preapproved', + syntaxKind: TSDocTagSyntaxKind.ModifierTag + }) + ], true); + } const tsdocParser: TSDocParser = new TSDocParser(tsdocConfiguration); From 7494cde0185d7d4a8b756b82c1e66b337e07a37e Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Sat, 16 Nov 2019 22:06:23 -0800 Subject: [PATCH 12/20] Implement error reporting --- eslint-plugin/src/index.ts | 18 +- tsdoc-config/src/TSDocConfigFile.ts | 263 +++++++++++++----- .../src/__tests__/TSDocConfigFile.test.ts | 35 ++- .../src/__tests__/assets/p2/tsdocconfig.json | 3 - tsdoc/src/parser/TSDocMessageId.ts | 42 +++ 5 files changed, 281 insertions(+), 80 deletions(-) delete mode 100644 tsdoc-config/src/__tests__/assets/p2/tsdocconfig.json diff --git a/eslint-plugin/src/index.ts b/eslint-plugin/src/index.ts index 0e126497..e62f6f86 100644 --- a/eslint-plugin/src/index.ts +++ b/eslint-plugin/src/index.ts @@ -31,7 +31,10 @@ const plugin: IPlugin = { // from the NPM package name, and then appending this string. "syntax": { meta: { - messages: tsdocMessageIds, + messages: { + "error-loading-config-file": "Error loading TSDoc config file:\n{{details}}", + ...tsdocMessageIds + }, type: "problem", docs: { description: "Validates that TypeScript documentation comments conform to the TSDoc standard", @@ -48,6 +51,19 @@ const plugin: IPlugin = { const tsdocConfigFile: TSDocConfigFile = TSDocConfigFile.loadForFolder(sourceFilePath); if (!tsdocConfigFile.fileNotFound) { + if (tsdocConfigFile.hasErrors) { + context.report({ + loc: { + line: 1, + column: 1 + }, + messageId: "error-loading-config-file", + data: { + details: tsdocConfigFile.getErrorSummary() + } + }); + } + tsdocConfigFile.configureParser(tsdocConfiguration); } else { // If we weren't able to find a tsdoc-config.json file, then by default we will use a lax configuration diff --git a/tsdoc-config/src/TSDocConfigFile.ts b/tsdoc-config/src/TSDocConfigFile.ts index ae5ff660..9b966bce 100644 --- a/tsdoc-config/src/TSDocConfigFile.ts +++ b/tsdoc-config/src/TSDocConfigFile.ts @@ -1,7 +1,12 @@ import { TSDocTagDefinition, TSDocTagSyntaxKind, - TSDocConfiguration + TSDocConfiguration, + ParserMessageLog, + TSDocMessageId, + ParserMessage, + TextRange, + IParserMessageParameters } from '@microsoft/tsdoc'; import * as fs from 'fs'; import * as resolve from 'resolve'; @@ -42,35 +47,126 @@ interface IConfigJson { */ export class TSDocConfigFile { public static readonly FILENAME: string = 'tsdocconfig.json'; - public static readonly CURRENT_SCHEMA_URL: string = 'https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json'; + public static readonly CURRENT_SCHEMA_URL: string + = 'https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json'; - private readonly _extendsFiles: TSDocConfigFile[] = []; + /** + * A queryable log that reports warnings and error messages that occurred during parsing. + */ + public readonly log: ParserMessageLog; + + private readonly _extendsFiles: TSDocConfigFile[]; + private _filePath: string; + private _fileNotFound: boolean; + private _hasErrors: boolean; + private _tsdocSchema: string; + private readonly _extendsPaths: string[]; + private readonly _tagDefinitions: TSDocTagDefinition[]; + + private constructor() { + this.log = new ParserMessageLog(); + + this._extendsFiles = []; + this._filePath = ''; + this._fileNotFound = true; + this._hasErrors = false; + this._tsdocSchema = ''; + this._extendsPaths = []; + this._tagDefinitions= []; + } + + /** + * Other config files that this file extends from. + */ + public get extendsFiles(): ReadonlyArray { + return this._extendsFiles; + } /** * The full path of the file that was attempted to load. */ - public readonly filePath: string; + public get filePath(): string { + return this._filePath; + } - public readonly fileNotFound: boolean = false; + /** + * If true, then the TSDocConfigFile object contains an empty state, because the `tsdocconfig.json` file could + * not be found by the loader. + */ + public get fileNotFound(): boolean { + return this._fileNotFound; + } + + /** + * If true, then at least one error was encountered while loading this file or one of its "extends" files. + * + * @remarks + * You can use {@link TSDocConfigFile.getErrorSummary} to report these errors. + * + * The individual messages can be retrieved from the {@link TSDocConfigFile.log} property of each `TSDocConfigFile` + * object (including the {@link TSDocConfigFile.extendsFiles} tree). + */ + public get hasErrors(): boolean { + return this._hasErrors; + } /** * The `$schema` field from the `tsdocconfig.json` file. */ - public readonly tsdocSchema: string; + public get tsdocSchema(): string { + return this._tsdocSchema; + } /** * The `extends` field from the `tsdocconfig.json` file. For the parsed file contents, * use the `extendsFiles` property instead. */ - public readonly extendsPaths: ReadonlyArray; + public get extendsPaths(): ReadonlyArray { + return this._extendsPaths; + } + + public get tagDefinitions(): ReadonlyArray { + return this._tagDefinitions; + } - public readonly tagDefinitions: ReadonlyArray; + private _reportError(parserMessageParameters: IParserMessageParameters): void { + this.log.addMessage(new ParserMessage(parserMessageParameters)); + this._hasErrors = true; + } + + private _loadJsonFile(): void { + const configJsonContent: string = fs.readFileSync(this._filePath).toString(); - private constructor(filePath: string, configJson: IConfigJson) { - this.filePath = filePath; - this.tsdocSchema = configJson.$schema; - this.extendsPaths = configJson.extends || []; - const tagDefinitions: TSDocTagDefinition[] = []; + this._fileNotFound = false; + + const configJson: IConfigJson = JSON.parse(configJsonContent); + + if (configJson.$schema !== TSDocConfigFile.CURRENT_SCHEMA_URL) { + this._reportError({ + messageId: TSDocMessageId.ConfigFileUnsupportedSchema, + messageText: `Unsupported JSON "$schema" value; expecting "${TSDocConfigFile.CURRENT_SCHEMA_URL}"`, + textRange: TextRange.empty + }); + return; + } + + const success: boolean = tsdocSchemaValidator(configJson) as boolean; + + if (!success) { + const description: string = ajv.errorsText(tsdocSchemaValidator.errors); + + this._reportError({ + messageId: TSDocMessageId.ConfigFileSchemaError, + messageText: 'Error loading config file: ' + description, + textRange: TextRange.empty + }); + return; + } + + this._tsdocSchema = configJson.$schema; + if (configJson.extends) { + this._extendsPaths.push(...configJson.extends); + } for (const jsonTagDefinition of configJson.tagDefinitions || []) { let syntaxKind: TSDocTagSyntaxKind; @@ -82,52 +178,73 @@ export class TSDocConfigFile { // The JSON schema should have caught this error throw new Error('Unexpected tag kind'); } - tagDefinitions.push(new TSDocTagDefinition({ + this._tagDefinitions.push(new TSDocTagDefinition({ tagName: jsonTagDefinition.tagName, syntaxKind: syntaxKind, allowMultiple: jsonTagDefinition.allowMultiple })); } - - this.tagDefinitions = tagDefinitions; } - /** - * Other config files that this file extends from. - */ - public get extendsFiles(): ReadonlyArray { - return this._extendsFiles; - } + private _loadWithExtends(configFilePath: string, referencingConfigFile: TSDocConfigFile | undefined, + alreadyVisitedPaths: Set): void { - /** - * Loads the contents of a single JSON input file. - * - * @remarks - * - * This method does not process the `extends` field of `tsdocconfig.json`. - * For full functionality, including discovery of the file path, use the {@link TSDocConfigFileSet} - * API instead. - */ - private static _loadSingleFile(jsonFilePath: string): TSDocConfigFile { - const fullJsonFilePath: string = path.resolve(jsonFilePath); - - const configJsonContent: string = fs.readFileSync(fullJsonFilePath).toString(); + if (!configFilePath) { + this._reportError({ + messageId: TSDocMessageId.ConfigFileNotFound, + messageText: 'File not found', + textRange: TextRange.empty + }); + return; + } - const configJson: IConfigJson = JSON.parse(configJsonContent); - const success: boolean = tsdocSchemaValidator(configJson) as boolean; + this._filePath = path.resolve(configFilePath); - if (!success) { - const description: string = ajv.errorsText(tsdocSchemaValidator.errors); - throw new Error('Error parsing config file: ' + description - + '\nError in file: ' + jsonFilePath); + if (!fs.existsSync(this._filePath)) { + this._reportError({ + messageId: TSDocMessageId.ConfigFileNotFound, + messageText: 'File not found', + textRange: TextRange.empty + }); + return; } - if (configJson.$schema !== TSDocConfigFile.CURRENT_SCHEMA_URL) { - throw new Error('Expecting JSON "$schema" field to be ' + TSDocConfigFile.CURRENT_SCHEMA_URL - + '\nError in file: ' + jsonFilePath); + const hashKey: string = fs.realpathSync(this._filePath); + if (referencingConfigFile && alreadyVisitedPaths.has(hashKey)) { + this._reportError({ + messageId: TSDocMessageId.ConfigFileCyclicExtends, + messageText: `Circular reference encountered for "extends" field of "${referencingConfigFile.filePath}"`, + textRange: TextRange.empty + }); + return; } + alreadyVisitedPaths.add(hashKey); + + this._loadJsonFile(); + + const configFileFolder: string = path.dirname(this.filePath); - return new TSDocConfigFile(fullJsonFilePath, configJson); + for (const extendsField of this.extendsPaths) { + const resolvedExtendsPath: string = resolve.sync(extendsField, { basedir: configFileFolder }); + + const baseConfigFile: TSDocConfigFile = new TSDocConfigFile(); + + baseConfigFile._loadWithExtends(resolvedExtendsPath, this, alreadyVisitedPaths); + + if (baseConfigFile.fileNotFound) { + this._reportError({ + messageId: TSDocMessageId.ConfigFileUnresolvedExtends, + messageText: `Unable to resolve "extends" reference to "${extendsField}"`, + textRange: TextRange.empty + }); + } + + this._extendsFiles.push(baseConfigFile); + + if (baseConfigFile.hasErrors) { + this._hasErrors = true; + } + } } private static _findConfigPathForFolder(folderPath: string): string { @@ -152,45 +269,45 @@ export class TSDocConfigFile { return ''; } - private static _loadWithExtends(configFilePath: string, alreadyVisitedPaths: Set): TSDocConfigFile { - const hashKey: string = fs.realpathSync(configFilePath); - if (alreadyVisitedPaths.has(hashKey)) { - throw new Error('Circular reference encountered for "extends" field of ' + configFilePath); - } - alreadyVisitedPaths.add(hashKey); - - const configFile: TSDocConfigFile = TSDocConfigFile._loadSingleFile(configFilePath); - - const configFileFolder: string = path.dirname(configFile.filePath); - - for (const extendsField of configFile.extendsPaths) { - const resolvedExtendsPath: string = resolve.sync(extendsField, { basedir: configFileFolder }); - if (!fs.existsSync(resolvedExtendsPath)) { - throw new Error('Unable to resolve "extends" field of ' + configFilePath); - } - - const baseConfigFile: TSDocConfigFile = TSDocConfigFile._loadWithExtends(resolvedExtendsPath, alreadyVisitedPaths); - configFile.addExtendsFile(baseConfigFile); - } - - return configFile; - } - /** * For the given folder, discover the relevant tsdocconfig.json files (if any), and load them. * @param folderPath - the path to a folder where the search should start */ public static loadForFolder(folderPath: string): TSDocConfigFile { + const configFile: TSDocConfigFile = new TSDocConfigFile(); const rootConfigPath: string = TSDocConfigFile._findConfigPathForFolder(folderPath); + const alreadyVisitedPaths: Set = new Set(); - return TSDocConfigFile._loadWithExtends(rootConfigPath, alreadyVisitedPaths); + configFile._loadWithExtends(rootConfigPath, undefined, alreadyVisitedPaths); + + return configFile; } /** - * Adds an item to `TSDocConfigFile.extendsFiles`. + * Returns a report of any errors that occurred while attempting to load this file or any files + * referenced via the "extends" field. + * + * @remarks + * Use {@link TSDocConfigFile.hasErrors} to determine whether any errors occurred. */ - public addExtendsFile(otherFile: TSDocConfigFile): void { - this._extendsFiles.push(otherFile); + public getErrorSummary(): string { + if (!this._hasErrors) { + return 'No errors.'; + } + + let result: string = `Errors encountered for ${this.filePath}:\n`; + + for (const message of this.log.messages) { + result += ` ${message.text}\n`; + } + + for (const extendsFile of this.extendsFiles) { + if (extendsFile.hasErrors) { + result += extendsFile.getErrorSummary(); + } + } + + return result; } /** diff --git a/tsdoc-config/src/__tests__/TSDocConfigFile.test.ts b/tsdoc-config/src/__tests__/TSDocConfigFile.test.ts index 7d914ac3..f913cb44 100644 --- a/tsdoc-config/src/__tests__/TSDocConfigFile.test.ts +++ b/tsdoc-config/src/__tests__/TSDocConfigFile.test.ts @@ -15,13 +15,15 @@ expect.addSnapshotSerializer({ return value instanceof TSDocConfigFile; }, // eslint-disable-next-line @typescript-eslint/no-explicit-any - print(value: any, serialize: (value: any) => string, indent: (str: string) => string): any { + print(value: TSDocConfigFile, serialize: (value: any) => string, indent: (str: string) => string): any { return serialize({ tsdocSchema: value.tsdocSchema, filePath: getRelativePath(value.filePath), + fileNotFound: value.fileNotFound, extendsPaths: value.extendsPaths, extendsFiles: value.extendsFiles, - tagDefinitions: value.tagDefinitions + tagDefinitions: value.tagDefinitions, + messages: value.log.messages }); } }); @@ -35,7 +37,9 @@ test('Load p1', () => { Object { "extendsFiles": Array [], "extendsPaths": Array [], + "fileNotFound": false, "filePath": "assets/p1/tsdocconfig.json", + "messages": Array [], "tagDefinitions": Array [], "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", } @@ -46,9 +50,24 @@ test('Load p2', () => { Object { "extendsFiles": Array [], "extendsPaths": Array [], + "fileNotFound": true, "filePath": "assets/p2/tsdocconfig.json", + "messages": Array [ + ParserMessage { + "_text": undefined, + "docNode": undefined, + "messageId": "tsdoc-config-file-not-found", + "textRange": TextRange { + "buffer": "", + "end": 0, + "pos": 0, + }, + "tokenSequence": undefined, + "unformattedText": "File not found", + }, + ], "tagDefinitions": Array [], - "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", + "tsdocSchema": "", } `); }); @@ -59,7 +78,9 @@ test('Load p3', () => { Object { "extendsFiles": Array [], "extendsPaths": Array [], + "fileNotFound": false, "filePath": "assets/p3/base1/tsdocconfig-base1.json", + "messages": Array [], "tagDefinitions": Array [ TSDocTagDefinition { "allowMultiple": false, @@ -74,7 +95,9 @@ test('Load p3', () => { Object { "extendsFiles": Array [], "extendsPaths": Array [], + "fileNotFound": false, "filePath": "assets/p3/base2/tsdocconfig-base2.json", + "messages": Array [], "tagDefinitions": Array [ TSDocTagDefinition { "allowMultiple": false, @@ -91,7 +114,9 @@ test('Load p3', () => { "./base1/tsdocconfig-base1.json", "./base2/tsdocconfig-base2.json", ], + "fileNotFound": false, "filePath": "assets/p3/tsdocconfig.json", + "messages": Array [], "tagDefinitions": Array [ TSDocTagDefinition { "allowMultiple": false, @@ -112,7 +137,9 @@ test('Load p4', () => { Object { "extendsFiles": Array [], "extendsPaths": Array [], + "fileNotFound": false, "filePath": "assets/p4/node_modules/example-lib/dist/tsdocconfig-example.json", + "messages": Array [], "tagDefinitions": Array [ TSDocTagDefinition { "allowMultiple": false, @@ -128,7 +155,9 @@ test('Load p4', () => { "extendsPaths": Array [ "example-lib/dist/tsdocconfig-example.json", ], + "fileNotFound": false, "filePath": "assets/p4/tsdocconfig.json", + "messages": Array [], "tagDefinitions": Array [ TSDocTagDefinition { "allowMultiple": false, diff --git a/tsdoc-config/src/__tests__/assets/p2/tsdocconfig.json b/tsdoc-config/src/__tests__/assets/p2/tsdocconfig.json deleted file mode 100644 index 2c333f97..00000000 --- a/tsdoc-config/src/__tests__/assets/p2/tsdocconfig.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json" -} diff --git a/tsdoc/src/parser/TSDocMessageId.ts b/tsdoc/src/parser/TSDocMessageId.ts index 092cee9e..814a87dc 100644 --- a/tsdoc/src/parser/TSDocMessageId.ts +++ b/tsdoc/src/parser/TSDocMessageId.ts @@ -11,6 +11,42 @@ * @public */ export const enum TSDocMessageId { + /** + * File not found + * @remarks + * Reported by the `@microsoft/tsdoc-config` package when it failed to find a `tsdocconfig.json` file. + */ + ConfigFileNotFound = 'tsdoc-config-file-not-found', + + /** + * Unsupported JSON "$schema" value + * @remarks + * Reported by the `@microsoft/tsdoc-config` package when the file format is not supported. + */ + ConfigFileUnsupportedSchema = 'tsdoc-config-unsupported-schema', + + /** + * Error loading config file: ___ + * @remarks + * Reported by the `@microsoft/tsdoc-config` package when the config file doesn't conform to its schema. + */ + ConfigFileSchemaError = 'tsdoc-config-schema-error', + + /** + * Circular reference encountered for "extends" field of "___" + * @remarks + * Reported by the `@microsoft/tsdoc-config` package when the "extends" field creates a chain of references + * that causes a file to indirectly extend itself. + */ + ConfigFileCyclicExtends = 'tsdoc-config-cyclic-extends', + + /** + * Unable to resolve "extends" reference to "___" + * @remarks + * Reported by the `@microsoft/tsdoc-config` package when module resolution fails for the "extends" field. + */ + ConfigFileUnresolvedExtends = 'tsdoc-config-unresolved-extends', + /** * Expecting a `/**` comment. * Unexpected end of input. @@ -338,6 +374,12 @@ export const enum TSDocMessageId { // Exposed via TSDocConfiguration.allTsdocMessageIds() export const allTsdocMessageIds: string[] = [ + 'tsdoc-config-file-not-found', + 'tsdoc-config-unsupported-schema', + 'tsdoc-config-schema-error', + 'tsdoc-config-cyclic-extends', + 'tsdoc-config-unresolved-extends', + 'tsdoc-comment-not-found', 'tsdoc-comment-missing-opening-delimiter', 'tsdoc-comment-missing-closing-delimiter', From 60c12f9616ba6a54419f5b1acb8d5fc94aa2a7f3 Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Sat, 16 Nov 2019 22:10:39 -0800 Subject: [PATCH 13/20] _findConfigPathForFolder() now also stops if it reaches a folder containing package.json --- tsdoc-config/src/TSDocConfigFile.ts | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/tsdoc-config/src/TSDocConfigFile.ts b/tsdoc-config/src/TSDocConfigFile.ts index 9b966bce..1447cec2 100644 --- a/tsdoc-config/src/TSDocConfigFile.ts +++ b/tsdoc-config/src/TSDocConfigFile.ts @@ -251,9 +251,14 @@ export class TSDocConfigFile { if (folderPath) { let foundFolder: string = folderPath; for (;;) { - const tsconfigFilePath: string = path.join(foundFolder, 'tsconfig.json'); - if (fs.existsSync(tsconfigFilePath)) { - // Success + const tsconfigJsonPath: string = path.join(foundFolder, 'tsconfig.json'); + if (fs.existsSync(tsconfigJsonPath)) { + // Stop when we reach a folder containing tsconfig.json + return path.join(foundFolder, TSDocConfigFile.FILENAME); + } + const packageJsonPath: string = path.join(foundFolder, 'package.json'); + if (fs.existsSync(packageJsonPath)) { + // Stop when we reach a folder containing package.json; this avoids crawling out of the current package return path.join(foundFolder, TSDocConfigFile.FILENAME); } @@ -261,7 +266,7 @@ export class TSDocConfigFile { foundFolder = path.dirname(foundFolder); if (!foundFolder || foundFolder === previousFolder) { - // Failed + // Give up if we reach the filesystem root directory break; } } From 8df95e6c0882ff20e10a475255e85b00ace6a961 Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Sat, 16 Nov 2019 23:15:38 -0800 Subject: [PATCH 14/20] Some additional fixes --- eslint-plugin/src/index.ts | 41 ++++++------------- rush.json | 2 +- tsdoc-config/src/TSDocConfigFile.ts | 3 +- tsdoc/src/configuration/TSDocConfiguration.ts | 5 ++- 4 files changed, 19 insertions(+), 32 deletions(-) diff --git a/eslint-plugin/src/index.ts b/eslint-plugin/src/index.ts index e62f6f86..efe5b451 100644 --- a/eslint-plugin/src/index.ts +++ b/eslint-plugin/src/index.ts @@ -3,9 +3,6 @@ import { TSDocParser, TextRange, TSDocConfiguration, - StandardTags, - TSDocTagDefinition, - TSDocTagSyntaxKind, ParserContext } from "@microsoft/tsdoc"; import { @@ -33,6 +30,7 @@ const plugin: IPlugin = { meta: { messages: { "error-loading-config-file": "Error loading TSDoc config file:\n{{details}}", + "error-applying-config": "Error applying TSDoc configuration: {{details}}", ...tsdocMessageIds }, type: "problem", @@ -53,10 +51,7 @@ const plugin: IPlugin = { if (!tsdocConfigFile.fileNotFound) { if (tsdocConfigFile.hasErrors) { context.report({ - loc: { - line: 1, - column: 1 - }, + loc: { line: 1, column: 1 }, messageId: "error-loading-config-file", data: { details: tsdocConfigFile.getErrorSummary() @@ -64,27 +59,17 @@ const plugin: IPlugin = { }); } - tsdocConfigFile.configureParser(tsdocConfiguration); - } else { - // If we weren't able to find a tsdoc-config.json file, then by default we will use a lax configuration - // that allows every standard tag regardless of standardization group. - tsdocConfiguration.setSupportForTags(StandardTags.allDefinitions, true); - - // Also allow the three AEDoc tags. - tsdocConfiguration.addTagDefinitions([ - new TSDocTagDefinition({ - tagName: '@betaDocumentation', - syntaxKind: TSDocTagSyntaxKind.ModifierTag - }), - new TSDocTagDefinition({ - tagName: '@internalRemarks', - syntaxKind: TSDocTagSyntaxKind.BlockTag - }), - new TSDocTagDefinition({ - tagName: '@preapproved', - syntaxKind: TSDocTagSyntaxKind.ModifierTag - }) - ], true); + try { + tsdocConfigFile.configureParser(tsdocConfiguration); + } catch (e) { + context.report({ + loc: { line: 1, column: 1 }, + messageId: "error-applying-config", + data: { + details: e.message + } + }); + } } const tsdocParser: TSDocParser = new TSDocParser(tsdocConfiguration); diff --git a/rush.json b/rush.json index b771afd9..7efcfe07 100644 --- a/rush.json +++ b/rush.json @@ -379,7 +379,7 @@ { "packageName": "@microsoft/tsdoc-config", "projectFolder": "tsdoc-config", - "shouldPublish": false + "shouldPublish": true }, { "packageName": "eslint-plugin-tsdoc", diff --git a/tsdoc-config/src/TSDocConfigFile.ts b/tsdoc-config/src/TSDocConfigFile.ts index 1447cec2..8a6bbdad 100644 --- a/tsdoc-config/src/TSDocConfigFile.ts +++ b/tsdoc-config/src/TSDocConfigFile.ts @@ -325,10 +325,9 @@ export class TSDocConfigFile { extendsFile.configureParser(configuration); } - // The apply this one + // Then apply this one for (const tagDefinition of this.tagDefinitions) { configuration.addTagDefinition(tagDefinition); - configuration.setSupportForTag(tagDefinition, true); } } } diff --git a/tsdoc/src/configuration/TSDocConfiguration.ts b/tsdoc/src/configuration/TSDocConfiguration.ts index 19d0a6cb..abd08a57 100644 --- a/tsdoc/src/configuration/TSDocConfiguration.ts +++ b/tsdoc/src/configuration/TSDocConfiguration.ts @@ -30,7 +30,10 @@ export class TSDocConfiguration { } /** - * The TSDoc block tag names that will be interpreted as modifier tags. + * The TSDoc tags that are defined in this configuration. + * + * @remarks + * The subset of "supported" tags is tracked by {@link TSDocConfiguration.supportedTagDefinitions}. */ public get tagDefinitions(): ReadonlyArray { return this._tagDefinitions; From f98668620c70382662eabaa87e8a44a30c6a2ebb Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Sat, 16 Nov 2019 23:28:09 -0800 Subject: [PATCH 15/20] rush change --- .../octogonz-tsdoc-config_2019-11-17-07-26.json | 11 +++++++++++ .../tsdoc/octogonz-tsdoc-config_2019-11-17-07-26.json | 11 +++++++++++ .../octogonz-tsdoc-config_2019-11-17-07-26.json | 11 +++++++++++ 3 files changed, 33 insertions(+) create mode 100644 common/changes/@microsoft/tsdoc-config/octogonz-tsdoc-config_2019-11-17-07-26.json create mode 100644 common/changes/@microsoft/tsdoc/octogonz-tsdoc-config_2019-11-17-07-26.json create mode 100644 common/changes/eslint-plugin-tsdoc/octogonz-tsdoc-config_2019-11-17-07-26.json diff --git a/common/changes/@microsoft/tsdoc-config/octogonz-tsdoc-config_2019-11-17-07-26.json b/common/changes/@microsoft/tsdoc-config/octogonz-tsdoc-config_2019-11-17-07-26.json new file mode 100644 index 00000000..27face1a --- /dev/null +++ b/common/changes/@microsoft/tsdoc-config/octogonz-tsdoc-config_2019-11-17-07-26.json @@ -0,0 +1,11 @@ +{ + "changes": [ + { + "packageName": "@microsoft/tsdoc-config", + "comment": "Initial release", + "type": "patch" + } + ], + "packageName": "@microsoft/tsdoc-config", + "email": "4673363+octogonz@users.noreply.github.com" +} \ No newline at end of file diff --git a/common/changes/@microsoft/tsdoc/octogonz-tsdoc-config_2019-11-17-07-26.json b/common/changes/@microsoft/tsdoc/octogonz-tsdoc-config_2019-11-17-07-26.json new file mode 100644 index 00000000..7dd06f1c --- /dev/null +++ b/common/changes/@microsoft/tsdoc/octogonz-tsdoc-config_2019-11-17-07-26.json @@ -0,0 +1,11 @@ +{ + "changes": [ + { + "packageName": "@microsoft/tsdoc", + "comment": "Add some new TSDocMessageId definitions used by @microsoft/tsdoc-config", + "type": "patch" + } + ], + "packageName": "@microsoft/tsdoc", + "email": "4673363+octogonz@users.noreply.github.com" +} \ No newline at end of file diff --git a/common/changes/eslint-plugin-tsdoc/octogonz-tsdoc-config_2019-11-17-07-26.json b/common/changes/eslint-plugin-tsdoc/octogonz-tsdoc-config_2019-11-17-07-26.json new file mode 100644 index 00000000..f6fd43d2 --- /dev/null +++ b/common/changes/eslint-plugin-tsdoc/octogonz-tsdoc-config_2019-11-17-07-26.json @@ -0,0 +1,11 @@ +{ + "changes": [ + { + "packageName": "eslint-plugin-tsdoc", + "comment": "Add support for defining your own custom tags using tsdocconfig.json", + "type": "minor" + } + ], + "packageName": "eslint-plugin-tsdoc", + "email": "4673363+octogonz@users.noreply.github.com" +} \ No newline at end of file From b36691d59f3ad1fc2fd2752d6caeea165f545f34 Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Sun, 17 Nov 2019 00:16:00 -0800 Subject: [PATCH 16/20] Add NPM package documentation --- tsdoc-config/README.md | 85 +++++++++++++++++++++++++++ tsdoc-config/package.json | 2 +- tsdoc/README.md | 15 ++++- tsdoc/schemas/tsdocconfig.schema.json | 2 +- 4 files changed, 100 insertions(+), 4 deletions(-) create mode 100644 tsdoc-config/README.md diff --git a/tsdoc-config/README.md b/tsdoc-config/README.md new file mode 100644 index 00000000..daa06bc3 --- /dev/null +++ b/tsdoc-config/README.md @@ -0,0 +1,85 @@ +# @microsoft/tsdoc-config + +**TSDoc** is a proposal to standardize the doc comments used in [TypeScript](http://www.typescriptlang.org/) +source files. The main package [`@microsoft/tsdoc`](https://www.npmjs.com/package/@microsoft/tsdoc) implements +the TSDoc parser. The `@microsoft/tsdoc-config` package is an optional add-on for loading the **tsdocconfig.json** +file format that enables users to define custom TSDoc tags. (This functionality was moved to its own package +because it requires external dependencies such as NodeJS and `ajv`, whereas the main package is fully self-contained.) + +For more information about TSDoc, please visit the project website: + +https://github.com/microsoft/tsdoc + + +## Creating config files + +The **tsdocconfig.json** file is optional. When used, it is expected to be found in the same folder as +the **tsconfig.json** file for a project. The loader looks for it by walking upwards in the directory tree +from until it finds a folder containing **tsconfig.json** or **package.json**, and then it attempts to load +**tsdocconfig.json** from that location. + +The **tsdocconfig.json** file conforms to the [tsdocconfig.schema.json]( +https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json) JSON schema. It defines tags using +similar fields as the +[TSDocTagDefinition](https://github.com/microsoft/tsdoc/blob/master/tsdoc/src/configuration/TSDocTagDefinition.ts) +API used by `TSDocParser` from `@microsoft/tsdoc`. + +Here's a simple example: + +**tsdocconfig.json** +```js +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", + "tagDefinitions": [ + { + "tagName": "@myTag", + "syntaxKind": "modifier" + } + ] +} +``` + +If you want to define custom tags in one place and share them across multiple projects, the `extends` field specifies +a list of paths that will be mixed in with the current file: + +**tsdocconfig.json** +```js +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", + "extends": [ + "my-package/dist/tsdocconfig-base.json", + "./path/to/local/file/tsdocconfig-local.json" + ] +} +``` + +> NOTE: The `extends` paths are resolved using NodeJS module resolution, so local paths must being with `./` to avoid +> being interpreted as an NPM package name. + + +## API Usage + +The code sample below illustrates how to invoke the `@microsoft/tsdoc-config` API to load a +**tsdocconfig.json** file: + +```ts +import * as path from 'path'; +import { TSDocParser, TSDocConfiguration } from '@microsoft/tsdoc'; +import { TSDocConfigFile } from '@microsoft/tsdoc-config'; + +// Sample source file to be parsed +const mySourceFile: string = 'my-project/src/example.ts'; + +// Load the nearest config file, for example `my-project/tsdocconfig.json` +const tsdocConfigFile: TSDocConfigFile = TSDocConfigFile.loadForFolder(path.dirname(mySourceFile)); +if (tsdocConfigFile.hasErrors) { + // Report any errors + console.log(tsdocConfigFile.getErrorSummary()); +} + +// Use the TSDocConfigFile to configure the parser +const tsdocConfiguration: TSDocConfiguration = new TSDocConfiguration(); +tsdocConfigFile.configureParser(tsdocConfiguration); +const tsdocParser: TSDocParser = new TSDocParser(tsdocConfiguration); +``` + diff --git a/tsdoc-config/package.json b/tsdoc-config/package.json index f080d58f..01f07aba 100644 --- a/tsdoc-config/package.json +++ b/tsdoc-config/package.json @@ -1,7 +1,7 @@ { "name": "@microsoft/tsdoc-config", "version": "0.12.15", - "description": "A loader for the tsdoc-config.json file", + "description": "A loader for the tsdocconfig.json file", "keywords": [ "TypeScript", "documentation", diff --git a/tsdoc/README.md b/tsdoc/README.md index a74cd1f9..3a8224a9 100644 --- a/tsdoc/README.md +++ b/tsdoc/README.md @@ -2,7 +2,8 @@ This library is the reference implementation of a parser for the TSDoc syntax. Using this library is an easy way to ensure that your tool is 100% compatible with the standard. -### What is TSDoc? + +## What is TSDoc? **TSDoc** is a proposal to standardize the doc comments used in [TypeScript](http://www.typescriptlang.org/) source files. It allows different tools to extract content from comments without getting confused by each other's syntax. The **TSDoc** notation looks pretty familiar: @@ -30,8 +31,18 @@ export class Statistics { Check out the [TSDoc Playground](https://microsoft.github.io/tsdoc/) for a cool live demo of our parser! + +## API Usage + +The [api-demo](https://github.com/microsoft/tsdoc/tree/master/api-demo) folder on GitHub illustrates how +to invoke the TSDoc parser. + +A separate NPM package [`@microsoft/tsdoc-config`](https://www.npmjs.com/package/@microsoft/tsdoc) +is used for loading the **tsdocconfig.json** file. + + ## Get involved The **TSDoc** project is actively evolving. Please visit our GitHub project for the latest documentation, instructions for building/debugging the projects, and other resources: -https://github.com/Microsoft/tsdoc +https://github.com/microsoft/tsdoc diff --git a/tsdoc/schemas/tsdocconfig.schema.json b/tsdoc/schemas/tsdocconfig.schema.json index f6cc9df2..bfb9b425 100644 --- a/tsdoc/schemas/tsdocconfig.schema.json +++ b/tsdoc/schemas/tsdocconfig.schema.json @@ -9,7 +9,7 @@ }, "extends": { - "description": "Optionally specifies another JSON config files that this file extends from. This provides a way for standard settings to be shared across multiple projects.", + "description": "Optionally specifies one or more JSON config files that will be combined with this file. This provides a way for standard settings to be shared across multiple projects. Important: The \"extends\" paths are resolved using NodeJS module resolution, so a path to a local file MUST be prefixed with \"./\".", "type": "array", "items": { "type": "string" From 3ee0a50b838cfa03aebb54c2cd9ca7529f0fe911 Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Sun, 17 Nov 2019 00:24:38 -0800 Subject: [PATCH 17/20] Fix GitHub URL case --- playground/src/samples/hyperlinkSample.ts | 2 +- rush.json | 2 +- tsdoc-config/README.md | 2 +- tsdoc-config/package.json | 4 ++-- tsdoc/package.json | 4 ++-- tsdoc/src/details/StandardTags.ts | 6 +++--- 6 files changed, 10 insertions(+), 10 deletions(-) diff --git a/playground/src/samples/hyperlinkSample.ts b/playground/src/samples/hyperlinkSample.ts index a7f02eab..2418c28a 100644 --- a/playground/src/samples/hyperlinkSample.ts +++ b/playground/src/samples/hyperlinkSample.ts @@ -3,7 +3,7 @@ * * @remarks * - * Links can point to a URL: {@link https://github.com/Microsoft/tsdoc} + * Links can point to a URL: {@link https://github.com/microsoft/tsdoc} * * Links can point to an API item: {@link Button} * diff --git a/rush.json b/rush.json index 7efcfe07..42f191dd 100644 --- a/rush.json +++ b/rush.json @@ -216,7 +216,7 @@ * your PR branch, and in this situation "rush change" will also automatically invoke "git fetch" * to retrieve the latest activity for the remote master branch. */ - "url": "https://github.com/Microsoft/tsdoc.git" + "url": "https://github.com/microsoft/tsdoc.git" }, /** diff --git a/tsdoc-config/README.md b/tsdoc-config/README.md index daa06bc3..aefb3934 100644 --- a/tsdoc-config/README.md +++ b/tsdoc-config/README.md @@ -15,7 +15,7 @@ https://github.com/microsoft/tsdoc The **tsdocconfig.json** file is optional. When used, it is expected to be found in the same folder as the **tsconfig.json** file for a project. The loader looks for it by walking upwards in the directory tree -from until it finds a folder containing **tsconfig.json** or **package.json**, and then it attempts to load +until it finds a folder containing **tsconfig.json** or **package.json**, and then it attempts to load **tsdocconfig.json** from that location. The **tsdocconfig.json** file conforms to the [tsdocconfig.schema.json]( diff --git a/tsdoc-config/package.json b/tsdoc-config/package.json index 01f07aba..1e42e386 100644 --- a/tsdoc-config/package.json +++ b/tsdoc-config/package.json @@ -13,9 +13,9 @@ ], "repository": { "type": "git", - "url": "https://github.com/Microsoft/tsdoc" + "url": "https://github.com/microsoft/tsdoc" }, - "homepage": "https://github.com/Microsoft/tsdoc", + "homepage": "https://github.com/microsoft/tsdoc", "main": "lib/index.js", "typings": "lib/index.d.ts", "license": "MIT", diff --git a/tsdoc/package.json b/tsdoc/package.json index d6773d3f..22737786 100644 --- a/tsdoc/package.json +++ b/tsdoc/package.json @@ -13,9 +13,9 @@ ], "repository": { "type": "git", - "url": "https://github.com/Microsoft/tsdoc" + "url": "https://github.com/microsoft/tsdoc" }, - "homepage": "https://github.com/Microsoft/tsdoc", + "homepage": "https://github.com/microsoft/tsdoc", "main": "lib/index.js", "typings": "lib/index.d.ts", "license": "MIT", diff --git a/tsdoc/src/details/StandardTags.ts b/tsdoc/src/details/StandardTags.ts index b500c133..126839c7 100644 --- a/tsdoc/src/details/StandardTags.ts +++ b/tsdoc/src/details/StandardTags.ts @@ -125,7 +125,7 @@ export class StandardTags { * separate NPM package. * * TODO: The notation for API item references is still being standardized. See this issue: - * https://github.com/Microsoft/tsdoc/issues/9 + * https://github.com/microsoft/tsdoc/issues/9 */ public static readonly inheritDoc: TSDocTagDefinition = StandardTags._defineTag({ tagName: '@inheritDoc', @@ -156,7 +156,7 @@ export class StandardTags { * using a selector in the TSDoc declaration reference notation. * * TODO: The `{@label}` notation is still being standardized. See this issue: - * https://github.com/Microsoft/tsdoc/issues/9 + * https://github.com/microsoft/tsdoc/issues/9 */ public static readonly label: TSDocTagDefinition = StandardTags._defineTag({ tagName: '@label', @@ -172,7 +172,7 @@ export class StandardTags { * expressions for referencing API items. * * TODO: The `{@link}` notation is still being standardized. See this issue: - * https://github.com/Microsoft/tsdoc/issues/9 + * https://github.com/microsoft/tsdoc/issues/9 */ public static readonly link: TSDocTagDefinition = StandardTags._defineTag({ tagName: '@link', From 0fd677c5572241d33bc28b2783ff6ae1df5eeea2 Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Sun, 17 Nov 2019 10:44:47 -0800 Subject: [PATCH 18/20] Rename files --- tsdoc-config/src/__tests__/assets/.gitignore | 2 ++ .../src/__tests__/assets/p1/{tsdocconfig.json => tsdoc.json} | 0 .../p3/base1/{tsdocconfig-base1.json => tsdoc-base1.json} | 0 .../p3/base2/{tsdocconfig-base2.json => tsdoc-base2.json} | 0 .../src/__tests__/assets/p3/{tsdocconfig.json => tsdoc.json} | 0 .../dist/{tsdocconfig-example.json => tsdoc-example.json} | 0 .../src/__tests__/assets/p4/{tsdocconfig.json => tsdoc.json} | 0 tsdoc/schemas/{tsdocconfig.schema.json => tsdoc.schema.json} | 0 8 files changed, 2 insertions(+) create mode 100644 tsdoc-config/src/__tests__/assets/.gitignore rename tsdoc-config/src/__tests__/assets/p1/{tsdocconfig.json => tsdoc.json} (100%) rename tsdoc-config/src/__tests__/assets/p3/base1/{tsdocconfig-base1.json => tsdoc-base1.json} (100%) rename tsdoc-config/src/__tests__/assets/p3/base2/{tsdocconfig-base2.json => tsdoc-base2.json} (100%) rename tsdoc-config/src/__tests__/assets/p3/{tsdocconfig.json => tsdoc.json} (100%) rename tsdoc-config/src/__tests__/assets/p4/node_modules/example-lib/dist/{tsdocconfig-example.json => tsdoc-example.json} (100%) rename tsdoc-config/src/__tests__/assets/p4/{tsdocconfig.json => tsdoc.json} (100%) rename tsdoc/schemas/{tsdocconfig.schema.json => tsdoc.schema.json} (100%) diff --git a/tsdoc-config/src/__tests__/assets/.gitignore b/tsdoc-config/src/__tests__/assets/.gitignore new file mode 100644 index 00000000..66d3a7f5 --- /dev/null +++ b/tsdoc-config/src/__tests__/assets/.gitignore @@ -0,0 +1,2 @@ +!node_modules +!dist diff --git a/tsdoc-config/src/__tests__/assets/p1/tsdocconfig.json b/tsdoc-config/src/__tests__/assets/p1/tsdoc.json similarity index 100% rename from tsdoc-config/src/__tests__/assets/p1/tsdocconfig.json rename to tsdoc-config/src/__tests__/assets/p1/tsdoc.json diff --git a/tsdoc-config/src/__tests__/assets/p3/base1/tsdocconfig-base1.json b/tsdoc-config/src/__tests__/assets/p3/base1/tsdoc-base1.json similarity index 100% rename from tsdoc-config/src/__tests__/assets/p3/base1/tsdocconfig-base1.json rename to tsdoc-config/src/__tests__/assets/p3/base1/tsdoc-base1.json diff --git a/tsdoc-config/src/__tests__/assets/p3/base2/tsdocconfig-base2.json b/tsdoc-config/src/__tests__/assets/p3/base2/tsdoc-base2.json similarity index 100% rename from tsdoc-config/src/__tests__/assets/p3/base2/tsdocconfig-base2.json rename to tsdoc-config/src/__tests__/assets/p3/base2/tsdoc-base2.json diff --git a/tsdoc-config/src/__tests__/assets/p3/tsdocconfig.json b/tsdoc-config/src/__tests__/assets/p3/tsdoc.json similarity index 100% rename from tsdoc-config/src/__tests__/assets/p3/tsdocconfig.json rename to tsdoc-config/src/__tests__/assets/p3/tsdoc.json diff --git a/tsdoc-config/src/__tests__/assets/p4/node_modules/example-lib/dist/tsdocconfig-example.json b/tsdoc-config/src/__tests__/assets/p4/node_modules/example-lib/dist/tsdoc-example.json similarity index 100% rename from tsdoc-config/src/__tests__/assets/p4/node_modules/example-lib/dist/tsdocconfig-example.json rename to tsdoc-config/src/__tests__/assets/p4/node_modules/example-lib/dist/tsdoc-example.json diff --git a/tsdoc-config/src/__tests__/assets/p4/tsdocconfig.json b/tsdoc-config/src/__tests__/assets/p4/tsdoc.json similarity index 100% rename from tsdoc-config/src/__tests__/assets/p4/tsdocconfig.json rename to tsdoc-config/src/__tests__/assets/p4/tsdoc.json diff --git a/tsdoc/schemas/tsdocconfig.schema.json b/tsdoc/schemas/tsdoc.schema.json similarity index 100% rename from tsdoc/schemas/tsdocconfig.schema.json rename to tsdoc/schemas/tsdoc.schema.json From 4f46de12fc7abacd2c5089749d16671b3f2e96f4 Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Sun, 17 Nov 2019 10:45:37 -0800 Subject: [PATCH 19/20] Rename tsdocconfig.json --> tsdoc.json based on community vote: https://twitter.com/octogonz_/status/1195793782534393856 --- ...ctogonz-tsdoc-config_2019-11-17-07-26.json | 2 +- tsdoc-config/README.md | 26 +++++++-------- tsdoc-config/package.json | 2 +- tsdoc-config/src/TSDocConfigFile.ts | 16 +++++----- .../src/__tests__/TSDocConfigFile.test.ts | 32 +++++++++---------- .../src/__tests__/assets/p1/tsdoc.json | 2 +- .../assets/p3/base1/tsdoc-base1.json | 2 +- .../assets/p3/base2/tsdoc-base2.json | 2 +- .../src/__tests__/assets/p3/tsdoc.json | 6 ++-- .../src/__tests__/assets/p4/tsdoc.json | 4 +-- tsdoc/README.md | 2 +- tsdoc/src/parser/TSDocMessageId.ts | 2 +- 12 files changed, 49 insertions(+), 49 deletions(-) diff --git a/common/changes/eslint-plugin-tsdoc/octogonz-tsdoc-config_2019-11-17-07-26.json b/common/changes/eslint-plugin-tsdoc/octogonz-tsdoc-config_2019-11-17-07-26.json index f6fd43d2..f7cb12f5 100644 --- a/common/changes/eslint-plugin-tsdoc/octogonz-tsdoc-config_2019-11-17-07-26.json +++ b/common/changes/eslint-plugin-tsdoc/octogonz-tsdoc-config_2019-11-17-07-26.json @@ -2,7 +2,7 @@ "changes": [ { "packageName": "eslint-plugin-tsdoc", - "comment": "Add support for defining your own custom tags using tsdocconfig.json", + "comment": "Add support for defining your own custom tags using tsdoc.json", "type": "minor" } ], diff --git a/tsdoc-config/README.md b/tsdoc-config/README.md index aefb3934..6bd79224 100644 --- a/tsdoc-config/README.md +++ b/tsdoc-config/README.md @@ -2,7 +2,7 @@ **TSDoc** is a proposal to standardize the doc comments used in [TypeScript](http://www.typescriptlang.org/) source files. The main package [`@microsoft/tsdoc`](https://www.npmjs.com/package/@microsoft/tsdoc) implements -the TSDoc parser. The `@microsoft/tsdoc-config` package is an optional add-on for loading the **tsdocconfig.json** +the TSDoc parser. The `@microsoft/tsdoc-config` package is an optional add-on for loading the **tsdoc.json** file format that enables users to define custom TSDoc tags. (This functionality was moved to its own package because it requires external dependencies such as NodeJS and `ajv`, whereas the main package is fully self-contained.) @@ -13,23 +13,23 @@ https://github.com/microsoft/tsdoc ## Creating config files -The **tsdocconfig.json** file is optional. When used, it is expected to be found in the same folder as +The **tsdoc.json** file is optional. When used, it is expected to be found in the same folder as the **tsconfig.json** file for a project. The loader looks for it by walking upwards in the directory tree until it finds a folder containing **tsconfig.json** or **package.json**, and then it attempts to load -**tsdocconfig.json** from that location. +**tsdoc.json** from that location. -The **tsdocconfig.json** file conforms to the [tsdocconfig.schema.json]( -https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json) JSON schema. It defines tags using +The **tsdoc.json** file conforms to the [tsdoc.schema.json]( +https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json) JSON schema. It defines tags using similar fields as the [TSDocTagDefinition](https://github.com/microsoft/tsdoc/blob/master/tsdoc/src/configuration/TSDocTagDefinition.ts) API used by `TSDocParser` from `@microsoft/tsdoc`. Here's a simple example: -**tsdocconfig.json** +**tsdoc.json** ```js { - "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json", "tagDefinitions": [ { "tagName": "@myTag", @@ -42,13 +42,13 @@ Here's a simple example: If you want to define custom tags in one place and share them across multiple projects, the `extends` field specifies a list of paths that will be mixed in with the current file: -**tsdocconfig.json** +**tsdoc.json** ```js { - "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json", "extends": [ - "my-package/dist/tsdocconfig-base.json", - "./path/to/local/file/tsdocconfig-local.json" + "my-package/dist/tsdoc-base.json", + "./path/to/local/file/tsdoc-local.json" ] } ``` @@ -60,7 +60,7 @@ a list of paths that will be mixed in with the current file: ## API Usage The code sample below illustrates how to invoke the `@microsoft/tsdoc-config` API to load a -**tsdocconfig.json** file: +**tsdoc.json** file: ```ts import * as path from 'path'; @@ -70,7 +70,7 @@ import { TSDocConfigFile } from '@microsoft/tsdoc-config'; // Sample source file to be parsed const mySourceFile: string = 'my-project/src/example.ts'; -// Load the nearest config file, for example `my-project/tsdocconfig.json` +// Load the nearest config file, for example `my-project/tsdoc.json` const tsdocConfigFile: TSDocConfigFile = TSDocConfigFile.loadForFolder(path.dirname(mySourceFile)); if (tsdocConfigFile.hasErrors) { // Report any errors diff --git a/tsdoc-config/package.json b/tsdoc-config/package.json index 1e42e386..e054d74c 100644 --- a/tsdoc-config/package.json +++ b/tsdoc-config/package.json @@ -1,7 +1,7 @@ { "name": "@microsoft/tsdoc-config", "version": "0.12.15", - "description": "A loader for the tsdocconfig.json file", + "description": "A loader for the tsdoc.json file", "keywords": [ "TypeScript", "documentation", diff --git a/tsdoc-config/src/TSDocConfigFile.ts b/tsdoc-config/src/TSDocConfigFile.ts index 8a6bbdad..2f78c532 100644 --- a/tsdoc-config/src/TSDocConfigFile.ts +++ b/tsdoc-config/src/TSDocConfigFile.ts @@ -16,7 +16,7 @@ import * as Ajv from 'ajv'; const ajv: Ajv.Ajv = new Ajv({ verbose: true }); function initializeSchemaValidator(): Ajv.ValidateFunction { - const jsonSchemaPath: string = resolve.sync('@microsoft/tsdoc/schemas/tsdocconfig.schema.json', { basedir: __dirname }); + const jsonSchemaPath: string = resolve.sync('@microsoft/tsdoc/schemas/tsdoc.schema.json', { basedir: __dirname }); const jsonSchemaContent: string = fs.readFileSync(jsonSchemaPath).toString(); const jsonSchema: object = JSON.parse(jsonSchemaContent); return ajv.compile(jsonSchema); @@ -41,14 +41,14 @@ interface IConfigJson { } /** - * Represents an individual `tsdocconfig.json` file. + * Represents an individual `tsdoc.json` file. * * @public */ export class TSDocConfigFile { - public static readonly FILENAME: string = 'tsdocconfig.json'; + public static readonly FILENAME: string = 'tsdoc.json'; public static readonly CURRENT_SCHEMA_URL: string - = 'https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json'; + = 'https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json'; /** * A queryable log that reports warnings and error messages that occurred during parsing. @@ -90,7 +90,7 @@ export class TSDocConfigFile { } /** - * If true, then the TSDocConfigFile object contains an empty state, because the `tsdocconfig.json` file could + * If true, then the TSDocConfigFile object contains an empty state, because the `tsdoc.json` file could * not be found by the loader. */ public get fileNotFound(): boolean { @@ -111,14 +111,14 @@ export class TSDocConfigFile { } /** - * The `$schema` field from the `tsdocconfig.json` file. + * The `$schema` field from the `tsdoc.json` file. */ public get tsdocSchema(): string { return this._tsdocSchema; } /** - * The `extends` field from the `tsdocconfig.json` file. For the parsed file contents, + * The `extends` field from the `tsdoc.json` file. For the parsed file contents, * use the `extendsFiles` property instead. */ public get extendsPaths(): ReadonlyArray { @@ -275,7 +275,7 @@ export class TSDocConfigFile { } /** - * For the given folder, discover the relevant tsdocconfig.json files (if any), and load them. + * For the given folder, discover the relevant tsdoc.json files (if any), and load them. * @param folderPath - the path to a folder where the search should start */ public static loadForFolder(folderPath: string): TSDocConfigFile { diff --git a/tsdoc-config/src/__tests__/TSDocConfigFile.test.ts b/tsdoc-config/src/__tests__/TSDocConfigFile.test.ts index f913cb44..3ae8a266 100644 --- a/tsdoc-config/src/__tests__/TSDocConfigFile.test.ts +++ b/tsdoc-config/src/__tests__/TSDocConfigFile.test.ts @@ -38,10 +38,10 @@ test('Load p1', () => { "extendsFiles": Array [], "extendsPaths": Array [], "fileNotFound": false, - "filePath": "assets/p1/tsdocconfig.json", + "filePath": "assets/p1/tsdoc.json", "messages": Array [], "tagDefinitions": Array [], - "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", + "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json", } `); }); @@ -51,7 +51,7 @@ test('Load p2', () => { "extendsFiles": Array [], "extendsPaths": Array [], "fileNotFound": true, - "filePath": "assets/p2/tsdocconfig.json", + "filePath": "assets/p2/tsdoc.json", "messages": Array [ ParserMessage { "_text": undefined, @@ -79,7 +79,7 @@ test('Load p3', () => { "extendsFiles": Array [], "extendsPaths": Array [], "fileNotFound": false, - "filePath": "assets/p3/base1/tsdocconfig-base1.json", + "filePath": "assets/p3/base1/tsdoc-base1.json", "messages": Array [], "tagDefinitions": Array [ TSDocTagDefinition { @@ -90,13 +90,13 @@ test('Load p3', () => { "tagNameWithUpperCase": "@BASE1", }, ], - "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", + "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json", }, Object { "extendsFiles": Array [], "extendsPaths": Array [], "fileNotFound": false, - "filePath": "assets/p3/base2/tsdocconfig-base2.json", + "filePath": "assets/p3/base2/tsdoc-base2.json", "messages": Array [], "tagDefinitions": Array [ TSDocTagDefinition { @@ -107,15 +107,15 @@ test('Load p3', () => { "tagNameWithUpperCase": "@BASE2", }, ], - "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", + "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json", }, ], "extendsPaths": Array [ - "./base1/tsdocconfig-base1.json", - "./base2/tsdocconfig-base2.json", + "./base1/tsdoc-base1.json", + "./base2/tsdoc-base2.json", ], "fileNotFound": false, - "filePath": "assets/p3/tsdocconfig.json", + "filePath": "assets/p3/tsdoc.json", "messages": Array [], "tagDefinitions": Array [ TSDocTagDefinition { @@ -126,7 +126,7 @@ test('Load p3', () => { "tagNameWithUpperCase": "@ROOT", }, ], - "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", + "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json", } `); }); @@ -138,7 +138,7 @@ test('Load p4', () => { "extendsFiles": Array [], "extendsPaths": Array [], "fileNotFound": false, - "filePath": "assets/p4/node_modules/example-lib/dist/tsdocconfig-example.json", + "filePath": "assets/p4/node_modules/example-lib/dist/tsdoc-example.json", "messages": Array [], "tagDefinitions": Array [ TSDocTagDefinition { @@ -149,14 +149,14 @@ test('Load p4', () => { "tagNameWithUpperCase": "@EXAMPLE", }, ], - "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", + "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json", }, ], "extendsPaths": Array [ - "example-lib/dist/tsdocconfig-example.json", + "example-lib/dist/tsdoc-example.json", ], "fileNotFound": false, - "filePath": "assets/p4/tsdocconfig.json", + "filePath": "assets/p4/tsdoc.json", "messages": Array [], "tagDefinitions": Array [ TSDocTagDefinition { @@ -167,7 +167,7 @@ test('Load p4', () => { "tagNameWithUpperCase": "@ROOT", }, ], - "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", + "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json", } `); }); diff --git a/tsdoc-config/src/__tests__/assets/p1/tsdoc.json b/tsdoc-config/src/__tests__/assets/p1/tsdoc.json index 2c333f97..212f75bd 100644 --- a/tsdoc-config/src/__tests__/assets/p1/tsdoc.json +++ b/tsdoc-config/src/__tests__/assets/p1/tsdoc.json @@ -1,3 +1,3 @@ { - "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json" + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json" } diff --git a/tsdoc-config/src/__tests__/assets/p3/base1/tsdoc-base1.json b/tsdoc-config/src/__tests__/assets/p3/base1/tsdoc-base1.json index 9860f535..b734ade0 100644 --- a/tsdoc-config/src/__tests__/assets/p3/base1/tsdoc-base1.json +++ b/tsdoc-config/src/__tests__/assets/p3/base1/tsdoc-base1.json @@ -1,5 +1,5 @@ { - "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json", "tagDefinitions": [ { "tagName": "@base1", diff --git a/tsdoc-config/src/__tests__/assets/p3/base2/tsdoc-base2.json b/tsdoc-config/src/__tests__/assets/p3/base2/tsdoc-base2.json index 6156064f..9d20231c 100644 --- a/tsdoc-config/src/__tests__/assets/p3/base2/tsdoc-base2.json +++ b/tsdoc-config/src/__tests__/assets/p3/base2/tsdoc-base2.json @@ -1,5 +1,5 @@ { - "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json", "tagDefinitions": [ { "tagName": "@base2", diff --git a/tsdoc-config/src/__tests__/assets/p3/tsdoc.json b/tsdoc-config/src/__tests__/assets/p3/tsdoc.json index e0c0fd9a..0be2eb39 100644 --- a/tsdoc-config/src/__tests__/assets/p3/tsdoc.json +++ b/tsdoc-config/src/__tests__/assets/p3/tsdoc.json @@ -1,8 +1,8 @@ { - "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json", "extends": [ - "./base1/tsdocconfig-base1.json", - "./base2/tsdocconfig-base2.json" + "./base1/tsdoc-base1.json", + "./base2/tsdoc-base2.json" ], "tagDefinitions": [ { diff --git a/tsdoc-config/src/__tests__/assets/p4/tsdoc.json b/tsdoc-config/src/__tests__/assets/p4/tsdoc.json index 06239971..0a857667 100644 --- a/tsdoc-config/src/__tests__/assets/p4/tsdoc.json +++ b/tsdoc-config/src/__tests__/assets/p4/tsdoc.json @@ -1,7 +1,7 @@ { - "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json", "extends": [ - "example-lib/dist/tsdocconfig-example.json" + "example-lib/dist/tsdoc-example.json" ], "tagDefinitions": [ { diff --git a/tsdoc/README.md b/tsdoc/README.md index 3a8224a9..4c3d86e5 100644 --- a/tsdoc/README.md +++ b/tsdoc/README.md @@ -38,7 +38,7 @@ The [api-demo](https://github.com/microsoft/tsdoc/tree/master/api-demo) folder o to invoke the TSDoc parser. A separate NPM package [`@microsoft/tsdoc-config`](https://www.npmjs.com/package/@microsoft/tsdoc) -is used for loading the **tsdocconfig.json** file. +is used for loading the **tsdoc.json** file. ## Get involved diff --git a/tsdoc/src/parser/TSDocMessageId.ts b/tsdoc/src/parser/TSDocMessageId.ts index 814a87dc..23159a31 100644 --- a/tsdoc/src/parser/TSDocMessageId.ts +++ b/tsdoc/src/parser/TSDocMessageId.ts @@ -14,7 +14,7 @@ export const enum TSDocMessageId { /** * File not found * @remarks - * Reported by the `@microsoft/tsdoc-config` package when it failed to find a `tsdocconfig.json` file. + * Reported by the `@microsoft/tsdoc-config` package when it failed to find a `tsdoc.json` file. */ ConfigFileNotFound = 'tsdoc-config-file-not-found', From d89d2c55615220e07bea0a409211063b71791ce0 Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Sun, 17 Nov 2019 10:49:25 -0800 Subject: [PATCH 20/20] Change schema URL to "v0" since we haven't done the 1.0 release yet --- tsdoc-config/README.md | 6 +++--- tsdoc-config/src/TSDocConfigFile.ts | 2 +- tsdoc-config/src/__tests__/TSDocConfigFile.test.ts | 12 ++++++------ tsdoc-config/src/__tests__/assets/p1/tsdoc.json | 2 +- .../src/__tests__/assets/p3/base1/tsdoc-base1.json | 2 +- .../src/__tests__/assets/p3/base2/tsdoc-base2.json | 2 +- tsdoc-config/src/__tests__/assets/p3/tsdoc.json | 2 +- .../node_modules/example-lib/dist/tsdoc-example.json | 2 +- tsdoc-config/src/__tests__/assets/p4/tsdoc.json | 2 +- 9 files changed, 16 insertions(+), 16 deletions(-) diff --git a/tsdoc-config/README.md b/tsdoc-config/README.md index 6bd79224..4bdc683b 100644 --- a/tsdoc-config/README.md +++ b/tsdoc-config/README.md @@ -19,7 +19,7 @@ until it finds a folder containing **tsconfig.json** or **package.json**, and th **tsdoc.json** from that location. The **tsdoc.json** file conforms to the [tsdoc.schema.json]( -https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json) JSON schema. It defines tags using +https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json) JSON schema. It defines tags using similar fields as the [TSDocTagDefinition](https://github.com/microsoft/tsdoc/blob/master/tsdoc/src/configuration/TSDocTagDefinition.ts) API used by `TSDocParser` from `@microsoft/tsdoc`. @@ -29,7 +29,7 @@ Here's a simple example: **tsdoc.json** ```js { - "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json", + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", "tagDefinitions": [ { "tagName": "@myTag", @@ -45,7 +45,7 @@ a list of paths that will be mixed in with the current file: **tsdoc.json** ```js { - "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json", + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", "extends": [ "my-package/dist/tsdoc-base.json", "./path/to/local/file/tsdoc-local.json" diff --git a/tsdoc-config/src/TSDocConfigFile.ts b/tsdoc-config/src/TSDocConfigFile.ts index 2f78c532..5c78b314 100644 --- a/tsdoc-config/src/TSDocConfigFile.ts +++ b/tsdoc-config/src/TSDocConfigFile.ts @@ -48,7 +48,7 @@ interface IConfigJson { export class TSDocConfigFile { public static readonly FILENAME: string = 'tsdoc.json'; public static readonly CURRENT_SCHEMA_URL: string - = 'https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json'; + = 'https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json'; /** * A queryable log that reports warnings and error messages that occurred during parsing. diff --git a/tsdoc-config/src/__tests__/TSDocConfigFile.test.ts b/tsdoc-config/src/__tests__/TSDocConfigFile.test.ts index 3ae8a266..8e0af966 100644 --- a/tsdoc-config/src/__tests__/TSDocConfigFile.test.ts +++ b/tsdoc-config/src/__tests__/TSDocConfigFile.test.ts @@ -41,7 +41,7 @@ test('Load p1', () => { "filePath": "assets/p1/tsdoc.json", "messages": Array [], "tagDefinitions": Array [], - "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json", + "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", } `); }); @@ -90,7 +90,7 @@ test('Load p3', () => { "tagNameWithUpperCase": "@BASE1", }, ], - "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json", + "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", }, Object { "extendsFiles": Array [], @@ -107,7 +107,7 @@ test('Load p3', () => { "tagNameWithUpperCase": "@BASE2", }, ], - "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json", + "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", }, ], "extendsPaths": Array [ @@ -126,7 +126,7 @@ test('Load p3', () => { "tagNameWithUpperCase": "@ROOT", }, ], - "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json", + "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", } `); }); @@ -149,7 +149,7 @@ test('Load p4', () => { "tagNameWithUpperCase": "@EXAMPLE", }, ], - "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json", + "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", }, ], "extendsPaths": Array [ @@ -167,7 +167,7 @@ test('Load p4', () => { "tagNameWithUpperCase": "@ROOT", }, ], - "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json", + "tsdocSchema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", } `); }); diff --git a/tsdoc-config/src/__tests__/assets/p1/tsdoc.json b/tsdoc-config/src/__tests__/assets/p1/tsdoc.json index 212f75bd..f4ac01a0 100644 --- a/tsdoc-config/src/__tests__/assets/p1/tsdoc.json +++ b/tsdoc-config/src/__tests__/assets/p1/tsdoc.json @@ -1,3 +1,3 @@ { - "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json" + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json" } diff --git a/tsdoc-config/src/__tests__/assets/p3/base1/tsdoc-base1.json b/tsdoc-config/src/__tests__/assets/p3/base1/tsdoc-base1.json index b734ade0..c2f4560a 100644 --- a/tsdoc-config/src/__tests__/assets/p3/base1/tsdoc-base1.json +++ b/tsdoc-config/src/__tests__/assets/p3/base1/tsdoc-base1.json @@ -1,5 +1,5 @@ { - "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json", + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", "tagDefinitions": [ { "tagName": "@base1", diff --git a/tsdoc-config/src/__tests__/assets/p3/base2/tsdoc-base2.json b/tsdoc-config/src/__tests__/assets/p3/base2/tsdoc-base2.json index 9d20231c..52c66531 100644 --- a/tsdoc-config/src/__tests__/assets/p3/base2/tsdoc-base2.json +++ b/tsdoc-config/src/__tests__/assets/p3/base2/tsdoc-base2.json @@ -1,5 +1,5 @@ { - "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json", + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", "tagDefinitions": [ { "tagName": "@base2", diff --git a/tsdoc-config/src/__tests__/assets/p3/tsdoc.json b/tsdoc-config/src/__tests__/assets/p3/tsdoc.json index 0be2eb39..e3845bcc 100644 --- a/tsdoc-config/src/__tests__/assets/p3/tsdoc.json +++ b/tsdoc-config/src/__tests__/assets/p3/tsdoc.json @@ -1,5 +1,5 @@ { - "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json", + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", "extends": [ "./base1/tsdoc-base1.json", "./base2/tsdoc-base2.json" diff --git a/tsdoc-config/src/__tests__/assets/p4/node_modules/example-lib/dist/tsdoc-example.json b/tsdoc-config/src/__tests__/assets/p4/node_modules/example-lib/dist/tsdoc-example.json index 460126fb..870374e4 100644 --- a/tsdoc-config/src/__tests__/assets/p4/node_modules/example-lib/dist/tsdoc-example.json +++ b/tsdoc-config/src/__tests__/assets/p4/node_modules/example-lib/dist/tsdoc-example.json @@ -1,5 +1,5 @@ { - "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", "tagDefinitions": [ { "tagName": "@example", diff --git a/tsdoc-config/src/__tests__/assets/p4/tsdoc.json b/tsdoc-config/src/__tests__/assets/p4/tsdoc.json index 0a857667..abb4b703 100644 --- a/tsdoc-config/src/__tests__/assets/p4/tsdoc.json +++ b/tsdoc-config/src/__tests__/assets/p4/tsdoc.json @@ -1,5 +1,5 @@ { - "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdoc.schema.json", + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", "extends": [ "example-lib/dist/tsdoc-example.json" ],