List and view the delta between two IG ASTs

Diff two ASTs by resource key: added, removed, changed (with a structural element-level differential) and version-changed resources, plus edges added and removed; optionally fold in the incremental plan, and render just-the-docs pages (an index that lists, a page per resource that shows) every one of which carries the provisional mark. list <ast> summarises one AST.

Skills it satisfies

A skill states the capability; this Tool is one way to exercise it. Each skill’s declared input and output contract follows, where it has one.

ig-ast-delta

List and view what changed between two IG ASTs, check whether an AST is still valid for the IG’s current inputs, and render the delta as just-the-docs pages that carry the provisional mark. Read before trusting a cached AST, before reviewing an incremental IG build, and before rendering anything from a cache.

Source: fhir-harness/skills/fhir-ig-base/ig-ast-delta.md.

Also satisfied by: ig-ast-jsonld, ig-ast-list, ig-ast-pages, ig-ast-plan, ig-ast-render, ig-ast-validity, ig-cache.

The skill declares no I/O contract (schemas/skills/ig-ast-delta/{input,output}.schema.json).

Inputs and outputs

Each port names a shared type by IRI, so two Tools for one skill can be checked for interchangeability.

porttyperequireddescriptionconstraint
inbaseFilesystemPathyesstring · A filesystem path, possibly outside the repository. Not admissible as a command-line argument.
inheadFilesystemPathyesstring · A filesystem path, possibly outside the repository. Not admissible as a command-line argument.
inplanFilesystemPathstring · A filesystem path, possibly outside the repository. Not admissible as a command-line argument.
insiteFilesystemPathA directory inside the IG’s just-the-docs source; pages are wrapped in Liquid raw blocks so FHIR narratives’ Liquid is not executed.string · A filesystem path, possibly outside the repository. Not admissible as a command-line argument.
outchangedCountinteger · A non-negative count — how many of something, or how many to show. Zero is a real answer.
outpagesCountPages written: one index, one per changed or version-changed resource.integer · A non-negative count — how many of something, or how many to show. Zero is a real answer.

Processes and tasks

Steps this Tool can carry out, because each names a skill it satisfies:

processsteplanevia skill
Is the incremental IG AST what a full build would have produced?Check the base AST against the inputsIncremental build (system)ig-ast-delta
Is the incremental IG AST what a full build would have produced?Diff the two ASTsIncremental build (system)ig-ast-delta
Is the incremental IG AST what a full build would have produced?Read the deltaQC reviewerig-ast-delta
An IG site, built from the AST on its cache branchRestore and judge the cached ASTSite build (agent, stage-local)ig-ast-delta
SMART Guideline end to endReview each L3 asset (before / after if adapted)Human adjudicatorsig-ast-delta

How it is deployed and reached

  • Command line. From the repository root: bun run fhir-harness/scripts/ig-ast.ts diff <base> <head> [--plan plan.json] [--json delta.json] [--site <dir>].
  • GitHub Actions. 11 workflow line(s) run its command:
workflowline
fhir-harness/.github/workflows/ig-ast-refresh.yml173bun run fhir-harness/scripts/ig-ast.ts validity output-ast --ig . > "$RUNNER_TEMP/ast-validity.json"
fhir-harness/.github/workflows/ig-ast-refresh.yml177bun run fhir-harness/scripts/ig-ast.ts cache-line output-ast --ig . 2>/dev/null \|\| true
fhir-harness/.github/workflows/ig-ast-refresh.yml199kind=$(bun run fhir-harness/scripts/ig-ast.ts build-kind output-ast 2>/dev/null \|\| echo full)
fhir-harness/.github/workflows/ig-ast-refresh.yml427&& bun run fhir-harness/scripts/ig-ast.ts validity output-ast --ig . > /dev/null; then
fhir-harness/.github/workflows/ig-ast-refresh.yml430kind=$(bun run fhir-harness/scripts/ig-ast.ts build-kind output-ast 2>/dev/null \|\| echo incremental)
fhir-harness/.github/workflows/ig-ast-refresh.yml433bun run fhir-harness/scripts/ig-ast.ts cache-line output-ast --ig . --warm 2>/dev/null \|\| true
fhir-harness/.github/workflows/ig-ast-refresh.yml459source_digest=$(bun run fhir-harness/scripts/ig-ast.ts digest --ig .) \\
fhir-harness/.github/workflows/ig-ast-refresh.yml498now=$(bun run fhir-harness/scripts/ig-ast.ts digest --ig .)
fhir-harness/.github/workflows/ig-ast-refresh.yml501bun run fhir-harness/scripts/ig-ast.ts source-inputs output-ast --digest "$source_digest" --pre-export "$PRE_EXPORT"
fhir-harness/.github/workflows/ig-ast-refresh.yml505bun run fhir-harness/scripts/ig-ast.ts validity output-ast --ig . \\
fhir-harness/.github/workflows/ig-release.yml123bun run fhir-harness/scripts/ig-ast.ts build-kind "$IN/output-ast" --require-full

