@n-dx/core 0.1.0

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

@@ -0,0 +1,176 @@
+/**
+ * Faceted classification for PRD items.
+ *
+ * Facets are stored as prefixed tags on items: `component:auth`, `concern:security`.
+ * This module provides helpers to read, write, and query facet values without
+ * requiring schema changes to PRDItem — facets piggyback on the existing `tags` array.
+ *
+ * @module rex/core/facets
+ */
+import { walkTree } from "./tree.js";
+/** Separator between facet key and value in a tag string. */
+const FACET_SEP = ":";
+// ── Tag-level helpers ────────────────────────────────────────────────────
+/** Check whether a tag string is a facet tag (contains exactly one `:`). */
+export function isFacetTag(tag) {
+    const idx = tag.indexOf(FACET_SEP);
+    return idx > 0 && idx < tag.length - 1 && tag.indexOf(FACET_SEP, idx + 1) === -1;
+}
+/** Parse a facet tag into key/value, or return null if not a facet. */
+export function parseFacetTag(tag) {
+    const idx = tag.indexOf(FACET_SEP);
+    if (idx <= 0 || idx >= tag.length - 1)
+        return null;
+    // Reject if there's a second colon (not a simple key:value facet)
+    if (tag.indexOf(FACET_SEP, idx + 1) !== -1)
+        return null;
+    return { key: tag.slice(0, idx), value: tag.slice(idx + 1) };
+}
+/** Build a facet tag string from key and value. */
+function buildFacetTag(key, value) {
+    return `${key}${FACET_SEP}${value}`;
+}
+// ── Item-level accessors ─────────────────────────────────────────────────
+/** Get the facet value for a given key on an item, or undefined if not set. */
+export function getFacetValue(item, key) {
+    if (!item.tags)
+        return undefined;
+    const prefix = key + FACET_SEP;
+    for (const tag of item.tags) {
+        if (tag.startsWith(prefix)) {
+            return tag.slice(prefix.length);
+        }
+    }
+    return undefined;
+}
+/**
+ * Set a facet value on an item (mutates `item.tags`).
+ * Replaces an existing value for the same key, or appends if new.
+ */
+export function setFacetValue(item, key, value) {
+    const newTag = buildFacetTag(key, value);
+    const prefix = key + FACET_SEP;
+    if (!item.tags) {
+        item.tags = [newTag];
+        return;
+    }
+    const idx = item.tags.findIndex((t) => t.startsWith(prefix));
+    if (idx >= 0) {
+        item.tags[idx] = newTag;
+    }
+    else {
+        item.tags.push(newTag);
+    }
+}
+/** Remove a facet key from an item (mutates `item.tags`). Returns true if removed. */
+export function removeFacet(item, key) {
+    if (!item.tags)
+        return false;
+    const prefix = key + FACET_SEP;
+    const before = item.tags.length;
+    item.tags = item.tags.filter((t) => !t.startsWith(prefix));
+    return item.tags.length < before;
+}
+/** Get all facets on an item as a key→value record. */
+export function getItemFacets(item) {
+    const result = {};
+    if (!item.tags)
+        return result;
+    for (const tag of item.tags) {
+        const parsed = parseFacetTag(tag);
+        if (parsed) {
+            result[parsed.key] = parsed.value;
+        }
+    }
+    return result;
+}
+// ── Collection-level queries ─────────────────────────────────────────────
+/** Find all items (flattened from tree) matching a facet key/value. */
+export function getItemsByFacet(items, key, value) {
+    const results = [];
+    const target = buildFacetTag(key, value);
+    for (const { item } of walkTree(items)) {
+        if (item.tags?.includes(target)) {
+            results.push(item);
+        }
+    }
+    return results;
+}
+/** Group all items (flattened) by the value of a facet key. Items without the facet are excluded. */
+export function groupByFacet(items, key) {
+    const groups = new Map();
+    const prefix = key + FACET_SEP;
+    for (const { item } of walkTree(items)) {
+        if (!item.tags)
+            continue;
+        for (const tag of item.tags) {
+            if (tag.startsWith(prefix)) {
+                const value = tag.slice(prefix.length);
+                const list = groups.get(value);
+                if (list) {
+                    list.push(item);
+                }
+                else {
+                    groups.set(value, [item]);
+                }
+                break; // one match per item per facet key
+            }
+        }
+    }
+    return groups;
+}
+/**
+ * Suggest facets for an item based on keyword matching and parent inheritance.
+ *
+ * Returns suggestions only — does not mutate the item.
+ */
+export function suggestFacets(item, facetConfig, parent) {
+    const suggestions = [];
+    const existing = getItemFacets(item);
+    const searchText = `${item.title} ${item.description ?? ""}`.toLowerCase();
+    for (const [key, config] of Object.entries(facetConfig)) {
+        // Skip if already set
+        if (existing[key])
+            continue;
+        // 1. Inherit from parent
+        if (parent) {
+            const parentValue = getFacetValue(parent, key);
+            if (parentValue && config.values.includes(parentValue)) {
+                suggestions.push({
+                    key,
+                    value: parentValue,
+                    reason: `inherited from parent "${parent.title}"`,
+                });
+                continue;
+            }
+        }
+        // 2. Keyword match against configured values
+        for (const value of config.values) {
+            if (searchText.includes(value.toLowerCase())) {
+                suggestions.push({
+                    key,
+                    value,
+                    reason: `keyword match in title/description`,
+                });
+                break;
+            }
+        }
+    }
+    return suggestions;
+}
+/**
+ * Compute facet distribution: for each configured facet, count items per value.
+ */
+export function computeFacetDistribution(items, facetConfig) {
+    const dist = {};
+    for (const key of Object.keys(facetConfig)) {
+        const counts = {};
+        const groups = groupByFacet(items, key);
+        for (const [value, group] of groups) {
+            counts[value] = group.length;
+        }
+        dist[key] = counts;
+    }
+    return dist;
+}
+//# sourceMappingURL=facets.js.map

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

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

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

@@ -0,0 +1,59 @@
+/**
+ * Auto-fix common PRD validation issues.
+ *
+ * Detects and repairs:
+ * 1. **Missing timestamps** — adds `startedAt` / `completedAt` based on status.
+ * 2. **Orphan blockedBy references** — clears IDs that don't exist in the tree.
+ * 3. **Parent-child status alignment** — resets completed parents whose
+ *    children are not all terminal.
+ *
+ * Each fix is reported individually so callers can preview (`--dry-run`)
+ * or log what changed.
+ *
+ * @module core/fix
+ */
+import type { PRDItem } from "../schema/index.js";
+export type FixKind = "missing_timestamp" | "orphan_blocked_by" | "parent_child_alignment";
+export interface FixAction {
+    /** Which category this fix belongs to. */
+    kind: FixKind;
+    /** The affected item ID. */
+    itemId: string;
+    /** Human-readable description of the fix. */
+    description: string;
+}
+export interface FixResult {
+    /** Actions that were (or would be) applied. */
+    actions: FixAction[];
+    /** Count of items mutated (0 in dry-run). */
+    mutatedCount: number;
+}
+/**
+ * Find items whose timestamps are inconsistent with their status:
+ * - `completed` without `completedAt`
+ * - `in_progress` or `completed` without `startedAt`
+ * - Non-completed with stale `completedAt`
+ */
+export declare function detectTimestampIssues(items: PRDItem[]): FixAction[];
+/**
+ * Find blockedBy references that point to IDs not present in the tree.
+ */
+export declare function detectOrphanBlockedBy(items: PRDItem[]): FixAction[];
+/**
+ * Find completed parents whose children are not all in terminal states.
+ * These parents should be reset to `in_progress`.
+ */
+export declare function detectParentChildMisalignment(items: PRDItem[]): FixAction[];
+/**
+ * Detect all fixable issues in a PRD tree.
+ * Pure function — does not mutate items.
+ */
+export declare function detectIssues(items: PRDItem[]): FixAction[];
+/**
+ * Apply all auto-fixes to a PRD tree.
+ * Mutates items in-place and returns a summary of what was done.
+ *
+ * @param items - The PRD items array (mutated in-place).
+ * @param now   - ISO timestamp to use for new timestamps (default: current time).
+ */
+export declare function applyFixes(items: PRDItem[], now?: string): FixResult;

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

@@ -0,0 +1,190 @@
+/**
+ * Auto-fix common PRD validation issues.
+ *
+ * Detects and repairs:
+ * 1. **Missing timestamps** — adds `startedAt` / `completedAt` based on status.
+ * 2. **Orphan blockedBy references** — clears IDs that don't exist in the tree.
+ * 3. **Parent-child status alignment** — resets completed parents whose
+ *    children are not all terminal.
+ *
+ * Each fix is reported individually so callers can preview (`--dry-run`)
+ * or log what changed.
+ *
+ * @module core/fix
+ */
+import { walkTree, collectAllIds } from "./tree.js";
+// ---------------------------------------------------------------------------
+// Detection helpers (pure — no mutations)
+// ---------------------------------------------------------------------------
+/**
+ * Find items whose timestamps are inconsistent with their status:
+ * - `completed` without `completedAt`
+ * - `in_progress` or `completed` without `startedAt`
+ * - Non-completed with stale `completedAt`
+ */
+export function detectTimestampIssues(items) {
+    const actions = [];
+    for (const { item } of walkTree(items)) {
+        if (item.status === "completed" && !item.completedAt) {
+            actions.push({
+                kind: "missing_timestamp",
+                itemId: item.id,
+                description: `Add completedAt to completed item "${item.title}"`,
+            });
+        }
+        if ((item.status === "in_progress" || item.status === "completed") &&
+            !item.startedAt) {
+            actions.push({
+                kind: "missing_timestamp",
+                itemId: item.id,
+                description: `Add startedAt to ${item.status} item "${item.title}"`,
+            });
+        }
+        if (item.status !== "completed" && item.completedAt) {
+            actions.push({
+                kind: "missing_timestamp",
+                itemId: item.id,
+                description: `Clear stale completedAt from ${item.status} item "${item.title}"`,
+            });
+        }
+    }
+    return actions;
+}
+/**
+ * Find blockedBy references that point to IDs not present in the tree.
+ */
+export function detectOrphanBlockedBy(items) {
+    const allIds = collectAllIds(items);
+    const actions = [];
+    for (const { item } of walkTree(items)) {
+        if (!item.blockedBy || item.blockedBy.length === 0)
+            continue;
+        const orphans = item.blockedBy.filter((ref) => !allIds.has(ref));
+        if (orphans.length > 0) {
+            actions.push({
+                kind: "orphan_blocked_by",
+                itemId: item.id,
+                description: `Remove ${orphans.length} orphan blockedBy ref${orphans.length > 1 ? "s" : ""} from "${item.title}": ${orphans.map((id) => id.slice(0, 8)).join(", ")}`,
+            });
+        }
+    }
+    return actions;
+}
+/**
+ * Find completed parents whose children are not all in terminal states.
+ * These parents should be reset to `in_progress`.
+ */
+export function detectParentChildMisalignment(items) {
+    const terminalStatuses = new Set(["completed", "deferred", "deleted"]);
+    const actions = [];
+    for (const { item } of walkTree(items)) {
+        if (item.status !== "completed")
+            continue;
+        if (!item.children || item.children.length === 0)
+            continue;
+        const nonTerminal = item.children.filter((c) => !terminalStatuses.has(c.status));
+        if (nonTerminal.length > 0) {
+            actions.push({
+                kind: "parent_child_alignment",
+                itemId: item.id,
+                description: `Reset completed parent "${item.title}" to in_progress (${nonTerminal.length} non-terminal child${nonTerminal.length > 1 ? "ren" : ""})`,
+            });
+        }
+    }
+    return actions;
+}
+// ---------------------------------------------------------------------------
+// Mutation helpers
+// ---------------------------------------------------------------------------
+function applyTimestampFixes(items, now) {
+    let count = 0;
+    for (const { item } of walkTree(items)) {
+        if (item.status === "completed" && !item.completedAt) {
+            item.completedAt = now;
+            count++;
+        }
+        if ((item.status === "in_progress" || item.status === "completed") &&
+            !item.startedAt) {
+            item.startedAt = now;
+            count++;
+        }
+        if (item.status !== "completed" && item.completedAt) {
+            delete item.completedAt;
+            count++;
+        }
+    }
+    return count;
+}
+function applyOrphanBlockedByFixes(items) {
+    const allIds = collectAllIds(items);
+    let count = 0;
+    for (const { item } of walkTree(items)) {
+        if (!item.blockedBy || item.blockedBy.length === 0)
+            continue;
+        const before = item.blockedBy.length;
+        item.blockedBy = item.blockedBy.filter((ref) => allIds.has(ref));
+        if (item.blockedBy.length < before) {
+            count++;
+        }
+        if (item.blockedBy.length === 0) {
+            delete item.blockedBy;
+        }
+    }
+    return count;
+}
+function applyParentChildFixes(items, now) {
+    const terminalStatuses = new Set(["completed", "deferred", "deleted"]);
+    let count = 0;
+    for (const { item } of walkTree(items)) {
+        if (item.status !== "completed")
+            continue;
+        if (!item.children || item.children.length === 0)
+            continue;
+        const nonTerminal = item.children.filter((c) => !terminalStatuses.has(c.status));
+        if (nonTerminal.length > 0) {
+            item.status = "in_progress";
+            if (!item.startedAt) {
+                item.startedAt = now;
+            }
+            delete item.completedAt;
+            count++;
+        }
+    }
+    return count;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Detect all fixable issues in a PRD tree.
+ * Pure function — does not mutate items.
+ */
+export function detectIssues(items) {
+    return [
+        ...detectTimestampIssues(items),
+        ...detectOrphanBlockedBy(items),
+        ...detectParentChildMisalignment(items),
+    ];
+}
+/**
+ * Apply all auto-fixes to a PRD tree.
+ * Mutates items in-place and returns a summary of what was done.
+ *
+ * @param items - The PRD items array (mutated in-place).
+ * @param now   - ISO timestamp to use for new timestamps (default: current time).
+ */
+export function applyFixes(items, now) {
+    const actions = detectIssues(items);
+    if (actions.length === 0) {
+        return { actions, mutatedCount: 0 };
+    }
+    const timestamp = now ?? new Date().toISOString();
+    const tsCount = applyTimestampFixes(items, timestamp);
+    const orphanCount = applyOrphanBlockedByFixes(items);
+    const parentCount = applyParentChildFixes(items, timestamp);
+    return {
+        actions,
+        mutatedCount: tsCount + orphanCount + parentCount,
+    };
+}
+//# sourceMappingURL=fix.js.map

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

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

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

@@ -0,0 +1,43 @@
+/**
+ * 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 type { PRDItem } from "../schema/index.js";
+export interface HealthDimensions {
+    /** Are items placed at appropriate depths? (0-100) */
+    depth: number;
+    /** Are containers roughly equal size? (0-100) */
+    balance: number;
+    /** Are leaf items similar scope (have descriptions/criteria)? (0-100) */
+    granularity: number;
+    /** What % of items have descriptions/criteria? (0-100) */
+    completeness: number;
+    /** Are there stale or stuck items? (0-100) */
+    staleness: number;
+}
+export interface StructureHealthScore {
+    /** Composite score 0-100. */
+    overall: number;
+    dimensions: HealthDimensions;
+    /** Top improvement suggestions, most impactful first. */
+    suggestions: string[];
+}
+export interface HealthOptions {
+    /** Override "now" for testing. Default: Date.now(). */
+    now?: number;
+    /** Threshold in ms before an in_progress task is considered stale. Default: 48 hours. */
+    staleThresholdMs?: number;
+}
+/**
+ * Compute the structure health score for a PRD tree.
+ */
+export declare function computeHealthScore(items: PRDItem[], options?: HealthOptions): StructureHealthScore;
+/**
+ * Format a health score for human-readable display.
+ */
+export declare function formatHealthScore(health: StructureHealthScore): string;