feat(config): add unwrapSingleRootDir (#15)

* feat(config): add unwrapSingleRootDir

* feat: implement unwrapSingleRootDir

* docs: update README

* ci: add precheck and typecheck

* refactor: improve type safety

* feat(config): add unwrapSingleRootDir option

* perf(materialize): use slice for prefix removal

* feat(test): add checkout arg handling

* fix: test

* fix: test

Author: fbosch

.github/workflows/ci.yml

@@ -8,7 +8,47 @@ on:
       - master
 
 jobs:
+  precheck:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          run_install: false
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Audit dependencies
+        run: pnpm audit --audit-level=high
+
+      - name: Lint
+        run: pnpm lint
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Test
+        run: pnpm test
+
+      - name: Build
+        run: pnpm build
+
+      - name: Size limit
+        run: pnpm size
+
   build:
+    needs: precheck
+    if: needs.precheck.result == 'success'
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false

README.md

@@ -94,12 +94,12 @@ All fields in `defaults` apply to all sources unless overridden per-source.
 | `mode`       | Cache mode. Default: `"materialize"`.                                                                     |
 | `include`    | Glob patterns to copy. Default: `["**/*.{md,mdx,markdown,mkd,txt,rst,adoc,asciidoc}"]`.                   |
 | `targetMode` | How to link or copy from the cache to the destination. Default: `"symlink"` on Unix, `"copy"` on Windows. |
-| `depth`      | Git clone depth. Default: `1`.                                                                            |
 | `required`   | Whether missing sources should fail. Default: `true`.                                                     |
 | `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`. Default: `true`. Supports `true`, `false`, or a format (`"tree"`, `"compressed"`). |
+| `unwrapSingleRootDir` | If the materialized output is nested under a single directory, unwrap it (recursively). Default: `false`. |
 
 ### Source options
 
@@ -123,6 +123,7 @@ All fields in `defaults` apply to all sources unless overridden per-source.
 | `maxBytes`   | Maximum total bytes to materialize.                              |
 | `maxFiles`   | Maximum total files to materialize.                              |
 | `toc`        | Generate per-source `TOC.md`. Supports `true`, `false`, or a format (`"tree"`, `"compressed"`). |
+| `unwrapSingleRootDir` | If the materialized output is nested under a single directory, unwrap it (recursively). |
 
 > **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.
 

docs.config.schema.json

@@ -37,10 +37,6 @@
 					"type": "string",
 					"enum": ["symlink", "copy"]
 				},
-				"depth": {
-					"type": "number",
-					"minimum": 1
-				},
 				"required": {
 					"type": "boolean"
 				},
@@ -60,6 +56,9 @@
 						"minLength": 1
 					}
 				},
