speculast 1.0.1__tar.gz

speculast-1.0.1/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+.pytest_cache/
+.coverage
+.speculast/
+.browser-check-profile*
+.tmp_chrome_report_test/
+*.tmp*
+

speculast-1.0.1/PKG-INFO

@@ -0,0 +1,292 @@
+Metadata-Version: 2.4
+Name: speculast
+Version: 1.0.1
+Summary: Semantic-first framework for Python architecture analysis, automated test generation, and infrastructure-aware reporting.
+Author: speculast team
+License: Proprietary
+Keywords: architecture-analysis,ast,automation,docker,pytest,python,reporting,semantic-analysis,testing
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.12
+Requires-Dist: asyncpg<1.0.0,>=0.29.0
+Requires-Dist: jinja2<4.0.0,>=3.1.4
+Requires-Dist: pydantic<3.0.0,>=2.7.0
+Requires-Dist: pytest-asyncio<1.0.0,>=0.23.0
+Requires-Dist: pytest-cov<7.0.0,>=5.0.0
+Requires-Dist: pytest-json-report<2.0.0,>=1.5.0
+Requires-Dist: pytest<9.0.0,>=8.2.0
+Requires-Dist: rich<15.0.0,>=13.7.0
+Requires-Dist: sqlalchemy<3.0.0,>=2.0.0
+Provides-Extra: dev
+Requires-Dist: ruff<1.0.0,>=0.5.0; extra == 'dev'
+Requires-Dist: testcontainers[postgresql,redis]<5.0.0,>=4.8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# speculast
+
+`speculast` is an installable Python framework for semantic code analysis,
+automatic pytest generation, infrastructure detection, and visual reporting.
+
+speculast parses Python projects through AST analysis, tracks semantic changes,
+detects external dependencies, prepares test suites, can orchestrate Docker-backed
+integration runs, and produces a self-contained HTML report.
+
+## What speculast Does
+
+- analyzes Python modules and projects at the semantic level;
+- extracts functions, methods, imports, and external calls;
+- detects infrastructure requirements such as PostgreSQL and Redis;
+- generates production-style pytest suites;
+- runs a full cycle with Docker, pytest, coverage, and JSON reports;
+- builds timestamped HTML dashboards grouped by day under `reports/`.
+
+## Installation
+
+Use Python `3.12+`. The project is packaged through `pyproject.toml`.
+
+```bash
+python -m venv .venv
+```
+
+Windows:
+
+```bash
+.venv\Scripts\activate
+python -m pip install --upgrade pip
+python -m pip install .
+```
+
+Linux / macOS:
+
+```bash
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install .
+```
+
+After installation, the CLI command `speculast` becomes available in the active environment.
+
+## CLI Quick Reference
+
+```bash
+speculast [PATH] [--no-tests] [--no-viz] [--no-real-db] [--no-cleanup] [--lang ru|en] [--cleanup-reports] [--report-retention-days N]
+```
+
+Examples:
+
+```bash
+speculast
+speculast path/to/module.py
+speculast . --cleanup-reports --report-retention-days 7
+speculast . --no-tests
+speculast . --no-viz --lang en
+```
+
+By default, `speculast` runs in Full Auto mode:
+
+- uses the current directory when `PATH` is omitted;
+- cleans temporary root-level technical noise automatically;
+- enables real DB mode by default;
+- runs generated tests;
+- builds the HTML report;
+- opens the fresh report in the browser automatically.
+
+`--cleanup-reports` additionally prunes aged HTML reports from `reports/`.
+
+The default full cycle performs:
+
+1. semantic analysis;
+2. test generation;
+3. infrastructure planning;
+4. `docker compose up -d` when services are required;
+5. pytest execution with coverage and JSON reports;
+6. HTML report generation;
+7. `docker compose down --remove-orphans`.
+
+## Template and Report Portability
+
+speculast resolves Jinja and HTML templates through `importlib.resources`.
+This means the package can locate bundled templates correctly after `pip install .`,
+even when `speculast` is started from an unrelated working directory.
+
+Bundled resources include:
+
+- `engine/generator/templates/*.jinja2`
+- `engine/visualizer/templates/report.html`
+
+## Scenario A: Quick Start on Any OS
+
+Install the package and run the full autonomous cycle against the current project:
+
+```bash
+python -m pip install .
+speculast
+```
+
+Expected outputs:
+
+- generated test suite under `tests/`;
+- `docker-compose.yaml` when infrastructure is required;
+- date-grouped reports such as `reports/2026-05-14/report_131530.html`.
+
+If you also want to keep raw pytest and coverage JSON artifacts:
+
+```bash
+speculast . --no-cleanup
+```
+
+If you only need the report without pytest execution:
+
+```bash
+speculast . --no-tests
+```
+
+## Scenario B: Windows + Docker Desktop
+
+Recommended stack:
+
+- Python `3.12+`
+- Docker Desktop
+- PowerShell or Windows Terminal
+
+Typical workflow:
+
+```powershell
+.venv\Scripts\activate
+python -m pip install .
+speculast
+```
+
+Notes for Windows:
+
+- `speculast` can start and stop Docker-backed infrastructure for integration scenarios.
+- If PostgreSQL-backed tests are generated, make sure Docker Desktop is installed and available in PATH.
+- speculast writes final diagnostics into timestamped files inside `reports/`, while terminal output stays compact.
+
+## Scenario C: Linux / macOS Server Mode
+
+speculast does not require a desktop UI. The report is generated as a plain HTML file
+that can be opened locally or archived as a build artifact.
+
+Typical workflow:
+
+```bash
+source .venv/bin/activate
+python -m pip install .
+speculast /opt/projects/my-service --lang en
+```
+
+Recommended environment preparation:
+
+- install Docker Engine or Docker Desktop for container-backed tests;
+- ensure the current user can run `docker compose`;
+- run inside a CI worker, VM, or server shell without GUI if needed.
+
+For analysis-only mode on a server:
+
+```bash
+speculast /opt/projects/my-service --no-tests --no-viz
+```
+
+## Scenario D: CI/CD Integration
+
+The CLI is designed to be called directly from automated validation pipelines.
+
+Minimal pipeline step:
+
+```bash
+python -m pip install .
+speculast . --lang en
+```
+
+Recommended artifacts to publish from the job:
+
+- `reports/`
+- generated `tests/` directory if you want to inspect emitted suites
+
+If the pipeline should also retain raw pytest and coverage JSON files, run with `--no-cleanup` and publish:
+
+- `.speculast/pytest-report.json`
+- `.speculast/coverage.json`
+
+Example GitHub Actions step:
+
+```yaml
+- name: Install framework
+  run: python -m pip install .
+
+- name: Run semantic analysis and tests
+  run: speculast . --lang en
+```
+
+Example GitLab CI job:
+
+```yaml
+speculast:
+  stage: test
+  script:
+    - python -m pip install .
+    - speculast . --lang en
+  artifacts:
+    when: always
+    paths:
+      - reports/
+```
+
+## Project Layout
+
+```text
+engine/
+  analyzer/    Semantic analysis and AST visitors
+  core/        Pydantic models, i18n, protocols
+  generator/   Jinja-based pytest generation templates and engine
+  infra/       Infrastructure detection and Docker Compose helpers
+  visualizer/  HTML dashboard rendering
+main.py        CLI entry module
+pyproject.toml Packaging metadata and script entry points
+```
+
+## Installed CLI Entry Point
+
+The package registers:
+
+```toml
+[project.scripts]
+speculast = "main:main"
+```
+
+So after installation, `speculast` runs the same autonomous CLI cycle exposed by `main.py`.
+
+## Output Artifacts
+
+Depending on the mode, the framework can generate:
+
+- `tests/`
+- `docker-compose.yaml`
+- `reports/`
+
+Temporary technical artifacts such as `.speculast/`, cache folders, and browser-check profiles are removed automatically unless `--no-cleanup` is used.
+
+## Development Notes
+
+Runtime dependencies are declared in `pyproject.toml` and include:
+
+- `pydantic`
+- `jinja2`
+- `sqlalchemy`
+- `asyncpg`
+- `pytest`
+- `pytest-asyncio`
+- `pytest-cov`
+- `pytest-json-report`
+- `rich`
+
+Optional development extras:
+
+```bash
+python -m pip install .[dev]
+```

