@n-dx/core 0.1.0

package/packages/rex/dist/core/health.js

@@ -0,0 +1,331 @@
+/**
+ * Structure health score: evaluates the overall quality and organization
+ * of a PRD tree across multiple dimensions.
+ *
+ * Each dimension produces a 0-100 score. The overall score is a weighted
+ * average. Suggestions are generated for the lowest-scoring dimensions.
+ *
+ * @module core/health
+ */
+import { isContainerLevel, isWorkItem, isRootLevel, getLevelLabel, } from "../schema/index.js";
+import { walkTree } from "./tree.js";
+const DEFAULT_STALE_MS = 48 * 60 * 60 * 1000; // 48 hours
+/** Weights for each dimension in the overall score. */
+const WEIGHTS = {
+    depth: 0.15,
+    balance: 0.20,
+    granularity: 0.20,
+    completeness: 0.25,
+    staleness: 0.20,
+};
+// ── Main entry point ─────────────────────────────────────────────────────────
+/**
+ * Compute the structure health score for a PRD tree.
+ */
+export function computeHealthScore(items, options) {
+    const now = options?.now ?? Date.now();
+    const staleMs = options?.staleThresholdMs ?? DEFAULT_STALE_MS;
+    // Collect live items
+    const liveItems = [];
+    for (const { item } of walkTree(items)) {
+        if (item.status !== "deleted")
+            liveItems.push(item);
+    }
+    if (liveItems.length === 0) {
+        return {
+            overall: 100,
+            dimensions: { depth: 100, balance: 100, granularity: 100, completeness: 100, staleness: 100 },
+            suggestions: [],
+        };
+    }
+    const dimensions = {
+        depth: scoreDepth(items),
+        balance: scoreBalance(items),
+        granularity: scoreGranularity(liveItems),
+        completeness: scoreCompleteness(liveItems),
+        staleness: scoreStaleness(liveItems, now, staleMs),
+    };
+    // Weighted overall
+    let overall = 0;
+    for (const [dim, weight] of Object.entries(WEIGHTS)) {
+        overall += dimensions[dim] * weight;
+    }
+    overall = Math.round(overall);
+    // Generate suggestions for weak dimensions
+    const suggestions = generateSuggestions(dimensions, items, liveItems, now, staleMs);
+    return { overall, dimensions, suggestions };
+}
+// ── Dimension scorers ────────────────────────────────────────────────────────
+/**
+ * Score depth placement: are items at valid depths per the hierarchy?
+ * Penalizes root-level features, deep nesting anomalies, etc.
+ */
+function scoreDepth(items) {
+    let total = 0;
+    let violations = 0;
+    for (const { item, parents } of walkTree(items)) {
+        if (item.status === "deleted")
+            continue;
+        total++;
+        const depth = parents.length;
+        // Root items should be root-level (epics)
+        if (depth === 0 && !isRootLevel(item.level)) {
+            violations++;
+        }
+        // Work items at root level is bad
+        if (depth === 0 && isWorkItem(item.level)) {
+            violations += 2; // Double penalty
+        }
+    }
+    if (total === 0)
+        return 100;
+    // Each violation reduces score proportionally
+    const ratio = violations / total;
+    return Math.round(Math.max(0, 100 - ratio * 200));
+}
+/**
+ * Score balance: are sibling containers roughly equal in size?
+ * Uses coefficient of variation (CV) of child counts.
+ */
+function scoreBalance(items) {
+    const cvValues = [];
+    // Check root-level balance
+    const rootContainers = items.filter((i) => isContainerLevel(i.level) && i.status !== "deleted");
+    if (rootContainers.length >= 2) {
+        const sizes = rootContainers.map((c) => countLiveChildren(c));
+        const cv = coefficientOfVariation(sizes);
+        if (cv !== null)
+            cvValues.push(cv);
+    }
+    // Check balance within each container
+    for (const { item } of walkTree(items)) {
+        if (!isContainerLevel(item.level))
+            continue;
+        if (item.status === "deleted")
+            continue;
+        const childContainers = (item.children ?? []).filter((c) => isContainerLevel(c.level) && c.status !== "deleted");
+        if (childContainers.length < 2)
+            continue;
+        const sizes = childContainers.map((c) => countLiveChildren(c));
+        const cv = coefficientOfVariation(sizes);
+        if (cv !== null)
+            cvValues.push(cv);
+    }
+    if (cvValues.length === 0)
+        return 100;
+    // Average CV across all container groups
+    const avgCv = cvValues.reduce((a, b) => a + b, 0) / cvValues.length;
+    // CV of 0 = perfect balance (score 100)
+    // CV of 1 = moderate imbalance (score ~50)
+    // CV of 2+ = severe imbalance (score ~0)
+    return Math.round(Math.max(0, 100 - avgCv * 50));
+}
+/**
+ * Score granularity: do work items have appropriate detail?
+ * Checks descriptions, acceptance criteria, and consistent sizing.
+ */
+function scoreGranularity(liveItems) {
+    const workItems = liveItems.filter((i) => isWorkItem(i.level));
+    if (workItems.length === 0)
+        return 100;
+    let score = 100;
+    // Penalize work items without descriptions
+    const noDesc = workItems.filter((i) => !i.description?.trim()).length;
+    score -= (noDesc / workItems.length) * 30;
+    // Penalize work items without acceptance criteria
+    const noCriteria = workItems.filter((i) => !i.acceptanceCriteria?.length).length;
+    score -= (noCriteria / workItems.length) * 20;
+    // Penalize very short titles (< 10 chars)
+    const shortTitles = workItems.filter((i) => i.title.length < 10).length;
+    score -= (shortTitles / workItems.length) * 15;
+    // Penalize containers with single-task features
+    const containers = liveItems.filter((i) => isContainerLevel(i.level));
+    const singleChild = containers.filter((i) => {
+        const live = (i.children ?? []).filter((c) => c.status !== "deleted");
+        return live.length === 1;
+    }).length;
+    if (containers.length > 0) {
+        score -= (singleChild / containers.length) * 15;
+    }
+    return Math.round(Math.max(0, score));
+}
+/**
+ * Score completeness: what fraction of items have substantive metadata?
+ */
+function scoreCompleteness(liveItems) {
+    if (liveItems.length === 0)
+        return 100;
+    let totalPoints = 0;
+    let earnedPoints = 0;
+    for (const item of liveItems) {
+        if (isWorkItem(item.level)) {
+            // Work items should have: description, acceptance criteria, priority
+            totalPoints += 3;
+            if (item.description?.trim())
+                earnedPoints++;
+            if (item.acceptanceCriteria?.length)
+                earnedPoints++;
+            if (item.priority)
+                earnedPoints++;
+        }
+        else if (isContainerLevel(item.level)) {
+            // Containers should have: description, children
+            totalPoints += 2;
+            if (item.description?.trim())
+                earnedPoints++;
+            const liveChildren = (item.children ?? []).filter((c) => c.status !== "deleted");
+            if (liveChildren.length > 0)
+                earnedPoints++;
+        }
+    }
+    if (totalPoints === 0)
+        return 100;
+    return Math.round((earnedPoints / totalPoints) * 100);
+}
+/**
+ * Score staleness: are there items that haven't progressed?
+ */
+function scoreStaleness(liveItems, now, staleMs) {
+    const activeItems = liveItems.filter((i) => i.status !== "completed" && i.status !== "deferred");
+    if (activeItems.length === 0)
+        return 100;
+    let staleCount = 0;
+    for (const item of activeItems) {
+        if (item.status === "in_progress" && item.startedAt) {
+            const elapsed = now - new Date(item.startedAt).getTime();
+            if (elapsed > staleMs)
+                staleCount++;
+        }
+        // Pending items don't have a createdAt timestamp, so we can't measure
+        // staleness by age. Instead, we rely on the structural validator for
+        // "blocked without blockedBy" checks. Pending items are not penalized here.
+        // Blocked items whose blockers are all completed
+        if (item.status === "blocked" && item.blockedBy?.length) {
+            // We can't check blocker status without the full tree, so skip this check
+            // It's handled by the structural validator instead
+        }
+    }
+    const ratio = staleCount / activeItems.length;
+    return Math.round(Math.max(0, 100 - ratio * 150));
+}
+function generateSuggestions(dimensions, items, liveItems, now, staleMs) {
+    const candidates = [];
+    // Depth suggestions
+    if (dimensions.depth < 80) {
+        const rootNonRoot = items.filter((i) => !isRootLevel(i.level) && i.status !== "deleted");
+        if (rootNonRoot.length > 0) {
+            candidates.push({
+                dimension: "depth",
+                score: dimensions.depth,
+                message: `${rootNonRoot.length} item${rootNonRoot.length === 1 ? "" : "s"} at root level should be moved under a parent ${getLevelLabel("epic").toLowerCase()}.`,
+            });
+        }
+    }
+    // Balance suggestions
+    if (dimensions.balance < 70) {
+        candidates.push({
+            dimension: "balance",
+            score: dimensions.balance,
+            message: "Container sizes are uneven. Consider splitting oversized containers or merging undersized ones.",
+        });
+    }
+    // Granularity suggestions
+    if (dimensions.granularity < 70) {
+        const workItems = liveItems.filter((i) => isWorkItem(i.level));
+        const noDesc = workItems.filter((i) => !i.description?.trim()).length;
+        if (noDesc > 0) {
+            candidates.push({
+                dimension: "granularity",
+                score: dimensions.granularity,
+                message: `${noDesc} work item${noDesc === 1 ? "" : "s"} missing descriptions. Add context to help implementers understand the intent.`,
+            });
+        }
+    }
+    // Completeness suggestions
+    if (dimensions.completeness < 70) {
+        const workItems = liveItems.filter((i) => isWorkItem(i.level));
+        const noCriteria = workItems.filter((i) => !i.acceptanceCriteria?.length).length;
+        if (noCriteria > 0) {
+            candidates.push({
+                dimension: "completeness",
+                score: dimensions.completeness,
+                message: `${noCriteria} work item${noCriteria === 1 ? "" : "s"} without acceptance criteria. Add verifiable criteria to ensure quality.`,
+            });
+        }
+    }
+    // Staleness suggestions
+    if (dimensions.staleness < 80) {
+        const staleInProgress = liveItems.filter((i) => {
+            if (i.status !== "in_progress" || !i.startedAt)
+                return false;
+            return (now - new Date(i.startedAt).getTime()) > staleMs;
+        });
+        if (staleInProgress.length > 0) {
+            candidates.push({
+                dimension: "staleness",
+                score: dimensions.staleness,
+                message: `${staleInProgress.length} item${staleInProgress.length === 1 ? "" : "s"} in progress for over 48 hours. Review and update or re-prioritize.`,
+            });
+        }
+    }
+    // Sort by score (worst first), take top 3
+    candidates.sort((a, b) => a.score - b.score);
+    return candidates.slice(0, 3).map((c) => c.message);
+}
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function countLiveChildren(item) {
+    return (item.children ?? []).filter((c) => c.status !== "deleted").length;
+}
+function coefficientOfVariation(values) {
+    if (values.length < 2)
+        return null;
+    const mean = values.reduce((a, b) => a + b, 0) / values.length;
+    if (mean === 0)
+        return null;
+    const variance = values.reduce((sum, v) => sum + (v - mean) ** 2, 0) / values.length;
+    return Math.sqrt(variance) / mean;
+}
+// ── Formatting ───────────────────────────────────────────────────────────────
+const DIM_LABELS = {
+    depth: "Depth",
+    balance: "Balance",
+    granularity: "Granularity",
+    completeness: "Completeness",
+    staleness: "Freshness",
+};
+function scoreBar(score) {
+    const filled = Math.round(score / 5);
+    const empty = 20 - filled;
+    return "█".repeat(filled) + "░".repeat(empty);
+}
+function scoreIcon(score) {
+    if (score >= 80)
+        return "🟢";
+    if (score >= 60)
+        return "🟡";
+    return "🔴";
+}
+/**
+ * Format a health score for human-readable display.
+ */
+export function formatHealthScore(health) {
+    const lines = [];
+    lines.push("Structure Health Score");
+    lines.push("─".repeat(50));
+    lines.push("");
+    lines.push(`  Overall: ${scoreIcon(health.overall)} ${health.overall}/100`);
+    lines.push("");
+    for (const [key, label] of Object.entries(DIM_LABELS)) {
+        const score = health.dimensions[key];
+        lines.push(`  ${label.padEnd(14)} ${scoreBar(score)} ${score}`);
+    }
+    if (health.suggestions.length > 0) {
+        lines.push("");
+        lines.push("Suggestions:");
+        for (const s of health.suggestions) {
+            lines.push(`  → ${s}`);
+        }
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=health.js.map

package/packages/rex/dist/core/health.js.map

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

package/packages/rex/dist/core/keywords.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Keyword extraction and matching utilities.
+ *
+ * Shared by the verify module (mapping acceptance criteria to test files)
+ * and the next-task module (keyword-based task matching/search).
+ *
+ * @module core/keywords
+ */
+/** Words to ignore when matching criteria to file names. */
+export declare const STOP_WORDS: Set<string>;
+/**
+ * Extract matching keywords from a text string.
+ * Returns lowercased, deduplicated tokens suitable for fuzzy matching.
+ */
+export declare function extractKeywords(text: string): string[];
+/**
+ * Score how well a target string matches a set of keywords.
+ * Returns 0 for no match, higher values for better matches.
+ */
+export declare function scoreMatch(target: string, keywords: string[]): number;

package/packages/rex/dist/core/keywords.js

@@ -0,0 +1,47 @@
+/**
+ * Keyword extraction and matching utilities.
+ *
+ * Shared by the verify module (mapping acceptance criteria to test files)
+ * and the next-task module (keyword-based task matching/search).
+ *
+ * @module core/keywords
+ */
+/** Words to ignore when matching criteria to file names. */
+export const STOP_WORDS = new Set([
+    "a", "an", "the", "is", "are", "was", "were", "be", "been", "being",
+    "have", "has", "had", "do", "does", "did", "will", "would", "shall",
+    "should", "may", "might", "must", "can", "could",
+    "and", "but", "or", "nor", "not", "no", "so", "if", "then",
+    "for", "in", "on", "at", "to", "of", "by", "with", "from",
+    "up", "out", "off", "over", "under", "into", "through",
+    "that", "this", "it", "its",
+    "test", "tests", "when", "each", "all", "any",
+]);
+/**
+ * Extract matching keywords from a text string.
+ * Returns lowercased, deduplicated tokens suitable for fuzzy matching.
+ */
+export function extractKeywords(text) {
+    const tokens = text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s\-_]/g, " ")
+        .split(/\s+/)
+        .filter((w) => w.length > 2 && !STOP_WORDS.has(w));
+    // Deduplicate while preserving order
+    return [...new Set(tokens)];
+}
+/**
+ * Score how well a target string matches a set of keywords.
+ * Returns 0 for no match, higher values for better matches.
+ */
+export function scoreMatch(target, keywords) {
+    const normalized = target.toLowerCase().replace(/[/\\]/g, " ").replace(/[.-]/g, " ");
+    let score = 0;
+    for (const keyword of keywords) {
+        if (normalized.includes(keyword)) {
+            score += 1;
+        }
+    }
+    return score;
+}
+//# sourceMappingURL=keywords.js.map

