compmark-vue 0.3.3 → 0.4.0

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { defineCommand, runMain } from "citty";
-import { existsSync, mkdirSync, readFileSync, statSync, watch, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, watch, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
 import { glob } from "tinyglobby";
 import { babelParse, compileScript, parse } from "@vue/compiler-sfc";
 //#region src/discovery.ts
@@ -9,17 +9,44 @@ async function discoverFiles(inputs, ignore) {
 	const baseIgnore = ["**/node_modules/**"];
 	const userIgnore = (ignore ?? []).map(normalizeIgnorePattern);
 	const allIgnore = [...baseIgnore, ...userIgnore];
+	const hasUserIgnore = userIgnore.length > 0;
 	const found = /* @__PURE__ */ new Set();
+	let ignoredCount = 0;
 	for (const input of inputs) {
 		const resolved = resolve(input);
 		if (input.endsWith(".vue") && existsSync(resolved)) found.add(resolved);
-		else if (isDirectory$1(resolved)) {
+		else if (isDirectory$1(resolved)) if (hasUserIgnore) {
+			const allFiles = await glob("**/*.vue", {
+				cwd: resolved,
+				absolute: true,
+				ignore: baseIgnore
+			});
+			const filteredFiles = await glob("**/*.vue", {
+				cwd: resolved,
+				absolute: true,
+				ignore: allIgnore
+			});
+			ignoredCount += allFiles.length - filteredFiles.length;
+			for (const f of filteredFiles) found.add(f);
+		} else {
 			const files = await glob("**/*.vue", {
 				cwd: resolved,
 				absolute: true,
 				ignore: allIgnore
 			});
 			for (const f of files) found.add(f);
+		}
+		else if (hasUserIgnore) {
+			const allFiles = await glob(input, {
+				absolute: true,
+				ignore: baseIgnore
+			});
+			const filteredFiles = await glob(input, {
+				absolute: true,
+				ignore: allIgnore
+			});
+			ignoredCount += allFiles.length - filteredFiles.length;
+			for (const f of filteredFiles) found.add(f);
 		} else {
 			const files = await glob(input, {
 				absolute: true,
@@ -28,7 +55,25 @@ async function discoverFiles(inputs, ignore) {
 			for (const f of files) found.add(f);
 		}
 	}
-	return [...found].sort();
+	const files = [...found].sort();
+	const basePath = computeBasePath(files);
+	return {
+		files,
+		ignoredCount,
+		basePath
+	};
+}
+function computeBasePath(files) {
+	if (files.length === 0) return ".";
+	if (files.length === 1) return dirname(files[0]);
+	const parts = files.map((f) => dirname(f).split("/"));
+	const common = [];
+	for (let i = 0; i < parts[0].length; i++) {
+		const segment = parts[0][i];
+		if (parts.every((p) => p[i] === segment)) common.push(segment);
+		else break;
+	}
+	return common.join("/") || "/";
 }
 function isDirectory$1(path) {
 	try {
@@ -209,15 +254,15 @@ function inferType(node) {
 		if (typeParams?.params?.length > 0) return `Ref<${resolveTypeAnnotation(typeParams.params[0])}>`;
 		const arg = node.arguments[0];
 		if (!arg) return "Ref<unknown>";
-		return `Ref<${inferLiteralType(arg)}>`;
+		return `Ref<${inferLiteralType$1(arg)}>`;
 	}
 	if (node.type === "CallExpression" && node.callee.type === "Identifier" && node.callee.name === "computed") return "ComputedRef";
 	if (node.type === "CallExpression" && node.callee.type === "Identifier" && node.callee.name === "reactive") return "Object";
 	if (node.type === "ArrowFunctionExpression" || node.type === "FunctionExpression") return inferFunctionSignature(node);
 	if (node.type === "CallExpression" && node.callee.type === "Identifier" && /^use[A-Z]/.test(node.callee.name)) return "unknown";
-	return inferLiteralType(node);
+	return inferLiteralType$1(node);
 }
-function inferLiteralType(node) {
+function inferLiteralType$1(node) {
 	switch (node.type) {
 		case "NumericLiteral": return "number";
 		case "StringLiteral": return "string";
@@ -430,12 +475,17 @@ function parseSFC(source, filename, sfcDir) {
 			else if (callee === "defineExpose" && args[0]?.type === "ObjectExpression") doc.exposes = extractExposes(args[0], scriptSource);
 		}
 		doc.composables = extractComposables(setupAst, importMap, sfcDir);
+		const { refs, computeds } = extractRefsAndComputeds(setupAst, scriptSource);
+		if (refs.length > 0) doc.refs = refs;
+		if (computeds.length > 0) doc.computeds = computeds;
 	}
 	const scriptAst = compiled.scriptAst;
 	if (scriptAst && doc.props.length === 0 && doc.emits.length === 0) {
 		const optionsDoc = extractOptionsAPI(scriptAst, compiled.content);
 		doc.props = optionsDoc.props;
 		doc.emits = optionsDoc.emits;
+		if (optionsDoc.refs.length > 0) doc.refs = optionsDoc.refs;
+		if (optionsDoc.computeds.length > 0) doc.computeds = optionsDoc.computeds;
 	}
 	return doc;
 }
@@ -444,7 +494,8 @@ function extractComponentJSDoc(ast) {
 		description: "",
 		internal: false
 	};
-	const comments = ast[0].leadingComments ?? [];
+	const first = ast[0];
+	const comments = first.leadingComments ?? [];
 	if (comments.length === 0) return {
 		description: "",
 		internal: false
@@ -459,6 +510,13 @@ function extractComponentJSDoc(ast) {
 		description: result.description,
 		internal: true
 	};
+	const isImport = first.type === "ImportDeclaration";
+	const isDefineCall = first.type === "ExpressionStatement" && first.expression.type === "CallExpression" && first.expression.callee.type === "Identifier" && first.expression.callee.name.startsWith("define");
+	const isDefineVar = first.type === "VariableDeclaration" && first.declarations.some((d) => d.init?.type === "CallExpression" && d.init.callee?.type === "Identifier" && (d.init.callee.name.startsWith("define") || d.init.callee.name === "withDefaults"));
+	if (firstComment.value.includes("@component") || isImport || isDefineCall || isDefineVar) return {
+		description: result.description,
+		internal: false
+	};
 	return {
 		description: "",
 		internal: false
@@ -798,6 +856,99 @@ function extractComposables(ast, importMap, sfcDir) {
 	}
 	return composables;
 }
+const REF_CALLEES = new Set([
+	"ref",
+	"shallowRef",
+	"reactive",
+	"shallowReactive"
+]);
+const COMPUTED_CALLEES = new Set(["computed"]);
+const SKIP_CALLEES = new Set([
+	"defineProps",
+	"defineEmits",
+	"defineSlots",
+	"defineExpose",
+	"withDefaults"
+]);
+function inferLiteralType(node) {
+	switch (node.type) {
+		case "StringLiteral": return "string";
+		case "NumericLiteral": return "number";
+		case "BooleanLiteral": return "boolean";
+		case "ArrayExpression": return "Array";
+		case "ObjectExpression": return "Object";
+		case "NullLiteral": return "null";
+		default: return null;
+	}
+}
+function extractRefsAndComputeds(ast, _scriptSource) {
+	const refs = [];
+	const computeds = [];
+	for (const stmt of ast) {
+		if (stmt.type !== "VariableDeclaration") continue;
+		const comments = stmt.leadingComments ?? [];
+		for (const decl of stmt.declarations) {
+			if (!decl.init || decl.init.type !== "CallExpression") continue;
+			if (decl.init.callee.type !== "Identifier") continue;
+			const calleeName = decl.init.callee.name;
+			if (/^use[A-Z]/.test(calleeName)) continue;
+			if (SKIP_CALLEES.has(calleeName)) continue;
+			const isRef = REF_CALLEES.has(calleeName);
+			const isComputed = COMPUTED_CALLEES.has(calleeName);
+			if (!isRef && !isComputed) continue;
+			const id = decl.id;
+			if (!id || id.type !== "Identifier") continue;
+			const varName = id.name;
+			const jsdoc = parseJSDocTags(comments);
+			const callExpr = decl.init;
+			const typeParams = callExpr.typeParameters;
+			const args = callExpr.arguments;
+			let type;
+			if (id.typeAnnotation?.typeAnnotation) type = resolveTypeString(id.typeAnnotation.typeAnnotation);
+			else if (typeParams?.params?.[0]) {
+				const genericType = resolveTypeString(typeParams.params[0]);
+				if (calleeName === "reactive" || calleeName === "shallowReactive") type = genericType;
+				else if (calleeName === "shallowRef") type = `ShallowRef<${genericType}>`;
+				else if (calleeName === "computed") type = `ComputedRef<${genericType}>`;
+				else type = `Ref<${genericType}>`;
+			} else if (isRef && args[0]) {
+				const literalType = inferLiteralType(args[0]);
+				if (literalType) if (calleeName === "reactive" || calleeName === "shallowReactive") type = literalType;
+				else if (calleeName === "shallowRef") type = `ShallowRef<${literalType}>`;
+				else type = `Ref<${literalType}>`;
+				else if (calleeName === "reactive") type = "Object";
+				else if (calleeName === "shallowReactive") type = "Object";
+				else if (calleeName === "shallowRef") type = "ShallowRef";
+				else type = "Ref";
+			} else if (isComputed && args[0]) {
+				let returnType = null;
+				const getter = args[0];
+				if ((getter.type === "ArrowFunctionExpression" || getter.type === "FunctionExpression") && getter.returnType?.type === "TSTypeAnnotation") returnType = resolveTypeString(getter.returnType.typeAnnotation);
+				if (returnType) type = `ComputedRef<${returnType}>`;
+				else type = "ComputedRef";
+			} else if (calleeName === "reactive") type = "Object";
+			else if (calleeName === "shallowReactive") type = "Object";
+			else if (calleeName === "shallowRef") type = "ShallowRef";
+			else if (calleeName === "computed") type = "ComputedRef";
+			else type = "Ref";
+			const docEntry = {
+				name: varName,
+				type,
+				description: jsdoc.description,
+				...jsdoc.deprecated !== void 0 && { deprecated: jsdoc.deprecated },
+				...jsdoc.since && { since: jsdoc.since },
+				...jsdoc.example && { example: jsdoc.example },
+				...jsdoc.see && { see: jsdoc.see }
+			};
+			if (isRef) refs.push(docEntry);
+			else computeds.push(docEntry);
+		}
+	}
+	return {
+		refs,
+		computeds
+	};
+}
 function extractTemplateSlots(templateAst) {
 	const slots = [];
 	walkTemplate(templateAst.children ?? [], slots);
@@ -827,31 +978,110 @@ function walkTemplate(children, slots) {
 function extractOptionsAPI(ast, source) {
 	let props = [];
 	let emits = [];
+	let refs = [];
+	let computeds = [];
 	for (const stmt of ast) {
 		if (stmt.type !== "ExportDefaultDeclaration") continue;
 		const decl = stmt.declaration;
 		if (decl.type !== "ObjectExpression") continue;
 		for (const prop of decl.properties) {
-			if (prop.type !== "ObjectProperty") continue;
+			if (prop.type !== "ObjectProperty" && prop.type !== "ObjectMethod") continue;
 			const key = prop.key;
 			const name = key.type === "Identifier" ? key.name : "";
 			if (name === "props") {
+				if (prop.type !== "ObjectProperty") continue;
 				if (prop.value.type === "ObjectExpression") props = extractProps(prop.value, source);
 				else if (prop.value.type === "ArrayExpression") props = extractArrayProps(prop.value);
 			} else if (name === "emits") {
+				if (prop.type !== "ObjectProperty") continue;
 				if (prop.value.type === "ArrayExpression") {
 					const comments = stmt.leadingComments ?? [];
 					emits = extractEmits(prop.value, comments);
 				} else if (prop.value.type === "ObjectExpression") emits = extractObjectEmits(prop.value);
+			} else if (name === "data") refs = extractOptionsData(prop);
+			else if (name === "computed") {
+				if (prop.type !== "ObjectProperty") continue;
+				if (prop.value.type === "ObjectExpression") computeds = extractOptionsComputed(prop.value);
 			}
 		}
 		break;
 	}
 	return {
 		props,
-		emits
+		emits,
+		refs,
+		computeds
 	};
 }
+function extractOptionsData(prop) {
+	const refs = [];
+	let body = null;
+	if (prop.type === "ObjectMethod") body = prop.body;
+	else if (prop.type === "ObjectProperty") {
+		const val = prop.value;
+		if (val.type === "ArrowFunctionExpression" || val.type === "FunctionExpression") body = val.body;
+	}
+	if (!body) return refs;
+	let returnArg = null;
+	if (body.type === "ObjectExpression") returnArg = body;
+	else if (body.type === "BlockStatement") {
+		for (const s of body.body) if (s.type === "ReturnStatement" && s.argument?.type === "ObjectExpression") {
+			returnArg = s.argument;
+			break;
+		}
+	}
+	if (!returnArg || returnArg.type !== "ObjectExpression") return refs;
+	for (const p of returnArg.properties) {
+		if (p.type !== "ObjectProperty") continue;
+		const name = p.key.type === "Identifier" ? p.key.name : p.key.type === "StringLiteral" ? p.key.value : "";
+		if (!name) continue;
+		const jsdoc = parseJSDocTags(p.leadingComments ?? []);
+		const type = inferLiteralType(p.value) ?? "unknown";
+		refs.push({
+			name,
+			type,
+			description: jsdoc.description,
+			...jsdoc.deprecated !== void 0 && { deprecated: jsdoc.deprecated },
+			...jsdoc.since && { since: jsdoc.since },
+			...jsdoc.example && { example: jsdoc.example },
+			...jsdoc.see && { see: jsdoc.see }
+		});
+	}
+	return refs;
+}
+function extractOptionsComputed(obj) {
+	const computeds = [];
+	for (const prop of obj.properties) {
+		if (prop.type !== "ObjectProperty" && prop.type !== "ObjectMethod") continue;
+		const name = prop.key.type === "Identifier" ? prop.key.name : prop.key.type === "StringLiteral" ? prop.key.value : "";
+		if (!name) continue;
+		const jsdoc = parseJSDocTags(prop.leadingComments ?? []);
+		let type = "unknown";
+		if (prop.type === "ObjectMethod") {
+			if (prop.returnType?.type === "TSTypeAnnotation") type = resolveTypeString(prop.returnType.typeAnnotation);
+		} else if (prop.type === "ObjectProperty") {
+			const val = prop.value;
+			if (val.type === "ObjectExpression") {
+				for (const member of val.properties) if (member.type === "ObjectMethod" && member.key?.type === "Identifier" && member.key.name === "get") {
+					if (member.returnType?.type === "TSTypeAnnotation") type = resolveTypeString(member.returnType.typeAnnotation);
+					break;
+				}
+			} else if (val.type === "ArrowFunctionExpression" || val.type === "FunctionExpression") {
+				if (val.returnType?.type === "TSTypeAnnotation") type = resolveTypeString(val.returnType.typeAnnotation);
+			}
+		}
+		computeds.push({
+			name,
+			type,
+			description: jsdoc.description,
+			...jsdoc.deprecated !== void 0 && { deprecated: jsdoc.deprecated },
+			...jsdoc.since && { since: jsdoc.since },
+			...jsdoc.example && { example: jsdoc.example },
+			...jsdoc.see && { see: jsdoc.see }
+		});
+	}
+	return computeds;
+}
 function extractArrayProps(arr) {
 	const props = [];
 	for (const el of arr.elements) if (el?.type === "StringLiteral") props.push({
@@ -902,15 +1132,53 @@ function generateMarkdown(doc) {
 	const sections = [`# ${doc.name}`];
 	if (doc.description) sections.push("", doc.description);
 	if (doc.scriptSetup) sections.push("", "**Note:** Uses `<script setup>` syntax.");
+	const hasRefs = (doc.refs?.length ?? 0) > 0;
+	const hasComputeds = (doc.computeds?.length ?? 0) > 0;
 	const hasProps = doc.props.length > 0;
 	const hasEmits = doc.emits.length > 0;
 	const hasSlots = (doc.slots?.length ?? 0) > 0;
 	const hasExposes = (doc.exposes?.length ?? 0) > 0;
 	const hasComposables = (doc.composables?.length ?? 0) > 0;
-	if (!hasProps && !hasEmits && !hasSlots && !hasExposes && !hasComposables) {
+	if (!hasProps && !hasEmits && !hasSlots && !hasExposes && !hasComposables && !hasRefs && !hasComputeds) {
 		sections.push("", "No documentable API found.");
 		return sections.join("\n") + "\n";
 	}
+	if (hasRefs) {
+		sections.push("", "## Refs", "");
+		sections.push("| Name | Type | Description |");
+		sections.push("| --- | --- | --- |");
+		const examples = [];
+		for (const r of doc.refs) {
+			let desc = r.description || "-";
+			if (r.deprecated) desc += typeof r.deprecated === "string" && r.deprecated ? ` **Deprecated**: ${r.deprecated}` : " **Deprecated**";
+			if (r.since) desc += ` *(since ${r.since})*`;
+			if (r.see) desc += ` See: ${r.see}`;
+			sections.push(`| ${esc(r.name)} | ${escHtml(esc(r.type))} | ${esc(desc)} |`);
+			if (r.example) examples.push({
+				name: r.name,
+				example: r.example
+			});
+		}
+		for (const { name, example } of examples) sections.push("", `**\`${name}\` example:**`, "", "```", example, "```");
+	}
+	if (hasComputeds) {
+		sections.push("", "## Computed", "");
+		sections.push("| Name | Type | Description |");
+		sections.push("| --- | --- | --- |");
+		const examples = [];
+		for (const c of doc.computeds) {
+			let desc = c.description || "-";
+			if (c.deprecated) desc += typeof c.deprecated === "string" && c.deprecated ? ` **Deprecated**: ${c.deprecated}` : " **Deprecated**";
+			if (c.since) desc += ` *(since ${c.since})*`;
+			if (c.see) desc += ` See: ${c.see}`;
+			sections.push(`| ${esc(c.name)} | ${escHtml(esc(c.type))} | ${esc(desc)} |`);
+			if (c.example) examples.push({
+				name: c.name,
+				example: c.example
+			});
+		}
+		for (const { name, example } of examples) sections.push("", `**\`${name}\` example:**`, "", "```", example, "```");
+	}
 	if (hasProps) {
 		sections.push("", "## Props", "");
 		sections.push("| Name | Type | Required | Default | Description |");
@@ -1041,18 +1309,28 @@ function processFiles(filePaths, options) {
 }
 //#endregion
 //#region src/output.ts
-function writeIndividualMarkdown(results, outDir, silent) {
+function writeIndividualMarkdown(results, outDir, silent, options) {
 	mkdirSync(outDir, { recursive: true });
+	const outputMap = /* @__PURE__ */ new Map();
 	const usedNames = /* @__PURE__ */ new Map();
-	for (const { doc } of results) {
+	for (const { path: sourcePath, doc } of results) {
+		let targetDir = outDir;
+		if (options?.preserveStructure && options.basePath) {
+			targetDir = join(outDir, relative(options.basePath, dirname(sourcePath)));
+			mkdirSync(targetDir, { recursive: true });
+		}
 		const baseName = doc.name;
-		const count = usedNames.get(baseName) ?? 0;
-		usedNames.set(baseName, count + 1);
+		const dedupKey = options?.preserveStructure ? `${targetDir}/${baseName}` : baseName;
+		const count = usedNames.get(dedupKey) ?? 0;
+		usedNames.set(dedupKey, count + 1);
 		const fileName = count === 0 ? baseName : `${baseName}-${count + 1}`;
 		const md = generateMarkdown(doc);
-		writeFileSync(join(outDir, `${fileName}.md`), md, "utf-8");
+		const outPath = join(targetDir, `${fileName}.md`);
+		writeFileSync(outPath, md, "utf-8");
+		outputMap.set(sourcePath, outPath);
 		if (!silent) console.log(`  Created ${fileName}.md`);
 	}
+	return outputMap;
 }
 function writeJoinedMarkdown(results, outDir, silent) {
 	mkdirSync(outDir, { recursive: true });
@@ -1077,8 +1355,9 @@ function writeJoinedMarkdown(results, outDir, silent) {
 	writeFileSync(join(outDir, "components.md"), sections.join("\n") + "\n", "utf-8");
 	if (!silent) console.log(`  Created components.md`);
 }
-function writeJSON(results, outDir, joined, silent) {
+function writeJSON(results, outDir, joined, silent, options) {
 	mkdirSync(outDir, { recursive: true });
+	const outputMap = /* @__PURE__ */ new Map();
 	if (joined) {
 		const data = {
 			generated: (/* @__PURE__ */ new Date()).toISOString(),
@@ -1088,42 +1367,82 @@ function writeJSON(results, outDir, joined, silent) {
 		if (!silent) console.log(`  Created components.json`);
 	} else {
 		const usedNames = /* @__PURE__ */ new Map();
-		for (const { doc } of results) {
+		for (const { path: sourcePath, doc } of results) {
+			let targetDir = outDir;
+			if (options?.preserveStructure && options.basePath) {
+				targetDir = join(outDir, relative(options.basePath, dirname(sourcePath)));
+				mkdirSync(targetDir, { recursive: true });
+			}
 			const baseName = doc.name;
-			const count = usedNames.get(baseName) ?? 0;
-			usedNames.set(baseName, count + 1);
+			const dedupKey = options?.preserveStructure ? `${targetDir}/${baseName}` : baseName;
+			const count = usedNames.get(dedupKey) ?? 0;
+			usedNames.set(dedupKey, count + 1);
 			const fileName = count === 0 ? baseName : `${baseName}-${count + 1}`;
-			writeFileSync(join(outDir, `${fileName}.json`), JSON.stringify(doc, null, 2) + "\n", "utf-8");
+			const outPath = join(targetDir, `${fileName}.json`);
+			writeFileSync(outPath, JSON.stringify(doc, null, 2) + "\n", "utf-8");
+			outputMap.set(sourcePath, outPath);
 			if (!silent) console.log(`  Created ${fileName}.json`);
 		}
 	}
+	return outputMap;
 }
 //#endregion
 //#region src/watcher.ts
-function startWatcher(inputs, ignore, rebuild) {
+function startWatcher(inputs, ignore, rebuildOrOptions) {
+	const options = typeof rebuildOrOptions === "function" ? {
+		rebuild: rebuildOrOptions,
+		isJoined: true
+	} : rebuildOrOptions;
 	const roots = /* @__PURE__ */ new Set();
 	for (const input of inputs) if (input.endsWith(".vue")) roots.add(dirname(resolve(input)));
 	else roots.add(resolve(input));
 	let timer = null;
-	const debounce = () => {
-		if (timer) clearTimeout(timer);
-		timer = setTimeout(() => {
+	const changedFiles = /* @__PURE__ */ new Set();
+	const flush = async () => {
+		if (options.isJoined || !options.incrementalUpdate) {
 			console.log("[watch] Rebuilding...");
 			try {
-				rebuild();
+				await options.rebuild();
 			} catch (err) {
 				const msg = err instanceof Error ? err.message : String(err);
 				console.error(`[watch] Error: ${msg}`);
 			}
 			console.log("[watch] Done.");
+		} else {
+			const files = [...changedFiles];
+			changedFiles.clear();
+			for (const file of files) try {
+				if (existsSync(file)) if (ignore.some((pattern) => file.includes(pattern))) {
+					if (options.removeOutput) options.removeOutput(file);
+					console.log(`[watch] Ignored: ${file.split("/").pop()}`);
+				} else {
+					console.log(`[watch] Updating: ${file.split("/").pop()}`);
+					await options.incrementalUpdate(file);
+				}
+				else {
+					if (options.removeOutput) options.removeOutput(file);
+					console.log(`[watch] Removed: ${file.split("/").pop()}`);
+				}
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				console.error(`[watch] Error processing ${file.split("/").pop()}: ${msg}`);
+			}
+			console.log("[watch] Done.");
+		}
+	};
+	const debounce = (filePath) => {
+		if (filePath) changedFiles.add(filePath);
+		if (timer) clearTimeout(timer);
+		timer = setTimeout(() => {
+			flush();
 		}, 300);
 	};
 	const watchers = [];
 	for (const root of roots) try {
 		const watcher = watch(root, { recursive: true }, (_event, filename) => {
 			if (!filename || !filename.endsWith(".vue")) return;
-			if (ignore.some((pattern) => filename.includes(pattern))) return;
-			debounce();
+			if (ignore.some((pattern) => filename.includes(pattern)) && options.isJoined) return;
+			debounce(join(root, filename));
 		});
 		watchers.push(watcher);
 	} catch {
@@ -1135,15 +1454,27 @@ function startWatcher(inputs, ignore, rebuild) {
 		process.exit(0);
 	});
 }
+function removeOutputFile(outputMap, sourcePath) {
+	const outPath = outputMap.get(sourcePath);
+	if (outPath && existsSync(outPath)) {
+		unlinkSync(outPath);
+		outputMap.delete(sourcePath);
+	}
+}
 //#endregion
 //#region src/cli.ts
 const main = defineCommand({
 	meta: {
 		name: "compmark",
-		version: "0.3.0",
+		version: "0.4.0",
 		description: "Auto-generate Markdown documentation from Vue 3 SFCs"
 	},
 	args: {
+		paths: {
+			type: "positional",
+			description: "Files, directories, or glob patterns",
+			required: true
+		},
 		out: {
 			type: "string",
 			description: "Output directory",
@@ -1169,6 +1500,10 @@ const main = defineCommand({
 		silent: {
 			type: "boolean",
 			description: "Suppress non-error output"
+		},
+		"preserve-structure": {
+			type: "boolean",
+			description: "Preserve input folder structure in output"
 		}
 	},
 	async run({ args }) {
@@ -1187,8 +1522,12 @@ const main = defineCommand({
 		const silent = args.silent ?? false;
 		const joined = args.join ?? false;
 		const outDir = args.out ?? ".";
+		const preserveStructure = args["preserve-structure"] ?? false;
+		let outputMap = /* @__PURE__ */ new Map();
+		let lastBasePath = "";
 		const rebuild = async () => {
-			const filePaths = await discoverFiles(inputPaths, ignorePatterns);
+			const { files: filePaths, ignoredCount, basePath } = await discoverFiles(inputPaths, ignorePatterns);
+			lastBasePath = basePath;
 			if (filePaths.length === 0) {
 				if (!args.watch) {
 					console.error("Error: No .vue files found");
@@ -1198,17 +1537,54 @@ const main = defineCommand({
 				return null;
 			}
 			const summary = processFiles(filePaths, { silent });
-			if (format === "json") writeJSON(summary.files, outDir, joined, silent);
+			const outputOptions = {
+				preserveStructure,
+				basePath
+			};
+			if (format === "json") outputMap = writeJSON(summary.files, outDir, joined, silent, outputOptions);
 			else if (joined) writeJoinedMarkdown(summary.files, outDir, silent);
-			else writeIndividualMarkdown(summary.files, outDir, silent);
-			if (!silent) console.log(`✓ ${summary.documented} components documented, ${summary.skipped} skipped, ${summary.errors} errors`);
+			else outputMap = writeIndividualMarkdown(summary.files, outDir, silent, outputOptions);
+			const totalSkipped = summary.skipped + ignoredCount;
+			if (!silent) console.log(`✓ ${summary.documented} components documented, ${totalSkipped} skipped, ${summary.errors} errors`);
 			return summary;
 		};
 		const summary = await rebuild();
-		if (args.watch) startWatcher(inputPaths, ignorePatterns, () => {
-			rebuild();
-		});
-		else if (summary && summary.errors > 0) process.exit(1);
+		if (args.watch) {
+			const outputOptions = {
+				preserveStructure,
+				basePath: lastBasePath
+			};
+			startWatcher(inputPaths, ignorePatterns, {
+				rebuild: async () => {
+					await rebuild();
+				},
+				incrementalUpdate: (changedFile) => {
+					try {
+						const doc = parseComponent(changedFile);
+						if (doc.internal) {
+							removeOutputFile(outputMap, changedFile);
+							if (!silent) console.log(`  Skipped ${changedFile.split("/").pop()} (marked @internal)`);
+							return;
+						}
+						const result = [{
+							path: changedFile,
+							doc
+						}];
+						let newMap;
+						if (format === "json") newMap = writeJSON(result, outDir, false, silent, outputOptions);
+						else newMap = writeIndividualMarkdown(result, outDir, silent, outputOptions);
+						for (const [k, v] of newMap) outputMap.set(k, v);
+					} catch (err) {
+						const msg = err instanceof Error ? err.message : String(err);
+						if (!silent) console.warn(`  Warning: Could not parse ${changedFile.split("/").pop()}: ${msg}`);
+					}
+				},
+				removeOutput: (changedFile) => {
+					removeOutputFile(outputMap, changedFile);
+				},
+				isJoined: joined
+			});
+		} else if (summary && summary.errors > 0) process.exit(1);
 	}
 });
 function collectInputPaths() {