@hawkeyexl/manni 2.0.1 → 2.1.0

package/dist/docmeta.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 import {
-  buildProgram,
+  buildProgram
+} from "./chunk-HNPRXGD7.js";
+import {
   runIfMain
-} from "./chunk-MV2T7XAW.js";
-import "./chunk-PDNSN5UJ.js";
+} from "./chunk-2DC2GSRH.js";
 
 // src/docmeta.ts
 runIfMain(import.meta.url, () => buildProgram().name("docmeta"));

package/dist/docmeta.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/docmeta.ts"],"sourcesContent":["/**\n * The `docmeta` bin: the metadata tool under the name it had before it became\n * `manni meta`. Same program, same options, same exit codes, so a script or\n * workflow written against `docmeta …` keeps working. Only the usage line and\n * the stderr prefix say `docmeta`.\n */\nimport { buildProgram } from \"./meta/cli.js\";\nimport { runIfMain } from \"./shared/run.js\";\n\nrunIfMain(import.meta.url, () => buildProgram().name(\"docmeta\"));\n"],"mappings":";;;;;;;;AASA,UAAU,YAAY,KAAK,MAAM,aAAa,EAAE,KAAK,SAAS,CAAC;","names":[]}
+{"version":3,"sources":["../src/docmeta.ts"],"sourcesContent":["/**\n * The `docmeta` bin: the metadata tool under the name it had before it became\n * `manni meta`. Same program, same options, same exit codes, so a script or\n * workflow written against `docmeta …` keeps working. Only the usage line and\n * the stderr prefix say `docmeta`.\n */\nimport { buildProgram } from \"./meta/cli.js\";\nimport { runIfMain } from \"./shared/run.js\";\n\nrunIfMain(import.meta.url, () => buildProgram().name(\"docmeta\"));\n"],"mappings":";;;;;;;;;AASA,UAAU,YAAY,KAAK,MAAM,aAAa,EAAE,KAAK,SAAS,CAAC;","names":[]}

package/dist/index.d.ts

@@ -402,6 +402,126 @@ interface ConfigFile {
     encryptionKeyPrevious?: string;
 }
 
