@dotdotgod/cli 0.1.40 → 0.1.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdotgod/cli",
-  "version": "0.1.40",
+  "version": "0.1.42",
   "description": "CLI for dotdotgod validation, project memory snapshots, and graph indexing.",
   "type": "module",
   "license": "Elastic-2.0",

package/src/docs/traceability.mjs

@@ -9,11 +9,12 @@ function isSecretIndexPath(path) {
 
 const TRACEABILITY_PATH_FIELDS = ['implementedBy', 'verifiedBy', 'relatedDocs'];
 const TRACEABILITY_COMMAND_FIELDS = ['verificationCommands'];
+const CONTRACT_ALLOWED_FIELDS = new Set(['id', 'title', 'sections', ...TRACEABILITY_PATH_FIELDS, ...TRACEABILITY_COMMAND_FIELDS]);
 export const TRACEABILITY_LINKS_START = '<!-- dotdotgod:traceability-links:start version=1 source=json-dotdotgod -->';
 export const TRACEABILITY_LINKS_END = '<!-- dotdotgod:traceability-links:end -->';
 
 export function traceabilityExample() {
-  return 'Expected dotdotgod traceability block:\n\n```json dotdotgod\n{\n  "kind": "spec",\n  "implementedBy": ["packages/..."],\n  "verifiedBy": ["packages/..."],\n  "relatedDocs": ["docs/..."],\n  "verificationCommands": ["pnpm ..."]\n}\n```\n\nProperty guidance:\n- kind: use "spec" for behavior specs.\n- implementedBy: source/config/script files that implement this spec\'s behavior.\n- verifiedBy: test files or verification docs that check this behavior.\n- relatedDocs: docs with relevant architecture, test strategy, or product context.\n- verificationCommands: commands an agent can run to verify this behavior.';
+  return 'Expected dotdotgod traceability block:\n\n```json dotdotgod\n{\n  "kind": "spec",\n  "implementedBy": ["packages/..."],\n  "verifiedBy": ["packages/..."],\n  "relatedDocs": ["docs/..."],\n  "verificationCommands": ["pnpm ..."],\n  "contracts": [{\n    "id": "FEATURE-BEHAVIOR-001",\n    "title": "Focused behavior contract",\n    "sections": ["Focused Behavior"],\n    "implementedBy": ["packages/..."],\n    "verifiedBy": ["packages/..."],\n    "relatedDocs": ["docs/..."],\n    "verificationCommands": ["pnpm ..."]\n  }]\n}\n```\n\nProperty guidance:\n- kind: use "spec" for behavior specs.\n- implementedBy: source/config/script files that implement this spec\'s behavior.\n- verifiedBy: test files or verification docs that check this behavior.\n- relatedDocs: docs with relevant architecture, test strategy, or product context.\n- verificationCommands: commands an agent can run to verify this behavior.\n- contracts: optional focused behavior contracts; each contract requires non-empty id and title, may include sections as navigation hints, and may include the same path and command fields. Unknown contract fields are validation errors.';
 }
 
 function lineForOffset(content, offset) {
@@ -128,6 +129,23 @@ function renderCommandList(commands) {
   return ['- Verification commands:', ...commands.map((command) => `  - \`${escapeCodeSpan(command)}\``)];
 }
 
+function renderContractList(contracts) {
+  if (!Array.isArray(contracts) || contracts.length === 0) return [];
+  const lines = ['- Contracts:'];
+  for (const contract of contracts) {
+    if (!contract || typeof contract !== 'object' || Array.isArray(contract)) continue;
+    const id = typeof contract.id === 'string' ? contract.id : '<missing-id>';
+    const title = typeof contract.title === 'string' ? contract.title : '<missing-title>';
+    const details = [];
+    if (Array.isArray(contract.sections) && contract.sections.length > 0) details.push(`sections: ${contract.sections.length}`);
+    for (const [field, label] of [['implementedBy', 'impl'], ['verifiedBy', 'verify'], ['relatedDocs', 'docs'], ['verificationCommands', 'commands']]) {
+      if (Array.isArray(contract[field]) && contract[field].length > 0) details.push(`${label}: ${contract[field].length}`);
+    }
+    lines.push(`  - \`${escapeCodeSpan(id)}\` — ${escapeMarkdownText(title)}${details.length > 0 ? ` (${details.join(', ')})` : ''}`);
+  }
+  return lines;
+}
+
 export function renderTraceabilityLinks(data, root, file) {
   const body = [
     '### Traceability Links',
@@ -136,6 +154,7 @@ export function renderTraceabilityLinks(data, root, file) {
     ...renderPathList('Verified by', data?.verifiedBy, root, file),
     ...renderPathList('Related docs', data?.relatedDocs, root, file),
     ...renderCommandList(data?.verificationCommands),
+    ...renderContractList(data?.contracts),
   ];
   return `${TRACEABILITY_LINKS_START}\n<!-- generated: do not edit manually -->\n\n${body.join('\n')}\n\n${TRACEABILITY_LINKS_END}`;
 }
@@ -168,39 +187,81 @@ export function syncTraceabilityLinksInContent(content, data, root, file) {
   return { ok: true, changed: next !== content, content: next };
 }
 
-export function validateTraceabilityBlock(data, root, file, line = null, config = defaultMemoryConfig()) {
-  const errors = [];
-  const add = (code, field, message) => errors.push(traceabilityFieldError(rel(root, file), code, field, message, line));
-  if (!data || typeof data !== 'object' || Array.isArray(data)) {
-    add('TRACEABILITY_INVALID_JSON', null, 'Traceability block must be a JSON object.');
-    return errors;
+function validateTraceabilityPathArray(data, field, add, root, config, { required = true, displayField = field } = {}) {
+  if (data[field] === undefined && !required) return;
+  if (!Array.isArray(data[field])) {
+    add('TRACEABILITY_INVALID_FIELD', displayField, 'must be an array of local relative paths.');
+    return;
   }
-  if (data.kind !== 'spec') add('TRACEABILITY_INVALID_KIND', 'kind', 'must be "spec" for behavior specs.');
-  for (const field of TRACEABILITY_PATH_FIELDS) {
-    if (!Array.isArray(data[field])) {
-      add('TRACEABILITY_INVALID_FIELD', field, 'must be an array of local relative paths.');
+  for (const value of data[field]) {
+    if (!isLocalRelativeTraceabilityPath(value)) {
+      add('TRACEABILITY_INVALID_PATH', displayField, `invalid local relative path: ${JSON.stringify(value)}.`);
       continue;
     }
-    for (const value of data[field]) {
-      if (!isLocalRelativeTraceabilityPath(value)) {
-        add('TRACEABILITY_INVALID_PATH', field, `invalid local relative path: ${JSON.stringify(value)}.`);
-        continue;
-      }
-      const area = resolveMemoryArea(value, config);
-      if (area?.scope === 'local') {
-        add('TRACEABILITY_LOCAL_MEMORY_TARGET', field, `target points to local memory area "${area.id}": ${value}. Traceability must point to shared durable files, not active plans or archive memory.`);
-        continue;
-      }
-      if (!existsSync(resolve(root, value))) add('TRACEABILITY_MISSING_TARGET', field, `target does not exist: ${value}.`);
+    const area = resolveMemoryArea(value, config);
+    if (area?.scope === 'local') {
+      add('TRACEABILITY_LOCAL_MEMORY_TARGET', displayField, `target points to local memory area "${area.id}": ${value}. Traceability must point to shared durable files, not active plans or archive memory.`);
+      continue;
     }
+    if (!existsSync(resolve(root, value))) add('TRACEABILITY_MISSING_TARGET', displayField, `target does not exist: ${value}.`);
+  }
+}
+
+function validateTraceabilityCommandArray(data, field, add, { required = true, displayField = field } = {}) {
+  if (data[field] === undefined && !required) return;
+  if (!Array.isArray(data[field])) {
+    add('TRACEABILITY_INVALID_FIELD', displayField, 'must be an array of executable project-local command strings.');
+    return;
   }
-  for (const field of TRACEABILITY_COMMAND_FIELDS) {
-    if (!Array.isArray(data[field])) {
-      add('TRACEABILITY_INVALID_FIELD', field, 'must be an array of executable project-local command strings.');
+  for (const value of data[field]) if (typeof value !== 'string' || value.trim().length === 0) add('TRACEABILITY_INVALID_COMMAND', displayField, `invalid command: ${JSON.stringify(value)}.`);
+}
+
+function validateTraceabilityContracts(data, root, add, config) {
+  if (data.contracts === undefined) return;
+  if (!Array.isArray(data.contracts)) {
+    add('TRACEABILITY_INVALID_FIELD', 'contracts', 'must be an array of focused contract objects.');
+    return;
+  }
+  const ids = new Set();
+  for (const [index, contract] of data.contracts.entries()) {
+    const base = `contracts[${index}]`;
+    if (!contract || typeof contract !== 'object' || Array.isArray(contract)) {
+      add('TRACEABILITY_INVALID_FIELD', base, 'must be an object with non-empty id and title fields.');
       continue;
     }
-    for (const value of data[field]) if (typeof value !== 'string' || value.trim().length === 0) add('TRACEABILITY_INVALID_COMMAND', field, `invalid command: ${JSON.stringify(value)}.`);
+    for (const field of Object.keys(contract)) {
+      if (!CONTRACT_ALLOWED_FIELDS.has(field)) add('TRACEABILITY_INVALID_FIELD', `${base}.${field}`, 'is not a supported contract field.');
+    }
+    if (typeof contract.id !== 'string' || contract.id.trim().length === 0) {
+      add('TRACEABILITY_INVALID_FIELD', `${base}.id`, 'must be a non-empty stable contract ID string.');
+    } else if (ids.has(contract.id)) {
+      add('TRACEABILITY_INVALID_FIELD', `${base}.id`, `duplicates contract id ${JSON.stringify(contract.id)} in this traceability block.`);
+    } else {
+      ids.add(contract.id);
+    }
+    if (typeof contract.title !== 'string' || contract.title.trim().length === 0) add('TRACEABILITY_INVALID_FIELD', `${base}.title`, 'must be a non-empty human-readable contract title.');
+    if (contract.sections !== undefined) {
+      if (!Array.isArray(contract.sections)) add('TRACEABILITY_INVALID_FIELD', `${base}.sections`, 'must be an array of same-file heading titles.');
+      else for (const [sectionIndex, section] of contract.sections.entries()) {
+        if (typeof section !== 'string' || section.trim().length === 0) add('TRACEABILITY_INVALID_FIELD', `${base}.sections[${sectionIndex}]`, 'must be a non-empty heading title string.');
+      }
+    }
+    for (const field of TRACEABILITY_PATH_FIELDS) validateTraceabilityPathArray(contract, field, add, root, config, { required: false, displayField: `${base}.${field}` });
+    for (const field of TRACEABILITY_COMMAND_FIELDS) validateTraceabilityCommandArray(contract, field, add, { required: false, displayField: `${base}.${field}` });
   }
+}
+
+export function validateTraceabilityBlock(data, root, file, line = null, config = defaultMemoryConfig()) {
+  const errors = [];
+  const add = (code, field, message) => errors.push(traceabilityFieldError(rel(root, file), code, field, message, line));
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    add('TRACEABILITY_INVALID_JSON', null, 'Traceability block must be a JSON object.');
+    return errors;
+  }
+  if (data.kind !== 'spec') add('TRACEABILITY_INVALID_KIND', 'kind', 'must be "spec" for behavior specs.');
+  for (const field of TRACEABILITY_PATH_FIELDS) validateTraceabilityPathArray(data, field, add, root, config);
+  for (const field of TRACEABILITY_COMMAND_FIELDS) validateTraceabilityCommandArray(data, field, add);
+  validateTraceabilityContracts(data, root, add, config);
   return errors;
 }
 

package/src/graph/metadata.mjs

@@ -68,18 +68,45 @@ function addTraceabilityTarget(graph, sourceId, root, relation, targetPath, data
   addEdge(graph, sourceId, targetId, relation, { confidence: 'CURATED_TRACEABILITY', ...data });
 }
 
+function contractNodeId(filePath, contractId) {
+  return `contract:${filePath}#${contractId}`;
+}
+
+function addTraceabilityCommands(graph, sourceId, filePath, commands, idPrefix) {
+  for (const [index, command] of (Array.isArray(commands) ? commands : []).entries()) {
+    if (typeof command !== 'string' || command.trim().length === 0) continue;
+    const id = `verification_command:${idPrefix}#${index}`;
+    addNode(graph, id, 'verification_command', { command, path: filePath });
+    addEdge(graph, sourceId, id, 'verification_command', { confidence: 'CURATED_TRACEABILITY' });
+  }
+}
+
+function addTraceabilityContracts(graph, root, fileId, filePath, contracts, config = defaultMemoryConfig()) {
+  if (!Array.isArray(contracts)) return;
+  for (const contract of contracts) {
+    if (!contract || typeof contract !== 'object' || Array.isArray(contract)) continue;
+    if (typeof contract.id !== 'string' || contract.id.trim().length === 0) continue;
+    if (typeof contract.title !== 'string' || contract.title.trim().length === 0) continue;
+    const id = contractNodeId(filePath, contract.id);
+    const sections = Array.isArray(contract.sections) ? contract.sections.filter((section) => typeof section === 'string' && section.trim().length > 0) : undefined;
+    addNode(graph, id, 'contract', { path: filePath, contractId: contract.id, title: contract.title, sections });
+    addEdge(graph, fileId, id, 'defines_contract', { confidence: 'CURATED_TRACEABILITY' });
+    for (const target of Array.isArray(contract.implementedBy) ? contract.implementedBy : []) addTraceabilityTarget(graph, id, root, 'implemented_by', target, {}, config);
+    for (const target of Array.isArray(contract.verifiedBy) ? contract.verifiedBy : []) addTraceabilityTarget(graph, id, root, 'verified_by', target, {}, config);
+    for (const target of Array.isArray(contract.relatedDocs) ? contract.relatedDocs : []) addTraceabilityTarget(graph, id, root, 'related_doc', target, {}, config);
+    addTraceabilityCommands(graph, id, filePath, Array.isArray(contract.verificationCommands) ? contract.verificationCommands : [], id);
+  }
+}
+
 export function addTraceabilityGraph(root, fileId, content, graph, config = defaultMemoryConfig()) {
+  const filePath = fileId.replace(/^file:/, '');
   for (const block of extractDotdotgodTraceabilityBlocks(content)) {
     if (block.error || !block.data || block.data.kind !== 'spec') continue;
     for (const target of block.data.implementedBy ?? []) addTraceabilityTarget(graph, fileId, root, 'implemented_by', target, {}, config);
     for (const target of block.data.verifiedBy ?? []) addTraceabilityTarget(graph, fileId, root, 'verified_by', target, {}, config);
     for (const target of block.data.relatedDocs ?? []) addTraceabilityTarget(graph, fileId, root, 'related_doc', target, {}, config);
-    for (const [index, command] of (Array.isArray(block.data.verificationCommands) ? block.data.verificationCommands : []).entries()) {
-      if (typeof command !== 'string' || command.trim().length === 0) continue;
-      const id = `verification_command:${fileId}#${index}`;
-      addNode(graph, id, 'verification_command', { command, path: fileId.replace(/^file:/, '') });
-      addEdge(graph, fileId, id, 'verification_command', { confidence: 'CURATED_TRACEABILITY' });
-    }
+    addTraceabilityCommands(graph, fileId, filePath, block.data.verificationCommands, fileId);
+    addTraceabilityContracts(graph, root, fileId, filePath, block.data.contracts, config);
   }
 }
 

package/src/graph/store.mjs

@@ -14,7 +14,7 @@ function graphNodeShard(node) {
 }
 
 function graphEdgeShard(edge) {
-  if (edge.relation === 'links_to' || edge.relation === 'routes_to' || edge.relation === 'contains_heading' || edge.relation === 'implemented_by' || edge.relation === 'verified_by' || edge.relation === 'related_doc' || edge.relation === 'verification_command' || SEMANTIC_RELATIONS.has(edge.relation)) return 'docs-links';
+  if (edge.relation === 'links_to' || edge.relation === 'routes_to' || edge.relation === 'contains_heading' || edge.relation === 'implemented_by' || edge.relation === 'verified_by' || edge.relation === 'related_doc' || edge.relation === 'verification_command' || edge.relation === 'defines_contract' || SEMANTIC_RELATIONS.has(edge.relation)) return 'docs-links';
   if (edge.relation === 'declares_package' || edge.relation === 'declares_script' || edge.relation === 'declares_bin' || edge.relation === 'depends_on' || edge.relation === 'includes_resource') return 'packages';
   return 'other';
 }

package/src/impact/format.mjs

@@ -6,7 +6,7 @@ function formatCompactImpactGroup(name, group) {
   return [
     `${name}:`,
     ...items.map((item) => {
-      const label = item.path ?? item.command ?? item.name ?? item.target ?? item.id;
+      const label = item.type === 'contract' && item.path && item.contractId ? `${item.path}#${item.contractId}${item.title ? ` — ${item.title}` : ''}` : item.path ?? item.command ?? item.name ?? item.target ?? item.id;
       const reasons = (item.reasons ?? []).slice(0, 3).join(', ');
       return `- ${label} (${item.impactScore}; ${reasons})`;
     }),
@@ -16,7 +16,7 @@ function formatCompactImpactGroup(name, group) {
 export function formatCompactImpactOutput(payload, impact) {
   const refreshNote = payload.metadata.cacheRefreshed ? ', refreshed' : '';
   const lines = [`graph impact compact: ${impact.related.length} related node(s), ${impact.omittedRelated ?? 0} omitted (${payload.status.status}${refreshNote} index)`];
-  for (const name of ['docs', 'tests', 'files', 'commands', 'events', 'packageResources', 'symbols']) lines.push(...formatCompactImpactGroup(name, impact.groups[name]));
+  for (const name of ['docs', 'contracts', 'tests', 'files', 'commands', 'events', 'packageResources', 'symbols']) lines.push(...formatCompactImpactGroup(name, impact.groups[name]));
   return lines.join('\n');
 }
 
@@ -37,6 +37,9 @@ function formatYmlImpactItem(item) {
   lines.push(`          type: ${ymlScalar(item.type)}`);
   lines.push(`          score: ${ymlScalar(item.impactScore)}`);
   lines.push(`          reasons: ${ymlList((item.reasons ?? []).slice(0, 6))}`);
+  if (item.contractId) lines.push(`          contract_id: ${ymlScalar(item.contractId)}`);
+  if (item.title) lines.push(`          title: ${ymlScalar(item.title)}`);
+  if (Array.isArray(item.sections) && item.sections.length > 0) lines.push(`          sections: ${ymlList(item.sections)}`);
   if (item.retrieval?.area) lines.push(`          area: ${ymlScalar(item.retrieval.area)}`);
   if (item.retrieval?.role) lines.push(`          role: ${ymlScalar(item.retrieval.role)}`);
   return lines;
@@ -68,7 +71,7 @@ export function formatYmlImpactOutput(payload, impact) {
     `    config_source: ${ymlScalar(impact.ranking?.configSource)}`,
     '  groups:',
   ];
-  for (const name of ['docs', 'tests', 'files', 'commands', 'events', 'packageResources', 'symbols']) lines.push(...formatYmlImpactGroup(name, impact.groups[name]));
+  for (const name of ['docs', 'contracts', 'tests', 'files', 'commands', 'events', 'packageResources', 'symbols']) lines.push(...formatYmlImpactGroup(name, impact.groups[name]));
   lines.push('  recommended_actions:');
   lines.push('    - "review_related_docs"');
   lines.push('    - "run_related_tests"');

package/src/impact/report.mjs

@@ -48,7 +48,7 @@ export function buildImpactReport(index, changedPath, limits = {}) {
   const nodeById = new Map(graph.nodes.map((node) => [node.id, node]));
   const seed = `file:${changedPath}`;
   const maxRelated = limits.related ?? 25;
-  const groups = { files: { items: [], omitted: 0 }, docs: { items: [], omitted: 0 }, tests: { items: [], omitted: 0 }, commands: { items: [], omitted: 0 }, events: { items: [], omitted: 0 }, packageResources: { items: [], omitted: 0 }, symbols: { items: [], omitted: 0 } };
+  const groups = { files: { items: [], omitted: 0 }, docs: { items: [], omitted: 0 }, contracts: { items: [], omitted: 0 }, tests: { items: [], omitted: 0 }, commands: { items: [], omitted: 0 }, events: { items: [], omitted: 0 }, packageResources: { items: [], omitted: 0 }, symbols: { items: [], omitted: 0 } };
   const relatedIds = new Set([seed]);
   const reasons = new Map([[seed, new Set(['changed-file'])]]);
   const addReason = (id, reason) => {
@@ -85,7 +85,8 @@ export function buildImpactReport(index, changedPath, limits = {}) {
       if (area) addImpactItem(groups.docs, { ...item, area }, limits.docs ?? 10);
       else if (isTestPath(item.path)) addImpactItem(groups.tests, item, limits.tests ?? 10);
       else addImpactItem(groups.files, item, limits.files ?? 10);
-    } else if (item.type === 'test') addImpactItem(groups.tests, item, limits.tests ?? 10);
+    } else if (item.type === 'contract') addImpactItem(groups.contracts, item, limits.contracts ?? 10);
+    else if (item.type === 'test') addImpactItem(groups.tests, item, limits.tests ?? 10);
     else if (item.type === 'command') addImpactItem(groups.commands, item, limits.commands ?? 10);
     else if (item.type === 'event') addImpactItem(groups.events, item, limits.events ?? 10);
     else if (item.type === 'package_resource') addImpactItem(groups.packageResources, item, limits.packageResources ?? 10);
@@ -101,7 +102,7 @@ function compactScoreBreakdown(scoreBreakdown = {}) {
 
 export function compactImpactItem(item) {
   const compact = { id: item.id, type: item.type, impactScore: item.impactScore, reasons: (item.reasons ?? []).slice(0, 6), scoreBreakdown: compactScoreBreakdown(item.scoreBreakdown) };
-  for (const key of ['path', 'area', 'name', 'command', 'target', 'kind', 'specifier', 'title']) if (item[key] !== undefined) compact[key] = item[key];
+  for (const key of ['path', 'area', 'name', 'command', 'target', 'kind', 'specifier', 'title', 'contractId', 'sections']) if (item[key] !== undefined) compact[key] = item[key];
   if (item.retrieval) compact.retrieval = { area: item.retrieval.area, role: item.retrieval.role, priority: item.retrieval.priority, freshness: item.retrieval.freshness };
   return compact;
 }
@@ -115,7 +116,7 @@ export function buildCompactImpactReport(impact, limits = {}) {
   const relatedLimit = limits.related ?? 10;
   const groupLimit = limits.groupItems ?? 5;
   const related = (impact.related ?? []).slice(0, relatedLimit).map(compactImpactItem);
-  const groupNames = ['files', 'docs', 'tests', 'commands', 'events', 'packageResources', 'symbols'];
+  const groupNames = ['files', 'docs', 'contracts', 'tests', 'commands', 'events', 'packageResources', 'symbols'];
   const groups = Object.fromEntries(groupNames.map((name) => [name, compactImpactGroup(impact.groups?.[name], groupLimit)]));
   const top10 = (impact.related ?? []).filter((item) => item.id !== `file:${impact.changed}`).slice(0, 10);
   return { changed: impact.changed, compact: true, ranking: { method: impact.ranking?.method, preset: impact.ranking?.preset, configSource: impact.ranking?.configSource }, related, groups, omittedRelated: (impact.omittedRelated ?? 0) + Math.max(0, (impact.related?.length ?? 0) - related.length), quality: { rawRelated: impact.related?.length ?? 0, compactRelated: related.length, semanticOnlyTop10: top10.filter((item) => isSemanticOnlyImpactItem(item)).length, curatedTop10: top10.filter((item) => hasCuratedImpactReason(item)).length, lowActionabilityTop10: top10.filter((item) => isLowActionabilityImpactItem(item)).length } };