Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
# Changelog

## Unreleased
- Actions with no node24 release now link the upstream issue or PR tracking the bump (open first, then most discussed) in text, Markdown and JSON (`upstream_issue`); archived upstream repos are called out as "replace the action". `--no-upstream` skips the lookup; results are disk-cached like tags and a rate-limited search is skipped silently

## v0.3.0 — 2026-10-19
- `--latest` (Action input `latest`): suggest the newest node24-capable release instead of the smallest major jump; default behavior unchanged
- Release-notes links on every suggested bump (`release_notes` in JSON; text `notes:` URL; Markdown column)
Expand Down
4 changes: 3 additions & 1 deletion ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@
- Show release-notes links for each major bump
- Optional PR mode for the Action (open a PR with the `--fix` diff)

## v0.4 — in progress
- Track upstream "no node24 release yet" actions and link the upstream issue (done; archived repos flagged)

## Later
- Track upstream "no node24 release yet" actions and link the upstream issue
- Publish to PyPI
2 changes: 1 addition & 1 deletion docs/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Dependabot opens version bumps if it's configured for `github-actions`, one PR p
Fewer breaking changes. `actions/checkout@v5` already runs on Node 24; you don't need to jump to v7 to clear the warning. Pass `--latest` (or Action input `latest: true`) when you *do* want the newest node24-capable release.

**An action has no Node 24 release. Now what?**
actnode reports it as `OLD` with "no release on node24 yet". Look for an open issue upstream (many exist: search "Node.js 24" in that repo), fork and change `runs.using`, or replace the action.
actnode reports it as `OLD` with "no release on node24 yet" and links the upstream issue or PR that tracks the bump, with its state, so you can subscribe to it instead of searching. If the action's repository is archived, it says so: nothing will ship, so replace the action or fork it and change `runs.using`. Pass `--no-upstream` to skip these lookups.

**Does it work with private actions?**
Actions in private repos need a token that can read them (`GITHUB_TOKEN`). Local `./` actions are read from disk.
Expand Down
9 changes: 6 additions & 3 deletions docs/reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
```
actnode [scan] [PATH] [--repo OWNER/NAME] [--org OWNER]
[--target N] [--format text|json|md] [-o FILE]
[--fix] [--latest] [--fail] [--all] [--no-cache]
[--fix] [--latest] [--fail] [--all] [--no-cache] [--no-upstream]
actnode demo
actnode --version
```
Expand All @@ -20,6 +20,7 @@ actnode --version
| `--latest` | suggest the newest release already on the target Node (default: smallest major jump) |
| `--fail` | exit code 1 if any step uses an older runtime |
| `--all` | in text mode, also show `ok`, composite, workflow and docker steps |
| `--no-upstream` | don't look up an upstream issue/PR or archived status for actions with no target-Node release |
| `--no-cache` | skip the on-disk tag cache (`~/.cache/actnode` / `$XDG_CACHE_HOME/actnode`) |

Exit codes: `0` ok, `1` old runtime found with `--fail`, `2` usage error or GitHub API rate limit (set a token).
Expand All @@ -30,7 +31,7 @@ Exit codes: `0` ok, `1` old runtime found with `--fail`, `2` usage error or GitH
|---|---|---|
| `ok` | `ok` | runs on target Node or newer |
| `old` | `OLD` | older Node; a suggested bump exists |
| `no-fix` | `OLD` | older Node; no node24 release yet |
| `no-fix` | `OLD` | older Node; no node24 release yet (note links the upstream issue/PR tracking it, or says the repo is archived) |
| `composite` | `cmp` | composite action (nested steps followed) |
| `workflow` | `wfl` | reusable workflow (nested uses followed) |
| `docker` | `dkr` | Docker action |
Expand All @@ -42,8 +43,10 @@ Exit codes: `0` ok, `1` old runtime found with `--fail`, `2` usage error or GitH
{"target": 24, "findings": [
{"file": ".github/workflows/ci.yml", "line": 7, "uses": "actions/checkout@v4",
"runtime": "node20", "status": "old", "suggest": "actions/checkout@v5", "via": null, "note": "",
"release_notes": "https://github.com/actions/checkout/releases/tag/v5"}
"release_notes": "https://github.com/actions/checkout/releases/tag/v5", "upstream_issue": null}
]}
```

For `no-fix` findings, `upstream_issue` is the best upstream match for "node24" in an issue or PR title (open first, then most discussed): `{"url", "title", "state", "number", "kind": "issue"|"pr"}`, or `null` if none was found. If the action's repository is archived, the note says so instead, since no bump will ever ship. Lookups use one GitHub search per repository, cached with the tags; a rate-limited search is skipped silently.

Remote scans use `file` values like `owner/repo:.github/workflows/ci.yml`. Nested findings set `via` to the composite or reusable workflow ref that pulled them in.
2 changes: 1 addition & 1 deletion docs/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ What it scans: every file in `.github/workflows/*.yml|yaml`, plus a root `action
|---|---|
| `ok` | the action runs on node24 (or the `--target`) or newer |
| `OLD` + `->` | runs on an older Node; a newer release on node24 exists, shown after `->` |
| `OLD` + note | runs on an older Node and **no** release runs on node24 yet: open an issue upstream, fork, or replace it |
| `OLD` + note | runs on an older Node and **no** release runs on node24 yet: the note links the upstream issue or PR tracking it (or says the repo is archived), so you can follow it, fork, or replace the action |
| `cmp` | composite action; the steps inside are checked and shown with `(inside …)` |
| `wfl` | reusable workflow; jobs/steps inside are checked recursively (same depth as composites) |
| `dkr` | Docker action, not affected |
Expand Down
4 changes: 2 additions & 2 deletions site/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -74,10 +74,10 @@ <h2>Scan the repo</h2>
<pre><code>$ actnode
[OLD] .github/workflows/ci.yml:7 node20 actions/checkout@v4 -> actions/checkout@v5
[OLD] .github/workflows/ci.yml:9 node20 actions/cache@v4 -> actions/cache@v5
[OLD] .github/workflows/ci.yml:11 node20 some-org/deploy@v2 no release on node24 yet
[OLD] .github/workflows/ci.yml:11 node20 some-org/deploy@v2 no release on node24 yet; upstream issue #41 (open) https://github.com/some-org/deploy/issues/41

3 step(s) run an action older than node24; 2 have a newer release ready.</code></pre>
<p>It reads every <code>uses:</code> in your workflows and local actions, fetches each action's <code>action.yml</code> at that exact ref, follows composite actions and reusable workflows inside, and picks the <em>smallest</em> major jump that runs on Node 24. SHA pins get a SHA back. Or scan remote with <code>actnode --repo owner/name</code> — no clone.</p>
<p>It reads every <code>uses:</code> in your workflows and local actions, fetches each action's <code>action.yml</code> at that exact ref, follows composite actions and reusable workflows inside, and picks the <em>smallest</em> major jump that runs on Node 24. SHA pins get a SHA back. When nothing ships yet, it links the upstream issue tracking the bump, or tells you the repo is archived and the action needs replacing. Or scan remote with <code>actnode --repo owner/name</code> — no clone.</p>
</div><div class="post"></div>
</section>

Expand Down
12 changes: 11 additions & 1 deletion src/actnode/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@ def render_text(findings, target):
where = f"{f.file}:{f.line}"
rt = f.runtime or "-"
extra = f"-> {f.suggest}" if f.suggest else f.note
if f.upstream_issue and f.upstream_issue.get("url"):
extra = f"{extra} {f.upstream_issue['url']}"
if f.release_notes:
extra = f"{extra} notes: {f.release_notes}" if extra else f"notes: {f.release_notes}"
via = f" (inside {f.via})" if f.via else ""
Expand All @@ -52,6 +54,9 @@ def render_md(findings, target):
]
for f in old:
up = f"`{f.suggest}`" if f.suggest else f.note
ui = f.upstream_issue
if not f.suggest and ui and ui.get("url"):
up = f"no node{target} release yet; upstream [#{ui['number']}]({ui['url']}) ({ui['state']})"
via = f" (via `{f.via}`)" if f.via else ""
notes = f"[notes]({f.release_notes})" if f.release_notes else ""
out.append(f"| `{f.file}:{f.line}` | `{f.uses}`{via} | {f.runtime} | {up} | {notes} |")
Expand Down Expand Up @@ -87,6 +92,11 @@ def _add_scan_flags(s):
)
s.add_argument("--fail", action="store_true", help="exit 1 if any step runs an old Node action")
s.add_argument("--all", action="store_true", help="show every step, not only problems")
s.add_argument(
"--no-upstream",
action="store_true",
help="don't search upstream for an issue/PR when an action has no target-Node release",
)
s.add_argument("--no-cache", action="store_true", help="skip disk tag cache (~/.cache/actnode)")


Expand Down Expand Up @@ -123,7 +133,7 @@ def main(argv=None):
print("actnode: --fix requires a local checkout; cannot rewrite remote scans", file=sys.stderr)
return 2

resolver = Resolver(use_cache=not a.no_cache, latest=a.latest)
resolver = Resolver(use_cache=not a.no_cache, latest=a.latest, upstream=not a.no_upstream)
try:
if a.repo:
if "/" not in a.repo or a.repo.count("/") != 1:
Expand Down
81 changes: 81 additions & 0 deletions src/actnode/core.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
import re
import time
import urllib.error
import urllib.parse
import urllib.request
from dataclasses import dataclass, field, asdict
from pathlib import Path
Expand Down Expand Up @@ -122,6 +123,23 @@ def release_notes_url(suggest: str) -> Optional[str]:
return f"https://github.com/{owner}/{repo}/releases/tag/{tag}"


def _pick_issue(items, target=CURRENT) -> Optional[dict]:
"""Choose the best search hit: title must mention node{target}; open first, then most comments."""
pat = re.compile(rf"node(?:\.?js)?[\s-]*{target}\b", re.I)
cands = [i for i in items if isinstance(i, dict) and pat.search(i.get("title") or "")]
if not cands:
return None
cands.sort(key=lambda i: (i.get("state") == "open", i.get("comments") or 0), reverse=True)
i = cands[0]
return {
"url": i.get("html_url"),
"title": i.get("title"),
"state": i.get("state"),
"number": i.get("number"),
"kind": "pr" if "pull_request" in i else "issue",
}


@dataclass
class Finding:
file: str
Expand All @@ -133,6 +151,7 @@ class Finding:
via: Optional[str] = None # composite/reusable workflow that pulled this in
note: str = ""
release_notes: Optional[str] = None # GitHub releases URL for the suggested tag
upstream_issue: Optional[dict] = None # {url, title, state, number} tracking the node bump upstream

def to_dict(self):
return asdict(self)
Expand All @@ -145,9 +164,12 @@ class Resolver:
cache_path: Optional[Path] = None # override for tests; default cache_dir()
cache_ttl: int = DEFAULT_CACHE_TTL
latest: bool = False # True → newest node{target} release; False → smallest major jump
upstream: bool = True # look up an upstream issue/PR for actions with no node{target} release
_yml: dict = field(default_factory=dict)
_tags: dict = field(default_factory=dict)
_wf: dict = field(default_factory=dict)
_issues: dict = field(default_factory=dict)
_archived: dict = field(default_factory=dict)

def _cache_root(self) -> Path:
return self.cache_path if self.cache_path is not None else cache_dir()
Expand Down Expand Up @@ -235,6 +257,56 @@ def _save_tag_cache(self, owner, repo, tags):
except OSError:
pass

def archived(self, owner, repo) -> bool:
"""True if the action's repo is archived (read-only: no node bump will ever ship)."""
key = (owner, repo)
if key not in self._archived:
try:
body = self.fetch(f"https://api.github.com/repos/{owner}/{repo}")
self._archived[key] = bool(body and json.loads(body).get("archived"))
except (RuntimeError, OSError, ValueError, urllib.error.URLError, AttributeError):
self._archived[key] = False
return self._archived[key]

def upstream_issue(self, owner, repo, target=CURRENT) -> Optional[dict]:
"""Find the upstream issue or PR tracking the move to node{target}.

One GitHub search per repo per run (disk-cached like tags). Prefers open items,
then the most-commented. Never raises: a failed lookup just returns None.
"""
key = (owner, repo, target)
if key in self._issues:
return self._issues[key]
cache = self._cache_root() / "issues" / f"{owner}__{repo}__node{target}.json".replace("/", "_")
hit = None
found = False
if self.use_cache:
try:
data = json.loads(cache.read_text(encoding="utf-8"))
if time.time() - float(data.get("fetched_at", 0)) <= self.cache_ttl:
hit, found = data.get("issue"), True
except (OSError, json.JSONDecodeError, TypeError, ValueError):
pass
if not found:
q = f'repo:{owner}/{repo} node{target} OR "node {target}" OR "node.js {target}" in:title'
url = ("https://api.github.com/search/issues?per_page=20&q="
+ urllib.parse.quote(q))
try:
body = self.fetch(url)
items = (json.loads(body).get("items") or []) if body else []
except (RuntimeError, OSError, ValueError, urllib.error.URLError):
self._issues[key] = None
return None # rate-limited or offline: don't cache the miss
hit = _pick_issue(items, target)
if self.use_cache:
try:
cache.parent.mkdir(parents=True, exist_ok=True)
cache.write_text(json.dumps({"fetched_at": time.time(), "issue": hit}), encoding="utf-8")
except OSError:
pass
self._issues[key] = hit
return hit

def suggest(self, owner, repo, sub, ref, target=CURRENT) -> Optional[str]:
"""Replacement ref whose action runs on node>=target, in the same ref style.

Expand Down Expand Up @@ -502,8 +574,17 @@ def _classify(root, rel, line, ref, y, parts, r, target, depth, via):
note = "" if sug else ("local action: bump runs.using" if not parts
else f"no release on node{target} yet; ask upstream or fork")
rn = release_notes_url(sug) if sug else None
up = None
if not sug and parts and r.upstream:
if r.archived(parts[0], parts[1]):
note = f"no release on node{target}; upstream repo is archived, replace the action"
else:
up = r.upstream_issue(parts[0], parts[1], target)
if up:
note = f"no release on node{target} yet; upstream {up['kind']} #{up['number']} ({up['state']})"
out.append(Finding(
rel, line, ref, using, st, suggest=sug, via=via, note=note, release_notes=rn,
upstream_issue=up,
))
elif using == "composite":
out.append(Finding(rel, line, ref, using, "composite", via=via))
Expand Down
Loading
Loading