@open-mercato/cli 0.6.8-develop.6961.1.5b7ca407e7 → 0.6.8-develop.6963.1.04a6d320e9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cli",
-  "version": "0.6.8-develop.6961.1.5b7ca407e7",
+  "version": "0.6.8-develop.6963.1.04a6d320e9",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -60,9 +60,9 @@
     "@mikro-orm/decorators": "^7.1.8",
     "@mikro-orm/migrations": "^7.1.8",
     "@mikro-orm/postgresql": "^7.1.8",
-    "@open-mercato/queue": "0.6.8-develop.6961.1.5b7ca407e7",
-    "@open-mercato/shared": "0.6.8-develop.6961.1.5b7ca407e7",
-    "@open-mercato/telemetry": "0.6.8-develop.6961.1.5b7ca407e7",
+    "@open-mercato/queue": "0.6.8-develop.6963.1.04a6d320e9",
+    "@open-mercato/shared": "0.6.8-develop.6963.1.04a6d320e9",
+    "@open-mercato/telemetry": "0.6.8-develop.6963.1.04a6d320e9",
     "cross-spawn": "^7.0.6",
     "pg": "8.22.0",
     "semver": "^7.8.5",
@@ -73,10 +73,10 @@
     "typescript-js": "npm:typescript@6.0.3"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.6.8-develop.6961.1.5b7ca407e7"
+    "@open-mercato/shared": "0.6.8-develop.6963.1.04a6d320e9"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.6.8-develop.6961.1.5b7ca407e7",
+    "@open-mercato/shared": "0.6.8-develop.6963.1.04a6d320e9",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.12"

package/src/lib/__integration__/TC-INT-008.spec.ts

@@ -247,20 +247,28 @@ function expectedGuideOutputNames(): string[] {
   }
 
   // Generated fact-sheet artifacts (spec 2026-06-27-ts-morph-module-fact-sheets):
-  // the v1 module-facts.json and corrected module-facts.v2.json sidecars are copied
-  // as-is and fact-sheets are filtered to the fixture's enabled modules. The legacy
+  // the v1/v2 sidecars and disabled local-reference projection are copied as-is,
+  // while installed fact-sheets are filtered to the fixture's enabled modules. The legacy
   // core.<module>.md redirect stubs are no longer
   // emitted (#3754). framework-extension-points.md is likewise generated into
   // dist/agentic/guides by both build.mjs pipelines (#4810) rather than checked in
   // alongside the static conceptual guides, so it needs an explicit entry here.
   collected.add('module-facts.json')
   collected.add('module-facts.v2.json')
+  collected.add('reference-module-facts.json')
   collected.add('framework-extension-points.md')
   collected.add('upstream/AGENTS.md')
   collected.add('upstream/BACKWARD_COMPATIBILITY.md')
   collected.add('upstream/manifest.json')
   for (const moduleId of FIXTURE_ENABLED_MODULES) {
-    collected.add(normalizePath(path.join('modules', `${moduleId}.md`)))
+    const moduleFactsRoot = path.join(cliDir, 'dist', 'agentic', 'guides', 'modules', moduleId)
+    for (const file of fs.readdirSync(moduleFactsRoot)) {
+      if (file.endsWith('.md')) collected.add(normalizePath(path.join('modules', moduleId, file)))
+    }
+  }
+  const referenceFactsRoot = path.join(cliDir, 'dist', 'agentic', 'guides', 'reference-modules')
+  for (const file of listRelativeFiles(referenceFactsRoot)) {
+    collected.add(normalizePath(path.join('reference-modules', file)))
   }
 
   return Array.from(collected).sort()
