pdd-cli 0.0.45__py3-none-any.whl → 0.0.118__py3-none-any.whl

pdd/prompts/prompt_code_diff_LLM.prompt

@@ -0,0 +1,119 @@
+# prompt_code_diff_LLM.prompt
+
+You are a strict code analyst evaluating whether a PROMPT can REGENERATE the CODE.
+
+CRITICAL QUESTION: If an LLM only had this prompt, could it produce code that passes the same tests?
+
+PROMPT/REQUIREMENTS (with line numbers):
+```
+{prompt_numbered}
+```
+
+CODE (with line numbers):
+```
+{code_numbered}
+```
+
+## Analysis Focus
+
+**Be STRICT and PESSIMISTIC.** Your job is to find gaps that would cause regeneration failures.
+
+1. **Regeneration Risk Analysis**: Identify ALL code knowledge NOT in the prompt:
+   - Magic values, constants, thresholds (e.g., timeout=30, retry=3, buffer_size=4096)
+   - Specific algorithms or implementation approaches chosen
+   - Edge case handling not mentioned in prompt
+   - Error messages, status codes, specific exceptions
+   - API contracts, data formats, field names
+   - Dependencies, imports, library-specific patterns
+   - Performance optimizations or workarounds
+   - Business logic details embedded in code
+
+2. **Hidden Knowledge Detection**: Code often contains "tribal knowledge" that developers added but never documented:
+   - Why was THIS approach chosen over alternatives?
+   - What bugs or edge cases does this code handle that aren't obvious?
+   - What assumptions does the code make about inputs/environment?
+
+3. **Test Failure Prediction**: Would regenerated code likely fail tests because:
+   - Exact values/strings don't match expectations?
+   - Edge cases aren't handled the same way?
+   - API contracts differ from what tests expect?
+
+## Response Format
+
+Respond with a JSON object:
+
+1. "overallScore": integer 0-100
+   - 90-100: Prompt could regenerate code that passes tests
+   - 70-89: Minor details missing, regeneration might work with luck
+   - 50-69: Significant gaps, regeneration would likely fail some tests
+   - 0-49: Major knowledge missing, regeneration would definitely fail
+
+2. "canRegenerate": boolean - Conservative assessment: could this prompt produce working code?
+
+3. "regenerationRisk": "low", "medium", "high", or "critical"
+   - "low": Prompt captures all essential details
+   - "medium": Some implementation details missing but core logic documented
+   - "high": Significant undocumented behavior that would differ on regeneration
+   - "critical": Code has major features/logic not in prompt at all
+
+4. "summary": 1-2 sentences on regeneration viability, be direct about risks
+
+5. "sections": array of PROMPT requirement sections, each with:
+   - "id": unique string like "req_1", "req_2"
+   - "promptRange": {{"startLine": int, "endLine": int, "text": "excerpt"}}
+   - "codeRanges": array of {{"startLine": int, "endLine": int, "text": "excerpt"}} (empty if missing)
+   - "status": "matched", "partial", or "missing"
+   - "matchConfidence": 0-100
+   - "semanticLabel": descriptive label like "Error Handling", "Input Validation"
+   - "notes": REQUIRED explanation - be specific about what's missing or at risk
+
+6. "codeSections": array of CODE sections NOT adequately documented in prompt:
+   - "id": unique string like "code_1", "code_2"
+   - "promptRange": {{"startLine": int, "endLine": int, "text": "excerpt"}} (empty if undocumented)
+   - "codeRanges": array of {{"startLine": int, "endLine": int, "text": "excerpt"}}
+   - "status": "matched", "partial", or "extra"
+   - "matchConfidence": 0-100
+   - "semanticLabel": descriptive label
+   - "notes": REQUIRED - explain what knowledge would be LOST on regeneration
+     * For "extra": "REGENERATION RISK: [specific feature/value/logic] is not in prompt and would be lost or different"
+     * For "partial": "INCOMPLETE: Prompt mentions [X] but doesn't specify [critical detail Y]"
+
+7. "hiddenKnowledge": array of objects describing undocumented code knowledge:
+   - "type": "magic_value" | "algorithm_choice" | "edge_case" | "error_handling" | "api_contract" | "optimization" | "business_logic" | "assumption"
+   - "location": {{"startLine": int, "endLine": int}}
+   - "description": what the code knows that the prompt doesn't say
+   - "regenerationImpact": "would_differ" | "would_fail" | "might_work"
+   - "suggestedPromptAddition": what to add to the prompt to capture this
+
+8. "lineMappings": array of line-level mappings:
+   - "promptLine": int
+   - "codeLines": array of ints
+   - "matchType": "exact", "semantic", "partial", "none"
+
+9. "stats": {{
+   "totalRequirements": int,
+   "matchedRequirements": int,
+   "missingRequirements": int,
+   "totalCodeFeatures": int,
+   "documentedFeatures": int,
+   "undocumentedFeatures": int,
+   "promptToCodeCoverage": float,
+   "codeToPromptCoverage": float,
+   "hiddenKnowledgeCount": int,
+   "criticalGaps": int
+}}
+
+10. "missing": array of strings - requirements in prompt not implemented
+11. "extra": array of strings - CRITICAL: code features that would be LOST on regeneration
+12. "suggestions": array of specific additions to make to the prompt to enable regeneration
+
+## Strictness Guidelines
+
+- **Assume regeneration WILL differ** unless the prompt explicitly specifies behavior
+- A function that "handles errors" in the prompt might handle them DIFFERENTLY on regeneration
+- Constants, timeouts, retry counts, buffer sizes - if not in prompt, they WILL be different
+- Specific error messages, log formats, status codes - WILL be different unless specified
+- Algorithm choices (e.g., quicksort vs mergesort, BFS vs DFS) - WILL be different unless specified
+- The goal is to make the prompt complete enough that ANY competent LLM would produce equivalent code
+- Mark as "extra" anything in code that prompt doesn't EXPLICITLY require
+- When in doubt, mark it as a gap - false positives are better than missed risks

