lumberjack-py 0.4.0__tar.gz

lumberjack_py-0.4.0/.dockerignore

@@ -0,0 +1,46 @@
+# Python artifacts
+__pycache__/
+*.py[cod]
+build/
+dist/
+wheels/
+*.egg-info/
+.venv/
+.env
+.env.*
+!.env.example
+
+# Frontend build artefacts (rebuilt inside Docker)
+lumberjack_webui/node_modules/
+lumberjack_webui/dist/
+src/lumberjack/web/static/
+
+# Test and dev artifacts
+tests/
+.ruff_cache/
+.pytest_cache/
+script/
+output/
+data/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Git
+.git/
+.gitignore
+
+# Docker
+docker/
+.dockerignore
+
+# Docs — keep README.md, hatchling requires it for the package metadata
+LICENSE
+CHANGELOG.md

lumberjack_py-0.4.0/.env.example

@@ -0,0 +1,5 @@
+VERSION=0.0.0
+IMAGE_NAME=lumberjack
+TAG=latest
+HOST_PORT=9612
+COMPOSE_PROJECT_NAME=lumberjack

lumberjack_py-0.4.0/.github/CODEOWNERS

@@ -0,0 +1,16 @@
+# CODEOWNERS — reviewers auto-requested on PRs that touch matching paths.
+# Docs: https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+#
+# Syntax: <pattern> @username (or @org/team)
+# Later rules take precedence over earlier ones. Add more specific rules at the bottom.
+
+# Default owner for everything in the repository.
+* @ouyangfeng2022
+
+# --- Per-area owners (uncomment and edit to add specific reviewers) ---
+# Core splitting pipeline
+# /src/lumberjack/core/        @expert-on-splitters
+# Markdown parser
+# /src/lumberjack/core/parser/markdown/ @expert-on-markdown
+# Web UI
+# /lumberjack_webui/           @expert-on-frontend

