splatfold 0.2.0__tar.gz

splatfold-0.2.0/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to Splatfold will be documented here.
+
+The project follows Semantic Versioning once its public API is released.
+
+## Unreleased
+
+### Changed
+
+- Renamed the project from Obtuse/preprocessor to Splatfold.
+- Added a side-effect-free Python build API and `BuildResult.write()`.
+- Added conventional `__version__` metadata and explicit public exports.
+- Added positional CLI input while retaining `-i` and `--input`.
+- Matched Python's package-before-module import resolution precedence.
+- Kept output writing compatible with Python 3.9.
+- Made output replacement atomic, synchronized file contents before replacement,
+  and preserved existing or input-file permissions.
+- Added Python 3.9-3.14 CI, 90% branch-coverage enforcement, distribution package
+  checks, and a Trusted Publishing release workflow with commit-pinned actions.
+- Added focused macOS and Windows CI jobs to verify the package's
+  operating-system-independent claim.
+- Added Dependabot maintenance for Python tooling and GitHub Actions.
+- Made the wheel smoke test install outside the source checkout so local build
+  metadata cannot masquerade as an installed distribution.
+- Added release-tag/version validation, serialized publishing, artifact
+  presence checks, and an isolated smoke test of the exact release wheel.
+- The release workflow now reruns lint, formatting, tests, and branch coverage
+  against the exact release commit before building publishable artifacts.
+- Checkout credentials are not persisted into CI or release workspaces; the
+  workflows pass a dedicated GitHub Actions security audit.
+- Added a required CI job that continuously enforces the GitHub Actions
+  security audit instead of relying only on manual release review.
+- Documented the Python API result contract, exception hierarchy, filesystem
+  mutation boundary, CLI streams, and exit statuses.
+- Added strict static type checking for the standalone implementation to local,
+  CI, and release quality gates, using the newest mypy line that still models
+  the supported Python 3.9 syntax target.
+- Added full `pyproject.toml` schema, dependency-version, and SPDX license
+  validation to package and release gates.
+- Added wheel-layout validation to local, CI, and release gates.
+- Added an Obtuse-to-Splatfold migration guide covering compatible commands,
+  renamed surfaces, corrected prototype behavior, and the new release model.
+- Defined the supported security release line and explicitly retired copied
+  Obtuse/preprocessor scripts from security support.
+
+### Fixed
+
+- Dependency `__main__` guards with `else` clauses now fail safely instead of
+  silently discarding code that normal imports would execute.
+- Encoding-cookie removal no longer mistakes ordinary first-line source text
+  containing `coding:` for a declaration.
+- Standalone `BuildResult` values now use safe default permissions when no
+  included source path is available.
+- Rewritten wildcard and future imports now reject physical lines shared with
+  other statements instead of silently discarding neighboring code.
+- Future-import hoisting now rejects root docstrings that share their final
+  physical line with another statement.
+- Included files without a final newline no longer join their last statement
+  to the importing file's following source line.
+- Indented comments beginning with `#!` are preserved instead of being
+  mistaken for executable shebang lines.
+- Future features are deduplicated individually even when source files group
+  them into different multi-feature import statements.
+- User-path expansion and resolution failures now use the stable public error
+  hierarchy instead of leaking raw filesystem exceptions.
+- `BuildResult.write()` now revalidates its current source immediately before
+  filesystem mutation, including for directly constructed or modified results.
+- Output protection now detects existing filesystem aliases of included source
+  files instead of relying only on textual path equality.

splatfold-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing
+
+Splatfold keeps its complete runtime implementation in `splatfold.py` so the
+tool itself remains easy to copy and run as one file. Tests, documentation,
+packaging metadata, and automation live beside it.
+
+## Development checks
+
+From this directory, run:
+
+```zsh
+python3 -m pip install -e ".[dev,release]"
+ruff check splatfold.py tests
+ruff format --check splatfold.py tests
+mypy splatfold.py
+python3 -m coverage run -m pytest
+python3 -m coverage report
+uvx zizmor .github/workflows
+python3 -m compileall -q splatfold.py
+validate-pyproject pyproject.toml
+python3 -m build
+python3 -m twine check dist/*
+check-wheel-contents dist/*.whl
+```
+
+Changes to resolution or rendering semantics must include a focused regression
+test. Tests should compare generated behavior with normal Python behavior when
+Splatfold claims equivalence, and should make intentional differences explicit.
+
+Before a release, install the built wheel into a clean virtual environment and
+use that installed CLI—not the source checkout—to fold and run the Acute
+integration fixture.

splatfold-0.2.0/DESIGN.md