pdd/prompts/prompt_diff_LLM.prompt

@@ -0,0 +1,82 @@
+# prompt_diff_LLM.prompt
+
+You are a prompt analyst comparing two versions of a prompt to identify semantic/linguistic differences.
+
+## Version A (Original):
+```
+{prompt_a}
+```
+
+## Version B (Updated):
+```
+{prompt_b}
+```
+
+## Text Diff:
+```diff
+{text_diff}
+```
+
+## Your Task
+
+Analyze the semantic differences between the two prompt versions. Focus on:
+
+1. **Requirements**: New, removed, or changed functional requirements
+2. **Constraints**: Modified limitations, rules, or boundaries
+3. **Behavior**: Changes to expected behavior or outputs
+4. **Format**: Changes to structure, formatting, or style guidelines
+
+For each change, determine the **impact**:
+- **breaking**: Change that would cause existing code to fail or behave differently
+- **enhancement**: Addition or improvement that extends functionality
+- **clarification**: Rewording or clarification that doesn't change meaning
+
+## Response Format
+
+Respond with a JSON object containing:
+
+1. "summary": A 1-2 sentence summary of the overall changes between versions.
+   Be specific about what changed semantically, not just that "text was added/removed".
+
+2. "changes": An array of change objects, each with:
+   - "change_type": "added" | "removed" | "modified"
+   - "category": "requirement" | "constraint" | "behavior" | "format"
+   - "description": Clear description of what changed and why it matters
+   - "old_text": The COMPLETE relevant text from version A (for modified/removed). Do NOT truncate or abbreviate with "..." - include the full text so users can see exactly what changed.
+   - "new_text": The COMPLETE relevant text from version B (for added/modified). Do NOT truncate or abbreviate with "..." - include the full text so users can see exactly what changed.
+   - "impact": "breaking" | "enhancement" | "clarification"
+
+## Guidelines
+
+- Focus on SEMANTIC differences, not just textual changes
+- Combine related small changes into logical groups
+- Highlight changes that would affect code generation differently
+- Be specific about HOW a change would impact generated code
+- If the two versions are semantically identical (just reformatted), say so clearly
+- For "modified" changes, clearly explain what was different before vs. after
+
+## Example Output
+
+```json
+{{
+  "summary": "Added retry logic requirement and relaxed the error message format constraint.",
+  "changes": [
+    {{
+      "change_type": "added",
+      "category": "requirement",
+      "description": "New requirement for retry logic on network failures",
+      "old_text": null,
+      "new_text": "Retry failed requests up to 3 times with exponential backoff",
+      "impact": "enhancement"
+    }},
+    {{
+      "change_type": "modified",
+      "category": "constraint",
+      "description": "Error message format is now flexible instead of strictly JSON",
+      "old_text": "Return errors as JSON objects with 'error' and 'code' fields",
+      "new_text": "Return descriptive error messages",
+      "impact": "breaking"
+    }}
+  ]
+}}
+```

