compmark-vue 0.3.3 → 0.4.0

package/dist/index.d.mts

@@ -34,6 +34,24 @@ interface ComposableDoc {
   source?: string;
   variables: ComposableVariable[];
 }
+interface RefDoc {
+  name: string;
+  type: string;
+  description: string;
+  deprecated?: string | boolean;
+  since?: string;
+  example?: string;
+  see?: string;
+}
+interface ComputedDoc {
+  name: string;
+  type: string;
+  description: string;
+  deprecated?: string | boolean;
+  since?: string;
+  example?: string;
+  see?: string;
+}
 interface ComponentDoc {
   name: string;
   description?: string;
@@ -44,6 +62,8 @@ interface ComponentDoc {
   slots?: SlotDoc[];
   exposes?: ExposeDoc[];
   composables?: ComposableDoc[];
+  refs?: RefDoc[];
+  computeds?: ComputedDoc[];
 }
 type OutputFormat = "md" | "json";
 interface RunSummary {
@@ -59,6 +79,11 @@ interface RunSummary {
     error: string;
   }>;
 }
+interface DiscoveryResult {
+  files: string[];
+  ignoredCount: number;
+  basePath: string;
+}
 //#endregion
 //#region src/parser.d.ts
 declare function parseSFC(source: string, filename: string, sfcDir?: string): ComponentDoc;
@@ -68,7 +93,7 @@ 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[]>;
+declare function discoverFiles(inputs: string[], ignore?: string[]): Promise<DiscoveryResult>;
 //#endregion
 //#region src/runner.d.ts
 declare function processFiles(filePaths: string[], options: {
@@ -83,4 +108,4 @@ declare function resolveImportedPropsType(typeName: string, importMap: Map<strin
 //#region src/index.d.ts
 declare function parseComponent(filePath: string): ComponentDoc;
 //#endregion
-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 };
+export { type ComponentDoc, type ComposableDoc, type ComposableVariable, type ComputedDoc, type DiscoveryResult, type EmitDoc, type ExposeDoc, type OutputFormat, type PropDoc, type RefDoc, type RunSummary, type SlotDoc, adjustHeadingLevel, discoverFiles, generateMarkdown, parseComponent, parseSFC, processFiles, resolveImportedPropsType };

package/dist/index.mjs

@@ -169,15 +169,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";
@@ -390,12 +390,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;
 }
@@ -404,7 +409,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
@@ -419,6 +425,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
@@ -758,6 +771,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);
@@ -787,31 +893,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({
@@ -862,15 +1047,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 |");
@@ -962,17 +1185,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(resolved)) {
+		else if (isDirectory(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,
@@ -981,7 +1231,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(path) {
 	try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compmark-vue",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "Auto-generate Markdown documentation from Vue 3 SFCs",
   "keywords": [
     "compmark",