ster 0.1.0__tar.gz

ster-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,98 @@
+name: CI
+
+on:
+  push:
+    branches: ["master", "main"]
+  pull_request:
+    branches: ["master", "main"]
+
+# Cancel any in-progress run for the same branch / PR
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+# ── Jobs run in parallel; 'test' is the only matrix job ───────────────────────
+
+jobs:
+
+  # ── 1. Lint & format ────────────────────────────────────────────────────────
+  lint:
+    name: Lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Install ruff
+        run: uv tool install ruff
+
+      - name: ruff — check rules
+        run: ruff check .
+
+      - name: ruff — check formatting
+        run: ruff format --check .
+
+  # ── 2. Static type checking ──────────────────────────────────────────────────
+  typecheck:
+    name: Type check (mypy)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Install deps
+        run: uv sync --extra html --extra dev
+
+      - name: mypy
+        run: uv run mypy ster/
+
+  # ── 3. Security ──────────────────────────────────────────────────────────────
+  security:
+    name: Security (bandit + pip-audit)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Install deps
+        run: uv sync --extra html --extra dev
+
+      - name: bandit — static analysis
+        run: uv run bandit -r ster/ -c pyproject.toml
+
+      - name: pip-audit — dependency CVEs
+        run: uv run pip-audit
+
+  # ── 4. Tests + coverage ──────────────────────────────────────────────────────
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install deps
+        run: uv sync --extra html --extra dev
+
+      - name: Run tests with coverage
+        run: uv run pytest --tb=short -q --cov=ster --cov-report=xml --cov-report=term-missing
+
+      - name: Upload coverage to Codecov
+        # Upload only once (latest Python) to avoid duplicate reports
+        if: matrix.python-version == '3.13'
+        uses: codecov/codecov-action@v4
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false   # don't break CI if Codecov is unreachable
+          token: ${{ secrets.CODECOV_TOKEN }}

ster-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,48 @@
+name: Publish to PyPI
+
+# Trigger: push a tag like v0.1.0
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Store distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+
+    # Trusted Publisher — configure once on pypi.org, no token secret needed
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ster
+    permissions:
+      id-token: write  # required for OIDC
+
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ster-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.coverage
+htmlcov/
+*.egg

ster-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+# Pre-commit hooks — mirrors the CI lint job so issues are caught locally.
+# Install once:  pip install pre-commit && pre-commit install
+# Run manually:  pre-commit run --all-files
+
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.4
+    hooks:
+      - id: ruff              # linting
+        args: [--fix]
+      - id: ruff-format       # formatting
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: debug-statements   # catch leftover breakpoint() / pdb calls

ster-0.1.0/LICENSE

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

ster-0.1.0/PKG-INFO

