smallsteps 0.1.1__tar.gz

smallsteps-0.1.1/.github/actions/babysteps/action.yml

@@ -0,0 +1,20 @@
+name: "Smallsteps Ratchet Evaluation"
+description: "Evaluates your quality goals"
+inputs:
+  SMALLSTEPS_PYTEST_COVERAGE:
+    description: "Current live performance value for 'Pytest Coverage'"
+    required: true
+
+runs:
+  using: "composite"
+  steps:
+    - name: Install uv
+      uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+      with:
+        enable-cache: true
+
+    - name: Run Smallsteps Guardrail Validation
+      shell: bash
+      run: uvx smallsteps-ratchet check
+      env:
+        SMALLSTEPS_PYTEST_COVERAGE: ${{ inputs.SMALLSTEPS_PYTEST_COVERAGE }}

smallsteps-0.1.1/.github/workflows/ci.yaml

@@ -0,0 +1,83 @@
+name: CI and Publish
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --all-groups --frozen
+
+      - name: Lint with ruff
+        run: uv run ruff check .
+
+      - name: Format check with ruff
+        run: uv run ruff format --check .
+
+      - name: Execute Test Suite with JSON Report
+        run: uv run pytest --cov --cov-report=json
+
+      - name: Parse Metrics
+        id: extract_metrics
+        run: |
+          COVERAGE_RAW=$(jq -r '.totals.percent_covered' coverage.json)
+          echo "coverage=$COVERAGE_RAW" >> $GITHUB_OUTPUT
+
+      # - name: Enforce Monotonic Progress Guardrails
+      #   uses: ./.github/actions/smallsteps
+      #   with:
+      #     SMALLSTEPS_PYTEST_COVERAGE: ${{ steps.extract_metrics.outputs.coverage }}
+
+  publish:
+    needs: test
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/nasa-lsp
+    permissions:
+      id-token: write
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --all-groups --frozen
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Bump version
+        run: uv run bump-my-version bump patch
+
+      - name: Push version bump
+        run: git push --follow-tags
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

smallsteps-0.1.1/.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+coverage.json
+
+# Virtual environments
+.venv
+
+
+.coverage

smallsteps-0.1.1/.python-version

@@ -0,0 +1 @@
+3.12

smallsteps-0.1.1/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: smallsteps
+Version: 0.1.1
+Summary: Add your description here
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: typer>=0.26.7
+Description-Content-Type: text/markdown
+
+# Smallsteps - improve your codebase in small steps
+
+Smallsteps allows you to declare ratchets – metrics that must increase over time – and to enforce them via testing or CI pipelines.
+
+A typical situation: you want to add test coverage as a health check.
+Initially your coverage is at 42% so you create a CI gate that fails if it falls under 40%. Now you have your baseline secured – so far so good. You make a resolution to yourself that you will increase your coverage to bump up the percentage in your CI action frequently.
+**Somehow that never happens and your coverage stays at 42%.**
+
+With smallsteps you declare your goal of 80% coverage and that you want to reach it in 100 days. Smallsteps computes the necessary percentage that must be met for each day (e.g. after 50 days you need 60% coverage) and fails if the goal is not met.
+
+## Example
+
+We are using this repository itself as an example. We want to enforce our test coverage to go up.
+So we create a ratchet:
+
+```
+uvx smallsteps add \
+  --name="Pytest Coverage" \
+  --command="uv run pytest --cov --cov-report=json > /dev/null && jq -r '.totals.percent_covered' coverage.json" \
+  --goal=80 \
+  --end="2026-10-01"
+```
+
+This created a new file – `smallsteps.toml` – which holds the configuration of our ratchet:
+
+```toml
+# Smallsteps Configuration
+
+[[ratchets]]
+name = "Pytest Coverage"
+start = 2026-06-25
+end = 2026-10-01
+initial_value = 57.142857142857146
+goal_value = 80
+command = "uv run pytest --cov --cov-report=json > /dev/null && jq -r '.totals.percent_covered' coverage.json"
+
+```
+
+**Note**
+
+- You don't need to memorize the command parameters, `smallsteps add` walks you through them interactively.
+- Ratchets can be increasing or decreasing. Percentages (56%) are parsed as floats (.56). So make sure that your goal matches the format of the command output.
+
+You can inspect, add or modify the ratchets using the the toml file.
+
+### Checking your Ratchets
+
+Run `uvx smallsteps check` to check the status of your ratchets. To simulate the future you can run with `--date`, e.g.:
+
+```
+uv smallsteps check --date 2026-10-31
+Evaluating 1 ratchet(s)...
+
+Pytest Coverage: BEHIND (Current: 57.14, Expected Min: 80.00)
+
+Progress check failed.
+
+```
+
+shows that on the goal date the check will fail if we do not achieve 80% test coverage.
+
+### CI and reading values from env
+
+When running `smallsteps check` all commands to gather your metrics are run by smallsteps. This may be not the desired behaviour in CI because you want to run the checks in different workflows / actions and do not want to use smallsteps as a central orchestrator.
+
+By default smallsteps looks for environment variables matching the ratchets before running the command. E.g. if `SMALLSTEPS_PYTEST_COVERAGE` is present, the coverage is not re-computed. You can use this in CI to pass outputs from test workflow into the smallsteps action. To get a scaffolding github action with the required input vars for your ratchets run `uvx smallsteps ci`.
+
+Have a look at [the action](.github/actions/smallsteps/action.yml) and the whole workflow (not provided by a command because too specific for your setup) to see how the plumbing can work.
+
+## Installation
+
+This documentaion assumes you are using `uv`, hence you don't need to do anything despite using the uv tool command (`ux`) to install and run smallsteps.
+
+# License
+
+MIT

