New Badge Version and Project Endpoints | MathSwe Ops Services (2024/09/18)

Getting a badge to show a project’s version in its documentation is more difficult for MathSwe projects as these can be granular independent projects inside the same repository, like microservices. MathSwe also requires project badges with their icon to present them. The Services API needs to automate these badges for version and project to improve the development and (primarily) fasten the release of MathSwe projects.

Allow hyphens in Hostname

Sep 16: PR #3 merged into by tobiasbriones

It fixes the rejection of valid hostnames with hyphens.

Add router with MS-Client CORS

Sep 16: PR #4 merged into by tobiasbriones

It adds the Itty-Router dependency that routes CF Worker applications and sets up the CORS origin to only accept MathSwe-Client curated origins.

Implement inference of project version from GitHub repository

Sep 17: PR #5 merged into by tobiasbriones

It defines a Git platform and build-system abstractions such as GitHub, NPM, and Cargo to provide an implementation through the GitHub API that reads a project (including subdirectories) given its repository URL, infers the build system it uses, finally, it reads the project’s version.

It only reads public repositories at branch main (production) for simplicity.

export async function inferVersion(
    gitPlatform: GitPlatform,
    user: string,
    repo: string,
    path: Option<string>,
): Promise<Either<string, string>>

InferVersion API

const rustProject = await inferVersion(
    gitHub,
    "rust-unofficial",
    "awesome-rust",
    none,
);
const jsProject = await inferVersion(
    gitHub,
    "jquery",
    "jquery",
    none,
);
const nestedMvp = await inferVersion(
    gitHub,
    "mathswe-ops",
    "mathswe-ops---mvp",
    some("system"),
);

console.log(rustProject);
console.log(jsProject);
console.log(nestedMvp);

Infering Project Versions

{ _tag: 'Right', right: '0.1.0' }
{ _tag: 'Right', right: '4.0.0-beta.2' }
{ _tag: 'Right', right: '0.1.0' }

Output: Infering Project Versions

Besides providing some GitHub and build system abstractions, it’s a useful API that an endpoint can use to get the version of a given GitHub project, even if it is a nested subdirectory, like microservice (independently versioned) or mono repository with sub-projects.

Add test suite for readBuildSystem

Sep 17: PR #6 merged into by tobiasbriones

It adds some tests for the method that reads the GitHub project’s build system by mocking the file list API response.

Implement endpoint badge/version

Sep 18: PR #7 merged into services/dev <- badge by tobiasbriones

It provides the new endpoint that takes a repository GitHub URL, or one of its subprojects (e.g., microservice), and responds with the badge showing its current version.

Implement endpoint badge/project and enhance badge styles and code

Sep 19: PR #8 merged into services/dev <- badge by tobiasbriones

The badge/project endpoint provides the main badge for a given MathSwe project (including MVPs).

The version badge endpoint required a relatively complex implementation to fetch a project version and return the SVG badge. It also required me to fix some styles in the SVG template. I also applied more FP with the FP-TS library and MathSwe-TS I designed in the previous PR #2, which was my first time using them.

The git-platform/git-platform and git-platform/project modules provide GitHub support to get a repository version by reading it directly from the GitHub API. They also infer a subproject version, like a microservice or a project in a mono repository, by reading the version in their build tool file, such as package.json or Cargo.toml.

Regarding the project badge, it accepts MathSwe projects with MVP variants (query param), which have their icon defined inside the Services app, so I just have to call the endpoint to keep README.md files clean.

The integration adds two GET endpoints to the MathSwe Ops Services API to fetch the version/release and the project SVG badge. The version badge takes a GitHub repository in its route params and a “path” query if you want a subproject version, while the project badge takes a MathSwe project and an “MVP” query. The new badge endpoints provide automation steps when releasing and creating MathSwe projects by implementing their custom standards.