Repository navigation
docs: document the Profile API and correct the gate count - #21
Merged
Merged
Conversation
The Profiler workspace shipped without API docs, and a couple of places still counted 10 verify gates instead of 11. - api.md: add a Profile section (POST/GET /api/profile, GET /api/profile/:id, and the /events SSE stream) covering the org-only request body, the 201/400 responses, and the progress/done event shapes — and note in the intro that /api/profile/* is the Profile workspace. - README: add profiling to the hero tagline and a Profile capability bullet; add the import-boundary gate to the "at a glance" list (10 → 11). - verify.yml: fix the stale "10-gate" comment to 11 and list the boundaries gate. Audited the rest of the docs against the current code: architecture, configuration, development (incl. the Releasing section), deployment, getting-started, troubleshooting, and CONTRIBUTING are already accurate and were left unchanged.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Brings the docs back in line with the code after this session's changes — primarily documenting the Profile workspace (which shipped without API docs) and correcting a stale gate count.
Approach
I audited all the docs against the current code, not just the obvious ones. Most were already accurate (the architecture/server-reorg and release-flow PRs kept them current). Only three files were actually wrong or incomplete:
docs/api.md— added the Profile API (was entirely missing)POST /api/profile— start a run (org-only body,201on success,400for bad org / no source creds)GET /api/profile— list runs →{ "runs": [...] }GET /api/profile/:id— run + per-repo considerations/insights,404if unknownGET /api/profile/:id/events— SSE progress streamprogress/done) and that profile streams are ephemeral (no replay/?after=cursor, unlike migration streams)./api/profile/*is the Profile workspace, and added it to the table of contents.GET /api/profilereturns{ runs }and is not paginated, the request body is just{ org }, andPOSTreturns201.README.md— surfaced Profile + fixed the gate countverifyruns 11 — added the missingimport-boundarygate..github/workflows/verify.yml— fixed a stale commentboundaries; corrected to 11 withboundarieslisted. (Comment-only; the actualbun run verify:jsonwas already correct.)Left unchanged (audited, already accurate)
architecture.md(already documents the core/migrate/profile layering, the boundaries gate, and the profile pipeline),configuration.md(all env vars match.env.example),development.md(11-gate suite + the new Releasing section),deployment.md,getting-started.md,troubleshooting.md,CONTRIBUTING.md.Validation
ok: true); docs and the workflow comment are outside all gate scopes.verify.ymlparses as valid YAML.src/routes/api/profile/**andsrc/lib/server/profile/{types,events}.ts.Minor follow-up (not in this PR)
Two code comments on
ProfileRun(src/lib/server/profile/types.ts) still say "gaps" for theblockers/warningsfields — leftover from thegap → considerationrename. Trivial, but it's asrc/change so I kept it out of this docs-only PR. Happy to fix separately.