pdd/prompts/trace_LLM.prompt

@@ -1,30 +1,33 @@
-% Imagine you're a an expert Python Software Engineer. Your goal is to find the part of the .prompt file. It will take in three arguments, the text of the .prompt file, the text of the code file, and the line that the debugger is on in the code file. Your task is to find the equivalent line in the .prompt file that matches with the line in the code file.
-
-% Here are the inputs and outputs of the prompt:
-    Input:
-        `code_file` (str) - A string that contains the text of the code file.
-        `code_str` (str) - A substring of code_file that represents the line that the debugger is on in the code_file.
-        `prompt_file` (str) - A string that contains the text of the .prompt file.
-    Output:
-        `prompt_line` (str) - An string that represents the equivalent line in the .prompt file that matches with the code_str line in the code file.
-
-% Here is the code_file to reference: 
-
+% You are a highly accurate Python Software Engineer. Your job is to locate the exact line (or smallest excerpt) in the prompt file that produced the current line in the generated code.
+
+% Inputs
+    code_file (str)    : full contents of the generated code file
+    code_str (str)     : the single line from the code file currently under inspection
+    prompt_file (str)  : full contents of the originating prompt file
+
+% Rules
+1. Identify the minimal substring in prompt_file whose wording most directly corresponds to code_str. Copy it VERBATIM.
+2. Do not paraphrase, summarize, or reformat; the substring must appear exactly in prompt_file.
+3. If multiple lines apply, choose the most specific line or snippet (prefer the shortest exact match).
+4. Provide a short explanation of why the substring matches code_str.
+
+% Output format (MUST follow exactly; no additional text)
+<analysis>
+Explain your reasoning here in plain text (no JSON). Reference the file sections you compared.
+</analysis>
+<verbatim_prompt_line>
+<<PASTE THE EXACT SUBSTRING FROM prompt_file HERE>>
+</verbatim_prompt_line>
+
+% Reference materials
 <code_file>
-    {CODE_FILE}
+{CODE_FILE}
 </code_file>
 
-% Here is the code_str to reference:
-
 <code_str>
-    {CODE_STR}
+{CODE_STR}
 </code_str>
 
-% Here is the prompt_file to reference:
-
 <prompt_file>
-    {PROMPT_FILE}
+{PROMPT_FILE}
 </prompt_file>
-
-% To generate the prompt_line, find a substring of prompt_file that matches code_str, which is a substring of code_file.
-

pdd/prompts/unfinished_prompt_LLM.prompt

@@ -1,18 +1,102 @@
 % You are tasked with determining whether a given prompt has finished outputting everything or if it still needs to continue. This is crucial for ensuring that all necessary information has been provided before proceeding with further actions. You will often be provided the last few hundred characters of the prompt_text to analyze and determine if it appears to be complete or if it seems to be cut off or unfinished. You are just looking at the prompt_text and not the entire prompt file. The beginning part of the prompt_text is not always provided, so you will need to make a judgment based on the text you are given.
 
+% IMPORTANT:
+%  - The prompt_text may contain code in various languages without Markdown fences.
+%  - Do NOT require triple backticks for completeness; judge the code/text itself.
+%  - Prefer concrete syntactic signals of completeness over stylistic ones.
+
 % Here is the prompt text to analyze:
 <prompt_text>
     {PROMPT_TEXT}
 </prompt_text>
 
