mizcausevic-dev/kg-suite-fleet-overview-action

Purpose and principal workflow: This GitHub Action scans the JSON files in the configured dir, routes documents from a mixed Kinetic Gain Suite fleet, and produces a composition report for terminal output and optionally a pull-request comment. The initiating actor is the GitHub Actions runner executing the Action in response to a workflow event—typically pull_request; optional gates can fail the run for missing core protocols or too many unrouted documents.

Components

Action entry and orchestration

• GitHub Actions runner — *null repository path.* Supplies the Action’s inputs and GitHub event environment, and invokes the configured JavaScript entry point.

• Action metadata — action.yml. Declares the reusable GitHub Action interface and execution configuration; its exact input and runtime declarations were not included in the sampled source.

• Action entry point — src/index.ts. Reads INPUT_* variables and GitHub environment values, calls the runner, and exits using its result or reports an error.

• Workflow runner — src/runner.ts. Validates inputs, loads JSON files, orchestrates report generation and publication, writes Action outputs, and applies configured failure gates.

• JSON fleet directory — *null repository path.* The caller-provided directory of JSON documents that the runner scans.

Protocol routing and composition

• Protocol detector — src/detect.ts. Implements the vendored routing logic, identifying supported protocols by version discriminator or document shape and returning confidence.

• Fleet overview builder — src/overview.ts. Routes each loaded document, extracts protocol-specific IDs and names, and groups and summarizes results, including missing core protocols, low-confidence detections, and unrouted files.

• Overview data types — src/types.ts. Defines protocol identifiers and the detection, document-summary, bucket, and fleet-report structures used across the workflow.

Report and publication

• Markdown formatter — src/format.ts. Converts the fleet report into the composition overview, including per-protocol tables, missing-protocol callouts, low-confidence results, and unrouted documents.

• GitHub Issues API — *null repository path.* Receives a PR comment when publication is enabled and the runner has a token and PR number.

Relationships

• GitHub Actions runner -> Action entry point: invokes the configured Action; the entry point reads runner-provided environment variables.

• Action entry point -> Workflow runner: calls run with parsed inputs and GitHub environment values.

• Workflow runner -> JSON fleet directory: reads the configured directory’s .json files and parses them.

• Workflow runner -> Fleet overview builder: passes loaded documents for report generation.

• Fleet overview builder -> Protocol detector: detects a protocol and confidence for each document before the builder classifies it.

• Fleet overview builder -> Overview data types: constructs the report using the shared protocol and summary structures.

• Workflow runner -> Markdown formatter: formats the completed report for output and, when appropriate, comment publication.

• Workflow runner -> GitHub Actions runner: appends report counts to GITHUB_OUTPUT, writes the report, and returns a failure result when configured gates are exceeded.

• Workflow runner -> GitHub Issues API: sends a POST request with the formatted comment body when comment publication is requested and the required token, repository, and PR number are available.

Coverage limits: The Action metadata and README document the intended interface, but action.yml content was not sampled, so its exact runtime wiring could not be verified. The sampled implementation shows comment creation but not comment updates or deduplication. The detector is vendored in this repository; the README’s references to external protocol-detection and overview packages do not establish runtime calls to those packages.