adrien 0.0.1 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +5 -2
  2. package/dist/index.js +398 -88
  3. package/package.json +9 -2
package/README.md CHANGED
@@ -53,7 +53,7 @@ adrien init --agents # adds a block to AGENTS.md
53
53
  adrien for src/Invoices/Invoice.ts
54
54
  ```
55
55
 
56
- ```
56
+ ```text
57
57
  src/Invoices/Invoice.ts [billing-service]
58
58
  ADR-0007 BINDING Store invoices in Postgres
59
59
  rule: Invoices are read and written through the repository, never the document client.
@@ -72,7 +72,7 @@ Run from the code repo (or log repo). Any MCP client that speaks stdio works the
72
72
 
73
73
  ## Commands
74
74
 
75
- `init`, `new`, `list`, `show`, `search`, `for`, `check`, `accept`, `status`, `supersede`, `renumber`, `sync`, `mcp`.
75
+ `init`, `new`, `list`, `show`, `search`, `for`, `check`, `lint`, `export`, `accept`, `status`, `supersede`, `renumber`, `sync`, `mcp`.
76
76
  Run `adrien <command> --help`. Add `--json` for machine-readable output.
77
77
 
78
78
  ## Documentation
@@ -80,6 +80,9 @@ Run `adrien <command> --help`. Add `--json` for machine-readable output.
80
80
  The [format reference](https://github.com/moumine9/adrien/blob/main/docs/format.md) covers the ADR format, the config
81
81
  files, anchors, and how approval works.
82
82
 
83
+ Adrien keeps its own architecture decisions in
84
+ [`docs/decisions`](https://github.com/moumine9/adrien/tree/main/docs/decisions), and its CI runs `adrien check` on them.
85
+
83
86
  ## Status
84
87
 
85
88
  Early. The local core (format, CLI, MCP server) is what exists today. Next: a server and API, a web UI, and detection
package/dist/index.js CHANGED
@@ -2,7 +2,7 @@
2
2
  import { createRequire } from "node:module";
3
3
  import picomatch from "picomatch";
4
4
  import { basename, dirname, isAbsolute, join, posix, relative, resolve } from "node:path";
5
- import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
5
+ import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
6
6
  import { homedir } from "node:os";
7
7
  import YAML, { visit } from "yaml";
8
8
  import { z } from "zod";
@@ -38,9 +38,9 @@ function section$1(body, heading) {
38
38
  function firstParagraph(body) {
39
39
  return body.split(/\n\s*\n/).map((p) => p.trim()).find((p) => p && !p.startsWith("#")) ?? "";
40
40
  }
41
- /** Why an ADR exists, in a few lines: its Rationale, else its Decision, else its first paragraph. */
41
+ /** Why an ADR exists, in a few lines: its Rationale, else its Decision (or MADR's Decision Outcome), else its first paragraph. */
42
42
  function excerpt(adr, max = 600) {
43
- const text = section$1(adr.body, "Rationale") ?? section$1(adr.body, "Decision") ?? firstParagraph(adr.body);
43
+ const text = section$1(adr.body, "Rationale") ?? section$1(adr.body, "Decision Outcome") ?? section$1(adr.body, "Decision") ?? firstParagraph(adr.body);
44
44
  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
45
45
  }
46
46
  // ../core/src/errors.ts
@@ -79,6 +79,63 @@ function nextIdNumber(ids, fmt) {
79
79
  for (const id of ids) max = Math.max(max, idNumber(id, fmt) ?? 0);
80
80
  return max + 1;
81
81
  }
82
+ // ../core/src/model.ts
83
+ const STATUSES = [
84
+ "proposed",
85
+ "accepted",
86
+ "rejected",
87
+ "superseded",
88
+ "deprecated"
89
+ ];
90
+ /** Body skeletons `adrien new` can start from. `standard` is Adrien's own; `madr` follows MADR 4's section names. */
91
+ const TEMPLATE_NAMES = [
92
+ "standard",
93
+ "minimal",
94
+ "madr"
95
+ ];
96
+ const ORIGINS = [
97
+ "manual",
98
+ "agent",
99
+ "mined"
100
+ ];
101
+ /** The frontmatter keys Adrien owns, in the order they are written. */
102
+ const META_KEYS = [
103
+ "id",
104
+ "title",
105
+ "status",
106
+ "date",
107
+ "review_on",
108
+ "tags",
109
+ "components",
110
+ "code",
111
+ "review_rule",
112
+ "sources",
113
+ "supersedes",
114
+ "superseded_by",
115
+ "related",
116
+ "deciders",
117
+ "origin",
118
+ "contested"
119
+ ];
120
+ const stringList = z.array(z.string()).default([]);
121
+ const adrMetaSchema = z.object({
122
+ id: z.string().min(1),
123
+ title: z.string().min(1),
124
+ status: z.enum(STATUSES),
125
+ date: z.string().optional(),
126
+ review_on: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "must be a date like 2027-03-04").optional(),
127
+ tags: stringList,
128
+ components: stringList,
129
+ code: stringList,
130
+ review_rule: z.string().optional(),
131
+ sources: stringList,
132
+ supersedes: stringList,
133
+ superseded_by: z.string().optional(),
134
+ related: stringList,
135
+ deciders: stringList,
136
+ origin: z.enum(ORIGINS).default("manual"),
137
+ contested: z.boolean().default(false)
138
+ });
82
139
  // ../core/src/config.ts
83
140
  const CONFIG_FILE = "adrien.config.yaml";
84
141
  const CODE_CONFIG_FILE = ".adrien.yaml";
@@ -99,8 +156,10 @@ const logConfigSchema = z.strictObject({
99
156
  product: z.string().min(1),
100
157
  adr_dir: z.string().min(1).default("docs/adr"),
101
158
  id_format: z.string().default("ADR-{n:4}"),
159
+ template: z.enum(TEMPLATE_NAMES).default("standard"),
102
160
  tags: z.array(z.string().regex(ID, idMessage)).default([]),
103
- components: z.record(z.string(), componentDef).default({})
161
+ components: z.record(z.string(), componentDef).default({}),
162
+ lint: z.strictObject({ markdownlint: z.record(z.string(), z.unknown()).default({}) }).optional()
104
163
  });
105
164
  const codeRepoSchema = z.strictObject({
106
165
  log: z.string().min(1),
@@ -119,13 +178,23 @@ function validate(schema, data, file) {
119
178
  const issue = parsed.error.issues[0];
120
179
  throw new AdrienError("CONFIG_INVALID", `${file}: ${issue?.path.join(".") || "config"}: ${issue?.message}`);
121
180
  }
181
+ /** Parses and validates the text of an `adrien.config.yaml`; `label` names it in error messages. */
182
+ function parseLogConfigText(text, label) {
183
+ let data;
184
+ try {
185
+ data = YAML.parse(text) ?? {};
186
+ } catch (e) {
187
+ throw new AdrienError("CONFIG_INVALID", `${label}: invalid YAML (${e.message.split("\n")[0]})`);
188
+ }
189
+ const config = validate(logConfigSchema, data, label);
190
+ for (const id of Object.keys(config.components)) if (!ID.test(id)) throw new AdrienError("CONFIG_INVALID", `${label}: component "${id}" ${idMessage}`);
191
+ parseIdFormat(config.id_format);
192
+ return config;
193
+ }
122
194
  function loadLogConfig(logRoot) {
123
195
  const file = join(logRoot, CONFIG_FILE);
124
196
  if (!existsSync(file)) throw new AdrienError("CONFIG_NOT_FOUND", `No ${CONFIG_FILE} in ${logRoot}`);
125
- const config = validate(logConfigSchema, readYamlFile(file), file);
126
- for (const id of Object.keys(config.components)) if (!ID.test(id)) throw new AdrienError("CONFIG_INVALID", `${file}: component "${id}" ${idMessage}`);
127
- parseIdFormat(config.id_format);
128
- return config;
197
+ return parseLogConfigText(readFileSync(file, "utf8"), file);
129
198
  }
130
199
  function writeNew(file, data) {
131
200
  if (existsSync(file)) throw new AdrienError("CONFIG_EXISTS", `${file} already exists`);
@@ -151,55 +220,38 @@ function findUp(startDir, fileName) {
151
220
  dir = parent;
152
221
  }
153
222
  }
154
- // ../core/src/model.ts
155
- const STATUSES = [
156
- "proposed",
157
- "accepted",
158
- "rejected",
159
- "superseded",
160
- "deprecated"
161
- ];
162
- const ORIGINS = [
163
- "manual",
164
- "agent",
165
- "mined"
166
- ];
167
- /** The frontmatter keys Adrien owns, in the order they are written. */
168
- const META_KEYS = [
169
- "id",
170
- "title",
171
- "status",
172
- "date",
173
- "tags",
174
- "components",
175
- "code",
176
- "review_rule",
177
- "sources",
178
- "supersedes",
179
- "superseded_by",
180
- "related",
181
- "deciders",
182
- "origin",
183
- "contested"
184
- ];
185
- const stringList = z.array(z.string()).default([]);
186
- const adrMetaSchema = z.object({
187
- id: z.string().min(1),
188
- title: z.string().min(1),
189
- status: z.enum(STATUSES),
190
- date: z.string().optional(),
191
- tags: stringList,
192
- components: stringList,
193
- code: stringList,
194
- review_rule: z.string().optional(),
195
- sources: stringList,
196
- supersedes: stringList,
197
- superseded_by: z.string().optional(),
198
- related: stringList,
199
- deciders: stringList,
200
- origin: z.enum(ORIGINS).default("manual"),
201
- contested: z.boolean().default(false)
202
- });
223
+ // ../core/src/frontmatter.ts
224
+ const TEMPLATES = {
225
+ standard: [
226
+ ["## Context"],
227
+ ["## Considered options"],
228
+ ["## Decision"],
229
+ ["## Rationale"],
230
+ ["## Consequences"]
231
+ ],
232
+ minimal: [
233
+ ["## Context"],
234
+ ["## Decision"],
235
+ ["## Consequences"]
236
+ ],
237
+ madr: [
238
+ ["## Context and Problem Statement"],
239
+ ["## Decision Drivers"],
240
+ ["## Considered Options"],
241
+ [
242
+ "## Decision Outcome",
243
+ "### Consequences",
244
+ "### Confirmation"
245
+ ],
246
+ ["## Pros and Cons of the Options"],
247
+ ["## More Information"]
248
+ ]
249
+ };
250
+ /** An empty skeleton: the headings only, each followed by a blank line, so it lints clean until it is filled in. */
251
+ function bodyTemplate(name = "standard") {
252
+ return `\n${TEMPLATES[name].map((headings) => headings.join("\n\n")).join("\n\n")}\n`;
253
+ }
254
+ bodyTemplate("standard");
203
255
  const FRONTMATTER = /^---\n([\s\S]*?\n)?---[ \t]*(?:\n|$)/;
204
256
  const FILE_NUMBER = /^(?:ADR-)?(\d+)-/i;
205
257
  const metaKeys = new Set(META_KEYS);
@@ -302,6 +354,23 @@ function serializeAdr(adr) {
302
354
  flowCollectionPadding: false
303
355
  })}---\n${adr.body}`;