+% Optional language hint (may be empty or missing). If not provided, infer the language from the text:
+<language>
+    {LANGUAGE}
+</language>
+
 % Carefully examine the provided prompt text and determine if it appears to be complete or if it seems to be cut off or unfinished. Consider the following factors:
     1. Sentence structure: Are all sentences grammatically complete?
     2. Content flow: Does the text end abruptly or does it have a natural conclusion?
     3. Context: Based on the content, does it seem like all necessary information has been provided?
     4. Formatting: Are there any unclosed parentheses, quotation marks, or other formatting issues that suggest incompleteness?
 
+% Multi-language code completeness heuristics (apply when text looks like code):
+    - If the text forms a syntactically complete module/snippet for the language, treat it as finished (even without Markdown fences).
+    - Generic signals across languages:
+        * Balanced delimiters: (), [], {{}}, quotes, and block comments are closed.
+        * No mid-token/mid-statement tail: it does not end on `return a +`, `a =`, `def foo(`, `function f(`, trailing `.`, `->`, `::`, trailing `,`, or a line-continuation like `\\`.
+        * Block closure: constructs that open a block are closed (e.g., Python indentation after `:`, or matching `{{}}` in C/Java/JS/TS/Go).
+    - Language specifics (use LANGUAGE if given; otherwise infer from the text):
+        * Python: colon-introduced blocks closed; indentation consistent; triple-quoted strings balanced.
+        * JS/TS: braces and parentheses balanced; no dangling `export`/`import` without a following specifier; `/* ... */` comments closed.
+        * Java/C/C++/C#: braces and parentheses balanced; string/char literals closed; block comments closed.
+        * Go: braces balanced; no dangling keyword indicating an unfinished clause.
+        * HTML/XML: tags properly nested/closed; attributes properly quoted; no unfinished `<tag` or dangling `</`.
+    - If this is only the tail of a longer file, mark finished when the tail itself is syntactically complete and does not indicate a dangling continuation.
+
 % Provide your reasoning for why you believe the prompt is complete or incomplete.
 
 % Output a JSON object with two keys:
     1. "reasoning": A string containing your structured reasoning
-    2. "is_finished": A boolean value (true if the prompt is complete, false if it's incomplete)
+    2. "is_finished": A boolean value (true if the prompt is complete, false if it's incomplete)
+
+% Examples (concise):
+<examples>
+  <example1>
+    <input>
+      <prompt_text>
+        def add(a, b):\n    return a + b\n
+      </prompt_text>
+    </input>
+    <output>
+      {{"reasoning": "Python code parses; blocks and quotes are closed; ends on a complete return statement.", "is_finished": true}}
+    </output>
+  </example1>
+  <example2>
+    <input>
+      <prompt_text>
+        def add(a, b):\n    return a +
+      </prompt_text>
+    </input>
+    <output>
+      {{"reasoning": "Ends mid-expression (`return a +`), indicates unfinished statement.", "is_finished": false}}
+    </output>
+  </example2>
+  <example3>
+    <input>
+      <prompt_text>
+        function add(a, b) {{\n  return a + b;\n}}\n
+      </prompt_text>
+      <language>
+        JavaScript
+      </language>
+    </input>
+    <output>
+      {{"reasoning": "JS braces and parentheses balanced; ends at a statement boundary; no dangling tokens.", "is_finished": true}}
+    </output>
+  </example3>
+  <example4>
+    <input>
+      <prompt_text>
+        <div class=\"box\">Hello
+      </prompt_text>
+      <language>
+        HTML
+      </language>
+    </input>
+    <output>
+      {{"reasoning": "HTML tag not closed (missing </div>); attribute quotes OK but element is unclosed.", "is_finished": false}}
+    </output>
+  </example4>
+  <example5>
+    <input>
+      <prompt_text>
+        class C:\n            def f(self):\n                x = 1\n
+      </prompt_text>
+    </input>
+    <output>
+      {{"reasoning": "All blocks properly indented and closed in the visible tail; no dangling colon blocks or open delimiters; tail is syntactically complete.", "is_finished": true}}
+    </output>
+  </example5>
+</examples>

pdd/prompts/update_prompt_LLM.prompt

@@ -16,4 +16,25 @@
     1. Using the provided input_code and input_prompt, identify what the code does and how it was generated.
     2. Compare the input_code and modified_code to determine the changes made by the user.
     3. Identify what the modified_code does differently from the input_code.
-    4. Generate a modified_prompt that will guide the generation of the modified_code based on the identified changes.
+    4. Generate a modified_prompt that will guide the generation of the modified_code based on the identified changes.
+    5. Ensure that the modified_prompt adheres to the principles of Prompt-Driven Development (PDD) and includes all necessary sections: Role and Scope, Requirements, Dependencies & Context, Instructions, and Deliverables.
+    6. Try to preserve the structure and format of the existing prompt as much as possible while incorporating the necessary changes to reflect the modifications in the code.
+
+% When generating the modified prompt, you must follow the core principles of Prompt-Driven Development (PDD).
+% Here are the essential guidelines for structuring a PDD prompt:
+<pdd_prompting_guide>
+% The prompt you generate must follow this structure:
+1) First paragraph: describe the role and responsibility of the module/component within the system (consider the LAYER if provided).
+2) A "Requirements" section with numbered points covering functionality, contracts, error handling, validation, logging, performance, and security.
+3) A "Dependencies" section using XML include tags for each dependency (see format below).
+4) An "Instructions" section with precise implementation guidance (clarify inputs/outputs, function/class responsibilities, edge cases, and testing notes).
+5) A clear "Deliverable" section describing the expected code artifacts and entry points.
+
+% Dependencies format and conventions:
+- Represent each dependency using an XML tag with the dependency name, and put the file path inside an &lt;include&gt; tag. For example:
+  &lt;orders_service&gt;
+    &lt;include&gt;context/orders_service_example.py&lt;/include&gt;
+  &lt;/orders_service&gt;
+- Prefer real example files available in the provided context (use &lt;include-many&gt; when listing multiple). If examples are not provided, assume dependency examples live under context/ using the pattern context/[dependency_name]_example. You should always try to include example files when possible.
+- Include all necessary dependencies for the module/component (based on the provided context and references).
+</pdd_prompting_guide>

