@n-dx/core 0.1.0

package/packages/rex/dist/recommend/conflict-detection.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Conflict detection for recommendation → PRD creation.
+ *
+ * Detects duplicate or conflicting items before creating PRD entries
+ * from accepted recommendations. Two kinds of conflicts are identified:
+ *
+ * 1. **Existing-item conflicts** — a recommendation matches a PRD item
+ *    that already exists (by title similarity).
+ * 2. **Intra-batch conflicts** — two recommendations in the same accept
+ *    batch are duplicates of each other.
+ *
+ * Uses the same character-bigram similarity engine as the smart-add
+ * duplicate detection pipeline, ensuring consistent thresholds and
+ * scoring across all duplicate-detection paths.
+ *
+ * @module recommend/conflict-detection
+ */
+import type { PRDItem, ItemLevel, ItemStatus } from "../schema/index.js";
+import type { EnrichedRecommendation } from "./types.js";
+/** Similarity threshold for flagging a conflict with existing items. Matches smart-add. */
+export declare const CONFLICT_THRESHOLD = 0.7;
+/**
+ * Stricter threshold for intra-batch duplicate detection.
+ *
+ * Intra-batch recommendations often share template patterns
+ * (e.g. "Address X issues (N findings)") that inflate both title
+ * and content similarity without meaning the items are duplicates.
+ * A higher threshold avoids false positives from template-generated
+ * pairs while still catching genuine duplicates.
+ */
+export declare const INTRA_BATCH_THRESHOLD = 0.85;
+/** Why a conflict was detected. */
+export type ConflictReason = "exact_title" | "semantic_title" | "content_overlap";
+/** Reference to the existing PRD item that conflicts. */
+export interface ConflictMatchedItem {
+    id: string;
+    title: string;
+    level: ItemLevel;
+    status: ItemStatus;
+}
+/** A single conflict between a recommendation and an existing PRD item. */
+export interface RecommendationConflict {
+    /** Index of the recommendation in the input array. */
+    recommendationIndex: number;
+    /** Title of the conflicting recommendation. */
+    recommendationTitle: string;
+    /** The existing PRD item that was matched. */
+    matchedItem: ConflictMatchedItem;
+    /** Why the conflict was detected. */
+    reason: ConflictReason;
+    /** Similarity score (0–1). */
+    score: number;
+}
+/** An intra-batch duplicate pair. */
+export interface IntraBatchDuplicate {
+    /** Index of the first recommendation. */
+    indexA: number;
+    /** Index of the second recommendation. */
+    indexB: number;
+    /** Title of the first recommendation. */
+    titleA: string;
+    /** Title of the second recommendation. */
+    titleB: string;
+    /** Similarity score between the two. */
+    score: number;
+}
+/** Full conflict report for a batch of recommendations. */
+export interface ConflictReport {
+    /** Conflicts with existing PRD items. */
+    conflicts: RecommendationConflict[];
+    /** Duplicates within the batch itself. */
+    intraBatchDuplicates: IntraBatchDuplicate[];
+    /** Whether any conflicts were detected. */
+    hasConflicts: boolean;
+    /** Indices of conflict-free recommendations (safe to create). */
+    safeIndices: number[];
+    /** Indices of conflicting recommendations. */
+    conflictingIndices: number[];
+}
+/**
+ * Detect conflicts between recommendations and existing PRD items.
+ *
+ * Each recommendation is scored against every item in the PRD tree
+ * using the same similarity engine as smart-add duplicate detection.
+ * The best match (highest score) is kept per recommendation.
+ *
+ * Also detects intra-batch duplicates where two recommendations in
+ * the same batch would create near-identical PRD items.
+ *
+ * @param recommendations - The recommendations to check.
+ * @param existingItems - The current PRD item tree.
+ * @returns A conflict report with conflicts, safe indices, etc.
+ */
+export declare function detectRecommendationConflicts(recommendations: readonly EnrichedRecommendation[], existingItems: PRDItem[]): ConflictReport;
+/**
+ * Format a human-readable summary of a conflict for CLI output.
+ */
+export declare function formatConflict(conflict: RecommendationConflict): string;
+/**
+ * Format a human-readable summary of an intra-batch duplicate.
+ */
+export declare function formatIntraBatchDuplicate(dup: IntraBatchDuplicate): string;

