@promptbook/cli 0.113.0-9 → 0.114.0-0

package/src/book-2.0/book-language-documentation/englishBookLanguageManualDictionary.ts

@@ -0,0 +1,346 @@
+import { spaceTrim } from 'spacetrim';
+import type { BookLanguageManualDictionary } from './BookLanguageManualDictionary';
+
+/**
+ * Canonical English wording of the standalone Book language manual.
+ *
+ * Every other language pack is a translation of this dictionary and is resolved
+ * through `getBookLanguageManualDictionary`.
+ *
+ * @private internal constant of `createStandaloneBookLanguageMarkdown`
+ */
+export const englishBookLanguageManualDictionary: BookLanguageManualDictionary = {
+    language: 'en',
+    title: 'Book Language blueprint',
+    introLines: [
+        'Canonical standalone guide for Promptbook Book Agent language.',
+        'Generated from repository https://github.com/webgptorg/promptbook',
+    ],
+    metadataLabels: {
+        bookLanguageVersion: 'Book language version',
+        generatedAt: 'Generated at',
+        commitmentGroups: 'Commitment groups',
+        implementedCommitments: 'Implemented commitments',
+        placeholderCommitments: 'Placeholder commitments',
+    },
+    tableOfContentsTitle: 'Table of Contents',
+    chapters: {
+        whatIs: {
+            title: 'What Book language is',
+            body: spaceTrim(`
+                Book language is a domain-specific language for defining **AI agents** as plain-text source.
+                It solves these problems:
+
+                - **One editable source of truth** for agent behavior, tools, memory, and profile metadata.
+                - **Composable agent architecture** through commitments like \`FROM\`, \`IMPORT\`, and \`TEAM\`.
+                - **Deterministic runtime preparation** where source is parsed and compiled into model requirements.
+                - **Portable agent definitions** that can be copied, versioned, and reviewed as text.
+
+                In this repository, "Book language" means **Book 2.0 agent language**.
+            `),
+        },
+        mentalModel: {
+            title: 'Mental model of an agent',
+            body: spaceTrim(`
+                Think of one agent source as four layers:
+
+                1. **Identity/Profile layer**:
+                Agent name (first non-commitment line), the last \`GOAL\`, and \`META*\` commitments.
+                2. **Behavior layer**:
+                \`RULE\`, \`KNOWLEDGE\`, \`WRITING SAMPLE\`, \`WRITING RULES\`, \`LANGUAGE\`, \`GOAL\`, and related commitments.
+                3. **Capability layer**:
+                \`USE*\`, \`MEMORY\`, and other tooling commitments exposing runtime abilities.
+                4. **Composition layer**:
+                \`FROM\` inheritance, \`IMPORT\` reuse, and \`TEAM\` delegation.
+            `),
+        },
+        howToStructure: {
+            title: 'How to structure good agents',
+            body: spaceTrim(`
+                Recommended patterns and tradeoffs:
+
+                1. **Single clear role first**:
+                Start with one narrow \`GOAL\` describing what the agent is responsible for.
+                Tradeoff: less initial flexibility, much higher reliability.
+                2. **Guardrails early**:
+                Add concrete \`RULE\` commitments before adding many tools.
+                Tradeoff: more upfront design, fewer runtime surprises.
+                3. **Grounding over improvisation**:
+                Prefer \`KNOWLEDGE\` + explicit citation rule for high-stakes answers.
+                Tradeoff: extra maintenance for sources, better factual control.
+                4. **Composition over monoliths**:
+                Use \`TEAM\`/\`IMPORT\` for specialized responsibilities.
+                Tradeoff: orchestration overhead, stronger modularity and reuse.
+                5. **Controlled memory**:
+                If using \`MEMORY\`, define what must and must not be remembered.
+                Tradeoff: stricter policy design, better privacy and signal quality.
+            `),
+        },
+        primitives: {
+            title: 'Primitives and constructs reference',
+            body: '',
+        },
+        commitmentCatalog: {
+            title: 'Commitment catalog',
+            body: spaceTrim(`
+                This section is generated from commitment definitions in \`src/commitments\`.
+                For each commitment group you get:
+
+                - semantics summary (description/icon/status)
+                - parsing schema (\`createTypeRegex\` and \`createRegex\`)
+                - canonical documentation block
+            `),
+        },
+        examples: {
+            title: 'End-to-end examples',
+        },
+        pitfalls: {
+            title: 'Do nots and common pitfalls',
+        },
+        tutorial: {
+            title: 'Build an agent from scratch (offline tutorial)',
+            body: spaceTrim(`
+                This tutorial is sufficient without internet access.
+
+                1. **Define role and goal**
+                Create a short name line and one clear \`GOAL\`.
+                2. **Add behavioral constraints**
+                Add 3-6 specific \`RULE\` commitments covering scope, tone, and safety boundaries.
+                3. **Add grounding**
+                Add \`KNOWLEDGE\` commitments (inline text or local/importable sources).
+                4. **Add capabilities**
+                Add only necessary \`USE*\` and/or \`MEMORY\` commitments.
+                5. **Set profile metadata**
+                Add \`META DESCRIPTION\`, \`META AVATAR\` / \`META VISUAL\` or \`META IMAGE\`, \`META INPUT PLACEHOLDER\`, \`META THINKING MESSAGE\`, and disclaimers if needed.
+                6. **Add first interaction**
+                Add \`INITIAL MESSAGE\` and optionally sample \`USER MESSAGE\` / \`AGENT MESSAGE\` pairs.
+                7. **Close for deterministic behavior (optional)**
+                Add \`CLOSED\` when you want stable non-self-modifying behavior.
+            `),
+        },
+        lowLevelCommitments: {
+            title: 'Low level commitments',
+            body: spaceTrim(`
+                The commitments below are fully part of Book language, but they are intended for advanced use only.
+                Most agents never need them, and using them incorrectly makes an agent harder to maintain.
+
+                Reach for them only when a specific technical requirement cannot be expressed with the commitments above.
+            `),
+        },
+    },
+    mentalModelSections: {
+        detectedIntro: 'Agent composition commitments in current runtime:',
+        detectedProfileLabel: 'Profile-centric commitments detected',
+        detectedBehaviorLabel: 'Behavior-centric commitments detected',
+        detectedToolingLabel: 'Tool/runtime commitments detected',
+        detectedCompositionLabel: 'Composition commitments detected',
+        meta: {
+            title: 'META commitments and agent profile',
+            body: spaceTrim(`
+                \`META*\` commitments control profile data shown in UI (for example avatar visual, image, description, disclaimers, domain, input placeholder).
+                They generally shape presentation/metadata rather than tool behavior.
+            `),
+        },
+        inheritance: {
+            title: 'FROM inheritance',
+            body: spaceTrim(`
+                \`FROM\` points to a parent agent source. During inheritance resolution:
+
+                - Parent corpus is merged into effective source.
+                - \`FROM {Void}\` / \`FROM VOID\` means explicit "no parent".
+                - Missing references are surfaced as notes in resolved source.
+            `),
+        },
+        composition: {
+            title: 'TEAM and IMPORT',
+            body: spaceTrim(`
+                - \`TEAM\` registers teammate agents as callable tools.
+                - \`IMPORT\` injects imported agent/file content into current agent context.
+                - In Agents Server, compact references like \`{Legal Reviewer}\` can resolve to embedded in-book agents.
+            `),
+        },
+        capabilities: {
+            title: 'USE commitments',
+            body: spaceTrim(`
+                \`USE*\` commitments enable capabilities (search, browser, project integration, email, image generation, etc.).
+                They expose runtime tools and system-message guidance used during execution.
+            `),
+        },
+    },
+    primitivesSections: {
+        coreSyntax: {
+            title: 'Core syntax primitives',
+            body: spaceTrim(`
+                1. **Agent title**:
+                First non-empty line that is not a commitment keyword.
+                2. **Commitment block**:
+                Starts with a commitment keyword and continues until the next commitment block or separator.
+                3. **Horizontal separator**:
+                Lines like \`---\` split sections; in Agents Server they can delimit embedded in-book agents.
+                4. **Code fences**:
+                Preserved inside commitment content; useful for examples/instructions.
+                5. **Parameters**:
+                Both \`@parameter\` and \`{parameter}\` notations are supported and parsed.
+            `),
+        },
+        references: {
+            title: 'Reference tokens and pseudo-agents',
+            body: spaceTrim(`
+                - Compact references like \`{Agent Name}\` are resolved by Agents Server reference resolver.
+                - Pseudo-agent forms (for example \`{User}\`, \`{Void}\`) are supported in relevant commitments.
+                - \`{User}\` is intended for \`TEAM\`; \`{Void}\` is useful for explicit no-parent inheritance.
+            `),
+        },
+        keywordsTitle: 'Commitment keywords currently recognized',
+    },
+    commitmentCatalogTitleSuffixes: {
+        usedFirst: ' (used commitments first)',
+        all: ' (all commitments)',
+    },
+    commitmentLabels: {
+        status: 'Status',
+        aliases: 'Aliases',
+        semantics: 'Semantics',
+        typeSchema: 'Type schema',
+        blockSchema: 'Block schema',
+        lowLevelNotice: 'Low-level commitment',
+        usage: 'Used in selected agents',
+        usageOccurrence: 'occurrence',
+        usageOccurrences: 'occurrences',
+        statusImplemented: 'Implemented',
+        statusPlaceholder: 'Placeholder (not fully implemented)',
+        noAliases: 'None',
+    },
+    exampleLabels: {
+        commitmentsUsed: 'Commitments used',
+        fullSource: 'Full source',
+        goal: 'Goal',
+        walkthrough: 'Walkthrough',
+        noCommitments: 'None',
+    },
+    exampleTexts: {
+        'minimal-hello-world-agent': {
+            title: 'Minimal hello-world agent',
+            goal: 'Create the smallest useful agent with identity and greeting.',
+            walkthrough: [
+                'The first line (`Hello World Agent`) is the agent name.',
+                '`GOAL` defines the effective role and profile text.',
+                '`INITIAL MESSAGE` sets a deterministic first message for a new chat.',
+                '`CLOSED` prevents conversational self-modification.',
+            ],
+        },
+        'tool-using-browser-search-agent': {
+            title: 'Tool-using agent (Browser + Search engine)',
+            goal: 'Enable internet research with clear sourcing behavior.',
+            walkthrough: [
+                '`USE SEARCH ENGINE` provides web search tooling and optional search instructions.',
+                '`USE BROWSER` enables URL fetching and interactive browsing tools.',
+                '`RULE` commitments make reliability behavior explicit and repeatable.',
+                'This pattern is ideal for current-events and fact-checking agents.',
+            ],
+        },
+        'rule-and-knowledge-agent': {
+            title: 'Agent with RULE and KNOWLEDGE',
+            goal: 'Ground responses in explicit constraints and curated sources.',
+            walkthrough: [
+                '`KNOWLEDGE` may be inline text or an external URL/document.',
+                '`RULE` commitments define non-negotiable behavior constraints.',
+                'Combining both creates predictable, grounded policy responses.',
+                'Use this pattern for compliance, support, and internal procedures.',
+            ],
+        },
+        'memory-agent-with-long-term-memory': {
+            title: 'MEMORY agent with long-term memory',
+            goal: 'Persist user preferences across conversations.',
+            walkthrough: [
+                '`MEMORY` adds runtime memory tools and memory-specific system guidance.',
+                '`RULE` commitments narrow what should be remembered to reduce privacy risks.',
+                'In Agents Server, memory is runtime-backed and user-scoped.',
+                'Use this for assistants that must preserve context over time.',
+            ],
+        },
+        'use-project-and-wallet-integration-agent': {
+            title: 'USE PROJECT and WALLET external integration',
+            goal: 'Work with GitHub repositories and wallet-backed credentials.',
+            walkthrough: [
+                '`USE PROJECT` enables repository tools for listing, reading, editing files, and creating PRs.',
+                'Credentials are resolved from wallet records at runtime in Agents Server.',
+                '`WALLET` is kept here as a compatibility marker, but current Book 2.0 parsing treats it as ignored.',
+                'In current runtime behavior, wallet-backed integrations are driven by commitments such as `USE PROJECT` and `USE EMAIL`.',
+            ],
+        },
+        'use-calendar-integration-agent': {
+            title: 'USE CALENDAR integration',
+            goal: 'Coordinate meetings and schedules through a connected Google Calendar.',
+            walkthrough: [
+                '`USE CALENDAR` enables calendar tools for listing, reading, creating, updating, and deleting events.',
+                'The first calendar URL identifies which calendar integration should be used.',
+                '`SCOPES` can explicitly request required Google Calendar OAuth permissions.',
+                'Credentials are resolved from wallet-backed Google Calendar OAuth records at runtime in Agents Server.',
+            ],
+        },
+        'agents-team-example': {
+            title: 'Agents TEAM (with in-book teammates)',
+            goal: 'Delegate sub-tasks to specialized teammates.',
+            walkthrough: [
+                'The main agent delegates via `TEAM` commitment.',
+                'References in `{...}` are resolved against embedded agents inside the same book (split by `---`).',
+                'Each teammate can be isolated with `FROM VOID` for deterministic specialization.',
+                'This pattern works well for multi-role review and decision support.',
+            ],
+        },
+    },
+    pitfallLabels: {
+        dont: "Don't",
+        doInstead: 'Do instead',
+    },
+    pitfalls: [
+        {
+            title: 'Too broad agent scope',
+            dont: 'One agent tries to be a lawyer, developer, marketer, and researcher at once.',
+            doInstead: 'Split into focused agents and orchestrate with TEAM or IMPORT.',
+        },
+        {
+            title: 'Unverifiable claims',
+            dont: 'The agent answers internet-dependent questions without tools or without citing sources.',
+            doInstead: 'Add `USE SEARCH ENGINE` / `USE BROWSER` and a citation-oriented `RULE`.',
+        },
+        {
+            title: 'Missing guardrails',
+            dont: 'Only the agent goal is defined, with no behavioral constraints.',
+            doInstead: 'Add concrete `RULE` commitments for safety, scope, and tone.',
+        },
+        {
+            title: 'Overloaded inheritance',
+            dont: 'Using deep `FROM` chains without documenting why each parent is needed.',
+            doInstead: 'Keep inheritance shallow and use focused IMPORT/TEAM composition for reuse.',
+        },
+        {
+            title: 'Unsafe memory usage',
+            dont: 'Storing every detail in memory without boundaries.',
+            doInstead: 'Pair `MEMORY` with explicit rules about what is allowed to persist.',
+        },
+    ],
+    tutorialSections: {
+        serverAgentsHint:
+            'Use one of the selected server-agent examples above as your starting point, then retain only the commitments needed for the new agent.',
+        templateIntro: 'Copy-paste template:',
+        checklistTitle: 'Validation checklist:',
+        checklistBody: spaceTrim(`
+            - Does each commitment have a clear purpose?
+            - Are there explicit constraints against hallucination and unsafe behavior?
+            - Are tools only enabled when genuinely needed?
+            - Is memory usage bounded by clear rules?
+            - Is composition (\`FROM\`/\`TEAM\`/\`IMPORT\`) justified and understandable?
+        `),
+    },
+    footer: {
+        title: 'Generated from:',
+        body: spaceTrim(`
+            - Commitments registry and runtime docs in \`src/commitments\`
+            - Parser/compiler behavior in \`src/book-2.0/agent-source\`
+            - Agents Server reference/inheritance resolution in \`apps/agents-server/src/utils\`
+            - Standalone docs source blocks in \`apps/agents-server/src/utils/bookLanguageDocumentation\`
+        `),
+    },
+};

