@harness-engineering/core 0.26.0 → 0.26.2

package/dist/index.js

@@ -55,6 +55,7 @@ __export(index_exports, {
   CINotifier: () => CINotifier,
   COMPLIANCE_DESCRIPTOR: () => COMPLIANCE_DESCRIPTOR,
   CORROBORATED_AGREEMENT: () => CORROBORATED_AGREEMENT,
+  CacheMetricsRecorder: () => CacheMetricsRecorder,
   CategoryBaselineSchema: () => CategoryBaselineSchema,
   CategoryForecastSchema: () => CategoryForecastSchema,
   CategoryRegressionSchema: () => CategoryRegressionSchema,
@@ -119,6 +120,7 @@ __export(index_exports, {
   NoOpExecutor: () => NoOpExecutor,
   NoOpSink: () => NoOpSink,
   NoOpTelemetryAdapter: () => NoOpTelemetryAdapter,
+  OTLPExporter: () => OTLPExporter,
   OpenAICacheAdapter: () => OpenAICacheAdapter,
   PII_FIELD_DENYLIST: () => PII_FIELD_DENYLIST,
   PII_LINE_RE: () => PII_LINE_RE,
@@ -157,6 +159,7 @@ __export(index_exports, {
   SharableSecurityRulesSchema: () => SharableSecurityRulesSchema,
   SkillEventSchema: () => SkillEventSchema,
   SolutionDocFrontmatterSchema: () => SolutionDocFrontmatterSchema,
+  SpanKind: () => SpanKind,
   SpecImpactEstimateSchema: () => SpecImpactEstimateSchema,
   SpecImpactEstimator: () => SpecImpactEstimator,
   SpecImpactSignalsSchema: () => SpecImpactSignalsSchema,
@@ -325,6 +328,7 @@ __export(index_exports, {
   goRules: () => goRules,
   injectionRules: () => injectionRules,
   insecureDefaultsRules: () => insecureDefaultsRules,
+  invalidateCheckState: () => invalidateCheckState,
   isBadPort: () => isBadPort,
   isDuplicateFinding: () => isDuplicateFinding,
   isRegression: () => isRegression,
@@ -5645,7 +5649,10 @@ function findDeadFiles(snapshot, reachability) {
   return deadFiles;
 }
 function isIdentifierUsedInAST(ast, identifier, skipImportDeclaration = true) {
-  const astString = JSON.stringify(ast);
+  const astString = JSON.stringify(
+    ast,
+    (_key, value) => typeof value === "bigint" ? value.toString() : value
+  );
   const identifierPattern = new RegExp(`"name"\\s*:\\s*"${identifier}"`, "g");
   const matches = astString.match(identifierPattern);
   if (!matches) return false;
@@ -20193,6 +20200,12 @@ function shouldRunCheck(state, intervalMs) {
   if (state === null) return true;
   return state.lastCheckTime + intervalMs <= Date.now();
 }
+function invalidateCheckState() {
+  try {
+    fs36.unlinkSync(getStatePath());
+  } catch {
+  }
+}
 function readCheckState() {
   try {
     const raw = fs36.readFileSync(getStatePath(), "utf-8");
@@ -21390,7 +21403,7 @@ function resolveConsent(projectRoot, config) {
 }
 
 // src/version.ts
-var VERSION = "0.23.3";
+var VERSION = "0.25.0";
 
 // src/telemetry/collector.ts
 function mapOutcome(outcome) {
@@ -21451,6 +21464,221 @@ async function send(events, apiKey) {
   }
 }
 
+// src/telemetry/cache-metrics.ts
+var DEFAULT_CAPACITY = 1e3;
+var CacheMetricsRecorder = class {
+  capacity;
+  now;
+  buffer = [];
+  windowStartedAt = 0;
+  constructor(opts = {}) {
+    this.capacity = opts.capacity ?? DEFAULT_CAPACITY;
+    this.now = opts.now ?? Date.now;
+  }
+  /**
+   * Append a single cache observation. Hot-path: O(1) amortized, no
+   * allocations beyond the sample object itself.
+   */
+  record(backendId, hit, tokensCreated, tokensRead) {
+    if (this.windowStartedAt === 0) this.windowStartedAt = this.now();
+    if (this.buffer.length >= this.capacity) this.buffer.shift();
+    this.buffer.push({ backendId, hit, tokensCreated, tokensRead });
+  }
+  /** Aggregate the current window into a `PromptCacheStats` snapshot. */
+  getStats() {
+    let hits = 0;
+    let misses = 0;
+    const byBackend = {};
+    for (const s of this.buffer) {
+      if (s.hit) hits++;
+      else misses++;
+      const slot = byBackend[s.backendId] ?? { hits: 0, misses: 0 };
+      if (s.hit) slot.hits++;
+      else slot.misses++;
+      byBackend[s.backendId] = slot;
+    }
+    const totalRequests = hits + misses;
+    const hitRate = totalRequests === 0 ? 0 : hits / totalRequests;
+    return {
+      totalRequests,
+      hits,
+      misses,
+      hitRate,
+      byBackend,
+      windowStartedAt: this.windowStartedAt
+    };
+  }
+  /** Clear the buffer and reset the window-start marker. */
+  reset() {
+    this.buffer.length = 0;
+    this.windowStartedAt = 0;
+  }
+};
+
+// src/telemetry/exporter/otlp-http.ts
+var RETRY_BACKOFFS_MS = [1e3, 2e3, 4e3];
+function toUnixNanoString(ns) {
+  return ns.toString(10);
+}
+function attributesToOTLP(attrs) {
+  const out = [];
+  for (const [key, value] of Object.entries(attrs)) {
+    if (typeof value === "string") {
+      out.push({ key, value: { stringValue: value } });
+    } else if (typeof value === "boolean") {
+      out.push({ key, value: { boolValue: value } });
+    } else if (typeof value === "number") {
+      if (Number.isInteger(value)) {
+        out.push({ key, value: { intValue: String(value) } });
+      } else {
+        out.push({ key, value: { doubleValue: value } });
+      }
+    }
+  }
+  return out;
+}
+var OTLPExporter = class {
+  endpoint;
+  enabled;
+  headers;
+  flushIntervalMs;
+  batchSize;
+  fetchImpl;
+  warn;
+  buffer = [];
+  timer = null;
+  inFlightFlushes = /* @__PURE__ */ new Set();
+  constructor(opts) {
+    this.endpoint = opts.endpoint;
+    this.enabled = opts.enabled !== false;
+    this.headers = { "Content-Type": "application/json", ...opts.headers ?? {} };
+    this.flushIntervalMs = opts.flushIntervalMs ?? 2e3;
+    this.batchSize = opts.batchSize ?? 64;
+    this.fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    this.warn = opts.warn ?? ((...a) => console.warn(...a));
+  }
+  /**
+   * O(1) buffer push. When `enabled === false` this is a no-op. If the
+   * buffer reaches `batchSize`, a flush is triggered without awaiting.
+   */
+  push(span) {
+    if (!this.enabled) return;
+    this.buffer.push(span);
+    if (this.buffer.length >= this.batchSize) {
+      void this.flush();
+    }
+  }
+  /** Start the periodic flush timer. Idempotent. */
+  start() {
+    if (!this.enabled || this.timer !== null) return;
+    this.timer = setInterval(() => {
+      void this.flush();
+    }, this.flushIntervalMs);
+    if (typeof this.timer.unref === "function") {
+      this.timer.unref();
+    }
+  }
+  /** Flush any pending spans and stop the timer. Awaits all in-flight flushes. */
+  async stop() {
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    void this.flush();
+    while (this.inFlightFlushes.size > 0) {
+      await Promise.all([...this.inFlightFlushes]);
+    }
+  }
+  /**
+   * Synchronously claim the current buffer and POST it to `/v1/traces`.
+   * Each invocation runs independently — concurrent flushes (e.g. one
+   * from the timer, one from a `batchSize` trip) each drain their own
+   * batch. Retries up to 3 times on transport or 5xx failure, then
+   * drops with a single warning.
+   */
+  flush() {
+    if (this.buffer.length === 0) return Promise.resolve();
+    const batch = this.buffer;
+    this.buffer = [];
+    const payload = this.spansToOTLPJSON(batch);
+    const work = (async () => {
+      let lastError = null;
+      for (let attempt = 0; attempt < RETRY_BACKOFFS_MS.length; attempt++) {
+        try {
+          const response = await this.fetchImpl(this.endpoint, {
+            method: "POST",
+            headers: this.headers,
+            body: JSON.stringify(payload)
+          });
+          if (response.ok) return;
+          try {
+            await response.text();
+          } catch {
+          }
+          lastError = new Error(`OTLP endpoint returned ${response.status}`);
+        } catch (err) {
+          lastError = err;
+        }
+        const backoff = RETRY_BACKOFFS_MS[attempt] ?? 0;
+        if (attempt < RETRY_BACKOFFS_MS.length - 1) {
+          await new Promise((resolve12) => setTimeout(resolve12, backoff));
+        }
+      }
+      this.warn(
+        `[harness telemetry] dropping ${batch.length} span(s) after 3 failed OTLP attempts:`,
+        lastError
+      );
+    })();
+    this.inFlightFlushes.add(work);
+    void work.finally(() => this.inFlightFlushes.delete(work));
+    return work;
+  }
+  /**
+   * Build the OTLP/HTTP JSON envelope for a batch of spans. Public for
+   * tests; not part of the supported API surface.
+   */
+  spansToOTLPJSON(spans) {
+    return {
+      resourceSpans: [
+        {
+          resource: {
+            attributes: [{ key: "service.name", value: { stringValue: "harness" } }]
+          },
+          scopeSpans: [
+            {
+              scope: { name: "harness" },
+              spans: spans.map((s) => {
+                const span = {
+                  traceId: s.traceId,
+                  spanId: s.spanId,
+                  name: s.name,
+                  kind: s.kind,
+                  startTimeUnixNano: toUnixNanoString(s.startTimeNs),
+                  endTimeUnixNano: toUnixNanoString(s.endTimeNs),
+                  attributes: attributesToOTLP(s.attributes)
+                };
+                if (s.parentSpanId !== void 0) span["parentSpanId"] = s.parentSpanId;
+                if (s.statusCode !== void 0) span["status"] = { code: s.statusCode };
+                return span;
+              })
+            }
+          ]
+        }
+      ]
+    };
+  }
+};
+
+// src/telemetry/exporter/types.ts
+var SpanKind = /* @__PURE__ */ ((SpanKind2) => {
+  SpanKind2[SpanKind2["INTERNAL"] = 1] = "INTERNAL";
+  SpanKind2[SpanKind2["SERVER"] = 2] = "SERVER";
+  SpanKind2[SpanKind2["CLIENT"] = 3] = "CLIENT";
+  SpanKind2[SpanKind2["PRODUCER"] = 4] = "PRODUCER";
+  SpanKind2[SpanKind2["CONSUMER"] = 5] = "CONSUMER";
+  return SpanKind2;
+})(SpanKind || {});
+
 // src/locks/compound-lock.ts
 var fs43 = __toESM(require("fs"));
 var path43 = __toESM(require("path"));
@@ -22210,6 +22438,7 @@ function assembleCandidateReport(input) {
   CINotifier,
   COMPLIANCE_DESCRIPTOR,
   CORROBORATED_AGREEMENT,
+  CacheMetricsRecorder,
   CategoryBaselineSchema,
   CategoryForecastSchema,
   CategoryRegressionSchema,
@@ -22274,6 +22503,7 @@ function assembleCandidateReport(input) {
   NoOpExecutor,
   NoOpSink,
   NoOpTelemetryAdapter,
+  OTLPExporter,
   OpenAICacheAdapter,
   PII_FIELD_DENYLIST,
   PII_LINE_RE,
@@ -22312,6 +22542,7 @@ function assembleCandidateReport(input) {
   SharableSecurityRulesSchema,
   SkillEventSchema,
   SolutionDocFrontmatterSchema,
+  SpanKind,
   SpecImpactEstimateSchema,
   SpecImpactEstimator,
   SpecImpactSignalsSchema,
@@ -22480,6 +22711,7 @@ function assembleCandidateReport(input) {
   goRules,
   injectionRules,
   insecureDefaultsRules,
+  invalidateCheckState,
   isBadPort,
   isDuplicateFinding,
   isRegression,

package/dist/index.mjs

@@ -3988,7 +3988,10 @@ function findDeadFiles(snapshot, reachability) {
   return deadFiles;
 }
 function isIdentifierUsedInAST(ast, identifier, skipImportDeclaration = true) {
-  const astString = JSON.stringify(ast);
+  const astString = JSON.stringify(
+    ast,
+    (_key, value) => typeof value === "bigint" ? value.toString() : value
+  );
   const identifierPattern = new RegExp(`"name"\\s*:\\s*"${identifier}"`, "g");
   const matches = astString.match(identifierPattern);
   if (!matches) return false;
@@ -16920,6 +16923,12 @@ function shouldRunCheck(state, intervalMs) {
   if (state === null) return true;
   return state.lastCheckTime + intervalMs <= Date.now();
 }
+function invalidateCheckState() {
+  try {
+    fs36.unlinkSync(getStatePath());
+  } catch {
+  }
+}
 function readCheckState() {
   try {
     const raw = fs36.readFileSync(getStatePath(), "utf-8");
@@ -18117,7 +18126,7 @@ function resolveConsent(projectRoot, config) {
 }
 
 // src/version.ts
-var VERSION = "0.23.3";
+var VERSION = "0.25.0";
 
 // src/telemetry/collector.ts
 function mapOutcome(outcome) {
@@ -18178,6 +18187,221 @@ async function send(events, apiKey) {
   }
 }
 
+// src/telemetry/cache-metrics.ts
+var DEFAULT_CAPACITY = 1e3;
+var CacheMetricsRecorder = class {
+  capacity;
+  now;
+  buffer = [];
+  windowStartedAt = 0;
+  constructor(opts = {}) {
+    this.capacity = opts.capacity ?? DEFAULT_CAPACITY;
+    this.now = opts.now ?? Date.now;
+  }
+  /**
+   * Append a single cache observation. Hot-path: O(1) amortized, no
+   * allocations beyond the sample object itself.
+   */
+  record(backendId, hit, tokensCreated, tokensRead) {
+    if (this.windowStartedAt === 0) this.windowStartedAt = this.now();
+    if (this.buffer.length >= this.capacity) this.buffer.shift();
+    this.buffer.push({ backendId, hit, tokensCreated, tokensRead });
+  }
+  /** Aggregate the current window into a `PromptCacheStats` snapshot. */
+  getStats() {
+    let hits = 0;
+    let misses = 0;
+    const byBackend = {};
+    for (const s of this.buffer) {
+      if (s.hit) hits++;
+      else misses++;
+      const slot = byBackend[s.backendId] ?? { hits: 0, misses: 0 };
+      if (s.hit) slot.hits++;
+      else slot.misses++;
+      byBackend[s.backendId] = slot;
+    }
+    const totalRequests = hits + misses;
+    const hitRate = totalRequests === 0 ? 0 : hits / totalRequests;
+    return {
+      totalRequests,
+      hits,
+      misses,
+      hitRate,
+      byBackend,
+      windowStartedAt: this.windowStartedAt
+    };
+  }
+  /** Clear the buffer and reset the window-start marker. */
+  reset() {
+    this.buffer.length = 0;
+    this.windowStartedAt = 0;
+  }
+};
+
+// src/telemetry/exporter/otlp-http.ts
+var RETRY_BACKOFFS_MS = [1e3, 2e3, 4e3];
+function toUnixNanoString(ns) {
+  return ns.toString(10);
+}
+function attributesToOTLP(attrs) {
+  const out = [];
+  for (const [key, value] of Object.entries(attrs)) {
+    if (typeof value === "string") {
+      out.push({ key, value: { stringValue: value } });
+    } else if (typeof value === "boolean") {
+      out.push({ key, value: { boolValue: value } });
+    } else if (typeof value === "number") {
+      if (Number.isInteger(value)) {
+        out.push({ key, value: { intValue: String(value) } });
+      } else {
+        out.push({ key, value: { doubleValue: value } });
+      }
+    }
+  }
+  return out;
+}
+var OTLPExporter = class {
+  endpoint;
+  enabled;
+  headers;
+  flushIntervalMs;
+  batchSize;
+  fetchImpl;
+  warn;
+  buffer = [];
+  timer = null;
+  inFlightFlushes = /* @__PURE__ */ new Set();
+  constructor(opts) {
+    this.endpoint = opts.endpoint;
+    this.enabled = opts.enabled !== false;
+    this.headers = { "Content-Type": "application/json", ...opts.headers ?? {} };
+    this.flushIntervalMs = opts.flushIntervalMs ?? 2e3;
+    this.batchSize = opts.batchSize ?? 64;
+    this.fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    this.warn = opts.warn ?? ((...a) => console.warn(...a));
+  }
+  /**
+   * O(1) buffer push. When `enabled === false` this is a no-op. If the
+   * buffer reaches `batchSize`, a flush is triggered without awaiting.
+   */
+  push(span) {
+    if (!this.enabled) return;
+    this.buffer.push(span);
+    if (this.buffer.length >= this.batchSize) {
+      void this.flush();
+    }
+  }
+  /** Start the periodic flush timer. Idempotent. */
+  start() {
+    if (!this.enabled || this.timer !== null) return;
+    this.timer = setInterval(() => {
+      void this.flush();
+    }, this.flushIntervalMs);
+    if (typeof this.timer.unref === "function") {
+      this.timer.unref();
+    }
+  }
+  /** Flush any pending spans and stop the timer. Awaits all in-flight flushes. */
+  async stop() {
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    void this.flush();
+    while (this.inFlightFlushes.size > 0) {
+      await Promise.all([...this.inFlightFlushes]);
+    }
+  }
+  /**
+   * Synchronously claim the current buffer and POST it to `/v1/traces`.
+   * Each invocation runs independently — concurrent flushes (e.g. one
+   * from the timer, one from a `batchSize` trip) each drain their own
+   * batch. Retries up to 3 times on transport or 5xx failure, then
+   * drops with a single warning.
+   */
+  flush() {
+    if (this.buffer.length === 0) return Promise.resolve();
+    const batch = this.buffer;
+    this.buffer = [];
+    const payload = this.spansToOTLPJSON(batch);
+    const work = (async () => {
+      let lastError = null;
+      for (let attempt = 0; attempt < RETRY_BACKOFFS_MS.length; attempt++) {
+        try {
+          const response = await this.fetchImpl(this.endpoint, {
+            method: "POST",
+            headers: this.headers,
+            body: JSON.stringify(payload)
+          });
+          if (response.ok) return;
+          try {
+            await response.text();
+          } catch {
+          }
+          lastError = new Error(`OTLP endpoint returned ${response.status}`);
+        } catch (err) {
+          lastError = err;
+        }
+        const backoff = RETRY_BACKOFFS_MS[attempt] ?? 0;
+        if (attempt < RETRY_BACKOFFS_MS.length - 1) {
+          await new Promise((resolve10) => setTimeout(resolve10, backoff));
+        }
+      }
+      this.warn(
+        `[harness telemetry] dropping ${batch.length} span(s) after 3 failed OTLP attempts:`,
+        lastError
+      );
+    })();
+    this.inFlightFlushes.add(work);
+    void work.finally(() => this.inFlightFlushes.delete(work));
+    return work;
+  }
+  /**
+   * Build the OTLP/HTTP JSON envelope for a batch of spans. Public for
+   * tests; not part of the supported API surface.
+   */
+  spansToOTLPJSON(spans) {
+    return {
+      resourceSpans: [
+        {
+          resource: {
+            attributes: [{ key: "service.name", value: { stringValue: "harness" } }]
+          },
+          scopeSpans: [
+            {
+              scope: { name: "harness" },
+              spans: spans.map((s) => {
+                const span = {
+                  traceId: s.traceId,
+                  spanId: s.spanId,
+                  name: s.name,
+                  kind: s.kind,
+                  startTimeUnixNano: toUnixNanoString(s.startTimeNs),
+                  endTimeUnixNano: toUnixNanoString(s.endTimeNs),
+                  attributes: attributesToOTLP(s.attributes)
+                };
+                if (s.parentSpanId !== void 0) span["parentSpanId"] = s.parentSpanId;
+                if (s.statusCode !== void 0) span["status"] = { code: s.statusCode };
+                return span;
+              })
+            }
+          ]
+        }
+      ]
+    };
+  }
+};
+
+// src/telemetry/exporter/types.ts
+var SpanKind = /* @__PURE__ */ ((SpanKind2) => {
+  SpanKind2[SpanKind2["INTERNAL"] = 1] = "INTERNAL";
+  SpanKind2[SpanKind2["SERVER"] = 2] = "SERVER";
+  SpanKind2[SpanKind2["CLIENT"] = 3] = "CLIENT";
+  SpanKind2[SpanKind2["PRODUCER"] = 4] = "PRODUCER";
+  SpanKind2[SpanKind2["CONSUMER"] = 5] = "CONSUMER";
+  return SpanKind2;
+})(SpanKind || {});
+
 // src/locks/compound-lock.ts
 import * as fs43 from "fs";
 import * as path43 from "path";
@@ -18935,6 +19159,7 @@ export {
   CINotifier,
   COMPLIANCE_DESCRIPTOR,
   CORROBORATED_AGREEMENT,
+  CacheMetricsRecorder,
   CategoryBaselineSchema,
   CategoryForecastSchema,
   CategoryRegressionSchema,
@@ -18999,6 +19224,7 @@ export {
   NoOpExecutor,
   NoOpSink,
   NoOpTelemetryAdapter,
+  OTLPExporter,
   OpenAICacheAdapter,
   PII_FIELD_DENYLIST,
   PII_LINE_RE,
@@ -19037,6 +19263,7 @@ export {
   SharableSecurityRulesSchema,
   SkillEventSchema,
   SolutionDocFrontmatterSchema,
+  SpanKind,
   SpecImpactEstimateSchema,
   SpecImpactEstimator,
   SpecImpactSignalsSchema,
@@ -19205,6 +19432,7 @@ export {
   goRules,
   injectionRules,
   insecureDefaultsRules,
+  invalidateCheckState,
   isBadPort,
   isDuplicateFinding,
   isRegression,