axm-ingot 0.5.0

axm-ingot — Shared helper library for the AXM forge

axm-ingot is the AXM forge's shared helper library: the single home for small, general-purpose functions that more than one package needs. Instead of copy-pasting the same logic into axm-ast, axm-audit, axm-init and axm-anvil — and testing it N times, inconsistently — the logic lives here once, is tested once, and is imported as a normal workspace dependency.

It is a Python library with no CLI or MCP tool. Workspace, suite and console helpers read the filesystem; they do not write files or launch processes.

Features

• uv-workspace resolution — resolve_workspace() parses [tool.uv.workspace], expands member globs, subtracts exclude, keeps only directories carrying a pyproject.toml, and returns members sorted by directory basename.
• Project-root discovery — find_project_root() walks parents to the first ancestor holding any pyproject.toml (never returns None); find_workspace_root() finds the nearest uv-workspace root specifically.
• Pure parsing primitive — parse_workspace_members() returns the raw, unexpanded member strings from pyproject text, with no filesystem access.
• Typed value objects — frozen ResolvedWorkspace and Member dataclasses describe the resolved result.
• Compact rendering — primitives plus the submodule-level render_result walker for readable text. Preserve structured data when exact types matter.
• Console and test helpers — console_script locates a script without executing it; tally_outcomes counts supplied outcome lines.
• Function-specific fallbacks — pyproject read/parse errors and rejected glob patterns have documented fallbacks. Arbitrary inputs and filesystem operations do not share a blanket never-raises guarantee.
• Modern Python — 3.12+ with strict typing, zero runtime dependencies beyond the standard library.

Installation

Requires Python 3.12 or newer. In a Python project managed by uv:

uv add axm-ingot

Or, as a sibling package inside the workspace, declare it as a workspace dependency in your pyproject.toml:

[project]
dependencies = ["axm-ingot"]

[tool.uv.sources]
axm-ingot = { workspace = true }

Quick Start

Parse workspace declarations without creating any files:

uv run python - <<'PY'
from axm_ingot.uv import parse_workspace_members

members = parse_workspace_members('[tool.uv.workspace]\nmembers = ["packages/*"]\n')
print(members)
PY

This prints ['packages/*']: the declared patterns, without glob expansion or filesystem access.

Usage

Discover workspace members

Run this from a project directory to locate its nearest project and enclosing uv workspace:

from pathlib import Path

from axm_ingot import (
    find_project_root,
    find_workspace_root,
    resolve_workspace,
)

# Walk up to the nearest project root (any pyproject.toml ancestor).
root = find_project_root(Path.cwd())
print("Project:", root)

# Resolve a uv workspace into its sorted members.
ws_root = find_workspace_root(Path.cwd())
workspace = resolve_workspace(ws_root) if ws_root is not None else None
if workspace is not None:
    for member in workspace.members:
        print(member.name, "->", member.path)

else:
    print("No uv workspace found")

Member.name is the directory basename, not the distribution name. Use paths as keys when two members may share a basename. find_project_root falls back to the resolved starting directory if no project exists.

Public API

render_result and record_table are imported from axm_ingot.render, not from the package root. See the API reference for exact signatures, import paths and limitations, and the temporary-workspace tutorial for a runnable example. Internal suite-discovery utilities live in axm_ingot.suite.

Why it exists

A monorepo accumulates duplication: the same "walk up to the project root", "read [tool.uv.workspace].members", "resolve the workspace members" snippets reappear in package after package, each with its own subtle bugs and its own half-tested copy. axm-ingot is the deliberate counter-move — a thin, dependency-light ingot of common code that downstream packages melt into their own logic:

• Factor once, fix once — a bug fixed here is fixed everywhere.
• Test once, trust everywhere — helpers are covered in this package, so consumers don't re-test the same primitive.
• Stable public surface — consumers import from axm_ingot, not from each other, avoiding cross-tool coupling.

The shared surface covers workspace discovery, text rendering, durations, console-script lookup and pytest outcome tallies. The library grows by promotion, subject to reuse and dependency checks.

What belongs here (the light-leaf invariant)

axm-ingot is a dependency-graph leaf imported across the whole galaxy. Its value depends on staying light: every consumer that imports it for one small helper inherits all of its dependencies. A fat leaf is no longer a leaf.

Hard rule — a helper may be promoted into axm-ingot only if its dependencies are stdlib-only — it adds no dependency at all. dependencies here stays empty. Even Pydantic — a near-universal AXM dependency — does not belong: it is still a dependency, and adding it breaks the leaf invariant. Value objects here are frozen @dataclass, not BaseModel.

A reusable-but-heavy helper does not come here even when it has several consumers: keep it reuse_in_place (import it from the package that owns it), or give it a thematic light lib of its own (e.g. an axm-net for resilient HTTP) — never the generic leaf. The Rule of Three (≥ 2 consumers) is necessary for promotion but not sufficient; the dependency gate is the second lock.

Documentation

• Published documentation
• Getting started: a temporary workspace.
• Promote a helper: reuse and dependency gates.
• API reference: imports, signatures and fallbacks.
• Architecture: the shared-library boundaries.

The MkDocs home page is docs/index.md, separate from this README.

Development

This package is part of the axm-forge workspace.

git clone https://github.com/axm-protocols/axm-forge.git
cd axm-forge
uv sync --all-packages --all-groups
uv run --package axm-ingot --directory packages/axm-ingot pytest -x -q

License

Licensed under Apache-2.0. See LICENSE.