@vitronai/themis 0.1.4 → 0.1.6

package/src/artifact-paths.js

@@ -0,0 +1,111 @@
+const path = require('path');
+
+const ARTIFACT_DIR = '.themis';
+const RUNS_DIR = ['runs'];
+const DIFFS_DIR = ['diffs'];
+const GENERATE_DIR = ['generate'];
+const REPORTS_DIR = ['reports'];
+const MIGRATION_DIR = ['migration'];
+const BENCHMARKS_DIR = ['benchmarks'];
+const SHOWCASE_COMPARISON_DIR = [...BENCHMARKS_DIR, 'showcase-comparison'];
+const MIGRATION_FIXTURES_DIR = [...MIGRATION_DIR, 'fixtures'];
+
+const ARTIFACT_SEGMENTS = Object.freeze({
+  lastRun: [...RUNS_DIR, 'last-run.json'],
+  failedTests: [...RUNS_DIR, 'failed-tests.json'],
+  runDiff: [...DIFFS_DIR, 'run-diff.json'],
+  runHistory: [...RUNS_DIR, 'run-history.json'],
+  fixHandoff: [...RUNS_DIR, 'fix-handoff.json'],
+  contractDiff: [...DIFFS_DIR, 'contract-diff.json'],
+  generateMap: [...GENERATE_DIR, 'generate-map.json'],
+  generateResult: [...GENERATE_DIR, 'generate-last.json'],
+  generateHandoff: [...GENERATE_DIR, 'generate-handoff.json'],
+  generateBacklog: [...GENERATE_DIR, 'generate-backlog.json'],
+  migrationReport: [...MIGRATION_DIR, 'migration-report.json'],
+  htmlReport: [...REPORTS_DIR, 'report.html'],
+  benchmarkLast: [...BENCHMARKS_DIR, 'benchmark-last.json'],
+  migrationProof: [...BENCHMARKS_DIR, 'migration-proof.json']
+});
+
+const LEGACY_ARTIFACT_SEGMENTS = Object.freeze({
+  lastRun: ['last-run.json'],
+  failedTests: ['failed-tests.json'],
+  runDiff: ['run-diff.json'],
+  runHistory: ['run-history.json'],
+  fixHandoff: ['fix-handoff.json'],
+  contractDiff: ['contract-diff.json'],
+  generateMap: ['generate-map.json'],
+  generateResult: ['generate-last.json'],
+  generateHandoff: ['generate-handoff.json'],
+  generateBacklog: ['generate-backlog.json'],
+  migrationReport: ['migration-report.json'],
+  htmlReport: ['report.html'],
+  benchmarkLast: ['benchmark-last.json'],
+  migrationProof: ['migration-proof.json']
+});
+
+function joinRelative(segments) {
+  return path.posix.join(ARTIFACT_DIR, ...segments);
+}
+
+function joinAbsolute(cwd, segments) {
+  return path.join(cwd, ARTIFACT_DIR, ...segments);
+}
+
+function buildRelativePathMap(segmentMap) {
+  return Object.fromEntries(
+    Object.entries(segmentMap).map(([key, segments]) => [key, joinRelative(segments)])
+  );
+}
+
+const ARTIFACT_RELATIVE_PATHS = Object.freeze(buildRelativePathMap(ARTIFACT_SEGMENTS));
+const LEGACY_ARTIFACT_RELATIVE_PATHS = Object.freeze(buildRelativePathMap(LEGACY_ARTIFACT_SEGMENTS));
+
+function resolveArtifactPath(cwd, key) {
+  return joinAbsolute(cwd, ARTIFACT_SEGMENTS[key]);
+}
+
+function resolveLegacyArtifactPath(cwd, key) {
+  return joinAbsolute(cwd, LEGACY_ARTIFACT_SEGMENTS[key]);
+}
+
+function resolveArtifactDir(cwd, ...segments) {
+  return path.join(cwd, ARTIFACT_DIR, ...segments);
+}
+
+function resolveRelativeDir(...segments) {
+  return path.posix.join(ARTIFACT_DIR, ...segments);
+}
+
+function getArtifactPaths(cwd) {
+  return Object.fromEntries(
+    Object.keys(ARTIFACT_SEGMENTS).map((key) => [key, resolveArtifactPath(cwd, key)])
+  );
+}
+
+function getArtifactPathCandidates(cwd, key) {
+  const nextPath = resolveArtifactPath(cwd, key);
+  const legacyPath = resolveLegacyArtifactPath(cwd, key);
+  return nextPath === legacyPath ? [nextPath] : [nextPath, legacyPath];
+}
+
+module.exports = {
+  ARTIFACT_DIR,
+  RUNS_DIR,
+  DIFFS_DIR,
+  GENERATE_DIR,
+  REPORTS_DIR,
+  MIGRATION_DIR,
+  BENCHMARKS_DIR,
+  SHOWCASE_COMPARISON_DIR,
+  MIGRATION_FIXTURES_DIR,
+  ARTIFACT_SEGMENTS,
+  ARTIFACT_RELATIVE_PATHS,
+  LEGACY_ARTIFACT_RELATIVE_PATHS,
+  resolveArtifactPath,
+  resolveLegacyArtifactPath,
+  resolveArtifactDir,
+  resolveRelativeDir,
+  getArtifactPaths,
+  getArtifactPathCandidates
+};