+/** Lines as an entry writes them: an integer for one line, `"L1-L2"` for several. */
+type LineSpec = number | string;
+/** Page lines as an editor numbers them, 1-based and inclusive. */
+interface PageLines {
+    start: number;
+    end: number;
+}
+/** A 1-based inclusive range, either end optional: no `start` is the whole text, no `end` one line. */
+interface LineRange {
+    start?: number;
+    end?: number;
+}
+/** BOM stripped, CRLF folded to LF. */
+declare function normalizeText(text: string): string;
+/** The normalized lines, without the empty element a trailing LF leaves. */
+declare function splitLines(text: string): string[];
+/**
+ * The pin of already-joined lines: `sha256-<hex>`, or with `key` the
+ * `hmac-sha256-<hex>` keyed pin an encrypted value carries. A plain pin
+ * passes `undefined`.
+ */
+declare function hashLines(joined: string, key?: string): string;
+/** Whether a pin is keyed (`hmac-sha256-`), the form an encrypted value carries. */
+declare function isKeyedPin(pin: string): boolean;
+/** The plain pin of a range of lines; undefined when the range falls outside them or ends before it starts. */
+declare function pinOfLines(lines: readonly string[], range: PageLines): string | undefined;
+/** Half-width of the band around the original position the blind move search tries first. */
+declare const MOVE_WINDOW_LINES = 2000;
+/** Default hashing budget for the blind move search, in bytes. */
+declare const MOVE_BUDGET_BYTES: number;
+/** The widest range a move search is attempted for. */
+declare const MAX_RANGE_LINES = 5000;
+interface FindWindowsOptions {
+    /** The 1-based start line the range was pinned at: the blind search begins around it. */
+    around?: number;
+    /** The pinned lines as they were, when known: enables the first-line filter. */
+    original?: readonly string[];
+    /** Hashing budget for the blind search, in bytes. Default `MOVE_BUDGET_BYTES`. */
+    budget?: number;
+}
+/**
+ * Pure move search over normalized lines: the 1-based start lines where a
+ * window of `length` lines hashes to `pin`. `original` (the pinned lines as
+ * they were, when known) enables the first-line filter. `key` keys the hash
+ * for a keyed pin and is `undefined` for a plain one.
+ */
+declare function findWindows(lines: readonly string[], length: number, pin: string, key: string | undefined, opts?: FindWindowsOptions): {
+    starts: number[];
+    truncated: boolean;
+};
+/**
+ * The lines a `LineSpec` names. Undefined for a value that is neither a
+ * positive integer nor `"L1-L2"` with `L1 <= L2`.
+ */
+declare function parseLines(spec: LineSpec): PageLines | undefined;
+/** Lines as an entry writes them: the integer for one line, `"L1-L2"` otherwise. */
+declare function lineSpec(lines: PageLines): LineSpec;
+/** Lines as a report spells them: `"9"` or `"9-12"`. */
+declare function spellLines(lines: PageLines): string;
+/** Body lines as file lines: body line 1 is the file line `bodyLine`, the first after the frontmatter. */
+declare function toFileLines(lines: PageLines, bodyLine: number): PageLines;
+/** File lines as body lines. */
+declare function toBodyLines(lines: PageLines, bodyLine: number): PageLines;
+
+/** One `provenance` entry as stored: body lines, and the pin over them. */
+interface ProvenanceEntry {
+    "generated-by": string;
+    lines: LineSpec;
+    integrity: string;
+}
+/** A page read for provenance. */
+interface ProvenancePage {
+    /** Every normalized line of the file. */
+    lines: string[];
+    /** The file line body line 1 sits on. */
+    bodyLine: number;
+    /** The body's lines: `lines` from `bodyLine` on. */
+    body: string[];
+    /** The well-formed `provenance` entries the frontmatter carries. */
+    stamp: ProvenanceEntry[];
+}
+/** Which of 0046's five evidence rules answered for a line. */
+type EvidenceRule = 1 | 2 | 3 | 4 | 5;
+/** A line's evidence: the machine, or none under rule 5, and the blamed sha. */
+interface LineEvidence {
+    machine?: string;
+    rule: EvidenceRule;
+    sha: string;
+}
+/** One derived range: its entry, its body lines, and its first line's evidence. */
+interface DerivedRange {
+    entry: ProvenanceEntry;
+    span: PageLines;
+    evidence: LineEvidence;
+}
+/** A page's derivation: the page, each body line's evidence, and the ranges. */
+interface ProvenanceDerivation {
+    page: ProvenancePage;
+    evidenceByLine: ReadonlyMap<number, LineEvidence>;
+    derived: DerivedRange[];
+}
+/** 0046's comparison verdicts. */
+type ProvenanceStatus = "current" | "moved" | "changed" | "stale" | "unset";
+/** One range of `DerivedField.ranges`, in file lines. */
+interface RangeResult {
+    lines: string;
+    "generated-by": string;
+    integrity: string;
+    status: ProvenanceStatus;
+    /** `uncommitted`, `blame <sha7>`, or `pin` when only the pin speaks for the range. */
+    evidence: string;
+    /** What the record said before: on `moved` and `stale` only. */
+    from?: {
+        lines: string;
+        "generated-by": string;
+    };
+    /** Whether `derive` wrote this range; always false until it does. */
+    written: boolean;
+}
+
 /**
  * The derived metadata channel: values computed from git history, CODEOWNERS
  * and the review record on GitHub or GitLab rather than written by hand.
@@ -415,11 +535,11 @@ interface ConfigFile {
  * one, and turning the stale comparisons into findings.
  */
 
-/** The six built-in fields, in the order messages list them. */
-declare const DERIVABLE_FIELDS: readonly ["created", "last-updated", "authors", "owner", "reviewed-by", "last-reviewed"];
+/** The seven built-in fields, in the order messages list them. */
+declare const DERIVABLE_FIELDS: readonly ["created", "last-updated", "authors", "owner", "reviewed-by", "last-reviewed", "provenance"];
 type BuiltinDerivableField = (typeof DERIVABLE_FIELDS)[number];
 /**
- * A managed field name: one of the six built-ins, or a key with an entry in
+ * A managed field name: one of the seven built-ins, or a key with an entry in
  * `derive.commands`. The config parser guarantees one or the other.
  */
 type DerivableField = string;
