@n-dx/core 0.1.0

package/packages/rex/dist/recommend/create-from-recommendations.js

@@ -0,0 +1,287 @@
+/**
+ * Atomic PRD item creation from selected recommendations.
+ *
+ * Replaces the previous inline accept loop in the recommend CLI command
+ * with a function that validates, creates, and persists items atomically.
+ * If any validation fails, no items are created (all-or-nothing).
+ *
+ * Uses the same validation pipeline as `cmdAdd`:
+ * - Level hierarchy validation for parent-child relationships
+ * - DAG integrity checks (no duplicate IDs, no orphan blockedBy refs)
+ * - Schema validation via store.saveDocument()
+ *
+ * @module recommend/create-from-recommendations
+ */
+import { randomUUID } from "node:crypto";
+import { LEVEL_HIERARCHY, CHILD_LEVEL, isLeafLevel, getLevelLabel } from "../schema/index.js";
+import { findItem, insertChild } from "../core/tree.js";
+import { validateDAG } from "../core/dag.js";
+import { detectRecommendationConflicts, } from "./conflict-detection.js";
+// ── Validation ───────────────────────────────────────────────────────
+/**
+ * Validate that an item can be placed under the given parent (or at root).
+ *
+ * When a parent is specified, validates the level hierarchy (mirrors cmdAdd).
+ * When no parent is specified, root placement is allowed for any level that
+ * has no strict parent-only constraint (subtasks). This is intentionally more
+ * permissive than cmdAdd for root items, matching the existing recommend
+ * behavior where features are created at root level from sourcevision findings.
+ */
+function validatePlacement(item, parentId, docItems, batchItems) {
+    const allowedParents = LEVEL_HIERARCHY[item.level];
+    if (!allowedParents) {
+        return `Unknown level "${item.level}" for item "${item.title}".`;
+    }
+    const allowedParentLevels = allowedParents.filter((p) => p !== null);
+    if (parentId) {
+        // Check both existing doc items and items being created in the same batch
+        const parentEntry = findItem(docItems, parentId);
+        const batchParent = batchItems?.get(parentId);
+        const parentLevel = parentEntry?.item.level ?? batchParent?.level;
+        if (!parentLevel) {
+            return `Parent "${parentId}" not found for item "${item.title}".`;
+        }
+        if (allowedParentLevels.length > 0 &&
+            !allowedParentLevels.includes(parentLevel)) {
+            const parentNames = allowedParentLevels.join(" or ");
+            return (`A ${item.level} must be a child of a ${parentNames}, ` +
+                `but "${parentId}" is a ${parentLevel}.`);
+        }
+    }
+    else {
+        // Root placement: only reject levels that strictly require a parent.
+        // Leaf levels (subtasks) always need a parent; other levels are allowed
+        // at root for recommendation workflows (e.g. features from sourcevision).
+        const canBeRoot = allowedParents.includes(null);
+        if (!canBeRoot && allowedParentLevels.length > 0) {
+            // Only block if this is a leaf-only level (e.g. subtask→task)
+            // Allow epics, features, and tasks at root for recommendation flexibility
+            const isStrictlyChildOnly = allowedParentLevels.length > 0 && isLeafLevel(item.level);
+            if (isStrictlyChildOnly) {
+                const parentNames = allowedParentLevels.map(getLevelLabel).join(" or ");
+                return `A ${getLevelLabel(item.level)} requires a parent (${parentNames}).`;
+            }
+        }
+    }
+    return null;
+}
+// ── Core creation ────────────────────────────────────────────────────
+/**
+ * Create PRD items from selected recommendations atomically.
+ *
+ * All items are validated upfront, then persisted in a single
+ * `saveDocument()` call. If any validation fails, no items are created.
+ *
+ * Follows the same patterns as `cmdAdd`:
+ * - Level hierarchy validation
+ * - DAG integrity checks
+ * - Schema validation (via saveDocument)
+ * - Execution log entries for each created item
+ *
+ * @param store - The PRD store to read from and write to.
+ * @param recommendations - Enriched recommendations to create items from.
+ * @param options - Optional creation options including conflict strategy.
+ * @returns Creation result with IDs and metadata of created items.
+ * @throws If validation fails for any item (atomic: zero items are created).
+ * @throws If conflict strategy is "error" and conflicts are detected.
+ */
+export async function createItemsFromRecommendations(store, recommendations, options) {
+    if (recommendations.length === 0) {
+        return { created: [] };
+    }
+    const strategy = options?.conflictStrategy ?? "force";
+    // 1. Load current document for validation and conflict detection
+    const doc = await store.loadDocument();
+    // 2. Run conflict detection when strategy is not "force"
+    let conflictReport;
+    let effectiveRecommendations = recommendations;
+    const skipped = [];
+    const updated = [];
+    const reparented = [];
+    if (strategy !== "force") {
+        conflictReport = detectRecommendationConflicts(recommendations, doc.items);
+        if (conflictReport.hasConflicts) {
+            if (strategy === "error") {
+                const messages = [];
+                for (const c of conflictReport.conflicts) {
+                    messages.push(`"${c.recommendationTitle}" conflicts with existing ${c.matchedItem.level} "${c.matchedItem.title}" (${c.reason}, ${Math.round(c.score * 100)}% match)`);
+                }
+                for (const d of conflictReport.intraBatchDuplicates) {
+                    messages.push(`Recommendations "${d.titleA}" and "${d.titleB}" are intra-batch duplicates (${Math.round(d.score * 100)}% match)`);
+                }
+                throw new Error(`Conflict detection found ${conflictReport.conflictingIndices.length} conflicting recommendation(s):\n${messages.join("\n")}`);
+            }
+            // strategy === "skip": split conflicts into update / reparent / skip
+            const reparentedRecs = [];
+            for (const idx of conflictReport.conflictingIndices) {
+                const rec = recommendations[idx];
+                const conflict = conflictReport.conflicts.find((c) => c.recommendationIndex === idx);
+                const intraDup = conflictReport.intraBatchDuplicates.find((d) => d.indexB === idx);
+                // Pending-item conflicts from same source: update in-place rather than
+                // skipping. Recommendation items are refreshed each run with updated
+                // findings — the existing pending item should reflect the latest data.
+                if (conflict &&
+                    conflict.matchedItem.status === "pending" &&
+                    rec.source) {
+                    const matched = findItem(doc.items, conflict.matchedItem.id);
+                    if (matched && matched.item.source === rec.source) {
+                        matched.item.description = rec.description;
+                        matched.item.priority = rec.priority;
+                        if (rec.meta)
+                            matched.item.recommendationMeta = rec.meta;
+                        updated.push({
+                            index: idx,
+                            title: rec.title,
+                            existingItemId: conflict.matchedItem.id,
+                        });
+                        continue;
+                    }
+                }
+                // Completed-item conflicts: reparent as child (if level allows demotion
+                // AND the matched item's level is a valid parent for the demoted level)
+                if (conflict && conflict.matchedItem.status === "completed") {
+                    const childLevel = CHILD_LEVEL[rec.level];
+                    const allowedParents = childLevel ? LEVEL_HIERARCHY[childLevel] : undefined;
+                    const parentLevelValid = allowedParents?.some((p) => p === conflict.matchedItem.level);
+                    if (childLevel && parentLevelValid) {
+                        reparented.push({
+                            index: idx,
+                            title: rec.title,
+                            originalLevel: rec.level,
+                            newLevel: childLevel,
+                            parentId: conflict.matchedItem.id,
+                            parentTitle: conflict.matchedItem.title,
+                        });
+                        reparentedRecs.push({
+                            ...rec,
+                            level: childLevel,
+                            parentId: conflict.matchedItem.id,
+                        });
+                        continue;
+                    }
+                    // subtask has no child level — fall through to skip
+                }
+                const reason = conflict
+                    ? `Conflicts with existing ${conflict.matchedItem.level} "${conflict.matchedItem.title}"`
+                    : intraDup
+                        ? `Duplicate of recommendation "${intraDup.titleA}"`
+                        : "Detected as conflicting";
+                skipped.push({ index: idx, title: rec.title, reason });
+            }
+            effectiveRecommendations = [
+                ...conflictReport.safeIndices.map((i) => recommendations[i]),
+                ...reparentedRecs,
+            ];
+            if (effectiveRecommendations.length === 0) {
+                // Even with no new items to create, we may have updated existing items
+                if (updated.length > 0) {
+                    await store.saveDocument(doc);
+                    for (const u of updated) {
+                        await store.appendLog({
+                            timestamp: new Date().toISOString(),
+                            event: "item_updated",
+                            itemId: u.existingItemId,
+                            detail: `Updated ${u.title} from recommendation refresh`,
+                        });
+                    }
+                }
+                const result = { created: [], skipped, conflictReport };
+                if (updated.length > 0)
+                    result.updated = updated;
+                if (reparented.length > 0)
+                    result.reparented = reparented;
+                return result;
+            }
+        }
+    }
+    // 3. Build PRDItems from effective recommendations
+    const pending = [];
+    for (const rec of effectiveRecommendations) {
+        const item = {
+            id: rec.id ?? randomUUID(),
+            title: rec.title,
+            status: "pending",
+            level: rec.level,
+            description: rec.description,
+            priority: rec.priority,
+            source: rec.source,
+        };
+        if (rec.tags && rec.tags.length > 0) {
+            item.tags = rec.tags;
+        }
+        // Preserve recommendation metadata for traceability
+        if (rec.meta) {
+            item.recommendationMeta = rec.meta;
+        }
+        pending.push({ item, parentId: rec.parentId });
+    }
+    // 4. Validate placement (level hierarchy) for each item
+    //    Build a map of batch items so intra-batch parent references resolve.
+    const batchItemMap = new Map();
+    for (const { item } of pending) {
+        batchItemMap.set(item.id, item);
+    }
+    const placementErrors = [];
+    for (const { item, parentId } of pending) {
+        const err = validatePlacement(item, parentId, doc.items, batchItemMap);
+        if (err)
+            placementErrors.push(err);
+    }
+    if (placementErrors.length > 0) {
+        throw new Error(`Placement validation failed:\n${placementErrors.join("\n")}`);
+    }
+    // 5. Add all items to the in-memory document
+    for (const { item, parentId } of pending) {
+        if (parentId) {
+            const inserted = insertChild(doc.items, parentId, item);
+            if (!inserted) {
+                throw new Error(`Failed to insert "${item.title}" under parent "${parentId}".`);
+            }
+        }
+        else {
+            doc.items.push(item);
+        }
+    }
+    // 6. Validate DAG integrity with all new items in place
+    const dagResult = validateDAG(doc.items);
+    if (!dagResult.valid) {
+        throw new Error(`DAG validation failed after adding recommendations: ${dagResult.errors.join("; ")}`);
+    }
+    // 7. Persist atomically — single write for all items
+    await store.saveDocument(doc);
+    // 8. Log creation and update events
+    const created = [];
+    for (const { item, parentId } of pending) {
+        await store.appendLog({
+            timestamp: new Date().toISOString(),
+            event: "item_added",
+            itemId: item.id,
+            detail: `Added ${item.level} from recommendation: ${item.title}`,
+        });
+        created.push({
+            id: item.id,
+            title: item.title,
+            level: item.level,
+            parentId,
+        });
+    }
+    for (const u of updated) {
+        await store.appendLog({
+            timestamp: new Date().toISOString(),
+            event: "item_updated",
+            itemId: u.existingItemId,
+            detail: `Updated ${u.title} from recommendation refresh`,
+        });
+    }
+    const result = { created };
+    if (skipped.length > 0)
+        result.skipped = skipped;
+    if (updated.length > 0)
+        result.updated = updated;
+    if (reparented.length > 0)
+        result.reparented = reparented;
+    if (conflictReport)
+        result.conflictReport = conflictReport;
+    return result;
+}
+//# sourceMappingURL=create-from-recommendations.js.map

