@contractspec/lib.contracts-spec 2.0.0

package/dist/node/telemetry/index.js

@@ -0,0 +1,417 @@
+import { createRequire } from "node:module";
+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 = /* @__PURE__ */ createRequire(import.meta.url);
+
+// 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/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();
+  }
+}
+
+// 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;
+  }
+}
+export {
+  makeTelemetryKey,
+  TelemetryTracker,
+  TelemetryRegistry,
+  TelemetryAnomalyMonitor
+};

package/dist/node/telemetry/spec.js

@@ -0,0 +1,261 @@
+import { createRequire } from "node:module";
+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 = /* @__PURE__ */ createRequire(import.meta.url);
+
+// 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);
+}
+export {
+  makeTelemetryKey,
+  TelemetryRegistry
+};