papa-lint 0.1.0__tar.gz

papa_lint-0.1.0/.gitattributes

@@ -0,0 +1 @@
+tests/ux/corpora/** -text

papa_lint-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,34 @@
+name: Bug report
+description: Something in Papa is wrong or crashes
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+      description: What went wrong, and what did you expect instead?
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: How to reproduce
+      description: The exact command and, if possible, a small input file or snippet.
+      placeholder: |
+        papa sample.md --max-grade 10
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Papa version
+      description: Output of `papa --version` (or the commit you are on).
+    validations:
+      required: false
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.11"
+    validations:
+      required: false

papa_lint-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security report
+    url: https://github.com/bharadwaj-pendyala/papa/security/advisories/new
+    about: Report a vulnerability privately. Do not open a public issue.

papa_lint-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,24 @@
+name: Feature request
+description: Suggest an analyzer, reporter, ingestor, or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: What are you trying to do that Papa does not support yet?
+    validations:
+      required: true
+  - type: textarea
+    id: idea
+    attributes:
+      label: Proposed solution
+      description: What would the feature look like? A flag, an analyzer, a reporter?
+    validations:
+      required: false
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+    validations:
+      required: false

papa_lint-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,23 @@
+<!-- Thanks for contributing to Papa. Keep PRs small and focused. -->
+
+## What and why
+
+<!-- What does this change, and why? Link any related issue with "Closes #123". -->
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature (analyzer, reporter, ingestor)
+- [ ] Docs
+- [ ] Refactor or chore
+
+## Checklist
+
+- [ ] `pytest` passes locally.
+- [ ] New behavior has a test.
+- [ ] README or spec.md updated if public behavior changed.
+- [ ] No em dashes in prose files.
+
+## Notes for the reviewer
+
+<!-- Anything you want a reviewer to look at first, tradeoffs, or open questions. -->

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

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Test
+        run: pytest -q
+      - name: UX checks (eyes)
+        run: |
+          pip install userlens
+          eyes run
+      - name: Upload eyes report
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: eyes-${{ matrix.python-version }}
+          path: artifacts/eyes

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

@@ -0,0 +1,38 @@
+name: Publish
+
+# Runs when a GitHub release is published. PyPI trusts this workflow through
+# trusted publishing, so no API token is stored in the repo.
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Check the tag matches the package version
+        run: |
+          version=$(python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          test "v$version" = "$GITHUB_REF_NAME" || { echo "tag $GITHUB_REF_NAME does not match version $version"; exit 1; }
+      - run: pip install build && python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

papa_lint-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.herdr/
+*.worktrees/
+__pycache__/
+*.pyc
+.venv/
+dist/
+.venv/
+artifacts/

papa_lint-0.1.0/AGENTS.md

@@ -0,0 +1,34 @@
+# Notes for coding agents
+
+- Set up: `python -m venv .venv && .venv/bin/pip install -e ".[dev,eyes]"`.
+- Use the venv for every command: `.venv/bin/pytest`, `.venv/bin/eyes run`.
+  eyes runs papa with the interpreter that runs eyes, so an `eyes` from another
+  environment without papa's dependencies fails every case.
+- Read `docs/eyes.md` before you change user-facing output. Add `--browser`
+  to `eyes run` to see the HTML report and terminal output as screenshots.
+- The JSON report is a contract (`docs/llm-contract.md`). Change its shape only
+  with a version bump.
+- No em dashes in prose. Keep comments few and about the why.
+
+<!-- eyes:start -->
+## Verify changes with eyes
+
+This repo uses [userlens](https://github.com/bharadwaj-pendyala/userlens)
+to check that the product works the way a user uses it. The cases are in
+`tests/ux/eyes.json`.
+
+When you build or change a feature:
+
+1. Before you write code, add cases for what the feature must do: the happy
+   path, the output and files it must produce, and the errors a user can hit.
+   Run `eyes run --case <id>` and confirm that the new cases fail.
+2. Build until they pass. After each run, read `artifacts/eyes/report.json`,
+   starting with `failures`.
+3. Open the screenshots and `stdout.txt` files of the cases you touched.
+   Confirm the result is right, not only that the checks pass.
+4. Run `eyes run` for every case before you finish. Fix what you broke.
+5. Read each `artifacts/eyes/cases/<id>/snapshot.diff`. Run
+   `eyes approve --case <id>` only for changes you meant to make.
+
+Fix the product, not the check. Change a check only when the check is wrong.
+<!-- eyes:end -->

papa_lint-0.1.0/CLAUDE.md

@@ -0,0 +1,22 @@
+<!-- eyes:start -->
+## Verify changes with eyes
+
+This repo uses [userlens](https://github.com/bharadwaj-pendyala/userlens)
+to check that the product works the way a user uses it. The cases are in
+`tests/ux/eyes.json`.
+
+When you build or change a feature:
+
+1. Before you write code, add cases for what the feature must do: the happy
+   path, the output and files it must produce, and the errors a user can hit.
+   Run `eyes run --case <id>` and confirm that the new cases fail.
+2. Build until they pass. After each run, read `artifacts/eyes/report.json`,
+   starting with `failures`.
+3. Open the screenshots and `stdout.txt` files of the cases you touched.
+   Confirm the result is right, not only that the checks pass.
+4. Run `eyes run` for every case before you finish. Fix what you broke.
+5. Read each `artifacts/eyes/cases/<id>/snapshot.diff`. Run
+   `eyes approve --case <id>` only for changes you meant to make.
+
+Fix the product, not the check. Change a check only when the check is wrong.
+<!-- eyes:end -->

papa_lint-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,57 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Showing empathy and kindness toward other people.
+- Being respectful of differing opinions, viewpoints, and experiences.
+- Giving and gracefully accepting constructive feedback.
+- Accepting responsibility, apologizing to those affected by our mistakes, and
+  learning from the experience.
+- Focusing on what is best for the overall community.
+
+Examples of unacceptable behavior:
+
+- 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, such as a physical or email address,
+  without their explicit permission.
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting.
+
+## Enforcement Responsibilities
+
+Community leaders 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 also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainer at bharadwajpendyala@gmail.com. All complaints will
+be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 2.1,
+available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

papa_lint-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# Contributing to Papa
+
+Thanks for helping make prose more readable. Papa is open source (MIT) and contributions of every size are welcome: bug reports, docs fixes, new analyzers, and reporters.
+
+## Ways to contribute
+
+- **Report a bug or request a feature** via [issues](https://github.com/bharadwaj-pendyala/papa/issues). Use the templates.
+- **Pick a `good first issue`** if you are new. They are [labeled](https://github.com/bharadwaj-pendyala/papa/labels/good%20first%20issue).
+- **Open a pull request** for a fix or a feature. Small, focused PRs get reviewed fastest.
+
+## Development setup
+
+Papa is a Python 3.11+ project.
+
+```bash
+git clone https://github.com/bharadwaj-pendyala/papa.git
+cd papa
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+On macOS, if `papa` fails with `No module named 'papa'` after an install, a
+sync tool such as iCloud may have hidden the editable `.pth` file. Python 3.13
+skips hidden `.pth` files. Run `chflags nohidden .venv/lib/python*/site-packages/*.pth`.
+
+Run the CLI against a file to see it work:
+
+```bash
+papa README.md
+papa README.md --report json
+```
+
+## Check the UX with eyes
+
+Papa's UX checks run the CLI like a user does and check the output. They use
+[userlens](https://github.com/bharadwaj-pendyala/userlens). Run them before
+you open a PR that changes what users see:
+
+```bash
+pip install -e ".[dev,eyes]"
+eyes run              # terminal, JSON and HTML checks
+eyes run --browser    # also screenshots and layout checks
+```
+
+See [docs/eyes.md](docs/eyes.md) for how to add a case and approve output
+changes.
+
+## Project layout
+
+```
+src/papa/
+  ingest.py        format detection, code/SVG/frontmatter stripping, offset map
+  normalize.py     neutralize numbers/dates/URLs/identifiers before scoring
+  analyzers/       pluggable analyzers (readability, passive, adverbs, complex_phrase)
+  aggregate.py     merge spans, compute the document score
+  inputs.py        files, folders, globs, stdin, and excludes
+  config.py        papa.toml and [tool.papa]
+  reporters/       cli, concise, json, html
+tests/             pytest suite (one file per area)
+tests/ux/          eyes cases, corpora, reviewed snapshots
+```
+
+The data flow is `Ingestor -> Analyzers -> Aggregator -> Reporters`. See `spec.md` for the full architecture.
+
+## Adding an analyzer
+
+1. Add a module under `src/papa/analyzers/` that returns a list of `Finding` objects.
+2. Register it in `src/papa/analyzers/__init__.py`.
+3. Add a test under `tests/`.
+4. Keep core heuristics small and dependency-light. Heavy linters belong as optional plugins.
+
+## Pull request checklist
+
+- [ ] `pytest` passes locally.
+- [ ] `eyes run` passes, and you reviewed any snapshot change.
+- [ ] New behavior has a test.
+- [ ] Public behavior changes are reflected in `README.md` or `spec.md`.
+- [ ] Commit messages explain the why, not just the what.
+
+## Code style
+
+- Minimal comments. Let names carry meaning.
+- Match the patterns already in the file you are editing.
+- No em dashes in prose files. Use a comma, a period, or rewrite.
+
+## Conduct
+
+By participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).

papa_lint-0.1.0/LICENSE

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