@monster-orange/den 0.0.0 → 0.2.0

package/src/shared/paths.ts

@@ -0,0 +1,190 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+  loadProfile,
+  PROFILE_FILE,
+  readEnv,
+  type ProductProfile,
+} from "./profile.js";
+
+/** Den's package name: the engine root is the directory that has it. */
+export const ENGINE_PACKAGE = "@monster-orange/den";
+
+/** A distribution root is a directory holding den.yml. */
+function isDistRootAt(dir: string): boolean {
+  return fs.existsSync(path.join(dir, PROFILE_FILE));
+}
+
+function isEngineRootAt(dir: string): boolean {
+  try {
+    const raw = fs.readFileSync(path.join(dir, "package.json"), "utf-8");
+    return (JSON.parse(raw) as { name?: unknown }).name === ENGINE_PACKAGE;
+  } catch {
+    return false;
+  }
+}
+
+function walkUp(start: string, test: (dir: string) => boolean): string | null {
+  let dir = path.resolve(start);
+  for (;;) {
+    if (test(dir)) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+const entryDir = (): string | null =>
+  process.argv[1] ? path.dirname(path.resolve(process.argv[1])) : null;
+
+/**
+ * An explicit root from the environment: DEN_ROOT, or `<PREFIX>_ROOT` where
+ * <PREFIX> is the env prefix of the profile found there (ACME_ROOT for a
+ * product named acme). Validated rather than trusted: everything downstream (clone
+ * destinations, the clone-guard allowlist, config writes) anchors here, so a
+ * stale or mistyped value must not re-open the Jun 29 incident.
+ */
+function rootFromEnv(): string | null {
+  const den = process.env.DEN_ROOT?.trim();
+  if (den) {
+    const resolved = path.resolve(den);
+    if (!isDistRootAt(resolved))
+      throw new Error(
+        `DEN_ROOT is set to "${den}" but that directory has no ${PROFILE_FILE}. ` +
+          `Point it at your distribution's checkout, or unset it.`,
+      );
+    return resolved;
+  }
+  for (const [key, value] of Object.entries(process.env)) {
+    if (!/^[A-Z][A-Z0-9_]*_ROOT$/.test(key) || !value?.trim()) continue;
+    const resolved = path.resolve(value.trim());
+    if (
+      isDistRootAt(resolved) &&
+      `${loadProfile(resolved).envPrefix}_ROOT` === key
+    )
+      return resolved;
+  }
+  return null;
+}
+
+/**
+ * The distribution root: where den.yml, config/, manifests/, reports/ and
+ * results/ live. Never process.cwd(): on Jun 29 a cwd-derived root caused a
+ * bulk clone of 13 repos into an unrelated checkout. Anything the walk can't
+ * anchor fails loudly.
+ */
+export function getDistRoot(): string {
+  const fromEnv = rootFromEnv();
+  if (fromEnv) return fromEnv;
+  const start = entryDir();
+  const root = start ? walkUp(start, isDistRootAt) : null;
+  if (root !== null) {
+    // The distribution's own <PREFIX>_ROOT, if set, must have been accepted
+    // above: one that points elsewhere is a mistake, never silently ignored.
+    const key = `${loadProfile(root).envPrefix}_ROOT`;
+    const set = process.env[key]?.trim();
+    if (set)
+      throw new Error(
+        `${key} is set to "${set}" but that directory has no ${PROFILE_FILE} ` +
+          `for this product. Point ${key} at your checkout, or unset it.`,
+      );
+    return root;
+  }
+  // Name any product root variable that was set but pointed nowhere useful.
+  for (const [key, value] of Object.entries(process.env))
+    if (/^[A-Z][A-Z0-9_]*_ROOT$/.test(key) && value?.trim()) {
+      const resolved = path.resolve(value.trim());
+      if (
+        fs.existsSync(resolved) &&
+        !isDistRootAt(resolved) &&
+        isProductRootVar(resolved, key)
+      )
+        throw new Error(
+          `${key} is set to "${value}" but that directory has no ${PROFILE_FILE}. ` +
+            `Point ${key} at your checkout, or unset it.`,
+        );
+    }
+  throw new Error(
+    `cannot locate the distribution root: walked up from ` +
+      `"${start ?? "(no entry script)"}" without finding ${PROFILE_FILE}. ` +
+      `Set DEN_ROOT (or <PRODUCT>_ROOT) to your checkout directory ` +
+      `(the current directory, "${process.cwd()}", is never used as an anchor).`,
+  );
+}
+
+/**
+ * Whether `<PREFIX>_ROOT` is a product root variable (rather than some other
+ * tool's): the active profile, if one is pinned by DEN_PROFILE, owns it.
+ */
+function isProductRootVar(dir: string, key: string): boolean {
+  const pinned = process.env.DEN_PROFILE?.trim();
+  if (!pinned) return false;
+  return `${loadProfile(dir).envPrefix}_ROOT` === key;
+}
+
+/**
+ * Where Den's own files live (src/, public pages, make/): the directory whose
+ * package.json is @monster-orange/den. In a distribution that is
+ * node_modules/@monster-orange/den; in Den's own checkout, its root.
+ */
+export function getEngineRoot(): string {
+  const env = process.env.DEN_ENGINE_ROOT?.trim();
+  if (env) return path.resolve(env);
+  for (const start of [entryDir(), process.cwd()]) {
+    if (!start) continue;
+    const viaWalk = walkUp(start, isEngineRootAt);
+    if (viaWalk) return viaWalk;
+    const nested = path.join(
+      start,
+      "node_modules",
+      ...ENGINE_PACKAGE.split("/"),
+    );
+    if (isEngineRootAt(nested)) return nested;
+  }
+  throw new Error(
+    `cannot locate Den's own files: no package.json named ${ENGINE_PACKAGE} ` +
+      `above the entry script or the current directory. Set DEN_ENGINE_ROOT.`,
+  );
+}
+
+/** Den's own version (its package.json), or undefined when unreadable. */
+export function engineVersion(): string | undefined {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(getEngineRoot(), "package.json"), "utf-8"),
+    ) as { version?: unknown };
+    return typeof pkg.version === "string" ? pkg.version : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** This distribution's profile. */
+export function getProfile(): ProductProfile {
+  return loadProfile(getDistRoot());
+}
+
+/**
+ * The caller's cwd, handed over by the CLI wrapper (bin/den) in
+ * DEN_INVOKE_CWD, or the product's own `<PREFIX>_INVOKE_CWD`.
+ */
+export function getInvokeCwd(): string {
+  const handed = process.env.DEN_INVOKE_CWD?.trim();
+  if (handed) return handed;
+  try {
+    return readEnv(getProfile(), "INVOKE_CWD") ?? process.cwd();
+  } catch {
+    return process.cwd(); // no distribution root yet: the caller's cwd
+  }
+}
+
+/**
+ * Per-user state directory for this instance (web server, daemons, logs,
+ * history): the profile's state_dir (~/.<name>), or `<PREFIX>_HOME`, so two
+ * instances on one machine never share or stop each other's processes.
+ */
+export function getStateDir(): string {
+  const profile = getProfile();
+  const home = readEnv(profile, "HOME")?.trim();
+  return home ? path.resolve(home) : profile.stateDir;
+}

package/src/shared/perf/optional-fields.ts

@@ -0,0 +1,105 @@
+/**
+ * Pure resolver for declarative per-perf-test "optional launch fields".
+ *
+ * A perf test declares `PerfOptionalField[]` (in its co-located manifest.yml or
+ * `.den.yml`). The web UI renders these generically and collects raw values;
+ * this resolver turns (fields, values) into the env-var map that gets injected
+ * into THAT test's k6 process. No I/O, no globals — fully unit-tested.
+ */
+
+import type { PerfOptionalField } from "../types/index.js";
+
+type FieldValue = string | number | boolean | undefined;
+
+/** True for the canonical truthy spellings a boolean field may arrive as. */
+function isTruthy(value: FieldValue): boolean {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") return value !== 0;
+  if (typeof value === "string") {
+    const v = value.trim().toLowerCase();
+    return v === "true" || v === "1" || v === "yes" || v === "on";
+  }
+  return false;
+}
+
+/**
+ * Resolve declared optional fields against user-supplied values into an env map.
+ *
+ * Rules (applied per field, in declaration order):
+ *  - `disabledWhen` satisfied by the (possibly defaulted) controlling field's
+ *    effective value → SKIP (no env emitted).
+ *  - effective value = values[name] ?? default.
+ *  - boolean: truthy → env = emit ?? "1"; falsy/undefined → omit.
+ *  - select: env set only when the value is one of options[].value; else omit.
+ *  - string/number: env = String(value) when defined and non-empty.
+ */
+export function resolveFieldEnv(
+  fields: PerfOptionalField[],
+  values: Record<string, FieldValue>,
+): Record<string, string> {
+  const effective = (field: PerfOptionalField): FieldValue =>
+    values[field.name] ?? field.default;
+
+  const byName = new Map(fields.map((f) => [f.name, f]));
+
+  const env: Record<string, string> = {};
+
+  for (const field of fields) {
+    if (field.disabledWhen) {
+      const controller = byName.get(field.disabledWhen.field);
+      const controllerValue = controller
+        ? effective(controller)
+        : values[field.disabledWhen.field];
+      if (matchesEquals(controllerValue, field.disabledWhen.equals)) {
+        continue;
+      }
+    }
+
+    const value = effective(field);
+
+    switch (field.type) {
+      case "boolean": {
+        if (isTruthy(value)) {
+          env[field.env] = field.emit ?? "1";
+        }
+        break;
+      }
+      case "select": {
+        const candidate =
+          value === undefined || value === null ? undefined : String(value);
+        const allowed = (field.options ?? []).some(
+          (opt) => opt.value === candidate,
+        );
+        if (candidate !== undefined && allowed) {
+          env[field.env] = candidate;
+        }
+        break;
+      }
+      case "string":
+      case "number": {
+        if (value !== undefined && value !== null && String(value) !== "") {
+          env[field.env] = String(value);
+        }
+        break;
+      }
+    }
+  }
+
+  return env;
+}
+
+/**
+ * Compare a controlling field's value against a `disabledWhen.equals` target.
+ * Booleans compare against the field's canonical truthiness so a checkbox that
+ * arrives as the string "true" still matches `equals: true`.
+ */
+function matchesEquals(
+  value: FieldValue,
+  equals: string | number | boolean,
+): boolean {
+  if (typeof equals === "boolean") {
+    return isTruthy(value) === equals;
+  }
+  if (value === undefined || value === null) return false;
+  return String(value) === String(equals);
+}

package/src/shared/perf/report-normalizer.ts

@@ -0,0 +1,404 @@
+import type {
+  PerfCheckResult,
+  PerfMetricSummary,
+  PerfModuleRunReport,
+  PerfReportValue,
+  PerfRunReport,
+  PerfScenarioSummary,
+  PerfThresholdResult,
+} from "./report-types.js";
+
+interface K6Metric {
+  type?: string;
+  contains?: string;
+  values?: Record<string, number>;
+  thresholds?: Record<string, boolean | { ok?: boolean }>;
+  [key: string]: unknown;
+}
+
+interface K6Check {
+  name?: string;
+  passes?: number;
+  fails?: number;
+}
+
+export interface K6Summary {
+  metrics?: Record<string, K6Metric>;
+  root_group?: {
+    checks?: K6Check[] | Record<string, Omit<K6Check, "name">>;
+  };
+  options?: {
+    scenarios?: Record<string, Record<string, unknown>>;
+  };
+}
+
+interface NormalizeSummaryInput {
+  module: string;
+  summary: K6Summary;
+  artifactPath: string;
+  startedAt?: string;
+  finishedAt?: string;
+}
+
+interface BuildRunReportInput {
+  environment: string;
+  modules: NormalizeSummaryInput[];
+  startedAt?: string;
+  finishedAt?: string;
+}
+
+const CORE_METRIC_DEFS: Array<{
+  key: string;
+  source: string;
+  label: string;
+  unit?: string;
+}> = [
+  { key: "count", source: "http_reqs", label: "HTTP requests" },
+  { key: "count", source: "iterations", label: "Iterations" },
+  { key: "value", source: "vus", label: "Virtual users" },
+];
+
+const LATENCY_METRIC_DEFS: Array<{
+  key: string;
+  source: string;
+  label: string;
+}> = [
+  { key: "avg", source: "http_req_duration", label: "HTTP avg" },
+  { key: "med", source: "http_req_duration", label: "HTTP p50" },
+  { key: "p(95)", source: "http_req_duration", label: "HTTP p95" },
+  { key: "p(99)", source: "http_req_duration", label: "HTTP p99" },
+  { key: "max", source: "http_req_duration", label: "HTTP max" },
+];
+
+const THROUGHPUT_METRIC_DEFS: Array<{
+  key: string;
+  source: string;
+  label: string;
+}> = [
+  { key: "rate", source: "http_reqs", label: "Requests / sec" },
+  { key: "rate", source: "iterations", label: "Iterations / sec" },
+  { key: "rate", source: "http_req_failed", label: "Failure rate" },
+];
+
+export function normalizeK6Summary(
+  input: NormalizeSummaryInput,
+): PerfModuleRunReport {
+  const metrics = input.summary.metrics ?? {};
+  const thresholds = flattenThresholds(metrics);
+  const checks = normalizeChecks(input.summary.root_group?.checks);
+  const scenarios = normalizeScenarios(input.summary.options?.scenarios);
+  const customMetrics = normalizeCustomMetrics(metrics);
+
+  return {
+    module: input.module,
+    status: thresholds.some((threshold) => !threshold.passed)
+      ? "failed"
+      : "passed",
+    startedAt: input.startedAt,
+    finishedAt: input.finishedAt,
+    thresholds,
+    coreMetrics: selectReportValues(metrics, CORE_METRIC_DEFS),
+    latencyMetrics: selectReportValues(metrics, LATENCY_METRIC_DEFS, "ms"),
+    throughputMetrics: selectReportValues(metrics, THROUGHPUT_METRIC_DEFS),
+    scenarios,
+    checks,
+    customMetrics,
+    rawArtifacts: [
+      {
+        kind: "k6-summary",
+        path: input.artifactPath,
+      },
+    ],
+  };
+}
+
+export function buildPerfRunReport(input: BuildRunReportInput): PerfRunReport {
+  const modules = input.modules.map((moduleInput) =>
+    normalizeK6Summary(moduleInput),
+  );
+
+  return {
+    pillar: "performance",
+    environment: input.environment,
+    status: modules.some((module) => module.status === "failed")
+      ? "failed"
+      : "passed",
+    startedAt: input.startedAt,
+    finishedAt: input.finishedAt,
+    modules,
+    rawArtifacts: modules.flatMap((module) => module.rawArtifacts),
+  };
+}
+
+function flattenThresholds(
+  metrics: Record<string, K6Metric>,
+): PerfThresholdResult[] {
+  return Object.entries(metrics).flatMap(([metricKey, metric]) => {
+    const thresholdEntries = Object.entries(metric.thresholds ?? {});
+    return thresholdEntries.map(([expression, passed]) => {
+      const actualValue = deriveThresholdActualValue(metric, expression);
+      return {
+        metric: metricKey,
+        name: `${metricKey}:${expression}`,
+        expression,
+        passed: normalizeThresholdPassed(actualValue, expression, passed),
+        actualValue,
+        unit: metric.contains === "time" ? "ms" : undefined,
+      };
+    });
+  });
+}
+
+function deriveThresholdActualValue(
+  metric: K6Metric,
+  expression: string,
+): number | string | null {
+  const values = getMetricValues(metric);
+  const percentile = expression.match(/^p\(([\d.]+)\)/);
+  if (percentile) {
+    return values[`p(${percentile[1]})`] ?? null;
+  }
+
+  if (expression.startsWith("rate")) {
+    return firstDefinedNumber(values.rate, values.value) ?? null;
+  }
+
+  if (expression.startsWith("avg")) {
+    return values.avg ?? null;
+  }
+
+  if (expression.startsWith("count")) {
+    return values.count ?? null;
+  }
+
+  return values.value ?? values.avg ?? values.rate ?? values.count ?? null;
+}
+
+function selectReportValues(
+  metrics: Record<string, K6Metric>,
+  definitions: Array<{ key: string; source: string; label: string }>,
+  unit?: string,
+): PerfReportValue[] {
+  return definitions.flatMap((definition) => {
+    const value = getMetricDisplayValue(
+      metrics[definition.source],
+      definition.key,
+    );
+    if (typeof value !== "number") {
+      return [];
+    }
+
+    return [
+      {
+        label: definition.label,
+        value,
+        unit,
+      },
+    ];
+  });
+}
+
+function normalizeChecks(
+  checks?: K6Check[] | Record<string, Omit<K6Check, "name">>,
+): PerfCheckResult[] {
+  const normalizedChecks = Array.isArray(checks)
+    ? checks
+    : Object.entries(checks ?? {}).map(([name, check]) => ({
+        ...check,
+        name,
+      }));
+
+  return normalizedChecks
+    .filter(
+      (check): check is Required<Pick<K6Check, "name">> & K6Check =>
+        typeof check.name === "string",
+    )
+    .map((check) => {
+      const passes = check.passes ?? 0;
+      const fails = check.fails ?? 0;
+      const total = passes + fails;
+      return {
+        name: check.name,
+        passes,
+        fails,
+        passRate: total > 0 ? passes / total : null,
+      };
+    });
+}
+
+function normalizeScenarios(
+  scenarios?: Record<string, Record<string, unknown>>,
+): PerfScenarioSummary[] {
+  return Object.entries(scenarios ?? {}).map(([name, scenario]) => ({
+    name,
+    executor:
+      typeof scenario.executor === "string" ? scenario.executor : undefined,
+    startTime:
+      typeof scenario.startTime === "string" ? scenario.startTime : undefined,
+    gracefulStop:
+      typeof scenario.gracefulStop === "string"
+        ? scenario.gracefulStop
+        : undefined,
+    options: scenario,
+  }));
+}
+
+function normalizeCustomMetrics(
+  metrics: Record<string, K6Metric>,
+): PerfMetricSummary[] {
+  const builtInMetrics = new Set([
+    "http_reqs",
+    "http_req_failed",
+    "http_req_duration",
+    "http_req_blocked",
+    "http_req_connecting",
+    "http_req_receiving",
+    "http_req_sending",
+    "http_req_tls_handshaking",
+    "http_req_waiting",
+    "iteration_duration",
+    "iterations",
+    "vus",
+    "vus_max",
+    "checks",
+    "data_received",
+    "data_sent",
+    "group_duration",
+  ]);
+
+  return Object.entries(metrics)
+    .filter(([metricKey]) => {
+      const baseKey = metricKey.replace(/\{.*\}$/, "");
+      return !builtInMetrics.has(baseKey);
+    })
+    .map(([metricKey, metric]) => ({
+      key: metricKey,
+      label: metricKey.replace(/_/g, " "),
+      type: metric.type,
+      contains: metric.contains,
+      values: normalizeMetricValues(getMetricValues(metric)),
+      thresholds: flattenThresholds({ [metricKey]: metric }),
+      isCustom: true,
+    }));
+}
+
+function normalizeMetricValues(
+  values?: Record<string, number>,
+): Record<string, number | null> {
+  return Object.fromEntries(
+    Object.entries(values ?? {}).map(([key, value]) => [
+      key,
+      typeof value === "number" ? value : null,
+    ]),
+  );
+}
+
+function getMetricValues(metric?: K6Metric): Record<string, number> {
+  if (!metric) {
+    return {};
+  }
+
+  if (metric.values && Object.keys(metric.values).length > 0) {
+    return normalizeNumericEntries(metric.values);
+  }
+
+  const topLevelEntries = Object.entries(metric).filter(
+    (entry): entry is [string, number] => {
+      const [key, value] = entry;
+      if (key === "type" || key === "contains" || key === "thresholds") {
+        return false;
+      }
+
+      return typeof value === "number";
+    },
+  );
+
+  return Object.fromEntries(topLevelEntries);
+}
+
+function getMetricDisplayValue(
+  metric: K6Metric | undefined,
+  preferredKey: string,
+): number | undefined {
+  const values = getMetricValues(metric);
+
+  if (metric?.type === "gauge" && preferredKey === "value") {
+    return firstDefinedNumber(values.max, values.value, values.min);
+  }
+
+  if (preferredKey === "rate") {
+    return firstDefinedNumber(values.rate, values.value);
+  }
+
+  return values[preferredKey];
+}
+
+function firstDefinedNumber(
+  ...candidates: Array<number | undefined>
+): number | undefined {
+  return candidates.find((candidate) => typeof candidate === "number");
+}
+
+function normalizeNumericEntries(
+  values: Record<string, number>,
+): Record<string, number> {
+  return Object.fromEntries(
+    Object.entries(values).filter(
+      (entry): entry is [string, number] => typeof entry[1] === "number",
+    ),
+  );
+}
+
+function normalizeThresholdPassed(
+  actualValue: number | string | null,
+  expression: string,
+  value: boolean | { ok?: boolean },
+): boolean {
+  const evaluated = evaluateThresholdExpression(actualValue, expression);
+  if (typeof evaluated === "boolean") {
+    return evaluated;
+  }
+
+  if (typeof value === "boolean") {
+    return value;
+  }
+
+  return value.ok ?? false;
+}
+
+function evaluateThresholdExpression(
+  actualValue: number | string | null,
+  expression: string,
+): boolean | undefined {
+  if (typeof actualValue !== "number") {
+    return undefined;
+  }
+
+  const match = expression.match(
+    /^[a-zA-Z0-9_.()]+\s*(<=|>=|<|>|==)\s*(-?\d+(?:\.\d+)?)$/,
+  );
+  if (!match) {
+    return undefined;
+  }
+
+  const [, operator, targetRaw] = match;
+  const target = Number(targetRaw);
+  if (!Number.isFinite(target)) {
+    return undefined;
+  }
+
+  switch (operator) {
+    case "<":
+      return actualValue < target;
+    case "<=":
+      return actualValue <= target;
+    case ">":
+      return actualValue > target;
+    case ">=":
+      return actualValue >= target;
+    case "==":
+      return actualValue === target;
+    default:
+      return undefined;
+  }
+}