Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jeremiah-shaulov/tsa

Typescript source code analysis and documentation tool
https://github.com/jeremiah-shaulov/tsa

Last synced: about 2 months ago
JSON representation

Typescript source code analysis and documentation tool

Awesome Lists containing this project

README 

        



# tsa - Typescript source code analysis and documentation tool



[Documentation Index](generated-doc/README.md)



Extension to `tsc` that adds custom file loader, and documentation generator.

It can be used as command-line tool, or programmatically as Typescript library.



The original [Typescript Compiler](https://www.npmjs.com/package/typescript) can load Typescript programs or modules from source files,

and parse them to syntax nodes. This allows to analyze the project, or to bundle it to a single Javascript file.



However `tsc` cannot load files from HTTP URLs as Deno does.



This library solves this issue by adding custom file loader. Also it adds facility to generate syntax nodes in less raw format, so the project structure

can be easily analyzed. The nodes this library produces are compatible with [x/deno\[email protected]](https://deno.land/x/[email protected]).

Also this library can bundle Typescript project to single Typescript file (not only Javascript), and to generate project documentation in Markdown format.



## Using as command-line tool



To install this tool do:



```bash

deno install --global --allow-env --allow-net --allow-read --allow-write https://deno.land/x/[email protected]/tsa.ts

```



The command supports 5 operations:

- `tsa doc-json` (alias: `tsa doc`) - generate JSON AST (abstract syntax tree) that contains functions and classes of the project together with their doc-comments.

- `tsa doc-md` - generate documentation in Markdown format.

- `tsa bundle-js` (alias: `tsa bundle`) - generate `.js` bundle that contains all the files of the project as single ECMA module or program.

- `tsa bundle-ts` - generate `.ts` bundle.

- `tsa types` - generate `.d.ts` file with type declarations.



### tsa doc-json [options]  [fileN.ts...]



Generate JSON AST suitable for further documentation generation.



Options:

- `--outFile ` - Where to save the result (default: stdout).

- `--pretty` - Produce human-readable JSON.



Example:

```bash

tsa doc-json --pretty --outFile=/tmp/doc.json jsr:@std/bytes

```



### tsa doc-md [options]  [fileN.ts...]



Generate documentation in markdown format.



Options:

- `--outFile ` (required) - Where to save the result.

- `--outDir ` - This command also creates linked README.md files in the --outDir directory (default: "generated-doc").

The directory will be created near --outFile or existing directory will be emptied if necessary.

- `--mainTitle ` - The title that will appear in the main README.md file.

- `--importUrl ` - Optionally specify one such flag per each source file in corresponding order.

This lets including in the documentation import examples for public symbols.

The specified importUrl must point to a public registry that downloads (or will download) the same file as provided to the generator.

For example: `tsa doc-md foo/mod.ts --importUrl https://deno.land/[email protected]/mod.ts bar/mod.ts --importUrl https://deno.land/[email protected]/mod.ts`

(the number of --importUrl options must be the same as number of given files).

- `--outUrl ` - If you plan to upload the resulting files to a public resource (such as github),

you can optionally specify URL by which the --outFile will be publicly accessible.

Then you can use script examples in doc-comments marked as `// To run this example:` on the first line,

and followed by a line that contains "example.ts", like `// deno run --allow-all example.ts`, and these lines will be converted to `// To download and run this example:`...



Example:

```bash

mkdir -p /tmp/tsa-test

tsa doc-md --mainTitle 'Standard bytes library' --outFile=/tmp/tsa-test/README.md jsr:@std/bytes

```



### tsa bundle-js [options]  [fileN.ts...]



Bundle Typescript source files to single Javascript module.



Options:

- `--outFile ` - Where to save the result (default: stdout).

- `--target ` - Target JavaScript version. One of: ES2015, ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext (default: ESNext).



Example:

```bash

tsa bundle --outFile=/tmp/bytes.js jsr:@std/bytes

```



### tsa bundle-ts [options]  [fileN.ts...]



Bundle Typescript source files to single `.ts` module.



Options:

- `--outFile ` - Where to save the result (default: stdout).

- `--target ` - Target JavaScript version. One of: ES2015, ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext (default: ESNext).



Example:

```bash

tsa bundle-ts --outFile=/tmp/bytes.ts jsr:@std/bytes

```



### tsa types [options]  [fileN.ts...]



Generate type declarations file (DTS).



Options:

- `--outFile ` - Where to save the result (default: stdout).



## Using as Typescript library



This library internally uses the official [Typescript Compiler](https://www.npmjs.com/package/typescript),

and reexports it's namespace as [tsa](generated-doc/namespace.tsa/README.md) symbol. This namespace contains all of the `ts` namespace,

plus this library extends it by defining [createTsaProgram](generated-doc/function.createTsaProgram/README.md) function within this namespace.



When using [Typescript Compiler](https://www.npmjs.com/package/typescript),

the first step is to create [ts.Program](generated-doc/interface.Program/README.md) by calling [ts.createProgram()](generated-doc/function.createProgram/README.md) function.

Similarly when using this library, the first step is to create [tsa.TsaProgram](generated-doc/interface.TsaProgram/README.md) object by calling [tsa.createTsaProgram()](generated-doc/function.createTsaProgram/README.md).



```ts

// To download and run this example:

// curl 'https://raw.githubusercontent.com/jeremiah-shaulov/tsa/v0.0.39/README.md' | perl -ne '$y=$1 if /^```(.)?/;  print $_ if $y&&$m;  $m=$y&&($m||m~~)' > /tmp/example-p9mn.ts

// deno run --allow-env --allow-net --allow-read --allow-write /tmp/example-p9mn.ts



import {tsa, printDiagnostics, LoadOptions} from 'https://deno.land/x/[email protected]/mod.ts';



const SUBJ = 'https://deno.land/x/[email protected]/mod.ts'; // Can be local file (`file:///...`)



// Options for typescript compiler.

// To generate docs, set `declaration` and `emitDeclarationOnly`.

// To bundle leave blank.

const compilerOptions: tsa.CompilerOptions =

{	declaration: true,

	emitDeclarationOnly: true,

};



// Configures how to resolve module specifiers, and how to load module contents.

const loadOptions: LoadOptions =

{

};



// Create typescript program

const program = await tsa.createTsaProgram([SUBJ], compilerOptions, loadOptions);



// Print errors and warnings (if any)

printDiagnostics(tsa.getPreEmitDiagnostics(program));



// Now use the `program` object...

```



[tsa.TsaProgram](generated-doc/interface.TsaProgram/README.md) extends [ts.Program](generated-doc/interface.Program/README.md) by adding 2 methods:

- [tsa.TsaProgram.emitDoc()](generated-doc/interface.TsaProgram/README.md#-emitdocoptions-emitdocoptions-docnodes)

- [tsa.TsaProgram.emitTsaBundle()](generated-doc/interface.TsaProgram/README.md#-emittsabundle-tsabundle)



The purpose of this library is to provide these 2 methods.