@polymorphism-tech/morph-spec 8.46.0 → 9.0.0

package/src/lib/specs/acervo-lifecycle.js

@@ -1,264 +0,0 @@
-/**
- * Lifecycle of the project's acervo: a use case stops being the current
- * behaviour when a later feature supersedes it.
- *
- *   status: superseded
- *   superseded_by: UC-589
- *   scope: "vitrine pública, fora de `.morph-admin-shell`"    ← only when partial
- *
- * Three roles live here:
- *   - the ONE rule for that frontmatter (`supersessionProblems`) — the check
- *     reads it, and the writer below only ever produces what it accepts;
- *   - the close-time writer (`applySpecRevocations`): what the feature's
- *     `spec.md` declared it revokes lands on `.morph/specs/usecases/` and on
- *     the ADR index, fail-open like the promotion it follows;
- *   - the plan-time check (`checkLifecycle`), shared by `dag` and `usecase
- *     check`, run while `spec.md` can still be fixed.
- */
-
-import { readFileSync, writeFileSync } from 'fs';
-import { join } from 'path';
-import { OUTPUT_SCHEMA } from '../../core/paths/output-schema.js';
-import {
-  SPECS_USECASES_PATHSPEC,
-  hasFrontmatter,
-  readFrontmatterField,
-  removeFrontmatterField,
-  setFrontmatterField,
-} from './usecase-promoter.js';
-import { SUPERSEDED, UC_ID_RE, useCaseFilesById } from './acervo-format.js';
-import { parseRevocations } from './revocations.js';
-import { ADR_INDEX_PATHSPEC, readAdrIndex, updateAdrIndex } from './adr-index.js';
-
-export { SUPERSEDED };
-
-const UC = OUTPUT_SCHEMA.usecases;
-const ACERVO_LABEL = SPECS_USECASES_PATHSPEC.replace(/\\/g, '/');
-const ADR_INDEX_LABEL = `${ADR_INDEX_PATHSPEC.replace(/\\/g, '/')}/`;
-
-/** @returns {{ status: string|null, supersededBy: string|null, scope: string|null }} */
-export function lifecycleOf(content) {
-  return {
-    status: readFrontmatterField(content, 'status'),
-    supersededBy: readFrontmatterField(content, 'superseded_by'),
-    scope: readFrontmatterField(content, 'scope'),
-  };
-}
-
-/**
- * The rule for a use case's supersession frontmatter.
- *
- * @param {string} content
- * @param {string} id - the use case's own id
- * @returns {string[]} one line per problem; `[]` = well formed
- */
-export function supersessionProblems(content, id) {
-  const { status, supersededBy, scope } = lifecycleOf(content);
-  const problems = [];
-  if (status === SUPERSEDED) {
-    if (!supersededBy) problems.push('status: superseded sem superseded_by');
-    else if (!UC_ID_RE.test(supersededBy)) problems.push(`superseded_by "${supersededBy}" não é um UC-{nn}`);
-    else if (supersededBy === id) problems.push('superseded_by aponta para o próprio use case');
-  } else if (supersededBy !== null || scope !== null) {
-    problems.push(`${supersededBy !== null ? 'superseded_by' : 'scope'} sem status: superseded`);
-  }
-  if (scope !== null && !String(scope).trim()) problems.push('scope vazio');
-  return problems;
-}
-
-function readOrNull(path) {
-  try { return readFileSync(path, 'utf8'); } catch { return null; }
-}
-
-const specPathOf = (featureDir) => join(featureDir, OUTPUT_SCHEMA.spec.phaseDir, OUTPUT_SCHEMA.spec.filename);
-
-/** A finished feature cannot be re-closed: the fix is the next feature's revocation row. */
-const FIX_NEXT_TIME = 'corrija a linha na seção de revogações do spec.md — a feature já arquivada não é reprocessada, ' +
-  'então a revogação corrigida entra no spec.md da próxima feature';
-
-/**
- * Mark the acervo use cases the entries revoke. Runs after the promotion, so
- * the acervo already holds every substitute this feature brought — except the
- * ones the promotion refused, which only LOOK present (the file under that id
- * belongs to another feature).
- *
- * @returns {{ superseded: Array<{id: string, file: string, supersededBy: string, scope?: string}>,
- *   problems: Array<{id: string, reason: string, message: string}> }}
- */
-function supersedeUseCases(cwd, entries, refusedIds) {
-  const superseded = [];
-  const problems = [];
-  if (!entries.length) return { superseded, problems };
-
-  const dir = join(cwd, SPECS_USECASES_PATHSPEC);
-  const files = useCaseFilesById(dir);
-  const problem = (id, reason, message) => problems.push({ id, reason, message });
-
-  for (const e of entries) {
-    const targets = files.get(e.id) ?? [];
-    if (targets.length === 0) {
-      problem(e.id, 'not-in-acervo', `${e.id} não está no acervo (${ACERVO_LABEL}/) — nada foi marcado; ${FIX_NEXT_TIME}`);
-      continue;
-    }
-    if (targets.length > 1) {
-      problem(e.id, 'duplicate-in-acervo',
-        `${e.id} tem ${targets.length} arquivos no acervo (${targets.join(', ')}) — nenhum foi marcado; o acervo precisa de um arquivo por UC`);
-      continue;
-    }
-    if (refusedIds.has(e.substitute)) {
-      problem(e.id, 'substitute-refused',
-        `o substituto ${e.substitute} de ${e.id} não foi promovido (colisão de numeração) — ${e.id} não foi marcado`);
-      continue;
-    }
-    if (!files.has(e.substitute)) {
-      problem(e.id, 'substitute-not-found',
-        `o substituto ${e.substitute} de ${e.id} não está no acervo — ${e.id} não foi marcado; ${FIX_NEXT_TIME}`);
-      continue;
-    }
-
-    const file = targets[0];
-    try {
-      const path = join(dir, file);
-      const before = readFileSync(path, 'utf8');
-      if (!hasFrontmatter(before)) {
-        problem(e.id, 'no-frontmatter', `${ACERVO_LABEL}/${file} não tem frontmatter — o status não foi aplicado`);
-        continue;
-      }
-      let next = setFrontmatterField(before, 'status', SUPERSEDED);
-      next = setFrontmatterField(next, 'superseded_by', e.substitute);
-      // JSON-quoted: free text with `: ` or a leading backtick breaks a bare YAML scalar.
-      next = e.scope
-        ? setFrontmatterField(next, 'scope', JSON.stringify(e.scope))
-        : removeFrontmatterField(next, 'scope');
-      if (next !== before) writeFileSync(path, next, 'utf8');
-      superseded.push({ id: e.id, file, supersededBy: e.substitute, ...(e.scope ? { scope: e.scope } : {}) });
-    } catch {
-      problem(e.id, 'unwritable', `${ACERVO_LABEL}/${file} não pôde ser lido/gravado — o status não foi aplicado`);
-    }
-  }
-  return { superseded, problems };
-}
-
-/**
- * Apply, at close time, what the feature's `spec.md` declared it revokes.
- * Fail-open: nothing here may refuse the close; what did not apply comes back
- * in `problems`, next to the row's own parse problems.
- *
- * @param {string} cwd        - project root that owns `.morph/specs/`
- * @param {string} featureDir - the feature folder (already moved to the archive)
- * @param {{ refused?: Array<{ id: string }> }} [promotion] - the promotion's result, run just before
- * @returns {{ superseded: Array<{id: string, file: string, supersededBy: string, scope?: string}>,
- *   adrIndex: ReturnType<typeof updateAdrIndex>|null,
- *   problems: Array<{id: string|null, reason: string, message: string}> }}
- */
-export function applySpecRevocations(cwd, featureDir, promotion = {}) {
-  const out = { superseded: [], adrIndex: null, problems: [] };
-
-  const spec = readOrNull(specPathOf(featureDir));
-  const parsed = spec === null ? { entries: [], problems: [] } : parseRevocations(spec);
-  out.problems.push(...parsed.problems);
-
-  try {
-    const refusedIds = new Set((promotion.refused ?? []).map((r) => r.id));
-    const uc = supersedeUseCases(cwd, parsed.entries.filter((e) => e.kind === 'uc'), refusedIds);
-    out.superseded = uc.superseded;
-    out.problems.push(...uc.problems);
-  } catch { /* fail-open */ }
-
-  try {
-    out.adrIndex = updateAdrIndex(cwd, featureDir, parsed.entries.filter((e) => e.kind === 'adr'));
-    out.problems.push(...out.adrIndex.problems);
-  } catch { /* fail-open */ }
-
-  return out;
-}
-
-/**
- * Plan-time check of a feature against the acervo's lifecycle.
- *
- * Warnings only, never errors: a superseded use case is a question for the
- * plan, and the revocation rows are re-reported at close time anyway.
- *
- * @param {{ cwd: string, featureDir: string, tasksData?: object|null }} input
- * @returns {{ warnings: string[] }}
- */
-export function checkLifecycle({ cwd, featureDir, tasksData = null }) {
-  const warnings = [];
-  const acervoDir = join(cwd, SPECS_USECASES_PATHSPEC);
-  const ownDir = join(featureDir, UC.phaseDir, UC.dirname);
-  const acervo = useCaseFilesById(acervoDir);
-  const own = useCaseFilesById(ownDir);
-
-  const ownLife = new Map();
-  for (const [id, files] of own) {
-    const file = files[files.length - 1];
-    const content = readOrNull(join(ownDir, file));
-    if (content === null) continue;
-    ownLife.set(id, lifecycleOf(content));
-    for (const p of supersessionProblems(content, id)) warnings.push(`2-plan/usecases/${file}: ${p}`);
-  }
-
-  // The acervo can hold hundreds of use cases: read only the ones this plan touches.
-  const acervoLife = new Map();
-  const acervoOf = (id) => {
-    if (acervoLife.has(id)) return acervoLife.get(id);
-    const files = acervo.get(id) ?? [];
-    if (files.length > 1) warnings.push(`${ACERVO_LABEL}/: ${id} tem ${files.length} arquivos (${files.join(', ')}) — o acervo precisa de um arquivo por UC`);
-    const file = files[files.length - 1];
-    const content = file ? readOrNull(join(acervoDir, file)) : null;
-    const life = content === null ? null : lifecycleOf(content);
-    if (content !== null) {
-      for (const p of supersessionProblems(content, id)) warnings.push(`${ACERVO_LABEL}/${file}: ${p}`);
-    }
-    acervoLife.set(id, life);
-    return life;
-  };
-
-  const spec = readOrNull(specPathOf(featureDir));
-  const rev = spec === null ? { entries: [], problems: [] } : parseRevocations(spec);
-  for (const p of rev.problems) warnings.push(`spec.md, revogações: ${p.message}`);
-
-  const revokedHere = new Map();
-  let indexedAdrs = null;
-  for (const e of rev.entries) {
-    if (e.kind === 'adr') {
-      indexedAdrs ??= new Set(readAdrIndex(cwd).map((r) => r.ref));
-      if (!indexedAdrs.has(e.id)) {
-        warnings.push(`spec.md, revogações: ${e.id} não está no índice de ADRs ativos (${ADR_INDEX_LABEL}) — o finish não terá o que retirar`);
-      }
-      continue;
-    }
-    revokedHere.set(e.id, e);
-    if (!acervo.has(e.id)) {
-      warnings.push(`spec.md, revogações: ${e.id} não está no acervo (${ACERVO_LABEL}/) — o finish não terá o que marcar`);
-    } else {
-      acervoOf(e.id);
-    }
-    if (!acervo.has(e.substitute) && !own.has(e.substitute)) {
-      warnings.push(`spec.md, revogações: o substituto ${e.substitute} de ${e.id} não existe no acervo nem em 2-plan/usecases/ — o finish não aplicará a linha`);
-    }
-  }
-
-  const tasks = Array.isArray(tasksData?.tasks) ? tasksData.tasks : [];
-  for (const task of tasks) {
-    const id = task?.usecase;
-    if (!id) continue;
-    const inAcervo = acervoOf(id);
-    const inOwn = ownLife.get(id);
-    const here = revokedHere.get(id);
-
-    let where = null;
-    if (inAcervo?.status === SUPERSEDED) where = { src: 'está superseded no acervo', ...inAcervo };
-    else if (inOwn?.status === SUPERSEDED) where = { src: 'está superseded na cópia da feature', ...inOwn };
-    else if (here) where = { src: 'é revogado por esta feature (spec.md)', supersededBy: here.substitute, scope: here.scope };
-    if (!where) continue;
-
-    const by = where.supersededBy;
-    const detail = [by ? `substituto: ${by}` : 'sem substituto declarado', where.scope ? `ainda vale em: ${where.scope}` : null]
-      .filter(Boolean).join('; ');
-    const advice = where.scope ? 'confira que a task realiza a parte que ainda vale' : by ? `cite ${by}` : 'confira o acervo';
-    warnings.push(`${task.id}.usecase → ${id} ${where.src} (${detail}) — ${advice}`);
-  }
-
-  return { warnings };
-}

