feat(toc): unify toc config into single field

fbosch · fbosch · commit db81975311c7 · 2026-02-02T13:01:55.000+01:00
diff --git a/README.md b/README.md
@@ -19,7 +19,7 @@ Documentation is cached in a gitignored location, exposed to agent and tool targ
 - **Fast**: Local cache avoids network roundtrips after sync.
 - **Flexible**: Cache full repos or just the subdirectories you need.
 
-> **Note**: Sources are downloaded to a local cache. If you provide a `targetDir`, `docs-cache` creates a symlink or copy from the cache to that target directory. The target should be outside `.docs`.
+> **Note**: Sources are downloaded to a local cache. If you provide a `targetDir`, `docs-cache` creates a symlink or copy from the cache to that target directory.
 
 ## Usage
 
@@ -99,9 +99,7 @@ All fields in `defaults` apply to all sources unless overridden per-source.
 | `maxBytes`   | Maximum total bytes to materialize. Default: `200000000` (200 MB).                                        |
 | `maxFiles`   | Maximum total files to materialize.                                                                       |
 | `allowHosts` | Allowed Git hosts. Default: `["github.com", "gitlab.com"]`.                                               |
-| `toc`        | Generate per-source `TOC.md` listing all documentation files. Default: `true`.                            |
-
-> **Note**: Git operation timeout can be configured via the `--timeout-ms` CLI flag (default: 120000ms / 2 minutes).
+| `toc`        | Generate per-source `TOC.md`. Default: `true`. Supports `true`, `false`, or a format (`"tree"`, `"compressed"`). |
 
 ### Source options
 
@@ -124,7 +122,7 @@ All fields in `defaults` apply to all sources unless overridden per-source.
 | `required`   | Whether missing sources should fail.                             |
 | `maxBytes`   | Maximum total bytes to materialize.                              |
 | `maxFiles`   | Maximum total files to materialize.                              |
-| `toc`        | Generate per-source `TOC.md` listing all documentation files.    |
+| `toc`        | Generate per-source `TOC.md`. Supports `true`, `false`, or a format (`"tree"`, `"compressed"`). |
 
 > **Note**: Sources are always downloaded to `.docs/<id>/`. If you provide a `targetDir`, `docs-cache` will create a symlink or copy pointing from the cache to that target directory. The target should be outside `.docs`. Git operation timeout is configured via the `--timeout-ms` CLI flag, not as a per-source configuration option.
 
diff --git a/src/config-schema.ts b/src/config-schema.ts
@@ -22,7 +22,6 @@ export const DefaultsSchema = z
 		maxFiles: z.number().min(1).optional(),
 		allowHosts: z.array(z.string().min(1)).min(1),
 		toc: z.union([z.boolean(), TocFormatSchema]).optional(),
-		tocFormat: TocFormatSchema.optional(),
 	})
 	.strict();
 
@@ -42,7 +41,6 @@ export const SourceSchema = z
 		maxFiles: z.number().min(1).optional(),
 		integrity: IntegritySchema.optional(),
 		toc: z.union([z.boolean(), TocFormatSchema]).optional(),
-		tocFormat: TocFormatSchema.optional(),
 	})
 	.strict();
 
