@typeslayer/analyze-trace 0.0.0 → 0.1.0

package/src/node-module-paths.ts

@@ -0,0 +1,44 @@
+import {
+  packageNameRegex,
+  type TraceEvent,
+  type TraceJsonSchema,
+} from "@typeslayer/validate";
+import type { NodeModulePaths } from "./utils";
+
+export function getNodeModulePaths(
+  traceJson: TraceJsonSchema,
+): NodeModulePaths {
+  const nodeModulePaths: NodeModulePaths = {};
+  traceJson.forEach((event: TraceEvent) => {
+    if (event.name !== "findSourceFile") {
+      return;
+    }
+    const path = event.args.fileName;
+    if (path) {
+      while (true) {
+        const match = packageNameRegex.exec(path);
+        if (!match) {
+          break;
+        }
+        const packageName = match[1];
+
+        const packagePath = match.input.substring(
+          0,
+          match.index + match[0].length,
+        );
+
+        if (packageName in nodeModulePaths) {
+          const paths = nodeModulePaths[packageName];
+          if (paths && paths.indexOf(packagePath) < 0) {
+            // Usually contains exactly one element
+            paths.push(packagePath);
+          }
+        } else {
+          nodeModulePaths[packageName] = [packagePath];
+        }
+      }
+    }
+  });
+
+  return nodeModulePaths;
+}

package/src/spans.ts

@@ -0,0 +1,137 @@
+import {
+  eventPhase,
+  type TraceEvent,
+  type TraceJsonSchema,
+} from "@typeslayer/validate";
+import type {
+  AnalyzeTraceOptions,
+  EventSpan,
+  Microseconds,
+  ParseResult,
+} from "./utils";
+
+/*
+ * This function takes an array of trace events and converts them into spans.
+ */
+export function createSpans(traceFile: TraceJsonSchema): ParseResult {
+  // Sorted in increasing order of start time (even when below timestamp resolution)
+  const unclosedStack: TraceEvent[] = [];
+
+  // Sorted in increasing order of end time, then increasing order of start time (even when below timestamp resolution)
+  const spans: EventSpan[] = [];
+
+  traceFile.forEach((event: TraceEvent) => {
+    switch (event.ph) {
+      case eventPhase.begin:
+        unclosedStack.push(event);
+        return;
+
+      case eventPhase.end: {
+        const beginEvent = unclosedStack.pop();
+        if (!beginEvent) {
+          throw new Error("Unmatched end event");
+        }
+        spans.push({
+          event: beginEvent,
+          start: beginEvent.ts,
+          end: event.ts,
+          duration: event.ts - beginEvent.ts,
+          children: [],
+        });
+        break;
+      }
+
+      case eventPhase.complete: {
+        const start = event.ts;
+        const duration = event.dur ?? 0;
+        spans.push({
+          event,
+          start,
+          end: start + duration,
+          duration,
+          children: [],
+        });
+        break;
+      }
+
+      case eventPhase.instantGlobal:
+      case eventPhase.metadata:
+        return;
+
+      default:
+        event satisfies never;
+    }
+  });
+
+  const parseResult: ParseResult = {
+    firstSpanStart: Math.min(...spans.map(span => span.start)),
+    lastSpanEnd: Math.max(...spans.map(span => span.end)),
+    spans,
+    unclosedStack,
+  };
+  return parseResult;
+}
+
+export function createSpanTree(
+  parseResult: ParseResult,
+  options: AnalyzeTraceOptions,
+): EventSpan {
+  const { firstSpanStart, lastSpanEnd, spans, unclosedStack } = parseResult;
+
+  // Add unclosed events to the spans
+  for (let i = unclosedStack.length - 1; i >= 0; i--) {
+    const event = unclosedStack[i];
+    const start = event.ts;
+    const end = lastSpanEnd;
+    spans.push({
+      event,
+      start,
+      end,
+      duration: end - start,
+      children: [],
+    });
+  }
+
+  spans.sort((a, b) => a.start - b.start);
+
+  const root: EventSpan = {
+    event: {
+      name: "root",
+      cat: "program",
+    },
+    start: firstSpanStart,
+    end: lastSpanEnd,
+    duration: lastSpanEnd - firstSpanStart,
+    children: [],
+  };
+  const stack = [root];
+
+  for (const span of spans) {
+    let i = stack.length - 1;
+    for (; i > 0; i--) {
+      // No need to check root at stack[0]
+      const curr = stack[i];
+      if (curr.end > span.start) {
+        // Pop down to parent
+        stack.length = i + 1;
+        break;
+      }
+    }
+
+    /** Microseconds */
+    const thresholdDuration: Microseconds = options.forceMillis * 1000;
+    const isAboveThresholdDuration = span.duration >= thresholdDuration;
+
+    const parent = stack[i];
+    const parentDuration = parent.end - parent.start;
+    const isSignificantPortionOfParent =
+      span.duration >= parentDuration * options.minSpanParentPercentage;
+
+    if (isAboveThresholdDuration || isSignificantPortionOfParent) {
+      parent.children.push(span);
+      stack.push(span);
+    }
+  }
+
+  return root;
+}

