@nikovirtala/adr 0.1.0 → 0.2.0

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/views.d.ts

@@ -37,6 +37,8 @@ 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
  * `limit` after ordering. `findings` are those of the listed decisions and of the log as a whole.

package/dist/types/write.d.ts

@@ -1,10 +1,10 @@
-import { type Actor, type EventEnvelope, type Finding, type Template, type TemplateSource, type Trailer } from "@nikovirtala/ledger";
+import { type Actor, type EventEnvelope, type Finding, type SetOp, type Template, type TemplateSource, type Trailer } from "@nikovirtala/ledger";
 import { type DecisionView } from "./kind.js";
 import { type DecisionLog, type DecisionsRead } from "./log.js";
-/** `adr new|accept|supersede --json` (design §5.5). */
+/** `adr <write command> --json` (design §5.5, §6.1). */
 export interface WriteResultJson {
     readonly format: "adr-write/v1";
-    readonly command: "new" | "accept" | "supersede";
+    readonly command: "new" | "accept" | "supersede" | "reject" | "withdraw" | "deprecate" | "note" | "link" | "scope";
     readonly ok: boolean;
     /**
      * The decision after the write; before it when `ok` is false (`null` for a refused `new`).
@@ -19,9 +19,21 @@ export interface WriteResultJson {
     readonly commit: string | null;
     /** Refusal findings when `ok` is false; the draft's template lint for `new` (informational). */
     readonly findings: readonly Finding[];
-    /** How the log was located (`ToolLog.notes`). */
+    /**
+     * How the log was located (`ToolLog.notes`), then the caller's notes (attribution), then the
+     * write's own (a shortened commit subject, …).
+     */
     readonly notes: readonly string[];
 }
