@nikovirtala/adr 0.1.0 → 0.3.0

package/dist/types/cli/reject.d.ts

@@ -0,0 +1,3 @@
+import { type CommandSpec } from "@nikovirtala/ledger/cli";
+/** `adr reject` (design §6.3): a proposal that won't be adopted. */
+export declare const rejectCommand: CommandSpec;

package/dist/types/cli/scope.d.ts

@@ -0,0 +1,7 @@
+import { type CommandSpec } from "@nikovirtala/ledger/cli";
+/**
+ * `adr scope <decision> --set|--clear|--add|--remove …` (design §6.8): the globs of the code a
+ * decision governs, written as one whole-set `scoped` event. `adr scope [<decision>]
+ * --follow-renames` rewrites them after staged renames and stages the events, never committing.
+ */
+export declare const scopeCommand: CommandSpec;

package/dist/types/cli/supersede.d.ts

@@ -1,3 +1,3 @@
-import type { CommandSpec } from "@nikovirtala/ledger/cli";
+import { type CommandSpec } from "@nikovirtala/ledger/cli";
 /** `adr supersede <decision> --by <decision> …` (design §5.6). */
 export declare const supersedeCommand: CommandSpec;

package/dist/types/cli/text.d.ts

@@ -1,16 +1,52 @@
+import { type Actor } from "@nikovirtala/ledger";
+import type { InitResultJson } from "../init.js";
+import type { ChangedSince } from "../log.js";
+import type { DecisionsForJson } from "../scope.js";
 import type { DecisionListJson, DecisionShowJson } from "../views.js";
-import type { WriteResultJson } from "../write.js";
+import type { ScopeOffer, WriteResultJson } from "../write.js";
 /** How a decision id is shown: its display (`ADR-0007`), or the id when it has no number. */
 export type Display = (id: string) => string;
 /** `adr list`: one row per decision, `→ <effective>` when it differs from the decision. */
 export declare function listText(doc: DecisionListJson, display: Display): string;
 /**
- * The text of `adr new|accept|supersede` (design §5.6). `subject` names what a refused command
- * was about; `number` is the decision's number in the write result, if it has one now.
+ * `adr list --since <rev>` (design 2b D7): a heading, then each row followed by the event types
+ * added since `rev`; nothing at all when no decision changed, so the post-merge hook stays quiet.
+ */
+export declare function sinceText(doc: DecisionListJson, since: ChangedSince, display: Display): string;
+/**
+ * The stderr warning of `new` when the draft it wrote has unfilled sections (design §7.2), or
+ * `null` when there are none.
+ */
+export declare function unfilledWarning(doc: WriteResultJson): string | null;
+export interface FollowRenamesBefore {
+    readonly before: ReadonlyMap<string, readonly string[]>;
+    readonly renamed: boolean;
+}
+/**
+ * The text of a write command (design §5.6, §6.1). `subject` names what a refused command was
+ * about; `number` is the decision's number in the write result, if it has one now; `reason` is
+ * the reason a lifecycle exit recorded.
  */
 export declare function writeText(doc: WriteResultJson, display: Display, o: {
     readonly subject: string;
     readonly number: string | null;
+    readonly reason?: string | null;
+    /** The decision's globs before a `scope` write. */
+    readonly scopeBefore?: readonly string[];
+    /** For `scope --follow-renames`: every decision's globs before, and whether renames were staged. */
+    readonly followRenames?: FollowRenamesBefore;
+    /** The superseded scope an `accept` copied. */
+    readonly copied?: ScopeOffer | null;
+    /** Who proposed with `new`, and the log's `accept_requires_human`, for the next step. */
+    readonly actor?: Actor;
+    readonly acceptRequiresHuman?: boolean;
 }): string;
 /** `adr show`: the state header, the decision's fields and its body. */
 export declare function showText(doc: DecisionShowJson, display: Display): string;