smallsteps-0.1.1/README.md

@@ -0,0 +1,76 @@
+# Smallsteps - improve your codebase in small steps
+
+Smallsteps allows you to declare ratchets – metrics that must increase over time – and to enforce them via testing or CI pipelines.
+
+A typical situation: you want to add test coverage as a health check.
+Initially your coverage is at 42% so you create a CI gate that fails if it falls under 40%. Now you have your baseline secured – so far so good. You make a resolution to yourself that you will increase your coverage to bump up the percentage in your CI action frequently.
+**Somehow that never happens and your coverage stays at 42%.**
+
+With smallsteps you declare your goal of 80% coverage and that you want to reach it in 100 days. Smallsteps computes the necessary percentage that must be met for each day (e.g. after 50 days you need 60% coverage) and fails if the goal is not met.
+
+## Example
+
+We are using this repository itself as an example. We want to enforce our test coverage to go up.
+So we create a ratchet:
+
+```
+uvx smallsteps add \
+  --name="Pytest Coverage" \
+  --command="uv run pytest --cov --cov-report=json > /dev/null && jq -r '.totals.percent_covered' coverage.json" \
+  --goal=80 \
+  --end="2026-10-01"
+```
+
+This created a new file – `smallsteps.toml` – which holds the configuration of our ratchet:
+
+```toml
+# Smallsteps Configuration
+
+[[ratchets]]
+name = "Pytest Coverage"
+start = 2026-06-25
+end = 2026-10-01
+initial_value = 57.142857142857146
+goal_value = 80
+command = "uv run pytest --cov --cov-report=json > /dev/null && jq -r '.totals.percent_covered' coverage.json"
+
+```
+
+**Note**
+
+- You don't need to memorize the command parameters, `smallsteps add` walks you through them interactively.
+- Ratchets can be increasing or decreasing. Percentages (56%) are parsed as floats (.56). So make sure that your goal matches the format of the command output.
+
+You can inspect, add or modify the ratchets using the the toml file.
+
+### Checking your Ratchets
+
+Run `uvx smallsteps check` to check the status of your ratchets. To simulate the future you can run with `--date`, e.g.:
+
+```
+uv smallsteps check --date 2026-10-31
+Evaluating 1 ratchet(s)...
+
+Pytest Coverage: BEHIND (Current: 57.14, Expected Min: 80.00)
+
+Progress check failed.
+
+```
+
+shows that on the goal date the check will fail if we do not achieve 80% test coverage.
+
+### CI and reading values from env
+
+When running `smallsteps check` all commands to gather your metrics are run by smallsteps. This may be not the desired behaviour in CI because you want to run the checks in different workflows / actions and do not want to use smallsteps as a central orchestrator.
+
+By default smallsteps looks for environment variables matching the ratchets before running the command. E.g. if `SMALLSTEPS_PYTEST_COVERAGE` is present, the coverage is not re-computed. You can use this in CI to pass outputs from test workflow into the smallsteps action. To get a scaffolding github action with the required input vars for your ratchets run `uvx smallsteps ci`.
+
+Have a look at [the action](.github/actions/smallsteps/action.yml) and the whole workflow (not provided by a command because too specific for your setup) to see how the plumbing can work.
+
+## Installation
+
+This documentaion assumes you are using `uv`, hence you don't need to do anything despite using the uv tool command (`ux`) to install and run smallsteps.
+
+# License
+
+MIT

