@n-dx/core 0.1.0

package/packages/rex/dist/analyze/reason.d.ts

@@ -0,0 +1,277 @@
+import type { PRDItem, AnalyzeTokenUsage } from "../schema/index.js";
+import type { ScanResult } from "./scanners.js";
+import type { Proposal } from "./propose.js";
+export { DEFAULT_MODEL, DEFAULT_CODEX_MODEL, MAX_RETRIES, parseTokenUsage, emptyAnalyzeTokenUsage, accumulateTokenUsage, detectFileFormat, extractJson, repairTruncatedJson, PRD_SCHEMA, TASK_QUALITY_RULES, OUTPUT_INSTRUCTION, } from "./analyze-shared.js";
+export type { ClaudeResult, FileFormat } from "./analyze-shared.js";
+export { setLLMConfig, setClaudeConfig, setClaudeClient, getAuthMode, getLLMVendor, spawnClaude, } from "./llm-bridge.js";
+import type { FileFormat } from "./analyze-shared.js";
+/**
+ * Read project documentation files from `dir`. Returns a trimmed string
+ * suitable for inclusion in an LLM prompt, or an empty string if nothing
+ * useful is found.
+ */
+export declare function readProjectContext(dir: string): Promise<string>;
+export declare function parseProposalResponse(raw: string): Proposal[];
+export interface QualityIssue {
+    level: "warning" | "error";
+    path: string;
+    message: string;
+}
+/**
+ * Validate semantic quality of LLM-generated proposals.
+ * Returns issues found. Empty array means all quality checks passed.
+ */
+export declare function validateProposalQuality(proposals: Proposal[]): QualityIssue[];
+/**
+ * Attempt to parse structured file content (JSON/YAML) directly into proposals
+ * without an LLM call. Returns null if the format is markdown or if the content
+ * cannot be meaningfully extracted.
+ */
+export declare function parseStructuredFile(content: string, format: FileFormat, existingItems: PRDItem[]): Proposal[] | null;
+export declare const ANTI_PATTERNS = "Avoid these common mistakes:\n- Do NOT produce tasks with only a title and no description or criteria \u2014 every task needs substance.\n- Do NOT use vague titles like \"Implement the feature\", \"Fix the bug\", \"Update code\" \u2014 be specific about WHAT is being implemented/fixed/updated.\n- Do NOT create single-task features \u2014 if a feature has only one task, either break the task down or merge it into a related feature.\n- Do NOT duplicate tasks already in the existing PRD (check the summary below).\n- Do NOT wrap your response in markdown fences \u2014 return raw JSON only.";
+/**
+ * Auto-placement instruction block. Included in prompts when no explicit
+ * parentId is specified, telling the LLM it can reference existing PRD
+ * items by ID to place new items under them.
+ */
+export declare const AUTO_PLACEMENT_INSTRUCTION = "\n## Placement\nThe existing PRD includes item IDs for epics and features. When new items\nnaturally belong under an existing epic or feature, set \"existingId\" on the\nepic/feature object to reference it by ID. Only create new epics/features\nwhen the items genuinely represent new work areas not covered by the existing tree.\n\nIf an existing parent's title needs to expand to accommodate the new scope,\nuse \"existingId\" to reference it AND set the title to the updated version.";
+/**
+ * Consolidation instruction block. Guides the LLM toward producing fewer,
+ * larger work packages rather than many micro-tasks. Included in prompts
+ * that process broad input (scan results, natural-language descriptions)
+ * to produce sprint-sized proposals.
+ */
+export declare const CONSOLIDATION_INSTRUCTION = "\n## Consolidation\nPrefer consolidated, sprint-sized work packages over many small tasks.\nFor broad input covering multiple areas, aim for 3\u20137 top-level proposals\n(epics) rather than 10+ micro-items. Each task should represent a\nmeaningful deliverable \u2014 not a single function or file change.\n\nGuidelines:\n- Merge related scan findings into a single task when they address the\n  same concern (e.g. \"add input validation\" across multiple routes \u2192\n  one task covering the validation pattern).\n- Prefer one well-scoped task with clear acceptance criteria over three\n  trivially small tasks that would be completed together anyway.\n- If a broad description covers an entire feature area, create 1\u20132\n  features with 2\u20135 tasks each, not a flat list of 15 micro-tasks.\n- Each task should still be completable in a single focused sprint\n  (roughly 0.5\u20134 engineer-weeks), not so large it becomes vague.";
+/**
+ * A compact example included in prompts to show the LLM the expected output
+ * shape, quality of titles, and level of detail for tasks.
+ */
+export declare const FEW_SHOT_EXAMPLE = "Example output (for reference \u2014 do NOT include this example in your response):\n[\n  {\n    \"epic\": { \"title\": \"User Authentication\" },\n    \"features\": [\n      {\n        \"title\": \"OAuth2 Integration\",\n        \"description\": \"Support third-party OAuth2 providers for user login\",\n        \"tasks\": [\n          {\n            \"title\": \"Implement OAuth2 callback handler\",\n            \"description\": \"Handle the authorization code exchange and token storage after provider redirects back to our app. Covers Google and GitHub providers with a pluggable adapter pattern for future providers.\",\n            \"acceptanceCriteria\": [\n              \"Handles Google and GitHub OAuth2 flows end-to-end\",\n              \"Stores refresh token securely in encrypted session storage\",\n              \"Returns meaningful error on provider rejection\",\n              \"Provider adapter interface documented with at least one example\"\n            ],\n            \"priority\": \"high\",\n            \"tags\": [\"auth\", \"backend\"],\n            \"loe\": 2,\n            \"loeRationale\": \"Two providers with shared adapter pattern, plus token storage and error handling \u2014 bounded by well-documented OAuth2 spec.\",\n            \"loeConfidence\": \"high\"\n          }\n        ]\n      }\n    ]\n  },\n  {\n    \"epic\": { \"title\": \"API Infrastructure\", \"existingId\": \"abc-123\" },\n    \"features\": [\n      {\n        \"title\": \"Rate Limiting\",\n        \"description\": \"Protect API endpoints from abuse with configurable rate limits\",\n        \"tasks\": [\n          {\n            \"title\": \"Implement token bucket rate limiter middleware\",\n            \"description\": \"Add per-endpoint rate limiting using a token bucket algorithm with configurable burst and sustained rates\",\n            \"acceptanceCriteria\": [\n              \"Returns 429 with Retry-After header when limit exceeded\",\n              \"Configurable per-route limits via middleware options\",\n              \"Supports both IP-based and API-key-based limiting\"\n            ],\n            \"priority\": \"high\",\n            \"tags\": [\"api\", \"security\"],\n            \"loe\": 1.5,\n            \"loeRationale\": \"Standard middleware pattern with token bucket algorithm; main effort is the configuration surface and tests.\",\n            \"loeConfidence\": \"medium\"\n          }\n        ]\n      }\n    ]\n  }\n]";
+/**
+ * Character budget per LLM chunk. Keeps each prompt well within token limits
+ * while leaving room for the system instructions, existing PRD summary, and
+ * project context that surround the scan data.
+ */
+export declare const CHUNK_CHAR_LIMIT = 40000;
+/**
+ * Maximum number of scan results per LLM chunk. Even if results fit within
+ * the character budget, limiting item count improves LLM reasoning quality
+ * by keeping context manageable. Set to 100 as a sensible default.
+ */
+export declare const CHUNK_ITEM_LIMIT = 100;
+/**
+ * Render an array of ScanResults into the text block used inside LLM prompts.
+ */
+export declare function summarizeScanResults(results: ScanResult[]): string;
+/**
+ * Estimate the serialized character length of a single ScanResult without
+ * allocating intermediate strings or arrays. Uses arithmetic on the existing
+ * field lengths to match what `summarizeScanResults([r])` would produce.
+ *
+ * This avoids O(N) full serializations during chunking — a significant
+ * saving for large codebases with thousands of scan results.
+ */
+export declare function estimateItemSize(r: ScanResult): number;
+/**
+ * Sort scan results so related items are adjacent: first by source file,
+ * then by kind (epic → feature → task). This keeps context together within
+ * chunks so the LLM sees complete feature areas rather than interleaved
+ * fragments from different parts of the codebase.
+ *
+ * Returns a new array — does not mutate the input.
+ */
+export declare function groupScanResults(results: ScanResult[]): ScanResult[];
+/**
+ * Split scan results into chunks that respect both `CHUNK_CHAR_LIMIT` and
+ * `CHUNK_ITEM_LIMIT`. When all results fit in a single chunk, this returns
+ * a one-element array — no overhead.
+ *
+ * Chunking triggers when either:
+ * - The serialized summary would exceed the character limit, OR
+ * - The item count would exceed 100 items per chunk
+ *
+ * This dual constraint ensures both:
+ * - Token budget stays within LLM limits (character-based)
+ * - LLM reasoning quality stays high (item-count-based)
+ *
+ * Optimizations over naive chunking:
+ * - Uses `estimateItemSize()` for O(1) size calculation per item instead
+ *   of full serialization, reducing allocations for large result sets.
+ * - Groups related items by source file and kind so the LLM sees coherent
+ *   context per chunk rather than interleaved fragments.
+ */
+export declare function chunkScanResults(results: ScanResult[]): ScanResult[][];
+/** Result of a reason* function: proposals plus aggregated token usage. */
+export interface ReasonResult {
+    proposals: Proposal[];
+    tokenUsage: AnalyzeTokenUsage;
+}
+export declare function reasonFromFile(filePath: string, existingItems: PRDItem[], model?: string): Promise<ReasonResult>;
+/**
+ * Merge proposals that share the same epic title (case-insensitive).
+ * Features and tasks are concatenated; duplicates within features are
+ * removed by normalized title.
+ */
+export declare function mergeProposals(all: Proposal[]): Proposal[];
+/**
+ * Process multiple input files and combine results into a single proposal list.
+ * Each file is read and parsed independently, then proposals are merged by epic.
+ */
+export declare function reasonFromFiles(filePaths: string[], existingItems: PRDItem[], model?: string): Promise<ReasonResult>;
+export declare function reasonFromScanResults(results: ScanResult[], existingItems: PRDItem[], options?: {
+    model?: string;
+    dir?: string;
+}): Promise<ReasonResult>;
+export interface AddPromptOptions {
+    parentId?: string;
+}
+/**
+ * Build the LLM prompt for a natural-language add command.
+ * Exported separately so it can be tested without spawning claude.
+ */
+export declare function buildAddPrompt(description: string, existingItems: PRDItem[], dir: string, options?: AddPromptOptions): Promise<string>;
+/**
+ * Send a natural-language description to the LLM and get back structured proposals.
+ */
+export declare function reasonFromDescription(description: string, existingItems: PRDItem[], options?: {
+    model?: string;
+    dir?: string;
+    parentId?: string;
+}): Promise<ReasonResult>;
+/**
+ * Build the LLM prompt for multiple natural-language descriptions in a single
+ * add call. Each description is treated as a distinct idea; the LLM is
+ * instructed to produce a coherent, de-duplicated structure that covers them
+ * all.
+ */
+export declare function buildMultiAddPrompt(descriptions: string[], existingItems: PRDItem[], dir: string, options?: AddPromptOptions): Promise<string>;
+/**
+ * Send multiple natural-language descriptions to the LLM in a single call and
+ * get back a unified set of proposals.
+ */
+export declare function reasonFromDescriptions(descriptions: string[], existingItems: PRDItem[], options?: {
+    model?: string;
+    dir?: string;
+    parentId?: string;
+}): Promise<ReasonResult>;
+/**
+ * Build an LLM prompt to break down proposals into finer-grained tasks.
+ * Each task is split into smaller subtasks; features may be expanded.
+ * Pure function — no I/O.
+ */
+export declare function buildBreakdownPrompt(proposals: Proposal[]): string;
+/**
+ * Build an LLM prompt to consolidate proposals into coarser-grained tasks.
+ * Multiple fine-grained tasks are merged into broader ones.
+ * Pure function — no I/O.
+ */
+export declare function buildConsolidatePrompt(proposals: Proposal[]): string;
+/**
+ * Adjust the granularity of proposals by calling the LLM.
+ * - "break_down": splits tasks into finer-grained subtasks
+ * - "consolidate": merges tasks into coarser-grained units
+ */
+export declare function adjustGranularity(proposals: Proposal[], direction: "break_down" | "consolidate", model?: string): Promise<ReasonResult>;
+/** Assessment of a single proposal's task granularity. */
+export interface GranularityAssessment {
+    /** 0-based index of the assessed proposal. */
+    proposalIndex: number;
+    /** The epic title of the assessed proposal. */
+    epicTitle: string;
+    /** Overall verdict. */
+    recommendation: "break_down" | "consolidate" | "keep";
+    /** Human-readable reasoning for the recommendation. */
+    reasoning: string;
+    /** Specific issues found (e.g. "Task X is too broad"). */
+    issues: string[];
+}
+/** Result of assessing all proposals in a set. */
+export interface GranularityAssessmentResult {
+    assessments: GranularityAssessment[];
+    tokenUsage: AnalyzeTokenUsage;
+}
+/**
+ * Build an LLM prompt to assess the granularity of proposals.
+ * The LLM evaluates whether tasks are appropriately sized and suggests
+ * when they should be broken down or consolidated.
+ * Pure function — no I/O.
+ */
+export declare function buildAssessmentPrompt(proposals: Proposal[]): string;
+/**
+ * Parse the LLM's granularity assessment response.
+ * Validates against schema and enriches with epic titles from proposals.
+ */
+export declare function parseAssessmentResponse(raw: string, proposals: Proposal[]): GranularityAssessment[];
+/**
+ * Format a granularity assessment for human-readable display.
+ * Pure function — returns a multi-line string.
+ */
+export declare function formatAssessment(assessments: GranularityAssessment[]): string;
+/**
+ * Assess the granularity of proposals by calling the LLM.
+ * Returns assessments with recommendations and reasoning for each proposal.
+ */
+export declare function assessGranularity(proposals: Proposal[], model?: string): Promise<GranularityAssessmentResult>;
+/**
+ * Build an LLM prompt for structuring freeform brainstorming notes into PRD
+ * proposals. Distinct from `buildAddPrompt` (single description) and
+ * `reasonFromFile` (formal spec import via analyze): this prompt is tuned for
+ * rough, unstructured idea dumps.
+ */
+export declare function buildIdeasPrompt(content: string, existingItems: PRDItem[], dir: string, options?: AddPromptOptions): Promise<string>;
+/**
+ * Read one or more freeform idea files and structure them into proposals.
+ *
+ * For well-structured files (markdown with headings, JSON matching the Proposal
+ * schema, YAML with title/name fields), extraction is performed locally without
+ * an LLM call. Files that cannot be meaningfully extracted fall back to the LLM
+ * ideas pipeline.
+ *
+ * Unlike `reasonFromFile` / `reasonFromFiles` (used by `analyze --file` for
+ * formal spec import), the LLM fallback uses a prompt specifically tuned for
+ * rough brainstorming notes.
+ */
+export declare function reasonFromIdeasFile(filePaths: string[], existingItems: PRDItem[], options?: {
+    model?: string;
+    dir?: string;
+    parentId?: string;
+}): Promise<ReasonResult>;
+/**
+ * A single item in a batch import. Each item carries its own content and
+ * a format hint that determines how it is processed.
+ */
+export interface BatchImportItem {
+    /** Raw content — file body or free-form text. */
+    content: string;
+    /** Format hint: "text" and "markdown" go through the LLM ideas pipeline,
+     *  "json" is tried as structured parsing first and falls back to LLM. */
+    format: "text" | "markdown" | "json";
+    /** Human-readable origin label (e.g. file name). Purely informational. */
+    source?: string;
+}
+/** Result of a batch import — proposals plus per-item status. */
+export interface BatchImportResult {
+    /** Merged, deduplicated proposals across all items. */
+    proposals: Proposal[];
+    /** Per-item processing status (same order as input). */
+    itemResults: Array<{
+        source?: string;
+        proposalCount: number;
+        error?: string;
+    }>;
+    /** Aggregated token usage across all LLM calls. */
+    tokenUsage: AnalyzeTokenUsage;
+}
+/**
+ * Process multiple import items through the smart-add pipeline and return
+ * consolidated, deduplicated proposals.
+ *
+ * JSON items are attempted via direct schema parsing first (no LLM). Text
+ * and markdown items are batched into a single LLM call using the ideas
+ * prompt for efficiency.
+ */
+export declare function reasonFromBatch(items: BatchImportItem[], existingItems: PRDItem[], options?: {
+    model?: string;
+    dir?: string;
+    parentId?: string;
+}): Promise<BatchImportResult>;