feat: add tests for build post list script

scripts/build-post-list.js

@@ -1,5 +1,5 @@
-const { readdirSync, statSync, existsSync, readFileSync, writeFileSync } = require('fs')
-const { resolve, basename } = require('path')
+const { readdir, stat, pathExists, readFile, writeFile } = require('fs-extra')
+const { basename, join, normalize, sep, posix, relative, extname } = require('path')
 const frontMatter = require('gray-matter')
 const toc = require('markdown-toc')
 const { slugify } = require('markdown-toc/lib/utils')
@@ -15,51 +15,55 @@ const result = {
   docsTree: {}
 }
 const releaseNotes = []
-const basePath = 'pages'
-const postDirectories = [
-  // order of these directories is important, as the blog should come before docs, to create a list of available release notes, which will later be used to release-note-link for spec docs
-  [`${basePath}/blog`, '/blog'],
-  [`${basePath}/docs`, '/docs'],
-  [`${basePath}/about`, '/about']
-];
 
 const addItem = (details) => {
-  if(details.slug.startsWith('/docs'))
+  if (details.slug.startsWith('/docs'))
     result["docs"].push(details)
-  else if(details.slug.startsWith('/blog'))
+  else if (details.slug.startsWith('/blog'))
     result["blog"].push(details)
-  else if(details.slug.startsWith('/about'))
+  else if (details.slug.startsWith('/about'))
     result["about"].push(details)
-  else {}
-}
+};
+
+async function buildPostList(postDirectories, basePath, writeFilePath) {
+  try {
+
+    if (!basePath || !writeFilePath) {
+            throw new Error('Error while building post list: basePath and writeFilePath are required');
+    }
 
-module.exports = async function buildPostList() {
-  walkDirectories(postDirectories, result)
-  const treePosts = buildNavTree(result["docs"].filter((p) => p.slug.startsWith('/docs/')))
-  result["docsTree"] = treePosts
-  result["docs"] = addDocButtons(result["docs"], treePosts)
-  if (process.env.NODE_ENV === 'production') {
-    // console.log(inspect(result, { depth: null, colors: true }))
+    if (postDirectories.length === 0) {
+      throw new Error('Error while building post list: No post directories provided');
+    }
+    const normalizedBasePath = normalize(basePath)
+    await walkDirectories(postDirectories, result, normalizedBasePath)
+    const treePosts = buildNavTree(result["docs"].filter((p) => p.slug.startsWith('/docs/')))
+    result["docsTree"] = treePosts
+    result["docs"] = addDocButtons(result["docs"], treePosts)
+    await writeFile(writeFilePath, JSON.stringify(result, null, '  '))
+  } catch (error) {
+    throw new Error(`Error while building post list: ${error.message}`, { cause: error });
   }
-  writeFileSync(resolve(__dirname, '..', 'config', 'posts.json'), JSON.stringify(result, null, '  '))
 }
 
-function walkDirectories(directories, result, sectionWeight = 0, sectionTitle, sectionId, rootSectionId) {
+async function walkDirectories(directories, result, basePath, sectionWeight = 0, sectionTitle, sectionId, rootSectionId) {
   for (let dir of directories) {
-    let directory = dir[0]
-    let sectionSlug = dir[1] || ''
-    let files = readdirSync(directory);
+    let directory = posix.normalize(dir[0]);
+    let sectionSlug = dir[1] || '';
+    let files = await readdir(directory)
 
     for (let file of files) {
-      let details
-      const fileName = [directory, file].join('/')
-      const fileNameWithSection = [fileName, '_section.mdx'].join('/')
-      const slug = fileName.replace(new RegExp(`^${basePath}`), '')
-      const slugElements = slug.split('/');
-      if (isDirectory(fileName)) {
-        if (existsSync(fileNameWithSection)) {
+      let details;
+      const fileName = posix.join(directory, file);
+      const fileNameWithSection = posix.join(fileName, '_section.mdx')
+      const normalizedSlug = posix.join('/', relative(basePath, fileName))
+      const slug = normalizedSlug.replace(/\\/g,'/')
+      const slugElements = slug.split('/')
+
+      if (await isDirectory(fileName)) {
+        if (await pathExists(fileNameWithSection)) {
           // Passing a second argument to frontMatter disables cache. See https://github.com/asyncapi/website/issues/1057
-          details = frontMatter(readFileSync(fileNameWithSection, 'utf-8'), {}).data
+          details = frontMatter(await readFile(fileNameWithSection, 'utf-8'), {}).data
           details.title = details.title || capitalize(basename(fileName))
         } else {
           details = {
@@ -68,8 +72,8 @@ function walkDirectories(directories, result, sectionWeight = 0, sectionTitle, s
         }
         details.isSection = true
         if (slugElements.length > 3) {
-           details.parent = slugElements[slugElements.length - 2]
-           details.sectionId = slugElements[slugElements.length - 1]
+          details.parent = slugElements[slugElements.length - 2]
+          details.sectionId = slugElements[slugElements.length - 1]
         }
         if (!details.parent) {
           details.isRootSection = true
@@ -79,9 +83,9 @@ function walkDirectories(directories, result, sectionWeight = 0, sectionTitle, s
         details.slug = slug
         addItem(details)
         const rootId = details.parent || details.rootSectionId
-        walkDirectories([[fileName, slug]], result, details.weight, details.title, details.sectionId, rootId)
-      } else if (file.endsWith('.mdx') && !fileName.endsWith('/_section.mdx')) {
-        const fileContent = readFileSync(fileName, 'utf-8')
+        await walkDirectories([[fileName, slug]], result, basePath, details.weight, details.title, details.sectionId, rootId)
+      } else if (file.endsWith('.mdx') && !fileName.endsWith(sep + '_section.mdx')) {
+        const fileContent = await readFile(fileName, 'utf-8')
         // Passing a second argument to frontMatter disables cache. See https://github.com/asyncapi/website/issues/1057
         const { data, content } = frontMatter(fileContent, {})
         details = data
@@ -93,21 +97,21 @@ function walkDirectories(directories, result, sectionWeight = 0, sectionTitle, s
         details.sectionTitle = sectionTitle
         details.sectionId = sectionId
         details.rootSectionId = rootSectionId
-        details.id = fileName
-        details.isIndex = fileName.endsWith('/index.mdx')
+        details.id = fileName.replace(/\\/g, '/')
+        details.isIndex = fileName.endsWith(join('index.mdx'))
         details.slug = details.isIndex ? sectionSlug : slug.replace(/\.mdx$/, '')
-        if(details.slug.includes('/reference/specification/') && !details.title) {
+        if (details.slug.includes('/reference/specification/') && !details.title) {
           const fileBaseName = basename(data.slug)  // ex. v2.0.0 | v2.1.0-next-spec.1
           const fileName = fileBaseName.split('-')[0] // v2.0.0 | v2.1.0
           details.weight = specWeight--
 
           if (fileName.startsWith('v')) {
-             details.title = capitalize(fileName.slice(1)) 
+            details.title = capitalize(fileName.slice(1))
           } else {
             details.title = capitalize(fileName)
           }
 
-          if(releaseNotes.includes(details.title)){
+          if (releaseNotes.includes(details.title)) {
             details.releaseNoteLink = `/blog/release-notes-${details.title}`
           }
 
@@ -122,12 +126,12 @@ function walkDirectories(directories, result, sectionWeight = 0, sectionTitle, s
         }
 
         // To create a list of available ReleaseNotes list, which will be used to add details.releaseNoteLink attribute.
-        if(file.startsWith("release-notes") && dir[1] === "/blog"){
-          const fileName_without_extension = file.slice(0,-4)
+        if (file.startsWith("release-notes") && dir[1] === "/blog") {
+          const fileNameWithoutExtension = basename(file, extname(file))
           // removes the file extension. For example, release-notes-2.1.0.md -> release-notes-2.1.0
-          const version = fileName_without_extension.slice(fileName_without_extension.lastIndexOf("-")+1)
+          const version = fileNameWithoutExtension.slice(fileNameWithoutExtension.lastIndexOf("-") + 1)
 
-          // gets the version from the name of the releaseNote .md file (from /blog). For example, version = 2.1.0 if fileName_without_extension = release-notes-2.1.0
+          // gets the version from the name of the releaseNote .md file (from /blog). For example, version = 2.1.0 if fileNameWithoutExtension = release-notes-2.1.0
           releaseNotes.push(version)
           // releaseNotes is the list of all available releaseNotes
         }
@@ -152,10 +156,12 @@ function slugifyToC(str) {
   return slug || slugify(str, { firsth1: true, maxdepth: 6 })
 }
 
-function isDirectory(dir) {
-  return statSync(dir).isDirectory()
+async function isDirectory(dir) {
+  return (await stat(dir)).isDirectory()
 }
 
 function capitalize(text) {
   return text.split(/[\s\-]/g).map(word => `${word[0].toUpperCase()}${word.substr(1)}`).join(' ')
 }
+
+module.exports = { slugifyToC, buildPostList }

scripts/index.js

@@ -1,13 +1,23 @@
 const { resolve } = require('path');
 const fs = require('fs');
 const rssFeed = require('./build-rss');
-const buildPostList = require('./build-post-list');
+const { buildPostList } = require('./build-post-list');
 const buildCaseStudiesList = require('./casestudies');
 const buildAdoptersList = require('./adopters');
 const buildFinanceInfoList = require('./finance');
 
 async function start() {
-  await buildPostList();
+
+  const postDirectories = [
+    ['pages/blog', '/blog'],
+    ['pages/docs', '/docs'],
+    ['pages/about', '/about']
+  ];
+  const basePath = 'pages';
+  const writeFilePath = resolve(__dirname, '../config', 'posts.json');
+
+  await buildPostList(postDirectories, basePath, writeFilePath);
+
   rssFeed(
     'blog',
     'AsyncAPI Initiative Blog RSS Feed',

tests/build-post-list.test.js

@@ -0,0 +1,161 @@
+const fs = require('fs-extra');
+const { resolve, join, normalize } = require('path');
+const { buildPostList, slugifyToC } = require('../scripts/build-post-list');
+
+describe('buildPostList', () => {
+  let tempDir;
+  let writeFilePath;
+  let postDirectories;
+
+  beforeEach(async () => {
+    tempDir = resolve(__dirname, `test-config`);
+    writeFilePath = resolve(tempDir, 'posts.json');
+    postDirectories = [
+      [join(tempDir, 'blog'), '/blog'],
+      [join(tempDir, 'docs'), '/docs'],
+      [join(tempDir, 'about'), '/about'],
+    ];
+
+    const normalizedDir = normalize(join(tempDir, 'blog'));
+    await fs.ensureDir(normalizedDir);
+
+    await fs.ensureDir(join(tempDir, 'blog'));
+    await fs.writeFile(join(tempDir, 'blog', 'release-notes-2.1.0.mdx'), '---\ntitle: Release Notes 2.1.0\n---\nThis is a release note.');
+
+    await fs.ensureDir(join(tempDir, 'docs'));
+    await fs.writeFile(join(tempDir, 'docs', 'index.mdx'), '---\ntitle: Docs Home\n---\nThis is the documentation homepage.');
+
+    await fs.ensureDir(join(tempDir, 'about'));
+    await fs.writeFile(join(tempDir, 'about', 'index.mdx'), '---\ntitle: About Us\n---\nThis is the about page.');
+
+    await fs.ensureDir(join(tempDir, 'docs', 'reference', 'specification'));
+  });
+
+  afterEach(async () => {
+    await fs.remove(tempDir);
+  });
+
+  it('builds a post list and writes the result to a file', async () => {
+    await buildPostList(postDirectories, tempDir, writeFilePath);
+
+    const outputExists = await fs.pathExists(writeFilePath);
+    expect(outputExists).toBe(true);
+
+    const output = JSON.parse(await fs.readFile(writeFilePath, 'utf-8'));
+
+    expect(output).toHaveProperty('docs');
+    expect(output).toHaveProperty('blog');
+    expect(output).toHaveProperty('about');
+    expect(output).toHaveProperty('docsTree');
+
+    const blogEntry = output.blog.find(item => item.slug === '/blog/release-notes-2.1.0');
+    expect(blogEntry).toBeDefined();
+    expect(blogEntry.title).toBe('Release Notes 2.1.0');
+  });
+
+  it('handles a directory with only section files', async () => {
+    await fs.ensureDir(join(tempDir, 'docs', 'section1'));
+    await fs.writeFile(join(tempDir, 'docs', 'section1', '_section.mdx'), '---\ntitle: Section 1\n---\nThis is section 1.');
+
+    await buildPostList(postDirectories, tempDir, writeFilePath);
+
+    const output = JSON.parse(await fs.readFile(writeFilePath, 'utf-8'));
+
+    expect(output.docs.length).toBeGreaterThan(0);
+    expect(output.docs.find(item => item.title === 'Section 1')).toBeDefined();
+  });
+
+  it('handles multiple release notes correctly', async () => {
+    await fs.writeFile(join(tempDir, 'blog', 'release-notes-2.1.1.mdx'), '---\ntitle: Release Notes 2.1.1\n---\nThis is a release note.');
+
+    await buildPostList(postDirectories, tempDir, writeFilePath);
+
+    const output = JSON.parse(await fs.readFile(writeFilePath, 'utf-8'));
+
+    const firstReleaseNote = output.blog.find(item => item.slug === '/blog/release-notes-2.1.0');
+    const secondReleaseNote = output.blog.find(item => item.slug === '/blog/release-notes-2.1.1');
+
+    expect(firstReleaseNote).toBeDefined();
+    expect(firstReleaseNote.title).toBe('Release Notes 2.1.0');
+
+    expect(secondReleaseNote).toBeDefined();
+    expect(secondReleaseNote.title).toBe('Release Notes 2.1.1');
+  });
+
+  it('handles errors gracefully', async () => {
+    const invalidDir = [join(tempDir, 'non-existent-dir'), '/invalid'];
+    await expect(buildPostList([invalidDir], tempDir, writeFilePath)).rejects.toThrow();
+  });
+
+  it('does not process specification files without a title', async () => {
+    const specDir = join(tempDir, 'docs', 'reference', 'specification');
+    await fs.writeFile(join(specDir, 'v2.1.0-no-title.mdx'), '---\n---\nContent of specification without a title.');
+
+    await buildPostList(postDirectories, tempDir, writeFilePath);
+
+    const output = JSON.parse(await fs.readFile(writeFilePath, 'utf-8'));
+    const noTitleEntry = output.docs.find(item => item.slug.includes('/reference/specification/v2.1.0-no-title'));
+
+    expect(noTitleEntry).toBeUndefined();
+  });
+
+  it('does not process specification files with "next-spec" in the filename', async () => {
+    const specDir = join(tempDir, 'docs', 'reference', 'specification');
+    await fs.writeFile(join(specDir, 'v2.1.0-next-spec.1.mdx'), '---\n---\nContent of pre-release specification v2.1.0-next-spec.1.');
+
+    await buildPostList(postDirectories, tempDir, writeFilePath);
+
+    const output = JSON.parse(await fs.readFile(writeFilePath, 'utf-8'));
+    const nextSpecEntry = output.docs.find(item => item.slug.includes('/reference/specification/v2.1.0-next-spec.1'));
+
+    expect(nextSpecEntry).toBeUndefined();
+  });
+
+  it('does not process specification files with "explorer" in the filename', async () => {
+    const specDir = join(tempDir, 'docs', 'reference', 'specification');
+    await fs.writeFile(join(specDir, 'explorer.mdx'), '---\n---\nContent of explorer specification.');
+
+    await buildPostList(postDirectories, tempDir, writeFilePath);
+
+    const output = JSON.parse(await fs.readFile(writeFilePath, 'utf-8'));
+    const explorerEntry = output.docs.find(item => item.slug.includes('/reference/specification/explorer'));
+
+    expect(explorerEntry).toBeUndefined();
+  });
+
+  it('throws an error if the front matter cannot be parsed', async () => {
+    await fs.writeFile(join(tempDir, 'docs', 'invalid.mdx'), '---\ninvalid front matter\n---\nContent');
+
+    await expect(buildPostList(postDirectories, tempDir, writeFilePath)).rejects.toThrow(/Error while building post list/);
+  });
+
+  it('throws an error if no post directories are provided', async () => {
+    await expect(buildPostList([], tempDir, writeFilePath)).rejects.toThrow(/Error while building post list/);
+  });
+
+  it('throws an error if basePath is missing', async () => {
+    await expect(buildPostList(postDirectories, undefined, writeFilePath)).rejects.toThrow(/Error while building post list: basePath and writeFilePath are required/);
+  });
+
+  it('throws an error if writeFilePath is missing', async () => {
+    await expect(buildPostList(postDirectories, tempDir, undefined)).rejects.toThrow(/Error while building post list: basePath and writeFilePath are required/);
+  });  
+
+  describe('slugifyToC', () => {
+
+    it('handles heading ids like {# myHeadingId}', () => {
+      const input = '## My Heading {#custom-id}';
+      expect(slugifyToC(input)).toBe('custom-id');
+    });
+
+    it('handles heading ids like {<a name="myHeadingId"/>}', () => {
+      const input = '## My Heading {<a name="custom-anchor-id"/>}';
+      expect(slugifyToC(input)).toBe('custom-anchor-id');
+    });
+
+    it('handles empty strings', () => {
+      expect(slugifyToC('')).toBe('');
+    });
+
+  });
+});

tests/index.test.js

@@ -1,5 +1,5 @@
 const rssFeed = require('../scripts/build-rss');
-const buildPostList = require('../scripts/build-post-list');
+const { buildPostList } = require('../scripts/build-post-list');
 const buildCaseStudiesList = require('../scripts/casestudies');
 const buildAdoptersList = require('../scripts/adopters');
 const buildFinanceInfoList = require('../scripts/finance');