@zxyycom/vibe-check 0.0.1

package/dist/esm/project-run/controls/validation.mjs

@@ -0,0 +1,156 @@
+import { snapshotClosedArray } from "../../data-boundary/closed-values.mjs";
+import { isNonArrayRecord, isUnknownArray } from "../../data-boundary/value-shapes.mjs";
+import { parseOutputsOverride } from "./outputs-override-validation.mjs";
+const RUN_CONTROL_KEYS = ["checkAggregation", "outputs", "flags", "projectRoot", "signal"];
+const CHECK_AGGREGATION_MODES = ["all", "any"];
+const UNAVAILABLE_HANDLING = ["propagate", "fail", "exclude"];
+const NOT_APPLICABLE_HANDLING = ["exclude", "pass", "fail"];
+const EMPTY_AGGREGATION_RESULTS = ["passed", "failed", "not-applicable"];
+export function validateRunControls(value = {}) {
+    try {
+        return validateRunControlsValue(value);
+    }
+    catch {
+        return invalidControls("controls");
+    }
+}
+function validateRunControlsValue(value) {
+    const data = exactControlRecord(value);
+    if (!data.ok)
+        return data;
+    const flags = parseFlags(data.value.flags);
+    if (!flags.ok)
+        return flags;
+    const checkAggregation = parseOptionalCheckAggregation(data.value.checkAggregation);
+    if (!checkAggregation.ok)
+        return checkAggregation;
+    const outputs = optionalControl(data.value.outputs, parseOutputsOverride, "controls.outputs");
+    if (!outputs.ok)
+        return outputs;
+    const projectRoot = optionalControl(data.value.projectRoot, parseString, "controls.projectRoot");
+    if (!projectRoot.ok)
+        return projectRoot;
+    const signal = optionalControl(data.value.signal, parseAbortSignal, "controls.signal");
+    if (!signal.ok)
+        return signal;
+    return Object.freeze({
+        ok: true,
+        value: Object.freeze({
+            ...(checkAggregation.value === undefined ? {} : { checkAggregation: checkAggregation.value }),
+            ...(outputs.value === undefined ? {} : { outputs: outputs.value }),
+            flags: flags.value,
+            ...(projectRoot.value === undefined ? {} : { projectRoot: projectRoot.value }),
+            ...(signal.value === undefined ? {} : { signal: signal.value })
+        })
+    });
+}
+function exactControlRecord(value) {
+    if (!isNonArrayRecord(value))
+        return invalidControls("controls");
+    const unknownKey = Object.keys(value).find((key) => !isRunControlKey(key));
+    return unknownKey === undefined
+        ? Object.freeze({ ok: true, value })
+        : invalidRunControl(`controls.${unknownKey}`, "unknown-key");
+}
+function optionalControl(value, parse, path) {
+    if (value === undefined)
+        return Object.freeze({ ok: true, value: undefined });
+    const parsed = parse(value);
+    return parsed === undefined ? invalidControls(path) : Object.freeze({ ok: true, value: parsed });
+}
+function parseFlags(value) {
+    if (value === undefined)
+        return Object.freeze({ ok: true, value: Object.freeze([]) });
+    if (!isUnknownArray(value))
+        return invalidControls("controls.flags");
+    const flags = [];
+    const length = value.length;
+    for (let index = 0; index < length; index += 1) {
+        if (!Object.hasOwn(value, index))
+            return invalidControls("controls.flags");
+        const flag = value[index];
+        if (typeof flag !== "string" || flag.length === 0) {
+            return invalidControls("controls.flags");
+        }
+        flags.push(flag);
+    }
+    return Object.freeze({
+        ok: true,
+        value: Object.freeze([...new Set(flags)].sort())
+    });
+}
+function parseOptionalCheckAggregation(value) {
+    if (value === undefined)
+        return Object.freeze({ ok: true, value: undefined });
+    const data = exactKeys(value, ["checks", "mode", "unavailable", "notApplicable", "empty"]);
+    if (data === undefined)
+        return invalidControls("controls.checkAggregation");
+    const checks = data.checks === "all" ? "all" : parseClosedCheckIds(data.checks);
+    if (checks === undefined)
+        return invalidControls("controls.checkAggregation.checks");
+    const mode = parseLiteral(data.mode, CHECK_AGGREGATION_MODES);
+    const unavailable = parseLiteral(data.unavailable, UNAVAILABLE_HANDLING);
+    const notApplicable = parseLiteral(data.notApplicable, NOT_APPLICABLE_HANDLING);
+    const empty = parseLiteral(data.empty, EMPTY_AGGREGATION_RESULTS);
+    if (mode === undefined ||
+        unavailable === undefined ||
+        notApplicable === undefined ||
+        empty === undefined)
+        return invalidControls("controls.checkAggregation");
+    return Object.freeze({
+        ok: true,
+        value: Object.freeze({
+            checks,
+            mode,
+            unavailable,
+            notApplicable,
+            empty
+        })
+    });
+}
+function parseClosedCheckIds(value) {
+    const values = snapshotClosedArray(value);
+    if (values === undefined)
+        return undefined;
+    const checkIds = [];
+    for (const checkId of values) {
+        if (typeof checkId !== "string" || checkId.length === 0)
+            return undefined;
+        checkIds.push(checkId);
+    }
+    return Object.freeze(checkIds);
+}
+function parseLiteral(value, allowed) {
+    return typeof value === "string" ? allowed.find((option) => option === value) : undefined;
+}
+function isRunControlKey(value) {
+    return RUN_CONTROL_KEYS.some((key) => key === value);
+}
+function exactKeys(value, keys) {
+    if (!isNonArrayRecord(value))
+        return undefined;
+    return Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key))
+        ? value
+        : undefined;
+}
+function isAbortSignal(value) {
+    return (isNonArrayRecord(value) &&
+        typeof value.aborted === "boolean" &&
+        typeof value.addEventListener === "function");
+}
+function parseAbortSignal(value) {
+    return isAbortSignal(value) ? value : undefined;
+}
+function parseString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function invalidControls(path) {
+    return invalidRunControl(path, "invalid-value");
+}
+function invalidRunControl(path, reason) {
+    return Object.freeze({
+        ok: false,
+        error: Object.freeze({ kind: "invalid-run-controls", path, reason })
+    });
+}
+//# sourceMappingURL=validation.mjs.map

