chronicle-devkit 0.1.0__py3-none-any.whl

chronicle/cli/commands/show.py

@@ -0,0 +1,106 @@
+import typer
+from chronicle.storage.observations import ObservationRepo
+from chronicle.storage.database import connect
+from chronicle.config.loader import get_chronicle_directory
+from chronicle.project.discovery import find_project_root
+
+def show(id:int | None = typer.Option(None, "--id")):
+    """Shows all the observations done by chronicle or shows observation by id using --id."""
+    project_root = find_project_root()
+    if project_root is None:
+            typer.echo("Error: could not find git repo.",err=True)
+            raise typer.Exit(code=1)
+    db_path = (get_chronicle_directory(project_root) / "chronicle.db")
+    conn = connect(db_path)
+    if id:
+        observation, = ObservationRepo(conn).list_all(id)
+        typer.echo()
+        typer.echo(f"Observation #{id}")
+        typer.echo("─" * 44)
+        typer.echo()
+
+        typer.echo(f"{'Source:':<14}{observation.source}")
+        typer.echo(f"{'Type:':<14}{observation.type}")
+        typer.echo(f"{'External ID:':<14}{observation.external_id}")
+        typer.echo(
+            f"{'Timestamp:':<14}"
+            f"{observation.timestamp.strftime('%Y-%m-%d %H:%M:%S UTC')}"
+        )
+
+        typer.echo()
+        typer.echo("Data")
+        typer.echo("─" * 44)
+
+        data = observation.data
+
+        if "app" in data:
+            typer.echo(f"{'App:':<14}{data['app']}")
+
+        if "name" in data:
+            typer.echo(f"{'Migration:':<14}{data['name']}")
+
+        if "dependencies" in data:
+            typer.echo()
+            typer.echo("Dependencies:")
+
+            for dependency in data["dependencies"]:
+                typer.echo(f"  • {dependency[0]}:{dependency[1]}")
+
+        if "operations" in data:
+            typer.echo()
+            typer.echo("Operations:")
+
+            for operation in data["operations"]:
+                typer.echo(
+                    f"  • {operation['operation']}"
+                )
+
+                details = operation.get("details", {})
+
+                if details.get("model"):
+                    typer.echo(
+                        f"      Model: {details['model']}"
+                    )
+
+                if details.get("field"):
+                    typer.echo(
+                        f"      Field: {details['field']}"
+                    )
+
+        typer.echo()
+        typer.echo("─" * 44)
+    else:
+        observations = ObservationRepo(conn).list_all()
+        
+        typer.echo()
+        typer.echo("Chronicle Observations")
+        typer.echo("─" * 75)
+        typer.echo()
+
+        if not observations:
+            typer.echo("No observations found.")
+            typer.echo()
+            return
+
+        typer.echo(
+            f"{'ID':<5}"
+            f"{'SOURCE':<12}"
+            f"{'TYPE':<15}"
+            f"EXTERNAL ID"
+        )
+
+        typer.echo("─" * 75)
+
+        for observation in observations:
+            formatted_external_id = observation.external_id[:7] if observation.source == "git" else observation.external_id
+            
+            typer.echo(
+                f"{observation.id:<5}"
+                f"{observation.source:<12}"
+                f"{observation.type:<15}"
+                f"{formatted_external_id}"
+            )
+
+        typer.echo()
+        typer.echo("─" * 75)
+        typer.echo(f"{len(observations)} observations")

chronicle/cli/commands/status.py

@@ -0,0 +1,26 @@
+from pathlib import Path
+from chronicle.project.status import get_status
+import typer
+
+def status():
+    """Show the current chronicle project status."""
+    project_status=get_status()
+    if project_status is None:
+        typer.echo("Error: could not find a Git repo in the project.")
+        raise typer.Exit(code=1)
+    
+    typer.echo("")    
+    typer.echo(f"Project: {project_status.project_root.name}")    
+    typer.echo(f"Root: {project_status.project_root}")    
+    if project_status.chronicle_initialized:
+        typer.echo("Chronicle: initialized")
+    else:
+        typer.echo("Chronicle: not initialized")
+    if project_status.git_detected:
+        typer.echo("Git: detected")
+    else:
+        typer.echo("Git: not detected")
+    if project_status.config_exists:
+        typer.echo("Configuration: found")
+    else:
+        typer.echo("Configuration: missing")

chronicle/cli/commands/version.py

@@ -0,0 +1,6 @@
+import typer
+from chronicle import __version__
+
+def version():
+    """Show Chronicle Version"""
+    typer.echo(f"Chronicle {__version__}")

chronicle/cli/main.py

