@contractspec/lib.contracts 1.62.0 → 1.63.0

package/dist/telemetry/index.js

@@ -1,417 +0,0 @@
-// @bun
-var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __moduleCache = /* @__PURE__ */ new WeakMap;
-var __toCommonJS = (from) => {
-  var entry = __moduleCache.get(from), desc;
-  if (entry)
-    return entry;
-  entry = __defProp({}, "__esModule", { value: true });
-  if (from && typeof from === "object" || typeof from === "function")
-    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
-      get: () => from[key],
-      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-    }));
-  __moduleCache.set(from, entry);
-  return entry;
-};
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, {
-      get: all[name],
-      enumerable: true,
-      configurable: true,
-      set: (newValue) => all[name] = () => newValue
-    });
-};
-var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
-var __require = import.meta.require;
-
-// src/registry-utils.ts
-var exports_registry_utils = {};
-__export(exports_registry_utils, {
-  groupByToArray: () => groupByToArray,
-  groupByMultiple: () => groupByMultiple,
-  groupBy: () => groupBy,
-  getUniqueTags: () => getUniqueTags,
-  getUniqueOwners: () => getUniqueOwners,
-  getUniqueDomains: () => getUniqueDomains,
-  filterBy: () => filterBy,
-  GroupingStrategies: () => GroupingStrategies
-});
-function filterBy(items, filter) {
-  return items.filter((item) => {
-    if (filter.tags?.length) {
-      const hasMatchingTag = filter.tags.some((tag) => item.meta.tags?.includes(tag));
-      if (!hasMatchingTag)
-        return false;
-    }
-    if (filter.owners?.length) {
-      const hasMatchingOwner = filter.owners.some((owner) => item.meta.owners?.includes(owner));
-      if (!hasMatchingOwner)
-        return false;
-    }
-    if (filter.stability?.length) {
-      if (!filter.stability.includes(item.meta.stability ?? "stable")) {
-        return false;
-      }
-    }
-    if (filter.domain) {
-      const itemDomain = GroupingStrategies.byDomain(item);
-      if (itemDomain !== filter.domain)
-        return false;
-    }
-    if (filter.keyPattern) {
-      const name = item.meta.key ?? item.meta.key ?? "";
-      const pattern = filter.keyPattern.replace(/\*/g, ".*").replace(/\?/g, ".");
-      const regex = new RegExp(`^${pattern}$`, "i");
-      if (!regex.test(name))
-        return false;
-    }
-    return true;
-  });
-}
-function groupBy(items, keyFn) {
-  const groups = new Map;
-  for (const item of items) {
-    const key = keyFn(item);
-    const existing = groups.get(key);
-    if (existing) {
-      existing.push(item);
-    } else {
-      groups.set(key, [item]);
-    }
-  }
-  return groups;
-}
-function groupByToArray(items, keyFn) {
-  const map = groupBy(items, keyFn);
-  return Array.from(map.entries()).map(([key, items2]) => ({ key, items: items2 }));
-}
-function groupByMultiple(items, keysFn) {
-  const groups = new Map;
-  for (const item of items) {
-    const keys = keysFn(item);
-    for (const key of keys) {
-      const existing = groups.get(key);
-      if (existing) {
-        existing.push(item);
-      } else {
-        groups.set(key, [item]);
-      }
-    }
-  }
-  return groups;
-}
-function getUniqueTags(items) {
-  const tags = new Set;
-  for (const item of items) {
-    for (const tag of item.meta.tags ?? []) {
-      tags.add(tag);
-    }
-  }
-  return Array.from(tags).sort();
-}
-function getUniqueOwners(items) {
-  const owners = new Set;
-  for (const item of items) {
-    for (const owner of item.meta.owners ?? []) {
-      owners.add(owner);
-    }
-  }
-  return Array.from(owners).sort();
-}
-function getUniqueDomains(items) {
-  const domains = new Set;
-  for (const item of items) {
-    domains.add(GroupingStrategies.byDomain(item));
-  }
-  return Array.from(domains).sort();
-}
-var GroupingStrategies;
-var init_registry_utils = __esm(() => {
-  GroupingStrategies = {
-    byTag: (item) => item.meta.tags?.[0] ?? "untagged",
-    byAllTags: (item) => item.meta.tags?.length ? item.meta.tags : ["untagged"],
-    byOwner: (item) => item.meta.owners?.[0] ?? "unowned",
-    byDomain: (item) => {
-      const name = item.meta.key ?? item.meta.key ?? "";
-      return name.split(".")[0] ?? "default";
-    },
-    byStability: (item) => item.meta.stability ?? "stable",
-    byUrlPath: (level) => (item) => {
-      if (!item.path)
-        return "root";
-      const segments = item.path.split("/").filter(Boolean);
-      return segments.slice(0, level).join("/") || "root";
-    }
-  };
-});
-
-// src/registry.ts
-init_registry_utils();
-import { compareVersions } from "compare-versions";
-var keyOfSpecContract = (spec) => `${spec.meta.key}.v${spec.meta.version}`;
-
-class SpecContractRegistry {
-  contractType;
-  items = new Map;
-  constructor(contractType, items) {
-    this.contractType = contractType;
-    if (items) {
-      items.forEach((p) => this.register(p));
-    }
-  }
-  register(p) {
-    const key = keyOfSpecContract(p);
-    if (this.items.has(key))
-      throw new Error(`Duplicate contract \`${this.contractType}\` ${key}`);
-    this.items.set(key, p);
-    return this;
-  }
-  count() {
-    return this.items.size;
-  }
-  list() {
-    return [...this.items.values()];
-  }
-  get(key, version) {
-    if (version != null)
-      return this.items.get(`${key}.v${version}`);
-    let candidate;
-    for (const [k, p] of this.items.entries()) {
-      if (!k.startsWith(`${key}.v`))
-        continue;
-      if (!candidate || compareVersions(p.meta.version, candidate.meta.version) > 0) {
-        candidate = p;
-      }
-    }
-    return candidate;
-  }
-  has(key, version) {
-    return !!this.get(key, version);
-  }
-  filter(criteria) {
-    return filterBy(this.list(), criteria);
-  }
-  listByTag(tag) {
-    return this.list().filter((p) => p.meta.tags?.includes(tag));
-  }
-  listByOwner(owner) {
-    return this.list().filter((p) => p.meta.owners?.includes(owner));
-  }
-  groupBy(keyFn) {
-    return groupBy(this.list(), keyFn);
-  }
-  getUniqueTags() {
-    return getUniqueTags(this.list());
-  }
-}
-
-// src/telemetry/spec.ts
-import { compareVersions as compareVersions2 } from "compare-versions";
-var telemetryKey = (meta) => `${meta.key}.v${meta.version}`;
-
-class TelemetryRegistry extends SpecContractRegistry {
-  eventsByKey = new Map;
-  specByEventKey = new Map;
-  constructor(items) {
-    super("telemetry", items);
-    if (items) {
-      items.forEach((spec) => this.indexEvents(spec));
-    }
-  }
-  register(spec) {
-    super.register(spec);
-    this.indexEvents(spec);
-    return this;
-  }
-  indexEvents(spec) {
-    for (const event of spec.events) {
-      this.eventsByKey.set(`${event.key}.v${event.version}`, event);
-      this.specByEventKey.set(`${event.key}.v${event.version}`, spec);
-    }
-  }
-  findEventDef(name, version) {
-    if (version != null) {
-      return this.eventsByKey.get(`${name}.v${version}`);
-    }
-    let latest;
-    for (const event of this.eventsByKey.values()) {
-      if (event.key !== name)
-        continue;
-      if (!latest || compareVersions2(event.version, latest.version) > 0) {
-        latest = event;
-      }
-    }
-    return latest;
-  }
-  getSpecForEvent(name, version) {
-    return this.specByEventKey.get(`${name}.v${version}`);
-  }
-}
-function makeTelemetryKey(meta) {
-  return telemetryKey(meta);
-}
-
-// src/telemetry/tracker.ts
-import { randomUUID } from "crypto";
-var maskValue = (value) => {
-  if (value == null)
-    return value;
-  if (typeof value === "string")
-    return "REDACTED";
-  if (typeof value === "number")
-    return 0;
-  if (typeof value === "boolean")
-    return false;
-  if (Array.isArray(value))
-    return value.map(() => "REDACTED");
-  if (typeof value === "object") {
-    return Object.fromEntries(Object.keys(value).map((key) => [
-      key,
-      "REDACTED"
-    ]));
-  }
-  return "REDACTED";
-};
-
-class TelemetryTracker {
-  providers = new Map;
-  registry;
-  anomalyMonitor;
-  random;
-  clock;
-  constructor(options) {
-    this.registry = options.registry;
-    this.anomalyMonitor = options.anomalyMonitor;
-    this.random = options.random ?? Math.random;
-    this.clock = options.clock ?? (() => new Date);
-    for (const provider of options.providers ?? []) {
-      this.providers.set(provider.id, provider);
-    }
-  }
-  registerProvider(provider) {
-    this.providers.set(provider.id, provider);
-  }
-  unregisterProvider(providerId) {
-    this.providers.delete(providerId);
-  }
-  async track(name, version, properties, context = {}) {
-    const definition = this.registry.findEventDef(name, version);
-    if (!definition)
-      return false;
-    const spec = this.registry.getSpecForEvent(definition.key, definition.version);
-    if (!spec)
-      return false;
-    if (!this.shouldSample(definition.sampling ?? spec.config?.defaultSamplingRate)) {
-      return false;
-    }
-    const redactedProperties = this.redactProperties(definition, properties);
-    const dispatch = {
-      id: randomUUID(),
-      name: definition.key,
-      version: definition.version,
-      occurredAt: this.clock().toISOString(),
-      properties: redactedProperties,
-      privacy: definition.privacy,
-      context,
-      tags: definition.tags,
-      spec,
-      definition
-    };
-    await Promise.all([...this.providers.values()].map((provider) => provider.send(dispatch)));
-    this.anomalyMonitor?.observe(dispatch);
-    return true;
-  }
-  shouldSample(sampling) {
-    if (typeof sampling === "number") {
-      return this.random() < sampling;
-    }
-    if (!sampling)
-      return true;
-    return this.random() < sampling.rate;
-  }
-  redactProperties(definition, properties) {
-    const result = {};
-    for (const [key, value] of Object.entries(properties)) {
-      const def = definition.properties[key];
-      if (!def) {
-        result[key] = value;
-        continue;
-      }
-      if (def.redact || def.pii || definition.privacy === "sensitive") {
-        result[key] = maskValue(value);
-      } else {
-        result[key] = value;
-      }
-    }
-    return result;
-  }
-}
-
-// src/telemetry/anomaly.ts
-class TelemetryAnomalyMonitor {
-  onAnomaly;
-  now;
-  samples = new Map;
-  constructor(options = {}) {
-    this.onAnomaly = options.onAnomaly;
-    this.now = options.now ?? (() => new Date);
-  }
-  observe(dispatch) {
-    const anomalyConfig = dispatch.definition.anomalyDetection;
-    if (!anomalyConfig?.enabled)
-      return;
-    if (!anomalyConfig.thresholds?.length)
-      return;
-    const eventKey = `${dispatch.name}.v${dispatch.version}`;
-    const count = this.samples.get(eventKey) ?? 0;
-    const newCount = count + 1;
-    this.samples.set(eventKey, newCount);
-    if (typeof anomalyConfig.minimumSample === "number" && newCount < anomalyConfig.minimumSample) {
-      return;
-    }
-    for (const threshold of anomalyConfig.thresholds) {
-      const value = this.extractMetric(dispatch, threshold.metric);
-      if (typeof value !== "number")
-        continue;
-      if (typeof threshold.min === "number" && value < threshold.min) {
-        this.emit(dispatch, anomalyConfig, threshold.metric, value, "min");
-      }
-      if (typeof threshold.max === "number" && value > threshold.max) {
-        this.emit(dispatch, anomalyConfig, threshold.metric, value, "max");
-      }
-    }
-  }
-  extractMetric(dispatch, metric) {
-    const value = dispatch.properties[metric];
-    if (typeof value === "number")
-      return value;
-    if (typeof value === "object" && value !== null && "value" in value) {
-      const maybeNumber = value.value;
-      return typeof maybeNumber === "number" ? maybeNumber : undefined;
-    }
-    return;
-  }
-  emit(dispatch, threshold, metric, value, type) {
-    this.onAnomaly?.({
-      dispatch,
-      threshold,
-      metric,
-      value,
-      type
-    });
-  }
-  reset() {
-    this.samples.clear();
-  }
-}
-export {
-  makeTelemetryKey,
-  TelemetryTracker,
-  TelemetryRegistry,
-  TelemetryAnomalyMonitor
-};