smallsteps-0.1.1/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "smallsteps"
+version = "0.1.1"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "pydantic>=2.13.4",
+    "typer>=0.26.7",
+]
+
+[dependency-groups]
+dev = [
+    "bump-my-version>=1.4.1",
+    "ruff>=0.15.19",
+]
+test = [
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+]
+
+[tool.uv]
+package = true
+
+[project.scripts]
+smallsteps = "smallsteps.cli:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.bumpversion]
+current_version = "0.1.1"
+commit = true
+tag = true
+tag_name = "v{new_version}"
+message = "Bump version: {current_version} → {new_version} [skip ci]"
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'

smallsteps-0.1.1/smallsteps.toml

@@ -0,0 +1,9 @@
+# Smallsteps Configuration
+
+[[ratchets]]
+name = "Pytest Coverage"
+start = 2026-06-25
+end = 2026-10-01
+initial_value = 57.142857142857146
+goal_value = 80
+command = "uv run pytest --cov --cov-report=json > /dev/null && jq -r '.totals.percent_covered' coverage.json"

smallsteps-0.1.1/src/smallsteps/__init__.py

@@ -0,0 +1,12 @@
+from smallsteps.cli import app
+from smallsteps.command_runner import CommandRunner
+from smallsteps.prober import Prober
+from smallsteps.ratchet import Ratchet, evaluate
+
+__all__ = [
+    "app",
+    "Ratchet",
+    "evaluate",
+    "CommandRunner",
+    "Prober",
+]

smallsteps-0.1.1/src/smallsteps/ci_adapter.py

@@ -0,0 +1,69 @@
+import re
+from pathlib import Path
+from typing import List
+
+from smallsteps.ratchet import Ratchet
+
+
+def ratchet_to_slug(ratchet: Ratchet) -> str:
+    """Generates a standardized environment variable key for a given ratchet name."""
+    return f"SMALLSTEPS_{re.sub(r'[^a-zA-Z0-9]', '_', ratchet.name).upper()}"
+
+
+class GitHubCIAdapter:
+    """Generates a custom local GitHub Composite Action matched to the project metrics."""
+
+    def generate_action(self, ratchets: List[Ratchet]) -> str:
+        """Generates an action.yml manifest string with dynamic inputs, setup stubs, and mapping."""
+        yaml_lines = [
+            "name: 'Smallsteps Ratchet Evaluation'",
+            "description: 'Evaluates your quality goals'",
+        ]
+
+        # 1. Append inputs only if there are active ratchets to list
+        if ratchets:
+            yaml_lines.append("inputs:")
+            for r in ratchets:
+                slug = ratchet_to_slug(r)
+                yaml_lines.extend(
+                    [
+                        f"  {slug}:",
+                        f"    description: \"Current live performance value for '{r.name}'\"",
+                        "    required: true",
+                    ]
+                )
+
+        # 2. Append core composite block infrastructure and the installation placeholder
+        yaml_lines.extend(
+            [
+                "",
+                "runs:",
+                "  using: 'composite'",
+                "  steps:",
+                "    - name: Install uv",
+                "      uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0",
+                "      with:",
+                "        enable-cache: true",
+                "",
+                "    - name: Run Smallsteps Guardrail Validation",
+                "      shell: bash",
+                "      run: uvx smallsteps-ratchet check",
+            ]
+        )
+
+        # 3. Append step context environment maps sequentially via loop execution
+        if ratchets:
+            yaml_lines.append("      env:")
+            for r in ratchets:
+                slug = ratchet_to_slug(r)
+                yaml_lines.append(f"        {slug}: ${{{{ inputs.{slug} }}}}")
+
+        return "\n".join(yaml_lines) + "\n"
+
+    def save(self, path: Path, content: str) -> None:
+        """Writes the custom composite action metadata safely out to file."""
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(content, encoding="utf-8")
+        except Exception as e:
+            raise IOError(f"Failed to write local custom action configuration: {e}")

smallsteps-0.1.1/src/smallsteps/cli.py

