mkforge 0.1.0__tar.gz → 0.2.0__tar.gz

mkforge-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+# Generated by yggtools — do not remove this line.
+name: CI
+
+on:
+  push:
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    name: Quality (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --python ${{ matrix.python-version }}
+      - name: Quality pipeline
+        run: PYTHONPATH=src uv run python -m yggtools.cli pipeline
+      - name: Upload quality reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: quality-py${{ matrix.python-version }}
+          path: work/reports/
+          if-no-files-found: ignore

mkforge-0.2.0/.gitlab-ci.yml

@@ -0,0 +1,41 @@
+# Generated by yggtools — do not remove this line.
+variables:
+  UV_CACHE_DIR: "$CI_PROJECT_DIR/.uv-cache"
+
+cache:
+  key: "$CI_COMMIT_REF_SLUG"
+  paths:
+    - .uv-cache/
+    - .venv/
+
+stages:
+  - quality
+
+.base:
+  before_script:
+    - pip install uv --quiet
+    - uv sync
+
+"quality:3.12":
+  extends: .base
+  stage: quality
+  image: python:3.12-slim
+  script:
+    - PYTHONPATH=src uv run python -m yggtools.cli pipeline
+  artifacts:
+    when: always
+    paths:
+      - work/reports/
+    expire_in: 7 days
+
+"quality:3.13":
+  extends: .base
+  stage: quality
+  image: python:3.13-slim
+  script:
+    - PYTHONPATH=src uv run python -m yggtools.cli pipeline
+  artifacts:
+    when: always
+    paths:
+      - work/reports/
+    expire_in: 7 days

mkforge-0.2.0/AGENTS.md

@@ -0,0 +1,196 @@
+# AI Agent Instructions
+
+These instructions apply to all AI coding agents (ChatGPT, GitHub Copilot,
+and other LLM-based tools) working on this repository.
+
+## Coding Standards
+
+- Strictly follow Python PEP rules and the Google Python Style Guide for all
+  Python code.
+- Keep each function's cyclomatic complexity at or below 10.
+- Keep Python modules below 500 lines unless an ADR explicitly justifies a
+  larger module.
+- Do not split a module purely to reduce its line count or cyclomatic
+  complexity. A split is justified only when the resulting modules have
+  genuinely independent reasons to change.
+- Write Google-style docstrings for every function and class, including private
+  functions and classes.
+- Write clean, auditable code with simple control flow.
+- Favor clarity over cleverness.
+- Use precise names for modules, classes, functions, variables, and tests.
+- Keep comments rare and useful.
+- Apply SOLID principles strictly:
+  - Single Responsibility: each module, class, and function must have one
+    clear reason to change.
+  - Open/Closed: add behavior through new focused implementations, rules,
+    strategies, or registries instead of editing large conditional blocks.
+  - Liskov Substitution: implementations of a public protocol must remain
+    interchangeable.
+  - Interface Segregation: depend on narrow protocols or callables rather
+    than broad objects with unrelated responsibilities.
+  - Dependency Inversion: high-level workflows depend on stable interfaces,
+    not concrete low-level details.
+
+## Dependencies
+
+- Minimize external dependencies.
+- Prefer Python standard library packages.
+- Do not add third-party dependencies unless there is a clear technical need
+  that cannot reasonably be met with the standard library.
+- Explain the reason for any new dependency before adding it.
+
+## Implementation Guidance
+
+- Start substantial feature work and architecture changes with an Architecture
+  Decision Record in `doc/` before implementing code.
+- Keep changes focused on the requested behavior.
+- Keep public interfaces small.
+- Name modules, classes, functions, variables, and tests with business/domain
+  vocabulary first.
+- Avoid global mutable state unless there is a clear reason.
+- Prefer deterministic behavior and explicit inputs.
+- Use design patterns deliberately:
+  - Strategy when behavior varies by profile, format, rule, or policy.
+  - Registry when behavior must be extended without modifying the engine.
+  - Adapter when exposing a simple callable or external API.
+  - Factory functions when object creation has validation or multiple variants.
+- Write tests for new behavior.
+- Maintain 100% test coverage.
+- Test function docstrings must state the requirement being verified using the
+  prefix `Requirement:`.
+- Every module, function, class, method, and test must include a strict
+  Google-style docstring, including private functions and classes.
+- Function and method docstrings must include:
+  - a precise summary that explains the domain behavior;
+  - `Args:` for every parameter except `self` and `cls`;
+  - `Returns:` for every non-`None` return value;
+  - `Raises:` for every intentionally raised exception.
+- Class docstrings must include `Attributes:` when instances expose public
+  attributes.
+
+## Project Structure
+
+- Source code lives in `src/mkforge/`.
+- Tests live in `tests/`.
+- Temporary outputs (coverage, caches, build artifacts) go into `work/`.
+
+## Quality Checks
+
+Before finishing code changes, run:
+
+```bash
+make check
+```
+
+Use `make ci` for non-mutating verification.
+
+---
+
+## Mode Architecte
+
+Activate this mode by saying: "mode architecte".
+
+### Posture
+
+- **Challenge first.** Before accepting any feature request, ask: Is this
+  feature necessary? What problem does it solve? Can an existing mechanism
+  handle it? If the request is vague, ask one targeted clarifying question
+  before doing anything else.
+- **Incremental ADRs.** Propose one focused ADR per decision. Never bundle
+  unrelated decisions in one document.
+- **Simplicity over cleverness.** Prefer fewer abstractions. A flat list of
+  steps beats a plugin framework when there are three plugins.
+- **Injection over inheritance.** Pass dependencies explicitly. Never use
+  base-class coupling or hidden global state.
+- **Design patterns deliberately.** Use Strategy when behavior varies by
+  policy. Use Registry when behavior must be extended without editing the
+  engine. Use Adapter to isolate I/O. Use Pipeline for ordered, independently
+  testable steps. Do not introduce a pattern for decoration.
+
+### Deliverables
+
+When asked to design a feature, produce documents in this order:
+
+1. **SRS fragment** — list only the requirements that are new or changed. Use
+   `REQ-<CATEGORY>-<NN>` identifiers. Each requirement gets one sentence with
+   SHALL / SHOULD / MAY. Include acceptance criteria.
+2. **ADR** — one decision, one document. Sections: Context, Decision,
+   Consequences, Alternatives rejected. Store in `doc/ADR-NNN-slug.md`.
+3. **SDD section** — update the relevant section of `doc/SDD.md` to reflect
+   the design. Include: affected modules, public interfaces changed, data
+   flow, error handling, test strategy.
+
+### Constraints
+
+- SOLID principles strictly applied.
+- Each module, class, and function has one clear reason to change.
+- High-level workflows depend on stable interfaces, not concrete low-level
+  details.
+- No module exceeds 500 lines unless an ADR explicitly justifies it.
+- No function has cyclomatic complexity above 10.
+- Public interfaces are small and named with business/domain vocabulary.
+- No global mutable state.
+
+---
+
+## Mode Codeur
+
+Activate this mode by saying: "mode codeur".
+
+### Posture
+
+- **Clarity over cleverness.** Write code a junior can read without
+  explanation.
+- **PEP-compliant always.** Follow PEP 8, PEP 257 (Google style), PEP 484,
+  PEP 526. Run `make check` before declaring done.
+- **100% check coverage.** Every code change must leave `make check` passing.
+  Fix ruff, flake8, mypy, bandit, and pytest failures before closing the task.
+- **Defensive programming at boundaries only.** Validate at entry points (CLI
+  args, external API responses, file I/O). Trust internal code and framework
+  guarantees. Do not add redundant guards inside a function that already
+  received a validated value.
+- **Exceptions with intent.** Raise only when the caller genuinely cannot
+  continue. Name exceptions with domain vocabulary. Never use bare `except:`.
+  Never swallow exceptions silently.
+- **Prefer stdlib, then well-known packages.** Use `pathlib`, `dataclasses`,
+  `typing`, `importlib.resources`. Do not add a dependency that the stdlib can
+  handle.
+- **Injection over inheritance.** Pass dependencies as arguments. Avoid global
+  state.
+
+### Coding Standards (Codeur)
+
+- Google-style docstrings on every function, method, class — including private
+  ones.
+- Function docstrings: summary + `Args:` + `Returns:` + `Raises:`.
+- Class docstrings: summary + `Attributes:` when public attributes exist.
+- Test docstrings use `Requirement:` prefix to state what is being verified.
+- Names use business/domain vocabulary.
+- Cyclomatic complexity <= 10 per function.
+- Module size <= 500 lines (justified by ADR if exceeded).
+
+### Testing Strategy
+
+For every code change, write:
+
+1. **Unit tests** — mock all I/O and subprocess calls. Test one function in
+   isolation. Cover the pass path, the fail path, and each `Raises:` clause.
+2. **Integration / end-to-end tests** — at least one test that exercises the
+   full workflow without mocking internal modules (only external calls like
+   `subprocess`).
+
+Test naming: `test_<what>_<condition>`.
+
+### Quality Gate
+
+Before reporting done, run:
+
+```bash
+make check
+```
+
+When fixing linter/type errors:
+- `ruff` errors — fix the code, not `# noqa`.
+- `mypy` errors — add proper type annotations; never use `# type: ignore`.
+- `bandit` B404/B603/B607 on subprocess — use `# nosec BXXX` on the offending
+  line.

mkforge-0.2.0/CLAUDE.md

@@ -0,0 +1,195 @@
+# Claude Code Instructions
+
+These instructions apply to the whole repository.
+
+## Coding Standards
+
+- Strictly follow Python PEP rules and the Google Python Style Guide for all
+  Python code.
+- Keep each function's cyclomatic complexity at or below 10.
+- Keep Python modules below 500 lines unless an ADR explicitly justifies a
+  larger module.
+- Do not split a module purely to reduce its line count or cyclomatic
+  complexity. A split is justified only when the resulting modules have
+  genuinely independent reasons to change.
+- Write Google-style docstrings for every function and class, including private
+  functions and classes.
+- Write clean, auditable code with simple control flow.
+- Favor clarity over cleverness.
+- Use precise names for modules, classes, functions, variables, and tests.
+- Keep comments rare and useful.
+- Apply SOLID principles strictly:
+  - Single Responsibility: each module, class, and function must have one
+    clear reason to change.
+  - Open/Closed: add behavior through new focused implementations, rules,
+    strategies, or registries instead of editing large conditional blocks.
+  - Liskov Substitution: implementations of a public protocol must remain
+    interchangeable.
+  - Interface Segregation: depend on narrow protocols or callables rather
+    than broad objects with unrelated responsibilities.
+  - Dependency Inversion: high-level workflows depend on stable interfaces,
+    not concrete low-level details.
+
+## Dependencies
+
+- Minimize external dependencies.
+- Prefer Python standard library packages.
+- Do not add third-party dependencies unless there is a clear technical need
+  that cannot reasonably be met with the standard library.
+- Explain the reason for any new dependency before adding it.
+
+## Implementation Guidance
+
+- Start substantial feature work and architecture changes with an Architecture
+  Decision Record in `doc/` before implementing code.
+- Keep changes focused on the requested behavior.
+- Keep public interfaces small.
+- Name modules, classes, functions, variables, and tests with business/domain
+  vocabulary first.
+- Avoid global mutable state unless there is a clear reason.
+- Prefer deterministic behavior and explicit inputs.
+- Use design patterns deliberately:
+  - Strategy when behavior varies by profile, format, rule, or policy.
+  - Registry when behavior must be extended without modifying the engine.
+  - Adapter when exposing a simple callable or external API.
+  - Factory functions when object creation has validation or multiple variants.
+- Write tests for new behavior.
+- Maintain 100% test coverage.
+- Test function docstrings must state the requirement being verified using the
+  prefix `Requirement:`.
+- Every module, function, class, method, and test must include a strict
+  Google-style docstring, including private functions and classes.
+- Function and method docstrings must include:
+  - a precise summary that explains the domain behavior;
+  - `Args:` for every parameter except `self` and `cls`;
+  - `Returns:` for every non-`None` return value;
+  - `Raises:` for every intentionally raised exception.
+- Class docstrings must include `Attributes:` when instances expose public
+  attributes.
+
+## Project Structure
+
+- Source code lives in `src/mkforge/`.
+- Tests live in `tests/`.
+- Temporary outputs (coverage, caches, build artifacts) go into `work/`.
+
+## Quality Checks
+
+Before finishing code changes, run:
+
+```bash
+make check
+```
+
+Use `make ci` for non-mutating verification.
+
+---
+
+## Mode Architecte
+
+Activate this mode by saying: "mode architecte".
+
+### Posture
+
+- **Challenge first.** Before accepting any feature request, ask: Is this
+  feature necessary? What problem does it solve? Can an existing mechanism
+  handle it? If the request is vague, ask one targeted clarifying question
+  before doing anything else.
+- **Incremental ADRs.** Propose one focused ADR per decision. Never bundle
+  unrelated decisions in one document.
+- **Simplicity over cleverness.** Prefer fewer abstractions. A flat list of
+  steps beats a plugin framework when there are three plugins.
+- **Injection over inheritance.** Pass dependencies explicitly. Never use
+  base-class coupling or hidden global state.
+- **Design patterns deliberately.** Use Strategy when behavior varies by
+  policy. Use Registry when behavior must be extended without editing the
+  engine. Use Adapter to isolate I/O. Use Pipeline for ordered, independently
+  testable steps. Do not introduce a pattern for decoration.
+
+### Deliverables
+
+When asked to design a feature, produce documents in this order:
+
+1. **SRS fragment** — list only the requirements that are new or changed. Use
+   `REQ-<CATEGORY>-<NN>` identifiers. Each requirement gets one sentence with
+   SHALL / SHOULD / MAY. Include acceptance criteria.
+2. **ADR** — one decision, one document. Sections: Context, Decision,
+   Consequences, Alternatives rejected. Store in `doc/ADR-NNN-slug.md`.
+3. **SDD section** — update the relevant section of `doc/SDD.md` to reflect
+   the design. Include: affected modules, public interfaces changed, data
+   flow, error handling, test strategy.
+
+### Constraints
+
+- SOLID principles strictly applied.
+- Each module, class, and function has one clear reason to change.
+- High-level workflows depend on stable interfaces, not concrete low-level
+  details.
+- No module exceeds 500 lines unless an ADR explicitly justifies it.
+- No function has cyclomatic complexity above 10.
+- Public interfaces are small and named with business/domain vocabulary.
+- No global mutable state.
+
+---
+
+## Mode Codeur
+
+Activate this mode by saying: "mode codeur".
+
+### Posture
+
+- **Clarity over cleverness.** Write code a junior can read without
+  explanation.
+- **PEP-compliant always.** Follow PEP 8, PEP 257 (Google style), PEP 484,
+  PEP 526. Run `make check` before declaring done.
+- **100% check coverage.** Every code change must leave `make check` passing.
+  Fix ruff, flake8, mypy, bandit, and pytest failures before closing the task.
+- **Defensive programming at boundaries only.** Validate at entry points (CLI
+  args, external API responses, file I/O). Trust internal code and framework
+  guarantees. Do not add redundant guards inside a function that already
+  received a validated value.
+- **Exceptions with intent.** Raise only when the caller genuinely cannot
+  continue. Name exceptions with domain vocabulary. Never use bare `except:`.
+  Never swallow exceptions silently.
+- **Prefer stdlib, then well-known packages.** Use `pathlib`, `dataclasses`,
+  `typing`, `importlib.resources`. Do not add a dependency that the stdlib can
+  handle.
+- **Injection over inheritance.** Pass dependencies as arguments. Avoid global
+  state.
+
+### Coding Standards (Codeur)
+
+- Google-style docstrings on every function, method, class — including private
+  ones.
+- Function docstrings: summary + `Args:` + `Returns:` + `Raises:`.
+- Class docstrings: summary + `Attributes:` when public attributes exist.
+- Test docstrings use `Requirement:` prefix to state what is being verified.
+- Names use business/domain vocabulary.
+- Cyclomatic complexity <= 10 per function.
+- Module size <= 500 lines (justified by ADR if exceeded).
+
+### Testing Strategy
+
+For every code change, write:
+
+1. **Unit tests** — mock all I/O and subprocess calls. Test one function in
+   isolation. Cover the pass path, the fail path, and each `Raises:` clause.
+2. **Integration / end-to-end tests** — at least one test that exercises the
+   full workflow without mocking internal modules (only external calls like
+   `subprocess`).
+
+Test naming: `test_<what>_<condition>`.
+
+### Quality Gate
+
+Before reporting done, run:
+
+```bash
+make check
+```
+
+When fixing linter/type errors:
+- `ruff` errors — fix the code, not `# noqa`.
+- `mypy` errors — add proper type annotations; never use `# type: ignore`.
+- `bandit` B404/B603/B607 on subprocess — use `# nosec BXXX` on the offending
+  line.

mkforge-0.2.0/Makefile

@@ -0,0 +1,45 @@
+# Generated by yggtools — do not remove this line.
+
+.PHONY: check ci test format lint typecheck metrics security build check-dist publish-test publish clean
+
+clean:
+	mkdir -p work
+	find work -mindepth 1 ! -name .gitkeep -exec rm -rf {} +
+
+format:
+	uv run ruff format src tests
+
+check: clean
+	PYTHONPATH=src uv run python -m yggtools.cli pipeline
+
+ci: check
+
+test: clean
+	uv run pytest
+
+lint: clean
+	uv run ruff check src tests
+
+typecheck: clean
+	uv run mypy src tests
+
+metrics: clean
+	PYTHONPATH=src uv run python -m yggtools.cli run metrics
+
+security: clean
+	PYTHONPATH=src uv run python -m yggtools.cli run security-code
+	PYTHONPATH=src uv run python -m yggtools.cli run security-deps
+
+build: clean
+	rm -rf dist
+	uv build --out-dir dist/
+
+check-dist: clean
+	uv build --out-dir work/dist
+	uv run twine check work/dist/*
+
+publish-test: check-dist
+	uv run twine upload --repository testpypi work/dist/*
+
+publish: check-dist
+	uv run twine upload work/dist/*

{mkforge-0.1.0 → mkforge-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkforge
-Version: 0.1.0
+Version: 0.2.0
 Summary: Programmatic Markdown report generation for Python.
 Project-URL: Homepage, https://github.com/antoinebarre/mkforge
 Project-URL: Repository, https://github.com/antoinebarre/mkforge
@@ -73,9 +73,9 @@ For package validation before publishing:
 make check-dist
 ```
 
-Temporary outputs are created under `work/` and removed at the end of each
-quality or packaging execution. The directory is kept in the repository with
-`work/.gitkeep`.
+Temporary quality reports are written under `work/reports/`. Packaging checks
+build distributions under `work/dist/`. The `work/` directory is kept in the
+repository with `work/.gitkeep`.
 
 ## Example
 
@@ -146,13 +146,28 @@ uv run python demo_verif.py
 uv run python demo_validation.py
 ```
 
+## Heading Slugification
+
+```python
+from mkforge import slugify_heading
+
+slugify_heading("Analyse des Risques")  # "analyse-des-risques"
+slugify_heading("`code` inline")        # "code-inline"
+```
+
+`slugify_heading` converts a raw heading title into a GitHub-style anchor
+slug: lowercase, inline Markdown markers removed, non-alphanumeric runs
+collapsed to a single hyphen, leading/trailing hyphens trimmed. Unicode
+letters are preserved (case-folded, not transliterated), which keeps slugs
+consistent with the anchors GitHub generates for the same heading.
+
 ## Relationship With Scribpy
 
 MkForge is intended to be independent from Scribpy.
 
 - `mkforge` generates Markdown reports from Python data.
 - `scribpy` assembles and builds Markdown documentation projects.
-- `uvforge` initializes and runs quality gates for Python packages using `uv`.
+- `yggtools` initializes and runs quality gates for Python packages using `uv`.
 
-Scribpy and uvforge may depend on MkForge for generated reports, but MkForge
+Scribpy and yggtools may depend on MkForge for generated reports, but MkForge
 should not depend on either of them.

{mkforge-0.1.0 → mkforge-0.2.0}/README.md

@@ -58,9 +58,9 @@ For package validation before publishing:
 make check-dist
 ```
 
-Temporary outputs are created under `work/` and removed at the end of each
-quality or packaging execution. The directory is kept in the repository with
-`work/.gitkeep`.
+Temporary quality reports are written under `work/reports/`. Packaging checks
+build distributions under `work/dist/`. The `work/` directory is kept in the
+repository with `work/.gitkeep`.
 
 ## Example
 
@@ -131,13 +131,28 @@ uv run python demo_verif.py
 uv run python demo_validation.py
 ```
 
+## Heading Slugification
+
+```python
+from mkforge import slugify_heading
+
+slugify_heading("Analyse des Risques")  # "analyse-des-risques"
+slugify_heading("`code` inline")        # "code-inline"
+```
+
+`slugify_heading` converts a raw heading title into a GitHub-style anchor
+slug: lowercase, inline Markdown markers removed, non-alphanumeric runs
+collapsed to a single hyphen, leading/trailing hyphens trimmed. Unicode
+letters are preserved (case-folded, not transliterated), which keeps slugs
+consistent with the anchors GitHub generates for the same heading.
+
 ## Relationship With Scribpy
 
 MkForge is intended to be independent from Scribpy.
 
 - `mkforge` generates Markdown reports from Python data.
 - `scribpy` assembles and builds Markdown documentation projects.
-- `uvforge` initializes and runs quality gates for Python packages using `uv`.
+- `yggtools` initializes and runs quality gates for Python packages using `uv`.
 
-Scribpy and uvforge may depend on MkForge for generated reports, but MkForge
+Scribpy and yggtools may depend on MkForge for generated reports, but MkForge
 should not depend on either of them.