feat(config): add exclude support to defaults

[fbosch]

Summary

Allow exclude patterns to be set in defaults and inherited by all sources.

Changes

• Add exclude field to defaults configuration with inheritance to sources
• Update schema and config types to support top-level exclude patterns
• Remove unused tocFormat and simplify documentation structure
• Add validation and test coverage for defaults exclude behavior

Summary by CodeRabbit

• New Features

  • Added exclude option to configuration defaults, enabling users to exclude paths globally across sources.
  • Sources automatically inherit default exclude patterns when their own exclude option is not specified.

• Documentation

  • Updated configuration documentation with expanded field descriptions, clarified default behaviors, and improved examples.

• Tests

  • Enhanced test coverage for exclude functionality in configuration validation and sync operations.

[pkg-pr-new]

Open in StackBlitz

npx https://pkg.pr.new/fbosch/docs-cache@17

commit: a1658de

[Copilot]

Pull request overview

This PR adds support for defaults.exclude in the configuration so exclude patterns can be defined once and inherited by all sources, and cleans up related schema and documentation.

Changes:

• Extend config types, resolver (resolveSources), and sync planning (getSyncPlan) to support defaults.exclude and inherit it to sources when per-source excludes are unset.
• Update the Zod schema, JSON schema, and README to document top-level defaults.exclude and simplify source option docs (removing tocFormat and redundant per-source options list).
• Add validation and integration tests to cover the new defaults exclude behavior and its propagation to sources and materialization.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/sync-include-exclude.test.js	Adds an integration test verifying that defaults.exclude is honored when a source does not specify its own exclude.
tests/edge-cases-validation.test.js	Extends validation tests to cover defaults.exclude round-tripping and inheritance into resolved sources.
src/sync.ts	Updates sync planning to fall back to defaults.exclude when source.exclude is unset so rule hashing and materialization respect default excludes.
src/config.ts	Adds exclude to DocsCacheDefaults, wires it through DEFAULT_CONFIG, validateConfig, and resolveSources so defaults are always resolved and inherited.
src/config-schema.ts	Extends the Zod DefaultsSchema to include an optional exclude array consistent with the runtime config shape.
docs.config.schema.json	Adds defaults.exclude to the public JSON schema and removes the unused tocFormat property from both defaults and sources.
README.md	Documents the new defaults.exclude option, clarifies inheritance behavior, and simplifies the source options section to highlight default-based configuration.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/config.ts (1)

278-285: ⚠️ Potential issue | 🟠 Major

Allow empty exclude arrays to clear defaults.

assertStringArray rejects empty arrays, so defaults.exclude: [] (and sources[].exclude: []) throws even though the schemas permit empty arrays. This blocks explicitly clearing defaults for a source. Either relax validation for exclude or tighten the schemas to require minItems: 1.

🛠️ Proposed fix (allow empty arrays for exclude)

-const assertStringArray = (value: unknown, label: string): string[] => {
-	if (!Array.isArray(value) || value.length === 0) {
-		throw new Error(`${label} must be a non-empty array of strings.`);
-	}
+const assertStringArray = (
+	value: unknown,
+	label: string,
+	options: { allowEmpty?: boolean } = {},
+): string[] => {
+	const { allowEmpty = false } = options;
+	if (!Array.isArray(value) || (!allowEmpty && value.length === 0)) {
+		throw new Error(
+			`${label} must be ${allowEmpty ? "an array" : "a non-empty array"} of strings.`,
+		);
+	}
 	for (const entry of value) {
 		if (typeof entry !== "string" || entry.length === 0) {
 			throw new Error(`${label} must contain non-empty strings.`);
 		}
 	}
 	return value as string[];
 };

-			exclude:
-				defaultsInput.exclude !== undefined
-					? assertStringArray(defaultsInput.exclude, "defaults.exclude")
-					: defaultValues.exclude,
+			exclude:
+				defaultsInput.exclude !== undefined
+					? assertStringArray(defaultsInput.exclude, "defaults.exclude", {
+							allowEmpty: true,
+						})
+					: defaultValues.exclude,

-		if (entry.exclude !== undefined) {
-			source.exclude = assertStringArray(
-				entry.exclude,
-				`sources[${index}].exclude`,
-			);
-		}
+		if (entry.exclude !== undefined) {
+			source.exclude = assertStringArray(
+				entry.exclude,
+				`sources[${index}].exclude`,
+				{ allowEmpty: true },
+			);
+		}