/** * Changelog Tests for Cleft Documentation * * Tests the changelog.mdx file for: * - Valid frontmatter (title, description, version, lastUpdated, rss) * - Update component structure (label, description, tags) * - Chronological date ordering (descending) * - Internal link validity * - Image file existence * - Valid tag values * - Content quality checks */ import { readFileSync, existsSync } from 'fs'; import { join, dirname } from 'path'; import { fileURLToPath } from 'url'; import matter from 'gray-matter'; const __filename = fileURLToPath(import.meta.url); const __dirname = dirname(__filename); const ROOT_DIR = join(__dirname, '..'); const CHANGELOG_PATH = join(ROOT_DIR, 'resources', 'changelog.mdx'); // Valid tags for Update components (user-focused filtering) // See CLAUDE.md "Changelog Tags" section for details const VALID_TAGS = [ // Content type 'release', 'policy', 'docs', 'podcast', // Platform 'ios', 'ipados', 'macos', 'watchos', // Temporary status 'pending', // Legacy (for historical entries) 'beta', 'media', 'coming-soon', 'pending-app-store-approval' ]; // Read and parse the changelog file let changelogContent; let frontmatter; let content; beforeAll(() => { changelogContent = readFileSync(CHANGELOG_PATH, 'utf-8'); const parsed = matter(changelogContent); frontmatter = parsed.data; content = parsed.content; }); describe('Changelog Frontmatter', () => { test('has required title field', () => { expect(frontmatter.title).toBeDefined(); expect(frontmatter.title).toBe('Changelog'); }); test('has required description field', () => { expect(frontmatter.description).toBeDefined(); expect(typeof frontmatter.description).toBe('string'); expect(frontmatter.description.length).toBeGreaterThan(10); }); test('has RSS setting defined', () => { // RSS can be true or false depending on release status // false = pending release (disable to prevent premature RSS updates) // true = released (enable for subscriber notifications) expect(frontmatter.rss).toBeDefined(); expect(typeof frontmatter.rss).toBe('boolean'); }); test('has valid version format (semver with v prefix)', () => { expect(frontmatter.version).toBeDefined(); expect(frontmatter.version).toMatch(/^v\d+\.\d+\.\d+$/); }); test('has lastUpdated in valid YYYY-MM-DD format', () => { expect(frontmatter.lastUpdated).toBeDefined(); expect(frontmatter.lastUpdated).toMatch(/^\d{4}-\d{2}-\d{2}$/); // Verify it's a valid date const date = new Date(frontmatter.lastUpdated); expect(date.toString()).not.toBe('Invalid Date'); }); test('lastUpdated is not in the future', () => { const lastUpdated = new Date(frontmatter.lastUpdated); const today = new Date(); today.setHours(23, 59, 59, 999); // End of today expect(lastUpdated <= today).toBe(true); }); }); describe('Update Components Structure', () => { // Extract all Update components with their properties const updateRegex = //g; let updates = []; beforeAll(() => { let match; const regex = new RegExp(updateRegex); while ((match = regex.exec(content)) !== null) { updates.push({ label: match[1], description: match[2], tags: match[3] ? JSON.parse(match[3].replace(/'/g, '"')) : [], fullMatch: match[0] }); } }); test('has at least one Update component', () => { expect(updates.length).toBeGreaterThan(0); }); test('all Updates have valid date labels (Month Day, Year format)', () => { const dateRegex = /^[A-Z][a-z]+ \d{1,2}, \d{4}$/; updates.forEach(update => { expect(update.label).toMatch(dateRegex); }); }); test('all Updates have non-empty descriptions', () => { updates.forEach(update => { expect(update.description).toBeDefined(); expect(update.description.length).toBeGreaterThan(0); }); }); test('all Update tags are from valid tag list', () => { const invalidTags = []; updates.forEach(update => { update.tags.forEach(tag => { if (!VALID_TAGS.includes(tag)) { invalidTags.push({ update: update.label, tag }); } }); }); if (invalidTags.length > 0) { console.log('Invalid tags found:'); invalidTags.forEach(({ update, tag }) => { console.log(` - "${tag}" in update "${update}"`); }); console.log(`Valid tags: ${VALID_TAGS.join(', ')}`); } expect(invalidTags).toHaveLength(0); }); test('no duplicate Update entries (same label AND description)', () => { const combinations = updates.map(u => `${u.label}|${u.description}`); const uniqueCombinations = new Set(combinations); if (combinations.length !== uniqueCombinations.size) { const duplicates = combinations.filter((item, index) => combinations.indexOf(item) !== index); console.log('Duplicate entries found:', duplicates); } expect(combinations.length).toBe(uniqueCombinations.size); }); }); describe('Chronological Order', () => { test('Updates are in descending chronological order (newest first)', () => { const dateRegex = / 0) { console.log('Out of order dates found:'); outOfOrder.forEach(({ current, next }) => { console.log(` - "${current}" appears before "${next}" but is older`); }); } expect(outOfOrder).toHaveLength(0); }); }); describe('Internal Links', () => { test('all internal links reference existing files', () => { // Match markdown links like [text](/path/to/page) const linkRegex = /\[([^\]]+)\]\((\/[^)#\s]+)/g; const brokenLinks = []; let match; while ((match = linkRegex.exec(content)) !== null) { const linkPath = match[2]; // Skip external protocols and anchors if (linkPath.startsWith('http') || linkPath.startsWith('mailto:')) { continue; } // Remove any query string const pathWithoutQuery = linkPath.split('?')[0]; // Check if the file exists (try various extensions) const possiblePaths = [ join(ROOT_DIR, pathWithoutQuery + '.mdx'), join(ROOT_DIR, pathWithoutQuery + '.md'), join(ROOT_DIR, pathWithoutQuery, 'index.mdx'), join(ROOT_DIR, pathWithoutQuery) // For images and other assets ]; const exists = possiblePaths.some(p => existsSync(p)); if (!exists) { brokenLinks.push({ text: match[1], path: linkPath }); } } if (brokenLinks.length > 0) { console.log('Broken internal links found:'); brokenLinks.forEach(link => { console.log(` - [${link.text}](${link.path})`); }); } expect(brokenLinks).toHaveLength(0); }); }); describe('Images', () => { test('all referenced images exist', () => { // Match image references like ![alt](/images/path.gif) const imageRegex = /!\[([^\]]*)\]$(\/[^)]+)$/g; const missingImages = []; let match; while ((match = imageRegex.exec(content)) !== null) { const imagePath = match[2]; const fullPath = join(ROOT_DIR, imagePath); if (!existsSync(fullPath)) { missingImages.push({ alt: match[1] || '(no alt text)', path: imagePath }); } } if (missingImages.length > 0) { console.log('Missing images found:'); missingImages.forEach(img => { console.log(` - ${img.path} (alt: "${img.alt}")`); }); } expect(missingImages).toHaveLength(0); }); test('all images have alt text (accessibility)', () => { // Match images with empty alt text: ![](/path) const emptyAltRegex = /!\[\]$\/[^)]+$/g; const imagesWithoutAlt = content.match(emptyAltRegex) || []; if (imagesWithoutAlt.length > 0) { console.log('Images without alt text (accessibility issue):'); imagesWithoutAlt.forEach(img => { console.log(` - ${img}`); }); } expect(imagesWithoutAlt).toHaveLength(0); }); }); describe('Content Quality', () => { test('no TODO/FIXME comments left in content', () => { const todoRegex = /\bTODO\b|\bFIXME\b|\bXXX\b|\bHACK\b/gi; const matches = content.match(todoRegex) || []; if (matches.length > 0) { console.log('TODO/FIXME comments found in changelog - these should be resolved'); } expect(matches).toHaveLength(0); }); test('version numbers in descriptions follow semver pattern', () => { // Match Version X.Y.Z or vX.Y.Z patterns const versionRegex = /(?:Version|v)\s*(\d+\.\d+\.\d+)/gi; const invalidVersions = []; let match; while ((match = versionRegex.exec(content)) !== null) { const version = match[1]; if (!/^\d+\.\d+\.\d+$/.test(version)) { invalidVersions.push(version); } } expect(invalidVersions).toHaveLength(0); }); test('external links use HTTPS (not HTTP)', () => { // Find HTTP links (not HTTPS), excluding localhost const httpRegex = /\]$http:\/\/(?!localhost)/g; const httpLinks = content.match(httpRegex) || []; if (httpLinks.length > 0) { console.log('Insecure HTTP links found (should use HTTPS):'); // Find the full URLs for reporting const fullHttpRegex = /\[([^\]]+)\]\((http:\/\/[^)]+)$/g; let urlMatch; while ((urlMatch = fullHttpRegex.exec(content)) !== null) { if (!urlMatch[2].includes('localhost')) { console.log(` - [${urlMatch[1]}](${urlMatch[2]})`); } } } expect(httpLinks).toHaveLength(0); }); test('email links have valid format', () => { // Match mailto links const mailtoRegex = /mailto:([^?\s)"]+)/g; const invalidEmails = []; let match; while ((match = mailtoRegex.exec(content)) !== null) { const email = match[1]; // Basic email validation if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) { invalidEmails.push(email); } } if (invalidEmails.length > 0) { console.log('Invalid email addresses found:'); invalidEmails.forEach(email => console.log(` - ${email}`)); } expect(invalidEmails).toHaveLength(0); }); test('all Update components are properly closed', () => { const openTags = (content.match(//g) || []).length; if (openTags !== closeTags) { console.log(`Mismatched Update tags: ${openTags} opening, ${closeTags} closing`); } expect(openTags).toBe(closeTags); }); }); describe('Accessibility', () => { test('headings follow proper hierarchy (no skipped levels)', () => { // Extract headings from the content const headingRegex = /^(#{1,6})\s+(.+)$/gm; const headings = []; let match; while ((match = headingRegex.exec(content)) !== null) { headings.push({ level: match[1].length, text: match[2].trim() }); } const skippedLevels = []; for (let i = 1; i < headings.length; i++) { const prevLevel = headings[i - 1].level; const currLevel = headings[i].level; // Going deeper should only increase by 1 if (currLevel > prevLevel && currLevel - prevLevel > 1) { skippedLevels.push({ from: `h${prevLevel}: "${headings[i - 1].text}"`, to: `h${currLevel}: "${headings[i].text}"`, skipped: currLevel - prevLevel - 1 }); } } if (skippedLevels.length > 0) { console.log('Skipped heading levels (accessibility issue):'); skippedLevels.forEach(skip => { console.log(` - ${skip.from} → ${skip.to} (skipped ${skip.skipped} level(s))`); }); } expect(skippedLevels).toHaveLength(0); }); }); describe('Release Consistency', () => { test('release updates have version info in description OR body', () => { // This is an informational test - version can be in description or body // Extract Update blocks with their full content const updateBlockRegex = /([\s\S]*?)<\/Update>/g; const releasesWithoutVersion = []; let match; while ((match = updateBlockRegex.exec(content)) !== null) { const label = match[1]; const description = match[2]; const tagsStr = match[3]; const body = match[4]; if (tagsStr) { const tags = JSON.parse(tagsStr.replace(/'/g, '"')); // Check if it's a release or beta tag if (tags.includes('release') || tags.includes('beta')) { // Version can be in description OR in the body (first few lines) const hasVersionInDesc = /v?\d+\.\d+\.\d+/i.test(description); const hasVersionInBody = /(?:Version|Build|v)\s*\d+\.\d+/i.test(body.slice(0, 500)); if (!hasVersionInDesc && !hasVersionInBody) { releasesWithoutVersion.push({ label, description, tags }); } } } } if (releasesWithoutVersion.length > 0) { console.log('⚠️ Releases without version info (consider adding):'); releasesWithoutVersion.forEach(({ label, description }) => { console.log(` - ${label}: "${description}"`); }); } // Informational - don't fail, just report expect(true).toBe(true); }); test('major releases (not beta) include version in description', () => { // For non-beta releases, we recommend version in description for clarity const updateRegex = //g; const missingVersions = []; let match; while ((match = updateRegex.exec(content)) !== null) { const label = match[1]; const description = match[2]; const tagsStr = match[3]; if (tagsStr) { const tags = JSON.parse(tagsStr.replace(/'/g, '"')); // Only check full releases (not beta), and only recent ones (2025+) if (tags.includes('release') && !tags.includes('beta')) { const year = parseInt(label.match(/\d{4}/)?.[0] || '0'); if (year >= 2025) { const hasVersion = /v?\d+\.\d+\.\d+/i.test(description); if (!hasVersion) { missingVersions.push({ label, description }); } } } } } if (missingVersions.length > 0) { console.log('2025+ releases without version in description:'); missingVersions.forEach(({ label, description }) => { console.log(` - ${label}: "${description}"`); }); } // Informational for now - can make strict later expect(true).toBe(true); }); });

Welcome to Cleft

​🔍 Looking for all features?

🔍 Looking for all features?