@libar-dev/architect 1.0.0-pre.3

package/dist/renderable/codecs/reference.d.ts

@@ -0,0 +1,215 @@
+/**
+ * @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 { type MasterDataset } from '../../validation-schemas/master-dataset.js';
+import { type SectionBlock } from '../schema.js';
+import { type BaseCodecOptions, type DetailLevel, type DocumentCodec } from './types/base.js';
+import type { ShapeSelector } from './shape-matcher.js';
+/** Content source identifiers for hardcoded domain diagrams */
+export declare const DIAGRAM_SOURCE_VALUES: readonly ["fsm-lifecycle", "generation-pipeline", "master-dataset-views"];
+/** Discriminated source type for DiagramScope.source */
+export type DiagramSource = (typeof DIAGRAM_SOURCE_VALUES)[number];
+/**
+ * Scoped diagram filter for dynamic mermaid generation from relationship metadata.
+ *
+ * Patterns matching the filter become diagram nodes. Immediate neighbors
+ * (connected via relationship edges but not in scope) appear with a distinct style.
+ */
+export interface DiagramScope {
+    /** Bounded contexts to include (matches pattern.archContext) */
+    readonly archContext?: readonly string[];
+    /** Explicit pattern names to include */
+    readonly patterns?: readonly string[];
+    /** Cross-cutting include tags (matches pattern.include entries) */
+    readonly include?: readonly string[];
+    /** Architectural layers to include (matches pattern.archLayer) */
+    readonly archLayer?: readonly string[];
+    /** Mermaid graph direction (default: 'TB') */
+    readonly direction?: 'TB' | 'LR';
+    /** Section heading for this diagram (default: 'Component Overview') */
+    readonly title?: string;
+    /** Mermaid diagram type (default: 'graph' for flowchart) */
+    readonly diagramType?: 'graph' | 'sequenceDiagram' | 'stateDiagram-v2' | 'C4Context' | 'classDiagram';
+    /** Show relationship type labels on edges (default: true) */
+    readonly showEdgeLabels?: boolean;
+    /** Content source override. When set, uses hardcoded domain content
+     * instead of computing from pattern relationships.
+     * - 'fsm-lifecycle': FSM state transitions with protection levels
+     * - 'generation-pipeline': 4-stage generation pipeline temporal flow
+     * - 'master-dataset-views': MasterDataset pre-computed view fan-out
+     */
+    readonly source?: DiagramSource;
+}
+/**
+ * Configuration for a reference document type.
+ *
+ * Each config object defines one reference document's composition.
+ * Convention tags, shape selectors, and behavior tags control content assembly.
+ */
+export interface ReferenceDocConfig {
+    /** Document title (e.g., "Process Guard Reference") */
+    readonly title: string;
+    /** Convention tag values to extract from decision records */
+    readonly conventionTags: readonly string[];
+    /** Categories to filter behavior patterns from MasterDataset */
+    readonly behaviorCategories: readonly string[];
+    /** Multiple scoped diagrams. */
+    readonly diagramScopes?: readonly DiagramScope[];
+    /** Target _claude-md/ directory for summary output */
+    readonly claudeMdSection: string;
+    /** Output filename for detailed docs (in docs/) */
+    readonly docsFilename: string;
+    /** Output filename for summary _claude-md module */
+    readonly claudeMdFilename: string;
+    /** DD-3/DD-6: Fine-grained shape selectors for declaration-level filtering */
+    readonly shapeSelectors?: readonly ShapeSelector[];
+    /** DD-1 (CrossCuttingDocumentInclusion): Include-tag values for cross-cutting content routing */
+    readonly includeTags?: readonly string[];
+    /**
+     * Product area filter (ADR-001 canonical values).
+     * When set, pre-filters all content sources to patterns with matching productArea.
+     * Auto-generates diagram scopes from productArea→archContext mapping if no
+     * explicit diagramScopes are provided.
+     */
+    readonly productArea?: string;
+    /**
+     * Exclude patterns whose source.file starts with any of these prefixes.
+     * Used to filter ephemeral planning specs from behavior sections.
+     * @example ['architect/specs/']
+     */
+    readonly excludeSourcePaths?: readonly string[];
+    /**
+     * Static preamble sections prepended before all generated content.
+     * Use for editorial intro prose that cannot be expressed as annotations.
+     * Appears in both detailed and summary outputs.
+     */
+    readonly preamble?: readonly SectionBlock[];
+    /** When true, shapes section renders before conventions (default: false) */
+    readonly shapesFirst?: boolean;
+}
+/**
+ * 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 declare const PRODUCT_AREA_ARCH_CONTEXT_MAP: Readonly<Record<string, readonly string[]>>;
+/**
+ * Product area metadata for intro sections and index generation.
+ *
+ * Each area has a reader-facing question (from ADR-001), a coverage summary,
+ * an intro paragraph synthesized from executable specs, key invariants
+ * curated from business rules, and the most important patterns in the area.
+ */
+export interface ProductAreaMeta {
+    /** Reader-facing question (from ADR-001 canonical values) */
+    readonly question: string;
+    /** Comma-separated coverage summary */
+    readonly covers: string;
+    /** 2-4 sentence intro explaining what this area does and why it matters */
+    readonly intro: string;
+    /** Additional structured content rendered after intro at 'detailed' level only */
+    readonly introSections?: readonly SectionBlock[];
+    /** Live diagram scopes generated from annotation data (overrides auto-generated diagram) */
+    readonly diagramScopes?: readonly DiagramScope[];
+    /** Key invariants to surface prominently (curated from executable specs) */
+    readonly keyInvariants: readonly string[];
+    /** Key patterns in this area */
+    readonly keyPatterns: readonly string[];
+}
+/**
+ * ADR-001 canonical product area metadata for intro sections.
+ */
+export declare const PRODUCT_AREA_META: Readonly<Record<string, ProductAreaMeta>>;
+export interface ReferenceCodecOptions extends BaseCodecOptions {
+    /** Override detail level (default: 'standard') */
+    readonly detailLevel?: DetailLevel;
+}
+/**
+ * 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 declare function createReferenceCodec(config: ReferenceDocConfig, options?: ReferenceCodecOptions): DocumentCodec;
+/**
+ * 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 declare function buildScopedDiagram(dataset: MasterDataset, scope: DiagramScope): SectionBlock[];
+//# sourceMappingURL=reference.d.ts.map

package/dist/renderable/codecs/reference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference.d.ts","sourceRoot":"","sources":["../../../src/renderable/codecs/reference.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AAGH,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,4CAA4C,CAAC;AACpD,OAAO,EAEL,KAAK,YAAY,EAYlB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,aAAa,EAGnB,MAAM,iBAAiB,CAAC;AASzB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAoBxD,+DAA+D;AAC/D,eAAO,MAAM,qBAAqB,2EAIxB,CAAC;AAEX,wDAAwD;AACxD,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAMnE;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,gEAAgE;IAChE,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEzC,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEtC,mEAAmE;IACnE,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAErC,kEAAkE;IAClE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEvC,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAEjC,uEAAuE;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,CAAC,EACjB,OAAO,GACP,iBAAiB,GACjB,iBAAiB,GACjB,WAAW,GACX,cAAc,CAAC;IAEnB,6DAA6D;IAC7D,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAElC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,6DAA6D;IAC7D,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAE3C,gEAAgE;IAChE,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAE/C,gCAAgC;IAChC,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAEjD,sDAAsD;IACtD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAEjC,mDAAmD;IACnD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B,oDAAoD;IACpD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAElC,8EAA8E;IAC9E,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAEnD,iGAAiG;IACjG,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEzC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEhD;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAE5C,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAMD;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAQrF,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uCAAuC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kFAAkF;IAClF,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IACjD,4FAA4F;IAC5F,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IACjD,4EAA4E;IAC5E,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,gCAAgC;IAChC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAkSvE,CAAC;AAMF,MAAM,WAAW,qBAAsB,SAAQ,gBAAgB;IAC7D,kDAAkD;IAClD,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;CACpC;AAWD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,kBAAkB,EAC1B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,aAAa,CAoJf;AAqqCD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,YAAY,GAAG,YAAY,EAAE,CA0D9F"}