package/dist/esm/project-run/controls/validation.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.mjs","sourceRoot":"","sources":["../../../../src/project-run/controls/validation.ts"],"names":[],"mappings":"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","sourcesContent":["import { snapshotClosedArray } from \"../../data-boundary/closed-values.ts\";\nimport { isNonArrayRecord, isUnknownArray } from \"../../data-boundary/value-shapes.ts\";\nimport { parseOutputsOverride } from \"./outputs-override-validation.ts\";\nimport type { RunControlDiagnostic, RunControlValidationResult } from \"./validation-result.ts\";\nimport type { CheckAggregation, RunControls } from \"./contract.ts\";\n\nconst RUN_CONTROL_KEYS = [\"checkAggregation\", \"outputs\", \"flags\", \"projectRoot\", \"signal\"] as const;\nconst CHECK_AGGREGATION_MODES = [\"all\", \"any\"] as const;\nconst UNAVAILABLE_HANDLING = [\"propagate\", \"fail\", \"exclude\"] as const;\nconst NOT_APPLICABLE_HANDLING = [\"exclude\", \"pass\", \"fail\"] as const;\nconst EMPTY_AGGREGATION_RESULTS = [\"passed\", \"failed\", \"not-applicable\"] as const;\n\nexport function validateRunControls(value: unknown = {}): RunControlValidationResult<RunControls> {\n  try {\n    return validateRunControlsValue(value);\n  } catch {\n    return invalidControls(\"controls\");\n  }\n}\n\nfunction validateRunControlsValue(value: unknown): RunControlValidationResult<RunControls> {\n  const data = exactControlRecord(value);\n  if (!data.ok) return data;\n  const flags = parseFlags(data.value.flags);\n  if (!flags.ok) return flags;\n  const checkAggregation = parseOptionalCheckAggregation(data.value.checkAggregation);\n  if (!checkAggregation.ok) return checkAggregation;\n  const outputs = optionalControl(data.value.outputs, parseOutputsOverride, \"controls.outputs\");\n  if (!outputs.ok) return outputs;\n  const projectRoot = optionalControl(data.value.projectRoot, parseString, \"controls.projectRoot\");\n  if (!projectRoot.ok) return projectRoot;\n  const signal = optionalControl(data.value.signal, parseAbortSignal, \"controls.signal\");\n  if (!signal.ok) return signal;\n  return Object.freeze({\n    ok: true,\n    value: Object.freeze({\n      ...(checkAggregation.value === undefined ? {} : { checkAggregation: checkAggregation.value }),\n      ...(outputs.value === undefined ? {} : { outputs: outputs.value }),\n      flags: flags.value,\n      ...(projectRoot.value === undefined ? {} : { projectRoot: projectRoot.value }),\n      ...(signal.value === undefined ? {} : { signal: signal.value })\n    })\n  });\n}\n\nfunction exactControlRecord(\n  value: unknown\n): RunControlValidationResult<Readonly<Record<string, unknown>>> {\n  if (!isNonArrayRecord(value)) return invalidControls(\"controls\");\n  const unknownKey = Object.keys(value).find((key) => !isRunControlKey(key));\n  return unknownKey === undefined\n    ? Object.freeze({ ok: true, value })\n    : invalidRunControl(`controls.${unknownKey}`, \"unknown-key\");\n}\n\nfunction optionalControl<T>(\n  value: unknown,\n  parse: (candidate: unknown) => T | undefined,\n  path: string\n): RunControlValidationResult<T | undefined> {\n  if (value === undefined) return Object.freeze({ ok: true, value: undefined });\n  const parsed = parse(value);\n  return parsed === undefined ? invalidControls(path) : Object.freeze({ ok: true, value: parsed });\n}\n\nfunction parseFlags(value: unknown): RunControlValidationResult<readonly string[]> {\n  if (value === undefined) return Object.freeze({ ok: true, value: Object.freeze([]) });\n  if (!isUnknownArray(value)) return invalidControls(\"controls.flags\");\n  const flags: string[] = [];\n  const length = value.length;\n  for (let index = 0; index < length; index += 1) {\n    if (!Object.hasOwn(value, index)) return invalidControls(\"controls.flags\");\n    const flag = value[index];\n    if (typeof flag !== \"string\" || flag.length === 0) {\n      return invalidControls(\"controls.flags\");\n    }\n    flags.push(flag);\n  }\n  return Object.freeze({\n    ok: true,\n    value: Object.freeze([...new Set(flags)].sort())\n  });\n}\n\nfunction parseOptionalCheckAggregation(\n  value: unknown\n): RunControlValidationResult<CheckAggregation | undefined> {\n  if (value === undefined) return Object.freeze({ ok: true, value: undefined });\n  const data = exactKeys(value, [\"checks\", \"mode\", \"unavailable\", \"notApplicable\", \"empty\"]);\n  if (data === undefined) return invalidControls(\"controls.checkAggregation\");\n  const checks = data.checks === \"all\" ? \"all\" : parseClosedCheckIds(data.checks);\n  if (checks === undefined) return invalidControls(\"controls.checkAggregation.checks\");\n  const mode = parseLiteral(data.mode, CHECK_AGGREGATION_MODES);\n  const unavailable = parseLiteral(data.unavailable, UNAVAILABLE_HANDLING);\n  const notApplicable = parseLiteral(data.notApplicable, NOT_APPLICABLE_HANDLING);\n  const empty = parseLiteral(data.empty, EMPTY_AGGREGATION_RESULTS);\n  if (\n    mode === undefined ||\n    unavailable === undefined ||\n    notApplicable === undefined ||\n    empty === undefined\n  )\n    return invalidControls(\"controls.checkAggregation\");\n  return Object.freeze({\n    ok: true,\n    value: Object.freeze({\n      checks,\n      mode,\n      unavailable,\n      notApplicable,\n      empty\n    })\n  });\n}\n\nfunction parseClosedCheckIds(value: unknown): readonly string[] | undefined {\n  const values = snapshotClosedArray(value);\n  if (values === undefined) return undefined;\n  const checkIds: string[] = [];\n  for (const checkId of values) {\n    if (typeof checkId !== \"string\" || checkId.length === 0) return undefined;\n    checkIds.push(checkId);\n  }\n  return Object.freeze(checkIds);\n}\n\nfunction parseLiteral<Value extends string>(\n  value: unknown,\n  allowed: readonly Value[]\n): Value | undefined {\n  return typeof value === \"string\" ? allowed.find((option) => option === value) : undefined;\n}\n\nfunction isRunControlKey(value: string): boolean {\n  return RUN_CONTROL_KEYS.some((key) => key === value);\n}\n\nfunction exactKeys(\n  value: unknown,\n  keys: readonly string[]\n): Readonly<Record<string, unknown>> | undefined {\n  if (!isNonArrayRecord(value)) return undefined;\n  return Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key))\n    ? value\n    : undefined;\n}\n\nfunction isAbortSignal(value: unknown): value is AbortSignal {\n  return (\n    isNonArrayRecord(value) &&\n    typeof value.aborted === \"boolean\" &&\n    typeof value.addEventListener === \"function\"\n  );\n}\n\nfunction parseAbortSignal(value: unknown): AbortSignal | undefined {\n  return isAbortSignal(value) ? value : undefined;\n}\n\nfunction parseString(value: unknown): string | undefined {\n  return typeof value === \"string\" ? value : undefined;\n}\n\nfunction invalidControls(path: string): RunControlValidationResult<never> {\n  return invalidRunControl(path, \"invalid-value\");\n}\n\nfunction invalidRunControl(\n  path: string,\n  reason: RunControlDiagnostic[\"reason\"]\n): RunControlValidationResult<never> {\n  return Object.freeze({\n    ok: false,\n    error: Object.freeze({ kind: \"invalid-run-controls\", path, reason })\n  });\n}\n"]}