@@ -0,0 +1,30 @@
+import typer
+from chronicle.cli.commands.init import init
+from chronicle.cli.commands.version import version
+from chronicle.cli.commands.status import status
+from chronicle.cli.commands.scan import scan
+from chronicle.cli.commands.show import show
+from chronicle.cli.commands.analyze import analyze
+from chronicle.cli.commands.config import config_app
+from chronicle.cli.commands.interpret import interpret
+
+app = typer.Typer(
+    name="chronicle",
+    help="Local-first developer intelligence tool.",
+    no_args_is_help=True,
+)
+  
+app.command(name="init")(init)
+app.command(name="version")(version)
+app.command(name="status")(status)
+app.command(name="scan")(scan)
+app.command(name="show")(show)
+app.command(name="analyze")(analyze)
+app.command(name="interpret")(interpret)
+app.add_typer(
+    config_app,
+    name="config"
+)
+    
+def main():
+    app()

chronicle/config/credentials.py

@@ -0,0 +1,17 @@
+import os 
+import keyring
+
+SERVICE_NAME = "chronicle"
+
+def set_api_key(provider:str,api_key:str):
+    keyring.set_password(
+        SERVICE_NAME,
+        provider,
+        api_key
+    )
+
+def get_api_key(provider: str) -> str | None:
+    return keyring.get_password(SERVICE_NAME,provider)
+
+def has_api_key(provider: str) -> bool:
+    return get_api_key(provider) is not None

chronicle/config/loader.py

@@ -0,0 +1,21 @@
+from pathlib import Path
+try:
+    import tomllib #type:ignore
+except ModuleNotFoundError:
+    import tomli as tomllib
+
+CHRONICLE_DIRECTORY = ".chronicle"
+CONFIG_FILE = "config.toml"
+
+def get_chronicle_directory(project_root:Path) -> Path:
+    return project_root / CHRONICLE_DIRECTORY
+
+def get_config_path(project_root:Path) -> Path:
+    return get_chronicle_directory(project_root=project_root) / CONFIG_FILE
+
+def load_config(config_path: Path) ->dict:
+    if not config_path.exists():
+        return {}
+    
+    with config_path.open("rb") as file:
+        return tomllib.load(file)

chronicle/config/manager.py

@@ -0,0 +1,52 @@
+from pathlib import Path
+from chronicle.config.loader import *
+import tomli_w
+
+DEFAULT_CONFIG = """\
+[chronicle]
+version=1
+
+[ai]
+provider=""
+model=""
+"""
+
+def create_gitignore(project_root:Path):
+    gitignore_path = project_root / ".gitignore"
+    if not gitignore_path.exists():
+        gitignore_path.write_text(".chronicle/\n")
+        return
+    existing_content = gitignore_path.read_text()
+    if ".chronicle/" in existing_content.splitlines():
+        return
+    with gitignore_path.open(mode="a") as file: 
+        file.write("\n.chronicle/\n")
+
+def create_config(config_path:Path) -> bool:
+    if not config_path.exists():
+        config_path.write_text(
+            DEFAULT_CONFIG
+        )
+        return True
+    return False
+
+def update_ai_config(
+    config_path:Path,
+    provider:str | None = None,
+    model:str | None=None,
+) -> None:
+    if not config_path.exists():
+        create_config(config_path)
+    
+    config = load_config(config_path)
+    
+    ai = config.setdefault("ai",{})
+    if provider is not None:
+        ai["provider"] = provider
+    if model is not None:
+        ai["model"] = model
+    
+    with config_path.open("wb") as file:
+        tomli_w.dump(config,file)
+    
+    

chronicle/integrations/git.py

@@ -0,0 +1,16 @@
+import subprocess
+from pathlib import Path
+
+class GitIntegration:
+    def __init__(self,repo:Path) -> None:
+        self.repo = repo
+        
+    def run(self, *arguments:str) -> str:
+        result = subprocess.run(
+            ["git", *arguments],
+            cwd=self.repo,
+            capture_output=True,
+            check=True,
+            text=True,
+        )
+        return result.stdout

chronicle/interpretation/context.py

@@ -0,0 +1,8 @@
+from dataclasses import dataclass
+from chronicle.storage.models import Findings,Observation
+
+@dataclass
+class InterpretationContext:
+    question: str
+    findings: list[Findings]
+    observations: list[Observation]

chronicle/interpretation/context_builder.py

