# kiyoon/changelog-action architecture

> Architecture diagram of the GitHub repository kiyoon/changelog-action, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kiyoon/changelog-action
- Repository: https://github.com/kiyoon/changelog-action

## Overview

##### Project type and purpose
- This is an open-source GitHub Action, written in TypeScript, whose sole purpose is to generate a Markdown CHANGELOG based on Conventional Commits between two Git tags (or commit refs).
- It is packaged for consumption on GitHub Marketplace and invoked inside GitHub workflows.

##### File structure
- Top-level files and folders:
- action.yml – metadata that defines inputs, outputs, and the entrypoint
- src/ – TypeScript source code:
– index.ts – main entrypoint
– index_testrun.ts – for local/testing scenarios
– utils/ – helper modules: github.ts, semver.ts(+spec), newFile.ts, set.ts
- dist/ – compiled JavaScript shipped to npm/GitHub Action runner
- .github/workflows/ – CI pipelines (auto-release, deploy)
- package.json, tsconfig.json, biome.jsonc, bun.lock – build/configuration
- That “action.yml” ties together the compiled dist/index.js, declares the inputs (token, version tags, exclude rules, etc.), and the one output (“changes”).

##### Key insights from README
- Describes how the Action is triggered (workflow_dispatch or on push), what inputs it accepts, and what outputs it emits.
- Explains two high-level use cases: generating a release PR changelog or generating a GitHub Release body.
- Outlines features such as PR linkification, breaking-change detection, file injection, and idempotence.

##### Main components
a. GitHub Runner (host environment)
b. Action Metadata & Entrypoint
– action.yml
– dist/index.js invoked by the runner
c. Core Modules
– CLI layer (index.ts) – read inputs, orchestrate flow
– GitHub API client (utils/github.ts) – fetch tags, commits, PRs
– SemVer logic (utils/semver.ts) – determine previous tag, sort commits
– File I/O (utils/newFile.ts) – read/write CHANGELOG.md
– Output setter (utils/set.ts) – set the “changes” output variable
d. External Systems
– GitHub REST API – to list tags, commits, PR details
– Git repository (local clone) – to run git commands if needed
e. Downstream steps (outside this Action)
– Pull-request creator or Release publisher consuming the output

##### Relationships and data flow
1. Runner reads action.yml → launches Node process (dist/index.js).
2. Entrypoint loads inputs (token, new-version-tag, previous-version-tag, etc.).
3. GitHub client module uses the token to call GitHub’s REST API → retrieves tags & commit history.
4. SemVer module computes the correct “previous” tag and filters commits by type/skip lists.
5. Markdown generator assembles commits into a versioned CHANGELOG snippet.
6. File I/O module optionally injects the snippet into CHANGELOG.md in the workspace.
7. Output setter publishes the generated snippet as the Action’s output (“changes”).
8. Subsequent workflow steps read this output to create PRs or Releases.

##### Architectural patterns and design principles
- Modular design: each util (GitHub API, semver, file I/O) is isolated for testability.
- Single Responsibility Principle: index.ts delegates work to specialized modules.
- Idempotence: File-inject logic checks and avoids duplicate entries.
- Configuration-driven behavior through action inputs (no hard-coded values).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% GitHub Runner Environment
    subgraph "GitHub Runner" 
        direction TB
        RunnerNode(("Node.js Runtime")):::external
        ActionYML["action.yml"]:::orchestration
        DistIndex["dist/index.js"]:::orchestration
    end

    %% Orchestration Layer
    subgraph "Action Orchestration" 
        direction TB
        CLI["src/index.ts"]:::orchestration
        TestRun["src/index_testrun.ts"]:::orchestration
    end

    %% Utility Modules
    subgraph "Utils Modules" 
        direction TB
        GitHubClient["utils/github.ts"]:::internal
        SemVerEngine["utils/semver.ts"]:::internal
        SemVerSpec["utils/semver.spec.ts"]:::internal
        FileInjector["utils/newFile.ts"]:::internal
        OutputSetter["utils/set.ts"]:::internal
    end

    %% Storage
    CHANGELOG["CHANGELOG.md"]:::storage

    %% External Systems
    GitHubAPI((GitHub REST API)):::external
    LocalGit[(Local Git Repo)]:::external

    %% Configuration & CI/CD
    subgraph "Config & CI/CD" 
        direction TB
        PackageJSON["package.json"]:::internal
        TSConfig["tsconfig.json"]:::internal
        BiomeJSONC["biome.jsonc"]:::internal
        BunLock["bun.lock"]:::internal
        AutoRelease[".github/workflows/auto-release.yml"]:::internal
        DeployCI[".github/workflows/deploy.yml"]:::internal
    end

    %% Connections
    RunnerNode -->|invoke| ActionYML
    ActionYML -->|entrypoint| DistIndex
    DistIndex -->|orchestrates| CLI
    DistIndex -->|test mode| TestRun

    CLI -->|listTags,listCommits| GitHubClient
    GitHubClient -->|API call| GitHubAPI
    CLI -->|determinePreviousTag| SemVerEngine
    SemVerEngine -->|tested by| SemVerSpec
    CLI -->|generateSnippet| FileInjector
    FileInjector -->|write| CHANGELOG
    CLI -->|setOutput| OutputSetter
    OutputSetter -->|emit| CHANGELOG

    CLI -->|git commands| LocalGit
    OutputSetter -->|exposes| RunnerNode

    %% Config & CI/CD connections
    RunnerNode --> PackageJSON
    RunnerNode --> TSConfig
    RunnerNode --> BiomeJSONC
    RunnerNode --> BunLock
    RunnerNode --> AutoRelease
    RunnerNode --> DeployCI

    %% Click Events
    click ActionYML "https://github.com/kiyoon/changelog-action/blob/main/action.yml"
    click DistIndex "https://github.com/kiyoon/changelog-action/blob/main/dist/index.js"
    click CLI "https://github.com/kiyoon/changelog-action/blob/main/src/index.ts"
    click TestRun "https://github.com/kiyoon/changelog-action/blob/main/src/index_testrun.ts"
    click GitHubClient "https://github.com/kiyoon/changelog-action/blob/main/src/utils/github.ts"
    click SemVerEngine "https://github.com/kiyoon/changelog-action/blob/main/src/utils/semver.ts"
    click SemVerSpec "https://github.com/kiyoon/changelog-action/blob/main/src/utils/semver.spec.ts"
    click FileInjector "https://github.com/kiyoon/changelog-action/blob/main/src/utils/newFile.ts"
    click OutputSetter "https://github.com/kiyoon/changelog-action/blob/main/src/utils/set.ts"
    click PackageJSON "https://github.com/kiyoon/changelog-action/blob/main/package.json"
    click TSConfig "https://github.com/kiyoon/changelog-action/blob/main/tsconfig.json"
    click BiomeJSONC "https://github.com/kiyoon/changelog-action/blob/main/biome.jsonc"
    click BunLock "https://github.com/kiyoon/changelog-action/blob/main/bun.lock"
    click AutoRelease "https://github.com/kiyoon/changelog-action/blob/main/.github/workflows/auto-release.yml"
    click DeployCI "https://github.com/kiyoon/changelog-action/blob/main/.github/workflows/deploy.yml"

    %% Styles
    classDef orchestration fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef internal fill:#b3d9ff,stroke:#333,stroke-width:1px
    classDef external fill:#ffd9b3,stroke:#333,stroke-width:1px
    classDef storage fill:#e6e6e6,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
