1.0.0 release

.travis.yml

@@ -0,0 +1,28 @@
+dist: focal
+language: node_js
+node_js:
+    - lts/*
+    - node
+sudo: false
+install:
+    - npm config set prefer-offline false
+    - git clone --branch=develop --depth 1 https://github.com/enactjs/cli ../cli
+    - pushd ../cli
+    - npm install
+    - npm link
+    - popd
+    - git clone --branch=develop --depth 1 https://github.com/enactjs/sandstone ../sandstone
+    - npm install
+script:
+    - echo -e "\x1b\x5b35;1m*** Starting tests...\x1b\x5b0m"
+    - npm test -- --runInBand --coverage
+    - echo -e "\x1b\x5b35;1m*** Tests complete\x1b\x5b0m"
+    - echo -e "\x1b\x5b35;1m*** Starting eslint...\x1b\x5b0m"
+    - npm run lint -- --report-unused-disable-directives --max-warnings 0 .
+    - echo -e "\x1b\x5b35;1m*** eslint complete\x1b\x5b0m"
+    - echo -e "\x1b\x5b35;1m*** Starting help option...\x1b\x5b0m"
+    - node bin/jsdoc-to-ts -h
+    - echo -e "\x1b\x5b35;1m*** help option complete\x1b\x5b0m"
+    - echo -e "\x1b\x5b35;1m*** Starting JSDoc converting...\x1b\x5b0m"
+    - node bin/jsdoc-to-ts ../sandstone -o=../sandstone
+    - echo -e "\x1b\x5b35;1m*** JSDoc converting complete\x1b\x5b0m"

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Change Log
 
+## [1.0.0] (July 5, 2023)
+
+* Migrated project to ESM.
+* Updated `jsonata` dependency to version 2.x and refactored code to use async functions.
+* Added more options to jsdoc-to-ts CLI: `ignore`, `importMap`, `output`, `outputPath`.
+
 ## [0.1.4] (March 3, 2023)
 
 * Added the rendering of static members for a component.

README.md

@@ -1,9 +1,26 @@
 ## @enact/jsdoc-to-ts [![NPM](https://img.shields.io/npm/v/@enact/jsdoc-to-ts.svg?style=flat-square)](https://www.npmjs.com/package/@enact/jsdoc-to-ts)
- 
+
 > Converts JSDoc comments into TypeScript d.ts files
 
 > Note. It's an experimental module.
 
+**IMPORTANT:** jsdoc-to-ts 1.0.0 is the ESM. After upgrading from 0.1.x, please change the previous command as follows.
+```bash
+// Before
+node -e "['core', 'ui', 'moonstone', 'i18n', 'webos', 'spotlight'].forEach(p => require('.')({
+  ...
+}))" "(path of jsdoc-to-ts)"
+
+// After
+node -e "import('(path of jsdoc-to-ts)/index.js').then(({default: jsdocToTs}) => {
+  ['core', 'ui', 'moonstone', 'i18n', 'webos', 'spotlight'].forEach(p => jsdocToTs({
+    ...
+})"
+```
+NOTE: The script requires at least Node.js 13.2.0. or later.
+
+Or, try a simple CLI command. [Read more.](./README.md#usage-with-cli-option-on-installation-path)
+
 ### Installation
 
 ```
@@ -15,51 +32,57 @@ npm install --save-dev @enact/jsdoc-to-ts
 Assuming this directory is a peer of the Enact source and you want to write this into an installed (from npm) version of enact:
 
 ```bash
-node -e "['core', 'ui', 'moonstone', 'i18n', 'webos', 'spotlight'].forEach(p => require('.')({
-  package: '../enact/packages/' + p,
-  output: require('fs').writeFileSync,
-  ignore: ['node_modules', 'ilib'],
-  importMap: {
-    ui: '@enact/ui',
-    moonstone: '@enact/moonstone',
-    core: '@enact/core',
-    webos: '@enact/webos',
-    spotlight: '@enact/spotlight',
-    i18n: '@enact/i18n'
-  },
-  outputPath: '<path to installation>/node_modules/@enact/' + p
-}))"
+node -e "import('./index.js').then(({default: jsdocToTs}) => {
+  ['core', 'ui', 'moonstone', 'i18n', 'webos', 'spotlight'].forEach(p => jsdocToTs({
+    package: '../enact/packages/' + p,
+    output: require('fs').writeFileSync,
+    ignore: ['node_modules', 'ilib'],
+    importMap: {
+      ui: '@enact/ui',
+      moonstone: '@enact/moonstone',
+      core: '@enact/core',
+      webos: '@enact/webos',
+      spotlight: '@enact/spotlight',
+      i18n: '@enact/i18n'
+    },
+    outputPath: '<path to installation>/node_modules/@enact/' + p
+  }))
+})"
 ```
-NOTE: Replace `<path to installation>` with the directory you wish to update.
+NOTE: Replace `<path to installation>` with the directory you wish to update. The script requires at least Node.js 13.2.0. or later.
 
 ## Working with Linked Enact
 
 The following command will parse the Enact source into a local `types` directory so you can use TypeScript with linked Enact:
+
 ```bash
-node -e "['core', 'ui', 'moonstone', 'i18n', 'webos', 'spotlight'].forEach(p => require('.')({
-  package: '<path to enact>/packages/' + p,
-  output: (filepath, content) => {
-    const path = require('path');
-    const dir = path.dirname(filepath);
-    const wfs = require('fs').writeFileSync;
-    // recursively create the path to the folder in types
-    require('mkdirp').sync(dir);
-    // write a package.json with a types member pointing to the .d.ts file
-    wfs(path.join(dir, 'package.json'), '{\"types\": \"' + path.basename(filepath) + '\"}');
-    // write the .d.ts file
-    wfs(filepath, content);
-  },
-  importMap: {
-    ui: '@enact/ui',
-    moonstone: '@enact/moonstone',
-    core: '@enact/core',
-    webos: '@enact/webos',
-    spotlight: '@enact/spotlight',
-    i18n: '@enact/i18n'
-  },
-  outputPath: '<path to installation>/types/@enact/' + p
-}))"
+node -e "import('./index.js').then(({default: jsdocToTs}) => {
+    ['core', 'ui', 'moonstone', 'i18n', 'webos', 'spotlight'].forEach(p => jsdocToTs({
+    package: '<path to enact>/packages/' + p,
+    output: (filepath, content) => {
+      const path = require('path');
+      const dir = path.dirname(filepath);
+      const wfs = require('fs').writeFileSync;
+      // recursively create the path to the folder in types
+      require('mkdirp').sync(dir);
+      // write a package.json with a types member pointing to the .d.ts file
+      wfs(path.join(dir, 'package.json'), '{\"types\": \"' + path.basename(filepath) + '\"}');
+      // write the .d.ts file
+      wfs(filepath, content);
+    },
+    importMap: {
+      ui: '@enact/ui',
+      moonstone: '@enact/moonstone',
+      core: '@enact/core',
+      webos: '@enact/webos',
+      spotlight: '@enact/spotlight',
+      i18n: '@enact/i18n'
+    },
+    outputPath: '<path to installation>/types/@enact/' + p
+  }))
+})"
 ```
+NOTE: You may need to install `mkdirp` module in `jsdoc-to-ts` by yourself.
 
 You also have to configure the app to resolve the generated typings by adding the following to the `tsconfig.json`.
 
@@ -75,6 +98,14 @@ You also have to configure the app to resolve the generated typings by adding th
     }
 ```
 
+## Usage with cli option on installation path
+
+Assuming jsdoc-to-ts is installed and linked globally on the current device, and we want to run the command in one of the installed Enact packages (core, ui, i18n, etc.) folder:
+
+```bash
+jsdoc-to-ts --ignore='["node_modules", "ilib", "build", "docs", "tests", "samples"]' --importMap='{"core":"@enact/core","ui":"@enact/ui","spotlight":"@enact/spotlight","i18n":"@enact/i18n","webos":"@enact/webos","moonstone":"@enact/moonstone","agate":"@enact/agate","sandstone":"@enact/sandstone"}' --outputPath='.'
+```
+
 ## Assumptions
 
 Many assumptions, currently:
@@ -88,7 +119,7 @@ Many assumptions, currently:
 Unless otherwise specified, all content, including all source code files and
 documentation files in this repository are:
 
-Copyright (c) 2018-2021 LG Electronics
+Copyright (c) 2018-2023 LG Electronics
 
 Unless otherwise specified or set forth in the NOTICE file, all content,
 including all source code files and documentation files in this repository are:

bin/jsdoc-to-ts.js

@@ -4,19 +4,22 @@
 
 'use strict';
 
-const fs = require('fs');
-const path = require('path');
-const minimist = require('minimist');
-const jsdocToTs = require('..');
+import fs from 'fs';
+import {fileURLToPath} from 'url';
+import path from 'path';
+import minimist from 'minimist';
+import jsdocToTs from '../index.js';
 
 // Uncaught error handler
 process.on('uncaughtException', err => console.error(err.stack));
 
 function displayHelp () {
-	let e = 'node ' + path.relative(process.cwd(), __filename);
-	if (require.main !== module) e = 'jsdoc-to-ts';
+	const modulePath = fileURLToPath(import.meta.url);
+	const pkg = JSON.parse(fs.readFileSync(path.resolve(modulePath + '../../../package.json'), 'utf-8'));
+	let e = 'node ' + path.relative(process.cwd(), modulePath);
+	if (process.argv[1] !== modulePath) e = 'jsdoc-to-ts';
 
-	console.log('  jsdoc-to-ts v' + require('../package.json').version);
+	console.log('  jsdoc-to-ts v' + pkg.version);
 	console.log();
 	console.log('  Usage');
 	console.log(`    ${e} [options] [source]`);
@@ -26,7 +29,9 @@ function displayHelp () {
 	console.log('                      (cwd by default)');
 	console.log();
 	console.log('  Options');
-	console.log('    -o, --output      Output path for .ts files');
+	console.log('    -i, --ignore      paths to be ignored');
+	console.log('    -m, --importMap   packages to be used by each module');
+	console.log('    -o, --outputPath  Output path for .ts files');
 	console.log('                      (cwd by default)');
 	console.log('    -h, --help        Display help information');
 	console.log();
@@ -37,27 +42,31 @@ function displayHelp () {
 // CLI execution mainline
 
 const opts = minimist(process.argv.slice(2), {
-	string: ['output'],
-	default: {output: '.'},
-	alias: {o: 'output', h: 'help'}
+	string: ['help', 'ignore', 'importMap', 'outputPath'],
+	default: {
+		ignore: ['node_modules', 'ilib', 'build', 'dist', 'samples', 'coverage', 'tests'],
+		importMap: {
+			core: '@enact/core',
+			ui: '@enact/ui',
+			spotlight: '@enact/spotlight',
+			i18n: '@enact/i18n',
+			webos: '@enact/webos',
+			moonstone: '@enact/moonstone',
+			'moonstone-ez': '@enact/moonstone-ez',
+			agate: '@enact/agate',
+			sandstone: '@enact/sandstone'
+		},
+		outputPath: '.'
+	},
+	alias: {h: 'help', i: 'ignore', m: 'importMap', o: 'outputPath'}
 });
 
 if (opts.help) displayHelp();
 
 jsdocToTs({
 	package: opts._[0] || '.',
 	output: fs.writeFileSync,
-	ignore: ['node_modules', 'ilib', 'build', 'dist', 'samples', 'coverage', 'tests'],
-	importMap: {
-		core: '@enact/core',
-		ui: '@enact/ui',
-		spotlight: '@enact/spotlight',
-		i18n: '@enact/i18n',
-		webos: '@enact/webos',
-		moonstone: '@enact/moonstone',
-		'moonstone-ez': '@enact/moonstone-ez',
-		agate: '@enact/agate',
-		sandstone: '@enact/sandstone'
-	},
-	outputPath: opts.output
+	ignore: typeof opts.ignore === 'string' ? JSON.parse(opts.ignore) : opts.ignore,
+	importMap: typeof opts.importMap === 'string' ? JSON.parse(opts.importMap) : opts.importMap,
+	outputPath: opts.outputPath
 });

index.js

@@ -1,10 +1,11 @@
-const fs = require('fs');
-const glob = require('glob');
-const path = require('path');
-const log = require('loglevel');
-const prettier = require('prettier');
+import fs from 'fs';
+import glob from 'glob';
+import path from 'path';
+import {build} from 'documentation';
+import log from 'loglevel';
+import prettier from 'prettier';
 
-const {makeParser} = require('./src/parsers');
+import {makeParser} from './src/parsers.js';
 
 const sourceExtension = /\.jsx?$/i;
 
@@ -13,18 +14,17 @@ function isScript (filePath) {
 }
 
 async function parse ({path: modulePath, files, format, importMap, output}) {
-	const documentation = await import('documentation');
-	const encodeModule = makeParser();
+	const encodeModule = await makeParser();
 
 	if (!files || files.length === 0) {
 		log.info(`No source files found for ${modulePath}.`);
 		return;
 	}
 
 	log.info(`Parsing ${modulePath} ...`);
-	documentation.build(files, {shallow: true}).then(
-		(root) => {
-			let result = encodeModule({root, section: root, parent: root, importMap, log}).join('\n');
+	build(files, {shallow: true}).then(
+		async (root) => {
+			let result = (await encodeModule({root, section: root, parent: root, importMap, log})).join('\n');
 			const firstNamedEntry = root.find(entry => entry.name);
 			let moduleName = firstNamedEntry ? firstNamedEntry.name : '';
 
@@ -52,7 +52,7 @@ function getSourceFiles (base, ignore) {
 				.filter(name => !ignore.find(i => name.includes(i)))
 				.map(relativePackageJsonPath => {
 					const packageJsonPath = path.join(base, relativePackageJsonPath);
-					const pkg = require(packageJsonPath);
+					const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
 					const dirPath = path.dirname(path.resolve(path.dirname(packageJsonPath), pkg.main));
 
 					return {
@@ -73,7 +73,7 @@ function isRequired (name) {
 	throw new Error(`${name} is a required argument`);
 }
 
-function main ({
+export default function main ({
 	output = isRequired('output'),
 	ignore = ['node_modules', 'build', 'dist', 'coverage'],
 	package: base = isRequired('package'),
@@ -101,5 +101,3 @@ function main ({
 		});
 	});
 }
-
-module.exports = main;