Roadmap to v1.0.0

[sachin-panayil]

This issue tracks the work required to take codejson-crosswalk from its current state to an official v1 release.

Phase 1: Core Correctness

• Define and export the public API in src/index.ts

  • Currently src/index.ts is an empty stub. Decide which functions and types are part of the public surface, and export them cleanly so downstream consumers can import from the package root.
  • Acceptance: A TypeScript project can import { fromCodemetaToCodejson, fromCodejsonToCodemeta, MappingEntry } from "codejson-crosswalk" with full type inference.

• Remove hardcoded test scripts from handler.ts

  • The bottom of handler.ts reads real files and logs results at import time. Move this into an example script or a test, leaving handler.ts as pure library code.
  • Acceptance: Importing anything from handler.ts produces no side effects, no console output, and no file reads.

• Set up bun test and write unit tests for the engine

  • Add test coverage for getNestedValue, setNestedValue, and convert, including edge cases like missing paths, nested writes that merge into existing objects, and target-only defaults.
  • Acceptance: bun test runs successfully, each helper has unit tests covering the happy path and at least two failure modes, and coverage on these three files is at least 90%.

• Add round-trip integration tests for codemeta ↔ code.json

  • Convert real sample files in each direction and assert on the resulting output shape. Include at least one round-trip test that documents what information is preserved and what is lost.
  • Acceptance: Integration tests exist for both directions, run as part of bun test, and the lossy fields are explicitly asserted rather than silently dropped.

• Create a fixtures/ directory with representative sample files

  • Build a small library of valid input files covering minimal, fully-populated, and edge-case shapes (multi-license, multi-author, missing optional fields). These serve both tests and documentation.
  • Acceptance: At least three codemeta fixtures and three code.json fixtures exist under fixtures/, each with a short comment or companion README explaining what it represents.

Phase 2: Safety

• Add Zod schemas for codemeta and code.json

  • Define Zod schemas that describe valid input for each format. Use them to parse and validate input inside the coordinator functions before the engine runs.
  • Acceptance: Malformed input produces a Zod validation error with a readable message identifying the offending field, rather than silently producing garbage output.

• Validate converted output against the target schema

  • After convert returns, validate the result against the target format's Zod schema. Decide whether invalid output throws or returns a warnings array, and document the choice.
  • Acceptance: A transform that returns an incorrectly shaped value is caught by output validation in a test, and the behavior (throw vs warn) is documented in the API docs.

• Type the transform functions properly

  • Replace (value: unknown) => unknown signatures with types derived from the Zod schemas, so transforms declare what they accept and return.
  • Acceptance: A transform with a mismatched input or output type produces a compile-time TypeScript error, and all existing transforms have typed signatures.

• Emit a conversion report alongside converted output

  • Produce a structured report describing which source fields were ignored, which target fields were filled with defaults, and any lossy transforms that ran. The report can be opt-in or always returned.
  • Acceptance: Callers can obtain a report for any conversion, and at least one test asserts on report contents for a known-lossy input (e.g. multi-author codemeta → code.json).

Phase 3: Usability

• Generate API documentation with TypeDoc

  • Set up TypeDoc to generate reference documentation from the exported functions and types. Add JSDoc comments to every public export.
  • Acceptance: Running the docs command produces an HTML site covering every public export, and the generated docs are published (GitHub Pages or committed to docs/).

• Add a CLI entry point

  • Expose a command-line interface so users can convert files without writing TypeScript. Support reading from stdin or a file path and writing to stdout or a file.
  • Acceptance: After npm install -g codejson-crosswalk, the command codejson-crosswalk input.json --to codejson produces a valid converted file, and --help describes all flags.

• Create an examples/ directory with runnable usage scripts

  • Provide minimal, focused example scripts for the common use cases: converting a single file, batch-converting a directory, and converting with output validation.
  • Acceptance: At least three runnable examples exist under examples/, each with a short README explaining what it demonstrates and how to run it.

• Audit and improve error messages

  • Walk through every failure mode — malformed input, missing files, failed validation, transform errors — and make sure each produces a message that identifies what went wrong and where.
  • Acceptance: A test suite for error paths exists, and each tested error includes both the failure type and a location or field reference in the message.

Phase 4: Maintainability

• Set up GitHub Actions for CI

  • Add a workflow that runs install, test, lint, and coverage on every PR and push to main. Fail the build if tests fail or coverage drops below a threshold.
  • Acceptance: A PR with a failing test or a lint violation is blocked by a red CI check, and the coverage threshold is documented in the workflow file.

• Add ESLint and Prettier

  • Adopt a shared preset (e.g. @typescript-eslint/recommended plus Prettier) and wire both into the CI workflow. No hand-rolled style debates.
  • Acceptance: bun run lint and bun run format both exist and succeed on the codebase, and the CI workflow runs both on every PR.

Phase 5: Release

• Finalize package.json fields for publication

  • Set main, module, types, exports, and engines correctly so that downstream consumers can import the package cleanly in both ESM and CommonJS contexts and know which runtimes are supported.
  • Acceptance: A test consumer project can install the packaged tarball (npm pack output) and import both types and runtime code without configuration.

• Create a CHANGELOG and adopt semver

  • Add a CHANGELOG.md following the Keep a Changelog convention, document the v1.0.0 release, and update contributing docs to require changelog entries in future PRs.
  • Acceptance: CHANGELOG.md exists with a v1.0.0 entry, and CONTRIBUTING.md instructs contributors to update it.

• Set up a release workflow to publish to npm on tags

  • Add a GitHub Actions workflow that publishes to npm when a version tag is pushed. Configure the npm token as a repository secret.
  • Acceptance: Pushing a tag like v0.0.1-test to a test branch triggers a successful (dry-run or scoped) publish, proving the workflow works before the real release.

• Cut and publish v1.0.0

  • Run through a pre-release checklist (tests green, docs current, changelog updated, version bumped, compliance files in place), tag the release, and publish.
  • Acceptance: codejson-crosswalk@1.0.0 is installable from npm, and a GitHub release exists with release notes mirroring the changelog entry.