# hailstails/hone architecture

> Architecture diagram of the GitHub repository hailstails/hone, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hailstails/hone
- Repository: https://github.com/hailstails/hone

## Overview

Hone is a repository-discipline checker: a user invokes its CLI, which reads the repository’s selected rules, configuration and exception records, dispatches checks to the chosen engine, then reports a verdict. Its domain stages include rule selection, mechanism execution, exception/debt handling and reporting; separate commands manage debt records and migrate version-1 repositories. The README documents these workflows and engine capabilities; sampled source confirms parts of engine dispatch and rule loading, but not every command’s internal call graph.

Main entry points: [`core/check/run-check.ts`](https://github.com/hailstails/hone/blob/main/core/check/run-check.ts) (Check workflow), [`core/run/engine-run.ts`](https://github.com/hailstails/hone/blob/main/core/run/engine-run.ts) (Engine dispatch), [`core/check/tool-command.ts`](https://github.com/hailstails/hone/blob/main/core/check/tool-command.ts) (Hone CLI), [`core/consumer-selection/consumer-selection.ts`](https://github.com/hailstails/hone/blob/main/core/consumer-selection/consumer-selection.ts) (Rule selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and commands"]
  node_cli["Hone CLI<br/>[tool-command.ts]"]
  node_arguments["Command arguments"]
end

subgraph group_assessment["Assessment core"]
  node_check["Check workflow<br/>[run-check.ts]"]
  node_selection["Rule selection"]
  node_rules["Rule-set reader<br/>[rule-set-reader.ts]"]
  node_catalogue["Symptom catalogue"]
  node_run["Engine orchestration<br/>[engines-run.ts]"]
  node_dispatch["Engine dispatch<br/>[engine-run.ts]"]
  node_mechanism["Mechanism contract"]
  node_report["Verdict report<br/>[report-text.ts]"]
end

subgraph group_engines["Check engines"]
  node_walker["Walker engine<br/>[runner.ts]"]
  node_eslint["ESLint engine<br/>[runner.ts]"]
end

subgraph group_records["Records and migration"]
  node_records[("Exception records")]
  node_answering["Finding answers<br/>[answering.ts]"]
  node_debt["Debt commands"]
  node_authorise["Authorise location<br/>[authorising.ts]"]
  node_upgrade["Version upgrade"]
end

node_user(("Repository user"))
node_repo[("Target repository")]

node_user -->|"invokes"| node_cli
node_cli -->|"parses commands"| node_arguments
node_cli -->|"runs check"| node_check
node_check -->|"reads configuration"| node_repo
node_check -->|"loads selection"| node_selection
node_selection -->|"reads rules"| node_rules
node_check -->|"loads catalogue"| node_catalogue
node_check -->|"runs selected engines"| node_run
node_run -->|"dispatches checks"| node_dispatch
node_dispatch -->|"loads runner contract"| node_mechanism
node_dispatch -->|"runs standalone checks"| node_walker
node_dispatch -->|"runs ESLint checks"| node_eslint
node_check -->|"reads exceptions"| node_records
node_check -->|"answers findings"| node_answering
node_check -->|"prints verdict"| node_report
node_user -->|"records or prunes"| node_debt
node_debt -->|"updates records"| node_repo
node_user -->|"authorises location"| node_authorise
node_authorise -->|"writes record"| node_repo
node_user -->|"requests migration"| node_upgrade
node_upgrade -->|"migrates repository"| node_repo

click node_cli "https://github.com/hailstails/hone/blob/main/core/check/tool-command.ts"
click node_arguments "https://github.com/hailstails/hone/blob/main/core/command-line/command-arguments.ts"
click node_check "https://github.com/hailstails/hone/blob/main/core/check/run-check.ts"
click node_selection "https://github.com/hailstails/hone/blob/main/core/consumer-selection/consumer-selection.ts"
click node_rules "https://github.com/hailstails/hone/blob/main/core/rule-set-reader/rule-set-reader.ts"
click node_catalogue "https://github.com/hailstails/hone/blob/main/core/symptom-catalogue/symptom-catalogue.ts"
click node_run "https://github.com/hailstails/hone/blob/main/core/run/engines-run.ts"
click node_dispatch "https://github.com/hailstails/hone/blob/main/core/run/engine-run.ts"
click node_mechanism "https://github.com/hailstails/hone/blob/main/core/mechanism-port/runner-module-schema.ts"
click node_walker "https://github.com/hailstails/hone/blob/main/mechanisms/audit/runner/runner.ts"
click node_eslint "https://github.com/hailstails/hone/blob/main/mechanisms/eslint/runner/runner.ts"
click node_records "https://github.com/hailstails/hone/blob/main/core/exception-records/exception-layout.ts"
click node_answering "https://github.com/hailstails/hone/blob/main/core/records/answering.ts"
click node_report "https://github.com/hailstails/hone/blob/main/core/verdict/report-text.ts"
click node_debt "https://github.com/hailstails/hone/blob/main/core/check/run-record-debt-command.ts"
click node_authorise "https://github.com/hailstails/hone/blob/main/core/records/authorising.ts"
click node_upgrade "https://github.com/hailstails/hone/blob/main/core/upgrade/command/run-upgrade-command.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_arguments,node_user toneBlue
class node_check,node_selection,node_rules,node_catalogue,node_run,node_dispatch,node_mechanism,node_report,node_repo toneAmber
class node_walker,node_eslint toneMint
class node_records,node_answering,node_debt,node_authorise,node_upgrade toneRose
```

## Components

### CLI and commands

- [Hone CLI](https://github.com/hailstails/hone/blob/main/core/check/tool-command.ts): `core/check/tool-command.ts`
- [Command arguments](https://github.com/hailstails/hone/blob/main/core/command-line/command-arguments.ts): `core/command-line/command-arguments.ts`

### Assessment core

- [Check workflow](https://github.com/hailstails/hone/blob/main/core/check/run-check.ts): `core/check/run-check.ts`
- [Rule selection](https://github.com/hailstails/hone/blob/main/core/consumer-selection/consumer-selection.ts): `core/consumer-selection/consumer-selection.ts`
- [Rule-set reader](https://github.com/hailstails/hone/blob/main/core/rule-set-reader/rule-set-reader.ts): `core/rule-set-reader/rule-set-reader.ts`
- [Symptom catalogue](https://github.com/hailstails/hone/blob/main/core/symptom-catalogue/symptom-catalogue.ts): `core/symptom-catalogue/symptom-catalogue.ts`
- [Engine orchestration](https://github.com/hailstails/hone/blob/main/core/run/engines-run.ts): `core/run/engines-run.ts`
- [Engine dispatch](https://github.com/hailstails/hone/blob/main/core/run/engine-run.ts): `core/run/engine-run.ts`
- [Mechanism contract](https://github.com/hailstails/hone/blob/main/core/mechanism-port/runner-module-schema.ts): `core/mechanism-port/runner-module-schema.ts`
- [Verdict report](https://github.com/hailstails/hone/blob/main/core/verdict/report-text.ts): `core/verdict/report-text.ts`

### Check engines

- [Walker engine](https://github.com/hailstails/hone/blob/main/mechanisms/audit/runner/runner.ts): `mechanisms/audit/runner/runner.ts`
- [ESLint engine](https://github.com/hailstails/hone/blob/main/mechanisms/eslint/runner/runner.ts): `mechanisms/eslint/runner/runner.ts`

### Records and migration

- [Exception records](https://github.com/hailstails/hone/blob/main/core/exception-records/exception-layout.ts): `core/exception-records/exception-layout.ts`
- [Finding answers](https://github.com/hailstails/hone/blob/main/core/records/answering.ts): `core/records/answering.ts`
- [Debt commands](https://github.com/hailstails/hone/blob/main/core/check/run-record-debt-command.ts): `core/check/run-record-debt-command.ts`
- [Authorise location](https://github.com/hailstails/hone/blob/main/core/records/authorising.ts): `core/records/authorising.ts`
- [Version upgrade](https://github.com/hailstails/hone/blob/main/core/upgrade/command/run-upgrade-command.ts): `core/upgrade/command/run-upgrade-command.ts`

### Other components

- **Repository user**
- **Target repository**

## Connections

- Repository user → Hone CLI: invokes (evidence: `README.md`)
- Hone CLI → Command arguments: parses commands (evidence: `README.md`)
- Hone CLI → Check workflow: runs check (evidence: `README.md`)
- Check workflow → Target repository: reads configuration (evidence: `README.md`)
- Check workflow → Rule selection: loads selection (evidence: `core/check/run-check.ts`)
- Rule selection → Rule-set reader: reads rules (evidence: `core/consumer-selection/consumer-selection.ts`)
- Check workflow → Symptom catalogue: loads catalogue (evidence: `README.md`)
- Check workflow → Engine orchestration: runs selected engines (evidence: `README.md`)
- Engine orchestration → Engine dispatch: dispatches checks (evidence: `core/run/engines-run.ts`)
- Engine dispatch → Mechanism contract: loads runner contract (evidence: `core/run/engine-run.ts`)
- Engine dispatch → Walker engine: runs standalone checks (evidence: `README.md`)
- Engine dispatch → ESLint engine: runs ESLint checks (evidence: `README.md`)
- Check workflow → Exception records: reads exceptions (evidence: `README.md`)
- Check workflow → Finding answers: answers findings (evidence: `README.md`)
- Check workflow → Verdict report: prints verdict (evidence: `README.md`)
- Repository user → Debt commands: records or prunes (evidence: `README.md`)
- Debt commands → Target repository: updates records (evidence: `README.md`)
- Repository user → Authorise location: authorises location (evidence: `README.md`)
- Authorise location → Target repository: writes record (evidence: `README.md`)
- Repository user → Version upgrade: requests migration (evidence: `README.md`)
- Version upgrade → Target repository: migrates repository (evidence: `README.md`)
