docsmoke 1.0.0__tar.gz

docsmoke-1.0.0/.dockerignore

@@ -0,0 +1,11 @@
+.git
+.github
+.DS_Store
+.mypy_cache
+.pytest_cache
+.ruff_cache
+.venv
+build
+dist
+htmlcov
+tests

docsmoke-1.0.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @dev-ugurkontel

docsmoke-1.0.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: [dev-ugurkontel]

docsmoke-1.0.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,31 @@
+name: Bug report
+description: Report a defect in docsmoke.
+labels: ["bug", "needs-triage"]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What happened?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      render: bash
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: docsmoke version
+      placeholder: "1.0.0"
+    validations:
+      required: true

docsmoke-1.0.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability (private)
+    url: https://github.com/dev-ugurkontel/docsmoke/security/advisories/new
+    about: For vulnerabilities in docsmoke itself, please report privately.
+  - name: Discussions
+    url: https://github.com/dev-ugurkontel/docsmoke/discussions
+    about: Ask questions and share ideas.

docsmoke-1.0.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,31 @@
+name: Feature request
+description: Propose a new capability or improvement.
+labels: ["enhancement", "needs-triage"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem statement
+      description: What workflow is currently painful or missing?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What would you like docsmoke to do?
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Discovery
+        - Executor
+        - Reporting
+        - Configuration
+        - Documentation
+        - CI / GitHub Action
+    validations:
+      required: true

docsmoke-1.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+## Summary
+
+Explain what changed and why.
+
+## Checklist
+
+- [ ] `make all` passes locally
+- [ ] Tests were added or updated when needed
+- [ ] Docs were updated for user-facing behavior
+- [ ] `CHANGELOG.md` includes an `[Unreleased]` entry when appropriate
+
+## Notes
+
+Trade-offs, follow-up work, or rollout details.

docsmoke-1.0.0/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5

docsmoke-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,84 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+# Actions are pinned to immutable commit SHAs per GitHub's security
+# hardening guidance. Comments retain the human-readable upstream
+# version so Dependabot updates stay reviewable.
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install project
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Format check
+        run: ruff format --check .
+
+      - name: Type check
+        run: mypy src
+
+      - name: Security static analysis
+        run: bandit -q -r src -c pyproject.toml
+
+      - name: Tests
+        run: pytest --cov=docsmoke --cov-report=xml --cov-fail-under=100
+
+      - name: Self-check docs
+        run: docsmoke scan README.md docs examples
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.12'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: coverage
+          path: coverage.xml
+
+  build:
+    name: Build distribution
+    needs: test
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.12"
+      - run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/

docsmoke-1.0.0/.github/workflows/pages.yml

@@ -0,0 +1,48 @@
+name: Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Actions are pinned to immutable commit SHAs per GitHub's security
+# hardening guidance. Comments retain the human-readable upstream
+# version so Dependabot updates stay reviewable.
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build Pages artifact
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+
+      - name: Upload static site
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: docs/site
+
+  deploy:
+    name: Deploy Pages site
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

docsmoke-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,162 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write
+  packages: write
+  id-token: write
+
+# Actions are pinned to immutable commit SHAs per GitHub's security
+# hardening guidance. Comments retain the human-readable upstream
+# version so Dependabot updates stay reviewable.
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: |
+          python -m pip install --upgrade pip build cyclonedx-bom
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Generate CycloneDX SBOM
+        run: |
+          python -m pip install -e .
+          cyclonedx-py environment --output-format json --output-file dist/sbom.cdx.json
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/docsmoke
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - name: Keep only wheels and sdists for PyPI upload
+        run: find dist/ -type f ! -name "*.whl" ! -name "*.tar.gz" -delete
+
+      - name: Publish via Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
+        with:
+          packages-dir: dist/
+          skip-existing: true
+          attestations: true
+
+  publish-ghcr:
+    name: Publish container to GHCR
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Log in to GHCR
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ github.token }}
+
+      - name: Extract container metadata
+        id: meta
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=raw,value=latest
+
+      - name: Build and push container image
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        with:
+          context: .
+          file: ./Dockerfile
+          push: true
+          provenance: false
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+  sign-and-release:
+    name: Sign artifacts and create GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - name: Sign distributions with sigstore
+        uses: sigstore/gh-action-sigstore-python@04cffa1d795717b140764e8b640de88853c92acc # v3.3.0
+        with:
+          inputs: |
+            ./dist/*.whl
+            ./dist/*.tar.gz
+
+      - name: Create or update GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          for attempt in 1 2 3; do
+            if gh release view "$TAG" >/dev/null 2>&1; then
+              gh release upload "$TAG" ./dist/* --clobber && exit 0
+            else
+              gh release create "$TAG" \
+                --title "$TAG" \
+                --notes "See CHANGELOG.md for details." \
+                ./dist/* && exit 0
+            fi
+
+            if [[ "$attempt" -lt 3 ]]; then
+              sleep "$((attempt * 10))"
+            fi
+          done
+
+          exit 1
+
+      - name: Move GitHub Action major tag
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          major="${TAG%%.*}"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -fa "$major" -m "Update $major to $TAG" "$GITHUB_SHA"
+          git push origin "refs/tags/$major" --force

docsmoke-1.0.0/.gitignore

@@ -0,0 +1,13 @@
+.coverage
+.DS_Store
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+coverage.xml
+dist/
+htmlcov/
+__pycache__/
+*.egg-info/
+*.py[cod]

docsmoke-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,42 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.11
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.20.1
+    hooks:
+      - id: mypy
+        args: ["--config-file=pyproject.toml"]
+        additional_dependencies:
+          - rich>=13.7
+          - tomli>=2.0
+          - typer>=0.12
+          - typing-extensions>=4.10
+        files: ^src/
+
+  - repo: https://github.com/PyCQA/bandit
+    rev: 1.9.4
+    hooks:
+      - id: bandit
+        args: ["-c", "pyproject.toml", "-q"]
+        additional_dependencies: ["bandit[toml]"]
+        files: ^src/
+
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.1
+    hooks:
+      - id: gitleaks

docsmoke-1.0.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on Keep a Changelog and this project adheres to Semantic
+Versioning.
+
+## [Unreleased]
+
+Nothing yet.
+
+## [1.0.0] - 2026-04-21
+
+- Initial public release of `docsmoke`
+- Markdown snippet discovery with explicit `docsmoke` directives
+- Built-in shell and Python executors
+- Per-snippet timeouts, expectations, environment variables, working
+  directories, shell overrides, and skips
+- Console, JSON, and Markdown reporting
+- Clean user-facing errors for missing paths, invalid regex expectations, and
+  invalid snippet working directories
+- CommonMark-aware fenced-code discovery for nested Markdown examples and tilde
+  fences
+- Typed Python package with strict linting, mypy, Bandit, pre-commit, and 100%
+  line and branch coverage
+- GitHub Action, CI workflow, release automation, GHCR container publishing,
+  Pages deployment, support docs, and repository-governance files
+- Apache 2.0 licensing aligned with the companion `surface-audit` project

docsmoke-1.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,45 @@
+# Code of Conduct
+
+## Our Pledge
+
+We are committed to making participation in the `docsmoke` community a
+harassment-free experience for everyone, regardless of age, body size,
+disability, ethnicity, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Demonstrating empathy and kindness toward other people
+- Giving and gracefully accepting constructive feedback
+- Focusing on what is best for the community
+- Showing respect for differing opinions, viewpoints, and experiences
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards
+of acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces and when an individual
+is officially representing the project in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to dev.ugurkontel@gmail.com.
+
+This Code of Conduct is adapted from the Contributor Covenant, version 2.1:
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

docsmoke-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing to docsmoke
+
+Thanks for considering a contribution.
+
+## Development setup
+
+```bash
+git clone <your-fork-or-repo-url>
+cd docsmoke
+make install
+make all
+```
+
+## Pull requests
+
+1. Open an issue or discussion for substantial changes.
+2. Keep changes focused and well-tested.
+3. Update docs for user-facing behavior changes.
+4. Add or update tests for code changes.
+5. Keep commit messages intentional and release-note friendly.
+
+## Tooling
+
+- `ruff` for linting and formatting
+- `mypy --strict` for type checking
+- `pytest` for tests
+- `pre-commit` for local checks
+
+## Branching and releases
+
+- Default branch: `main`
+- Feature branches: `feat/<slug>` or `fix/<slug>`
+- Release tags: `vMAJOR.MINOR.PATCH`
+- Moving GitHub Action tags: `vMAJOR`, for example `v1`
+- Changelog entries belong under `[Unreleased]` until release day
+- Repository settings are tracked in [docs/REPOSITORY.md](docs/REPOSITORY.md)
+
+## Good first contributions
+
+- Add new snippet fixtures for real-world docs layouts
+- Improve renderer output
+- Add executor support for another runtime
+- Tighten docs around CI and onboarding workflows

docsmoke-1.0.0/Dockerfile

@@ -0,0 +1,30 @@
+# syntax=docker/dockerfile:1.7
+
+FROM python:3.12.7-slim AS builder
+
+ENV PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PYTHONDONTWRITEBYTECODE=1
+
+WORKDIR /build
+RUN pip install --upgrade pip build
+
+COPY pyproject.toml README.md LICENSE NOTICE ./
+COPY src ./src
+RUN python -m build --wheel --outdir /dist
+
+FROM python:3.12.7-slim AS runtime
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+RUN useradd --create-home --uid 10001 app
+
+COPY --from=builder /dist/*.whl /tmp/
+RUN pip install /tmp/*.whl && rm /tmp/*.whl
+
+USER app
+WORKDIR /home/app
+
+ENTRYPOINT ["docsmoke"]
+CMD ["--help"]