pptlint 0.3.1__tar.gz

pptlint-0.3.1/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,31 @@
+name: Bug report
+description: Report a crash, invalid report, or renderer failure.
+title: "[Bug]: "
+labels: [bug]
+body:
+  - type: input
+    id: version
+    attributes:
+      label: PPTLint version
+    validations:
+      required: true
+  - type: textarea
+    id: command
+    attributes:
+      label: Command and exit code
+      render: shell
+    validations:
+      required: true
+  - type: textarea
+    id: behavior
+    attributes:
+      label: Expected and actual behavior
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Safe reproduction
+      description: Use a synthetic or public file. Never attach confidential material.
+    validations:
+      required: true

pptlint-0.3.1/.github/ISSUE_TEMPLATE/challenge-check.yml

@@ -0,0 +1,30 @@
+name: Challenge a PPTLint check
+description: Report a false positive, false negative, unclear impact, or unhelpful repair step.
+title: "[Check challenge] "
+labels: [rule-review]
+body:
+  - type: dropdown
+    id: challenge
+    attributes:
+      label: What needs correction?
+      options:
+        - A correct slide was reported as a problem
+        - A real problem was missed
+        - The delivery impact is overstated
+        - The PowerPoint repair steps are unclear
+    validations:
+      required: true
+  - type: input
+    id: rule
+    attributes:
+      label: Reported check name
+      description: Copy the small rule identifier from the report if available.
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Evidence
+      description: Explain the expected behavior and provide a safe minimal PPTX or reproducible construction steps.
+    validations:
+      required: true

pptlint-0.3.1/.github/ISSUE_TEMPLATE/false-positive.yml

@@ -0,0 +1,32 @@
+name: False positive
+description: Report a high-confidence finding that should not have affected the score or CI gate.
+title: "[False positive]: "
+labels: [false-positive]
+body:
+  - type: input
+    id: version
+    attributes:
+      label: PPTLint version
+    validations:
+      required: true
+  - type: input
+    id: rule
+    attributes:
+      label: Rule ID
+      placeholder: readability.small-font
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Why the finding is incorrect
+      description: Share a synthetic or public reproduction. Do not upload a private deck.
+    validations:
+      required: true
+  - type: textarea
+    id: report
+    attributes:
+      label: Redacted finding JSON
+      render: json
+    validations:
+      required: true

pptlint-0.3.1/.github/ISSUE_TEMPLATE/integrate-generator.yml

@@ -0,0 +1,29 @@
+name: Add an AI presentation project
+description: Propose a generator for the open PowerPoint delivery check or request Action integration.
+title: "[Generator] "
+labels: [integration]
+body:
+  - type: input
+    id: repository
+    attributes:
+      label: Public repository
+      placeholder: https://github.com/owner/project
+    validations:
+      required: true
+  - type: dropdown
+    id: request
+    attributes:
+      label: Request
+      options:
+        - Add this project to the controlled benchmark
+        - Add PPTLint to this project's GitHub Actions
+        - Re-run an existing benchmark result
+    validations:
+      required: true
+  - type: textarea
+    id: instructions
+    attributes:
+      label: Recommended generation instructions
+      description: Link to the project's documented recommended model, provider, and export workflow.
+    validations:
+      required: true

pptlint-0.3.1/.github/ISSUE_TEMPLATE/submit-sample.yml

@@ -0,0 +1,29 @@
+name: Submit a PowerPoint sample
+description: Share a public or safely reduced PPTX that demonstrates a real delivery problem.
+title: "[Sample] "
+labels: [sample]
+body:
+  - type: markdown
+    attributes:
+      value: "Do not attach confidential files. Use an openly licensed or safely reduced example."
+  - type: input
+    id: source
+    attributes:
+      label: Public source or license
+      description: Link to the source and state why the file can be redistributed.
+    validations:
+      required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: What goes wrong for the recipient?
+      description: Describe what a person sees when opening, presenting, editing, or sending the file.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Safe reproduction
+      description: Provide the PPTLint command, version, page number, and report excerpt without private data.
+    validations:
+      required: true

pptlint-0.3.1/.github/workflows/ci.yml

