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

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

@@ -1,215 +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 { 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

@@ -1 +0,0 @@
-{"version":3,"file":"reference.d.ts","sourceRoot":"","sources":["../../../src/renderable/codecs/reference.ts"],"names":[],"mappings":"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"}