wizz-method 2.15.0 → 2.17.0

package/tools/hooks/wizz-feature-lib.js

@@ -0,0 +1,414 @@
+// wizz-feature-lib.js — funções puras de feature, artefato e layout.
+//
+// Fonte de verdade: wizz-method/tools/hooks/. Não é hook registrado: é a
+// biblioteca que os hooks (session-rules, wizz-router-enforce,
+// wizz-artifact-guard) e as CLIs (wizz-feature, wizz-arrumar) dividem. Mora
+// AQUI porque tudo em tools/hooks/ viaja junto: o installer copia a pasta
+// inteira para `_wizz/hooks/` e o `sync:global` para `~/.claude/hooks/`.
+//
+// Sem dependência de pacote de propósito (roda fora do node_modules do repo):
+// o YAML do config é lido com parser de chave única, que é tudo o que precisa.
+// Toda leitura é fail-open: config ausente ou ilegível vira "sem valor".
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Branches que NUNCA viram feature: são linha principal, não trabalho nomeado.
+const TRUNK = new Set(['main', 'master', 'develop', 'dev', 'staging', 'stage', 'prod', 'production', 'trunk', 'default', 'release']);
+
+// Branch de release/versão não é feature: nomeia um corte do produto, não um trabalho.
+const RELEASE_PREFIX = /^(release|rc|v)[/-]/i;
+
+// Prefixos de convenção que descrevem o TIPO do trabalho, não a feature.
+const TYPE_PREFIX = /^(feat|feature|fix|bugfix|hotfix|chore|refactor|docs|test|perf|ci|build|style)[/-]/i;
+
+// Tipos de artefato com nome padronizado `<tipo>-<slug>.md` e a pasta de cada um.
+// `roteiro` (aplicação + rollback) vai para o conhecimento do projeto, não para
+// os artefatos: é o que alguém reabre no dia do deploy, meses depois.
+const ARTIFACT_TYPES = {
+  spec: 'planning',
+  plano: 'planning',
+  auditoria: 'planning',
+  story: 'implementation',
+  review: 'implementation',
+  roteiro: 'knowledge',
+};
+
+const STATUS = ['rascunho', 'aprovado', 'implementado', 'no-ar'];
+
+// Artefato de projeto inteiro: fica na raiz das pastas de artefato, nunca numa feature.
+const PROJECT_WIDE = /^(architecture|arquitetura|project-context|contexto|sprint-status|readme|index)([-._]|$)/i;
+
+const CONFIG_REL = path.join('_wizz', 'bmm', 'config.yaml');
+
+/**
+ * Normaliza texto livre para slug kebab-case: o mesmo formato que a skill
+ * `wizz-set-feature` grava, para branch e config nunca divergirem.
+ * @param {string} raw
+ * @returns {string} slug, ou '' se não sobrar nada utilizável
+ */
+function toSlug(raw) {
+  if (typeof raw !== 'string') return '';
+  return raw
+    .normalize('NFD')
+    .replaceAll(/[̀-ͯ]/g, '')
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9]+/g, '-')
+    .replaceAll(/^-+|-+$/g, '')
+    .slice(0, 60)
+    .replace(/-+$/, '');
+}
+
+/**
+ * Data local em YYYY-MM-DD. `toISOString()` daria o dia em UTC, que em UTC-3
+ * vira o dia seguinte depois das 21h. `WIZZ_TODAY` fixa a data nos testes.
+ * @returns {string}
+ */
+function today() {
+  if (process.env.WIZZ_TODAY && /^\d{4}-\d{2}-\d{2}$/.test(process.env.WIZZ_TODAY)) return process.env.WIZZ_TODAY;
+  const d = new Date();
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+
+/**
+ * Sobe a partir de `start` procurando `name` (até 6 níveis).
+ * @param {string} start
+ * @param {string} name
+ * @returns {string} diretório que contém `name`, ou ''
+ */
+function findUp(start, name) {
+  let dir = start;
+  for (let i = 0; i < 6; i++) {
+    try {
+      if (fs.existsSync(path.join(dir, name))) return dir;
+    } catch {
+      // segue subindo
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return '';
+}
+
+/** Raiz do projeto Wizz (a pasta que contém `_wizz/`), ou ''. */
+function findWizzRoot(cwd) {
+  return findUp(cwd, '_wizz');
+}
+
+/**
+ * Lê o estado git sem subprocesso: `.git/HEAD` já traz o ref.
+ * @param {string} cwd
+ * @returns {{isRepo: boolean, branch: string}} branch '' em detached HEAD
+ */
+function readGitState(cwd) {
+  const repoDir = findUp(cwd, '.git');
+  if (!repoDir) return { isRepo: false, branch: '' };
+  try {
+    const gitPath = path.join(repoDir, '.git');
+    let headFile = path.join(gitPath, 'HEAD');
+    if (fs.statSync(gitPath).isFile()) {
+      // worktree/submódulo: `.git` é um arquivo `gitdir: <caminho>`
+      const m = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(gitPath, 'utf8'));
+      if (!m) return { isRepo: true, branch: '' };
+      headFile = path.join(path.resolve(repoDir, m[1].trim()), 'HEAD');
+    }
+    const ref = /^ref:\s*refs\/heads\/(.+)$/.exec(fs.readFileSync(headFile, 'utf8').trim());
+    return { isRepo: true, branch: ref ? ref[1] : '' };
+  } catch {
+    return { isRepo: true, branch: '' };
+  }
+}
+
+/** Só o nome do branch (compatível com a API antiga do session-rules). */
+function readGitBranch(cwd) {
+  return readGitState(cwd).branch;
+}
+
+/** Branch de tronco ou de release: linha principal, não trabalho nomeado. */
+function isTrunkBranch(branch) {
+  return Boolean(branch) && (TRUNK.has(branch.toLowerCase()) || RELEASE_PREFIX.test(branch));
+}
+
+/**
+ * Deriva o slug de feature do nome do branch. Tronco e branch sem nome útil
+ * devolvem '' (nenhuma feature), nunca um slug inventado.
+ * @param {string} branch
+ * @returns {string}
+ */
+function featureFromBranch(branch) {
+  if (!branch || isTrunkBranch(branch)) return '';
+  const slug = toSlug(branch.replace(TYPE_PREFIX, ''));
+  if (!slug || TRUNK.has(slug)) return '';
+  // Branch que é só um número de issue não descreve feature nenhuma.
+  if (/^\d+$/.test(slug)) return '';
+  return slug;
+}
+
+function unquote(raw) {
+  return String(raw)
+    .replace(/\s+#.*$/, '')
+    .trim()
+    .replaceAll(/^["']|["']$/g, '');
+}
+
+/**
+ * Lê o config do bmm num objeto plano + o bloco `layout:`. Fail-open.
+ * @param {string} root - raiz do projeto Wizz
+ * @returns {{exists: boolean, text: string, values: Record<string,string>, layout: Record<string,string>}}
+ */
+function readConfig(root) {
+  const empty = { exists: false, text: '', values: {}, layout: {} };
+  if (!root) return empty;
+  let text;
+  try {
+    text = fs.readFileSync(path.join(root, CONFIG_REL), 'utf8');
+  } catch {
+    return empty;
+  }
+  const values = {};
+  const layout = {};
+  let inLayout = false;
+  for (const line of text.split(/\r?\n/)) {
+    const top = /^([A-Za-z_][\w-]*):\s*(.*)$/.exec(line);
+    if (top) {
+      inLayout = top[1] === 'layout' && unquote(top[2]) === '';
+      if (!inLayout) values[top[1]] = unquote(top[2]);
+      continue;
+    }
+    const nested = /^\s+([A-Za-z_][\w-]*):\s*(.*)$/.exec(line);
+    if (inLayout && nested) layout[nested[1]] = unquote(nested[2]);
+    else if (line.trim() && !line.trim().startsWith('#') && !/^\s/.test(line)) inLayout = false;
+  }
+  return { exists: true, text, values, layout };
+}
+
+/** Lê só o `active_feature` (API antiga do session-rules). */
+function readConfigFeature(root) {
+  const configPath = path.join(root || '', CONFIG_REL);
+  return { slug: toSlug(readConfig(root).values.active_feature || ''), configPath };
+}
+
+/**
+ * Resolve um caminho do config (`{project-root}/x`, relativo ou absoluto).
+ * @param {string|undefined} value
+ * @param {string} root
+ * @param {string} fallback - relativo à raiz
+ */
+function resolveConfigPath(value, root, fallback) {
+  const raw = value && value.trim() ? value.trim() : fallback;
+  const replaced = raw.replace('{project-root}', root);
+  return path.isAbsolute(replaced) ? path.normalize(replaced) : path.join(root, replaced);
+}
+
+/**
+ * Pastas de artefato do projeto, já resolvidas.
+ * @param {string} root
+ * @param {{values: Record<string,string>}} [config]
+ */
+function artifactDirs(root, config = readConfig(root)) {
+  const output = resolveConfigPath(config.values.output_folder, root, '_wizz-output');
+  return {
+    planning: resolveConfigPath(config.values.planning_artifacts, root, path.join(path.relative(root, output), 'planning-artifacts')),
+    implementation: resolveConfigPath(
+      config.values.implementation_artifacts,
+      root,
+      path.join(path.relative(root, output), 'implementation-artifacts'),
+    ),
+    knowledge: resolveConfigPath(config.values.project_knowledge, root, 'docs'),
+  };
+}
+
+/**
+ * Estado completo da feature: de onde veio, branch, config e opção de branch.
+ * Ordem: branch git > `active_feature` do config > nada.
+ * @param {string} cwd
+ */
+function resolveFeature(cwd) {
+  const root = findWizzRoot(cwd);
+  const config = readConfig(root);
+  const git = readGitState(root || cwd);
+  const fromBranch = featureFromBranch(git.branch);
+  const fromConfig = toSlug(config.values.active_feature || '');
+  const slug = fromBranch || fromConfig;
+  let source = '';
+  if (fromBranch) source = 'branch';
+  else if (fromConfig) source = 'config';
+  return {
+    root,
+    isWizz: Boolean(root),
+    slug,
+    source,
+    fromBranch,
+    fromConfig,
+    git,
+    onTrunk: git.isRepo && (isTrunkBranch(git.branch) || !git.branch),
+    featureBranches: (config.values.feature_branches || 'off').toLowerCase() === 'auto' ? 'auto' : 'off',
+    hasLayout: Object.keys(config.layout).length > 0,
+    config,
+  };
+}
+
+function yamlScalar(value) {
+  return `"${String(value)
+    .replaceAll('\\', '\\\\')
+    .replaceAll('"', String.raw`\"`)}"`;
+}
+
+/**
+ * Grava uma chave escalar de topo no config, preservando o resto do arquivo.
+ * Escrita atômica (tmp + rename): config pela metade derrubaria todo agente.
+ * @returns {boolean} true se gravou
+ */
+function writeConfigValue(root, key, value) {
+  const file = path.join(root, CONFIG_REL);
+  let text = '';
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+  }
+  const line = `${key}: ${yamlScalar(value)}`;
+  const re = new RegExp(String.raw`^${key}:.*$`, 'm');
+  let next;
+  if (re.test(text)) next = text.replace(re, line);
+  else if (text && !text.endsWith('\n')) next = `${text}\n${line}\n`;
+  else next = `${text}${line}\n`;
+  atomicWrite(file, next);
+  return true;
+}
+
+/**
+ * Grava (substitui) o bloco `layout:` do config.
+ * @param {string} root
+ * @param {Record<string,string>} layout
+ */
+function writeLayout(root, layout) {
+  const file = path.join(root, CONFIG_REL);
+  let text = '';
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+  }
+  const block = ['layout:', ...Object.entries(layout).map(([k, v]) => `  ${k}: ${yamlScalar(v)}`)].join('\n');
+  const lines = text.split('\n');
+  const start = lines.findIndex((l) => /^layout:\s*$/.test(l));
+  if (start === -1) {
+    atomicWrite(file, `${text}${text && !text.endsWith('\n') ? '\n' : ''}${block}\n`);
+    return;
+  }
+  let end = start + 1;
+  while (end < lines.length && (/^\s+\S/.test(lines[end]) || lines[end].trim() === '')) end++;
+  // Linha em branco final pertence ao que vem depois, não ao bloco.
+  while (end > start + 1 && lines[end - 1].trim() === '') end--;
+  atomicWrite(file, [...lines.slice(0, start), block, ...lines.slice(end)].join('\n'));
+}
+
+function atomicWrite(file, content) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, content);
+  fs.renameSync(tmp, file);
+}
+
+// ── Frontmatter ─────────────────────────────────────────────────────────
+
+/**
+ * Lê o frontmatter YAML simples (chave: valor) do topo de um markdown.
+ * @param {string} text
+ * @returns {{has: boolean, data: Record<string,string>}}
+ */
+function parseFrontmatter(text) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---(\r?\n|$)/.exec(String(text || ''));
+  if (!m) return { has: false, data: {} };
+  const data = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = /^([A-Za-z_][\w-]*):\s*(.*)$/.exec(line);
+    if (kv) data[kv[1]] = unquote(kv[2]);
+  }
+  return { has: true, data };
+}
+
+/**
+ * Troca (ou adiciona) uma chave do frontmatter. Sem frontmatter, cria um.
+ * @param {string} text
+ * @param {string} key
+ * @param {string} rawValue - já formatado (ex.: `no-ar`, `[D-01, D-02]`)
+ */
+function setFrontmatterField(text, key, rawValue) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  if (!m) return `---\n${key}: ${rawValue}\n---\n\n${text}`;
+  const body = m[1];
+  const re = new RegExp(String.raw`^${key}:.*$`, 'm');
+  const nextBody = re.test(body) ? body.replace(re, `${key}: ${rawValue}`) : `${body}\n${key}: ${rawValue}`;
+  return `---\n${nextBody}\n---${text.slice(m[0].length)}`;
+}
+
+/**
+ * Valida o frontmatter de um artefato tipado. Devolve a lista de problemas
+ * (vazia quando está tudo certo).
+ * @param {string} text
+ * @param {string} [expectedFeature]
+ * @returns {string[]}
+ */
+function frontmatterProblems(text, expectedFeature) {
+  const { has, data } = parseFrontmatter(text);
+  if (!has) return ['sem frontmatter (feature, status, atualizado_em, decisoes)'];
+  const problems = [];
+  if (!data.feature) problems.push('falta `feature:`');
+  else if (expectedFeature && toSlug(data.feature) !== expectedFeature)
+    problems.push(`\`feature: ${data.feature}\` diverge da pasta (${expectedFeature})`);
+  if (!STATUS.includes(data.status)) problems.push(`\`status:\` precisa ser ${STATUS.join('|')}`);
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(data.atualizado_em || '')) problems.push('`atualizado_em:` precisa ser YYYY-MM-DD');
+  if (!('decisoes' in data)) problems.push('falta `decisoes:` (use [] quando não houver)');
+  return problems;
+}
+
+/** Tipo do artefato pelo nome (`spec-x.md` → spec), ou ''. */
+function artifactTypeOf(fileName) {
+  const m = /^([a-z]+)-[a-z0-9][a-z0-9-]*\.md$/.exec(fileName);
+  return m && ARTIFACT_TYPES[m[1]] ? m[1] : '';
+}
+
+/** Conteúdo de uma seção `## Título` (sem comentários HTML), ou null se ausente. */
+function sectionContent(text, title) {
+  const lines = String(text).split('\n');
+  const start = lines.findIndex((l) => new RegExp(String.raw`^##\s+${title}\s*$`, 'i').test(l.trim()));
+  if (start === -1) return null;
+  const out = [];
+  for (let i = start + 1; i < lines.length && !/^#{1,2}\s/.test(lines[i]); i++) out.push(lines[i]);
+  return out
+    .join('\n')
+    .replaceAll(/<!--[\s\S]*?-->/g, '')
+    .trim();
+}
+
+module.exports = {
+  TRUNK,
+  ARTIFACT_TYPES,
+  STATUS,
+  PROJECT_WIDE,
+  CONFIG_REL,
+  toSlug,
+  today,
+  findUp,
+  findWizzRoot,
+  readGitState,
+  readGitBranch,
+  isTrunkBranch,
+  featureFromBranch,
+  readConfig,
+  readConfigFeature,
+  resolveConfigPath,
+  artifactDirs,
+  resolveFeature,
+  writeConfigValue,
+  writeLayout,
+  atomicWrite,
+  parseFrontmatter,
+  setFrontmatterField,
+  frontmatterProblems,
+  artifactTypeOf,
+  sectionContent,
+};