@libar-dev/architect 1.0.0-pre.3

package/dist/scanner/gherkin-scanner.js

@@ -0,0 +1,149 @@
+/**
+ * @architect
+ * @architect-scanner
+ * @architect-pattern GherkinScanner
+ * @architect-status completed
+ * @architect-implements GherkinRulesSupport
+ * @architect-uses GherkinASTParser, GherkinTypes
+ * @architect-used-by DualSourceExtractor, Orchestrator
+ * @architect-arch-role infrastructure
+ * @architect-arch-context scanner
+ * @architect-arch-layer infrastructure
+ *
+ * ## GherkinScanner - Multi-Source Pattern Extraction from Feature Files
+ *
+ * Scans .feature files for pattern metadata encoded in Gherkin tags.
+ * Enables roadmap patterns to be defined in acceptance criteria files
+ * before implementation, supporting specification-first development.
+ *
+ * ### When to Use
+ *
+ * - When defining roadmap patterns in .feature files
+ * - When extracting pattern metadata from acceptance criteria
+ * - When building multi-source documentation (TypeScript + Gherkin)
+ *
+ * ### Key Concepts
+ *
+ * - **Feature Tags**: @pattern:Name, @phase:N, @status:roadmap map to pattern metadata
+ * - **Multi-Source**: Patterns can be defined in TypeScript stubs OR Gherkin features
+ * - **Conflict Detection**: Same pattern name in both sources triggers error
+ */
+import * as fs from 'fs/promises';
+import { glob } from 'glob';
+import { Result as R } from '../types/index.js';
+import { parseFeatureFile } from './gherkin-ast-parser.js';
+/**
+ * Find all .feature files matching the scanner configuration
+ *
+ * @param config - Scanner configuration
+ * @returns Array of absolute file paths to .feature files
+ *
+ * @example
+ * ```typescript
+ * const files = await findFeatureFiles({
+ *   patterns: 'tests/features/**\/*.feature',
+ *   baseDir: '/path/to/project'
+ * });
+ * console.log(files); // ['/path/to/project/tests/features/my-pattern.feature', ...]
+ * ```
+ */
+export async function findFeatureFiles(config) {
+    const defaultExclude = ['node_modules/**', 'dist/**'];
+    const excludePatterns = config.exclude ? [...defaultExclude, ...config.exclude] : defaultExclude;
+    const patterns = Array.isArray(config.patterns) ? config.patterns : [config.patterns];
+    const files = await glob(patterns, {
+        cwd: config.baseDir ?? process.cwd(),
+        ignore: excludePatterns,
+        absolute: true,
+    });
+    // Filter to only .feature and .feature.md files (MDG format)
+    return files.filter((file) => file.endsWith('.feature') || file.endsWith('.feature.md'));
+}
+/**
+ * Scan Gherkin feature files and extract pattern metadata
+ *
+ * Parses .feature files and extracts:
+ * - Feature name, description, tags
+ * - Scenario names, tags, steps
+ * - Pattern metadata from tags (@pattern:Name, @phase:N, etc.)
+ *
+ * **Result Pattern**: Returns Result<GherkinScanResults, never> where:
+ * - Success contains both successful files AND individual file errors
+ * - Never fails completely (errors are collected in results)
+ *
+ * @param config - Scanner configuration
+ * @returns Result containing scan results with success and error collections
+ *
+ * @example
+ * ```typescript
+ * const result = await scanGherkinFiles({
+ *   patterns: 'tests/features/roadmap/**\/*.feature',
+ *   baseDir: '/path/to/project'
+ * });
+ *
+ * if (result.ok) {
+ *   const { files, errors } = result.value;
+ *   console.log(`Scanned ${files.length} features successfully`);
+ *   console.log(`Failed to parse ${errors.length} features`);
+ *
+ *   for (const file of files) {
+ *     console.log(`Feature: ${file.feature.name}`);
+ *     console.log(`  Tags: ${file.feature.tags.join(', ')}`);
+ *     console.log(`  Scenarios: ${file.scenarios.length}`);
+ *   }
+ *
+ *   // Handle errors
+ *   for (const { file, error } of errors) {
+ *     console.error(`Failed to parse ${file}: ${error.message}`);
+ *     if (error.line) {
+ *       console.error(`  at line ${error.line}${error.column ? `, column ${error.column}` : ''}`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export async function scanGherkinFiles(config) {
+    // Find all feature files to scan
+    const files = await findFeatureFiles(config);
+    const scanned = [];
+    const errors = [];
+    for (const filePath of files) {
+        try {
+            // Read feature file content
+            const content = await fs.readFile(filePath, 'utf-8');
+            // Parse the feature file
+            const parseResult = parseFeatureFile(content, filePath);
+            if (R.isErr(parseResult)) {
+                // Failed to parse - collect error
+                errors.push(parseResult.error);
+                continue;
+            }
+            const { feature, background, rules, scenarios } = parseResult.value;
+            // Store scanned file
+            scanned.push({
+                filePath,
+                feature,
+                ...(background && { background }),
+                ...(rules && rules.length > 0 && { rules }),
+                scenarios,
+            });
+        }
+        catch (error) {
+            // Collect filesystem/IO errors
+            errors.push({
+                file: filePath,
+                error: {
+                    message: error instanceof Error ? error.message : String(error),
+                },
+            });
+            continue;
+        }
+    }
+    // Always succeeds - errors are collected in results
+    return R.ok({
+        files: scanned,
+        errors,
+    });
+}
+export { parseFeatureFile, extractPatternTags } from './gherkin-ast-parser.js';
+//# sourceMappingURL=gherkin-scanner.js.map

package/dist/scanner/gherkin-scanner.js.map

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

package/dist/scanner/index.d.ts

@@ -0,0 +1,85 @@
+import type { Result, ScannerConfig, DocDirective, ExportInfo, FileParseError, DirectiveValidationError } from '../types/index.js';
+import type { TagRegistry } from '../validation-schemas/tag-registry.js';
+/**
+ * Result of scanning a single file
+ */
+export interface ScannedFile {
+    readonly filePath: string;
+    readonly directives: ReadonlyArray<{
+        readonly directive: DocDirective;
+        readonly code: string;
+        readonly exports: readonly ExportInfo[];
+    }>;
+}
+/**
+ * Information about a file that failed to scan
+ */
+export interface FileError {
+    readonly file: string;
+    readonly error: FileParseError;
+}
+/**
+ * Information about a directive that was skipped due to validation errors
+ */
+export interface SkippedDirective {
+    readonly file: string;
+    readonly error: DirectiveValidationError;
+}
+/**
+ * Results of scanning multiple files
+ *
+ * Contains successfully scanned files, file-level errors, and directive-level errors.
+ * This provides full visibility into what was processed and what failed.
+ */
+export interface ScanResults {
+    /** Successfully scanned files with directives */
+    readonly files: readonly ScannedFile[];
+    /** Files that failed to parse entirely (syntax errors) */
+    readonly errors: readonly FileError[];
+    /** Individual directives that failed validation but file parsed successfully */
+    readonly skippedDirectives: readonly SkippedDirective[];
+}
+/**
+ * Scans source files for @architect-* directives and extracts them
+ * with their associated code blocks and export information.
+ *
+ * **Result Pattern**: Returns Result<ScanResults, never> where:
+ * - Success contains both successful files AND individual file errors
+ * - Never fails completely (errors are collected in results)
+ *
+ * @param config - Scanner configuration
+ * @param registry - Optional tag registry for metadata extraction (uses default if not provided)
+ * @returns Result containing scan results with success and error collections
+ *
+ * @example
+ * ```typescript
+ * const config = await loadConfig();
+ * const result = await scanPatterns({
+ *   patterns: ['src/**\/*.ts'],
+ *   baseDir: '/path/to/project'
+ * }, config.tagRegistry);
+ *
+ * if (result.ok) {
+ *   const { files, errors } = result.value;
+ *   console.log(`Scanned ${files.length} files successfully`);
+ *   console.log(`Failed to scan ${errors.length} files`);
+ *
+ *   for (const file of files) {
+ *     console.log(`File: ${file.filePath}`);
+ *     for (const { directive, code, exports } of file.directives) {
+ *       console.log(`  Tags: ${directive.tags.join(', ')}`);
+ *       console.log(`  Exports: ${exports.map(e => e.name).join(', ')}`);
+ *     }
+ *   }
+ *
+ *   // Handle errors
+ *   for (const { file, error } of errors) {
+ *     console.error(`Failed to scan ${file}: ${error.message}`);
+ *   }
+ * }
+ * ```
+ */
+export declare function scanPatterns(config: ScannerConfig, registry?: TagRegistry): Promise<Result<ScanResults, never>>;
+export { findFilesToScan, hasDocDirectives, hasFileOptIn } from './pattern-scanner.js';
+export { parseFileDirectives, type ParseDirectivesResult } from './ast-parser.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/scanner/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scanner/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,MAAM,EACN,aAAa,EACb,YAAY,EACZ,UAAU,EACV,cAAc,EACd,wBAAwB,EACzB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uCAAuC,CAAC;AAIzE;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;QACjC,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;QACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;KACzC,CAAC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,wBAAwB,CAAC;CAC1C;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,gFAAgF;IAChF,QAAQ,CAAC,iBAAiB,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,aAAa,EACrB,QAAQ,CAAC,EAAE,WAAW,GACrB,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CAkErC;AAED,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACvF,OAAO,EAAE,mBAAmB,EAAE,KAAK,qBAAqB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/scanner/index.js