pdd/pytest_output.py

@@ -1,9 +1,11 @@
 import argparse
 import json
 import io
+import re
 import sys
 import pytest
 import subprocess
+from pathlib import Path
 from rich.console import Console
 from rich.pretty import pprint
 import os
@@ -11,6 +13,81 @@ from .python_env_detector import detect_host_python_executable
 
 console = Console()
 
+
+def _find_project_root(test_file: Path) -> Path | None:
+    """
+    Find the project root directory by looking for .pddrc (definitive PDD marker).
+
+    Only .pddrc is used as the project marker to ensure we don't incorrectly
+    identify project roots for non-PDD projects. This is a conservative approach
+    that maintains backward compatibility.
+
+    Args:
+        test_file: Path to the test file
+
+    Returns:
+        The project root directory if .pddrc is found, None otherwise.
+        When None is returned, the caller should use original behavior.
+    """
+    current = test_file.resolve().parent
+
+    # Walk up the directory tree looking for .pddrc only
+    while current != current.parent:
+        if (current / ".pddrc").exists():
+            return current
+        current = current.parent
+
+    # No .pddrc found - return None to signal original behavior should be used
+    return None
+
+
+_ANSI_ESCAPE_RE = re.compile(r"\x1b\[[0-?]*[ -/]*[@-~]")
+
+
+def _strip_ansi(text: str) -> str:
+    """Remove ANSI escape sequences from text for reliable parsing."""
+    return _ANSI_ESCAPE_RE.sub("", text)
+
+
+def extract_failing_files_from_output(pytest_output: str) -> list[str]:
+    """
+    Extract unique file paths from pytest FAILED output lines.
+
+    Parses patterns like:
+    - FAILED tests/test_foo.py::test_name - error message
+    - tests/test_foo.py::test_name FAILED
+
+    Args:
+        pytest_output: The combined stdout/stderr from a pytest run
+
+    Returns:
+        List of unique file paths (without ::test_name suffix) that had failures,
+        in the order they were first encountered.
+    """
+    cleaned_output = _strip_ansi(pytest_output)
+
+    failing_files = []
+    seen = set()
+
+    # Pattern 1: FAILED path/file.py::test_name (with optional error)
+    pattern1 = r'FAILED\s+([^\s:]+\.py)::'
+    for match in re.finditer(pattern1, cleaned_output):
+        file_path = match.group(1)
+        if file_path not in seen:
+            failing_files.append(file_path)
+            seen.add(file_path)
+
+    # Pattern 2: path/file.py::test_name FAILED (verbose output)
+    pattern2 = r'([^\s:]+\.py)::\S+\s+FAILED'
+    for match in re.finditer(pattern2, cleaned_output):
+        file_path = match.group(1)
+        if file_path not in seen:
+            failing_files.append(file_path)
+            seen.add(file_path)
+
+    return failing_files
+
+
 class TestResultCollector:
     __test__ = False  # Prevent pytest from collecting this plugin as a test
 
