@polymorphism-tech/morph-spec 8.35.0 → 8.36.0

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

@@ -0,0 +1,200 @@
+/**
+ * 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 };
+}

package/src/lib/specs/usecase-check.js

@@ -3,8 +3,15 @@
  *
  * This is the mechanical half of the use-case layer. Whether a post-condition is
  * *observable in a test* is semantic and stays with Gate 2 and the evaluator —
- * no checker can decide it. What IS decidable is the plumbing, and the plumbing
- * is where the requirement actually leaked before:
+ * no checker can decide it. A narrower question IS decidable, though: a
+ * post-condition phrased as "nenhum arquivo/grep/binário…" describes an
+ * ARTIFACT, not behaviour, and that is a lexical warning `done-criteria-check.js`
+ * raises against `dag`. A `> [!note] Por que artefato:` callout right below the
+ * post-condition is how a use case justifies keeping it literal — this module
+ * parses that callout (`parseArtifactJustifications`) so the lexical checker
+ * can skip the labels an author already defended. What IS decidable beyond
+ * that is the plumbing, and the plumbing is where the requirement actually
+ * leaked before:
  *
  *   - a task pointing at a use case that does not exist  → ERROR (a broken plan)
  *   - a post-condition no task ever mentions            → warning (orphan)
@@ -37,11 +44,117 @@ import { useCaseId } from './usecase-promoter.js';
  */
 const POSTCONDITION_RE = /^[ \t]*[-*][ \t]*\*\*(P\d+)\*\*[ \t]*[—–-][ \t]*(.+?)[ \t]*$/gm;
 
+/**
+ * Single-line form of `POSTCONDITION_RE`, used to walk a document line by line.
+ * DERIVED, never retyped: two hand copies drift, and a bullet shape only one
+ * of them accepts makes its justification stop working in silence.
+ */
+const POSTCONDITION_LINE_RE = new RegExp(POSTCONDITION_RE.source);
+
+/** Any bullet (not just a labelled post-condition) — closes an open block. */
+const BULLET_LINE_RE = /^\s*[-*]\s/;
+
+/** A markdown heading — closes an open block. */
+const HEADING_LINE_RE = /^\s*#/;
+
+/** A blockquote line — it belongs to a callout, never to the post-condition text. */
+const BLOCKQUOTE_LINE_RE = /^\s*>/;
+
+/**
+ * The justification marker, ONE spelling for both forms: the callout below a
+ * use-case post-condition (here) and the inline form in a task's own
+ * `doneCriteria` (`done-criteria-check.js`). Tolerant of spacing — including
+ * before the colon — because the spacing is a typing accident, not a decision.
+ */
+export const ARTIFACT_MARKER_RE = /por\s+que\s+artefato\s*:/i;
+
+/**
+ * The artifact-justification callout. It must live on its OWN line right
+ * below the post-condition — never inline, because `POSTCONDITION_RE`
+ * captures to end of line and that text travels literally into `doneCriteria`.
+ * The foldable forms (`[!note]-`, `[!note]+`) are the same callout.
+ */
+const ARTIFACT_NOTE_RE = new RegExp(String.raw`^\s*>\s*\[!note\][-+]?\s*` + ARTIFACT_MARKER_RE.source, 'i');
+
 /** Case-folded, whitespace-collapsed form used for containment tests. */