package/src/book-2.0/book-language-documentation/getBookLanguageManualCommitmentGroups.ts

@@ -0,0 +1,61 @@
+import {
+    getCommitmentNoticeMetadata,
+    isLowVisibilityCommitmentNotice,
+} from '../../commitments/_common/getCommitmentNoticeMetadata';
+import { getGroupedCommitmentDefinitions } from '../../commitments/_common/getGroupedCommitmentDefinitions';
+
+/**
+ * One grouped commitment definition as returned by the runtime registry.
+ *
+ * @private internal type of `createStandaloneBookLanguageMarkdown`
+ */
+export type BookLanguageManualCommitmentGroup = ReturnType<typeof getGroupedCommitmentDefinitions>[number];
+
+/**
+ * Commitment groups of the manual, split by how prominently they are documented.
+ *
+ * @private internal type of `createStandaloneBookLanguageMarkdown`
+ */
+export type BookLanguageManualCommitmentGroups = {
+    /**
+     * Commitments documented in the main catalog.
+     */
+    readonly documented: ReadonlyArray<BookLanguageManualCommitmentGroup>;
+
+    /**
+     * Low-level and unfinished commitments documented in their own closing chapter.
+     */
+    readonly lowLevel: ReadonlyArray<BookLanguageManualCommitmentGroup>;
+};
+
+/**
+ * Splits the commitment registry into the groups documented by the manual.
+ *
+ * Deprecated commitments are intentionally left out completely, so that the
+ * manual never teaches a keyword that should no longer be written into a book.
+ *
+ * @returns Commitment groups for the main catalog and for the low-level chapter.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+export function getBookLanguageManualCommitmentGroups(): BookLanguageManualCommitmentGroups {
+    const documented: Array<BookLanguageManualCommitmentGroup> = [];
+    const lowLevel: Array<BookLanguageManualCommitmentGroup> = [];
+
+    for (const groupedCommitment of getGroupedCommitmentDefinitions()) {
+        const notice = getCommitmentNoticeMetadata(groupedCommitment.primary);
+
+        if (notice?.kind === 'deprecated') {
+            continue;
+        }
+
+        if (isLowVisibilityCommitmentNotice(notice)) {
+            lowLevel.push(groupedCommitment);
+            continue;
+        }
+
+        documented.push(groupedCommitment);
+    }
+
+    return { documented, lowLevel };
+}

package/src/book-2.0/book-language-documentation/getBookLanguageManualDictionary.ts

@@ -0,0 +1,39 @@
+import type { string_language } from '../../types/string_token';
+import type { BookLanguageManualDictionary } from './BookLanguageManualDictionary';
+import { czechBookLanguageManualDictionary } from './czechBookLanguageManualDictionary';
+import { englishBookLanguageManualDictionary } from './englishBookLanguageManualDictionary';
+
+/**
+ * All language packs of the standalone Book language manual.
+ *
+ * Add a new dictionary here to make the manual exportable in one more language.
+ *
+ * @private internal constant of `createStandaloneBookLanguageMarkdown`
+ */
+const BOOK_LANGUAGE_MANUAL_DICTIONARIES: ReadonlyArray<BookLanguageManualDictionary> = [
+    englishBookLanguageManualDictionary,
+    czechBookLanguageManualDictionary,
+];
+
+/**
+ * Resolves the manual dictionary for one requested language.
+ *
+ * Unknown and region-qualified codes (for example `cs-CZ`) fall back to the
+ * closest available pack and finally to English, so an export never fails
+ * because of an unsupported language.
+ *
+ * @param language - Requested language code.
+ * @returns Manual dictionary for the requested language or the English fallback.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+export function getBookLanguageManualDictionary(
+    language: string_language | null | undefined,
+): BookLanguageManualDictionary {
+    const normalizedLanguage = (language || '').trim().toLowerCase().split(/[-_]/)[0];
+
+    return (
+        BOOK_LANGUAGE_MANUAL_DICTIONARIES.find((dictionary) => dictionary.language === normalizedLanguage) ||
+        englishBookLanguageManualDictionary
+    );
+}

package/src/book-2.0/book-language-documentation/getSafeCodeBlock.ts

@@ -0,0 +1,14 @@
+/**
+ * Creates a safe markdown fenced code block even when content contains backticks.
+ *
+ * @param content - Raw code content.
+ * @param language - Optional info-string language label.
+ * @returns Fenced code block.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+export function getSafeCodeBlock(content: string, language = 'markdown'): string {
+    const maxBacktickCount = Math.max(0, ...(content.match(/`+/g) || []).map((match) => match.length));
+    const fence = '`'.repeat(Math.max(3, maxBacktickCount + 1));
+    return `${fence}${language}\n${content}\n${fence}`;
+}

package/src/book-2.0/book-language-documentation/renderCommitmentCatalogSection.ts

@@ -0,0 +1,110 @@
+import { spaceTrim } from 'spacetrim';
+import { NotYetImplementedCommitmentDefinition } from '../../commitments/_base/NotYetImplementedCommitmentDefinition';
+import {
+    formatCommitmentReplacementText,
+    getCommitmentNoticeMetadata,
+} from '../../commitments/_common/getCommitmentNoticeMetadata';
+import type { BookLanguageManualDictionary } from './BookLanguageManualDictionary';
+import type { BookLanguageManualCommitmentGroup } from './getBookLanguageManualCommitmentGroups';
+import { renderGroupedCommitmentDocumentationMarkdown } from './renderGroupedCommitmentDocumentationMarkdown';
+import { toStableAnchorId } from './toStableAnchorId';
+
+/**
+ * How deep one commitment documentation body is nested inside the catalog.
+ *
+ * A catalog entry is a `###` heading, therefore the `##` sections of the
+ * commitment documentation have to become `####` sections.
+ *
+ * @private internal constant of `renderCommitmentCatalogSection`
+ */
+const COMMITMENT_CATALOG_HEADING_LEVEL_SHIFT = 2;
+
+/**
+ * Options for rendering one commitment section of the generated catalog.
+ *
+ * @private internal type of `createStandaloneBookLanguageMarkdown`
+ */
+export type RenderCommitmentCatalogSectionOptions = {
+    /**
+     * Grouped commitment definition with aliases.
+     */
+    readonly groupedCommitment: BookLanguageManualCommitmentGroup;
+
+    /**
+     * Number of uses across the selected server agents.
+     */
+    readonly usageCount: number;
+
+    /**
+     * Translated labels of the manual.
+     */
+    readonly dictionary: BookLanguageManualDictionary;
+};
+
+/**
+ * Renders one commitment section in the generated catalog.
+ *
+ * @param options - Commitment group, usage statistics, and translated labels.
+ * @returns Markdown section for a single commitment.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+export function renderCommitmentCatalogSection(options: RenderCommitmentCatalogSectionOptions): string {
+    const { groupedCommitment, usageCount, dictionary } = options;
+    const { primary, aliases } = groupedCommitment;
+    const labels = dictionary.commitmentLabels;
+    const notice = getCommitmentNoticeMetadata(primary);
+    const status =
+        primary instanceof NotYetImplementedCommitmentDefinition
+            ? labels.statusPlaceholder
+            : notice
+            ? `${labels.statusImplemented} (${notice.detailLabel})`
+            : labels.statusImplemented;
+    const aliasText = aliases.length === 0 ? labels.noAliases : aliases.map((alias) => `\`${alias}\``).join(', ');
+    const noticeText = notice
+        ? notice.kind === 'deprecated'
+            ? `- **${notice.detailLabel}:** ${notice.message}${formatCommitmentReplacementText(
+                  primary.deprecation?.replacedBy,
+              )}`
+            : `- **${labels.lowLevelNotice}:** ${notice.message}`
+        : '';
+    const usageMarkdown =
+        usageCount > 0
+            ? `- **${labels.usage}:** ${usageCount} ${
+                  usageCount === 1 ? labels.usageOccurrence : labels.usageOccurrences
+              }`
+            : '';
+
+    return spaceTrim(
+        (block) => `
+            ### <a id="commitment-${toStableAnchorId(primary.type)}"></a>${primary.icon} ${primary.type}
+
+            - **${labels.status}:** ${status}
+            - **${labels.aliases}:** ${aliasText}
+            - **${labels.semantics}:** ${primary.description}
+            - **${labels.typeSchema} (\`createTypeRegex\`):** \`${stringifyRegex(primary.createTypeRegex())}\`
+            - **${labels.blockSchema} (\`createRegex\`):** \`${stringifyRegex(primary.createRegex())}\`
+            ${noticeText}
+            ${usageMarkdown}
+
+            ${block(
+                renderGroupedCommitmentDocumentationMarkdown(
+                    groupedCommitment,
+                    COMMITMENT_CATALOG_HEADING_LEVEL_SHIFT,
+                ),
+            )}
+        `,
+    );
+}
+
+/**
+ * Converts a regular expression into a concise literal-like string.
+ *
+ * @param regex - Regex instance.
+ * @returns Printable regex pattern and flags.
+ *
+ * @private internal utility of `renderCommitmentCatalogSection`
+ */
+function stringifyRegex(regex: RegExp): string {
+    return `/${regex.source}/${regex.flags}`;
+}

