codejson-core Refactor

[sachin-panayil]

codejson-core Refactor

Problem

This repository owned the code.json schema, its Zod validation rules, and the
logic that merges repository metadata into an existing file. That put four separate concerns in one action: talking to GitHub, measuring the repository, deciding what a valid code.json is, and deciding how a new observation merges over an old file.

Two costs followed:

• Any other tool that wanted to produce or check a code.json
  had to reimplement the schema.
• Keeping the schema current required a monthly workflow that regenerated a Zod schema from gov-codejson and opened a PR against a large generated file

Solution

The schema, validation, and merge logic now come from
codejson-core, a library shared the provides logic to validate and assemble code.json's. This action binds to the libraries CMS profile in a single file, src/codejson.ts, and owns only what core leaves out:

• using the GitHub API
• running SCC
• scanning dependencies
• opening the pull request

A generated code.json is a draft by design so things like status, longDescription, and the other unobservable fields are blank for a human to complete from the PR. The pull_request status check is unchanged and remains the gate that keeps invalid files off main.

AI Usage

• Generated AI was used in this contribution
• Description:
  • Claude Code was used to create tests, generate docs and code, and review my overall refactoring plan
• Type of Assistance:
  • Code generation
  • Documentation
  • Debugging
  • Testing
  • Refactoring
  • Other:
• Scope of Usage:
  • Files within this PR
• AI System Used:
  • ChatGPT
  • Claude
  • Gemini
  • GitHub Copilot
• Level of Modification:
  • As-is
  • Modified
  • Used as inspiration
• Prompts Used:
  • Create tests for the newly created codejson.ts file that includes coverage of the usage of the new package
  • Review this refactor plan of removing the hardcoded logic of validation and assembly that is now modularized from codejson-core
  • Update documentation reflecting these changes and help me fill out the PR template

Result

The schema is version-pinned by the codejson-core release, so schema updates reach this action as a Dependabot bump rather than a code change, and the update-codejson-schema workflow is deleted. Roughly 2,300 lines leave this repository and the action is more lightweight. This repo is now simply a wrapper around core logic and an interface to Github Actions, significantly reducing its concerns and introducing more separation.

One known follow-up: src/codejson.ts works around two gaps in codejson-core. Its assemble rejects in-progress drafts, and its CMS baseline leaves enum keysundefined so they vanish on serialization. Both get fixed upstream in codejson-core 0.2.0, after which the code becomes even more simpler.

Test Plan

• npm ci
• npm test
• npm run lint
• npm run package
• review e2e test status

To verify manually, run the action against a repository with an existing
code.json and confirm the generated file is unchanged apart from
date.metadataLastUpdated, then run it against one with no code.json and
confirm the log lists the blank fields as warnings while the PR is still opened. I'm gonna actually test these on repos of different cases and paste the links here: