@ai-setting/roy-agent-core 1.0.0

package/src/env/log-trace/decorator.ts

@@ -0,0 +1,230 @@
+/**
+ * @fileoverview @Traced 装饰器实现
+ * 
+ * 提供函数包装和装饰器来自动创建 Span
+ * 支持注解到 async 函数和非 async 函数上
+ * 使用 OpenTelemetry 标准方式
+ */
+
+import { getTracerProvider, type OTelTracer, type OTelSpan } from "./opentelemetry/tracer-provider";
+import { createLogger, simplifyFilePath, getMaxOutput } from "./logger";
+
+export interface TracedOptions {
+  name?: string;
+  recordParams?: boolean;
+  recordResult?: boolean;
+  recordError?: boolean;
+  log?: boolean;
+  maxLogSize?: number;
+  paramFilter?: (args: any[], argNames?: string[]) => Record<string, any>;
+}
+
+/**
+ * @Traced 装饰器工厂
+ */
+export function Traced(options?: TracedOptions) {
+  return function <T extends (...args: any[]) => any>(
+    target: any,
+    propertyKey: string,
+    descriptor: TypedPropertyDescriptor<T>
+  ) {
+    const originalFn = descriptor.value!;
+    const spanName = options?.name || propertyKey;
+
+    descriptor.value = wrapFunction(originalFn, spanName, {
+      recordParams: options?.recordParams ?? true,
+      recordResult: options?.recordResult ?? false,
+      recordError: options?.recordError ?? true,
+      log: options?.log ?? false,
+      maxLogSize: options?.maxLogSize,
+      paramFilter: options?.paramFilter,
+    }) as T;
+
+    return descriptor;
+  };
+}
+
+/**
+ * @TracedAs 装饰器工厂 - 使用自定义名称
+ */
+export function TracedAs(name: string, options?: Omit<TracedOptions, "name">) {
+  return Traced({ name, ...options });
+}
+
+/**
+ * @TracedLightweight 装饰器工厂 - 轻量级追踪
+ */
+export function TracedLightweight(options?: { log?: boolean; maxLogSize?: number }) {
+  return Traced({ recordParams: false, recordResult: false, log: options?.log ?? false, maxLogSize: options?.maxLogSize });
+}
+
+/**
+ * 包装函数以自动创建 Span
+ * 
+ * 同时支持 async 函数和非 async 函数：
+ * - async 函数：自动检测 Promise 并正确处理
+ * - 非 async 函数：同步执行，直接返回结果
+ */
+export function wrapFunction<T extends (...args: any[]) => any>(
+  fn: T,
+  name: string,
+  options?: {
+    recordParams?: boolean;
+    recordResult?: boolean;
+    recordError?: boolean;
+    log?: boolean;
+    maxLogSize?: number;
+    paramFilter?: (args: any[], argNames?: string[]) => Record<string, any>;
+  }
+): T {
+  const shouldLog = options?.log ?? false;
+
+  const getMaxLogSize = (): number => {
+    if (options?.maxLogSize !== undefined) {
+      return options.maxLogSize;
+    }
+    const configMaxOutput = getMaxOutput();
+    return configMaxOutput !== undefined ? configMaxOutput : 500;
+  };
+
+  const truncate = (obj: any): any => {
+    if (obj === undefined) return undefined;
+    if (obj === null) return null;
+    
+    const maxLogSize = getMaxLogSize();
+    let str: string;
+    try {
+      str = typeof obj === "string" ? obj : JSON.stringify(obj, null, 0).replace(/\n/g, "");
+    } catch (e) {
+      str = `[Object with circular reference: ${e instanceof Error ? e.message : String(e)}]`;
+    }
+    if (maxLogSize > 0 && str.length > maxLogSize) {
+      return str.slice(0, maxLogSize) + " [TRUNCATED]";
+    }
+    try {
+      return JSON.parse(str);
+    } catch {
+      return str;
+    }
+  };
+
+  const truncateString = (obj: any): string => {
+    if (obj === undefined) return "undefined";
+    if (obj === null) return "null";
+    
+    const maxLogSize = getMaxLogSize();
+    let str: string;
+    try {
+      str = typeof obj === "string" ? obj : JSON.stringify(obj, null, 0).replace(/\n/g, "");
+    } catch (e) {
+      str = `[Object with circular reference: ${e instanceof Error ? e.message : String(e)}]`;
+    }
+    return maxLogSize > 0 && str.length > maxLogSize ? str.slice(0, maxLogSize) + " [TRUNCATED]" : str;
+  };
+
+  const TRACE_LOG_PREFIX = "[TRACE]";
+
+  const getCallerLocation = (): string => {
+    const originalLimit = Error.stackTraceLimit;
+    Error.stackTraceLimit = 15;
+    const err = new Error();
+    Error.captureStackTrace(err, getCallerLocation);
+    const stack = err.stack?.split("\n") || [];
+    Error.stackTraceLimit = originalLimit;
+
+    for (let i = 1; i < stack.length; i++) {
+      const line = stack[i];
+      if (line.includes("decorator.ts") || line.includes("decorator.js") || line.includes("logFn") || line.includes("getCallerLocation")) continue;
+      const match = line.match(/at\s+.+\s+\((.+):(\d+):\d+\)/) || line.match(/at\s+(.+):(\d+):\d+/);
+      if (match) {
+        const filePath = match[1];
+        if (!filePath || filePath === "native") continue;
+        const relativePath = simplifyFilePath(filePath);
+        return `${relativePath}:${match[2]}`;
+      }
+    }
+    return "";
+  };
+
+  const logFn = (event: "enter" | "quit" | "error", argsOrData?: any, callerLocation?: string) => {
+    if (!shouldLog) return;
+    const logger = createLogger("traced:" + name);
+
+    const tag = event === "enter" ? ">>>" : event === "quit" ? "<<<" : "!!!";
+    const prefix = `${TRACE_LOG_PREFIX} ${tag} ${name}`;
+    const originalFnLocation = callerLocation || getCallerLocation();
+
+    const logMessage = (msg: string, data?: any) => {
+      if (data !== undefined) {
+        logger.info(`${prefix} ${msg}: ${truncateString(data)}`, { callerLocation: originalFnLocation });
+      } else {
+        logger.info(`${prefix} ${msg}`, { callerLocation: originalFnLocation });
+      }
+    };
+
+    if (event === "enter") {
+      logMessage("enter", argsOrData);
+    } else if (event === "quit") {
+      logMessage("quit", options?.recordResult ? argsOrData : undefined);
+    } else {
+      logMessage("error", argsOrData);
+    }
+  };
+
+  // 包装函数 - 支持 async 和非 async 函数
+  return function(this: any, ...args: any[]) {
+    // 获取 OTel Tracer
+    const tracer: OTelTracer = getTracerProvider().getTracer("roy-tracer");
+
+    const attributes: Record<string, any> = {};
+
+    if (options?.recordParams !== false) {
+      if (options?.paramFilter) {
+        attributes["params"] = truncate(options.paramFilter(args));
+      } else {
+        attributes["params"] = truncate(args);
+      }
+    }
+
+    // 在 enter 时获取调用位置并保存
+    const callerLocation = getCallerLocation();
+    logFn("enter", args, callerLocation);
+
+    // 启动 OTel Span
+    const span = tracer.startSpan(name, { attributes });
+
+    try {
+      const result = fn.call(this, ...args);
+
+      // 处理 Promise
+      if (result && typeof result === 'object' && typeof (result as Promise<unknown>).then === 'function') {
+        return (result as Promise<unknown>).then(
+          (resolved) => {
+            span.setAttribute('result', JSON.stringify(truncate(resolved)));
+            span.end(resolved);
+            logFn("quit", options?.recordResult ? resolved : undefined, callerLocation);
+            return resolved;
+          },
+          (rejected) => {
+            span.setAttribute('error', String(rejected));
+            span.end(undefined, rejected instanceof Error ? rejected : new Error(String(rejected)));
+            logFn("error", (rejected as Error).message, callerLocation);
+            throw rejected;
+          }
+        );
+      }
+
+      // 同步方法
+      span.setAttribute('result', JSON.stringify(truncate(result)));
+      span.end(result);
+      logFn("quit", options?.recordResult ? result : undefined, callerLocation);
+      return result;
+
+    } catch (error) {
+      span.setAttribute('error', String(error));
+      span.end(undefined, error instanceof Error ? error : new Error(String(error)));
+      logFn("error", (error as Error).message, callerLocation);
+      throw error;
+    }
+  } as T;
+}

