@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/src/lib/specs/adr-index.js

@@ -1,36 +1,17 @@
-/**
- * The index of the ADRs that still hold across the project:
- * `.morph/specs/adrs/`, one file per ADR, committed next to the use-case acervo.
- *
- * Every feature writes ADRs into its own `decisions.md`, and most of them only
- * matter inside that feature. The index keeps the few that set a project-wide
- * rule, so brainstorming and plan read one folder instead of every archived
- * `decisions.md` — those stay as history, not as instruction.
- *
- * One file per ADR (`{feature}--ADR-{nnn}.md`), like the use-case acervo:
- * parallel features that index different ADRs never touch the same file, so
- * their archive commits merge cleanly — a single shared page conflicted on the
- * second merge.
- *
- * Maintained by finish/archive alone, inside the archive commit:
- *   - enters: an ADR of the closing feature whose block carries `**Alcance:** projeto`;
- *   - leaves: an ADR the closing feature's `spec.md` revokes in full (file deleted);
- *   - narrows: one it revokes in part keeps its file, with `scope:` where it still holds.
- * Nothing to add or revoke → nothing is touched (nor created).
- */
+// One file per ADR under `.morph/specs/adrs/`, so parallel features that index different ADRs merge cleanly.
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
 import { basename, join } from 'path';
+import { readFrontmatterField, setFrontmatterField } from './frontmatter.js';
+import { parseRevocations } from './revocations.js';
+import { parsePlan } from '../plan/plan-parser.js';
 import { OUTPUT_SCHEMA } from '../../core/paths/output-schema.js';
-import { readFrontmatterField, setFrontmatterField } from './usecase-promoter.js';
 
 /** Project-relative path of the index folder (git pathspec-ready). */
 export const ADR_INDEX_PATHSPEC = join('.morph', 'specs', 'adrs');
 
