@libar-dev/architect 1.0.0-pre.3

package/dist/renderable/utils.js

@@ -0,0 +1,362 @@
+/**
+ * @architect
+ * @architect-core
+ * @architect-pattern RenderableUtils
+ * @architect-status completed
+ *
+ * ## Renderable Utilities
+ *
+ * Utility functions for document codecs. These are pure functions that
+ * transform pattern data into display-ready strings.
+ *
+ * ### When to Use
+ *
+ * - When formatting status values, names, or progress indicators
+ * - When computing status counts or completion percentages
+ * - When sorting patterns for display in documents
+ *
+ * Ported from the original helpers.ts with the essential functions
+ * needed by document codecs.
+ */
+import { camelCaseToTitleCase, groupBy } from '../utils/index.js';
+import { normalizeStatus as taxonomyNormalizeStatus, } from '../taxonomy/index.js';
+// ═══════════════════════════════════════════════════════════════════════════
+// Status Utilities
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Default status emoji mapping (fallback when no workflow)
+ * Per PDR-005: roadmap, active, completed, deferred
+ */
+const STATUS_EMOJI = {
+    completed: '\u2705', // ✅
+    active: '\ud83d\udea7', // 🚧
+    roadmap: '\ud83d\udccb', // 📋
+    planned: '\ud83d\udccb', // 📋 (normalized)
+    deferred: '\u23f8\ufe0f', // ⏸️
+};
+/**
+ * Get status emoji
+ *
+ * @param status - Status string
+ * @param workflow - Optional workflow for custom emojis
+ * @returns Emoji string
+ */
+export function getStatusEmoji(status, workflow) {
+    if (!status)
+        return '';
+    if (workflow) {
+        const statusDef = workflow.statusMap.get(status.toLowerCase());
+        return statusDef?.emoji ?? '';
+    }
+    return STATUS_EMOJI[status.toLowerCase()] ?? '';
+}
+/**
+ * Get status display text (capitalized)
+ */
+export function getStatusText(status) {
+    if (!status)
+        return 'Planned';
+    return status.charAt(0).toUpperCase() + status.slice(1);
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Display Name & Text Processing
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Get human-readable display name for a pattern
+ *
+ * Priority: title > patternName (CamelCase converted) > name
+ */
+export function getDisplayName(pattern) {
+    if (pattern.title)
+        return pattern.title;
+    if (pattern.patternName)
+        return camelCaseToTitleCase(pattern.patternName);
+    return pattern.name;
+}
+/**
+ * Common acronyms that should be rendered in uppercase
+ */
+const ACRONYMS = new Set(['ddd', 'cqrs', 'api', 'cms', 'es', 'occ', 'dcb', 'bc']);
+/**
+ * Format category name (capitalize words, handle acronyms)
+ *
+ * Handles common acronyms like DDD, CQRS, API by rendering them in uppercase.
+ * Hyphenated names like "event-sourcing" become "Event Sourcing".
+ */
+export function formatCategoryName(category) {
+    return category
+        .split('-')
+        .map((word) => {
+        const lower = word.toLowerCase();
+        if (ACRONYMS.has(lower)) {
+            return word.toUpperCase();
+        }
+        return word.charAt(0).toUpperCase() + word.slice(1);
+    })
+        .join(' ');
+}
+/**
+ * Format business value (replace hyphens with spaces)
+ */
+export function formatBusinessValue(value) {
+    if (!value)
+        return '';
+    return value.replace(/-/g, ' ');
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Description Extraction
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Strip leading markdown headers from text to avoid duplicate headings.
+ *
+ * When directive descriptions start with a markdown header (e.g., "## Topic"),
+ * rendering under a "## Description" heading creates duplicate/nested headers.
+ * This function removes leading headers and empty lines to get the actual content.
+ *
+ * @param text - Text that may start with markdown headers
+ * @returns Text with leading headers and empty lines stripped
+ *
+ * @example
+ * ```typescript
+ * stripLeadingHeaders("## Topic\n\nActual content here")
+ * // Returns: "Actual content here"
+ *
+ * stripLeadingHeaders("Content without header")
+ * // Returns: "Content without header"
+ * ```
+ */
+export function stripLeadingHeaders(text) {
+    if (!text)
+        return text;
+    const lines = text.split('\n');
+    let startIndex = 0;
+    // Skip leading empty lines and markdown header lines (# to ######)
+    while (startIndex < lines.length) {
+        const line = lines[startIndex]?.trim() ?? '';
+        if (!line) {
+            // Skip empty lines
+            startIndex++;
+            continue;
+        }
+        // Check if line is a markdown header (starts with 1-6 # followed by space)
+        if (/^#{1,6}\s/.test(line)) {
+            startIndex++;
+            continue;
+        }
+        // Found non-empty, non-header line - stop here
+        break;
+    }
+    return lines.slice(startIndex).join('\n').trim();
+}
+/** Maximum length for summary text */
+const SUMMARY_MAX_LENGTH = 120;
+/** Truncation suffix */
+const TRUNCATION_SUFFIX = '...';
+/**
+ * Strip markdown formatting from text
+ */
+export function stripMarkdown(text) {
+    return text
+        .replace(/^#+\s*/, '') // Remove heading markers
+        .replace(/\*\*([^*]+)\*\*/g, '$1') // Bold
+        .replace(/\*([^*]+)\*/g, '$1') // Italic
+        .replace(/`([^`]+)`/g, '`$1`') // Keep inline code
+        .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1'); // Links
+}
+/**
+ * Extract summary for pattern (first complete sentence, truncated if needed)
+ *
+ * Combines multiple lines to find a complete sentence, respecting max length.
+ * If no sentence ending is found within the limit, truncates at word boundary with "..."
+ */
+export function extractSummary(description, patternName) {
+    if (!description)
+        return '';
+    const lines = description.split('\n');
+    const nonEmptyLines = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed && !trimmed.startsWith('#')) {
+            nonEmptyLines.push(trimmed);
+        }
+    }
+    if (nonEmptyLines.length === 0)
+        return '';
+    // Find starting index, skipping tautological first lines and section headers
+    let startIndex = 0;
+    const firstCleaned = stripMarkdown(nonEmptyLines[0] ?? '');
+    // Skip tautological first line (just the pattern name)
+    if (firstCleaned.toLowerCase().trim() === patternName?.toLowerCase().trim()) {
+        startIndex = 1;
+    }
+    // Skip section header labels like "Problem:", "Solution:", "Context:"
+    const startText = stripMarkdown(nonEmptyLines[startIndex] ?? '');
+    if (/^[A-Za-z]+:$/.test(startText) && startIndex < nonEmptyLines.length - 1) {
+        startIndex++;
+    }
+    // Combine lines until we find a sentence ending or exceed max length
+    let summary = '';
+    const sentenceEndPattern = /[.!?](?=\s+[A-Z]|\s*$)/;
+    for (let i = startIndex; i < nonEmptyLines.length && summary.length < SUMMARY_MAX_LENGTH; i++) {
+        const lineText = stripMarkdown(nonEmptyLines[i] ?? '');
+        if (!lineText)
+            continue;
+        // Add space between combined lines
+        if (summary.length > 0) {
+            summary += ' ';
+        }
+        summary += lineText;
+        // Check if we've found a complete sentence
+        const sentenceMatch = sentenceEndPattern.exec(summary);
+        if (sentenceMatch) {
+            summary = summary.slice(0, sentenceMatch.index + 1);
+            break;
+        }
+    }
+    // Truncate if too long, preferring sentence boundaries
+    if (summary.length > SUMMARY_MAX_LENGTH) {
+        const withinLimit = summary.slice(0, SUMMARY_MAX_LENGTH);
+        // Try to find the last complete sentence within the limit
+        const lastSentenceMatch = /.*[.!?](?=\s|$)/.exec(withinLimit);
+        if (lastSentenceMatch && lastSentenceMatch[0].length > 20) {
+            // Found a sentence boundary with reasonable length
+            summary = lastSentenceMatch[0];
+        }
+        else {
+            // No sentence boundary found - truncate at word boundary
+            const truncateAt = SUMMARY_MAX_LENGTH - TRUNCATION_SUFFIX.length;
+            const lastSpace = withinLimit.lastIndexOf(' ', truncateAt);
+            summary = withinLimit.slice(0, lastSpace > 0 ? lastSpace : truncateAt) + TRUNCATION_SUFFIX;
+        }
+    }
+    else if (summary.length > 0 && !/[.!?]$/.test(summary)) {
+        // Text is under limit but doesn't end with sentence punctuation - add ellipsis
+        summary = summary + TRUNCATION_SUFFIX;
+    }
+    return summary.trim();
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Progress & Counts
+// ═══════════════════════════════════════════════════════════════════════════
+// StatusCounts type imported from validation-schemas (canonical source)
+/**
+ * Compute status counts from patterns
+ */
+export function computeStatusCounts(patterns) {
+    const counts = { completed: 0, active: 0, planned: 0, total: patterns.length };
+    for (const p of patterns) {
+        const status = taxonomyNormalizeStatus(p.status);
+        counts[status]++;
+    }
+    return counts;
+}
+/**
+ * Calculate completion percentage
+ */
+export function completionPercentage(counts) {
+    if (counts.total === 0)
+        return 0;
+    return Math.round((counts.completed / counts.total) * 100);
+}
+/**
+ * Check if all items are completed
+ */
+export function isFullyCompleted(counts) {
+    return counts.total > 0 && counts.completed === counts.total;
+}
+/**
+ * Render ASCII progress bar
+ *
+ * @param completed - Number completed
+ * @param total - Total number
+ * @param width - Bar width in characters
+ * @returns Progress bar string like "[████░░░░] 4/8"
+ */
+export function renderProgressBar(completed, total, width = 10) {
+    if (total === 0)
+        return `[${'░'.repeat(width)}] 0/0`;
+    const percent = completed / total;
+    const filled = Math.round(percent * width);
+    const empty = width - filled;
+    return `[${'█'.repeat(filled)}${'░'.repeat(empty)}] ${completed}/${total}`;
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Pattern Grouping
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Group patterns by category
+ */
+export function groupByCategory(patterns) {
+    return groupBy(patterns, (p) => p.category);
+}
+/**
+ * Group patterns by phase number
+ */
+export function groupByPhase(patterns) {
+    const withPhase = patterns.filter((p) => p.phase !== undefined);
+    return groupBy(withPhase, (p) => p.phase);
+}
+/**
+ * Group patterns by quarter
+ */
+export function groupByQuarter(patterns) {
+    const withQuarter = patterns.filter((p) => p.quarter !== undefined);
+    return groupBy(withQuarter, (p) => p.quarter);
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Sorting
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Sort patterns by phase number then name
+ *
+ * @param patterns - Array of patterns to sort
+ * @param inPlace - If true, sorts the array in place (mutates input).
+ *                  If false (default), creates a copy before sorting.
+ *                  Use inPlace=true when you've already created a copy.
+ * @returns Sorted array (same reference if inPlace=true, new array otherwise)
+ *
+ * @example
+ * ```typescript
+ * // Safe default - doesn't modify input
+ * const sorted = sortByPhaseAndName(patterns);
+ *
+ * // Performance optimization - when array is already a copy
+ * const copy = [...patterns];
+ * sortByPhaseAndName(copy, true); // Mutates copy
+ * ```
+ */
+export function sortByPhaseAndName(patterns, inPlace = false) {
+    const arr = inPlace ? patterns : [...patterns];
+    return arr.sort((a, b) => {
+        const phaseA = a.phase ?? Infinity;
+        const phaseB = b.phase ?? Infinity;
+        if (phaseA !== phaseB)
+            return phaseA - phaseB;
+        return a.name.localeCompare(b.name);
+    });
+}
+/**
+ * Sort patterns by status (completed first) then name
+ *
+ * @param patterns - Array of patterns to sort
+ * @param inPlace - If true, sorts the array in place (mutates input).
+ *                  If false (default), creates a copy before sorting.
+ *                  Use inPlace=true when you've already created a copy.
+ * @returns Sorted array (same reference if inPlace=true, new array otherwise)
+ */
+export function sortByStatusAndName(patterns, inPlace = false) {
+    const statusOrder = {
+        completed: 0,
+        active: 1,
+        planned: 2,
+    };
+    const arr = inPlace ? patterns : [...patterns];
+    return arr.sort((a, b) => {
+        const statusA = statusOrder[taxonomyNormalizeStatus(a.status)];
+        const statusB = statusOrder[taxonomyNormalizeStatus(b.status)];
+        if (statusA !== statusB)
+            return statusA - statusB;
+        return a.name.localeCompare(b.name);
+    });
+}
+//# sourceMappingURL=utils.js.map

package/dist/renderable/utils.js.map

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

package/dist/scanner/ast-parser.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @architect
+ * @architect-core @architect-scanner
+ * @architect-pattern TypeScript AST Parser
+ * @architect-status completed
+ * @architect-arch-role infrastructure
+ * @architect-arch-context scanner
+ * @architect-arch-layer infrastructure
+ * @architect-uses TagRegistry, DocDirectiveSchema, typescript-estree
+ * @architect-used-by Pattern Scanner, Doc Extractor
+ * @architect-usecase "When parsing JSDoc comments for @architect-* directives"
+ * @architect-usecase "When extracting code blocks following documentation comments"
+ *
+ * ## TypeScript AST Parser - JSDoc Directive Extraction
+ *
+ * Parses TypeScript source files using @typescript-eslint/typescript-estree
+ * to extract @architect-* directives with their associated code blocks.
+ * First stage of the three-stage pipeline: Scanner → Extractor → Generator.
+ *
+ * ### When to Use
+ *
+ * - Scanning TypeScript files for documentation directives
+ * - Extracting code snippets following JSDoc comments
+ * - Building pattern metadata from JSDoc tags
+ *
+ * ### Key Concepts
+ *
+ * - **Data-Driven Extraction**: Tag formats defined in registry, not hardcoded
+ * - **Schema-First Validation**: All directives validated against Zod schemas
+ * - **Result Monad**: Returns Result<T, E> for explicit error handling
+ */
+import { Result } from '../types/index.js';
+import type { DocDirective, ExportInfo, DirectiveValidationError, FileParseError } from '../types/index.js';
+import { type TagRegistry } from '../validation-schemas/index.js';
+/**
+ * Result of parsing a file for directives
+ */
+export interface ParseDirectivesResult {
+    readonly directives: ReadonlyArray<{
+        directive: DocDirective;
+        code: string;
+        exports: readonly ExportInfo[];
+    }>;
+    /** Directive-level validation errors (individual directives that failed) */
+    readonly skippedDirectives: readonly DirectiveValidationError[];
+}
+/**
+ * Parses TypeScript content and extracts all @architect-* directives
+ * with their associated code blocks and exports.
+ *
+ * **Error Handling**: Returns Result type to surface parse errors:
+ * - Ok: Contains successfully parsed directives and any skipped directive errors
+ * - Err: Contains FileParseError when the entire file fails to parse
+ *
+ * @param content - TypeScript file content
+ * @param filePath - Path to TypeScript file (for error messages)
+ * @param registry - Tag registry for metadata extraction (optional, defaults to generic registry)
+ * @returns Result with parsed directives or parse error
+ *
+ * @example
+ * ```typescript
+ * const content = await fs.readFile(filePath, "utf-8");
+ * const result = parseFileDirectives(content, filePath, registry);
+ *
+ * if (Result.isOk(result)) {
+ *   const { directives, skippedDirectives } = result.value;
+ *   console.log(`Parsed ${directives.length} directives`);
+ *   console.log(`Skipped ${skippedDirectives.length} invalid directives`);
+ * } else {
+ *   console.error(`Parse error: ${result.error.message}`);
+ * }
+ * ```
+ */
+export declare function parseFileDirectives(content: string, filePath: string, registry?: TagRegistry): Result<ParseDirectivesResult, FileParseError>;
+//# sourceMappingURL=ast-parser.d.ts.map

package/dist/scanner/ast-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast-parser.d.ts","sourceRoot":"","sources":["../../src/scanner/ast-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAG3C,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EACV,wBAAwB,EACxB,cAAc,EACf,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EAGL,KAAK,WAAW,EAEjB,MAAM,gCAAgC,CAAC;AAsCxC;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;QACjC,SAAS,EAAE,YAAY,CAAC;QACxB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;KAChC,CAAC,CAAC;IACH,4EAA4E;IAC5E,QAAQ,CAAC,iBAAiB,EAAE,SAAS,wBAAwB,EAAE,CAAC;CACjE;AAyPD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,WAAW,GACrB,MAAM,CAAC,qBAAqB,EAAE,cAAc,CAAC,CAqE/C"}