diff --git a/src/config.ts b/src/config.ts
@@ -26,7 +26,6 @@ export interface DocsCacheDefaults {
 	maxFiles?: number;
 	allowHosts: string[];
 	toc?: boolean | TocFormat;
-	tocFormat?: TocFormat;
 }
 
 export interface DocsCacheSource {
@@ -44,7 +43,6 @@ export interface DocsCacheSource {
 	maxFiles?: number;
 	integrity?: DocsCacheIntegrity;
 	toc?: boolean | TocFormat;
-	tocFormat?: TocFormat;
 }
 
 export interface DocsCacheConfig {
@@ -70,7 +68,6 @@ export interface DocsCacheResolvedSource {
 	maxFiles?: number;
 	integrity?: DocsCacheIntegrity;
 	toc?: boolean | TocFormat;
-	tocFormat?: TocFormat;
 }
 
 export const DEFAULT_CONFIG_FILENAME = "docs.config.json";
@@ -88,7 +85,7 @@ export const DEFAULT_CONFIG: DocsCacheConfig = {
 		required: true,
 		maxBytes: 200000000,
 		allowHosts: ["github.com", "gitlab.com"],
-		tocFormat: "compressed",
+		toc: true,
 	},
 	sources: [],
 };
@@ -238,33 +235,6 @@ const assertIntegrity = (value: unknown, label: string): DocsCacheIntegrity => {
 	return { type, value: integrityValue };
 };
 
-const normalizeTocConfig = (
-	toc: boolean | TocFormat | undefined,
-	tocFormat: TocFormat | undefined,
-): { toc?: boolean | TocFormat; tocFormat?: TocFormat } => {
-	// If tocFormat is explicitly set, use it (and keep toc if it was set too)
-	if (tocFormat !== undefined) {
-		if (toc !== undefined) {
-			return { toc, tocFormat };
-		}
-		return { tocFormat };
-	}
-	// If toc is a format string, set tocFormat but also keep toc
-	if (typeof toc === "string") {
-		return { toc, tocFormat: toc };
-	}
-	// If toc is a boolean, keep it and set tocFormat accordingly
-	if (typeof toc === "boolean") {
-		if (toc) {
-			return { toc, tocFormat: "compressed" };
-		}
-		// When toc is explicitly false, omit tocFormat to avoid setting a format for a disabled TOC
-		return { toc };
-	}
-	// Default case - no toc or tocFormat provided
-	return {};
-};
-
 export const validateConfig = (input: unknown): DocsCacheConfig => {
 	if (!isRecord(input)) {
 		throw new Error("Config must be a JSON object.");
@@ -293,12 +263,6 @@ export const validateConfig = (input: unknown): DocsCacheConfig => {
 			throw new Error("defaults must be an object.");
 		}
 
-		// Normalize toc/tocFormat config for defaults
-		const normalizedToc = normalizeTocConfig(
-			defaultsInput.toc as boolean | TocFormat | undefined,
-			defaultsInput.tocFormat as TocFormat | undefined,
-		);
-
 		defaults = {
 			ref:
 				defaultsInput.ref !== undefined
@@ -336,11 +300,10 @@ export const validateConfig = (input: unknown): DocsCacheConfig => {
 				defaultsInput.allowHosts !== undefined
 					? assertStringArray(defaultsInput.allowHosts, "defaults.allowHosts")
 					: defaultValues.allowHosts,
-			toc: normalizedToc.toc,
-			tocFormat:
-				normalizedToc.tocFormat !== undefined
-					? normalizedToc.tocFormat
-					: defaultValues.tocFormat,
+			toc:
+				defaultsInput.toc !== undefined
+					? (defaultsInput.toc as boolean | TocFormat)
+					: defaultValues.toc,
 		};
 	} else if (targetModeOverride !== undefined) {
 		defaults = {
@@ -428,16 +391,8 @@ export const validateConfig = (input: unknown): DocsCacheConfig => {
 			);
 		}
 
-		// Normalize toc/tocFormat config for this source
-		const normalizedToc = normalizeTocConfig(
-			entry.toc as boolean | TocFormat | undefined,
-			entry.tocFormat as TocFormat | undefined,
-		);
-		if (normalizedToc.toc !== undefined) {
-			source.toc = normalizedToc.toc;
-		}
-		if (normalizedToc.tocFormat !== undefined) {
-			source.tocFormat = normalizedToc.tocFormat;
+		if (entry.toc !== undefined) {
+			source.toc = entry.toc as boolean | TocFormat;
 		}
 
 		return source;
@@ -486,7 +441,6 @@ export const resolveSources = (
 		maxFiles: source.maxFiles ?? defaults.maxFiles,
 		integrity: source.integrity,
 		toc: source.toc ?? defaults.toc,
-		tocFormat: source.tocFormat ?? defaults.tocFormat,
 	}));
 };
 
diff --git a/src/toc.ts b/src/toc.ts
@@ -210,17 +210,13 @@ export const writeToc = async (params: {
 
 		// Determine if TOC should be generated and what format to use
 		const sourceTocConfig = source?.toc;
-		const sourceTocFormat = source?.tocFormat;
 
 		// Determine if TOC is enabled (default: true)
 		const tocEnabled = sourceTocConfig !== false;
 
 		// Determine TOC format
 		let tocFormat: TocFormat = "compressed"; // default
-		if (sourceTocFormat) {
-			tocFormat = sourceTocFormat;
-		} else if (typeof sourceTocConfig === "string") {
-			// Backward compatibility: if toc is a format string, use it
+		if (typeof sourceTocConfig === "string") {
 			tocFormat = sourceTocConfig;
 		}
 
diff --git a/tests/sync-toc-formats.test.js b/tests/sync-toc-formats.test.js
@@ -104,7 +104,7 @@ test("sync writes TOC with tree format when specified", async () => {
 			{
 				id: "local",
 				repo: "https://example.com/repo.git",
-				tocFormat: "tree",
+				toc: "tree",
 			},
 		],
 	};
@@ -157,7 +157,7 @@ test("sync writes TOC with tree format when specified", async () => {
 	assert.ok(!sourceToc.includes("repository:"));
 });
 
-test("sync writes TOC with compressed format via defaults.tocFormat", async () => {
+test("sync writes TOC with compressed format via defaults.toc", async () => {
 	const tmpRoot = path.join(
 		tmpdir(),
 		`docs-cache-toc-defaults-compressed-${Date.now().toString(36)}`,
@@ -174,7 +174,7 @@ test("sync writes TOC with compressed format via defaults.tocFormat", async () =
 		$schema:
 			"https://raw.githubusercontent.com/fbosch/docs-cache/main/docs.config.schema.json",
 		defaults: {
-			tocFormat: "compressed",
+			toc: "compressed",
 		},
 		sources: [
 			{
@@ -223,7 +223,7 @@ test("sync writes TOC with compressed format via defaults.tocFormat", async () =
 	assert.ok(sourceToc.includes("root:{README.md}"));
 });
 
-test("sync writes TOC with tree format via defaults.tocFormat", async () => {
+test("sync writes TOC with tree format via defaults.toc", async () => {
 	const tmpRoot = path.join(
 		tmpdir(),
 		`docs-cache-toc-defaults-tree-${Date.now().toString(36)}`,
@@ -241,7 +241,7 @@ test("sync writes TOC with tree format via defaults.tocFormat", async () => {
 		$schema:
 			"https://raw.githubusercontent.com/fbosch/docs-cache/main/docs.config.schema.json",
 		defaults: {
-			tocFormat: "tree",
+			toc: "tree",
 		},
 		sources: [
 			{
@@ -295,7 +295,7 @@ test("sync writes TOC with tree format via defaults.tocFormat", async () => {
 	assert.ok(!sourceToc.includes("---"));
 });
 
-test("sync supports backward compatibility: toc=true uses compressed format", async () => {
+test("sync supports toc=true using compressed format", async () => {
 	const tmpRoot = path.join(
 		tmpdir(),
 		`docs-cache-toc-backward-compat-${Date.now().toString(36)}`,
