///
import { spawnSync } from 'node:child_process';
import {
appendFileSync,
mkdtempSync,
mkdirSync,
readFileSync,
rmSync,
writeFileSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { parseArgs, stripVTControlCharacters } from 'node:util';
type ToolName = 'vite' | 'vitest' | 'oxlint' | 'oxfmt' | 'tsdown';
type Tool = {
commands: string[][];
name: ToolName;
packageName: string;
title: string;
};
type ToolSnapshot = {
help: string;
version: string;
};
type Snapshot = {
tools: Record;
};
type VersionMetadata = Partial<
Record<
ToolName,
{
new: string;
tag?: string;
}
>
>;
const ROOT = process.cwd();
const WORKSPACE_PATH = join(ROOT, 'pnpm-workspace.yaml');
// Leave room for five reports plus Markdown within GitHub's 65,536-character comment limit.
const MAX_DIFF_LENGTH = 12_000;
const TOOLS: Tool[] = [
{
// Vite+ mirrors the root command plus the build and preview option sets.
commands: [['--help'], ['build', '--help'], ['preview', '--help']],
name: 'vite',
packageName: 'vite',
title: 'Vite',
},
{
commands: [['--help']],
name: 'vitest',
packageName: 'vitest',
title: 'Vitest',
},
{
commands: [['--help']],
name: 'oxlint',
packageName: 'oxlint',
title: 'Oxlint',
},
{
commands: [['--help']],
name: 'oxfmt',
packageName: 'oxfmt',
title: 'Oxfmt',
},
{
commands: [['--help']],
name: 'tsdown',
packageName: 'tsdown',
title: 'tsdown',
},
];
function readJson(filePath: string): unknown {
return JSON.parse(readFileSync(filePath, 'utf8'));
}
function readToolVersion(tool: Tool, versions?: VersionMetadata): string {
if (versions) {
const change = versions[tool.name];
const version = tool.name === 'vite' ? change?.tag?.replace(/^v/, '') : change?.new;
if (!version) {
throw new Error(`Upgrade metadata has no target version for ${tool.name}`);
}
return version;
}
if (tool.name === 'vite') {
const pkg = readJson(join(ROOT, 'vite/packages/vite/package.json')) as { version?: unknown };
if (typeof pkg.version !== 'string') {
throw new TypeError('vite/packages/vite/package.json has no version');
}
return pkg.version;
}
const workspace = readFileSync(WORKSPACE_PATH, 'utf8');
const match = new RegExp(`^ ${tool.name}: [=~^]?([^\\s#]+)`, 'm').exec(workspace);
if (!match) {
throw new Error(`Could not find ${tool.name} in the pnpm workspace catalog`);
}
return match[1];
}
function normalizeOutput(output: string, version: string): string {
// Version banners change on every release but do not represent CLI option drift.
return stripVTControlCharacters(output)
.replaceAll('\r\n', '\n')
.replaceAll(version, '')
.split('\n')
.map((line) => line.trimEnd())
.join('\n')
.trimEnd();
}
function captureToolHelp(tool: Tool, version: string, cwd: string): string {
return tool.commands
.map((command) => {
const result = spawnSync(
'pnpm',
['--silent', 'dlx', `${tool.packageName}@${version}`, ...command],
{
cwd,
encoding: 'utf8',
env: {
...process.env,
CI: '1',
COLUMNS: '120',
FORCE_COLOR: '0',
NO_COLOR: '1',
TERM: 'dumb',
},
},
);
if (result.status !== 0) {
throw new Error(
`Failed to capture ${tool.title} help (${command.join(' ')}):\n${result.stderr}`,
);
}
return [`$ ${tool.packageName} ${command.join(' ')}`, result.stdout.trimEnd()].join('\n');
})
.join('\n\n');
}
function captureSnapshot(outputPath: string, versionsPath?: string): void {
const versions = versionsPath ? (readJson(versionsPath) as VersionMetadata) : undefined;
const tools = {} as Record;
// Run outside the repository so pnpm dlx does not inherit workspace overrides or patches.
const cwd = mkdtempSync(join(tmpdir(), 'vite-plus-cli-help-capture-'));
try {
for (const tool of TOOLS) {
const version = readToolVersion(tool, versions);
console.log(`Capturing ${tool.title} ${version} help...`);
tools[tool.name] = {
help: captureToolHelp(tool, version, cwd),
version,
};
}
} finally {
rmSync(cwd, { force: true, recursive: true });
}
mkdirSync(dirname(outputPath), { recursive: true });
writeFileSync(outputPath, `${JSON.stringify({ tools } satisfies Snapshot, null, 2)}\n`);
}
function createUnifiedDiff(tool: Tool, before: ToolSnapshot, after: ToolSnapshot): string {
const tempDir = mkdtempSync(join(tmpdir(), 'vite-plus-cli-help-'));
const beforePath = join(tempDir, 'before.txt');
const afterPath = join(tempDir, 'after.txt');
try {
writeFileSync(beforePath, `${normalizeOutput(before.help, before.version)}\n`);
writeFileSync(afterPath, `${normalizeOutput(after.help, after.version)}\n`);
const result = spawnSync(
'git',
[
'diff',
'--no-index',
'--no-color',
'--no-ext-diff',
'--unified=3',
'--',
beforePath,
afterPath,
],
{ encoding: 'utf8' },
);
// `git diff --no-index` exits with 1 when it successfully finds differences.
if (result.status !== 1) {
throw new Error(`Failed to diff ${tool.title} help:\n${result.stderr}`);
}
const firstHunk = result.stdout.indexOf('@@');
if (firstHunk === -1) {
throw new Error(`Git produced no diff hunk for ${tool.title}`);
}
return [
`--- ${tool.packageName}@${before.version}`,
`+++ ${tool.packageName}@${after.version}`,
result.stdout.slice(firstHunk).trimEnd(),
].join('\n');
} finally {
rmSync(tempDir, { force: true, recursive: true });
}
}
function truncateDiff(diff: string): string {
if (diff.length <= MAX_DIFF_LENGTH) {
return diff;
}
return `${diff.slice(0, MAX_DIFF_LENGTH)}\n... diff truncated to fit in one GitHub comment ...`;
}
function hasHelpChanges(before: Snapshot, after: Snapshot): boolean {
return TOOLS.some((tool) => {
const previous = before.tools[tool.name];
const current = after.tools[tool.name];
return (
previous.version !== current.version &&
normalizeOutput(previous.help, previous.version) !==
normalizeOutput(current.help, current.version)
);
});
}
function renderReport(before: Snapshot, after: Snapshot, hasChanges: boolean): string {
const lines = [
hasChanges
? '## ⚠️ Upstream CLI help changes detected'
: '## ✅ No upstream CLI help changes detected',
'',
'Compared normalized `--help` output for the upstream CLIs mirrored by Vite+.',
'',
];
for (const tool of TOOLS) {
const previous = before.tools[tool.name];
const current = after.tools[tool.name];
lines.push('');
if (previous.version === current.version) {
lines.push(
`➖ ${tool.title}: no version update (${current.version})
`,
'',
'No version update was detected, so there is no CLI help diff.',
);
} else if (
normalizeOutput(previous.help, previous.version) ===
normalizeOutput(current.help, current.version)
) {
lines.push(
`✅ ${tool.title}: no CLI help changes (${previous.version} → ${current.version})
`,
'',
'The version was updated, but the normalized CLI help output has no differences.',
);
} else {
lines.push(
`⚠️ ${tool.title}: CLI help changed (${previous.version} → ${current.version})
`,
'',
'```diff',
truncateDiff(createUnifiedDiff(tool, previous, current)),
'```',
);
}
lines.push('', ' ', '');
}
return `${lines.join('\n').trimEnd()}\n`;
}
function generateReport(
beforePath: string,
afterPath: string,
outputPath: string,
githubOutputPath?: string,
): void {
const before = readJson(beforePath) as Snapshot;
const after = readJson(afterPath) as Snapshot;
const hasChanges = hasHelpChanges(before, after);
mkdirSync(dirname(outputPath), { recursive: true });
writeFileSync(outputPath, renderReport(before, after, hasChanges));
if (githubOutputPath) {
appendFileSync(githubOutputPath, `has-changes=${hasChanges}\n`);
}
console.log(`Wrote CLI help report to ${outputPath}`);
}
const { positionals, values } = parseArgs({
allowPositionals: true,
options: {
after: { type: 'string' },
before: { type: 'string' },
'github-output': { type: 'string' },
output: { short: 'o', type: 'string' },
versions: { type: 'string' },
},
});
const [command] = positionals;
if (command === 'capture' && values.output) {
captureSnapshot(values.output, values.versions);
} else if (command === 'report' && values.before && values.after && values.output) {
generateReport(values.before, values.after, values.output, values['github-output']);
} else {
throw new Error(
'Usage: cli-help-diff.ts capture --output [--versions ] | report --before --after --output [--github-output ]',
);
}