Skip to content

check-sources --json emits a machine-readable drift report #2298

Description

@mesejo

Parent

#2293

What to build

check-sources --json emits one machine-readable document, so drift can be consumed by a
script or a CI step without parsing human output or re-deriving anything.

Unlike the human output, JSON is buffered and emitted once after all probing has finished, so
the document is always complete or absent.

The root is an object keyed by entry name — direct lookup, not a list a consumer has to
search. Each entry carries its rolled-up state, its leaves, and its bundled counts. The root
also carries the rolled-up state and the exit code, so a consumer never has to re-derive the
precedence rule from $?.

Each leaf reports its kind, display name, state, recorded schema and live schema. Recorded
and live are objects mapping column name to dtype string, which makes the delta one line of
set arithmetic on the consumer's side. There is deliberately no delta field: it would be
redundant and permanent API surface. Live is null for table-missing and unreachable, and
an error message appears only when there is one.

The document shape is documented in the module docstring.

Acceptance criteria

  • --json output parses and matches the shape in the spec
  • Root is keyed by entry name and carries a rolled-up state and exit code
  • Recorded and live are column-name-to-dtype objects, with no delta field
  • Live is null for table-missing and for unreachable; the error field appears only when non-null
  • An entry with only bundled sources reports empty leaves and its bundle counts
  • Nothing is printed before probing completes, and the exit code matches the human run for the same input
  • The document shape is documented in the module docstring

Blocked by

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    featureready-for-agentScoped ticket an agent can pick up unattended

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions