@jaimevalasek/aioson 1.7.2 → 1.8.0

package/src/dossier/codemap-store.js

@@ -0,0 +1,267 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { isValidSlug } = require('./schema');
+
+const FEATURES_SUBDIR = 'features';
+const DOSSIER_FILENAME = 'dossier.md';
+
+const VALID_ROLES = new Set([
+  'command-entry', 'core-module', 'io-layer', 'store', 'schema',
+  'test', 'util', 'config', 'integration', 'cli', 'other'
+]);
+const VALID_COUPLING = new Set(['low', 'medium', 'high']);
+const LINES_REGEX = /^\d+-\d+$/;
+
+function dossierPath(contextDir, slug) {
+  return path.join(contextDir, FEATURES_SUBDIR, slug, DOSSIER_FILENAME);
+}
+
+function parseCodeMapBlock(raw) {
+  const marker = '```yaml\n';
+  const start = raw.indexOf('## Code Map\n');
+  if (start === -1) return null;
+  const blockStart = raw.indexOf(marker, start);
+  if (blockStart === -1) return null;
+  const codeStart = blockStart + marker.length;
+  const codeEnd = raw.indexOf('\n```', codeStart);
+  if (codeEnd === -1) return null;
+  return { blockStart, codeStart, codeEnd };
+}
+
+function parseYamlCodeMap(yamlText) {
+  const result = { files: [], modules: [], patterns: [] };
+  const lines = yamlText.split('\n');
+  let currentSection = null;
+  let currentItem = null;
+
+  const flushItem = () => {
+    if (currentItem !== null && currentSection !== null) {
+      result[currentSection].push(currentItem);
+      currentItem = null;
+    }
+  };
+
+  for (const line of lines) {
+    if (!line.trim()) continue;
+
+    // Section header
+    const sectionMatch = line.match(/^(files|modules|patterns):\s*(\[\])?$/);
+    if (sectionMatch) {
+      flushItem();
+      currentSection = sectionMatch[1];
+      continue;
+    }
+
+    // List item start: "- key: value"
+    const listItemMatch = line.match(/^-\s+(\w+):\s*(.*)$/);
+    if (listItemMatch && currentSection) {
+      flushItem();
+      currentItem = {};
+      currentItem[listItemMatch[1]] = listItemMatch[2].replace(/^["']|["']$/g, '');
+      continue;
+    }
+
+    // Continuation: "  key: value"
+    const kvMatch = line.match(/^\s+(\w+):\s*(.*)$/);
+    if (kvMatch && currentItem !== null) {
+      currentItem[kvMatch[1]] = kvMatch[2].replace(/^["']|["']$/g, '');
+    }
+  }
+  flushItem();
+  return result;
+}
+
+function serializeCodeMap(map) {
+  const lines = [];
+  const serializeList = (key, items) => {
+    if (!items || items.length === 0) {
+      lines.push(`${key}: []`);
+      return;
+    }
+    lines.push(`${key}:`);
+    for (const item of items) {
+      const entries = Object.entries(item);
+      if (entries.length === 0) continue;
+      lines.push(`- ${entries[0][0]}: ${entries[0][1]}`);
+      for (const [k, v] of entries.slice(1)) {
+        lines.push(`  ${k}: ${v}`);
+      }
+    }
+  };
+  serializeList('files', map.files);
+  serializeList('modules', map.modules);
+  serializeList('patterns', map.patterns);
+  return lines.join('\n');
+}
+
+function validateFileEntry(entry) {
+  const errors = [];
+  if (!entry.path || typeof entry.path !== 'string') errors.push('path is required');
+  if (entry.lines && !LINES_REGEX.test(entry.lines)) errors.push(`lines must be int-int (got: ${entry.lines})`);
+  if (entry.role && !VALID_ROLES.has(entry.role)) errors.push(`role must be one of [${[...VALID_ROLES].join(', ')}]`);
+  if (entry.coupling_risk && !VALID_COUPLING.has(entry.coupling_risk)) errors.push(`coupling_risk must be low|medium|high`);
+  return errors;
+}
+
+async function addCodemap({ slug, contextDir, filePath, lines, role, coupling, addedBy, now = () => new Date() }) {
+  if (!isValidSlug(slug)) {
+    const err = new Error(`invalid slug: ${JSON.stringify(slug)}`);
+    err.code = 'EDOSSIERSLUG';
+    throw err;
+  }
+  const errors = validateFileEntry({ path: filePath, lines, role, coupling_risk: coupling });
+  if (errors.length > 0) {
+    const err = new Error(`invalid codemap entry: ${errors.join('; ')}`);
+    err.code = 'ECODEMAPVALIDATION';
+    err.errors = errors;
+    throw err;
+  }
+
+  // Warn (not error) when the file path doesn't exist on disk — may be a planned file
+  let fileWarn = null;
+  try {
+    await fs.access(path.resolve(contextDir, '..', '..', filePath));
+  } catch {
+    fileWarn = 'file_not_found';
+  }
+
+  const p = dossierPath(contextDir, slug);
+  let raw;
+  try {
+    raw = await fs.readFile(p, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      const e = new Error(`dossier not found for slug "${slug}"`);
+      e.code = 'EDOSSIERMISSING';
+      throw e;
+    }
+    throw err;
+  }
+
+  const parsed = parseCodeMapBlock(raw);
+  let map = { files: [], modules: [], patterns: [] };
+  if (parsed) {
+    const yamlText = raw.slice(parsed.codeStart, parsed.codeEnd);
+    map = parseYamlCodeMap(yamlText);
+  }
+
+  // Idempotency: dedupe by (path, lines)
+  const existing = map.files.find(f => f.path === filePath && f.lines === (lines || ''));
+  if (existing) {
+    return { added: false, path: filePath, warn: fileWarn };
+  }
+
+  const entry = { path: filePath };
+  if (lines) entry.lines = lines;
+  if (role) entry.role = role;
+  if (coupling) entry.coupling_risk = coupling;
+  if (addedBy) entry.added_by = addedBy;
+  entry.added_at = now().toISOString();
+
+  map.files.push(entry);
+  const newYaml = serializeCodeMap(map);
+
+  let newRaw;
+  if (parsed) {
+    newRaw = raw.slice(0, parsed.codeStart) + newYaml + raw.slice(parsed.codeEnd);
+  } else {
+    // Insert a Code Map section if absent (shouldn't happen in well-formed dossiers)
+    newRaw = raw + `\n## Code Map\n\n\`\`\`yaml\n${newYaml}\n\`\`\`\n`;
+  }
+
+  await fs.writeFile(p, newRaw, 'utf8');
+  return { added: true, path: filePath, warn: fileWarn };
+}
+
+async function linkRule({ slug, contextDir, rulePath, reason, targetDir }) {
+  if (!isValidSlug(slug)) {
+    const err = new Error(`invalid slug: ${JSON.stringify(slug)}`);
+    err.code = 'EDOSSIERSLUG';
+    throw err;
+  }
+
+  // Validate rule path exists in .aioson/rules/ or .aioson/design-docs/
+  const base = targetDir || process.cwd();
+  const absRule = path.resolve(base, rulePath);
+  const rulesDir = path.join(base, '.aioson', 'rules');
+  const designDocsDir = path.join(base, '.aioson', 'design-docs');
+
+  const inRules = absRule.startsWith(rulesDir + path.sep) || absRule.startsWith(rulesDir + '/');
+  const inDesignDocs = absRule.startsWith(designDocsDir + path.sep) || absRule.startsWith(designDocsDir + '/');
+
+  if (!inRules && !inDesignDocs) {
+    const err = new Error(`rule path must be under .aioson/rules/ or .aioson/design-docs/ (got: ${rulePath})`);
+    err.code = 'ELINKREULEPATH';
+    throw err;
+  }
+
+  try {
+    await fs.access(absRule);
+  } catch {
+    const err = new Error(`rule file not found: ${absRule}`);
+    err.code = 'ELINKREULENOTFOUND';
+    err.path = absRule;
+    throw err;
+  }
+
+  const p = dossierPath(contextDir, slug);
+  let raw;
+  try {
+    raw = await fs.readFile(p, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      const e = new Error(`dossier not found for slug "${slug}"`);
+      e.code = 'EDOSSIERMISSING';
+      throw e;
+    }
+    throw err;
+  }
+
+  const rulesSection = '## Rules & Design-Docs aplicáveis';
+  const entry = `- [${rulePath}](${rulePath})${reason ? ` — ${reason}` : ''}`;
+
+  // Idempotency: don't duplicate same path
+  if (raw.includes(`[${rulePath}]`)) {
+    return { added: false, path: rulePath };
+  }
+
+  const lines = raw.split('\n');
+  let sectionEnd = lines.length;
+  let inSection = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trimEnd() === rulesSection) {
+      inSection = true;
+    } else if (inSection && /^## /.test(lines[i])) {
+      sectionEnd = i;
+      break;
+    }
+  }
+
+  const before = lines.slice(0, sectionEnd);
+  const after = lines.slice(sectionEnd);
+
+  // Remove placeholder line if present
+  const placeholderIdx = before.findIndex(l => l.includes('_(vazio —') || l.includes('_(empty'));
+  if (placeholderIdx !== -1) before.splice(placeholderIdx, 1);
+
+  while (before.length > 0 && before[before.length - 1].trim() === '') before.pop();
+  before.push('', entry);
+
+  const newRaw = [...before, '', ...after].join('\n');
+  await fs.writeFile(p, newRaw, 'utf8');
+  return { added: true, path: rulePath };
+}
+
+module.exports = {
+  addCodemap,
+  linkRule,
+  parseCodeMapBlock,
+  parseYamlCodeMap,
+  serializeCodeMap,
+  validateFileEntry,
+  VALID_ROLES,
+  VALID_COUPLING
+};

package/src/dossier/dossier-bootstrap.js

@@ -0,0 +1,222 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const { isValidSlug, SCHEMA_VERSION, ALLOWED_CLASSIFICATIONS, validateFrontmatter } = require('./schema');
+const { featureDir, dossierPath, parseSections, parseFrontmatter } = require('./store');
+
+// Maps canonical artifact filenames to the agent that typically produces them.
+const ARTIFACT_AGENTS = {
+  [`prd`]: 'product',
+  [`spec`]: 'architect',
+  [`sheldon-enrichment`]: 'sheldon',
+  [`requirements`]: 'analyst',
+  [`architecture`]: 'architect'
+};
+
+async function fileExists(p) {
+  try { await fs.access(p); return true; } catch { return false; }
+}
+
+async function readText(p) {
+  try { return await fs.readFile(p, 'utf8'); } catch { return null; }
+}
+
+function extractSection(markdown, headingNames) {
+  if (!markdown) return null;
+  const sections = parseSections(markdown);
+  for (const name of headingNames) {
+    if (sections[name]) {
+      const t = sections[name].trim();
+      if (t) return t;
+    }
+  }
+  return null;
+}
+
+function artifactHash(artifacts) {
+  const keys = Object.keys(artifacts).sort();
+  const payload = keys.map(k => `${k}=${artifacts[k] ? artifacts[k].length : 0}`).join(';');
+  return crypto.createHash('sha256').update(payload).digest('hex').slice(0, 12);
+}
+
+function buildBootstrapDossier({ slug, classification, createdAt, artifacts, why, what, agentTrail }) {
+  const fm = [
+    '---',
+    `feature_slug: ${slug}`,
+    `schema_version: "${SCHEMA_VERSION}"`,
+    `created_by: dossier-init`,
+    `created_at: ${createdAt}`,
+    `status: ${artifacts.done ? 'closed' : 'active'}`,
+    `classification: ${classification}`,
+    `last_updated_by: dossier-init`,
+    `last_updated_at: ${createdAt}`,
+    `bootstrap_hash: ${artifactHash(artifacts)}`,
+    '---',
+    ''
+  ].join('\n');
+
+  const whyText = why || '_(não encontrado — preencher manualmente)_';
+  const whatText = what || '_(não encontrado — preencher manualmente)_';
+
+  const trailLines = agentTrail.length > 0
+    ? agentTrail.map(e => `- **${e.timestamp}** | @${e.agent} | _${e.artifact}_`).join('\n')
+    : '_(sintetizado a partir de artefatos existentes)_';
+
+  const body = [
+    '## Why',
+    '',
+    whyText,
+    '',
+    '## What',
+    '',
+    whatText,
+    '',
+    '## Code Map',
+    '',
+    '```yaml',
+    'files: []',
+    'modules: []',
+    'patterns: []',
+    '```',
+    '',
+    '## Rules & Design-Docs aplicáveis',
+    '',
+    '_(populado via dossier:link-rule)_',
+    '',
+    '## Agent Trail',
+    '',
+    trailLines,
+    '',
+    '## Revision Requests',
+    '',
+    '_(vazio)_',
+    ''
+  ].join('\n');
+
+  return fm + body;
+}
+
+async function initFromExisting({ slug, contextDir, classification, targetDir, now = () => new Date() } = {}) {
+  if (!isValidSlug(slug)) {
+    const err = new Error(`invalid slug (must be kebab-case): ${JSON.stringify(slug)}`);
+    err.code = 'EDOSSIERSLUG';
+    throw err;
+  }
+
+  const dir = featureDir(contextDir, slug);
+  const p = dossierPath(contextDir, slug);
+
+  // Check if dossier already exists (idempotency guard)
+  if (await fileExists(p)) {
+    // Check if it has the same bootstrap_hash — if artifacts unchanged, it's a no-op
+    const raw = await readText(p);
+    const fmParse = raw ? parseFrontmatter(raw) : { ok: false };
+    if (fmParse.ok && fmParse.data.bootstrap_hash) {
+      // Re-compute hash to detect changes
+      const artifacts = await gatherArtifacts(slug, contextDir, targetDir);
+      const newHash = artifactHash(artifacts);
+      if (newHash === fmParse.data.bootstrap_hash) {
+        return { created: false, reason: 'unchanged', path: p };
+      }
+    }
+    const err = new Error(`dossier already exists at ${p} — use dossier:show to inspect`);
+    err.code = 'EDOSSIEREXISTS';
+    err.path = p;
+    throw err;
+  }
+
+  const artifacts = await gatherArtifacts(slug, contextDir, targetDir);
+
+  // Must have at least one artifact to synthesize from
+  const hasAny = Object.values(artifacts).some(Boolean);
+  if (!hasAny) {
+    const err = new Error(`no artifacts found for slug "${slug}" — use dossier:init without --from-existing`);
+    err.code = 'EBOOTSTRAPEMPTY';
+    throw err;
+  }
+
+  // Resolve classification
+  let cls = classification;
+  if (!cls) {
+    const ctxPath = path.join(contextDir, 'project.context.md');
+    const ctxRaw = await readText(ctxPath);
+    if (ctxRaw) {
+      const m = ctxRaw.match(/^classification:\s*"?([A-Z]+)"?\s*$/m);
+      if (m && ALLOWED_CLASSIFICATIONS.has(m[1])) cls = m[1];
+    }
+  }
+  cls = cls || 'MEDIUM';
+
+  // Extract Why/What
+  const prdContent = artifacts.prd || artifacts.prdGlobal;
+  const why = extractSection(prdContent, ['Problem', 'Why', 'Vision', 'Problema']);
+  const what = extractSection(prdContent, ['Escopo do MVP', 'Scope', 'What', 'Escopo']);
+
+  // Build agent trail from artifact metadata
+  const createdAt = now().toISOString();
+  const agentTrail = buildAgentTrail(artifacts, createdAt);
+
+  // Validate frontmatter before writing
+  const fmCheck = validateFrontmatter({
+    feature_slug: slug,
+    schema_version: SCHEMA_VERSION,
+    created_by: 'dossier-init',
+    created_at: createdAt,
+    status: artifacts.done ? 'closed' : 'active',
+    classification: cls,
+    last_updated_by: 'dossier-init',
+    last_updated_at: createdAt
+  });
+  if (!fmCheck.valid) {
+    const err = new Error(`schema error: ${fmCheck.errors.join('; ')}`);
+    err.code = 'EDOSSIERSCHEMA';
+    throw err;
+  }
+
+  const markdown = buildBootstrapDossier({ slug, classification: cls, createdAt, artifacts, why, what, agentTrail });
+
+  await fs.mkdir(dir, { recursive: true });
+  await fs.writeFile(p, markdown, 'utf8');
+
+  return { created: true, path: p, classification: cls, artifactsFound: Object.keys(artifacts).filter(k => artifacts[k]) };
+}
+
+async function gatherArtifacts(slug, contextDir, targetDir) {
+  const base = targetDir || path.join(contextDir, '..', '..');
+  const artifacts = {};
+
+  // Per-slug artifacts
+  artifacts.prd = await readText(path.join(contextDir, `prd-${slug}.md`));
+  artifacts.spec = await readText(path.join(contextDir, `spec-${slug}.md`));
+  artifacts.sheldonEnrichment = await readText(path.join(contextDir, `sheldon-enrichment-${slug}.md`));
+  artifacts.requirements = await readText(path.join(contextDir, `requirements-${slug}.md`));
+  artifacts.architecture = await readText(path.join(contextDir, `architecture-${slug}.md`));
+
+  // Global PRD fallback
+  artifacts.prdGlobal = !artifacts.prd ? await readText(path.join(contextDir, 'prd.md')) : null;
+
+  // done/ directory (feature already closed)
+  const doneDir = path.join(contextDir, 'done', slug);
+  artifacts.done = await fileExists(doneDir) ? doneDir : null;
+
+  return artifacts;
+}
+
+function buildAgentTrail(artifacts, fallbackTimestamp) {
+  const trail = [];
+  const add = (artifact, agent) => {
+    if (artifacts[artifact]) trail.push({ artifact, agent, timestamp: fallbackTimestamp });
+  };
+  add('prd', 'product');
+  add('prdGlobal', 'product');
+  add('requirements', 'analyst');
+  add('sheldonEnrichment', 'sheldon');
+  add('architecture', 'architect');
+  add('spec', 'architect');
+  return trail;
+}
+
+module.exports = { initFromExisting };

package/src/dossier/dossier-compact.js

@@ -0,0 +1,159 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { isValidSlug } = require('./schema');
+
+const FEATURES_SUBDIR = 'features';
+const DOSSIER_FILENAME = 'dossier.md';
+const HISTORY_FILENAME = 'dossier-history.md';
+const MAX_ACTIVE_SIZE = 15000;
+const TARGET_ACTIVE_SIZE = 10000;
+
+// Sections whose content can be migrated once the gate they belong to is closed.
+// The ordering reflects which gates close first in MEDIUM flow.
+const MIGRATABLE_SECTIONS = [
+  'Why',
+  'What',
+  'Rules & Design-Docs aplicáveis'
+];
+
+function dossierPath(contextDir, slug) {
+  return path.join(contextDir, FEATURES_SUBDIR, slug, DOSSIER_FILENAME);
+}
+
+function historyPath(contextDir, slug) {
+  return path.join(contextDir, FEATURES_SUBDIR, slug, HISTORY_FILENAME);
+}
+
+function splitSections(raw) {
+  const result = [];
+  const lines = raw.split('\n');
+  let current = null;
+  let buf = [];
+  let frontmatter = null;
+  let inFm = false;
+  let fmClosed = false;
+  let fmBuf = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!fmClosed) {
+      if (i === 0 && line === '---') { inFm = true; fmBuf.push(line); continue; }
+      if (inFm) {
+        fmBuf.push(line);
+        if (line === '---' && i > 0) { fmClosed = true; frontmatter = fmBuf.join('\n'); continue; }
+        continue;
+      }
+      fmClosed = true;
+    }
+    const m = line.match(/^##\s+(.+?)\s*$/);
+    if (m) {
+      if (current !== null) result.push({ heading: current, lines: buf });
+      current = m[1].trim();
+      buf = [];
+    } else {
+      if (current !== null) buf.push(line);
+    }
+  }
+  if (current !== null) result.push({ heading: current, lines: buf });
+  return { frontmatter, sections: result };
+}
+
+function joinSections(frontmatter, sections) {
+  const parts = [];
+  if (frontmatter) parts.push(frontmatter, '');
+  for (const sec of sections) {
+    parts.push(`## ${sec.heading}`);
+    parts.push(...sec.lines);
+  }
+  return parts.join('\n');
+}
+
+async function compact({ slug, contextDir, now = () => new Date(), force = false } = {}) {
+  if (!isValidSlug(slug)) {
+    const err = new Error(`invalid slug: ${JSON.stringify(slug)}`);
+    err.code = 'EDOSSIERSLUG';
+    throw err;
+  }
+
+  const p = dossierPath(contextDir, slug);
+  let raw;
+  try {
+    raw = await fs.readFile(p, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      const e = new Error(`dossier not found for slug "${slug}"`);
+      e.code = 'EDOSSIERMISSING';
+      throw e;
+    }
+    throw err;
+  }
+
+  if (!force && Buffer.byteLength(raw, 'utf8') <= MAX_ACTIVE_SIZE) {
+    return { compacted: false, reason: 'size_ok', sizeBytes: Buffer.byteLength(raw, 'utf8') };
+  }
+
+  const { frontmatter, sections } = splitSections(raw);
+  const date = now().toISOString().slice(0, 10);
+  const hp = historyPath(contextDir, slug);
+
+  // Load or initialize history
+  let historyContent = '';
+  try {
+    historyContent = await fs.readFile(hp, 'utf8');
+  } catch {
+    historyContent = `# Dossier History — ${slug}\n\n`;
+  }
+
+  const migratedHeadings = [];
+  const activeSections = [];
+
+  for (const sec of sections) {
+    const body = sec.lines.join('\n').trim();
+    const isEmpty = !body || body.startsWith('_(vazio') || body.startsWith('_(empty') || body.startsWith('_(preencher');
+
+    if (MIGRATABLE_SECTIONS.includes(sec.heading) && !isEmpty) {
+      // Append to history (append-only, never compact again)
+      const anchor = sec.heading.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/-+/g, '-');
+      historyContent += `\n## [Migrated from active dossier on ${date}] ${sec.heading} {#${anchor}-${date}}\n\n${body}\n`;
+      migratedHeadings.push(sec.heading);
+
+      // Replace in active with summary + link
+      activeSections.push({
+        heading: sec.heading,
+        lines: [``, `_(migrated to [dossier-history.md](dossier-history.md#${anchor}-${date}))_`, ``]
+      });
+    } else {
+      activeSections.push(sec);
+    }
+  }
+
+  if (migratedHeadings.length === 0) {
+    return { compacted: false, reason: 'nothing_migratable', sizeBytes: Buffer.byteLength(raw, 'utf8') };
+  }
+
+  const newRaw = joinSections(frontmatter, activeSections);
+  await fs.writeFile(p, newRaw, 'utf8');
+  // History is append-only
+  await fs.writeFile(hp, historyContent, 'utf8');
+
+  return {
+    compacted: true,
+    migratedSections: migratedHeadings,
+    activeSizeBytes: Buffer.byteLength(newRaw, 'utf8'),
+    historyPath: hp
+  };
+}
+
+async function shouldCompact({ slug, contextDir } = {}) {
+  const p = dossierPath(contextDir, slug);
+  try {
+    const stat = await fs.stat(p);
+    return stat.size > MAX_ACTIVE_SIZE;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { compact, shouldCompact, MAX_ACTIVE_SIZE, TARGET_ACTIVE_SIZE, dossierPath, historyPath };