+/**
+ * `adr for`: per path, one row per decision (named, status, title, how it matched), its warning
+ * below it when it isn't in force, then the anchors that name no decision of this log.
+ */
+export declare function forText(doc: DecisionsForJson, display: Display, keyword: string): string;
+/** `adr init`: what was written and kept, then the next step; or that nothing was needed. */
+export declare function initText(doc: InitResultJson): string;

package/dist/types/cli/withdraw.d.ts

@@ -0,0 +1,3 @@
+import { type CommandSpec } from "@nikovirtala/ledger/cli";
+/** `adr withdraw` (design §6.4): a proposal its author takes back. */
+export declare const withdrawCommand: CommandSpec;

package/dist/types/commit-actions.d.ts

@@ -0,0 +1,72 @@
+/**
+ * `{action}` of a commit that writes one event of each type (design §4.3), and what the title slot
+ * names: the decision's title for the events that change whether it is decided, else its display.
+ */
+export declare const ACTIONS: {
+    readonly proposed: {
+        readonly action: "propose to";
+        readonly names: "title";
+    };
+    readonly accepted: {
+        readonly action: "decide to";
+        readonly names: "title";
+    };
+    readonly rejected: {
+        readonly action: "decide not to";
+        readonly names: "title";
+    };
+    readonly withdrawn: {
+        readonly action: "withdraw the proposal to";
+        readonly names: "title";
+    };
+    readonly deprecated: {
+        readonly action: "deprecate";
+        readonly names: "display";
+    };
+    readonly superseded: {
+        readonly action: "supersede";
+        readonly names: "display";
+    };
+    readonly noted: {
+        readonly action: "add a note to";
+        readonly names: "display";
+    };
+    readonly linked: {
+        readonly action: "link";
+        readonly names: "display";
+    };
+    readonly scoped: {
+        readonly action: "set the scope of";
+        readonly names: "display";
+    };
+};
+/** `{action}` of `adr index --commit`, whose title slot holds `the decision index`. */
+export declare const INDEX_ACTION = "regenerate";
+/** What `adr index --commit`'s title slot holds. */
+export declare const INDEX_TITLE = "the decision index";
+/** The longest `{action}`, which `[commit] subject` must leave room for. */
+export declare const LONGEST_ACTION: number;
+/** The longest display: `ADR-` and up to 9 digits (`formatDecisionNumber`, kind/project.ts). */
+export declare const DISPLAY_LENGTH = 13;
+/** What a link's title slot names after the display when the target is in another log. */
+export declare const CROSS_LOG_LINK = "to a decision in another log";
+/** adr's commit-subject placeholders, each with its longest value (design §4.2). */
+export declare const COMMIT_VARS: Readonly<{
+    action: number;
+    id: 8;
+    display: 13;
+    command: 9;
+}>;
+/**
+ * The names the title placeholder holds instead of a title, which are never shortened, each with
+ * its action: supersede's `<display> with <display>` and a link's `<display> to <display>` or
+ * `<display> to a decision in another log` (`planLink` in write.ts), and `adr index`'s
+ * `the decision index`. The shorter names (a display, at most 13 characters) always fit in the
+ * room a title gets.
+ */
+export declare const COMMIT_NAMES: readonly {
+    length: number;
+    vars: {
+        action: number;
+    };
+}[];

package/dist/types/config.d.ts