package/dist/esm/project-run/diagnostic-logging/diagnostic-detail-rendering.mjs

@@ -0,0 +1,182 @@
+import { types } from "node:util";
+export function summarizeDiagnosticValue(value) {
+    const rendered = renderSafeDiagnosticDetail(value);
+    if (!rendered.ok)
+        return Object.freeze({ availability: "unavailable", reason: rendered.reason });
+    const parsed = JSON.parse(rendered.text);
+    return summarizeRenderedDiagnosticValue(parsed, Buffer.byteLength(rendered.text, "utf8"));
+}
+function summarizeRenderedDiagnosticValue(value, bytes) {
+    if (value === null)
+        return Object.freeze({ availability: "available", bytes, shape: "null" });
+    if (Array.isArray(value)) {
+        return Object.freeze({ availability: "available", bytes, items: value.length, shape: "array" });
+    }
+    return summarizeNonArrayDiagnosticValue(value, bytes);
+}
+function summarizeNonArrayDiagnosticValue(value, bytes) {
+    switch (typeof value) {
+        case "boolean":
+            return Object.freeze({ availability: "available", bytes, shape: "boolean" });
+        case "number":
+            return Object.freeze({ availability: "available", bytes, shape: "number" });
+        case "string":
+            return Object.freeze({ availability: "available", bytes, shape: "string" });
+        case "object":
+            return Object.freeze({
+                availability: "available",
+                bytes,
+                keys: value === null ? 0 : Object.keys(value).length,
+                shape: "object"
+            });
+        case "bigint":
+        case "function":
+        case "symbol":
+        case "undefined":
+            throw new Error("safe diagnostic rendering produced a non-JSON value");
+        default:
+            throw new Error("safe diagnostic rendering produced an unknown value");
+    }
+}
+export function renderSafeDiagnosticDetail(value) {
+    return renderDetailValue(value, {
+        ancestors: new Set(),
+        remainingCharacters: MAX_DETAIL_CHARACTERS,
+        remainingValues: MAX_DETAIL_VALUES
+    });
+}
+// These bounds admit ordinary package handoffs while keeping diagnostic work finite.
+const MAX_DETAIL_CHARACTERS = 1_048_576;
+const MAX_DETAIL_DEPTH = 16;
+const MAX_DETAIL_VALUES = 32_768;
+const MAX_DETAIL_WIDTH = 4_096;
+/** Renders only descriptor-readable JSON values; diagnostics must never invoke author hooks. */
+function renderDetailValue(value, context, depth = 0) {
+    if (context.remainingValues <= 0)
+        return unavailable("value-limit");
+    context.remainingValues -= 1;
+    const scalar = renderDetailScalar(value, context);
+    if (scalar !== undefined)
+        return scalar;
+    return renderDetailCompound(value, context, depth);
+}
+function renderDetailScalar(value, context) {
+    if (value === null || typeof value === "boolean" || typeof value === "string") {
+        return renderDetailText(JSON.stringify(value), context);
+    }
+    if (typeof value !== "number")
+        return undefined;
+    return Number.isFinite(value)
+        ? renderDetailText(JSON.stringify(value), context)
+        : unavailable("non-finite-number");
+}
+function renderDetailCompound(value, context, depth) {
+    if (value === null || typeof value !== "object")
+        return unavailable(`unsupported-${typeof value}`);
+    if (types.isProxy(value))
+        return unavailable("proxy");
+    if (context.ancestors.has(value))
+        return unavailable("cycle");
+    if (depth >= MAX_DETAIL_DEPTH)
+        return unavailable("depth-limit");
+    return Array.isArray(value)
+        ? renderDetailArray(value, context, depth)
+        : renderDetailRecord(value, context, depth);
+}
+function renderDetailArray(value, context, depth) {
+    const inspection = inspectDetailArray(value);
+    if (!inspection.ok)
+        return inspection;
+    context.ancestors.add(value);
+    try {
+        return renderDetailArrayItems(value, inspection.length, context, depth);
+    }
+    finally {
+        context.ancestors.delete(value);
+    }
+}
+function inspectDetailArray(value) {
+    if (Object.getPrototypeOf(value) !== Array.prototype)
+        return unavailableArray("unsupported-prototype");
+    const length = readableArrayLength(value);
+    if (length === null)
+        return unavailableArray("invalid-array");
+    if (length > MAX_DETAIL_WIDTH)
+        return unavailableArray("width-limit");
+    return Reflect.ownKeys(value).length === length + 1
+        ? Object.freeze({ length, ok: true })
+        : unavailableArray("invalid-array");
+}
+function readableArrayLength(value) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, "length");
+    const length = descriptor?.value;
+    if (descriptor?.get !== undefined || descriptor?.set !== undefined)
+        return null;
+    return typeof length === "number" && Number.isSafeInteger(length) && length >= 0 ? length : null;
+}
+function renderDetailArrayItems(value, length, context, depth) {
+    const items = [];
+    for (let index = 0; index < length; index += 1) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+        if (!isEnumerableDataDescriptor(descriptor))
+            return unavailable("accessor-or-sparse-array");
+        const rendered = renderDetailValue(descriptor.value, context, depth + 1);
+        if (!rendered.ok)
+            return rendered;
+        items.push(rendered.text);
+    }
+    return renderDetailText(`[${items.join(",")}]`, context);
+}
+function renderDetailRecord(value, context, depth) {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        return unavailable("unsupported-prototype");
+    const keys = Reflect.ownKeys(value);
+    if (keys.length > MAX_DETAIL_WIDTH)
+        return unavailable("width-limit");
+    const textKeys = [];
+    for (let index = 0; index < keys.length; index += 1) {
+        const key = keys[index];
+        if (typeof key !== "string")
+            return unavailable("symbol-key");
+        textKeys.push(key);
+    }
+    textKeys.sort();
+    context.ancestors.add(value);
+    try {
+        const entries = [];
+        for (const key of textKeys) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!isEnumerableDataDescriptor(descriptor))
+                return unavailable("accessor-or-hidden-property");
+            const rendered = renderDetailValue(descriptor.value, context, depth + 1);
+            if (!rendered.ok)
+                return rendered;
+            entries.push(`${JSON.stringify(key)}:${rendered.text}`);
+        }
+        return renderDetailText(`{${entries.join(",")}}`, context);
+    }
+    finally {
+        context.ancestors.delete(value);
+    }
+}
+function isEnumerableDataDescriptor(descriptor) {
+    return (descriptor !== undefined &&
+        descriptor.enumerable === true &&
+        descriptor.get === undefined &&
+        descriptor.set === undefined &&
+        Object.hasOwn(descriptor, "value"));
+}
+function renderDetailText(text, context) {
+    if (text.length > context.remainingCharacters)
+        return unavailable("size-limit");
+    context.remainingCharacters -= text.length;
+    return Object.freeze({ ok: true, text });
+}
+function unavailable(reason) {
+    return Object.freeze({ ok: false, reason });
+}
+function unavailableArray(reason) {
+    return Object.freeze({ ok: false, reason });
+}
+//# sourceMappingURL=diagnostic-detail-rendering.mjs.map