304
356
  }
357
+ // ../core/src/paths.ts
358
+ /**
359
+ * The physical path: symlinks, Windows 8.3 short names (`RUNNER~1`) and drive-letter case resolved. Git reports paths
360
+ * this way, so every path node compares with one of git's goes through here first.
361
+ */
362
+ function canonicalPath(path) {
363
+ try {
364
+ return realpathSync.native(path);
365
+ } catch {
366
+ return path;
367
+ }
368
+ }
369
+ /** True when `child` is `parent` or lies below it. */
370
+ function isInside(child, parent) {
371
+ const rel = relative(parent, child);
372
+ return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
373
+ }
305
374
  // ../core/src/slug.ts
306
375
  const MAX_SLUG = 60;
307
376
  function normalizeTitle(s) {
@@ -352,11 +421,30 @@ function adrFilePath(config, id, title, subdir) {
352
421
  const dir = posix.join(adrDir, toPosix(subdir ?? ""));
353
422
  const inside = posix.relative(adrDir, dir);
354
423
  if (inside === ".." || inside.startsWith("../")) throw new AdrienError("INVALID_INPUT", `--subdir "${subdir}" leaves the ADR directory (${config.adr_dir}).`);
355
- return posix.join(dir, `${id}-${slugify(title)}.md`);
424
+ const file = posix.join(dir, `${id}-${slugify(title)}.md`);
425
+ const filePart = posix.relative(adrDir, file);
426
+ if (filePart === ".." || filePart.startsWith("../")) throw new AdrienError("INVALID_INPUT", `The id "${id}" would place ${file} outside the ADR directory (${config.adr_dir}).`);
427
+ return file;
428
+ }
429
+ /** Refuses a destination that leaves the log, lexically or through a symlink (whether the file or a folder above it). */
430
+ function assertInsideLog(logRoot, file, adrPath) {
431
+ const root = canonicalPath(logRoot);
432
+ const outside = (where) => new AdrienError("INVALID_INPUT", `${adrPath} resolves outside the log (${where}); refusing to write it.`);
433
+ if (!isInside(file, logRoot)) throw outside(file);
434
+ if (lstatSync(file, { throwIfNoEntry: false })?.isSymbolicLink()) {
435
+ const real = canonicalPath(file);
436
+ if (real === file || !isInside(real, root)) throw outside(real);
437
+ return;
438
+ }
439
+ let probe = file;
440
+ while (!existsSync(probe) && dirname(probe) !== probe) probe = dirname(probe);
441
+ const real = canonicalPath(probe);
442
+ if (!isInside(real, root)) throw outside(real);
356
443
  }
357
444
  /** `exclusive` refuses to replace an existing file, so creating an ADR can never overwrite another one. */
358
445
  function writeAdr(logRoot, adr, opts = {}) {
359
446
  const file = join(logRoot, ...adr.path.split("/"));
447
+ assertInsideLog(logRoot, file, adr.path);
360
448
  mkdirSync(dirname(file), { recursive: true });
361
449
  try {
362
450
  writeFileSync(file, serializeAdr(adr), { flag: opts.exclusive ? "wx" : "w" });
@@ -384,7 +472,7 @@ async function git(cwd, args) {
384
472
  async function gitToplevel(dir) {
385
473
  if (!existsSync(dir)) return null;
386
474
  const out = await git(dir, ["rev-parse", "--show-toplevel"]);
387
- return out ? resolve(out.trim()) : null;
475
+ return out ? canonicalPath(resolve(out.trim())) : null;
388
476
  }
389
477
  async function isCommit(repoDir, ref) {
390
478
  return await git(repoDir, [
@@ -456,6 +544,10 @@ async function readTreeAtRef(repoDir, ref, subdir) {
456
544
  if (paths.length === 0) return [];
457
545
  return parseBatch(await catFileBatch(repoDir, paths.map((p) => `${ref}:${p}`)), paths);
458
546
  }
547
+ /** The text of one file at `ref`, or null when the ref or the file does not exist. */
548
+ async function readFileAtRef(repoDir, ref, path) {
549
+ return git(repoDir, ["show", `${ref}:${path}`]);
550
+ }
459
551
  async function remoteUrl(repoDir, remote = "origin") {
460
552
  return (await git(repoDir, [
461
553
  "remote",
@@ -563,10 +655,6 @@ async function locate(log, baseDir, env) {
563
655
  logSource: logRoot
564
656
  };
565
657
  }
566
- const isInside = (child, parent) => {
567
- const rel = relative(parent, child);
568
- return !rel.startsWith("..") && !isAbsolute(rel);
569
- };
570
658
  async function detectCodeRepo(cwd, logRoot, config) {
571
659
  const codeConfigDir = findUp(cwd, CODE_CONFIG_FILE);
572
660
  const root = codeConfigDir ?? await gitToplevel(cwd) ?? (isInside(cwd, logRoot) ? logRoot : null);
@@ -587,7 +675,7 @@ async function detectCodeRepo(cwd, logRoot, config) {
587
675
  }
588
676
  async function resolveContext(opts) {
589
677
  const env = opts.env ?? process.env;
590
- const cwd = resolve(opts.cwd);
678
+ const cwd = canonicalPath(resolve(opts.cwd));
591
679
  let located;
592
680
  if (opts.log) located = await locate(opts.log, cwd, env);
593
681
  else {
@@ -602,6 +690,10 @@ async function resolveContext(opts) {
602
690
  else if (codeConfig && codeConfigDir) located = await locate(codeConfig.log, codeConfigDir, env);
603
691
  else throw new AdrienError("CONFIG_NOT_FOUND", NOT_FOUND);
604
692
  }
693
+ located = {
694
+ ...located,
695
+ logRoot: canonicalPath(located.logRoot)
696
+ };
605
697
  const config = loadLogConfig(located.logRoot);
606
698
  return {
607
699
  cwd,
@@ -719,12 +811,22 @@ async function loadLogView(logRoot, config) {
719
811
  }
720
812
  const logFromTop = toPosix(relative(top, logRoot));
721
813
  const prefix = logFromTop ? `${logFromTop}/` : "";
722
- const adrDir = toPosix(relative(top, join(logRoot, config.adr_dir)));
814
+ const configAt = async (ref) => {
815
+ const text = await readFileAtRef(top, ref, `${prefix}${CONFIG_FILE}`);
816
+ if (text === null) return config;
817
+ try {
818
+ return parseLogConfigText(text, `${ref}:${prefix}${CONFIG_FILE}`);
819
+ } catch {
820
+ return config;
821
+ }
822
+ };
723
823
  const logAt = async (ref) => {
824
+ const atRef = await configAt(ref);
825
+ const adrDir = toPosix(relative(top, join(logRoot, atRef.adr_dir)));
724
826
  return parseLogFiles((await readTreeAtRef(top, ref, adrDir)).filter((f) => f.path.endsWith(".md")).map((f) => ({
725
827
  path: f.path.slice(prefix.length),
726
828
  text: f.text
727
- })), config);
829
+ })), atRef);
728
830
  };
729
831
  const atBase = await logAt(baseRef);
730
832
  const base = atBase.adrs;
@@ -736,11 +838,13 @@ async function loadLogView(logRoot, config) {
736
838
  baseRef
737
839
  ]))?.trim();
738
840
  const baseSha = (await git(top, ["rev-parse", baseRef]))?.trim();
841
+ const fork = forkPoint && forkPoint !== baseSha ? (await logAt(forkPoint)).adrs : base;
739
842
  return {
843
+ ...forkPoint ? {} : { forkUnresolved: true },
740
844
  mode: "git",
741
845
  baseRef,
742
846
  base,
743
- pending: diff(forkPoint && forkPoint !== baseSha ? (await logAt(forkPoint)).adrs : base, working.adrs).map((change) => ({
847
+ pending: diff(fork, working.adrs).map((change) => ({
744
848
  ...change,
745
849
  base: latest(change.base, base)
746
850
  })),
@@ -771,6 +875,90 @@ function mergedAdrs(view) {
771
875
  }
772
876
  return merged.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
773
877
  }
878
+ // ../core/src/lint.ts
879
+ /**
880
+ * markdownlint settings tuned for ADRs, overridable under `lint.markdownlint` in the config. They follow MADR's: "the
881
+ * linter should support the user and not annoy them".
882
+ */
883
+ const MARKDOWNLINT_DEFAULTS = {
884
+ default: true,
885
+ MD013: false,
886
+ MD024: false,
887
+ MD025: { front_matter_title: "" },
888
+ MD041: false
889
+ };
890
+ const FENCE = /^(```|~~~)[\s\S]*?^\1[^\n]*$/gm;
891
+ const INLINE_CODE = /`[^`\n]*`/g;
892
+ const COMMENT = /<!--[\s\S]*?-->/g;
893
+ /** `{short title, representative of …}`: braces around words, without the quotes or colon of JSON or `{n:4}`. */
894
+ const PLACEHOLDER = /\{(?![^{}\n]*["':])[^{}\n]*\s[^{}\n]*\}/;
895
+ const NUMBERED_HEADING = /^#{1,6}\s+\d+[.)]\s/m;
896
+ const prose = (body) => body.replace(FENCE, "").replace(COMMENT, "").replace(INLINE_CODE, "");
897
+ /** The text under the Decision (or MADR's Decision Outcome) heading; null when the ADR has no such heading. */
898
+ function decisionText(body) {
899
+ const m = /^##\s+(?:Decision Outcome|Decision)\s*$([\s\S]*?)(?=^##\s|(?![\s\S]))/im.exec(body);
900
+ if (!m) return null;
901
+ return (m[1] ?? "").replace(COMMENT, "").replace(/^#+\s.*$/gm, "").trim();
902
+ }
903
+ function adrienRules(adr) {
904
+ const at = {
905
+ id: adr.meta.id,
906
+ path: adr.path
907
+ };
908
+ const out = [];
909
+ const text = prose(adr.body);
910
+ const placeholder = PLACEHOLDER.exec(text)?.[0];
911
+ if (placeholder) out.push({
912
+ severity: "warning",
913
+ code: "unfilled-placeholder",
914
+ ...at,
915
+ message: `Template placeholder left in the body: ${placeholder}`
916
+ });
917
+ if (adr.meta.status === "accepted" && decisionText(adr.body) === "") out.push({
918
+ severity: "warning",
919
+ code: "empty-decision",
920
+ ...at,
921
+ message: "An accepted ADR has an empty Decision section"
922
+ });
923
+ if (NUMBERED_HEADING.test(text)) out.push({
924
+ severity: "warning",
925
+ code: "numbered-heading",
926
+ ...at,
927
+ message: "Headings are not numbered (\"## Context\", not \"## 1. Context\"), so sections can move without renumbering"
928
+ });
929
+ return out;
930
+ }
931
+ /**
932
+ * Style warnings for the ADRs in the working tree: markdownlint over each file, plus Adrien's own rules. They are
933
+ * advice about how an ADR reads, never errors: a decision with a long line is still a decision.
934
+ */
935
+ async function lintAdrs(ctx, view) {
936
+ const adrs = workingAdrs(view);
937
+ const strings = Object.fromEntries(adrs.map((adr) => [adr.path, readFileSync(join(ctx.logRoot, ...adr.path.split("/")), "utf8")]));
938
+ const { lint } = await import("markdownlint/promise");
939
+ const results = await lint({
940
+ strings,
941
+ config: {
942
+ ...MARKDOWNLINT_DEFAULTS,
943
+ ...ctx.config.lint?.markdownlint
944
+ }
945
+ });
946
+ const out = [];
947
+ for (const adr of adrs) {
948
+ for (const e of results[adr.path] ?? []) {
949
+ const detail = e.errorDetail ? ` [${e.errorDetail}]` : "";
950
+ out.push({
951
+ severity: "warning",
952
+ code: "markdown",
953
+ id: adr.meta.id,
954
+ path: adr.path,
955
+ message: `${e.ruleNames[0]} ${e.ruleNames[1]}: ${e.ruleDescription}${detail} (line ${e.lineNumber})`
956
+ });
957
+ }
958
+ out.push(...adrienRules(adr));
959
+ }
960
+ return out;
961
+ }
774
962
  // ../core/src/check.ts
775
963
  const RETIRED$1 = /* @__PURE__ */ new Set([
776
964
  "rejected",
@@ -917,6 +1105,11 @@ async function runCheck(ctx, view, opts = {}) {
917
1105
  code: "base-unresolved",
918
1106
  message: "No default branch found (looked for origin/HEAD, origin/main, origin/master, main, master), so pending ADRs cannot be told from merged ones. Fetch it first, e.g. `git fetch origin <default-branch>`."
919
1107
  });
1108
+ if (opts.mr && view.forkUnresolved) out.push({
1109
+ severity: "error",
1110
+ code: "fork-unresolved",
1111
+ message: `This checkout shares no history with ${view.baseRef} (a shallow clone?), so what the merge request changed cannot be told from what landed upstream. Fetch more history first, e.g. \`git fetch --unshallow\`.`
1112
+ });
920
1113
  const adrs = mergedAdrs(view);
921
1114
  for (const adr of adrs) checkFields(ctx, adr, out);
922
1115
  checkLinks(adrs, out);
@@ -929,6 +1122,17 @@ async function runCheck(ctx, view, opts = {}) {
929
1122
  message: `${change.id} is still "proposed": merging it adds only a hint. Run \`adrien accept ${change.id}\` to approve it`
930
1123
  });
931
1124
  }
1125
+ const today = opts.today ?? (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
1126
+ for (const adr of adrs) {
1127
+ const due = adr.meta.review_on;
1128
+ if (due && due <= today && !RETIRED$1.has(adr.meta.status)) out.push({
1129
+ severity: "warning",
1130
+ code: "review-due",
1131
+ ...at(adr),
1132
+ message: `${adr.meta.id} was due for review on ${due}: confirm it still holds, or supersede it`
1133
+ });
1134
+ }
1135
+ if (opts.lint) out.push(...await lintAdrs(ctx, view));
932
1136
  return out;
933
1137
  }
934
1138
  function exitCodeFor(diags, strict = false) {
@@ -964,6 +1168,51 @@ function findDuplicates(title, adrs) {
964
1168
  }
965
1169
  return hits.sort((a, b) => b.score - a.score).slice(0, 5);
966
1170
  }
1171
+ // ../core/src/export.ts
1172
+ const EXPORT_FORMATS = ["markdown", "llms"];
1173
+ const byId = (a, b) => a.meta.id.localeCompare(b.meta.id, "en", { numeric: true });
1174
+ const cell = (text) => text.replace(/\|/g, "\\|");
1175
+ /**
1176
+ * A generated overview of the ADRs in this checkout. `markdown` is a table of all of them; `llms` follows the
1177
+ * llms.txt convention, so a model can read the accepted decisions and their rules from one file.
1178
+ * `from` is the directory of the file that will hold the export, so its links resolve from there; by default they are
1179
+ * relative to the log root.
1180
+ */
1181
+ function exportLog(ctx, view, format, opts = {}) {
1182
+ const adrs = [...workingAdrs(view)].sort(byId);
1183
+ const { from } = opts;
1184
+ const link = (adr) => from === void 0 ? adr.path : toPosix(relative(from, join(ctx.logRoot, ...adr.path.split("/"))));
1185
+ const { product } = ctx.config;
1186
+ if (format === "markdown") {
1187
+ const rows = adrs.map((a) => `| [${a.meta.id}](${link(a)}) | ${cell(a.meta.title)} | ${a.meta.status} | ${a.meta.tags.join(", ")} |`);
1188
+ return [
1189
+ `# ${product}: architecture decisions`,
1190
+ "",
1191
+ "| ID | Title | Status | Tags |",
1192
+ "| --- | --- | --- | --- |",
1193
+ ...rows,
1194
+ ""
1195
+ ].join("\n");
1196
+ }
1197
+ const base = [...view.base].sort(byId);
1198
+ const pending = view.pending.filter((c) => c.current !== void 0).sort((a, b) => byId(a.current, b.current));
1199
+ const entry = (a, kind = "") => `- [${a.meta.id}: ${a.meta.title}](${link(a)})${a.meta.review_rule ? `: ${a.meta.review_rule}` : ""}${kind}`;
1200
+ const group = (title, lines) => lines.length ? [
1201
+ "",
1202
+ `## ${title}`,
1203
+ "",
1204
+ ...lines
1205
+ ] : [];
1206
+ return [
1207
+ `# ${product}`,
1208
+ "",
1209
+ `> Architecture decisions for ${product}. Before changing code, follow the rule of every accepted decision that governs it.`,
1210
+ ...group("Accepted", base.filter((a) => a.meta.status === "accepted").map((a) => entry(a))),
1211
+ ...group("Proposed (not yet binding)", base.filter((a) => a.meta.status === "proposed").map((a) => entry(a))),
1212
+ ...group("Pending in this checkout (not yet binding)", pending.map((c) => entry(c.current, ` (${c.kind})`))),
1213
+ ""
1214
+ ].join("\n");
1215
+ }
967
1216
  // ../core/src/for-files.ts
968
1217
  const RETIRED = /* @__PURE__ */ new Set([
969
1218
  "rejected",
@@ -1034,6 +1283,14 @@ function adrsForFiles(ctx, view, paths) {
1034
1283
  };
1035
1284
  });
1036
1285
  }
1286
+ /**
1287
+ * A warning for callers that show decisions as binding: with no default branch to compare against, ADR statuses are
1288
+ * read as written, so an ADR that says `accepted` may not have been merged.
1289
+ */
1290
+ function unverifiedBaseNote(view) {
1291
+ if (!view.baseUnresolved) return null;
1292
+ return "No default branch was found (looked for origin/HEAD, origin/main, origin/master, main, master), so ADR statuses are read as written and nothing is verified as merged. Fetch the default branch to be sure which decisions are binding.";
1293
+ }
1037
1294
  // ../core/src/sqlite.ts
1038
1295
  let loading;
1039
1296
  /**
@@ -1221,6 +1478,7 @@ function assertWritable(ctx) {
1221
1478
  if (ctx.readOnly) throw new AdrienError("READ_ONLY_LOG", `The ADR log is a read-only cached clone (${ctx.logSource}). Check out the log repo and point \`log:\` in .adrien.yaml to its local path to propose changes.`);
1222
1479
  }
1223
1480
  function validateInput(ctx, input) {
1481
+ if (input.review_on !== void 0 && !/^\d{4}-\d{2}-\d{2}$/.test(input.review_on)) throw new AdrienError("INVALID_INPUT", `review_on "${input.review_on}" must be a date like 2027-03-04`);
1224
1482
  const known = Object.keys(ctx.config.components);
1225
1483
  const badTags = (input.tags ?? []).filter((t) => !ctx.config.tags.includes(t));
1226
1484
  if (badTags.length) throw new AdrienError("INVALID_INPUT", `Unknown tag(s): ${badTags.join(", ")}. Allowed: ${ctx.config.tags.join(", ")}`);
@@ -1233,8 +1491,12 @@ function validateInput(ctx, input) {
1233
1491
  if (badAnchors.length) throw new AdrienError("INVALID_INPUT", `Invalid anchor(s): ${badAnchors.join(", ")}. Use <component>:<glob> with a component from: ${known.join(", ")}`);
1234
1492
  }
1235
1493
  const allIds = (view) => [...view.base, ...workingAdrs(view)].map((a) => a.meta.id);
1236
- function findAdr(view, id) {
1237
- const matches = workingAdrs(view).filter((a) => a.meta.id === id);
1494
+ /**
1495
+ * The ADR as it is on disk now. A view was loaded asynchronously and may predate another edit, and rewriting an ADR from
1496
+ * a stale copy would silently undo that edit.
1497
+ */
1498
+ function findAdr(ctx, id) {
1499
+ const matches = readWorkingLog(ctx.logRoot, ctx.config).adrs.filter((a) => a.meta.id === id);
1238
1500
  if (matches.length === 0) throw new AdrienError("ADR_NOT_FOUND", `No ADR ${id} in the log`);
1239
1501
  if (matches.length > 1) throw new AdrienError("INVALID_INPUT", `${id} is used by ${matches.map((a) => a.path).join(", ")}. Run \`adrien renumber ${id}\` first`);
1240
1502
  return matches[0];
@@ -1254,7 +1516,7 @@ function createAdr(ctx, view, input, opts) {
1254
1516
  const id = formatId(nextIdNumber(allIds(live), ctx.config.id_format), ctx.config.id_format);
1255
1517
  const adr = {
1256
1518
  path: adrFilePath(ctx.config, id, input.title, input.subdir),
1257
- body: input.body ?? "\n## Context\n\n## Considered options\n\n## Decision\n\n## Rationale\n\n## Consequences\n",
1519
+ body: input.body ?? bodyTemplate(input.template ?? ctx.config.template),
1258
1520
  meta: {
1259
1521
  id,
1260
1522
  title: input.title,
@@ -1264,6 +1526,7 @@ function createAdr(ctx, view, input, opts) {
1264
1526
  components: input.components ?? [],
1265
1527
  code: input.code ?? [],
1266
1528
  review_rule: input.review_rule,
1529
+ review_on: input.review_on,
1267
1530
  sources: input.sources ?? [],
1268
1531
  supersedes: [],
1269
1532
  related: input.related ?? [],
@@ -1274,6 +1537,7 @@ function createAdr(ctx, view, input, opts) {
1274
1537
  }
1275
1538
  };
1276
1539
  if (adr.meta.review_rule === void 0) delete adr.meta.review_rule;
1540
+ if (adr.meta.review_on === void 0) delete adr.meta.review_on;
1277
1541
  writeAdr(ctx.logRoot, adr, { exclusive: true });
1278
1542
  return {
1279
1543
  written: true,
@@ -1291,12 +1555,12 @@ const PATCH_KEYS = /* @__PURE__ */ new Set([
1291
1555
  "body"
1292
1556
  ]);
1293
1557
  /** Edits an ADR in the working copy; the merge request that carries it is the approval gate. */
1294
- function updateAdr(ctx, view, id, patch, opts) {
1558
+ function updateAdr(ctx, _view, id, patch, opts) {
1295
1559
  assertWritable(ctx);
1296
1560
  const forbidden = Object.keys(patch).filter((k) => !PATCH_KEYS.has(k));
1297
1561
  if (forbidden.length) throw new AdrienError("INVALID_INPUT", `Cannot change ${forbidden.join(", ")} this way (status changes need an architect)`);
1298
1562
  validateInput(ctx, patch);
1299
- const adr = findAdr(view, id);
1563
+ const adr = findAdr(ctx, id);
1300
1564
  const { body, ...metaPatch } = patch;
1301
1565
  let nextBody = body ?? adr.body;
1302
1566
  if (opts?.note) nextBody = `${nextBody.replace(/\n*$/, "\n")}\n> Proposed change (${opts.origin ?? "agent"}, ${todayOf(opts)}): ${opts.note}\n`;
@@ -1322,28 +1586,29 @@ function write(ctx, adr, meta) {
1322
1586
  writeAdr(ctx.logRoot, updated);
1323
1587
  return updated;
1324
1588
  }
1325
- function acceptAdr(ctx, view, id, opts) {
1589
+ function acceptAdr(ctx, _view, id, opts) {
1326
1590
  assertWritable(ctx);
1327
- const adr = findAdr(view, id);
1591
+ const adr = findAdr(ctx, id);
1328
1592
  if (!adr.meta.review_rule?.trim()) throw new AdrienError("INVALID_INPUT", `${id} needs a review_rule before it can be accepted`);
1329
1593
  return write(ctx, adr, {
1330
1594
  status: "accepted",
1331
1595
  date: adr.meta.date ?? todayOf(opts)
1332
1596
  });
1333
1597
  }
1334
- function setStatus(ctx, view, id, status) {
1598
+ function setStatus(ctx, _view, id, status) {
1335
1599
  assertWritable(ctx);
1336
1600
  if (![
1337
1601
  "proposed",
1338
1602
  "rejected",
1339
1603
  "deprecated"
1340
1604
  ].includes(status)) throw new AdrienError("INVALID_INPUT", `Use \`adrien accept\` or \`adrien supersede\` to set "${status}"`);
1341
- return write(ctx, findAdr(view, id), { status });
1605
+ return write(ctx, findAdr(ctx, id), { status });
1342
1606
  }
1343
- function supersede(ctx, view, oldId, newId) {
1607
+ function supersede(ctx, _view, oldId, newId) {
1344
1608
  assertWritable(ctx);
1345
- const oldAdr = findAdr(view, oldId);
1346
- const newAdr = findAdr(view, newId);
1609
+ if (oldId === newId) throw new AdrienError("INVALID_INPUT", `${oldId} cannot supersede itself`);
1610
+ const oldAdr = findAdr(ctx, oldId);
1611
+ const newAdr = findAdr(ctx, newId);
1347
1612
  return {
1348
1613
  old: write(ctx, oldAdr, {
1349
1614
  status: "superseded",
@@ -1355,7 +1620,7 @@ function supersede(ctx, view, oldId, newId) {
1355
1620
  /** Gives a colliding ADR the next free id; references in other pending ADRs follow it, base ADRs are never touched. */
1356
1621
  function renumber(ctx, view, id, opts) {
1357
1622
  assertWritable(ctx);
1358
- const candidates = workingAdrs(view).filter((a) => a.meta.id === id);
1623
+ const candidates = readWorkingLog(ctx.logRoot, ctx.config).adrs.filter((a) => a.meta.id === id);
1359
1624
  if (candidates.length === 0) throw new AdrienError("ADR_NOT_FOUND", `No ADR ${id} in the log`);
1360
1625
  const basePaths = new Set(view.base.filter((a) => a.meta.id === id).map((a) => a.path));
1361
1626
  const notInBase = candidates.filter((a) => !basePaths.has(a.path));
@@ -1363,6 +1628,7 @@ function renumber(ctx, view, id, opts) {
1363
1628
  if (!target) throw new AdrienError("INVALID_INPUT", `Say which file to renumber with --file: ${candidates.map((a) => a.path).join(", ")}`);
1364
1629
  const to = formatId(nextIdNumber(allIds(view), ctx.config.id_format), ctx.config.id_format);
1365
1630
  const path = posix.join(posix.dirname(target.path), `${to}-${slugify(target.meta.title)}.md`);
1631
+ const inPlace = path === target.path;
1366
1632
  writeAdr(ctx.logRoot, {
1367
1633
  ...target,
1368
1634
  path,
@@ -1370,8 +1636,8 @@ function renumber(ctx, view, id, opts) {
1370
1636
  ...target.meta,
1371
1637
  id: to
1372
1638
  }
1373
- });
1374
- unlinkSync(join(ctx.logRoot, ...target.path.split("/")));
1639
+ }, { exclusive: !inPlace });
1640
+ if (!inPlace) unlinkSync(join(ctx.logRoot, ...target.path.split("/")));
1375
1641
  const swap = (ids) => ids.map((x) => x === id ? to : x);
1376
1642
  for (const change of view.pending) {
1377
1643
  const adr = change.current;
@@ -1463,7 +1729,7 @@ function formatDiagnostic(d) {
1463
1729
  }
1464
1730
  // src/commands/check.ts
1465
1731
  function registerCheck(program, cli) {
1466
- program.command("check").description("Validate the ADR log (CI-ready exit code)").option("--here", "verify anchors against the code repo this runs in (use in code-repo CI)").option("--mr", "merge-request mode: fetch the default branch, warn about ADRs left \"proposed\"").option("--strict", "fail on warnings too").action(async (opts, cmd) => {
1732
+ program.command("check").description("Validate the ADR log (CI-ready exit code)").option("--here", "verify anchors against the code repo this runs in (use in code-repo CI)").option("--mr", "merge-request mode: fetch the default branch, warn about ADRs left \"proposed\"").option("--lint", "also report style warnings (see `adrien lint`)").option("--strict", "fail on warnings too").action(async (opts, cmd) => {
1467
1733
  const globals = cmd.optsWithGlobals();
1468
1734
  const ctx = await contextOf(cli, globals);
1469
1735
  if (opts.mr) {
@@ -1472,7 +1738,8 @@ function registerCheck(program, cli) {
1472
1738
  }
1473
1739
  const diags = await runCheck(ctx, await loadLogView(ctx.logRoot, ctx.config), {
1474
1740
  here: opts.here,
1475
- mr: opts.mr
1741
+ mr: opts.mr,
1742
+ lint: opts.lint
1476
1743
  });
1477
1744
  const errors = diags.filter((d) => d.severity === "error").length;
1478
1745
  const warnings = diags.filter((d) => d.severity === "warning").length;
@@ -1486,12 +1753,28 @@ function registerCheck(program, cli) {
1486
1753
  cli.out(`${errors} errors, ${warnings} warnings\n`);
1487
1754
  });
1488
1755
  }
1756
+ // src/commands/export.ts
1757
+ function registerExport(program, cli) {
1758
+ program.command("export").description("Print or write an overview of the ADRs: a markdown table, or an llms.txt").option("--format <format>", `${EXPORT_FORMATS.join(" | ")}`, "markdown").option("--out <file>", "write to this file instead of printing (links are relative to it)").action(async (opts, cmd) => {
1759
+ const format = opts.format;
1760
+ if (!EXPORT_FORMATS.includes(format)) throw new AdrienError("INVALID_INPUT", `Unknown format "${opts.format}". Use one of: ${EXPORT_FORMATS.join(", ")}`);
1761
+ const { ctx, view } = await open(cli, cmd.optsWithGlobals());
1762
+ if (!opts.out) return cli.out(exportLog(ctx, view, format));
1763
+ const file = resolve(cli.cwd, opts.out);
1764
+ const text = exportLog(ctx, view, format, { from: dirname(file) });
1765
+ mkdirSync(dirname(file), { recursive: true });
1766
+ writeFileSync(file, text);
1767
+ cli.out(`Wrote ${opts.out}\n`);
1768
+ });
1769
+ }
1489
1770
  // src/commands/for.ts
1490
1771
  function registerFor(program, cli) {
1491
1772
  program.command("for").description("Show the decisions that govern these files, and why").argument("<paths...>", "files, relative to the current directory").action(async (paths, _opts, cmd) => {
1492
1773
  const globals = cmd.optsWithGlobals();
1493
1774
  const { ctx, view } = await open(cli, globals);
1494
1775
  const files = adrsForFiles(ctx, view, paths);
1776
+ const note = unverifiedBaseNote(view);
1777
+ if (note) cli.err(`note: ${note}\n`);
1495
1778
  if (globals.json) return printJson(cli, files);
1496
1779
  cli.out(formatFileDecisions(files));
1497
1780
  });
@@ -1565,6 +1848,22 @@ function registerInit(program, cli) {
1565
1848
  if (!opts.codeRepo && !opts.agents) initLog(cli, opts);
1566
1849
  });
1567
1850
  }
1851
+ // src/commands/lint.ts
1852
+ function registerLint(program, cli) {
1853
+ program.command("lint").description("Style warnings for the ADRs: markdownlint plus Adrien rules (placeholders, empty decisions)").option("--strict", "exit 1 on warnings").action(async (opts, cmd) => {
1854
+ const globals = cmd.optsWithGlobals();
1855
+ const ctx = await contextOf(cli, globals);
1856
+ const diags = await lintAdrs(ctx, await loadLogView(ctx.logRoot, ctx.config));
1857
+ cli.setCode(exitCodeFor(diags, opts.strict));
1858
+ if (globals.json) return printJson(cli, {
1859
+ errors: 0,
1860
+ warnings: diags.length,
1861
+ diagnostics: diags
1862
+ });
1863
+ for (const d of diags) cli.out(formatDiagnostic(d));
1864
+ cli.out(`0 errors, ${diags.length} warnings\n`);
1865
+ });
1866
+ }
1568
1867
  // src/commands/list.ts
1569
1868
  function registerList(program, cli) {
1570
1869
  program.command("list").description("List ADRs (base and pending)").option("--tag <tag>", "only ADRs with this tag (repeatable: all must match)", collect, []).option("--component <id>", "only ADRs for this component (repeatable: any matches)", collect, []).option("--status <status>", "only this status (repeatable)", collect, []).option("--pending", "only pending (unmerged) changes").action(async (opts, cmd) => {
@@ -1638,9 +1937,15 @@ const section = (heading, text) => text?.trim() ? `## ${heading}\n\n${text.trim(
1638
1937
  function registerTools(server, opts) {
1639
1938
  server.registerTool("adr_for_files", {
1640
1939
  title: "Decisions governing files",
1641
- description: "Call this BEFORE editing code. For each file, returns the architecture decisions that govern it, with the review_rule to follow. binding:true means an accepted decision on the default branch; binding:false is a pending proposal or a hint.",
1940
+ description: "Call this BEFORE editing code. For each file, returns the architecture decisions that govern it, with the review_rule to follow. binding:true means an accepted decision on the default branch; binding:false is a pending proposal or a hint. If `notes` is present, read it: it says the default branch could not be found, so bindingness is unverified.",
1642
1941
  inputSchema: { paths: z.array(z.string().min(1)).min(1).max(50) }
1643
- }, handler(opts, ({ paths }, ctx, view) => ok({ files: adrsForFiles(ctx, view, paths) })));
1942
+ }, handler(opts, ({ paths }, ctx, view) => {
1943
+ const note = unverifiedBaseNote(view);
1944
+ return ok({
1945
+ files: adrsForFiles(ctx, view, paths),
1946
+ ...note ? { notes: [note] } : {}
1947
+ });
1948
+ }));
1644
1949
  server.registerTool("adr_search", {
1645
1950
  title: "Search decisions",
1646
1951
  description: "Full-text search over ADR titles, review rules and bodies. Accent-insensitive; prefix matching.",
@@ -1798,8 +2103,9 @@ function registerMcp(program, cli) {
1798
2103
  }
1799
2104
  // src/commands/new.ts
1800
2105
  function registerNew(program, cli) {
1801
- program.command("new").description("Create a proposed ADR").argument("<title>", "decision title").option("--tags <list>", "tags, comma-separated").option("--components <list>", "components, comma-separated").option("--code <component:glob>", "code it governs (repeatable)", collect, []).option("--review-rule <text>", "one checkable sentence for reviewers and agents").option("--subdir <path>", "folder inside the ADR dir").option("--force", "create even if a similar title exists").action(async (title, opts, cmd) => {
2106
+ program.command("new").description("Create a proposed ADR").argument("<title>", "decision title").option("--tags <list>", "tags, comma-separated").option("--components <list>", "components, comma-separated").option("--code <component:glob>", "code it governs (repeatable)", collect, []).option("--review-rule <text>", "one checkable sentence for reviewers and agents").option("--review-on <date>", "when to look at this decision again, as YYYY-MM-DD").option("--subdir <path>", "folder inside the ADR dir").option("--template <name>", `body skeleton: ${TEMPLATE_NAMES.join(", ")} (default: the config's template)`).option("--force", "create even if a similar title exists").action(async (title, opts, cmd) => {
1802
2107
  const globals = cmd.optsWithGlobals();
2108
+ if (opts.template && !TEMPLATE_NAMES.includes(opts.template)) throw new AdrienError("INVALID_INPUT", `Unknown template "${opts.template}". Use one of: ${TEMPLATE_NAMES.join(", ")}`);
1803
2109
  const { ctx, view } = await open(cli, globals);
1804
2110
  const result = createAdr(ctx, view, {
1805
2111
  title,
@@ -1807,7 +2113,9 @@ function registerNew(program, cli) {
1807
2113
  components: csv(opts.components),
1808
2114
  code: opts.code,
1809
2115
  review_rule: opts.reviewRule,
1810
- subdir: opts.subdir
2116
+ review_on: opts.reviewOn,
2117
+ subdir: opts.subdir,
2118
+ template: opts.template
1811
2119
  }, {
1812
2120
  today: today(),
1813
2121
  force: opts.force
@@ -1932,11 +2240,13 @@ function buildProgram(cli) {
1932
2240
  registerSearch,
1933
2241
  registerFor,
1934
2242
  registerCheck,
2243
+ registerLint,
1935
2244
  registerAccept,
1936
2245
  registerStatus,
1937
2246
  registerSupersede,
1938
2247
  registerRenumber,
1939
2248
  registerSync,
2249
+ registerExport,
1940
2250
  registerMcp
1941
2251
  ]) register(program, cli);
1942
2252
  return program;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "adrien",
3
- "version": "0.0.1",
3
+ "version": "0.1.0",
4
4
  "description": "AI-native Architecture Decision Records: a CLI and MCP server that tells developers and AI agents which decisions govern their code, and why.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -28,13 +28,20 @@
28
28
  "cli"
29
29
  ],
30
30
  "scripts": {
31
- "build": "tsdown"
31
+ "build": "tsdown",
32
+ "prepack": "node -e \"const fs=require('fs');fs.copyFileSync('../../LICENSE','LICENSE');fs.copyFileSync('../../README.md','README.md')\""
32
33
  },
33
34
  "dependencies": {
34
35
  "@modelcontextprotocol/sdk": "^1.32.2",
35
36
  "commander": "^15.1.0",
37
+ "markdownlint": "^0.42.1",
36
38
  "picomatch": "^4.0.7",
37
39
  "yaml": "^2.9.1",
38
40
  "zod": "^4.6.7"
41
+ },
42
+ "devDependencies": {
43
+ "@adrien/core": "workspace:*",
44
+ "@adrien/mcp": "workspace:*",
45
+ "tsdown": "^0.23.7"
39
46
  }
40
47
  }