Rebuild only the cone of a change and merge it into the AST

Write the unchanged part of a base AST as a FHIR package into the package cache, build a temporary IG of only the rebuild set with the stock Publisher, merge the result into a mixed-provenance AST (builtAt per resource), and repeat while the merged graph’s cone reaches resources that were not rebuilt.

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-publisher-fork

Requirements for an agent working a local experimental fork of the IG Publisher — which repositories, what the AST must carry, what must not change, and the acceptance criteria. Read before forking, and before reporting a fork’s work complete.

Source: fhir-harness/skills/fhir-ig-base/ig-publisher-fork.md.

Also satisfied by: fhir-cache-seed-npm, fhir-package-mirror, ig-ast-export, ig-ast-measure-real-igs, ig-ast-plan, smart-fhir-cache-seed.

The skill declares no I/O contract (schemas/skills/ig-publisher-fork/{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
inastFilesystemPathyesstring · A filesystem path, possibly outside the repository. Not admissible as a command-line argument.
inigFilesystemPathyesstring · A filesystem path, possibly outside the repository. Not admissible as a command-line argument.
inoutFilesystemPathyesstring · A filesystem path, possibly outside the repository. Not admissible as a command-line argument.
incache-folderFilesystemPathKeeps the *.ast-cache packages out of ~/.fhir/packages.string · A filesystem path, possibly outside the repository. Not admissible as a command-line argument.
infsh-usersFilesystemPathfsh-file-users/v1 from fsh-cone --file-users, so a changed RuleSet- or Alias-only file reaches its users instead of forcing a full build.string · A filesystem path, possibly outside the repository. Not admissible as a command-line argument.
outroundsCountRounds to a fixed point; exit 3 when it does not converge, which means run a full build.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
An IG site, built from the AST on its cache branchBuild the IG with the AST exporterAST refresh (GitHub runner: IG Publisher with the AST exporter)ig-publisher-fork

How it is deployed and reached

  • Command line. From the repository root: java -cp "target/classes:$(cat cp.txt)" org.hl7.fhir.igtools.ast.IncrementalBuildCli -ast <base> -ig <ig> -out <dir> [-cache-folder <dir>] [-fsh-users <json>].
  • 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.

installcli: git clone -b claude/ast-export https://github.com/litlfred/fhir-ig-publisher && cd fhir-ig-publisher/ast-export && mvn -q package && mvn -q dependency:build-classpath -Dmdep.outputFile=cp.txt
runtimejava, sushi
networkyes

When a host it reaches is refused:

host / errorremedy
packages.fhir.orgtool fhir-cache-seed-npm
tx.fhir.orgnone: No declared Tool replaces the terminology server. The HL7 IG Publisher’s own -tx n/a skips terminology validation, at the cost of not validating it.
repo1.maven.orgnone: The Maven build needs Maven Central; a populated ~/.m2 from an earlier build is the only other source.
when to choose it
whenA plan says incremental.
limitsUNTESTED end to end as of 2026-09-30. The fork README names the risks to check first, beginning with a canonical collision between the cache package and the temporary IG.
costA Publisher run over the cone, plus loading the cache package.

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-incremental-build.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-incremental-build.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-incremental-build",
  "title": "Rebuild only the cone of a change and merge it into the AST",
  "description": "Write the unchanged part of a base AST as a FHIR package into the package cache, build a temporary IG of only the rebuild set with the stock Publisher, merge the result into a mixed-provenance AST (`builtAt` per resource), and repeat while the merged graph's cone reaches resources that were not rebuilt.",
  "install": {
    "cli": "git clone -b claude/ast-export https://github.com/litlfred/fhir-ig-publisher && cd fhir-ig-publisher/ast-export && mvn -q package && mvn -q dependency:build-classpath -Dmdep.outputFile=cp.txt"
  },
  "invoke": {
    "shell": "java -cp \"target/classes:$(cat cp.txt)\" org.hl7.fhir.igtools.ast.IncrementalBuildCli -ast <base> -ig <ig> -out <dir> [-cache-folder <dir>] [-fsh-users <json>]"
  },
  "io": {
    "inputs": [
      {
        "name": "ast",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/FilesystemPath",
        "required": true
      },
      {
        "name": "ig",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/FilesystemPath",
        "required": true
      },
      {
        "name": "out",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/FilesystemPath",
        "required": true
      },
      {
        "name": "cache-folder",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/FilesystemPath",
        "description": "Keeps the `*.ast-cache` packages out of `~/.fhir/packages`.",
        "required": false
      },
      {
        "name": "fsh-users",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/FilesystemPath",
        "description": "`fsh-file-users/v1` from `fsh-cone --file-users`, so a changed RuleSet- or Alias-only file reaches its users instead of forcing a full build.",
        "required": false
      }
    ],
    "outputs": [
      {
        "name": "rounds",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Count",
        "description": "Rounds to a fixed point; exit 3 when it does not converge, which means run a full build."
      }
    ]
  },
  "satisfies": [
    "ig-publisher-fork"
  ],
  "requirements": {
    "runtime": [
      "java",
      "sushi"
    ],
    "network": true
  },
  "remedies": [
    {
      "host": "packages.fhir.org",
      "tool": "fhir-cache-seed-npm"
    },
    {
      "host": "tx.fhir.org",
      "none": "No declared Tool replaces the terminology server. The HL7 IG Publisher's own `-tx n/a` skips terminology validation, at the cost of not validating it."
    },
    {
      "host": "repo1.maven.org",
      "none": "The Maven build needs Maven Central; a populated `~/.m2` from an earlier build is the only other source."
    }
  ],
  "selection": {
    "when": "A plan says `incremental`.",
    "limits": "UNTESTED end to end as of 2026-09-30. The fork README names the risks to check first, beginning with a canonical collision between the cache package and the temporary IG.",
    "cost": "A Publisher run over the cone, plus loading the cache package."
  }
}

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