@typeslayer/analyze-trace 0.0.0 → 0.1.10

package/README.md

@@ -0,0 +1,81 @@
+# @typeslayer/analyze-trace
+
+Analyze TypeScript compiler trace events to identify performance bottlenecks and compilation hot spots.
+
+Initially, this started as a full rewrite of [@typescript/analyze-trace](https://github.com/microsoft/typescript-analyze-trace)*.  That rewrite was successful, and new features were added during the development of [TypeSlayer](https://github.com/dimitropoulos/typeslayer) (where it was rewritten a second time in Rust).
+
+> \* <sub>why did it need a full rewrite?<br /><br />well.. it's been unmaintained for many years and also I <a href="https://github.com/dimitropoulos">dimitropoulos</a> wanted to learn every detail of how it works.  academically speaking, rewrites are great for that.  when I looked deeper, though I saw some exceedingly interesting things (like some of the instantaneous events for type limits) that the original tool completely ignores (<a href="https://github.com/microsoft/typescript-analyze-trace/issues/1">sometimes intentionally</a>), yet some are actually quite fundamental to the goal of TypeSlayer!<br /><br /> also the original was intended as a end-of-the-pipeline CLI tool (giving nice human readable format, but only experimental JSON support) and the rewrite is though of as a middle-of-the-pipeline tool (1st-class JSON support). </sub>
+
+## CLI Usage
+
+```bash
+tsc --generateTrace ./trace-json-path
+npx @typeslayer/analyze-trace trace-json-path
+```
+
+### Examples
+
+```bash
+# Analyze a trace file
+typeslayer-analyze-trace ./trace.json
+
+# With custom output
+typeslayer-analyze-trace ./dist/trace.json > analysis.json
+```
+
+## Programmatic Usage
+
+```ts
+import { analyzeTrace } from '@typeslayer/analyze-trace';
+import { readFileSync } from 'fs';
+
+// Read and parse trace
+const traceJson = JSON.parse(readFileSync('trace.json', 'utf-8'));
+
+// Analyze
+const result = analyzeTrace(traceJson);
+
+console.log('Hot spots:', result.hotSpots);
+console.log('Depth limits:', result.depthLimits);
+console.log('Duplicate packages:', result.duplicatePackages);
+```
+
+## Analysis Output
+
+The analyzer provides:
+
+### Hot Spot Detection
+
+This is a sliding scale that looks at the events that consumed the most time during compilation.  It's not a given that because something is hot it's necessarily _bad_.  But, the thinking is, if you see something that's much more intensive than something else, it's worth flagging.  So.  There you go.
+
+### Duplicate Package Detection
+
+Package versions appearing in multiple locations from the same package.  This is one of those things that people often have no idea is going on, but in reality most projects have this problem.  Well.  "problem" might be a strong word.  Similar to [Hot Spot Detection](#hot-spot-detection), you'll have to use your judgement here to decide whether it's a big deal or not.  That's largely going to depend on the size/scale/usage of the thing that's duplicated.
+
+### Unterminated Events
+
+In a perfect world, all events created by TypeScript's trace machinery should be terminated.  What's that mean?  Think of it like a missing JSX closing tag.  The thinking here is that if that ever happens, it's guaranteed to be a symptom of something else being wrong - so the tool flags it.
+
+### Depth Limits (unique to `@typeslayer/analyze-trace`)
+
+Type-level limits that were hit during the type checking, including:
+
+| Depth Limit                                     | Error Triggered                                                                                                                                                                             |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `checkCrossProductUnion_DepthLimit`             | triggers `TS(2590) Expression produces a union type that is too complex to represent.`                                                                                                      |
+| `checkTypeRelatedTo_DepthLimit`                 | triggers `TS(2859) Excessive complexity comparing types '{0}' and '{1}'.` or `TS(2321) Excessive stack depth comparing types '{0}' and '{1}'.`                                              |
+| `getTypeAtFlowNode_DepthLimit`                  | triggers `TS(2563) The containing function or module body is too large for control flow analysis.`                                                                                          |
+| `instantiateType_DepthLimit`                    | triggers `TS(2589) Type instantiation is excessively deep and possibly infinite.`                                                                                                           |
+| `recursiveTypeRelatedTo_DepthLimit`             | This is not currently considered a hard error by the compiler and therefore does not report to the user (unless you're a [TypeSlayer](https://github.com/dimitropoulos/typeslayer) user 😉). |
+| `removeSubtypes_DepthLimit`                     | triggers `TS(2590) Expression produces a union type that is too complex to represent.`                                                                                                      |
+| `traceUnionsOrIntersectionsTooLarge_DepthLimit` | This is not currently considered a hard error by the compiler and therefore does not report to the user (unless you're a [TypeSlayer](https://github.com/dimitropoulos/typeslayer) user 😉). |
+| `typeRelatedToDiscriminatedType_DepthLimit`     | This is not currently considered a hard error by the compiler and therefore does not report to the user (unless you're a [TypeSlayer](https://github.com/dimitropoulos/typeslayer) user 😉). |
+
+### Type Graph
+
+> _note_:
+> As fate would have it, when [TypeSlayer](https://github.com/dimitropoulos/typeslayer) moved from Node.js to Rust to be a Tauri app, this entire package was _again_ rewritten in Rust.  Since this version was fully up-and-running first, and the original has some issues, I decided to just not delete this and publish it in case others stuck in the Node ecosystem (🪦) find it useful.
+>
+> This particular feature is only in the Rust version.  If you'd like a wasm-build of it or something lemme know.
+
+This is the thing that powers the [TypeSlayer](https://github.com/dimitropoulos/typeslayer) "Type Graph".  It basically takes the `types.json` output and combines it with the information in the `trace.json` to create a list of relations (of various sorts) between all the types in your project.  It also compiles stats for records like "biggest union" and "most commonly included in an intersection" and literally over a doze more like that.

package/bin/typeslayer-analyze-trace.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+import { statSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import process, { exit } from "node:process";
+import { ANALYZE_TRACE_FILENAME, analyzeTrace, defaultOptions } from "../dist/index.js";
+
+const { argv } = process;
+
+const traceDirArg = argv[2];
+
+if (!traceDirArg) {
+	console.error("Gotta give a trace directory, brah.");
+	exit(1);
+}
+
+const traceDir = resolve(traceDirArg);
+
+try {
+	const stat = statSync(traceDir);
+	if (!stat.isDirectory()) {
+		console.error(`Trace directory "${traceDir}" is not a directory.`);
+		exit(1);
+	}
+} catch (err) {
+	if (err.code === "ENOENT") {
+		console.error(`Trace directory "${traceDir}" does not exist.`);
+	} else {
+		console.error(
+			`Error checking trace directory "${traceDir}": ${err.message}`,
+		);
+	}
+	exit(1);
+}
+
+console.log({ traceDir });
+
+analyzeTrace({ traceDir, options: defaultOptions }).then((result) => {
+	const destination = resolve(traceDir, ANALYZE_TRACE_FILENAME);
+	writeFileSync(destination, JSON.stringify(result, null, 2), "utf-8");
+	console.log("Analysis result:", result);
+});