Skip to content

feat: align output helpers with Data/Classification/Procedure - #49

Merged
beogip merged 1 commit into
mainfrom
beogip/issue-48-align-output-helpers
Jul 28, 2026
Merged

feat: align output helpers with Data/Classification/Procedure#49
beogip merged 1 commit into
mainfrom
beogip/issue-48-align-output-helpers

Conversation

@beogip

@beogip beogip commented Jul 28, 2026

Copy link
Copy Markdown
Owner

Summary

Aligns the output-schema helpers with the Data / Classification / Procedure tool-type
vocabulary from the deterministic-tools spec.
The library previously used an L1/L2/L3 "output spectrum" naming that no longer matches the spec.

Before After
l1Output dataTypeOutput
l2Output classificationTypeOutput
l3Output procedureTypeOutput

Non-breaking

The three old names stay exported as @deprecated declaration aliases bound to the same
function objects — no wrapper, no second implementation:

/** @deprecated Use {@link classificationTypeOutput}. Kept until the next breaking change, then removed. */
export const l2Output = classificationTypeOutput;

Verified against the emitted declarations in dist/index.d.ts, which is the contract consumers
actually get: the @deprecated JSDoc survives into the build, and typeof classificationTypeOutput
preserves 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 instructions field.
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

Area What
src/output-helpers.ts Canonical renames, rewritten JSDoc, three @deprecated aliases, type-change policy notes
src/index.ts Barrel exports all six names
src/tool-class.ts JSDoc worked example, prose, two runtime error strings
src/types.ts JSDoc on SubcommandSpec.output
README.md, examples/ Code samples, API table (with deprecated rows), headings and prose
tests/ Migrated existing coverage to canonical names; added a behavioral deprecated-alias suite
.gitignore Ignore .cothinker/

Scope boundaries

CHANGELOG.md and docs/specs/* are deliberately untouched — they are historical records, and
rewriting them would falsify what actually shipped. The unrelated --level CLI flag in the test
fixtures is also untouched; bun test continuing to pass on those cases proves the sweep didn't
over-reach.

Testing

  • bun test124 pass, 0 fail (244 assertions)
  • bunx tsc --noEmit → clean
  • bunx biome check . → clean

New describe("deprecated output helper aliases") suite exercises the old names behaviorally
through Tool.invoke() — asserting the full output envelope, not schema-object identity — covering
both l2Output overloads and both l3Output overloads. If a deprecated name ever stops producing
the same envelope structure, the suite fails.

Reviewed with a code-reviewer + code-attacker pass: zero P0, zero P1.

Closes #48

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.
@beogip
beogip merged commit 0af16f5 into main Jul 28, 2026
6 checks passed
@beogip
beogip deleted the beogip/issue-48-align-output-helpers branch July 28, 2026 23:51
beogip pushed a commit that referenced this pull request Jul 28, 2026
# [0.2.0](v0.1.5...v0.2.0) (2026-07-28)

### Features

* align output helpers with Data/Classification/Procedure ([#48](#48)) ([#49](#49)) ([0af16f5](0af16f5))
@github-actions

Copy link
Copy Markdown
Contributor

🎉 This PR is included in version 0.2.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: align output helpers with Data/Classification/Procedure

1 participant