docfriction 0.1.0__tar.gz

docfriction-0.1.0/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,toml,md}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

docfriction-0.1.0/.env.example

@@ -0,0 +1,4 @@
+# Get a key at https://typesafe.ai (Jev is served from the System One API).
+TYPESAFE_API_KEY=your-key-here
+# Optional: override the API host, e.g. a compatible gateway.
+# TYPESAFE_BASE_URL=https://api.typesafe.ai

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

@@ -0,0 +1,33 @@
+name: Bug report
+description: Something did not work as documented
+labels: [bug]
+body:
+  - type: input
+    id: version
+    attributes:
+      label: docfriction version
+      description: Output of `docfriction --version`
+    validations:
+      required: true
+  - type: input
+    id: page
+    attributes:
+      label: Documentation page
+      description: The URL or a description of the page you ran it on, if it can be shared
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+      description: Include the command you ran and the full error or the unexpected part of the report
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+  - type: textarea
+    id: dryrun
+    attributes:
+      label: Dry-run output
+      description: Output of `docfriction <page> --dry-run` (this never calls Jev)
+      render: text

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

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security issue
+    url: https://github.com/Cyvid7-Darus10/docfriction/security/advisories/new
+    about: Report vulnerabilities privately, not as a public issue

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

@@ -0,0 +1,27 @@
+name: Feature request
+description: Suggest a check, a rubric change, or a new capability
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What friction are you trying to catch?
+      description: Describe the documentation problem, ideally with a real example
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed change
+      description: A new Jev question, a deterministic check, a CLI flag, or something else
+  - type: dropdown
+    id: kind
+    attributes:
+      label: Kind
+      options:
+        - Rubric question (Jev)
+        - Deterministic check
+        - Fetching / segmentation
+        - Report format
+        - CLI / CI
+        - Other

docfriction-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+## Why
+
+<!-- What problem does this solve? Link the issue if there is one. -->
+
+## What changed
+
+<!-- Short summary. The diff shows the details. -->
+
+## Checklist
+
+- [ ] Tests added or updated, `uv run pytest` passes
+- [ ] `uv run ruff check src tests`, `uv run ruff format --check src tests`, `uv run mypy src` pass
+- [ ] `CHANGELOG.md` updated under Unreleased
+- [ ] If the rubric changed: wording follows `CONTRIBUTING.md` and `NOUL_FAILURE_DETAIL` is updated

docfriction-0.1.0/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: monthly
+    groups:
+      dev-dependencies:
+        dependency-type: development

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

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --all-groups
+      - run: uv run ruff check src tests
+      - run: uv run ruff format --check src tests
+      - run: uv run mypy src
+      - run: uv run pytest -q --cov=docfriction --cov-fail-under=80

docfriction-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,40 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+      - run: uv sync --all-groups
+      - run: uv run pytest -q
+      - run: uv build
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # PyPI trusted publishing, no API token needed
+      contents: write   # create the GitHub release
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+      - name: GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" dist/* --repo "$GITHUB_REPOSITORY" --title "$GITHUB_REF_NAME" --generate-notes

docfriction-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.env
+friction-log.*

docfriction-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.8
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-toml

docfriction-0.1.0/.python-version

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

docfriction-0.1.0/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-20
+
+### Added
+
+- `docfriction` CLI: fetch a docs page by URL or path, split it into
+  heading-level steps, evaluate each step with a batched Jev rubric, and render
+  a Markdown or JSON friction log.
+- Rubric: friction type (choice), severity (score), and yes/no checks for
+  prerequisites, expected result, terms, code/prose match, and placeholders.
+- Deterministic checks: dead links (`--check-links`), untagged code blocks,
+  stub sections, placeholder detection.
+- `--fail-on-severity` CI gate, `--dry-run`, `--max-sections`, `--concurrency`,
+  `--model`.
+- Thin Jev HTTP client with exponential backoff on 429/529; answers are
+  validated against the questions asked.
+- Link checks refuse private, loopback and link-local addresses on every
+  redirect hop unless `--allow-private-links` is set; fetched pages are capped
+  at 5 MB.
+- Segmenter handles setext headings, indented code blocks, nested fences of
+  different lengths, YAML front matter and HTML comments, and strips anchor
+  links and escapes from headings.
+- Example GitHub Actions workflow and research notes on Jev.
+
+[Unreleased]: https://github.com/Cyvid7-Darus10/docfriction/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Cyvid7-Darus10/docfriction/releases/tag/v0.1.0