package/dist/telemetry/spec.d.ts

@@ -1,88 +0,0 @@
-import type { OwnerShipMeta } from '../ownership';
-export type TelemetryPrivacyLevel = 'public' | 'internal' | 'pii' | 'sensitive';
-export type TelemetryMeta = OwnerShipMeta;
-export interface TelemetryPropertyDef {
-    type: 'string' | 'number' | 'boolean' | 'timestamp' | 'json';
-    required?: boolean;
-    pii?: boolean;
-    redact?: boolean;
-    description?: string;
-}
-export interface TelemetryAnomalyThreshold {
-    metric: string;
-    min?: number;
-    max?: number;
-}
-export type TelemetryAnomalyAction = 'alert' | 'log' | 'trigger_regen';
-export interface TelemetryAnomalyDetectionConfig {
-    enabled: boolean;
-    thresholds?: TelemetryAnomalyThreshold[];
-    actions?: TelemetryAnomalyAction[];
-    /**
-     * Minimum sample size before evaluating thresholds.
-     * Helps avoid false positives on small sample sizes.
-     */
-    minimumSample?: number;
-}
-export interface TelemetrySamplingConfig {
-    rate: number;
-    conditions?: string[];
-}
-export interface TelemetryRetentionConfig {
-    days: number;
-    policy?: 'archive' | 'delete';
-}
-export interface TelemetryEventDef {
-    /** Name of the event (should match EventSpec.key for cross-reference). */
-    key: string;
-    /** Version of the underlying event. */
-    version: string;
-    /** High-level semantics for docs/analyzers. */
-    semantics: {
-        who?: string;
-        what: string;
-        why?: string;
-    };
-    /** Detailed property metadata keyed by property name. */
-    properties: Record<string, TelemetryPropertyDef>;
-    /** Privacy level for the entire event. */
-    privacy: TelemetryPrivacyLevel;
-    /** Retention policy overrides. */
-    retention?: TelemetryRetentionConfig;
-    /** Sampling rules, defaulting to spec.config defaults. */
-    sampling?: TelemetrySamplingConfig;
-    /** Anomaly detection overrides. */
-    anomalyDetection?: TelemetryAnomalyDetectionConfig;
-    /** Optional tags for analytics/AI hints. */
-    tags?: string[];
-}
-export interface TelemetryProviderConfig {
-    type: 'posthog' | 'segment' | 'opentelemetry' | 'internal';
-    config: Record<string, unknown>;
-}
-export interface TelemetryConfig {
-    defaultRetentionDays?: number;
-    defaultSamplingRate?: number;
-    providers?: TelemetryProviderConfig[];
-    anomalyDetection?: {
-        enabled: boolean;
-        checkIntervalMs?: number;
-    };
-}
-export interface TelemetrySpec {
-    meta: TelemetryMeta;
-    events: TelemetryEventDef[];
-    config?: TelemetryConfig;
-}
-import { SpecContractRegistry } from '../registry';
-export declare class TelemetryRegistry extends SpecContractRegistry<'telemetry', TelemetrySpec> {
-    private readonly eventsByKey;
-    private readonly specByEventKey;
-    constructor(items?: TelemetrySpec[]);
-    register(spec: TelemetrySpec): this;
-    private indexEvents;
-    findEventDef(name: string, version?: string): TelemetryEventDef | undefined;
-    getSpecForEvent(name: string, version: string): TelemetrySpec | undefined;
-}
-export declare function makeTelemetryKey(meta: TelemetryMeta): string;
-//# sourceMappingURL=spec.d.ts.map

package/dist/telemetry/spec.d.ts.map

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