@@ -1,11 +1,13 @@
-import { type Severity, type ToolConfig } from "@nikovirtala/ledger";
+import { type CommitTemplate, type Severity, type ToolConfig } from "@nikovirtala/ledger";
+/** The default `[commit] subject`. */
+export declare const DEFAULT_COMMIT_SUBJECT = "docs(adr): {action} {title}";
 /** adr's settings from `adr.toml` (design §5.3); every key is optional. */
 export interface AdrConfig {
     /** `[log] default_template`: the template `adr new` uses without `--template`. */
     readonly defaultTemplate: string;
     /** `[log] main_branch`: the ref numbers come from; `null` resolves it automatically. */
     readonly mainBranch: string | null;
-    /** `[log] index`: validated now, used in phase 2. */
+    /** `[log] index`: `committed` keeps a generated `<root>/index.md` fresh and verified. */
     readonly index: "committed" | "none";
     /** `[policy] accept_requires_human`. */
     readonly acceptRequiresHuman: boolean;
@@ -15,6 +17,18 @@ export interface AdrConfig {
     readonly mcpCanDecide: boolean;
     /** `[verify] fail_on`. */
     readonly failOn: Severity;
+    /** `[verify] governed_by_inactive`: the severity of `decision/governed-by-inactive`. */
+    readonly governedByInactive: Severity;
+    /** `[hooks] scope_follow_renames`: what the pre-commit hook does with renames of covered files. */
+    readonly scopeFollowRenames: "stage" | "warn" | "off";
+    /** `[hooks] index`: whether the pre-commit hook only checks `index.md` or regenerates it. */
+    readonly hookIndex: "check" | "stage";
+    /** `[commit] subject`: the template of `--commit` subjects. */
+    readonly commitSubject: CommitTemplate;
+    /** `[scope] anchor_keyword`: the code-anchor keyword, `adr` in `// adr:<id>`. */
+    readonly anchorKeyword: string;
+    /** `[scope] anchor_exclude`: globs of files whose anchors are ignored (docs that show examples). */
+    readonly anchorExclude: readonly string[];
 }
 export declare const DEFAULT_ADR_CONFIG: AdrConfig;
 /**

package/dist/types/hooks.d.ts

@@ -0,0 +1,59 @@
+import { type Finding, type HookManager, type HookName, type Severity } from "@nikovirtala/ledger";
+import type { DecisionLog } from "./log.js";
+/** `adr hooks … --json` (design 2b §4.3); `hooks run` prints `ledger-findings/v1` instead. */
+export interface HooksResultJson {
+    readonly format: "adr-hooks/v1";
+    readonly action: "install" | "uninstall" | "print" | "trailers";
+    /** Repo-relative shim paths written or removed. */
+    readonly written: readonly string[];
+    readonly unchanged: readonly string[];
+    readonly registrations: readonly {
+        readonly hook: HookName;
+        readonly argv: readonly string[];
+    }[];
+    /** `print` only. */
+    readonly snippet: string | null;
+    /** `trailers` only: the trailers added, in order. */
+    readonly trailers: readonly (readonly [string, string])[];
+}
+/**
+ * adr's command per hook (design 2b D4), after `adr`. `--root <root>` comes first only when the
+ * root can't be found without it: no `<repo>/adr.toml` names it and it isn't `docs/adr`. So the
+ * hooks see the same config as a plain `adr` run, and never print the root-override note.
+ */
+export declare function decisionHookCommands(log: DecisionLog): Partial<Record<HookName, readonly string[]>>;
+/**
+ * Registers adr's four commands in ledger's shims, one per hook and shared with other ark tools
+ * (design 2b D4). With `core.hooksPath` set or a foreign hook file present, it writes the rest and
+ * then throws `HookConflictError` (exit 2), naming each conflict and the `print` command.
+ */
+export declare function installDecisionHooks(log: DecisionLog): Promise<HooksResultJson>;
+/** Removes adr from every shim; a shim left with no tool is deleted. */
+export declare function uninstallDecisionHooks(log: DecisionLog): Promise<HooksResultJson>;
+/** The config to paste into a hook manager instead of installing shims. */
+export declare function printDecisionHooks(log: DecisionLog, manager: HookManager): HooksResultJson;
+/**
+ * The `commit-msg` step (P1 §7.1): appends one `ADR`/`ADR-Event` pair per staged added event file
+ * of the log, by path, keeping repeats (`ifExists: "add"`). It does nothing for a message that
+ * already has an `ADR-Event:` trailer (an `adr … --commit` message), or during a merge, whose
+ * events came with their own commits' trailers. Throws `UsageError` when the file is missing.
+ */
+export declare function addHookTrailers(log: DecisionLog, messageFile: string): Promise<HooksResultJson>;
+/**
+ * `adr hooks run pre-commit` (design 2b D8): rename following, then the index, then `verify
+ * --staged`, stopping at the first step that fails. `worktree` must be opened with the work-tree
+ * reader, because rename following writes through `write()`; `index` with the index reader, for
+ * the config as staged, the index render and verify. Only the index step stages `index.md`, and
+ * only with `[hooks] index = "stage"`; rename following passes `index: "skip"`. Neither stages
+ * into a temporary index (`stagingSafe`). A step that can't run throws (exit 2).
+ */
+export declare function runPreCommitHook(o: {
+    readonly worktree: DecisionLog;
+    readonly index: DecisionLog;
+    readonly env: NodeJS.ProcessEnv;
+}): Promise<{
+    readonly exit: 0 | 1;
+    readonly findings: readonly Finding[];
+    readonly notes: readonly string[];
+    readonly failOn: Severity;
+}>;

package/dist/types/index.d.ts

@@ -1,6 +1,10 @@
 export { type AdrConfig, DEFAULT_ADR_CONFIG, parseAdrConfig } from "./config.js";
+export { addHookTrailers, decisionHookCommands, type HooksResultJson, installDecisionHooks, printDecisionHooks, runPreCommitHook, uninstallDecisionHooks, } from "./hooks.js";
+export { type InitResultJson, initDecisionLog } from "./init.js";
 export { type AdrOptions, adrKind, DECISION_STATUSES, type DecisionEvents, type DecisionState, type DecisionStatus, type DecisionView, formatDecisionNumber, type LinkRel, parseDecisionNumber, REF, } from "./kind.js";
-export { type DecisionLog, type DecisionsRead, openDecisionLog, readDecisions, readDecisionsFrom, resolveDecision, } from "./log.js";
+export { type ChangedSince, changedSince, type DecisionLog, type DecisionsRead, openDecisionLog, readDecisions, readDecisionsFrom, resolveDecision, } from "./log.js";
+export { type IndexResultJson, indexDecisionLog, renderDecisionIndex } from "./log-index.js";
+export { type DecisionForJson, type DecisionsForJson, decisionsFor, type UnresolvedAnchorJson, } from "./scope.js";
 export { adrChecks, verifyDecisions } from "./verify.js";
 export { type DecisionListJson, type DecisionShowJson, listDecisions, type NumberingJson, showDecision, stateHeader, } from "./views.js";
-export { acceptDecision, type ProposeInput, proposeDecision, supersedeDecision, type WriteResultJson, } from "./write.js";
+export { acceptDecision, type CopyScope, deprecateDecision, followScopeRenames, type LinkInput, linkDecision, noteDecision, type ProposeInput, proposeDecision, type ReasonInput, rejectDecision, type ScopeInput, type ScopeOffer, scopeDecision, scopeToCopy, supersedeDecision, type WriteOptions, type WriteResultJson, withdrawDecision, } from "./write.js";

package/dist/types/init.d.ts

@@ -0,0 +1,33 @@
+import type { DecisionLog } from "./log.js";
+/** `adr init --json` (design §6.2). */
+export interface InitResultJson {
+    readonly format: "adr-init/v1";
+    readonly root: string;
+    /** The config file of the log after init, repo-relative; `null` if there is none. */
+    readonly config: string | null;
+    /** Repo-relative paths written, in write order. */
+    readonly written: readonly string[];
+    /** Files that were already there and were left as they are. */
+    readonly kept: readonly string[];
+    readonly commit: string | null;
+    readonly notes: readonly string[];
+}
+/**
+ * What the recovery hint says about rerunning `adr init` after `git commit` failed (design 2b D5):
+ * init keeps existing files, so it would commit nothing.
+ */
+export declare const INIT_RERUN = "Running adr init again won't commit them: the files exist now, so it keeps them and commits nothing.";
+/**
+ * `adr init` (design §6.2): writes a config for the log, unless one is found, and each built-in
+ * template in `o.templates` (default `nygard`) to `<root>/templates/`, never overwriting a file.
+ * A `--root` other than `docs/adr` gets a repo-level `adr.toml` naming it, so later commands find
+ * the log without `--root`; when that file exists for another log, the config goes in the root.
+ * With `[log] index = "committed"` it also writes `<root>/index.md` unless one exists. With
+ * `commit` (default `[policy] auto_commit`) the written files are committed on their own;
+ * nothing written means nothing committed. No events are written.
+ */
+export declare function initDecisionLog(log: DecisionLog, o?: {
+    readonly templates?: readonly string[];
+    readonly commit?: boolean;
+    readonly message?: string | null;
+}): Promise<InitResultJson>;

package/dist/types/log-index.d.ts

@@ -0,0 +1,117 @@
+import { type Check, type Finding, type Git, type IndexSpec, type LogLayout, type TreeReader } from "@nikovirtala/ledger";
+import type { AdrConfig } from "./config.js";
+import { type DecisionView } from "./kind.js";
+import { type DecisionLog } from "./log.js";
+import type { WriteOptions } from "./write.js";
+/** `adr index --json` (design 2b §4.5). */
+export interface IndexResultJson {
+    readonly format: "adr-index/v1";
+    /** The index file, repo-relative: `<root>/index.md`. */
+    readonly path: string;
+    readonly check: boolean;
+    /**
+     * `--check`: no finding. Otherwise: the copies the command compares (the work tree and the
+     * index, or HEAD's when committing) already held the render.
+     */
+    readonly fresh: boolean;
+    /** Repo-relative paths this command wrote. */
+    readonly written: readonly string[];
+    readonly commit: string | null;
+    /** `--check`'s findings; `[]` otherwise. */
+    readonly findings: readonly Finding[];
+    readonly notes: readonly string[];
+}
+/**
+ * What the recovery hint says about rerunning `adr index --commit` after `git commit` failed
+ * (design 2b D5). It names the file, not the path, which the hint lists above it.
+ */
+export declare const INDEX_RERUN = "You can also run adr index --commit again once git accepts the commit; it commits index.md while it differs from HEAD's.";
+/**
+ * The step before the manual commit when a write's second index render failed after staging
+ * (design 2b §4.5 step 4).
+ */
+export declare const INDEX_BEFORE: (root: string) => string;
+/**
+ * The step after the manual commit when the commit carried the index: the commit's render leaves
+ * out other decisions' uncommitted entries (design 2b D5, §4.5 step 5).
+ */
+export declare const INDEX_AFTER: (root: string) => string;
+/** The repo-relative path of a log's generated index. */
+export declare const indexPath: (layout: LogLayout) => string;
+/**
+ * adr's index spec (01:209: active decisions first), built per render so that a superseded
+ * decision's status can name its successor's display from `views`.
+ */
+export declare const DECISION_INDEX: (root: string, views: ReadonlyMap<string, DecisionView>) => IndexSpec<DecisionView>;
+/**
+ * The index `tree` must hold: its decisions, numbered as they will be once the commit holding
+ * `tree` (which builds on `history`: HEAD, a commit, or null on an unborn HEAD) is on main
+ * (design 2b D2), with `[log] main_branch`'s numbers first. A tree that isn't a commit's (the work
+ * tree, the index) also merges `MERGE_HEAD` while a merge is in progress. In a shallow clone the
+ * numbers continue from those `history`'s index recorded; `null` when there are none, so the
+ * numbers can't be projected.
+ */
+export declare function renderDecisionIndex(git: Git, o: {
+    readonly layout: LogLayout;
+    readonly adr: AdrConfig;
+    readonly tree: TreeReader;
+    readonly history: string | null;
+}): Promise<string | null>;
+/**
+ * What the unstaged-files `index/stale` finding and the matching write note both start with:
+ * `path` lists `files` (some of them), which aren't staged.
+ */
+export declare function unstagedIndexText(path: string, files: readonly string[]): string;
+/**
+ * The log's event and body files whose work-tree content isn't staged (untracked or modified),
+ * sorted: the cause of a staged `index.md` that only the work tree's render matches.
+ */
+export declare function unstagedLogFiles(git: Git, layout: LogLayout): Promise<string[]>;
+/**
+ * The verify check that `<root>/index.md` is current (design 2b §4.5, "Freshness in verify"). In
+ * staged mode (the pre-commit hook), a stale staged copy that equals the work tree's render
+ * means another decision's files aren't staged: writes stage the work tree's render (D2), and
+ * `adr index` would change nothing. The finding then names those files and says to stage them.
+ */
+export declare function decisionIndexCheck(log: DecisionLog): Check;
+/** Whether `bytes` (null: absent) hold exactly `text`. */
+export declare function holdsText(bytes: Uint8Array | null, text: string): boolean;
+/** HEAD's copy of `path`; `null` when it is absent or HEAD is unborn. */
+export declare function headBytes(git: Git, path: string): Promise<Uint8Array | null>;
+/** HEAD's tree, or an empty tree on an unborn HEAD. */
+export declare function headTree(git: Git, head: string | null): Promise<TreeReader>;
+/**
+ * Brings the work-tree copy of `path` to `text` (atomically, when it differs) and reports whether
+ * the staged copy differs, so the caller stages it. `old` is the work-tree copy before the write
+ * (`null` when absent), for rollback.
+ */
+export declare function writeIndexCopy(git: Git, path: string, text: string): Promise<{
+    readonly wrote: boolean;
+    readonly old: Uint8Array | null;
+    readonly stage: boolean;
+}>;
+/** The first line of an error's message, for notes and headlines. */
+export declare const firstLine: (err: unknown) => string;
+/** `adr index`'s result and whether the work-tree refresh after a commit changed a copy. */
+export interface IndexRun {
+    readonly doc: IndexResultJson;
+    /** With a commit requested: step 5 wrote or staged the work tree's render. */
+    readonly refreshed: boolean;
+}
+/**
+ * `adr index` (design 2b §4.5) with what the text output needs; `indexDecisionLog` is the
+ * library entry.
+ */
+export declare function runDecisionIndex(log: DecisionLog, o?: WriteOptions & {
+    readonly check?: boolean;
+}): Promise<IndexRun>;
+/**
+ * `adr index [--check] [--commit | --no-commit] [-m <message>]` (design 2b §4.5): renders
+ * `<root>/index.md` and writes and stages it where the work tree or the index differ. With
+ * `commit` (default `[policy] auto_commit`) it renders HEAD's tree and commits the file alone when
+ * HEAD's copy differs, then refreshes the work tree's copy, which may include other decisions'
+ * uncommitted entries. `check` writes nothing and reports `index/*` findings.
+ */
+export declare function indexDecisionLog(log: DecisionLog, o?: WriteOptions & {
+    readonly check?: boolean;
+}): Promise<IndexResultJson>;

package/dist/types/log.d.ts

@@ -33,8 +33,15 @@ export interface DecisionsRead {
     /** How the log was located (`ToolLog.notes`); `[]` for a MemoryTree read. */
     readonly notes: readonly string[];
 }
-/** `numberLog` on the repository, then `readDecisionsFrom(log.tree, …)`. */
+/**
+ * `numberLog` on the repository, then `readDecisionsFrom(log.tree, …)`. In a shallow clone of a
+ * log with `[log] index = "committed"`, the numbers come from `<root>/index.md` in the commit
+ * being read (`--ref`, else HEAD, resolved when the numbers are needed), never from the work tree's
+ * copy, which may number acceptances that exist only there (design 2b D1, §4.6).
+ */
 export declare function readDecisions(log: DecisionLog): Promise<DecisionsRead>;
+/** The display numbers `readDecisions` uses, with its shallow-clone fallback to `index.md`. */
+export declare function numberDecisions(log: DecisionLog): Promise<Numbering>;
 /** The git-free core of `readDecisions`; tests pass a MemoryTree and a hand-made `Numbering`. */
 export declare function readDecisionsFrom(tree: TreeReader, o: {
     readonly layout: LogLayout;
@@ -44,6 +51,13 @@ export declare function readDecisionsFrom(tree: TreeReader, o: {
     readonly commit?: string | null;
     readonly notes?: readonly string[];
 }): Promise<DecisionsRead>;
+/**
+ * The note a read command adds about where numbers come from: the shallow-clone index, or why
+ * they are unavailable (`unavailable: false` leaves that one out); `null` for none.
+ */
+export declare function numberingNote(read: DecisionsRead, o: {
+    readonly unavailable: boolean;
+}): string | null;
 /** Why numbers are unavailable, in words: `shallow clone` or `no main branch`. */
 export declare function unavailableReason(n: Numbering): string;
 /**
@@ -51,3 +65,22 @@ export declare function unavailableReason(n: Numbering): string;
  * Throws `UsageError` (exit 2) naming the reason when it names nothing.
  */
 export declare function resolveDecision(read: DecisionsRead, input: string): string;
+/** The `since` key of `adr list --since <rev>` (design 2b D7). */
+export interface ChangedSince {
+    /** The revision as given, such as `ORIG_HEAD`. */
+    readonly rev: string;
+    readonly commit: string;
+    /** Event files added since `rev`, sorted by path. */
+    readonly events: readonly {
+        readonly subject: string;
+        readonly type: string;
+        readonly path: string;
+    }[];
+}
+/**
+ * The event files in `--ref`'s tree (else HEAD's) that `rev`'s tree lacks (design 2b D7). Diffing
+ * trees answers "what did this pull bring" for fast-forwards and merges (`ORIG_HEAD` is the tip
+ * before them), and lists nothing for a rebase of your own work, whose events are in both trees.
+ * Throws `RefNotFoundError` when either revision doesn't resolve.
+ */
+export declare function changedSince(log: DecisionLog, rev: string): Promise<ChangedSince>;

package/dist/types/scope.d.ts

@@ -0,0 +1,51 @@
+import { type Finding, type ScopeVia } from "@nikovirtala/ledger";
+import type { DecisionStatus } from "./kind.js";
+import type { DecisionLog, DecisionsRead } from "./log.js";
+import { type NumberingJson } from "./views.js";
+/** One decision that governs a path in `adr-for/v1` (design §6.9). */
+export interface DecisionForJson {
+    readonly id: string;
+    readonly display: string;
+    readonly title: string;
+    readonly status: DecisionStatus;
+    readonly effective: string | null;
+    /** What to know before applying it: superseded, deprecated, never in force; `null` if nothing. */
+    readonly warning: string | null;
+    /** The globs that matched, then the anchor lines. */
+    readonly via: readonly ScopeVia[];
+}
+/** An anchor naming no decision of this log. */
+export interface UnresolvedAnchorJson {
+    /** The id, or `<source>:<id>` for a qualified anchor. */
+    readonly ref: string;
+    readonly line: number;
+    readonly reason: "not-found" | "other-log";
+}
+/** `adr for <path>… --json` (design §6.9). */
+export interface DecisionsForJson {
+    readonly format: "adr-for/v1";
+    readonly root: string;
+    readonly ref: string | null;
+    readonly commit: string | null;
+    readonly numbering: NumberingJson;
+    readonly paths: readonly {
+        readonly path: string;
+        /** In the index, or in the `--ref` tree. */
+        readonly tracked: boolean;
+        readonly decisions: readonly DecisionForJson[];
+        readonly unresolved: readonly UnresolvedAnchorJson[];
+    }[];
+    /** The read's findings of the listed decisions and of the log as a whole. */
+    readonly findings: readonly Finding[];
+    readonly notes: readonly string[];
+}
+/**
+ * Which decisions govern each path (design §6.9): globs of decisions that were ever in force, and
+ * comment anchors of any decision, read from the work tree or, with a `--ref` log, that commit.
+ * Paths are relative to `o.cwd` (default the repository root); directories and paths outside the
+ * repository are `UsageError`s. Paths need not be tracked.
+ */
+export declare function decisionsFor(read: DecisionsRead, log: DecisionLog, o: {
+    readonly paths: readonly string[];
+    readonly cwd?: string;
+}): Promise<DecisionsForJson>;

package/dist/types/verify.d.ts

@@ -1,9 +1,11 @@
 import { type Check, type Finding, type VerifyMode } from "@nikovirtala/ledger";
-import type { DecisionLog } from "./log.js";
+import { type DecisionLog } from "./log.js";
 /**
- * Every phase-1 check for the log: ledger's mechanical and fold checks with adr's actor policy,
- * and template lint against the templates in the head tree and, for older versions, the history
- * of `historyRef`.
+ * Every check for the log: ledger's mechanical and fold checks with adr's actor policy, template
+ * lint against the templates in the head tree and, for older versions, the history of
+ * `historyRef`, the scope-glob and anchor checks, and the decision checks over code
+ * (`decision/governed-by-inactive`, `decision/scope-narrowed`). With `[log] index = "committed"`,
+ * also the freshness of `<root>/index.md`.
  */
 export declare function adrChecks(log: DecisionLog, historyRef: string | null): readonly Check[];
 /** Verifies the decision log in `mode` (staged, range or full) with `adrChecks`. */

package/dist/types/views.d.ts

@@ -1,10 +1,10 @@
 import { type EventEnvelope, type Finding, type StateHeader } from "@nikovirtala/ledger";
 import type { DecisionStatus, DecisionView } from "./kind.js";
-import type { DecisionsRead } from "./log.js";
+import type { ChangedSince, DecisionsRead } from "./log.js";
 /** The `numbering` key of the read documents. */
 export interface NumberingJson {
     readonly available: boolean;
-    readonly reason: "shallow" | "no-main-ref" | null;
+    readonly reason: "shallow" | "no-main-ref" | "index" | null;
     readonly ref: string | null;
 }
 /** `adr list --json` (design §5.5). */
@@ -15,6 +15,8 @@ export interface DecisionListJson {
     readonly commit: string | null;
     readonly numbering: NumberingJson;
     readonly decisions: readonly DecisionView[];
+    /** With `--since <rev>`: the event files added since `rev`; `null` without it. */
+    readonly since: ChangedSince | null;
     /** Newer envelope or schema versions; upgrade adr. */
     readonly unreadable: readonly string[];
     /** First event not `proposed`, or a body with no events; run adr verify. */
@@ -37,12 +39,16 @@ export interface DecisionShowJson {
     readonly findings: readonly Finding[];
     readonly notes: readonly string[];
 }
+/** The `numbering` key of `adr-list/v1`, `adr-show/v1` and `adr-for/v1`. */
+export declare const numberingJson: (read: DecisionsRead) => NumberingJson;
 /**
- * The `adr-list/v1` document: decisions in list order, filtered by `status` and truncated to
+ * The `adr-list/v1` document: decisions in list order, filtered by `status` and by `since` (only
+ * the decisions with event files added since its revision, from `changedSince`), and truncated to
  * `limit` after ordering. `findings` are those of the listed decisions and of the log as a whole.
  */
 export declare function listDecisions(read: DecisionsRead, o?: {
     readonly status?: readonly DecisionStatus[];
+    readonly since?: ChangedSince | null;
     readonly limit?: number;
 }): DecisionListJson;
 /**