src/generators

Module summary

Module src/generators

Exports

Name	Kind	Default
GENERATOR_REGISTRY	variable	no
IGNORE_PATTERNS	variable	no
KNOWN_GENERATOR_NAMES	variable	no
__getAtomicWriteFileForTests	function	no
__resetPromptCacheForTests	function	no
_getValidator	function	no
appendEntryToFile	function	no
bucketOf	function	no
buildDepGraph	function	no
crossCheckHallucinations	function	no
demoteHeadings	function	no
enforcePromptBudget	function	no
escapeScalar	function	no
extractMentionedSymbols	function	no
formatEntryMarkdown	function	no
generateApiReference	function	no
generateArchitectureDoc	function	no
generateChangelog	function	no
generateIssueEntries	function	no
generateLlmsFullTxt	function	no
generateLlmsTxt	function	no
generateModuleDocs	function	no
generateReferencePages	function	no
generateSidebar	function	no
generateWorkflowDocs	function	no
groupModules	function	no
loadModuleHashes	function	no
loadPrompt	function	no
loadPromptTemplate	function	no
newFileHeader	function	no
pageNameForDir	function	no
parseFrontmatter	function	no
renderMermaid	function	no
renderModulePage	function	no
renderPage	function	no
renderTable	function	no
resolveEnabledGenerators	function	no
resolveOutputPath	function	no
saveModuleHashes	function	no
serializeFrontmatter	function	no
serializeObject	function	no
serializeReferenceFrontmatter	function	no
serializeScalar	function	no
splitSections	function	no
stripFrontmatter	function	no
validateEntry	function	no
validateHedges	function	no

Detail

GENERATOR_REGISTRY

GENERATOR_REGISTRY

Params

None.

Returns

None.

Examples

None.

IGNORE_PATTERNS

IGNORE_PATTERNS

Params

None.

Returns

None.

Examples

None.

KNOWN_GENERATOR_NAMES

KNOWN_GENERATOR_NAMES

Params

None.

Returns

None.

Examples

None.

__getAtomicWriteFileForTests

__getAtomicWriteFileForTests()

Test-only seam so a stubbed rename failure can exercise AC-8 without mocking node:fs/promises globally. NOT public API.

Params

None.

Returns

None.

Examples

None.

__resetPromptCacheForTests

__resetPromptCacheForTests(): void

Test-only: reset the cached template so a fresh read can be triggered after a hot edit. Not part of the public surface.

Params

None.

Returns

void

Examples

None.

_getValidator

_getValidator()

Internal getter so tests can confirm the validator is the same instance.

Params

None.

Returns

None.

Examples

None.

appendEntryToFile

appendEntryToFile(outputPath, formattedMarkdown, category, issueNumber): object

Params

• outputPath
• formattedMarkdown
• category
• issueNumber

Returns

object

Examples

None.

bucketOf

bucketOf(dirRel, buckets)

Classify a JS-module dirRel into a bucket name. Iterates buckets in declaration order; first match wins. Returns ‘core’ as catch-all.

Params

• dirRel
• buckets

Returns

None.

Examples

None.

buildDepGraph

async buildDepGraph({ rootDir, globs, buckets }): Promise<object>

Build the architecture dep graph: JS modules from AST + directory descriptors from config.buckets.

Params

• { rootDir, globs, buckets }

Returns

Promise<object>

Examples

None.

crossCheckHallucinations

crossCheckHallucinations(llmText, exportNames)

Compute the set of mentioned symbols that are neither in exportNames nor in the intrinsics allowlist. A non-empty result is a hallucination.

Params

• llmText
• exportNames

Returns

None.

Examples

None.

demoteHeadings

demoteHeadings(text)

Demote every ATX heading line (#-prefixed) by one level, capped at ######. Code fences are tracked so headings inside fenced blocks are preserved verbatim.

Fence tracking follows CommonMark: a closing fence must use the same marker character (` or ~) as the opening fence and be at least as long. A mismatched delimiter inside a fenced block (e.g. a ~~~ line within a ``` block) is therefore not treated as a close.

Params

• text

Returns

None.

Examples

None.

enforcePromptBudget

enforcePromptBudget({ userTemplate, vars }): object

Enforce the input prompt budget. If the rendered USER text exceeds PROMPT_BUDGET_BYTES, progressively drop the JSDOC block, clamp README, then drop EXPORTS, SIGNATURES, and RELATED blocks. If the prompt is still over budget after every block has been dropped, a final hard clamp truncates the rendered text to the byte budget so the caller is guaranteed never to send an oversized prompt. Returns {prompt, truncated} where truncated is the array of applied truncations (for diagnostics in warnings).

Params

• { userTemplate, vars }

Returns

object

Examples

None.

escapeScalar

escapeScalar(s)

Quote a YAML scalar string conservatively.

Strings that contain anything that could be misparsed (special YAML chars, leading/trailing whitespace, leading sigils, or sequences that resemble other scalar types) are double-quoted with backslash escaping. Otherwise the value is emitted as a plain scalar.

Params

• s

Returns

None.

Examples

None.

extractMentionedSymbols

extractMentionedSymbols(text)

Scan the LLM text for backtick-quoted bare identifiers. Returns the set of distinct mentioned symbols (excluding strings that span multiple tokens or contain operators / punctuation).

Params

• text

Returns

None.

Examples

None.

formatEntryMarkdown

formatEntryMarkdown(category, entry, issueNumber)

Params

• category
• entry
• issueNumber

Returns

None.

Examples

None.

generateApiReference

async generateApiReference({ rootDir, config, now }): Promise<object>

Generate API reference pages, write them to disk, and reconcile orphans. Returns the run summary and — for tests — a counter that proves no LLM call was made (__llmCallCount === 0).

Params

• { rootDir, config, now }

Returns

Promise<object>

Examples

None.

generateArchitectureDoc

async generateArchitectureDoc({ rootDir, config, now, describer }): Promise<object>

Params

• { rootDir, config, now, describer }

Returns

Promise<object>

Examples

None.

generateChangelog

async generateChangelog({ rootDir, config, now, fetcher, narrator }): Promise<object>

Generate wiki/reference/changelog.md.

Params

• { rootDir, config, now, fetcher, narrator }

Returns

Promise<object>

Examples

None.

generateIssueEntries

async generateIssueEntries({
  issues,
  classify,
  generateEntry,
  sanitize,
  config,
  stateDir,
  rootDir,
}): Promise<object>

Generate wiki entries from a batch of classified issues.

Params

• { issues, classify, generateEntry, sanitize, config, stateDir, rootDir, }

Returns

Promise<object>

Examples

None.

generateLlmsFullTxt

async generateLlmsFullTxt({ rootDir, config }): Promise<object>

Generate llms-full.txt. See file header for full behaviour.

Params

• { rootDir, config }

Returns

Promise<object>

Examples

None.

generateLlmsTxt

async generateLlmsTxt({ rootDir, config }): Promise<object>

Generate llms.txt. See file header for full behaviour.

Params

• { rootDir, config }

Returns

Promise<object>

Examples

None.

generateModuleDocs

async generateModuleDocs({ rootDir, config }): Promise<object>

Generate module documentation pages. See file header for the contract.

Params

• { rootDir, config }

Returns

Promise<object>

Examples

None.

generateReferencePages

async generateReferencePages({ rootDir, config, now }): Promise<object>

Generate the 6 reference pages, write them under <rootDir>/<config.paths.wikiOutput>/reference/, and — best-effort — fire a Telegram notification when warnings accumulated.

Params

• { rootDir, config, now }

Returns

Promise<object>

Examples

None.

generateSidebar

async generateSidebar({ rootDir, config, humanizer }): Promise<object>

Generate sidebar.json. See file header for full behaviour.

The optional humanizer parameter exists so tests can inject a deterministic stand-in for humanizeWithHaiku. Production callers omit it; the default uses the real Haiku-backed helper.

Params

• { rootDir, config, humanizer }

Returns

Promise<object>

Examples

None.

generateWorkflowDocs

async generateWorkflowDocs({ rootDir, config, now, _generateGuide }): Promise<object>

Generate workflow guide pages. See the file header for behaviour.

Params

• { rootDir, config, now, _generateGuide }

Returns

Promise<object>

Examples

None.

groupModules

async groupModules({ rootDir, globs }): Promise<unknown>

Expand globs and group matching source files by immediate parent dir.

Params

• { rootDir, globs }

Returns

Promise<unknown>

Examples

None.

loadModuleHashes

async loadModuleHashes(stateDirAbs): Promise<unknown>

Load the persisted module-hash map. The schema is richer than hash_tracker.js (which only stores string values): each entry is {hash, promptVersion, pageWritten}. Returns an empty plain object if the file is missing.

Params

• stateDirAbs

Returns

Promise<unknown>

Examples

None.

loadPrompt

loadPrompt(category): object

Load a prompt template for the given category.

Params

• category

Returns

object

Examples

None.

loadPromptTemplate

loadPromptTemplate()

Load and cache the prompt template, splitting on the three section headings. Returns {system, user, version} where version is the prompt-version: <n> numeric value.

Params

None.

Returns

None.

Examples

None.

newFileHeader

newFileHeader(category)

Params

• category

Returns

None.

Examples

None.

pageNameForDir

pageNameForDir(dirRel): string

Derive the page filename from a POSIX-relative directory path.

Uses split/join so EVERY / becomes _, not just the first occurrence.

Params

• dirRel

Returns

string

Examples

None.

parseFrontmatter

parseFrontmatter(text)

Extract the title and description fields from a frontmatter YAML block. The parser is intentionally permissive: it accepts unquoted, double-quoted, and single-quoted scalars and ignores any other keys.

Params

• text

Returns

None.

Examples

None.

renderMermaid

renderMermaid({ nodes, edges, title })

Render a Mermaid graph LR block from a node + edge set.

Each node renders as nN["<dirRel> (<fileCount> files)"] when the node is a directory-descriptor (non-JS bucket), or nN["<dirRel>"] for a JS-module node. Edges render one per line, sorted lexically.

Params

• { nodes, edges, title }

Returns

None.

Examples

None.

renderModulePage

renderModulePage({
  frontmatter,
  moduleSummary,
  exports,
  signatures,
  jsdocBlocks,
})

Render a complete API reference page.

Params

• { frontmatter, moduleSummary, exports, signatures, jsdocBlocks, }

Returns

None.

Examples

None.

renderPage

renderPage({ frontmatter, summary, sections })

Compose the full architecture page from a frontmatter block, a summary paragraph, and an ordered list of sections (each either a mermaid or table kind).

Params

• { frontmatter, summary, sections }

Returns

None.

Examples

None.

renderTable

renderTable({ nodes, edges, title })

Render a Markdown table fallback for sub-graphs that exceed the Mermaid node cap. JS-module nodes use the columns Module | Imports From | Imported By; directory-descriptor nodes use Directory | Files | Description.

Params

• { nodes, edges, title }

Returns

None.

Examples

None.

resolveEnabledGenerators

resolveEnabledGenerators(enabled)

Resolve the ordered list of generator entries to run from a config enabled array. Iteration order matches the input array (sequential dispatch in the orchestrator).

Throws synchronously with a human-readable message on:

• non-array input (defense in depth; loader already validates shape)
• an entry that is not a registered generator name

Params

• enabled

Returns

None.

Examples

None.

resolveOutputPath

resolveOutputPath(rootDir, config, category)

Params

• rootDir
• config
• category

Returns

None.

Examples

None.

saveModuleHashes

async saveModuleHashes(stateDirAbs, hashes): Promise<void>

Persist the module-hash map atomically. Keys sorted alphabetically. Mirrors the tmp+rename pattern from hash_tracker.saveHashes.

Params

• stateDirAbs
• hashes

Returns

Promise<void>

Examples

None.

serializeFrontmatter

serializeFrontmatter(obj): string

Build, ajv-validate, and deterministically serialize Starlight frontmatter.

Throws an Error tagged with the ajv error path on invalid input.

Params

• obj

Returns

string

Examples

None.

serializeObject

serializeObject(obj, depth)

Serialize an object as YAML at the given indent depth, with sorted keys.

Params

• obj
• depth

Returns

None.

Examples

None.

serializeReferenceFrontmatter

serializeReferenceFrontmatter(obj): string

Variant of serializeFrontmatter for WG-34 reference/catalog pages. Identical surface and YAML output discipline; the only difference is the underlying schema, which permits editUrl: null. Used by reference_pages_generator when config.site.repoUrl is unavailable.

Params

• obj

Returns

string

Examples

None.

serializeScalar

serializeScalar(value)

Serialize a single value with stable formatting.

Booleans render unquoted, numbers render verbatim, null renders as bare null (Clarification C4), strings go through escapeScalar.

Params

• value

Returns

None.

Examples

None.

splitSections

splitSections(text): object

Split the LLM text into the five required sections. Throws a typed error when a section is missing or out of order.

Params

• text

Returns

object

Examples

None.

stripFrontmatter

stripFrontmatter(text)

Strip a leading frontmatter block (---\n...\n---\n). Returns the post-frontmatter content; if no frontmatter is present, returns the input unchanged.

Params

• text

Returns

None.

Examples

None.

validateEntry

validateEntry(category, entry): object

Run the binary rubric against an entry.

Params

• category
• entry

Returns

object

Examples

None.

validateHedges

validateHedges(content): object

Detect banned hedge phrases (case-insensitive substring match).

Params

• content

Returns

object

Examples

None.