scripts/repro/vue-docs-examples/run.mjs
GitHub#!/usr/bin/env node
import {
existsSync,
mkdirSync,
readFileSync,
readdirSync,
rmSync,
statSync,
writeFileSync,
} from "node:fs";
import { createRequire } from "node:module";
import { dirname, join, relative, resolve } from "node:path";
import { spawnSync } from "node:child_process";
import { fileURLToPath } from "node:url";
import { ensureNodeTool } from "../lib/runner.mjs";
import {
compileVueSfc,
VUE_SFC_COMPILE_PROFILES,
vueSfcCompileProfile,
} from "../lib/vue-sfc-compiler.mjs";
const scriptDir = dirname(fileURLToPath(import.meta.url));
const repoRoot = resolve(scriptDir, "../../..");
const defaultDocsRoot = join(repoRoot, "target", "vue-docs");
const outputRoot = join(repoRoot, "target", "vue-docs-examples");
const BABEL_PARSER_VERSION = "7.29.7";
export const VUE_DOCS_COMMIT = "e4641141026871271e5083c99ad4cd3f4a8e9a68";
const VUE_DOCS_REPOSITORY = "git@github.com:vuejs/docs.git";
export function toScriptSetup(source, template) {
const exportDefaultIndex = source.indexOf("export default");
const lastReturnIndex = source.lastIndexOf("return {");
let setupCode = lastReturnIndex > -1
? deindent(
source
.slice(exportDefaultIndex, lastReturnIndex)
.replace(/export default[^]+?setup\([^)]*\)\s*{/, "")
.trim(),
)
: "";
const propsStartIndex = source.indexOf("\n props:");
if (propsStartIndex > -1) {
const propsEndIndex = source.indexOf("\n }", propsStartIndex) + 4;
const propsVar = /\bprops\b/.test(template) || /\bprops\b/.test(source)
? "const props = "
: "";
const propsDef = deindent(
source
.slice(propsStartIndex, propsEndIndex)
.trim()
.replace(/,$/, "")
.replace(/^props: /, `${propsVar}defineProps(`) + ")",
1,
);
setupCode = `${propsDef}\n\n${setupCode}`.trim();
}
const emitsStartIndex = source.indexOf("\n emits:");
if (emitsStartIndex > -1) {
const emitsEndIndex = source.indexOf("]", emitsStartIndex) + 1;
const emitsDef = source
.slice(emitsStartIndex, emitsEndIndex)
.trim()
.replace(/,$/, "")
.replace(/^emits: /, "const emit = defineEmits(") + ")";
setupCode = `${emitsDef}\n\n${setupCode}`.trim();
}
const prefix = source.slice(0, exportDefaultIndex);
const result = prefix + setupCode;
return `${setupCode ? result : result.trim()}\n`;
}
export function assembleCompositionSfc({ description = "", script, template, style = "" }) {
let source = description.trim() ? `<!--\n${description.trim()}\n-->\n\n` : "";
source += `<script setup>\n${toScriptSetup(script, template)}</script>\n\n`;
source += `<template>\n${indent(template)}</template>`;
if (style) source += `\n\n<style>\n${style}</style>`;
return source;
}
function indent(source) {
return source
.split("\n")
.map((line) => line.trim() ? ` ${line}` : line)
.join("\n");
}
function deindent(source, tabSize = 2) {
return source
.split("\n")
.map((line) => line.replace(tabSize === 1 ? /^\s{2}/ : /^\s{4}/, ""))
.join("\n");
}
function main() {
const options = parseArgs(process.argv.slice(2));
const docsRoot = resolve(options.docsRoot ?? defaultDocsRoot);
ensureDocsCheckout(docsRoot, { pin: options.docsRoot === undefined });
const examplesRoot = join(docsRoot, "src", "examples", "src");
if (!existsSync(examplesRoot)) {
throw new Error(`Vue docs examples not found at ${examplesRoot}`);
}
const docsPackage = JSON.parse(readFileSync(join(docsRoot, "package.json"), "utf8"));
const vueVersion = docsPackage.dependencies.vue.replace(/^[^\d]*/, "");
const toolDir = ensureNodeTool(
`vue-docs-examples-sfc-${vueVersion}`,
[
`@vue/compiler-sfc@${vueVersion}`,
`@babel/parser@${BABEL_PARSER_VERSION}`,
],
);
const require = createRequire(join(toolDir, "package.json"));
const compiler = require("@vue/compiler-sfc");
const babelParser = require("@babel/parser");
const wakaru = resolveWakaru(options);
const profiles = options.profile
? [vueSfcCompileProfile(options.profile)]
: VUE_SFC_COMPILE_PROFILES;
rmSync(outputRoot, { recursive: true, force: true });
mkdirSync(outputRoot, { recursive: true });
const generatedRoot = join(outputRoot, "generated");
const recoveredRoot = join(outputRoot, "recovered");
mkdirSync(generatedRoot, { recursive: true });
mkdirSync(recoveredRoot, { recursive: true });
const fixtures = readFixtures(examplesRoot)
.filter((fixture) => !options.filter || fixture.name.includes(options.filter));
const rows = profiles.flatMap((profile) =>
fixtures.map((fixture) =>
runFixture({
fixture,
profile,
compiler,
babelParser,
wakaru,
generatedRoot,
recoveredRoot,
}),
),
);
const docsCommit = runCapture(["git", "-C", docsRoot, "rev-parse", "HEAD"]).trim();
const report = {
docs_commit: docsCommit,
vue_version: vueVersion,
profiles: profiles.map(({ name, tier, isProd, inlineTemplate }) => ({
name,
tier,
is_prod: isProd,
inline_template: inlineTemplate,
})),
rows,
};
writeFileSync(join(outputRoot, "report.json"), `${JSON.stringify(report, null, 2)}\n`);
writeFileSync(join(outputRoot, "report.md"), formatReport(report));
process.stdout.write(options.json
? `${JSON.stringify(report, null, 2)}\n`
: formatReport(report));
}
function parseArgs(args) {
const options = {
docsRoot: undefined,
filter: "",
profile: "",
json: false,
skipWakaruBuild: false,
};
for (let index = 0; index < args.length; index++) {
const arg = args[index];
if (arg === "--docs") options.docsRoot = args[++index];
else if (arg === "--filter") options.filter = args[++index] ?? "";
else if (arg === "--profile") options.profile = args[++index] ?? "";
else if (arg === "--json") options.json = true;
else if (arg === "--no-build-wakaru") options.skipWakaruBuild = true;
else throw new Error(`unknown option ${arg}`);
}
return options;
}
export function ensureDocsCheckout(docsRoot, options = {}) {
const {
commit = VUE_DOCS_COMMIT,
pin = true,
repository = VUE_DOCS_REPOSITORY,
} = options;
const exists = existsSync(join(docsRoot, ".git"));
if (!exists) {
mkdirSync(dirname(docsRoot), { recursive: true });
const cloneArgs = pin
? ["git", "clone", "--filter=blob:none", "--no-checkout", repository, docsRoot]
: ["git", "clone", repository, docsRoot];
runChecked(cloneArgs);
}
if (!pin) return;
const currentCommit = runCapture(["git", "-C", docsRoot, "rev-parse", "HEAD"]).trim();
if (exists) {
const dirty = runCapture(["git", "-C", docsRoot, "status", "--porcelain"]);
if (dirty.trim()) {
throw new Error(`refusing to update dirty Vue docs checkout at ${docsRoot}`);
}
}
if (exists && currentCommit === commit) return;
runChecked(["git", "-C", docsRoot, "fetch", "--depth", "1", "origin", commit]);
runChecked(["git", "-C", docsRoot, "checkout", "--detach", commit]);
}
function resolveWakaru(options) {
const binary = process.env.WAKARU || join(
repoRoot,
"target",
"debug",
process.platform === "win32" ? "wakaru.exe" : "wakaru",
);
if (!options.skipWakaruBuild && !process.env.WAKARU) {
runChecked(["cargo", "build", "-p", "wakaru-cli"], { cwd: repoRoot });
}
if (!existsSync(binary)) throw new Error(`Wakaru binary not found at ${binary}`);
return binary;
}
function readFixtures(examplesRoot) {
const fixtures = [];
for (const example of readdirSync(examplesRoot).sort()) {
const exampleRoot = join(examplesRoot, example);
if (!statSync(exampleRoot).isDirectory()) continue;
const descriptionPath = join(exampleRoot, "description.txt");
const description = existsSync(descriptionPath) ? readFileSync(descriptionPath, "utf8") : "";
for (const component of readdirSync(exampleRoot).sort()) {
const componentRoot = join(exampleRoot, component);
if (!statSync(componentRoot).isDirectory()) continue;
const compositionPath = join(componentRoot, "composition.js");
const templatePath = join(componentRoot, "template.html");
if (!existsSync(compositionPath) || !existsSync(templatePath)) continue;
const stylePath = join(componentRoot, "style.css");
fixtures.push({
name: `${example}/${component}`,
filename: `${component}.vue`,
source: assembleCompositionSfc({
description: component === "App" ? description : "",
script: readFileSync(compositionPath, "utf8"),
template: readFileSync(templatePath, "utf8"),
style: existsSync(stylePath) ? readFileSync(stylePath, "utf8") : "",
}),
});
}
}
return fixtures;
}
function runFixture({
fixture,
profile,
compiler,
babelParser,
wakaru,
generatedRoot,
recoveredRoot,
}) {
const generated = compileVueSfc({
source: fixture.source,
filename: fixture.filename,
compiler,
profile,
id: `data-v-docs-${fixture.filename.replace(/\W/g, "-")}`,
includeFilename: !profile.isProd,
});
const generatedPath = join(generatedRoot, profile.name, `${fixture.name}.js`);
const recoveredPath = join(recoveredRoot, profile.name, `${fixture.name}.vue`);
mkdirSync(dirname(generatedPath), { recursive: true });
mkdirSync(dirname(recoveredPath), { recursive: true });
writeFileSync(generatedPath, generated);
const result = spawnSync(wakaru, [
generatedPath,
"--vue-sfc",
"--force",
"-o",
recoveredPath,
], { cwd: repoRoot, encoding: "utf8", maxBuffer: 1024 * 1024 * 20 });
const recovered = result.status === 0 && existsSync(recoveredPath)
? readFileSync(recoveredPath, "utf8")
: "";
const validation = validateRecovered(
fixture.source,
recovered,
fixture.filename,
compiler,
babelParser,
);
return {
name: fixture.name,
profile: profile.name,
profile_tier: profile.tier,
recovered: Boolean(recovered),
exit_code: result.status,
stderr: result.stderr.trim(),
...validation,
};
}
function validateRecovered(original, recovered, filename, compiler, babelParser) {
if (!recovered) {
return {
parse_ok: false,
template_ok: false,
script_setup: false,
missing_imports: [],
leaked_markers: [],
template_equivalent: false,
};
}
const originalParsed = compiler.parse(original, { filename }).descriptor;
const parsed = compiler.parse(recovered, { filename });
const parseOk = parsed.errors.length === 0;
const descriptor = parsed.descriptor;
let templateOk = false;
let templateEquivalent = false;
if (parseOk && descriptor.template) {
const recoveredTemplate = compileTemplateForComparison(descriptor.template.content, filename, compiler);
const originalTemplate = compileTemplateForComparison(
originalParsed.template.content,
filename,
compiler,
);
templateOk = recoveredTemplate.errors.length === 0;
templateEquivalent = templateOk
&& normalizeCompiledTemplate(recoveredTemplate.code, babelParser)
=== normalizeCompiledTemplate(originalTemplate.code, babelParser);
}
const recoveredScript = [descriptor.script?.content, descriptor.scriptSetup?.content]
.filter(Boolean)
.join("\n");
const originalImports = importRequirements(originalParsed.scriptSetup?.content ?? "");
const missingImports = originalImports
.filter((requirement) => !hasImportRequirement(recoveredScript, requirement))
.map((requirement) => `${requirement.imported} from ${requirement.source}`);
const leakedMarkers = ["$setup", "__isScriptSetup", "__expose"]
.filter((marker) => recovered.includes(marker));
return {
parse_ok: parseOk,
template_ok: templateOk,
script_setup: Boolean(descriptor.scriptSetup),
missing_imports: missingImports,
leaked_markers: leakedMarkers,
template_equivalent: templateEquivalent,
};
}
function compileTemplateForComparison(source, filename, compiler) {
return compiler.compileTemplate({
source,
filename,
id: "data-v-docs-compare",
isProd: true,
compilerOptions: { hoistStatic: true },
});
}
export function normalizeCompiledTemplate(code, babelParser) {
const parsed = babelParser.parse(code, {
sourceType: "module",
tokens: true,
});
const hoistNames = new Map();
return JSON.stringify(parsed.tokens
.filter((token) => typeof token.type !== "string")
.map((token) => {
const type = token.type.label;
let value = token.value ?? type;
if (type === "name" && /^_hoisted_\d+$/.test(value)) {
if (!hoistNames.has(value)) hoistNames.set(value, `_hoisted_${hoistNames.size}`);
value = hoistNames.get(value);
}
return [type, value];
}));
}
export function importRequirements(source) {
const requirements = [];
const pattern = /import\s+([^;\n]+?)\s+from\s+["']([^"']+)["']/g;
for (const match of source.matchAll(pattern)) {
const clause = match[1].trim();
const sourceName = match[2];
const defaultMatch = clause.match(/^([A-Za-z_$][\w$]*)/);
if (defaultMatch) {
requirements.push({ kind: "default", imported: "default", local: defaultMatch[1], source: sourceName });
}
const namespaceMatch = clause.match(/\*\s+as\s+([A-Za-z_$][\w$]*)/);
if (namespaceMatch) {
requirements.push({ kind: "namespace", imported: "*", local: namespaceMatch[1], source: sourceName });
}
const named = clause.match(/\{([^}]*)\}/)?.[1] ?? "";
for (const specifier of named.split(",").map((part) => part.trim()).filter(Boolean)) {
const parts = specifier.split(/\s+as\s+/);
requirements.push({
kind: "named",
imported: parts[0].trim(),
local: parts.at(-1).trim(),
source: sourceName,
});
}
}
return requirements;
}
export function hasImportRequirement(script, requirement) {
return importRequirements(script).some((candidate) =>
candidate.kind === requirement.kind
&& candidate.imported === requirement.imported
&& candidate.source === requirement.source
);
}
function formatReport(report) {
const passed = report.rows.filter((row) =>
row.recovered
&& row.parse_ok
&& row.template_ok
&& row.script_setup
&& row.missing_imports.length === 0
&& row.leaked_markers.length === 0,
).length;
const equivalent = report.rows.filter((row) => row.template_equivalent).length;
const lines = [
"# Vue docs examples recovery",
`# docs: ${report.docs_commit}`,
`# Vue compiler: ${report.vue_version}`,
`# acceptance: ${passed}/${report.rows.length}`,
`# template-equivalent: ${equivalent}/${report.rows.length}`,
];
for (const profile of report.profiles) {
const rows = report.rows.filter((row) => row.profile === profile.name);
const profilePassed = rows.filter((row) =>
row.recovered
&& row.parse_ok
&& row.template_ok
&& row.script_setup
&& row.missing_imports.length === 0
&& row.leaked_markers.length === 0,
).length;
const profileEquivalent = rows.filter((row) => row.template_equivalent).length;
lines.push(
`# ${profile.name} (${profile.tier}): ${profilePassed}/${rows.length} accepted, ${profileEquivalent}/${rows.length} template-equivalent`,
);
}
lines.push(
"",
"| profile | component | recovered | valid | script setup | imports | template | leaks |",
"|---|---|---:|---:|---:|---:|---:|---|",
);
for (const row of report.rows) {
lines.push(`| ${row.profile} | ${row.name} | ${yes(row.recovered)} | ${yes(row.parse_ok && row.template_ok)} | ${yes(row.script_setup)} | ${row.missing_imports.length ? row.missing_imports.join(", ") : "yes"} | ${yes(row.template_equivalent)} | ${row.leaked_markers.join(", ")} |`);
}
return `${lines.join("\n")}\n`;
}
function yes(value) {
return value ? "yes" : "no";
}
function runChecked(command, options = {}) {
const result = spawnSync(command[0], command.slice(1), {
cwd: options.cwd ?? repoRoot,
encoding: "utf8",
stdio: "inherit",
});
if (result.error) throw result.error;
if (result.status !== 0) throw new Error(`${command.join(" ")} exited ${result.status}`);
}
function runCapture(command) {
const result = spawnSync(command[0], command.slice(1), { encoding: "utf8" });
if (result.error) throw result.error;
if (result.status !== 0) throw new Error(`${command.join(" ")} exited ${result.status}`);
return result.stdout;
}
if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
try {
main();
} catch (error) {
console.error(error?.stack ?? String(error));
process.exitCode = 1;
}
}