docmeta publishes a programmatic entry point alongside the CLI. A Node.js or TypeScript tool can call the same cores the CLI is built on. There is no process to spawn and no stdout to parse. Consume docmeta results shows the worked example; this page is the exhaustive list.
One function per subcommand, each taking an options object and resolving to a
structured result. The cores contain no CLI or IO plumbing: they do not read
process.argv, do not write to stdout, and do not call process.exit. Turning
a result into text is the reporters’ job, and mapping it to an
exit code is the caller’s.
Export
Purpose
runValidate
Run the validation pipeline over the resolved inputs. Backs docmeta validate.
ValidateOptions (type)
Input to runValidate. Mirrors the CLI: inputs, cliSchemas, exts, exclude, as, configPath, stdinContent, baseline and offline settings.
ValidateRun (type)
What runValidate resolves to: results, summary, and the frame describing where the run stood.
runGet
Read named metadata fields from each input. Backs docmeta get. Always returns every file it saw, since --quiet filtering lives in the reporter.
GetOptions (type)
Input to runGet: the same input model plus the fields to read.
GetFileResult (type)
One runGet result. The file, whether metadata was present, the resolved values, and an optional error when the metadata block could not be read at all.
runQuery
Run one SQL statement over an in-memory table built from every input’s metadata. Backs docmeta query. Returns every row. The --check verdict is the CLI’s exit code, not the result’s.
QueryOptions (type)
Input to runQuery. The same input model plus the sql to run. Optional named-parameter params, with values encoded like stored cells: booleans as 1/0, arrays and objects as JSON text. Optional schemas naming the set a DDL statement evolves (the CLI’s -s). A run that produces no schema-evolving effects then refuses, export-only runs included. An optional db export path makes sql optional.
QueryRun (type)
What runQuery resolves to. Result columns (present even for zero rows), rows, and a mutating statement’s changes. The frame describing where the run stood, which is what SARIF and JUnit rendering need. When db was written, its path and size.
QueryChange (type)
One thing a mutating statement changed, as a union of kinds. A cell set (key/from/to), a key deletion (deleted), or a key rename (renamedFrom). A stripped block (cleared), a created file (created), or a file move (renamed). A schema edit (schema) carries the op, the type/format/enum/required intent, 0028’s fields included, and any forkedFrom. A DDL side effect on the governing config (config), which is either a fork’s schemas: repoint or a refreshed integrity: pin, as one change object each. Every kind records whether it was written or previewed.
runFill
Propose and write missing metadata with an inference provider. Backs docmeta fill.
FillOptions (type)
Input to runFill: provider, model, confidence threshold, cost ceiling, concurrency, and whether to write.
FillRun (type)
What runFill resolves to: per-file results plus the run summary.
FillFileResult (type)
One file’s fill outcome: the fields considered and whether the document was rewritten.
FillSummary (type)
Aggregate fill counts, including cost and the required fields left unfilled.
FilledField (type)
One proposed field: JSON Pointer, required, confidence, reasoning, the value, and whether it was written.
SkipReason (type)
Why a proposal was not written: low-confidence, schema-mismatch, or no-proposal.
getSchemasInfo
The built-in schema registry and the supported input formats, as data. Backs docmeta schemas.
runVendorSchema
Fetch a remote schema, write it into the repository, and record its integrity pin. Backs docmeta schemas vendor.
VendorOptions (type)
Input to runVendorSchema: the URL, the destination directory, and whether to update the config.
VendorResult (type)
What was written. The file path, the integrity digest, and the config edit that was made.
vendorFileName
The file name schemas vendor derives from a schema URL.
DEFAULT_VENDOR_DIR
The default destination directory for vendored schemas (./schema).
The shapes below are the ones --format json serializes, so a programmatic
caller and a subprocess caller are reading the same data model.
Export
Purpose
Validator
The Ajv-backed engine. Validate already-extracted metadata against a schema set without going through the file pipeline.
ValidationResult (type)
One file’s outcome: the file label, ok, the schemas applied, the errors, and how many findings a baseline suppressed.
FieldError (type)
One violation. The JSON Pointer, the message, the failing keyword, and the schema that produced it.
RunSummary (type)
Aggregate counts for a run. Files, passed, failed, errors, plus optional gitignoreSkipped and baseline blocks.
BaselineSummary (type)
How a baseline shaped the run. Its path, whether it was written, and the recorded, suppressed, and stale counts.
FingerprintContext (type)
The frame a ValidateRun returns: the working directory, the directory canonical paths are measured from, and the directory result labels are relative to. Pass it back into render for SARIF.
Pure formatting. A reporter turns a core’s result into text and never writes it anywhere. --quiet lives here rather than in the cores, so a programmatic caller can never mistake a filtered run for an empty one.
Export
Purpose
render
Format a validation run in any report format. SARIF also wants the run’s frame.
renderSarif
The SARIF reporter on its own, for callers that only want that one.
renderJunit
The JUnit XML reporter on its own.
REPORT_FORMATS
The formats validate accepts: pretty, json, github, sarif, junit.
ReportFormat (type)
The union of those names.
isReportFormat
Type guard for a user-supplied format string.
ReportOptions (type)
Options passed to render: color, and everything SarifOptions and JunitOptions carry.
SarifOptions (type)
SARIF-specific options, notably the frame used to build repository-relative URIs.
JunitOptions (type)
JUnit-specific options: the frame, and the classname each testcase carries. That is docmeta.validate by default; query --check findings ship as docmeta.query.
QUERY_FORMATS
The formats query accepts: pretty, json, csv, plus the findings formats github, sarif, junit (legal only with --check).
QueryFormat (type)
The union of those names.
isQueryFormat
Type guard for a user-supplied query format string.
COMMON_FORMATS
The two formats every command supports: pretty and json.
CommonFormat (type)
The union of those two names.
isCommonFormat
Type guard for the narrower set, used by get.
renderGet
The reporter behind docmeta get.
GetReportOptions (type)
color and quiet for renderGet.
renderQuery
The reporter behind docmeta query: the aligned table, the row count, and the --check verdict line.
renderQueryCsv
The -f csv fork of the query reporter, giving result rows as CSV. Header always, LF endings, RFC 4180 quoting, and SQL NULL as an empty field.
QueryReportOptions (type)
color and check for renderQuery.
stringifyValue
How a single field value is spelled: (unset) when missing, JSON for anything that is not a string.
renderFill
The reporter behind docmeta fill, across the fill formats.
renderFillGithub
GitHub Actions annotations for the work fill could not do, as one ::error per unfilled required property.
FILL_FORMATS
The formats fill accepts: pretty, json, github.
FillReportFormat (type)
The union of those names.
isFillFormat
Type guard for a user-supplied fill format string.
The per-format metadata layer. Everything after extraction operates on the
generic ExtractedMetadata shape, which is why a new input format never touches
validation, resolution, or reporting. See supported
formats.
Export
Purpose
extractorForExtension
The implemented extractor for a file extension (including the dot), or undefined.
supportedExtensions
Every extension an implemented extractor handles, which is the default set for directory and glob walks.
MetadataExtractor (type)
The extractor interface. Name, extensions, and the read and write entry points.
ExtractedMetadata (type)
The format-independent result of extraction: whether metadata was present, the parsed data, and any parse error.
ExtractOptions (type)
Per-run inputs to extraction beyond the document itself, currently the elements: paths, which lift metadata held in elements rather than attributes. Pass the same value to apply, or a writer re-reads without them and cannot find the key it just wrote.
Replace a file atomically, falling back to a direct write with a warning when the rename keeps failing on a locked target. Accepts a Uint8Array so vendored bytes are written byte-for-byte.