package/packages/rex/dist/core/keywords.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keywords.js","sourceRoot":"","sources":["../../src/core/keywords.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,4DAA4D;AAC5D,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC;IAChC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO;IACnE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO;IACnE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;IAChD,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM;IAC1D,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM;IACzD,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS;IACtD,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK;IAC3B,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK;CAC9C,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,MAAM,MAAM,GAAG,IAAI;SAChB,WAAW,EAAE;SACb,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC;SAC/B,KAAK,CAAC,KAAK,CAAC;SACZ,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAErD,qCAAqC;IACrC,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;AAC9B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,MAAc,EAAE,QAAkB;IAC3D,MAAM,UAAU,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACrF,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,UAAU,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YACjC,KAAK,IAAI,CAAC,CAAC;QACb,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/packages/rex/dist/core/merge.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Merge (consolidate) multiple PRD items into one.
+ *
+ * Use cases:
+ * - Cleaning up redundant tasks generated by `rex analyze`
+ * - Combining tasks that turned out to be the same work
+ * - Rolling up granular subtasks into a single task
+ *
+ * Rules:
+ * - All source items must be siblings (same parent and same level)
+ * - One source item is designated the "target" — it survives
+ * - The rest are "absorbed" — their data is merged into the target,
+ *   then they are removed from the tree
+ * - Children of absorbed items are reparented under the target
+ * - blockedBy references to absorbed items are rewritten to point to the target
+ *
+ * @module core/merge
+ */
+import type { PRDItem, ItemLevel } from "../schema/index.js";
+export interface MergeOptions {
+    /** New title for the merged item. If not provided, keeps the target's title. */
+    title?: string;
+    /** New description for the merged item. If not provided, combines all descriptions. */
+    description?: string;
+}
+export interface MergeValidation {
+    valid: boolean;
+    error?: string;
+}
+export interface MergePreview {
+    /** The item that will survive (with merged fields applied). */
+    target: {
+        id: string;
+        title: string;
+        description?: string;
+        acceptanceCriteria: string[];
+        tags: string[];
+        blockedBy: string[];
+        childCount: number;
+    };
+    /** Items that will be absorbed (removed). */
+    absorbed: Array<{
+        id: string;
+        title: string;
+        level: ItemLevel;
+        status: string;
+        childCount: number;
+    }>;
+    /** IDs whose blockedBy references will be rewritten. */
+    rewrittenDependencyCount: number;
+}
+export interface MergeResult {
+    /** The surviving merged item. */
+    targetId: string;
+    /** IDs of items that were absorbed (removed). */
+    absorbedIds: string[];
+    /** IDs of children that were reparented under the target. */
+    reparentedChildIds: string[];
+    /** Count of blockedBy references rewritten across the tree. */
+    rewrittenDependencyCount: number;
+}
+/**
+ * Validate that a merge operation is structurally valid.
+ *
+ * Requirements:
+ * 1. At least 2 source IDs
+ * 2. Target must be one of the source IDs
+ * 3. All source items must exist
+ * 4. All source items must be at the same level
+ * 5. All source items must share the same parent (siblings)
+ */
+export declare function validateMerge(items: PRDItem[], sourceIds: string[], targetId: string): MergeValidation;
+/**
+ * Build a preview of the merge result without modifying the tree.
+ *
+ * Call after validateMerge succeeds.
+ */
+export declare function previewMerge(items: PRDItem[], sourceIds: string[], targetId: string, options?: MergeOptions): MergePreview;
+/**
+ * Execute the merge: update the target, reparent children, rewrite
+ * dependencies, and remove absorbed items.
+ *
+ * Modifies the items array in place.
+ *
+ * Call after validateMerge succeeds.
+ */
+export declare function mergeItems(items: PRDItem[], sourceIds: string[], targetId: string, options?: MergeOptions): MergeResult;