-function normalize(text) {
+export function normalize(text) {
   return String(text).toLowerCase().replace(/\s+/g, ' ').trim();
 }
 
+/**
+ * Parse every post-condition of a use-case document as a BLOCK: its full text
+ * (first line + wrapped continuation) and whether a `> [!note] Por que
+ * artefato:` callout justifies it.
+ *
+ * A post-condition bullet opens a block for its label; continuation lines
+ * (wrapped post-condition text) are appended to the block's text; the block
+ * closes at a blank line, a new bullet, or a heading — same shape as a
+ * post-condition itself, so a callout separated by a blank line or living
+ * under the NEXT bullet never counts.
+ *
+ * Blockquote lines are never post-condition text: they belong to the callout,
+ * and a justification wrapped over two `>` lines is ordinary Obsidian style.
+ * Once the blockquote opens, a following line without `>` is the quote's lazy
+ * continuation (CommonMark), so it stays out of the text too. Appending either
+ * to the post-condition produced a text no `doneCriteria` ever carries.
+ *
+ * A repeated label counts once — first wins, as in `parsePostConditions`.
+ *
+ * @param {string} content
+ * @returns {Map<string, { text: string, justified: boolean }>}
+ */
+export function parsePostConditionBlocks(content) {
+  const blocks = new Map();
+  let current = null; // { label, textParts: string[], justified: boolean, quoted: boolean }
+
+  const closeBlock = () => {
+    if (current && !blocks.has(current.label)) {
+      blocks.set(current.label, { text: current.textParts.join(' ').trim(), justified: current.justified });
+    }
+    current = null;
+  };
+
+  for (const line of String(content).split(/\r?\n/)) {
+    const bulletMatch = line.match(POSTCONDITION_LINE_RE);
+    if (bulletMatch) {
+      closeBlock();
+      current = { label: bulletMatch[1], textParts: [bulletMatch[2].trim()], justified: false, quoted: false };
+      continue;
+    }
+    if (!current) continue; // prose outside any post-condition block
+
+    if (line.trim() === '' || HEADING_LINE_RE.test(line) || BULLET_LINE_RE.test(line)) {
+      closeBlock();
+      continue;
+    }
+    if (BLOCKQUOTE_LINE_RE.test(line)) {
+      if (ARTIFACT_NOTE_RE.test(line)) current.justified = true;
+      current.quoted = true;
+      continue; // callout lines are metadata, never part of the post-condition text
+    }
+    if (current.quoted) continue; // lazy continuation of the blockquote
+    current.textParts.push(line.trim());
+  }
+  closeBlock();
+
+  return blocks;
+}
+
+/**
+ * The justified post-conditions of a use-case document — the labels whose
+ * block (see `parsePostConditionBlocks`) carried the callout.
+ *
+ * @param {string} content
+ * @returns {Map<string, string>} label → full post-condition text (first line + continuation)
+ */
+export function parseArtifactJustifications(content) {
+  const result = new Map();
+  for (const [label, block] of parsePostConditionBlocks(content)) {
+    if (block.justified) result.set(label, block.text);
+  }
+  return result;
+}
+
 /**
  * Parse one use-case document into its post-conditions.
  *
@@ -63,8 +176,12 @@ export function parsePostConditions(content) {
 /**
  * Read every use case of a feature, keyed by ID.
  *
+ * `fullText` maps EVERY label to its whole block (first line + wrapped
+ * continuation); `postConditions[].text` stays the first line, which is what
+ * the literal-carry check compares against.
+ *
  * @param {string} usecasesDir - absolute path to `2-plan/usecases`
- * @returns {Map<string, { id: string, file: string, postConditions: Array<{label: string, text: string}> }>}
+ * @returns {Map<string, { id: string, file: string, postConditions: Array<{label: string, text: string}>, artifactJustified: Map<string, string>, fullText: Map<string, string> }>}
  */
 export function loadUseCases(usecasesDir) {
   const byId = new Map();
@@ -82,7 +199,14 @@ export function loadUseCases(usecasesDir) {
     if (!id || !file.endsWith('.md')) continue;
     try {
       const content = readFileSync(join(usecasesDir, file), 'utf8');
-      byId.set(id, { id, file, postConditions: parsePostConditions(content) });
+      const blocks = parsePostConditionBlocks(content);
+      const artifactJustified = new Map();
+      const fullText = new Map();
+      for (const [label, block] of blocks) {
+        fullText.set(label, block.text);
+        if (block.justified) artifactJustified.set(label, block.text);
+      }
+      byId.set(id, { id, file, postConditions: parsePostConditions(content), artifactJustified, fullText });
     } catch { /* one unreadable use case must not sink the rest */ }
   }
   return byId;