3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
import { readdir, readFile, writeFile, rm } from 'node:fs/promises';
import { resolve } from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
import { isAllowedMediaUrl, isVideoUrl } from '../src/changelog-media.js';
const root = fileURLToPath(new URL('..', import.meta.url));
const fragmentsFolder = resolve(root, 'changes');
const changelogPath = resolve(root, 'CHANGELOG.md');
const semver = /^\d+\.\d+\.\d+(?:-[a-z0-9.-]+)?$/;
export function isFragmentName(name) {
return name.endsWith('.md') && !name.endsWith('.size.md') && name.toLowerCase() !== 'readme.md';
}
function trimBlankLines(text) {
return text.replace(/\r\n/g, '\n').replace(/^\n+/, '').replace(/\s+$/, '');
}
// Reads every fragment in name order, so the same files always give the same text.
export async function readFragments(folder = fragmentsFolder) {
const names = (await readdir(folder)).filter(isFragmentName).sort();
const fragments = [];
for (const name of names) {
const text = trimBlankLines(await readFile(resolve(folder, name), 'utf8'));
if (text) fragments.push({ name, text });
}
return fragments;
}
// A changelog entry is a "- " bullet; a line that follows without a bullet continues it.
// An entry is breaking when its text says "Breaking" with a capital B, as in "Breaking:" or "Breaking look change:".
const breakingPattern = /\bBreaking\b/;
function issueNumberOf(text, fallbackName) {
const inText = text.match(/#(\d+)/);
if (inText) return Number(inText[1]);
const inName = fallbackName?.match(/^(\d+)/);
return inName ? Number(inName[1]) : null;
}
// A "### Group" heading names the group of the entries below it. Every entry under a group called
// "Breaking changes" is breaking.
const groupHeading = /^###\s+(.+?)\s*$/;
// A note adds a picture or clip with a line "media: <url> <alt text>" under its bullet. CHANGELOG.md holds the same
// thing as markdown ("", or "[alt](url)" for a video), so both forms are read back.
const mediaLine = /^\s*media:\s+(\S+)(?:\s+(.*\S))?\s*$/;
const markdownImageLine = /^\s*!\[([^\]]*)\]\((\S+)\)\s*$/;
const markdownVideoLine = /^\s*\[([^\]]*)\]\((\S+)\)\s*$/;
function mediaOfLine(line) {
const note = line.match(mediaLine);
if (note) return { url: note[1], alt: note[2] ?? '' };
const image = line.match(markdownImageLine);
if (image) return { url: image[2], alt: image[1] };
const video = line.match(markdownVideoLine);
if (video && isVideoUrl(video[2])) return { url: video[2], alt: video[1] };
return null;
}
function checkedMedia(media, line) {
if (!isAllowedMediaUrl(media.url)) {
throw new Error(`Media line "${line.trim()}" needs an https URL or a path that starts with "/". Write "media: https://example.com/clip.mp4 What the clip shows".`);
}
if (!media.alt) throw new Error(`Media line "${line.trim()}" needs alt text after the URL. Write "media: <url> What the picture shows".`);
return media;
}
// Turns "media:" lines into the markdown GitHub renders: an image, or a link for a video.
export function mediaLinesToMarkdown(text) {
return text.split('\n').map((line) => {
const note = line.match(mediaLine);
if (!note) return line;
const media = checkedMedia({ url: note[1], alt: note[2] ?? '' }, line);
return isVideoUrl(media.url) ? ` [${media.alt}](${media.url})` : ` `;
}).join('\n');
}
export function parseEntries(markdown, fallbackName) {
const entries = [];
let group = null;
for (const line of markdown.replace(/\r\n/g, '\n').split('\n')) {
const heading = line.match(groupHeading);
if (heading) {
group = heading[1];
} else if (line.startsWith('- ')) {
entries.push({ text: line.slice(2).trim(), group });
} else if (line.trim() && entries.length > 0 && mediaOfLine(line)) {
entries[entries.length - 1].media = checkedMedia(mediaOfLine(line), line);
} else if (line.trim() && entries.length > 0) {
entries[entries.length - 1].text += ` ${line.trim()}`;
}
}
return entries.map(({ text, group: entryGroup, media }) => {
const breaking = breakingPattern.test(text) || breakingPattern.test(entryGroup ?? '');
const entry = { issue: issueNumberOf(text, fallbackName), text, breaking };
if (entryGroup) entry.group = entryGroup;
if (media) entry.media = media;
return entry;
});
}
// Splits CHANGELOG.md into its "## <version>" sections, newest first as written.
export function parseChangelogSections(changelogText) {
const sections = [];
const text = changelogText.replace(/\r\n/g, '\n');
const headings = [...text.matchAll(/^## (\S+)[ \t]*$/gm)];
headings.forEach((heading, index) => {
const end = index + 1 < headings.length ? headings[index + 1].index : text.length;
const body = text.slice(heading.index + heading[0].length, end);
sections.push({ version: heading[1], body: trimBlankLines(body) });
});
return sections;
}
// The markdown of one version's section, without its heading. Throws when the version is not in the changelog.
export function extractVersionSection(changelogText, version) {
const section = parseChangelogSections(changelogText).find((candidate) => candidate.version === version);
if (!section) throw new Error(`CHANGELOG.md has no section for ${version}.`);
return section.body;
}
// Everything a reader or an agent needs: released sections from the changelog, pending entries from the fragments.
export async function readChangelogData({ changelogText, version, folder = fragmentsFolder }) {
const fragments = await readFragments(folder);
const unreleased = fragments.flatMap((fragment) => parseEntries(fragment.text, fragment.name));
const released = parseChangelogSections(changelogText).map((section) => ({ version: section.version, entries: parseEntries(section.body) }));
return { version, released, unreleased };
}
// The body of a changelog section from several fragments. A "### Group" heading groups every line below it until the next
// heading, so a fragment that opens a group would pull the bullets of the next fragment into it, and they would read as
// belonging to that group (as breaking, for "Breaking changes"). Lines without a group come first and each group follows
// once, so every bullet keeps the group its own fragment gave it.
function sectionBody(fragments) {
const plainLines = [];
const groups = new Map();
for (const fragment of fragments) {
let groupLines = plainLines;
for (const line of fragment.text.split('\n')) {
const heading = line.match(groupHeading);
if (heading) {
if (!groups.has(heading[1])) groups.set(heading[1], []);
groupLines = groups.get(heading[1]);
} else {
groupLines.push(line);
}
}
}
const lines = [...plainLines];
for (const [name, groupLines] of groups) lines.push(`### ${name}`, ...groupLines);
return mediaLinesToMarkdown(lines.join('\n'));
}
// The changelog text with a "## Unreleased" section above the released ones, for the site's /changelog.md.
export async function changelogWithUnreleased(changelogText, folder = fragmentsFolder) {
const fragments = await readFragments(folder);
if (fragments.length === 0) return changelogText;
const text = changelogText.replace(/\r\n/g, '\n');
const section = `## Unreleased\n\n${sectionBody(fragments)}\n\n`;
const firstSection = text.search(/^## /m);
return firstSection === -1 ? `${text.replace(/\s+$/, '')}\n\n${section.trimEnd()}\n` : `${text.slice(0, firstSection)}${section}${text.slice(firstSection)}`;
}
// Puts a version section above the newest one. Fragment text is copied as it is, except that media lines become markdown.
export function foldIntoChangelog(changelogText, version, fragments) {
const changelog = changelogText.replace(/\r\n/g, '\n');
if (!semver.test(version)) throw new Error(`Not a valid version: ${version}`);
if (fragments.length === 0) throw new Error('No change fragments to fold.');
if (new RegExp(`^## ${version.replaceAll('.', '\\.')}$`, 'm').test(changelog)) {
throw new Error(`CHANGELOG.md already has a section for ${version}.`);
}
const section = `## ${version}\n\n${sectionBody(fragments)}\n\n`;
const firstSection = changelog.search(/^## /m);
if (firstSection === -1) return `${changelog.replace(/\s+$/, '')}\n\n${section.trimEnd()}\n`;
return `${changelog.slice(0, firstSection)}${section}${changelog.slice(firstSection)}`;
}
async function main() {
const [command, versionArgument] = process.argv.slice(2);
const fragments = await readFragments();
if (command === 'fold') {
const version = versionArgument ?? JSON.parse(await readFile(resolve(root, 'package.json'), 'utf8')).version;
const changelog = await readFile(changelogPath, 'utf8');
await writeFile(changelogPath, foldIntoChangelog(changelog, version, fragments));
for (const fragment of fragments) await rm(resolve(fragmentsFolder, fragment.name));
// Size notes only matter to the pull request that adds them. The release refreshes the size numbers instead.
const sizeNotes = (await readdir(fragmentsFolder)).filter((name) => name.endsWith('.size.md'));
for (const name of sizeNotes) await rm(resolve(fragmentsFolder, name));
console.log(`Folded ${fragments.length} fragments into CHANGELOG.md as ${version}, and removed ${sizeNotes.length} size notes. Run npm run size:release next.`);
return;
}
if (fragments.length === 0) {
console.log('No pending change notes.');
return;
}
for (const fragment of fragments) console.log(`# changes/${fragment.name}\n${fragment.text}\n`);
}
if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) await main();