foothold 0.1.2__tar.gz → 0.1.4__tar.gz

{foothold-0.1.2 → foothold-0.1.4}/.github/workflows/ci.yml

@@ -17,9 +17,9 @@ jobs:
         os: [ubuntu-latest, macos-latest, windows-latest]
         python: ["3.10", "3.11", "3.12", "3.13"]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with: { fetch-depth: 0 }   # churn signal needs real history
-      - uses: astral-sh/setup-uv@v3
+      - uses: astral-sh/setup-uv@v9.0.0
         with: { enable-cache: true }
       - run: uv python install ${{ matrix.python }}
       - run: uv sync --all-extras

foothold-0.1.4/.github/workflows/reading-path.yml

@@ -0,0 +1,23 @@
+name: Reading path
+
+# Dogfooding the action this repository publishes. The job summary of every pull
+# request shows the files that hold the project together, so a reviewer sees what
+# a newcomer would see.
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  map:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0   # the churn signal needs real history
+      - uses: ./           # the action defined in this repository
+        with:
+          top: "15"

{foothold-0.1.2 → foothold-0.1.4}/.github/workflows/release.yml

@@ -11,11 +11,11 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v3
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v9.0.0
         with: { enable-cache: true }
       - run: uv build
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/
@@ -34,6 +34,6 @@ jobs:
     permissions:
       id-token: write   # trusted publishing - no API token in secrets
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with: { name: dist, path: dist }
       - uses: pypa/gh-action-pypi-publish@release/v1

{foothold-0.1.2 → foothold-0.1.4}/CHANGELOG.md

@@ -6,6 +6,32 @@ All notable changes are documented here. Format follows
 
 ## [Unreleased]
 
+## [0.1.4]
+
+### Changed
+
+- The action's Marketplace name is now "Foothold reading path". GitHub requires that
+  name to be unique across every action, user and organisation, and the organisation
+  `github.com/FootHold` already holds "Foothold". Nothing else changes: the package is
+  still `foothold` on PyPI and the action is still used as `serdairy/foothold@vX.Y.Z`.
+
+## [0.1.3]
+
+### Added
+
+- A GitHub Action. `uses: serdairy/foothold@v0.1.3` runs the tool against the calling
+  repository and writes the ranked reading path to the job summary. Composite action, so
+  there is no container to pull; it needs no token and no write permission.
+
+### Changed
+
+- Every GitHub Action dependency moved to its current major: checkout v4 to v7,
+  setup-python v5 to v7, setup-uv v3 to v9.0.0, upload-artifact v4 to v7,
+  download-artifact v4 to v8. The older majors run on Node 20, which GitHub has
+  deprecated, so every run printed a warning - including runs in repositories that
+  merely use this action. `setup-uv` stopped publishing moving major tags after v7, so
+  it is pinned to an exact version.
+
 ## [0.1.2]
 
 ### Fixed
@@ -30,6 +56,8 @@ All notable changes are documented here. Format follows
 
 ## [0.1.0]
 
+Tagged before PyPI trusted publishing was configured, so this version exists as a git tag only. The first version on PyPI is 0.1.1.
+
 ### Added
 
 - `foothold map` — offline ranking of the files that hold a Python repository together,