package/packages/rex/dist/recommend/create-from-recommendations.js.map

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

package/packages/rex/dist/recommend/types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Shared types for the recommendation pipeline.
+ *
+ * Extracted from create-from-recommendations.ts to break the circular
+ * dependency between create-from-recommendations ↔ conflict-detection.
+ * Both modules import these types from here instead of from each other.
+ *
+ * @module recommend/types
+ */
+import type { ItemLevel, Priority } from "../schema/index.js";
+/**
+ * Metadata carried forward from the recommendation's source findings.
+ * Persisted on created PRDItems for traceability.
+ */
+export interface RecommendationMeta {
+    /** Content hashes of the source findings that produced this recommendation. */
+    findingHashes?: string[];
+    /** Category of the grouped findings (e.g. "auth", "perf", "security"). */
+    category?: string;
+    /** Distribution of finding severities in this recommendation group. */
+    severityDistribution?: Record<string, number>;
+    /** Total number of findings that contributed to this recommendation. */
+    findingCount?: number;
+}
+/**
+ * Enriched recommendation carrying all metadata needed for PRD item creation.
+ *
+ * This is the input type for {@link createItemsFromRecommendations}.
+ * Callers build these from whatever recommendation source they have
+ * (sourcevision findings, manual input, etc.).
+ */
+export interface EnrichedRecommendation {
+    /** Pre-assigned ID. When set, creation uses this instead of generating a new UUID. */
+    id?: string;
+    /** Title for the PRD item. */
+    title: string;
+    /** PRD hierarchy level (epic, feature, task, subtask). */
+    level: ItemLevel;
+    /** Description text for the PRD item. */
+    description: string;
+    /** Priority derived from finding severities. */
+    priority: Priority;
+    /** Source identifier (e.g. "sourcevision"). */
+    source: string;
+    /** Parent PRD item ID. When omitted, item is added at root level. */
+    parentId?: string;
+    /** Tags to apply to the created item. */
+    tags?: string[];
+    /** Recommendation metadata for traceability. */
+    meta?: RecommendationMeta;
+}
+/**
+ * How to handle conflicting recommendations during creation.
+ *
+ * - `"skip"` — silently skip conflicting items; create only non-conflicting ones.
+ * - `"force"` — ignore conflicts; create all items regardless.
+ * - `"error"` — throw if any conflicts are detected (default for backwards compat).
+ */
+export type ConflictStrategy = "skip" | "force" | "error";

