@hawkeyexl/manni 0.2.0 → 0.3.0

package/dist/{chunk-OXH2ZM7E.js → chunk-BKJOQHWN.js}

@@ -39,7 +39,7 @@ import {
   shouldColor,
   supportedExtensions,
   toJsonText
-} from "./chunk-2OALUJV2.js";
+} from "./chunk-7M2YOXVG.js";
 
 // src/shared/run.ts
 import { realpathSync } from "node:fs";
@@ -1047,4 +1047,4 @@ export {
   runIfMain,
   buildProgram
 };
-//# sourceMappingURL=chunk-OXH2ZM7E.js.map
+//# sourceMappingURL=chunk-BKJOQHWN.js.map

package/dist/cli.js

@@ -3,7 +3,7 @@ import {
   buildProgram,
   fail,
   runIfMain
-} from "./chunk-OXH2ZM7E.js";
+} from "./chunk-BKJOQHWN.js";
 import {
   ToolError,
   escapeWorkflowCommandMessage,
@@ -14,7 +14,7 @@ import {
   programName,
   readConfigFile,
   shouldColor
-} from "./chunk-2OALUJV2.js";
+} from "./chunk-7M2YOXVG.js";
 
 // src/cli.ts
 import { Command as Command2 } from "commander";

package/dist/docmeta.js

@@ -2,8 +2,8 @@
 import {
   buildProgram,
   runIfMain
-} from "./chunk-OXH2ZM7E.js";
-import "./chunk-2OALUJV2.js";
+} from "./chunk-BKJOQHWN.js";
+import "./chunk-7M2YOXVG.js";
 
 // src/docmeta.ts
 runIfMain(import.meta.url, () => buildProgram().name("docmeta"));

package/dist/index.d.ts