@@ -0,0 +1,102 @@
+import * as fs from 'fs/promises';
+import { Result as R, createFileParseError } from '../types/index.js';
+import { parseFileDirectives } from './ast-parser.js';
+import { findFilesToScan, hasDocDirectives, hasFileOptIn } from './pattern-scanner.js';
+/**
+ * Scans source files for @architect-* directives and extracts them
+ * with their associated code blocks and export information.
+ *
+ * **Result Pattern**: Returns Result<ScanResults, never> where:
+ * - Success contains both successful files AND individual file errors
+ * - Never fails completely (errors are collected in results)
+ *
+ * @param config - Scanner configuration
+ * @param registry - Optional tag registry for metadata extraction (uses default if not provided)
+ * @returns Result containing scan results with success and error collections
+ *
+ * @example
+ * ```typescript
+ * const config = await loadConfig();
+ * const result = await scanPatterns({
+ *   patterns: ['src/**\/*.ts'],
+ *   baseDir: '/path/to/project'
+ * }, config.tagRegistry);
+ *
+ * if (result.ok) {
+ *   const { files, errors } = result.value;
+ *   console.log(`Scanned ${files.length} files successfully`);
+ *   console.log(`Failed to scan ${errors.length} files`);
+ *
+ *   for (const file of files) {
+ *     console.log(`File: ${file.filePath}`);
+ *     for (const { directive, code, exports } of file.directives) {
+ *       console.log(`  Tags: ${directive.tags.join(', ')}`);
+ *       console.log(`  Exports: ${exports.map(e => e.name).join(', ')}`);
+ *     }
+ *   }
+ *
+ *   // Handle errors
+ *   for (const { file, error } of errors) {
+ *     console.error(`Failed to scan ${file}: ${error.message}`);
+ *   }
+ * }
+ * ```
+ */
+export async function scanPatterns(config, registry) {
+    // Find all files to scan
+    const files = await findFilesToScan(config);
+    const scanned = [];
+    const errors = [];
+    const skippedDirectives = [];
+    for (const filePath of files) {
+        try {
+            // Read file content once - passed to all functions (no double read!)
+            const content = await fs.readFile(filePath, 'utf-8');
+            // Check for file-level opt-in (requires opt-in tag from registry)
+            if (!hasFileOptIn(content, registry))
+                continue;
+            // Quick check if file has any section directives
+            if (!hasDocDirectives(content, registry))
+                continue;
+            // Parse the file for directives (pass content to avoid re-reading)
+            // Pass registry for metadata tag extraction (uses, usedBy, usecase, etc.)
+            const parseResult = parseFileDirectives(content, filePath, registry);
+            if (R.isErr(parseResult)) {
+                // File-level parse error (syntax error, etc.)
+                errors.push({
+                    file: filePath,
+                    error: parseResult.error,
+                });
+                continue;
+            }
+            const { directives, skippedDirectives: fileSkipped } = parseResult.value;
+            // Collect directive-level validation errors
+            for (const skipped of fileSkipped) {
+                skippedDirectives.push({ file: filePath, error: skipped });
+            }
+            if (directives.length === 0)
+                continue;
+            scanned.push({
+                filePath,
+                directives,
+            });
+        }
+        catch (error) {
+            // Collect filesystem/IO errors
+            errors.push({
+                file: filePath,
+                error: createFileParseError(filePath, error instanceof Error ? error.message : String(error), undefined, error),
+            });
+            continue;
+        }
+    }
+    // Always succeeds - errors are collected in results
+    return R.ok({
+        files: scanned,
+        errors,
+        skippedDirectives,
+    });
+}
+export { findFilesToScan, hasDocDirectives, hasFileOptIn } from './pattern-scanner.js';
+export { parseFileDirectives } from './ast-parser.js';
+//# sourceMappingURL=index.js.map

