@jaimevalasek/aioson 1.7.0 → 1.8.0

package/src/doctor.js

@@ -5,8 +5,8 @@ const path = require('node:path');
 const { REQUIRED_FILES } = require('./constants');
 const { installTemplate, TEMPLATE_DIR } = require('./installer');
 const { exists, copyFileWithDir } = require('./utils');
-const { validateProjectContextFile } = require('./context');
-const { applyAgentLocale, resolveAgentLocale } = require('./locales');
+const { validateProjectContextFile, getInteractionLanguage } = require('./context');
+const { applyAgentLocale } = require('./locales');
 
 function parseMajor(version) {
   const cleaned = String(version || '').replace(/^v/, '');
@@ -34,6 +34,14 @@ const GEMINI_COMMAND_EXPECTATIONS = [
   { file: '.gemini/commands/aios-orchestrator.toml', agent: 'orchestrator' }
 ];
 
+const DESIGN_GOVERNANCE_FILES = [
+  '.aioson/design-docs/code-reuse.md',
+  '.aioson/design-docs/componentization.md',
+  '.aioson/design-docs/file-size.md',
+  '.aioson/design-docs/folder-structure.md',
+  '.aioson/design-docs/naming.md'
+];
+
 const GATEWAY_FILE_BY_CHECK_ID = {
   'gateway:claude:contract': 'CLAUDE.md',
   'gateway:codex:contract': 'AGENTS.md',
@@ -79,6 +87,16 @@ async function runDoctor(targetDir) {
     });
   }
 
+  for (const rel of DESIGN_GOVERNANCE_FILES) {
+    checks.push({
+      id: `design-governance:${rel}`,
+      key: 'doctor.required_file',
+      params: { rel },
+      ok: await exists(path.join(targetDir, rel)),
+      hintKey: 'doctor.context_hint'
+    });
+  }
+
   const gatewayChecks = [
     {
       id: 'gateway:claude:contract',
@@ -130,7 +148,7 @@ async function runDoctor(targetDir) {
       key: 'doctor.gateway_gemini_command_pointer',
       params: { file: expectation.file },
       ok: await fileContainsAll(commandPath, [
-        `instruction_file = ".aioson/agents/${expectation.agent}.md"`
+        `@{ .aioson/agents/${expectation.agent}.md }`
       ]),
       hintKey: 'doctor.gateway_gemini_command_pointer_hint',
       hintParams: {
@@ -250,14 +268,36 @@ async function applyDoctorFixes(targetDir, report, options = {}) {
     });
   }
 
+  const missingDesignGovernanceFiles = report.checks
+    .filter((check) => !check.ok && check.id.startsWith('design-governance:'))
+    .map((check) => check.params.rel);
+
+  if (missingDesignGovernanceFiles.length > 0) {
+    const restored = await restoreTemplateFiles(targetDir, missingDesignGovernanceFiles, { dryRun });
+    if (restored.length > 0) changedCount += restored.length;
+    actions.push({
+      id: 'design_governance',
+      applied: restored.length > 0,
+      count: restored.length,
+      missingCount: missingDesignGovernanceFiles.length
+    });
+  } else {
+    actions.push({
+      id: 'design_governance',
+      applied: false,
+      skipped: true,
+      count: 0,
+      missingCount: 0
+    });
+  }
+
   if (
     report.contextValidation &&
     report.contextValidation.parsed &&
     report.contextValidation.valid &&
-    report.contextValidation.data &&
-    report.contextValidation.data.conversation_language
+    report.contextValidation.data
   ) {
-    const locale = resolveAgentLocale(report.contextValidation.data.conversation_language);
+    const locale = getInteractionLanguage(report.contextValidation.data, 'en');
     const localeResult = await applyAgentLocale(targetDir, locale, { dryRun });
     if (localeResult.copied.length > 0) changedCount += localeResult.copied.length;
     actions.push({

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 };