refactor: 重构项目结构，将 tracer 模块提取为独立子包

- 将 tracer 相关代码移动到 tracers.ts 子目录中
- 新增类型定义文件，统一管理命令类型
- 实现上下文管理机制，集中处理 tracer 命令
- 更新构建配置和依赖管理
- 移除旧的根目录文件，保持代码结构清晰

tracers.ts/.gitignore

@@ -0,0 +1,34 @@
+# dependencies (bun install)
+node_modules
+
+# output
+out
+dist
+*.tgz
+
+# code coverage
+coverage
+*.lcov
+
+# logs
+logs
+_.log
+report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# caches
+.eslintcache
+.cache
+*.tsbuildinfo
+
+# IntelliJ based IDEs
+.idea
+
+# Finder (MacOS) folder config
+.DS_Store

tracers.ts/README.md

@@ -0,0 +1,15 @@
+# tracers.ts
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+To run:
+
+```bash
+bun run src/index.ts
+```
+
+This project was created using `bun init` in bun v1.3.4. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.

tracers.ts/bun.lock

@@ -0,0 +1,26 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "tracers.ts",
+      "devDependencies": {
+        "@types/bun": "latest",
+      },
+      "peerDependencies": {
+        "typescript": "^5",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.8", "", { "dependencies": { "bun-types": "1.3.8" } }, "sha512-3LvWJ2q5GerAXYxO2mffLTqOzEu5qnhEAlh48Vnu8WQfnmSwbgagjGZV6BoHKJztENYEDn6QmVd949W4uESRJA=="],
+
+    "@types/node": ["@types/node@25.2.0", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-DZ8VwRFUNzuqJ5khrvwMXHmvPe+zGayJhr2CDNiKB1WBE1ST8Djl00D0IC4vvNmHMdj6DlbYRIaFE7WHjlDl5w=="],
+
+    "bun-types": ["bun-types@1.3.8", "", { "dependencies": { "@types/node": "*" } }, "sha512-fL99nxdOWvV4LqjmC+8Q9kW3M4QTtTR1eePs94v5ctGqU8OeceWrSUaRw3JYb7tU3FkMIAjkueehrHPPPGKi5Q=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+  }
+}

tracers.ts/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "tracers.ts",
+  "module": "src/index.ts",
+  "type": "module",
+  "private": true,
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

tracers.ts/src/context/index.ts

@@ -0,0 +1 @@
+export * from './tracer-context';

tracers.ts/src/context/tracer-context.ts

@@ -0,0 +1,22 @@
+import type { TracerCommand } from '../types';
+
+const createTracerContext = () => {
+  const commands: TracerCommand[] = [];
+
+  const getTracerContext = () => {
+    const command = (command: TracerCommand) => {
+      commands.push(command);
+    };
+
+    return {
+      commands,
+      command,
+    };
+  };
+
+  return {
+    getTracerContext,
+  };
+};
+
+export const { getTracerContext } = createTracerContext();

tracers.ts/src/index.ts

@@ -0,0 +1,20 @@
+import { getTracerContext } from './context';
+import {
+  createArrayTracer,
+  createControlTracer,
+  createLogTracer,
+} from './tracers';
+
+const logTracer = createLogTracer({ description: 'LogTracer' });
+const controlTracer = createControlTracer({ description: 'ControlTracer' });
+
+const arrayTracer = createArrayTracer({
+  description: 'ArrayTracer',
+  array: [1, 2, 3],
+});
+
+arrayTracer.patch(0, 100);
+
+controlTracer.step();
+
+console.log(getTracerContext().commands);

tracers.ts/src/tracers/array-tracer.ts

@@ -0,0 +1,90 @@
+import { getTracerContext } from '../context';
+import type { JsonValue } from '../types';
+
+interface ArrayTracerCreateOptions<T extends JsonValue[]> {
+  description?: string;
+  array?: T;
+}
+
+export const createArrayTracer = <T extends JsonValue[]>(
+  options: ArrayTracerCreateOptions<T>,
+) => {
+  const { description = 'ArrayTracer', array } = options;
+  const tracer = crypto.randomUUID();
+
+  const { command } = getTracerContext();
+
+  command({
+    type: 'ArrayTracer',
+    tracer: tracer,
+    action: 'create',
+    params: {
+      description: description,
+      array: array,
+    },
+  });
+
+  const scale = (size: number) => {
+    command({
+      type: 'ArrayTracer',
+      tracer: tracer,
+      action: 'scale',
+      params: {
+        size: size,
+      },
+    });
+  };
+
+  const pick = (index: number) => {
+    command({
+      type: 'ArrayTracer',
+      tracer: tracer,
+      action: 'pick',
+      params: {
+        index: index,
+      },
+    });
+  };
+
+  const drop = (index: number) => {
+    command({
+      type: 'ArrayTracer',
+      tracer: tracer,
+      action: 'drop',
+      params: {
+        index: index,
+      },
+    });
+  };
+
+  const patch = (index: number, value: T[number]) => {
+    command({
+      type: 'ArrayTracer',
+      tracer: tracer,
+      action: 'patch',
+      params: {
+        index: index,
+        value: value,
+      },
+    });
+  };
+
+  const unset = (index: number) => {
+    command({
+      type: 'ArrayTracer',
+      tracer: tracer,
+      action: 'unset',
+      params: {
+        index: index,
+      },
+    });
+  };
+
+  return {
+    scale,
+    pick,
+    drop,
+    patch,
+    unset,
+  };
+};

tracers.ts/src/tracers/control-tracer.ts

@@ -0,0 +1,81 @@
+import { getTracerContext } from '../context';
+
+export const getLocation = (targetFn?: Function) => {
+  const stackObject: { stack: string } = { stack: '' };
+  Error.captureStackTrace(stackObject, targetFn ?? getLocation);
+  const { stack } = stackObject;
+  // D:\Projects\structrail-sdk\tracers.ts\src\index.ts:23:18
+  const location = stack.split('\n').at(1)?.trim().split(' ').at(1)?.trim();
+  // console.log(location);
+  if (!location) return null;
+
+  const matches = location?.match(/:(\d+):?(\d+)?\)?$/);
+  // console.log(matches);
+  const file = location?.replace(matches?.at(0) ?? '', '');
+  // console.log(file);
+  const line = parseInt(matches?.at(1) ?? '0');
+  // console.log(line);
+
+  return {
+    file,
+    line,
+  };
+};
+
+interface ControlTracerCreateOptions {
+  description?: string;
+}
+
+export const createControlTracer = (options: ControlTracerCreateOptions) => {
+  const { description = 'ControlTracer' } = options;
+  const tracer = crypto.randomUUID();
+
+  const { command } = getTracerContext();
+
+  command({
+    type: 'ControlTracer',
+    tracer: tracer,
+    action: 'create',
+    params: {
+      description: description,
+    },
+  });
+
+  const step = (...range: (number | [number, number])[]) => {
+    const { line: currentLine } = getLocation(step) ?? {};
+    if (!currentLine) return;
+    // console.log(currentLine);
+
+    const linesSet = new Set<number>([currentLine]);
+    range.forEach((item) => {
+      if (Array.isArray(item) && item.length === 2) {
+        const [offsetStart, offsetEnd] = item;
+        const lineStart = currentLine - offsetStart;
+        const lineEnd = currentLine - offsetEnd;
+        const lineMin = Math.min(lineStart, lineEnd);
+        const lineMax = Math.max(lineStart, lineEnd);
+        for (let line = lineMin; line <= lineMax; line++) {
+          linesSet.add(line);
+        }
+      }
+      if (typeof item === 'number') {
+        const line = item;
+        linesSet.add(currentLine - line);
+      }
+    });
+    const lines = Array.from(linesSet).sort((line1, line2) => line1 - line2);
+
+    command({
+      type: 'ControlTracer',
+      tracer: tracer,
+      action: 'step',
+      params: {
+        lines: lines,
+      },
+    });
+  };
+
+  return {
+    step,
+  };
+};

tracers.ts/src/tracers/index.ts

@@ -0,0 +1,3 @@
+export * from './array-tracer';
+export * from './control-tracer';
+export * from './log-tracer';

tracers.ts/src/tracers/log-tracer.ts

@@ -0,0 +1,44 @@
+import { getTracerContext } from '../context';
+
+interface LogTracerCreateOptions {
+  description?: string;
+}
+
+export const createLogTracer = (options: LogTracerCreateOptions) => {
+  const { description = 'LogTracer' } = options;
+  const tracer = crypto.randomUUID();
+
+  const { command } = getTracerContext();
+
+  command({
+    type: 'LogTracer',
+    tracer: tracer,
+    action: 'create',
+    params: {
+      description: description,
+    },
+  });
+
+  const log = (...args: unknown[]) => {
+    const parsed = args.map((arg) => {
+      if (typeof arg === 'string') {
+        return arg;
+      }
+      return JSON.stringify(arg);
+    });
+    const message = parsed.join(' ');
+
+    command({
+      type: 'LogTracer',
+      tracer: tracer,
+      action: 'log',
+      params: {
+        message: message,
+      },
+    });
+  };
+
+  return {
+    log,
+  };
+};

tracers.ts/src/types/array-tracer.ts

@@ -0,0 +1,57 @@
+import type { BaseTracerCommand, JsonValue } from './common';
+
+type BaseArrayTracerCommand = BaseTracerCommand & {
+  type: 'ArrayTracer';
+};
+
+type ArrayTracerCreateCommand = BaseArrayTracerCommand & {
+  action: 'create';
+  params: {
+    description: string;
+    array?: JsonValue[];
+  };
+};
+
+type ArrayTracerScaleCommand = BaseArrayTracerCommand & {
+  action: 'scale';
+  params: {
+    size: number;
+  };
+};
+
+type ArrayTracerPickCommand = BaseArrayTracerCommand & {
+  action: 'pick';
+  params: {
+    index: number;
+  };
+};
+
+type ArrayTracerDropCommand = BaseArrayTracerCommand & {
+  action: 'drop';
+  params: {
+    index: number;
+  };
+};
+
+type ArrayTracerPatchCommand = BaseArrayTracerCommand & {
+  action: 'patch';
+  params: {
+    index: number;
+    value: JsonValue;
+  };
+};
+
+type ArrayTracerUnsetCommand = BaseArrayTracerCommand & {
+  action: 'unset';
+  params: {
+    index: number;
+  };
+};
+
+export type ArrayTracerCommand =
+  | ArrayTracerCreateCommand
+  | ArrayTracerScaleCommand
+  | ArrayTracerPickCommand
+  | ArrayTracerDropCommand
+  | ArrayTracerPatchCommand
+  | ArrayTracerUnsetCommand;

tracers.ts/src/types/command.ts

@@ -0,0 +1,8 @@
+import type { ArrayTracerCommand } from './array-tracer';
+import type { ControlTracerCommand } from './control-tracer';
+import type { LogTracerCommand } from './log-tracer';
+
+export type TracerCommand =
+  | ArrayTracerCommand
+  | LogTracerCommand
+  | ControlTracerCommand;

tracers.ts/src/types/common.ts

@@ -0,0 +1,16 @@
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+export type TracerType = 'ArrayTracer' | 'LogTracer' | 'ControlTracer';
+
+export type TracerId = ReturnType<typeof crypto.randomUUID>;
+
+export type BaseTracerCommand = {
+  type: TracerType;
+  tracer: TracerId;
+};

tracers.ts/src/types/control-tracer.ts

@@ -0,0 +1,23 @@
+import type { BaseTracerCommand } from './common';
+
+type BaseControlTracerCommand = BaseTracerCommand & {
+  type: 'ControlTracer';
+};
+
+type ControlTracerCreateCommand = BaseControlTracerCommand & {
+  action: 'create';
+  params: {
+    description: string;
+  };
+};
+
+type ControlTracerStepCommand = BaseControlTracerCommand & {
+  action: 'step';
+  params: {
+    lines: number[];
+  };
+};
+
+export type ControlTracerCommand =
+  | ControlTracerCreateCommand
+  | ControlTracerStepCommand;

tracers.ts/src/types/index.ts

@@ -0,0 +1,5 @@
+export * from './array-tracer';
+export * from './command';
+export * from './common';
+export * from './control-tracer';
+export * from './log-tracer';

tracers.ts/src/types/log-tracer.ts

@@ -0,0 +1,21 @@
+import type { BaseTracerCommand } from "./common";
+
+type BaseLogTracerCommand = BaseTracerCommand & {
+  type: 'LogTracer';
+};
+
+type LogTracerCreateCommand = BaseLogTracerCommand & {
+  action: 'create';
+  params: {
+    description: string;
+  };
+};
+
+type LogTracerLogCommand = BaseLogTracerCommand & {
+  action: 'log';
+  params: {
+    message: string;
+  };
+};
+
+export type LogTracerCommand = LogTracerCreateCommand | LogTracerLogCommand;

tracers.ts/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}