package/dist/esm/project-run/diagnostic-logging/diagnostic-detail-rendering.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostic-detail-rendering.mjs","sourceRoot":"","sources":["../../../../src/project-run/diagnostic-logging/diagnostic-detail-rendering.ts"],"names":[],"mappings":"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","sourcesContent":["import { types } from \"node:util\";\n\nimport type { DiagnosticValueSummary } from \"./logger.ts\";\n\nexport function summarizeDiagnosticValue(value: unknown): DiagnosticValueSummary {\n  const rendered = renderSafeDiagnosticDetail(value);\n  if (!rendered.ok) return Object.freeze({ availability: \"unavailable\", reason: rendered.reason });\n\n  const parsed: unknown = JSON.parse(rendered.text);\n  return summarizeRenderedDiagnosticValue(parsed, Buffer.byteLength(rendered.text, \"utf8\"));\n}\n\nfunction summarizeRenderedDiagnosticValue(value: unknown, bytes: number): DiagnosticValueSummary {\n  if (value === null) return Object.freeze({ availability: \"available\", bytes, shape: \"null\" });\n  if (Array.isArray(value)) {\n    return Object.freeze({ availability: \"available\", bytes, items: value.length, shape: \"array\" });\n  }\n  return summarizeNonArrayDiagnosticValue(value, bytes);\n}\n\nfunction summarizeNonArrayDiagnosticValue(value: unknown, bytes: number): DiagnosticValueSummary {\n  switch (typeof value) {\n    case \"boolean\":\n      return Object.freeze({ availability: \"available\", bytes, shape: \"boolean\" });\n    case \"number\":\n      return Object.freeze({ availability: \"available\", bytes, shape: \"number\" });\n    case \"string\":\n      return Object.freeze({ availability: \"available\", bytes, shape: \"string\" });\n    case \"object\":\n      return Object.freeze({\n        availability: \"available\",\n        bytes,\n        keys: value === null ? 0 : Object.keys(value).length,\n        shape: \"object\"\n      });\n    case \"bigint\":\n    case \"function\":\n    case \"symbol\":\n    case \"undefined\":\n      throw new Error(\"safe diagnostic rendering produced a non-JSON value\");\n    default:\n      throw new Error(\"safe diagnostic rendering produced an unknown value\");\n  }\n}\n\nexport function renderSafeDiagnosticDetail(value: unknown): DetailRendering {\n  return renderDetailValue(value, {\n    ancestors: new Set<object>(),\n    remainingCharacters: MAX_DETAIL_CHARACTERS,\n    remainingValues: MAX_DETAIL_VALUES\n  });\n}\n\n// These bounds admit ordinary package handoffs while keeping diagnostic work finite.\nconst MAX_DETAIL_CHARACTERS = 1_048_576;\nconst MAX_DETAIL_DEPTH = 16;\nconst MAX_DETAIL_VALUES = 32_768;\nconst MAX_DETAIL_WIDTH = 4_096;\n\ntype DetailRendering =\n  | Readonly<{ readonly ok: true; readonly text: string }>\n  | Readonly<{ readonly ok: false; readonly reason: string }>;\n\ninterface DetailRenderingContext {\n  readonly ancestors: Set<object>;\n  remainingCharacters: number;\n  remainingValues: number;\n}\n\n/** Renders only descriptor-readable JSON values; diagnostics must never invoke author hooks. */\nfunction renderDetailValue(\n  value: unknown,\n  context: DetailRenderingContext,\n  depth = 0\n): DetailRendering {\n  if (context.remainingValues <= 0) return unavailable(\"value-limit\");\n  context.remainingValues -= 1;\n  const scalar = renderDetailScalar(value, context);\n  if (scalar !== undefined) return scalar;\n  return renderDetailCompound(value, context, depth);\n}\n\nfunction renderDetailScalar(\n  value: unknown,\n  context: DetailRenderingContext\n): DetailRendering | undefined {\n  if (value === null || typeof value === \"boolean\" || typeof value === \"string\") {\n    return renderDetailText(JSON.stringify(value), context);\n  }\n  if (typeof value !== \"number\") return undefined;\n  return Number.isFinite(value)\n    ? renderDetailText(JSON.stringify(value), context)\n    : unavailable(\"non-finite-number\");\n}\n\nfunction renderDetailCompound(\n  value: unknown,\n  context: DetailRenderingContext,\n  depth: number\n): DetailRendering {\n  if (value === null || typeof value !== \"object\")\n    return unavailable(`unsupported-${typeof value}`);\n  if (types.isProxy(value)) return unavailable(\"proxy\");\n  if (context.ancestors.has(value)) return unavailable(\"cycle\");\n  if (depth >= MAX_DETAIL_DEPTH) return unavailable(\"depth-limit\");\n  return Array.isArray(value)\n    ? renderDetailArray(value, context, depth)\n    : renderDetailRecord(value, context, depth);\n}\n\nfunction renderDetailArray(\n  value: readonly unknown[],\n  context: DetailRenderingContext,\n  depth: number\n): DetailRendering {\n  const inspection = inspectDetailArray(value);\n  if (!inspection.ok) return inspection;\n  context.ancestors.add(value);\n  try {\n    return renderDetailArrayItems(value, inspection.length, context, depth);\n  } finally {\n    context.ancestors.delete(value);\n  }\n}\n\ntype DetailArrayInspection =\n  | Readonly<{ readonly ok: false; readonly reason: string }>\n  | Readonly<{ readonly ok: true; readonly length: number }>;\n\nfunction inspectDetailArray(value: readonly unknown[]): DetailArrayInspection {\n  if (Object.getPrototypeOf(value) !== Array.prototype)\n    return unavailableArray(\"unsupported-prototype\");\n  const length = readableArrayLength(value);\n  if (length === null) return unavailableArray(\"invalid-array\");\n  if (length > MAX_DETAIL_WIDTH) return unavailableArray(\"width-limit\");\n  return Reflect.ownKeys(value).length === length + 1\n    ? Object.freeze({ length, ok: true })\n    : unavailableArray(\"invalid-array\");\n}\n\nfunction readableArrayLength(value: readonly unknown[]): number | null {\n  const descriptor = Object.getOwnPropertyDescriptor(value, \"length\");\n  const length: unknown = descriptor?.value;\n  if (descriptor?.get !== undefined || descriptor?.set !== undefined) return null;\n  return typeof length === \"number\" && Number.isSafeInteger(length) && length >= 0 ? length : null;\n}\n\nfunction renderDetailArrayItems(\n  value: readonly unknown[],\n  length: number,\n  context: DetailRenderingContext,\n  depth: number\n): DetailRendering {\n  const items: string[] = [];\n  for (let index = 0; index < length; index += 1) {\n    const descriptor = Object.getOwnPropertyDescriptor(value, String(index));\n    if (!isEnumerableDataDescriptor(descriptor)) return unavailable(\"accessor-or-sparse-array\");\n    const rendered = renderDetailValue(descriptor.value, context, depth + 1);\n    if (!rendered.ok) return rendered;\n    items.push(rendered.text);\n  }\n  return renderDetailText(`[${items.join(\",\")}]`, context);\n}\n\nfunction renderDetailRecord(\n  value: object,\n  context: DetailRenderingContext,\n  depth: number\n): DetailRendering {\n  const prototype: unknown = Object.getPrototypeOf(value);\n  if (prototype !== Object.prototype && prototype !== null)\n    return unavailable(\"unsupported-prototype\");\n  const keys = Reflect.ownKeys(value);\n  if (keys.length > MAX_DETAIL_WIDTH) return unavailable(\"width-limit\");\n  const textKeys: string[] = [];\n  for (let index = 0; index < keys.length; index += 1) {\n    const key = keys[index];\n    if (typeof key !== \"string\") return unavailable(\"symbol-key\");\n    textKeys.push(key);\n  }\n  textKeys.sort();\n  context.ancestors.add(value);\n  try {\n    const entries: string[] = [];\n    for (const key of textKeys) {\n      const descriptor = Object.getOwnPropertyDescriptor(value, key);\n      if (!isEnumerableDataDescriptor(descriptor))\n        return unavailable(\"accessor-or-hidden-property\");\n      const rendered = renderDetailValue(descriptor.value, context, depth + 1);\n      if (!rendered.ok) return rendered;\n      entries.push(`${JSON.stringify(key)}:${rendered.text}`);\n    }\n    return renderDetailText(`{${entries.join(\",\")}}`, context);\n  } finally {\n    context.ancestors.delete(value);\n  }\n}\n\nfunction isEnumerableDataDescriptor(\n  descriptor: PropertyDescriptor | undefined\n): descriptor is PropertyDescriptor & Readonly<{ readonly value: unknown }> {\n  return (\n    descriptor !== undefined &&\n    descriptor.enumerable === true &&\n    descriptor.get === undefined &&\n    descriptor.set === undefined &&\n    Object.hasOwn(descriptor, \"value\")\n  );\n}\n\nfunction renderDetailText(text: string, context: DetailRenderingContext): DetailRendering {\n  if (text.length > context.remainingCharacters) return unavailable(\"size-limit\");\n  context.remainingCharacters -= text.length;\n  return Object.freeze({ ok: true, text });\n}\n\nfunction unavailable(reason: string): DetailRendering {\n  return Object.freeze({ ok: false, reason });\n}\n\nfunction unavailableArray(reason: string): DetailArrayInspection {\n  return Object.freeze({ ok: false, reason });\n}\n"]}

