@superblocksteam/telemetry 2.0.0-SNAPSHOT.329be19cb7ca892b

package/dist/common/trace-sanitizer.js

@@ -0,0 +1,234 @@
+"use strict";
+/**
+ * Tier 2 Trace Sanitizer
+ *
+ * Sanitizes spans for Tier 2 export per epic-a3-sanitized-traces.
+ * - Drops spans for high-volume, low-value routes (health, metrics)
+ * - Drops spans not in the contract
+ * - Drops forbidden attributes (PII, Tier 1 content)
+ * - Drops high-cardinality attributes (e.g. binding_keys) when configured
+ * - Hashes configured attributes using keyed HMAC (when hash config provided)
+ * - Only includes attributes in the allowlist for each span type
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TraceSanitizer = void 0;
+const node_crypto_1 = require("node:crypto");
+/** http.route values for which we never export spans (high volume, no operational value). */
+const DROPPED_HTTP_ROUTES = new Set([
+    "/health/liveness",
+    "/health/readiness",
+    "/metrics",
+    "/api/v1/metrics",
+]);
+const tier2_traces_js_1 = require("./contracts/tier2-traces.js");
+/** Normalize span name for pattern matching. Server uses "POST /path" but contract uses "HTTP POST *". */
+function normalizeSpanNameForMatching(name) {
+    const candidates = [name];
+    const methodPrefix = /^(GET|POST|PUT|PATCH|DELETE)\s+/i;
+    const match = name.match(methodPrefix);
+    if (match) {
+        const method = match[1].toUpperCase();
+        candidates.push(`HTTP ${method} ${name.slice(match[0].length)}`);
+    }
+    return candidates;
+}
+class TraceSanitizer {
+    contractMap;
+    hashConfig;
+    forbiddenAttributes;
+    droppedAttributes;
+    hashedAttributes;
+    attributeAllowlistPassthrough;
+    constructor(options) {
+        this.hashConfig = options.hashConfig;
+        this.forbiddenAttributes = options.forbiddenAttributes;
+        this.droppedAttributes = options.droppedAttributes;
+        this.hashedAttributes = options.hashedAttributes;
+        this.attributeAllowlistPassthrough =
+            options.attributeAllowlistPassthrough ?? false;
+        const definitions = options.spanDefinitions ?? tier2_traces_js_1.TIER_2_TRACE_CONTRACT;
+        this.contractMap = new Map();
+        for (const def of definitions) {
+            this.contractMap.set(def.name, def);
+        }
+    }
+    /**
+     * Check if a span should be exported to Tier 2.
+     */
+    shouldExport(span) {
+        return this.findMatchingDefinition(span.name) !== undefined;
+    }
+    /**
+     * Sanitize span attributes for Tier 2 export.
+     * Returns null if span should not be exported.
+     *
+     * Returns a ReadableSpan-like object that delegates to the original span for
+     * spanContext() and other methods (spread does not copy prototype methods,
+     * and the OTLP exporter calls span.spanContext()).
+     */
+    sanitize(span) {
+        const httpRoute = span.attributes["http.route"];
+        const routeStr = typeof httpRoute === "string"
+            ? httpRoute
+            : typeof httpRoute === "number"
+                ? String(httpRoute)
+                : undefined;
+        if (routeStr !== undefined && DROPPED_HTTP_ROUTES.has(routeStr)) {
+            return null;
+        }
+        const definition = this.findMatchingDefinition(span.name);
+        if (!definition) {
+            return null;
+        }
+        const sanitizedAttributes = this.sanitizeAttributes(span.attributes, definition.allowedAttributes);
+        return {
+            name: span.name,
+            kind: span.kind,
+            spanContext: () => span.spanContext(),
+            // Preserve parent context exactly as OTLP serializers consume it.
+            // In current OTel SDK versions, parent linkage is read from
+            // `parentSpanContext` (not `parentSpanId`).
+            // https://github.com/open-telemetry/opentelemetry-js/blob/main/experimental/packages/otlp-transformer/src/trace/internal.ts#L44
+            parentSpanContext: span.parentSpanContext,
+            startTime: span.startTime,
+            endTime: span.endTime,
+            status: span.status,
+            attributes: sanitizedAttributes,
+            resource: span.resource,
+            instrumentationScope: span.instrumentationScope,
+            events: this.sanitizeEvents(span.events),
+            links: this.sanitizeLinks(span.links),
+            duration: span.duration,
+            ended: span.ended,
+            droppedAttributesCount: span.droppedAttributesCount,
+            droppedEventsCount: span.droppedEventsCount,
+            droppedLinksCount: span.droppedLinksCount,
+        };
+    }
+    findMatchingDefinition(spanName) {
+        const candidates = normalizeSpanNameForMatching(spanName);
+        for (const name of candidates) {
+            if (this.contractMap.has(name)) {
+                return this.contractMap.get(name);
+            }
+            for (const [pattern, def] of this.contractMap) {
+                if (this.matchesPattern(name, pattern)) {
+                    return def;
+                }
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Pattern matching: "*" matches any name; suffix wildcards (e.g. "HTTP POST *", "ws.*").
+     * For "HTTP POST *", matches "HTTP POST" (exact) or "HTTP POST /path" (prefix + rest).
+     */
+    matchesPattern(name, pattern) {
+        if (pattern === "*") {
+            return true;
+        }
+        if (pattern.endsWith("*")) {
+            const prefix = pattern.slice(0, -1);
+            const prefixNoSpace = prefix.trimEnd();
+            return (name === prefixNoSpace ||
+                name === prefix ||
+                (prefix.length > 0 && name.startsWith(prefix)));
+        }
+        return name === pattern;
+    }
+    /**
+     * Sanitize span links for Tier 2: link attributes are filtered the same way as
+     * event attributes (forbidden dropped, high-cardinality dropped, hashed values).
+     * Link context (trace/span IDs) is preserved.
+     */
+    sanitizeLinks(links) {
+        if (!links?.length) {
+            return links ?? [];
+        }
+        return links.map((link) => ({
+            ...link,
+            attributes: this.sanitizeEventOrLinkAttributes(link.attributes ?? {}),
+        }));
+    }
+    /**
+     * Sanitize span events for Tier 2: event attributes are filtered the same way as
+     * span attributes (forbidden dropped, high-cardinality dropped, hashed values).
+     * Event names and timestamps are preserved.
+     */
+    sanitizeEvents(events) {
+        if (!events?.length) {
+            return events ?? [];
+        }
+        return events.map((event) => ({
+            name: event.name,
+            time: event.time,
+            attributes: this.sanitizeEventOrLinkAttributes(event.attributes ?? {}),
+        }));
+    }
+    /**
+     * Sanitize attributes that appear on events or links (no allowlist; only
+     * drop forbidden/high-cardinality and hash hashed).
+     */
+    sanitizeEventOrLinkAttributes(attributes) {
+        const result = {};
+        for (const [key, value] of Object.entries(attributes)) {
+            if (this.forbiddenAttributes.has(key)) {
+                continue;
+            }
+            if (this.droppedAttributes.has(key)) {
+                continue;
+            }
+            if (this.hashedAttributes.has(key)) {
+                result[key] = this.hashValue(String(value));
+                continue;
+            }
+            result[key] = value;
+        }
+        return result;
+    }
+    sanitizeAttributes(attributes, allowedAttrs) {
+        const result = {};
+        const allowedMap = new Map();
+        for (const attr of allowedAttrs) {
+            allowedMap.set((0, tier2_traces_js_1.getAttributeName)(attr), attr);
+        }
+        for (const [key, value] of Object.entries(attributes)) {
+            if (this.forbiddenAttributes.has(key)) {
+                continue;
+            }
+            if (this.droppedAttributes.has(key)) {
+                continue;
+            }
+            if (this.hashedAttributes.has(key)) {
+                result[key] = this.hashValue(String(value));
+                continue;
+            }
+            if (this.attributeAllowlistPassthrough) {
+                result[key] = value;
+                continue;
+            }
+            if (!allowedMap.has(key)) {
+                continue;
+            }
+            const attrDef = allowedMap.get(key);
+            if (typeof attrDef === "object" && attrDef.allowedValues != null) {
+                if (!attrDef.allowedValues.includes(String(value))) {
+                    continue;
+                }
+            }
+            result[key] = value;
+        }
+        return result;
+    }
+    hashValue(value) {
+        if (!this.hashConfig) {
+            return "[redacted]";
+        }
+        const hmac = (0, node_crypto_1.createHmac)(this.hashConfig.algorithm, this.hashConfig.secretKey);
+        hmac.update(this.hashConfig.salt);
+        hmac.update(value);
+        return hmac.digest("hex").slice(0, this.hashConfig.outputLengthBytes * 2);
+    }
+}
+exports.TraceSanitizer = TraceSanitizer;
+//# sourceMappingURL=trace-sanitizer.js.map

package/dist/common/trace-sanitizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-sanitizer.js","sourceRoot":"","sources":["../../src/common/trace-sanitizer.ts"],"names":[],"mappings":"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"}

package/dist/common/traced-socket-types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared TracedSocket types for WebSocket message envelopes.
+ *
+ * Both the browser (TracedSocket in telemetry/browser) and the server
+ * (TracedSocket in telemetry/node) inject and extract trace context using
+ * these field names. Keeping them in one place ensures the two sides speak
+ * the same envelope protocol so traces link correctly end-to-end.
+ *
+ * Envelope structure mirrors @superblocksteam/shared SocketRequest:
+ *   { request?: { method, payload, id, traceparent?, tracestate?, ... } }
+ *
+ * The W3C Trace Context propagator writes/reads exactly these two fields.
+ * See: https://www.w3.org/TR/trace-context/
+ */
+/**
+ * W3C Trace Context fields that live inside a socket message's request object.
+ * The propagator uses these as the carrier for context injection/extraction.
+ */
+export interface SocketTraceContext {
+    traceparent?: string;
+    tracestate?: string;
+}
+/**
+ * Minimal shape of the request portion of a socket message envelope.
+ * Both browser and server code passes this object as the propagation carrier.
+ */
+export interface SocketRequestEnvelope extends SocketTraceContext {
+    method?: string;
+    id?: number;
+    [key: string]: unknown;
+}
+/**
+ * Minimal shape of the full socket message envelope.
+ * Request messages carry trace context; response messages do not.
+ */
+export interface SocketMessageEnvelope {
+    request?: SocketRequestEnvelope;
+    response?: {
+        id?: number;
+        [key: string]: unknown;
+    };
+}
+//# sourceMappingURL=traced-socket-types.d.ts.map

package/dist/common/traced-socket-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traced-socket-types.d.ts","sourceRoot":"","sources":["../../src/common/traced-socket-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAsB,SAAQ,kBAAkB;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAChC,QAAQ,CAAC,EAAE;QACT,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;CACH"}

package/dist/common/traced-socket-types.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * Shared TracedSocket types for WebSocket message envelopes.
+ *
+ * Both the browser (TracedSocket in telemetry/browser) and the server
+ * (TracedSocket in telemetry/node) inject and extract trace context using
+ * these field names. Keeping them in one place ensures the two sides speak
+ * the same envelope protocol so traces link correctly end-to-end.
+ *
+ * Envelope structure mirrors @superblocksteam/shared SocketRequest:
+ *   { request?: { method, payload, id, traceparent?, tracestate?, ... } }
+ *
+ * The W3C Trace Context propagator writes/reads exactly these two fields.
+ * See: https://www.w3.org/TR/trace-context/
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=traced-socket-types.js.map

package/dist/common/traced-socket-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traced-socket-types.js","sourceRoot":"","sources":["../../src/common/traced-socket-types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG"}

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @superblocksteam/telemetry
+ *
+ * Canonical telemetry bootstrap package for all Superblocks services.
+ * Provides policy-aware OpenTelemetry initialization with tier-based routing.
+ *
+ * This package is the ONLY approved way to initialize telemetry.
+ * Direct usage of NodeSDK or WebTracerProvider is prohibited.
+ *
+ * ## Usage
+ *
+ * ### Node.js Services
+ *
+ * ```typescript
+ * import { initNodeTelemetry } from '@superblocksteam/telemetry/node';
+ * import { getDefaultPolicy, DeploymentType } from '@superblocksteam/shared';
+ *
+ * const policy = getDefaultPolicy(DeploymentType.CLOUD_PREM);
+ * const telemetry = initNodeTelemetry({
+ *   serviceName: 'my-service',
+ *   serviceVersion: '1.0.0',
+ *   environment: 'production',
+ *   otlpUrl: 'http://localhost:4318',
+ * }, policy);
+ * ```
+ *
+ * ### Browser
+ *
+ * ```typescript
+ * import { initBrowserTelemetry } from '@superblocksteam/telemetry/browser';
+ * ```
+ *
+ * ### Testing
+ *
+ * ```typescript
+ * import { initTestTelemetry } from '@superblocksteam/telemetry/testing';
+ * ```
+ */
+export * from "./types/index.js";
+export * from "./common/index.js";
+export * from "./npm-registry/index.js";
+export * from "./llmobs/index.js";
+export { REDACTED_PLACEHOLDER } from "./common/index.js";
+export { createSafeLogger, getLoggingPolicy, getMinimumPinoLevelForDeployment, getMinimumPinoLevelFromLoggingPolicy, parseLogExportMode, getTelemetryInstance, initNodeTelemetry, isLocalObsMode, isTelemetryInitialized, LogExportMode, redactForbiddenFields, resetTelemetry, type NodeTelemetryInstance, type LoggingPolicyConfig, type SafeLoggerLike, MetricsClient, type Labels, type CounterHandle, type CounterOptions, type GaugeHandle, type HistogramHandle, type HistogramOptions, TracedSocket, type TracedSocketConfig, type TracedSocketOptions, } from "./node/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAGH,cAAc,kBAAkB,CAAC;AAGjC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,yBAAyB,CAAC;AAGxC,cAAc,mBAAmB,CAAC;AAIlC,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,gCAAgC,EAChC,oCAAoC,EACpC,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,cAAc,EACd,sBAAsB,EACtB,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,aAAa,EACb,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,YAAY,EACZ,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * @superblocksteam/telemetry
+ *
+ * Canonical telemetry bootstrap package for all Superblocks services.
+ * Provides policy-aware OpenTelemetry initialization with tier-based routing.
+ *
+ * This package is the ONLY approved way to initialize telemetry.
+ * Direct usage of NodeSDK or WebTracerProvider is prohibited.
+ *
+ * ## Usage
+ *
+ * ### Node.js Services
+ *
+ * ```typescript
+ * import { initNodeTelemetry } from '@superblocksteam/telemetry/node';
+ * import { getDefaultPolicy, DeploymentType } from '@superblocksteam/shared';
+ *
+ * const policy = getDefaultPolicy(DeploymentType.CLOUD_PREM);
+ * const telemetry = initNodeTelemetry({
+ *   serviceName: 'my-service',
+ *   serviceVersion: '1.0.0',
+ *   environment: 'production',
+ *   otlpUrl: 'http://localhost:4318',
+ * }, policy);
+ * ```
+ *
+ * ### Browser
+ *
+ * ```typescript
+ * import { initBrowserTelemetry } from '@superblocksteam/telemetry/browser';
+ * ```
+ *
+ * ### Testing
+ *
+ * ```typescript
+ * import { initTestTelemetry } from '@superblocksteam/telemetry/testing';
+ * ```
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TracedSocket = exports.MetricsClient = exports.resetTelemetry = exports.redactForbiddenFields = exports.LogExportMode = exports.isTelemetryInitialized = exports.isLocalObsMode = exports.initNodeTelemetry = exports.getTelemetryInstance = exports.parseLogExportMode = exports.getMinimumPinoLevelFromLoggingPolicy = exports.getMinimumPinoLevelForDeployment = exports.getLoggingPolicy = exports.createSafeLogger = exports.REDACTED_PLACEHOLDER = void 0;
+// Re-export types
+__exportStar(require("./types/index.js"), exports);
+// Re-export common utilities
+__exportStar(require("./common/index.js"), exports);
+// Re-export npm-registry telemetry (sanitization, metrics emitter, spans)
+__exportStar(require("./npm-registry/index.js"), exports);
+// Re-export LLMObs tiered telemetry
+__exportStar(require("./llmobs/index.js"), exports);
+// Re-export Node.js telemetry functions for convenience
+// This allows imports like: import { initNodeTelemetry } from '@superblocksteam/telemetry'
+var index_js_1 = require("./common/index.js");
+Object.defineProperty(exports, "REDACTED_PLACEHOLDER", { enumerable: true, get: function () { return index_js_1.REDACTED_PLACEHOLDER; } });
+var index_js_2 = require("./node/index.js");
+Object.defineProperty(exports, "createSafeLogger", { enumerable: true, get: function () { return index_js_2.createSafeLogger; } });
+Object.defineProperty(exports, "getLoggingPolicy", { enumerable: true, get: function () { return index_js_2.getLoggingPolicy; } });
+Object.defineProperty(exports, "getMinimumPinoLevelForDeployment", { enumerable: true, get: function () { return index_js_2.getMinimumPinoLevelForDeployment; } });
+Object.defineProperty(exports, "getMinimumPinoLevelFromLoggingPolicy", { enumerable: true, get: function () { return index_js_2.getMinimumPinoLevelFromLoggingPolicy; } });
+Object.defineProperty(exports, "parseLogExportMode", { enumerable: true, get: function () { return index_js_2.parseLogExportMode; } });
+Object.defineProperty(exports, "getTelemetryInstance", { enumerable: true, get: function () { return index_js_2.getTelemetryInstance; } });
+Object.defineProperty(exports, "initNodeTelemetry", { enumerable: true, get: function () { return index_js_2.initNodeTelemetry; } });
+Object.defineProperty(exports, "isLocalObsMode", { enumerable: true, get: function () { return index_js_2.isLocalObsMode; } });
+Object.defineProperty(exports, "isTelemetryInitialized", { enumerable: true, get: function () { return index_js_2.isTelemetryInitialized; } });
+Object.defineProperty(exports, "LogExportMode", { enumerable: true, get: function () { return index_js_2.LogExportMode; } });
+Object.defineProperty(exports, "redactForbiddenFields", { enumerable: true, get: function () { return index_js_2.redactForbiddenFields; } });
+Object.defineProperty(exports, "resetTelemetry", { enumerable: true, get: function () { return index_js_2.resetTelemetry; } });
+Object.defineProperty(exports, "MetricsClient", { enumerable: true, get: function () { return index_js_2.MetricsClient; } });
+Object.defineProperty(exports, "TracedSocket", { enumerable: true, get: function () { return index_js_2.TracedSocket; } });
+// Note: Browser and Testing modules are still exported via package.json subpath exports
+// Import them as:
+//   - @superblocksteam/telemetry/browser
+//   - @superblocksteam/telemetry/testing
+//   - @superblocksteam/telemetry/llmobs
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;;;;;;;;;;;;;;;;;AAEH,kBAAkB;AAClB,mDAAiC;AAEjC,6BAA6B;AAC7B,oDAAkC;AAElC,0EAA0E;AAC1E,0DAAwC;AAExC,oCAAoC;AACpC,oDAAkC;AAElC,wDAAwD;AACxD,2FAA2F;AAC3F,8CAAyD;AAAhD,gHAAA,oBAAoB,OAAA;AAC7B,4CA0ByB;AAzBvB,4GAAA,gBAAgB,OAAA;AAChB,4GAAA,gBAAgB,OAAA;AAChB,4HAAA,gCAAgC,OAAA;AAChC,gIAAA,oCAAoC,OAAA;AACpC,8GAAA,kBAAkB,OAAA;AAClB,gHAAA,oBAAoB,OAAA;AACpB,6GAAA,iBAAiB,OAAA;AACjB,0GAAA,cAAc,OAAA;AACd,kHAAA,sBAAsB,OAAA;AACtB,yGAAA,aAAa,OAAA;AACb,iHAAA,qBAAqB,OAAA;AACrB,0GAAA,cAAc,OAAA;AAId,yGAAA,aAAa,OAAA;AAOb,wGAAA,YAAY,OAAA;AAKd,wFAAwF;AACxF,kBAAkB;AAClB,yCAAyC;AACzC,yCAAyC;AACzC,wCAAwC"}

package/dist/lint/forbidden-attributes.d.ts

@@ -0,0 +1,149 @@
+/**
+ * ESLint Rule: No Forbidden Telemetry Attributes
+ *
+ * This rule detects usage of forbidden attributes in span/metric instrumentation.
+ * It catches common leak paths before code is merged.
+ *
+ * Usage in eslint.config.js:
+ * ```
+ * import { noForbiddenTelemetryAttributes } from '@superblocksteam/telemetry/lint';
+ *
+ * export default [
+ *   {
+ *     plugins: {
+ *       telemetry: { rules: { 'no-forbidden-attributes': noForbiddenTelemetryAttributes } }
+ *     },
+ *     rules: {
+ *       'telemetry/no-forbidden-attributes': 'error'
+ *     }
+ *   }
+ * ];
+ * ```
+ */
+/**
+ * Forbidden attribute patterns for static analysis.
+ */
+export declare const FORBIDDEN_ATTRIBUTE_PATTERNS: string[];
+/**
+ * ESLint rule metadata.
+ */
+export declare const noForbiddenTelemetryAttributesMeta: {
+    type: string;
+    docs: {
+        description: string;
+        category: string;
+        recommended: boolean;
+    };
+    messages: {
+        forbiddenAttribute: string;
+        resourceOnlyAttribute: string;
+    };
+    schema: never[];
+};
+/**
+ * ESLint rule implementation.
+ *
+ * Detects patterns like:
+ * - span.setAttribute('prompt', value)
+ * - span.setAttributes({ prompt: value })
+ * - { 'prompt': value }
+ */
+export declare function noForbiddenTelemetryAttributesCreate(context: any): {
+    CallExpression(node: any): void;
+    Property(node: any): void;
+};
+/**
+ * Complete ESLint rule export.
+ */
+export declare const noForbiddenTelemetryAttributes: {
+    meta: {
+        type: string;
+        docs: {
+            description: string;
+            category: string;
+            recommended: boolean;
+        };
+        messages: {
+            forbiddenAttribute: string;
+            resourceOnlyAttribute: string;
+        };
+        schema: never[];
+    };
+    create: typeof noForbiddenTelemetryAttributesCreate;
+};
+/**
+ * ESLint rule: No Direct OTEL SDK Usage
+ *
+ * Detects direct usage of NodeSDK or WebTracerProvider outside the telemetry package.
+ */
+export declare const noDirectOtelSdkMeta: {
+    type: string;
+    docs: {
+        description: string;
+        category: string;
+        recommended: boolean;
+    };
+    messages: {
+        directSdkUsage: string;
+    };
+    schema: never[];
+};
+export declare function noDirectOtelSdkCreate(context: any): {
+    ImportSpecifier?: undefined;
+    CallExpression?: undefined;
+} | {
+    ImportSpecifier(node: any): void;
+    CallExpression(node: any): void;
+};
+export declare const noDirectOtelSdk: {
+    meta: {
+        type: string;
+        docs: {
+            description: string;
+            category: string;
+            recommended: boolean;
+        };
+        messages: {
+            directSdkUsage: string;
+        };
+        schema: never[];
+    };
+    create: typeof noDirectOtelSdkCreate;
+};
+/**
+ * All telemetry ESLint rules.
+ */
+export declare const telemetryRules: {
+    "no-forbidden-attributes": {
+        meta: {
+            type: string;
+            docs: {
+                description: string;
+                category: string;
+                recommended: boolean;
+            };
+            messages: {
+                forbiddenAttribute: string;
+                resourceOnlyAttribute: string;
+            };
+            schema: never[];
+        };
+        create: typeof noForbiddenTelemetryAttributesCreate;
+    };
+    "no-direct-otel-sdk": {
+        meta: {
+            type: string;
+            docs: {
+                description: string;
+                category: string;
+                recommended: boolean;
+            };
+            messages: {
+                directSdkUsage: string;
+            };
+            schema: never[];
+        };
+        create: typeof noDirectOtelSdkCreate;
+    };
+};
+//# sourceMappingURL=forbidden-attributes.d.ts.map

package/dist/lint/forbidden-attributes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forbidden-attributes.d.ts","sourceRoot":"","sources":["../../src/lint/forbidden-attributes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAOH;;GAEG;AACH,eAAO,MAAM,4BAA4B,UAKxC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kCAAkC;;;;;;;;;;;;CAgB9C,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,oCAAoC,CAAC,OAAO,EAAE,GAAG;yBAsBxC,GAAG;mBAgCT,GAAG;EAuBrB;AAED;;GAEG;AACH,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;CAG1C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;CAc/B,CAAC;AAYF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,GAAG;;;;0BASxB,GAAG;yBAYJ,GAAG;EAsB3B;AAED,eAAO,MAAM,eAAe;;;;;;;;;;;;;;CAG3B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAG1B,CAAC"}