feat: make this a real thang

Author: Elad Ben-Israel

.projenrc.js

@@ -8,6 +8,9 @@ const project = new TypeScriptLibraryProject({
   authorName: 'Elad Ben-Israel',
   authorEmail: 'benisrae@amazon.com',
   stability: 'experimental',
+  bin: {
+    'jsii-srcmak': 'bin/jsii-srcmak'
+  },
   devDependencies: {
     '@types/node': Semver.caret('13.9.8'),
     '@types/fs-extra': Semver.caret('9.0.1'),

README.md

@@ -1,38 +1,127 @@
 # jsii-srcmak
 
-> Generates jsii source files for multiple languages from TypeScript.
+> Generates [jsii] source files for multiple languages from TypeScript.
+
+[jsii]: https://github.com/aws/jsii
 
 ## Usage
 
-Say I have a TypeScript file `source/index.ts`:
+This package can be either used as a library or through a CLI.
+
+The library entry point is the `srcmak` function:
 
 ```ts
-export interface Operands {
-  readonly lhs: number;
-  readonly rhs: number;
-}
-
-export class Calc {
-  public add(ops: Operands): number {
-    return ops.lhs + ops.rhs;
-  }
+import { srcmak } from 'jsii-srcmak';
+await srcmak(srcdir[, options]);
+```
+
+The CLI is `jsii-srcmak`:
+
+```bash
+$ jsii-srcmak srcdir [OPTIONS]
+```
+
+The `srcdir` argument points to a directory tree that includes TypeScript files
+which will be translated through jsii to one of the supported languages.
+
+### Compile only
+
+If called with no additional arguments, `srcmak` will only jsii-compile the source. If compilation fails, it will throw an error. This is a nice way to check if generated typescript code is jsii-compatible:
+
+```ts
+const srcdir = generateSomeTypeScriptCode();
+
+// verify it is jsii-compatible (throws otherwise)
+await srcmak(srcdir);
+```
+
+CLI:
+
+```bash
+$ jsii-srcmak /source/directory
+```
 
-  public mul(ops: Operands): number {
-    return ops.lhs * opts.rhs;
+### Python Output
+
+To produce a Python module from your source, use the `python` option:
+
+```ts
+await srcmak('srcdir', {
+  python: {
+    outdir: '/path/to/project/root',
+    moduleName: 'name.of.python.module'
   }
-}
+});
+```
+
+Or the `--python-*` switches in the CLI:
+
+```bash
+$ jsii-srcmak /src/dir --python-outdir=dir --python-module-name=module.name
 ```
 
-The following invocation will generate `target/my_python_module` with `Calc` in python:
+* The `outdir`/`--python-outdir` option points to the root directory of your Python project.
+* The `moduleName`/`--python-module-name` option is the python module name. Dots (`.`) delimit submodules.
+
+The output directory will include a python module that corresponds to the
+original module. This code depends on the following python modules:
+
+- [jsii](https://pypi.org/project/jsii/)
+- [publication](https://pypi.org/project/publication/)
+
+### Entrypoint
+
+The `entrypoint` option can be used to customize the name of the typescript entrypoint (default is `index.ts`).
+
+For example, if the code's entry point is under `/srcdir/foobar/lib/index.ts` then I can specify:
 
 ```ts
-import { srcmak } from 'jsii-srcmak';
+await srcmak('/srcdir', {
+  entrypoint: 'foobar/lib/index.ts'
+});
+```
+
+Or through the CLI:
+
+```bash
+$ jsii-srcmak /srcdir --entrypoint lib/main.ts
+```
 
-await srcmak('source', 'target', {
-  pythonName: 'my_python_module'
+### Dependencies
+
+The `deps` option can be used to specify a list of node module **directories** (must have a `package.json` file) which will be symlinked into the workspace when compiling your code.
+
+This is required if your code references types from other modules.
+
+Use this idiom to resolve a set of modules directories from the calling process:
+
+```ts
+const modules = [
+  '@types/node', // commonly needed
+  'foobar'       // a node module in *my* closure
+];
+
+const getModuleDir = m =>
+  path.dirname(require.resolve(`${m}/package.json`));
+
+await srcmak('srcdir', {
+  deps: modules.map(getModuleDir)
 });
 ```
 
+Or through the CLI:
+
+```bash
+$ jsii-srcmak /src/dir --dep node_modules/@types/node --dep node_modules/constructs
+```
+
+## What's with this name?
+
+It's a silly little pun that stems from another pun: jsii has `jsii-pacmak`
+which stands for "package maker". That's the tool that takes in a .jsii manifest
+and produces language-idiomatic *packages* from it. This tool produces *sources*
+from a .jsii manifest. Hence, "source maker". Yeah, it's lame.
+
 ## License
 
 Distributed under the [Apache 2.0](./LICENSE) license.

bin/jsii-srcmak

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('./jsii-srcmak.js');

bin/jsii-srcmak.ts

@@ -0,0 +1,68 @@
+import { srcmak } from '../lib';
+import * as yargs from 'yargs';
+
+async function main() {
+  const args = yargs
+    .usage('$0 SRCDIR [OPTIONS]')
+    .option('entrypoint', { desc: 'typescript entrypoint (relative to SRCDIR)', default: 'index.ts' })
+    .option('dep', { desc: 'node module directories to include in compilation', type: 'array', string: true })
+    .option('jsii-path', { desc: 'write .jsii output to this path', type: 'string' })
+    .option('python-outdir', { desc: 'python output directory (requires --python-module-name)', type: 'string' })
+    .option('python-module-name', { desc: 'python module name', type: 'string' })
+    .showHelpOnFail(true)
+    .help();
+
+  const argv = args.argv;
+
+  if (argv._.length !== 1) {
+    args.showHelp();
+    console.error();
+    console.error('Invalid number of arguments. expecting a single positional argument.');
+    process.exit(1);
+  }
+
+  const srcdir = argv._[0];
+  await srcmak(srcdir, {
+    entrypoint: argv.entrypoint,
+    ...parseDepOption(),
+    ...parseJsiiOptions(),
+    ...parsePythonOptions(),
+  });
+
+  function parseJsiiOptions() {
+    const jsiiPath = argv['jsii-path'];
+    if (!jsiiPath) { return undefined; }
+    return {
+      jsii: {
+        path: jsiiPath,
+      },
+    }
+  }
+
+  function parsePythonOptions() {
+    const outdir = argv['python-outdir'];
+    const moduleName = argv['python-module-name'];
+    if (!outdir && !moduleName) { return undefined; }
+    if (!outdir) { throw new Error('--python-outdir is required if --python-module-name is specified'); }
+    if (!moduleName) { throw new Error('--python-module-name is required if --python-outdir is specified'); }
+    return {
+      python: {
+        outdir: outdir,
+        moduleName: moduleName,
+      },
+    }
+  }
+
+  function parseDepOption() {
+    if (argv.dep?.length === 0) { return undefined; }
+    return {
+      deps: argv.dep,
+    };
+  }
+}
+
+main().catch((e: Error) => {
+  console.error(e.stack);
+  process.exit(1);
+});
+

example/lib/main.ts

@@ -0,0 +1,43 @@
+/**
+ * Math operands
+ */
+export interface Operands {
+  /**
+   * Left-hand side operand
+   */
+  readonly lhs: number;
+
+  /**
+   * Right-hand side operand
+   */
+  readonly rhs: number;
+}
+
+/**
+ * A sophisticaed multi-language calculator
+ */
+export class Calculator {
+  /**
+   * Adds the two operands
+   * @param ops operands
+   */
+  public add(ops: Operands) {
+    return ops.lhs + ops.rhs;
+  }
+
+  /**
+   * Subtracts the two operands
+   * @param ops operands
+   */
+  public sub(ops: Operands) {
+    return ops.lhs - ops.rhs;
+  }
+  
+  /**
+   * Multiplies the two operands
+   * @param ops operands
+   */
+  public mul(ops: Operands) {
+    return ops.lhs * ops.rhs
+  }
+}

lib/compile.ts

@@ -16,11 +16,15 @@ export async function compile(workdir: string, options: Options) {
     throw new Error(`jsii entrypoint must be a .ts file: ${entrypoint}`);
   }
 
+  if (!(await fs.pathExists(path.join(workdir, entrypoint)))) {
+    throw new Error(`unable to find typescript entrypoint: ${path.join(workdir, entrypoint)}`);
+  }
+
   // path to entrypoint without extension
   const basepath = path.join(path.dirname(entrypoint), path.basename(entrypoint, '.ts'));
 
   // jsii modules to include
-  const moduleDirs = options.moduleDirs ?? [];
+  const moduleDirs = options.deps ?? [];
 
   const targets: Record<string, any> = { };
 
@@ -59,14 +63,13 @@ export async function compile(workdir: string, options: Options) {
     peerDependencies: deps,
   };
 
-  if (options.pythonName) {
+  if (options.python) {
     targets.python = {
       distName: 'generated',
-      module: options.pythonName,
+      module: options.python.moduleName,
     };
   }
 
-
   await fs.writeFile(path.join(workdir, 'package.json'), JSON.stringify(pkg, undefined, 2));
 
   await exec(compilerModule, args, {

lib/options.ts

@@ -1,4 +1,4 @@
-export interface CommonOptions {
+export interface Options {
   /**
    * The relative path of the .ts entrypoint within the source directory.
    * @default "index.ts"
@@ -10,20 +10,36 @@ export interface CommonOptions {
    * package. For example, if your generated code references some library, you
    * should include it's module directory in here.
    */
-  moduleDirs?: string[];
+  deps?: string[];
 
   /**
-   * Path to output the .jsii file output.
-   * @default - jsii file is not emitted.
+   * Save .jsii file to an output location.
+   * @default - jsii manifest is omitted.
    */
-  outputJsii?: string;
+  jsii?: JsiiOutputOptions;
+
+  /**
+   * Produce python code.
+   * @default - python is not generated
+   */
+  python?: PythonOutputOptions;
 }
 
-export interface PythonOptions extends CommonOptions {
+export interface JsiiOutputOptions {
   /**
-   * The name of the the python module to generate. If omitted python will not be generated.
+   * Path to save the .jsii output to.
    */
-  pythonName?: string;
+  path: string;
 }
 
-export type Options = PythonOptions; /* | JavaOptions | DotNetOptions */
+export interface PythonOutputOptions {
+  /**
+   * Base root directory.
+   */
+  outdir: string;
+
+  /**
+   * The name of the the python module to generate.
+   */
+  moduleName: string;
+}