@@ -0,0 +1,147 @@
+from chronicle.interpretation.context import InterpretationContext
+from chronicle.storage.models import Findings,Observation
+from chronicle.project.discovery import find_project_root
+from nltk.tokenize import word_tokenize
+from pathlib import Path
+
+STOP_WORDS = {"the","a","an","is","was","were","to","of","in","on","for","my","me","why","what","how","did","does","do","has","have","been","there",}
+
+def build_context(
+    question:str,
+    findings: list[Findings],
+    observations:list[Observation],
+) -> InterpretationContext:
+    
+    keywords = _extract_keywords(question)
+    scored_findings = []
+    
+    for finding in findings:
+        score = _score_finding(
+            finding,
+            keywords,
+        )
+        
+        if score > 0:
+            scored_findings.append(
+                (score, finding)
+            )
+        
+    scored_findings.sort(
+        key = lambda item: item[0],
+        reverse=True
+    )
+    
+    selected_findings = [
+        finding for _, finding in scored_findings[:10]
+    ]
+    
+    observation_map = {
+        observation.id: observation for observation in observations
+    }
+    
+    selected_observations = []
+    
+    for finding in selected_findings:
+        observation = observation_map.get(finding.observation_id)
+        
+        if observation is not None:
+            selected_observations.append(observation)
+    
+    related_observations = []
+    
+    for observation in selected_observations:
+        related = _find_related_git_observations(
+            observation,
+            observations
+        )
+        
+        related_observations.extend(related)
+
+    selected_observations.extend(related_observations)
+    
+    unique_observations = {}
+    
+    for observation in selected_observations:
+        unique_observations[observation.id] = observation
+        
+    selected_observations = list(unique_observations.values())
+    
+    return InterpretationContext(
+        question=question,
+        findings=selected_findings,
+        observations=selected_observations,
+    )
+    
+def _extract_keywords(question:str) -> list[str]:
+    tokens = word_tokenize(question.lower())
+    return [
+        token for token in tokens if token.isalnum() and token not in STOP_WORDS and len(token) >= 3
+    ]
+
+def _finding_text(finding: Findings) -> str:
+    return " ".join(
+        [
+            finding.title,
+            finding.message,
+            str(finding.data),
+        ]
+    ).lower()
+    
+def _score_finding(finding: Findings, keywords: list[str]) -> int:
+    text = _finding_text(finding)
+    score = 0
+    
+    for keyword in keywords:
+        if keyword in finding.title.lower():
+            score += 3
+        if keyword in finding.message.lower():
+            score += 2
+        if keyword in str(finding.data).lower():
+            score += 3
+            
+    return score
+
+def _get_migration_path(observation: Observation) -> Path | None:
+    project_root = find_project_root()
+    if project_root is None:
+        return None
+    if observation.source != "django":
+        return None
+    if observation.type != "migration":
+        return None
+    
+    root_name = project_root.name
+    migration_name = observation.data.get("name")
+    app_name = observation.data.get("app")
+    if not migration_name:
+        return None
+    if not app_name:
+        return None
+    
+    migration_file = migration_name + ".py"
+    if app_name == root_name:
+        return Path("migrations") / migration_file
+     
+    return Path(app_name) / "migrations" / migration_file
+
+def _find_related_git_observations(migration: Observation, observations: list[Observation]) -> list[Observation]:
+    migration_path = _get_migration_path(migration)
+    
+    if migration_path is None:
+        return []
+    
+    related = []
+    for observation in observations:
+        if observation.source != "git":
+            continue
+        if observation.type != "commit":
+            continue
+        
+        changes = observation.data.get("changes",[])
+        
+        for change in changes:
+            if change.get("path") == str(migration_path):
+                related.append(observation)
+                break
+            
+    return related

chronicle/interpretation/interpreter.py

@@ -0,0 +1,12 @@
+from chronicle.ai.base import AIProvider
+from chronicle.interpretation.context import InterpretationContext
+from chronicle.interpretation.prompts import build_interpretation_prompt
+
+class Interpreter:
+    def __init__(self,provider: AIProvider) -> None:
+        self.provider = provider
+        
+    def interpret(self, context: InterpretationContext) -> str:
+        prompt = build_interpretation_prompt(context)
+        
+        return self.provider.generate(prompt)

chronicle/interpretation/prompts.py

@@ -0,0 +1,51 @@
+from chronicle.interpretation.context import InterpretationContext
+
+def build_interpretation_prompt(context: InterpretationContext) -> str:
+    prompt = f"""
+You are Chronicle, a software project history interpreter.
+
+Answer the user's question using only the project history
+provided below.
+
+User question:
+{context.question}
+
+Findings:
+"""
+
+    for finding in context.findings:
+        prompt += f"""
+- Analyzer: {finding.analyzer}
+- Severity: {finding.severity}
+- Title: {finding.title}
+- Message: {finding.message}
+- Observation ID: {finding.observation_id}
+- Data: {finding.data}
+"""
+
+    prompt += """
+
+Observations:
+"""
+
+    for observation in context.observations:
+        prompt += f""" 
+- ID: {observation.id}
+- Source: {observation.source}
+- Type: {observation.type}
+- External ID: {observation.external_id}
+- Timestamp: {observation.timestamp}
+- Data: {observation.data}
+"""
+
+    prompt += """
+
+Explain what happened, why it happened, and what effect it
+may have on the project.
+
+If the provided project history does not contain enough
+information to answer the question, say so instead of
+inventing information.   
+"""
+
+    return prompt

