feat: align output helpers with Data/Classification/Procedure - #49
Merged
Conversation
Rename l1Output/l2Output/l3Output to dataTypeOutput/classificationTypeOutput/ procedureTypeOutput, matching the Data/Classification/Procedure tool-type vocabulary from the deterministic-tools spec. The old names remain exported as JSDoc-only @deprecated declaration aliases bound to the same function objects, so existing consumers keep working until the next breaking change. The wire format is unchanged: the Procedure envelope still carries an 'instructions' field. Docs and examples sweep is scoped to src/, README.md, examples/ and CLAUDE.md. CHANGELOG.md and docs/specs/ are left alone as historical records, and the unrelated --level CLI flag fixtures are untouched.
Contributor
|
🎉 This PR is included in version 0.2.0 🎉 The release is available on: Your semantic-release bot 📦🚀 |
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
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
Aligns the output-schema helpers with the
Data/Classification/Proceduretool-typevocabulary from the deterministic-tools spec.
The library previously used an L1/L2/L3 "output spectrum" naming that no longer matches the spec.
l1OutputdataTypeOutputl2OutputclassificationTypeOutputl3OutputprocedureTypeOutputNon-breaking
The three old names stay exported as
@deprecateddeclaration aliases bound to the samefunction objects — no wrapper, no second implementation:
Verified against the emitted declarations in
dist/index.d.ts, which is the contract consumersactually get: the
@deprecatedJSDoc survives into the build, andtypeof classificationTypeOutputpreserves the full overload set, so both call forms still resolve for anyone on an old name.
The wire format is unchanged — the Procedure envelope still carries an
instructionsfield.No stdout or stderr output changes for a consumer on a deprecated name.
Deprecation policy
Each canonical helper's JSDoc now records the rule: changing that helper's type is a breaking
change, and at that point the deprecated alias is removed rather than adapted to the new type.
Changes
src/output-helpers.ts@deprecatedaliases, type-change policy notessrc/index.tssrc/tool-class.tssrc/types.tsSubcommandSpec.outputREADME.md,examples/tests/.gitignore.cothinker/Scope boundaries
CHANGELOG.mdanddocs/specs/*are deliberately untouched — they are historical records, andrewriting them would falsify what actually shipped. The unrelated
--levelCLI flag in the testfixtures is also untouched;
bun testcontinuing to pass on those cases proves the sweep didn'tover-reach.
Testing
bun test→ 124 pass, 0 fail (244 assertions)bunx tsc --noEmit→ cleanbunx biome check .→ cleanNew
describe("deprecated output helper aliases")suite exercises the old names behaviorallythrough
Tool.invoke()— asserting the full output envelope, not schema-object identity — coveringboth
l2Outputoverloads and bothl3Outputoverloads. If a deprecated name ever stops producingthe same envelope structure, the suite fails.
Reviewed with a code-reviewer + code-attacker pass: zero P0, zero P1.
Closes #48