compmark-vue 0.2.6 → 0.3.1

package/README.md

@@ -9,17 +9,105 @@
 
 Auto-generate Markdown documentation from Vue 3 SFCs. Zero configuration required.
 
+## Installation
+
+```sh
+# npm
+npm install -D compmark-vue
+
+# pnpm
+pnpm add -D compmark-vue
+
+# yarn
+yarn add -D compmark-vue
+```
+
+> Requires Node.js >= 20
+
 ## Quick Start
 
+Document a single component:
+
 ```sh
 npx compmark-vue ./src/components/Button.vue
 ```
 
-This parses the component and creates `Button.md` in your current directory.
+Document an entire directory:
+
+```sh
+npx compmark-vue ./src/components --out ./docs/api
+```
+
+Add to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "docs": "compmark ./src/components --out ./docs/api"
+  }
+}
+```
+
+## CLI
+
+```
+compmark <files/dirs/globs> [options]
+```
+
+| Option                | Description                     | Default |
+| --------------------- | ------------------------------- | ------- |
+| `--out <dir>`         | Output directory                | `.`     |
+| `--format <md\|json>` | Output format                   | `md`    |
+| `--join`              | Combine into a single file      |         |
+| `--ignore <patterns>` | Comma-separated ignore patterns |         |
+| `--watch`             | Watch for changes and rebuild   |         |
+| `--silent`            | Suppress non-error output       |         |
+
+### Examples
+
+```sh
+# Single file
+compmark Button.vue
+
+# Directory (recursive)
+compmark src/components --out docs/api
+
+# Glob pattern
+compmark "src/**/components/*.vue" --out docs
+
+# Monorepo
+compmark "packages/*/src/components" --out docs/api
+
+# Combined markdown with table of contents
+compmark src/components --out docs --join
+
+# JSON output
+compmark src/components --out docs/api --format json
+
+# JSON combined into single file
+compmark src/components --format json --join --out docs
+
+# Ignore patterns
+compmark src/components --ignore "internal,*.test"
+
+# Watch mode
+compmark src/components --out docs --watch
+
+# Multiple inputs
+compmark src/components src/layouts --out docs
+```
+
+The summary line shows what happened:
+
+```
+✓ 24 components documented, 2 skipped, 0 errors
+```
+
+Exit code is `1` when errors occur (except in watch mode).
 
 ## Features
 
-- [Props](#props) — runtime and TypeScript generic syntax
+- [Props](#props) — runtime and TypeScript generic syntax, including imported types
 - [Emits](#emits) — array, TypeScript property, and call signature syntax
 - [Slots](#slots) — `defineSlots` with typed bindings, template `<slot>` fallback
 - [Expose](#expose) — `defineExpose` with JSDoc descriptions
@@ -27,6 +115,7 @@ This parses the component and creates `Button.md` in your current directory.
 - [JSDoc tags](#jsdoc-tags) — `@deprecated`, `@since`, `@example`, `@see`, `@default`
 - [`@internal`](#internal-components) — exclude components from output
 - [Options API](#options-api) — `export default { props, emits }` support
+- [Output formats](#output-formats) — Markdown (individual or joined), JSON
 - Empty sections are skipped cleanly — no placeholder noise
 
 ## Examples
@@ -83,6 +172,29 @@ defineProps({
 </script>
 ```
 
+#### Imported types
+
+`defineProps<ImportedType>()` with exported interfaces or type aliases is supported:
+
+```ts
+// types.ts
+export interface ButtonProps {
+  /** The label text */
+  label: string;
+  disabled?: boolean;
+}
+```
+
+```vue
+<script setup lang="ts">
+import type { ButtonProps } from "./types";
+
+defineProps<ButtonProps>();
+</script>
+```
+
+Interface `extends` is resolved (up to 5 levels deep). `withDefaults` works with imported types too.
+
 ### Emits
 
 TypeScript generic syntax with payloads:
@@ -186,15 +298,18 @@ Output:
 
 ### Composables
 
-Any `useX()` calls in `<script setup>` are automatically detected:
+Any `useX()` calls in `<script setup>` are automatically detected. Variable bindings (simple assignment, object/array destructuring, rest elements) are extracted:
 
 ```vue
 <script setup lang="ts">
 import { useRouter } from "vue-router";
 import { useMouse } from "@vueuse/core";
+import { useAuth } from "./composables/useAuth";
 
 const router = useRouter();
 const { x, y } = useMouse();
+const { user, login, logout } = useAuth();
+useHead({ title: "My App" });
 </script>
 ```
 
@@ -203,10 +318,31 @@ Output:
 ```md
 ## Composables Used
 
-- `useRouter`
-- `useMouse`
+### `useRouter`
+
+**Returns:** `router`
+
+### `useMouse`
+
+**Returns:** `x`, `y`
+
+### `useAuth`
+
+_Source: `./composables/useAuth`_
+
+| Variable | Type                                        |
+| -------- | ------------------------------------------- |
+| user     | Ref<User>                                   |
+| login    | (credentials: Credentials) => Promise<void> |
+| logout   | () => void                                  |
+
+### `useHead`
+
+Called for side effects.
 ```
 