@@ -500,6 +620,32 @@ interface DeriveInput {
     absPath: string;
     content: string;
     extracted: ExtractedMetadata;
+    /**
+     * Where the page's `provenance` record lives when a manifest owns it
+     * (proposal 0046), so evidence rule 2 reads the manifest's blob at each
+     * commit rather than the page's frontmatter. Absent: the page's own.
+     */
+    provenanceManifest?: ProvenanceManifestRef;
+    /**
+     * `manni meta derive <path>:L1-L2 --generated-by <name>`: the file lines
+     * each target names go to `generatedBy`, committed or not, unless evidence
+     * names another machine, and no other uncommitted line does. Ranges that
+     * overlap attribute their union. Each target is a positional as typed,
+     * which every refusal quotes.
+     */
+    attribution?: {
+        targets: string[];
+        generatedBy: string;
+    };
+}
+/** A manifest that holds one page's `provenance`, as the git source reads it at a commit. */
+interface ProvenanceManifestRef {
+    /** The manifest file, absolute. */
+    absPath: string;
+    /** The page's key there: its path relative to the config directory, or its join value. */
+    entry: string;
+    /** `path`, or the page field the manifest joins on. */
+    join: string;
 }
 /** What a derive run holds constant across every document it visits. */
 interface DeriveContext {
@@ -518,6 +664,10 @@ interface DeriveContext {
     now: () => Date;
     /** The review client for every repository in the run; the built-in `gh` / `glab` clients when absent. */
     reviews?: ReviewClient;
+    /** `--generated-by` or `MANNI_GENERATED_BY` (proposal 0046): who uncommitted body lines go to. */
+    generatedBy?: string;
+    /** `derive.machines`: trailer identities that are machines; `["*[bot]"]` when absent. */
+    machines?: readonly string[];
 }
 /**
  * How an asserted value stands against the derived one.
@@ -542,6 +692,17 @@ interface DerivedField {
     status: DerivedStatus;
     /** Whether `derive` wrote the value into the document. */
     written: boolean;
+    /**
+     * `provenance` only (proposal 0046): one verdict per range, in file lines.
+     * The field's own `status` is `current` when every range is, and
+     * otherwise `stale`, or `unset` when the page carries no record at all.
+     */
+    ranges?: RangeResult[];
+    /**
+     * `provenance` only: the manifest that holds the page's record, as the run
+     * reports it, when one does. `derive` writes there, never into the page.
+     */
+    manifest?: string;
 }
 /**
  * The `schema` ref a stale-field finding carries, and so its baseline and
@@ -708,6 +869,14 @@ interface DeriveConfig {
      * is never a built-in field, `$schema`, or a key a manifest owns.
      */
     commands?: Record<string, DeriveCommandConfig>;