{foothold-0.1.2 → foothold-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: foothold
-Version: 0.1.2
+Version: 0.1.4
 Summary: Turn an unfamiliar repository into a reading path
 Project-URL: Homepage, https://github.com/serdairy/foothold
 Project-URL: Issues, https://github.com/serdairy/foothold/issues
@@ -33,8 +33,8 @@ Description-Content-Type: text/markdown
 # Foothold
 
 [![CI](https://github.com/serdairy/foothold/actions/workflows/ci.yml/badge.svg)](https://github.com/serdairy/foothold/actions/workflows/ci.yml)
-[![PyPI](https://img.shields.io/pypi/v/foothold.svg)](https://pypi.org/project/foothold/)
-[![Python](https://img.shields.io/pypi/pyversions/foothold.svg)](https://pypi.org/project/foothold/)
+[![PyPI](https://img.shields.io/pypi/v/foothold?logo=pypi&logoColor=white)](https://pypi.org/project/foothold/)
+[![Python](https://img.shields.io/pypi/pyversions/foothold?logo=python&logoColor=white)](https://pypi.org/project/foothold/)
 [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 [![Checked with mypy](https://img.shields.io/badge/mypy-strict-blue.svg)](https://mypy-lang.org/)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
@@ -100,6 +100,38 @@ Python specifically to avoid pulling ~100 MB of scipy and numpy into a CLI.
 The two commands that cost money print an estimate and require confirmation; `--yes` is
 mandatory for non-interactive use.
 
+## GitHub Action
+
+Put the reading path in the job summary of every pull request. No token, no write
+permission, nothing to configure:
+
+```yaml
+- uses: actions/checkout@v7
+  with:
+    fetch-depth: 0        # the churn signal needs real history
+- uses: serdairy/foothold@v0.1.3
+  with:
+    top: "20"
+```
+
+| Input | Default | What it does |
+|---|---|---|
+| `path` | `.` | Repository root to analyse |
+| `command` | `map` | `map`, `docs` or `issues` |
+| `top` | `20` | How many files to report |
+| `output` | `ARCHITECTURE.md` | File written when `command: docs` |
+| `version` | latest | Pin a foothold version, e.g. `0.1.3` |
+| `summary` | `true` | Write the result to the job summary |
+| `python-version` | `3.12` | Python that runs foothold, independent of the analysed project |
+
+The action exposes the output as `steps.<id>.outputs.result`, so you can post it
+wherever you like. It runs `pip install foothold` and nothing else — no container to
+pull, no code from the analysed repository is executed.
+
+`fetch-depth: 0` matters: a shallow clone has no history, so the churn term collapses to
+zero and the ranking degrades to pure graph structure. It still works, it is just less
+informative.
+
 ## How the ranking works
 
 ```
@@ -183,10 +215,10 @@ Stated plainly, because the alternative wastes your time:
 
 | Version | Scope | Status |
 |---|---|---|
-| **v0.1** | `map`, `docs`, `issues`, `explain`; Python; 85% coverage | **shipped** |
+| **v0.1** | `map`, `docs`, `issues`, `explain`; GitHub Action; Python; 86% coverage | **shipped** |
 | v0.2 | Content-hash cache; incremental re-analysis on diff; `--since` | next |
 | v0.3 | tree-sitter parsers: TypeScript, JavaScript, Go | planned |
-| v0.4 | `tour` with personas; GitHub Action for CI-regenerated docs | planned |
+| v0.4 | `tour` with personas; PR-scoped reading paths | planned |
 | v0.5 | Monorepo support; call-graph edges, not just imports | planned |
 | v1.0 | Stable JSON schema; benchmark suite against hand-written docs | planned |
 

{foothold-0.1.2 → foothold-0.1.4}/README.md

@@ -1,8 +1,8 @@
 # Foothold
 
 [![CI](https://github.com/serdairy/foothold/actions/workflows/ci.yml/badge.svg)](https://github.com/serdairy/foothold/actions/workflows/ci.yml)
-[![PyPI](https://img.shields.io/pypi/v/foothold.svg)](https://pypi.org/project/foothold/)
-[![Python](https://img.shields.io/pypi/pyversions/foothold.svg)](https://pypi.org/project/foothold/)
+[![PyPI](https://img.shields.io/pypi/v/foothold?logo=pypi&logoColor=white)](https://pypi.org/project/foothold/)
+[![Python](https://img.shields.io/pypi/pyversions/foothold?logo=python&logoColor=white)](https://pypi.org/project/foothold/)
 [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 [![Checked with mypy](https://img.shields.io/badge/mypy-strict-blue.svg)](https://mypy-lang.org/)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
@@ -68,6 +68,38 @@ Python specifically to avoid pulling ~100 MB of scipy and numpy into a CLI.
 The two commands that cost money print an estimate and require confirmation; `--yes` is
 mandatory for non-interactive use.
 
+## GitHub Action
+
+Put the reading path in the job summary of every pull request. No token, no write
+permission, nothing to configure:
+
+```yaml
+- uses: actions/checkout@v7
+  with:
+    fetch-depth: 0        # the churn signal needs real history
+- uses: serdairy/foothold@v0.1.3
+  with:
+    top: "20"
+```
+
+| Input | Default | What it does |
+|---|---|---|
+| `path` | `.` | Repository root to analyse |
+| `command` | `map` | `map`, `docs` or `issues` |
+| `top` | `20` | How many files to report |
+| `output` | `ARCHITECTURE.md` | File written when `command: docs` |
+| `version` | latest | Pin a foothold version, e.g. `0.1.3` |
+| `summary` | `true` | Write the result to the job summary |
+| `python-version` | `3.12` | Python that runs foothold, independent of the analysed project |
+
+The action exposes the output as `steps.<id>.outputs.result`, so you can post it
+wherever you like. It runs `pip install foothold` and nothing else — no container to
+pull, no code from the analysed repository is executed.
+
+`fetch-depth: 0` matters: a shallow clone has no history, so the churn term collapses to
+zero and the ranking degrades to pure graph structure. It still works, it is just less
+informative.
+
 ## How the ranking works
 
 ```
@@ -151,10 +183,10 @@ Stated plainly, because the alternative wastes your time:
 
 | Version | Scope | Status |
 |---|---|---|
-| **v0.1** | `map`, `docs`, `issues`, `explain`; Python; 85% coverage | **shipped** |
+| **v0.1** | `map`, `docs`, `issues`, `explain`; GitHub Action; Python; 86% coverage | **shipped** |
 | v0.2 | Content-hash cache; incremental re-analysis on diff; `--since` | next |
 | v0.3 | tree-sitter parsers: TypeScript, JavaScript, Go | planned |
-| v0.4 | `tour` with personas; GitHub Action for CI-regenerated docs | planned |
+| v0.4 | `tour` with personas; PR-scoped reading paths | planned |
 | v0.5 | Monorepo support; call-graph edges, not just imports | planned |
 | v1.0 | Stable JSON schema; benchmark suite against hand-written docs | planned |
 

foothold-0.1.4/action.yml

@@ -0,0 +1,98 @@
+name: Foothold reading path
+description: Rank the files that hold a Python repository together, and put the reading path in the job summary.
+author: Sergei Petrov
+
+branding:
+  icon: map
+  color: green
+
+inputs:
+  path:
+    description: Repository root to analyse.
+    required: false
+    default: "."
+  command:
+    description: "One of: map, docs, issues."
+    required: false
+    default: map
+  top:
+    description: How many files to report.
+    required: false
+    default: "20"
+  output:
+    description: File to write when command is `docs`.
+    required: false
+    default: ARCHITECTURE.md
+  version:
+    description: 'Version of foothold to install, e.g. "0.1.2". Empty installs the latest.'
+    required: false
+    default: ""
+  summary:
+    description: Write the result to the GitHub job summary.
+    required: false
+    default: "true"
+  python-version:
+    description: Python used to run foothold. Independent of the analysed project.
+    required: false
+    default: "3.12"
+
+outputs:
+  result:
+    description: The command output as plain text.
+    value: ${{ steps.run.outputs.result }}
+
+runs:
+  using: composite
+  steps:
+    - name: Set up Python for foothold
+      uses: actions/setup-python@v7
+      with:
+        python-version: ${{ inputs.python-version }}
+
+    - name: Install foothold
+      shell: bash
+      run: |
+        if [ -n "${{ inputs.version }}" ]; then
+          python -m pip install --quiet "foothold==${{ inputs.version }}"
+        else
+          python -m pip install --quiet foothold
+        fi
+        foothold --version
+
+    - name: Run foothold
+      id: run
+      shell: bash
+      env:
+        # rich wraps to the terminal width; fix it so the summary is stable.
+        COLUMNS: "110"
+      run: |
+        set -euo pipefail
+        case "${{ inputs.command }}" in
+          map)    foothold map    "${{ inputs.path }}" --top "${{ inputs.top }}" | tee /tmp/foothold-out.txt ;;
+          issues) foothold issues "${{ inputs.path }}" --max "${{ inputs.top }}" --markdown | tee /tmp/foothold-out.txt ;;
+          docs)   foothold docs   "${{ inputs.path }}" --out "${{ inputs.output }}" --top "${{ inputs.top }}" | tee /tmp/foothold-out.txt ;;
+          *)      echo "::error::Unknown command '${{ inputs.command }}'. Use map, docs or issues."; exit 1 ;;
+        esac
+        {
+          echo "result<<FOOTHOLD_EOF"
+          cat /tmp/foothold-out.txt
+          echo "FOOTHOLD_EOF"
+        } >> "$GITHUB_OUTPUT"
+
+    - name: Write the job summary
+      if: ${{ inputs.summary == 'true' }}
+      shell: bash
+      run: |
+        {
+          echo "## Foothold"
+          echo
+          if [ "${{ inputs.command }}" = "issues" ]; then
+            cat /tmp/foothold-out.txt
+          else
+            echo '```'
+            cat /tmp/foothold-out.txt
+            echo '```'
+          fi
+          echo
+          echo "_Ranked by import graph and git churn. Checkout needs \`fetch-depth: 0\` for the churn signal._"
+        } >> "$GITHUB_STEP_SUMMARY"

{foothold-0.1.2 → foothold-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "foothold"
-version = "0.1.2"
+version = "0.1.4"
 description = "Turn an unfamiliar repository into a reading path"
 readme = "README.md"
 requires-python = ">=3.10"