package/dist/scanner/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/scanner/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,aAAa,CAAC;AASlC,OAAO,EAAE,MAAM,IAAI,CAAC,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AA6CvF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAAqB,EACrB,QAAsB;IAEtB,yBAAyB;IACzB,MAAM,KAAK,GAAG,MAAM,eAAe,CAAC,MAAM,CAAC,CAAC;IAE5C,MAAM,OAAO,GAAkB,EAAE,CAAC;IAClC,MAAM,MAAM,GAAgB,EAAE,CAAC;IAC/B,MAAM,iBAAiB,GAAuB,EAAE,CAAC;IAEjD,KAAK,MAAM,QAAQ,IAAI,KAAK,EAAE,CAAC;QAC7B,IAAI,CAAC;YACH,qEAAqE;YACrE,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAErD,kEAAkE;YAClE,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC;gBAAE,SAAS;YAE/C,iDAAiD;YACjD,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,QAAQ,CAAC;gBAAE,SAAS;YAEnD,mEAAmE;YACnE,0EAA0E;YAC1E,MAAM,WAAW,GAAG,mBAAmB,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;YAErE,IAAI,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC;gBACzB,8CAA8C;gBAC9C,MAAM,CAAC,IAAI,CAAC;oBACV,IAAI,EAAE,QAAQ;oBACd,KAAK,EAAE,WAAW,CAAC,KAAK;iBACzB,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YAED,MAAM,EAAE,UAAU,EAAE,iBAAiB,EAAE,WAAW,EAAE,GAAG,WAAW,CAAC,KAAK,CAAC;YAEzE,4CAA4C;YAC5C,KAAK,MAAM,OAAO,IAAI,WAAW,EAAE,CAAC;gBAClC,iBAAiB,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;YAC7D,CAAC;YAED,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS;YAEtC,OAAO,CAAC,IAAI,CAAC;gBACX,QAAQ;gBACR,UAAU;aACX,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,+BAA+B;YAC/B,MAAM,CAAC,IAAI,CAAC;gBACV,IAAI,EAAE,QAAQ;gBACd,KAAK,EAAE,oBAAoB,CACzB,QAAQ,EACR,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EACtD,SAAS,EACT,KAAK,CACN;aACF,CAAC,CAAC;YACH,SAAS;QACX,CAAC;IACH,CAAC;IAED,oDAAoD;IACpD,OAAO,CAAC,CAAC,EAAE,CAAC;QACV,KAAK,EAAE,OAAO;QACd,MAAM;QACN,iBAAiB;KAClB,CAAC,CAAC;AACL,CAAC;AAED,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACvF,OAAO,EAAE,mBAAmB,EAA8B,MAAM,iBAAiB,CAAC"}