+/** What every write function takes besides its input (design §6.1). */
+export interface WriteOptions {
+    /** Commit the write; default `[policy] auto_commit`. */
+    readonly commit?: boolean;
+    /** The commit message to use instead of the `[commit] subject` one; used only when committing. */
+    readonly message?: string | null;
+    /** Notes to report before the write's own, such as the attribution notes. */
+    readonly notes?: readonly string[];
+}
 export interface ProposeInput {
     readonly title: string;
     /** Default `[log] default_template`. */
@@ -64,15 +76,32 @@ export interface WritePlan {
         readonly rendered: Uint8Array;
         readonly template: Template;
     } | null;
-    /** The D6 commit message. */
-    readonly message: string;
+    /** What the commit message is made of; `write()` renders it with `[commit] subject`. */
+    readonly commit: CommitParts | null;
     /** One `ADR`/`ADR-Event` pair per plan event, in write order. */
     readonly trailers: readonly Trailer[];
     /** Views after the write, computed on `overlayTree(read.tree, files)`. */
-    readonly decision: DecisionView;
+    readonly decision: DecisionView | null;
     readonly affected: readonly DecisionView[];
     /** Informational (new: the draft's template lint). */
     readonly findings: readonly Finding[];
+    /** The write's own notes for the result (an already existing link, …). */
+    readonly notes?: readonly string[];
+}
+/** The parts of a commit message (design §4.3): the template's variables and the body. */
+export interface CommitParts {
+    /** `{action}`, the verb phrase, e.g. `propose to` or `set the scope of`. */
+    readonly action: string;
+    /**
+     * The text after `{action}`, which `{title}` and `{raw_title}` come from: the decision's title
+     * as recorded for propose, accept, reject and withdraw, else its display (`ADR-0006`, or
+     * `ADR-0006 with ADR-0007` for supersede).
+     */
+    readonly title: string;
+    readonly id: string;
+    readonly display: string;
+    /** Body paragraphs, each wrapped at 72. */
+    readonly body: readonly string[];
 }
 export type PlanResult = {
     readonly ok: true;
@@ -82,13 +111,42 @@ export type PlanResult = {
     readonly decision: DecisionView | null;
     readonly findings: readonly Finding[];
 };
-/** Plans `adr new`: a rendered body, a materialized template if needed, and `proposed`. */
-export declare function planPropose(read: DecisionsRead, input: ProposeInput, c: PlanContext): Promise<PlanResult>;
+/**
+ * Plans `adr new`: a rendered body, a materialized template if needed, and `proposed`. With
+ * `refuseIncomplete` (a commit with no editor to fill the draft in, design §7.2), a draft that
+ * fails the template lint is refused with those findings before any file is planned.
+ */
+export declare function planPropose(read: DecisionsRead, input: ProposeInput, c: PlanContext, o?: {
+    readonly refuseIncomplete?: boolean;
+}): Promise<PlanResult>;
 /** Plans `adr accept`: `accepted` with the body hash, and `superseded` on each declared target. */
 export declare function planAccept(read: DecisionsRead, input: {
     readonly id: string;
     readonly actor: Actor;
-}, c: PlanContext): Promise<PlanResult>;
+}, c: PlanContext, o?: {
+    readonly copyGlobs?: readonly string[];
+}): Promise<PlanResult>;
+/** The scope an `accept` can copy from the decisions it supersedes (design §6.10). */
+export interface ScopeOffer {
+    /** The decision being accepted. */
+    readonly id: string;
+    /** The superseded decisions with globs the accepted one lacks, sorted by id. */
+    readonly sources: readonly string[];
+    /** Their displays (`ADR-0002`, or the id), in `sources` order. */
+    readonly displays: readonly string[];
+    /** The globs to add: the union of their scopes minus the accepted decision's own, sorted. */
+    readonly globs: readonly string[];
+}
+/**
+ * Whether `accept` copies the superseded decisions' scope: always, never, never but with a note
+ * naming the `adr scope` command that would (the default), or as a function decides.
+ */
+export type CopyScope = "copy" | "skip" | "suggest" | ((offer: ScopeOffer) => Promise<boolean>);
+/**
+ * What accepting `id` could copy: the declared targets it will supersede (accepted or
+ * deprecated, as `planAccept` selects them) and the globs of theirs it doesn't have yet.
+ */
+export declare function scopeToCopy(read: DecisionsRead, id: string): ScopeOffer;
 /** Plans `adr supersede <id> --by <by>`: one `superseded` event on `id`. */
 export declare function planSupersede(read: DecisionsRead, input: {
     readonly id: string;
@@ -107,6 +165,63 @@ export declare function planEvent(read: DecisionsRead, input: {
     readonly reason?: string | null;
     readonly actor: Actor;
 }, c: PlanContext): Promise<PlanResult>;
+/** Input of the lifecycle exits: the decision and the envelope's `reason`. */
+export interface ReasonInput {
+    readonly id: string;
+    readonly reason?: string | null;
+    readonly actor: Actor;
+}
+/** Plans `adr reject`: `rejected` with its required reason, while proposed. */
+export declare function planReject(read: DecisionsRead, input: ReasonInput, c: PlanContext): Promise<PlanResult>;
+/** Plans `adr withdraw`: `withdrawn`, with a reason when given, while proposed. */
+export declare function planWithdraw(read: DecisionsRead, input: ReasonInput, c: PlanContext): Promise<PlanResult>;
+/** Plans `adr deprecate`: `deprecated` with its required reason, while accepted. */
+export declare function planDeprecate(read: DecisionsRead, input: ReasonInput, c: PlanContext): Promise<PlanResult>;
+/** Plans `adr note`: `noted` with the text as given, in every state. */
+export declare function planNote(read: DecisionsRead, input: {
+    readonly id: string;
+    readonly text: string;
+    readonly actor: Actor;
+}, c: PlanContext): Promise<PlanResult>;
+export interface LinkInput {
+    readonly id: string;
+    /** A local id or number, or `<source>:<id>` naming a configured `[[sources]]` entry. */
+    readonly to: string;
+    /** Default `relates-to`. */
+    readonly rel?: string;
+    readonly actor: Actor;
+}
+/**
+ * Plans `adr link` (design §6.7): `linked` in every state. A qualified target must name one of
+ * `o.sources` (the log's `[[sources]]` names); it isn't looked up in the other log. A link that
+ * already exists plans nothing, with a note.
+ */
+export declare function planLink(read: DecisionsRead, input: LinkInput, c: PlanContext, o?: {
+    readonly sources?: readonly string[];
+}): Promise<PlanResult>;
+export interface ScopeInput {
+    readonly id: string;
+    /** Replace (`set`, `[]` clears), or `add` and `remove` globs (design §3.2). */
+    readonly op: SetOp;
+    readonly actor: Actor;
+    /** How the caller names `set`, `add`, `remove` and `clear` in messages; default the field names. */
+    readonly names?: {
+        readonly set: string;
+        readonly add: string;
+        readonly remove: string;
+        readonly clear?: string;
+    };
+}
+/**
+ * Plans `adr scope` with a set operation (design §6.8): one `scoped` event with the whole new set
+ * while proposed, accepted or deprecated, or nothing when the set doesn't change. Invalid globs,
+ * conflicting operations and more than 200 globs are `UsageError`s. Notes name removed globs that
+ * weren't there, added ones that were, resulting globs matching none of `o.tracked` (when given)
+ * and a narrowed accepted scope.
+ */
+export declare function planScope(read: DecisionsRead, input: ScopeInput, c: PlanContext, o?: {
+    readonly tracked?: readonly string[];
+}): Promise<PlanResult>;
 /** What the editor step decided (§5.4 step 4a). */
 export interface AfterStage {
     /** Draft lint findings to report instead of `plan.findings`; `null` keeps `plan.findings`. */
@@ -121,6 +236,10 @@ export interface AfterStage {
  */
 export declare function applyPlan(log: DecisionLog, plan: WritePlan, o: {
     readonly commit: boolean;
+    /** The commit message, without trailers; required when committing. */
+    readonly message?: string;
+    /** `message` is the user's own: append the trailers to its own trailer block, if it ends in one. */
+    readonly mergeTrailers?: boolean;
     readonly afterStage?: () => Promise<AfterStage>;
 }): Promise<{
     written: string[];
@@ -144,21 +263,25 @@ export interface WriteDeps {
  * body path. It resolves to `null` when the editor exited 0, else to a note for the user (spawn
  * error, exit status). `onNote` receives the notes about a skipped commit or a removed body,
  * without the "not committed: " prefix the CLI adds when a commit was requested.
+ *
+ * A draft with unfilled sections is never committed (design §7.2): without `edit` a commit is
+ * refused (`ok: false`, nothing written); after `edit` the commit is skipped with a note.
  */
-export declare function proposeDecision(log: DecisionLog, input: ProposeInput, o?: {
-    readonly commit?: boolean;
+export declare function proposeDecision(log: DecisionLog, input: ProposeInput, o?: WriteOptions & {
     readonly edit?: (absBodyPath: string) => Promise<string | null>;
     readonly onNote?: (note: string) => void;
 }, deps?: WriteDeps): Promise<WriteResultJson>;
 /**
  * `adr accept`: lints the draft, hashes the body, writes `accepted` and a `superseded` event on
- * each declared target, stages them with the body, and commits with `commit`.
+ * each declared target, stages them with the body, and commits with `commit`. When the targets
+ * have globs the decision lacks, `copyScope` decides whether a `scoped` event copies them
+ * (default `"suggest"`: no copy, and a note with the `adr scope` command that would).
  */
 export declare function acceptDecision(log: DecisionLog, input: {
     readonly id: string;
     readonly actor: Actor;
-}, o?: {
-    readonly commit?: boolean;
+}, o?: WriteOptions & {
+    readonly copyScope?: CopyScope;
 }, deps?: WriteDeps): Promise<WriteResultJson>;
 /** `adr supersede <id> --by <by>`: writes `superseded`, stages it, and commits with `commit`. */
 export declare function supersedeDecision(log: DecisionLog, input: {
@@ -166,6 +289,45 @@ export declare function supersedeDecision(log: DecisionLog, input: {
     readonly by: string;
     readonly reason?: string | null;
     readonly actor: Actor;
-}, o?: {
-    readonly commit?: boolean;
+}, o?: WriteOptions, deps?: WriteDeps): Promise<WriteResultJson>;
+/**
+ * `adr reject <id> --reason <text>`: writes `rejected`, stages it, and commits with `commit`. The
+ * kind requires the reason; without one the write is refused (findings, nothing written).
+ */
+export declare function rejectDecision(log: DecisionLog, input: ReasonInput, o?: WriteOptions, deps?: WriteDeps): Promise<WriteResultJson>;
+/** `adr withdraw <id> [--reason <text>]`: writes `withdrawn`, stages it, and commits with `commit`. */
+export declare function withdrawDecision(log: DecisionLog, input: ReasonInput, o?: WriteOptions, deps?: WriteDeps): Promise<WriteResultJson>;
+/**
+ * `adr deprecate <id> --reason <text>`: writes `deprecated`, stages it, and commits with `commit`.
+ * The kind requires the reason, as for `rejectDecision`.
+ */
+export declare function deprecateDecision(log: DecisionLog, input: ReasonInput, o?: WriteOptions, deps?: WriteDeps): Promise<WriteResultJson>;
+/** `adr note <id> <text>`: writes `noted`, stages it, and commits with `commit`. */
+export declare function noteDecision(log: DecisionLog, input: {
+    readonly id: string;
+    readonly text: string;
+    readonly actor: Actor;
+}, o?: WriteOptions, deps?: WriteDeps): Promise<WriteResultJson>;
+/**
+ * `adr link <id> <target> [--rel <rel>]`: writes `linked`, stages it, and commits with `commit`.
+ * Qualified targets name the log's `[[sources]]`; a link that exists already writes nothing.
+ */
+export declare function linkDecision(log: DecisionLog, input: LinkInput, o?: WriteOptions, deps?: WriteDeps): Promise<WriteResultJson>;
+/**
+ * `adr scope <id> --set|--add|--remove …`: writes one `scoped` event with the new set, stages it,
+ * and commits with `commit`. An unchanged set writes nothing.
+ */
+export declare function scopeDecision(log: DecisionLog, input: ScopeInput, o?: WriteOptions, deps?: WriteDeps): Promise<WriteResultJson>;
+/**
+ * `adr scope [<decision>] --follow-renames` (design §6.8): rewrites the scope globs of the given
+ * decision, or of every decision, after the renames staged against `HEAD`, and stages one
+ * `scoped` event per changed decision. It never commits, whatever `[policy] auto_commit` says
+ * (the events belong in the commit with the renames), so `o.commit: true` and a message are
+ * `InvalidArgumentError`s. `dryRun` plans the same events and notes without writing anything.
+ */
+export declare function followScopeRenames(log: DecisionLog, input: {
+    readonly id?: string;
+    readonly actor: Actor;
+}, o?: WriteOptions & {
+    readonly dryRun?: boolean;
 }, deps?: WriteDeps): Promise<WriteResultJson>;