@forwardimpact/libutil 0.1.94 → 0.1.95

package/LICENSE

@@ -1,201 +1,21 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to the Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright 2026 Dick Olsson
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+MIT License
+
+Copyright (c) 2019 Zachary Rice
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libutil",
-  "version": "0.1.94",
+  "version": "0.1.95",
   "description": "Cross-cutting utilities: retry, hashing, token counting, and project discovery.",
   "keywords": [
     "util",

package/src/git-client.js

@@ -17,6 +17,33 @@ export class GitError extends Error {
   }
 }
 
+// Resolve a `git diff` "+++ <target>" header to a working-tree path, or null
+// for a deletion ("+++ /dev/null"). The "b/" prefix is git's destination side.
+function parseDiffTarget(headerLine) {
+  const target = headerLine.slice(4).trim();
+  return target.startsWith("b/") ? target.slice(2) : null;
+}
+
+/**
+ * Reject `:`-prefixed pathspec entries before they reach git. A leading `:`
+ * marks git pathspec magic (`:/`, `:(exclude)…`, `:(glob)…`), which the `--`
+ * separator does NOT neutralise — `--` ends OPTION parsing, not pathspec magic.
+ * A dynamically derived filename starting with `:` could therefore widen a
+ * scoped commit beyond the named files, so the path-forwarding methods
+ * (`commitPaths`, `status`) reject it at entry rather than passing it to git.
+ * @param {string[]} [paths]
+ */
+function assertSafePaths(paths) {
+  for (const p of paths ?? []) {
+    if (typeof p === "string" && p.startsWith(":")) {
+      throw new Error(
+        `unsafe pathspec: ':'-prefixed entries are rejected (got '${p}'); ` +
+          "':' magic survives the '--' separator and could widen the commit",
+      );
+    }
+  }
+}
+
 /**
  * Typed wrapper over the `git` CLI. All shelling-out flows through the
  * injected `runtime.subprocess`, so callers never import `node:child_process`
@@ -56,8 +83,15 @@ export class GitClient {
     return this.#runRaw(args, { cwd });
   }
 
-  /** Return `git status --porcelain` output, optionally limited to `paths`. */
+  /**
+   * Return `git status --porcelain` output, optionally limited to `paths`.
+   * @param {object} [options]
+   * @param {string} [options.cwd]
+   * @param {string[]} [options.paths] - Pathspecs to scope the status to.
+   *   `:`-prefixed entries are rejected ({@link assertSafePaths}).
+   */
   async status({ cwd, paths } = {}) {
+    assertSafePaths(paths);
     const args = ["status", "--porcelain"];
     if (paths?.length) args.push("--", ...paths);
     return this.#runRaw(args, { cwd });
@@ -77,12 +111,107 @@ export class GitClient {
     return this.#runRaw(["rebase", "--abort"], { cwd, allowFailure: true });
   }
 
-  /** Merge `ref` into the current branch resolving conflicts with `-X ours`. */
-  async mergeOursStrategy({ cwd, ref, autostash = false }) {
+  /**
+   * Move HEAD to `ref` without touching the index or working tree
+   * (`git reset --soft`). Drops local commits ahead of `ref` while leaving every
+   * uncommitted change — including foreign residue from parallel writers — in
+   * place, unlike a `--hard` reset.
+   */
+  async resetSoft(ref, { cwd } = {}) {
+    return this.#runRaw(["reset", "--soft", ref], { cwd });
+  }
+
+  /**
+   * Reset only `paths` to their content at `ref` (`git checkout <ref> --
+   * <paths>`), leaving the rest of the working tree untouched. With
+   * `allowMissing`, a path absent on `ref` (e.g. a founding write of a file the
+   * tip does not yet carry) yields a non-zero result instead of throwing.
+   * @param {string} ref
+   * @param {string[]} paths
+   * @param {{cwd?: string, allowMissing?: boolean}} [options]
+   */
+  async checkoutPaths(ref, paths, { cwd, allowMissing = false } = {}) {
+    return this.#runRaw(["checkout", ref, "--", ...paths], {
+      cwd,
+      allowFailure: allowMissing,
+    });
+  }
+
+  /**
+   * Merge `ref` into the current branch resolving conflicts with `-X ours`.
+   * With `allowFailure`, a non-zero exit resolves to the raw result instead of
+   * throwing, so the caller can abort and refuse rather than strand a
+   * mid-merge tree.
+   */
+  async mergeOursStrategy({
+    cwd,
+    ref,
+    autostash = false,
+    allowFailure = false,
+  }) {
     const args = ["merge"];
     if (autostash) args.push("--autostash");
     args.push("-X", "ours", "--no-edit", ref);
-    return this.#runRaw(args, { cwd });
+    return this.#runRaw(args, { cwd, allowFailure });
+  }
+
+  /** Abort an in-progress merge, restoring the pre-merge state. */
+  async mergeAbort({ cwd } = {}) {
+    return this.#runRaw(["merge", "--abort"], { cwd, allowFailure: true });
+  }
+
+  /**
+   * Paths with an unmerged index entry (`git status --porcelain` rows whose XY
+   * status is a U-family code: `UU`/`AA`/`DD`/`AU`/`UA`/`DU`/`UD`). Decidable
+   * from the index alone — no history resolution — so it holds on a shallow
+   * clone.
+   */
+  async unmergedPaths({ cwd } = {}) {
+    const result = await this.#runRaw(["status", "--porcelain"], { cwd });
+    const unmerged = /^(DD|AU|UD|UA|DU|AA|UU)/;
+    return result.stdout
+      .split("\n")
+      .filter((line) => unmerged.test(line))
+      .map((line) => line.slice(3).trim())
+      .filter(Boolean);
+  }
+
+  /**
+   * Whether the repository is mid-merge: an unmerged index entry exists or a
+   * MERGE_HEAD is pinned. Both signals are local to the clone, so this holds at
+   * any fetch depth.
+   */
+  async isMidMerge({ cwd } = {}) {
+    if ((await this.unmergedPaths({ cwd })).length > 0) return true;
+    const head = await this.#runRaw(
+      ["rev-parse", "-q", "--verify", "MERGE_HEAD"],
+      { cwd, allowFailure: true },
+    );
+    return head.exitCode === 0;
+  }
+
+  /**
+   * The content introduced by `range` (e.g. `origin/master..HEAD`), grouped by
+   * path. Returns a `Map<path, addedText>` where `addedText` is the added side
+   * of the diff with the leading `+` of each hunk line stripped and the
+   * `+++`/`---` file headers excluded, so line-anchored scanners match at
+   * column 1. Throws {@link GitError} on a non-zero exit (e.g. an unresolvable
+   * ref) — callers must treat a throw as refuse-with-reason, never a silent
+   * pass.
+   */
+  async introducedByFile(range, { cwd } = {}) {
+    const result = await this.#runRaw(["diff", "--no-color", range], { cwd });
+    const byFile = new Map();
+    let current = null;
+    for (const line of result.stdout.split("\n")) {
+      if (line.startsWith("+++ ")) {
+        current = parseDiffTarget(line);
+        if (current && !byFile.has(current)) byFile.set(current, []);
+      } else if (current && line.startsWith("+")) {
+        byFile.get(current).push(line.slice(1));
+      }
+    }
+    return new Map([...byFile].map(([p, lines]) => [p, lines.join("\n")]));
   }
 
   /** Stage all changes and commit with `message`. */
