fix(html): list pages without a document-level stability index (#1061)

The generated index page is built from every page carrying a stability
index, so a document that has none is dropped from the listing.

A document-level stability index is optional. Documents such as `cli`,
`process` and `errors` place stability on their individual sections
instead, and `cli` alone carries 50 of them, so having none at the
document level says nothing about whether the page belongs in a listing
of the documentation.

Against the current nodejs/node docs this drops 13 of 68 pages,
including `module`, the one the issue reports, along with `process`,
`errors` and `cli`. The sidebar, built from the same input by
`buildPageList()`, applies no such filter and lists all of them.

List every page instead, excluding only the index itself, which is the
page doing the listing. The stability badge renders only when the entry
has an index, so a page without one no longer produces an empty badge
labelled `Stability: undefined`.

Fixes: #1055

Signed-off-by: Avocado <ujubongbong@gmail.com>

Author: zeexzeex

.changeset/index-page-missing-docs.md

@@ -0,0 +1,5 @@
+---
+'@doc-kit/generator-react': patch
+---
+
+fix(html): list pages without a document-level stability index

packages/react/src/html/ui/components/DocumentationIndex/index.jsx

@@ -9,7 +9,8 @@ import { documentationIndex } from '#theme/config';
  * @typedef {Object} DocumentationIndexEntry
  * @property {string} api - Basename of the document, linked as `${api}.html`
  * @property {string} name - Human-readable name from the document's heading
- * @property {string} index - Stability index (e.g. `'2'` or `'1.1'`)
+ * @property {string} [index] - Stability index (e.g. `'2'` or `'1.1'`), absent
+ * on documents that carry stability only on their individual sections
  * @property {string} [description] - The document's `llm_description`, or its
  * first paragraph, rendered to HTML at build time
  */
@@ -26,13 +27,15 @@ const IndexEntry = ({ api, name, index, description }) => {
       <span className={styles.title}>
         <span className={styles.name}>{name}</span>
 
-        <Badge
-          size="small"
-          kind={STABILITY_KINDS[level] ?? 'neutral'}
-          aria-label={`Stability: ${index}`}
-        >
-          {label}
-        </Badge>
+        {index !== undefined && (
+          <Badge
+            size="small"
+            kind={STABILITY_KINDS[level] ?? 'neutral'}
+            aria-label={`Stability: ${index}`}
+          >
+            {label}
+          </Badge>
+        )}
       </span>
 
       {description && (

packages/react/src/html/utils/__tests__/config.test.mjs

@@ -52,6 +52,7 @@ const makeEntry = (api, name, path, extra = {}) => ({
   api,
   path,
   heading: { depth: 1, data: { name } },
+  content: { type: 'root', children: [] },
   ...extra,
 });
 
@@ -131,7 +132,7 @@ describe('buildPageList', () => {
 });
 
 describe('buildDocumentationIndex', () => {
-  it('lists only pages with a stability index, with their descriptions', () => {
+  it('lists every page but the index itself, with their descriptions', () => {
     const input = [
       {
         api: 'fs',
@@ -183,6 +184,46 @@ describe('buildDocumentationIndex', () => {
     ]);
   });
 
+  it('keeps pages that carry no document-level stability index', () => {
+    // `process` and `errors` are documented this way: stability lives on their
+    // individual sections rather than on the document.
+    const input = [
+      {
+        api: 'process',
+        path: '/process',
+        heading: { depth: 1, data: { name: 'Process' } },
+        stability: null,
+        llm_description: 'Information about the current process.',
+        content: { type: 'root', children: [] },
+      },
+      {
+        api: 'fs',
+        path: '/fs',
+        heading: { depth: 1, data: { name: 'File System' } },
+        stability: { data: { index: '2' } },
+        llm_description: 'File system APIs.',
+        content: { type: 'root', children: [] },
+      },
+    ];
+
+    const result = buildDocumentationIndex(input);
+
+    assert.deepStrictEqual(result, [
+      {
+        api: 'fs',
+        name: 'File System',
+        index: '2',
+        description: 'File system APIs.',
+      },
+      {
+        api: 'process',
+        name: 'Process',
+        index: undefined,
+        description: 'Information about the current process.',
+      },
+    ]);
+  });
+
   it('renders descriptions to HTML, without the links entries cannot nest', () => {
     const input = [
       {

packages/react/src/html/utils/config.mjs

@@ -116,18 +116,22 @@ export function buildChunkGroups(input) {
 
 /**
  * Pre-compute the entries rendered by the `<DocumentationIndex />` component:
- * every page with a stability index, plus its description.
+ * every page other than the index itself, plus its description.
+ *
+ * A document-level stability index is optional. Documents such as `process`
+ * and `errors` carry stability only on their individual sections, and pages
+ * that list them by document, this one included, still need to link to them.
  *
  * @param {Array<import('@doc-kit/core/generators/metadata/types').MetadataEntry>} input
- * @returns {Array<{api: string, name: string, index: string, description: string}>}
+ * @returns {Array<{api: string, name: string, index: string | undefined, description: string}>}
  */
 export function buildDocumentationIndex(input) {
   return getSortedHeadNodes(input)
-    .filter(entry => entry.stability)
+    .filter(entry => entry.api !== 'index')
     .map(entry => ({
       api: entry.api,
       name: entry.heading.data.name,
-      index: entry.stability.data.index,
+      index: entry.stability?.data.index,
       description: renderAsHTML(parseInline(getEntryDescription(entry), true)),
     }));
 }