package/dist/esm/project-run/diagnostic-logging/logger.mjs

@@ -0,0 +1,242 @@
+import { closeSync, mkdirSync, openSync, writeSync } from "node:fs";
+import { dirname } from "node:path";
+import { renderSafeDiagnosticDetail } from "./diagnostic-detail-rendering.mjs";
+export { summarizeDiagnosticValue } from "./diagnostic-detail-rendering.mjs";
+export const createDiagnosticLogger = (input) => {
+    if (!input.enabled || input.file === null)
+        return disabledLogger();
+    return createEnabledLogger({ clock: input.clock, file: input.file });
+};
+/** Builds one immutable set of human-filterable diagnostic labels. */
+export function diagnosticTags(...tags) {
+    return Object.freeze([...tags]);
+}
+function disabledLogger() {
+    return Object.freeze({
+        close: () => "disabled",
+        observe: () => undefined
+    });
+}
+function createEnabledLogger(input) {
+    let descriptor;
+    let failed = false;
+    let sequence = 0;
+    const startedAt = safeNow(input.clock);
+    try {
+        mkdirSync(dirname(input.file), { recursive: true });
+        descriptor = openSync(input.file, "wx");
+    }
+    catch {
+        failed = true;
+    }
+    return Object.freeze({
+        close: () => {
+            if (descriptor !== undefined) {
+                try {
+                    closeSync(descriptor);
+                }
+                catch {
+                    failed = true;
+                }
+                descriptor = undefined;
+            }
+            return failed ? "failed" : "succeeded";
+        },
+        observe: (observation) => {
+            if (failed || descriptor === undefined)
+                return;
+            try {
+                const buffer = renderObservation({
+                    elapsedMs: elapsedSince(startedAt, input.clock),
+                    observation,
+                    sequence: sequence + 1
+                });
+                sequence += 1;
+                writeBuffer(descriptor, buffer);
+            }
+            catch {
+                failed = true;
+            }
+        }
+    });
+}
+function writeBuffer(descriptor, buffer) {
+    const bytes = Buffer.from(buffer, "utf8");
+    let offset = 0;
+    while (offset < bytes.length) {
+        const written = writeSync(descriptor, bytes, offset, bytes.length - offset, null);
+        if (written <= 0)
+            throw new Error("Diagnostic log append made no progress");
+        offset += written;
+    }
+}
+function renderObservation(input) {
+    const tags = input.observation.tags.map((tag) => `[${escapeLogHeaderField(tag)}]`).join(" ");
+    const header = `#${String(input.sequence).padStart(6, "0")} +${formatElapsed(input.elapsedMs)} ${tags} ${escapeLogHeaderField(input.observation.event)}`;
+    return renderFactLines(header, diagnosticFacts(input.observation));
+}
+/** Keeps author-controlled header fields on one physical header line. */
+function escapeLogHeaderField(text) {
+    let escaped = "";
+    for (const character of text) {
+        if (character === "\\") {
+            escaped += "\\\\";
+            continue;
+        }
+        const codeUnit = character.charCodeAt(0);
+        escaped +=
+            codeUnit <= 0x1f ||
+                (codeUnit >= 0x7f && codeUnit <= 0x9f) ||
+                codeUnit === 0x5b ||
+                codeUnit === 0x5d ||
+                codeUnit === 0x2028 ||
+                codeUnit === 0x2029
+                ? `\\u${codeUnit.toString(16).padStart(4, "0")}`
+                : character;
+    }
+    return escaped;
+}
+function diagnosticFacts(observation) {
+    if (observation.details === undefined)
+        return Object.freeze([]);
+    const rendered = renderSafeDiagnosticDetail(observation.details);
+    if (!rendered.ok)
+        return Object.freeze([`details=unavailable:${escapeLogHeaderField(rendered.reason)}`]);
+    const value = JSON.parse(rendered.text);
+    const facts = [];
+    flattenDiagnosticFacts(value, [], facts, observation);
+    return Object.freeze(facts);
+}
+function flattenDiagnosticFacts(value, path, facts, observation) {
+    if (Array.isArray(value)) {
+        flattenDiagnosticArrayFacts(value, path, facts, observation);
+        return;
+    }
+    if (value !== null && typeof value === "object") {
+        flattenDiagnosticRecordFacts(value, path, facts, observation);
+        return;
+    }
+    facts.push(`${factKey(path)}=${factValue(path, value)}`);
+}
+function flattenDiagnosticArrayFacts(value, path, facts, observation) {
+    const inline = JSON.stringify(value);
+    if (inline.length <= MAX_INLINE_DIAGNOSTIC_VALUE_CHARACTERS) {
+        facts.push(`${factKey(path)}=${inline}`);
+        return;
+    }
+    const arrayPath = path.length === 0 ? ["details"] : path;
+    for (let index = 0; index < value.length; index += 1) {
+        flattenDiagnosticFacts(value[index], [...arrayPath, String(index)], facts, observation);
+    }
+}
+function flattenDiagnosticRecordFacts(value, path, facts, observation) {
+    const entries = Object.entries(value);
+    if (entries.length === 0) {
+        facts.push(`${factKey(path)}={}`);
+        return;
+    }
+    for (const [key, nested] of entries) {
+        if (path.length === 0 && isTopLevelFactRepresentedByTag(observation, key, nested))
+            continue;
+        flattenDiagnosticFacts(nested, [...path, key], facts, observation);
+    }
+}
+/** Omits only exact producer facts already visible in the observation's filter tags. */
+function isTopLevelFactRepresentedByTag(observation, key, value) {
+    if (typeof value !== "string")
+        return false;
+    if (observation.event === "scheduler.decision") {
+        if (key === "kind")
+            return observation.tags.includes(value.toUpperCase());
+        return key === "taskId" && observation.tags.includes(`TASK:${value}`);
+    }
+    return (observation.event === "record.reported" &&
+        key === "result" &&
+        observation.tags.includes(value.toUpperCase()));
+}
+const MAX_INLINE_DIAGNOSTIC_VALUE_CHARACTERS = 120;
+function factKey(path) {
+    if (path.length === 0)
+        return "details";
+    const joined = path.join(".");
+    return /^[A-Za-z_][A-Za-z0-9_.-]*$/u.test(joined) ? joined : JSON.stringify(joined);
+}
+function factValue(path, value) {
+    const key = path.at(-1);
+    if (typeof value === "number" && key?.endsWith("Ms")) {
+        return String(Math.round(value * 1_000) / 1_000);
+    }
+    return JSON.stringify(value);
+}
+const MAX_DIAGNOSTIC_LINE_CHARACTERS = 200;
+function renderFactLines(header, facts) {
+    if (facts.length === 0)
+        return `${header}\n`;
+    const lines = [];
+    let current = header;
+    for (const fact of facts) {
+        if (current.length + 1 + fact.length <= MAX_DIAGNOSTIC_LINE_CHARACTERS) {
+            current += ` ${fact}`;
+            continue;
+        }
+        lines.push(current);
+        const firstCapacity = MAX_DIAGNOSTIC_LINE_CHARACTERS - "│ ".length;
+        const continuationCapacity = MAX_DIAGNOSTIC_LINE_CHARACTERS - "│   ".length;
+        let offset = 0;
+        let prefix = "│ ";
+        while (fact.length - offset > (prefix === "│ " ? firstCapacity : continuationCapacity)) {
+            const capacity = prefix === "│ " ? firstCapacity : continuationCapacity;
+            const end = diagnosticChunkEnd(fact, offset, capacity);
+            lines.push(`${prefix}${fact.slice(offset, end)}`);
+            offset = end;
+            prefix = "│   ";
+        }
+        current = `${prefix}${fact.slice(offset)}`;
+    }
+    lines.push(current);
+    return `${lines.join("\n")}\n`;
+}
+function diagnosticChunkEnd(text, offset, capacity) {
+    let end = offset + capacity;
+    const preferredMinimum = offset + Math.floor(capacity * 0.6);
+    for (let index = end - 1; index >= preferredMinimum; index -= 1) {
+        if (text[index] === " ") {
+            end = index;
+            break;
+        }
+        if (text[index] === ",") {
+            end = index + 1;
+            break;
+        }
+    }
+    if (end < text.length &&
+        text.charCodeAt(end - 1) >= 0xd800 &&
+        text.charCodeAt(end - 1) <= 0xdbff &&
+        text.charCodeAt(end) >= 0xdc00 &&
+        text.charCodeAt(end) <= 0xdfff) {
+        end -= 1;
+    }
+    return end;
+}
+function formatElapsed(elapsedMs) {
+    const totalMilliseconds = Math.round(elapsedMs);
+    const hours = Math.floor(totalMilliseconds / 3_600_000);
+    const minutes = Math.floor((totalMilliseconds % 3_600_000) / 60_000);
+    const seconds = Math.floor((totalMilliseconds % 60_000) / 1_000);
+    const milliseconds = totalMilliseconds % 1_000;
+    return `${String(hours).padStart(2, "0")}:${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}.${String(milliseconds).padStart(3, "0")}`;
+}
+function safeNow(clock) {
+    try {
+        const now = clock.now();
+        return Number.isFinite(now) ? now : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function elapsedSince(startedAt, clock) {
+    const elapsed = safeNow(clock) - startedAt;
+    return Number.isFinite(elapsed) && elapsed >= 0 ? elapsed : 0;
+}
+//# sourceMappingURL=logger.mjs.map