elspais 0.9.1__tar.gz

elspais-0.9.1/.gitignore

@@ -0,0 +1,76 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# OS
+.DS_Store
+Thumbs.db

elspais-0.9.1/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to elspais will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.9.1] - 2026-01-03
+
+### Changed
+- Updated CLAUDE.md with complete architecture documentation
+- Added testing/, mcp/, and content_rules modules to CLAUDE.md
+- Added ParseResult API design pattern documentation
+- Added Workflow section with contribution guidelines
+- Updated Python version reference from 3.8+ to 3.9+
+
+## [0.9.0] - 2026-01-03
+
+### Added
+- Test mapping and coverage functionality (`elspais.testing` module)
+  - `TestScanner`: Scans test files for requirement references
+  - `ResultParser`: Parses JUnit XML and pytest JSON test results
+  - `TestMapper`: Orchestrates scanning and result mapping
+- Parser resilience with `ParseResult` API and warning system
+  - Parser now returns `ParseResult` containing both requirements and warnings
+  - Non-fatal issues generate warnings instead of failing parsing
+
+## [0.2.1] - 2025-12-28
+
+### Changed
+- Renamed "sponsor" to "associated" throughout the codebase
+  - Config: `[sponsor]` → `[associated]`, `[patterns.sponsor]` → `[patterns.associated]`
+  - CLI: `--sponsor-prefix` → `--associated-prefix`, `--type sponsor` → `--type associated`
+  - ID template: `{sponsor}` → `{associated}`
+- Made the tool generic by removing standards-specific references
+- Updated documentation to use neutral terminology
+
+## [0.2.0] - 2025-12-28
+
+### Added
+- Multi-directory spec support: `spec = ["spec", "spec/roadmap"]`
+- Generic `get_directories()` function for any config key
+- Recursive directory scanning for code directories
+- `get_code_directories()` convenience function with auto-recursion
+- `ignore` config for excluding directories (node_modules, .git, etc.)
+- Configurable `no_reference_values` for Implements field (-, null, none, N/A)
+- `parse_directories()` method for parsing multiple spec directories
+- `skip_files` config support across all commands
+
+### Fixed
+- Body extraction now matches hht-diary behavior (includes Rationale/Acceptance)
+- Hash calculation strips trailing whitespace for consistency
+- skip_files config now properly passed to parser in all commands
+
+## [0.1.0] - 2025-12-27
+
+### Added
+- Initial release of elspais requirements validation tools
+- Configurable requirement ID patterns (REQ-p00001, PRD-00001, PROJ-123, etc.)
+- Configurable validation rules with hierarchy enforcement
+- TOML-based per-repository configuration (.elspais.toml)
+- CLI commands: validate, trace, hash, index, analyze, init
+- Multi-repository support (core/associated model)
+- Traceability matrix generation (Markdown, HTML, CSV)
+- Hash-based change detection for requirements
+- Zero external dependencies (Python 3.8+ standard library only)
+- Core requirement parsing and validation
+- Pattern matching for multiple ID formats
+- Rule engine for hierarchy validation
+- Configuration system with sensible defaults
+- Test fixtures for multiple requirement formats
+- Comprehensive documentation

elspais-0.9.1/LICENSE

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

elspais-0.9.1/PKG-INFO

@@ -0,0 +1,393 @@
+Metadata-Version: 2.1
+Name: elspais
+Version: 0.9.1
+Summary: Requirements validation and traceability tools - L-Space connects all libraries
+Home-page: https://github.com/anspar/elspais
+Author: Anspar
+Author-email: dev@anspar.io
+License: MIT
+Project-URL: Documentation, https://github.com/anspar/elspais#readme
+Project-URL: Repository, https://github.com/anspar/elspais
+Project-URL: Issues, https://github.com/anspar/elspais/issues
+Project-URL: Changelog, https://github.com/anspar/elspais/blob/main/CHANGELOG.md
+Keywords: documentation,requirements,specifications,traceability,validation
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: binary
+Requires-Dist: pyinstaller>=6.0; extra == 'binary'
+Provides-Extra: dev
+Requires-Dist: black>=23.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# elspais
+
+> "L-Space is the ultimate library, connecting all libraries everywhere through the sheer weight of accumulated knowledge."
+> — Terry Pratchett
+
+**elspais** is a requirements validation and traceability tool that helps teams manage formal requirements across single or multiple repositories. It supports configurable ID patterns, validation rules, and generates traceability matrices.
+
+## Features
+
+- **Zero Dependencies**: Core CLI uses only Python 3.9+ standard library
+- **Configurable ID Patterns**: Support for `REQ-p00001`, `PRD-00001`, `PROJ-123`, named requirements, and custom formats
+- **Validation Rules**: Enforce requirement hierarchies (PRD → OPS → DEV) with configurable constraints
+- **Multi-Repository**: Link requirements across core and associated repositories
+- **Traceability Matrices**: Generate Markdown, HTML, or CSV output
+- **Hash-Based Change Detection**: Track requirement changes with SHA-256 hashes
+- **Content Rules**: Define semantic validation guidelines for AI agents
+- **MCP Server**: Integrate with AI assistants via Model Context Protocol
+
+## Installation
+
+```bash
+pip install elspais
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/anspar/elspais.git
+cd elspais
+pip install -e .
+```
+
+## Quick Start
+
+### Initialize a Repository
+
+```bash
+# Create .elspais.toml with default configuration
+elspais init
+
+# Or specify repository type
+elspais init --type core              # Core repository
+elspais init --type associated --associated-prefix CAL  # Associated repo
+```
+
+### Validate Requirements
+
+```bash
+# Validate all requirements in spec/ directory
+elspais validate
+
+# Verbose output
+elspais validate -v
+
+# Validate with auto-fix for fixable issues
+elspais validate --fix
+```
+
+### Generate Traceability Matrix
+
+```bash
+# Generate both Markdown and HTML
+elspais trace
+
+# Generate specific format
+elspais trace --format html
+elspais trace --format csv
+
+# Custom output location
+elspais trace --output docs/traceability.html
+```
+
+### Manage Requirement Hashes
+
+```bash
+# Verify all hashes match content
+elspais hash verify
+
+# Update all hashes
+elspais hash update
+
+# Update specific requirement
+elspais hash update REQ-d00027
+```
+
+### Analyze Requirements
+
+```bash
+# Show requirement hierarchy tree
+elspais analyze hierarchy
+
+# Find orphaned requirements
+elspais analyze orphans
+
+# Implementation coverage report
+elspais analyze coverage
+```
+
+## Configuration
+
+Create `.elspais.toml` in your repository root:
+
+```toml
+[project]
+name = "my-project"
+type = "core"  # "core" | "associated"
+
+[directories]
+spec = "spec"
+docs = "docs"
+code = ["src", "apps", "packages"]
+
+[patterns]
+id_template = "{prefix}-{type}{id}"
+prefix = "REQ"
+
+[patterns.types]
+prd = { id = "p", name = "Product Requirement", level = 1 }
+ops = { id = "o", name = "Operations Requirement", level = 2 }
+dev = { id = "d", name = "Development Requirement", level = 3 }
+
+[patterns.id_format]
+style = "numeric"
+digits = 5
+leading_zeros = true
+
+[rules.hierarchy]
+allowed_implements = [
+    "dev -> ops, prd",
+    "ops -> prd",
+    "prd -> prd",
+]
+allow_circular = false
+allow_orphans = false
+
+[rules.format]
+require_hash = true
+require_assertions = true
+allowed_statuses = ["Active", "Draft", "Deprecated", "Superseded"]
+```
+
+See [docs/configuration.md](docs/configuration.md) for full reference.
+
+## Requirement Format
+
+elspais expects requirements in Markdown format:
+
+```markdown
+### REQ-d00001: Requirement Title
+
+**Level**: Dev | **Implements**: p00001 | **Status**: Active
+
+The system SHALL provide user authentication.
+
+**Rationale**: Security requires identity verification.
+
+**Acceptance Criteria**:
+- Users can log in with email/password
+- Session expires after 30 minutes of inactivity
+
+*End* *Requirement Title* | **Hash**: a1b2c3d4
+---
+```
+
+## ID Pattern Examples
+
+elspais supports multiple ID formats:
+
+| Pattern | Example | Configuration |
+|---------|---------|---------------|
+| HHT Default | `REQ-p00001` | `id_template = "{prefix}-{type}{id}"` |
+| Type-Prefix | `PRD-00001` | `id_template = "{type}-{id}"` |
+| Jira-Like | `PROJ-123` | `id_template = "{prefix}-{id}"` |
+| Named | `REQ-UserAuth` | `style = "named"` |
+| Associated | `REQ-CAL-d00001` | `associated.enabled = true` |
+
+See [docs/patterns.md](docs/patterns.md) for details.
+
+## Multi-Repository Support
+
+For associated repositories that reference a core repository:
+
+```toml
+[project]
+type = "associated"
+
+[associated]
+prefix = "CAL"
+
+[core]
+path = "../core-repo"
+```
+
+Validate with core linking:
+
+```bash
+elspais validate --core-repo ../core-repo
+```
+
+## Content Rules
+
+Content rules are markdown files that provide semantic validation guidance for AI agents authoring requirements:
+
+```bash
+# Configure content rules
+elspais config add rules.content_rules "spec/AI-AGENT.md"
+
+# List configured rules
+elspais rules list
+
+# View a specific rule
+elspais rules show AI-AGENT.md
+```
+
+Content rule files can include YAML frontmatter for metadata:
+
+```markdown
+---
+title: AI Agent Guidelines
+type: guidance
+applies_to: [requirements, assertions]
+---
+
+# AI Agent Guidelines
+
+- Use SHALL for normative statements
+- One assertion per obligation
+- No duplication across levels
+```
+
+## MCP Server (AI Integration)
+
+elspais includes an MCP (Model Context Protocol) server for AI assistant integration:
+
+```bash
+# Install with MCP support
+pip install elspais[mcp]
+
+# Start MCP server
+elspais mcp serve
+```
+
+Configure in Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "elspais": {
+      "command": "elspais",
+      "args": ["mcp", "serve"],
+      "cwd": "/path/to/your/project"
+    }
+  }
+}
+```
+
+### MCP Resources
+
+| Resource | Description |
+|----------|-------------|
+| `requirements://all` | List all requirements |
+| `requirements://{id}` | Get requirement details |
+| `requirements://level/{level}` | Filter by PRD/OPS/DEV |
+| `content-rules://list` | List content rules |
+| `content-rules://{file}` | Get content rule content |
+| `config://current` | Current configuration |
+
+### MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `validate` | Run validation rules |
+| `parse_requirement` | Parse requirement text |
+| `search` | Search requirements |
+| `get_requirement` | Get requirement details |
+| `analyze` | Analyze hierarchy/orphans/coverage |
+
+## CLI Reference
+
+```
+elspais [OPTIONS] COMMAND [ARGS]
+
+Options:
+  --config PATH    Path to config file
+  --spec-dir PATH  Override spec directory
+  -v, --verbose    Verbose output
+  -q, --quiet      Suppress non-error output
+  --version        Show version
+  --help           Show help
+
+Commands:
+  validate   Validate requirements format, links, hashes
+  trace      Generate traceability matrix
+  hash       Manage requirement hashes (verify, update)
+  index      Validate or regenerate INDEX.md
+  analyze    Analyze requirement hierarchy
+  edit       Edit requirements in-place (status, implements, move)
+  config     View and modify configuration
+  rules      View and manage content rules
+  mcp        MCP server commands (requires elspais[mcp])
+  version    Show version and check for updates
+  init       Create .elspais.toml configuration
+```
+
+## Development
+
+```bash
+# Clone and install in development mode
+git clone https://github.com/anspar/elspais.git
+cd elspais
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run with coverage
+pytest --cov=elspais
+
+# Type checking
+mypy src/elspais
+
+# Linting
+ruff check src/elspais
+black --check src/elspais
+```
+
+## Version Pinning
+
+For reproducible builds, pin the version in your project:
+
+```bash
+# .github/versions.env
+ELSPAIS_VERSION=0.1.0
+```
+
+```yaml
+# GitHub Actions
+- name: Install elspais
+  run: pip install elspais==${{ env.ELSPAIS_VERSION }}
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Contributions welcome! Please read the contributing guidelines before submitting PRs.
+
+## Links
+
+- [Documentation](https://github.com/anspar/elspais#readme)
+- [Issue Tracker](https://github.com/anspar/elspais/issues)
+- [Changelog](CHANGELOG.md)