@@ -0,0 +1,307 @@
+Metadata-Version: 2.4
+Name: ster
+Version: 0.1.0
+Summary: Interactive terminal editor for SKOS taxonomy files
+Project-URL: Homepage, https://github.com/gbelbe/ster
+Project-URL: Repository, https://github.com/gbelbe/ster
+Project-URL: Issues, https://github.com/gbelbe/ster/issues
+License: MIT License
+        
+        Copyright (c) 2024 gbelbe
+        
+        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.
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: rdflib>=7.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Provides-Extra: all
+Requires-Dist: bandit[toml]>=1.7; extra == 'all'
+Requires-Dist: coverage[toml]>=7.0; extra == 'all'
+Requires-Dist: mypy>=1.10; extra == 'all'
+Requires-Dist: pip-audit>=2.7; extra == 'all'
+Requires-Dist: pylode>=3.0; extra == 'all'
+Requires-Dist: pytest-cov>=5.0; extra == 'all'
+Requires-Dist: pytest>=8.0; extra == 'all'
+Requires-Dist: ruff>=0.4; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: bandit[toml]>=1.7; extra == 'dev'
+Requires-Dist: coverage[toml]>=7.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pip-audit>=2.7; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: html
+Requires-Dist: pylode>=3.0; extra == 'html'
+Description-Content-Type: text/markdown
+
+# ster
+
+[![CI](https://github.com/gbelbe/ster/actions/workflows/ci.yml/badge.svg)](https://github.com/gbelbe/ster/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/gbelbe/ster/graph/badge.svg)](https://codecov.io/gh/gbelbe/ster)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+[![rdflib](https://img.shields.io/pypi/v/rdflib?label=rdflib&color=orange)](https://pypi.org/project/rdflib/)
+[![typer](https://img.shields.io/pypi/v/typer?label=typer&color=brightgreen)](https://pypi.org/project/typer/)
+[![rich](https://img.shields.io/pypi/v/rich?label=rich&color=purple)](https://pypi.org/project/rich/)
+[![pylode](https://img.shields.io/pypi/v/pylode?label=pylode+%5Boptional%5D&color=blue)](https://pypi.org/project/pylode/)
+
+```
+   _____ ______ ______ ____
+  / ___//_  __// ____// __ \
+  \__ \  / /  / __/  / /_/ /
+ ___/ / / /  / /___ / _, _/
+/____/ /_/  /_____//_/ |_|
+
+  [ Breton: "Meaning" or "Sense" ]
+  [  Simple Taxonomy EditoR     ]
+```
+
+**ster** is an interactive terminal editor for [SKOS](https://www.w3.org/TR/skos-reference/) taxonomy files.
+Browse, create, and edit concepts in a full-screen TUI — no GUI, no database, just clean Turtle files.
+
+> *ster* is the Breton word for *meaning*, with homonyms for *river* and *star*.
+> Let it guide your semantic voyage, keeping the flow and always following your star.
+
+---
+
+## Features
+
+### Interactive TUI
+- Full-screen tree browser with keyboard navigation
+- Inline concept creation, renaming, deletion, and label editing
+- Detail panel: view and edit all SKOS fields (labels, definitions, scope notes, related links…)
+- Fold / unfold subtrees; shows hidden-concept count
+- Visual `⇔` indicator for concepts that carry cross-scheme mapping links
+
+### Multi-file workspace
+- Open several `.ttl` files at once and see a merged taxonomy view
+- Edits are always written to the correct source file automatically
+
+### Cross-scheme mapping
+- Add `exactMatch`, `closeMatch`, `broadMatch`, `narrowMatch`, `relatedMatch` links between concepts in different files
+- Remove links from the detail view — works even when the target file has been deleted
+- Both source and target files are saved and staged in git on every change
+
+### Git integration
+- Stage, commit, and push changes without leaving the terminal
+- Browse full commit history with diffs inside the TUI
+
+### HTML export
+- Generate a browsable, wiki-style HTML page from any taxonomy via [pyLODE](https://github.com/RDFLib/pyLODE)
+- One HTML file per language detected in the taxonomy
+- Sticky language-switcher bar links between language versions
+- Available from the main menu or `ster export`
+
+### Other
+- Step-by-step **init wizard** (`ster init`)
+- Auto-detection of taxonomy files in the current directory
+- Round-trip safe: reads and writes `.ttl`, `.rdf`, `.jsonld`
+- SKOS integrity validation
+
+---
+
+## Installation
+
+### Minimal (TUI + editing)
+
+```bash
+pip install ster
+```
+
+### With HTML export
+
+```bash
+pip install "ster[html]"
+```
+
+### From source
+
+```bash
+git clone https://github.com/gbelbe/ster.git
+cd ster
+pip install -e .          # core only
+pip install -e ".[html]"  # with HTML export
+pip install -e ".[dev]"   # with test suite
+```
+
+---
+
+## Dependencies
+
+| Group | Package | Purpose |
+|---|---|---|
+| core | `rdflib>=7.0` | RDF parsing and serialisation |
+| core | `typer[all]>=0.12` | CLI framework |
+| core | `rich>=13.0` | Terminal rendering, prompts, tables |
+| `[html]` | `pylode>=3.0` | HTML generation from SKOS (VocPub profile) |
+| `[dev]` | `pytest>=8.0` | Test suite |
+| `[dev]` | `pytest-cov>=5.0` | Coverage reporting |
+
+pyLODE is **not** installed by default. When you trigger an HTML export, ster will offer to install it automatically.
+
+---
+
+## Quick start
+
+### Launch the interactive editor
+
+```bash
+ster
+```
+
+The home screen lists all taxonomy files in the current directory. Use arrow keys to check files, then press **Enter** to open them.
+
+```
+  ┌─────────────────────────────────────────────────────┐
+  │  [ ] equipement.ttl          7 concepts             │
+  │  [x] windvane-taxonomy.ttl  23 concepts             │
+  └─────────────────────────────────────────────────────┘
+  ↵  Open checked files
+  ⎇  Browse git history
+  🌐 Generate webpage
+  +  Create new taxonomy
+  ✕  Quit
+```
+
+### Keyboard shortcuts (TUI)
+
+| Key | Action |
+|---|---|
+| `↑` `↓` | Navigate tree / fields |
+| `Enter` | Expand/collapse node or open detail |
+| `a` | Add a child concept |
+| `A` | Add a top-level concept |
+| `d` | Delete selected concept |
+| `e` | Edit selected field in detail panel |
+| `m` | Add a mapping link to another concept |
+| `g` | Commit & push changes |
+| `?` | Help screen |
+| `q` / `Esc` | Back / quit |
+
+### Create a new taxonomy
+
+```bash
+ster init my-taxonomy.ttl
+```
+
+The wizard walks you through name, description, base URI, languages, and author.
+
+### Export to HTML
+
+```bash
+ster export my-taxonomy.ttl          # generates ./html/my-taxonomy_en.html …
+ster export my-taxonomy.ttl -l en,fr # specific languages only
+ster export my-taxonomy.ttl -o /tmp  # custom output directory
+```
+
+Or use the **🌐 Generate webpage** option from the main menu.
+
+### Validate
+
+```bash
+ster validate my-taxonomy.ttl
+```
+
+---
+
+## Architecture
+
+```
+ster/
+├── model.py         — Pure dataclasses: Concept, ConceptScheme, Taxonomy
+├── store.py         — RDF I/O via rdflib (.ttl / .rdf / .jsonld)
+├── operations.py    — All SKOS mutations (add, remove, move, relate…)
+├── workspace.py     — Multi-file workspace: merged view + per-file saves
+├── workspace_ops.py — Cross-file mapping operations
+├── nav.py           — Full-screen TUI (curses): tree, detail, inline edit
+├── cli.py           — Typer entry-points (ster, ster init, ster export…)
+├── html_export.py   — HTML generation via pyLODE VocPub
+├── git_manager.py   — Git staging, commit, push
+├── git_log.py       — Git history browser (TUI)
+├── wizard.py        — Init wizard
+├── handles.py       — Short handle generation from camelCase URIs
+└── validator.py     — SKOS integrity checks
+```
+
+Each layer depends only on the layers below it, keeping every module independently testable.
+
+---
+
+## Supported formats
+
+| Extension | Format |
+|---|---|
+| `.ttl` | Turtle (recommended) |
+| `.rdf` / `.xml` | RDF/XML |
+| `.jsonld` / `.json` | JSON-LD |
+
+---
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+pytest --cov=ster --cov-report=term-missing
+```
+
+---
+
+## CI / CD
+
+Every push and pull request runs four parallel jobs via GitHub Actions:
+
+| Job | Tool | What it checks |
+|---|---|---|
+| **Lint** | [ruff](https://docs.astral.sh/ruff/) | Code style, import order, common bugs |
+| **Type check** | [mypy](https://mypy.readthedocs.io/) | Static type correctness |
+| **Security** | [bandit](https://bandit.readthedocs.io/) + [pip-audit](https://pypi.org/project/pip-audit/) | SAST + known CVEs in dependencies |
+| **Tests** | [pytest](https://pytest.org/) × Python 3.11 / 3.12 / 3.13 | Full test suite + coverage report |
+
+Coverage is uploaded to [Codecov](https://codecov.io/gh/gbelbe/ster) on every run.
+
+### Run checks locally
+
+```bash
+pip install -e ".[dev]"
+
+ruff check .            # lint
+ruff format --check .   # format
+mypy ster/              # types
+bandit -r ster/ -c pyproject.toml   # security
+pip-audit               # dependency CVEs
+pytest --cov=ster       # tests + coverage
+```
+
+Or install the pre-commit hooks to run ruff automatically on every commit:
+
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+---
+
+## License
+
+MIT