Roadmap to v0.1.0

Xem xét thiết lập GitHub Actions hiện có và package.json, sau đó tập trung vào hai tác vụ phát hành chưa được đánh dấu: phát hành khi có các tag phiên bản và tạo v1.0.0. Được xem là hoàn tất khi một tag thử nghiệm chứng minh workflow có thể phát hành an toàn, tiếp theo là một package [email protected] có thể cài đặt và một bản phát hành GitHub có ghi chú phản ánh CHANGELOG.md.

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 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: [email protected] is installable from npm, and a GitHub release exists with release notes mirroring the changelog entry.