package/packages/rex/dist/recommend/types.js

@@ -0,0 +1,11 @@
+/**
+ * Shared types for the recommendation pipeline.
+ *
+ * Extracted from create-from-recommendations.ts to break the circular
+ * dependency between create-from-recommendations ↔ conflict-detection.
+ * Both modules import these types from here instead of from each other.
+ *
+ * @module recommend/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/packages/rex/dist/recommend/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/recommend/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/packages/rex/dist/schema/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Schema barrel — re-exports types and constants from v1.ts.
+ *
+ * ⚠️ HIGH FAN-IN MODULE — imported by 40+ files across rex, hench, and web.
+ * Changes here have wide ripple effects. Treat this module's public surface
+ * as a stability contract:
+ *   - Adding exports is safe.
+ *   - Renaming or removing exports requires updating all consumers.
+ *   - Moving types between v1.ts and levels.ts is invisible to consumers
+ *     as long as this barrel continues to re-export them.
+ *
+ * Validation schemas (Zod) are intentionally NOT re-exported here.
+ * Import directly from `./validate.js` when validation is needed.
+ * This avoids forcing a transitive Zod dependency on every consumer
+ * that only needs type definitions and domain constants.
+ *
+ * @see ./v1.ts       — canonical type definitions and domain constants
+ * @see ./validate.ts — Zod schemas and validation functions (import directly)
+ */
+export { SCHEMA_VERSION, isCompatibleSchema, assertSchemaVersion, LEVEL_HIERARCHY, PRIORITY_ORDER, VALID_LEVELS, VALID_STATUSES, VALID_PRIORITIES, VALID_REQUIREMENT_CATEGORIES, VALID_VALIDATION_TYPES, CHILD_LEVEL, LOE_DEFAULTS, isPriority, isItemLevel, isItemStatus, isRequirementCategory, isValidationType, DEFAULT_CONFIG, } from "./v1.js";
+export type { ItemLevel, ItemStatus, Priority, ResolutionType, RequirementCategory, RequirementValidationType, Requirement, DuplicateOverrideMarker, MergedProposalRecord, PRDItem, PRDDocument, RexConfig, FacetDefinition, BudgetThresholds, LoEConfig, LogEntry, TokenUsage, AnalyzeTokenUsage, } from "./v1.js";
+export { isRootLevel, isWorkItem, isContainerLevel, isLeafLevel, isValidLevel, getLevelLabel, getLevelPlural, getLevelEmoji, getLevelDisplayMap, getChildLevel, getParentLevels, getAllLevels, getWorkItemLevels, getContainerLevels, formatLevelSummary, setLevelDisplay, resetLevelDisplay, } from "./levels.js";
+export type { LevelDisplay } from "./levels.js";

