@fulmenhq/tsfulmen 0.3.3 → 0.4.0

package/dist/chunk-5HZEJGZ5.js

@@ -0,0 +1,725 @@
+import { hostname } from 'os';
+import pino from 'pino';
+import { readFileSync, appendFileSync } from 'fs';
+import { parse } from 'yaml';
+
+// src/logging/logger.ts
+
+// src/logging/types.ts
+var LoggingProfile = /* @__PURE__ */ ((LoggingProfile2) => {
+  LoggingProfile2["SIMPLE"] = "simple";
+  LoggingProfile2["STRUCTURED"] = "structured";
+  LoggingProfile2["ENTERPRISE"] = "enterprise";
+  LoggingProfile2["CUSTOM"] = "custom";
+  return LoggingProfile2;
+})(LoggingProfile || {});
+var PolicyError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PolicyError";
+  }
+};
+
+// src/logging/policy.ts
+var PolicyEnforcer = class {
+  policy;
+  policyFile;
+  /**
+   * Create a new policy enforcer
+   *
+   * @param policyFile - Path to YAML policy file
+   * @throws {PolicyError} If policy file cannot be loaded or is invalid
+   */
+  constructor(policyFile) {
+    this.policyFile = policyFile;
+    this.policy = this.loadPolicy(policyFile);
+  }
+  /**
+   * Validate if a profile is allowed under the current policy
+   *
+   * @param profile - The logging profile to validate
+   * @param options - Optional validation context (appType, environment)
+   * @returns true if profile is allowed, false otherwise
+   *
+   * @example
+   * const enforcer = new PolicyEnforcer('/org/logging-policy.yaml');
+   * if (enforcer.validateProfile(LoggingProfile.ENTERPRISE, { environment: 'production' })) {
+   *   // Profile is allowed
+   * }
+   */
+  validateProfile(profile, options) {
+    if (!this.policy.allowedProfiles.includes(profile)) {
+      return false;
+    }
+    if (options?.environment && this.policy.environmentRules) {
+      const envRules = this.policy.environmentRules[options.environment];
+      if (envRules && !envRules.includes(profile)) {
+        return false;
+      }
+    }
+    if (options?.appType && this.policy.requiredProfiles) {
+      const appTypeRules = this.policy.requiredProfiles[options.appType];
+      if (appTypeRules && !appTypeRules.includes(profile)) {
+        return false;
+      }
+    }
+    return true;
+  }
+  /**
+   * Get the required profile for a given app type and environment
+   *
+   * @param appType - The application type
+   * @param environment - The deployment environment
+   * @returns The required logging profile
+   * @throws {PolicyError} If no required profile found for app type
+   *
+   * @example
+   * const enforcer = new PolicyEnforcer('/org/logging-policy.yaml');
+   * const profile = enforcer.getRequiredProfile('api-server', 'production');
+   * // Returns LoggingProfile.ENTERPRISE
+   */
+  getRequiredProfile(appType, environment) {
+    if (this.policy.requiredProfiles?.[appType]) {
+      const profiles = this.policy.requiredProfiles[appType];
+      if (this.policy.environmentRules?.[environment]) {
+        const envProfiles = this.policy.environmentRules[environment];
+        const validProfiles = profiles.filter((p) => envProfiles.includes(p));
+        if (validProfiles.length > 0) {
+          return this.getMostRestrictiveProfile(validProfiles);
+        }
+      }
+      return this.getMostRestrictiveProfile(profiles);
+    }
+    throw new PolicyError(
+      `No required profile found for app type "${appType}" in policy ${this.policyFile}`
+    );
+  }
+  /**
+   * Get a helpful error message for policy validation failure
+   *
+   * @param profile - The profile that failed validation
+   * @param options - The validation options used
+   * @returns A descriptive error message
+   */
+  getValidationErrorMessage(profile, options) {
+    const parts = [`Profile "${profile}" not allowed by policy "${this.policyFile}".`];
+    if (options?.environment) {
+      parts.push(`Environment: ${options.environment}`);
+    }
+    if (options?.appType) {
+      parts.push(`App Type: ${options.appType}`);
+    }
+    parts.push(`Allowed profiles: ${this.policy.allowedProfiles.join(", ")}`);
+    if (options?.environment && this.policy.environmentRules?.[options.environment]) {
+      const envProfiles = this.policy.environmentRules[options.environment];
+      parts.push(`Environment "${options.environment}" allows: ${envProfiles.join(", ")}`);
+    }
+    if (options?.appType && this.policy.requiredProfiles?.[options.appType]) {
+      const appProfiles = this.policy.requiredProfiles[options.appType];
+      parts.push(`App type "${options.appType}" requires: ${appProfiles.join(", ")}`);
+    }
+    return parts.join(" | ");
+  }
+  /**
+   * Load and parse the policy file
+   *
+   * @param policyFile - Path to YAML policy file
+   * @returns Parsed logging policy
+   * @throws {PolicyError} If file cannot be read or parsed
+   */
+  loadPolicy(policyFile) {
+    try {
+      const content = readFileSync(policyFile, "utf-8");
+      const parsed = parse(content);
+      if (!parsed.allowedProfiles || !Array.isArray(parsed.allowedProfiles)) {
+        throw new PolicyError(
+          `Invalid policy file ${policyFile}: missing or invalid "allowedProfiles" field`
+        );
+      }
+      const validProfiles = Object.values(LoggingProfile);
+      for (const profile of parsed.allowedProfiles) {
+        if (!validProfiles.includes(profile)) {
+          throw new PolicyError(`Invalid policy file ${policyFile}: unknown profile "${profile}"`);
+        }
+      }
+      if (parsed.requiredProfiles) {
+        if (typeof parsed.requiredProfiles !== "object") {
+          throw new PolicyError(
+            `Invalid policy file ${policyFile}: "requiredProfiles" must be an object`
+          );
+        }
+        for (const [appType, profiles] of Object.entries(parsed.requiredProfiles)) {
+          if (!Array.isArray(profiles)) {
+            throw new PolicyError(
+              `Invalid policy file ${policyFile}: requiredProfiles["${appType}"] must be an array, got ${typeof profiles}. Check YAML formatting - each profile should be on a new line with a hyphen.`
+            );
+          }
+          for (const profile of profiles) {
+            if (!validProfiles.includes(profile)) {
+              throw new PolicyError(
+                `Invalid policy file ${policyFile}: requiredProfiles["${appType}"] contains unknown profile "${profile}"`
+              );
+            }
+          }
+        }
+      }
+      if (parsed.environmentRules) {
+        if (typeof parsed.environmentRules !== "object") {
+          throw new PolicyError(
+            `Invalid policy file ${policyFile}: "environmentRules" must be an object`
+          );
+        }
+        for (const [environment, profiles] of Object.entries(parsed.environmentRules)) {
+          if (!Array.isArray(profiles)) {
+            throw new PolicyError(
+              `Invalid policy file ${policyFile}: environmentRules["${environment}"] must be an array, got ${typeof profiles}. Check YAML formatting - each profile should be on a new line with a hyphen.`
+            );
+          }
+          for (const profile of profiles) {
+            if (!validProfiles.includes(profile)) {
+              throw new PolicyError(
+                `Invalid policy file ${policyFile}: environmentRules["${environment}"] contains unknown profile "${profile}"`
+              );
+            }
+          }
+        }
+      }
+      return parsed;
+    } catch (error) {
+      if (error instanceof PolicyError) {
+        throw error;
+      }
+      if (error.code === "ENOENT") {
+        throw new PolicyError(`Policy file not found: ${policyFile}`);
+      }
+      throw new PolicyError(
+        `Failed to load policy file ${policyFile}: ${error.message}`
+      );
+    }
+  }
+  /**
+   * Get the most restrictive profile from a list
+   * Order: CUSTOM > ENTERPRISE > STRUCTURED > SIMPLE
+   *
+   * @param profiles - List of profiles
+   * @returns The most restrictive profile
+   */
+  getMostRestrictiveProfile(profiles) {
+    const order = [
+      "custom" /* CUSTOM */,
+      "enterprise" /* ENTERPRISE */,
+      "structured" /* STRUCTURED */,
+      "simple" /* SIMPLE */
+    ];
+    for (const profile of order) {
+      if (profiles.includes(profile)) {
+        return profile;
+      }
+    }
+    return profiles[0];
+  }
+};
+var ConsoleSink = class {
+  write(event) {
+    console.log(JSON.stringify(event));
+  }
+};
+var FileSink = class {
+  constructor(filePath) {
+    this.filePath = filePath;
+  }
+  write(event) {
+    try {
+      appendFileSync(this.filePath, `${JSON.stringify(event)}
+`);
+    } catch (error) {
+      console.error(`FileSink: Failed to write to ${this.filePath}:`, error.message);
+      console.log(JSON.stringify(event));
+    }
+  }
+};
+var NullSink = class {
+  write(_event) {
+  }
+};
+
+// src/logging/logger.ts
+var Logger = class {
+  service;
+  profile;
+  impl;
+  constructor(config) {
+    this.service = config.service;
+    this.profile = config.profile;
+    if (config.policyFile) {
+      this.validatePolicy(config.profile, config.policyFile);
+    }
+    this.impl = this.createImplementation(config);
+  }
+  debug(message, context) {
+    this.impl.debug(message, context);
+  }
+  info(message, context) {
+    this.impl.info(message, context);
+  }
+  warn(message, context) {
+    this.impl.warn(message, context);
+  }
+  error(message, error, context) {
+    this.impl.error(message, error, context);
+  }
+  child(bindings) {
+    const childLogger = Object.create(this);
+    childLogger.impl = this.impl.child(bindings);
+    return childLogger;
+  }
+  validatePolicy(profile, policyFile) {
+    const enforcer = new PolicyEnforcer(policyFile);
+    const appType = process.env.APP_TYPE;
+    const environment = process.env.NODE_ENV;
+    if (!enforcer.validateProfile(profile, { appType, environment })) {
+      throw new PolicyError(enforcer.getValidationErrorMessage(profile, { appType, environment }));
+    }
+  }
+  createImplementation(config) {
+    switch (config.profile) {
+      case "simple" /* SIMPLE */:
+        return new SimpleLogger(config.service);
+      case "structured" /* STRUCTURED */: {
+        const structuredConfig = config;
+        return new StructuredLogger(
+          structuredConfig.service,
+          structuredConfig.filePath,
+          structuredConfig.middleware
+        );
+      }
+      case "enterprise" /* ENTERPRISE */:
+        return new EnterpriseLogger(config.service, {
+          // biome-ignore lint/suspicious/noExplicitAny: Phase 1 - proper discriminated union handling in Phase 2
+          sinks: config.sinks,
+          // biome-ignore lint/suspicious/noExplicitAny: Phase 1 - proper discriminated union handling in Phase 2
+          middleware: config.middleware
+        });
+      case "custom" /* CUSTOM */:
+        return new EnterpriseLogger(config.service, config.customConfig);
+    }
+  }
+};
+var SimpleLogger = class {
+  constructor(service) {
+    this.service = service;
+    this.pino = pino({
+      name: service,
+      level: "debug",
+      messageKey: "message",
+      base: void 0,
+      timestamp: false,
+      formatters: {
+        level: (label) => ({ severity: label.toUpperCase() }),
+        // biome-ignore lint/suspicious/noExplicitAny: Pino formatter requires any type
+        log: (object) => {
+          return {
+            service: this.service,
+            ...object
+          };
+        }
+      }
+    });
+  }
+  pino;
+  debug(message, context) {
+    this.pino.debug(context, message);
+  }
+  info(message, context) {
+    this.pino.info(context, message);
+  }
+  warn(message, context) {
+    this.pino.warn(context, message);
+  }
+  error(message, error, context) {
+    const errorContext = {
+      ...context,
+      ...error && { error: error.message, stack: error.stack }
+    };
+    this.pino.error(errorContext, message);
+  }
+  child(bindings) {
+    const childPino = this.pino.child(bindings);
+    const childLogger = Object.create(this);
+    childLogger.pino = childPino;
+    return childLogger;
+  }
+};
+var StructuredLogger = class _StructuredLogger {
+  constructor(service, filePath, middleware, bindings, existingPino) {
+    this.service = service;
+    this.filePath = filePath;
+    this.middleware = middleware ?? [];
+    this.bindings = bindings ?? {};
+    const config = {
+      name: service,
+      level: "debug",
+      messageKey: "message",
+      base: void 0,
+      timestamp: () => `,"timestamp":"${(/* @__PURE__ */ new Date()).toISOString()}"`,
+      formatters: {
+        level: (label) => ({ severity: label.toUpperCase() }),
+        // biome-ignore lint/suspicious/noExplicitAny: Pino formatter requires any type
+        log: (object) => {
+          return {
+            service: this.service,
+            ...object
+          };
+        }
+      }
+    };
+    this.pino = existingPino ?? (filePath ? pino(
+      config,
+      pino.multistream([{ stream: process.stdout }, { stream: pino.destination(filePath) }])
+    ) : pino(config));
+  }
+  pino;
+  middleware;
+  bindings;
+  debug(message, context) {
+    if (this.middleware.length > 0) {
+      this.logWithMiddleware("DEBUG", message, context);
+    } else {
+      this.pino.debug(context, message);
+    }
+  }
+  info(message, context) {
+    if (this.middleware.length > 0) {
+      this.logWithMiddleware("INFO", message, context);
+    } else {
+      this.pino.info(context, message);
+    }
+  }
+  warn(message, context) {
+    if (this.middleware.length > 0) {
+      this.logWithMiddleware("WARN", message, context);
+    } else {
+      this.pino.warn(context, message);
+    }
+  }
+  error(message, error, context) {
+    const errorContext = {
+      ...context,
+      ...error && { error: error.message, stack: error.stack }
+    };
+    if (this.middleware.length > 0) {
+      this.logWithMiddleware("ERROR", message, errorContext);
+    } else {
+      this.pino.error(errorContext, message);
+    }
+  }
+  logWithMiddleware(severity, message, context) {
+    let event = {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      service: this.service,
+      severity,
+      message,
+      ...this.bindings,
+      ...context
+    };
+    for (const mw of this.middleware) {
+      event = mw.process(event);
+    }
+    const { message: finalMessage, severity: finalSeverity, ...finalContext } = event;
+    const level = (finalSeverity || severity).toLowerCase();
+    switch (level) {
+      case "debug":
+        this.pino.debug(finalContext, finalMessage);
+        break;
+      case "info":
+        this.pino.info(finalContext, finalMessage);
+        break;
+      case "warn":
+        this.pino.warn(finalContext, finalMessage);
+        break;
+      case "error":
+        this.pino.error(finalContext, finalMessage);
+        break;
+      default:
+        this.pino.info(finalContext, finalMessage);
+    }
+  }
+  child(bindings) {
+    const mergedBindings = { ...this.bindings, ...bindings };
+    const childPino = this.pino.child(bindings);
+    return new _StructuredLogger(
+      this.service,
+      this.filePath,
+      this.middleware,
+      mergedBindings,
+      childPino
+    );
+  }
+};
+var EnterpriseLogger = class _EnterpriseLogger {
+  constructor(service, config, bindings) {
+    this.service = service;
+    this.sinks = config?.sinks ?? [new ConsoleSink()];
+    this.middleware = config?.middleware ?? [];
+    this.bindings = bindings ?? {};
+  }
+  sinks;
+  middleware;
+  bindings;
+  debug(message, context) {
+    this.logWithPipeline("DEBUG", message, context);
+  }
+  info(message, context) {
+    this.logWithPipeline("INFO", message, context);
+  }
+  warn(message, context) {
+    this.logWithPipeline("WARN", message, context);
+  }
+  error(message, error, context) {
+    const errorContext = {
+      ...context,
+      ...error && {
+        error: error.message,
+        stack: error.stack,
+        errorType: error.constructor.name
+      }
+    };
+    this.logWithPipeline("ERROR", message, errorContext);
+  }
+  logWithPipeline(severity, message, context) {
+    let event = {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      service: this.service,
+      severity,
+      message,
+      correlationId: context?.correlationId ?? this.generateCorrelationId(),
+      host: this.getHostname(),
+      pid: process.pid,
+      ...this.bindings,
+      ...context
+    };
+    for (const mw of this.middleware) {
+      event = mw.process(event);
+    }
+    for (const sink of this.sinks) {
+      sink.write(event);
+    }
+  }
+  child(bindings) {
+    const mergedBindings = { ...this.bindings, ...bindings };
+    return new _EnterpriseLogger(
+      this.service,
+      {
+        sinks: this.sinks,
+        middleware: this.middleware
+      },
+      mergedBindings
+    );
+  }
+  generateCorrelationId() {
+    return `corr-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+  }
+  getHostname() {
+    try {
+      return hostname();
+    } catch {
+      return process.env.HOSTNAME || "unknown";
+    }
+  }
+};
+
+// src/logging/middleware.ts
+var DEFAULT_SECRET_KEYS = [
+  "password",
+  "token",
+  "apikey",
+  "api_key",
+  "authorization",
+  "secret",
+  "cardnumber",
+  "card_number",
+  "cvv",
+  "ssn",
+  "accesstoken",
+  "access_token",
+  "refreshtoken",
+  "refresh_token"
+];
+var DEFAULT_SECRET_PATTERNS = [
+  /SECRET_[A-Z0-9_]+/g,
+  // Environment variable secrets
+  /[A-Z0-9_]*TOKEN[A-Z0-9_]*/g,
+  // Token variants
+  /[A-Z0-9_]*KEY[A-Z0-9_]*/g,
+  // Key variants
+  /[A-Za-z0-9+/]{40,}={0,2}/g,
+  // Base64 blobs (~40+ chars)
+  /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g,
+  // Email addresses
+  /\b\d{13,19}\b/g
+  // Credit card numbers (13-19 digits)
+];
+var MAX_PATTERN_SCAN_SIZE = 10240;
+var RedactSecretsMiddleware = class {
+  secretKeys;
+  secretKeysLower;
+  patterns;
+  constructor(optionsOrKeys) {
+    let secretKeys;
+    let patterns = [];
+    let useDefaultPatterns = true;
+    if (Array.isArray(optionsOrKeys)) {
+      secretKeys = optionsOrKeys;
+      useDefaultPatterns = false;
+    } else {
+      secretKeys = optionsOrKeys?.secretKeys ?? DEFAULT_SECRET_KEYS;
+      patterns = optionsOrKeys?.patterns ?? [];
+      useDefaultPatterns = optionsOrKeys?.useDefaultPatterns ?? true;
+    }
+    this.secretKeys = secretKeys;
+    this.secretKeysLower = secretKeys.map((k) => k.toLowerCase());
+    this.patterns = [...useDefaultPatterns ? DEFAULT_SECRET_PATTERNS : [], ...patterns];
+  }
+  process(event) {
+    const redacted = { ...event };
+    for (const key of Object.keys(redacted)) {
+      if (this.isSecretKey(key)) {
+        redacted[key] = "[REDACTED]";
+      }
+    }
+    this.redactNested(redacted);
+    return redacted;
+  }
+  isSecretKey(key) {
+    return this.secretKeysLower.includes(key.toLowerCase());
+  }
+  redactNested(obj) {
+    for (const [key, value] of Object.entries(obj)) {
+      if (this.isSecretKey(key)) {
+        obj[key] = "[REDACTED]";
+      } else if (typeof value === "string") {
+        obj[key] = this.redactPatterns(value);
+      } else if (value && typeof value === "object") {
+        if (this.isPlainObject(value)) {
+          if (Array.isArray(value)) {
+            this.redactArray(value);
+          } else {
+            this.redactNested(value);
+          }
+        }
+      }
+    }
+  }
+  redactArray(arr) {
+    for (let i = 0; i < arr.length; i++) {
+      const item = arr[i];
+      if (typeof item === "string") {
+        arr[i] = this.redactPatterns(item);
+      } else if (item && typeof item === "object") {
+        if (this.isPlainObject(item)) {
+          if (Array.isArray(item)) {
+            this.redactArray(item);
+          } else {
+            this.redactNested(item);
+          }
+        }
+      }
+    }
+  }
+  /**
+   * Apply regex patterns to redact secrets from string values
+   * Skips strings larger than MAX_PATTERN_SCAN_SIZE for performance
+   */
+  redactPatterns(value) {
+    if (value.length > MAX_PATTERN_SCAN_SIZE) {
+      return value;
+    }
+    let result = value;
+    for (const pattern of this.patterns) {
+      pattern.lastIndex = 0;
+      result = result.replace(pattern, "[REDACTED]");
+    }
+    return result;
+  }
+  /**
+   * Check if value is a plain object (not Date, Buffer, Error, etc.)
+   */
+  isPlainObject(value) {
+    if (!value || typeof value !== "object") {
+      return false;
+    }
+    if (value instanceof Date || value instanceof Error || value instanceof RegExp || ArrayBuffer.isView(value) || // Covers Buffer, TypedArray, DataView
+    value instanceof ArrayBuffer) {
+      return false;
+    }
+    if (Array.isArray(value)) {
+      return true;
+    }
+    return true;
+  }
+};
+var AddFieldsMiddleware = class {
+  constructor(fields) {
+    this.fields = fields;
+  }
+  process(event) {
+    return {
+      ...event,
+      ...this.fields
+    };
+  }
+};
+var TransformMiddleware = class {
+  constructor(transformer) {
+    this.transformer = transformer;
+  }
+  process(event) {
+    return this.transformer(event);
+  }
+};
+
+// src/logging/create-logger.ts
+function createLogger(config) {
+  return new Logger(config);
+}
+function createSimpleLogger(service) {
+  return new Logger({
+    service,
+    profile: "simple" /* SIMPLE */
+  });
+}
+function createStructuredLogger(service, filePath) {
+  return new Logger({
+    service,
+    profile: "structured" /* STRUCTURED */,
+    filePath
+  });
+}
+function createEnterpriseLogger(service, options) {
+  return new Logger({
+    service,
+    profile: "enterprise" /* ENTERPRISE */,
+    ...options
+  });
+}
+function createStructuredLoggerWithRedaction(service, options) {
+  return new Logger({
+    service,
+    profile: "structured" /* STRUCTURED */,
+    filePath: options?.filePath,
+    middleware: [
+      new RedactSecretsMiddleware({
+        secretKeys: options?.customFields,
+        patterns: options?.customPatterns,
+        useDefaultPatterns: options?.useDefaultPatterns
+      })
+    ]
+  });
+}
+
+// src/logging/index.ts
+var VERSION = "0.1.0";
+
+export { AddFieldsMiddleware, ConsoleSink, FileSink, Logger, LoggingProfile, NullSink, PolicyEnforcer, PolicyError, RedactSecretsMiddleware, TransformMiddleware, VERSION, createEnterpriseLogger, createLogger, createSimpleLogger, createStructuredLogger, createStructuredLoggerWithRedaction };
+//# sourceMappingURL=chunk-5HZEJGZ5.js.map
+//# sourceMappingURL=chunk-5HZEJGZ5.js.map