Module github 

Shared infrastructure for the GitHub-native text formats: --format github-annotations (workflow commands on stdout) and --format github-summary (step-summary markdown).

The escaping contract is byte-compatible with the strict typed fallback in action/scripts/annotate.sh, NOT the legacy jq san helper: message bodies escape % to %25, CR to %0D, and LF to %0A; property values (file=, title=) additionally escape , to %2C and : to %3A. Non-ASCII text passes through as UTF-8. Line numbers below 1 clamp to 1, and fallow’s 0-based columns convert to GitHub’s 1-based workflow-command columns at this boundary.

Structs

Annotation

One GitHub workflow-command annotation, pre-escaping. message holds real newlines; render_annotation applies the escaping contract.

RenderOptions

Ambient options for the GitHub renderers, resolved once per render at the CLI print boundary so the pure render functions stay deterministic.

Enums

AnnotationLevel

Annotation severity, ordered most-severe-first so a plain sort puts errors ahead of warnings ahead of notices (GitHub shows at most 10 annotations per type per step; the worst findings must sort into view).

PackageManager

Package manager for fix-command hints, mirroring the jq layer’s PKG_MANAGER parameterization plus native lockfile sniffing (bun is new relative to the jq layer).

PathRebase

How report paths are rebased onto the git repository root. CI platforms address files by repo-root-relative path (GitHub annotations, GitLab’s Code Quality widget, the review-discussion APIs), while fallow emits analysis-root-relative paths; when the analysis root is a subdirectory (e.g. packages/app/), every path needs the offset prefixed.

Functions

arr

Iterate an optional array field (.[key][]? in jq terms).

b

Boolean field, or false when missing.

budget_notice

The trailing total notice: always emitted after the annotation stream when at least one annotation exists, so consumers know when GitHub’s 10-per-type display cap truncated the visible set. There is deliberately no producer-side cap (the bundled action keeps its own MAX_ANNOTATIONS during migration).

clamp_line

Clamp a line number below 1 to 1: GitHub rejects line=0, and the typed annotation fallback in annotate.sh applies the same floor.

escape_message

Escape a workflow-command message body: % to %25, CR to %0D, LF to %0A. The % escape runs first so already-escaped input escapes again (matching the jq esc helper’s gsub order).

escape_property

Escape a workflow-command property value (file=, title=): message escaping plus , to %2C and : to %3A, because commas separate properties and colons terminate the command prefix.

fmt_num

Format a JSON number the way jq interpolates it: integers without a decimal point, floats in shortest round-trip form.

init_report_prefix

Resolve the presentation prefix once, after --report-path-prefix is recorded. Call at most once.

num

Format a numeric field, or "0" when missing.

one_based_col

Convert fallow’s 0-based column to GitHub’s 1-based workflow-command column (the jq layer’s col + 1 convention).

render_annotation

Render one annotation as a workflow-command line. Property order matches the jq layer: file, line, endLine, col, title.

report_prefix

The prefix prepended to every CI-facing path emitted this run. Empty when the analysis root is the repository root, or when no CLI run resolved it.

report_rebase

Rebase every CI-facing report path emitted for this run onto the repo root.

resolve_package_manager

Resolve the package manager: an explicit PKG_MANAGER env value wins (action parity; unrecognized values fall back to npm exactly like the jq else branch), otherwise lockfile sniffing at the analysis root.

resolve_render_options

Resolve render options from the process environment and the analysis root.

s

String field, or "" when missing or not a string.

set_report_path_prefix

Record the --report-path-prefix flag value. Call at most once.

sort_annotations

Sort annotations most-severe-first, then by path, then by line. Default result ordering is path-sorted (ADR-004), so without this sort GitHub’s visible 10 per type would be the lexicographically first paths, not the worst findings.

u

Unsigned number field, or 0 when missing.