mkforge 0.1.0__tar.gz

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

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  check:
+    name: Lint · Type-check · Test
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run CI checks
+        run: make ci
+

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

@@ -0,0 +1,82 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Ensure tag belongs to main
+        run: |
+          git fetch origin main
+          git merge-base --is-ancestor "$GITHUB_SHA" origin/main
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Check tag matches package version
+        run: |
+          python - <<'PY'
+          import os
+          import tomllib
+
+          with open("pyproject.toml", "rb") as file:
+              version = tomllib.load(file)["project"]["version"]
+
+          tag = os.environ["GITHUB_REF_NAME"]
+          expected = f"v{version}"
+          if tag != expected:
+              raise SystemExit(f"Tag {tag} does not match package version {expected}")
+          PY
+
+      - name: Run checks
+        run: make ci
+
+      - name: Build distributions
+        run: uv build --out-dir work/dist
+
+      - name: Verify distributions
+        run: uv run twine check work/dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-distributions
+          path: work/dist/
+          if-no-files-found: error
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mkforge
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+

mkforge-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Test and coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Type checkers and linters
+.mypy_cache/
+.ruff_cache/
+.pyre/
+.pytype/
+
+# Editors and OS files
+.DS_Store
+.idea/
+.vscode/
+
+# Local workspace
+work/*
+!work/.gitkeep
+

mkforge-0.1.0/.gitlab-ci.yml

@@ -0,0 +1,55 @@
+image: python:3.12-slim
+
+stages:
+  - check
+  - publish
+
+workflow:
+  rules:
+    - if: $CI_COMMIT_TAG
+    - if: $CI_MERGE_REQUEST_IID
+    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
+      when: never
+    - if: $CI_COMMIT_BRANCH
+
+variables:
+  UV_CACHE_DIR: "$CI_PROJECT_DIR/.cache/uv"
+
+cache:
+  key: "$CI_COMMIT_REF_SLUG"
+  paths:
+    - .cache/uv
+
+before_script:
+  - apt-get update -qq && apt-get install -y -qq make
+  - pip install uv --quiet
+  - uv sync --group dev
+
+check:
+  stage: check
+  script:
+    - make ci
+
+publish-pypi:
+  stage: publish
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+.*$/
+  script:
+    - |
+      python - <<'PY'
+      import os
+      import tomllib
+
+      with open("pyproject.toml", "rb") as file:
+          version = tomllib.load(file)["project"]["version"]
+
+      tag = os.environ["CI_COMMIT_TAG"]
+      expected = f"v{version}"
+      if tag != expected:
+          raise SystemExit(f"Tag {tag} does not match package version {expected}")
+      PY
+    - make ci
+    - uv build --out-dir work/dist
+    - uv run twine check work/dist/*
+    - uv run twine upload work/dist/*
+

mkforge-0.1.0/.mkforge

@@ -0,0 +1,67 @@
+[verification]
+disabled = []
+
+[verification.rules.MD001]
+front_matter_title = "^\\s*title\\s*[:=]"
+
+[verification.rules.MD002]
+level = 1
+front_matter_title = "^\\s*title\\s*[:=]"
+
+[verification.rules.MD003]
+style = "consistent"
+
+[verification.rules.MD004]
+style = "consistent"
+
+[verification.rules.MD007]
+indent = 3
+
+[verification.rules.MD009]
+br_spaces = 2
+
+[verification.rules.MD010]
+ignore_code_blocks = false
+
+[verification.rules.MD013]
+line_length = 80
+ignore_code_blocks = false
+code_blocks = true
+tables = true
+headings = true
+treat_links_as_single_words = false
+
+[verification.rules.MD024]
+allow_different_nesting = false
+
+[verification.rules.MD025]
+level = 1
+front_matter_title = "^\\s*title\\s*[:=]"
+
+[verification.rules.MD026]
+punctuation = ".,;:!?"
+
+[verification.rules.MD029]
+style = "one"
+
+[verification.rules.MD030]
+ul_single = 1
+ol_single = 1
+ul_multi = 1
+ol_multi = 1
+
+[verification.rules.MD033]
+allowed_elements = ""
+
+[verification.rules.MD035]
+style = "consistent"
+
+[verification.rules.MD036]
+punctuation = ".,;:!?"
+
+[verification.rules.MD041]
+level = 1
+front_matter_title = "^\\s*title\\s*[:=]"
+
+[verification.rules.MD046]
+style = "fenced"

mkforge-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

mkforge-0.1.0/AGENTS.md

@@ -0,0 +1,120 @@
+# Codex Instructions
+
+These instructions apply to the whole repository.
+
+## Coding Standards
+
+- Write Python code that strictly follows Python PEP rules and the Google
+  Python Style Guide.
+- Keep each function small and focused.
+- Keep cyclomatic complexity at or below 10 for every function.
+- Keep Python modules below 500 lines unless an ADR explicitly justifies a
+  larger module.
+- Do not optimize for maintainability-index scores when they encourage
+  artificial fragmentation into very small files.
+- Write Google-style docstrings for every function and class, including private
+  functions and classes.
+- Prefer explicit, readable, auditable code over clever abstractions.
+- Use clear names and simple control flow.
+- Add comments only when they clarify non-obvious intent or constraints.
+- 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 and must not weaken expected behavior.
+  - 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 the Python standard library by default.
+- Add third-party packages only when explicitly requested or when the standard
+  library is clearly insufficient for the task.
+- Before adding a dependency, document why it is needed.
+
+## Design
+
+- Start substantial feature work and architecture changes with an Architecture
+  Decision Record before implementing code.
+- Include PlantUML diagrams in ADRs when they clarify structure, behavior,
+  dependencies, lifecycles, or integration flows.
+- Document the design patterns used in each ADR, including why each pattern is
+  appropriate and what tradeoff it introduces.
+- Define public APIs, internal interfaces, data contracts, and expected error
+  behavior in the ADR before filling in feature implementation details.
+- Implement features only after the architecture, API boundaries, and extension
+  points are explicit enough to review.
+- Prefer a clean package layout over compatibility with unpublished APIs.
+- Name modules, classes, functions, variables, and tests with business/domain
+  vocabulary first. Prefer names such as `verify_file`, `heading_slugs`, or
+  `required_headings` over architecture-first names such as `node`, `leaf`,
+  `manager`, `processor`, `handler`, `orchestrator`, or `service` unless those
+  words are the real domain concept.
+- Prefer concrete, short, auditable names over abstract framework names.
+- Keep public APIs narrow and stable.
+- Avoid hidden side effects.
+- Prefer pure functions for transformation logic.
+- Validate inputs close to the boundary of the system.
+- Make error messages precise and useful.
+- Use design patterns deliberately to improve maintainability and evolvability:
+  - use Strategy when behavior varies by profile, format, rule, or policy;
+  - use Registry when behavior must be extended without modifying the engine;
+  - use Adapter when exposing a simple callable or external API behind an
+    internal interface;
+  - use Factory functions when object creation has validation or multiple
+    variants;
+  - use Template Method only when a workflow is stable and extension points are
+    explicit.
+- Do not introduce a design pattern for decoration. A pattern is acceptable only
+  when it removes duplication, reduces conditional complexity, clarifies an
+  extension point, or protects a public contract.
+- Separate verification from validation:
+  - verification checks Markdown or GitHub Flavored Markdown conformance;
+  - validation checks document content, metadata, required headings, wording,
+    and project-specific policies.
+- Keep diagnostics auditable: one diagnostic rule must live in one Python
+  module, grouped under the relevant `verification/` or `validation/`
+  package, and the module docstring must explain precisely what the rule
+  checks.
+- Avoid Python files that only re-export imports. A module must own behavior,
+  data, or documentation that justifies its existence.
+
+## Tests and Documentation
+
+- Maintain 100% test coverage.
+- Write tests for all new behavior.
+- For new public behavior, add targeted validation tests for construction and
+  input contracts, targeted verification tests for rendered Markdown or GFM
+  conformance when applicable, and end-to-end tests only as workflow coverage;
+  do not rely on end-to-end tests alone.
+- Test function docstrings must state the requirement being verified.
+- 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.
+- Module docstrings for diagnostic rules must explain what the rule checks, why
+  it belongs to verification or validation, and what kind of diagnostic it
+  emits.
+- Avoid placeholder docstrings such as `Function result.`, vague summaries, or a
+  single imperative sentence that does not document inputs and outputs.
+
+## Quality Checks
+
+Run these checks before considering code complete:
+
+```bash
+make check
+```
+
+Use `make ci` for non-mutating verification and `make check-dist` before
+publishing.

mkforge-0.1.0/CLAUDE.md

@@ -0,0 +1,121 @@
+# 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. Validation helpers that are only
+  ever used by one module belong in that module, not in a separate file.
+- Do not optimize for maintainability-index scores when they encourage
+  artificial fragmentation into very small files.
+- 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 and must not weaken expected behavior.
+  - 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 explicitly requested by the user or
+  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 before implementing code.
+- Include PlantUML diagrams in ADRs when they clarify structure, behavior,
+  dependencies, lifecycles, or integration flows.
+- Document the design patterns used in each ADR, including why each pattern is
+  appropriate and what tradeoff it introduces.
+- Define public APIs, internal interfaces, data contracts, and expected error
+  behavior in the ADR before filling in feature implementation details.
+- Implement features only after the architecture, API boundaries, and extension
+  points are explicit enough to review.
+- Keep changes focused on the requested behavior.
+- Keep public interfaces small.
+- Name modules, classes, functions, variables, and tests with business/domain
+  vocabulary first. Prefer names such as `verify_file`, `heading_slugs`, or
+  `required_headings` over architecture-first names such as `node`, `leaf`,
+  `manager`, `processor`, `handler`, `orchestrator`, or `service` unless those
+  words are the real domain concept.
+- Prefer concrete, short, auditable names over abstract framework names.
+- Avoid global mutable state unless there is a clear reason.
+- Prefer deterministic behavior and explicit inputs.
+- Use design patterns deliberately to improve maintainability and evolvability:
+  - use Strategy when behavior varies by profile, format, rule, or policy;
+  - use Registry when behavior must be extended without modifying the engine;
+  - use Adapter when exposing a simple callable or external API behind an
+    internal interface;
+  - use Factory functions when object creation has validation or multiple
+    variants;
+  - use Template Method only when a workflow is stable and extension points are
+    explicit.
+- Do not introduce a design pattern for decoration. A pattern is acceptable only
+  when it removes duplication, reduces conditional complexity, clarifies an
+  extension point, or protects a public contract.
+- Keep diagnostics auditable: one diagnostic rule must live in one Python
+  module, grouped under the relevant `verification/` or `validation/`
+  package, and the module docstring must explain precisely what the rule
+  checks.
+- Avoid Python files that only re-export imports. A module must own behavior,
+  data, or documentation that justifies its existence.
+- Group code by business cohesion, not by technical layer. Content element
+  types and their construction-time validation belong together. Rendering
+  logic for all element types belongs in one rendering module. Do not create
+  separate ``*_validation.py``, ``*_rendering.py``, or ``*_helpers.py``
+  satellites when the behavior is inseparable from its host module.
+- Write tests for new behavior.
+- For new public behavior, add targeted validation tests for construction and
+  input contracts, targeted verification tests for rendered Markdown or GFM
+  conformance when applicable, and end-to-end tests only as workflow coverage;
+  do not rely on end-to-end tests alone.
+- Maintain 100% test coverage.
+- Test function docstrings must state the requirement being verified.
+- 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.
+- Module docstrings for diagnostic rules must explain what the rule checks, why
+  it belongs to verification or validation, and what kind of diagnostic it
+  emits.
+- Avoid placeholder docstrings such as `Function result.`, vague summaries, or a
+  single imperative sentence that does not document inputs and outputs.
+
+## Quality Checks
+
+Before finishing code changes, run:
+
+```bash
+make check
+```
+
+Use `make ci` for non-mutating verification and `make check-dist` before
+publishing.

mkforge-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Antoine Barré
+
+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.
+

mkforge-0.1.0/Makefile

@@ -0,0 +1,57 @@
+.PHONY: clean clean-work format format-check lint flake8 docstrings typecheck metrics security test check ci build check-dist publish-test publish
+
+PYTHON_FILES := src tests scripts
+
+clean-work:
+	@mkdir -p work
+	@find work -mindepth 1 ! -name .gitkeep -exec rm -rf {} +
+
+clean: clean-work
+
+format format-check lint flake8 docstrings typecheck metrics security test check ci build check-dist publish-test publish: clean-work
+
+format:
+	@uv run ruff format $(PYTHON_FILES)
+
+format-check:
+	@uv run ruff format --check $(PYTHON_FILES)
+
+lint:
+	@uv run ruff check $(PYTHON_FILES)
+
+flake8:
+	@uv run flake8 $(PYTHON_FILES)
+
+docstrings:
+	@uv run python scripts/check_docstrings.py
+
+typecheck:
+	@uv run mypy src tests scripts
+
+metrics:
+	@uv run python scripts/code_metrics.py
+
+security:
+	@uv run bandit -c pyproject.toml -r src scripts
+	@bash scripts/security_deps.sh
+
+test:
+	@uv run pytest
+
+check:
+	@bash scripts/check.sh
+
+ci:
+	@bash scripts/check.sh --ci
+
+build:
+	@bash scripts/publish.sh build
+
+check-dist:
+	@bash scripts/publish.sh check-dist
+
+publish-test:
+	@bash scripts/publish.sh publish-test
+
+publish:
+	@bash scripts/publish.sh publish