package/src/env/log-trace/index.ts

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview Log & Trace 模块导出
+ * 
+ * OpenTelemetry 标准接口
+ */
+
+// Types
+export {
+  type Span,
+  type SpanContext,
+  type SpanAttributes,
+  type TraceInfo,
+  type SpanStorage,
+  type ITraceContext,
+  type LogLevel,
+  type LoggerConfig,
+  type ILogger,
+  type TraceContextOptions,
+} from "./types";
+
+export { SpanKind, SpanStatus } from "./types";
+
+// Storage
+export { SQLiteSpanStorage } from "./span-storage";
+
+// Component
+export {
+  LogTraceComponent,
+  type LogTraceConfig,
+  type LogTraceComponentOptions,
+  LogTraceConfigSchema,
+  getDefaultLogDir,
+  getDefaultSpanDbPath,
+} from "./log-trace-component";
+
+// OpenTelemetry Tracer Provider
+export {
+  OTelTracerProvider,
+  getTracerProvider,
+  resetTracerProvider,
+  type OTelTracer,
+  type OTelSpan,
+  type SpanOptions,
+} from "./opentelemetry/tracer-provider";
+
+// OpenTelemetry Propagation
+export {
+  propagation,
+  serialize,
+  parse,
+  type ExtractedContext,
+} from "./opentelemetry/propagation";
+
+export {
+  injectToEnv,
+  injectToEnvWithContext,
+  injectToEnvFromCarrier,
+  getTraceparentHeader,
+  type EnvCarrier,
+} from "./opentelemetry/propagation-env";
+
+// Logger
+export {
+  createLogger,
+  setQuietMode,
+  isQuietMode,
+  setConfigComponent as setLoggerConfigComponent,
+  getLogLevel,
+  getLogLevels,
+  getLogDir,
+  getLogFile,
+  setLogDirOverride,
+  getLogDirOverride,
+  simplifyFilePath,
+  getMaxOutput,
+} from "./logger";
+
+// Decorator
+export { TracedAs, Traced, TracedLightweight, wrapFunction, type TracedOptions } from "./decorator";