@@ -312,7 +320,7 @@ test.describe('TC-INT-008: CLI agentic init mirrors standalone scaffolding asset
       for (const moduleId of FIXTURE_ENABLED_MODULES) {
         expect(agentsSource).toContain(`\`${moduleId}\``)
       }
-      expect(agentsSource).toContain('`.ai/guides/modules/<id>.md`')
+      expect(agentsSource).toContain('`.ai/guides/modules/<id>/index.md`')
       expect(agentsSource.match(/\.ai\/guides\/modules\//g)).toHaveLength(1)
       expect(agentsSource).not.toContain('`auth`')
       expect(agentsSource).not.toContain('Core CRM capabilities')

package/src/lib/__tests__/agentic-setup.ownership.test.ts

@@ -173,6 +173,25 @@ describe('applyHarnessUpdate', () => {
     expect(manifest.files.map((item) => item.path)).toEqual([modified])
   })
 
+  it('removes retired flat module facts even when their generated copy was modified', () => {
+    const installedFact = '.ai/guides/modules/customers.md'
+    const referenceFact = '.ai/guides/reference-modules/example.md'
+    const unknownFact = '.ai/guides/modules/private.md'
+    write(join(targetDir, installedFact), 'locally modified generated facts\n')
+    write(join(targetDir, referenceFact), 'locally modified reference facts\n')
+    write(join(targetDir, unknownFact), 'unknown local file\n')
+    writeManifest(targetDir, [
+      entry(installedFact, 'old installed facts\n'),
+      entry(referenceFact, 'old reference facts\n'),
+    ])
+    writeManifest(stagingDir, [])
+
+    expect(applyHarnessUpdate(targetDir, stagingDir)).toEqual([])
+    expect(existsSync(join(targetDir, installedFact))).toBe(false)
+    expect(existsSync(join(targetDir, referenceFact))).toBe(false)
+    expect(readFileSync(join(targetDir, unknownFact), 'utf8')).toBe('unknown local file\n')
+  })
+
   it('leaves the prior manifest and app files untouched when candidate validation fails', () => {
     write(join(targetDir, '.ai', 'owned.md'), 'old\n')
     const oldManifestPath = writeManifest(targetDir, [entry('.ai/owned.md', 'old\n')])

package/src/lib/agentic-setup.ts

@@ -120,9 +120,9 @@ function readEnabledModuleIds(modulesPath: string): { parsed: boolean; ids: stri
 // (R5 — degraded, never empty).
 function selectModuleFactSheets(targetDir: string, modulesSubdir: string): string[] {
   const available = existsSync(modulesSubdir)
-    ? readdirSync(modulesSubdir)
-        .filter((file) => file.endsWith('.md'))
-        .map((file) => file.replace(/\.md$/, ''))
+    ? readdirSync(modulesSubdir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && existsSync(join(modulesSubdir, entry.name, 'index.md')))
+        .map((entry) => entry.name)
     : []
   if (available.length === 0) return []
   const parsed = readEnabledModuleIds(join(targetDir, 'src', 'modules.ts'))
@@ -157,7 +157,7 @@ export function renderModuleGuidesBlock(
   return [
     index,
     '',
-    'Load `.ai/guides/modules/<id>.md` only for a named or targeted installed module/host; never preload all module facts.',
+    'Load `.ai/guides/modules/<id>/index.md` only for a targeted installed module/host; never preload all module facts.',
   ].join('\n')
 }
 
@@ -439,14 +439,26 @@ function finalizeHarnessManifest(config: AgenticConfig, selectedTools: string[])
     ...targetPathsForTree(join(srcDir, 'scripts'), join(targetDir, 'scripts')),
   ])
   for (const file of readdirSync(GUIDES_DIR)) {
-    if (file.endsWith('.md') || file === 'module-facts.json' || file === 'module-facts.v2.json') {
+    if (
+      file.endsWith('.md')
+      || file === 'module-facts.json'
+      || file === 'module-facts.v2.json'
+      || file === 'reference-module-facts.json'
+    ) {
       paths.add(join(targetDir, '.ai', 'guides', file))
     }
   }
   for (const file of listFiles(join(GUIDES_DIR, 'upstream'))) {
     paths.add(join(targetDir, '.ai', 'guides', 'upstream', relative(join(GUIDES_DIR, 'upstream'), file)))
   }
-  for (const moduleId of selectedModules) paths.add(join(targetDir, '.ai', 'guides', 'modules', `${moduleId}.md`))
+  for (const moduleId of selectedModules) {
+    const sourceRoot = join(GUIDES_DIR, 'modules', moduleId)
+    const destinationRoot = join(targetDir, '.ai', 'guides', 'modules', moduleId)
+    for (const file of targetPathsForTree(sourceRoot, destinationRoot)) paths.add(file)
+  }
+  for (const file of listFiles(join(GUIDES_DIR, 'reference-modules'))) {
+    paths.add(join(targetDir, '.ai', 'guides', 'reference-modules', relative(join(GUIDES_DIR, 'reference-modules'), file)))
+  }
   if (selectedTools.includes('claude-code')) {
     paths.add(join(targetDir, 'CLAUDE.md'))
     paths.add(join(targetDir, '.claude', 'settings.json'))
@@ -577,6 +589,12 @@ export function applyHarnessUpdate(
     const destinationPath = resolveManifestPath(targetRoot, previousEntry.path)
     if (!destinationPath || !existsSync(destinationPath)) continue
     assertManagedPath(targetRoot, destinationPath, { leaf: 'file' })
+    const isRetiredFlatModuleFact = !previousEntry.userEditable
+      && /^\.ai\/guides\/(?:modules|reference-modules)\/[^/]+\.md$/.test(previousEntry.path)
+    if (isRetiredFlatModuleFact) {
+      rmSync(destinationPath, { force: true })
+      continue
+    }
     let unchanged = false
     try {
       unchanged = hashFile(destinationPath) === previousEntry.sha256
@@ -620,7 +638,7 @@ function generateShared(config: AgenticConfig): void {
   copyTree(join(srcDir, 'scripts'), join(targetDir, 'scripts'), config)
 
   // Routed conceptual guides are copied wholesale (framework-wide). Per-module
-  // fact-sheets (.ai/guides/modules/<module>.md) are filtered to the app's enabled
+  // fact-sheets (.ai/guides/modules/<module>/) are filtered to the app's enabled
   // module set; the combined v1 and corrected v2 module-facts sidecars are copied as-is.
   if (existsSync(GUIDES_DIR)) {
     const guidesDestDir = join(targetDir, '.ai', 'guides')
@@ -646,13 +664,19 @@ function generateShared(config: AgenticConfig): void {
       copyFileSync(moduleFactsV2Path, destPath)
     }
 
+    const referenceFactsPath = join(GUIDES_DIR, 'reference-module-facts.json')
+    if (existsSync(referenceFactsPath)) {
+      const destPath = join(guidesDestDir, 'reference-module-facts.json')
+      ensureDir(destPath)
+      copyFileSync(referenceFactsPath, destPath)
+    }
+
     copyTree(join(GUIDES_DIR, 'upstream'), join(guidesDestDir, 'upstream'), config)
+    copyTree(join(GUIDES_DIR, 'reference-modules'), join(guidesDestDir, 'reference-modules'), config)
 
     const modulesSubdir = join(GUIDES_DIR, 'modules')
     for (const moduleId of selectedModules) {
-      const destPath = join(guidesDestDir, 'modules', `${moduleId}.md`)
-      ensureDir(destPath)
-      copyFileSync(join(modulesSubdir, `${moduleId}.md`), destPath)
+      copyTree(join(modulesSubdir, moduleId), join(guidesDestDir, 'modules', moduleId), config)
     }
   }
 

package/src/lib/generators/__tests__/module-facts.bc-guard.test.ts

@@ -1,6 +1,11 @@
 import fs from 'node:fs'
 import path from 'node:path'
-import { extractAllModuleFacts, isExactSourceFilePath, renderModuleFactsJson } from '../module-facts'
+import {
+  extractAllModuleFacts,
+  isExactSourceFilePath,
+  renderModuleFactsDirectory,
+  renderModuleFactsJson,
+} from '../module-facts'
 import { discoverPackageModuleSources } from '../module-facts-discovery'
 import { createResolver } from '../../resolver'
 
@@ -18,16 +23,29 @@ function isUnique(values: string[]): boolean {
 }
 
 const MARKDOWN_LINK_TARGET = /\]\(\.\.\/\.\.\/\.\.\/([^)#]+)(?:#L\d+)?\)/g
+const DIRECTORY_MARKDOWN_LINK_TARGET = /\]\(\.\.\/\.\.\/\.\.\/\.\.\/([^)#]+)(?:#L\d+)?\)/g
+const MAX_ANCHORED_SECTION_BYTES = 32 * 1024
 
 function collectLinkTargets(markdown: string): string[] {
   return [...markdown.matchAll(MARKDOWN_LINK_TARGET)].map((match) => match[1])
 }
 
+function expectAnchoredLeafCap(markdown: string): void {
+  const lines = markdown.split('\n')
+  const subheadings = lines.flatMap((line, index) => line.startsWith('### ') ? [index] : [])
+  if (Buffer.byteLength(markdown) > MAX_ANCHORED_SECTION_BYTES) expect(subheadings.length).toBeGreaterThan(0)
+  for (let index = 0; index < subheadings.length; index += 1) {
+    const start = subheadings[index]
+    const end = subheadings[index + 1] ?? lines.length
+    expect(Buffer.byteLength(lines.slice(start, end).join('\n'))).toBeLessThanOrEqual(MAX_ANCHORED_SECTION_BYTES)
+  }
+}
+
 describe('module-facts BC resolve guard (T2)', () => {
   const repoRoot = findRepoRoot()
   const sources = discoverPackageModuleSources(createResolver(repoRoot))
   const extractionStartedAt = process.cpuUsage()
-  const { factsByModule, markdownByModule, frameworkMarkdown } = extractAllModuleFacts({ sources })
+  const { factsByModule, markdownByModule, directoryByModule, frameworkMarkdown } = extractAllModuleFacts({ sources })
   const legacyFactsByModule = extractAllModuleFacts({ sources, factsContractVersion: 1 }).factsByModule
   const extractionCpuUsage = process.cpuUsage(extractionStartedAt)
   const extractionCpuDurationMs = (extractionCpuUsage.user + extractionCpuUsage.system) / 1_000
@@ -36,6 +54,7 @@ describe('module-facts BC resolve guard (T2)', () => {
     const repeated = extractAllModuleFacts({ sources })
     expect(renderModuleFactsJson(repeated.factsByModule)).toBe(renderModuleFactsJson(factsByModule))
     expect(repeated.markdownByModule).toEqual(markdownByModule)
+    expect(repeated.directoryByModule).toEqual(directoryByModule)
     expect(repeated.frameworkMarkdown).toBe(frameworkMarkdown)
     for (const facts of Object.values(factsByModule)) {
       expect(facts.extensionSurfaces).toBeDefined()
@@ -67,6 +86,12 @@ describe('module-facts BC resolve guard (T2)', () => {
     ))
     const markdownBytes = Object.values(markdownByModule)
       .reduce((total, markdown) => total + Buffer.byteLength(markdown), Buffer.byteLength(frameworkMarkdown))
+    const directoryMarkdownBytes = Object.values(directoryByModule).reduce(
+      (total, directory) => total
+        + Buffer.byteLength(directory.index)
+        + directory.sections.reduce((sectionTotal, section) => sectionTotal + Buffer.byteLength(section.markdown), 0),
+      Buffer.byteLength(frameworkMarkdown),
+    )
 
     // Budget raised by the bidirectional-topology spec
     // (2026-08-02-module-facts-extension-activation-and-incoming-index): the
@@ -123,6 +148,75 @@ describe('module-facts BC resolve guard (T2)', () => {
     // contributions all render a resolved Source cell, and contribution
     // resolutions render as their own source-linked section.
     expect(markdownBytes).toBeLessThan(1_650_000)
+    expect(directoryMarkdownBytes).toBeLessThan(2_050_000)
+  })
+
+  it('keeps every shipped directory section resumable and every advertised subsection anchor exact', () => {
+    for (const [moduleId, directory] of Object.entries(directoryByModule)) {
+      expect(directory.index.trimEnd()).toMatch(
+        new RegExp(`<!-- end module facts: ${moduleId} — ${directory.sections.length} sections -->$`),
+      )
+      const bySlug = new Map(directory.sections.map((section) => [section.slug, section]))
+      for (const section of directory.sections) {
+        expect(section.markdown.trimEnd()).toMatch(
+          new RegExp(`<!-- end module facts section: ${moduleId}/${section.slug} -->$`),
+        )
+        expectAnchoredLeafCap(section.markdown)
+      }
+      const anchors = [...directory.index.matchAll(/^  - (.+) — ([a-z0-9-]+)\.md:L(\d+), ~\d+ KB$/gm)]
+      for (const anchor of anchors) {
+        const section = bySlug.get(anchor[2])
+        expect(section).toBeDefined()
+        const heading = section?.markdown.split('\n')[Number(anchor[3]) - 1]
+        expect(heading).toBe(`### ${anchor[1].slice(anchor[1].lastIndexOf(' / ') + 3)}`)
+      }
+      const expectedAnchorCount = directory.sections.reduce(
+        (total, section) => total + (section.markdown.match(/^### /gm) ?? []).length,
+        0,
+      )
+      expect(anchors).toHaveLength(expectedAnchorCount)
+    }
+  })
+
+  it('chunks oversized natural groups and rejects a single row larger than the read cap', () => {
+    const customers = factsByModule.customers
+    const routeTargets = customers.overrideTargets?.filter((target) => target.domain === 'routes') ?? []
+    expect(routeTargets.length).toBeGreaterThan(0)
+    const oversizedOverrides = renderModuleFactsDirectory({
+      ...customers,
+      overrideTargets: [
+        ...(customers.overrideTargets?.filter((target) => target.domain !== 'routes') ?? []),
+        ...Array.from({ length: 10 }, () => routeTargets).flat(),
+      ],
+    })
+    const overrideSection = oversizedOverrides.sections.find((section) => section.slug === 'exact-override-targets')
+    expect(overrideSection?.markdown).toMatch(/^### routes \(continued 2\)$/m)
+    expectAnchoredLeafCap(overrideSection?.markdown ?? '')
+
+    const boundHost = customers.extensionSurfaces?.hosts.find((host) => host.bound)
+    if (!boundHost) throw new Error('[internal] customers must expose a bound host for the chunking guard')
+    const oversizedHosts = renderModuleFactsDirectory({
+      ...customers,
+      extensionSurfaces: {
+        ...(customers.extensionSurfaces ?? { hosts: [], contributions: [], unresolved: [] }),
+        hosts: Array.from({ length: 400 }, (_, index) => ({
+          ...boundHost,
+          id: `${boundHost.id}:synthetic-${index}`,
+        })),
+      },
+    })
+    const hostSection = oversizedHosts.sections.find((section) => section.slug === 'umes-hosts')
+    expect(hostSection?.markdown).toMatch(/\(continued 2\)/)
+    expectAnchoredLeafCap(hostSection?.markdown ?? '')
+
+    const routeTarget = routeTargets[0]
+    if (!routeTarget) throw new Error('[internal] customers must expose a route target for the chunking guard')
+    const oversizedRow = {
+      ...routeTarget,
+      path: ['x'.repeat(MAX_ANCHORED_SECTION_BYTES)],
+    }
+    expect(() => renderModuleFactsDirectory({ ...customers, overrideTargets: [oversizedRow] }))
+      .toThrow(/contains a row larger than the anchored read cap/)
   })
 
   it('links every generated fact to an exact resolvable file, never a directory', () => {
@@ -150,6 +244,28 @@ describe('module-facts BC resolve guard (T2)', () => {
     expect([...unresolvedTargets]).toEqual([])
   })
 
+  it('keeps directory source hrefs exact and resolvable at their deeper relative depth', () => {
+    const packageLinkRoot = path.join(repoRoot, 'node_modules', '@open-mercato')
+    const canCheckDisk = fs.existsSync(packageLinkRoot)
+    const unresolvedTargets = new Set<string>()
+    let checkedTargets = 0
+
+    for (const directory of Object.values(directoryByModule)) {
+      for (const section of directory.sections) {
+        for (const match of section.markdown.matchAll(DIRECTORY_MARKDOWN_LINK_TARGET)) {
+          checkedTargets += 1
+          const target = match[1]
+          if (canCheckDisk && (!fs.existsSync(path.join(repoRoot, target)) || !fs.statSync(path.join(repoRoot, target)).isFile())) {
+            unresolvedTargets.add(target)
+          }
+        }
+      }
+    }
+
+    expect(checkedTargets).toBeGreaterThan(1_000)
+    expect([...unresolvedTargets]).toEqual([])
+  })
+
   it('keeps directory-valued provenance readable as plain text', () => {
     const frameworkHostMarkdowns = Object.values(markdownByModule)
       .filter((markdown) => markdown.includes('packages/ui/src'))

package/src/lib/generators/__tests__/module-facts.source-links.test.ts

@@ -1,7 +1,12 @@
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
-import { extractModuleFacts, isExactSourceFilePath, renderModuleFactsMarkdown } from '../module-facts'
+import {
+  extractModuleFacts,
+  isExactSourceFilePath,
+  renderModuleFactsDirectory,
+  renderModuleFactsMarkdown,
+} from '../module-facts'
 
 const MARKDOWN_LINK_TARGET = /\]\(\.\.\/\.\.\/\.\.\/([^)#]+)(?:#L\d+)?\)/g
 
@@ -119,7 +124,78 @@ describe('module-facts source-linked extension surfaces', () => {
     expect(markdown).toContain('## AI tools / MCP capabilities')
     expect(markdown).toContain('## AI agents')
     expect(markdown).toContain(
-      '(../../../node_modules/@open-mercato/example/src/modules/facts/api/records/route.ts)',
+      '[api/records/route.ts](../../../node_modules/@open-mercato/example/src/modules/facts/api/records/route.ts)',
+    )
+  })
+
+  it('emits deterministic contents anchors and a terminal completeness marker', () => {
+    const facts = extractModuleFacts({
+      moduleId: 'facts',
+      moduleRoot,
+      sourcePackage: '@open-mercato/example',
+      sourceVersion: '1.2.3',
+    })
+    const markdown = renderModuleFactsMarkdown(facts)
+    const lines = markdown.split('\n')
+    const anchors = [...markdown.matchAll(/^(  )?- (.+) — L(\d+), ~\d+ KB$/gm)]
+
+    expect(anchors.length).toBeGreaterThan(10)
+    for (const anchor of anchors) {
+      const heading = lines[Number(anchor[3]) - 1]
+      if (anchor[1]) {
+        expect(heading).toBe(`### ${anchor[2].slice(anchor[2].lastIndexOf(' / ') + 3)}`)
+      } else {
+        expect(heading).toMatch(new RegExp(`^## ${anchor[2]}(?:\\s+\\(\\d+\\))?$`))
+      }
+    }
+    expect(markdown.trimEnd()).toMatch(/<!-- end module facts: facts — \d+ sections -->$/)
+    expect(renderModuleFactsMarkdown(facts)).toBe(markdown)
+  })
+
+  it('renders a directory index and section files with deeper exact source links', () => {
+    const facts = extractModuleFacts({
+      moduleId: 'facts',
+      moduleRoot,
+      sourcePackage: '@open-mercato/example',
+      sourceVersion: '1.2.3',
+      registrySource: `export const modules = [{
+        id: 'facts',
+        apis: [{
+          path: '/facts/records-custom',
+          handlers: { GET: async () => undefined },
+          metadata: { GET: { requireFeatures: ['facts.view'] } },
+        }],
+      }]`,
+    })
+    const directory = renderModuleFactsDirectory(facts)
+
+    expect(directory.index).toContain('[API routes](api-routes.md)')
+    expect(directory.index.trimEnd()).toMatch(/<!-- end module facts: facts — \d+ sections -->$/)
+    const apiRoutes = directory.sections.find((section) => section.slug === 'api-routes')
+    expect(apiRoutes?.markdown).toContain(
+      '[api/records/route.ts](../../../../node_modules/@open-mercato/example/src/modules/facts/api/records/route.ts)',
+    )
+    expect(apiRoutes?.markdown.trimEnd()).toMatch(/<!-- end module facts section: facts\/api-routes -->$/)
+  })
+
+  it('omits sections with no facts and says so in the index', () => {
+    const facts = extractModuleFacts({
+      moduleId: 'facts',
+      moduleRoot,
+      sourcePackage: '@open-mercato/example',
+      sourceVersion: '1.2.3',
+    })
+    const flatHeadings = [...renderModuleFactsMarkdown(facts).matchAll(/^## (.+)$/gm)].map((match) => match[1])
+    const emptyHeadings = [...renderModuleFactsMarkdown(facts).matchAll(/^## (.+)\n\n_none_$/gm)]
+      .map((match) => match[1].replace(/\s+\(\d+\)\s*$/, ''))
+    const directory = renderModuleFactsDirectory(facts)
+
+    expect(emptyHeadings.length).toBeGreaterThan(0)
+    expect(flatHeadings.length).toBeGreaterThan(directory.sections.length)
+    for (const section of directory.sections) expect(section.markdown).not.toContain('_none_')
+    for (const heading of emptyHeadings) expect(directory.index).not.toContain(`[${heading}](`)
+    expect(directory.index).toContain(
+      'A section absent from this list has no facts for facts; this index is complete only when the read reaches the marker below.',
     )
   })