@@ -0,0 +1,88 @@
+name: CI
+on:
+  push:
+  pull_request:
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install -e ".[dev]"
+      - run: pytest
+      - run: ruff check src tests tools
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+  action-contract:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Passing deck uploads reports
+        uses: ./
+        with:
+          path: examples/good-deck.pptx
+          renderer: wireframe
+          artifact-name: good-deck-report
+      - name: Failing deck still uploads reports
+        id: bad
+        continue-on-error: true
+        uses: ./
+        with:
+          path: examples/bad-deck.pptx
+          profile: ai-generated
+          renderer: wireframe
+          artifact-name: bad-deck-report
+      - name: Confirm the bad deck requires changes
+        if: always()
+        env:
+          BAD_OUTCOME: ${{ steps.bad.outcome }}
+        run: test "$BAD_OUTCOME" = failure
+      - name: Minimum secondary score can fail independently
+        id: minimum
+        continue-on-error: true
+        uses: ./
+        with:
+          path: examples/bad-deck.pptx
+          fail-on: none
+          min-score: "100"
+          renderer: wireframe
+          artifact-name: minimum-score-report
+      - name: Confirm minimum-score exit code
+        if: always()
+        env:
+          OUTCOME: ${{ steps.minimum.outcome }}
+          EXIT_CODE: ${{ steps.minimum.outputs.exit-code }}
+        run: test "$OUTCOME" = failure && test "$EXIT_CODE" = 1
+      - name: Create damaged PPTX input
+        run: printf 'not a zip' > "$RUNNER_TEMP/damaged.pptx"
+      - name: Damaged files are operational errors
+        id: damaged
+        continue-on-error: true
+        uses: ./
+        with:
+          path: ${{ runner.temp }}/damaged.pptx
+          renderer: wireframe
+          artifact-name: damaged-deck-report
+      - name: Confirm damaged-file exit code
+        if: always()
+        env:
+          OUTCOME: ${{ steps.damaged.outcome }}
+          EXIT_CODE: ${{ steps.damaged.outputs.exit-code }}
+        run: test "$OUTCOME" = failure && test "$EXIT_CODE" = 2

pptlint-0.3.1/.github/workflows/pages.yml

@@ -0,0 +1,30 @@
+name: Deploy GitHub Pages
+on:
+  push:
+    branches: [main]
+    paths:
+      - "site/**"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: pages
+  cancel-in-progress: true
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4

pptlint-0.3.1/.github/workflows/publish-pypi.yml

@@ -0,0 +1,39 @@
+name: Publish to PyPI
+on:
+  workflow_dispatch:
+    inputs:
+      confirm-version:
+        description: Version to publish, for example 0.3.0.
+        required: true
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build
+      - name: Confirm package version
+        env:
+          EXPECTED: ${{ inputs.confirm-version }}
+        run: python -c 'import tomllib, os; actual=tomllib.load(open("pyproject.toml","rb"))["project"]["version"]; assert actual == os.environ["EXPECTED"], (actual, os.environ["EXPECTED"])'
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: pypi-distributions
+          path: dist/
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: pypi-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

pptlint-0.3.1/.gitignore

@@ -0,0 +1,12 @@
+.worktrees/
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+build/
+dist/
+*.egg-info/
+.coverage
+htmlcov/
+decklint-report.html
+decklint-report.json

