docs: document config diagnostics helpers

steipete · steipete · commit 8408c16da4db · 2026-06-04T04:03:16.000-04:00
diff --git a/src/config/byte-size.ts b/src/config/byte-size.ts
@@ -1,3 +1,4 @@
+// Parses byte-size config values for logging and retention limits.
 import { parseByteSize } from "../cli/parse-bytes.js";
 
 /**
diff --git a/src/config/cache-utils.ts b/src/config/cache-utils.ts
@@ -1,3 +1,4 @@
+// Provides config cache helpers with filesystem freshness checks.
 import fs from "node:fs";
 import { parseStrictNonNegativeInteger } from "../infra/parse-finite-number.js";
 
diff --git a/src/config/codex-plugin-diagnostics.ts b/src/config/codex-plugin-diagnostics.ts
@@ -1,3 +1,4 @@
+// Builds diagnostics for Codex plugin config and provider wiring.
 import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import {
diff --git a/src/config/config.allowlist-requires-allowfrom.test.ts b/src/config/config.allowlist-requires-allowfrom.test.ts
@@ -1,3 +1,4 @@
+// Regresses allowlist config requiring explicit allowFrom entries.
 import { describe, expect, it } from "vitest";
 import {
   DiscordConfigSchema,
diff --git a/src/config/config.hooks-module-paths.test.ts b/src/config/config.hooks-module-paths.test.ts
@@ -1,3 +1,4 @@
+// Covers hook module path config validation.
 import { describe, expect, it } from "vitest";
 import { validateConfigObjectWithPlugins } from "./validation.js";
 
diff --git a/src/config/config.multi-agent-agentdir-validation.test.ts b/src/config/config.multi-agent-agentdir-validation.test.ts
@@ -1,3 +1,4 @@
+// Verifies multi-agent agent directory validation and rejection paths.
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { describe, expect, it, vi } from "vitest";
diff --git a/src/config/logging.ts b/src/config/logging.ts
@@ -1,3 +1,4 @@
+// Normalizes logging config, log paths, and file-size limits.
 import fs from "node:fs";
 import { theme } from "../../packages/terminal-core/src/theme.js";
 import type { RuntimeEnv } from "../runtime.js";
diff --git a/src/config/markdown-tables.test.ts b/src/config/markdown-tables.test.ts
@@ -1,3 +1,4 @@
+// Covers markdown table config normalization and channel overrides.
 import { describe, expect, it, vi } from "vitest";
 
 const listChannelPluginsMock = vi.hoisted(() =>
diff --git a/src/config/merge-patch.proto-pollution.test.ts b/src/config/merge-patch.proto-pollution.test.ts
@@ -1,3 +1,4 @@
+// Verifies config merge patches reject prototype pollution inputs.
 import { describe, it, expect } from "vitest";
 import { applyMergePatch } from "./merge-patch.js";
 
diff --git a/src/config/merge-patch.test.ts b/src/config/merge-patch.test.ts
@@ -1,3 +1,4 @@
+// Covers JSON merge-patch behavior for config mutations.
 import { describe, expect, it } from "vitest";
 import { applyMergePatch } from "./merge-patch.js";
 
diff --git a/src/config/plugin-install-config-migration.ts b/src/config/plugin-install-config-migration.ts
@@ -1,3 +1,4 @@
+// Migrates plugin install config entries into canonical config shape.
 import { isRecord } from "@openclaw/normalization-core/record-coerce";
 import { z } from "zod";
 import type { PluginInstallRecord } from "./types.plugins.js";
diff --git a/src/config/plugins-runtime-boundary.test.ts b/src/config/plugins-runtime-boundary.test.ts
@@ -1,3 +1,4 @@
+// Verifies config code does not cross plugin runtime boundaries.
 import { describe, expect, it } from "vitest";
 import { FIELD_HELP } from "./schema.help.js";
 import { FIELD_LABELS } from "./schema.labels.js";
diff --git a/src/config/port-defaults.ts b/src/config/port-defaults.ts
@@ -1,3 +1,4 @@
+// Defines default port ranges for gateway and service config.
 type PortRange = { start: number; end: number };
 
 function isValidPort(port: number): boolean {
diff --git a/src/config/runtime-schema.test.ts b/src/config/runtime-schema.test.ts
@@ -1,3 +1,4 @@
+// Covers runtime schema defaults and generated runtime config behavior.
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { createEmptyPluginRegistry } from "../plugins/registry-empty.js";
 import {
diff --git a/src/config/schema.help.quality.test.ts b/src/config/schema.help.quality.test.ts
@@ -1,3 +1,4 @@
+// Checks config help text quality and coverage.
 import { describe, expect, it } from "vitest";
 import { MEDIA_AUDIO_FIELD_KEYS } from "./media-audio-field-metadata.js";
 import { FIELD_HELP } from "./schema.help.js";
diff --git a/src/config/schema.hints.test.ts b/src/config/schema.hints.test.ts
@@ -1,3 +1,4 @@
+// Verifies schema hint metadata and sensitive path handling.
 import { isSensitiveUrlConfigPath } from "@openclaw/net-policy/redact-sensitive-url";
 import { describe, expect, it } from "vitest";
 import { z } from "zod";
diff --git a/src/config/session-parent-fork-config-keys.test.ts b/src/config/session-parent-fork-config-keys.test.ts
@@ -1,3 +1,4 @@
+// Verifies parent-fork session config keys stay aligned with schema.
 import { describe, expect, it } from "vitest";
 import { validateConfigObjectRaw } from "./validation.js";
 
diff --git a/src/config/types.gateway.ts b/src/config/types.gateway.ts
@@ -1,3 +1,4 @@
+// Defines gateway runtime and networking configuration types.
 import type { SecretInput } from "./types.secrets.js";
 
 /** Gateway bind-address policy for local server startup. */
