docs: readme for instrument package

core/instrument/package.json

@@ -13,6 +13,7 @@
   "scripts": {
     "build": "yarn cross-env NODE_ENV=production rollup -c",
     "dev": "yarn cross-env NODE_ENV=development yarn build -w",
+    "doc": "yarn cross-env typedoc --theme bitbucket --out doc --target es6 --mode library src/index.ts",
     "fix": "yarn lint --fix",
     "lint": "yarn eslint . --ext mdx,ts,tsx",
     "prepare": "yarn build",

core/instrument/src/index.ts

@@ -1,5 +1,6 @@
 import * as parser from '@babel/parser';
-const mdx = require('@mdx-js/mdx');
+//@ts-ignore
+import mdx from '@mdx-js/mdx';
 import { toId, storyNameFromExport } from '@storybook/csf';
 import traverse from '@babel/traverse';
 import generate from '@babel/generator';
@@ -27,6 +28,14 @@ export * from './types';
 
 type TraverseFn = (stories: StoriesStore) => any;
 
+/**
+ * Instrument a source file, with options
+ * @param code The source code
+ * @param traverseFn A traverse function. can be different for MDX and CSF story files
+ * @param originalSource If the source was modified (ie mdx compiler)
+ * @param filePath file name with fiull path
+ * @param options Instrument options
+ */
 const parseSource = async (
   code: string,
   traverseFn: TraverseFn,
@@ -57,7 +66,9 @@ const parseSource = async (
   const prettify = async (c: string): Promise<string> => {
     if (prettierOptions !== false) {
       const { resolveConfigOptions, ...otherOptions } = prettierOptions || {};
-      let allPrettierOptions = otherOptions;
+      let allPrettierOptions:
+        | prettier.Options
+        | undefined = otherOptions as any;
       if (filePath) {
         const userOptions = await prettier.resolveConfig(
           filePath,
@@ -158,7 +169,12 @@ const parseSource = async (
   });
   return store;
 };
-
+/**
+ * Parse and instrument a javascript or typescript file of stories
+ * @param source Source of the file to be instrumented
+ * @param filePath Resolved file path name.
+ * @param options Instrumenting options
+ */
 export const parseCSF = async (
   source: string,
   filePath: string,
@@ -173,6 +189,13 @@ export const parseCSF = async (
   );
 };
 
+/**
+ * Parse and instrument an MDX file of stories
+ * @param source Source of the file to be instrumented
+ * @param filePath Resolved file path name.
+ * @param options Instrumenting options
+ */
+
 export const parseMDX = async (
   source: string,
   filePath: string,

core/instrument/src/project/packageInfo.ts

@@ -1,7 +1,9 @@
 import fs from 'fs';
 import path from 'path';
+//@ts-ignore
 import readJson from 'read-package-json';
 import hostedGitInfo from 'hosted-git-info';
+//@ts-ignore
 import parseRepositoryURL from '@hutson/parse-repository-url';
 import { Repository } from '@component-controls/specification';
 

core/instrument/src/types.ts

@@ -1,31 +1,38 @@
-import * as parser from '@babel/parser';
-import * as resolve from 'resolve';
-import { Options, ResolveConfigOptions } from 'prettier';
+import { ParserOptions } from '@babel/parser';
+import { SyncOpts as ResolveOptions } from 'resolve';
+import {
+  Options,
+  ResolveConfigOptions as ResolvePrettierConfigOptions,
+} from 'prettier';
 
-export type PrettierOptions = Options & {
-  resolveConfigOptions?: ResolveConfigOptions;
+type PrettierOptions = Options & {
+  resolveConfigOptions?: ResolvePrettierConfigOptions;
 };
+export { ParserOptions, ResolveOptions, PrettierOptions };
 
-export const defaultResolveOptions: resolve.SyncOpts = {
+export const defaultResolveOptions: ResolveOptions = {
   extensions: ['.js', '.jsx', '.ts', '.tsx', '.vue', '.mjs', '.es', '.es6'],
 };
 
-export const defaultParserOptions: parser.ParserOptions = {
+export const defaultParserOptions: ParserOptions = {
   sourceType: 'module',
   plugins: ['jsx', 'typescript'],
 };
 
 export interface ComponentOptions {
-  resolveFile?: (componentName: string, FilePath: string) => string | undefined;
+  resolveFile?: (componentName: string, filePath: string) => string | undefined;
 }
-
-export type ParserOptions = parser.ParserOptions;
-
-export type ResolveOptions = resolve.SyncOpts;
-
+/**
+ * Options passed for instrumenting
+ */
 export interface InstrumentOptions {
-  parser?: parser.ParserOptions;
-  prettier?: PrettierOptions;
+  parser?: ParserOptions;
+  /**
+   * prettier options are used to prettify the code at the end of the process
+   * this is useful for "story" code, where the story is extracted from the full file
+   * fassing a value of false as prettier option will disabled prettifying
+   */
+  prettier?: PrettierOptions | false;
   resolve?: ResolveOptions;
   component?: ComponentOptions;
 }

core/instrument/src/typings.d.ts

@@ -1,3 +1,4 @@
 declare module 'read-package-json';
 declare module '@hutson/parse-repository-url';
 declare module 'hosted-git-info';
+declare module '@mdx-js/mdx';

package.json

@@ -70,6 +70,8 @@
     "rollup": "^1.31.0",
     "trash-cli": "^3.0.0",
     "ts-jest": "^24.0.2",
+    "typedoc": "^0.17.0-3",
+    "typedoc-plugin-markdown": "^2.2.17",
     "typescript": "^3.7.5"
   },
   "workspaces": {
@@ -80,4 +82,4 @@
       "examples/*"
     ]
   }
-}
+}

yarn.lock

@@ -3394,7 +3394,7 @@
   dependencies:
     "@types/react" "*"
 
-"@types/minimatch@*":
+"@types/minimatch@*", "@types/[email protected]":
   version "3.0.3"
   resolved "https://registry.yarnpkg.com/@types/minimatch/-/minimatch-3.0.3.tgz#3dca0e3f33b200fc7d1139c0cd96c1268cadfd9d"
   integrity sha512-tHq6qdbT9U1IRSGf14CL0pUlULksvY9OZ+5eEgl1N7t+OA3tGvNpxJCzuKQlsNgCVwbAs670L1vcVQi8j9HjnA==
@@ -4780,6 +4780,13 @@ babylon@^6.18.0:
   resolved "https://registry.yarnpkg.com/babylon/-/babylon-6.18.0.tgz#af2f3b88fa6f5c1e4c634d1a0f8eac4f55b395e3"
   integrity sha512-q/UEjfGJ2Cm3oKV71DJz9d25TPnq5rhBVL2Q4fA5wcC3jcrdn7+SssEybFIxwAvvP+YCsCYNKughoF33GxgycQ==
 
+backbone@^1.4.0:
+  version "1.4.0"
+  resolved "https://registry.yarnpkg.com/backbone/-/backbone-1.4.0.tgz#54db4de9df7c3811c3f032f34749a4cd27f3bd12"
+  integrity sha512-RLmDrRXkVdouTg38jcgHhyQ/2zjg7a8E6sz2zxfz21Hh17xDJYUHBZimVIt5fUyS8vbfpeSmTL3gUjTEvUV3qQ==
+  dependencies:
+    underscore ">=1.8.3"
+
 bail@^1.0.0:
   version "1.0.5"
   resolved "https://registry.yarnpkg.com/bail/-/bail-1.0.5.tgz#b6fa133404a392cbc1f8c4bf63f5953351e7a776"
@@ -8410,7 +8417,7 @@ [email protected], gzip-size@^5.1.1:
     duplexer "^0.1.1"
     pify "^4.0.1"
 
-handlebars@^4.4.0:
+handlebars@^4.4.0, handlebars@^4.7.2, handlebars@^4.7.3:
   version "4.7.3"
   resolved "https://registry.yarnpkg.com/handlebars/-/handlebars-4.7.3.tgz#8ece2797826886cf8082d1726ff21d2a022550ee"
   integrity sha512-SRGwSYuNfx8DwHD/6InAPzD6RgeruWLT+B8e8a7gGs8FWgHzlExpTFMEq2IA6QpAfOClpKHy6+8IqTjeBCu6Kg==
@@ -8603,6 +8610,11 @@ hex-color-regex@^1.1.0:
   resolved "https://registry.yarnpkg.com/hex-color-regex/-/hex-color-regex-1.1.0.tgz#4c06fccb4602fe2602b3c93df82d7e7dbf1a8a8e"
   integrity sha512-l9sfDFsuqtOqKDsQdqrMRk0U85RZc0RtOR9yPI7mRVOa4FsR/BVnZ0shmQRM96Ji99kYZP/7hn1cedc1+ApsTQ==
 
+highlight.js@^9.18.0:
+  version "9.18.1"
+  resolved "https://registry.yarnpkg.com/highlight.js/-/highlight.js-9.18.1.tgz#ed21aa001fe6252bb10a3d76d47573c6539fe13c"
+  integrity sha512-OrVKYz70LHsnCgmbXctv/bfuvntIKDz177h0Co37DQ5jamGZLVmoCVMtjMtNZY3X9DrCcKfklHPNeA0uPZhSJg==
+
 highlight.js@~9.13.0:
   version "9.13.1"
   resolved "https://registry.yarnpkg.com/highlight.js/-/highlight.js-9.13.1.tgz#054586d53a6863311168488a0f58d6c505ce641e"
@@ -10055,6 +10067,11 @@ jest@^24.8.0, jest@^24.9.0:
     import-local "^2.0.0"
     jest-cli "^24.9.0"
 
+jquery@^3.4.1:
+  version "3.4.1"
+  resolved "https://registry.yarnpkg.com/jquery/-/jquery-3.4.1.tgz#714f1f8d9dde4bdfa55764ba37ef214630d80ef2"
+  integrity sha512-36+AdBzCL+y6qjw5Tx7HgzeGCzC81MDDgaUP8ld2zhx58HdqXGoBd+tHdrBMiyjGQs0Hxs/MLZTu/eHNJJuWPw==
+
 js-string-escape@^1.0.1:
   version "1.0.1"
   resolved "https://registry.yarnpkg.com/js-string-escape/-/js-string-escape-1.0.1.tgz#e2625badbc0d67c7533e9edc1068c587ae4137ef"
@@ -10718,6 +10735,11 @@ lru-cache@^5.1.1:
   dependencies:
     yallist "^3.0.2"
 
+lunr@^2.3.8:
+  version "2.3.8"
+  resolved "https://registry.yarnpkg.com/lunr/-/lunr-2.3.8.tgz#a8b89c31f30b5a044b97d2d28e2da191b6ba2072"
+  integrity sha512-oxMeX/Y35PNFuZoHp+jUj5OSEmLCaIH4KTFJh7a93cHBoFmpw2IoPs22VIz7vyO2YUnx2Tn9dzIwO2P/4quIRg==
+
 macos-release@^2.2.0:
   version "2.3.0"
   resolved "https://registry.yarnpkg.com/macos-release/-/macos-release-2.3.0.tgz#eb1930b036c0800adebccd5f17bc4c12de8bb71f"
@@ -10855,6 +10877,11 @@ markdown-to-jsx@^6.11.0, markdown-to-jsx@^6.9.1, markdown-to-jsx@^6.9.3:
     prop-types "^15.6.2"
     unquote "^1.1.0"
 
+marked@^0.8.0:
+  version "0.8.0"
+  resolved "https://registry.yarnpkg.com/marked/-/marked-0.8.0.tgz#ec5c0c9b93878dc52dd54be8d0e524097bd81a99"
+  integrity sha512-MyUe+T/Pw4TZufHkzAfDj6HarCBWia2y27/bhuYkTaiUnfDYFnCP3KUN+9oM7Wi6JA2rymtVYbQu3spE0GCmxQ==
+
 material-colors@^1.2.1:
   version "1.2.6"
   resolved "https://registry.yarnpkg.com/material-colors/-/material-colors-1.2.6.tgz#6d1958871126992ceecc72f4bcc4d8f010865f46"
@@ -12867,7 +12894,7 @@ process@^0.11.10:
   resolved "https://registry.yarnpkg.com/process/-/process-0.11.10.tgz#7332300e840161bda3e69a1d1d91a7d4bc16f182"
   integrity sha1-czIwDoQBYb2j5podHZGn1LwW8YI=
 
-progress@^2.0.0:
+progress@^2.0.0, progress@^2.0.3:
   version "2.0.3"
   resolved "https://registry.yarnpkg.com/progress/-/progress-2.0.3.tgz#7e8cf8d8f5b8f239c1bc68beb4eb78567d572ef8"
   integrity sha512-7PiHtLll5LdnKIMw100I+8xJXR5gW2QwWYkT6iJva0bXitZKa/XMrSbdmg3r2Xnaidz9Qumd0VPaMrZlF9V9sA==
@@ -15878,6 +15905,40 @@ typedarray@^0.0.6:
   resolved "https://registry.yarnpkg.com/typedarray/-/typedarray-0.0.6.tgz#867ac74e3864187b1d3d47d996a78ec5c8830777"
   integrity sha1-hnrHTjhkGHsdPUfZlqeOxciDB3c=
 
+[email protected]:
+  version "0.8.0-0"
+  resolved "https://registry.yarnpkg.com/typedoc-default-themes/-/typedoc-default-themes-0.8.0-0.tgz#80b7080837b2c9eba36c2fe06601ebe01973a0cd"
+  integrity sha512-blFWppm5aKnaPOa1tpGO9MLu+njxq7P3rtkXK4QxJBNszA+Jg7x0b+Qx0liXU1acErur6r/iZdrwxp5DUFdSXw==
+  dependencies:
+    backbone "^1.4.0"
+    jquery "^3.4.1"
+    lunr "^2.3.8"
+    underscore "^1.9.1"
+
+typedoc-plugin-markdown@^2.2.17:
+  version "2.2.17"
+  resolved "https://registry.yarnpkg.com/typedoc-plugin-markdown/-/typedoc-plugin-markdown-2.2.17.tgz#aaef7420e8268170e62c764f43740e10f842548d"
+  integrity sha512-eE6cTeqsZIbjur6RG91Lhx1vTwjR49OHwVPRlmsxY3dthS4FNRL8sHxT5Y9pkosBwv1kSmNGQEPHjMYy1Ag6DQ==
+  dependencies:
+    fs-extra "^8.1.0"
+    handlebars "^4.7.3"
+
+typedoc@^0.17.0-3:
+  version "0.17.0-3"
+  resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.17.0-3.tgz#91996e77427ff3a208ab76595a927ee11b75e9e8"
+  integrity sha512-DO2djkR4NHgzAWfNbJb2eQKsFMs+gOuYBXlQ8dOSCjkAK5DRI7ZywDufBGPUw7Ue9Qwi2Cw1DxLd3reDq8wFuQ==
+  dependencies:
+    "@types/minimatch" "3.0.3"
+    fs-extra "^8.1.0"
+    handlebars "^4.7.2"
+    highlight.js "^9.18.0"
+    lodash "^4.17.15"
+    marked "^0.8.0"
+    minimatch "^3.0.0"
+    progress "^2.0.3"
+    shelljs "^0.8.3"
+    typedoc-default-themes "0.8.0-0"
+
 [email protected]:
   version "3.5.3"
   resolved "https://registry.yarnpkg.com/typescript/-/typescript-3.5.3.tgz#c830f657f93f1ea846819e929092f5fe5983e977"
@@ -15921,6 +15982,11 @@ umask@^1.1.0:
   resolved "https://registry.yarnpkg.com/umask/-/umask-1.1.0.tgz#f29cebf01df517912bb58ff9c4e50fde8e33320d"
   integrity sha1-8pzr8B31F5ErtY/5xOUP3o4zMg0=
 
+underscore@>=1.8.3, underscore@^1.9.1:
+  version "1.9.2"
+  resolved "https://registry.yarnpkg.com/underscore/-/underscore-1.9.2.tgz#0c8d6f536d6f378a5af264a72f7bec50feb7cf2f"
+  integrity sha512-D39qtimx0c1fI3ya1Lnhk3E9nONswSKhnffBI0gME9C99fYOkNi04xs8K6pePLhvl1frbDemkaBQ5ikWllR2HQ==
+
 unfetch@^4.1.0:
   version "4.1.0"
   resolved "https://registry.yarnpkg.com/unfetch/-/unfetch-4.1.0.tgz#6ec2dd0de887e58a4dee83a050ded80ffc4137db"