pptlint-0.3.1/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## 0.3.1 — 2026-07-11
+
+- Put the plain-language delivery result first in the terminal and HTML report.
+- Print the three most important slide-level actions directly in the terminal.
+- Move scores, rule identifiers, renderer names, and other technical details behind optional sections.
+- Make the coding-agent instruction the first action on the public homepage.
+
+## 0.3.0 — 2026-07-11
+
+- Rename the primary product and package to PPTLint while keeping the previous command available through v0.4.
+- Add `pptlint check`, `pptlint-report/v2`, plain-language delivery results, and three priority actions.
+- Add content-type, blank-slide, substantial text-overlap, clipping-risk, font-portability, aspect-ratio, and editability checks.
+- Replace the score-first report and homepage with a ready, review, or blocked result for ordinary PowerPoint users.
+
+## 0.2.0 — 2026-07-11
+
+- Add deterministic before/after comparison with resolved, persistent, and new findings.
+- Add `decklint-comparison/v1`, a Chinese-first offline comparison report, and regression gates.
+- Infer semantic titles for editable AI-generated slides without weakening the baseline profile.
+- Add the documented Ultimate PPT Master repair loop while keeping DeckLint read-only.
+- Publish a reproducible Proof Loop case study: 49→100, 103 findings resolved, and zero new findings.
+- Add an offline GitHub Pages product surface with downloadable PPTX, JSON, and HTML evidence.
+
+## 0.1.0 — 2026-07-11
+
+- Add deterministic local PPTX parsing with package safety limits.
+- Add integrity, readability, editability, consistency, accessibility, and privacy findings.
+- Add transparent weighted scoring and the `decklint-report/v1` JSON Schema.
+- Publish category weights, scoring policy, per-finding deductions, caps, and calculation state in JSON and HTML.
+- Add self-contained HTML reports with wireframe and optional LibreOffice previews.
+- Add CLI, Agent Skill, composite GitHub Action, 30-case synthetic corpus, and good/bad proof reports.

pptlint-0.3.1/CONTRIBUTING.md

@@ -0,0 +1,11 @@
+# Contributing
+
+PPTLint accepts narrowly scoped checks with reproducible PPTX fixtures.
+
+1. Open an issue describing the observable defect and why it can be judged deterministically.
+2. Add a synthetic or openly licensed fixture; never commit private presentations.
+3. Add a failing test that proves the rule's positive, negative, and boundary behavior.
+4. Keep low-confidence visual heuristics advisory: they must not deduct points or fail CI.
+5. Run `pytest`, `ruff check src tests tools`, `python -m build`, and `git diff --check`.
+
+Every reported item must include evidence and a concrete repair step. Checks that judge taste, factual truth, or business strategy are out of scope.

pptlint-0.3.1/LICENSE

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

