Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
#!/usr/bin/env node
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { parse } from 'parse5';
import {
compareSemver,
isStableCoreVersion,
parseSemver,
validateLocalRelease,
validateStableUpdateManifest,
} from '../archify/scripts/update-contract.mjs';
const scriptRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const rootFlag = process.argv.indexOf('--root');
const repoRoot = rootFlag === -1 ? scriptRoot : path.resolve(process.argv[rootFlag + 1] || '');
const failures = [];
function fail(message) {
failures.push(message);
}
function read(relativePath) {
try {
return fs.readFileSync(path.join(repoRoot, relativePath), 'utf8');
} catch {
fail(`${relativePath} is missing or unreadable.`);
return '';
}
}
function readJson(relativePath) {
const source = read(relativePath);
if (!source) return {};
try {
return JSON.parse(source);
} catch {
fail(`${relativePath} is not valid JSON.`);
return {};
}
}
function checkSkillRelease(value, version, isDevelopment) {
const expectedChannel = isDevelopment ? 'development' : 'stable';
try {
const release = validateLocalRelease(value);
if (release.version === version && release.channel === expectedChannel) return;
} catch {
// Report the repository-specific cross-artifact requirement below.
}
fail(`archify/skill-release.json must identify archify ${version} as ${expectedChannel}, use the official repository, and pin the trusted update manifest URL.`);
}
function checkStableUpdateManifest(value, expectedVersion, previousVersion, packageVersion, isDevelopment) {
try {
const manifest = validateStableUpdateManifest(value);
const allowedVersions = isDevelopment
? [expectedVersion]
: [expectedVersion, previousVersion].filter(Boolean);
if (expectedVersion && allowedVersions.includes(manifest.version)
&& (isDevelopment || packageVersion === expectedVersion)) return;
} catch {
// Report the repository-specific cross-artifact requirement below.
}
const releaseWindow = !isDevelopment && previousVersion
? `newest stable v${expectedVersion} or immediate prior v${previousVersion} during the enforced post-Release publication window`
: `newest published stable v${expectedVersion || '(missing)'}`;
fail(`docs/skill-updates/archify/stable.json must describe the ${releaseWindow} with the fixed repository, immutable tree/archive digests, and official release-notes URL.`);
}
function shieldEscape(value) {
return value.replaceAll('_', '__').replaceAll('-', '--');
}
function versionLabels(source) {
return [...source.matchAll(/\bv(\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?)\b/g)]
.map((match) => match[1]);
}
const readmeMarkers = {
en: { development: 'Current development version:', stable: 'Current stable version:' },
zh: { development: '当前开发版本:', stable: '当前稳定版本:' },
ja: { development: '現在の開発版:', stable: '現在の安定版:' },
};
function checkReadme(relativePath, source, version, language, isDevelopment) {
const badge = `/badge/version-${shieldEscape(version)}-`;
const markerLabel = readmeMarkers[language][isDevelopment ? 'development' : 'stable'];
const identity = isDevelopment ? 'development' : 'stable';
const hasMarker = source.split('\n').some((line) => line.includes(markerLabel) && line.includes(`\`v${version}\``));
if (!source.includes(badge) || !hasMarker) {
fail(`${relativePath} must advertise ${identity} identity v${version} with an exact escaped badge and explicit ${identity} marker.`);
}
}
function checkDocument(relativePath, source, version, isDevelopment) {
const labels = versionLabels(source);
const identity = isDevelopment ? 'development' : 'stable';
const englishLabel = isDevelopment ? /development/i : /stable/i;
const chineseLabel = isDevelopment ? /开发版/ : /稳定版/;
if (labels.length === 0 || labels.some((label) => label !== version)
|| !englishLabel.test(source) || !chineseLabel.test(source)) {
fail(`${relativePath} must advertise ${identity} identity v${version} in both languages without a conflicting version alias.`);
}
}
function checkNoRavenSwitcher(relativePath, source) {
if (/data-agent=["']raven["']|--agent\s+raven\b|[?&]agent=raven\b/i.test(source)) {
fail(`${relativePath}: Raven is not an agent-switcher target.`);
}
}
function checkIdentityTemplate(relativePath, source, isDevelopment) {
// SVG path coordinates can resemble SemVer (for example, `4.3.6-3.1`).
// Remove only real SVG d attributes, not path-like text inside other
// attributes or scripts. Keep the original bytes everywhere else.
const pathDataRanges = [];
function collectPathData(node) {
const location = node.sourceCodeLocation?.attrs?.d;
if (node.namespaceURI === 'http://www.w3.org/2000/svg' && node.tagName === 'path' && location) {
pathDataRanges.push(location);
}
for (const child of node.childNodes || []) collectPathData(child);
if (node.content) collectPathData(node.content);
}
collectPathData(parse(source, { sourceCodeLocationInfo: true }));
let sourceWithoutPathData = source;
for (const { startOffset, endOffset } of pathDataRanges.sort((a, b) => b.startOffset - a.startOffset)) {
sourceWithoutPathData = sourceWithoutPathData.slice(0, startOffset) + sourceWithoutPathData.slice(endOffset);
}
const hasHardcodedVersion = /\b\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?\b/.test(sourceWithoutPathData);
const identity = isDevelopment ? 'development and 开发版' : 'stable and 稳定版';
const hasIdentity = isDevelopment
? /development/i.test(source) && /开发版/.test(source)
: /stable/i.test(source) && /稳定版/.test(source);
if (!source.includes('[[ARCHIFY_VERSION]]') || !hasIdentity || hasHardcodedVersion) {
fail(`${relativePath} must use [[ARCHIFY_VERSION]] with ${identity} labels, never a hardcoded package version.`);
}
const versionLines = source.split('\n').filter(line => line.includes('[[ARCHIFY_VERSION]]'));
const staleIdentity = isDevelopment ? /\bstable\b|稳定版/i : /\bdevelopment\b|开发版/i;
if (versionLines.some(line => staleIdentity.test(line))) {
const staleLabel = isDevelopment ? 'stable or 稳定版' : 'development or 开发版';
fail(`${relativePath} must not label [[ARCHIFY_VERSION]] as ${staleLabel}.`);
}
}
function checkRoadmap(relativePath, source, version, isDevelopment) {
const identity = isDevelopment ? 'development line' : 'stable version';
const marker = `The current ${identity} is \`v${version}\``;
if (!source.includes(marker)) {
fail(`${relativePath} must declare the current ${identity} as v${version}.`);
}
}
const packageJson = readJson('archify/package.json');
const changelog = read('CHANGELOG.md');
const unreleasedStart = changelog.search(/^## \[Unreleased\][^\n]*(?:\n|$)/m);
const afterUnreleased = unreleasedStart === -1
? ''
: changelog.slice(unreleasedStart).replace(/^## \[Unreleased\][^\n]*(?:\n|$)/, '');
const nextRelease = afterUnreleased.search(/^## \[/m);
const unreleased = nextRelease === -1 ? afterUnreleased : afterUnreleased.slice(0, nextRelease);
const hasRealUnreleasedChanges = /^\s*-\s+\S/m.test(unreleased);
const version = packageJson.version;
let parsedVersion = null;
try {
parsedVersion = parseSemver(version);
} catch {
// The consolidated error below owns package-version policy reporting.
}
const supportedPrerelease = parsedVersion?.prerelease === null
|| (parsedVersion?.prerelease?.length === 2
&& parsedVersion.prerelease[0] === 'dev'
&& /^\d+$/.test(parsedVersion.prerelease[1]));
const hasSupportedVersion = Boolean(parsedVersion && parsedVersion.build === null && supportedPrerelease);
const isDevelopment = Boolean(hasSupportedVersion && parsedVersion.prerelease);
const publishedLabels = [...changelog.matchAll(/^## \[([^\]]+)\]/gm)]
.map((match) => match[1])
.filter((label) => label !== 'Unreleased');
for (const label of publishedLabels) {
if (!isStableCoreVersion(label)) fail(`CHANGELOG published version is not stable SemVer: ${label}.`);
}
const stableLabels = publishedLabels
.filter(isStableCoreVersion)
.sort((left, right) => compareSemver(right, left));
const newestStableLabel = stableLabels[0] ?? null;
const previousStableLabel = stableLabels[1] ?? null;
if (!hasSupportedVersion) {
fail(`package version is not a supported SemVer identity: ${JSON.stringify(version)}`);
} else if (hasRealUnreleasedChanges && !isDevelopment) {
fail(`Unreleased changes require a prerelease package version; found stable ${version}.`);
}
if (hasSupportedVersion && hasRealUnreleasedChanges) {
const currentCore = parsedVersion.core.join('.');
if (newestStableLabel && compareSemver(currentCore, newestStableLabel) <= 0) {
fail(`Unreleased package core ${currentCore} must be newer than published ${newestStableLabel}.`);
}
}
if (hasSupportedVersion) {
checkSkillRelease(readJson('archify/skill-release.json'), version, isDevelopment);
checkStableUpdateManifest(
readJson('docs/skill-updates/archify/stable.json'),
newestStableLabel,
previousStableLabel,
version,
isDevelopment,
);
const lock = readJson('archify/package-lock.json');
if (lock.version !== version || lock.packages?.['']?.version !== version) {
fail(`archify/package-lock.json must match ${version} at the root and packages[""].`);
}
const skill = read('archify/SKILL.md');
const skillVersion = skill.match(/^\s*version:\s*["']?([^"'\s]+)["']?\s*$/m)?.[1];
const expectedSkillVersion = `${parsedVersion.core[0]}.${parsedVersion.core[1]}`;
if (skillVersion !== expectedSkillVersion) {
fail(`archify/SKILL.md metadata version ${skillVersion || '(missing)'} must map to package ${version} as ${expectedSkillVersion}.`);
}
const rendererTemplate = read('archify/assets/template.html');
const generatorVersions = [...rendererTemplate.matchAll(/<meta\s+name="generator"\s+content="archify\s+([^"]+)"\s*\/?>/g)]
.map((match) => match[1]);
if (generatorVersions.length !== 1 || generatorVersions[0] !== version) {
fail(`archify/assets/template.html generator must be archify ${version}; found ${generatorVersions.join(', ') || '(missing)'}.`);
}
const english = read('README.md');
const englishMirror = read('README_EN.md');
const chinese = read('README_ZH.md');
const japanese = read('README_JA.md');
checkReadme('README.md', english, version, 'en', isDevelopment);
checkReadme('README_EN.md', englishMirror, version, 'en', isDevelopment);
checkReadme('README_ZH.md', chinese, version, 'zh', isDevelopment);
checkReadme('README_JA.md', japanese, version, 'ja', isDevelopment);
for (const [path, content] of [['README.md', english], ['README_EN.md', englishMirror], ['README_ZH.md', chinese], ['README_JA.md', japanese]]) {
checkNoRavenSwitcher(path, content);
}
if (english !== englishMirror) fail('README_EN.md must remain byte-identical to README.md.');
if (newestStableLabel && isDevelopment) {
const stableMinor = newestStableLabel.split('.').slice(0, 2).join('\\.');
if (new RegExp(`Archify ${stableMinor} includes\\b`).test(english)
|| new RegExp(`Archify ${stableMinor} 已覆盖`).test(chinese)) {
fail(`README capability summary must describe v${version} as development, not published ${newestStableLabel}.`);
}
}
const landing = read('docs/index.html');
checkDocument('docs/index.html', landing, version, isDevelopment);
checkNoRavenSwitcher('docs/index.html', landing);
const proofCounts = [...landing.matchAll(/\b\d+\/\d+\b/g)].map((match) => match[0]);
const staleProofCounts = [...new Set(proofCounts.filter((count) => count !== '9/9'))];
if (proofCounts.length === 0 || staleProofCounts.length > 0) {
const found = staleProofCounts.length > 0 ? `; found ${staleProofCounts.join(', ')}` : '';
fail(`docs/index.html proof receipt must say 9/9 everywhere; every N/N proof receipt must be exactly 9/9${found}.`);
}
const start = read('docs/start.html');
checkDocument('docs/start.html', start, version, isDevelopment);
checkNoRavenSwitcher('docs/start.html', start);
checkRoadmap('ROADMAP.md', read('ROADMAP.md'), version, isDevelopment);
for (const templatePath of [
'scripts/start-template.html',
'scripts/guide-template.html',
'scripts/gallery-template.html',
]) {
checkIdentityTemplate(templatePath, read(templatePath), isDevelopment);
}
const changelogMarker = `Development identity: \`v${version}\``;
if (hasRealUnreleasedChanges && !unreleased.includes(changelogMarker)) {
fail(`CHANGELOG.md Unreleased must declare ${changelogMarker}.`);
}
}
if (failures.length > 0) {
for (const message of failures) console.error(`release identity: ${message}`);
process.exit(1);
}
console.log(`release identity ok: ${version}`);