mcp-adr-analysis-server 2.7.48 → 2.9.0

package/dist/src/utils/adr-format.js

@@ -0,0 +1,232 @@
+/**
+ * ADR format reader and Nygard -> MADR converter (issue #1466).
+ *
+ * Pure functions, no I/O and no side effects — modelled on `src/utils/rule-format.ts`.
+ * Two capabilities:
+ *
+ *   - `detectAdrFormat(content)` classifies an ADR document as `'nygard'`, `'madr'`,
+ *     or `'custom'`.
+ *   - `convertNygardToMadr(content)` rewrites a Nygard-style ADR into the ADR-022
+ *     canonical MADR shape the real corpus uses (see docs/adrs/adr-025 and adr-026 as
+ *     golden references), with `js-yaml` front matter.
+ *
+ * Field-level parsing (title/status/date/context/decision/consequences/tags) is reused
+ * from `adr-discovery.ts` via the shared `extractAdrFields` helper rather than keeping a
+ * third private copy of those regexes.
+ */
+import yaml from 'js-yaml';
+/**
+ * Extract ADR fields from raw markdown content.
+ *
+ * `filename` is optional: when supplied it seeds the title fallback and the ADR-number
+ * lookup (callers that only have content, such as the format converter, omit it).
+ */
+export function extractAdrFields(content, filename = '') {
+    // Extract title (usually first # heading)
+    let title = filename ? filename.replace(/\.md$/, '') : undefined;
+    const titleMatch = content.match(/^#\s+(.+)$/m);
+    if (titleMatch && titleMatch[1]) {
+        title = titleMatch[1].trim();
+    }
+    // Extract status
+    let status = 'unknown';
+    const statusMatch = content.match(/(?:##?\s*status|status:)\s*(.+?)(?:\n|$)/i);
+    if (statusMatch && statusMatch[1]) {
+        status = statusMatch[1].trim().toLowerCase();
+    }
+    // Extract date
+    let date;
+    const dateMatch = content.match(/(?:##?\s*date|date:)\s*(.+?)(?:\n|$)/i);
+    if (dateMatch && dateMatch[1]) {
+        date = dateMatch[1].trim();
+    }
+    // Extract ADR number from filename or content
+    let number;
+    const numberMatch = (filename ? filename.match(/(?:adr[-_]?)?(\d+)/i) : null) || content.match(/adr[-_]?(\d+)/i);
+    if (numberMatch && numberMatch[1]) {
+        number = numberMatch[1];
+    }
+    // Extract context
+    let context;
+    const contextMatch = content.match(/##?\s*context\s*\n([\s\S]*?)(?=\n##|\n#|$)/i);
+    if (contextMatch && contextMatch[1]) {
+        context = contextMatch[1].trim();
+    }
+    // Extract decision
+    let decision;
+    const decisionMatch = content.match(/##?\s*decision\s*\n([\s\S]*?)(?=\n##|\n#|$)/i);
+    if (decisionMatch && decisionMatch[1]) {
+        decision = decisionMatch[1].trim();
+    }
+    // Extract consequences
+    let consequences;
+    const consequencesMatch = content.match(/##?\s*consequences\s*\n([\s\S]*?)(?=\n##|\n#|$)/i);
+    if (consequencesMatch && consequencesMatch[1]) {
+        consequences = consequencesMatch[1].trim();
+    }
+    // Extract category/tags (if any).
+    //
+    // Three forms occur in the wild, and the idiomatic MADR one used to be the only one
+    // that did NOT work -- a YAML block list returned ["- architecture"], capturing the
+    // dash and dropping every entry after the first. ADR-022 adopted MADR, whose template
+    // uses block lists, so that was the form this needed most.
+    //
+    //   tags:               tags: a, b        tags: [a, b]
+    //     - a
+    //     - b
+    //
+    // Scoped to the leading `---` front-matter block when one is present, so a `tags:`
+    // mention in prose cannot be picked up -- the same discipline scripts/check-adr-drift.sh
+    // and repo-governor's adapters/adr both use after that exact false positive.
+    const tags = [];
+    const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    const tagScope = fmMatch?.[1] ?? content;
+    const blockMatch = tagScope.match(/^[ \t]*(?:tags?|categories?):[ \t]*\r?\n((?:[ \t]*-[ \t]*\S.*\r?\n?)+)/im);
+    if (blockMatch?.[1]) {
+        tags.push(...blockMatch[1]
+            .split(/\r?\n/)
+            .map(line => line.replace(/^[ \t]*-[ \t]*/, '').trim())
+            .filter(Boolean));
+    }
+    else {
+        const inlineMatch = tagScope.match(/^[ \t]*(?:tags?|categories?):[ \t]*(.+?)[ \t]*\r?$/im);
+        if (inlineMatch?.[1]) {
+            tags.push(...inlineMatch[1]
+                .replace(/^\[|\]$/g, '') // tolerate the bracket form, which used to keep its brackets
+                .split(',')
+                .map(tag => tag.trim().replace(/^['"]|['"]$/g, ''))
+                .filter(Boolean));
+        }
+    }
+    const fields = { status, tags };
+    if (title !== undefined)
+        fields.title = title;
+    if (date)
+        fields.date = date;
+    if (number)
+        fields.number = number;
+    if (context)
+        fields.context = context;
+    if (decision)
+        fields.decision = decision;
+    if (consequences)
+        fields.consequences = consequences;
+    return fields;
+}
+/**
+ * Does the document open with a `---...---` YAML front-matter block that declares
+ * `status:` and/or `date:`?
+ */
+function hasFrontMatterStatusOrDate(content) {
+    const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!fmMatch || !fmMatch[1])
+        return false;
+    return /^[ \t]*(?:status|date):/im.test(fmMatch[1]);
+}
+/** Does the document use MADR-style headings? */
+function hasMadrHeadings(content) {
+    return (/^##\s+Context and Problem Statement\s*$/im.test(content) ||
+        /^##\s+Considered Options\s*$/im.test(content) ||
+        /^##\s+Decision Drivers\s*$/im.test(content));
+}
+/**
+ * Detect the format of an ADR document.
+ *
+ * - `'madr'`  — leading YAML front matter with `status:`/`date:` AND MADR headings
+ *   (`## Context and Problem Statement`, and/or `## Considered Options`/
+ *   `## Decision Drivers`).
+ * - `'nygard'` — the Nygard heading set (`## Status`, `## Context`, `## Decision`,
+ *   `## Consequences`) with a status value on the following line.
+ * - `'custom'` — anything else.
+ */
+export function detectAdrFormat(content) {
+    if (hasFrontMatterStatusOrDate(content) && hasMadrHeadings(content)) {
+        return 'madr';
+    }
+    // Nygard: reuse the field extractor's heading regexes. Context/Decision/Consequences
+    // each require the `##`-heading-then-body form, and a status value on the following
+    // line resolves to something other than the 'unknown' sentinel.
+    const fields = extractAdrFields(content);
+    const hasNygardSet = fields.status !== 'unknown' &&
+        fields.context !== undefined &&
+        fields.decision !== undefined &&
+        fields.consequences !== undefined;
+    if (hasNygardSet) {
+        return 'nygard';
+    }
+    return 'custom';
+}
+/**
+ * Map a Nygard status value onto the lowercase MADR status vocabulary.
+ *
+ * Nygard "Accepted" -> "accepted", "Deprecated" -> "deprecated",
+ * "Superseded" -> "superseded", "Proposed" -> "proposed". Absent/unknown -> "proposed".
+ * Any other value passes through lowercased.
+ */
+function mapStatusToMadr(status) {
+    const s = (status ?? '').trim().toLowerCase();
+    if (!s || s === 'unknown')
+        return 'proposed';
+    if (s.startsWith('accept'))
+        return 'accepted';
+    if (s.startsWith('deprecat'))
+        return 'deprecated';
+    if (s.startsWith('supersed'))
+        return 'superseded';
+    if (s.startsWith('propos'))
+        return 'proposed';
+    return s;
+}
+/**
+ * Convert a Nygard-style ADR into the ADR-022 canonical MADR shape.
+ *
+ * Idempotent: content already detected as `'madr'` is returned unchanged.
+ *
+ * `'custom'` content is converted best-effort — whatever Nygard-shaped sections can be
+ * recovered are carried across, and any section with nothing to carry becomes an empty
+ * placeholder heading. The result is always valid MADR (front matter + MADR headings).
+ */
+export function convertNygardToMadr(content) {
+    if (detectAdrFormat(content) === 'madr') {
+        return content;
+    }
+    const fields = extractAdrFields(content);
+    // Build the YAML front matter via js-yaml (block style, 2-space indent).
+    const frontMatter = { status: mapStatusToMadr(fields.status) };
+    if (fields.date)
+        frontMatter['date'] = fields.date;
+    if (fields.tags.length > 0)
+        frontMatter['tags'] = fields.tags;
+    const yamlBlock = yaml.dump(frontMatter, { indent: 2, lineWidth: -1 }).trimEnd();
+    const title = fields.title ?? 'ADR';
+    const section = (body) => (body && body.trim() ? body.trim() : '');
+    const lines = [
+        '---',
+        yamlBlock,
+        '---',
+        '',
+        `# ${title}`,
+        '',
+        '## Context and Problem Statement',
+        '',
+        section(fields.context),
+        '',
+        '## Decision',
+        '',
+        section(fields.decision),
+        '',
+        '## Consequences',
+        '',
+        section(fields.consequences),
+        '',
+        '## More Information',
+        '',
+    ];
+    // Collapse the doubled blank lines that empty sections introduce, then end with a
+    // single trailing newline.
+    return lines
+        .join('\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .replace(/\s*$/, '\n');
+}
+//# sourceMappingURL=adr-format.js.map

package/dist/src/utils/adr-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adr-format.js","sourceRoot":"","sources":["../../../src/utils/adr-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,IAAI,MAAM,SAAS,CAAC;AA8B3B;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,QAAQ,GAAG,EAAE;IAC7D,0CAA0C;IAC1C,IAAI,KAAK,GAAuB,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACrF,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IAChD,IAAI,UAAU,IAAI,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;QAChC,KAAK,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC/B,CAAC;IAED,iBAAiB;IACjB,IAAI,MAAM,GAAG,SAAS,CAAC;IACvB,MAAM,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/E,IAAI,WAAW,IAAI,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;QAClC,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC/C,CAAC;IAED,eAAe;IACf,IAAI,IAAwB,CAAC;IAC7B,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAC;IACzE,IAAI,SAAS,IAAI,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9B,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7B,CAAC;IAED,8CAA8C;IAC9C,IAAI,MAA0B,CAAC;IAC/B,MAAM,WAAW,GACf,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;IAC/F,IAAI,WAAW,IAAI,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;QAClC,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC;IAED,kBAAkB;IAClB,IAAI,OAA2B,CAAC;IAChC,MAAM,YAAY,GAAG,OAAO,CAAC,KAAK,CAAC,6CAA6C,CAAC,CAAC;IAClF,IAAI,YAAY,IAAI,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;QACpC,OAAO,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACnC,CAAC;IAED,mBAAmB;IACnB,IAAI,QAA4B,CAAC;IACjC,MAAM,aAAa,GAAG,OAAO,CAAC,KAAK,CAAC,8CAA8C,CAAC,CAAC;IACpF,IAAI,aAAa,IAAI,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;QACtC,QAAQ,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACrC,CAAC;IAED,uBAAuB;IACvB,IAAI,YAAgC,CAAC;IACrC,MAAM,iBAAiB,GAAG,OAAO,CAAC,KAAK,CAAC,kDAAkD,CAAC,CAAC;IAC5F,IAAI,iBAAiB,IAAI,iBAAiB,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9C,YAAY,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7C,CAAC;IAED,kCAAkC;IAClC,EAAE;IACF,oFAAoF;IACpF,oFAAoF;IACpF,sFAAsF;IACtF,2DAA2D;IAC3D,EAAE;IACF,uDAAuD;IACvD,UAAU;IACV,UAAU;IACV,EAAE;IACF,mFAAmF;IACnF,yFAAyF;IACzF,6EAA6E;IAC7E,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;IAC7D,MAAM,QAAQ,GAAG,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC;IAEzC,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,CAC/B,0EAA0E,CAC3E,CAAC;IACF,IAAI,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpB,IAAI,CAAC,IAAI,CACP,GAAG,UAAU,CAAC,CAAC,CAAC;aACb,KAAK,CAAC,OAAO,CAAC;aACd,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;aACtD,MAAM,CAAC,OAAO,CAAC,CACnB,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,MAAM,WAAW,GAAG,QAAQ,CAAC,KAAK,CAAC,sDAAsD,CAAC,CAAC;QAC3F,IAAI,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrB,IAAI,CAAC,IAAI,CACP,GAAG,WAAW,CAAC,CAAC,CAAC;iBACd,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,6DAA6D;iBACrF,KAAK,CAAC,GAAG,CAAC;iBACV,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;iBAClD,MAAM,CAAC,OAAO,CAAC,CACnB,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAuB,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IACpD,IAAI,KAAK,KAAK,SAAS;QAAE,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC;IAC9C,IAAI,IAAI;QAAE,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC;IAC7B,IAAI,MAAM;QAAE,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC;IACnC,IAAI,OAAO;QAAE,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC;IACtC,IAAI,QAAQ;QAAE,MAAM,CAAC,QAAQ,GAAG,QAAQ,CAAC;IACzC,IAAI,YAAY;QAAE,MAAM,CAAC,YAAY,GAAG,YAAY,CAAC;IACrD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,SAAS,0BAA0B,CAAC,OAAe;IACjD,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;IAC7D,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1C,OAAO,2BAA2B,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;AACtD,CAAC;AAED,iDAAiD;AACjD,SAAS,eAAe,CAAC,OAAe;IACtC,OAAO,CACL,2CAA2C,CAAC,IAAI,CAAC,OAAO,CAAC;QACzD,gCAAgC,CAAC,IAAI,CAAC,OAAO,CAAC;QAC9C,8BAA8B,CAAC,IAAI,CAAC,OAAO,CAAC,CAC7C,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,IAAI,0BAA0B,CAAC,OAAO,CAAC,IAAI,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC;QACpE,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,qFAAqF;IACrF,oFAAoF;IACpF,gEAAgE;IAChE,MAAM,MAAM,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IACzC,MAAM,YAAY,GAChB,MAAM,CAAC,MAAM,KAAK,SAAS;QAC3B,MAAM,CAAC,OAAO,KAAK,SAAS;QAC5B,MAAM,CAAC,QAAQ,KAAK,SAAS;QAC7B,MAAM,CAAC,YAAY,KAAK,SAAS,CAAC;IACpC,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,SAAS,eAAe,CAAC,MAA0B;IACjD,MAAM,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC9C,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC;IAC7C,IAAI,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,UAAU,CAAC;IAC9C,IAAI,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,YAAY,CAAC;IAClD,IAAI,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,YAAY,CAAC;IAClD,IAAI,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,UAAU,CAAC;IAC9C,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAe;IACjD,IAAI,eAAe,CAAC,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC;QACxC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,MAAM,MAAM,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAEzC,yEAAyE;IACzE,MAAM,WAAW,GAA4B,EAAE,MAAM,EAAE,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;IACxF,IAAI,MAAM,CAAC,IAAI;QAAE,WAAW,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC;IACnD,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,WAAW,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC;IAE9D,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;IAEjF,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,KAAK,CAAC;IAEpC,MAAM,OAAO,GAAG,CAAC,IAAwB,EAAU,EAAE,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAE/F,MAAM,KAAK,GAAa;QACtB,KAAK;QACL,SAAS;QACT,KAAK;QACL,EAAE;QACF,KAAK,KAAK,EAAE;QACZ,EAAE;QACF,kCAAkC;QAClC,EAAE;QACF,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;QACvB,EAAE;QACF,aAAa;QACb,EAAE;QACF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC;QACxB,EAAE;QACF,iBAAiB;QACjB,EAAE;QACF,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC;QAC5B,EAAE;QACF,qBAAqB;QACrB,EAAE;KACH,CAAC;IAEF,kFAAkF;IAClF,2BAA2B;IAC3B,OAAO,KAAK;SACT,IAAI,CAAC,IAAI,CAAC;SACV,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC;SAC1B,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAC3B,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-adr-analysis-server",
   "mcpName": "io.github.tosin2013/mcp-adr-analysis-server",
-  "version": "2.7.48",
+  "version": "2.9.0",
   "description": "MCP server for analyzing Architectural Decision Records and project architecture",
   "main": "dist/src/index.js",
   "type": "module",