As an API: its operation in the OpenAPI document and the MCP tool list of its layer.

installnone
runtimebun
networkno
when to choose it
whenReviewing an incremental build, or comparing an incremental AST with a full one.
limitsStructural, not FHIR-semantic: a reordered repeating element shows a change at every index. At most 200 differential rows per resource; the rest is counted, never dropped silently.
costReads both ASTs once.

What it is made of

Linked data

The Tool is published as its own JSON-LD document at its IRI, https://litlfred.github.io/folio-assistant/fhir-harness/tools/ig-ast-diff.jsonld, partOf its layer’s document. The node below is the definition this page was drawn from, and is embedded in the page as application/ld+json.

{
  "@context": "https://litlfred.github.io/folio-assistant/fhir-harness/fhir-harness.context.jsonld",
  "@id": "https://litlfred.github.io/folio-assistant/fhir-harness/tools/ig-ast-diff.jsonld",
  "@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
  "partOf": "https://litlfred.github.io/folio-assistant/fhir-harness/fhir-harness.jsonld",
  "name": "ig-ast-diff",
  "title": "List and view the delta between two IG ASTs",
  "description": "Diff two ASTs by resource key: added, removed, changed (with a structural element-level differential) and version-changed resources, plus edges added and removed; optionally fold in the incremental plan, and render just-the-docs pages (an index that lists, a page per resource that shows) every one of which carries the provisional mark. `list <ast>` summarises one AST.",
  "install": {
    "none": true
  },
  "invoke": {
    "shell": "bun run fhir-harness/scripts/ig-ast.ts diff <base> <head> [--plan plan.json] [--json delta.json] [--site <dir>]"
  },
  "io": {
    "inputs": [
      {
        "name": "base",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/FilesystemPath",
        "required": true
      },
      {
        "name": "head",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/FilesystemPath",
        "required": true
      },
      {
        "name": "plan",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/FilesystemPath",
        "required": false
      },
      {
        "name": "site",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/FilesystemPath",
        "description": "A directory inside the IG's just-the-docs source; pages are wrapped in Liquid raw blocks so FHIR narratives' Liquid is not executed.",
        "required": false
      }
    ],
    "outputs": [
      {
        "name": "changed",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Count"
      },
      {
        "name": "pages",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Count",
        "description": "Pages written: one index, one per changed or version-changed resource."
      }
    ]
  },
  "satisfies": [
    "ig-ast-delta"
  ],
  "requirements": {
    "runtime": [
      "bun"
    ],
    "network": false
  },
  "selection": {
    "when": "Reviewing an incremental build, or comparing an incremental AST with a full one.",
    "limits": "Structural, not FHIR-semantic: a reordered repeating element shows a change at every index. At most 200 differential rows per resource; the rest is counted, never dropped silently.",
    "cost": "Reads both ASTs once."
  }
}

folio-assistant — code under the Apache License 2.0, documentation under CC BY 3.0. Generated schema and API references are rebuilt from source on every push to main.

deployed dev