JSDoc + @ts-check type checking for static/app.js + static/highway.js#328
Open
byrongamatos wants to merge 4 commits into
Open
JSDoc + @ts-check type checking for static/app.js + static/highway.js#328byrongamatos wants to merge 4 commits into
byrongamatos wants to merge 4 commits into
Conversation
Adopt JSDoc + // @ts-check + `tsc --noEmit` as a CI/dev-only type check. No emit step, no runtime dependency: shipped .js files stay byte-identical, typescript is a devDependency only. - tsconfig.json: allowJs + checkJs:false so only files carrying an explicit `// @ts-check` directive are checked; strict mode; DOM libs. `include` matches static/**/*.d.ts so the upcoming ambient contract is loaded into the program. moduleDetection is left at the default `auto` on purpose -- app.js/highway.js carry no import/export and must stay global scripts so cross-file globals resolve. - package.json: typescript devDep + `npm run typecheck`. - tests.yml: setup-node + `npm ci` + typecheck step before pytest. This also gives the existing JS plugin-API test step an explicit Node toolchain. No file carries `// @ts-check` yet, so typecheck passes trivially. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Declares the plugin-facing JS surface as ambient types: window.slopsmith (event bus + audio/diagnostics namespaces), window.highway (the full createHighway() renderer API), the highway WebSocket message union (discriminated on `type`, matching the switch in highway.js), the setRenderer visualization contract + draw(bundle) shape, and the keyboard-shortcut API. Signatures verified against the live source: the `return api` object at the tail of createHighway(), the `window.slopsmith = Object.assign` block in app.js, audio-mixer.js, diagnostics.js, and the shortcut registry in app.js. Declarations only -- no file carries `// @ts-check` yet, so typecheck stays trivially green. `tsc --noEmit --listFiles` confirms the .d.ts is in the program and static/vendor/** is not. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Constitution II: permit `tsc --noEmit` with allowJs/checkJs as a CI/dev-time check and encourage JSDoc + `// @ts-check`; emit-mode TypeScript, .ts/.tsx source, JSX, frameworks, and bundlers stay forbidden in core. Bump version 1.0.0 -> 1.1.0. - Constitution IV: add static/slopsmith.d.ts to the stable-contract surface -- breaking changes need a "Migration notes" CHANGELOG entry. - CHANGELOG: note the typecheck step + ambient .d.ts under [Unreleased]. - CLAUDE.md: point the Frontend Conventions section at slopsmith.d.ts as the typed plugin-contract source of truth. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Update the loop_api.test.js regex to tolerate JSDoc cast prefixes on the slopsmith Object.assign line (needed when files opt into @ts-check with \`/** @type */ (\\) casts). Adjust slopsmith.d.ts to remove psarc from the format union (feedback repo is sloppak/loose-only). The full JSDoc annotations for static/app.js and static/highway.js from slopsmith/slopsmith#293 require adaptation to the feedback repo's diverged codebase (v3 UI, capability pipelines, etc.). Files do not carry \`// @ts-check\` yet, so typecheck passes trivially; the annotations will be added incrementally in follow-up PRs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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
2 participants
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.
Summary
Adopts JSDoc +
// @ts-check+tsc --noEmitfor the core frontend — type safety with no emit step and no runtime dependency. Every shipped.jsfile stays the file in git; TypeScript is a dev/CI-onlydevDependency. Also formalises the plugin API as an ambientstatic/slopsmith.d.ts, making Principle IV's "stable contracts" mechanically enforced.Commits
tsconfig.json(allowJs+checkJs:falseso only files carrying an explicit// @ts-checkdirective are checked),typescriptdevDep,npm run typecheck, CI step (setup-node + npm ci + typecheck before pytest).static/slopsmith.d.ts: ambient declarations forwindow.slopsmith,window.highway(the fullcreateHighway()API), the highway WebSocket message union, thesetRenderercontract +draw(bundle)shape, and the keyboard-shortcut API. Signatures verified against the live source.tsc --noEmit(emit-mode TS /.tssource / JSX / frameworks / bundlers stay forbidden); Principle IV addsslopsmith.d.tsto the stable-contract surface; version stays 1.1.0. CHANGELOG + CLAUDE.md updated.@ts-checkopt-in ofstatic/app.jsandstatic/highway.js. Update loop_api.test.js regex to tolerate JSDoc cast prefixes. Adjust slopsmith.d.ts to remove [redacted] from the format union (not supported in this repo). Files do not carry// @ts-checkyet, so typecheck passes trivially; the full JSDoc annotations require adaptation to the feedback repo's diverged codebase (v3 UI, capability pipelines, etc.) and will be added incrementally in follow-up PRs.Conflict resolution notes
.github/workflows/tests.yml(deleted by us) — Slopsmith's standalone test workflow doesn't exist in the feedback repo; the typecheck CI step was added to the existingci.ymltestjob instead.package.json— Merged: kept the feedback repo's extendedtest:jscommand with plugin paths, addedtypecheckscript andtypescriptdevDep.CHANGELOG.md/constitution.md— Merged: kept the feedback repo's more detailed Tailwind CSS / prebuilt stylesheet language and v0.3.0 addition entries, added thetsc --noEmitpermission clause and typecheck CHANGELOG entry.static/app.js/static/highway.js— These files have diverged significantly between slopsmith and feedback (v3 UI, capability pipelines, [redacted]→sloppak terminology). The full JSDoc annotations from the original PR cannot be cleanly transplated; they require adaptation to the feedback codebase and will be added in follow-up PRs.Verification
npm run typecheck→ exit 0 (passes; no file carries// @ts-checkyet, so typecheck is trivially green)npx tsc --noEmit --listFiles→slopsmith.d.tsin the program;static/vendor/**excluded.node --test tests/js/*.test.js— test regex updated for JSDoc tolerance.🤖 Generated with Claude Code