package/packages/rex/dist/schema/index.js

@@ -0,0 +1,22 @@
+/**
+ * Schema barrel — re-exports types and constants from v1.ts.
+ *
+ * ⚠️ HIGH FAN-IN MODULE — imported by 40+ files across rex, hench, and web.
+ * Changes here have wide ripple effects. Treat this module's public surface
+ * as a stability contract:
+ *   - Adding exports is safe.
+ *   - Renaming or removing exports requires updating all consumers.
+ *   - Moving types between v1.ts and levels.ts is invisible to consumers
+ *     as long as this barrel continues to re-export them.
+ *
+ * Validation schemas (Zod) are intentionally NOT re-exported here.
+ * Import directly from `./validate.js` when validation is needed.
+ * This avoids forcing a transitive Zod dependency on every consumer
+ * that only needs type definitions and domain constants.
+ *
+ * @see ./v1.ts       — canonical type definitions and domain constants
+ * @see ./validate.ts — Zod schemas and validation functions (import directly)
+ */
+export { SCHEMA_VERSION, isCompatibleSchema, assertSchemaVersion, LEVEL_HIERARCHY, PRIORITY_ORDER, VALID_LEVELS, VALID_STATUSES, VALID_PRIORITIES, VALID_REQUIREMENT_CATEGORIES, VALID_VALIDATION_TYPES, CHILD_LEVEL, LOE_DEFAULTS, isPriority, isItemLevel, isItemStatus, isRequirementCategory, isValidationType, DEFAULT_CONFIG, } from "./v1.js";
+export { isRootLevel, isWorkItem, isContainerLevel, isLeafLevel, isValidLevel, getLevelLabel, getLevelPlural, getLevelEmoji, getLevelDisplayMap, getChildLevel, getParentLevels, getAllLevels, getWorkItemLevels, getContainerLevels, formatLevelSummary, setLevelDisplay, resetLevelDisplay, } from "./levels.js";
+//# sourceMappingURL=index.js.map