package/src/lib/specs/done-criteria-check.js

@@ -1,200 +0,0 @@
-/**
- * Lexical heuristic: does a task's `doneCriteria` describe an ARTIFACT (a
- * file, a grep, a binary) instead of behaviour observable at runtime?
- *
- * A literal `doneCriteria` travels verbatim into the test that verifies it
- * (`morph-implement` copies it, never paraphrases). A use-case post-condition
- * shaped like "nenhum arquivo em X contém Y" — even a literal `grep` command —
- * becomes a test that reads file text instead of exercising behaviour. This
- * is a WARNING, never an error: `dag`'s exit code never changes because of
- * it, the same way `checkUseCases`'s coverage/literalness findings do not.
- *
- * Runs over EVERY task, unlike `usecase-check.js#checkUseCases` (which
- * short-circuits when the feature has no use cases): a task's own
- * `doneCriteria` can describe an artifact with no use case in sight, and
- * that must still be caught. This is why it lives in its own file — it is a
- * standalone lexical pass, not wiring between use cases and tasks.
- *
- * Two ways a match is silenced:
- *   - a task WITHOUT a use case can justify itself inline, with
- *     `Por que artefato: …` anywhere in its own `doneCriteria`. A task WITH a
- *     use case never can — it justifies in the use case, otherwise the marker
- *     would silence every post-condition it carries at once;
- *   - a task carrying a use-case post-condition literally is silenced only
- *     if THAT post-condition was justified in the use case document (the
- *     `> [!note] Por que artefato:` callout `usecase-check.js` parses).
- * Justified text is removed from the task's `doneCriteria` before scanning —
- * not skipped as a whole task — so a justified P1 never silences an
- * unjustified P2 carried in the same `doneCriteria`. The scan runs on the
- * whitespace-collapsed text with its CASE PRESERVED: an uppercase format
- * acronym (`arquivo em CSV`) is the only thing that tells an export from a
- * directory (`arquivo em src`), and lowercasing first would erase it.
- */
-
-import { ARTIFACT_MARKER_RE, loadUseCases, normalize } from './usecase-check.js';
-
-/**
- * Case-insensitive spelling of `word` inside a regex that must stay
- * case-SENSITIVE elsewhere — Node 18 has no inline `(?i:…)` modifier.
- */
-const anyCase = (word) => [...word].map((c) => {
-  const lo = c.toLowerCase();
-  const up = c.toUpperCase();
-  return lo === up ? c : `[${lo}${up}]`;
-}).join('');
-
-/**
- * What follows "arquivo em" in a behavioural export criterion ("exporta o
- * arquivo em CSV", "salva o arquivo em formato aberto"): an uppercase file
- * format acronym or the word `formato`. Case-sensitive on purpose — `src`,
- * `docs` or `lib` after "arquivo em" are places, and places are artifacts.
- */
-const FORMAT_TOKEN = String.raw`\s+(?:[A-Z]{2,5}(?![\p{L}\d_])|${anyCase('formato')}(?![\p{L}]))`;
-
-/**
- * Vocabulary of artifact-shaped phrasing. `term` is the label surfaced in
- * warnings and cited by the `morph-plan` skill prose — keep it stable, a
- * later parity test imports it verbatim.
- *
- * Unicode lookarounds, never `\b`: in JS, `\b` does not treat accented
- * letters (é, á, ó…) as word characters, so it would false-boundary inside
- * "não" or "binário".
- */
-export const ARTIFACT_VOCABULARY = [
-  { term: 'grep',                        re: /(?<![\p{L}\d_])grep(?![\p{L}\d_])/iu },
-  { term: 'contém a string',             re: /cont[ée]m\s+as?\s+strings?/iu },
-  { term: 'o binário',                   re: /(?<![\p{L}])o\s+bin[áa]rio(?![\p{L}])/iu },
-  { term: 'nenhum arquivo',              re: /(?<![\p{L}])nenhum\s+arquivo(?![\p{L}])/iu },
-  {
-    term: 'arquivo/pasta/diretório em',
-    re: new RegExp(
-      String.raw`(?<![\p{L}])(?:${anyCase('arquivo')}|${anyCase('pasta')}|${anyCase('diret')}[óoÓO]${anyCase('rio')})` +
-      String.raw`[sS]?\s+${anyCase('em')}(?![\p{L}])(?!${FORMAT_TOKEN})`,
-      'u',
-    ),
-  },
-  { term: 'glob **/',                    re: /\*\*\/|\/\*\*/ },
-];
-
-/**
- * Vocabulary terms matched in `text`, in vocabulary order, each at most once.
- *
- * @param {string} text
- * @returns {string[]}
- */
-export function findArtifactTerms(text) {
-  const s = String(text ?? '');
-  const found = [];
-  for (const { term, re } of ARTIFACT_VOCABULARY) {
-    if (re.test(s)) found.push(term);
-  }
-  return found;
-}
-
-/** Whitespace-collapsed, case PRESERVED — `normalize` without the lowercasing. */
-function collapse(text) {
-  return String(text).replace(/\s+/g, ' ').trim();
-}
-
-/**
- * Remove every case-insensitive occurrence of `needle` (already normalized)
- * from `text`, keeping the case of what remains. Relies on `text` and its
- * lowercase form being index-aligned — the caller guarantees it.
- */
-function cut(text, needle) {
-  if (!needle) return text;
-  const lower = text.toLowerCase();
-  let out = '';
-  let from = 0;
-  let at;
-  while ((at = lower.indexOf(needle, from)) !== -1) {
-    out += `${text.slice(from, at)} `;
-    from = at + needle.length;
-  }
-  return out + text.slice(from);
-}
-
-/**
- * Flag every task whose `doneCriteria` describes an artifact rather than
- * behaviour, after removing use-case text the author already justified.
- *
- * Fail-open: a missing `usecasesDir` still checks every task (it just has no
- * justifications or post-conditions to consult); a malformed `tasksData`
- * (no `tasks` array) or a non-string `doneCriteria` never throws.
- *
- * @param {Object} tasksData - parsed tasks.json
- * @param {string} usecasesDir - absolute path to `2-plan/usecases`
- * @returns {{ warnings: string[], flagged: Array<{ task: string, usecase: string|null, labels: string[], terms: string[] }>, checked: true }}
- */
-export function checkArtifactCriteria(tasksData, usecasesDir) {
-  const warnings = [];
-  const flagged = [];
-  const tasks = Array.isArray(tasksData?.tasks) ? tasksData.tasks : [];
-
-  let byId = new Map();
-  if (typeof usecasesDir === 'string') {
-    try { byId = loadUseCases(usecasesDir); } catch { byId = new Map(); }
-  }
-
-  for (const task of tasks) {
-    if (typeof task?.doneCriteria !== 'string') continue;
-
-    let D = collapse(task.doneCriteria);
-    if (!D) continue;
-    // `cut` needs `D` index-aligned with its lowercase form. The rare letter
-    // whose lowercase is longer (`İ`) breaks that; fall back to the lowercase
-    // text, which only costs the format-acronym exception for that task.
-    if (D.toLowerCase().length !== D.length) D = D.toLowerCase();
-
-    // Inline justification is for tasks WITHOUT a use case (morph-plan: "Task
-    // sem `usecase` justifica no próprio doneCriteria"). On a use-case task it
-    // would silence every post-condition carried, justified or not.
-    if (!task.usecase && ARTIFACT_MARKER_RE.test(D)) continue;
-
-    const uc = task.usecase ? byId.get(task.usecase) : null;
-    const unjustifiedLabels = [];
-
-    if (uc) {
-      // Remove justified post-condition text first, so its own vocabulary
-      // hits (if any) never surface — and so it cannot mask what remains.
-      // A wrapped post-condition is removed in both forms a plan legitimately
-      // carries: the whole block, or only its first line (what `checkUseCases`
-      // treats as THE post-condition). Longest first.
-      for (const pc of uc.postConditions) {
-        if (!uc.artifactJustified.has(pc.label)) continue;
-        for (const text of [uc.artifactJustified.get(pc.label), pc.text]) {
-          D = cut(D, normalize(text));
-        }
-      }
-      // Among what is left, name the unjustified post-conditions actually
-      // carried into this doneCriteria AND that themselves read as artifact —
-      // judged on the whole block, since a wrapped post-condition can carry
-      // its vocabulary on the continuation line.
-      const carried = D.toLowerCase();
-      for (const pc of uc.postConditions) {
-        if (uc.artifactJustified.has(pc.label)) continue;
-        const needle = normalize(pc.text);
-        const block = uc.fullText.get(pc.label) ?? pc.text;
-        if (needle && carried.includes(needle) && findArtifactTerms(block).length > 0) {
-          unjustifiedLabels.push(pc.label);
-        }
-      }
-    }
-
-    const terms = findArtifactTerms(D);
-    if (terms.length === 0) continue;
-
-    const quoted = terms.join(', ');
-    const message = unjustifiedLabels.length > 0
-      ? `${task.id}.doneCriteria descreve artefato, não comportamento ("${quoted}") — ` +
-        `reescreva ${task.usecase} ${unjustifiedLabels.join('/')} como efeito observável em runtime, ` +
-        `ou justifique com "> [!note] Por que artefato:" na linha abaixo dela`
-      : `${task.id}.doneCriteria descreve artefato, não comportamento ("${quoted}") — ` +
-        `reescreva como efeito observável em runtime, ou acrescente "Por que artefato: …" ao próprio critério`;
-
-    warnings.push(message);
-    flagged.push({ task: task.id, usecase: task.usecase || null, labels: unjustifiedLabels, terms });
-  }
-
-  return { warnings, flagged, checked: true };
-}