FSH dependency cone

Compute the dependency cone over an IG’s FSH graph, and the blast radius of a set of changed files. It is what lets an incremental IG build rebuild less than everything.

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.

fhir-validation

Source: fhir-harness/skills/content/fhir-ig-authoring/fhir-validation.md.

Also satisfied by: check-translation-supplements.

input [1..1]output [1..1]sushiResult [0..1]publisherResult [0..1]conformanceResults [0..*]fhir-validation«skill»fhir-validationinput : FHIRValidationInput [1..1]output : FHIRValidationOutput [1..1]FHIRValidationInput«json-schema»FHIRValidationInputigRoot : string [1..1]validationLevel : "sushi-only" | "publisher-qa" | "full" [0..1]targetProfiles : string[] [0..*]FHIRValidationOutput«json-schema»FHIRValidationOutputoverallStatus : "pass" | "warnings" | "errors" [1..1]sushiResult : FHIRValidationOutput.sushiResult [0..1]publisherResult : FHIRValidationOutput.publisherResult [0..1]conformanceResults : FHIRValidationOutput.conformanceRes… [0..*]FHIRValidationOutput.sushiResult«json-schema»FHIRValidationOutput.sushiResultstatus : string [0..1]errors : integer [0..1]warnings : integer [0..1]FHIRValidationOutput.publisherResult«json-schema»FHIRValidationOutput.publisherResultstatus : string [0..1]qaHtmlPath : string [0..1]errorCount : integer [0..1]warningCount : integer [0..1]infoCount : integer [0..1]FHIRValidationOutput.conformanceResults«json-schema»FHIRValidationOutput.conformanceResultsresource : string [0..1]profile : string [0..1]status : "conformant" | "non-conformant" [0..1]issues : string[] [0..*]

input — fhir-harness/schemas/skills/fhir-validation/input.schema.json

fieldtyperequireddescription
igRootstringyesPath to the IG repository root.
validationLevelsushi-only \| publisher-qa \| fullLevel of validation to perform.
targetProfilesstring[]Specific CRMI profiles to validate against (Shareable, Publishable, Computable, Executable).

output — fhir-harness/schemas/skills/fhir-validation/output.schema.json

fieldtyperequireddescription
overallStatuspass \| warnings \| errorsyes
sushiResultobject
publisherResultobject
conformanceResultsobject[]

Inputs and outputs

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

porttyperequireddescriptionconstraint
inigRootRepoPathyesThe IG root holding the FSH sources. Absent, the command exits 2 with its usage — could-not-determine, not an empty cone.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
incsvRepoPathWrite the report as CSV to this path instead of printing it.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
intopCountShow only the N largest cones; 0 shows none.integer · A non-negative count — how many of something, or how many to show. Zero is a real answer.
inhistoryCountReport the blast radius over the last N commits instead of a static cone.integer · A non-negative count — how many of something, or how many to show. Zero is a real answer.
infileUsersRepoPathAlso write fsh-file-users/v1: for each FSH file, the files that use what it declares. The IG AST’s incremental plan reads it (AstPlanCli -fsh-users) so a changed RuleSet- or Alias-only file reaches its users rather than forcing a full build.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
outconeTextThe cone, or the impact of --changed. With --csv it goes to that path instead.string · A short single-line human string. Not admissible as a command-line argument.

Processes and tasks

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

processsteplanevia skill
Incremental IG buildValidate the cone (fhir_validate)Publisher + validator services (JVM)fhir-validation
L3 FHIR IG pipelineValidate against profilesBuild pipeline — SUSHI · validator · IG Publisherfhir-validation

How it is deployed and reached

  • Command line. From the repository root: bun run fhir-harness/scripts/fsh-cone.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

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/fsh-cone.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/fsh-cone.jsonld",
  "@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
  "partOf": "https://litlfred.github.io/folio-assistant/fhir-harness/fhir-harness.jsonld",
  "name": "fsh-cone",
  "title": "FSH dependency cone",
  "description": "Compute the dependency cone over an IG's FSH graph, and the blast radius of a set of changed files. It is what lets an incremental IG build rebuild less than everything.",
  "install": {
    "none": true
  },
  "invoke": {
    "shell": "bun run fhir-harness/scripts/fsh-cone.ts"
  },
  "io": {
    "inputs": [
      {
        "name": "igRoot",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The IG root holding the FSH sources. Absent, the command exits 2 with its usage — could-not-determine, not an empty cone.",
        "required": true,
        "arg": {
          "positional": 0
        }
      },
      {
        "name": "csv",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "Write the report as CSV to this path instead of printing it.",
        "required": false,
        "arg": {
          "flag": "--csv"
        }
      },
      {
        "name": "top",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Count",
        "description": "Show only the N largest cones; `0` shows none.",
        "required": false,
        "arg": {
          "flag": "--top"
        }
      },
      {
        "name": "history",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Count",
        "description": "Report the blast radius over the last N commits instead of a static cone.",
        "required": false,
        "arg": {
          "flag": "--history"
        }
      },
      {
        "name": "fileUsers",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "Also write `fsh-file-users/v1`: for each FSH file, the files that use what it declares. The IG AST's incremental plan reads it (`AstPlanCli -fsh-users`) so a changed RuleSet- or Alias-only file reaches its users rather than forcing a full build.",
        "required": false,
        "arg": {
          "flag": "--file-users"
        }
      }
    ],
    "outputs": [
      {
        "name": "cone",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Text",
        "description": "The cone, or the impact of `--changed`. With `--csv` it goes to that path instead."
      }
    ]
  },
  "satisfies": [
    "fhir-validation"
  ],
  "requirements": {
    "runtime": [
      "bun"
    ],
    "network": false
  }
}

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