package/packages/rex/dist/recommend/conflict-detection.js

@@ -0,0 +1,238 @@
+/**
+ * Conflict detection for recommendation → PRD creation.
+ *
+ * Detects duplicate or conflicting items before creating PRD entries
+ * from accepted recommendations. Two kinds of conflicts are identified:
+ *
+ * 1. **Existing-item conflicts** — a recommendation matches a PRD item
+ *    that already exists (by title similarity).
+ * 2. **Intra-batch conflicts** — two recommendations in the same accept
+ *    batch are duplicates of each other.
+ *
+ * Uses the same character-bigram similarity engine as the smart-add
+ * duplicate detection pipeline, ensuring consistent thresholds and
+ * scoring across all duplicate-detection paths.
+ *
+ * @module recommend/conflict-detection
+ */
+import { similarity } from "../analyze/dedupe.js";
+import { walkTree } from "../core/tree.js";
+// ── Constants ─────────────────────────────────────────────────────────
+/** Similarity threshold for flagging a conflict with existing items. Matches smart-add. */
+export const CONFLICT_THRESHOLD = 0.7;
+/**
+ * Stricter threshold for intra-batch duplicate detection.
+ *
+ * Intra-batch recommendations often share template patterns
+ * (e.g. "Address X issues (N findings)") that inflate both title
+ * and content similarity without meaning the items are duplicates.
+ * A higher threshold avoids false positives from template-generated
+ * pairs while still catching genuine duplicates.
+ */
+export const INTRA_BATCH_THRESHOLD = 0.85;
+// ── Helpers ───────────────────────────────────────────────────────────
+function normalize(text) {
+    return text.toLowerCase().trim().replace(/\s+/g, " ");
+}
+function titleContains(a, b) {
+    if (a.length < 5 || b.length < 5)
+        return false;
+    return a.includes(b) || b.includes(a);
+}
+function buildRecommendationContent(rec) {
+    return rec.description?.trim() ?? "";
+}
+function buildItemContent(item) {
+    const parts = [];
+    if (item.description)
+        parts.push(item.description);
+    if (item.acceptanceCriteria?.length)
+        parts.push(item.acceptanceCriteria.join(" "));
+    return parts.join(" ").trim();
+}
+/**
+ * Score a recommendation against a single existing PRD item.
+ * Returns null if the similarity is below the conflict threshold.
+ */
+function scoreRecommendationAgainstItem(rec, item) {
+    // Category-aware short-circuit: when both items carry recommendation
+    // metadata with a category (e.g. "observation", "suggestion", "anti-pattern"),
+    // different categories mean different work — skip the match entirely.
+    // Template-style titles like "Address X issues (N findings)" inflate
+    // similarity across categories without representing actual duplicates.
+    const recCategory = rec.meta?.category;
+    const itemCategory = item.recommendationMeta?.category;
+    if (recCategory && itemCategory && recCategory !== itemCategory) {
+        return null;
+    }
+    const recTitle = normalize(rec.title);
+    const itemTitle = normalize(item.title);
+    // Exact title match
+    if (recTitle === itemTitle) {
+        return { item, score: 1.0, reason: "exact_title" };
+    }
+    // Title containment
+    if (titleContains(recTitle, itemTitle)) {
+        return { item, score: 0.95, reason: "semantic_title" };
+    }
+    // Blended similarity (title + content)
+    const titleScore = similarity(rec.title, item.title);
+    const recContent = buildRecommendationContent(rec);
+    const itemContent = buildItemContent(item);
+    const contentScore = recContent.length > 0 && itemContent.length > 0
+        ? similarity(recContent, itemContent)
+        : 0;
+    const blended = Math.max(titleScore, titleScore * 0.75 + contentScore * 0.25, contentScore * 0.7);
+    const isConflict = blended >= CONFLICT_THRESHOLD ||
+        (titleScore >= 0.62 && contentScore >= 0.55);
+    if (!isConflict)
+        return null;
+    return {
+        item,
+        score: blended,
+        reason: contentScore > titleScore ? "content_overlap" : "semantic_title",
+    };
+}
+// ── Public API ────────────────────────────────────────────────────────
+/**
+ * Detect conflicts between recommendations and existing PRD items.
+ *
+ * Each recommendation is scored against every item in the PRD tree
+ * using the same similarity engine as smart-add duplicate detection.
+ * The best match (highest score) is kept per recommendation.
+ *
+ * Also detects intra-batch duplicates where two recommendations in
+ * the same batch would create near-identical PRD items.
+ *
+ * @param recommendations - The recommendations to check.
+ * @param existingItems - The current PRD item tree.
+ * @returns A conflict report with conflicts, safe indices, etc.
+ */
+export function detectRecommendationConflicts(recommendations, existingItems) {
+    const conflicts = [];
+    const conflictingSet = new Set();
+    // 1. Check each recommendation against existing PRD items.
+    //    Skip completed items — they represent finished work, and new
+    //    recommendations with similar titles represent new findings that
+    //    need separate attention (e.g. "Address observation issues (4 findings)"
+    //    is genuinely new work even if "(1 findings)" was already completed).
+    for (let i = 0; i < recommendations.length; i++) {
+        const rec = recommendations[i];
+        let best = null;
+        for (const { item } of walkTree(existingItems)) {
+            if (item.status === "completed")
+                continue;
+            const candidate = scoreRecommendationAgainstItem(rec, item);
+            if (!candidate)
+                continue;
+            if (!best || candidate.score > best.score) {
+                best = candidate;
+            }
+        }
+        if (best) {
+            conflicts.push({
+                recommendationIndex: i,
+                recommendationTitle: rec.title,
+                matchedItem: {
+                    id: best.item.id,
+                    title: best.item.title,
+                    level: best.item.level,
+                    status: best.item.status,
+                },
+                reason: best.reason,
+                score: best.score,
+            });
+            conflictingSet.add(i);
+        }
+    }
+    // 2. Detect intra-batch duplicates.
+    //
+    //    Intra-batch detection is deliberately stricter than existing-item
+    //    conflict detection because recommendations from the same source
+    //    often share template patterns (e.g. "Address X issues (N findings)")
+    //    that inflate title similarity without meaning the items are duplicates.
+    //
+    //    A pair is flagged only when:
+    //    - The exact normalized titles match (score >= 0.95), OR
+    //    - BOTH title AND content similarity independently exceed the threshold.
+    //
+    //    This avoids false positives from template-generated titles while still
+    //    catching genuine duplicates that share both title and description.
+    const intraBatchDuplicates = [];
+    for (let i = 0; i < recommendations.length; i++) {
+        for (let j = i + 1; j < recommendations.length; j++) {
+            const titleScore = similarity(recommendations[i].title, recommendations[j].title);
+            // Near-exact title match is always a duplicate
+            if (titleScore >= 0.95) {
+                intraBatchDuplicates.push({
+                    indexA: i,
+                    indexB: j,
+                    titleA: recommendations[i].title,
+                    titleB: recommendations[j].title,
+                    score: titleScore,
+                });
+                conflictingSet.add(j);
+                continue;
+            }
+            // For non-exact matches, require both title AND content to exceed
+            // the stricter intra-batch threshold to avoid template false positives
+            const contentA = buildRecommendationContent(recommendations[i]);
+            const contentB = buildRecommendationContent(recommendations[j]);
+            const contentScore = contentA.length > 0 && contentB.length > 0
+                ? similarity(contentA, contentB)
+                : 0;
+            if (titleScore >= INTRA_BATCH_THRESHOLD &&
+                contentScore >= INTRA_BATCH_THRESHOLD) {
+                const blended = Math.max(titleScore * 0.75 + contentScore * 0.25, contentScore * 0.7);
+                intraBatchDuplicates.push({
+                    indexA: i,
+                    indexB: j,
+                    titleA: recommendations[i].title,
+                    titleB: recommendations[j].title,
+                    score: blended,
+                });
+                conflictingSet.add(j);
+            }
+        }
+    }
+    // 3. Build safe indices (those not in any conflict)
+    const safeIndices = [];
+    for (let i = 0; i < recommendations.length; i++) {
+        if (!conflictingSet.has(i)) {
+            safeIndices.push(i);
+        }
+    }
+    return {
+        conflicts,
+        intraBatchDuplicates,
+        hasConflicts: conflictingSet.size > 0,
+        safeIndices,
+        conflictingIndices: [...conflictingSet].sort((a, b) => a - b),
+    };
+}
+/**
+ * Format a human-readable summary of a conflict for CLI output.
+ */
+export function formatConflict(conflict) {
+    const pct = Math.round(conflict.score * 100);
+    const statusNote = conflict.matchedItem.status === "completed"
+        ? " (completed)"
+        : conflict.matchedItem.status === "in_progress"
+            ? " (in progress)"
+            : "";
+    const reasonLabel = conflict.reason === "exact_title" ? "exact title match" :
+        conflict.reason === "semantic_title" ? "similar title" :
+            "overlapping content";
+    return (`"${conflict.recommendationTitle}" conflicts with existing ` +
+        `${conflict.matchedItem.level} "${conflict.matchedItem.title}"${statusNote} ` +
+        `(${reasonLabel}, ${pct}% similarity)`);
+}
+/**
+ * Format a human-readable summary of an intra-batch duplicate.
+ */
+export function formatIntraBatchDuplicate(dup) {
+    const pct = Math.round(dup.score * 100);
+    return (`Recommendations #${dup.indexA + 1} "${dup.titleA}" and ` +
+        `#${dup.indexB + 1} "${dup.titleB}" are duplicates (${pct}% similarity)`);
+}
+//# sourceMappingURL=conflict-detection.js.map