package/src/artifacts.js

@@ -1,31 +1,35 @@
 const fs = require('fs');
 const path = require('path');
-
-const ARTIFACT_DIR = '.themis';
-const LAST_RUN_FILE = 'last-run.json';
-const FAILED_TESTS_FILE = 'failed-tests.json';
-const RUN_DIFF_FILE = 'run-diff.json';
-const RUN_HISTORY_FILE = 'run-history.json';
-const FIX_HANDOFF_FILE = 'fix-handoff.json';
-const CONTRACT_DIFF_FILE = 'contract-diff.json';
-const GENERATE_MAP_FILE = 'generate-map.json';
-const GENERATE_BACKLOG_FILE = 'generate-backlog.json';
+const {
+  ARTIFACT_RELATIVE_PATHS,
+  getArtifactPathCandidates,
+  getArtifactPaths
+} = require('./artifact-paths');
 
 function writeRunArtifacts(cwd, result) {
-  const artifactDir = path.join(cwd, ARTIFACT_DIR);
-  fs.mkdirSync(artifactDir, { recursive: true });
+  const artifactPaths = getArtifactPaths(cwd);
+  for (const artifactPath of [
+    artifactPaths.lastRun,
+    artifactPaths.failedTests,
+    artifactPaths.runDiff,
+    artifactPaths.runHistory,
+    artifactPaths.fixHandoff,
+    artifactPaths.contractDiff
+  ]) {
+    fs.mkdirSync(path.dirname(artifactPath), { recursive: true });
+  }
 
-  const runPath = path.join(artifactDir, LAST_RUN_FILE);
-  const previousRun = readJsonIfExists(runPath);
+  const runPath = artifactPaths.lastRun;
+  const previousRun = readJsonFromCandidates(getArtifactPathCandidates(cwd, 'lastRun'));
   const runId = createRunId(result.meta?.startedAt || new Date().toISOString());
   const comparison = buildRunComparison(previousRun, result);
   const relativePaths = {
-    lastRun: path.join(ARTIFACT_DIR, LAST_RUN_FILE),
-    failedTests: path.join(ARTIFACT_DIR, FAILED_TESTS_FILE),
-    runDiff: path.join(ARTIFACT_DIR, RUN_DIFF_FILE),
-    runHistory: path.join(ARTIFACT_DIR, RUN_HISTORY_FILE),
-    fixHandoff: path.join(ARTIFACT_DIR, FIX_HANDOFF_FILE),
-    contractDiff: path.join(ARTIFACT_DIR, CONTRACT_DIFF_FILE)
+    lastRun: ARTIFACT_RELATIVE_PATHS.lastRun,
+    failedTests: ARTIFACT_RELATIVE_PATHS.failedTests,
+    runDiff: ARTIFACT_RELATIVE_PATHS.runDiff,
+    runHistory: ARTIFACT_RELATIVE_PATHS.runHistory,
+    fixHandoff: ARTIFACT_RELATIVE_PATHS.fixHandoff,
+    contractDiff: ARTIFACT_RELATIVE_PATHS.contractDiff
   };
 
   result.artifacts = {
@@ -35,6 +39,7 @@ function writeRunArtifacts(cwd, result) {
   };
 
   fs.writeFileSync(runPath, `${stringifyArtifact(result)}\n`, 'utf8');
+  removeLegacyArtifact(cwd, 'lastRun');
 
   const failedTests = [];
   for (const fileEntry of result.files || []) {
@@ -61,19 +66,21 @@ function writeRunArtifacts(cwd, result) {
     failedTests
   };
 
-  const failuresPath = path.join(artifactDir, FAILED_TESTS_FILE);
+  const failuresPath = artifactPaths.failedTests;
   fs.writeFileSync(failuresPath, `${stringifyArtifact(failuresPayload)}\n`, 'utf8');
+  removeLegacyArtifact(cwd, 'failedTests');
 
   const diffPayload = {
     schema: 'themis.run.diff.v1',
     runId,
     ...comparison
   };
-  const diffPath = path.join(artifactDir, RUN_DIFF_FILE);
+  const diffPath = artifactPaths.runDiff;
   fs.writeFileSync(diffPath, `${stringifyArtifact(diffPayload)}\n`, 'utf8');
+  removeLegacyArtifact(cwd, 'runDiff');
 
-  const historyPath = path.join(artifactDir, RUN_HISTORY_FILE);
-  const previousHistory = readJsonIfExists(historyPath);
+  const historyPath = artifactPaths.runHistory;
+  const previousHistory = readJsonFromCandidates(getArtifactPathCandidates(cwd, 'runHistory'));
   const nextHistory = Array.isArray(previousHistory) ? previousHistory.slice(-19) : [];
   nextHistory.push({
     runId,
@@ -84,16 +91,18 @@ function writeRunArtifacts(cwd, result) {
     comparison
   });
   fs.writeFileSync(historyPath, `${stringifyArtifact(nextHistory)}\n`, 'utf8');
+  removeLegacyArtifact(cwd, 'runHistory');
 
   const contractDiffPayload = buildContractDiffPayload(result, {
     runId,
     createdAt: new Date().toISOString(),
     relativePaths
   });
-  const contractDiffPath = path.join(artifactDir, CONTRACT_DIFF_FILE);
+  const contractDiffPath = artifactPaths.contractDiff;
   fs.writeFileSync(contractDiffPath, `${stringifyArtifact(contractDiffPayload)}\n`, 'utf8');
+  removeLegacyArtifact(cwd, 'contractDiff');
 
-  const fixHandoffPath = path.join(artifactDir, FIX_HANDOFF_FILE);
+  const fixHandoffPath = artifactPaths.fixHandoff;
   let fixHandoff = null;
   if (failedTests.length > 0) {
     fixHandoff = buildFixHandoffPayload(cwd, result, {
@@ -102,7 +111,11 @@ function writeRunArtifacts(cwd, result) {
       relativePaths
     });
     fs.writeFileSync(fixHandoffPath, `${stringifyArtifact(fixHandoff)}\n`, 'utf8');
+    removeLegacyArtifact(cwd, 'fixHandoff');
+  } else if (fs.existsSync(fixHandoffPath)) {
+    fs.rmSync(fixHandoffPath, { force: true });
   }
+  removeLegacyArtifact(cwd, 'fixHandoff');
 
   return {
     runPath,
@@ -119,18 +132,19 @@ function writeRunArtifacts(cwd, result) {
 }
 
 function readFailedTestsArtifact(cwd) {
-  const failuresPath = path.join(cwd, ARTIFACT_DIR, FAILED_TESTS_FILE);
-  if (!fs.existsSync(failuresPath)) {
+  const candidates = getArtifactPathCandidates(cwd, 'failedTests');
+  const existingPath = candidates.find((candidate) => fs.existsSync(candidate));
+  if (!existingPath) {
     return null;
   }
 
-  const raw = fs.readFileSync(failuresPath, 'utf8');
+  const raw = fs.readFileSync(existingPath, 'utf8');
   let parsed;
   try {
     parsed = JSON.parse(raw);
   } catch (error) {
     return {
-      failuresPath,
+      failuresPath: existingPath,
       failedTests: [],
       parseError: String(error?.message || error)
     };
@@ -138,18 +152,52 @@ function readFailedTestsArtifact(cwd) {
 
   if (!parsed || !Array.isArray(parsed.failedTests)) {
     return {
-      failuresPath,
+      failuresPath: existingPath,
       failedTests: [],
       parseError: 'Invalid artifact shape: expected "failedTests" to be an array'
     };
   }
 
   return {
-    failuresPath,
+    failuresPath: existingPath,
     failedTests: parsed.failedTests
   };
 }
 
+function readFixHandoffArtifact(cwd) {
+  const candidates = getArtifactPathCandidates(cwd, 'fixHandoff');
+  const existingPath = candidates.find((candidate) => fs.existsSync(candidate));
+  if (!existingPath) {
+    return null;
+  }
+
+  const raw = fs.readFileSync(existingPath, 'utf8');
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    return {
+      fixHandoffPath: existingPath,
+      items: [],
+      parseError: String(error?.message || error)
+    };
+  }
+
+  if (!parsed || !Array.isArray(parsed.items)) {
+    return {
+      fixHandoffPath: existingPath,
+      items: [],
+      parseError: 'Invalid artifact shape: expected "items" to be an array'
+    };
+  }
+
+  return {
+    fixHandoffPath: existingPath,
+    items: parsed.items,
+    payload: parsed
+  };
+}
+
 function buildRunComparison(previousRun, result) {
   const currentFailures = collectFailureNames(result);
   const currentFailureSet = new Set(currentFailures);
@@ -266,14 +314,24 @@ function readJsonIfExists(filePath) {
 
   try {
     return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-  } catch (error) {
+  } catch {
     return null;
   }
 }
 
+function readJsonFromCandidates(filePaths) {
+  for (const filePath of filePaths) {
+    const parsed = readJsonIfExists(filePath);
+    if (parsed) {
+      return parsed;
+    }
+  }
+  return null;
+}
+
 function buildFixHandoffPayload(cwd, result, context) {
-  const generateMap = readJsonIfExists(path.join(cwd, ARTIFACT_DIR, GENERATE_MAP_FILE));
-  const generateBacklog = readJsonIfExists(path.join(cwd, ARTIFACT_DIR, GENERATE_BACKLOG_FILE));
+  const generateMap = readJsonFromCandidates(getArtifactPathCandidates(cwd, 'generateMap'));
+  const generateBacklog = readJsonFromCandidates(getArtifactPathCandidates(cwd, 'generateBacklog'));
   const mapEntries = Array.isArray(generateMap && generateMap.entries) ? generateMap.entries : [];
   const backlogItems = Array.isArray(generateBacklog && generateBacklog.items) ? generateBacklog.items : [];
   const byGeneratedTest = new Map();
@@ -341,8 +399,8 @@ function buildFixHandoffPayload(cwd, result, context) {
     summary,
     artifacts: {
       failedTests: context.relativePaths.failedTests,
-      generateMap: path.join(ARTIFACT_DIR, GENERATE_MAP_FILE),
-      generateBacklog: path.join(ARTIFACT_DIR, GENERATE_BACKLOG_FILE),
+      generateMap: ARTIFACT_RELATIVE_PATHS.generateMap,
+      generateBacklog: ARTIFACT_RELATIVE_PATHS.generateBacklog,
       fixHandoff: context.relativePaths.fixHandoff
     },
     items,
@@ -423,7 +481,7 @@ function buildFixCandidateFiles(entry, backlogMatch) {
 function buildFixNextActions(summary) {
   const actions = [];
   if (summary.generatedFailures > 0) {
-    actions.push('Review .themis/fix-handoff.json and start with source-drift items.');
+    actions.push(`Review ${ARTIFACT_RELATIVE_PATHS.fixHandoff} and start with source-drift items.`);
     actions.push('Regenerate narrow targets before rerunning the full suite.');
   }
   if (summary.generatedFailures === 0) {
@@ -436,11 +494,21 @@ function roundDuration(value) {
   return Math.round(Number(value || 0) * 100) / 100;
 }
 
+function removeLegacyArtifact(cwd, key) {
+  const [currentPath, ...legacyPaths] = getArtifactPathCandidates(cwd, key);
+  for (const legacyPath of legacyPaths) {
+    if (legacyPath !== currentPath && fs.existsSync(legacyPath)) {
+      fs.rmSync(legacyPath, { force: true });
+    }
+  }
+}
+
 function stringifyArtifact(value) {
   return JSON.stringify(value);
 }
 
 module.exports = {
   writeRunArtifacts,
-  readFailedTestsArtifact
+  readFailedTestsArtifact,
+  readFixHandoffArtifact
 };

package/src/cli.js

@@ -3,10 +3,11 @@ const { loadConfig } = require('./config');
 const { discoverTests } = require('./discovery');
 const { runTests } = require('./runner');
 const { printSpec, printJson, printAgent, printNext, writeHtmlReport } = require('./reporter');
+const { ARTIFACT_RELATIVE_PATHS } = require('./artifact-paths');
 const { runInit } = require('./init');
 const { runMigrate } = require('./migrate');
 const { generateTestsFromSource, writeGenerateArtifacts } = require('./generate');
-const { writeRunArtifacts, readFailedTestsArtifact } = require('./artifacts');
+const { writeRunArtifacts, readFailedTestsArtifact, readFixHandoffArtifact } = require('./artifacts');
 const { buildStabilityReport, hasStabilityBreaches } = require('./stability');
 const { verdictReveal } = require('./verdict');
 const { runWatchMode } = require('./watch');
@@ -21,7 +22,7 @@ async function main(argv) {
 
   if (command === 'init') {
     runInit(cwd);
-    console.log('Themis initialized. Run: npx themis test');
+    console.log('Themis initialized. Next: npx themis generate src && npx themis test');
     return;
   }
 
@@ -77,6 +78,9 @@ async function main(argv) {
     if (result.packageUpdated && result.packageJsonPath) {
       console.log(`Scripts: updated ${formatCliPath(cwd, result.packageJsonPath)} with test:themis`);
     }
+    if (result.gitignoreUpdated) {
+      console.log(`Gitignore: updated ${formatCliPath(cwd, result.gitignorePath)} with .themis/`);
+    }
     if (result.rewriteImports) {
       console.log(`Imports: rewrote ${result.rewrittenFiles.length} file(s) to local Themis compatibility imports.`);
     }
@@ -124,6 +128,62 @@ async function main(argv) {
 }
 
 async function executeTestRun(cwd, flags) {
+  const execution = flags.fix
+    ? await executeTestFixRun(cwd, flags)
+    : await runTestCommand(cwd, flags);
+
+  await finalizeTestExecution(execution);
+}
+
+async function executeTestFixRun(cwd, flags) {
+  let fixArtifact = readFixHandoffArtifact(cwd);
+
+  if (fixArtifact && fixArtifact.parseError) {
+    return {
+      notices: [
+        `Failed to parse fix handoff artifact at ${fixArtifact.fixHandoffPath}: ${fixArtifact.parseError}. Run npx themis test to regenerate it.`
+      ],
+      ...(await runTestCommand(cwd, { ...flags, fix: false }))
+    };
+  }
+
+  let seededExecution = null;
+  if (!fixArtifact || fixArtifact.items.length === 0) {
+    seededExecution = await runTestCommand(cwd, { ...flags, fix: false });
+    fixArtifact = readFixHandoffArtifact(cwd);
+
+    if (fixArtifact && fixArtifact.parseError) {
+      return {
+        ...seededExecution,
+        notices: [
+          `Failed to parse fix handoff artifact at ${fixArtifact.fixHandoffPath}: ${fixArtifact.parseError}.`
+        ]
+      };
+    }
+
+    if (!fixArtifact || fixArtifact.items.length === 0) {
+      const notices = seededExecution.result.summary.failed > 0
+        ? [`No generated-test autofixes were available for this run. Review ${ARTIFACT_RELATIVE_PATHS.fixHandoff} when generated tests fail.`]
+        : ['No generated-test repairs were needed.'];
+      return {
+        ...seededExecution,
+        notices
+      };
+    }
+  }
+
+  const fixSummary = applyGeneratedAutofix(cwd, fixArtifact.payload || { items: fixArtifact.items });
+  const rerunExecution = await runTestCommand(cwd, { ...flags, fix: false });
+  return {
+    ...rerunExecution,
+    notices: [
+      `Applied generated-test fixes for ${fixSummary.sources.length} source file(s).`,
+      ...fixSummary.messages
+    ]
+  };
+}
+
+async function runTestCommand(cwd, flags) {
   const config = loadConfig(cwd);
 
   if (flags.match) {
@@ -141,29 +201,29 @@ async function executeTestRun(cwd, flags) {
   if (flags.isolation) {
     validateIsolation(flags.isolation);
   }
-  printBanner(reporter);
   const maxWorkers = resolveWorkerCount(flags.workers, config.maxWorkers);
   const stabilityRuns = resolveStabilityRuns(flags.stability);
 
   let files = discoverTests(cwd, config);
   if (files.length === 0) {
-    console.log(`No test files found in ${config.testDir}`);
-    return;
+    return buildNoResultExecution(reporter, lexicon, cwd, flags, [`No test files found in ${config.testDir}`]);
   }
 
   let allowedFullNames = null;
   if (flags.rerunFailed) {
     const artifact = readFailedTestsArtifact(cwd);
     if (artifact && artifact.parseError) {
-      console.log(
-        `Failed to parse failed test artifact at ${artifact.failuresPath}: ${artifact.parseError}. Run a full test pass to regenerate it.`
+      return buildNoResultExecution(
+        reporter,
+        lexicon,
+        cwd,
+        flags,
+        [`Failed to parse failed test artifact at ${artifact.failuresPath}: ${artifact.parseError}. Run a full test pass to regenerate it.`]
       );
-      return;
     }
 
     if (!artifact || artifact.failedTests.length === 0) {
-      console.log('No failed test artifact found. Run a failing test first.');
-      return;
+      return buildNoResultExecution(reporter, lexicon, cwd, flags, ['No failed test artifact found. Run a failing test first.']);
     }
 
     const fileSet = new Set(artifact.failedTests.map((entry) => entry.file));
@@ -171,8 +231,7 @@ async function executeTestRun(cwd, flags) {
     files = files.filter((file) => fileSet.has(file));
 
     if (files.length === 0) {
-      console.log('No matching files found for failed test artifact.');
-      return;
+      return buildNoResultExecution(reporter, lexicon, cwd, flags, ['No matching files found for failed test artifact.']);
     }
   }
 
@@ -201,20 +260,95 @@ async function executeTestRun(cwd, flags) {
   }
 
   writeRunArtifacts(cwd, result);
-  printResult(reporter, result, {
+  return {
+    reporter,
     lexicon,
+    result,
     cwd,
     htmlOutput: flags.htmlOutput || null
+  };
+}
+
+async function finalizeTestExecution(execution) {
+  printBanner(execution.reporter);
+
+  if (execution.reporter !== 'json' && execution.reporter !== 'agent') {
+    for (const notice of execution.notices || []) {
+      console.log(notice);
+    }
+  }
+
+  if (!execution.result) {
+    return;
+  }
+
+  printResult(execution.reporter, execution.result, {
+    lexicon: execution.lexicon,
+    cwd: execution.cwd,
+    htmlOutput: execution.htmlOutput || null
   });
 
-  const revealFailed = result.summary.failed > 0 || hasStabilityBreaches(stabilityReport);
-  await maybeRevealVerdict(reporter, result, stabilityReport, revealFailed);
+  const revealFailed = execution.result.summary.failed > 0 || hasStabilityBreaches(execution.result.stability);
+  await maybeRevealVerdict(execution.reporter, execution.result, execution.result.stability, revealFailed);
 
   if (revealFailed) {
     process.exitCode = 1;
   }
 }
 
+function buildNoResultExecution(reporter, lexicon, cwd, flags, notices) {
+  return {
+    reporter,
+    lexicon,
+    cwd,
+    htmlOutput: flags.htmlOutput || null,
+    notices,
+    result: null
+  };
+}
+
+function applyGeneratedAutofix(cwd, fixPayload) {
+  const bySourceFile = new Map();
+  for (const item of fixPayload.items || []) {
+    if (!item || !item.sourceFile) {
+      continue;
+    }
+    const current = bySourceFile.get(item.sourceFile);
+    if (!current) {
+      bySourceFile.set(item.sourceFile, item);
+      continue;
+    }
+    if (current.repairStrategy !== 'tighten-hints' && item.repairStrategy === 'tighten-hints') {
+      bySourceFile.set(item.sourceFile, item);
+    }
+  }
+
+  const sources = [...bySourceFile.keys()];
+  const messages = [];
+
+  for (const sourceFile of sources) {
+    const item = bySourceFile.get(sourceFile);
+    const writeHints = item.repairStrategy === 'tighten-hints' || item.category === 'generated-contract-failure';
+    const summary = generateTestsFromSource(cwd, {
+      targetDir: sourceFile,
+      update: true,
+      writeHints
+    });
+    writeGenerateArtifacts(summary, cwd);
+
+    const createdHintCount = Number(summary.hintFiles?.created?.length || 0);
+    const updatedHintCount = Number(summary.hintFiles?.updated?.length || 0);
+    if (writeHints && (createdHintCount > 0 || updatedHintCount > 0)) {
+      messages.push(`Updated hints for ${sourceFile} (${createdHintCount} created, ${updatedHintCount} updated).`);
+    }
+  }
+
+  return {
+    sources,
+    messages
+  };
+}
+
 function resolveReporter(flags, config) {
   if (flags.reporter) {
     return flags.reporter;
@@ -292,6 +426,10 @@ function parseFlags(args) {
       flags.updateContracts = true;
       continue;
     }
+    if (token === '--fix') {
+      flags.fix = true;
+      continue;
+    }
     if (token === '-w' || token === '--watch') {
       flags.watch = true;
       continue;
@@ -485,7 +623,7 @@ function parseGenerateFlags(args) {
 function validateRegex(pattern) {
   try {
     new RegExp(pattern);
-  } catch (error) {
+  } catch {
     throw new Error(`Invalid --match regex: ${pattern}`);
   }
 }
@@ -572,12 +710,12 @@ function resolveStabilityRuns(value) {
 function printUsage() {
   console.log('Usage: themis <command> [options]');
   console.log('Commands:');
-  console.log('  init                    Create themis.config.json and sample tests');
+  console.log('  init                    Create themis.config.json and gitignore .themis/ artifacts');
   console.log('  generate [path]         Scan source files and generate Themis contract tests');
   console.log('                         Options: [--json] [--plan] [--output path] [--files a,b] [--match-source regex] [--match-export regex] [--scenario name] [--min-confidence level] [--require-confidence level] [--include regex] [--exclude regex] [--review] [--update] [--clean] [--changed] [--force] [--strict] [--write-hints] [--fail-on-skips] [--fail-on-conflicts]');
   console.log('  scan [path]             Alias for generate');
   console.log('  migrate <jest|vitest> [--rewrite-imports] [--convert]   Scaffold an incremental migration bridge for existing suites');
-  console.log('  test [--json] [--agent] [--next] [--reporter spec|next|json|agent|html] [--workers N] [--stability N] [--environment node|jsdom] [--isolation worker|in-process] [--cache] [--update-contracts] [-w|--watch] [--html-output path] [--match regex] [--rerun-failed] [--no-memes] [--lexicon classic|themis]');
+  console.log('  test [--json] [--agent] [--next] [--reporter spec|next|json|agent|html] [--workers N] [--stability N] [--environment node|jsdom] [--isolation worker|in-process] [--cache] [--update-contracts] [--fix] [-w|--watch] [--html-output path] [--match regex] [--rerun-failed] [--no-memes] [--lexicon classic|themis]');
 }
 
 function printGenerateSummary(summary, cwd) {