@@ -0,0 +1,58 @@
+# Splatfold design contract
+
+Splatfold is a source preprocessor, not an import-system emulator. It gives a
+restricted set of valid Python wildcard imports an additional build-time
+meaning: include the referenced local source once at the import location.
+
+## Invariants
+
+1. Development sources remain valid Python and continue to work without
+   Splatfold when their ordinary imports are valid.
+2. Project source is read and parsed, never imported or executed during a
+   build.
+3. Only module-level `from ... import *` statements are candidates for local
+   inclusion. Every other import is preserved.
+4. A source file is emitted at most once. Active recursion edges are reported
+   as cycles and omitted from the generated module.
+5. The generated source is UTF-8 and is compiled for syntax validity both when
+   built and immediately before it can be written.
+6. Writing is explicit in the Python API and atomic with respect to the final
+   destination path.
+7. The input and every included source path are protected from accidental
+   output overwrite, including filesystem aliases of the same file.
+8. The implementation remains a standalone standard-library-only Python file.
+
+## Resolution
+
+Absolute imports are searched in `root` followed by each configured search
+path. Relative imports are resolved from the importing file. On each path
+entry, `name/__init__.py` takes precedence over `name.py`, matching Python.
+
+An unresolved wildcard import is preserved by default because it may refer to
+the standard library or an installed dependency. Strict mode rejects it.
+
+## Rendering
+
+Inclusion is depth-first at the original import location. Dependency shebangs
+and encoding cookies are removed. The root shebang is retained and the output
+declares UTF-8. Future imports are deduplicated and hoisted after the root
+module docstring.
+
+Conventional dependency `if __name__ == "__main__":` blocks without `else`
+are removed by default. A guard with `else` is rejected because deleting the
+whole statement would discard code that normal importing executes.
+
+Statements that Splatfold removes or replaces must occupy their own physical
+lines. A trailing comment is allowed. Sharing such a line with another Python
+statement is rejected explicitly rather than risking silent loss of code.
+
+## Intentional limits
+
+All included definitions share one global namespace. Per-module values of
+`__name__`, `__package__`, `__file__`, module dictionaries, `sys.modules`
+entries, import hooks, and initialization isolation are not reproduced.
+`__all__` remains ordinary source metadata but does not hide code that has been
+physically included.
+
+These limits are fundamental to source folding and must remain visible in user
+documentation and tests.

splatfold-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WithoutSophie
+
+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.

splatfold-0.2.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include CHANGELOG.md
+include CONTRIBUTING.md
+include DESIGN.md
+include LICENSE
+include MIGRATING.md
+include RELEASING.md
+include SECURITY.md
+include readme.md
+recursive-include tests *.py

splatfold-0.2.0/MIGRATING.md

@@ -0,0 +1,66 @@
+# Migrating from Obtuse
+
+Splatfold is the production continuation of the project previously published
+on GitHub as **Obtuse**. It keeps the wildcard-include model while replacing
+the prototype's script-only release process with a tested Python distribution.
+
+## Source compatibility
+
+Existing module-level directives remain valid:
+
+```python
+from module import *
+from package.module import *
+from .local import *
+```
+
+The original `-i` and `--input` CLI forms remain supported, along with the
+output, root, search-path, strictness, marker, tracing, dependency-listing, and
+check-only behavior. The preferred form now uses a positional input:
+
+```zsh
+splatfold main.py -o dist/app.py
+```
+
+## Names that changed
+
+- The command and standalone implementation are now named `splatfold` and
+  `splatfold.py`; no `preprocessor` or `obtuse` package is installed.
+- Generated comments identify `splatfold` instead of the prototype script.
+- The importable API is `splatfold.build(...)`, returning a `BuildResult` whose
+  `write()` method performs the explicit filesystem mutation.
+
+Code that invokes an old checkout as `python3 preprocessor.py ...` should
+install Splatfold and invoke the `splatfold` console command instead. Existing
+automation may keep `-i/--input` while migrating.
+
+## Intentional safety changes
+
+Several prototype behaviors were bugs and are not preserved:
+
+- When `name.py` and `name/__init__.py` coexist on one search entry, the
+  package now wins, matching Python's import system.
+- A dependency `if __name__ == "__main__": ... else: ...` is rejected unless
+  `--keep-main-guards` is requested; the prototype silently discarded the
+  import-time `else` branch.
+- Wildcard and future imports that share a physical line with another Python
+  statement are rejected instead of silently deleting neighboring code.
+- Output writes work on Python 3.9, are atomic, preserve appropriate file
+  permissions, and refuse to overwrite any included source.
+- Future features are deduplicated individually and included files missing a
+  final newline cannot merge with the importing file's next statement.
+
+These changes favor explicit failure over generating code with altered
+semantics. Projects relying on a rejected edge case should first rewrite the
+source into ordinary multi-line Python; `--keep-main-guards` is available only
+when literal guard inclusion is genuinely intended.
+
+## Release and packaging changes
+
+Splatfold requires Python 3.9 or newer and has no runtime dependencies outside
+the standard library. Releases provide both a universal wheel and source
+distribution. The version is available as `splatfold.__version__`, and the CLI
+reports the same value with `splatfold --version`.
+
+PyPI publication uses GitHub OIDC Trusted Publishing. The obsolete Obtuse
+workflow and long-lived upload tokens must not be reused.