@@ -0,0 +1,275 @@
+from datetime import date, datetime, timedelta
+from pathlib import Path
+
+import typer
+
+from smallsteps.ci_adapter import GitHubCIAdapter
+from smallsteps.cli_helpers import find_git_root
+from smallsteps.command_runner import (
+    CommandRunnerWithEnvLookUp,
+    OSCommandRunner,
+    OSEnvAdapter,
+)
+from smallsteps.config_adapter import TOMLConfigAdapter
+from smallsteps.parsing import parse_numeric_input
+from smallsteps.prober import Prober, StaticDateProvider, local_system_date_provider
+from smallsteps.ratchet import (
+    Ratchet,
+    RatchetEvaluationFailure,
+    RatchetEvaluationSuccess,
+)
+
+app = typer.Typer(
+    help="Smallsteps: Monotonic progress tracking and enforcement.",
+    no_args_is_help=True,
+)
+
+DEFAULT_CONFIG_FILE = Path("smallsteps.toml")
+
+
+def resolve_config_path(explicit_path: Path | None) -> Path:
+    if explicit_path is not None:
+        return explicit_path
+    return find_git_root() / DEFAULT_CONFIG_FILE
+
+
+@app.command(name="add")
+def add(
+    name: str = typer.Option(
+        None, "--name", "-n", help="Unique name for your ratchet."
+    ),
+    goal_val: str = typer.Option(
+        None, "--goal", "-g", help="Goal value (e.g. .9 or 250)."
+    ),
+    command_str: str = typer.Option(
+        None, "--command", "-cmd", help="Shell command to compute the value."
+    ),
+    end_date: datetime | None = typer.Option(
+        None, "--end", "-e", help="Ratchet goal end date (YYYY-MM-DD)."
+    ),
+    config: Path | None = typer.Option(
+        None, "--config", "-c", help="Custom path to config file."
+    ),
+):
+    """Adds a ratchet to your configuration (Auto-creates smallsteps.toml if missing)."""
+    config_path = resolve_config_path(config)
+    config_adapter = TOMLConfigAdapter()
+
+    # 1. Collect or prompt for the name first
+    final_name = name or typer.prompt("Ratchet name (e.g., Test Coverage)")
+
+    existing_ratchets = config_adapter.load(config_path)
+    if any(r.name == final_name for r in existing_ratchets):
+        typer.secho(
+            f"❌ A ratchet named '{final_name}' already exists.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    # 2. Ask for command and use it for baseline
+    final_cmd = command_str or typer.prompt(
+        "Shell command to compute the ratchet value"
+    )
+    typer.echo("Running command to establish live baseline value...")
+    runner = OSCommandRunner()
+    try:
+        # Create a temporary Ratchet instance to satisfy our runner protocol
+        temp_ratchet = Ratchet(
+            name=final_name,
+            start=date.today(),
+            end=date.today(),
+            initial_value=0,
+            goal_value=100,
+            command=final_cmd,
+        )
+        discovered_baseline = runner(temp_ratchet)
+
+    except Exception as e:
+        typer.secho(
+            f"❌ Failed to calculate baseline using that command.\nError: {e}",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    typer.echo(f"Live baseline discovered: {discovered_baseline:.2f}")
+    # 3. Ask for the Goal
+    raw_goal = goal_val or typer.prompt(
+        f"What is your goal value? (Current: {discovered_baseline})"
+    )
+
+    try:
+        final_goal = parse_numeric_input(raw_goal)
+    except ValueError as e:
+        typer.secho(f"❌ Invalid goal value: {e}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+    # 4. Handle Target Goal Date
+    if end_date:
+        final_end_date = end_date.date()
+    else:
+        goal_date_str = typer.prompt(
+            f"What is the end date by which the goal must be met? (YYYY-MM-DD, e.g. in 30 days its {(date.today() + timedelta(days=30)).isoformat()} ) ",
+        )
+        try:
+            final_end_date = date.fromisoformat(goal_date_str)
+        except ValueError:
+            typer.secho(
+                f"❌ Invalid date format '{goal_date_str}'. Please use YYYY-MM-DD.",
+                fg=typer.colors.RED,
+                err=True,
+            )
+            raise typer.Exit(code=1)
+
+    # 5. Construct Ratchet
+    try:
+        validated_ratchet = Ratchet(
+            name=final_name,
+            start=date.today(),
+            end=final_end_date,
+            initial_value=discovered_baseline,
+            goal_value=final_goal,
+            command=final_cmd,
+        )
+    except Exception as e:
+        typer.secho(
+            f"❌ Ratchet validation failed:\n{e}", fg=typer.colors.RED, err=True
+        )
+        raise typer.Exit(code=1)
+
+    # 6. Write
+    config_adapter.append(config_path, validated_ratchet)
+    typer.secho(
+        f"✨ Successfully added '{validated_ratchet.name}' to {config_path.name}!",
+        fg=typer.colors.GREEN,
+    )
+
+
+@app.command(name="check")
+def check(
+    date: datetime | None = typer.Option(
+        None,
+        "--date",
+        "-d",
+        help="Timetravel to a specific date to check your ratchets at.",
+    ),
+    config: Path | None = typer.Option(None, "--config", "-c"),
+):
+    """Evaluates all ratchets and enforces progress."""
+    config_path = resolve_config_path(config)
+    config_adapter = TOMLConfigAdapter()
+
+    try:
+        ratchets = config_adapter.load(config_path)
+    except RuntimeError as e:
+        typer.secho(str(e), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+    if not ratchets:
+        typer.secho(
+            f"No active ratchets found in {config_path.name}.",
+            fg=typer.colors.YELLOW,
+        )
+        return
+
+    # Wire up runner & prober pipeline
+    runner_with_lookup = CommandRunnerWithEnvLookUp(
+        env_adapter=OSEnvAdapter(), command_runner=OSCommandRunner()
+    )
+    date_provider = (
+        StaticDateProvider(date.date()) if date else local_system_date_provider
+    )
+    prober = Prober(command_runner=runner_with_lookup, date_provider=date_provider)
+
+    any_failed = False
+    typer.echo(f"Evaluating {len(ratchets)} ratchet(s)...\n")
+
+    for ratchet in ratchets:
+        eval_result = prober.probe(ratchet)
+
+        match eval_result:
+            # TRACK 1: Metric is completely healthy and on track
+            case RatchetEvaluationSuccess(is_healthy=True) as success:
+                typer.secho(
+                    f"{ratchet.name}: ON TRACK "
+                    f"(Current: {success.current_value:.2f}, Expected Min: {success.expected_value:.2f})",
+                    fg=typer.colors.GREEN,
+                )
+
+            # TRACK 2: Command executed fine, but progress dropped below expected target bounds
+            case RatchetEvaluationSuccess(is_healthy=False) as below:
+                any_failed = True
+                typer.secho(
+                    f"{ratchet.name}: BEHIND "
+                    f"(Current: {below.current_value:.2f}, Expected Min: {below.expected_value:.2f})",
+                    fg=typer.colors.RED,
+                )
+
+            # TRACK 3: Underlying shell execution exploded completely (command error, timeout, missing binary)
+            case RatchetEvaluationFailure() as failure:
+                any_failed = True
+
+                typer.secho(
+                    f"{ratchet.name} EVALUATION FAILED! \n"
+                    f"Details: {failure.error_message}",
+                    fg=typer.colors.RED,
+                    err=True,
+                )
+
+    if any_failed:
+        typer.echo("\nProgress check failed.")
+        raise typer.Exit(code=1)
+
+    typer.echo("All monitored project metrics are completely healthy.")
+
+
+@app.command(name="ci")
+def ci(
+    overwrite: bool = typer.Option(
+        False,
+        "--overwrite",
+        "-o",
+        help="Force overwrite the action.yml file if it already exists.",
+    ),
+    config: Path | None = typer.Option(
+        None, "--config", "-c", help="Custom path to the smallsteps configuration file."
+    ),
+):
+    """Generates a scaffoling for a github action"""
+    config_path = resolve_config_path(config)
+    config_adapter = TOMLConfigAdapter()
+    ci_adapter = GitHubCIAdapter()
+
+    # 1. Check if the target file destination already exists
+    action_path = Path(".github/actions/smallsteps/action.yml")
+    if action_path.exists() and not overwrite:
+        typer.secho(
+            f"Action manifest already exists at:\n   {action_path.resolve()}\n\n"
+            f"To overwrite this file, re-run this command with the overwrite flag:\n"
+            f"uv run smallsteps ci --overwrite",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    # 2. Extract configuration records
+    try:
+        ratchets = config_adapter.load(config_path)
+    except RuntimeError as e:
+        typer.secho(str(e), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+    # 3. Process layout formatting maps
+    yaml_content = ci_adapter.generate_action(ratchets)
+
+    # 4. Save out structural changes
+    try:
+        ci_adapter.save(action_path, yaml_content)
+        typer.secho(
+            f"🚀 Custom GitHub Composite Action successfully written to:\n   {action_path}",
+            fg=typer.colors.GREEN,
+        )
+    except Exception as e:
+        typer.secho(str(e), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)