package/src/env/log-trace/log-trace-component.test.ts

@@ -0,0 +1,242 @@
+/**
+ * @fileoverview LogTraceComponent Tests
+ * 
+ * 使用 TDD 方法测试 LogTraceComponent 配置加载
+ */
+
+import { describe, test, expect, beforeEach, afterEach, vi } from "bun:test";
+import { LogTraceComponent } from "./log-trace-component";
+import { ConfigComponent } from "../../config/config-component";
+import * as fsSync from "fs";
+import * as path from "path";
+import * as os from "os";
+import type { Environment } from "../interface";
+
+describe("LogTraceComponent Config Loading", () => {
+  let component: LogTraceComponent;
+  let configComponent: ConfigComponent;
+  let mockEnv: Environment;
+  let tempDir: string;
+
+  beforeEach(() => {
+    component = new LogTraceComponent();
+    configComponent = new ConfigComponent();
+    
+    // Create temp directory for config files
+    tempDir = fsSync.mkdtempSync(path.join(os.tmpdir(), "logtrace-config-test-"));
+    
+    // Set XDG_DATA_HOME to temp directory so ConfigComponent can find config files
+    configComponent.setXdgDataHome(tempDir);
+    
+    // Mock environment
+    mockEnv = {
+      name: "test-env",
+      version: "1.0.0",
+      getComponent: vi.fn((name: string) => {
+        if (name === "config") return configComponent;
+        return undefined;
+      }),
+      hasComponent: vi.fn((name: string) => name === "config"),
+      logger: vi.fn(),
+      trace: vi.fn(),
+    } as unknown as Environment;
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    // Clean up environment variables
+    delete process.env.LOG_TRACE_LOGGING_LEVEL;
+    delete process.env.LOG_TRACE_LOGGING_QUIET;
+    delete process.env.LOG_TRACE_TRACING_ENABLED;
+    delete process.env.LOG_TRACE_TRACING_STORAGE;
+    delete process.env.LOG_LOGGING_LEVEL;
+    delete process.env.LOG_LOGGING_LEVEL;
+    // Clean up temp directory
+    try {
+      fsSync.rmSync(tempDir, { recursive: true });
+    } catch {}
+  });
+
+  describe("LogTraceComponentOptions", () => {
+    test("should accept configComponent only", async () => {
+      await component.init({
+        name: "log-trace",
+        version: "1.0.0",
+        enabled: true,
+        env: mockEnv,
+        options: { configComponent }
+      });
+      expect(component.getStatus()).toBe("running");
+    });
+
+    test("should accept configPath option", async () => {
+      fsSync.writeFileSync(path.join(tempDir, "config.jsonc"), JSON.stringify({
+        "log-trace": {
+          logging: {
+            level: "debug"
+          }
+        }
+      }), "utf-8");
+
+      await component.init({
+        name: "log-trace",
+        version: "1.0.0",
+        enabled: true,
+        env: mockEnv,
+        options: { configComponent, configPath: "config.jsonc" }
+      });
+      expect(component.getStatus()).toBe("running");
+    });
+
+    test("should accept envPrefix option", async () => {
+      process.env.LOG_TRACE_LOGGING_LEVEL = "warn";
+      
+      await component.init({
+        name: "log-trace",
+        version: "1.0.0",
+        enabled: true,
+        env: mockEnv,
+        options: { configComponent, envPrefix: "LOG_TRACE" }
+      });
+      expect(component.getStatus()).toBe("running");
+      
+      delete process.env.LOG_TRACE_LOGGING_LEVEL;
+    });
+
+    test("should accept config option with direct object", async () => {
+      await component.init({
+        name: "log-trace",
+        version: "1.0.0",
+        enabled: true,
+        env: mockEnv,
+        options: { 
+          configComponent, 
+          config: {
+            logging: {
+              level: "error"
+            }
+          }
+        }
+      });
+      expect(component.getStatus()).toBe("running");
+    });
+  });
+
+  describe("config priority: Object > Env > File", () => {
+    test("should Object config override Env config", async () => {
+      // Set environment variable (使用正确的格式)
+      // LOG_TRACE_LOGGING_LEVEL -> log-trace.logging.level
+      process.env.LOG_TRACE_LOGGING_LEVEL = "warn";
+      
+      // Create file config
+      fsSync.writeFileSync(path.join(tempDir, "config.jsonc"), JSON.stringify({
+        "log-trace": { logging: { level: "info" } }
+      }), "utf-8");
+
+      await component.init({
+        name: "log-trace",
+        version: "1.0.0",
+        enabled: true,
+        env: mockEnv,
+        options: { 
+          configComponent, 
+          configPath: "config.jsonc",
+          envPrefix: "LOG_TRACE",
+          config: { logging: { level: "error" } }  // Object has highest priority
+        }
+      });
+      
+      // Object config should have highest priority
+      expect(configComponent.get("log-trace.logging.level")).toBe("error");
+      
+      delete process.env.LOG_TRACE_LOGGING_LEVEL;
+    });
+
+    test("should Env config override File config", async () => {
+      // Set environment variable (使用正确的格式: PREFIX + KEY)
+      // LOG_TRACE_LOGGING_LEVEL -> log-trace.logging.level
+      process.env.LOG_TRACE_LOGGING_LEVEL = "warn";
+      
+      // Create file config
+      fsSync.writeFileSync(path.join(tempDir, "config.jsonc"), JSON.stringify({
+        "log-trace": { logging: { level: "info" } }
+      }), "utf-8");
+
+      await component.init({
+        name: "log-trace",
+        version: "1.0.0",
+        enabled: true,
+        env: mockEnv,
+        options: { 
+          configComponent, 
+          configPath: "config.jsonc",
+          envPrefix: "LOG_TRACE"
+        }
+      });
+      
+      // Env should override file
+      expect(configComponent.get("log-trace.logging.level")).toBe("warn");
+      
+      delete process.env.LOG_TRACE_LOGGING_LEVEL;
+    });
+
+    test("should File config be loaded when present", async () => {
+      fsSync.writeFileSync(path.join(tempDir, "config.jsonc"), JSON.stringify({
+        "log-trace": { 
+          logging: { 
+            level: "debug",
+            quiet: true 
+          },
+          tracing: {
+            enabled: false
+          }
+        }
+      }), "utf-8");
+
+      await component.init({
+        name: "log-trace",
+        version: "1.0.0",
+        enabled: true,
+        env: mockEnv,
+        options: { 
+          configComponent, 
+          configPath: "config.jsonc"
+        }
+      });
+      
+      expect(configComponent.get("log-trace.logging.level")).toBe("debug");
+      expect(configComponent.get("log-trace.logging.quiet")).toBe(true);
+      expect(configComponent.get("log-trace.tracing.enabled")).toBe(false);
+    });
+
+    test("should use default values when no config provided", async () => {
+      await component.init({
+        name: "log-trace",
+        version: "1.0.0",
+        enabled: true,
+        env: mockEnv,
+        options: { configComponent }
+      });
+      
+      // Default values should be set from LOG_TRACE_DEFAULTS
+      expect(configComponent.get("log-trace.logging.level")).toBe("info");
+    });
+  });
+
+  describe("config hot reload", () => {
+    test("should register config watcher for hot reload", async () => {
+      const watcherFn = vi.fn();
+      vi.spyOn(configComponent, "watch").mockReturnValue(watcherFn);
+      
+      await component.init({
+        name: "log-trace",
+        version: "1.0.0",
+        enabled: true,
+        env: mockEnv,
+        options: { configComponent }
+      });
+      
+      expect(configComponent.watch).toHaveBeenCalledWith("log-trace.*", expect.any(Function));
+    });
+  });
+});