Crate adrs_core 

adrs-core

The engine behind the adrs command-line tool: a standalone library for creating, reading, linking, validating, and exporting Architecture Decision Records (ADRs).

Depend on adrs-core directly when you want to manage ADRs from your own program – a build tool, an editor integration, or an AI agent – instead of shelling out to the CLI. The CLI is a thin layer over this crate, so anything adrs does is available here as a normal Rust API.

Key types

• Repository – the main entry point. Open or initialize a directory of ADRs, then list, new_adr, link, supersede, and set_status.
• Adr – a single decision record: number, title, AdrStatus, body sections, AdrLinks, tags, and MADR metadata (deciders, consulted, informed).
• AdrStatus and LinkKind – typed status values and link relationships (e.g. Supersedes / SupersededBy).
• Config and discover – repository configuration and upward directory discovery (find the ADR directory from a nested path).
• Parser – parse an ADR from markdown, in either legacy (adr-tools) or YAML-frontmatter form.
• The export module – convert ADRs to and from the JSON-ADR interchange format, handy for feeding a decision log to other tools or to an AI agent that reasons over it.
• The lint module – repository health checks via check_all: broken links, duplicate numbers, numbering gaps, and missing fields.
• Error and Result – the library’s error type, built on thiserror.

Modes

ADRs can be stored in two on-disk formats:

• Compatible mode (default): markdown-only, interoperable with adr-tools. Reads both legacy and next-gen files; writes legacy.
• Next-gen mode: YAML frontmatter for structured metadata, enabling richer features like typed links, tags, and stronger validation.

The mode is chosen at Repository::init time (the ng argument) or via Config, and the parser transparently reads either format.

Quick start

use adrs_core::Repository;

// Initialize a repository (compatible mode).
let repo = Repository::init(tmp.path(), None, false)?;

// Create a decision record.
let (adr, _path) = repo.new_adr("Use PostgreSQL for persistence")?;
assert_eq!(adr.title, "Use PostgreSQL for persistence");

// List all ADRs (`init` seeds the first one).
let all = repo.list()?;
assert!(all.len() >= 2);

Exporting to JSON-ADR

export_repository converts an open Repository to the JSON-ADR format. For a plain directory that isn’t an initialized adrs repository, use export_directory (or export_directory_with_warnings to also receive a message for every file that failed to parse, rather than skipping silently).

More examples

The examples directory has runnable programs: create_and_list, link_adrs, export_json, and lint_repository.

Re-exports

pub use export::ConsideredOption;

pub use export::ImportOptions;

pub use export::ImportResult;

pub use export::JSON_ADR_SCHEMA;

pub use export::JSON_ADR_VERSION;

pub use export::JsonAdr;

pub use export::JsonAdrBulkExport;

pub use export::JsonAdrLink;

pub use export::JsonAdrSingle;

pub use export::RepositoryInfo;

pub use export::ToolInfo;

pub use export::export_adr;

pub use export::export_directory;

pub use export::export_directory_with_warnings;

pub use export::export_repository;

pub use export::import_to_directory;

pub use lint::Issue;

pub use lint::IssueSeverity;

pub use lint::LintReport;

pub use lint::check_all;

pub use lint::check_repository;

pub use lint::lint_adr;

pub use lint::lint_all;

pub use doctor::Check;

pub use doctor::Diagnostic;

pub use doctor::DoctorReport;

pub use doctor::Severity;

pub use doctor::check as doctor_check;

Modules

doctor

Health checks for ADR repositories.

export

JSON-ADR export functionality.

lint

ADR linting using mdbook-lint rules.

Structs

Adr

An Architecture Decision Record.

AdrLink

A link between ADRs.

Config

Configuration for an ADR repository.

DiscoveredConfig

Result of discovering configuration.

Parser

Parser for ADR files.

Repository

A repository of Architecture Decision Records.

Template

A template for generating ADRs.

TemplateEngine

Template engine for managing and rendering templates.

Enums

AdrStatus

The status of an ADR.

ConfigMode

The mode of operation for the ADR tool.

ConfigSource

Where the configuration was loaded from.

Error

Errors that can occur when working with ADRs.

LinkKind

The kind of link between ADRs.

TemplateFormat

Built-in template formats.

TemplateVariant

Template variants for different levels of detail.

Functions

discover

Discover configuration by searching up the directory tree.

Type Aliases

Result

Result type alias using the library’s error type.