package/src/book-2.0/book-language-documentation/renderGroupedCommitmentDocumentationMarkdown.ts

@@ -1,5 +1,7 @@
 import { spaceTrim } from 'spacetrim';
 import { getCommitmentDefinition } from '../../commitments/_common/getCommitmentDefinition';
+import type { string_markdown } from '../../types/string_markdown';
+import { shiftMarkdownHeadingLevels } from '../../utils/markdown/shiftMarkdownHeadingLevels';
 
 /**
  * Minimal commitment shape used by documentation renderers.
@@ -47,6 +49,16 @@ const OPEN_COMMITMENT_TYPE = 'OPEN';
  */
 const CLOSED_COMMITMENT_TYPE = 'CLOSED';
 
+/**
+ * Heading level of the sections a commitment documentation body starts with.
+ *
+ * Every commitment body opens with `# TYPE` followed by `##` sections, so a
+ * family subsection heading has to sit exactly one level above those sections.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+const COMMITMENT_DOCUMENTATION_SECTION_HEADING_LEVEL = 2;
+
 /**
  * Removes the top-level heading from one commitment documentation block.
  *
@@ -64,16 +76,24 @@ function removeLeadingTopLevelHeading(markdown: string): string {
  *
  * @param title - Heading label for the subsection.
  * @param documentation - Raw commitment documentation markdown.
- * @returns Markdown subsection with a `####` heading.
+ * @param headingLevelShift - How many levels the whole entry is nested by its host document.
+ * @returns Markdown subsection introducing one commitment of the family.
  *
  * @private internal utility of `createStandaloneBookLanguageMarkdown`
  */
-function renderDocumentationSection(title: string, documentation: string): string {
+function renderDocumentationSection(title: string, documentation: string, headingLevelShift: number): string {
+    const headingPrefix = '#'.repeat(COMMITMENT_DOCUMENTATION_SECTION_HEADING_LEVEL + headingLevelShift);
+
     return spaceTrim(
         (block) => `
-            #### ${title}
+            ${headingPrefix} ${title}
 
-            ${block(removeLeadingTopLevelHeading(documentation))}
+            ${block(
+                shiftMarkdownHeadingLevels(
+                    removeLeadingTopLevelHeading(documentation) as string_markdown,
+                    headingLevelShift + 1,
+                ),
+            )}
         `,
     );
 }
@@ -85,11 +105,15 @@ function renderDocumentationSection(title: string, documentation: string): strin
  * surfaces present them as one conceptual switch instead of two isolated pages.
  *
  * @param group - Grouped commitment metadata.
+ * @param headingLevelShift - How many levels the entry is nested by its host document.
  * @returns Markdown body for the docs page/catalog entry.
  *
  * @private internal utility of `createStandaloneBookLanguageMarkdown`
  */
-export function renderGroupedCommitmentDocumentationMarkdown(group: GroupedCommitmentDocumentationSource): string {
+export function renderGroupedCommitmentDocumentationMarkdown(
+    group: GroupedCommitmentDocumentationSource,
+    headingLevelShift = 0,
+): string {
     const commitmentTypes = new Set([group.primary.type, ...group.aliases]);
 
     if (commitmentTypes.has(OPEN_COMMITMENT_TYPE) && commitmentTypes.has(CLOSED_COMMITMENT_TYPE)) {
@@ -99,15 +123,28 @@ export function renderGroupedCommitmentDocumentationMarkdown(group: GroupedCommi
         if (openCommitmentDefinition && closedCommitmentDefinition) {
             return spaceTrim(
                 (block) => `
-                    ${block(renderDocumentationSection(OPEN_COMMITMENT_TYPE, openCommitmentDefinition.documentation))}
+                    ${block(
+                        renderDocumentationSection(
+                            OPEN_COMMITMENT_TYPE,
+                            openCommitmentDefinition.documentation,
+                            headingLevelShift,
+                        ),
+                    )}
 
                     ${block(
-                        renderDocumentationSection(CLOSED_COMMITMENT_TYPE, closedCommitmentDefinition.documentation),
+                        renderDocumentationSection(
+                            CLOSED_COMMITMENT_TYPE,
+                            closedCommitmentDefinition.documentation,
+                            headingLevelShift,
+                        ),
                     )}
                 `,
             );
         }
     }
 
-    return removeLeadingTopLevelHeading(group.primary.documentation);
+    return shiftMarkdownHeadingLevels(
+        removeLeadingTopLevelHeading(group.primary.documentation) as string_markdown,
+        headingLevelShift,
+    );
 }