pptlint-0.3.1/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: pptlint
+Version: 0.3.1
+Summary: Open-source PPT/PPTX preflight checks for AI-generated PowerPoint files.
+Project-URL: Homepage, https://github.com/kdnsna/pptlint
+Project-URL: Repository, https://github.com/kdnsna/pptlint
+Project-URL: Issues, https://github.com/kdnsna/pptlint/issues
+Project-URL: Documentation, https://kdnsna.github.io/pptlint/
+Author: Kdnsna
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Office Suites
+Requires-Python: >=3.10
+Requires-Dist: defusedxml<1,>=0.7.1
+Requires-Dist: pillow<13,>=10
+Requires-Dist: pypdfium2<6,>=4.30
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: jsonschema<5,>=4.23; extra == 'dev'
+Requires-Dist: pytest<10,>=8; extra == 'dev'
+Requires-Dist: python-pptx<2,>=1.0; extra == 'dev'
+Requires-Dist: pyyaml<7,>=6; extra == 'dev'
+Requires-Dist: ruff<1,>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PPTLint
+
+> **Check an AI-generated PowerPoint before you send or present it.**
+
+[简体中文](README.zh-CN.md) · [Live example](https://kdnsna.github.io/pptlint/) · [Before/after report](https://kdnsna.github.io/pptlint/proof-loop/comparison.html)
+
+[![CI](https://github.com/kdnsna/pptlint/actions/workflows/ci.yml/badge.svg)](https://github.com/kdnsna/pptlint/actions/workflows/ci.yml)
+[![Pages](https://github.com/kdnsna/pptlint/actions/workflows/pages.yml/badge.svg)](https://kdnsna.github.io/pptlint/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-10233f.svg)](LICENSE)
+
+AI tools can make a PowerPoint quickly. They can also leave behind missing files, clipped text, overlapping text boxes, unreadable type, flattened slides, speaker notes, comments, and personal information.
+
+PPTLint checks the `.pptx` on your computer and answers three questions:
+
+- **Ready to send** — no high-confidence delivery problem was found.
+- **Check before sending** — open the named slides and confirm the highlighted items.
+- **Fix before sending** — fix the listed problem before sending the file.
+
+PPTLint does not upload the presentation, call an AI model, or change the source file.
+
+## Ask your coding agent
+
+Copy this into Codex, Claude Code, or another coding agent:
+
+```text
+Install PPTLint and check whether this AI-generated PowerPoint is ready to send.
+Show me the slides I must fix first and the exact PowerPoint steps for each one.
+```
+
+## Run it yourself
+
+Until the first PyPI release is verified, run the release wheel:
+
+```bash
+uvx --from https://github.com/kdnsna/pptlint/releases/download/v0.3.1/pptlint-0.3.1-py3-none-any.whl \
+  pptlint check output.pptx --profile ai-generated
+```
+
+PPTLint writes two files:
+
+- `pptlint-report.html` — an offline report for people;
+- `pptlint-report.json` — the same result for agents and automation.
+
+The first screen shows whether the file is ready and the three most important actions. The numerical score is secondary and is intended only for comparing the same presentation before and after changes.
+
+## See real examples
+
+- [Ready example](examples/reports/good-deck.html)
+- [Problem example](examples/reports/bad-deck.html)
+- [Real editable PowerPoint improvement: 49 → 100](https://kdnsna.github.io/pptlint/proof-loop/comparison.html)
+- [Before PPTX](examples/proof-loop/before.pptx) and [after PPTX](examples/proof-loop/after.pptx)
+- [Open method for checking five AI PowerPoint projects](https://kdnsna.github.io/pptlint/benchmark/)
+
+## Check changes
+
+Keep the original file, check a separate edited copy, and compare the two reports:
+
+```bash
+pptlint check before.pptx --output before
+pptlint check after.pptx --output after
+pptlint compare before.json after.json --output comparison
+```
+
+The comparison separates problems that were fixed, problems that remain, and problems introduced by the edit.
+
+## Use it in GitHub Actions
+
+```yaml
+- uses: kdnsna/pptlint@v0
+  with:
+    path: output.pptx
+    profile: ai-generated
+    renderer: wireframe
+```
+
+The reports are uploaded even when the check fails.
+
+## What PPTLint checks
+
+| User concern | Checks |
+|---|---|
+| Will it open correctly? | PPTX package, relationships, content types, media, slide list, real rendering |
+| Will it fail on screen? | Off-slide text, substantial text overlap, explicit clipping risk, small type, low contrast, unusual page size |
+| Can someone edit it later? | Full-slide images and native text, table, chart, shape coverage |
+| Is it safe to send? | Notes, comments, hidden slides, author information, external files and links |
+
+Low-confidence hints never block delivery. PPTLint does not judge whether a presentation is beautiful, persuasive, or factually correct.
+
+## Stable interfaces
+
+- Current report: [`pptlint-report/v2`](schema/pptlint-report-v2.schema.json)
+- Previous report: [`decklint-report/v1`](schema/decklint-report-v1.schema.json)
+- Comparison format: [`decklint-comparison/v1`](schema/decklint-comparison-v1.schema.json)
+- Exit code `0`: completed; `1`: changes required; `2`: file or runtime error.
+
+The previous `decklint` command remains available through v0.4. Existing v1 reports can still be compared.
+
+## Development
+
+```bash
+uv venv --python 3.13
+uv pip install -e '.[dev]'
+PYTHONPATH=src .venv/bin/python -m pytest
+.venv/bin/ruff check src tests tools
+```
+
+PPTLint is local, read-only, model-free, telemetry-free, and MIT licensed.

pptlint-0.3.1/README.md

@@ -0,0 +1,107 @@
+# PPTLint
+
+> **Check an AI-generated PowerPoint before you send or present it.**
+
+[简体中文](README.zh-CN.md) · [Live example](https://kdnsna.github.io/pptlint/) · [Before/after report](https://kdnsna.github.io/pptlint/proof-loop/comparison.html)
+
+[![CI](https://github.com/kdnsna/pptlint/actions/workflows/ci.yml/badge.svg)](https://github.com/kdnsna/pptlint/actions/workflows/ci.yml)
+[![Pages](https://github.com/kdnsna/pptlint/actions/workflows/pages.yml/badge.svg)](https://kdnsna.github.io/pptlint/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-10233f.svg)](LICENSE)
+
+AI tools can make a PowerPoint quickly. They can also leave behind missing files, clipped text, overlapping text boxes, unreadable type, flattened slides, speaker notes, comments, and personal information.
+
+PPTLint checks the `.pptx` on your computer and answers three questions:
+
+- **Ready to send** — no high-confidence delivery problem was found.
+- **Check before sending** — open the named slides and confirm the highlighted items.
+- **Fix before sending** — fix the listed problem before sending the file.
+
+PPTLint does not upload the presentation, call an AI model, or change the source file.
+
+## Ask your coding agent
+
+Copy this into Codex, Claude Code, or another coding agent:
+
+```text
+Install PPTLint and check whether this AI-generated PowerPoint is ready to send.
+Show me the slides I must fix first and the exact PowerPoint steps for each one.
+```
+
+## Run it yourself
+
+Until the first PyPI release is verified, run the release wheel:
+
+```bash
+uvx --from https://github.com/kdnsna/pptlint/releases/download/v0.3.1/pptlint-0.3.1-py3-none-any.whl \
+  pptlint check output.pptx --profile ai-generated
+```
+
+PPTLint writes two files:
+
+- `pptlint-report.html` — an offline report for people;
+- `pptlint-report.json` — the same result for agents and automation.
+
+The first screen shows whether the file is ready and the three most important actions. The numerical score is secondary and is intended only for comparing the same presentation before and after changes.
+
+## See real examples
+
+- [Ready example](examples/reports/good-deck.html)
+- [Problem example](examples/reports/bad-deck.html)
+- [Real editable PowerPoint improvement: 49 → 100](https://kdnsna.github.io/pptlint/proof-loop/comparison.html)
+- [Before PPTX](examples/proof-loop/before.pptx) and [after PPTX](examples/proof-loop/after.pptx)
+- [Open method for checking five AI PowerPoint projects](https://kdnsna.github.io/pptlint/benchmark/)
+
+## Check changes
+
+Keep the original file, check a separate edited copy, and compare the two reports:
+
+```bash
+pptlint check before.pptx --output before
+pptlint check after.pptx --output after
+pptlint compare before.json after.json --output comparison
+```
+
+The comparison separates problems that were fixed, problems that remain, and problems introduced by the edit.
+
+## Use it in GitHub Actions
+
+```yaml
+- uses: kdnsna/pptlint@v0
+  with:
+    path: output.pptx
+    profile: ai-generated
+    renderer: wireframe
+```
+
+The reports are uploaded even when the check fails.
+
+## What PPTLint checks
+
+| User concern | Checks |
+|---|---|
+| Will it open correctly? | PPTX package, relationships, content types, media, slide list, real rendering |
+| Will it fail on screen? | Off-slide text, substantial text overlap, explicit clipping risk, small type, low contrast, unusual page size |
+| Can someone edit it later? | Full-slide images and native text, table, chart, shape coverage |
+| Is it safe to send? | Notes, comments, hidden slides, author information, external files and links |
+
+Low-confidence hints never block delivery. PPTLint does not judge whether a presentation is beautiful, persuasive, or factually correct.
+
+## Stable interfaces
+
+- Current report: [`pptlint-report/v2`](schema/pptlint-report-v2.schema.json)
+- Previous report: [`decklint-report/v1`](schema/decklint-report-v1.schema.json)
+- Comparison format: [`decklint-comparison/v1`](schema/decklint-comparison-v1.schema.json)
+- Exit code `0`: completed; `1`: changes required; `2`: file or runtime error.
+
+The previous `decklint` command remains available through v0.4. Existing v1 reports can still be compared.
+
+## Development
+
+```bash
+uv venv --python 3.13
+uv pip install -e '.[dev]'
+PYTHONPATH=src .venv/bin/python -m pytest
+.venv/bin/ruff check src tests tools
+```
+
+PPTLint is local, read-only, model-free, telemetry-free, and MIT licensed.