package/dist/scanner/pattern-scanner.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @architect
+ * @architect-core @architect-scanner
+ * @architect-pattern Pattern Scanner
+ * @architect-status completed
+ * @architect-arch-role infrastructure
+ * @architect-arch-context scanner
+ * @architect-arch-layer infrastructure
+ * @architect-include pipeline-stages
+ * @architect-uses glob, AST Parser
+ * @architect-used-by Doc Extractor, Orchestrator
+ * @architect-usecase "When discovering TypeScript files for documentation extraction"
+ * @architect-usecase "When filtering files by @architect opt-in marker"
+ *
+ * ## Pattern Scanner - File Discovery and Directive Detection
+ *
+ * Discovers TypeScript files matching glob patterns and filters to only
+ * those with `@architect` opt-in. Entry point for the scanning phase.
+ *
+ * ### When to Use
+ *
+ * - Discovering source files for documentation generation
+ * - Checking file opt-in status before extraction
+ * - Building file lists for batch processing
+ *
+ * ### Key Concepts
+ *
+ * - **Opt-in Model**: Files must explicitly declare `@architect` to be processed
+ * - **Glob Patterns**: Uses glob for flexible file matching
+ * - **Exclusion Support**: Configurable exclude patterns for node_modules, tests, etc.
+ */
+import type { ScannerConfig } from '../types/index.js';
+import type { TagRegistry } from '../validation-schemas/tag-registry.js';
+/**
+ * Finds all TypeScript files matching the scanner configuration
+ *
+ * @param config - Scanner configuration
+ * @returns Array of file paths to scan
+ */
+export declare function findFilesToScan(config: ScannerConfig): Promise<readonly string[]>;
+/**
+ * Checks if file has opted-in to documentation generation
+ *
+ * Files must have the file-level opt-in tag (e.g., `@architect` without suffix)
+ * in a JSDoc block comment to be included in documentation generation.
+ * This is separate from section tags (e.g., `@architect-*`) which mark
+ * individual blocks for extraction.
+ *
+ * @param content - File content to check
+ * @param registry - Optional TagRegistry for custom prefix configuration
+ * @returns True if file has opt-in tag
+ *
+ * @example
+ * ```typescript
+ * // File with opt-in
+ * const content1 = `
+ *   /** @architect This file is documented *\/
+ *   export function foo() {}
+ * `;
+ * hasFileOptIn(content1); // true
+ *
+ * // File without opt-in (only has section tags)
+ * const content2 = `
+ *   /** @architect-core *\/
+ *   export function bar() {}
+ * `;
+ * hasFileOptIn(content2); // false
+ *
+ * // With custom registry
+ * const registry = { tagPrefix: "@acme-", fileOptInTag: "@acme", ... };
+ * hasFileOptIn(content, registry); // Uses @acme pattern
+ * ```
+ */
+export declare function hasFileOptIn(content: string, registry?: TagRegistry): boolean;
+/**
+ * Checks if file content contains doc directives (e.g., @architect-*)
+ *
+ * @param content - File content to check
+ * @param registry - Optional TagRegistry for custom prefix configuration
+ * @returns True if content contains documentation directives
+ */
+export declare function hasDocDirectives(content: string, registry?: TagRegistry): boolean;
+//# sourceMappingURL=pattern-scanner.d.ts.map

package/dist/scanner/pattern-scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pattern-scanner.d.ts","sourceRoot":"","sources":["../../src/scanner/pattern-scanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uCAAuC,CAAC;AAEzE;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAmBvF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,OAAO,CAK7E;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,OAAO,CAKjF"}

package/dist/scanner/pattern-scanner.js

@@ -0,0 +1,110 @@
+/**
+ * @architect
+ * @architect-core @architect-scanner
+ * @architect-pattern Pattern Scanner
+ * @architect-status completed
+ * @architect-arch-role infrastructure
+ * @architect-arch-context scanner
+ * @architect-arch-layer infrastructure
+ * @architect-include pipeline-stages
+ * @architect-uses glob, AST Parser
+ * @architect-used-by Doc Extractor, Orchestrator
+ * @architect-usecase "When discovering TypeScript files for documentation extraction"
+ * @architect-usecase "When filtering files by @architect opt-in marker"
+ *
+ * ## Pattern Scanner - File Discovery and Directive Detection
+ *
+ * Discovers TypeScript files matching glob patterns and filters to only
+ * those with `@architect` opt-in. Entry point for the scanning phase.
+ *
+ * ### When to Use
+ *
+ * - Discovering source files for documentation generation
+ * - Checking file opt-in status before extraction
+ * - Building file lists for batch processing
+ *
+ * ### Key Concepts
+ *
+ * - **Opt-in Model**: Files must explicitly declare `@architect` to be processed
+ * - **Glob Patterns**: Uses glob for flexible file matching
+ * - **Exclusion Support**: Configurable exclude patterns for node_modules, tests, etc.
+ */
+import { glob } from 'glob';
+import { createRegexBuilders } from '../config/regex-builders.js';
+import { DEFAULT_REGEX_BUILDERS } from '../config/defaults.js';
+/**
+ * Finds all TypeScript files matching the scanner configuration
+ *
+ * @param config - Scanner configuration
+ * @returns Array of file paths to scan
+ */
+export async function findFilesToScan(config) {
+    const defaultExclude = [
+        'node_modules/**',
+        'dist/**',
+        '**/*.test.ts',
+        '**/*.spec.ts',
+        '**/*.d.ts',
+    ];
+    const excludePatterns = config.exclude ? [...defaultExclude, ...config.exclude] : defaultExclude;
+    const files = await glob([...config.patterns], {
+        cwd: config.baseDir,
+        ignore: excludePatterns,
+        absolute: true,
+    });
+    // Filter to only TypeScript source files
+    return files.filter((file) => file.endsWith('.ts') && !file.endsWith('.d.ts'));
+}
+/**
+ * Checks if file has opted-in to documentation generation
+ *
+ * Files must have the file-level opt-in tag (e.g., `@architect` without suffix)
+ * in a JSDoc block comment to be included in documentation generation.
+ * This is separate from section tags (e.g., `@architect-*`) which mark
+ * individual blocks for extraction.
+ *
+ * @param content - File content to check
+ * @param registry - Optional TagRegistry for custom prefix configuration
+ * @returns True if file has opt-in tag
+ *
+ * @example
+ * ```typescript
+ * // File with opt-in
+ * const content1 = `
+ *   /** @architect This file is documented *\/
+ *   export function foo() {}
+ * `;
+ * hasFileOptIn(content1); // true
+ *
+ * // File without opt-in (only has section tags)
+ * const content2 = `
+ *   /** @architect-core *\/
+ *   export function bar() {}
+ * `;
+ * hasFileOptIn(content2); // false
+ *
+ * // With custom registry
+ * const registry = { tagPrefix: "@acme-", fileOptInTag: "@acme", ... };
+ * hasFileOptIn(content, registry); // Uses @acme pattern
+ * ```
+ */
+export function hasFileOptIn(content, registry) {
+    const builders = registry
+        ? createRegexBuilders(registry.tagPrefix, registry.fileOptInTag)
+        : DEFAULT_REGEX_BUILDERS;
+    return builders.hasFileOptIn(content);
+}
+/**
+ * Checks if file content contains doc directives (e.g., @architect-*)
+ *
+ * @param content - File content to check
+ * @param registry - Optional TagRegistry for custom prefix configuration
+ * @returns True if content contains documentation directives
+ */
+export function hasDocDirectives(content, registry) {
+    const builders = registry
+        ? createRegexBuilders(registry.tagPrefix, registry.fileOptInTag)
+        : DEFAULT_REGEX_BUILDERS;
+    return builders.hasDocDirectives(content);
+}
+//# sourceMappingURL=pattern-scanner.js.map