+For local imports (`./` or `@/` paths), types are automatically resolved from the composable source file — `ref()`, `computed()`, `reactive()`, function signatures, and literals are all inferred. Source attribution is shown for local imports only.
+
 ### JSDoc Tags
 
 Props support `@deprecated`, `@since`, `@example`, and `@see`:
@@ -259,7 +395,8 @@ defineProps<{
 
 ```sh
 $ compmark InternalHelper.vue
-Skipped InternalHelper.vue (marked @internal)
+  Skipped InternalHelper.vue (marked @internal)
+✓ 0 components documented, 1 skipped, 0 errors
 ```
 
 ### Options API
@@ -303,6 +440,36 @@ Output:
 | update | -           |
 ```
 
+### Output Formats
+
+**Individual markdown** (default) — one `.md` file per component:
+
+```sh
+compmark src/components --out docs
+# Creates: docs/Button.md, docs/Dialog.md, ...
+```
+
+**Joined markdown** — single file with table of contents:
+
+```sh
+compmark src/components --out docs --join
+# Creates: docs/components.md
+```
+
+The joined file includes a generated timestamp, table of contents with anchor links, and all components with headings bumped one level.
+
+**JSON** — machine-readable output:
+
+```sh
+# Individual JSON files
+compmark src/components --out docs --format json
+# Creates: docs/Button.json, docs/Dialog.json, ...
+
+# Combined JSON
+compmark src/components --format json --join --out docs
+# Creates: docs/components.json with { generated, components: [...] }
+```
+
 ## Programmatic API
 
 ```sh
@@ -325,6 +492,16 @@ const doc = parseSFC(source, "Button.vue");
 const md = generateMarkdown(doc);
 ```
 
+Multi-file processing:
+
+```ts
+import { discoverFiles, processFiles } from "compmark-vue";
+
+const files = await discoverFiles(["src/components"], ["dist"]);
+const summary = processFiles(files, { silent: false });
+// summary.files, summary.documented, summary.skipped, summary.errors
+```
+
 ## Development
 
 <details>
@@ -332,7 +509,7 @@ const md = generateMarkdown(doc);
 <summary>local development</summary>
 
 - Clone this repository
-- Install latest LTS version of [Node.js](https://nodejs.org/en/)
+- Install latest LTS version of [Node.js](https://nodejs.org/en/) (>= 20)
 - Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable`
 - Install dependencies using `pnpm install`
 - Run interactive tests using `pnpm dev`

package/dist/cli.mjs

@@ -1,7 +1,47 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { defineCommand, runMain } from "citty";
+import { existsSync, mkdirSync, readFileSync, statSync, watch, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { glob } from "tinyglobby";
 import { babelParse, compileScript, parse } from "@vue/compiler-sfc";
+//#region src/discovery.ts
+async function discoverFiles(inputs, ignore) {
+	const baseIgnore = ["**/node_modules/**"];
+	const userIgnore = (ignore ?? []).map(normalizeIgnorePattern);
+	const allIgnore = [...baseIgnore, ...userIgnore];
+	const found = /* @__PURE__ */ new Set();
+	for (const input of inputs) {
+		const resolved = resolve(input);
+		if (input.endsWith(".vue") && existsSync(resolved)) found.add(resolved);
+		else if (isDirectory$1(resolved)) {
+			const files = await glob("**/*.vue", {
+				cwd: resolved,
+				absolute: true,
+				ignore: allIgnore
+			});
+			for (const f of files) found.add(f);
+		} else {
+			const files = await glob(input, {
+				absolute: true,
+				ignore: allIgnore
+			});
+			for (const f of files) found.add(f);
+		}
+	}
+	return [...found].sort();
+}
+function isDirectory$1(path) {
+	try {
+		return statSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+}
+function normalizeIgnorePattern(pattern) {
+	if (pattern.includes("*") || pattern.includes("/")) return pattern;
+	return `**/${pattern}/**`;
+}
+//#endregion
 //#region src/resolver.ts
 function resolveImportPath(importSource, sfcDir) {
 	try {
@@ -265,6 +305,56 @@ function resolveTypeAnnotation(node) {
 	}
 }
 //#endregion
+//#region src/type-resolver.ts
+function resolveImportedPropsType(typeName, importMap, sfcDir) {
+	const source = importMap.get(typeName);
+	if (!source) return null;
+	const resolvedPath = resolveImportPath(source, sfcDir);
+	if (!resolvedPath) return null;
+	try {
+		return findExportedType(babelParse(readFileSync(resolvedPath, "utf-8"), {
+			plugins: ["typescript"],
+			sourceType: "module"
+		}).program.body, typeName, 0);
+	} catch {
+		return null;
+	}
+}
+function findExportedType(stmts, typeName, depth) {
+	if (depth > 5) return null;
+	for (const stmt of stmts) {
+		if (stmt.type === "ExportNamedDeclaration" && stmt.declaration?.type === "TSInterfaceDeclaration" && stmt.declaration.id.name === typeName) return resolveInterfaceMembers(stmt.declaration, stmts, depth);
+		if (stmt.type === "ExportNamedDeclaration" && stmt.declaration?.type === "TSTypeAliasDeclaration" && stmt.declaration.id.name === typeName && stmt.declaration.typeAnnotation.type === "TSTypeLiteral") return { members: [...stmt.declaration.typeAnnotation.members] };
+	}
+	if (hasNamedExport(stmts, typeName)) return findTypeInFile(stmts, typeName, depth);
+	return null;
+}
+function findTypeInFile(stmts, typeName, depth) {
+	if (depth > 5) return null;
+	for (const stmt of stmts) {
+		if (stmt.type === "ExportNamedDeclaration" && stmt.declaration?.type === "TSInterfaceDeclaration" && stmt.declaration.id.name === typeName) return resolveInterfaceMembers(stmt.declaration, stmts, depth);
+		if (stmt.type === "ExportNamedDeclaration" && stmt.declaration?.type === "TSTypeAliasDeclaration" && stmt.declaration.id.name === typeName && stmt.declaration.typeAnnotation.type === "TSTypeLiteral") return { members: [...stmt.declaration.typeAnnotation.members] };
+		if (stmt.type === "TSInterfaceDeclaration" && stmt.id.name === typeName) return resolveInterfaceMembers(stmt, stmts, depth);
+		if (stmt.type === "TSTypeAliasDeclaration" && stmt.id.name === typeName && stmt.typeAnnotation.type === "TSTypeLiteral") return { members: [...stmt.typeAnnotation.members] };
+	}
+	return null;
+}
+function resolveInterfaceMembers(decl, stmts, depth) {
+	const members = [];
+	if (decl.extends) for (const ext of decl.extends) {
+		const parentName = ext.expression?.type === "Identifier" ? ext.expression.name : null;
+		if (parentName) {
+			const parent = findTypeInFile(stmts, parentName, depth + 1);
+			if (parent) members.push(...parent.members);
+		}
+	}
+	members.push(...decl.body.body);
+	return { members };
+}
+function hasNamedExport(stmts, name) {
+	return stmts.some((s) => s.type === "ExportNamedDeclaration" && !s.declaration && s.specifiers.some((spec) => spec.type === "ExportSpecifier" && (spec.local.type === "Identifier" && spec.local.name === name || spec.exported.type === "Identifier" && spec.exported.name === name)));
+}
+//#endregion
 //#region src/parser.ts
 function parseJSDocTags(comments) {
 	const result = { description: "" };
@@ -291,29 +381,55 @@ function parseSFC(source, filename, sfcDir) {
 		props: [],
 		emits: []
 	};
-	const { descriptor } = parse(source, { filename });
+	const fullPath = sfcDir ? `${sfcDir}/${filename}` : filename;
+	const { descriptor } = parse(source, { filename: fullPath });
+	doc.scriptSetup = !!descriptor.scriptSetup;
 	if (descriptor.template?.ast) {
 		const templateSlots = extractTemplateSlots(descriptor.template.ast);
 		if (templateSlots.length > 0) doc.slots = templateSlots;
 	}
 	if (!descriptor.scriptSetup && !descriptor.script) return doc;
-	const compiled = compileScript(descriptor, { id: filename });
+	let compiled;
+	try {
+		compiled = compileScript(descriptor, {
+			id: fullPath,
+			fs: {
+				fileExists: (file) => existsSync(file),
+				readFile: (file) => {
+					try {
+						return readFileSync(file, "utf-8");
+					} catch {
+						return;
+					}
+				}
+			}
+		});
+	} catch {
+		return doc;
+	}
 	const componentJSDoc = extractComponentJSDoc(compiled.scriptSetupAst ?? compiled.scriptAst ?? []);
 	doc.description = componentJSDoc.description;
 	doc.internal = componentJSDoc.internal;
 	const setupAst = compiled.scriptSetupAst;
 	if (setupAst) {
 		const scriptSource = descriptor.scriptSetup?.content ?? compiled.content;
+		const importMap = buildImportMap(setupAst);
 		for (const stmt of setupAst) {
 			const calls = extractDefineCalls(stmt);
 			for (const { callee, args, leadingComments, typeParams, defaultsArg } of calls) if (callee === "defineProps" && args[0]?.type === "ObjectExpression") doc.props = extractProps(args[0], scriptSource);
 			else if (callee === "defineProps" && typeParams?.params[0]?.type === "TSTypeLiteral") doc.props = extractTypeProps(typeParams.params[0], defaultsArg, scriptSource);
-			else if (callee === "defineEmits" && args[0]?.type === "ArrayExpression") doc.emits = extractEmits(args[0], leadingComments);
+			else if (callee === "defineProps" && typeParams?.params[0]?.type === "TSTypeReference") {
+				const typeName = typeParams.params[0].typeName?.name;
+				if (typeName && sfcDir) {
+					const resolved = resolveImportedPropsType(typeName, importMap, sfcDir);
+					if (resolved) doc.props = extractTypeProps(resolved, defaultsArg, scriptSource);
+				}
+			} else if (callee === "defineEmits" && args[0]?.type === "ArrayExpression") doc.emits = extractEmits(args[0], leadingComments);
 			else if (callee === "defineEmits" && typeParams?.params[0]?.type === "TSTypeLiteral") doc.emits = extractTypeEmits(typeParams.params[0]);
 			else if (callee === "defineSlots" && typeParams?.params[0]?.type === "TSTypeLiteral") doc.slots = extractTypeSlots(typeParams.params[0]);
 			else if (callee === "defineExpose" && args[0]?.type === "ObjectExpression") doc.exposes = extractExposes(args[0], scriptSource);
 		}
-		doc.composables = extractComposables(setupAst, buildImportMap(setupAst), sfcDir);
+		doc.composables = extractComposables(setupAst, importMap, sfcDir);
 	}
 	const scriptAst = compiled.scriptAst;
 	if (scriptAst && doc.props.length === 0 && doc.emits.length === 0) {
@@ -785,6 +901,7 @@ function escHtml(value) {
 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 hasProps = doc.props.length > 0;
 	const hasEmits = doc.emits.length > 0;
 	const hasSlots = (doc.slots?.length ?? 0) > 0;
@@ -873,6 +990,12 @@ function generateMarkdown(doc) {
 	}
 	return sections.join("\n") + "\n";
 }
+function adjustHeadingLevel(md, increment) {
+	return md.replace(/^(#{1,6})\s/gm, (_, hashes) => {
+		const newLevel = Math.min(hashes.length + increment, 6);
+		return "#".repeat(newLevel) + " ";
+	});
+}
 //#endregion
 //#region src/index.ts
 function parseComponent(filePath) {
@@ -880,37 +1003,239 @@ function parseComponent(filePath) {
 	return parseSFC(readFileSync(abs, "utf-8"), abs.split("/").pop() ?? "Unknown.vue", abs.substring(0, abs.lastIndexOf("/")));
 }
 //#endregion
-//#region src/cli.ts
-const filePath = process.argv[2];
-if (!filePath) {
-	console.error("Usage: compmark <path-to-component.vue>");
-	process.exit(1);
-}
-if (!filePath.endsWith(".vue")) {
-	console.error(`Error: Expected a .vue file, got: ${filePath}`);
-	process.exit(1);
-}
-const abs = resolve(filePath);
-if (!existsSync(abs)) {
-	console.error(`Error: File not found: ${filePath}`);
-	process.exit(1);
-}
-try {
-	const doc = parseComponent(abs);
-	if (doc.internal) {
-		const name = abs.split("/").pop() ?? filePath;
-		console.log(`Skipped ${name} (marked @internal)`);
+//#region src/runner.ts
+function processFiles(filePaths, options) {
+	const summary = {
+		documented: 0,
+		skipped: 0,
+		errors: 0,
+		files: [],
+		errorDetails: []
+	};
+	for (const filePath of filePaths) try {
+		const doc = parseComponent(filePath);
+		if (doc.internal) {
+			summary.skipped++;
+			if (!options.silent) {
+				const name = filePath.split("/").pop() ?? filePath;
+				console.log(`  Skipped ${name} (marked @internal)`);
+			}
+			continue;
+		}
+		summary.documented++;
+		summary.files.push({
+			path: filePath,
+			doc
+		});
+	} catch (err) {
+		summary.errors++;
+		const name = filePath.split("/").pop() ?? filePath;
+		const message = err instanceof Error ? err.message : String(err);
+		summary.errorDetails.push({
+			path: filePath,
+			error: message
+		});
+		if (!options.silent) console.warn(`  Warning: Could not parse ${name}: ${message}`);
+	}
+	return summary;
+}
+//#endregion
+//#region src/output.ts
+function writeIndividualMarkdown(results, outDir, silent) {
+	mkdirSync(outDir, { recursive: true });
+	const usedNames = /* @__PURE__ */ new Map();
+	for (const { doc } of results) {
+		const baseName = doc.name;
+		const count = usedNames.get(baseName) ?? 0;
+		usedNames.set(baseName, count + 1);
+		const fileName = count === 0 ? baseName : `${baseName}-${count + 1}`;
+		const md = generateMarkdown(doc);
+		writeFileSync(join(outDir, `${fileName}.md`), md, "utf-8");
+		if (!silent) console.log(`  Created ${fileName}.md`);
+	}
+}
+function writeJoinedMarkdown(results, outDir, silent) {
+	mkdirSync(outDir, { recursive: true });
+	const sections = [];
+	sections.push("# Component Documentation");
+	sections.push("");
+	sections.push(`*Generated: ${(/* @__PURE__ */ new Date()).toISOString()}*`);
+	sections.push("");
+	sections.push("## Table of Contents");
+	sections.push("");
+	for (const { doc } of results) {
+		const anchor = doc.name.toLowerCase().replace(/[^a-z0-9-]/g, "-");
+		sections.push(`- [${doc.name}](#${anchor})`);
+	}
+	for (const { doc } of results) {
+		const adjusted = adjustHeadingLevel(generateMarkdown(doc), 1);
+		sections.push("");
+		sections.push("---");
+		sections.push("");
+		sections.push(adjusted.trimEnd());
+	}
+	writeFileSync(join(outDir, "components.md"), sections.join("\n") + "\n", "utf-8");
+	if (!silent) console.log(`  Created components.md`);
+}
+function writeJSON(results, outDir, joined, silent) {
+	mkdirSync(outDir, { recursive: true });
+	if (joined) {
+		const data = {
+			generated: (/* @__PURE__ */ new Date()).toISOString(),
+			components: results.map((r) => r.doc)
+		};
+		writeFileSync(join(outDir, "components.json"), JSON.stringify(data, null, 2) + "\n", "utf-8");
+		if (!silent) console.log(`  Created components.json`);
+	} else {
+		const usedNames = /* @__PURE__ */ new Map();
+		for (const { doc } of results) {
+			const baseName = doc.name;
+			const count = usedNames.get(baseName) ?? 0;
+			usedNames.set(baseName, count + 1);
+			const fileName = count === 0 ? baseName : `${baseName}-${count + 1}`;
+			writeFileSync(join(outDir, `${fileName}.json`), JSON.stringify(doc, null, 2) + "\n", "utf-8");
+			if (!silent) console.log(`  Created ${fileName}.json`);
+		}
+	}
+}
+//#endregion
+//#region src/watcher.ts
+function startWatcher(inputs, ignore, rebuild) {
+	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(() => {
+			console.log("[watch] Rebuilding...");
+			try {
+				rebuild();
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				console.error(`[watch] Error: ${msg}`);
+			}
+			console.log("[watch] Done.");
+		}, 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();
+		});
+		watchers.push(watcher);
+	} catch {
+		console.warn(`[watch] Could not watch: ${root}`);
+	}
+	console.log(`[watch] Watching ${roots.size} root(s) for changes...`);
+	process.on("SIGINT", () => {
+		for (const w of watchers) w.close();
 		process.exit(0);
+	});
+}
+//#endregion
+//#region src/cli.ts
+const main = defineCommand({
+	meta: {
+		name: "compmark",
+		version: "0.3.0",
+		description: "Auto-generate Markdown documentation from Vue 3 SFCs"
+	},
+	args: {
+		out: {
+			type: "string",
+			description: "Output directory",
+			default: "."
+		},
+		ignore: {
+			type: "string",
+			description: "Comma-separated ignore patterns"
+		},
+		join: {
+			type: "boolean",
+			description: "Combine output into a single file"
+		},
+		format: {
+			type: "string",
+			description: "Output format: md | json",
+			default: "md"
+		},
+		watch: {
+			type: "boolean",
+			description: "Watch for changes and rebuild"
+		},
+		silent: {
+			type: "boolean",
+			description: "Suppress non-error output"
+		}
+	},
+	async run({ args }) {
+		const inputPaths = collectInputPaths();
+		if (inputPaths.length === 0) {
+			console.error("Error: No input files or directories specified");
+			console.error("Usage: compmark <files/dirs/globs> [options]");
+			process.exit(1);
+		}
+		const format = args.format;
+		if (format !== "md" && format !== "json") {
+			console.error(`Error: Unknown format "${format}". Use "md" or "json".`);
+			process.exit(1);
+		}
+		const ignorePatterns = args.ignore ? args.ignore.split(",").map((s) => s.trim()).filter(Boolean) : [];
+		const silent = args.silent ?? false;
+		const joined = args.join ?? false;
+		const outDir = args.out ?? ".";
+		const rebuild = async () => {
+			const filePaths = await discoverFiles(inputPaths, ignorePatterns);
+			if (filePaths.length === 0) {
+				if (!args.watch) {
+					console.error("Error: No .vue files found");
+					process.exit(1);
+				}
+				console.warn("Warning: No .vue files found");
+				return null;
+			}
+			const summary = processFiles(filePaths, { silent });
+			if (format === "json") writeJSON(summary.files, outDir, joined, silent);
+			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`);
+			return summary;
+		};
+		const summary = await rebuild();
+		if (args.watch) startWatcher(inputPaths, ignorePatterns, () => {
+			rebuild();
+		});
+		else if (summary && summary.errors > 0) process.exit(1);
+	}
+});
+function collectInputPaths() {
+	const argv = process.argv.slice(2);
+	const paths = [];
+	const flagsWithValue = new Set([
+		"--out",
+		"--ignore",
+		"--format"
+	]);
+	let i = 0;
+	while (i < argv.length) {
+		const arg = argv[i];
+		if (arg === "--") {
+			paths.push(...argv.slice(i + 1));
+			break;
+		}
+		if (flagsWithValue.has(arg)) i += 2;
+		else if (arg.startsWith("--") && arg.includes("=")) i++;
+		else if (arg.startsWith("--")) i++;
+		else {
+			paths.push(arg);
+			i++;
+		}
 	}
-	const md = generateMarkdown(doc);
-	const outFile = `${doc.name}.md`;
-	writeFileSync(join(process.cwd(), outFile), md, "utf-8");
-	console.log(`Created ${outFile}`);
-} catch (err) {
-	const name = abs.split("/").pop() ?? filePath;
-	const reason = err instanceof Error ? err.message : String(err);
-	console.error(`Error: Could not parse ${name}: ${reason}`);
-	process.exit(1);
+	return paths;
 }
+runMain(main);
 //#endregion
 export {};

package/dist/index.d.mts

@@ -38,20 +38,49 @@ interface ComponentDoc {
   name: string;
   description?: string;
   internal?: boolean;
+  scriptSetup?: boolean;
   props: PropDoc[];
   emits: EmitDoc[];
   slots?: SlotDoc[];
   exposes?: ExposeDoc[];
   composables?: ComposableDoc[];
 }
+type OutputFormat = "md" | "json";
+interface RunSummary {
+  documented: number;
+  skipped: number;
+  errors: number;
+  files: Array<{
+    path: string;
+    doc: ComponentDoc;
+  }>;
+  errorDetails: Array<{
+    path: string;
+    error: string;
+  }>;
+}
 //#endregion
 //#region src/parser.d.ts
 declare function parseSFC(source: string, filename: string, sfcDir?: string): ComponentDoc;
 //#endregion
 //#region src/markdown.d.ts
 declare function generateMarkdown(doc: ComponentDoc): string;
+declare function adjustHeadingLevel(md: string, increment: number): string;
+//#endregion
+//#region src/discovery.d.ts
+declare function discoverFiles(inputs: string[], ignore?: string[]): Promise<string[]>;
+//#endregion
+//#region src/runner.d.ts
+declare function processFiles(filePaths: string[], options: {
+  silent?: boolean;
+}): RunSummary;
+//#endregion
+//#region src/type-resolver.d.ts
+declare function resolveImportedPropsType(typeName: string, importMap: Map<string, string>, sfcDir: string): {
+  members: Array<any>;
+} | null;
 //#endregion
 //#region src/index.d.ts
 declare function parseComponent(filePath: string): ComponentDoc;
 //#endregion
-export { type ComponentDoc, type ComposableDoc, type ComposableVariable, type EmitDoc, type ExposeDoc, type PropDoc, type SlotDoc, generateMarkdown, parseComponent, parseSFC };
+export { type ComponentDoc, type ComposableDoc, type ComposableVariable, type EmitDoc, type ExposeDoc, type OutputFormat, type PropDoc, type RunSummary, type SlotDoc, adjustHeadingLevel, discoverFiles, generateMarkdown, parseComponent, parseSFC, processFiles, resolveImportedPropsType };

package/dist/index.mjs

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { babelParse, compileScript, parse } from "@vue/compiler-sfc";
+import { glob } from "tinyglobby";
 //#region src/resolver.ts
 function resolveImportPath(importSource, sfcDir) {
 	try {
@@ -27,7 +28,7 @@ function resolveImportPath(importSource, sfcDir) {
 	}
 }
 function tryResolveFile(basePath) {
-	if (existsSync(basePath) && !isDirectory(basePath)) return basePath;
+	if (existsSync(basePath) && !isDirectory$1(basePath)) return basePath;
 	for (const ext of [".ts", ".js"]) {
 		const candidate = basePath + ext;
 		if (existsSync(candidate)) return candidate;
@@ -38,7 +39,7 @@ function tryResolveFile(basePath) {
 	}
 	return null;
 }
-function isDirectory(filePath) {
+function isDirectory$1(filePath) {
 	try {
 		return statSync(filePath).isDirectory();
 	} catch {
@@ -264,6 +265,56 @@ function resolveTypeAnnotation(node) {
 	}
 }
 //#endregion
+//#region src/type-resolver.ts
+function resolveImportedPropsType(typeName, importMap, sfcDir) {
+	const source = importMap.get(typeName);
+	if (!source) return null;
+	const resolvedPath = resolveImportPath(source, sfcDir);
+	if (!resolvedPath) return null;
+	try {
+		return findExportedType(babelParse(readFileSync(resolvedPath, "utf-8"), {
+			plugins: ["typescript"],
+			sourceType: "module"
+		}).program.body, typeName, 0);
+	} catch {
+		return null;
+	}
+}
+function findExportedType(stmts, typeName, depth) {
+	if (depth > 5) return null;
+	for (const stmt of stmts) {
+		if (stmt.type === "ExportNamedDeclaration" && stmt.declaration?.type === "TSInterfaceDeclaration" && stmt.declaration.id.name === typeName) return resolveInterfaceMembers(stmt.declaration, stmts, depth);
+		if (stmt.type === "ExportNamedDeclaration" && stmt.declaration?.type === "TSTypeAliasDeclaration" && stmt.declaration.id.name === typeName && stmt.declaration.typeAnnotation.type === "TSTypeLiteral") return { members: [...stmt.declaration.typeAnnotation.members] };
+	}
+	if (hasNamedExport(stmts, typeName)) return findTypeInFile(stmts, typeName, depth);
+	return null;
+}
+function findTypeInFile(stmts, typeName, depth) {
+	if (depth > 5) return null;
+	for (const stmt of stmts) {
+		if (stmt.type === "ExportNamedDeclaration" && stmt.declaration?.type === "TSInterfaceDeclaration" && stmt.declaration.id.name === typeName) return resolveInterfaceMembers(stmt.declaration, stmts, depth);
+		if (stmt.type === "ExportNamedDeclaration" && stmt.declaration?.type === "TSTypeAliasDeclaration" && stmt.declaration.id.name === typeName && stmt.declaration.typeAnnotation.type === "TSTypeLiteral") return { members: [...stmt.declaration.typeAnnotation.members] };
+		if (stmt.type === "TSInterfaceDeclaration" && stmt.id.name === typeName) return resolveInterfaceMembers(stmt, stmts, depth);
+		if (stmt.type === "TSTypeAliasDeclaration" && stmt.id.name === typeName && stmt.typeAnnotation.type === "TSTypeLiteral") return { members: [...stmt.typeAnnotation.members] };
+	}
+	return null;
+}
+function resolveInterfaceMembers(decl, stmts, depth) {
+	const members = [];
+	if (decl.extends) for (const ext of decl.extends) {
+		const parentName = ext.expression?.type === "Identifier" ? ext.expression.name : null;
+		if (parentName) {
+			const parent = findTypeInFile(stmts, parentName, depth + 1);
+			if (parent) members.push(...parent.members);
+		}
+	}
+	members.push(...decl.body.body);
+	return { members };
+}
+function hasNamedExport(stmts, name) {
+	return stmts.some((s) => s.type === "ExportNamedDeclaration" && !s.declaration && s.specifiers.some((spec) => spec.type === "ExportSpecifier" && (spec.local.type === "Identifier" && spec.local.name === name || spec.exported.type === "Identifier" && spec.exported.name === name)));
+}
+//#endregion
 //#region src/parser.ts
 function parseJSDocTags(comments) {
 	const result = { description: "" };
@@ -290,29 +341,55 @@ function parseSFC(source, filename, sfcDir) {
 		props: [],
 		emits: []
 	};
-	const { descriptor } = parse(source, { filename });
+	const fullPath = sfcDir ? `${sfcDir}/${filename}` : filename;
+	const { descriptor } = parse(source, { filename: fullPath });
+	doc.scriptSetup = !!descriptor.scriptSetup;
 	if (descriptor.template?.ast) {
 		const templateSlots = extractTemplateSlots(descriptor.template.ast);
 		if (templateSlots.length > 0) doc.slots = templateSlots;
 	}
 	if (!descriptor.scriptSetup && !descriptor.script) return doc;
-	const compiled = compileScript(descriptor, { id: filename });
+	let compiled;
+	try {
+		compiled = compileScript(descriptor, {
+			id: fullPath,
+			fs: {
+				fileExists: (file) => existsSync(file),
+				readFile: (file) => {
+					try {
+						return readFileSync(file, "utf-8");
+					} catch {
+						return;
+					}
+				}
+			}
+		});
+	} catch {
+		return doc;
+	}
 	const componentJSDoc = extractComponentJSDoc(compiled.scriptSetupAst ?? compiled.scriptAst ?? []);
 	doc.description = componentJSDoc.description;
 	doc.internal = componentJSDoc.internal;
 	const setupAst = compiled.scriptSetupAst;
 	if (setupAst) {
 		const scriptSource = descriptor.scriptSetup?.content ?? compiled.content;
+		const importMap = buildImportMap(setupAst);
 		for (const stmt of setupAst) {
 			const calls = extractDefineCalls(stmt);
 			for (const { callee, args, leadingComments, typeParams, defaultsArg } of calls) if (callee === "defineProps" && args[0]?.type === "ObjectExpression") doc.props = extractProps(args[0], scriptSource);
 			else if (callee === "defineProps" && typeParams?.params[0]?.type === "TSTypeLiteral") doc.props = extractTypeProps(typeParams.params[0], defaultsArg, scriptSource);
-			else if (callee === "defineEmits" && args[0]?.type === "ArrayExpression") doc.emits = extractEmits(args[0], leadingComments);
+			else if (callee === "defineProps" && typeParams?.params[0]?.type === "TSTypeReference") {
+				const typeName = typeParams.params[0].typeName?.name;
+				if (typeName && sfcDir) {
+					const resolved = resolveImportedPropsType(typeName, importMap, sfcDir);
+					if (resolved) doc.props = extractTypeProps(resolved, defaultsArg, scriptSource);
+				}
+			} else if (callee === "defineEmits" && args[0]?.type === "ArrayExpression") doc.emits = extractEmits(args[0], leadingComments);
 			else if (callee === "defineEmits" && typeParams?.params[0]?.type === "TSTypeLiteral") doc.emits = extractTypeEmits(typeParams.params[0]);
 			else if (callee === "defineSlots" && typeParams?.params[0]?.type === "TSTypeLiteral") doc.slots = extractTypeSlots(typeParams.params[0]);
 			else if (callee === "defineExpose" && args[0]?.type === "ObjectExpression") doc.exposes = extractExposes(args[0], scriptSource);
 		}
-		doc.composables = extractComposables(setupAst, buildImportMap(setupAst), sfcDir);
+		doc.composables = extractComposables(setupAst, importMap, sfcDir);
 	}
 	const scriptAst = compiled.scriptAst;
 	if (scriptAst && doc.props.length === 0 && doc.emits.length === 0) {
@@ -784,6 +861,7 @@ function escHtml(value) {
 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 hasProps = doc.props.length > 0;
 	const hasEmits = doc.emits.length > 0;
 	const hasSlots = (doc.slots?.length ?? 0) > 0;
@@ -872,6 +950,87 @@ function generateMarkdown(doc) {
 	}
 	return sections.join("\n") + "\n";
 }
+function adjustHeadingLevel(md, increment) {
+	return md.replace(/^(#{1,6})\s/gm, (_, hashes) => {
+		const newLevel = Math.min(hashes.length + increment, 6);
+		return "#".repeat(newLevel) + " ";
+	});
+}
+//#endregion
+//#region src/discovery.ts
+async function discoverFiles(inputs, ignore) {
+	const baseIgnore = ["**/node_modules/**"];
+	const userIgnore = (ignore ?? []).map(normalizeIgnorePattern);
+	const allIgnore = [...baseIgnore, ...userIgnore];
+	const found = /* @__PURE__ */ new Set();
+	for (const input of inputs) {
+		const resolved = resolve(input);
+		if (input.endsWith(".vue") && existsSync(resolved)) found.add(resolved);
+		else if (isDirectory(resolved)) {
+			const files = await glob("**/*.vue", {
+				cwd: resolved,
+				absolute: true,
+				ignore: allIgnore
+			});
+			for (const f of files) found.add(f);
+		} else {
+			const files = await glob(input, {
+				absolute: true,
+				ignore: allIgnore
+			});
+			for (const f of files) found.add(f);
+		}
+	}
+	return [...found].sort();
+}
+function isDirectory(path) {
+	try {
+		return statSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+}
+function normalizeIgnorePattern(pattern) {
+	if (pattern.includes("*") || pattern.includes("/")) return pattern;
+	return `**/${pattern}/**`;
+}
+//#endregion
+//#region src/runner.ts
+function processFiles(filePaths, options) {
+	const summary = {
+		documented: 0,
+		skipped: 0,
+		errors: 0,
+		files: [],
+		errorDetails: []
+	};
+	for (const filePath of filePaths) try {
+		const doc = parseComponent(filePath);
+		if (doc.internal) {
+			summary.skipped++;
+			if (!options.silent) {
+				const name = filePath.split("/").pop() ?? filePath;
+				console.log(`  Skipped ${name} (marked @internal)`);
+			}
+			continue;
+		}
+		summary.documented++;
+		summary.files.push({
+			path: filePath,
+			doc
+		});
+	} catch (err) {
+		summary.errors++;
+		const name = filePath.split("/").pop() ?? filePath;
+		const message = err instanceof Error ? err.message : String(err);
+		summary.errorDetails.push({
+			path: filePath,
+			error: message
+		});
+		if (!options.silent) console.warn(`  Warning: Could not parse ${name}: ${message}`);
+	}
+	return summary;
+}
 //#endregion
 //#region src/index.ts
 function parseComponent(filePath) {
@@ -879,4 +1038,4 @@ function parseComponent(filePath) {
 	return parseSFC(readFileSync(abs, "utf-8"), abs.split("/").pop() ?? "Unknown.vue", abs.substring(0, abs.lastIndexOf("/")));
 }
 //#endregion
-export { generateMarkdown, parseComponent, parseSFC };
+export { adjustHeadingLevel, discoverFiles, generateMarkdown, parseComponent, parseSFC, processFiles, resolveImportedPropsType };

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "compmark-vue",
-  "version": "0.2.6",
+  "version": "0.3.1",
   "description": "Auto-generate Markdown documentation from Vue 3 SFCs",
   "license": "MIT",
   "repository": "noopurphalak/compmark-vue",
   "bin": {
-    "compmark": "./dist/cli.mjs"
+    "compmark": "./dist/cli.mjs",
+    "compmark-vue": "./dist/cli.mjs"
   },
   "files": [
     "dist"
@@ -28,7 +29,9 @@
     "prepare": "husky"
   },
   "dependencies": {
-    "@vue/compiler-sfc": "^3.5.0"
+    "@vue/compiler-sfc": "^3.5.0",
+    "citty": "^0.2.1",
+    "tinyglobby": "^0.2.15"
   },
   "devDependencies": {
     "@babel/types": "latest",
@@ -51,5 +54,8 @@
       "oxfmt"
     ]
   },
+  "engines": {
+    "node": ">=20"
+  },
   "packageManager": "pnpm@10.29.3"
 }