-const ADR_HEADING_RE = /^(#{2,6})\s+(ADR-\d+)\b[\s:—–-]*(.*?)\s*$/;
-const ANY_HEADING_RE = /^(#{1,6})\s/;
-/** `**Alcance:** projeto` — also `**Alcance**: projeto`. */
-const PROJECT_SCOPE_RE = /^\s*\*\*Alcance:?\*\*:?\s*projeto\b/i;
+const PLAN = OUTPUT_SCHEMA.plan;
+const INDEX_LABEL = '.morph/specs/adrs/';
 const INDEX_FILE_RE = /^([a-z0-9][a-z0-9-]*)--(ADR-\d+)\.md$/;
 
 /** `admin/ADR-001` ↔ `admin--ADR-001.md`. */
@@ -40,61 +21,26 @@ const refOf = (name) => {
   return m ? `${m[1]}/${m[2]}` : null;
 };
 
-/**
- * The ADRs of one `decisions.md` marked as project-wide, each with its block.
- *
- * @param {string} content
- * @returns {Array<{ adr: string, title: string, body: string }>}
- */
-export function projectAdrs(content) {
-  const out = [];
-  let current = null; // { adr, title, level, marked, lines }
-  const close = () => {
-    if (current?.marked) out.push({ adr: current.adr, title: current.title, body: current.lines.join('\n').trim() });
-    current = null;
-  };
-
-  for (const line of String(content ?? '').split(/\r?\n/)) {
-    const adr = ADR_HEADING_RE.exec(line);
-    if (adr) {
-      close();
-      current = { adr: adr[2], title: adr[3], level: adr[1].length, marked: false, lines: [] };
-      continue;
-    }
-    const heading = ANY_HEADING_RE.exec(line);
-    if (current && heading && heading[1].length <= current.level) { close(); continue; }
-    if (!current) continue;
-    if (PROJECT_SCOPE_RE.test(line)) current.marked = true;
-    current.lines.push(line);
-  }
-  close();
-  return out;
-}
-
 function renderAdrFile({ ref, title, body }, feature) {
-  const decisions = `.morph/archive/${feature}/${OUTPUT_SCHEMA.decisions.phaseDir}/${OUTPUT_SCHEMA.decisions.filename}`;
+  const source = `.morph/archive/${feature}/${PLAN.phaseDir}/${PLAN.filename}`;
   return [
     '---',
     `adr: ${ref}`,
     `title: ${JSON.stringify(title)}`,
-    `source: ${decisions}`,
+    `source: ${source}`,
     '---',
     '',
     `# ${ref}: ${title}`,
     '',
-    '> Mantido pelo `morph-spec finish` — não edite à mão. Vale no projeto até que o `spec.md` de uma',
-    '> feature o revogue: por inteiro, e este arquivo sai; em parte, e `scope:` diz onde ele ainda vale.',
+    '> Mantido pelo `morph-spec finish` — não edite à mão. Vale no projeto até que o `plan.md` de uma',
+    '> feature o revogue em `### Conflitos com o acervo`: por inteiro, e este arquivo sai; em parte, e `scope:` diz onde ele ainda vale.',
     '',
     body,
     '',
   ].join('\n');
 }
 
-/**
- * The ADRs the index holds; `[]` when there is none or it cannot be read.
- *
- * @returns {Array<{ ref: string, file: string, title: string|null, scope: string|null }>}
- */
+/** `[]` when there is no index or it cannot be read. */
 export function readAdrIndex(cwd) {
   const dir = join(cwd, ADR_INDEX_PATHSPEC);
   try {
@@ -103,7 +49,7 @@ export function readAdrIndex(cwd) {
       const ref = refOf(file);
       if (!ref) return [];
       let content = '';
-      try { content = readFileSync(join(dir, file), 'utf8'); } catch { /* listed, unreadable */ }
+      try { content = readFileSync(join(dir, file), 'utf8'); } catch {}
       return [{ ref, file, title: readFrontmatterField(content, 'title'), scope: readFrontmatterField(content, 'scope') }];
     });
   } catch {
@@ -111,30 +57,21 @@ export function readAdrIndex(cwd) {
   }
 }
 
-/**
- * Apply a closing feature to the index: its project-wide ADRs enter, and the
- * ADR revocations its `spec.md` declared delete a file (total) or narrow it
- * (parcial).
- *
- * @param {string} cwd
- * @param {string} featureDir - the feature folder (already archived, at close time)
- * @param {Array<{ id: string, change: 'total'|'parcial', scope: string|null }>} revocations - ADR entries of `parseRevocations`
- * @returns {{ changed: boolean, added: string[], revoked: string[], narrowed: string[],
- *   problems: Array<{ id: string, reason: string, message: string }> }}
- */
-export function updateAdrIndex(cwd, featureDir, revocations = []) {
+/** An unreadable or absent plan touches nothing. */
+export function updateAdrIndex(cwd, featureDir) {
   const result = { changed: false, added: [], revoked: [], narrowed: [], problems: [] };
   const feature = basename(featureDir);
   const dir = join(cwd, ADR_INDEX_PATHSPEC);
 
-  let marked = [];
+  let plan = null;
   try {
-    const decisions = join(featureDir, OUTPUT_SCHEMA.decisions.phaseDir, OUTPUT_SCHEMA.decisions.filename);
-    if (existsSync(decisions)) marked = projectAdrs(readFileSync(decisions, 'utf8'));
-  } catch { /* unreadable decisions.md — nothing enters */ }
+    const planPath = join(featureDir, PLAN.phaseDir, PLAN.filename);
+    if (existsSync(planPath)) plan = parsePlan(readFileSync(planPath, 'utf8'));
+  } catch {}
+  if (!plan) return result;
 
-  for (const { adr, title, body } of marked) {
-    const ref = `${feature}/${adr}`;
+  for (const { id, title, body } of plan.adrs.filter((a) => a.scope === 'projeto')) {
+    const ref = `${feature}/${id}`;
     const path = join(dir, adrFileName(ref));
     const next = renderAdrFile({ ref, title, body }, feature);
     const existed = existsSync(path);
@@ -145,13 +82,15 @@ export function updateAdrIndex(cwd, featureDir, revocations = []) {
     if (!existed) result.added.push(ref);
   }
 
+  const { entries: revocations, problems } = parseRevocations(plan.conflicts?.text);
+  result.problems.push(...problems);
   for (const rev of revocations) {
     const path = join(dir, adrFileName(rev.id));
     if (!existsSync(path)) {
       result.problems.push({
         id: rev.id,
         reason: 'adr-not-indexed',
-        message: `${rev.id} não está no índice de ADRs ativos (${ADR_INDEX_PATHSPEC.replace(/\\/g, '/')}/) — nada a retirar; o decisions.md arquivado segue como história`,
+        message: `${rev.id} não está no índice de ADRs ativos (${INDEX_LABEL}) — nada a retirar; o plan.md arquivado segue como história`,
       });
       continue;
     }
@@ -167,3 +106,17 @@ export function updateAdrIndex(cwd, featureDir, revocations = []) {
 
   return result;
 }
+
+/** What the finish would fail to apply from the revocation table, reported while the plan can still change. */
+export function revocationWarnings(cwd, plan) {
+  const { entries, problems } = parseRevocations(plan.conflicts?.text);
+  const warnings = problems.map((p) => `### Conflitos com o acervo: ${p.message}`);
+  if (entries.length === 0) return warnings;
+  const indexed = new Set(readAdrIndex(cwd).map((a) => a.ref));
+  for (const e of entries) {
+    if (!indexed.has(e.id)) {
+      warnings.push(`### Conflitos com o acervo: ${e.id} não está no índice de ADRs ativos (${INDEX_LABEL}) — o finish não terá o que retirar`);
+    }
+  }
+  return warnings;
+}

package/src/lib/specs/design-seed.js

@@ -0,0 +1,18 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { templateSourcePath, writeIfAbsent } from '../../core/templates/template-seed.js';
+import { renderTemplateString } from '../../core/templates/template-renderer.js';
+import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
+
+export function seedDesignArtifacts(featureName, cwd = process.cwd()) {
+  const mockupsTemplate = readFileSync(templateSourcePath('ui-mockups', cwd), 'utf8');
+  const mockups = writeIfAbsent(
+    getAbsoluteOutputPath(cwd, featureName, 'uiMockups'),
+    renderTemplateString(mockupsTemplate, { FEATURE_NAME: featureName, DATE: new Date().toISOString().slice(0, 10) }),
+  );
+  const designSystem = writeIfAbsent(
+    join(cwd, '.morph', 'context', 'design-system.md'),
+    readFileSync(templateSourcePath('context-design-system', cwd), 'utf8'),
+  );
+  return { mockups, designSystem };
+}

package/src/lib/specs/frontmatter.js

@@ -0,0 +1,31 @@
+const FRONTMATTER_RE = /^(?---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/;
+
+/** Preserves every other line, the EOL style and the body; no frontmatter block → unchanged. `value` is written as-is. */
+export function setFrontmatterField(content, key, value) {
+  const m = FRONTMATTER_RE.exec(content);
+  if (!m || m.index !== 0) return content;
+
+  const [full, open, body, close] = m;
+  const eol = full.includes('\r\n') ? '\r\n' : '\n';
+  const fieldLine = new RegExp(`^${key}:[ \\t]*.*$`, 'm');
+  // Function replacer: a value carrying `$&` or `$1` is text, not a pattern.
+  const next = fieldLine.test(body)
+    ? body.replace(fieldLine, () => `${key}: ${value}`)
+    : `${body}${eol}${key}: ${value}`;
+
+  return open + next + close + content.slice(full.length);
+}
+
+/** `null` when absent; double-quoted values read as JSON strings, single-quoted as YAML (`''` is a quote). */
+export function readFrontmatterField(content, key) {
+  const m = FRONTMATTER_RE.exec(content);
+  if (!m || m.index !== 0) return null;
+  const line = new RegExp(`^${key}:[ \\t]*(.+?)[ \\t]*$`, 'm').exec(m[2]);
+  if (!line) return null;
+  const raw = line[1].trim();
+  if (raw.length >= 2 && raw.startsWith('"') && raw.endsWith('"')) {
+    try { return JSON.parse(raw); } catch { return raw; }
+  }
+  if (raw.length >= 2 && raw.startsWith("'") && raw.endsWith("'")) return raw.slice(1, -1).replace(/''/g, "'");
+  return raw;
+}

package/src/lib/specs/gfm-table.js

@@ -0,0 +1,11 @@
+/** A markdown table separator row: `|---|:--:|`, with or without the outer pipes. */
+export const SEPARATOR_ROW_RE = /^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)*\|?\s*$/;
+
+/** A line that belongs to a table: it carries an unescaped pipe (GFM does not require the leading one). */
+export const isTableLine = (line) => /(?<!\\)\|/.test(line);
+
+/** Splits on unescaped pipes, outer pipes optional; `\|` inside a cell is a literal pipe. */
+export function tableCells(row) {
+  const inner = row.trim().replace(/^\|/, '').replace(/(?<!\\)\|$/, '');
+  return inner.split(/(?<!\\)\|/).map((c) => c.replace(/\\\|/g, '|').trim());
+}

package/src/lib/specs/revocations.js

@@ -1,156 +1,85 @@
-/**
- * The plan's declaration of what a feature supersedes in the project's acervo:
- * the "UCs e ADRs que esta feature altera ou revoga" section of `spec.md`.
- *
- *   ## UCs e ADRs que esta feature altera ou revoga
- *
- *   | Id | Mudança | Substituto | Escopo em que o antigo ainda vale |
- *   |---|---|---|---|
- *   | UC-{nn} | parcial | UC-{nn} | {onde o antigo ainda vale} |
- *   | {feature}/ADR-{nnn} | total | — | — |
- *
- * Columns are positional, so the header wording is free. Parsing is pure: the
- * finish applies the entries (`acervo-lifecycle.js`), and `dag`/`usecase
- * check` report the problems while `spec.md` can still be edited — it freezes
- * at Gate 2, so a bad row found at close time can no longer be fixed there.
- *
- * Nothing ambiguous is applied: a row with any problem, and every row of an id
- * declared twice, stays out of `entries`. A table inside a code fence is an
- * example, never a declaration.
- */
+// plan-check reports the problems while the plan can still change, so nothing ambiguous reaches the finish.
 
-import { SEPARATOR_ROW_RE, UC_ID_RE, isTableLine, tableCells } from './acervo-format.js';
-
-export const REVOCATIONS_TITLE = 'UCs e ADRs que esta feature altera ou revoga';
+import { SEPARATOR_ROW_RE, isTableLine, tableCells } from './gfm-table.js';
 
 /** ADR numbers restart in every feature, so only `{feature}/ADR-{nnn}` is unambiguous. */
 export const ADR_REF_RE = /^[a-z0-9][a-z0-9-]*\/ADR-\d+$/;
 
-const HEADING_RE = /^(#{1,6})\s+(.+?)\s*#*\s*$/;
 const FENCE_RE = /^\s*(```|~~~)/;
-const ID_TOKEN_RE = /\b(?:UC|ADR)-\d+\b/;
-/** A list item: the shape a revocation takes when the author skips the table. */
+const REF_TOKEN_RE = /\b[a-z0-9][a-z0-9-]*\/ADR-\d+\b/;
 const LIST_ITEM_RE = /^\s*(?:[-*+]|\d+[.)])\s/;
-
 const CHANGES = new Map([['total', 'total'], ['parcial', 'parcial'], ['partial', 'parcial']]);
 
-/** `—`, `–`, `-` and an empty cell all mean "none". */
 const isNone = (cell) => /^(?:—|–|-)?$/.test(cell);
-
-/** Id-like cells tolerate the typography an author reaches for: `code` and **bold**. */
 const bare = (cell) => cell.replace(/^[`*]+|[`*]+$/g, '').trim();
 
-/**
- * The problems of one data row; `[]` = the row is applicable.
- * @returns {{ entry: object|null, problems: Array<{ id: string|null, reason: string, message: string }> }}
- */
 function readRow(line) {
   const problems = [];
   const problem = (id, reason, message) => problems.push({ id, reason, message });
 
   const row = tableCells(line);
-  if (row.length < 4) {
-    problem(null, 'malformed-row', `linha com ${row.length} coluna(s), esperado 4 (Id | Mudança | Substituto | Escopo): ${line.trim()}`);
+  if (row.length < 3) {
+    problem(null, 'malformed-row', `linha com ${row.length} coluna(s), esperado 3 (ADR | Mudança | Escopo): ${line.trim()}`);
     return { entry: null, problems };
   }
   const id = bare(row[0]);
-  const changeCell = bare(row[1]).toLowerCase();
-  const substitute = isNone(bare(row[2])) ? null : bare(row[2]);
-  const scope = isNone(row[3]) ? null : row[3];
+  const change = CHANGES.get(bare(row[1]).toLowerCase());
+  const scope = isNone(row[2]) ? null : row[2];
 
-  const kind = UC_ID_RE.test(id) ? 'uc' : ADR_REF_RE.test(id) ? 'adr' : null;
-  if (!kind) {
-    problem(id || null, 'malformed-id', `"${id}" não é um UC-{nn} nem um {feature}/ADR-{nnn}`);
+  if (!ADR_REF_RE.test(id)) {
+    problem(id || null, 'malformed-id', `"${id}" não é um {feature}/ADR-{nnn}`);
     return { entry: null, problems };
   }
-
-  const change = CHANGES.get(changeCell);
   if (!change) problem(id, 'malformed-change', `${id}: mudança "${bare(row[1])}" — use total ou parcial`);
-
-  if (kind === 'uc' && !substitute) {
-    problem(id, 'missing-substitute', `${id}: UC revogado precisa do substituto (UC-{nn}) — é o superseded_by do acervo`);
-  } else if (substitute && !(kind === 'uc' ? UC_ID_RE : ADR_REF_RE).test(substitute)) {
-    problem(id, 'malformed-substitute',
-      `${id}: substituto "${substitute}" — esperado ${kind === 'uc' ? 'UC-{nn}' : '{feature}/ADR-{nnn}'}`);
-  } else if (substitute === id) {
-    problem(id, 'self-substitute', `${id}: o substituto é o próprio ${id}`);
-  }
-
   if (change === 'parcial' && !scope) {
     problem(id, 'missing-scope', `${id}: revogação parcial precisa dizer onde o antigo ainda vale (coluna Escopo)`);
   } else if (change === 'total' && scope) {
     problem(id, 'scope-on-total', `${id}: revogação total com escopo "${scope}" — se o antigo ainda vale em algum lugar, a mudança é parcial`);
   }
 
-  return { entry: problems.length ? { id } : { kind, id, change, substitute, scope }, problems };
+  return { entry: problems.length ? { id } : { id, change, scope }, problems };
 }
 
-/**
- * @param {string} content - the whole `spec.md`
- * @returns {{
- *   declared: boolean,
- *   entries: Array<{ kind: 'uc'|'adr', id: string, change: 'total'|'parcial', substitute: string|null, scope: string|null }>,
- *   problems: Array<{ id: string|null, reason: string, message: string }>
- * }}
- *   `declared: false` — no section at all (a plan written before it existed).
- */
-export function parseRevocations(content) {
-  const lines = String(content ?? '').split(/\r?\n/);
-  const title = REVOCATIONS_TITLE.toLowerCase();
-
-  let start = -1;
-  let level = 0;
-  for (let i = 0; i < lines.length; i++) {
-    const h = HEADING_RE.exec(lines[i]);
-    if (h && h[2].toLowerCase().startsWith(title)) { start = i + 1; level = h[1].length; break; }
-  }
-  if (start === -1) return { declared: false, entries: [], problems: [] };
-
-  let end = lines.length;
-  for (let i = start; i < lines.length; i++) {
-    const h = HEADING_RE.exec(lines[i]);
-    if (h && h[1].length <= level) { end = i; break; }
-  }
-
+export function parseRevocations(conflicts) {
   const problems = [];
-  const rows = []; // { id, entry } in order, applicable or not
+  const rows = [];
   let fenced = false;
-  let separatorSeen = false;
-  let tableLines = 0;
+  let table = null;
 
-  for (const line of lines.slice(start, end)) {
-    if (FENCE_RE.test(line)) { fenced = !fenced; continue; }
+  for (const line of String(conflicts ?? '').split(/\r?\n/)) {
+    if (FENCE_RE.test(line)) { fenced = !fenced; table = null; continue; }
     if (fenced) continue;
 
     if (!isTableLine(line)) {
-      const stray = LIST_ITEM_RE.test(line) ? ID_TOKEN_RE.exec(line) : null;
+      table = null;
+      const stray = LIST_ITEM_RE.test(line) ? REF_TOKEN_RE.exec(line) : null;
       if (stray) {
         problems.push({ id: stray[0], reason: 'outside-table',
-          message: `${stray[0]} aparece fora da tabela — só as linhas da tabela são aplicadas no finish` });
+          message: `${stray[0]} aparece fora da tabela ADR | Mudança | Escopo — só as linhas da tabela são aplicadas no finish` });
       }
       continue;
     }
-    tableLines++;
-    if (SEPARATOR_ROW_RE.test(line)) { separatorSeen = true; continue; }
-    if (!separatorSeen) continue; // the header row: its wording is free
-
+    if (!table) {
+      table = { revocations: bare(tableCells(line)[0] ?? '').toLowerCase() === 'adr', separatorSeen: false };
+      continue;
+    }
+    if (!table.revocations) continue;
+    if (!table.separatorSeen) {
+      if (SEPARATOR_ROW_RE.test(line)) { table.separatorSeen = true; continue; }
+      problems.push({ id: null, reason: 'unreadable-table',
+        message: 'tabela de revogação ilegível — falta a linha separadora (|---|---|---|) depois do cabeçalho; nenhuma linha foi lida' });
+      table.revocations = false;
+      continue;
+    }
     const { entry, problems: rowProblems } = readRow(line);
     problems.push(...rowProblems);
     if (entry) rows.push(entry);
   }
 
-  if (tableLines > 0 && !separatorSeen) {
-    problems.push({ id: null, reason: 'unreadable-table',
-      message: 'tabela ilegível — falta a linha separadora (|---|---|---|---) depois do cabeçalho; nenhuma linha foi lida' });
-  }
-
-  // An id declared twice is ambiguous as a whole: none of its rows applies.
   const count = new Map();
   for (const r of rows) count.set(r.id, (count.get(r.id) ?? 0) + 1);
   for (const [id, n] of count) {
     if (n > 1) problems.push({ id, reason: 'duplicate-id', message: `${id} aparece em ${n} linhas — nenhuma foi aplicada; deixe uma só` });
   }
-  const entries = rows.filter((r) => r.kind && count.get(r.id) === 1);
-
-  return { declared: true, entries, problems };
+  return { entries: rows.filter((r) => r.change && count.get(r.id) === 1), problems };
 }