@@ -97,8 +226,14 @@ export class GitClient {
    * Stage and commit only `paths`, leaving the rest of the working tree
    * untouched. The commit carries the same pathspec so content staged by
    * other writers is never swept in.
+   * @param {string} message
+   * @param {string[]} paths - Pathspecs to stage and commit. `:`-prefixed
+   *   entries are rejected ({@link assertSafePaths}) so a dynamically derived
+   *   filename can never widen the commit beyond the named files.
+   * @param {{cwd?: string, author?: string}} [options]
    */
   async commitPaths(message, paths, { cwd, author } = {}) {
+    assertSafePaths(paths);
     await this.#runRaw(["add", "--", ...paths], { cwd });
     const args = ["commit", "-m", message];
     if (author) args.push("--author", author);
@@ -114,6 +249,63 @@ export class GitClient {
     return this.#runRaw(args, { cwd });
   }
 
+  /**
+   * List commits in `ref` authored by `author`, newest first, as
+   * `{sha, when}` where `when` is the commit epoch seconds (`%ct`). Excludes
+   * merge commits. Returns `[]` on any git failure (e.g. an unborn ref).
+   * @param {string} author - Author match (git `--author=` pattern).
+   * @param {{cwd?: string, ref?: string}} [opts]
+   * @returns {Promise<Array<{sha: string, when: number}>>}
+   */
+  async logByAuthor(author, { cwd, ref = "HEAD" } = {}) {
+    const r = await this.#runRaw(
+      ["log", ref, `--author=${author}`, "--no-merges", "--format=%H %ct"],
+      { cwd, allowFailure: true },
+    );
+    if (r.exitCode !== 0) return [];
+    return r.stdout
+      .trim()
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => {
+        const [sha, ct] = line.split(" ");
+        return { sha, when: Number.parseInt(ct, 10) };
+      });
+  }
+
+  /**
+   * Unified-diff text (`--unified=0`) of a two-tree `range` (e.g. `"A B"` or
+   * `"A..B"`), or `null` on git failure. A two-tree range diff (never a
+   * single-commit `git show`) diffs merge commits correctly. An empty string
+   * is a legitimate empty diff; `null` is an error — callers distinguish them.
+   * @param {string} range - Range spec; split on spaces into git args.
+   * @param {{cwd?: string}} [opts]
+   * @returns {Promise<string|null>}
+   */
+  async diffRange(range, { cwd } = {}) {
+    const r = await this.#runRaw(
+      ["diff", "--no-color", "--unified=0", ...range.split(" ")],
+      { cwd, allowFailure: true },
+    );
+    return r.exitCode === 0 ? r.stdout : null;
+  }
+
+  /**
+   * Contents of `filePath` at `ref` (`git show ref:path`), or `null` when the
+   * path is absent at that ref.
+   * @param {string} ref - The ref to read from (e.g. `"origin/master"`).
+   * @param {string} filePath - Repo-relative path.
+   * @param {{cwd?: string}} [opts]
+   * @returns {Promise<string|null>}
+   */
+  async showFile(ref, filePath, { cwd } = {}) {
+    const r = await this.#runRaw(["show", `${ref}:${filePath}`], {
+      cwd,
+      allowFailure: true,
+    });
+    return r.exitCode === 0 ? r.stdout : null;
+  }
+
   /** Count commits in `range` (`git rev-list --count`). */
   async revListCount(range, { cwd }) {
     const result = await this.#runRaw(["rev-list", "--count", range], { cwd });
@@ -145,6 +337,82 @@ export class GitClient {
     return result.stdout.trim();
   }
 
+  /**
+   * The short name of the branch HEAD points at, or "" when HEAD is detached.
+   * An unborn HEAD on a branch (no commits yet) still returns that branch name —
+   * `symbolic-ref` reads the ref HEAD targets, not whether it resolves.
+   */
+  async headBranch({ cwd } = {}) {
+    const r = await this.#runRaw(["symbolic-ref", "--short", "-q", "HEAD"], {
+      cwd,
+      allowFailure: true,
+    });
+    return r.stdout.trim();
+  }
+
+  /** Whether `ref` resolves to a commit (`rev-parse --verify`). */
+  async refExists(ref, { cwd } = {}) {
+    const r = await this.#runRaw(
+      ["rev-parse", "--verify", "-q", `${ref}^{commit}`],
+      { cwd, allowFailure: true },
+    );
+    return r.exitCode === 0;
+  }
+
+  /**
+   * Whether `a` and `b` share a merge-base within the fetched history.
+   * `git merge-base` exits 1 (not an error) when no base exists, so this runs
+   * with `allowFailure` and reads the exit code rather than throwing.
+   */
+  async mergeBaseExists(a, b, { cwd } = {}) {
+    const r = await this.#runRaw(["merge-base", a, b], {
+      cwd,
+      allowFailure: true,
+    });
+    return r.exitCode === 0;
+  }
+
+  /**
+   * Whether `branch` exists on `remote` (`ls-remote --heads`). Throws a
+   * {@link GitError} when the remote cannot be observed, so callers can
+   * distinguish a genuinely empty remote from a failed observation.
+   */
+  async remoteBranchExists(remote, branch, { cwd } = {}) {
+    const r = await this.#runRaw(["ls-remote", "--heads", remote, branch], {
+      cwd,
+    });
+    return r.stdout.trim() !== "";
+  }
+
+  /**
+   * Deepen history to full depth for `branch` from `remote`. Runs with
+   * `allowFailure` because `--unshallow` errors on a complete clone; callers
+   * gate this behind a shallow-clone check and treat a non-zero exit as
+   * "deepening failed".
+   */
+  async fetchDeepen(remote, branch, { cwd } = {}) {
+    return this.#runRaw(["fetch", "--unshallow", remote, branch], {
+      cwd,
+      allowFailure: true,
+    });
+  }
+
+  /**
+   * List the tags and heads a remote `url` exposes, without cloning. Returns
+   * the raw `{ stdout, stderr, exitCode }` so callers can distinguish exit 0
+   * (refs listed), exit 128 (auth demand — absent or private), and transport
+   * faults. Auth and env are handled by `#runRaw`: a tokenless client transports
+   * anonymously, and `GIT_TERMINAL_PROMPT` is whatever the runtime's `proc.env`
+   * carries.
+   * @param {string} url - The repository URL (e.g. `https://github.com/owner/repo`).
+   * @returns {Promise<{stdout: string, stderr: string, exitCode: number}>}
+   */
+  async lsRemote(url) {
+    return this.#runRaw(["ls-remote", "--tags", "--heads", url], {
+      allowFailure: true,
+    });
+  }
+
   /** Return a new client that threads `token` into the git env. */
   withAuth(token) {
     return new GitClient({ runtime: this.#runtime, token });

package/src/rules.js

@@ -11,8 +11,10 @@
 //   an array of finding items. Each item is a plain object whose fields the
 //   rule's `message` function reads (e.g., `{ value: 572 }`).
 // - `message(subject, item, ctx)` builds the human-readable message string.
-// - `hint` is an optional static string rendered as an action prompt by the
-//   text emitter.
+// - `hint` is an optional action prompt rendered by the text emitter: either a
+//   static string or a `(subject, item, ctx) => string` resolved once per
+//   finding. A function hint lets a rule emit a fully resolved command from the
+//   subject (e.g. a `rotate --agent <prefix>` naming the flagged file's agent).
 //
 // `ctx` is passed unchanged to every rule. Cross-subject state (e.g., a
 // duplicate-detection map) lives on `ctx` and is mutated by the rule during
@@ -38,7 +40,10 @@ function applyRule(rule, subject, ctx) {
     path: subject.path ?? null,
     lineNo: item.lineNo ?? subject.lineNo ?? null,
     message: rule.message(subject, item, ctx),
-    hint: rule.hint ?? null,
+    hint:
+      typeof rule.hint === "function"
+        ? rule.hint(subject, item, ctx)
+        : (rule.hint ?? null),
   }));
 }