speculast-1.0.1/README.md

@@ -0,0 +1,264 @@
+# speculast
+
+`speculast` is an installable Python framework for semantic code analysis,
+automatic pytest generation, infrastructure detection, and visual reporting.
+
+speculast parses Python projects through AST analysis, tracks semantic changes,
+detects external dependencies, prepares test suites, can orchestrate Docker-backed
+integration runs, and produces a self-contained HTML report.
+
+## What speculast Does
+
+- analyzes Python modules and projects at the semantic level;
+- extracts functions, methods, imports, and external calls;
+- detects infrastructure requirements such as PostgreSQL and Redis;
+- generates production-style pytest suites;
+- runs a full cycle with Docker, pytest, coverage, and JSON reports;
+- builds timestamped HTML dashboards grouped by day under `reports/`.
+
+## Installation
+
+Use Python `3.12+`. The project is packaged through `pyproject.toml`.
+
+```bash
+python -m venv .venv
+```
+
+Windows:
+
+```bash
+.venv\Scripts\activate
+python -m pip install --upgrade pip
+python -m pip install .
+```
+
+Linux / macOS:
+
+```bash
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install .
+```
+
+After installation, the CLI command `speculast` becomes available in the active environment.
+
+## CLI Quick Reference
+
+```bash
+speculast [PATH] [--no-tests] [--no-viz] [--no-real-db] [--no-cleanup] [--lang ru|en] [--cleanup-reports] [--report-retention-days N]
+```
+
+Examples:
+
+```bash
+speculast
+speculast path/to/module.py
+speculast . --cleanup-reports --report-retention-days 7
+speculast . --no-tests
+speculast . --no-viz --lang en
+```
+
+By default, `speculast` runs in Full Auto mode:
+
+- uses the current directory when `PATH` is omitted;
+- cleans temporary root-level technical noise automatically;
+- enables real DB mode by default;
+- runs generated tests;
+- builds the HTML report;
+- opens the fresh report in the browser automatically.
+
+`--cleanup-reports` additionally prunes aged HTML reports from `reports/`.
+
+The default full cycle performs:
+
+1. semantic analysis;
+2. test generation;
+3. infrastructure planning;
+4. `docker compose up -d` when services are required;
+5. pytest execution with coverage and JSON reports;
+6. HTML report generation;
+7. `docker compose down --remove-orphans`.
+
+## Template and Report Portability
+
+speculast resolves Jinja and HTML templates through `importlib.resources`.
+This means the package can locate bundled templates correctly after `pip install .`,
+even when `speculast` is started from an unrelated working directory.
+
+Bundled resources include:
+
+- `engine/generator/templates/*.jinja2`
+- `engine/visualizer/templates/report.html`
+
+## Scenario A: Quick Start on Any OS
+
+Install the package and run the full autonomous cycle against the current project:
+
+```bash
+python -m pip install .
+speculast
+```
+
+Expected outputs:
+
+- generated test suite under `tests/`;
+- `docker-compose.yaml` when infrastructure is required;
+- date-grouped reports such as `reports/2026-05-14/report_131530.html`.
+
+If you also want to keep raw pytest and coverage JSON artifacts:
+
+```bash
+speculast . --no-cleanup
+```
+
+If you only need the report without pytest execution:
+
+```bash
+speculast . --no-tests
+```
+
+## Scenario B: Windows + Docker Desktop
+
+Recommended stack:
+
+- Python `3.12+`
+- Docker Desktop
+- PowerShell or Windows Terminal
+
+Typical workflow:
+
+```powershell
+.venv\Scripts\activate
+python -m pip install .
+speculast
+```
+
+Notes for Windows:
+
+- `speculast` can start and stop Docker-backed infrastructure for integration scenarios.
+- If PostgreSQL-backed tests are generated, make sure Docker Desktop is installed and available in PATH.
+- speculast writes final diagnostics into timestamped files inside `reports/`, while terminal output stays compact.
+
+## Scenario C: Linux / macOS Server Mode
+
+speculast does not require a desktop UI. The report is generated as a plain HTML file
+that can be opened locally or archived as a build artifact.
+
+Typical workflow:
+
+```bash
+source .venv/bin/activate
+python -m pip install .
+speculast /opt/projects/my-service --lang en
+```
+
+Recommended environment preparation:
+
+- install Docker Engine or Docker Desktop for container-backed tests;
+- ensure the current user can run `docker compose`;
+- run inside a CI worker, VM, or server shell without GUI if needed.
+
+For analysis-only mode on a server:
+
+```bash
+speculast /opt/projects/my-service --no-tests --no-viz
+```
+
+## Scenario D: CI/CD Integration
+
+The CLI is designed to be called directly from automated validation pipelines.
+
+Minimal pipeline step:
+
+```bash
+python -m pip install .
+speculast . --lang en
+```
+
+Recommended artifacts to publish from the job:
+
+- `reports/`
+- generated `tests/` directory if you want to inspect emitted suites
+
+If the pipeline should also retain raw pytest and coverage JSON files, run with `--no-cleanup` and publish:
+
+- `.speculast/pytest-report.json`
+- `.speculast/coverage.json`
+
+Example GitHub Actions step:
+
+```yaml
+- name: Install framework
+  run: python -m pip install .
+
+- name: Run semantic analysis and tests
+  run: speculast . --lang en
+```
+
+Example GitLab CI job:
+
+```yaml
+speculast:
+  stage: test
+  script:
+    - python -m pip install .
+    - speculast . --lang en
+  artifacts:
+    when: always
+    paths:
+      - reports/
+```
+
+## Project Layout
+
+```text
+engine/
+  analyzer/    Semantic analysis and AST visitors
+  core/        Pydantic models, i18n, protocols
+  generator/   Jinja-based pytest generation templates and engine
+  infra/       Infrastructure detection and Docker Compose helpers
+  visualizer/  HTML dashboard rendering
+main.py        CLI entry module
+pyproject.toml Packaging metadata and script entry points
+```
+
+## Installed CLI Entry Point
+
+The package registers:
+
+```toml
+[project.scripts]
+speculast = "main:main"
+```
+
+So after installation, `speculast` runs the same autonomous CLI cycle exposed by `main.py`.
+
+## Output Artifacts
+
+Depending on the mode, the framework can generate:
+
+- `tests/`
+- `docker-compose.yaml`
+- `reports/`
+
+Temporary technical artifacts such as `.speculast/`, cache folders, and browser-check profiles are removed automatically unless `--no-cleanup` is used.
+
+## Development Notes
+
+Runtime dependencies are declared in `pyproject.toml` and include:
+
+- `pydantic`
+- `jinja2`
+- `sqlalchemy`
+- `asyncpg`
+- `pytest`
+- `pytest-asyncio`
+- `pytest-cov`
+- `pytest-json-report`
+- `rich`
+
+Optional development extras:
+
+```bash
+python -m pip install .[dev]
+```