package/src/utils.ts

@@ -0,0 +1,185 @@
+import { existsSync } from "node:fs";
+import { stat } from "node:fs/promises";
+import {
+  event_checktypes__checkCrossProductUnion_DepthLimit,
+  event_checktypes__checkTypeRelatedTo_DepthLimit,
+  event_checktypes__getTypeAtFlowNode_DepthLimit,
+  event_checktypes__instantiateType_DepthLimit,
+  event_checktypes__recursiveTypeRelatedTo_DepthLimit,
+  event_checktypes__removeSubtypes_DepthLimit,
+  event_checktypes__traceUnionsOrIntersectionsTooLarge_DepthLimit,
+  event_checktypes__typeRelatedToDiscriminatedType_DepthLimit,
+  resolvedType,
+  traceEvent,
+} from "@typeslayer/validate";
+import { z } from "zod/v4";
+
+export const absolutePath = z.string().refine(
+  path => {
+    return (
+      path.startsWith("/") || path.startsWith("C:\\") || path.startsWith("D:\\")
+    );
+  },
+  {
+    message: "Path must be absolute",
+  },
+);
+export type AbsolutePath = z.infer<typeof absolutePath>;
+
+export const project = z.object({
+  configFilePath: absolutePath.optional(),
+  tracePath: absolutePath,
+  typesPath: absolutePath,
+});
+export type Project = z.infer<typeof project>;
+
+export const projectResult = z.object({
+  project: project,
+  stdout: z.string(),
+  stderr: z.string(),
+  exitCode: z.number().optional(),
+  signal: z.enum(["SIGINT", "SIGTERM"]).optional(),
+});
+export type ProjectResult = z.infer<typeof projectResult>;
+
+export const hotType = z.object({
+  resolvedType: resolvedType,
+  get children() {
+    return z.array(hotType);
+  },
+});
+export type HotType = z.infer<typeof hotType>;
+
+export const hotSpot = z.object({
+  description: z.string(),
+  timeMs: z.number(),
+  get children() {
+    return z.array(hotSpot);
+  },
+
+  path: absolutePath.optional(),
+  types: z.array(hotType).optional(),
+  startLine: z.number().optional(),
+  startChar: z.number().optional(),
+  startOffset: z.number().optional(),
+  endLine: z.number().optional(),
+  endChar: z.number().optional(),
+  endOffset: z.number().optional(),
+});
+export type HotSpot = z.infer<typeof hotSpot>;
+
+export const duplicatedPackageInstance = z.object({
+  path: absolutePath,
+  version: z.string(),
+});
+export type DuplicatedPackageInstance = z.infer<
+  typeof duplicatedPackageInstance
+>;
+
+export const duplicatedPackage = z.object({
+  name: z.string(),
+  instances: z.array(duplicatedPackageInstance),
+});
+export type DuplicatedPackage = z.infer<typeof duplicatedPackage>;
+
+export const rootSpan = z.object({
+  name: z.literal("root"),
+  cat: z.literal("program"),
+});
+export type RootSpan = z.infer<typeof rootSpan>;
+
+export const eventSpan = z.object({
+  event: z.union([traceEvent, rootSpan]),
+  start: z.number(),
+  end: z.number(),
+  duration: z.number(),
+  get children() {
+    return z.array(eventSpan);
+  },
+});
+export type EventSpan = z.infer<typeof eventSpan>;
+
+export const microseconds = z.number();
+export type Microseconds = z.infer<typeof microseconds>;
+
+export const packageName = z.string();
+
+export const packagePath = z.string();
+
+export const nodeModulePaths = z.record(packageName, z.array(packagePath));
+/** This is a map where the key corresponds to an NPM package and the value is an array of all files in that package that were used */
+export type NodeModulePaths = z.infer<typeof nodeModulePaths>;
+
+export const parseResult = z.object({
+  firstSpanStart: z.number(),
+  lastSpanEnd: z.number(),
+  spans: z.array(eventSpan),
+  unclosedStack: z.array(traceEvent),
+});
+export type ParseResult = z.infer<typeof parseResult>;
+
+export const analyzeTraceOptions = z.object({
+  /** Events of at least this duration (in milliseconds) will reported unconditionally */
+  forceMillis: z.number(),
+  /** Events of less than this duration (in milliseconds) will suppressed unconditionally */
+  skipMillis: z.number(),
+  /** Expand types when printing */
+  expandTypes: z.boolean(),
+  /** force showing spans that are some percentage of their parent, independent of parent time */
+  minSpanParentPercentage: z.number(),
+  /** the minimum number of emitted imports from a declaration file or bundle */
+  importExpressionThreshold: z.number(),
+});
+export type AnalyzeTraceOptions = z.infer<typeof analyzeTraceOptions>;
+
+export const isFile = async (path: string) => {
+  return stat(path)
+    .then(stats => stats.isFile())
+    .catch(_ => false);
+};
+
+export const throwIfNotDirectory = async (path: string) => {
+  if (!existsSync(path) || !(await stat(path))?.isDirectory()) {
+    throw new Error(`${path} is not a directory`);
+  }
+  return path;
+};
+
+export const analyzeTraceResult = z.object({
+  /** Events that were not closed */
+  unterminatedEvents: z.array(traceEvent),
+  /** Hot spots in the trace */
+  hotSpots: z.array(hotSpot),
+  /** Packages that are duplicated in the trace */
+  duplicatePackages: z.array(duplicatedPackage),
+  /** Paths to all node modules used in the trace */
+  nodeModulePaths: nodeModulePaths,
+  /** Depth limit events grouped by their event name */
+  depthLimits: z.object({
+    checkCrossProductUnion_DepthLimit: z.array(
+      event_checktypes__checkCrossProductUnion_DepthLimit,
+    ),
+    checkTypeRelatedTo_DepthLimit: z.array(
+      event_checktypes__checkTypeRelatedTo_DepthLimit,
+    ),
+    getTypeAtFlowNode_DepthLimit: z.array(
+      event_checktypes__getTypeAtFlowNode_DepthLimit,
+    ),
+    instantiateType_DepthLimit: z.array(
+      event_checktypes__instantiateType_DepthLimit,
+    ),
+    recursiveTypeRelatedTo_DepthLimit: z.array(
+      event_checktypes__recursiveTypeRelatedTo_DepthLimit,
+    ),
+    removeSubtypes_DepthLimit: z.array(
+      event_checktypes__removeSubtypes_DepthLimit,
+    ),
+    traceUnionsOrIntersectionsTooLarge_DepthLimit: z.array(
+      event_checktypes__traceUnionsOrIntersectionsTooLarge_DepthLimit,
+    ),
+    typeRelatedToDiscriminatedType_DepthLimit: z.array(
+      event_checktypes__typeRelatedToDiscriminatedType_DepthLimit,
+    ),
+  }),
+});
+export type AnalyzeTraceResult = z.infer<typeof analyzeTraceResult>;

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "outDir": "dist",
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "target": "ES2024",
+    "strict": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true
+  },
+  "include": ["**/*.ts"]
+}

package/tsup.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["esm"],
+  target: "es2024",
+  dts: true,
+  splitting: true,
+  sourcemap: true,
+  clean: true,
+});