package/dist/scanner/pattern-scanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pattern-scanner.js","sourceRoot":"","sources":["../../src/scanner/pattern-scanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAG/D;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,MAAqB;IACzD,MAAM,cAAc,GAAG;QACrB,iBAAiB;QACjB,SAAS;QACT,cAAc;QACd,cAAc;QACd,WAAW;KACZ,CAAC;IAEF,MAAM,eAAe,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,cAAc,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC;IAEjG,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,EAAE;QAC7C,GAAG,EAAE,MAAM,CAAC,OAAO;QACnB,MAAM,EAAE,eAAe;QACvB,QAAQ,EAAE,IAAI;KACf,CAAC,CAAC;IAEH,yCAAyC;IACzC,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;AACjF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,QAAsB;IAClE,MAAM,QAAQ,GAAG,QAAQ;QACvB,CAAC,CAAC,mBAAmB,CAAC,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,YAAY,CAAC;QAChE,CAAC,CAAC,sBAAsB,CAAC;IAC3B,OAAO,QAAQ,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,QAAsB;IACtE,MAAM,QAAQ,GAAG,QAAQ;QACvB,CAAC,CAAC,mBAAmB,CAAC,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,YAAY,CAAC;QAChE,CAAC,CAAC,sBAAsB,CAAC;IAC3B,OAAO,QAAQ,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAC5C,CAAC"}

