shirokuma-docs 0.1.0-alpha.1

package/dist/md/analyzer/index.js

@@ -0,0 +1,288 @@
+import matter from 'gray-matter';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { parseHeadings, countLines, flattenHeadings } from '../utils/markdown.js';
+import { estimateTokens } from '../utils/tokens.js';
+import { FileCollector } from '../utils/file-collector.js';
+/**
+ * Document analyzer
+ * Analyzes document structure and dependencies
+ */
+export class Analyzer {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Analyzes document structure and dependencies
+     *
+     * Performs comprehensive analysis including:
+     * - Dependency graph extraction (frontmatter, wiki-links, markdown links)
+     * - Circular dependency detection
+     * - Orphan file detection
+     * - File metrics (lines, tokens, headings)
+     * - Split suggestions for large files (optional)
+     *
+     * @param sourceDir - Source directory containing markdown files
+     * @param options - Analysis options (includeMetrics, includeSplitSuggestions)
+     * @returns Analysis result with dependencies, metrics, and suggestions
+     *
+     * @example
+     * ```typescript
+     * const analyzer = new Analyzer(config);
+     * const result = await analyzer.analyze('./docs', { includeMetrics: true });
+     * console.log(`Found ${result.dependencies.length} dependencies`);
+     * console.log(`Detected ${result.cycles.length} circular dependencies`);
+     * ```
+     */
+    async analyze(sourceDir, options) {
+        // Collect all markdown files
+        const collector = new FileCollector(this.config);
+        const allFiles = await collector.collect(sourceDir);
+        // Parse documents
+        const documents = [];
+        for (const filePath of allFiles) {
+            const content = await fs.readFile(filePath, 'utf-8');
+            const parsed = matter(content);
+            documents.push({
+                path: filePath,
+                frontmatter: parsed.data,
+                content: parsed.content,
+                sections: [],
+            });
+        }
+        // Extract dependencies
+        const dependencies = this.extractDependencies(documents, sourceDir);
+        // Detect cycles
+        const cycles = this.detectCycles(dependencies);
+        // Detect orphans
+        const orphans = this.detectOrphans(documents, dependencies);
+        // Calculate most referenced files
+        const mostReferenced = this.calculateMostReferenced(dependencies);
+        const result = {
+            totalFiles: documents.length,
+            dependencies,
+            orphans,
+            cycles,
+            mostReferenced,
+        };
+        // Optionally compute file metrics
+        if (options?.includeMetrics) {
+            const fileMetrics = await this.calculateFileMetrics(documents, sourceDir);
+            result.fileMetrics = fileMetrics;
+            result.totalTokens = fileMetrics.reduce((sum, m) => sum + m.tokens, 0);
+            result.averageTokensPerFile = result.totalTokens / fileMetrics.length;
+        }
+        // Optionally generate split suggestions
+        if (options?.includeSplitSuggestions && result.fileMetrics) {
+            result.splitSuggestions = this.generateSplitSuggestions(result.fileMetrics);
+        }
+        return result;
+    }
+    extractDependencies(documents, sourceDir) {
+        const edges = [];
+        for (const doc of documents) {
+            const from = path.relative(sourceDir, doc.path);
+            // 1. Extract from frontmatter dependencies
+            if (doc.frontmatter.dependencies && Array.isArray(doc.frontmatter.dependencies)) {
+                for (const dep of doc.frontmatter.dependencies) {
+                    edges.push({
+                        from,
+                        to: dep,
+                        type: 'frontmatter',
+                    });
+                }
+            }
+            // 2. Extract wiki-links [[filename]]
+            const wikiLinkRegex = /\[\[([^\]]+)\]\]/g;
+            let match;
+            while ((match = wikiLinkRegex.exec(doc.content)) !== null) {
+                if (match[1]) {
+                    edges.push({
+                        from,
+                        to: match[1],
+                        type: 'wiki-link',
+                    });
+                }
+            }
+            // 3. Extract markdown links [text](path.md)
+            const mdLinkRegex = /\[([^\]]+)\]\(([^)]+\.md)\)/g;
+            while ((match = mdLinkRegex.exec(doc.content)) !== null) {
+                if (match[2]) {
+                    edges.push({
+                        from,
+                        to: match[2],
+                        type: 'markdown-link',
+                    });
+                }
+            }
+        }
+        return edges;
+    }
+    detectCycles(dependencies) {
+        const cycles = [];
+        const graph = this.buildGraph(dependencies);
+        const visited = new Set();
+        const recStack = new Set();
+        const dfs = (node, path) => {
+            visited.add(node);
+            recStack.add(node);
+            path.push(node);
+            const neighbors = graph.get(node) || [];
+            for (const neighbor of neighbors) {
+                if (!visited.has(neighbor)) {
+                    dfs(neighbor, [...path]);
+                }
+                else if (recStack.has(neighbor)) {
+                    // Found a cycle
+                    const cycleStart = path.indexOf(neighbor);
+                    if (cycleStart !== -1) {
+                        cycles.push([...path.slice(cycleStart), neighbor]);
+                    }
+                }
+            }
+            recStack.delete(node);
+        };
+        for (const node of graph.keys()) {
+            if (!visited.has(node)) {
+                dfs(node, []);
+            }
+        }
+        return cycles;
+    }
+    detectOrphans(documents, dependencies) {
+        const referenced = new Set();
+        for (const edge of dependencies) {
+            referenced.add(edge.to);
+        }
+        const orphans = [];
+        for (const doc of documents) {
+            const fileName = path.basename(doc.path);
+            if (!referenced.has(fileName) && !referenced.has(doc.path)) {
+                orphans.push(doc.path);
+            }
+        }
+        return orphans;
+    }
+    calculateMostReferenced(dependencies) {
+        const counts = new Map();
+        for (const edge of dependencies) {
+            counts.set(edge.to, (counts.get(edge.to) || 0) + 1);
+        }
+        return Array.from(counts.entries())
+            .map(([file, count]) => ({ file, count }))
+            .sort((a, b) => b.count - a.count)
+            .slice(0, 10); // Top 10
+    }
+    buildGraph(dependencies) {
+        const graph = new Map();
+        for (const edge of dependencies) {
+            if (!graph.has(edge.from)) {
+                graph.set(edge.from, []);
+            }
+            graph.get(edge.from).push(edge.to);
+        }
+        return graph;
+    }
+    async calculateFileMetrics(documents, sourceDir) {
+        const metrics = [];
+        for (const doc of documents) {
+            const stat = await fs.stat(doc.path);
+            const lines = countLines(doc.content);
+            const tokens = estimateTokens(doc.content);
+            const headings = parseHeadings(doc.content);
+            metrics.push({
+                file: path.relative(sourceDir, doc.path),
+                size: stat.size,
+                lines,
+                tokens,
+                headings,
+                topLevelSections: headings.length,
+            });
+        }
+        return metrics;
+    }
+    generateSplitSuggestions(fileMetrics) {
+        const suggestions = [];
+        // Thresholds for suggesting splits
+        const MAX_LINES = 200;
+        const MAX_TOKENS = 2000;
+        const MIN_SPLIT_SIZE = 50; // Minimum lines for a split section
+        for (const metrics of fileMetrics) {
+            const shouldSplit = metrics.lines > MAX_LINES || metrics.tokens > MAX_TOKENS;
+            if (!shouldSplit) {
+                continue;
+            }
+            // Find Level 2 headings as split candidates
+            const splitCandidates = [];
+            const allHeadings = flattenHeadings(metrics.headings);
+            for (const heading of allHeadings) {
+                if (heading.level === 2) {
+                    const sectionLines = heading.endLine - heading.startLine + 1;
+                    const sectionContent = this.extractSectionContent(heading);
+                    const sectionTokens = estimateTokens(sectionContent);
+                    if (sectionLines >= MIN_SPLIT_SIZE) {
+                        splitCandidates.push({
+                            heading: heading.text,
+                            level: heading.level,
+                            startLine: heading.startLine,
+                            endLine: heading.endLine,
+                            estimatedLines: sectionLines,
+                            estimatedTokens: sectionTokens,
+                        });
+                    }
+                }
+            }
+            if (splitCandidates.length > 0) {
+                let reason = '';
+                if (metrics.lines > MAX_LINES && metrics.tokens > MAX_TOKENS) {
+                    reason = `File is too large (${metrics.lines} lines, ${metrics.tokens} tokens)`;
+                }
+                else if (metrics.lines > MAX_LINES) {
+                    reason = `File has too many lines (${metrics.lines})`;
+                }
+                else {
+                    reason = `File has too many tokens (${metrics.tokens})`;
+                }
+                suggestions.push({
+                    file: metrics.file,
+                    reason,
+                    currentSize: metrics.lines,
+                    currentTokens: metrics.tokens,
+                    suggestedSplits: splitCandidates,
+                });
+            }
+        }
+        return suggestions;
+    }
+    extractSectionContent(heading) {
+        // Rough estimate based on lines - in real implementation,
+        // we'd need the original content
+        const avgCharsPerLine = 80;
+        const estimatedChars = (heading.endLine - heading.startLine + 1) * avgCharsPerLine;
+        return 'x'.repeat(estimatedChars);
+    }
+    generateGraph(result) {
+        const lines = ['```mermaid', 'graph TD'];
+        // Add nodes and edges
+        const nodeIds = new Map();
+        let nodeCounter = 0;
+        for (const edge of result.dependencies) {
+            // Create node IDs
+            if (!nodeIds.has(edge.from)) {
+                nodeIds.set(edge.from, `N${nodeCounter++}`);
+            }
+            if (!nodeIds.has(edge.to)) {
+                nodeIds.set(edge.to, `N${nodeCounter++}`);
+            }
+            const fromId = nodeIds.get(edge.from);
+            const toId = nodeIds.get(edge.to);
+            // Add edge with type label
+            const edgeStyle = edge.type === 'frontmatter' ? '-->' : edge.type === 'wiki-link' ? '-..->' : '-->';
+            lines.push(`  ${fromId}["${edge.from}"] ${edgeStyle} ${toId}["${edge.to}"]`);
+        }
+        lines.push('```');
+        return lines.join('\n');
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/md/analyzer/index.js.map

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

package/dist/md/builder/index.d.ts

@@ -0,0 +1,91 @@
+import type { Config, BuildResult } from '../types/config.js';
+/**
+ * Document builder
+ * Combines multiple Markdown files into a single document
+ */
+export declare class Builder {
+    private config;
+    constructor(config: Config);
+    /**
+     * Builds combined markdown document from source directory
+     *
+     * Collects all markdown files matching include/exclude patterns, applies
+     * build-time optimizations (frontmatter stripping, token optimization),
+     * and combines them into a single output file.
+     *
+     * @param sourceDir - Source directory containing markdown files
+     * @param outputPath - Optional output path (uses config default if not specified)
+     * @returns Build result with file count, token count, and execution time
+     * @throws {Error} If no files found or build fails
+     *
+     * @example
+     * ```typescript
+     * const builder = new Builder(config);
+     * const result = await builder.build('./docs', './dist/output.md');
+     * console.log(`Built ${result.fileCount} files in ${result.buildTime}ms`);
+     * ```
+     */
+    build(sourceDir: string, outputPath?: string): Promise<BuildResult>;
+    private collectFiles;
+    private parseDocuments;
+    private parseSections;
+    private sortDocuments;
+    private groupByPattern;
+    /**
+     * Topological sort of documents based on dependencies
+     * Uses Kahn's algorithm with stable ordering by layer/category/title
+     */
+    private topologicalSort;
+    /**
+     * Build path map for quick document lookup
+     */
+    private buildPathMap;
+    /**
+     * Build dependency graph with in-degrees and dependents
+     */
+    private buildDependencyGraph;
+    /**
+     * Sort documents by metadata (layer, category, title)
+     */
+    private sortByMetadata;
+    /**
+     * Kahn's algorithm for topological sorting
+     */
+    private kahnsAlgorithm;
+    /**
+     * Handle circular dependencies by appending remaining documents
+     */
+    private handleCircularDependencies;
+    private getSortIndex;
+    private generateTOC;
+    private slugify;
+    private combineDocuments;
+    /**
+     * Apply build-time optimizations (non-destructive to source files)
+     */
+    /**
+     * Apply build optimizations using unified remark pipeline
+     * Migrated from regex-based to AST-based processing for safety
+     */
+    private applyBuildOptimizations;
+    /**
+     * Watches source directory for changes and rebuilds automatically
+     *
+     * Starts a file watcher that monitors changes to markdown files and triggers
+     * automatic rebuilds with debouncing. Runs indefinitely until interrupted.
+     *
+     * @param sourceDir - Source directory to watch
+     * @param outputPath - Output path for rebuilt files
+     * @returns Promise that never resolves (runs until process exit)
+     * @throws {Error} If watcher setup fails (watcher is cleaned up on error)
+     *
+     * @example
+     * ```typescript
+     * const builder = new Builder(config);
+     * await builder.watch('./docs', './dist/output.md');
+     * // Press Ctrl+C to stop watching
+     * ```
+     */
+    watch(sourceDir: string, outputPath: string): Promise<never>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/md/builder/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/md/builder/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAgB9D;;;GAGG;AACH,qBAAa,OAAO;IACN,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,MAAM;IAElC;;;;;;;;;;;;;;;;;;OAkBG;IACG,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;YAoD3D,YAAY;YAMZ,cAAc;IAwB5B,OAAO,CAAC,aAAa;IAoBrB,OAAO,CAAC,aAAa;IAkBrB,OAAO,CAAC,cAAc;IAiBtB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAUvB;;OAEG;IACH,OAAO,CAAC,YAAY;IASpB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAgC5B;;OAEG;IACH,OAAO,CAAC,cAAc;IAgBtB;;OAEG;IACH,OAAO,CAAC,cAAc;IAqCtB;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAWlC,OAAO,CAAC,YAAY;IAgBpB,OAAO,CAAC,WAAW;IAgBnB,OAAO,CAAC,OAAO;IAOf,OAAO,CAAC,gBAAgB;IAMxB;;OAEG;IACH;;;OAGG;YACW,uBAAuB;IAsErC;;;;;;;;;;;;;;;;;OAiBG;IACG,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;CAwFnE"}