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.
- package/README.md +5 -2
- package/dist/index.js +398 -88
- 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
|
-
|
|
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/
|
|
155
|
-
const
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
]
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
]
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
"
|
|
184
|
-
|
|
185
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
})),
|
|
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(
|
|
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
|
-
|
|
1237
|
-
|
|
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 ??
|
|
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,
|
|
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(
|
|
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,
|
|
1589
|
+
function acceptAdr(ctx, _view, id, opts) {
|
|
1326
1590
|
assertWritable(ctx);
|
|
1327
|
-
const adr = findAdr(
|
|
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,
|
|
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(
|
|
1605
|
+
return write(ctx, findAdr(ctx, id), { status });
|
|
1342
1606
|
}
|
|
1343
|
-
function supersede(ctx,
|
|
1607
|
+
function supersede(ctx, _view, oldId, newId) {
|
|
1344
1608
|
assertWritable(ctx);
|
|
1345
|
-
|
|
1346
|
-
const
|
|
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 =
|
|
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) =>
|
|
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
|
-
|
|
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
|
|
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
|
}
|