@@ -174,6 +174,16 @@ interface FieldError {
     line?: number;
     /** 1-based column, when known. */
     col?: number;
+    /**
+     * The file `line` and `col` refer to, when it is not the result's own file.
+     *
+     * Set only for a value a sidecar manifest supplied (proposal 0037), spelled
+     * the way the run spells file labels. Absent means the document itself,
+     * which is every violation that existed before sidecars. The finding's
+     * subject file stays `ValidationResult.file`: that is its baseline identity
+     * and its SARIF location, and this names where the *value* was written.
+     */
+    file?: string;
 }
 /** Validation outcome for a single file. */
 interface ValidationResult {
@@ -347,6 +357,40 @@ interface CheckConfig {
     /** One SQL statement whose rows follow the finding column convention. */
     query: string;
 }
+/**
+ * One sidecar manifest (proposal 0037): a YAML file that supplies a fixed set
+ * of top-level keys for named documents, merged into each document's metadata
+ * before schema resolution. The private half of a public docset.
+ */
+interface SidecarConfig {
+    /**
+     * Manifest path, relative to the config file's directory, or an `https://`
+     * URL (proposal 0038) fetched at the start of every run. A URL serves a
+     * manifest in another public repository as readily as a private one; only
+     * the private one needs `tokenEnv`.
+     */
+    file: string;
+    /**
+     * The top-level keys this manifest owns. Ownership is disjoint across
+     * entries, so two manifests can never disagree about one key, and a
+     * document carrying an owned key is a finding rather than a tiebreak.
+     */
+    keys: string[];
+    /**
+     * Name of an environment variable whose value is sent as a bearer token
+     * when `file` is a URL. The token never appears in the config, a message,
+     * or a report. Refused on a path `file`, where it would do nothing.
+     */
+    tokenEnv?: string;
+    /**
+     * `path` (the default), or the top-level frontmatter field whose value the
+     * manifest's keys name (proposal 0039). A field join survives a rename;
+     * what it cannot survive is two documents sharing one value, which is a
+     * finding on both. Never `$schema`, and never a key this entry owns: the
+     * value that selects an entry cannot come from the entry.
+     */
+    join?: string;
+}
 /** Defaults for the `fill` command; every key is overridable by a CLI flag. */
 interface FillConfig {
     provider?: string;
@@ -381,6 +425,11 @@ interface DocmetaConfig {
      * run's file set is the config-resolved corpus. See `CheckConfig`.
      */
     checks?: CheckConfig[];
+    /**
+     * Sidecar manifests whose keys are merged into the documents they name.
+     * See `SidecarConfig`.
+     */
+    sidecars?: SidecarConfig[];
     /**
      * Element paths to lift in addition to each format's convention. See
      * `parseElementPath` for the syntax.
@@ -1125,6 +1174,153 @@ interface FillOptions {
 
 declare function runFill(opts: FillOptions): Promise<FillRun>;
 
+/**
+ * The `schema` ref a collision finding carries, and so its baseline and rule
+ * identity: `sidecar:owned/sidecar`. Shaped like `check:<name>` so
+ * `classifyRef` passes it through as a built-in id rather than resolving it
+ * as a cwd-relative file path, and reserved in the registry for the same
+ * reason `check` is.
+ */
+declare const SIDECAR_OWNED_SCHEMA = "sidecar:owned";
+/**
+ * The `schema` ref of a duplicate-join finding (0039): two documents carry
+ * the same value of a join field, so one manifest entry matched both.
+ */
+declare const SIDECAR_DUPLICATE_SCHEMA = "sidecar:duplicate";
+/** The `keyword` every sidecar finding carries: no Ajv keyword produced it. */
+declare const SIDECAR_KEYWORD = "sidecar";
+/** The join that names documents by path, and the default. */
+declare const PATH_JOIN = "path";
+/** One value a sidecar supplied, and where it was written. */
+interface SidecarValue {
+    value: unknown;
+    /** Manifest path as the run reports it: relative to the run's base, posix — or the URL. */
+    file: string;
+    /** 1-based line of the key in the manifest, when known. */
+    line?: number;
+}
+/** One manifest entry, for the orphan checks. */
+interface SidecarEntry {
+    /** `path`, or the frontmatter field this entry is keyed by. */
+    join: string;
+    /** Absolute document path, for a path entry. */
+    abs?: string;
+    /** The key exactly as written in the manifest. */
+    spelled: string;
+    /** Manifest path as the run reports it. */
+    file: string;
+    /** 1-based line of the entry in the manifest, when known. */
+    line?: number;
+}
+/** Every sidecar of a run, loaded once and consulted per document. */
+interface SidecarIndex {
+    /** Owned key -> manifest path as reported. */
+    owners: ReadonlyMap<string, string>;
+    /** Path-joined sidecars: absolute document path -> owned key -> value. */
+    byPath: ReadonlyMap<string, ReadonlyMap<string, SidecarValue>>;
+    /** Field-joined sidecars: field -> value -> owned key -> value. */
+    byField: ReadonlyMap<string, ReadonlyMap<string, ReadonlyMap<string, SidecarValue>>>;
+    /** Every manifest entry, in manifest order. */
+    entries: readonly SidecarEntry[];
+}
+interface LoadSidecarsOptions {
+    /** Directory `sidecars[].file` and every manifest key resolve from. */
+    configDir: string;
+    /** Directory the run's file labels are relative to; manifests are reported the same way. */
+    base: string;
+    /** `--offline` / `offline:`: a URL manifest is refused rather than fetched (0038). */
+    offline?: boolean;
+    /** Network timeout for a URL manifest; the schema fetch's default otherwise. */
+    timeoutMs?: number;
+    /** For tests: the environment `tokenEnv` is read from. */
+    env?: Record<string, string | undefined>;
+}
+/** A place a merged value lives, for a finding that must name it. */
+interface SourceLocation {
+    file: string;
+    line?: number;
+    col?: number;
+}
+/** A key the document carries that a sidecar owns. */
+interface SidecarCollision {
+    key: string;
+    /** The owning manifest, as the run reports it. */
+    file: string;
+}
+/** A field-joined entry a document matched (0039). */
+interface SidecarJoin {
+    field: string;
+    value: string;
+    /** The manifest, as the run reports it. */
+    file: string;
+}
+/** What `mergeSidecars` hands back. */
+interface MergedMetadata {
+    /** The document's metadata with every owned key the manifest supplied. */
+    extracted: ExtractedMetadata;
+    /**
+     * Owned keys the document itself also carried, in document order, each
+     * with the manifest that owns it — so the finding names it without a
+     * second lookup, and without a fallback for an index that is not there.
+     */
+    collisions: SidecarCollision[];
+    /** Field-joined entries this document matched, one per sidecar at most. */
+    joins: SidecarJoin[];
+    /**
+     * Where a merged pointer's value lives. Answers only for a value the
+     * manifest supplied — a bare key or its `/key` pointer, and anything
+     * beneath it — and `undefined` for everything the document owns, which is
+     * what `lineFor` is for.
+     */
+    locate: (pointer: string) => SourceLocation | undefined;
+}
+/** The join a sidecar config asks for: `path` unless it names a field. */
+declare function sidecarJoin(sidecar: Pick<SidecarConfig, "join">): string;
+/**
+ * Load every configured manifest. Resolves to `null` when the config declares
+ * none, which is every setup that existed before this feature.
+ *
+ * Every refusal is a `DocmetaError`: the manifest is a config-supplied input,
+ * and one that is missing or misshapen is the run's problem, not a
+ * document's (0014).
+ */
+declare function loadSidecars(config: DocmetaConfig | null | undefined, opts: LoadSidecarsOptions): Promise<SidecarIndex | null>;
+/**
+ * Merge the sidecar values for one document into its extracted metadata.
+ *
+ * `label` is the document as the run spells it, relative to `base`; a path
+ * entry matches on the resolved absolute path, never on the spelling, so a
+ * positional run from a subdirectory finds the same entry a config-corpus
+ * run does. A field entry matches on the document's own value of the join
+ * field, wherever the document lives. Stdin never matches a path entry:
+ * there is no file behind it.
+ *
+ * `present`, `format` and the document's own positions are untouched. A
+ * sidecar key is not in the document, so `lineFor` keeps answering
+ * `undefined` for it, and `locate` answers instead.
+ */
+declare function mergeSidecars(label: string, extracted: ExtractedMetadata, index: SidecarIndex | null, base: string): MergedMetadata;
+/** The `/key` pointer for a sidecar finding, RFC 6901 escaped. */
+declare function sidecarPointer(key: string): string;
+/**
+ * Path entries naming no loaded document.
+ *
+ * `loaded` are the run's file labels, relative to `base`. Checked only when
+ * the run is the config corpus (the same invariant corpus checks use): a
+ * positional path means the operator chose to look at part of the corpus,
+ * and an entry for the rest is expected, not orphaned.
+ */
+declare function orphanEntries(index: SidecarIndex | null, loaded: readonly string[], base: string): SidecarEntry[];
+/**
+ * Field entries no loaded document matched (0039). `matched` is field -> the
+ * values documents in the run carried, which the caller collects from each
+ * document's `joins` — so this runs after the per-file loop, under the same
+ * corpus invariant as `orphanEntries`.
+ */
+declare function orphanJoins(index: SidecarIndex | null, matched: ReadonlyMap<string, ReadonlySet<string>>): SidecarEntry[];
+/** The operational error an orphan check raises, naming the first entry. */
+declare function orphanError(orphans: readonly SidecarEntry[]): DocmetaError;
+
 declare class Validator {
     private readonly schemaOptions;
     /**
@@ -1170,7 +1366,13 @@ declare class Validator {
      * Callers with an extractor that supplies no column pass nothing and get the
      * previous behavior exactly.
      */
-    validate(data: Record<string, unknown>, refs: string[], lineFor: (pointer: string) => number | undefined, colFor?: (pointer: string) => number | undefined): Promise<FieldError[]>;
+    validate(data: Record<string, unknown>, refs: string[], lineFor: (pointer: string) => number | undefined, colFor?: (pointer: string) => number | undefined, 
+    /**
+     * Where a merged value lives when it is not in the document (proposal
+     * 0037): a sidecar manifest's file and line. Consulted before `lineFor`,
+     * and additive in the way `colFor` was.
+     */
+    locate?: (pointer: string) => SourceLocation | undefined): Promise<FieldError[]>;
 }
 
 /**
@@ -1273,6 +1475,30 @@ declare function integrityOf(bytes: Uint8Array): string;
 /** Whether `value` is a pin this version can verify. */
 declare function isIntegrity(value: string): boolean;
 
+/** Default network timeout, matching the schema fetch. */
+declare const SIDECAR_FETCH_TIMEOUT_MS = 10000;
+/** Body cap, matching the schema fetch. */
+declare const SIDECAR_FETCH_MAX_BYTES: number;
+interface SidecarFetchOptions {
+    /** Environment variable holding a bearer token. Absent means an anonymous request. */
+    tokenEnv?: string;
+    timeoutMs?: number;
+    maxBytes?: number;
+    /** `--offline` / `offline:`: refuse rather than fetch. */
+    offline?: boolean;
+    /** For tests: the environment to read `tokenEnv` from. Defaults to `process.env`. */
+    env?: Record<string, string | undefined>;
+}
+/**
+ * Whether a URL may name a sidecar manifest: `https://` anywhere, or `http://`
+ * on a loopback host only, where plaintext leaks nothing. Userinfo is refused
+ * because the URL is printed in every diagnostic and a secret in it would
+ * print too. Returns the reason it may not, or `null`.
+ */
+declare function sidecarUrlProblem(url: string): string | null;
+/** Fetch one remote manifest. Resolves to its text; throws `DocmetaError`. */
+declare function fetchSidecar(url: string, opts?: SidecarFetchOptions): Promise<string>;
+
 /**
  * Where the cache lives, relative to the project root.
  *
@@ -1620,4 +1846,4 @@ declare function extractorForExtension(ext: string): MetadataExtractor | undefin
 /** Extensions handled by implemented extractors (used for directory walks). */
 declare function supportedExtensions(): string[];
 
-export { type ApplyOptions, type BaselineSummary, COMMON_FORMATS, type CheckConfig, type CommonFormat, type ConfigNotice, DEFAULT_SCHEMAS, DEFAULT_TTL_HOURS, DEFAULT_VENDOR_DIR, type DocmetaConfig, DocmetaError, type DocumentRefTrust, type ExtractOptions, type ExtractedMetadata, FILL_FORMATS, type FetchedSchema, type FieldError, type FillConfig, type FillFileResult, type FillOptions, type FillReportFormat, type FillReportOptions, type FillRun, type FillSummary, type FilledField, type FingerprintContext, type FrontmatterFlavor, type FrontmatterLocation, type GetFileResult, type GetOptions, type GetReportOptions, INTEGRITY_SHAPE, type JunitOptions, type LoadSchemaOptions, type LoadedConfig, type MetadataExtractor, type MetadataPatch, QUERY_FORMATS, type QueryChange, type QueryFormat, type QueryOptions, type QueryReportOptions, type QueryRun, REPORT_FORMATS, type ReadOptions, type ReportFormat, type ReportOptions, type RunConfig, type RunConfigOptions, type RunSummary, SCHEMA_CACHE_DIR, SCHEMA_CACHE_VERSION, type SarifOptions, SchemaCache, type SchemaCacheConfig, type SchemaCacheEntry, type SchemaEntry, type SchemaPin, type SchemaRefEntry, type SchemaTrustConfig, type SkipReason, type ValidateOptions, type ValidateRun, type ValidationResult, Validator, type VendorOptions, type VendorResult, applyFrontmatter, classifyRef, collectSchemaPins, extractFrontmatter, extractorForExtension, fetchSchemaBytes, frontmatterInnerText, getSchemasInfo, integrityOf, isCommonFormat, isFillFormat, isIntegrity, isQueryFormat, isReportFormat, listBuiltins, loadConfig, loadSchema, locateFrontmatter, parseConfig, rebaseConfigSchemaRefs, render, renderFill, renderFillGithub, renderGet, renderJunit, renderQuery, renderQueryCsv, renderSarif, resolveRunConfig, resolveSchemaSet, runFill, runGet, runQuery, runValidate, runVendorSchema, schemaCacheDir, schemaEntryRef, schemaLoadOptions, stringifyValue, supportedExtensions, vendorFileName, writeFileAtomic };
+export { type ApplyOptions, type BaselineSummary, COMMON_FORMATS, type CheckConfig, type CommonFormat, type ConfigNotice, DEFAULT_SCHEMAS, DEFAULT_TTL_HOURS, DEFAULT_VENDOR_DIR, type DocmetaConfig, DocmetaError, type DocumentRefTrust, type ExtractOptions, type ExtractedMetadata, FILL_FORMATS, type FetchedSchema, type FieldError, type FillConfig, type FillFileResult, type FillOptions, type FillReportFormat, type FillReportOptions, type FillRun, type FillSummary, type FilledField, type FingerprintContext, type FrontmatterFlavor, type FrontmatterLocation, type GetFileResult, type GetOptions, type GetReportOptions, INTEGRITY_SHAPE, type JunitOptions, type LoadSchemaOptions, type LoadSidecarsOptions, type LoadedConfig, type MergedMetadata, type MetadataExtractor, type MetadataPatch, PATH_JOIN, QUERY_FORMATS, type QueryChange, type QueryFormat, type QueryOptions, type QueryReportOptions, type QueryRun, REPORT_FORMATS, type ReadOptions, type ReportFormat, type ReportOptions, type RunConfig, type RunConfigOptions, type RunSummary, SCHEMA_CACHE_DIR, SCHEMA_CACHE_VERSION, SIDECAR_DUPLICATE_SCHEMA, SIDECAR_FETCH_MAX_BYTES, SIDECAR_FETCH_TIMEOUT_MS, SIDECAR_KEYWORD, SIDECAR_OWNED_SCHEMA, type SarifOptions, SchemaCache, type SchemaCacheConfig, type SchemaCacheEntry, type SchemaEntry, type SchemaPin, type SchemaRefEntry, type SchemaTrustConfig, type SidecarCollision, type SidecarConfig, type SidecarEntry, type SidecarFetchOptions, type SidecarIndex, type SidecarJoin, type SidecarValue, type SkipReason, type SourceLocation, type ValidateOptions, type ValidateRun, type ValidationResult, Validator, type VendorOptions, type VendorResult, applyFrontmatter, classifyRef, collectSchemaPins, extractFrontmatter, extractorForExtension, fetchSchemaBytes, fetchSidecar, frontmatterInnerText, getSchemasInfo, integrityOf, isCommonFormat, isFillFormat, isIntegrity, isQueryFormat, isReportFormat, listBuiltins, loadConfig, loadSchema, loadSidecars, locateFrontmatter, mergeSidecars, orphanEntries, orphanError, orphanJoins, parseConfig, rebaseConfigSchemaRefs, render, renderFill, renderFillGithub, renderGet, renderJunit, renderQuery, renderQueryCsv, renderSarif, resolveRunConfig, resolveSchemaSet, runFill, runGet, runQuery, runValidate, runVendorSchema, schemaCacheDir, schemaEntryRef, schemaLoadOptions, sidecarJoin, sidecarPointer, sidecarUrlProblem, stringifyValue, supportedExtensions, vendorFileName, writeFileAtomic };

package/dist/index.js

@@ -7,10 +7,16 @@ import {
   DocmetaError,
   FILL_FORMATS,
   INTEGRITY_SHAPE,
+  PATH_JOIN,
   QUERY_FORMATS,
   REPORT_FORMATS,
   SCHEMA_CACHE_DIR,
   SCHEMA_CACHE_VERSION,
+  SIDECAR_DUPLICATE_SCHEMA,
+  SIDECAR_FETCH_MAX_BYTES,
+  SIDECAR_FETCH_TIMEOUT_MS,
+  SIDECAR_KEYWORD,
+  SIDECAR_OWNED_SCHEMA,
   SchemaCache,
   Validator,
   applyFrontmatter,
@@ -19,6 +25,7 @@ import {
   extractFrontmatter,
   extractorForExtension,
   fetchSchemaBytes,
+  fetchSidecar,
   frontmatterInnerText,
   getSchemasInfo,
   integrityOf,
@@ -30,7 +37,12 @@ import {
   listBuiltins,
   loadConfig,
   loadSchema,
+  loadSidecars,
   locateFrontmatter,
+  mergeSidecars,
+  orphanEntries,
+  orphanError,
+  orphanJoins,
   parseConfig,
   rebaseConfigSchemaRefs,
   render,
@@ -51,11 +63,14 @@ import {
   schemaCacheDir,
   schemaEntryRef,
   schemaLoadOptions,
+  sidecarJoin,
+  sidecarPointer,
+  sidecarUrlProblem,
   stringifyValue,
   supportedExtensions,
   vendorFileName,
   writeFileAtomic
-} from "./chunk-2OALUJV2.js";
+} from "./chunk-7M2YOXVG.js";
 export {
   COMMON_FORMATS,
   DEFAULT_SCHEMAS,
@@ -64,10 +79,16 @@ export {
   DocmetaError,
   FILL_FORMATS,
   INTEGRITY_SHAPE,
+  PATH_JOIN,
   QUERY_FORMATS,
   REPORT_FORMATS,
   SCHEMA_CACHE_DIR,
   SCHEMA_CACHE_VERSION,
+  SIDECAR_DUPLICATE_SCHEMA,
+  SIDECAR_FETCH_MAX_BYTES,
+  SIDECAR_FETCH_TIMEOUT_MS,
+  SIDECAR_KEYWORD,
+  SIDECAR_OWNED_SCHEMA,
   SchemaCache,
   Validator,
   applyFrontmatter,
@@ -76,6 +97,7 @@ export {
   extractFrontmatter,
   extractorForExtension,
   fetchSchemaBytes,
+  fetchSidecar,
   frontmatterInnerText,
   getSchemasInfo,
   integrityOf,
@@ -87,7 +109,12 @@ export {
   listBuiltins,
   loadConfig,
   loadSchema,
+  loadSidecars,
   locateFrontmatter,
+  mergeSidecars,
+  orphanEntries,
+  orphanError,
+  orphanJoins,
   parseConfig,
   rebaseConfigSchemaRefs,
   render,
@@ -108,6 +135,9 @@ export {
   schemaCacheDir,
   schemaEntryRef,
   schemaLoadOptions,
+  sidecarJoin,
+  sidecarPointer,
+  sidecarUrlProblem,
   stringifyValue,
   supportedExtensions,
   vendorFileName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hawkeyexl/manni",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "One command line for documentation that is meant to be checked. `manni meta` validates the presence and format of document metadata (Markdown frontmatter and more) against JSON Schema, built for CI. Formerly docmeta.",
   "type": "module",
   "bin": {