+    /**
+     * Trailer identities that are machines (proposal 0046), as globs matched
+     * case-sensitively against a trailer's name and its email, with literal
+     * brackets. A match names a machine for `provenance` and is left out of
+     * `authors`. Absent means `["*[bot]"]`, which is 0040's rule; read it
+     * through `machinesOf`.
+     */
+    machines?: string[];
 }
 /** Defaults for the `fill` command; every key is overridable by a CLI flag. */
 interface FillConfig {
@@ -1181,6 +1350,17 @@ interface GetFileResult {
      * one. A run carrying any `error` exits 1.
      */
     error?: string;
+    /**
+     * `provenance` only (proposal 0046), present when it was requested and the
+     * file parsed. `bodyLine` is the file line body line 1 sits on, which the
+     * record's body lines are shown against. `current` is whether the record
+     * agrees with git as `validate` judges it, range by range; absent when
+     * nothing was derived.
+     */
+    provenance?: {
+        bodyLine: number;
+        current?: boolean;
+    };
 }
 declare function runGet(opts: GetOptions): Promise<GetFileResult[]>;
 
@@ -1599,6 +1779,46 @@ interface FilledField {
      */
     encrypted?: boolean;
 }
+/**
+ * One `meta-provenance` entry as `fill` writes it (proposal 0046): the model,
+ * the JSON Pointers of the fields it proposed, escaped per RFC 6901, and the
+ * confidence each was written at. Keys are the page's own spelling, so the
+ * JSON report shows exactly what landed in the document. An entry `fill`
+ * merged into keeps whatever else it held.
+ */
+interface MetaProvenanceEntry {
+    "generated-by": string;
+    fields: string[];
+    confidence: Record<string, number>;
+    [other: string]: unknown;
+}
+/**
+ * What became of this file's `meta-provenance` entry. It is never a failure:
+ * neither outcome changes the summary or the exit code.
+ */
+type MetaProvenanceReport = {
+    written: true;
+    entry: MetaProvenanceEntry;
+}
+/** The page's schemas, checked with the entry in place, reject it. */
+ | {
+    written: false;
+    skipReason: "schema-mismatch";
+}
+/** A manifest in one of the page's collections owns the key. */
+ | {
+    written: false;
+    skipReason: "manifest-owned";
+    manifest: string;
+}
+/**
+ * The format's writer cannot hold a list of entries (an HTML or XML
+ * attribute holds one line), so the fields were written without it.
+ */
+ | {
+    written: false;
+    skipReason: "unwritable";
+};
 interface FillFileResult {
     file: string;
     format: string;
@@ -1610,6 +1830,12 @@ interface FillFileResult {
     error?: string;
     /** The filled document. Populated only when the caller asks for it. */
     content?: string;
+    /**
+     * The `meta-provenance` entry recording the fields this run wrote
+     * (proposal 0046). Absent when no field was written; reported, not written,
+     * under `--dry-run`.
+     */
+    metaProvenance?: MetaProvenanceReport;
 }
 interface FillSummary {
     files: number;
@@ -1765,6 +1991,12 @@ interface DeriveOptions {
      * `process.env`; tests pass their own.
      */
     env?: NodeJS.ProcessEnv;
+    /**
+     * `--generated-by <name>` (proposal 0046): the machine uncommitted body
+     * lines go to, or the lines a `<path>:L1-L2` positional names. Absent reads
+     * `MANNI_GENERATED_BY` from `env`; an empty value is unset either way.
+     */
+    generatedBy?: string;
 }
 interface DeriveFileResult {
     file: string;
@@ -1792,6 +2024,12 @@ interface DeriveSummary {
     changed: number;
     /** Fields whose write reached the disk: always 0 under `dryRun` and `check`. */
     written: number;
+    /**
+     * `provenance` ranges whose write reached the disk (proposal 0046): always
+     * 0 under `dryRun` and `check`. Present only when the run derives
+     * `provenance`.
+     */
+    ranges?: number;
     stale: number;
     unset: number;
     unknown: number;
@@ -2297,6 +2535,12 @@ interface DeriveResult {
      * not point at. Absent means not applicable here, never unavailable.
      */
     sources: Partial<Record<DeriveSource, SourceStatus$1>>;
+    /**
+     * The provenance derivation per input label (proposal 0046), for the
+     * comparison with a page's stamp: present only when `provenance` was
+     * requested and the git source answered.
+     */
+    provenance?: ReadonlyMap<string, ProvenanceDerivation>;
 }
 /**
  * Which sources can state a field, in precedence order: the built-in table
@@ -3008,8 +3252,7 @@ interface SourceRange {
     start?: number;
     end?: number;
 }
-/** Lines as an entry writes them: an integer for one line, `"L1-L2"` for several. */
-type LineSpec = number | string;
+
 /** The page text a citation supports. */
 interface CitationClaim {
     /** Body lines: counted from the first line after the frontmatter. Absent when a marker anchors the entry. */
@@ -3344,11 +3587,6 @@ interface CheckRun {
     warnings: number;
     notices: number;
 }
-/** Page lines as an editor numbers them, 1-based and inclusive. */
-interface PageLines {
-    start: number;
-    end: number;
-}
 interface AddOptions {
     page: string;
     /** The claim's lines as an editor numbers them (`page:L`, `page:L1-L2`). Absent: a bare pin. */
@@ -3596,16 +3834,6 @@ declare const SRC_PATTERN: RegExp;
 declare function parseSrc(src: string): SourceRange;
 /** The canonical spelling: `path:L` for one line, `path:L1-L2` otherwise. */
 declare function formatSrc(range: SourceRange): string;
-/**
- * The lines an entry's `lines` names. Undefined for a value that is neither
- * a positive integer nor `"L1-L2"` with `L1 <= L2`: the schema refuses the
- * first, and `readPage` reports the second.
- */
-declare function parseLines(spec: LineSpec): PageLines | undefined;
-/** Lines as an entry writes them: the integer for one line, `"L1-L2"` otherwise. */
-declare function lineSpec(lines: PageLines): LineSpec;
-/** Lines as a report spells them: `"9"` or `"9-12"`. */
-declare function spellLines(lines: PageLines): string;
 /** An entry's source as a range. Its lines must already be valid (see `parseLines`). */
 declare function sourceRange(source: CitationSource): SourceRange;
 /** An entry's source spelled as one string, `path:L1-L2`, the way the command line takes it. */
@@ -3613,31 +3841,19 @@ declare function spellSource(source: CitationSource): string;
 /** A range's lines as an entry writes them; undefined for a whole file. */
 declare function rangeLines(range: SourceRange): LineSpec | undefined;
 
-/** BOM stripped, CRLF folded to LF. */
-declare function normalizeText(text: string): string;
-/** The normalized lines, without the empty element a trailing LF leaves. */
-declare function splitLines(text: string): string[];
 /**
- * The cited lines joined by LF. Throws `CiteError` when the range runs past
- * the end of the text (`<path> has N lines; line M is out of range`).
+ * The hashing rule, as cite uses it. The engine is `src/shared/pin.ts`, shared
+ * with meta; this module keeps cite's import path and its error contract: a
+ * range past the end of the text throws `CiteError`.
  */
-declare function sliceLines(lines: readonly string[], range?: {
-    start?: number;
-    end?: number;
-}, label?: string): string;
-/** The pin of the cited lines: plain, or the keyed pin under `key` when one is given. */
-declare function hashRange(text: string, range?: {
-    start?: number;
-    end?: number;
-}, key?: string): string;
+
 /**
- * The pin of already-joined lines: `sha256-<hex>`, or with `key` the
- * `hmac-sha256-<hex>` keyed pin an encrypted source carries. A plain pin
- * passes `undefined`.
+ * The cited lines joined by LF. Throws `CiteError` when the range runs past
+ * the end of the text (`<path> has N lines; line M is out of range`).
  */
-declare function hashLines(joined: string, key?: string): string;
-/** Whether a pin is keyed (`hmac-sha256-`), the form an encrypted source carries. */
-declare function isKeyedPin(pin: string): boolean;
+declare function sliceLines(lines: readonly string[], range?: LineRange, label?: string): string;
+/** The pin of the cited lines: plain, or the keyed pin under `key` when one is given. Throws `CiteError` past the end. */
+declare function hashRange(text: string, range?: LineRange, key?: string): string;
 
 /**
  * How a citation reads on a terminal. A pin is sixty-four hex digits and a
@@ -3801,12 +4017,6 @@ declare function offsetOfLine(content: string, line: number): number;
 declare function normalizeWhitespace(text: string): string;
 /** `true` when the block's normalized text equals the cited lines under the hashing rule. */
 declare function blockMatches(blockText: string, citedJoined: string): boolean;
-/** Body lines as file lines: body line 1 is the first line after the frontmatter. */
-declare function toFileLines(lines: PageLines, bodyLine: number): PageLines;
-/** File lines as body lines. */
-declare function toBodyLines(lines: PageLines, bodyLine: number): PageLines;
-/** The pin of a page range, under the claim rule: always plain. */
-declare function pinOfLines(lines: readonly string[], range: PageLines): string | undefined;
 /** The first file line of a classified claim: where its findings sit. */
 declare function claimLine(claim: ClaimEnd): number | undefined;
 /**
@@ -3877,9 +4087,6 @@ declare function noGit(): GitClient;
  * `moved`, not `never-true`; the search sees the file as it is.
  */
 
-declare const MOVE_WINDOW_LINES = 2000;
-declare const MOVE_BUDGET_BYTES: number;
-declare const MAX_RANGE_LINES = 5000;
 interface ClassifyOptions {
     root: string;
     index: SourceIndex;
@@ -3890,24 +4097,6 @@ interface ClassifyOptions {
     /** Hashing budget for the blind move search, in bytes. Default `MOVE_BUDGET_BYTES`. */
     budget?: number;
 }
-interface FindWindowsOptions {
-    /** The 1-based start line the range was pinned at: the blind search begins around it. */
-    around?: number;
-    /** The cited lines at the commit, when git could show them: enables the first-line filter. */
-    original?: readonly string[];
-    /** Hashing budget for the blind search, in bytes. Default `MOVE_BUDGET_BYTES`. */
-    budget?: number;
-}
-/**
- * Pure move search over normalized lines: the 1-based start lines where a
- * window of `length` lines hashes to `pin`. `original` (the cited lines at the
- * commit, when known) enables the first-line filter. `key` keys the hash for
- * an encrypted source's pin and is `undefined` for a plain one.
- */
-declare function findWindows(lines: readonly string[], length: number, pin: string, key: string | undefined, opts?: FindWindowsOptions): {
-    starts: number[];
-    truncated: boolean;
-};
 /**
  * What git could say about the pin at the recorded commit. `unknown` is a
  * file at the commit too large to search under the budget with the pin found

package/dist/index.js

@@ -5,7 +5,7 @@ import {
   reencryptMetadata,
   runKeyRotate,
   runKeySet
-} from "./chunk-QLVNSAHR.js";
+} from "./chunk-UTXTVCBV.js";
 import {
   BinMissing,
   COMMON_FORMATS,
@@ -125,7 +125,7 @@ import {
   valueOf,
   vendorFileName,
   writeFileAtomic
-} from "./chunk-PDNSN5UJ.js";
+} from "./chunk-2DC2GSRH.js";
 
 // src/key/index.ts
 var key_exports = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hawkeyexl/manni",
-  "version": "2.0.1",
+  "version": "2.1.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": {