compmark-vue 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# vuemark
+
+<!-- automd:badges color=yellow -->
+
+[![npm version](https://img.shields.io/npm/v/compmark-vue?color=yellow)](https://npmjs.com/package/compmark-vue)
+[![npm downloads](https://img.shields.io/npm/dm/compmark-vue?color=yellow)](https://npm.chart.dev/compmark-vue)
+
+<!-- /automd -->
+
+Auto-generate Markdown documentation from Vue 3 SFCs. Zero configuration required.
+
+## Quick Start
+
+```sh
+npx compmark-vue ./src/components/Button.vue
+```
+
+This parses the component and creates `Button.md` in your current directory.
+
+### Example Output
+
+Given a component like:
+
+```vue
+<script setup>
+/**
+ * @emit submit Emitted on form submit
+ * @emit cancel Emitted on cancel
+ */
+const emit = defineEmits(["submit", "cancel"]);
+
+const props = defineProps({
+  /** Title of the dialog */
+  title: {
+    type: String,
+    required: true,
+  },
+  /** Whether the dialog is visible */
+  visible: {
+    type: Boolean,
+    default: false,
+  },
+});
+</script>
+```
+
+vuemark generates:
+
+```md
+# Dialog
+
+## Props
+
+| Name    | Type    | Required | Default | Description                   |
+| ------- | ------- | -------- | ------- | ----------------------------- |
+| title   | String  | Yes      | -       | Title of the dialog           |
+| visible | Boolean | No       | `false` | Whether the dialog is visible |
+
+## Emits
+
+| Name   | Description            |
+| ------ | ---------------------- |
+| submit | Emitted on form submit |
+| cancel | Emitted on cancel      |
+```
+
+## Programmatic API
+
+```sh
+pnpm install compmark-vue
+```
+
+```ts
+import { parseComponent, generateMarkdown } from "compmark-vue";
+
+const doc = parseComponent("./src/components/Button.vue");
+const md = generateMarkdown(doc);
+```
+
+Or parse from a string:
+
+```ts
+import { parseSFC, generateMarkdown } from "compmark-vue";
+
+const doc = parseSFC(source, "Button.vue");
+const md = generateMarkdown(doc);
+```
+
+## Supported Syntax
+
+- `defineProps({ ... })` — shorthand (`String`), array type (`[String, Number]`), and full object syntax
+- `defineEmits([...])` — array syntax
+- JSDoc comments on props and emits (`/** ... */`)
+- `const props = defineProps(...)` variable assignment pattern
+- Default value extraction (string, number, boolean literals, arrow functions)
+
+## Development
+
+<details>
+
+<summary>local development</summary>
+
+- Clone this repository
+- Install latest LTS version of [Node.js](https://nodejs.org/en/)
+- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable`
+- Install dependencies using `pnpm install`
+- Run interactive tests using `pnpm dev`
+
+</details>
+
+## License
+
+Published under the [MIT](https://github.com/noopurphalak/vuemark/blob/main/LICENSE) license.

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/cli.mjs

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { compileScript, parse } from "@vue/compiler-sfc";
+//#region src/parser.ts
+function parseSFC(source, filename) {
+	const doc = {
+		name: filename.replace(/\.vue$/, "").split("/").pop() ?? "Unknown",
+		props: [],
+		emits: []
+	};
+	const { descriptor } = parse(source, { filename });
+	if (!descriptor.scriptSetup && !descriptor.script) return doc;
+	const compiled = compileScript(descriptor, { id: filename });
+	const ast = compiled.scriptSetupAst;
+	if (!ast) return doc;
+	const scriptSource = descriptor.scriptSetup?.content ?? compiled.content;
+	for (const stmt of ast) {
+		const calls = extractDefineCalls(stmt);
+		for (const { callee, args, leadingComments } of calls) if (callee === "defineProps" && args[0]?.type === "ObjectExpression") doc.props = extractProps(args[0], scriptSource);
+		else if (callee === "defineEmits" && args[0]?.type === "ArrayExpression") doc.emits = extractEmits(args[0], leadingComments);
+	}
+	return doc;
+}
+function extractDefineCalls(stmt) {
+	const calls = [];
+	if (stmt.type === "ExpressionStatement" && stmt.expression.type === "CallExpression" && stmt.expression.callee.type === "Identifier") calls.push({
+		callee: stmt.expression.callee.name,
+		args: stmt.expression.arguments,
+		leadingComments: stmt.leadingComments ?? []
+	});
+	if (stmt.type === "VariableDeclaration") {
+		for (const decl of stmt.declarations) if (decl.init?.type === "CallExpression" && decl.init.callee.type === "Identifier") calls.push({
+			callee: decl.init.callee.name,
+			args: decl.init.arguments,
+			leadingComments: stmt.leadingComments ?? []
+		});
+	}
+	return calls;
+}
+function extractProps(obj, source) {
+	const props = [];
+	for (const prop of obj.properties) {
+		if (prop.type !== "ObjectProperty") continue;
+		const p = prop;
+		const name = p.key.type === "Identifier" ? p.key.name : p.key.type === "StringLiteral" ? p.key.value : "";
+		if (!name) continue;
+		const description = extractJSDoc(p.leadingComments ?? []);
+		if (p.value.type === "Identifier") props.push({
+			name,
+			type: p.value.name,
+			required: false,
+			default: void 0,
+			description
+		});
+		else if (p.value.type === "ArrayExpression") {
+			const types = p.value.elements.filter((el) => el?.type === "Identifier").map((el) => el.name);
+			props.push({
+				name,
+				type: types.join(" | "),
+				required: false,
+				default: void 0,
+				description
+			});
+		} else if (p.value.type === "ObjectExpression") {
+			let type = "unknown";
+			let required = false;
+			let defaultVal;
+			for (const field of p.value.properties) {
+				if (field.type !== "ObjectProperty") continue;
+				const fieldName = field.key.type === "Identifier" ? field.key.name : "";
+				if (fieldName === "type") {
+					if (field.value.type === "Identifier") type = field.value.name;
+					else if (field.value.type === "ArrayExpression") type = field.value.elements.filter((el) => el?.type === "Identifier").map((el) => el.name).join(" | ");
+				} else if (fieldName === "required") required = field.value.type === "BooleanLiteral" && field.value.value;
+				else if (fieldName === "default") defaultVal = stringifyDefault(field.value, source);
+			}
+			props.push({
+				name,
+				type,
+				required,
+				default: defaultVal,
+				description
+			});
+		}
+	}
+	return props;
+}
+function extractEmits(arr, leadingComments) {
+	const emits = [];
+	const jsdocMap = parseEmitJSDoc(leadingComments);
+	for (const el of arr.elements) if (el?.type === "StringLiteral") emits.push({
+		name: el.value,
+		description: jsdocMap.get(el.value) ?? ""
+	});
+	return emits;
+}
+function parseEmitJSDoc(comments) {
+	const map = /* @__PURE__ */ new Map();
+	for (const c of comments) {
+		if (c.type !== "CommentBlock") continue;
+		const lines = c.value.split("\n").map((l) => l.replace(/^\s*\*\s?/, "").replace(/^\s*\/?\*+\s?/, "").trim());
+		for (const line of lines) {
+			const match = line.match(/^@emit\s+(\S+)\s+(.*)/);
+			if (match?.[1] && match[2]) map.set(match[1], match[2].trim());
+		}
+	}
+	return map;
+}
+function extractJSDoc(comments) {
+	for (let i = comments.length - 1; i >= 0; i--) {
+		const c = comments[i];
+		if (c.type !== "CommentBlock") continue;
+		const lines = c.value.split("\n").map((l) => l.replace(/^\s*\*\s?/, "").trim()).filter((l) => l && !l.startsWith("@") && !l.startsWith("/"));
+		if (lines.length > 0) return lines.join(" ");
+	}
+	return "";
+}
+function stringifyDefault(node, source) {
+	switch (node.type) {
+		case "StringLiteral": return JSON.stringify(node.value);
+		case "NumericLiteral": return String(node.value);
+		case "BooleanLiteral": return String(node.value);
+		case "NullLiteral": return "null";
+		case "ArrowFunctionExpression":
+		case "FunctionExpression":
+			if (node.start != null && node.end != null) return source.slice(node.start, node.end);
+			return "...";
+		default: return "...";
+	}
+}
+//#endregion
+//#region src/markdown.ts
+function generateMarkdown(doc) {
+	const sections = [`# ${doc.name}`];
+	if (doc.props.length === 0 && doc.emits.length === 0) {
+		sections.push("", "No documentable props or emits found.");
+		return sections.join("\n") + "\n";
+	}
+	if (doc.props.length > 0) {
+		sections.push("", "## Props", "");
+		sections.push("| Name | Type | Required | Default | Description |");
+		sections.push("| --- | --- | --- | --- | --- |");
+		for (const p of doc.props) {
+			const def = p.default !== void 0 ? `\`${p.default}\`` : "-";
+			const desc = p.description || "-";
+			const req = p.required ? "Yes" : "No";
+			sections.push(`| ${p.name} | ${p.type} | ${req} | ${def} | ${desc} |`);
+		}
+	}
+	if (doc.emits.length > 0) {
+		sections.push("", "## Emits", "");
+		sections.push("| Name | Description |");
+		sections.push("| --- | --- |");
+		for (const e of doc.emits) {
+			const desc = e.description || "-";
+			sections.push(`| ${e.name} | ${desc} |`);
+		}
+	}
+	return sections.join("\n") + "\n";
+}
+//#endregion
+//#region src/index.ts
+function parseComponent(filePath) {
+	const abs = resolve(filePath);
+	return parseSFC(readFileSync(abs, "utf-8"), abs.split("/").pop() ?? "Unknown.vue");
+}
+//#endregion
+//#region src/cli.ts
+const filePath = process.argv[2];
+if (!filePath) {
+	console.error("Usage: compmark-vue <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);
+	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);
+}
+//#endregion
+export {};

package/dist/index.d.mts

@@ -0,0 +1,28 @@
+//#region src/types.d.ts
+interface PropDoc {
+  name: string;
+  type: string;
+  required: boolean;
+  default: string | undefined;
+  description: string;
+}
+interface EmitDoc {
+  name: string;
+  description: string;
+}
+interface ComponentDoc {
+  name: string;
+  props: PropDoc[];
+  emits: EmitDoc[];
+}
+//#endregion
+//#region src/parser.d.ts
+declare function parseSFC(source: string, filename: string): ComponentDoc;
+//#endregion
+//#region src/markdown.d.ts
+declare function generateMarkdown(doc: ComponentDoc): string;
+//#endregion
+//#region src/index.d.ts
+declare function parseComponent(filePath: string): ComponentDoc;
+//#endregion
+export { type ComponentDoc, type EmitDoc, type PropDoc, generateMarkdown, parseComponent, parseSFC };

package/dist/index.mjs

@@ -0,0 +1,168 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { compileScript, parse } from "@vue/compiler-sfc";
+//#region src/parser.ts
+function parseSFC(source, filename) {
+	const doc = {
+		name: filename.replace(/\.vue$/, "").split("/").pop() ?? "Unknown",
+		props: [],
+		emits: []
+	};
+	const { descriptor } = parse(source, { filename });
+	if (!descriptor.scriptSetup && !descriptor.script) return doc;
+	const compiled = compileScript(descriptor, { id: filename });
+	const ast = compiled.scriptSetupAst;
+	if (!ast) return doc;
+	const scriptSource = descriptor.scriptSetup?.content ?? compiled.content;
+	for (const stmt of ast) {
+		const calls = extractDefineCalls(stmt);
+		for (const { callee, args, leadingComments } of calls) if (callee === "defineProps" && args[0]?.type === "ObjectExpression") doc.props = extractProps(args[0], scriptSource);
+		else if (callee === "defineEmits" && args[0]?.type === "ArrayExpression") doc.emits = extractEmits(args[0], leadingComments);
+	}
+	return doc;
+}
+function extractDefineCalls(stmt) {
+	const calls = [];
+	if (stmt.type === "ExpressionStatement" && stmt.expression.type === "CallExpression" && stmt.expression.callee.type === "Identifier") calls.push({
+		callee: stmt.expression.callee.name,
+		args: stmt.expression.arguments,
+		leadingComments: stmt.leadingComments ?? []
+	});
+	if (stmt.type === "VariableDeclaration") {
+		for (const decl of stmt.declarations) if (decl.init?.type === "CallExpression" && decl.init.callee.type === "Identifier") calls.push({
+			callee: decl.init.callee.name,
+			args: decl.init.arguments,
+			leadingComments: stmt.leadingComments ?? []
+		});
+	}
+	return calls;
+}
+function extractProps(obj, source) {
+	const props = [];
+	for (const prop of obj.properties) {
+		if (prop.type !== "ObjectProperty") continue;
+		const p = prop;
+		const name = p.key.type === "Identifier" ? p.key.name : p.key.type === "StringLiteral" ? p.key.value : "";
+		if (!name) continue;
+		const description = extractJSDoc(p.leadingComments ?? []);
+		if (p.value.type === "Identifier") props.push({
+			name,
+			type: p.value.name,
+			required: false,
+			default: void 0,
+			description
+		});
+		else if (p.value.type === "ArrayExpression") {
+			const types = p.value.elements.filter((el) => el?.type === "Identifier").map((el) => el.name);
+			props.push({
+				name,
+				type: types.join(" | "),
+				required: false,
+				default: void 0,
+				description
+			});
+		} else if (p.value.type === "ObjectExpression") {
+			let type = "unknown";
+			let required = false;
+			let defaultVal;
+			for (const field of p.value.properties) {
+				if (field.type !== "ObjectProperty") continue;
+				const fieldName = field.key.type === "Identifier" ? field.key.name : "";
+				if (fieldName === "type") {
+					if (field.value.type === "Identifier") type = field.value.name;
+					else if (field.value.type === "ArrayExpression") type = field.value.elements.filter((el) => el?.type === "Identifier").map((el) => el.name).join(" | ");
+				} else if (fieldName === "required") required = field.value.type === "BooleanLiteral" && field.value.value;
+				else if (fieldName === "default") defaultVal = stringifyDefault(field.value, source);
+			}
+			props.push({
+				name,
+				type,
+				required,
+				default: defaultVal,
+				description
+			});
+		}
+	}
+	return props;
+}
+function extractEmits(arr, leadingComments) {
+	const emits = [];
+	const jsdocMap = parseEmitJSDoc(leadingComments);
+	for (const el of arr.elements) if (el?.type === "StringLiteral") emits.push({
+		name: el.value,
+		description: jsdocMap.get(el.value) ?? ""
+	});
+	return emits;
+}
+function parseEmitJSDoc(comments) {
+	const map = /* @__PURE__ */ new Map();
+	for (const c of comments) {
+		if (c.type !== "CommentBlock") continue;
+		const lines = c.value.split("\n").map((l) => l.replace(/^\s*\*\s?/, "").replace(/^\s*\/?\*+\s?/, "").trim());
+		for (const line of lines) {
+			const match = line.match(/^@emit\s+(\S+)\s+(.*)/);
+			if (match?.[1] && match[2]) map.set(match[1], match[2].trim());
+		}
+	}
+	return map;
+}
+function extractJSDoc(comments) {
+	for (let i = comments.length - 1; i >= 0; i--) {
+		const c = comments[i];
+		if (c.type !== "CommentBlock") continue;
+		const lines = c.value.split("\n").map((l) => l.replace(/^\s*\*\s?/, "").trim()).filter((l) => l && !l.startsWith("@") && !l.startsWith("/"));
+		if (lines.length > 0) return lines.join(" ");
+	}
+	return "";
+}
+function stringifyDefault(node, source) {
+	switch (node.type) {
+		case "StringLiteral": return JSON.stringify(node.value);
+		case "NumericLiteral": return String(node.value);
+		case "BooleanLiteral": return String(node.value);
+		case "NullLiteral": return "null";
+		case "ArrowFunctionExpression":
+		case "FunctionExpression":
+			if (node.start != null && node.end != null) return source.slice(node.start, node.end);
+			return "...";
+		default: return "...";
+	}
+}
+//#endregion
+//#region src/markdown.ts
+function generateMarkdown(doc) {
+	const sections = [`# ${doc.name}`];
+	if (doc.props.length === 0 && doc.emits.length === 0) {
+		sections.push("", "No documentable props or emits found.");
+		return sections.join("\n") + "\n";
+	}
+	if (doc.props.length > 0) {
+		sections.push("", "## Props", "");
+		sections.push("| Name | Type | Required | Default | Description |");
+		sections.push("| --- | --- | --- | --- | --- |");
+		for (const p of doc.props) {
+			const def = p.default !== void 0 ? `\`${p.default}\`` : "-";
+			const desc = p.description || "-";
+			const req = p.required ? "Yes" : "No";
+			sections.push(`| ${p.name} | ${p.type} | ${req} | ${def} | ${desc} |`);
+		}
+	}
+	if (doc.emits.length > 0) {
+		sections.push("", "## Emits", "");
+		sections.push("| Name | Description |");
+		sections.push("| --- | --- |");
+		for (const e of doc.emits) {
+			const desc = e.description || "-";
+			sections.push(`| ${e.name} | ${desc} |`);
+		}
+	}
+	return sections.join("\n") + "\n";
+}
+//#endregion
+//#region src/index.ts
+function parseComponent(filePath) {
+	const abs = resolve(filePath);
+	return parseSFC(readFileSync(abs, "utf-8"), abs.split("/").pop() ?? "Unknown.vue");
+}
+//#endregion
+export { generateMarkdown, parseComponent, parseSFC };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "compmark-vue",
+  "version": "0.1.0",
+  "description": "Auto-generate Markdown documentation from Vue 3 SFCs",
+  "license": "MIT",
+  "repository": "noopurphalak/vuemark",
+  "bin": {
+    "compmark-vue": "./dist/cli.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": "./dist/index.mjs"
+  },
+  "scripts": {
+    "build": "obuild",
+    "dev": "vitest dev",
+    "fmt": "automd && oxlint . --fix && oxfmt .",
+    "lint": "oxlint . && oxfmt --check .",
+    "prepack": "pnpm build",
+    "release": "pnpm test && pnpm build && changelogen --release && npm publish && git push --follow-tags",
+    "test": "pnpm lint && pnpm typecheck && vitest run --coverage",
+    "typecheck": "tsgo --noEmit --skipLibCheck"
+  },
+  "dependencies": {
+    "@vue/compiler-sfc": "^3.5.0"
+  },
+  "devDependencies": {
+    "@babel/types": "latest",
+    "@types/node": "latest",
+    "@typescript/native-preview": "latest",
+    "@vitest/coverage-v8": "latest",
+    "automd": "latest",
+    "changelogen": "latest",
+    "obuild": "latest",
+    "oxfmt": "latest",
+    "oxlint": "latest",
+    "typescript": "latest",
+    "vitest": "latest"
+  },
+  "packageManager": "pnpm@10.29.3"
+}