@lannguyensi/harness 0.63.0 → 1.0.0

package/dist/schema/removed-keys.d.ts

@@ -0,0 +1,185 @@
+/** A manifest path a release removed. */
+export interface RemovedManifestPath {
+    /** Dotted path from the manifest root, e.g. `grounding.policies_source`. */
+    path: string;
+    /** The release that removed it. */
+    removedIn: string;
+    /** One line on why it went. */
+    reason: string;
+    /**
+     * Extra sentence for the warning, derived from the stripped value (for
+     * example a sub-setting whose removal changes behaviour). Return undefined
+     * when the value needs no extra sentence.
+     */
+    note?: (stripped: unknown) => string | undefined;
+    /**
+     * Strip an empty value (`[]`, `{}`, null) without a warning. A non-empty
+     * value, or a scalar, still warns.
+     */
+    silentWhenEmpty?: boolean;
+    /**
+     * Strip a value silently when this predicate returns true for it, in
+     * addition to `silentWhenEmpty`. For a shape an older release wrote by
+     * default into every exported manifest (`harness export` serialised the
+     * parsed manifest, schema defaults included): the shape configures nothing,
+     * but `isEmptyValue` does not cover it and must not be widened for other
+     * keys. Any other value of the path still warns.
+     */
+    silentWhen?: (stripped: unknown) => boolean;
+}
+/**
+ * A field of a `hooks[]` entry a release removed. The field is stripped and
+ * ignored, with one warning per hook; a later layer may still delete the hook.
+ */
+export interface RemovedHookField {
+    /** The key on a `hooks[]` entry, e.g. `bash_match`. */
+    field: string;
+    removedIn: string;
+    /** One line on why it went. */
+    reason: string;
+}
+/** A builtin pack name a release removed. */
+export interface RemovedPackName {
+    name: string;
+    removedIn: string;
+    reason: string;
+}
+export interface RemovedManifestTable {
+    paths: readonly RemovedManifestPath[];
+    hookFields: readonly RemovedHookField[];
+    packs: readonly RemovedPackName[];
+}
+export declare const REMOVED_MANIFEST_PATHS: readonly RemovedManifestPath[];
+export declare const REMOVED_HOOK_FIELDS: readonly RemovedHookField[];
+export declare const REMOVED_PACK_NAMES: readonly RemovedPackName[];
+export declare const REMOVED_MANIFEST_TABLE: RemovedManifestTable;
+/**
+ * A `harness list` category or `harness describe --pillar` value a release
+ * removed. Naming one on the command line is a usage error that says so.
+ */
+export interface RemovedInspectName {
+    name: string;
+    removedIn: string;
+    reason: string;
+}
+export declare const REMOVED_LIST_CATEGORIES: readonly RemovedInspectName[];
+export declare const REMOVED_DESCRIBE_PILLARS: readonly RemovedInspectName[];
+/** The usage-error text for a removed `kind` ("list category", "pillar") given on the command line. */
+export declare function removedInspectNameMessage(kind: string, removed: RemovedInspectName): string;
+/** One stripped entry, for display. */
+export interface ManifestPostureWarning {
+    /** Where it was found (`grounding.policies_source`, `policy_packs[2]`). */
+    path: string;
+    message: string;
+}
+/**
+ * Where the entries an array kept sat in the manifest as written. Dropping an
+ * entry re-indexes the array, so a diagnostic about a later entry would name
+ * the wrong position without it.
+ */
+export interface IndexMap {
+    /** `kept[k]` is the original index of the entry now at index `k`. */
+    kept: readonly number[];
+    /** Length of the array before any entry was dropped. */
+    originalLength: number;
+}
+/** Index maps of the arrays `stripRemovedManifestEntries` dropped entries from. */
+export interface StrippedIndexMaps {
+    policy_packs?: IndexMap;
+}
+export interface StrippedManifest {
+    raw: unknown;
+    warnings: ManifestPostureWarning[];
+    /** Present only when an array lost an entry. */
+    indexMaps?: StrippedIndexMaps;
+}
+/**
+ * The index in the manifest as written for index `k` of the stripped array.
+ * An index past the kept entries (an entry appended after the parse) keeps
+ * its distance from the end.
+ */
+export declare function originalIndex(map: IndexMap | undefined, k: number): number;
+/** Remap a zod issue path (`["policy_packs", 0, ...]`) to the manifest as written. */
+export declare function remapIssuePath(path: ReadonlyArray<string | number>, maps: StrippedIndexMaps | undefined): Array<string | number>;
+/**
+ * Remap a diagnostic path that names `policy_packs[k]` (also the dotted
+ * `policy_packs.k`) to the manifest as written. Any other path is returned
+ * unchanged.
+ */
+export declare function remapDiagnosticPath(path: string, maps: StrippedIndexMaps | undefined): string;
+/**
+ * A plain `{...}` mapping: not null, not an array, and with `Object.prototype`
+ * or no prototype at all. The one shared copy (the merge engine and the
+ * layer-root check were copies of this); YAML-parsed documents only ever
+ * carry such objects, arrays, and scalars, so the prototype check only
+ * excludes exotic values like a YAML timestamp's `Date`.
+ */
+export declare function isPlainObject(v: unknown): v is Record<string, unknown>;
+/**
+ * Strip every removed manifest path from a raw manifest (or one override
+ * layer), one warning per path that was present, none for an empty value of a
+ * `silentWhenEmpty` path or a value its `silentWhen` accepts. Pure: `raw` is
+ * not modified, and the same object is returned when nothing was stripped.
+ */
+export declare function stripRemovedManifestPaths(raw: unknown, paths?: readonly RemovedManifestPath[]): {
+    raw: unknown;
+    warnings: ManifestPostureWarning[];
+};
+/**
+ * Strip every removed per-hook field from one raw source (the base manifest
+ * or one override layer) BEFORE it is merged: the merge walks name-keyed
+ * lists and throws on a shape it cannot reconcile, and a removed field like
+ * `bash_match` can carry exactly such colliding shapes across sources. The
+ * hooks stay; one warning per hook that carried a key, as in
+ * `stripRemovedManifestEntries`, whose post-merge strip stays as the safety
+ * net for callers that parse without merging (it then finds nothing left).
+ * Pure: `raw` is not modified, and the same object is returned when nothing
+ * was stripped.
+ */
+export declare function stripRemovedHookFields(raw: unknown, hookFields?: readonly RemovedHookField[]): {
+    raw: unknown;
+    warnings: ManifestPostureWarning[];
+};
+/**
+ * Strip every removed manifest path, strip every removed field from the
+ * hooks that carry it (the hook stays), and drop every removed pack entry
+ * from a raw (merged, not yet parsed) manifest. After a
+ * `mergeLayersStrippingRemovedPaths` merge the hook fields are already
+ * stripped (they went before the merge), so this strip finds nothing left of
+ * them and warns no second time; it stays for callers that parse a single
+ * source without merging. Pure: `raw` is not modified.
+ */
+export declare function stripRemovedManifestEntries(raw: unknown, table?: RemovedManifestTable): StrippedManifest;
+/** One line per warning, as `harness validate` / `harness doctor` print it. */
+export declare function formatPostureWarning(w: ManifestPostureWarning): string;
+/** A CLI command prefix a release removed (a generated hook or producer that still calls it fails). */
+export interface RemovedCommand {
+    /** Command prefix as it appears in a hook or producer `command`, e.g. `harness session-start`. */
+    command: string;
+    removedIn: string;
+    reason: string;
+}
+export declare const REMOVED_COMMANDS: readonly RemovedCommand[];
+/**
+ * The removed command `command` invokes, if any. Matching rule: after trimming
+ * and dropping leading plain `NAME=value` assignments, the command must start
+ * with a table entry followed by the end, whitespace or a hyphen. Anything
+ * else is not matched: a command word given as a path (`/usr/local/bin/harness
+ * preflight`), a wrapper (`npx harness preflight`), a compound command (`cd x
+ * && harness preflight`), or an assignment with a quoted or expanded value.
+ */
+export declare function invokesRemovedCommand(command: string, table?: readonly RemovedCommand[]): RemovedCommand | undefined;
+export declare function removedCommandMessage(removed: RemovedCommand, remedy: string): string;
+/**
+ * Every place a raw (merged) manifest still calls a removed CLI command, one
+ * warning per site. A manifest generated before the removal keeps such hooks
+ * and pack configs until the operator deletes them: `harness apply` renders from
+ * the manifest, so it re-emits them, and the hook or the agent-facing remedy
+ * then runs a command that no longer exists.
+ *
+ * Scanned sites: `hooks[].command`; each pack's `config.producers[].command`
+ * and `config.ux.run[]`. An entry of a removed pack is skipped (the pack
+ * itself already warns). Pure and tolerant: anything that is not the expected
+ * shape is skipped, the strict parse reports it.
+ */
+export declare function findRemovedCommandUses(raw: unknown, commands?: readonly RemovedCommand[], removedPacks?: readonly RemovedPackName[]): ManifestPostureWarning[];