@nikovirtala/adr 0.0.0 → 0.2.0

package/dist/types/views.d.ts

@@ -0,0 +1,65 @@
+import { type EventEnvelope, type Finding, type StateHeader } from "@nikovirtala/ledger";
+import type { DecisionStatus, DecisionView } from "./kind.js";
+import type { 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 ref: string | null;
+}
+/** `adr list --json` (design §5.5). */
+export interface DecisionListJson {
+    readonly format: "adr-list/v1";
+    readonly root: string;
+    readonly ref: string | null;
+    readonly commit: string | null;
+    readonly numbering: NumberingJson;
+    readonly decisions: readonly DecisionView[];
+    /** Newer envelope or schema versions; upgrade adr. */
+    readonly unreadable: readonly string[];
+    /** First event not `proposed`, or a body with no events; run adr verify. */
+    readonly unfoldable: readonly string[];
+    readonly findings: readonly Finding[];
+    readonly notes: readonly string[];
+}
+/** `adr show <decision> --json` (design §5.5). */
+export interface DecisionShowJson {
+    readonly format: "adr-show/v1";
+    readonly root: string;
+    readonly ref: string | null;
+    readonly commit: string | null;
+    readonly numbering: NumberingJson;
+    readonly header: StateHeader;
+    readonly decision: DecisionView;
+    readonly body: string | null;
+    /** Every valid event in fold order with `history`, else `null`. */
+    readonly events: readonly EventEnvelope[] | null;
+    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.
+ */
+export declare function listDecisions(read: DecisionsRead, o?: {
+    readonly status?: readonly DecisionStatus[];
+    readonly limit?: number;
+}): DecisionListJson;
+/**
+ * The `adr-show/v1` document of the decision `id` (resolve it with `resolveDecision` first).
+ * Throws `UsageError` for an unknown, unreadable or unfoldable decision.
+ */
+export declare function showDecision(read: DecisionsRead, id: string, o?: {
+    readonly history?: boolean;
+}): Promise<DecisionShowJson>;
+/**
+ * The state header (01:258–259): `<display> (<id>) · <status>`, and for a decision that isn't in
+ * force a warning saying what to read instead. `refer` names where to read another decision. CLI
+ * default: `display(id)`. Phase 3 MCP passes `id => "adr://decision/" + display(id)`, e.g.
+ * `adr://decision/ADR-0012`, or the id when unnumbered.
+ */
+export declare function stateHeader(view: DecisionView, read: DecisionsRead, o?: {
+    readonly refer?: (id: string) => string;
+}): StateHeader;

package/dist/types/write.d.ts

@@ -0,0 +1,333 @@
+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 <write command> --json` (design §5.5, §6.1). */
+export interface WriteResultJson {
+    readonly format: "adr-write/v1";
+    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`).
+     * After a commit it is read again from the log, so an acceptance committed on the main ref
+     * carries its number; otherwise `number` is `null` until the acceptance lands on main.
+     */
+    readonly decision: DecisionView | null;
+    /** Each decision superseded by this write, after it (read again after a commit, like `decision`). */
+    readonly affected: readonly DecisionView[];
+    /** Repo-relative paths this command wrote, in write order. */
+    readonly written: readonly string[];
+    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`), 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`. */
+    readonly template?: string;
+    /** Section id → markdown. */
+    readonly sections?: Readonly<Record<string, string>>;
+    /** Decisions this one is meant to replace, as ids or numbers. */
+    readonly supersedes?: readonly string[];
+    readonly actor: Actor;
+}
+/** What a plan needs besides the read: a clock, randomness and templates. */
+export interface PlanContext {
+    /** Clock for `nextEventIdentity`. */
+    readonly now: () => number;
+    /** ULID and subject-id randomness. */
+    readonly random?: (buf: Uint8Array) => void;
+    /** Drafts' recorded template versions. */
+    readonly templates: TemplateSource;
+    /** Built-in template texts by name (§5.7), for `new`. */
+    readonly builtins: Readonly<Record<string, string>>;
+}
+/** Everything one write command does, computed without touching git or the disk. */
+export interface WritePlan {
+    readonly command: "new" | "accept" | "supersede" | "event";
+    readonly subject: string;
+    /** New files, repo-relative path → bytes, in write order: body, materialized template, events. */
+    readonly files: Readonly<Record<string, Uint8Array>>;
+    readonly events: readonly EventEnvelope[];
+    /** Paths to stage: every new file, plus the existing body for accept. */
+    readonly stage: readonly string[];
+    /** Subject ids involved (D6): the subject, every superseded target, and `by` for supersede. Sorted. */
+    readonly involved: readonly string[];
+    /** Per involved subject: its body, its events dir and its recorded template. Sorted, deduplicated. */
+    readonly commitScope: readonly string[];
+    /** The events directories in `commitScope`, sorted; the rest of `commitScope` are file paths. */
+    readonly eventDirs: readonly string[];
+    /** For new: the body path, the rendered bytes and the template, for the editor step. */
+    readonly draft: {
+        readonly path: string;
+        readonly rendered: Uint8Array;
+        readonly template: Template;
+    } | null;
+    /** 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 | 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;
+    readonly plan: WritePlan;
+} | {
+    readonly ok: false;
+    readonly decision: DecisionView | null;
+    readonly findings: readonly Finding[];
+};
+/**
+ * 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, 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;
+    readonly by: string;
+    readonly reason?: string | null;
+    readonly actor: Actor;
+}, c: PlanContext): Promise<PlanResult>;
+/**
+ * Plans any one event on an existing decision: the state machine and the event's validation
+ * decide, then the precheck. Phase 2's reject, withdraw, deprecate, note, link and scope wrap it.
+ */
+export declare function planEvent(read: DecisionsRead, input: {
+    readonly subject: string;
+    readonly type: string;
+    readonly data: Record<string, unknown>;
+    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`. */
+    readonly findings: readonly Finding[] | null;
+    /** `false` skips the commit: the files stay written and staged, and `commit` is `null`. */
+    readonly commit: boolean;
+}
+/**
+ * Applies a plan (§5.4): refuses a commit whose scope has unstaged or needed untracked paths,
+ * writes the files (removing them again if a write fails), stages them, runs `afterStage`, and
+ * commits `plan.stage` plus the involved subjects' already-staged files with exact trailers.
+ */
+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[];
+    commit: string | null;
+    findings: readonly Finding[];
+}>;
+/**
+ * The clock, the randomness and `applyPlan` the write functions use. Only tests pass their own
+ * (for example an `apply` that fails once); the default is the real ones.
+ */
+export interface WriteDeps {
+    readonly now: () => number;
+    readonly random?: (buf: Uint8Array) => void;
+    readonly apply: typeof applyPlan;
+}
+/**
+ * `adr new`: renders a draft, writes the body, any materialized template and the `proposed`
+ * event, stages them, and commits with `commit` (default `[policy] auto_commit`).
+ *
+ * `edit` (CLI only; MCP never passes it) runs between staging and committing, on the absolute
+ * 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?: 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`. 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?: 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: {
+    readonly id: string;
+    readonly by: string;
+    readonly reason?: string | null;
+    readonly actor: Actor;
+}, 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>;