diff --git a/src/config/types.models.ts b/src/config/types.models.ts
@@ -1,3 +1,4 @@
+// Defines model selection and provider configuration types.
 import type {
   AnthropicMessagesCompat,
   OpenAICompletionsCompat,
diff --git a/src/config/types.plugins.ts b/src/config/types.plugins.ts
@@ -1,3 +1,4 @@
+// Defines plugin entry and install configuration types.
 export type PluginEntryConfig = {
   enabled?: boolean;
   hooks?: {
diff --git a/src/config/types.signal.ts b/src/config/types.signal.ts
@@ -1,3 +1,4 @@
+// Defines Signal channel configuration types.
 import type { CommonChannelMessagingConfig } from "./types.channel-messaging-common.js";
 import type { GroupToolPolicyBySenderConfig, GroupToolPolicyConfig } from "./types.tools.js";
 
diff --git a/src/config/validation.policy.test.ts b/src/config/validation.policy.test.ts
@@ -1,3 +1,4 @@
+// Covers config validation policy decisions and warning behavior.
 import { describe, expect, it, vi } from "vitest";
 import { validateConfigObjectRaw } from "./validation.js";
 
diff --git a/src/config/zod-schema.providers-whatsapp.test.ts b/src/config/zod-schema.providers-whatsapp.test.ts
@@ -1,3 +1,4 @@
+// Verifies WhatsApp provider schema parsing and defaults.
 import { describe, it, expect } from "vitest";
 import { WhatsAppConfigSchema, WhatsAppAccountSchema } from "./zod-schema.providers-whatsapp.js";
 
diff --git a/src/config/zod-schema.talk.test.ts b/src/config/zod-schema.talk.test.ts
@@ -1,3 +1,4 @@
+// Covers talk schema parsing and validation behavior.
 import { describe, expect, it } from "vitest";
 import { OpenClawSchema } from "./zod-schema.js";
 

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Parses byte-size config values for logging and retention limits.`
`1`	`2`	`import { parseByteSize } from "../cli/parse-bytes.js";`
`2`	`3`
`3`	`4`	`/**`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Provides config cache helpers with filesystem freshness checks.`
`1`	`2`	`import fs from "node:fs";`
`2`	`3`	`import { parseStrictNonNegativeInteger } from "../infra/parse-finite-number.js";`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Builds diagnostics for Codex plugin config and provider wiring.`
`1`	`2`	`import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";`
`2`	`3`	`import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";`
`3`	`4`	`import {`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Regresses allowlist config requiring explicit allowFrom entries.`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import {`
`3`	`4`	`DiscordConfigSchema,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Covers hook module path config validation.`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import { validateConfigObjectWithPlugins } from "./validation.js";`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Verifies multi-agent agent directory validation and rejection paths.`
`1`	`2`	`import { tmpdir } from "node:os";`
`2`	`3`	`import path from "node:path";`
`3`	`4`	`import { describe, expect, it, vi } from "vitest";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Normalizes logging config, log paths, and file-size limits.`
`1`	`2`	`import fs from "node:fs";`
`2`	`3`	`import { theme } from "../../packages/terminal-core/src/theme.js";`
`3`	`4`	`import type { RuntimeEnv } from "../runtime.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Covers markdown table config normalization and channel overrides.`
`1`	`2`	`import { describe, expect, it, vi } from "vitest";`
`2`	`3`
`3`	`4`	`const listChannelPluginsMock = vi.hoisted(() =>`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Verifies config merge patches reject prototype pollution inputs.`
`1`	`2`	`import { describe, it, expect } from "vitest";`
`2`	`3`	`import { applyMergePatch } from "./merge-patch.js";`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Covers JSON merge-patch behavior for config mutations.`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import { applyMergePatch } from "./merge-patch.js";`
`3`	`4`