docfriction-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# 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, caste, color, 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 for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* 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.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## 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 cyrus@pastelero.ph. All complaints will be
+reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

docfriction-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# Contributing to docfriction
+
+docfriction does one thing: turn a docs page into a friction log using Jev
+plus deterministic checks. Bug reports on real pages, new checks, and better
+rubric wording are the most useful contributions.
+
+## Set up
+
+```bash
+git clone https://github.com/Cyvid7-Darus10/docfriction
+cd docfriction
+uv sync --all-groups
+uv run pre-commit install   # optional but recommended
+```
+
+You do not need a TypeSafe API key to develop. The whole test suite runs
+against a mocked HTTP transport, and `docfriction <page> --dry-run` exercises
+fetching and segmentation without calling Jev.
+
+## Run the checks
+
+```bash
+uv run pytest --cov=docfriction        # tests, coverage gate is 80%
+uv run ruff check src tests            # lint
+uv run ruff format src tests           # format
+uv run mypy src                        # strict type check
+```
+
+CI runs the same four commands on Python 3.10, 3.12 and 3.13.
+
+## Where things live
+
+| Path | What |
+|---|---|
+| `src/docfriction/fetch.py` | URL / file loading, HTML to Markdown |
+| `src/docfriction/segment.py` | Markdown to heading-level steps |
+| `src/docfriction/rubric.py` | Every question we ask Jev, and the failure text per check |
+| `src/docfriction/checks.py` | Deterministic checks (links, placeholders, stubs) |
+| `src/docfriction/jev.py` | Thin HTTP client for `POST /v1/systemone` |
+| `src/docfriction/evaluate.py` | Orchestration and thresholds |
+| `src/docfriction/report.py` | Markdown and JSON rendering |
+| `src/docfriction/cli.py` | argparse entry point |
+
+## Changing the rubric
+
+Changes to `rubric.py` get the closest review, because a badly worded
+question quietly changes every report. Follow TypeSafe's guidance for Jev,
+which the existing questions do:
+
+- Put the judgment in `instructions` and the possible answers in `criteria`.
+- Score levels describe concrete situations, not degrees ("the reader has to
+  leave the page", not "moderately confusing").
+- Choices include a no-match option.
+- Reference state fields with backticks, e.g. `` `section_text` ``.
+- Phrase yes/no checks positively; a low probability is the signal.
+- Anything Jev is bad at (counting, comparing, following links) belongs in
+  `checks.py`, not in a question.
+
+Add a test in `tests/test_evaluate.py` for any new check, and a line in
+`NOUL_FAILURE_DETAIL` so the report can explain it.
+
+## Pull requests
+
+- One logical change per PR. Keep refactors separate from behaviour changes.
+- Use conventional commit messages: `feat:`, `fix:`, `docs:`, `test:`,
+  `refactor:`, `chore:`, `ci:`.
+- Add or update tests. New code should not lower coverage.
+- Update `CHANGELOG.md` under "Unreleased".
+- Explain *why* in the PR description; the diff shows what.
+
+## Reporting bugs
+
+Use the bug report issue template. If the bug is about a specific docs page,
+include the URL and the output of `docfriction <url> --dry-run`, which never
+sends anything to Jev.
+
+## Security
+
+Please do not open public issues for security problems. See
+[SECURITY.md](SECURITY.md).
+
+## Code of conduct
+
+This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md).

docfriction-0.1.0/LICENSE

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