Skip to content

Repo cleanup: restore sponsio refresh, edge-runtime SDK, docs/config sync#82

Closed
donalddellapietra wants to merge 10 commits into
mainfrom
worktree-cleanup-fixes
Closed

Repo cleanup: restore sponsio refresh, edge-runtime SDK, docs/config sync#82
donalddellapietra wants to merge 10 commits into
mainfrom
worktree-cleanup-fixes

Conversation

@donalddellapietra

@donalddellapietra donalddellapietra commented Jun 13, 2026

Copy link
Copy Markdown
Contributor

Summary

A batch of well-scoped cleanups found while surveying the repo. The headline is restoring the sponsio refresh CLI command — its full logic (sponsio/refresh.py) and all its docs (README, QUICKSTART, SKILL.md, prompts/refresh.md) shipped, but the @cli.command registration had been dropped, so the documented command errored as unknown. The rest are doc/config accuracy and an edge-runtime/SDK fix.

Type of change

  • feat: restore the sponsio refresh command
  • fix: trace-mining fails open; @sponsio/sdk edge-runtime tree-shaking
  • docs / build: cli.md & CLAUDE.md accuracy, ruff/mypy config

Design notes

  • refresh was recovered from its original commit (505dd50) and verified against the current CodeAnalyzer.generate_yaml / parse_since APIs (unchanged). Tests restored as tests/test_refresh.py with fixtures updated for the E:→G: rename (23 tests).
  • Trace-mining fail-open: CodeAnalyzer imported TraceMiner unguarded, before the try/except that fails open on trace-loading errors — so in builds without the optional trace_mining extension it crashed scan --trace / refresh instead of degrading. Now guarded, matching the package's two other call sites.
  • SDK sideEffects: false complements the createRequire deferral that landed in #78/0.2.0a3: that stops the eager throw; this lets bundlers tree-shake the Node-only YAML path out of edge bundles entirely.
  • mypy config is intentionally non-gating — the tree has ~180 type errors; the config gives a reproducible local invocation and a documented ratchet path, not a CI gate.
  • Out of scope: wiring --emit-traces / the prompt-driven refresh flow (the restored command matches the documented --since/--apply/--mode interface); broadening ruff rules (e.g. import sorting); type-error cleanup.

Test plan

pytest -q                        # 2319 passed, 26 skipped
pytest tests/test_refresh.py -q  # 23 passed
ruff check sponsio/ tests/ scripts/      # clean
ruff format --check sponsio/ tests/ scripts/   # clean
(cd ts/packages/sdk && npm run build && npm test)   # build OK; all suites pass
python -m sponsio.cli refresh --help     # registered

Checklist

  • Tests added or updated.
  • pytest -v passes locally.
  • ruff check / ruff format --check clean.
  • CHANGELOG.md [Unreleased] updated.
  • No new external dependency added to sponsio/ core (mypy/types-PyYAML are dev-only).
  • N/A: no new patterns or integrations.

Note: commits are not DCO Signed-off-by signed. If the DCO check is enforced on this repo, I can amend the trailers.

🤖 Generated with Claude Code

donalddellapietra and others added 9 commits June 13, 2026 14:11
@donalddellapietra @claude
docs(claude): fix duplicate packages/sdk line in repo map
a685d71 
The ts/ workspace has a single package (@sponsio/sdk); the second
'AST static scanner CLI' line described the same package as if it were
a separate one. Merge into one accurate entry.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@donalddellapietra @claude
docs(cli): sync command reference with actual CLI surface
403bc13 
- Remove the 'sponsio refresh' section: no such command exists; the
  refresh workflow is driven via 'sponsio prompt refresh' (already
  documented) and the described --since/--apply flags were never real.
- Document 'sponsio onboard' (one-shot init+scan+doctor wire-up).
- Document 'sponsio serve' (placeholder stub in this distribution).
- Document the 'sponsio daemon' group (run/ping/status).
- Document the 'sponsio cursor' group (install-hooks/guard).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@donalddellapietra @claude
build: add explicit [tool.ruff] config
1907761 
Pin line-length, target-version, and the lint rule selection that CI's
pinned ruff relies on, instead of inheriting version-dependent defaults.
Codifies current behaviour (88-col, default E/F set) so the existing
tree stays clean; broadening the rule set is left to a follow-up.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@donalddellapietra @claude
docs(claude): drop stale scoring/ entry from repo map
eaea9f4 
sponsio/scoring/ was removed in bd9a80a (sto/scoring cleanup) but the
repo map still listed it. No such package exists.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@donalddellapietra @claude
build: add non-gating mypy foothold config
89213ca 
Add [tool.mypy] + mypy/types-PyYAML dev deps so contributors get a
single reproducible 'mypy -p sponsio' invocation with framework import
noise silenced. Intentionally not wired into CI yet — the tree has ~180
type errors — and documents the module-by-module ratchet path to a gate.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@donalddellapietra @claude
fix(sdk): mark @sponsio/sdk side-effect-free for tree-shaking
7d587cd 
Add "sideEffects": false so bundlers can drop the yaml/config-loading
modules entirely for consumers that only use the deterministic engine
(e.g. inline-contract usage on Cloudflare Workers). Complements the
createRequire deferral landed in #78: that stops the eager
createRequire(undefined) throw, this lets the Node-only yaml path be
tree-shaken out of edge bundles rather than merely deferred.

