api #

Builds the dependency graph and runs cycle/wildcard analysis, tolerating cycles (reports rather than throws). The shared core of gitops_analyze and gitops_validate, which format the result themselves.

A package whose current version the registry doesn't show, with no changesets to publish.

A semver bump kind: major, minor, or patch.

Calculates every dependency update between packages (to_dependency_updates for each repo, in repos order) and the breaking cascades: each package whose release is breaking for some dependent's prod/peer range, with those dependents.

Best-effort read of a repo's root Cargo.toml for the identity fields the dashboard renders. Returns null when there's no Cargo.toml.

Extracts name/version/description/repository from the [package] and [workspace.package] tables of a Cargo.toml.

Deliberately not a full TOML parser: it scans for simple key = "value" string entries in those two tables, which covers both a single-crate manifest and a workspace root. Inline-table values like version = { workspace = true } (and the equivalent version.workspace = true) are ignored — a member crate inheriting from the workspace has no literal here, and fuz_repos only ever reads a repo's root manifest, where these are concrete. The first non-empty value for a key wins, so a top-level [package] takes precedence over [workspace.package] when both appear.

The handful of identity fields fuz_repos reads from a Rust repo's Cargo.toml to render it on the dashboard. Everything is optional — a workspace root has no name, and any field may be absent or inherited.