speculast-1.0.1/demo_shop/__init__.py

@@ -0,0 +1,22 @@
+"""Demo e-commerce application used by speculast."""
+
+from .logic import (
+    calculate_discount,
+    calculate_line_total,
+    calculate_order_total,
+    validate_stock,
+)
+from .models import OrderCreateRequest, OrderItemRequest, OrderResult, Product
+from .service import create_order
+
+__all__ = [
+    "OrderCreateRequest",
+    "OrderItemRequest",
+    "OrderResult",
+    "Product",
+    "calculate_discount",
+    "calculate_line_total",
+    "calculate_order_total",
+    "create_order",
+    "validate_stock",
+]

speculast-1.0.1/demo_shop/database.py

@@ -0,0 +1,89 @@
+"""SQLAlchemy models and helpers for the demo shop."""
+
+from __future__ import annotations
+
+import os
+from decimal import Decimal
+
+from sqlalchemy import ForeignKey, Numeric, String
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
+
+
+DEFAULT_DATABASE_URL = "postgresql+asyncpg://app:app@127.0.0.1:55432/app"
+
+
+class Base(DeclarativeBase):
+    """Shared SQLAlchemy declarative base."""
+
+
+class ProductRecord(Base):
+    """Catalog inventory row."""
+
+    __tablename__ = "shop_products"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    sku: Mapped[str] = mapped_column(String(64), unique=True, index=True)
+    title: Mapped[str] = mapped_column(String(255))
+    unit_price: Mapped[Decimal] = mapped_column(Numeric(10, 2))
+    stock: Mapped[int] = mapped_column()
+
+
+class OrderRecord(Base):
+    """Order header row."""
+
+    __tablename__ = "shop_orders"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    customer_email: Mapped[str] = mapped_column(String(255), index=True)
+    promo_code: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    subtotal: Mapped[Decimal] = mapped_column(Numeric(10, 2))
+    discount_total: Mapped[Decimal] = mapped_column(Numeric(10, 2))
+    total: Mapped[Decimal] = mapped_column(Numeric(10, 2))
+
+    items: Mapped[list["OrderItemRecord"]] = relationship(
+        back_populates="order",
+        cascade="all, delete-orphan",
+    )
+
+
+class OrderItemRecord(Base):
+    """Order line row."""
+
+    __tablename__ = "shop_order_items"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    order_id: Mapped[int] = mapped_column(ForeignKey("shop_orders.id", ondelete="CASCADE"))
+    product_id: Mapped[int] = mapped_column(ForeignKey("shop_products.id"))
+    sku: Mapped[str] = mapped_column(String(64))
+    quantity: Mapped[int] = mapped_column()
+    unit_price: Mapped[Decimal] = mapped_column(Numeric(10, 2))
+    line_total: Mapped[Decimal] = mapped_column(Numeric(10, 2))
+
+    order: Mapped[OrderRecord] = relationship(back_populates="items")
+
+
+def resolve_database_url() -> str:
+    """Return the connection string used by integration tests and services."""
+
+    return os.getenv("DEMO_SHOP_DATABASE_URL", DEFAULT_DATABASE_URL)
+
+
+def create_engine(database_url: str | None = None) -> AsyncEngine:
+    """Build an async SQLAlchemy engine."""
+
+    return create_async_engine(
+        database_url or resolve_database_url(),
+        future=True,
+        connect_args={"ssl": False},
+    )
+
+
+def create_session_factory(database_url: str | None = None) -> async_sessionmaker[AsyncSession]:
+    """Build a reusable async session factory."""
+
+    return async_sessionmaker(
+        create_engine(database_url),
+        class_=AsyncSession,
+        expire_on_commit=False,
+    )