No top-level side effects exist in the published source, so this is safe.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@donalddellapietra @claude
fix(discovery): fail open when trace_mining extension is absent
ddb4b72 
CodeAnalyzer.extract_trace_contracts imported TraceMiner unguarded,
before the try/except that fails open on trace-loading errors. In
builds that don't bundle the trace_mining extension (it's an optional
extension point — see discovery/extractors/__init__.py, which already
guards the same import), this raised ModuleNotFoundError and crashed
'sponsio scan --trace' / 'sponsio refresh' instead of degrading.

Guard the import with try/except ImportError and emit a skip line,
matching the established pattern at the package's other two call sites.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@donalddellapietra @claude
feat(cli): restore the 'sponsio refresh' command
10c25f1 
refresh re-mines source:trace contracts from recent session logs and
surgically merges them into sponsio.yaml (companion to 'sponsio scan').
The backing logic (sponsio/refresh.py: compute_refresh / apply_refresh /
render_report) and all its docs (README, QUICKSTART, SKILL.md,
prompts/refresh.md) shipped, but the @cli.command registration was
dropped at some point, so 'sponsio refresh' errored as an unknown
command despite being documented everywhere.

- Re-add the command (recovered from 505dd50, verified against the
  current CodeAnalyzer.generate_yaml / parse_since APIs, which are
  unchanged): -c/--config, -a/--agent, -t/--trace, --since, --mode,
  --apply, dry-run by default, .sponsio.bak backup on apply.
- Restore tests/test_refresh.py (E:->G: fixtures updated for the rename)
  — 23 tests covering identity/dedup, the diff buckets, add-only vs
  replace-trace apply, and the CLI surface.
- Restore the 'sponsio refresh' section in docs/reference/cli.md (this
  reverts its removal earlier in the branch, now that the command is
  real again) and note the trace-mining-extension caveat.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@donalddellapietra @claude
docs: changelog entries for refresh, edge-runtime, trace-mining fixes
a13ec74 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@donalddellapietra @claude
test/fix: address PR review on refresh restoration
ca265c4 
- Add test_cli_refresh_mines_and_merges: stubs CodeAnalyzer.generate_yaml
  with a real-schema mining result so the full mine→diff→apply pipeline
  is exercised (add/drift/stale + user-rule preservation + backup). The
  existing CLI tests only used empty traces, so the generate_yaml↔
  _normalize_contract_entry schema contract was never validated.
- Replace the unused _make_native_trace helper with that test.
- Fix a trivially-true backup assertion (dead 'or True') to actually
  assert the backup retains the original.
- Narrow SDK 'sideEffects' to ['./dist/cli/**']: the CLI entry runs
  main() at module scope, so a blanket 'false' was inaccurate (the
  library exports remain side-effect-free and tree-shakeable).
- Fix a stale 'E:'→'G:' comment in code_analysis YAML emission.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@yfxiao16 yfxiao16 mentioned this pull request Jun 15, 2026
Merged
@yfxiao16

yfxiao16 commented Jun 15, 2026

Copy link
Copy Markdown
Contributor

Hey Donald, nice survey. We're going to pass on restoring sponsio refresh for now: it depends on the trace-mining engine that isn't in this distribution, so re-registering it just gives a command that runs and always mines nothing (the fail-open change is basically proof of that).

I've adopted the surrounding cleanup separately with attribution in #83: the CLAUDE.md repo-map fixes, the cli.md sync for onboard/serve/daemon/cursor, the ruff config, the trace_mining fail-open guard, and the sdk sideEffects fix (narrowed to the CLI entry per your follow-up). Skipped the mypy config for now, and no need to worry about DCO, it's not enabled on this repo.

Will fill you in on the rest offline. Thanks!

@yfxiao16 yfxiao16 closed this Jun 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@yfxiao16 yfxiao16 Awaiting requested review from yfxiao16

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@donalddellapietra @yfxiao16