Changeset operations for reading and predicting versions from .changeset/*.md files.

Checks a repos status --json report on the repos gitops_sync generates the site data from (repo_readiness_for_gen).

Checks whether pkg@version is on the npm registry, by npm view.

Reads a repos status --fetch --json report for a release step: each key's entry ready (repo_readiness_for_publish), the report fetched, and busy detection available, since a live session it can't vouch for may be working in any checkout. A step commits rewrites in a dependent and names packages to publish, so a repo that isn't ready is held, and the reasons say how to fix it.

How a repo's declared ci diverges from its workflow files on disk.

Compares bump types. Returns positive if a > b, negative if a < b, 0 if equal.

Compares two x.y.z versions.

Creates file-system backed cache for fuz_util's fetch.js API responses.

Cache invalidation strategy: If cache file can't be read or parsed, entire cache is cleared (delete file) and starts fresh. This handles format changes.

Uses structuredClone to track changes - only writes to disk if data modified. Formatted with gro's format_file before writing for version control friendliness.

The npm operations over a npm program, resolved each time one runs.

A config module's default export in function form.

Every dependency section, in the order updates are listed.

The auto-generated changeset's filename. A dependent keeps one, rewritten as each of its dependencies publishes, so its release notes list every dependency that moved under one entry rather than one entry per publish.

Cycles and wildcard dependencies found by DependencyGraph.analyze.

A package.json dependency section.

A dependency range that moves to name its dependency's version after the release.

Determines the bump type for a package from its changesets.

When multiple changesets exist for the same package, returns the highest bump type (major > minor > patch) to ensure the most significant change is reflected in the version bump.

Fetches the check runs on ref and reduces them to one overall status and conclusion.

Fetches GitHub metadata (CI status, PRs) for all repos.

Fetches sequentially with a delay before each request to respect GitHub API rate limits. Uses await_in_loop intentionally to avoid parallel requests overwhelming the API. CI status is read for the branch each repo's registry entry follows (main when it names none), and that branch is written to RepoJson.branch.

A repo whose registry entry declares no CI (ci: false) isn't asked for check runs, and one with none on its branch isn't a failure: both leave check_runs null without logging. A failed fetch is logged as an error and leaves null for that repo's check_runs or pull_requests, and the remaining repos still fetch — except a 401 response or a repo URL without a GitHub owner, which throw.

Options for fetch_repo_data.

Formats data and outputs to file or stdout based on options.

Supports three formats:

• stdout: Uses logger for colored/styled output (cannot use with --outfile)
• json: Stringified JSON
• markdown: Formatted markdown text

Formats dev circular dependencies as styled strings. Returns array of lines for inclusion in output.

Formats production/peer circular dependencies as styled strings. Returns array of lines for inclusion in output.

Formats the diagnostics' readiness block: a header and a line per problem, saying what each repo not at rest is doing instead — or no lines when every repo is at rest. Not a failure: the diagnostics read repos as they sit.

What a readiness problem says is wrong with the repo keyed key, and the fix, when there is one to name.

Formats waves as one line each, numbered from 1: 1. a, b.

Formats wildcard dependencies as styled strings. Returns array of lines for inclusion in output.

The typed error of a failed FsOperations call, discriminated on kind.

File system operations for reading and writing files.

Errors are typed via FsError (`not_found | permission_denied | already_exists | io_error) so callers can branch on kind` instead of regex-matching message.

Generates markdown changeset content for dependency updates.

Creates properly formatted changeset with YAML frontmatter, summary, and categorized list of breaking vs regular updates. Output format matches changesets CLI for consistency.

Generates the publishing plan in one pass over the prod/peer topological order. Each package's dependencies are settled before it is reached, so its required bump — from its prod/peer ranges against each dependency's version after the release — is final when computed: explicit changesets, escalation, or an auto-changeset, with no iteration.

Every package's version after the release is its predicted one when it publishes and its current one otherwise, so a dependent whose range trails a dependency's current version gets that rewrite too, along with the bump it implies.

Central initialization function for the publishing and dependency tasks (gitops_analyze, gitops_plan, gitops_release, gitops_validate): resolves the config's repos through repos status (resolve_gitops_repos), then loads each repo as its working tree sits (local_repos_load) with no module analysis — those tasks read each package's name, version, and dependencies, never its modules — so it moves no ref and writes nothing.

Determines version prefix to use when updating dependencies.

Strategy:

• Wildcard (*): Use caret (^) as default
• Has existing prefix: Preserve it (^, ~, >=, <=, etc)
• No prefix: Use default_strategy

This preserves user intent while handling wildcard replacements sensibly.

Gets the version prefix (^, ~, >=, <=, or empty string).

Adds files to git staging area and throws if anything goes wrong.

Commits files alone with a message, leaving anything else staged out of the commit, and throws if anything goes wrong. files must be non-empty: an empty list would commit the whole index.

Minimal interface for GitHub API calls, satisfied structurally by fuz_ui's Library.

Git operations the release step authors with: staging and committing dependency rewrites and auto-changesets. All operations return Result instead of throwing errors. Where each repo sits (branch, dirt, relation to origin) is ReposOperations's to report.

Default number of repos to process concurrently during parallel operations.

The private repos a public host package must not publish. gitops_sync writes every configured repo's GitHub metadata into the host project's generated repos.json — a public site's data when the host package is public — so a private repo in that config would leak. Empty when the host is private.

Default path to the gitops configuration file.

Default timeout in milliseconds for gitops_release --wait to wait on registry propagation (10 minutes). npm's CDN is eventually consistent, so a published version can take minutes to show.

A project's gitops config.

Groups names into levels by their longest dependency path: a name's level is one past the deepest of its dependencies in names, and dependencies outside names don't count. So a level's names never depend on each other, and each depends only on names in earlier levels — work within a level can run in parallel. Within a level, names follow rank when given (config order, say), else order.

Checks if a repo has any changeset files (excluding README.md).

Used by the publishing plan to determine which packages need to be published. Returns false if .changeset directory doesn't exist or contains only README.md.

Determines if a bump is a breaking change based on semver rules. Pre-1.0: minor bumps are breaking 1.0+: major bumps are breaking

Loads a gitops config module and validates it.

Runs repos status <keys…> --json and parses its report.

Loads a resolved repo as its working tree sits (the tasks read where each repo sits from repos status, and repos sync moves them). Moves no ref.

1. Loads library_json, with the module analysis or without it (modules)
2. Creates Library and extracts dependency maps

A repo with no package.json but a Rust Cargo.toml loads as a dashboard-only cargo repo instead.

Loads each resolved repo (local_repo_load), in order.

Resolves a gitops config's registry keys against a repos status report, in config order. Every key must name an owned repo that's present and was probed; each that doesn't is a problem, and any problem fails the whole resolve, naming them all.

Fully loaded local repo with Library and extracted dependency data. Does not extend LocalRepoPath - Library is source of truth for name/repo_url/etc.

Options for loading resolved repos (local_repo_load, local_repos_load).

A configured repo resolved through repos status: present on disk, before its library is loaded. See local_repos_resolve.

Logs all dependency analysis results (wildcards, production cycles, dev cycles). Convenience function that calls all three logging functions in order.

Logs dev circular dependencies as info. Dev cycles are normal and non-blocking, so they're informational, not warnings.

Logs production/peer circular dependencies as errors. Production cycles block publishing and must be resolved.

Logs a complete publishing plan to the console.

Displays errors, the waves, version changes grouped by scenario, dependency-only updates, packages awaiting the registry, warnings, and a summary.

Logs the diagnostics' readiness block as warnings (stderr, so a `--format json or markdown` document on stdout stays clean): each npm repo not at rest, and how. Logs nothing when every one is at rest. Reads the entries repos status already reported, from local refs.

Logs wildcard dependencies as warnings. Wildcard dependencies require attention and should be reviewed.

Merges new dependency changes into existing ones, in order: a dependency in both keeps its first from_version, takes the later to_version, the larger bump, and is breaking if either change was.

Whether a dependency range must move to name new_version: a wildcard always does, and so does a range whose base version is older. One already naming it, or a newer version (a range staged ahead of a publish), doesn't — the rewrite never moves a range backward. A base that isn't x.y.z moves whenever it differs, and a protocol range (file:, workspace:, npm:) never.

Normalizes version string for comparison.

Strips prefixes (^, ~, >=) to get bare version number. Handles wildcards as-is. Used by needs_update to compare versions.

Registry operations: whether a version is out, and waiting for one to propagate. npm's own config picks the registry, so a scope pointed elsewhere is read there.

The side effects of the registry checks — running npm, sleeping, and reading the clock — injected so tests drive them with plain objects.