lumberjack_py-0.4.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,98 @@
+name: Bug report
+description: Report something that isn't working as expected
+title: "[bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug report! Before you continue,
+        please [search existing issues](https://github.com/ouyangfeng2022/lumberjack/issues?q=is%3Aissue+label%3Abug)
+        to avoid duplicates.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear and concise description of the bug.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Minimal steps to reproduce the behavior.
+      placeholder: |
+        1. Run `...`
+        2. With input `...`
+        3. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What you expected to happen.
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: What actually happened. Paste error output, stack traces, or unexpected output here.
+    validations:
+      required: true
+
+  - type: textarea
+    id: code
+    attributes:
+      label: Reproducer
+      description: A minimal code snippet or command that triggers the bug. Use ``` code fences.
+      render: python
+
+  - type: input
+    id: lumberjack-version
+    attributes:
+      label: lumberjack version
+      description: Run `uv pip show lumberjack` or check your lockfile.
+      placeholder: "e.g. 0.2.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: "e.g. 3.12.3"
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      placeholder: "e.g. Ubuntu 24.04, macOS 14, Windows 11"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: install-method
+    attributes:
+      label: How did you install lumberjack?
+      options:
+        - pip / pipx
+        - uv
+        - From source (git clone)
+        - Docker
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Anything else that might be relevant — config, workarounds you tried, related issues.

lumberjack_py-0.4.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,4 @@
+# Issue template chooser config
+# https://docs.github.com/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository
+blank_issues_enabled: false
+contact_links: []

lumberjack_py-0.4.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,38 @@
+name: Feature request
+description: Suggest an idea for lumberjack
+title: "[feat]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a feature! Please [search existing issues](https://github.com/ouyangfeng2022/lumberjack/issues?q=is%3Aissue+label%3Aenhancement)
+        first to see if it's already been requested.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem does this feature solve? What are you trying to do that's currently hard or impossible?
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: Describe what you'd like to happen. An API sketch or example usage helps a lot.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: What workarounds or alternative approaches have you considered?
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Mockups, links, related issues, or anything else relevant.

lumberjack_py-0.4.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,35 @@
+## Summary
+
+<!-- Briefly describe what this PR changes and why. 1-3 sentences. -->
+
+## Related issue
+
+<!-- Link the issue this PR addresses, e.g. "Closes #123". Use "Closes", "Fixes", or "Resolves". -->
+
+Closes #
+
+## Type of change
+
+<!-- Check the one that applies. -->
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+- [ ] Refactor / performance improvement
+- [ ] Test improvement
+
+## Checklist
+
+<!-- Please make sure all of the following are done. If something doesn't apply, mark it and explain why in the PR description. -->
+
+- [ ] My code follows the style of this project (`uv run ruff format`, `uv run ruff check`)
+- [ ] I have run `uv run ty check .` and there are no type errors
+- [ ] I have added tests that prove my fix is effective or my feature works
+- [ ] New and existing tests pass locally (`uv run pytest`)
+- [ ] I have updated the documentation (README / docstrings / CHANGELOG) where relevant
+- [ ] My commits follow [Conventional Commits](https://www.conventionalcommits.org/) (e.g. `feat:`, `fix:`, `docs:`)
+
+## Notes for reviewer
+
+<!-- Anything you'd like the reviewer to focus on, tricky parts, alternative approaches considered, etc. Optional. -->

lumberjack_py-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,77 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+
+# Cancel superseded runs on the same ref.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  python:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # hatch-vcs derives the version from git tags; need full history.
+          fetch-depth: 0
+
+      - name: Install uv and Python ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@v6
+        with:
+          # setup-uv installs this exact Python via `uv python install`,
+          # so uv won't fall back to a runner-default (e.g. 3.14).
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install dependencies
+        # `web` is an optional-dependency extra (not a group); tests/web/test_web.py
+        # imports fastapi.testclient, so the web server stack must be installed.
+        run: uv sync --group dev --group test --extra tokenizers --extra docx --extra web
+
+      - name: Type check
+        run: uv run ty check .
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Verify formatting
+        run: uv run ruff format --check
+
+      - name: Test
+        run: uv run pytest
+
+  frontend:
+    name: Frontend (lint + build)
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.x
+          cache: true
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+        working-directory: lumberjack_webui
+
+      - name: Lint
+        run: bun run lint
+        working-directory: lumberjack_webui
+
+      - name: Build (includes tsc type check)
+        run: bun run build
+        working-directory: lumberjack_webui

lumberjack_py-0.4.0/.github/workflows/package.yml

@@ -0,0 +1,59 @@
+name: Package
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and smoke-test distributions
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # hatch-vcs derives the version from git tags.
+          fetch-depth: 0
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.10"
+          enable-cache: true
+
+      - name: Build wheel and source distribution
+        run: uv build --out-dir "$RUNNER_TEMP/dist"
+
+      - name: Validate package metadata
+        run: uvx twine check "$RUNNER_TEMP"/dist/*
+
+      - name: Assert distribution contents
+        run: uv run --group test pytest tests/test_distribution.py
+        env:
+          LUMBERJACK_DIST_DIR: ${{ runner.temp }}/dist
+
+      - name: Smoke-test wheel installation
+        run: |
+          uv venv --python 3.10 .venv-wheel
+          uv pip install --python .venv-wheel/bin/python "$RUNNER_TEMP"/dist/*.whl
+          .venv-wheel/bin/python -c 'from lumberjack import Lumberjack; assert Lumberjack().saw("# Title\\n\\nBody")'
+          .venv-wheel/bin/lumber --help
+
+      - name: Smoke-test source distribution installation
+        run: |
+          uv venv --python 3.10 .venv-sdist
+          uv pip install --python .venv-sdist/bin/python "$RUNNER_TEMP"/dist/*.tar.gz
+          .venv-sdist/bin/python -c 'from lumberjack import Lumberjack; assert Lumberjack().saw("# Title\\n\\nBody")'
+          .venv-sdist/bin/lumber --help
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-distributions
+          path: ${{ runner.temp }}/dist/
+          if-no-files-found: error

lumberjack_py-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,66 @@
+name: Publish release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  validate-release-tag:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Validate release tag format
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          if [[ ! "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error::Production release tag '$RELEASE_TAG' must use stable v<MAJOR>.<MINOR>.<PATCH> format."
+            exit 1
+          fi
+
+  verify:
+    needs: validate-release-tag
+    uses: ./.github/workflows/ci.yml
+
+  package:
+    needs: verify
+    uses: ./.github/workflows/package.yml
+
+  publish:
+    needs: package
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/lumberjack-py
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-distributions
+          path: dist
+
+      - name: Verify distribution version matches tag
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          expected_version="${RELEASE_TAG#v}"
+          actual_version="$(unzip -p dist/*.whl '*/METADATA' | sed -n 's/^Version: //p' | head -n 1)"
+          if [[ "$actual_version" != "$expected_version" ]]; then
+            echo "::error::Wheel version '$actual_version' does not match tag '$RELEASE_TAG'."
+            exit 1
+          fi
+
+      - name: Publish to PyPI with Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" dist/* --generate-notes --verify-tag

lumberjack_py-0.4.0/.github/workflows/test-release.yml

@@ -0,0 +1,32 @@
+name: Publish TestPyPI release
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  package:
+    uses: ./.github/workflows/package.yml
+
+  publish:
+    needs: package
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/lumberjack-py/
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-distributions
+          path: dist
+
+      - name: Publish to TestPyPI with Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

lumberjack_py-0.4.0/.gitignore

@@ -0,0 +1,46 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Environment files
+.env
+.env.*
+!.env.example
+
+# Frontend
+lumberjack_webui/node_modules/
+lumberjack_webui/dist/
+src/lumberjack/web/static/
+
+# Datasets
+data/
+output/
+
+# Private development documentation
+internal_docs/
+
+# Tool caches
+.ruff_cache/
+.pytest_cache/
+.worktrees
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# tar
+*.tar
+*.tar.gz