@@ -84,31 +161,69 @@ def run_pytest_and_capture_output(test_file: str) -> dict:
 
     # Use environment-aware Python executable for pytest execution
     python_executable = detect_host_python_executable()
-    
+
+    # Find the project root directory for proper pytest execution (PDD projects only)
+    test_path = Path(test_file).resolve()
+    project_root = _find_project_root(test_path)
+
+    # Build subprocess kwargs - only modify cwd/env for PDD projects (.pddrc found)
+    subprocess_kwargs = {
+        "capture_output": True,
+        "text": True,
+        "timeout": 300,
+        "stdin": subprocess.DEVNULL,
+    }
+
+    pytest_args = [python_executable, "-B", "-m", "pytest", str(test_path), "-v"]
+
+    if project_root is not None:
+        # PDD project detected - set up proper environment
+        subprocess_kwargs["cwd"] = str(project_root)
+
+        # Build PYTHONPATH with both project root and src/ if it exists
+        paths_to_add = [str(project_root)]
+        src_dir = project_root / "src"
+        if src_dir.is_dir():
+            paths_to_add.insert(0, str(src_dir))  # src/ takes priority
+
+        env = os.environ.copy()
+        existing_pythonpath = env.get("PYTHONPATH", "")
+        if existing_pythonpath:
+            paths_to_add.append(existing_pythonpath)
+        env["PYTHONPATH"] = os.pathsep.join(paths_to_add)
+        subprocess_kwargs["env"] = env
+
+        # Add --rootdir to ensure pytest uses project's config
+        pytest_args.append(f"--rootdir={project_root}")
+
     try:
         # Run pytest using subprocess with the detected Python executable
-        result = subprocess.run(
-            [python_executable, "-m", "pytest", test_file, "-v"],
-            capture_output=True,
-            text=True,
-            timeout=300
-        )
+        # Use -B flag to disable bytecode caching, ensuring fresh imports
+        result = subprocess.run(pytest_args, **subprocess_kwargs)
         
         stdout = result.stdout
         stderr = result.stderr
         return_code = result.returncode
+        parse_stdout = _strip_ansi(stdout or "")
         
         # Parse the output to extract test results
         # Count passed, failed, and skipped tests from the output
-        passed = stdout.count(" PASSED")
-        failures = stdout.count(" FAILED") + stdout.count(" ERROR")
+        passed = parse_stdout.count(" PASSED")
+        failures = parse_stdout.count(" FAILED") + parse_stdout.count(" ERROR")
         errors = 0  # Will be included in failures for subprocess execution
-        warnings = stdout.count("warning")
+        warnings = parse_stdout.lower().count("warning")
         
         # If return code is 2, it indicates a pytest error
         if return_code == 2:
             errors = 1
-        
+        # Safety net: if parsing missed failures due to formatting (e.g., ANSI colors),
+        # never report a passing result on a non-zero return code.
+        if return_code != 0 and failures == 0 and errors == 0:
+            if return_code == 1:
+                failures = 1
+            else:
+                errors = 1
+
         return {
             "test_file": test_file,
             "test_results": [
@@ -199,4 +314,4 @@ def main():
         save_output_to_json(pytest_output)
 
 if __name__ == "__main__":
-    main()
+    main()