package/packages/rex/dist/schema/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/schema/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,cAAc,EACd,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,4BAA4B,EAC5B,sBAAsB,EACtB,WAAW,EACX,YAAY,EACZ,UAAU,EACV,WAAW,EACX,YAAY,EACZ,qBAAqB,EACrB,gBAAgB,EAChB,cAAc,GACf,MAAM,SAAS,CAAC;AAuBjB,OAAO,EACL,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,aAAa,EACb,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,GAClB,MAAM,aAAa,CAAC"}

package/packages/rex/dist/schema/levels.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Level system — semantic helpers and configurable display.
+ *
+ * This module provides two things:
+ *
+ * 1. **Semantic helpers** that replace scattered `level === "epic"` /
+ *    `level === "task" || "subtask"` checks with meaningful functions
+ *    (`isRootLevel`, `isWorkItem`, etc.). These derive their answers
+ *    from `LEVEL_HIERARCHY` and `CHILD_LEVEL`, not from string matching.
+ *
+ * 2. **Display configuration** — labels, plurals, and emoji for each level,
+ *    consolidated into a single `LevelConfig`. The default config matches
+ *    current behavior (Epic/Feature/Task/Subtask); users can override
+ *    via `.n-dx.json` → `rex.levels`.
+ *
+ * @module rex/schema/levels
+ */
+import type { ItemLevel } from "./v1.js";
+export interface LevelDisplay {
+    /** Display label, e.g. "Epic" */
+    label: string;
+    /** Plural form, e.g. "Epics" */
+    labelPlural: string;
+    /** CLI/UI emoji */
+    emoji: string;
+}
+/** Replace the active display config (called on startup with user overrides). */
+export declare function setLevelDisplay(config: Record<string, LevelDisplay>): void;
+/** Reset to defaults (useful for tests). */
+export declare function resetLevelDisplay(): void;
+/**
+ * Can this level exist at the tree root (no parent)?
+ *
+ * Replaces: `level === "epic"`
+ */
+export declare function isRootLevel(level: string): boolean;
+/**
+ * Is this a work item (actionable leaf-level item)?
+ * Work items are levels that don't have container semantics — they
+ * represent actual units of work, not groupings.
+ *
+ * Replaces: `level === "task" || level === "subtask"`
+ */
+export declare function isWorkItem(level: string): boolean;
+/**
+ * Is this a container level (groups other items)?
+ *
+ * Replaces: `level === "epic" || level === "feature"`
+ */
+export declare function isContainerLevel(level: string): boolean;
+/**
+ * Is this the deepest possible level (cannot have children)?
+ *
+ * Replaces: `level === "subtask"` or `CHILD_LEVEL[level] === null`
+ */
+export declare function isLeafLevel(level: string): boolean;
+/**
+ * Is this a valid level string?
+ */
+export declare function isValidLevel(level: string): level is ItemLevel;
+/** Get the display label for a level. e.g. "epic" → "Epic" */
+export declare function getLevelLabel(level: string): string;
+/** Get the plural display label. e.g. "epic" → "Epics" */
+export declare function getLevelPlural(level: string): string;
+/** Get the emoji for a level. e.g. "epic" → "📦" */
+export declare function getLevelEmoji(level: string): string;
+/** Get all level display configs (for iteration). */
+export declare function getLevelDisplayMap(): Readonly<Record<string, LevelDisplay>>;
+/** Get the default child level. e.g. "epic" → "feature" */
+export declare function getChildLevel(level: string): ItemLevel | null;
+/** Get all valid parent levels (excluding null). e.g. "task" → ["feature", "epic"] */
+export declare function getParentLevels(level: string): ItemLevel[];
+/** Get all levels in hierarchy order (shallowest first). */
+export declare function getAllLevels(): ItemLevel[];
+/** Get all work-item levels. */
+export declare function getWorkItemLevels(): ItemLevel[];
+/** Get all container levels. */
+export declare function getContainerLevels(): ItemLevel[];
+/**
+ * Format a level summary string. e.g. { epic: 2, task: 3 } → "2 epics, 3 tasks"
+ */
+export declare function formatLevelSummary(byLevel: Record<string, number>): string;