package/dist/taxonomy/categories.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @architect
+ * @architect-pattern CategoryDefinitions
+ * @architect-status completed
+ * @architect-core
+ * @architect-arch-role read-model
+ * @architect-arch-context taxonomy
+ * @architect-arch-layer domain
+ * @architect-extract-shapes CategoryDefinition, CATEGORIES, CategoryTag, CATEGORY_TAGS
+ *
+ * ## Category Definitions
+ *
+ * Categories are used to classify patterns and organize documentation.
+ * Priority determines display order (lower = higher priority).
+ * The ddd-es-cqrs preset includes all 21 categories; simpler presets use subsets.
+ *
+ * **When to Use:** When adding new pattern categories or configuring preset category subsets for tag registries.
+ */
+/**
+ * @architect-implements CategoryDefinitions
+ * @architect-shape reference-sample
+ */
+export interface CategoryDefinition {
+    /** Category tag name without prefix (e.g., "core", "api", "ddd", "saga") */
+    readonly tag: string;
+    /** Human-readable domain name for display (e.g., "Strategic DDD", "Event Sourcing") */
+    readonly domain: string;
+    /** Display order priority - lower values appear first in sorted output */
+    readonly priority: number;
+    /** Brief description of the category's purpose and typical patterns */
+    readonly description: string;
+    /** Alternative tag names that map to this category (e.g., "es" for "event-sourcing") */
+    readonly aliases: readonly string[];
+}
+/**
+ * All category definitions for the monorepo
+ */
+export declare const CATEGORIES: readonly CategoryDefinition[];
+/**
+ * Category tags as a union type
+ */
+export type CategoryTag = (typeof CATEGORIES)[number]['tag'];
+/**
+ * Extract all category tags as an array
+ */
+export declare const CATEGORY_TAGS: readonly CategoryTag[];
+//# sourceMappingURL=categories.d.ts.map

package/dist/taxonomy/categories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"categories.d.ts","sourceRoot":"","sources":["../../src/taxonomy/categories.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,uFAAuF;IACvF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,wFAAwF;IACxF,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED;;GAEG;AACH,eAAO,MAAM,UAAU,EAAE,SAAS,kBAAkB,EAoJ1C,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC;AAE7D;;GAEG;AACH,eAAO,MAAM,aAAa,EAAmC,SAAS,WAAW,EAAE,CAAC"}