@yumemi-inc/statictrace - npm Package Compare versions

Comparing version 1.0.0-beta.14 to 1.0.0-beta.15

package.json

 {
   "name": "@yumemi-inc/statictrace",
-  "version": "1.0.0-beta.14",
+  "version": "1.0.0-beta.15",
   "description": "A library for semi-automatic static testing.",
@@ -5,0 +5,0 @@ "keywords": [

README.JP.md

@@ -7,6 +7,12 @@ # statictrace
 
-## Usage
+## Installation
 
-現在は、ソースからビルドする以外の使用方法がありません。
+### Install
 
+`npm install @yumemi-inc/statictrace`
+
+`statictrace`はプロジェクトごとにインストールできるし、グローバルなパッケージとしてもインストールできます。
+
+### Build from source
+
 ```
@@ -17,13 +23,12 @@ pnpm install
 
-### Use as CLI
+### `ts-node`
 
 ```
-pnpm run build
-pnpm run parse -- -p /absolute/path/to/tsconfig.json
+`pnpx ts-node src/lib.ts -p /absolute/path/to/tsconfig.json`
 ```
 
-`ts-node`の場合:
+### Use as CLI
 
 ```
-`pnpx ts-node src/lib.ts -p /absolute/path/to/tsconfig.json`
+statictrace -- -p /absolute/path/to/tsconfig.json
 ```
@@ -33,2 +38,6 @@
 
+```
+TS_PROJECT_CONFIG=/absolute/path/to/tsconfig.json
+```
+
 **その他のオプション**
@@ -38,6 +47,62 @@
 
+### 使い方
+
+`statictrace`は、開発者が特殊なコメントでヒントした箇所からコードの静的な分析をはじめる。例えば以下のように登録フローを分析するために、フローがはじまることを表すヒント (`@entrypoint フローの名前`) を関数に JSDoc 形式で追加します。
+
+```ts
+/**
+ * @entrypoint Registration
+ */
+function startRegistration() {
+  processRegistration();
+  finishRegistration();
+  untracedFunction();
+  cleanupSomething();
+}
 ```
-TS_PROJECT_CONFIG=/absolute/path/to/tsconfig.json
+
+これだけでは何もアウトプットされないが、`statictrace` は `startRegistration()` の中で呼ばれる関数やメソッドをすべて把握します。開発者がテストやドキュメントの目的で、呼び出しの有無・順番・親子関係を記録したい場合は、気になる関数とメソッドだけ別の特殊なヒントでマークできる。そのヒントは `@trace`。
+
+```ts
+/** @trace */
+function processRegistration() {
+  someRegistrationProcedure();
+}
 ```
 
+これで `statictrace` を実行すると以下のアウトプットが得られる：
+
+```
+Entrypoint: Registration
+startRegistration
+        processRegistration
+                someRegistrationProcedure
+```
+
+このアウトプットをスナップショットのように使って、好みのテストライブラリでリファクタリング前と後の差分でフローが変わっていないことを保証できる。または [`mermaid`](https://mermaid-js.github.io/mermaid/#/) として結果をアウトプットできる（以下に画像がある）。
+
+### 例
+
+- デバッガーのスタックトレースのようにインデントされたテキストとしてアウトプットする：
+
+```sh
+$ statictrace
+
+=======================
+Entrypoint: SomeEntrypoint
+begin
+        funcA
+                funcC
+        beingNestedEntrypoint
+                funcA
+                        funcC
+                funcB
+        funcB
+```
+
+- mermaid グラフとしてマークダウンファイルにアウトプットする: `statictrace -u mermaid > graphs.md`
+
+この場合のグラフが以下のように表示されます：
+![mermaid](./assets/mermaid.png)
+
 ### Use API programmatically
@@ -47,14 +112,8 @@
 const { run } = require('./build/lib');
-const output = run('/absolute/path/to/tsconfig.json');
+const output = run('/absolute/path/to/tsconfig.json', 'text');
 // ...do something with output
 ```
 
-#### `run(pathToTsConfig: string, printer?: Printer): any`
+#### `run(pathToTsConfig: string, printerType: "text" | "mermaid"): any`
 
-全てのプロジェクトのファイルをロードし、`@entrypoint`か`@trace`でマークされている全ての関数のコールのグラフを作る。`Printer`は、グラフをプリント（なんらかの方法で表示できる）ことを表すインターフェースで、そのインターフェースを implement したものならなんでもオプショナルな引数として渡すことができます。何も渡さなかった場合は、解析の結果を`TextPrinter`が文字列として戻します。
-
-```ts
-interface Printer {
-  print(graph: Into<Printable>): any;
-}
-```
+全てのプロジェクトのファイルをロードし、`@entrypoint`か`@trace`でマークされている全ての関数のコールのグラフを作る。第二の引数としてプリンタータイプを指定する。プリンターというのは静的分析の結果をなんらかの形で表示できるインターフェースを指します。現在、独自の実装は不可能で、デフォルトのタイプから選択する必要がある。

README.md

@@ -9,6 +9,12 @@ # statictrace
 
-## Usage
+## Installation
 
-Currently you can only use this tool by building it from source.
+### Install
 
+`npm install @yumemi-inc/statictrace`
+
+You can install `statictrace` either per-project or globally.
+
+### Build from source
+
 ```
@@ -19,6 +25,6 @@ pnpm install
 
-With `ts-node`:
+### `ts-node`:
 
 ```
-`pnpx ts-node src/lib.ts -p /absolute/path/to/tsconfig.json`
+pnpx ts-node src/lib.ts -p /absolute/path/to/tsconfig.json
 ```
@@ -35,2 +41,6 @@
 
+```
+TS_PROJECT_CONFIG=/absolute/path/to/tsconfig.json
+```
+
 **Other options**
@@ -40,10 +50,63 @@
 
-**Examples**
+## Usage
 
-- Output the result printed as mermaid graphs to a markdown file: `pnpm run parse -- -u mermaid > graphs.md`
+`statictrace` begins static analysis of your code from a point that is explicitly hinted by a developer. For example, if you want to analyse the registration flow like below, you need to add a JSDoc hint to the function where the flow begins: `@entrypoint YourFlowName`.
 
+```ts
+/**
+ * @entrypoint Registration
+ */
+function startRegistration() {
+  processRegistration();
+  finishRegistration();
+  untracedFunction();
+  cleanupSomething();
+}
 ```
-TS_PROJECT_CONFIG=/absolute/path/to/tsconfig.json
+
+Just doing this produces no output but `statictrace` internally tracks all function and method calls that occur within `startRegistration()` and every function calls within those functions until there are no calls. In other words, it builds a static stacktrace. If there are any particular functions and methods that you want to test or document, for example to know whether some functions are called, their call order and parent/child relationship, you need to mark relevant functions with another special comment: `@trace`.
+
+```ts
+/** @trace */
+function processRegistration() {
+  someRegistrationProcedure();
+}
 ```
 
+With this `statictrace` produces the following output:
+
+```
+Entrypoint: Registration
+startRegistration
+        processRegistration
+                someRegistrationProcedure
+```
+
+You can use this output as a snapshot of a stacktrace, and use it from your testing library of choice to guarantee that the flow does not change after e.g. refactoring. You can also output the stacktrace as [`mermaid`](https://mermaid-js.github.io/mermaid/#/) graphs for documentation purposes (see picture below).
+
+## Examples
+
+- Output the result as indented text similar to a debugger stacktrace:
+
+```sh
+$ statictrace
+
+=======================
+Entrypoint: SomeEntrypoint
+begin
+        funcA
+                funcC
+        beingNestedEntrypoint
+                funcA
+                        funcC
+                funcB
+        funcB
+```
+
+- Output the result printed as mermaid graphs to a markdown file: `statictrace -u mermaid > graphs.md`
+
+This is how rendered mermaid graphs look like:
+
+![mermaid](./assets/mermaid.png)
+
 ### Use API programmatically
@@ -53,3 +116,3 @@
 const { run } = require('./build/lib');
-const output = run('/absolute/path/to/tsconfig.json');
+const output = run('/absolute/path/to/tsconfig.json', 'text');
 // ...do something with output
@@ -56,0 +119,0 @@ ```

No alert changes

Improved metrics

Total package byte prevSize

19744

increased by27.41%

Number of lines in readme file

119

increased by112.5%

No dependency changes