buildlog 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

buildlog/seed_engine/extractors.py

@@ -0,0 +1,148 @@
+"""Rule extractors for Step 2 of the seed engine pipeline.
+
+Extractors take sources and produce candidate rules.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Callable
+
+from buildlog.seed_engine.models import CandidateRule, Source
+
+
+class RuleExtractor(ABC):
+    """Protocol for extracting rules from sources.
+
+    Implementations:
+    - ManualExtractor: Human-curated rules (highest quality)
+    - LLMExtractor: LLM-assisted extraction (future)
+    - StructuredExtractor: Parse structured docs like OWASP (future)
+    """
+
+    @abstractmethod
+    def extract(self, source: Source) -> list[CandidateRule]:
+        """Extract candidate rules from a source.
+
+        Args:
+            source: The source to extract rules from.
+
+        Returns:
+            List of candidate rules with defensibility fields.
+        """
+        ...
+
+    @abstractmethod
+    def validate(self, rule: CandidateRule) -> list[str]:
+        """Validate a candidate rule, returning any issues.
+
+        Args:
+            rule: The rule to validate.
+
+        Returns:
+            List of validation issues (empty if valid).
+        """
+        ...
+
+
+class ManualExtractor(RuleExtractor):
+    """Manual rule extraction via human curation.
+
+    This is the gold standard—humans read the source and
+    extract rules with full defensibility metadata.
+
+    Usage:
+        extractor = ManualExtractor()
+
+        # Register rules for a source
+        extractor.register(
+            source=google_testing_blog,
+            rules=[
+                CandidateRule(
+                    rule="Tests must not depend on execution order",
+                    context="Test suites with multiple tests",
+                    antipattern="Test A sets state that Test B relies on",
+                    rationale="Order-dependent tests are flaky",
+                    source=google_testing_blog,
+                    raw_tags=["isolation", "flaky"],
+                )
+            ]
+        )
+
+        # Extract returns registered rules
+        rules = extractor.extract(google_testing_blog)
+    """
+
+    def __init__(self) -> None:
+        self._rules_by_source: dict[str, list[CandidateRule]] = {}
+
+    def register(self, source: Source, rules: list[CandidateRule]) -> None:
+        """Register manually curated rules for a source.
+
+        Args:
+            source: The source these rules come from.
+            rules: The curated rules.
+        """
+        # Validate all rules are complete
+        for rule in rules:
+            issues = self.validate(rule)
+            if issues:
+                raise ValueError(
+                    f"Invalid rule '{rule.rule[:50]}...': {'; '.join(issues)}"
+                )
+        self._rules_by_source[source.url] = rules
+
+    def extract(self, source: Source) -> list[CandidateRule]:
+        """Return registered rules for this source."""
+        return self._rules_by_source.get(source.url, [])
+
+    def validate(self, rule: CandidateRule) -> list[str]:
+        """Validate defensibility fields are populated."""
+        issues = []
+        if not rule.rule.strip():
+            issues.append("Rule text is empty")
+        if not rule.context.strip():
+            issues.append("Context is required for defensibility")
+        if not rule.antipattern.strip():
+            issues.append("Antipattern is required for defensibility")
+        if not rule.rationale.strip():
+            issues.append("Rationale is required for defensibility")
+        return issues
+
+
+class FunctionExtractor(RuleExtractor):
+    """Extraction via custom function (for structured sources).
+
+    Allows plugging in custom extraction logic for sources
+    with known structure (e.g., OWASP pages, API docs).
+
+    Usage:
+        def extract_from_owasp(source: Source) -> list[CandidateRule]:
+            # Custom parsing logic for OWASP format
+            ...
+
+        extractor = FunctionExtractor(extract_from_owasp)
+        rules = extractor.extract(owasp_source)
+    """
+
+    def __init__(
+        self,
+        extract_fn: Callable[[Source], list[CandidateRule]],
+        validate_fn: Callable[[CandidateRule], list[str]] | None = None,
+    ) -> None:
+        self._extract_fn = extract_fn
+        self._validate_fn = validate_fn or self._default_validate
+
+    def extract(self, source: Source) -> list[CandidateRule]:
+        """Run the custom extraction function."""
+        return self._extract_fn(source)
+
+    def validate(self, rule: CandidateRule) -> list[str]:
+        """Run the validation function."""
+        return self._validate_fn(rule)
+
+    def _default_validate(self, rule: CandidateRule) -> list[str]:
+        """Default validation: check completeness."""
+        if not rule.is_complete():
+            return ["Rule is missing required defensibility fields"]
+        return []

buildlog/seed_engine/generators.py

@@ -0,0 +1,144 @@
+"""Seed file generators for Step 4 of the seed engine pipeline.
+
+Generators take categorized rules and produce the final seed file.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from buildlog.seed_engine.models import CategorizedRule
+
+
+@dataclass
+class SeedGenerator:
+    """Generate YAML seed files from categorized rules.
+
+    Usage:
+        generator = SeedGenerator(
+            persona="test_terrorist",
+            version=1,
+            output_dir=Path(".buildlog/seeds"),
+        )
+
+        seed_file = generator.generate(categorized_rules)
+        generator.write(seed_file)
+    """
+
+    persona: str
+    version: int = 1
+    output_dir: Path | None = None
+    header_comment: str | None = None
+
+    def generate(self, rules: list[CategorizedRule]) -> dict[str, Any]:
+        """Generate seed file dictionary from categorized rules.
+
+        Args:
+            rules: The categorized rules to include.
+
+        Returns:
+            Seed file as dictionary (ready for YAML serialization).
+        """
+        # Validate all rules are complete
+        incomplete = [r for r in rules if not self._is_complete(r)]
+        if incomplete:
+            raise ValueError(
+                f"{len(incomplete)} rules are incomplete. "
+                f"First: '{incomplete[0].rule[:50]}...'"
+            )
+
+        return {
+            "persona": self.persona,
+            "version": self.version,
+            "rules": [r.to_seed_dict() for r in rules],
+        }
+
+    def write(
+        self,
+        seed_data: dict[str, Any],
+        path: Path | None = None,
+    ) -> Path:
+        """Write seed file to disk.
+
+        Args:
+            seed_data: The seed file dictionary.
+            path: Output path. If None, uses output_dir/persona.yaml.
+
+        Returns:
+            Path to written file.
+        """
+        if path is None:
+            if self.output_dir is None:
+                raise ValueError("No output path or output_dir specified")
+            self.output_dir.mkdir(parents=True, exist_ok=True)
+            path = self.output_dir / f"{self.persona}.yaml"
+
+        # Build YAML content with optional header
+        yaml_content = yaml.dump(
+            seed_data,
+            default_flow_style=False,
+            allow_unicode=True,
+            sort_keys=False,
+            width=100,
+        )
+
+        # Add header comment if provided
+        if self.header_comment:
+            lines = [f"# {line}" for line in self.header_comment.split("\n")]
+            header = "\n".join(lines) + "\n\n"
+            yaml_content = header + yaml_content
+
+        path.write_text(yaml_content)
+        return path
+
+    def _is_complete(self, rule: CategorizedRule) -> bool:
+        """Check if a rule has all required fields."""
+        return bool(
+            rule.rule.strip()
+            and rule.context.strip()
+            and rule.antipattern.strip()
+            and rule.rationale.strip()
+            and rule.category.strip()
+        )
+
+    def validate(self, seed_data: dict[str, Any]) -> list[str]:
+        """Validate seed file structure.
+
+        Args:
+            seed_data: The seed file dictionary.
+
+        Returns:
+            List of validation issues (empty if valid).
+        """
+        issues = []
+
+        if "persona" not in seed_data:
+            issues.append("Missing 'persona' field")
+        if "version" not in seed_data:
+            issues.append("Missing 'version' field")
+        if "rules" not in seed_data:
+            issues.append("Missing 'rules' field")
+            return issues
+
+        for i, rule in enumerate(seed_data.get("rules", [])):
+            prefix = f"Rule {i + 1}"
+            if not rule.get("rule"):
+                issues.append(f"{prefix}: Missing 'rule' text")
+            if not rule.get("context"):
+                issues.append(
+                    f"{prefix}: Missing 'context' (required for defensibility)"
+                )
+            if not rule.get("antipattern"):
+                issues.append(
+                    f"{prefix}: Missing 'antipattern' (required for defensibility)"
+                )
+            if not rule.get("rationale"):
+                issues.append(
+                    f"{prefix}: Missing 'rationale' (required for defensibility)"
+                )
+
+        return issues

buildlog/seed_engine/models.py

@@ -0,0 +1,113 @@
+"""Data models for the seed engine pipeline."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class SourceType(Enum):
+    """Type of authoritative source."""
+
+    REFERENCE_DOC = "reference_doc"  # OWASP, RFC, official docs
+    BLOG_POST = "blog_post"  # Google Testing Blog, Fowler
+    BOOK = "book"  # Clean Code, xUnit Patterns
+    STANDARD = "standard"  # ISO, IEEE standards
+    CHEATSHEET = "cheatsheet"  # OWASP cheatsheets
+
+
+@dataclass
+class Source:
+    """An authoritative source for rule extraction.
+
+    Step 1 output: Sources define where domain knowledge comes from.
+    Each source should be citable and defensible.
+    """
+
+    name: str
+    url: str
+    source_type: SourceType
+    domain: str  # e.g., "security", "testing", "code-quality"
+    description: str = ""
+    sections: list[str] = field(default_factory=list)  # Specific sections to extract
+
+    def to_reference(self) -> dict[str, str]:
+        """Convert to seed file reference format."""
+        return {"url": self.url, "title": self.name}
+
+
+@dataclass
+class CandidateRule:
+    """A rule extracted from a source, before categorization.
+
+    Step 2 output: Raw rule with all defensibility fields.
+    May not yet be categorized or tagged.
+    """
+
+    rule: str  # The prescription
+    context: str  # When it applies
+    antipattern: str  # What violation looks like
+    rationale: str  # Why it matters
+    source: Source  # Where it came from
+    raw_tags: list[str] = field(default_factory=list)  # Tags from extraction
+    confidence: float = 1.0  # Extraction confidence (1.0 for manual)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def is_complete(self) -> bool:
+        """Check if all defensibility fields are populated."""
+        return bool(
+            self.rule.strip()
+            and self.context.strip()
+            and self.antipattern.strip()
+            and self.rationale.strip()
+        )
+
+
+@dataclass
+class CategorizedRule:
+    """A rule after categorization and tagging.
+
+    Step 3 output: Ready for seed file generation.
+    Has final category and tags assigned.
+    """
+
+    rule: str
+    category: str  # Final category (e.g., "testing", "security")
+    context: str
+    antipattern: str
+    rationale: str
+    tags: list[str]  # Final tags
+    references: list[dict[str, str]]  # [{"url": ..., "title": ...}]
+    confidence: float = 1.0
+
+    @classmethod
+    def from_candidate(
+        cls,
+        candidate: CandidateRule,
+        category: str,
+        tags: list[str],
+    ) -> CategorizedRule:
+        """Create from a candidate rule with assigned category/tags."""
+        return cls(
+            rule=candidate.rule,
+            category=category,
+            context=candidate.context,
+            antipattern=candidate.antipattern,
+            rationale=candidate.rationale,
+            tags=tags,
+            references=[candidate.source.to_reference()],
+            confidence=candidate.confidence,
+        )
+
+    def to_seed_dict(self) -> dict[str, Any]:
+        """Convert to seed file rule format."""
+        return {
+            "rule": self.rule,
+            "category": self.category,
+            "context": self.context,
+            "antipattern": self.antipattern,
+            "rationale": self.rationale,
+            "tags": self.tags,
+            "references": self.references,
+        }

buildlog/seed_engine/pipeline.py

@@ -0,0 +1,202 @@
+"""Pipeline orchestration for the seed engine.
+
+The Pipeline ties together all 4 steps:
+1. Source identification (input)
+2. Rule extraction
+3. Categorization
+4. Seed generation
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from buildlog.seed_engine.categorizers import Categorizer, TagBasedCategorizer
+from buildlog.seed_engine.extractors import ManualExtractor, RuleExtractor
+from buildlog.seed_engine.generators import SeedGenerator
+from buildlog.seed_engine.models import CandidateRule, CategorizedRule, Source
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class PipelineResult:
+    """Result of running the seed engine pipeline."""
+
+    persona: str
+    sources: list[Source]
+    candidates: list[CandidateRule]
+    categorized: list[CategorizedRule]
+    seed_data: dict[str, Any]
+    output_path: Path | None = None
+
+    @property
+    def rule_count(self) -> int:
+        return len(self.categorized)
+
+    @property
+    def source_count(self) -> int:
+        return len(self.sources)
+
+    def summary(self) -> str:
+        """Human-readable summary of the pipeline run."""
+        lines = [
+            f"Seed Engine Pipeline Result: {self.persona}",
+            f"  Sources: {self.source_count}",
+            f"  Candidates extracted: {len(self.candidates)}",
+            f"  Rules categorized: {self.rule_count}",
+        ]
+        if self.output_path:
+            lines.append(f"  Output: {self.output_path}")
+        return "\n".join(lines)
+
+
+@dataclass
+class Pipeline:
+    """The seed engine pipeline.
+
+    Orchestrates the 4-step process for creating reviewer personas:
+
+    1. SOURCES → Define authoritative domain sources
+    2. EXTRACT → Pull rules with defensibility fields
+    3. CATEGORIZE → Assign categories and tags
+    4. GENERATE → Output validated YAML seed file
+
+    Usage:
+        # Create pipeline with default components
+        pipeline = Pipeline(
+            persona="test_terrorist",
+            default_category="testing",
+        )
+
+        # Or customize each step
+        pipeline = Pipeline(
+            persona="test_terrorist",
+            extractor=MyCustomExtractor(),
+            categorizer=MyCustomCategorizer(),
+            generator=SeedGenerator(persona="test_terrorist", version=1),
+        )
+
+        # Run the pipeline
+        result = pipeline.run(sources, output_dir=Path(".buildlog/seeds"))
+    """
+
+    persona: str
+    default_category: str = "general"
+    version: int = 1
+    extractor: RuleExtractor | None = None
+    categorizer: Categorizer | None = None
+    generator: SeedGenerator | None = None
+
+    def __post_init__(self) -> None:
+        # Set defaults if not provided
+        if self.extractor is None:
+            self.extractor = ManualExtractor()
+        if self.categorizer is None:
+            self.categorizer = TagBasedCategorizer(
+                default_category=self.default_category
+            )
+        if self.generator is None:
+            self.generator = SeedGenerator(
+                persona=self.persona,
+                version=self.version,
+            )
+
+    def run(
+        self,
+        sources: list[Source],
+        output_dir: Path | None = None,
+        write: bool = True,
+    ) -> PipelineResult:
+        """Run the full pipeline.
+
+        Args:
+            sources: Step 1 - The authoritative sources to extract from.
+            output_dir: Where to write the seed file.
+            write: Whether to write the seed file to disk.
+
+        Returns:
+            PipelineResult with all intermediate and final outputs.
+        """
+        logger.info(f"Starting seed engine pipeline for '{self.persona}'")
+        logger.info(f"Processing {len(sources)} sources")
+
+        # These are guaranteed set by __post_init__
+        assert self.extractor is not None
+        assert self.categorizer is not None
+        assert self.generator is not None
+
+        # Step 2: Extract rules from each source
+        candidates: list[CandidateRule] = []
+        for source in sources:
+            extracted = self.extractor.extract(source)
+            logger.info(f"  Extracted {len(extracted)} rules from {source.name}")
+            candidates.extend(extracted)
+
+        logger.info(f"Total candidates: {len(candidates)}")
+
+        # Step 3: Categorize each rule
+        categorized: list[CategorizedRule] = []
+        for candidate in candidates:
+            cat_rule = self.categorizer.categorize(candidate)
+            categorized.append(cat_rule)
+
+        logger.info(f"Categorized {len(categorized)} rules")
+
+        # Step 4: Generate seed file
+        self.generator.output_dir = output_dir
+        seed_data = self.generator.generate(categorized)
+
+        # Optionally write to disk
+        output_path = None
+        if write and output_dir:
+            output_path = self.generator.write(seed_data)
+            logger.info(f"Wrote seed file to {output_path}")
+
+        return PipelineResult(
+            persona=self.persona,
+            sources=sources,
+            candidates=candidates,
+            categorized=categorized,
+            seed_data=seed_data,
+            output_path=output_path,
+        )
+
+    def validate_sources(self, sources: list[Source]) -> list[str]:
+        """Validate that sources are properly defined.
+
+        Args:
+            sources: The sources to validate.
+
+        Returns:
+            List of validation issues (empty if valid).
+        """
+        issues = []
+        for i, source in enumerate(sources):
+            prefix = f"Source {i + 1} ({source.name})"
+            if not source.name.strip():
+                issues.append(f"{prefix}: Missing name")
+            if not source.url.strip():
+                issues.append(f"{prefix}: Missing URL")
+            if not source.domain.strip():
+                issues.append(f"{prefix}: Missing domain")
+        return issues
+
+    def dry_run(self, sources: list[Source]) -> dict[str, Any]:
+        """Run pipeline without writing, returning preview.
+
+        Useful for validation before committing to disk.
+        """
+        result = self.run(sources, write=False)
+        return {
+            "persona": result.persona,
+            "rule_count": result.rule_count,
+            "source_count": result.source_count,
+            "categories": list(set(r.category for r in result.categorized)),
+            "sample_rules": [
+                {"rule": r.rule, "category": r.category} for r in result.categorized[:3]
+            ],
+        }