package/packages/rex/dist/recommend/conflict-detection.js.map

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

package/packages/rex/dist/recommend/create-from-recommendations.d.ts

@@ -0,0 +1,109 @@
+/**
+ * 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 type { PRDStore } from "../store/contracts.js";
+import type { ItemLevel } from "../schema/index.js";
+import type { ConflictReport } from "./conflict-detection.js";
+export type { EnrichedRecommendation, RecommendationMeta, ConflictStrategy, } from "./types.js";
+import type { EnrichedRecommendation, ConflictStrategy } from "./types.js";
+/**
+ * Options for {@link createItemsFromRecommendations}.
+ */
+export interface CreationOptions {
+    /**
+     * How to handle recommendations that conflict with existing PRD items
+     * or with each other. Defaults to `"force"` (no conflict checking)
+     * for backwards compatibility.
+     */
+    conflictStrategy?: ConflictStrategy;
+}
+/**
+ * A recommendation that was skipped due to a conflict.
+ */
+export interface SkippedRecommendation {
+    /** Index of the recommendation in the original input array. */
+    index: number;
+    /** Title of the skipped recommendation. */
+    title: string;
+    /** Reason the recommendation was skipped. */
+    reason: string;
+}
+/**
+ * A recommendation that updated an existing pending item in-place.
+ */
+export interface UpdatedRecommendation {
+    /** Index of the recommendation in the original input array. */
+    index: number;
+    /** Title of the recommendation. */
+    title: string;
+    /** ID of the existing item that was updated. */
+    existingItemId: string;
+}
+/**
+ * A recommendation that was reparented as a child of a completed item.
+ */
+export interface ReparentedRecommendation {
+    /** Index of the recommendation in the original input array. */
+    index: number;
+    /** Title of the recommendation. */
+    title: string;
+    /** Original level of the recommendation before demotion. */
+    originalLevel: ItemLevel;
+    /** New (demoted) level of the recommendation. */
+    newLevel: ItemLevel;
+    /** ID of the completed parent item. */
+    parentId: string;
+    /** Title of the completed parent item. */
+    parentTitle: string;
+}
+/**
+ * Result of a successful batch creation.
+ */
+export interface CreationResult {
+    /** Items that were created, in order. */
+    created: Array<{
+        id: string;
+        title: string;
+        level: ItemLevel;
+        parentId?: string;
+    }>;
+    /** Recommendations that were skipped due to conflicts (only with skip strategy). */
+    skipped?: SkippedRecommendation[];
+    /** Recommendations that updated existing pending items in-place. */
+    updated?: UpdatedRecommendation[];
+    /** Recommendations reparented as children of completed items. */
+    reparented?: ReparentedRecommendation[];
+    /** Full conflict report when conflict detection was run. */
+    conflictReport?: ConflictReport;
+}
+/**
+ * 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 declare function createItemsFromRecommendations(store: PRDStore, recommendations: readonly EnrichedRecommendation[], options?: CreationOptions): Promise<CreationResult>;