@doquflow/server 0.2.0 → 0.4.0

package/dist/tools/lint-wiki.js

@@ -0,0 +1,342 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lintWiki = lintWiki;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+function parsePageMetadata(content) {
+    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+    if (!frontmatterMatch) {
+        return { metadata: null, body: content };
+    }
+    const frontmatterStr = frontmatterMatch[1];
+    const body = frontmatterMatch[2];
+    const metadata = {
+        created_at: extractYamlField(frontmatterStr, "created_at") || new Date().toISOString(),
+        updated_at: extractYamlField(frontmatterStr, "updated_at") || new Date().toISOString(),
+        sources: parseYamlArray(frontmatterStr, "sources") || [],
+        tags: parseYamlArray(frontmatterStr, "tags") || [],
+        inbound_links: parseYamlArray(frontmatterStr, "inbound_links") || [],
+        outbound_links: parseYamlArray(frontmatterStr, "outbound_links") || [],
+    };
+    return { metadata, body };
+}
+function extractYamlField(yaml, field) {
+    const regex = new RegExp(`^${field}:\\s*(.+)$`, "m");
+    const match = yaml.match(regex);
+    return match ? match[1].trim() : null;
+}
+function parseYamlArray(yaml, field) {
+    const regex = new RegExp(`^${field}:\\s*\\[(.+)\\]$`, "m");
+    const match = yaml.match(regex);
+    if (!match)
+        return [];
+    return match[1].split(",").map((s) => s.trim().replace(/['"]/g, ""));
+}
+function extractLinks(content) {
+    const linkRegex = /\[([^\]]+)\]\(\.\/([^)]+)\)/g;
+    const links = [];
+    let match;
+    while ((match = linkRegex.exec(content)) !== null) {
+        links.push(match[2].replace(".md", ""));
+    }
+    return links;
+}
+function findOrphanPages(pageMap) {
+    const issues = [];
+    for (const [pageId, filePath] of pageMap) {
+        if (!fs.existsSync(filePath))
+            continue;
+        const content = fs.readFileSync(filePath, "utf-8");
+        const { metadata } = parsePageMetadata(content);
+        if (metadata && metadata.inbound_links.length === 0) {
+            issues.push({
+                type: "orphan",
+                page_id: pageId,
+                page_title: extractPageTitle(content),
+                severity: "medium",
+                detail: `Page has no inbound links from other wiki pages`,
+                suggestion: `Consider linking this page from related entity or concept pages, or remove if not needed.`,
+            });
+        }
+    }
+    return issues;
+}
+function findStalePages(pageMap) {
+    const issues = [];
+    const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+    for (const [pageId, filePath] of pageMap) {
+        if (!fs.existsSync(filePath))
+            continue;
+        const content = fs.readFileSync(filePath, "utf-8");
+        const { metadata } = parsePageMetadata(content);
+        if (metadata) {
+            const updatedAt = new Date(metadata.updated_at);
+            if (updatedAt < thirtyDaysAgo) {
+                issues.push({
+                    type: "stale",
+                    page_id: pageId,
+                    page_title: extractPageTitle(content),
+                    severity: "low",
+                    detail: `Page last updated ${Math.floor((Date.now() - updatedAt.getTime()) / (24 * 60 * 60 * 1000))} days ago`,
+                    suggestion: `Consider reviewing and updating if new information is available.`,
+                });
+            }
+        }
+    }
+    return issues;
+}
+function findMissingReferences(pageMap) {
+    const issues = [];
+    for (const [pageId, filePath] of pageMap) {
+        if (!fs.existsSync(filePath))
+            continue;
+        const content = fs.readFileSync(filePath, "utf-8");
+        const { body } = parsePageMetadata(content);
+        const links = extractLinks(body);
+        for (const link of links) {
+            if (!pageMap.has(link)) {
+                issues.push({
+                    type: "missing_ref",
+                    page_id: pageId,
+                    page_title: extractPageTitle(content),
+                    severity: "high",
+                    detail: `References non-existent page: ${link}`,
+                    suggestion: `Check if ${link} should be created or if the reference should be updated.`,
+                });
+            }
+        }
+    }
+    return issues;
+}
+function findMetadataGaps(pageMap) {
+    const issues = [];
+    for (const [pageId, filePath] of pageMap) {
+        if (!fs.existsSync(filePath))
+            continue;
+        const content = fs.readFileSync(filePath, "utf-8");
+        const { metadata } = parsePageMetadata(content);
+        if (!metadata) {
+            issues.push({
+                type: "metadata_gap",
+                page_id: pageId,
+                page_title: extractPageTitle(content),
+                severity: "medium",
+                detail: `Page missing YAML frontmatter with metadata`,
+                suggestion: `Add frontmatter with created_at, updated_at, sources, tags, and links.`,
+            });
+        }
+        else {
+            if (!metadata.created_at || !metadata.updated_at) {
+                issues.push({
+                    type: "metadata_gap",
+                    page_id: pageId,
+                    page_title: extractPageTitle(content),
+                    severity: "low",
+                    detail: `Page missing timestamp metadata (created_at or updated_at)`,
+                    suggestion: `Ensure all pages have creation and update timestamps in frontmatter.`,
+                });
+            }
+            if (metadata.sources.length === 0) {
+                issues.push({
+                    type: "metadata_gap",
+                    page_id: pageId,
+                    page_title: extractPageTitle(content),
+                    severity: "low",
+                    detail: `Page has no source references`,
+                    suggestion: `Add source document references to improve traceability.`,
+                });
+            }
+        }
+    }
+    return issues;
+}
+function findContradictions(wikiPath) {
+    const issues = [];
+    const pageContents = new Map();
+    // Load all pages
+    for (const categoryDir of fs.readdirSync(wikiPath)) {
+        const categoryPath = path.join(wikiPath, categoryDir);
+        if (!fs.statSync(categoryPath).isDirectory())
+            continue;
+        for (const file of fs.readdirSync(categoryPath)) {
+            if (!file.endsWith(".md"))
+                continue;
+            const pageId = file.replace(".md", "");
+            const content = fs.readFileSync(path.join(categoryPath, file), "utf-8");
+            const title = extractPageTitle(content);
+            pageContents.set(pageId, { title, content });
+        }
+    }
+    // Look for contradiction patterns
+    const contradictionPatterns = [
+        { pattern: /should be|must be/i, opposite: /should not be|must not be/i },
+        { pattern: /recommended/i, opposite: /not recommended/i },
+        { pattern: /required/i, opposite: /optional/i },
+    ];
+    const contentArray = Array.from(pageContents.values()).map((p) => p.content);
+    for (let i = 0; i < contentArray.length; i++) {
+        for (let j = i + 1; j < contentArray.length; j++) {
+            for (const { pattern, opposite } of contradictionPatterns) {
+                if (pattern.test(contentArray[i]) && opposite.test(contentArray[j])) {
+                    const key1 = Array.from(pageContents.entries()).find(([, v]) => v.content === contentArray[i])?.[0];
+                    const key2 = Array.from(pageContents.entries()).find(([, v]) => v.content === contentArray[j])?.[0];
+                    if (key1 && key2) {
+                        issues.push({
+                            type: "contradiction",
+                            page_id: key1,
+                            page_title: pageContents.get(key1)?.title || key1,
+                            severity: "high",
+                            detail: `Potential contradiction with ${key2}`,
+                            suggestion: `Review both pages and resolve conflicting statements.`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return issues;
+}
+function extractPageTitle(content) {
+    const match = content.match(/^#+\s+(.+)$/m);
+    return match ? match[1].trim() : "Untitled";
+}
+function calculateHealthScore(result) {
+    const { issues_found, total_pages } = result;
+    if (total_pages === 0)
+        return 100;
+    const issueWeights = {
+        high: 10,
+        medium: 5,
+        low: 2,
+    };
+    let penalty = 0;
+    for (const issue of issues_found) {
+        penalty += issueWeights[issue.severity];
+    }
+    const maxPenalty = total_pages * 10;
+    const score = Math.max(0, 100 - (penalty / maxPenalty) * 100);
+    return Math.round(score);
+}
+function generateRecommendations(result) {
+    const recommendations = [];
+    if (result.metrics.orphan_pages > 0) {
+        recommendations.push(`${result.metrics.orphan_pages} orphan pages found. Consider linking them or removing if outdated.`);
+    }
+    if (result.metrics.missing_refs > 0) {
+        recommendations.push(`${result.metrics.missing_refs} broken references found. Update or create missing pages.`);
+    }
+    if (result.metrics.stale_pages > 0) {
+        recommendations.push(`${result.metrics.stale_pages} pages not updated in 30+ days. Review and refresh content.`);
+    }
+    if (result.metrics.metadata_gaps > 0) {
+        recommendations.push(`${result.metrics.metadata_gaps} pages have metadata gaps. Add source references and timestamps.`);
+    }
+    if (result.metrics.contradictions > 0) {
+        recommendations.push(`${result.metrics.contradictions} potential contradictions found. Review and resolve.`);
+    }
+    if (result.health_score >= 90) {
+        recommendations.push("✓ Wiki is in excellent health! Continue maintaining current standards.");
+    }
+    else if (result.health_score >= 70) {
+        recommendations.push("Wiki health is good. Address high-severity issues to improve further.");
+    }
+    else if (result.health_score < 50) {
+        recommendations.push("⚠ Wiki needs maintenance. Prioritize fixing high-severity issues.");
+    }
+    return recommendations;
+}
+async function lintWiki(params) {
+    const { project_path, check_type = "all" } = params;
+    const wikiPath = path.join(project_path, ".docuflow", "wiki");
+    if (!fs.existsSync(wikiPath)) {
+        throw new Error(`Wiki not found at ${wikiPath}`);
+    }
+    // Collect all page IDs mapped to their full file paths
+    const pageMap = new Map();
+    for (const categoryDir of fs.readdirSync(wikiPath)) {
+        const categoryPath = path.join(wikiPath, categoryDir);
+        if (!fs.statSync(categoryPath).isDirectory())
+            continue;
+        for (const file of fs.readdirSync(categoryPath)) {
+            if (file.endsWith(".md")) {
+                const pageId = file.replace(".md", "");
+                pageMap.set(pageId, path.join(categoryPath, file));
+            }
+        }
+    }
+    // Run checks
+    let issues = [];
+    if (check_type === "all" || check_type === "orphans") {
+        issues.push(...findOrphanPages(pageMap));
+    }
+    if (check_type === "all" || check_type === "contradictions") {
+        issues.push(...findContradictions(wikiPath));
+    }
+    if (check_type === "all" || check_type === "stale") {
+        issues.push(...findStalePages(pageMap));
+    }
+    if (check_type === "all" || check_type === "metadata") {
+        issues.push(...findMissingReferences(pageMap));
+        issues.push(...findMetadataGaps(pageMap));
+    }
+    // Calculate metrics
+    const metrics = {
+        orphan_pages: issues.filter((i) => i.type === "orphan").length,
+        contradictions: issues.filter((i) => i.type === "contradiction").length,
+        stale_pages: issues.filter((i) => i.type === "stale").length,
+        missing_refs: issues.filter((i) => i.type === "missing_ref").length,
+        metadata_gaps: issues.filter((i) => i.type === "metadata_gap").length,
+    };
+    // Build result
+    const result = {
+        total_pages: pageMap.size,
+        issues_found: issues,
+        metrics,
+        recommendations: [],
+        health_score: 0,
+    };
+    // Calculate health score and recommendations
+    result.health_score = calculateHealthScore(result);
+    result.recommendations = generateRecommendations(result);
+    // Append to log.md
+    const logPath = path.join(project_path, ".docuflow", "log.md");
+    if (fs.existsSync(logPath)) {
+        const timestamp = new Date().toISOString();
+        const logEntry = `\n## [${timestamp}] lint | Wiki lint check completed\n\n- Pages checked: ${result.total_pages}\n- Issues found: ${result.issues_found.length}\n- Health score: ${result.health_score}%\n- High severity: ${metrics.contradictions + metrics.missing_refs}\n`;
+        fs.appendFileSync(logPath, logEntry);
+    }
+    return result;
+}

package/dist/tools/list-wiki.js

@@ -0,0 +1,129 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listWiki = listWiki;
+const node_path_1 = __importDefault(require("node:path"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+const filesystem_1 = require("../filesystem");
+const PLURAL_TO_SINGULAR = {
+    entities: "entity",
+    concepts: "concept",
+    timelines: "timeline",
+    syntheses: "synthesis",
+};
+const SINGULAR_TO_PLURAL = {
+    entity: "entities",
+    concept: "concepts",
+    timeline: "timelines",
+    synthesis: "syntheses",
+};
+const STALE_DAYS = 30;
+/**
+ * Parse frontmatter from markdown
+ */
+function parseFrontmatter(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match)
+        return {};
+    const yaml = match[1];
+    const result = {};
+    for (const line of yaml.split("\n")) {
+        if (!line.trim())
+            continue;
+        const [key, ...valueParts] = line.split(":");
+        const value = valueParts.join(":").trim();
+        try {
+            if (value.startsWith("[") || value.startsWith("{")) {
+                result[key.trim()] = JSON.parse(value);
+            }
+            else {
+                result[key.trim()] = value;
+            }
+        }
+        catch {
+            result[key.trim()] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Extract title from markdown
+ */
+function extractTitle(content) {
+    const match = content.match(/^#\s+(.+?)$/m);
+    return match ? match[1].trim() : "Untitled";
+}
+async function listWiki(input) {
+    try {
+        const projectPath = node_path_1.default.resolve(input.project_path);
+        const docuDir = node_path_1.default.join(projectPath, ".docuflow");
+        const wikiDir = node_path_1.default.join(docuDir, "wiki");
+        const pages = [];
+        const categories = {};
+        const now = Date.now();
+        // Build list of categories to scan — always use correct plural directory names
+        let categoriesToScan = ["entities", "concepts", "timelines", "syntheses"];
+        if (input.category) {
+            const pluralDir = SINGULAR_TO_PLURAL[input.category] ?? `${input.category}s`;
+            categoriesToScan = [pluralDir];
+        }
+        // Scan each category
+        for (const categoryDir of categoriesToScan) {
+            const fullCategoryPath = node_path_1.default.join(wikiDir, categoryDir);
+            const category = PLURAL_TO_SINGULAR[categoryDir] ?? categoryDir;
+            try {
+                const files = await promises_1.default.readdir(fullCategoryPath);
+                let categoryCount = 0;
+                for (const file of files) {
+                    if (!file.endsWith(".md"))
+                        continue;
+                    const filePath = node_path_1.default.join(fullCategoryPath, file);
+                    const read = await (0, filesystem_1.safeReadFile)(filePath);
+                    if (read.error || read.binary || !read.content)
+                        continue;
+                    const fm = parseFrontmatter(read.content);
+                    const title = extractTitle(read.content);
+                    const pageId = file.replace(".md", "");
+                    const updatedAt = fm.updated_at ?? new Date().toISOString();
+                    const updatedMs = new Date(updatedAt).getTime();
+                    const stale = !isNaN(updatedMs) && (now - updatedMs) > STALE_DAYS * 86_400_000;
+                    pages.push({
+                        id: pageId,
+                        title,
+                        category,
+                        path: node_path_1.default.relative(docuDir, filePath),
+                        created_at: fm.created_at ?? new Date().toISOString(),
+                        updated_at: updatedAt,
+                        sources: fm.sources ?? [],
+                        tags: fm.tags ?? [],
+                        stale,
+                    });
+                    categoryCount++;
+                }
+                if (categoryCount > 0) {
+                    categories[category] = categoryCount;
+                }
+            }
+            catch (e) {
+                // Category directory may not exist yet
+            }
+        }
+        return {
+            total_pages: pages.length,
+            stale_pages: pages.filter((p) => p.stale).length,
+            pages: pages.sort((a, b) => a.title.localeCompare(b.title)),
+            categories,
+        };
+    }
+    catch (e) {
+        return {
+            total_pages: 0,
+            stale_pages: 0,
+            pages: [],
+            categories: {},
+            error: e?.message ?? String(e),
+        };
+    }
+}