+				"unwrapSingleRootDir": {
+					"type": "boolean"
+				},
 				"toc": {
 					"anyOf": [
 						{
@@ -107,10 +106,6 @@
 						"type": "string",
 						"enum": ["materialize"]
 					},
-					"depth": {
-						"type": "number",
-						"minimum": 1
-					},
 					"include": {
 						"type": "array",
 						"items": {
@@ -171,6 +166,9 @@
 					"tocFormat": {
 						"type": "string",
 						"enum": ["tree", "compressed"]
+					},
+					"unwrapSingleRootDir": {
+						"type": "boolean"
 					}
 				},
 				"required": ["id", "repo"],

package.json

@@ -84,7 +84,7 @@
 		}
 	],
 	"simple-git-hooks": {
-		"pre-commit": "pnpm lint-staged"
+		"pre-commit": "pnpm lint-staged && pnpm typecheck"
 	},
 	"lint-staged": {
 		"*.{js,ts,cjs,mjs,d.cts,d.mts,jsx,tsx,json,jsonc}": [

src/cli/index.ts

@@ -3,7 +3,7 @@ import process from "node:process";
 import pc from "picocolors";
 import { ExitCode } from "./exit-code";
 import { parseArgs } from "./parse-args";
-import type { CliOptions } from "./types";
+import type { CliCommand } from "./types";
 import { setSilentMode, symbols, ui } from "./ui";
 
 export const CLI_NAME = "docs-cache";
@@ -93,12 +93,10 @@ const parseAddEntries = (rawArgs: string[]) => {
 	return entries;
 };
 
-const runCommand = async (
-	command: string,
-	options: CliOptions,
-	positionals: string[],
-	rawArgs: string[],
-) => {
+const runCommand = async (parsed: CliCommand, rawArgs: string[]) => {
+	const command = parsed.command;
+	const options = parsed.options;
+	const positionals = parsed.args;
 	if (command === "add") {
 		const { addSources } = await import("../add");
 		const { runSync } = await import("../sync");
@@ -380,12 +378,7 @@ export async function main(): Promise<void> {
 			process.exit(ExitCode.InvalidArgument);
 		}
 
-		await runCommand(
-			parsed.command,
-			parsed.options,
-			parsed.positionals,
-			parsed.rawArgs,
-		);
+		await runCommand(parsed.parsed, parsed.rawArgs);
 	} catch (error) {
 		errorHandler(error as Error);
 	}

src/cli/parse-args.ts

@@ -2,7 +2,7 @@ import process from "node:process";
 
 import cac from "cac";
 import { ExitCode } from "./exit-code";
-import type { CliOptions } from "./types";
+import type { CliCommand, CliOptions } from "./types";
 
 const COMMANDS = [
 	"add",
@@ -23,6 +23,7 @@ export type ParsedArgs = {
 	positionals: string[];
 	rawArgs: string[];
 	help: boolean;
+	parsed: CliCommand;
 };
 
 export const parseArgs = (argv = process.argv): ParsedArgs => {
@@ -83,6 +84,11 @@ export const parseArgs = (argv = process.argv): ParsedArgs => {
 			positionals: result.args.slice(1),
 			rawArgs,
 			help: Boolean(result.options.help),
+			parsed: {
+				command: command ?? null,
+				args: result.args.slice(1),
+				options,
+			},
 		};
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);

src/cli/types.ts

@@ -11,3 +11,15 @@ export type CliOptions = {
 	timeoutMs?: number;
 	silent: boolean;
 };
+
+export type CliCommand =
+	| { command: "add"; args: string[]; options: CliOptions }
+	| { command: "remove"; args: string[]; options: CliOptions }
+	| { command: "sync"; args: string[]; options: CliOptions }
+	| { command: "status"; args: string[]; options: CliOptions }
+	| { command: "clean"; args: string[]; options: CliOptions }
+	| { command: "clean-cache"; args: string[]; options: CliOptions }
+	| { command: "prune"; args: string[]; options: CliOptions }
+	| { command: "verify"; args: string[]; options: CliOptions }
+	| { command: "init"; args: string[]; options: CliOptions }
+	| { command: null; args: string[]; options: CliOptions };

src/config-schema.ts

@@ -16,12 +16,12 @@ export const DefaultsSchema = z
 		mode: CacheModeSchema,
 		include: z.array(z.string().min(1)).min(1),
 		targetMode: TargetModeSchema.optional(),
-		depth: z.number().min(1),
 		required: z.boolean(),
 		maxBytes: z.number().min(1),
 		maxFiles: z.number().min(1).optional(),
 		allowHosts: z.array(z.string().min(1)).min(1),
 		toc: z.union([z.boolean(), TocFormatSchema]).optional(),
+		unwrapSingleRootDir: z.boolean().optional(),
 	})
 	.strict();
 
@@ -33,14 +33,14 @@ export const SourceSchema = z
 		targetMode: TargetModeSchema.optional(),
 		ref: z.string().min(1).optional(),
 		mode: CacheModeSchema.optional(),
-		depth: z.number().min(1).optional(),
 		include: z.array(z.string().min(1)).optional(),
 		exclude: z.array(z.string().min(1)).optional(),
 		required: z.boolean().optional(),
 		maxBytes: z.number().min(1).optional(),
 		maxFiles: z.number().min(1).optional(),
 		integrity: IntegritySchema.optional(),
 		toc: z.union([z.boolean(), TocFormatSchema]).optional(),
+		unwrapSingleRootDir: z.boolean().optional(),
 	})
 	.strict();
 

src/config.ts

@@ -20,12 +20,12 @@ export interface DocsCacheDefaults {
 	mode: CacheMode;
 	include: string[];
 	targetMode?: "symlink" | "copy";
-	depth: number;
 	required: boolean;
 	maxBytes: number;
 	maxFiles?: number;
 	allowHosts: string[];
 	toc?: boolean | TocFormat;
+	unwrapSingleRootDir?: boolean;
 }
 
 export interface DocsCacheSource {
@@ -35,14 +35,14 @@ export interface DocsCacheSource {
 	targetMode?: "symlink" | "copy";
 	ref?: string;
 	mode?: CacheMode;
-	depth?: number;
 	include?: string[];
 	exclude?: string[];
 	required?: boolean;
 	maxBytes?: number;
 	maxFiles?: number;
 	integrity?: DocsCacheIntegrity;
 	toc?: boolean | TocFormat;
+	unwrapSingleRootDir?: boolean;
 }
 
 export interface DocsCacheConfig {
@@ -60,14 +60,14 @@ export interface DocsCacheResolvedSource {
 	targetMode?: "symlink" | "copy";
 	ref: string;
 	mode: CacheMode;
-	depth: number;
 	include?: string[];
 	exclude?: string[];
 	required: boolean;
 	maxBytes: number;
 	maxFiles?: number;
 	integrity?: DocsCacheIntegrity;
 	toc?: boolean | TocFormat;
+	unwrapSingleRootDir?: boolean;
 }
 
 export const DEFAULT_CONFIG_FILENAME = "docs.config.json";
@@ -81,11 +81,11 @@ export const DEFAULT_CONFIG: DocsCacheConfig = {
 		mode: "materialize",
 		include: ["**/*.{md,mdx,markdown,mkd,txt,rst,adoc,asciidoc}"],
 		targetMode: DEFAULT_TARGET_MODE,
-		depth: 1,
 		required: true,
 		maxBytes: 200000000,
 		allowHosts: ["github.com", "gitlab.com"],
 		toc: true,
+		unwrapSingleRootDir: false,
 	},
 	sources: [],
 };
@@ -246,15 +246,16 @@ export const validateConfig = (input: unknown): DocsCacheConfig => {
 			.join("; ");
 		throw new Error(`Config does not match schema: ${details}.`);
 	}
+	const configInput = parsed.data;
 
-	const cacheDir = input.cacheDir
-		? assertString(input.cacheDir, "cacheDir")
+	const cacheDir = configInput.cacheDir
+		? assertString(configInput.cacheDir, "cacheDir")
 		: DEFAULT_CACHE_DIR;
 
-	const defaultsInput = input.defaults;
+	const defaultsInput = configInput.defaults;
 	const targetModeOverride =
-		input.targetMode !== undefined
-			? assertTargetMode(input.targetMode, "targetMode")
+		configInput.targetMode !== undefined
+			? assertTargetMode(configInput.targetMode, "targetMode")
 			: undefined;
 	const defaultValues = DEFAULT_CONFIG.defaults as DocsCacheDefaults;
 	let defaults: DocsCacheDefaults = defaultValues;
@@ -280,10 +281,6 @@ export const validateConfig = (input: unknown): DocsCacheConfig => {
 				defaultsInput.targetMode !== undefined
 					? assertTargetMode(defaultsInput.targetMode, "defaults.targetMode")
 					: (targetModeOverride ?? defaultValues.targetMode),
-			depth:
-				defaultsInput.depth !== undefined
-					? assertPositiveNumber(defaultsInput.depth, "defaults.depth")
-					: defaultValues.depth,
 			required:
 				defaultsInput.required !== undefined
 					? assertBoolean(defaultsInput.required, "defaults.required")
@@ -304,6 +301,13 @@ export const validateConfig = (input: unknown): DocsCacheConfig => {
 				defaultsInput.toc !== undefined
 					? (defaultsInput.toc as boolean | TocFormat)
 					: defaultValues.toc,
+			unwrapSingleRootDir:
+				defaultsInput.unwrapSingleRootDir !== undefined
+					? assertBoolean(
+							defaultsInput.unwrapSingleRootDir,
+							"defaults.unwrapSingleRootDir",
+						)
+					: defaultValues.unwrapSingleRootDir,
 		};
 	} else if (targetModeOverride !== undefined) {
 		defaults = {
@@ -312,11 +316,7 @@ export const validateConfig = (input: unknown): DocsCacheConfig => {
 		};
 	}
 
-	if (!Array.isArray(input.sources)) {
-		throw new Error("sources must be an array.");
-	}
-
-	const sources = input.sources.map((entry, index) => {
+	const sources = configInput.sources.map((entry, index) => {
 		if (!isRecord(entry)) {
 			throw new Error(`sources[${index}] must be an object.`);
 		}
@@ -348,12 +348,6 @@ export const validateConfig = (input: unknown): DocsCacheConfig => {
 		if (entry.mode !== undefined) {
 			source.mode = assertMode(entry.mode, `sources[${index}].mode`);
 		}
-		if (entry.depth !== undefined) {
-			source.depth = assertPositiveNumber(
-				entry.depth,
-				`sources[${index}].depth`,
-			);
-		}
 		if (entry.include !== undefined) {
 			source.include = assertStringArray(
 				entry.include,
@@ -394,6 +388,12 @@ export const validateConfig = (input: unknown): DocsCacheConfig => {
 		if (entry.toc !== undefined) {
 			source.toc = entry.toc as boolean | TocFormat;
 		}
+		if (entry.unwrapSingleRootDir !== undefined) {
+			source.unwrapSingleRootDir = assertBoolean(
+				entry.unwrapSingleRootDir,
+				`sources[${index}].unwrapSingleRootDir`,
+			);
+		}
 
 		return source;
 	});
@@ -433,14 +433,15 @@ export const resolveSources = (
 		targetMode: source.targetMode ?? defaults.targetMode,
 		ref: source.ref ?? defaults.ref,
 		mode: source.mode ?? defaults.mode,
-		depth: source.depth ?? defaults.depth,
 		include: source.include ?? defaults.include,
 		exclude: source.exclude,
 		required: source.required ?? defaults.required,
 		maxBytes: source.maxBytes ?? defaults.maxBytes,
 		maxFiles: source.maxFiles ?? defaults.maxFiles,
 		integrity: source.integrity,
 		toc: source.toc ?? defaults.toc,
+		unwrapSingleRootDir:
+			source.unwrapSingleRootDir ?? defaults.unwrapSingleRootDir,
 	}));
 };