Write the IG AST viewer: a page per instance holding ig-ast directories, and a hub

For every visualiser an instance declares renderedBy: ig-ast-pages, write the hub at <locale>/<harness>/<id>/ and, with subgraphs: "instance", one page per instance that declares an ig-ast directory, at …/<instance>/. Each lists the ASTs the directory holds: the IG’s package id, resources in total and by type, dependency edges (resolved inside the IG, by origin, by kind), the rebuild plan when one is recorded, and what stays provisional. A declared directory not on disk — a branch-family member not restored, which is the normal case — is reported UNKNOWN with the family it would be restored from, never as zero ASTs. ig-ast-list summarises one AST it is handed; this Tool needs no AST path.

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-diff, ig-ast-jsonld, ig-ast-list, 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
insiteRepoPathA site being built: the pages go under it (visualiser-writers.ts in cat-harness-tools passes it). Absent, they go under the checkout’s site directory.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inrootRepoPathThe checkout whose declarations are read. Default: the checkout holding the working directory.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
incheckFlagWrite nothing; exit 1 when a page is stale, missing or orphaned.boolean · A boolean switch — projects to a bare flag, with no value word
outpagesCountPages written: the hub and one per instance.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/gen-ig-ast-pages.ts.
  • GitHub Actions. No workflow in this checkout runs its command.

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

installnone
runtimebun
networkno
when to choose it
whenPublishing a site that should show which IG ASTs each instance holds.
limitsCounts what the cache holds; it does not check an AST against its IG’s inputs (ig-ast-validity does) or diff two (ig-ast-diff).
costReads each AST’s manifest and dependency document once.

What it is made of

It draws the viewer for the graph typology ig-ast.

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-pages.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-pages.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-pages",
  "title": "Write the IG AST viewer: a page per instance holding `ig-ast` directories, and a hub",
  "description": "For every visualiser an instance declares `renderedBy: ig-ast-pages`, write the hub at `<locale>/<harness>/<id>/` and, with `subgraphs: \"instance\"`, one page per instance that declares an `ig-ast` directory, at `…/<instance>/`. Each lists the ASTs the directory holds: the IG's package id, resources in total and by type, dependency edges (resolved inside the IG, by origin, by kind), the rebuild plan when one is recorded, and what stays provisional. A declared directory not on disk — a branch-family member not restored, which is the normal case — is reported UNKNOWN with the family it would be restored from, never as zero ASTs. `ig-ast-list` summarises one AST it is handed; this Tool needs no AST path.",
  "install": {
    "none": true
  },
  "invoke": {
    "shell": "bun run fhir-harness/scripts/gen-ig-ast-pages.ts"
  },
  "io": {
    "inputs": [
      {
        "name": "site",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "A site being built: the pages go under it (`visualiser-writers.ts` in cat-harness-tools passes it). Absent, they go under the checkout's site directory.",
        "required": false,
        "arg": {
          "flag": "--site"
        }
      },
      {
        "name": "root",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The checkout whose declarations are read. Default: the checkout holding the working directory.",
        "required": false,
        "arg": {
          "flag": "--root"
        }
      },
      {
        "name": "check",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
        "description": "Write nothing; exit 1 when a page is stale, missing or orphaned.",
        "required": false
      }
    ],
    "outputs": [
      {
        "name": "pages",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Count",
        "description": "Pages written: the hub and one per instance."
      }
    ]
  },
  "satisfies": [
    "ig-ast-delta"
  ],
  "requirements": {
    "runtime": [
      "bun"
    ],
    "network": false
  },
  "renders": [
    "ig-ast"
  ],
  "selection": {
    "when": "Publishing a site that should show which IG ASTs each instance holds.",
    "limits": "Counts what the cache holds; it does not check an AST against its IG's inputs (`ig-ast-validity` does) or diff two (`ig-ast-diff`).",
    "cost": "Reads each AST's manifest and dependency document 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