@libar-dev/architect 1.0.0-pre.3 → 1.0.0-pre.5

package/dist/renderable/codecs/reference.js

@@ -1,1578 +0,0 @@
-/**
- * @architect
- * @architect-pattern ReferenceDocumentCodec
- * @architect-status active
- * @architect-implements CodecDrivenReferenceGeneration
- * @architect-convention codec-registry
- * @architect-product-area:Generation
- *
- * ## ReferenceDocumentCodec
- *
- * A single codec factory that creates reference document codecs from
- * configuration objects. Convention content is sourced from
- * decision records tagged with @architect-convention.
- *
- * **Purpose:** Scoped reference documentation assembling four content layers (conventions, diagrams, shapes, behaviors) into a single document.
- *
- * **Output Files:** Configured per-instance (e.g., `docs/REFERENCE-SAMPLE.md`, `_claude-md/architecture/reference-sample.md`)
- *
- * ### 4-Layer Composition (in order)
- *
- * 1. **Convention content** -- Extracted from `@architect-convention`-tagged patterns (rules, invariants, tables)
- * 2. **Scoped diagrams** -- Mermaid diagrams filtered by `archContext`, `archLayer`, `patterns`, or `include` tags
- * 3. **TypeScript shapes** -- API surfaces from `shapeSelectors` (declaration-level filtering)
- * 4. **Behavior content** -- Gherkin-sourced patterns from `behaviorCategories`
- *
- * ### Key Options (ReferenceDocConfig)
- *
- * | Option | Type | Description |
- * | --- | --- | --- |
- * | conventionTags | string[] | Convention tag values to extract from decision records |
- * | diagramScopes | DiagramScope[] | Multiple diagrams |
- * | shapeSelectors | ShapeSelector[] | Fine-grained declaration-level shape filtering |
- * | behaviorCategories | string[] | Category tags for behavior pattern content |
- * | includeTags | string[] | Cross-cutting content routing via include tags |
- * | preamble | SectionBlock[] | Static editorial sections prepended before generated content |
- * | productArea | string | Pre-filter all content sources to matching product area |
- * | excludeSourcePaths | string[] | Exclude patterns by source path prefix |
- *
- * ### DiagramScope.diagramType Values
- *
- * | Type | Description |
- * | --- | --- |
- * | graph (default) | Flowchart with subgraphs by archContext, custom node shapes |
- * | sequenceDiagram | Sequence diagram with typed messages between participants |
- * | stateDiagram-v2 | State diagram with transitions from dependsOn relationships |
- * | C4Context | C4 context diagram with boundaries, systems, and relationships |
- * | classDiagram | Class diagram with archRole stereotypes and typed arrows |
- *
- * ### ShapeSelector Variants
- *
- * | Variant | Example | Behavior |
- * | --- | --- | --- |
- * | group only | `{ group: "api-types" }` | Match shapes by group tag |
- * | source + names | `{ source: "src/types.ts", names: ["Config"] }` | Named shapes from file |
- * | source only | `{ source: "src/path/*.ts" }` | All tagged shapes from glob |
- *
- * ### When to Use
- *
- * - When generating reference documentation from convention-tagged decisions
- * - When creating scoped product area documents with live diagrams
- * - When creating both detailed (docs/) and summary (_claude-md/) outputs
- * - When assembling multi-layer documents that combine conventions, diagrams, shapes, and behaviors
- *
- * ### Factory Pattern
- *
- * ```typescript
- * const codec = createReferenceCodec(config, { detailLevel: 'detailed' });
- * const doc = codec.decode(dataset);
- * ```
- */
-import { z } from 'zod';
-import { MasterDatasetSchema, } from '../../validation-schemas/master-dataset.js';
-import { heading, paragraph, separator, table, code, list, mermaid, collapsible, linkOut, document, } from '../schema.js';
-import { DEFAULT_BASE_OPTIONS, mergeOptions, } from './types/base.js';
-import { RenderableDocumentOutputSchema } from './shared-schema.js';
-import { extractConventions, extractConventionsFromPatterns, } from './convention-extractor.js';
-import { parseBusinessRuleAnnotations, truncateText } from './helpers.js';
-import { filterShapesBySelectors } from './shape-matcher.js';
-import { sanitizeNodeId, EDGE_STYLES, EDGE_LABELS, SEQUENCE_ARROWS, formatNodeDeclaration, } from './diagram-utils.js';
-import { getPatternName } from '../../api/pattern-helpers.js';
-import { VALID_TRANSITIONS } from '../../validation/fsm/transitions.js';
-import { PROTECTION_LEVELS } from '../../validation/fsm/states.js';
-import { camelCaseToTitleCase, slugify } from '../../utils/string-utils.js';
-// ============================================================================
-// Shared Constants
-// ============================================================================
-/** Content source identifiers for hardcoded domain diagrams */
-export const DIAGRAM_SOURCE_VALUES = [
-    'fsm-lifecycle',
-    'generation-pipeline',
-    'master-dataset-views',
-];
-// ============================================================================
-// Product Area → archContext Mapping (ADR-001)
-// ============================================================================
-/**
- * Maps canonical product area values to their associated archContext values.
- * Product areas are Gherkin-side tags; archContexts are TypeScript-side tags.
- * This mapping bridges the two tagging domains for diagram scoping.
- */
-export const PRODUCT_AREA_ARCH_CONTEXT_MAP = {
-    Annotation: ['scanner', 'extractor', 'taxonomy'],
-    Configuration: ['config'],
-    Generation: ['generator', 'renderer'],
-    Validation: ['validation', 'lint'],
-    DataAPI: ['api', 'cli'],
-    CoreTypes: [],
-    Process: [],
-};
-/**
- * ADR-001 canonical product area metadata for intro sections.
- */
-export const PRODUCT_AREA_META = {
-    Annotation: {
-        question: 'How do I annotate code?',
-        covers: 'Scanning, extraction, tag parsing, dual-source',
-        intro: 'The annotation system is the ingestion boundary — it transforms annotated TypeScript ' +
-            'and Gherkin files into `ExtractedPattern[]` objects that feed the entire downstream ' +
-            'pipeline. Two parallel scanning paths (TypeScript AST + Gherkin parser) converge ' +
-            'through dual-source merging. The system is fully data-driven: the `TagRegistry` ' +
-            'defines all tags, formats, and categories — adding a new annotation requires only ' +
-            'a registry entry, zero parser changes.',
-        diagramScopes: [
-            {
-                archContext: ['scanner', 'extractor'],
-                diagramType: 'C4Context',
-                title: 'Scanning & Extraction Boundary',
-            },
-            {
-                archContext: ['scanner', 'extractor'],
-                direction: 'LR',
-                title: 'Annotation Pipeline',
-            },
-        ],
-        keyInvariants: [
-            'Source ownership enforced: `uses`/`used-by`/`category` belong in TypeScript only; `depends-on`/`quarter`/`team`/`phase` belong in Gherkin only. Anti-pattern detector validates at lint time',
-            'Data-driven tag dispatch: Both AST parser and Gherkin parser use `TagRegistry.metadataTags` to determine extraction. 6 format types (`value`/`enum`/`csv`/`number`/`flag`/`quoted-value`) cover all tag shapes — zero parser changes for new tags',
-            'Pipeline data preservation: Gherkin `Rule:` blocks, deliverables, scenarios, and all metadata flow through scanner → extractor → `ExtractedPattern` → generators without data loss',
-            'Dual-source merge with conflict detection: Same pattern name in both TypeScript and Gherkin produces a merge conflict error. Phase mismatches between sources produce validation errors',
-        ],
-        keyPatterns: [
-            'PatternRelationshipModel',
-            'ShapeExtraction',
-            'DualSourceExtraction',
-            'GherkinRulesSupport',
-            'DeclarationLevelShapeTagging',
-            'CrossSourceValidation',
-            'ExtractionPipelineEnhancementsTesting',
-        ],
-    },
-    Configuration: {
-        question: 'How do I configure the tool?',
-        covers: 'Config loading, presets, resolution, source merging, schema validation',
-        intro: 'Configuration is the entry boundary — it transforms a user-authored ' +
-            '`architect.config.ts` file into a fully resolved `ArchitectInstance` ' +
-            'that powers the entire pipeline. The flow is: `defineConfig()` provides type-safe ' +
-            'authoring (Vite convention, zero validation), `ConfigLoader` discovers and loads ' +
-            'the file, `ProjectConfigSchema` validates via Zod, `ConfigResolver` applies defaults ' +
-            'and merges stubs into sources, and `ArchitectFactory` builds the final instance ' +
-            'with `TagRegistry` and `RegexBuilders`. Two presets define escalating taxonomy ' +
-            'complexity — from 3 categories (`libar-generic`) to 21 (`ddd-es-cqrs`). ' +
-            '`SourceMerger` computes per-generator source overrides, enabling generators like ' +
-            'changelog to pull from different feature sets than the base config.',
-        diagramScopes: [
-            {
-                archContext: ['config'],
-                diagramType: 'C4Context',
-                title: 'Configuration Loading Boundary',
-            },
-            {
-                archContext: ['config'],
-                direction: 'LR',
-                title: 'Configuration Resolution Pipeline',
-            },
-        ],
-        keyInvariants: [
-            'Preset-based taxonomy: `libar-generic` (3 categories, `@architect-`) and `ddd-es-cqrs` (21 categories, full DDD). Presets replace base categories entirely — they define prefix, categories, and metadata tags as a unit',
-            'Resolution pipeline: defineConfig() → ConfigLoader → ProjectConfigSchema (Zod) → ConfigResolver → ArchitectFactory → ArchitectInstance. Each stage has a single responsibility',
-            'Stubs merged at resolution time: Stub directory globs are appended to typescript sources, making stubs transparent to the downstream pipeline',
-            'Source override composition: SourceMerger applies per-generator overrides (`replaceFeatures`, `additionalFeatures`, `additionalInput`) to base sources. Exclude is always inherited from base',
-        ],
-        keyPatterns: [
-            'ArchitectFactory',
-            'ConfigLoader',
-            'ConfigResolver',
-            'DefineConfig',
-            'ConfigurationPresets',
-            'SourceMerger',
-        ],
-    },
-    Generation: {
-        question: 'How does code become docs?',
-        covers: 'Codecs, generators, orchestrator, rendering, diagrams, progressive disclosure, product areas, RenderableDocument IR',
-        intro: 'The generation pipeline transforms annotated source code into markdown documents through a ' +
-            'four-stage architecture: Scanner discovers files, Extractor produces `ExtractedPattern` objects, ' +
-            'Transformer builds MasterDataset with pre-computed views, and Codecs render to markdown via ' +
-            'RenderableDocument IR. Nine specialized codecs handle reference docs, planning, session, reporting, ' +
-            'timeline, ADRs, business rules, taxonomy, and composite output — each supporting three detail levels ' +
-            '(detailed, standard, summary). The Orchestrator runs generators in registration order, producing both ' +
-            'detailed `docs-live/` references and compact `_claude-md/` summaries.',
-        introSections: [
-            heading(3, 'Pipeline Stages'),
-            table(['Stage', 'Module', 'Responsibility'], [
-                ['Scanner', '`src/scanner/`', 'File discovery, AST parsing, opt-in via `@architect`'],
-                [
-                    'Extractor',
-                    '`src/extractor/`',
-                    'Pattern extraction from TypeScript JSDoc and Gherkin tags',
-                ],
-                [
-                    'Transformer',
-                    '`src/generators/pipeline/`',
-                    'MasterDataset with pre-computed views for O(1) access (ADR-006)',
-                ],
-                [
-                    'Codec',
-                    '`src/renderable/`',
-                    'Pure functions: MasterDataset → RenderableDocument → Markdown',
-                ],
-            ]),
-            heading(3, 'Codec Inventory'),
-            table(['Codec', 'Purpose'], [
-                [
-                    'ReferenceDocumentCodec',
-                    'Conventions, diagrams, shapes, behaviors (4-layer composition)',
-                ],
-                ['PlanningCodec', 'Roadmap and remaining work'],
-                ['SessionCodec', 'Current work and session findings'],
-                ['ReportingCodec', 'Changelog'],
-                ['TimelineCodec', 'Timeline and traceability'],
-                ['RequirementsAdrCodec', 'ADR generation'],
-                ['BusinessRulesCodec', 'Gherkin rule extraction'],
-                ['TaxonomyCodec', 'Tag registry docs'],
-                ['CompositeCodec', 'Composes multiple codecs into a single document'],
-            ]),
-        ],
-        keyInvariants: [
-            'Codec purity: Every codec is a pure function (dataset in, document out). No side effects, no filesystem access. Same input always produces same output',
-            'Single read model (ADR-006): All codecs consume MasterDataset. No codec reads raw scanner/extractor output. Anti-patterns: Parallel Pipeline, Lossy Local Type, Re-derived Relationship',
-            'Progressive disclosure: Every document renders at three detail levels (detailed, standard, summary) from the same codec. Summary feeds `_claude-md/` modules; detailed feeds `docs-live/reference/`',
-            'Config-driven generation: A single `ReferenceDocConfig` produces a complete document. Content sources compose in fixed order: conventions, diagrams, shapes, behaviors',
-            'RenderableDocument IR: Codecs express intent ("this is a table"), the renderer handles syntax ("pipe-delimited markdown"). Switching output format requires only a new renderer',
-            'Composition order: Reference docs compose four content layers in fixed order. Product area docs compose five layers: intro, conventions, diagrams, shapes, business rules',
-            'Shape extraction: TypeScript shapes (`interface`, `type`, `enum`, `function`, `const`) are extracted by declaration-level `@architect-shape` tags. Shapes include source text, JSDoc, type parameters, and property documentation',
-            'Generator registration: Generators self-register via `registerGenerator()`. The orchestrator runs them in registration order. Each generator owns its output files and codec configuration',
-        ],
-        keyPatterns: [
-            'ADR005CodecBasedMarkdownRendering',
-            'CodecDrivenReferenceGeneration',
-            'CrossCuttingDocumentInclusion',
-            'ArchitectureDiagramGeneration',
-            'ScopedArchitecturalView',
-            'CompositeCodec',
-            'RenderableDocument',
-            'ProductAreaOverview',
-        ],
-    },
-    Validation: {
-        question: 'How is the workflow enforced?',
-        covers: 'FSM, DoD, anti-patterns, process guard, lint',
-        intro: 'Validation is the enforcement boundary — it ensures that every change to annotated source files ' +
-            'respects the delivery lifecycle rules defined by the FSM, protection levels, and scope constraints. ' +
-            'The system operates in three layers: the FSM validator checks status transitions against a 4-state ' +
-            'directed graph, the Process Guard orchestrates commit-time validation using a Decider pattern ' +
-            '(state derived from annotations, not stored separately), and the lint engine provides pluggable ' +
-            'rule execution with pretty and JSON output. Anti-pattern detection enforces dual-source ownership ' +
-            'boundaries — `@architect-uses` belongs on TypeScript, `@architect-depends-on` belongs on Gherkin — ' +
-            'preventing cross-domain tag confusion that causes documentation drift. Definition of Done validation ' +
-            'ensures completed patterns have all deliverables marked done and at least one acceptance-criteria scenario.',
-        diagramScopes: [
-            {
-                archContext: ['validation', 'lint'],
-                diagramType: 'C4Context',
-                title: 'Validation & Lint Boundary',
-            },
-            {
-                archContext: ['validation', 'lint'],
-                direction: 'LR',
-                title: 'Enforcement Pipeline',
-            },
-        ],
-        keyInvariants: [
-            'Protection levels: `roadmap`/`deferred` = none (fully editable), `active` = scope-locked (no new deliverables), `completed` = hard-locked (requires `@architect-unlock-reason`)',
-            'Valid FSM transitions: Only roadmap→active, roadmap→deferred, active→completed, active→roadmap, deferred→roadmap. Completed is terminal',
-            'Decider pattern: All validation is (state, changes, options) → result. State is derived from annotations, not maintained separately',
-            'Dual-source ownership: Anti-pattern detection enforces tag boundaries — `uses` on TypeScript (runtime deps), `depends-on`/`quarter`/`team` on Gherkin (planning metadata). Violations are flagged before they cause documentation drift',
-        ],
-        keyPatterns: [
-            'ProcessGuardLinter',
-            'PhaseStateMachineValidation',
-            'DoDValidation',
-            'StepLintVitestCucumber',
-            'ProgressiveGovernance',
-        ],
-    },
-    DataAPI: {
-        question: 'How do I query process state?',
-        covers: 'Process state API, stubs, context assembly, CLI',
-        intro: 'The Data API provides direct terminal access to project state. ' +
-            'It replaces reading generated markdown or launching explore agents — targeted queries ' +
-            'use 5-10x less context. The `context` command assembles curated bundles tailored to ' +
-            'session type (planning, design, implement).',
-        keyInvariants: [
-            'One-command context assembly: `context <pattern> --session <type>` returns metadata + file paths + dependency status + architecture position in ~1.5KB',
-            'Session type tailoring: `planning` (~500B, brief + deps), `design` (~1.5KB, spec + stubs + deps), `implement` (deliverables + FSM + tests)',
-            'Direct API queries replace doc reading: JSON output is 5-10x smaller than generated docs',
-        ],
-        keyPatterns: [
-            'DataAPIContextAssembly',
-            'ProcessStateAPICLI',
-            'DataAPIDesignSessionSupport',
-            'DataAPIRelationshipGraph',
-            'DataAPIOutputShaping',
-        ],
-    },
-    CoreTypes: {
-        question: 'What foundational types exist?',
-        covers: 'Result monad, error factories, branded types, string utils',
-        intro: 'CoreTypes provides the foundational type system used across all other areas. Three pillars ' +
-            'enforce discipline at compile time: the Result monad replaces try/catch with explicit ' +
-            'error handling — functions return `Result.ok(value)` or `Result.err(error)` instead of ' +
-            'throwing. The DocError discriminated union provides structured error context with type, ' +
-            'file, line, and reason fields, enabling exhaustive pattern matching in error handlers. ' +
-            'Branded types create nominal typing from structural TypeScript — `PatternId`, ' +
-            '`CategoryName`, and `SourceFilePath` are compile-time distinct despite all being strings. ' +
-            'String utilities handle slugification and case conversion with acronym-aware title casing.',
-        diagramScopes: [
-            {
-                include: ['core-types'],
-                diagramType: 'C4Context',
-                title: 'Core Type System',
-            },
-            {
-                include: ['core-types'],
-                direction: 'LR',
-                title: 'Error Handling Flow',
-            },
-        ],
-        keyInvariants: [
-            'Result over try/catch: All functions return `Result<T, E>` instead of throwing. Compile-time verification that errors are handled. `isOk`/`isErr` type guards enable safe narrowing',
-            'DocError discriminated union: 12 structured error types with `type` discriminator field. `isDocError` type guard for safe classification. Specialized union aliases (`ScanError`, `ExtractionError`) scope error handling per operation',
-            'Branded nominal types: `Branded<T, Brand>` creates compile-time distinct types from structural TypeScript. Prevents mixing `PatternId` with `CategoryName` even though both are `string` at runtime',
-            'String transformation consistency: `slugify` produces URL-safe identifiers, `camelCaseToTitleCase` preserves acronyms (e.g., "APIEndpoint" becomes "API Endpoint"), `toKebabCase` handles consecutive uppercase correctly',
-        ],
-        keyPatterns: [
-            'ResultMonad',
-            'ErrorHandlingUnification',
-            'ErrorFactories',
-            'StringUtils',
-            'KebabCaseSlugs',
-        ],
-    },
-    Process: {
-        question: 'How does the session workflow work?',
-        covers: 'Session lifecycle, handoffs, FSM alignment, governance decisions, conventions',
-        intro: 'Process defines the USDP-inspired session workflow that governs how work moves through ' +
-            'the delivery lifecycle. Three session types (planning, design, implementation) have fixed ' +
-            'input/output contracts: planning creates roadmap specs from pattern briefs, design produces ' +
-            'code stubs and decision records, and implementation writes code against scope-locked specs. ' +
-            'Git is the event store — documentation artifacts are projections of annotated source code, ' +
-            'not hand-maintained files. The FSM enforces state transitions (roadmap → active → completed) ' +
-            'with escalating protection levels, while handoff templates preserve context across LLM session ' +
-            'boundaries. ADR-003 established that TypeScript source owns pattern identity; tier 1 specs ' +
-            'are ephemeral planning documents that lose value after completion.',
-        diagramScopes: [
-            {
-                source: 'fsm-lifecycle',
-                title: 'Delivery Lifecycle FSM',
-            },
-            {
-                include: ['process-workflow'],
-                direction: 'LR',
-                title: 'Process Pattern Relationships',
-            },
-        ],
-        keyInvariants: [
-            'TypeScript source owns pattern identity: `@architect-pattern` in TypeScript defines the pattern. Tier 1 specs are ephemeral working documents',
-            '7 canonical product-area values: Annotation, Configuration, Generation, Validation, DataAPI, CoreTypes, Process — reader-facing sections, not source modules',
-            'Two distinct status domains: Pattern FSM status (4 values) vs. deliverable status (6 values). Never cross domains',
-            'Session types define capabilities: planning creates specs, design creates stubs, implementation writes code. Each session type has a fixed input/output contract enforced by convention',
-        ],
-        keyPatterns: [
-            'ADR001TaxonomyCanonicalValues',
-            'ADR003SourceFirstPatternArchitecture',
-            'MvpWorkflowImplementation',
-            'SessionHandoffs',
-        ],
-    },
-};
-const DEFAULT_REFERENCE_OPTIONS = {
-    ...DEFAULT_BASE_OPTIONS,
-    detailLevel: 'standard',
-};
-// ============================================================================
-// Codec Factory
-// ============================================================================
-/**
- * Creates a reference document codec from configuration.
- *
- * The codec composes a RenderableDocument from up to four sources:
- * 1. Convention content from convention-tagged decision records
- * 2. Scoped relationship diagram (if diagramScopes configured)
- * 3. TypeScript shapes from selector-matched patterns
- * 4. Behavior content from category-tagged patterns
- *
- * @param config - Reference document configuration
- * @param options - Codec options including DetailLevel
- */
-export function createReferenceCodec(config, options) {
-    const opts = mergeOptions(DEFAULT_REFERENCE_OPTIONS, options);
-    return z.codec(MasterDatasetSchema, RenderableDocumentOutputSchema, {
-        decode: (dataset) => {
-            const sections = [];
-            // Product area filtering: when set, pre-filter and auto-derive content sources
-            // Preamble is applied inside decodeProductArea() — not here, to avoid dead code
-            if (config.productArea !== undefined) {
-                return decodeProductArea(dataset, config, opts);
-            }
-            // DD-1 (CrossCuttingDocumentInclusion): Pre-compute include set for additive merging
-            const includeSet = config.includeTags !== undefined && config.includeTags.length > 0
-                ? new Set(config.includeTags)
-                : undefined;
-            // 1. Convention content from tagged decision records
-            const conventions = extractConventions(dataset, config.conventionTags);
-            // DD-1: Merge include-tagged convention patterns (additive)
-            if (includeSet !== undefined) {
-                const existingNames = new Set(conventions.flatMap((b) => b.sourceDecisions));
-                const includedConventionPatterns = dataset.patterns.filter((p) => !existingNames.has(p.name) &&
-                    p.include?.some((v) => includeSet.has(v)) === true &&
-                    p.convention !== undefined &&
-                    p.convention.length > 0);
-                if (includedConventionPatterns.length > 0) {
-                    // Build bundles from included convention patterns
-                    const includedConventions = extractConventionsFromPatterns(includedConventionPatterns);
-                    conventions.push(...includedConventions);
-                }
-            }
-            const conventionBlocks = conventions.length > 0 ? buildConventionSections(conventions, opts.detailLevel) : [];
-            // 2. Scoped relationship diagrams
-            const diagramBlocks = [];
-            if (opts.detailLevel !== 'summary') {
-                const scopes = config.diagramScopes ?? [];
-                for (const scope of scopes) {
-                    const diagramSections = buildScopedDiagram(dataset, scope);
-                    if (diagramSections.length > 0) {
-                        diagramBlocks.push(...diagramSections);
-                    }
-                }
-            }
-            // 3. Shape extraction: selector-based filtering only
-            const shapeBlocks = [];
-            {
-                const allShapes = config.shapeSelectors !== undefined && config.shapeSelectors.length > 0
-                    ? [...filterShapesBySelectors(dataset, config.shapeSelectors)]
-                    : [];
-                const seenNames = new Set(allShapes.map((s) => s.name));
-                // DD-1: Merge include-tagged shapes (additive)
-                if (includeSet !== undefined) {
-                    for (const pattern of dataset.patterns) {
-                        if (pattern.extractedShapes === undefined || pattern.extractedShapes.length === 0)
-                            continue;
-                        for (const shape of pattern.extractedShapes) {
-                            if (!seenNames.has(shape.name) &&
-                                shape.includes?.some((v) => includeSet.has(v)) === true) {
-                                seenNames.add(shape.name);
-                                allShapes.push(shape);
-                            }
-                        }
-                    }
-                }
-                if (allShapes.length > 0) {
-                    shapeBlocks.push(...buildShapeSections(allShapes, opts.detailLevel));
-                }
-            }
-            // 4. Behavior content from tagged patterns
-            const behaviorPatterns = config.behaviorCategories.length > 0
-                ? dataset.patterns.filter((p) => config.behaviorCategories.includes(p.category))
-                : [];
-            // DD-1: Merge include-tagged behavior patterns (additive)
-            if (includeSet !== undefined) {
-                const existingNames = new Set(behaviorPatterns.map((p) => p.name));
-                const includedBehaviors = dataset.patterns.filter((p) => !existingNames.has(p.name) &&
-                    p.include?.some((v) => includeSet.has(v)) === true &&
-                    (p.directive.description.length > 0 || (p.rules !== undefined && p.rules.length > 0)));
-                behaviorPatterns.push(...includedBehaviors);
-            }
-            const behaviorBlocks = behaviorPatterns.length > 0
-                ? buildBehaviorSectionsFromPatterns(behaviorPatterns, opts.detailLevel)
-                : [];
-            // Static preamble: editorial sections before generated content
-            if (config.preamble !== undefined && config.preamble.length > 0) {
-                sections.push(...config.preamble);
-                sections.push(separator());
-            }
-            // DD-4 (GeneratedDocQuality): Assemble in configured order
-            if (config.shapesFirst === true) {
-                sections.push(...shapeBlocks, ...conventionBlocks, ...diagramBlocks, ...behaviorBlocks);
-            }
-            else {
-                sections.push(...conventionBlocks, ...diagramBlocks, ...shapeBlocks, ...behaviorBlocks);
-            }
-            if (sections.length === 0) {
-                const diagnostics = [];
-                if (config.conventionTags.length > 0) {
-                    diagnostics.push(`conventions [${config.conventionTags.join(', ')}]`);
-                }
-                if (config.shapeSelectors !== undefined && config.shapeSelectors.length > 0) {
-                    diagnostics.push(`selectors [${config.shapeSelectors.length} selectors]`);
-                }
-                if (config.behaviorCategories.length > 0) {
-                    diagnostics.push(`behaviors [${config.behaviorCategories.join(', ')}]`);
-                }
-                if (includeSet !== undefined) {
-                    diagnostics.push(`includeTags [${[...includeSet].join(', ')}]`);
-                }
-                sections.push(paragraph(`No content found. Sources checked: ${diagnostics.join('; ')}.`));
-            }
-            return document(config.title, sections, {
-                purpose: `Reference document: ${config.title}`,
-                detailLevel: opts.detailLevel === 'summary' ? 'Compact summary' : 'Full reference',
-            });
-        },
-        encode: () => {
-            throw new Error('ReferenceDocumentCodec is decode-only');
-        },
-    });
-}
-// ============================================================================
-// Product Area Decode Path
-// ============================================================================
-/**
- * Decode a product-area-scoped reference document.
- *
- * When `config.productArea` is set, this function replaces the standard decode
- * path. It pre-filters all patterns by product area and auto-derives content
- * sources from the filtered set rather than relying on explicit config arrays.
- *
- * Document structure:
- * 1. Intro (reader question + coverage from ADR-001 metadata)
- * 2. Invariant rules from executable specs (conventions + behavior rules)
- * 3. Architecture diagrams (auto-scoped via productArea→archContext mapping)
- * 4. Key API types (shapes from TypeScript patterns in this area)
- * 5. Behavior specifications (all patterns with rules/descriptions)
- */
-function decodeProductArea(dataset, config, opts) {
-    const area = config.productArea;
-    if (area === undefined) {
-        return document('Error', [paragraph('No product area specified.')], {});
-    }
-    const sections = [];
-    // Static preamble: editorial sections before generated content
-    if (config.preamble !== undefined && config.preamble.length > 0) {
-        sections.push(...config.preamble);
-        sections.push(separator());
-    }
-    // Pre-computed view: O(1) lookup instead of linear filter
-    const areaPatterns = dataset.byProductArea[area] ?? [];
-    // Collect TypeScript patterns by explicit archContext tag (for shapes + diagrams)
-    // Note: archIndex.byContext includes inferred contexts — use explicit filter to match only tagged patterns
-    const archContexts = PRODUCT_AREA_ARCH_CONTEXT_MAP[area] ?? [];
-    const contextSet = new Set(archContexts);
-    const tsPatterns = contextSet.size > 0
-        ? dataset.patterns.filter((p) => p.archContext !== undefined && contextSet.has(p.archContext))
-        : [];
-    // 1. Intro section from ADR-001 metadata with key invariants
-    const meta = PRODUCT_AREA_META[area];
-    if (meta !== undefined) {
-        sections.push(paragraph(`**${meta.question}** ${meta.intro}`));
-        if (meta.introSections !== undefined && opts.detailLevel === 'detailed') {
-            sections.push(...meta.introSections);
-        }
-        if (meta.keyInvariants.length > 0) {
-            sections.push(heading(2, 'Key Invariants'));
-            sections.push(list([...meta.keyInvariants]));
-        }
-        sections.push(separator());
-    }
-    // 2. Convention/invariant content from area patterns with convention tags
-    const conventionPatterns = areaPatterns.filter((p) => p.convention !== undefined && p.convention.length > 0);
-    if (conventionPatterns.length > 0) {
-        const conventions = extractConventionsFromPatterns(conventionPatterns);
-        if (conventions.length > 0) {
-            sections.push(...buildConventionSections(conventions, opts.detailLevel));
-        }
-    }
-    // 3. Architecture diagrams — priority: config > meta > auto-generate
-    if (opts.detailLevel !== 'summary') {
-        const scopes = config.diagramScopes ?? meta?.diagramScopes ?? [];
-        if (scopes.length > 0) {
-            // Explicit scopes from config or meta — always render
-            for (const scope of scopes) {
-                const diagramSections = buildScopedDiagram(dataset, scope);
-                if (diagramSections.length > 0) {
-                    sections.push(...diagramSections);
-                }
-            }
-        }
-        else if (archContexts.length > 0) {
-            // Auto-generate fallback — only when archContext mappings exist
-            const autoScope = {
-                archContext: archContexts,
-                direction: 'TB',
-                title: `${area} Components`,
-            };
-            const diagramSections = buildScopedDiagram(dataset, autoScope);
-            if (diagramSections.length > 0) {
-                sections.push(...diagramSections);
-            }
-        }
-    }
-    else {
-        // Compact boundary summary for summary-level documents (replaces diagrams)
-        const scopes = config.diagramScopes ?? meta?.diagramScopes ?? [];
-        const summary = buildBoundarySummary(dataset, scopes);
-        if (summary !== undefined) {
-            sections.push(summary);
-        }
-    }
-    // 4. Shapes from TypeScript patterns in this product area
-    {
-        const allShapes = [];
-        const seenNames = new Set();
-        const seenPatternNames = new Set();
-        // Collect shapes from all patterns associated with this area
-        for (const pattern of [...areaPatterns, ...tsPatterns]) {
-            if (seenPatternNames.has(pattern.name))
-                continue;
-            seenPatternNames.add(pattern.name);
-            if (pattern.extractedShapes === undefined || pattern.extractedShapes.length === 0)
-                continue;
-            for (const shape of pattern.extractedShapes) {
-                if (!seenNames.has(shape.name)) {
-                    seenNames.add(shape.name);
-                    allShapes.push(shape);
-                }
-            }
-        }
-        if (config.shapeSelectors !== undefined && config.shapeSelectors.length > 0) {
-            for (const shape of filterShapesBySelectors(dataset, config.shapeSelectors)) {
-                if (!seenNames.has(shape.name)) {
-                    seenNames.add(shape.name);
-                    allShapes.push(shape);
-                }
-            }
-        }
-        if (allShapes.length > 0) {
-            // Prioritize interfaces and types over functions/variables to keep
-            // product area docs focused on key API types, not implementation details.
-            const kindOrder = {
-                interface: 0,
-                type: 1,
-                enum: 2,
-                function: 3,
-                const: 4,
-            };
-            const sorted = [...allShapes].sort((a, b) => (kindOrder[a.kind] ?? 5) - (kindOrder[b.kind] ?? 5));
-            const maxShapes = opts.detailLevel === 'detailed' ? 30 : 20;
-            const limited = sorted.slice(0, maxShapes);
-            sections.push(...buildShapeSections(limited, opts.detailLevel));
-        }
-    }
-    // 5. Compact business rules index (replaces verbose Behavior Specifications)
-    // Shows only rule name, invariant, and rationale per rule in tables
-    const rulesPatterns = areaPatterns.filter((p) => (config.excludeSourcePaths === undefined ||
-        config.excludeSourcePaths.length === 0 ||
-        !config.excludeSourcePaths.some((prefix) => p.source.file.startsWith(prefix))) &&
-        p.rules !== undefined &&
-        p.rules.length > 0);
-    if (rulesPatterns.length > 0) {
-        sections.push(...buildBusinessRulesCompactSection(rulesPatterns, opts.detailLevel));
-    }
-    // DD-4 (GeneratedDocQuality): Insert TOC after intro for large product area docs
-    const tocBlocks = buildTableOfContents(sections);
-    if (tocBlocks.length > 0) {
-        const firstSepIdx = sections.findIndex((s) => s.type === 'separator');
-        if (firstSepIdx >= 0) {
-            sections.splice(firstSepIdx + 1, 0, ...tocBlocks);
-        }
-    }
-    if (sections.length === 0) {
-        sections.push(paragraph(`No content found for product area "${area}". ` +
-            `Checked ${areaPatterns.length} patterns by productArea tag, ` +
-            `${tsPatterns.length} patterns by archContext [${archContexts.join(', ')}].`));
-    }
-    return document(config.title, sections, {
-        purpose: `${area} product area overview`,
-        detailLevel: opts.detailLevel === 'summary' ? 'Compact summary' : 'Full reference',
-    });
-}
-// ============================================================================
-// Section Builders
-// ============================================================================
-/**
- * Build sections from convention bundles.
- */
-function buildConventionSections(conventions, detailLevel) {
-    const sections = [];
-    for (const bundle of conventions) {
-        if (bundle.rules.length === 0)
-            continue;
-        for (const rule of bundle.rules) {
-            sections.push(heading(2, rule.ruleName));
-            if (rule.invariant) {
-                sections.push(paragraph(`**Invariant:** ${rule.invariant}`));
-            }
-            if (rule.narrative && detailLevel !== 'summary') {
-                sections.push(paragraph(rule.narrative));
-            }
-            if (rule.rationale && detailLevel === 'detailed') {
-                sections.push(paragraph(`**Rationale:** ${rule.rationale}`));
-            }
-            for (const tbl of rule.tables) {
-                const rows = tbl.rows.map((row) => tbl.headers.map((h) => row[h] ?? ''));
-                sections.push(table([...tbl.headers], rows));
-            }
-            if (rule.codeExamples !== undefined && detailLevel !== 'summary') {
-                for (const example of rule.codeExamples) {
-                    if (example.type === 'code' && example.language === 'mermaid') {
-                        sections.push(mermaid(example.content));
-                    }
-                    else {
-                        sections.push(example);
-                    }
-                }
-            }
-            if (rule.verifiedBy && rule.verifiedBy.length > 0 && detailLevel === 'detailed') {
-                sections.push(paragraph(`**Verified by:** ${rule.verifiedBy.join(', ')}`));
-            }
-            sections.push(separator());
-        }
-    }
-    return sections;
-}
-/**
- * Build sections from a pre-filtered list of behavior patterns.
- *
- * DD-1 (CrossCuttingDocumentInclusion): Extracted from buildBehaviorSections to
- * accept pre-merged patterns (category-selected + include-tagged).
- */
-function buildBehaviorSectionsFromPatterns(patterns, detailLevel) {
-    const sections = [];
-    if (patterns.length === 0)
-        return sections;
-    sections.push(heading(2, 'Behavior Specifications'));
-    for (const pattern of patterns) {
-        sections.push(heading(3, pattern.name));
-        // Cross-reference link to source file (omitted at summary level)
-        if (detailLevel !== 'summary') {
-            sections.push(linkOut(`View ${pattern.name} source`, pattern.source.file));
-        }
-        if (pattern.directive.description && detailLevel !== 'summary') {
-            sections.push(paragraph(pattern.directive.description));
-        }
-        if (pattern.rules && pattern.rules.length > 0) {
-            if (detailLevel === 'summary') {
-                // Compact table with word-boundary-aware truncation
-                const ruleRows = pattern.rules.map((r) => [
-                    r.name,
-                    r.description ? truncateText(r.description, 120) : '',
-                ]);
-                sections.push(table(['Rule', 'Description'], ruleRows));
-            }
-            else {
-                // Structured per-rule rendering with parsed annotations
-                // Wrap in collapsible blocks when 3+ rules for progressive disclosure
-                const wrapInCollapsible = pattern.rules.length >= 3;
-                for (const rule of pattern.rules) {
-                    const ruleBlocks = [];
-                    ruleBlocks.push(heading(4, rule.name));
-                    const annotations = parseBusinessRuleAnnotations(rule.description);
-                    if (annotations.invariant) {
-                        ruleBlocks.push(paragraph(`**Invariant:** ${annotations.invariant}`));
-                    }
-                    if (annotations.rationale && detailLevel === 'detailed') {
-                        ruleBlocks.push(paragraph(`**Rationale:** ${annotations.rationale}`));
-                    }
-                    if (annotations.remainingContent) {
-                        ruleBlocks.push(paragraph(annotations.remainingContent));
-                    }
-                    if (annotations.codeExamples && detailLevel === 'detailed') {
-                        for (const example of annotations.codeExamples) {
-                            ruleBlocks.push(example);
-                        }
-                    }
-                    // Merged scenario names + verifiedBy as deduplicated list
-                    const names = new Set(rule.scenarioNames);
-                    if (annotations.verifiedBy) {
-                        for (const v of annotations.verifiedBy) {
-                            names.add(v);
-                        }
-                    }
-                    if (names.size > 0) {
-                        ruleBlocks.push(paragraph('**Verified by:**'));
-                        ruleBlocks.push(list([...names]));
-                    }
-                    if (wrapInCollapsible) {
-                        const scenarioCount = rule.scenarioNames.length;
-                        const summary = scenarioCount > 0 ? `${rule.name} (${scenarioCount} scenarios)` : rule.name;
-                        sections.push(collapsible(summary, ruleBlocks));
-                    }
-                    else {
-                        sections.push(...ruleBlocks);
-                    }
-                }
-            }
-        }
-    }
-    sections.push(separator());
-    return sections;
-}
-/**
- * Build a compact business rules index section.
- *
- * Replaces the verbose Behavior Specifications in product area docs.
- * Groups rules by pattern, showing only rule name, invariant, and rationale.
- * Always renders open H3 headings with tables for immediate scannability.
- *
- * Detail level controls:
- * - summary: Section omitted entirely
- * - standard: Rules with invariants only; truncated to 150/120 chars
- * - detailed: All rules; full text, no truncation
- */
-function buildBusinessRulesCompactSection(patterns, detailLevel) {
-    if (detailLevel === 'summary')
-        return [];
-    const sections = [];
-    // Count totals for header (lightweight pass — no annotation parsing)
-    let totalRules = 0;
-    let totalInvariants = 0;
-    for (const p of patterns) {
-        if (p.rules === undefined)
-            continue;
-        for (const r of p.rules) {
-            totalRules++;
-            if (r.description.includes('**Invariant:**'))
-                totalInvariants++;
-        }
-    }
-    if (totalRules === 0)
-        return sections;
-    sections.push(heading(2, 'Business Rules'));
-    sections.push(paragraph(`${String(patterns.length)} patterns, ` +
-        `${String(totalInvariants)} rules with invariants ` +
-        `(${String(totalRules)} total)`));
-    const isDetailed = detailLevel === 'detailed';
-    const maxInvariant = isDetailed ? 0 : 150;
-    const maxRationale = isDetailed ? 0 : 120;
-    const sorted = [...patterns].sort((a, b) => a.name.localeCompare(b.name));
-    for (const pattern of sorted) {
-        if (pattern.rules === undefined)
-            continue;
-        const rows = [];
-        for (const rule of pattern.rules) {
-            const ann = parseBusinessRuleAnnotations(rule.description);
-            // At standard level, skip rules without invariant
-            if (!isDetailed && ann.invariant === undefined)
-                continue;
-            const invariantText = ann.invariant ?? '';
-            const rationaleText = ann.rationale ?? '';
-            rows.push([
-                rule.name,
-                maxInvariant > 0 ? truncateText(invariantText, maxInvariant) : invariantText,
-                maxRationale > 0 ? truncateText(rationaleText, maxRationale) : rationaleText,
-            ]);
-        }
-        if (rows.length === 0)
-            continue;
-        sections.push(heading(3, camelCaseToTitleCase(pattern.name)));
-        sections.push(table(['Rule', 'Invariant', 'Rationale'], rows));
-    }
-    sections.push(separator());
-    return sections;
-}
-/**
- * Build a table of contents from H2 headings in a sections array.
- *
- * DD-4 (GeneratedDocQuality): Product area docs can be 100+ KB with many
- * sections. A TOC at the top makes browser navigation practical. Only
- * generated when there are 3 or more H2 headings (below that, a TOC adds
- * noise without navigation value).
- */
-function buildTableOfContents(allSections) {
-    const h2Headings = allSections.filter((s) => s.type === 'heading' && s.level === 2);
-    if (h2Headings.length < 3)
-        return [];
-    const tocItems = h2Headings.map((h) => {
-        const anchor = slugify(h.text);
-        return `[${h.text}](#${anchor})`;
-    });
-    return [heading(2, 'Contents'), list(tocItems), separator()];
-}
-/**
- * Build sections from extracted TypeScript shapes.
- *
- * Composition order follows AD-5: conventions → shapes → behaviors.
- *
- * Detail level controls:
- * - summary: type name + kind table only (compact)
- * - standard: names + source text code blocks
- * - detailed: full source with JSDoc and property doc tables
- */
-function buildShapeSections(shapes, detailLevel) {
-    const sections = [];
-    sections.push(heading(2, 'API Types'));
-    if (detailLevel === 'summary') {
-        // Summary: just a table of type names and kinds
-        const rows = shapes.map((s) => [s.name, s.kind]);
-        sections.push(table(['Type', 'Kind'], rows));
-    }
-    else {
-        // Standard/Detailed: code blocks for each shape
-        for (const shape of shapes) {
-            sections.push(heading(3, `${shape.name} (${shape.kind})`));
-            if (shape.jsDoc) {
-                sections.push(code(shape.jsDoc, 'typescript'));
-            }
-            sections.push(code(shape.sourceText, 'typescript'));
-            // Property docs table for interfaces at detailed level
-            if (detailLevel === 'detailed' && shape.propertyDocs && shape.propertyDocs.length > 0) {
-                const propRows = shape.propertyDocs.map((p) => [p.name, p.jsDoc]);
-                sections.push(table(['Property', 'Description'], propRows));
-            }
-            // Param docs table for functions at standard and detailed levels
-            if (shape.params && shape.params.length > 0) {
-                const paramRows = shape.params.map((p) => [p.name, p.type ?? '', p.description]);
-                sections.push(table(['Parameter', 'Type', 'Description'], paramRows));
-            }
-            // Returns and throws docs at detailed level only
-            if (detailLevel === 'detailed') {
-                if (shape.returns) {
-                    const returnText = shape.returns.type
-                        ? `**Returns** (\`${shape.returns.type}\`): ${shape.returns.description}`
-                        : `**Returns:** ${shape.returns.description}`;
-                    sections.push(paragraph(returnText));
-                }
-                if (shape.throws && shape.throws.length > 0) {
-                    const throwsRows = shape.throws.map((t) => [t.type ?? '', t.description]);
-                    sections.push(table(['Exception', 'Description'], throwsRows));
-                }
-            }
-        }
-    }
-    sections.push(separator());
-    return sections;
-}
-// ============================================================================
-// Boundary Summary Builder
-// ============================================================================
-/**
- * Build a compact boundary summary paragraph from diagram scope data.
- *
- * Groups scope patterns by archContext and produces a text like:
- * **Components:** Scanner (PatternA, PatternB), Extractor (PatternC)
- *
- * Skips scopes with `source` override (hardcoded diagrams like fsm-lifecycle).
- * Returns undefined if no patterns found.
- */
-function buildBoundarySummary(dataset, scopes) {
-    const allPatterns = [];
-    const seenNames = new Set();
-    for (const scope of scopes) {
-        // Skip hardcoded source diagrams — they don't represent pattern boundaries
-        if (scope.source !== undefined)
-            continue;
-        for (const pattern of collectScopePatterns(dataset, scope)) {
-            const name = getPatternName(pattern);
-            if (!seenNames.has(name)) {
-                seenNames.add(name);
-                allPatterns.push(pattern);
-            }
-        }
-    }
-    if (allPatterns.length === 0)
-        return undefined;
-    // Group by archContext
-    const byContext = new Map();
-    for (const pattern of allPatterns) {
-        const ctx = pattern.archContext ?? 'Other';
-        const group = byContext.get(ctx) ?? [];
-        group.push(getPatternName(pattern));
-        byContext.set(ctx, group);
-    }
-    // Build compact text: "Context (A, B), Context (C)"
-    const parts = [];
-    for (const [context, names] of [...byContext.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
-        const label = context.charAt(0).toUpperCase() + context.slice(1);
-        parts.push(`${label} (${names.join(', ')})`);
-    }
-    return paragraph(`**Components:** ${parts.join(', ')}`);
-}
-// ============================================================================
-// Scoped Diagram Builder
-// ============================================================================
-/**
- * Collect patterns matching a DiagramScope filter.
- */
-function collectScopePatterns(dataset, scope) {
-    const nameSet = new Set(scope.patterns ?? []);
-    const contextSet = new Set(scope.archContext ?? []);
-    const viewSet = new Set(scope.include ?? []);
-    const layerSet = new Set(scope.archLayer ?? []);
-    return dataset.patterns.filter((p) => {
-        const name = getPatternName(p);
-        if (nameSet.has(name))
-            return true;
-        if (p.archContext !== undefined && contextSet.has(p.archContext))
-            return true;
-        if (p.include?.some((v) => viewSet.has(v)) === true)
-            return true;
-        if (p.archLayer !== undefined && layerSet.has(p.archLayer))
-            return true;
-        return false;
-    });
-}
-/**
- * Collect neighbor patterns — targets of relationship edges from scope patterns
- * that are not themselves in scope. Only outgoing edges (uses, dependsOn,
- * implementsPatterns, extendsPattern) are traversed; incoming edges (usedBy,
- * enables) are intentionally excluded to keep scoped diagrams focused on what
- * the scope depends on, not what depends on it.
- */
-function collectNeighborPatterns(dataset, scopeNames) {
-    const neighborNames = new Set();
-    const relationships = dataset.relationshipIndex ?? {};
-    for (const name of scopeNames) {
-        const rel = relationships[name];
-        if (!rel)
-            continue;
-        for (const target of rel.uses) {
-            if (!scopeNames.has(target))
-                neighborNames.add(target);
-        }
-        for (const target of rel.dependsOn) {
-            if (!scopeNames.has(target))
-                neighborNames.add(target);
-        }
-        for (const target of rel.implementsPatterns) {
-            if (!scopeNames.has(target))
-                neighborNames.add(target);
-        }
-        if (rel.extendsPattern !== undefined && !scopeNames.has(rel.extendsPattern)) {
-            neighborNames.add(rel.extendsPattern);
-        }
-    }
-    if (neighborNames.size === 0)
-        return [];
-    return dataset.patterns.filter((p) => neighborNames.has(getPatternName(p)));
-}
-/** Extract shared setup from scope + dataset into a reusable context */
-function prepareDiagramContext(dataset, scope) {
-    const scopePatterns = collectScopePatterns(dataset, scope);
-    if (scopePatterns.length === 0)
-        return undefined;
-    const nodeIds = new Map();
-    const scopeNames = new Set();
-    for (const pattern of scopePatterns) {
-        const name = getPatternName(pattern);
-        scopeNames.add(name);
-        nodeIds.set(name, sanitizeNodeId(name));
-    }
-    const neighborPatterns = collectNeighborPatterns(dataset, scopeNames);
-    const neighborNames = new Set();
-    for (const pattern of neighborPatterns) {
-        const name = getPatternName(pattern);
-        neighborNames.add(name);
-        nodeIds.set(name, sanitizeNodeId(name));
-    }
-    const relationships = dataset.relationshipIndex ?? {};
-    const allNames = new Set([...scopeNames, ...neighborNames]);
-    // Prune orphan scope patterns — nodes with zero edges in the diagram context.
-    // A pattern participates if it is the source or target of any edge within allNames.
-    const connected = new Set();
-    for (const name of allNames) {
-        const rel = relationships[name];
-        if (!rel)
-            continue;
-        const edgeArrays = [rel.uses, rel.dependsOn, rel.implementsPatterns];
-        for (const targets of edgeArrays) {
-            for (const target of targets) {
-                if (allNames.has(target)) {
-                    connected.add(name);
-                    connected.add(target);
-                }
-            }
-        }
-        if (rel.extendsPattern !== undefined && allNames.has(rel.extendsPattern)) {
-            connected.add(name);
-            connected.add(rel.extendsPattern);
-        }
-    }
-    // Only prune orphan scope patterns when the diagram has SOME connected
-    // patterns. If no edges exist at all, the diagram is a component listing
-    // and all scope patterns should be preserved.
-    if (connected.size > 0) {
-        const prunedScopePatterns = scopePatterns.filter((p) => connected.has(getPatternName(p)));
-        if (prunedScopePatterns.length === 0) {
-            return undefined;
-        }
-        const prunedScopeNames = new Set();
-        for (const p of prunedScopePatterns) {
-            prunedScopeNames.add(getPatternName(p));
-        }
-        // Rebuild nodeIds — remove pruned entries
-        const prunedNodeIds = new Map();
-        for (const name of [...prunedScopeNames, ...neighborNames]) {
-            const id = nodeIds.get(name);
-            if (id !== undefined)
-                prunedNodeIds.set(name, id);
-        }
-        const prunedAllNames = new Set([...prunedScopeNames, ...neighborNames]);
-        return {
-            scopePatterns: prunedScopePatterns,
-            neighborPatterns,
-            scopeNames: prunedScopeNames,
-            neighborNames,
-            nodeIds: prunedNodeIds,
-            relationships,
-            allNames: prunedAllNames,
-        };
-    }
-    return {
-        scopePatterns,
-        neighborPatterns,
-        scopeNames,
-        neighborNames,
-        nodeIds,
-        relationships,
-        allNames,
-    };
-}
-/** Emit relationship edges for flowchart diagrams (DD-4, DD-7) */
-function emitFlowchartEdges(ctx, showLabels) {
-    const lines = [];
-    const edgeTypes = ['uses', 'dependsOn', 'implementsPatterns'];
-    for (const sourceName of ctx.allNames) {
-        const sourceId = ctx.nodeIds.get(sourceName);
-        if (sourceId === undefined)
-            continue;
-        const rel = ctx.relationships[sourceName];
-        if (!rel)
-            continue;
-        for (const type of edgeTypes) {
-            for (const target of rel[type]) {
-                const targetId = ctx.nodeIds.get(target);
-                if (targetId !== undefined) {
-                    const arrow = EDGE_STYLES[type];
-                    const label = showLabels ? `|${EDGE_LABELS[type]}|` : '';
-                    lines.push(`    ${sourceId} ${arrow}${label} ${targetId}`);
-                }
-            }
-        }
-        if (rel.extendsPattern !== undefined) {
-            const targetId = ctx.nodeIds.get(rel.extendsPattern);
-            if (targetId !== undefined) {
-                const arrow = EDGE_STYLES.extendsPattern;
-                const label = showLabels ? `|${EDGE_LABELS.extendsPattern}|` : '';
-                lines.push(`    ${sourceId} ${arrow}${label} ${targetId}`);
-            }
-        }
-    }
-    return lines;
-}
-/** Build a Mermaid flowchart diagram with custom shapes and edge labels (DD-1, DD-4) */
-function buildFlowchartDiagram(ctx, scope) {
-    const direction = scope.direction ?? 'TB';
-    const showLabels = scope.showEdgeLabels !== false;
-    const lines = [`graph ${direction}`];
-    // Group scope patterns by archContext for subgraphs
-    const byContext = new Map();
-    const noContext = [];
-    for (const pattern of ctx.scopePatterns) {
-        if (pattern.archContext !== undefined) {
-            const group = byContext.get(pattern.archContext) ?? [];
-            group.push(pattern);
-            byContext.set(pattern.archContext, group);
-        }
-        else {
-            noContext.push(pattern);
-        }
-    }
-    // Emit context subgraphs
-    for (const [context, patterns] of [...byContext.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
-        const contextLabel = context.charAt(0).toUpperCase() + context.slice(1);
-        lines.push(`    subgraph ${sanitizeNodeId(context)}["${contextLabel}"]`);
-        for (const pattern of patterns) {
-            const name = getPatternName(pattern);
-            const nodeId = ctx.nodeIds.get(name) ?? sanitizeNodeId(name);
-            lines.push(`        ${formatNodeDeclaration(nodeId, name, pattern.archRole)}`);
-        }
-        lines.push('    end');
-    }
-    // Emit scope patterns without context
-    for (const pattern of noContext) {
-        const name = getPatternName(pattern);
-        const nodeId = ctx.nodeIds.get(name) ?? sanitizeNodeId(name);
-        lines.push(`    ${formatNodeDeclaration(nodeId, name, pattern.archRole)}`);
-    }
-    // Emit neighbor subgraph
-    if (ctx.neighborPatterns.length > 0) {
-        lines.push('    subgraph related["Related"]');
-        for (const pattern of ctx.neighborPatterns) {
-            const name = getPatternName(pattern);
-            const nodeId = ctx.nodeIds.get(name) ?? sanitizeNodeId(name);
-            lines.push(`        ${nodeId}["${name}"]:::neighbor`);
-        }
-        lines.push('    end');
-    }
-    // Emit edges
-    lines.push(...emitFlowchartEdges(ctx, showLabels));
-    // Add neighbor class definition
-    if (ctx.neighborPatterns.length > 0) {
-        lines.push('    classDef neighbor stroke-dasharray: 5 5');
-    }
-    return lines;
-}
-/** Build a Mermaid sequence diagram with participants and messages (DD-2) */
-function buildSequenceDiagram(ctx) {
-    const lines = ['sequenceDiagram'];
-    const edgeTypes = ['uses', 'dependsOn', 'implementsPatterns'];
-    // Emit participant declarations for scope patterns (sanitized for Mermaid syntax)
-    for (const name of ctx.scopeNames) {
-        lines.push(`    participant ${sanitizeNodeId(name)} as ${name}`);
-    }
-    // Emit participant declarations for neighbor patterns
-    for (const name of ctx.neighborNames) {
-        lines.push(`    participant ${sanitizeNodeId(name)} as ${name}`);
-    }
-    // Emit messages from relationships
-    for (const sourceName of ctx.allNames) {
-        const rel = ctx.relationships[sourceName];
-        if (!rel)
-            continue;
-        for (const type of edgeTypes) {
-            for (const target of rel[type]) {
-                if (ctx.allNames.has(target)) {
-                    const arrow = SEQUENCE_ARROWS[type];
-                    lines.push(`    ${sanitizeNodeId(sourceName)} ${arrow} ${sanitizeNodeId(target)}: ${EDGE_LABELS[type]}`);
-                }
-            }
-        }
-        if (rel.extendsPattern !== undefined && ctx.allNames.has(rel.extendsPattern)) {
-            const arrow = SEQUENCE_ARROWS.extendsPattern;
-            lines.push(`    ${sanitizeNodeId(sourceName)} ${arrow} ${sanitizeNodeId(rel.extendsPattern)}: ${EDGE_LABELS.extendsPattern}`);
-        }
-    }
-    return lines;
-}
-/** Build a Mermaid state diagram with transitions and pseudo-states (DD-3) */
-function buildStateDiagram(ctx, scope) {
-    const showLabels = scope.showEdgeLabels !== false;
-    const lines = ['stateDiagram-v2'];
-    // Track incoming/outgoing dependsOn edges for pseudo-states
-    const hasIncoming = new Set();
-    const hasOutgoing = new Set();
-    // Emit state declarations for scope patterns
-    for (const name of ctx.scopeNames) {
-        const nodeId = ctx.nodeIds.get(name) ?? sanitizeNodeId(name);
-        lines.push(`    state "${name}" as ${nodeId}`);
-    }
-    // Emit state declarations for neighbor patterns
-    for (const name of ctx.neighborNames) {
-        const nodeId = ctx.nodeIds.get(name) ?? sanitizeNodeId(name);
-        lines.push(`    state "${name}" as ${nodeId}`);
-    }
-    // Emit transitions from dependsOn relationships
-    for (const sourceName of ctx.allNames) {
-        const rel = ctx.relationships[sourceName];
-        if (!rel)
-            continue;
-        for (const target of rel.dependsOn) {
-            if (!ctx.allNames.has(target))
-                continue;
-            const sourceId = ctx.nodeIds.get(sourceName) ?? sanitizeNodeId(sourceName);
-            const targetId = ctx.nodeIds.get(target) ?? sanitizeNodeId(target);
-            const label = showLabels ? ` : ${EDGE_LABELS.dependsOn}` : '';
-            lines.push(`    ${targetId} --> ${sourceId}${label}`);
-            hasIncoming.add(sourceName);
-            hasOutgoing.add(target);
-        }
-    }
-    // Add start pseudo-states for patterns with no incoming edges
-    for (const name of ctx.scopeNames) {
-        if (!hasIncoming.has(name)) {
-            const nodeId = ctx.nodeIds.get(name) ?? sanitizeNodeId(name);
-            lines.push(`    [*] --> ${nodeId}`);
-        }
-    }
-    // Add end pseudo-states for patterns with no outgoing edges
-    for (const name of ctx.scopeNames) {
-        if (!hasOutgoing.has(name)) {
-            const nodeId = ctx.nodeIds.get(name) ?? sanitizeNodeId(name);
-            lines.push(`    ${nodeId} --> [*]`);
-        }
-    }
-    return lines;
-}
-/** Presentation labels for FSM transitions (codec concern, not FSM domain) */
-const FSM_TRANSITION_LABELS = {
-    roadmap: { active: 'Start work', deferred: 'Postpone', roadmap: 'Stay in planning' },
-    active: { completed: 'All deliverables done', roadmap: 'Blocked / regressed' },
-    deferred: { roadmap: 'Resume planning' },
-};
-/** Display names for protection levels in diagram notes */
-const PROTECTION_DISPLAY = {
-    none: 'none',
-    scope: 'scope-locked',
-    hard: 'hard-locked',
-};
-/** Build FSM lifecycle state diagram from VALID_TRANSITIONS and PROTECTION_LEVELS */
-function buildFsmLifecycleStateDiagram() {
-    const lines = ['stateDiagram-v2'];
-    const states = Object.keys(VALID_TRANSITIONS);
-    // Entry point: first state is initial
-    const initialState = states[0];
-    if (initialState !== undefined) {
-        lines.push(`    [*] --> ${initialState}`);
-    }
-    // Transitions derived from the FSM transition matrix
-    for (const [from, targets] of Object.entries(VALID_TRANSITIONS)) {
-        if (targets.length === 0) {
-            // Terminal state
-            lines.push(`    ${from} --> [*]`);
-        }
-        else {
-            for (const to of targets) {
-                const label = FSM_TRANSITION_LABELS[from]?.[to];
-                const suffix = label !== undefined ? ` : ${label}` : '';
-                lines.push(`    ${from} --> ${to}${suffix}`);
-            }
-        }
-    }
-    // Protection level notes derived from PROTECTION_LEVELS
-    for (const [state, level] of Object.entries(PROTECTION_LEVELS)) {
-        const display = PROTECTION_DISPLAY[level];
-        lines.push(`    note right of ${state}`);
-        lines.push(`        Protection: ${display}`);
-        lines.push('    end note');
-    }
-    return lines;
-}
-/** Build generation pipeline sequence diagram from hardcoded domain knowledge */
-function buildGenerationPipelineSequenceDiagram() {
-    return [
-        'sequenceDiagram',
-        '    participant CLI',
-        '    participant Orchestrator',
-        '    participant Scanner',
-        '    participant Extractor',
-        '    participant Transformer',
-        '    participant Codec',
-        '    participant Renderer',
-        '    CLI ->> Orchestrator: generate(config)',
-        '    Orchestrator ->> Scanner: scanPatterns(globs)',
-        '    Scanner -->> Orchestrator: TypeScript ASTs',
-        '    Orchestrator ->> Scanner: scanGherkinFiles(globs)',
-        '    Scanner -->> Orchestrator: Gherkin documents',
-        '    Orchestrator ->> Extractor: extractPatterns(files)',
-        '    Extractor -->> Orchestrator: ExtractedPattern[]',
-        '    Orchestrator ->> Extractor: extractFromGherkin(docs)',
-        '    Extractor -->> Orchestrator: ExtractedPattern[]',
-        '    Orchestrator ->> Orchestrator: mergePatterns(ts, gherkin)',
-        '    Orchestrator ->> Transformer: transformToMasterDataset(patterns)',
-        '    Transformer -->> Orchestrator: MasterDataset',
-        '    Orchestrator ->> Codec: codec.decode(dataset)',
-        '    Codec -->> Orchestrator: RenderableDocument',
-        '    Orchestrator ->> Renderer: render(document)',
-        '    Renderer -->> Orchestrator: markdown string',
-    ];
-}
-/** Build MasterDataset fan-out diagram from hardcoded domain knowledge */
-function buildMasterDatasetViewsDiagram() {
-    return [
-        'graph TB',
-        '    MD[MasterDataset]',
-        '    MD --> byStatus["byStatus<br/>(completed / active / planned)"]',
-        '    MD --> byPhase["byPhase<br/>(sorted, with counts)"]',
-        '    MD --> byQuarter["byQuarter<br/>(keyed by Q-YYYY)"]',
-        '    MD --> byCategory["byCategory<br/>(keyed by category name)"]',
-        '    MD --> bySource["bySource<br/>(typescript / gherkin / roadmap / prd)"]',
-        '    MD --> counts["counts<br/>(aggregate statistics)"]',
-        '    MD --> RI["relationshipIndex?<br/>(forward + reverse lookups)"]',
-        '    MD --> AI["archIndex?<br/>(role / context / layer / view)"]',
-    ];
-}
-/** Build a Mermaid C4 context diagram with system boundaries */
-function buildC4Diagram(ctx, scope) {
-    const showLabels = scope.showEdgeLabels !== false;
-    const lines = ['C4Context'];
-    if (scope.title !== undefined) {
-        lines.push(`    title ${scope.title}`);
-    }
-    // Group scope patterns by archContext for system boundaries
-    const byContext = new Map();
-    const noContext = [];
-    for (const pattern of ctx.scopePatterns) {
-        if (pattern.archContext !== undefined) {
-            const group = byContext.get(pattern.archContext) ?? [];
-            group.push(pattern);
-            byContext.set(pattern.archContext, group);
-        }
-        else {
-            noContext.push(pattern);
-        }
-    }
-    // Emit system boundaries
-    for (const [context, patterns] of [...byContext.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
-        const contextLabel = context.charAt(0).toUpperCase() + context.slice(1);
-        const contextId = sanitizeNodeId(context);
-        lines.push(`    Boundary(${contextId}, "${contextLabel}") {`);
-        for (const pattern of patterns) {
-            const name = getPatternName(pattern);
-            const nodeId = ctx.nodeIds.get(name) ?? sanitizeNodeId(name);
-            lines.push(`        System(${nodeId}, "${name}")`);
-        }
-        lines.push('    }');
-    }
-    // Emit standalone systems (no context)
-    for (const pattern of noContext) {
-        const name = getPatternName(pattern);
-        const nodeId = ctx.nodeIds.get(name) ?? sanitizeNodeId(name);
-        lines.push(`    System(${nodeId}, "${name}")`);
-    }
-    // Emit external systems for neighbor patterns
-    for (const pattern of ctx.neighborPatterns) {
-        const name = getPatternName(pattern);
-        const nodeId = ctx.nodeIds.get(name) ?? sanitizeNodeId(name);
-        lines.push(`    System_Ext(${nodeId}, "${name}")`);
-    }
-    // Emit relationships
-    const edgeTypes = ['uses', 'dependsOn', 'implementsPatterns'];
-    for (const sourceName of ctx.allNames) {
-        const sourceId = ctx.nodeIds.get(sourceName);
-        if (sourceId === undefined)
-            continue;
-        const rel = ctx.relationships[sourceName];
-        if (!rel)
-            continue;
-        for (const type of edgeTypes) {
-            for (const target of rel[type]) {
-                const targetId = ctx.nodeIds.get(target);
-                if (targetId !== undefined) {
-                    const label = showLabels ? EDGE_LABELS[type] : '';
-                    lines.push(`    Rel(${sourceId}, ${targetId}, "${label}")`);
-                }
-            }
-        }
-        if (rel.extendsPattern !== undefined) {
-            const targetId = ctx.nodeIds.get(rel.extendsPattern);
-            if (targetId !== undefined) {
-                const label = showLabels ? EDGE_LABELS.extendsPattern : '';
-                lines.push(`    Rel(${sourceId}, ${targetId}, "${label}")`);
-            }
-        }
-    }
-    return lines;
-}
-/** Build a Mermaid class diagram with pattern exports and relationships */
-function buildClassDiagram(ctx) {
-    const lines = ['classDiagram'];
-    const edgeTypes = ['uses', 'dependsOn', 'implementsPatterns'];
-    // Class arrow styles per relationship type
-    const classArrows = {
-        uses: '..>',
-        dependsOn: '..>',
-        implementsPatterns: '..|>',
-        extendsPattern: '--|>',
-    };
-    // Emit class declarations for scope patterns (with members)
-    for (const pattern of ctx.scopePatterns) {
-        const name = getPatternName(pattern);
-        const nodeId = ctx.nodeIds.get(name) ?? sanitizeNodeId(name);
-        lines.push(`    class ${nodeId} {`);
-        if (pattern.archRole !== undefined) {
-            lines.push(`        <<${pattern.archRole}>>`);
-        }
-        if (pattern.exports.length > 0) {
-            for (const exp of pattern.exports) {
-                lines.push(`        +${exp.name} ${exp.type}`);
-            }
-        }
-        lines.push('    }');
-    }
-    // Emit class declarations for neighbor patterns (no members)
-    for (const pattern of ctx.neighborPatterns) {
-        const name = getPatternName(pattern);
-        const nodeId = ctx.nodeIds.get(name) ?? sanitizeNodeId(name);
-        lines.push(`    class ${nodeId}`);
-    }
-    // Emit relationship edges
-    for (const sourceName of ctx.allNames) {
-        const sourceId = ctx.nodeIds.get(sourceName);
-        if (sourceId === undefined)
-            continue;
-        const rel = ctx.relationships[sourceName];
-        if (!rel)
-            continue;
-        for (const type of edgeTypes) {
-            for (const target of rel[type]) {
-                const targetId = ctx.nodeIds.get(target);
-                if (targetId !== undefined) {
-                    const arrow = classArrows[type] ?? '..>';
-                    lines.push(`    ${sourceId} ${arrow} ${targetId} : ${EDGE_LABELS[type]}`);
-                }
-            }
-        }
-        if (rel.extendsPattern !== undefined) {
-            const targetId = ctx.nodeIds.get(rel.extendsPattern);
-            if (targetId !== undefined) {
-                lines.push(`    ${sourceId} --|> ${targetId} : ${EDGE_LABELS.extendsPattern}`);
-            }
-        }
-    }
-    return lines;
-}
-/**
- * Build a scoped relationship diagram from DiagramScope config.
- *
- * Dispatches to type-specific builders based on scope.diagramType (DD-6).
- * Scope patterns are grouped by archContext in subgraphs (flowchart) or
- * rendered as participants/states (sequence/state diagrams).
- */
-export function buildScopedDiagram(dataset, scope) {
-    const title = scope.title ?? 'Component Overview';
-    // Content source override: render hardcoded domain diagrams
-    if (scope.source === 'fsm-lifecycle') {
-        return [
-            heading(2, title),
-            paragraph('FSM lifecycle showing valid state transitions and protection levels:'),
-            mermaid(buildFsmLifecycleStateDiagram().join('\n')),
-            separator(),
-        ];
-    }
-    if (scope.source === 'generation-pipeline') {
-        return [
-            heading(2, title),
-            paragraph('Temporal flow of the documentation generation pipeline:'),
-            mermaid(buildGenerationPipelineSequenceDiagram().join('\n')),
-            separator(),
-        ];
-    }
-    if (scope.source === 'master-dataset-views') {
-        return [
-            heading(2, title),
-            paragraph('Pre-computed view fan-out from MasterDataset (single-pass transform):'),
-            mermaid(buildMasterDatasetViewsDiagram().join('\n')),
-            separator(),
-        ];
-    }
-    const ctx = prepareDiagramContext(dataset, scope);
-    if (ctx === undefined)
-        return [];
-    let diagramLines;
-    switch (scope.diagramType ?? 'graph') {
-        case 'sequenceDiagram':
-            diagramLines = buildSequenceDiagram(ctx);
-            break;
-        case 'stateDiagram-v2':
-            diagramLines = buildStateDiagram(ctx, scope);
-            break;
-        case 'C4Context':
-            diagramLines = buildC4Diagram(ctx, scope);
-            break;
-        case 'classDiagram':
-            diagramLines = buildClassDiagram(ctx);
-            break;
-        case 'graph':
-        default:
-            diagramLines = buildFlowchartDiagram(ctx, scope);
-            break;
-    }
-    return [
-        heading(2, title),
-        paragraph('Scoped architecture diagram showing component relationships:'),
-        mermaid(diagramLines.join('\n')),
-        separator(),
-    ];
-}
-//# sourceMappingURL=reference.js.map