Release hygiene, typed package, CI matrix, property laws, docs

.github/workflows/ci.yml

@@ -1,15 +1,23 @@
 name: CI
-on: [push, pull_request]
+on:
+  push:
+    branches: ["main"]
+    tags: ["v*"]
+  pull_request:
+    branches: ["main"]
 
 jobs:
   test:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          python-version: "${{ matrix.python-version }}"
       - run: pip install poetry
-      - run: poetry install
-      - run: poetry run pytest -v --cov=darkcore
+      - run: poetry install --with dev
+      - run: poetry run pytest -q
       - run: poetry run mypy --strict darkcore

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 minamorl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -89,6 +89,19 @@ print(v)  # Failure(['non-positive', 'non-positive'])
 
 Validation is primarily intended for Applicative composition; `bind` short-circuits like `Result` and is not recommended for error accumulation scenarios.
 
+### Choosing between `Result`, `Either`, and `Validation`
+
+| Type       | Error shape            | Behavior on bind (`>>`) | Best use case                          |
+|------------|------------------------|--------------------------|----------------------------------------|
+| `Result`   | Typically string/Exception-like | Short-circuits          | IO boundaries, failing effects         |
+| `Either`   | Domain-typed error     | Short-circuits          | Domain errors with rich types          |
+| `Validation` | Accumulates via Applicative | **Short-circuits monadically** | Form-style multi-error accumulation    |
+
+> Note: `Validation` accumulates errors in `Applicative` flows (`@` / `ap`, `traverse`, `sequence_*`), but *monadically* (`>>`) it short-circuits.
+
+### Equality of `ReaderT` / `StateT`
+These transformers represent computations. Equality is **extensional**: compare results of `run` under the same environment/state, not object identity.
+
 ---
 
 ### Reader

darkcore/reader_t.py

@@ -1,3 +1,7 @@
+"""ReaderT monad transformer.
+
+Equality is extensional. Compare outputs of `run` on same inputs.
+"""
 from __future__ import annotations
 from typing import Callable, Generic, TypeVar
 from .core import Monad as MonadLike  # Protocol として使う

darkcore/state_t.py

@@ -1,3 +1,7 @@
+"""StateT monad transformer.
+
+Equality is extensional. Compare outputs of `run` on same inputs.
+"""
 from __future__ import annotations
 from typing import Callable, Generic, TypeVar, Any, cast
 from .core import Monad

pyproject.toml

@@ -1,16 +1,18 @@
 [tool.poetry]
 name = "darkcore"
-version = "0.5.0"
+version = "0.5.1"
 description = "Practical functional programming primitives for Python: Monads, Transformers, and DSL operators for safe business logic"
 authors = ["minamorl <minamorl@users.noreply.github.com>"]
 license = "MIT"
 readme = "README.md"
 repository = "https://github.com/minamorl/darkcore"
 homepage = "https://github.com/minamorl/darkcore"
 keywords = ["monad", "functional", "dsl", "business logic"]
+packages = [{ include = "darkcore" }]
+include = ["darkcore/py.typed"]
 
 [tool.poetry.dependencies]
-python = "^3.12"
+python = ">=3.10,<3.13"
 
 
 [tool.poetry.group.dev.dependencies]

tests/test_laws_property_based.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from hypothesis import given, strategies as st
+
+from darkcore.maybe import Maybe
+from darkcore.result import Ok
+from darkcore.validation import Success
+
+
+@given(st.integers())
+def test_functor_identity_maybe(x: int) -> None:
+    m = Maybe(x)
+    assert (m | (lambda v: v)) == m
+
+
+@given(st.integers())
+def test_monad_associativity_result(x: int) -> None:
+    r = Ok(x)
+    f = lambda a: Ok(a + 1)
+    g = lambda a: Ok(a * 2)
+    assert ((r >> f) >> g) == (r >> (lambda a: f(a) >> g))
+
+
+@given(st.integers(), st.integers(), st.integers())
+def test_applicative_composition_validation(x: int, y: int, z: int) -> None:
+    u = Success(lambda b: b + x)
+    v = Success(lambda a: a * y)
+    w = Success(z)
+    compose = lambda f: lambda g: lambda a: f(g(a))
+    left = Success(compose) @ u @ v @ w
+    right = u @ (v @ w)
+    assert left == right