chronicle/project/discovery.py

@@ -0,0 +1,9 @@
+from pathlib import Path
+
+def find_project_root(start:Path | None=None) -> Path | None:
+    """Find the nearest ancestor containing a .git directory"""
+    cwd = start or Path.cwd()
+    for directory in [cwd,*cwd.parents]:
+        if (directory / ".git").exists():
+            return directory
+    return None

chronicle/project/initializer.py

@@ -0,0 +1,45 @@
+from pathlib import Path
+from chronicle.config.loader import *
+from chronicle.config.manager import *
+from chronicle.storage.schema import init_schema
+from chronicle.storage.database import connect
+from chronicle.config.credentials import has_api_key,set_api_key
+import nltk
+import os
+import typer
+
+def initialize_chronicle(project_root:Path) -> tuple[Path, bool]:
+    chronicle_directory = get_chronicle_directory(project_root)
+    chronicle_directory.mkdir(parents=True,exist_ok=True)
+    
+    db_path = chronicle_directory / "chronicle.db"
+    if not db_path.exists():
+        db_path.touch()
+        
+    conn = connect(db_path)
+    init_schema(conn)
+    
+    config_path = get_config_path(project_root)
+    created = create_config(config_path)
+    
+    create_gitignore(project_root)
+    
+    try:
+        nltk.data.find("tokenizers/punkt_tab")
+    except LookupError:
+        nltk.download("punkt_tab",quiet=True)
+    
+    return config_path,created
+
+def setup_ai_config(config_path: Path):
+    provider = typer.prompt("   AI provider", default="gemini")
+    model = typer.prompt("   AI model", default="gemini-2.5-flash")
+    if has_api_key(provider):
+        typer.echo("   API key already found in the system.")
+    else:
+        api_key = typer.prompt("   API KEY",hide_input=True)
+        set_api_key(provider,api_key)
+        typer.echo("   ✓ API key stored securely.")
+        
+    
+    update_ai_config(config_path=config_path,provider=provider,model=model)

chronicle/project/status.py

@@ -0,0 +1,25 @@
+from pathlib import Path
+from dataclasses import dataclass
+from chronicle.project.discovery import find_project_root
+from chronicle.config.loader import *
+
+@dataclass
+class ProjectStatus:
+    project_root:Path
+    chronicle_initialized:bool
+    git_detected:bool
+    config_exists:bool
+
+def get_status() -> ProjectStatus | None:
+    project_root = find_project_root()
+    if project_root is None:
+        return None
+    
+    config_path = get_config_path(project_root)
+    
+    return ProjectStatus(
+        project_root=project_root,
+        chronicle_initialized=config_path.exists(),
+        git_detected=(project_root / ".git").exists(),
+        config_exists=config_path.exists()
+    )

chronicle/scanning/context.py

@@ -0,0 +1,10 @@
+from dataclasses import dataclass, field
+
+@dataclass
+class ScanContext:
+    state: dict[str,str | None] = field(
+        default_factory=dict
+    )
+    
+    def get_state(self,scanner:str,key:str) -> str |None:
+        return self.state.get(f"{scanner}.{key}")

chronicle/scanning/engine.py

@@ -0,0 +1,16 @@
+from pathlib import Path
+from chronicle.scanning.scanners.base import Scanner
+from chronicle.storage.models import Observation
+from .context import ScanContext
+
+class ScanEngine:
+    def __init__(self,project_root:Path,scanners:list[Scanner]) -> None:
+        self.project_root = project_root
+        self.scanners = scanners
+        
+    def scan(self,contexts:list[ScanContext]) -> list[Observation]:
+        observation:list[Observation] = []
+        for scanner in self.scanners:
+            observation.extend(scanner.scan(contexts=contexts))
+        
+        return observation

chronicle/scanning/scanners/base.py

@@ -0,0 +1,17 @@
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from ...storage.models import Observation
+from chronicle.scanning.context import ScanContext
+
+class Scanner(ABC):
+    """Base class for all chronicle scanners."""
+    
+    def __init__(self,project_root:Path) -> None:
+        self.project_root = project_root
+        
+    @abstractmethod
+    def scan(self,contexts:list[ScanContext]) -> list[Observation]:
+        """Scan the project and return observation"""
+        pass
+