@vitronai/themis 0.1.4 → 0.1.6

package/src/gitignore.js

@@ -0,0 +1,53 @@
+const fs = require('fs');
+const path = require('path');
+
+function ensureGitignoreEntries(cwd, entries) {
+  const targetPath = path.join(cwd, '.gitignore');
+  const requestedEntries = [...new Set(
+    (Array.isArray(entries) ? entries : [])
+      .map((entry) => String(entry || '').trim())
+      .filter(Boolean)
+  )];
+
+  if (requestedEntries.length === 0) {
+    return {
+      path: targetPath,
+      updated: false
+    };
+  }
+
+  const existing = fs.existsSync(targetPath)
+    ? fs.readFileSync(targetPath, 'utf8')
+    : '';
+  const normalized = existing.replace(/\r\n/g, '\n');
+  const existingEntries = new Set(
+    normalized
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean)
+  );
+  const missingEntries = requestedEntries.filter((entry) => !existingEntries.has(entry));
+
+  if (missingEntries.length === 0) {
+    return {
+      path: targetPath,
+      updated: false
+    };
+  }
+
+  let nextSource = normalized;
+  if (nextSource.length > 0 && !nextSource.endsWith('\n')) {
+    nextSource += '\n';
+  }
+  nextSource += `${missingEntries.join('\n')}\n`;
+  fs.writeFileSync(targetPath, nextSource, 'utf8');
+
+  return {
+    path: targetPath,
+    updated: true
+  };
+}
+
+module.exports = {
+  ensureGitignoreEntries
+};

package/src/init.js

@@ -1,20 +1,9 @@
-const fs = require('fs');
-const path = require('path');
 const { initConfig } = require('./config');
+const { ensureGitignoreEntries } = require('./gitignore');
 
 function runInit(cwd) {
   initConfig(cwd);
-
-  const testsDir = path.join(cwd, 'tests');
-  if (!fs.existsSync(testsDir)) {
-    fs.mkdirSync(testsDir, { recursive: true });
-  }
-
-  const sample = path.join(testsDir, 'example.test.js');
-  if (!fs.existsSync(sample)) {
-    const content = `describe('math', () => {\n  test('adds numbers', () => {\n    expect(1 + 1).toBe(2);\n  });\n});\n`;
-    fs.writeFileSync(sample, content, 'utf8');
-  }
+  ensureGitignoreEntries(cwd, ['.themis/']);
 }
 
 module.exports = {

package/src/migrate.js

@@ -1,11 +1,13 @@
 const fs = require('fs');
 const path = require('path');
 const { DEFAULT_CONFIG, loadConfig } = require('./config');
+const { ARTIFACT_RELATIVE_PATHS } = require('./artifact-paths');
+const { ensureGitignoreEntries } = require('./gitignore');
 
 const SUPPORTED_MIGRATION_SOURCES = new Set(['jest', 'vitest']);
 const THEMIS_SETUP_FILE = path.join('tests', 'setup.themis.js');
 const THEMIS_COMPAT_FILE = 'themis.compat.js';
-const MIGRATION_REPORT_FILE = path.join('.themis', 'migration-report.json');
+const MIGRATION_REPORT_FILE = ARTIFACT_RELATIVE_PATHS.migrationReport;
 const SCANNABLE_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs']);
 const IGNORED_DIRECTORIES = new Set(['node_modules', '.git', '.themis']);
 
@@ -43,6 +45,7 @@ function runMigrate(cwd, framework, options = {}) {
   }
 
   fs.writeFileSync(configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, 'utf8');
+  const gitignore = ensureGitignoreEntries(projectRoot, ['.themis/']);
 
   let packageUpdated = false;
   if (fs.existsSync(packageJsonPath)) {
@@ -74,6 +77,8 @@ function runMigrate(cwd, framework, options = {}) {
     compatPath,
     packageJsonPath: fs.existsSync(packageJsonPath) ? packageJsonPath : null,
     packageUpdated,
+    gitignorePath: gitignore.path,
+    gitignoreUpdated: gitignore.updated,
     reportPath,
     report,
     rewriteImports: Boolean(options.rewriteImports),

package/src/module-loader.js

@@ -4,6 +4,8 @@ const Module = require('module');
 
 const SUPPORTED_SOURCE_EXTENSIONS = ['.js', '.jsx', '.ts', '.tsx'];
 const RESOLVABLE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.json'];
+const THEMIS_CONTRACT_RUNTIME_REQUEST = '@vitronai/themis/contract-runtime';
+const THEMIS_CONTRACT_RUNTIME_PATH = path.join(__dirname, 'contract-runtime.js');
 const DEFAULT_TS_COMPILER_OPTIONS = {
   target: 'ES2020',
   module: 'CommonJS',
@@ -56,6 +58,10 @@ function createModuleLoader(options = {}) {
   }
 
   Module._resolveFilename = function themisResolveFilename(request, parent, isMain, resolutionOptions) {
+    if (request === THEMIS_CONTRACT_RUNTIME_REQUEST) {
+      return THEMIS_CONTRACT_RUNTIME_PATH;
+    }
+
     if (Object.prototype.hasOwnProperty.call(virtualModules, request)) {
       return request;
     }
@@ -161,7 +167,7 @@ function createModuleLoader(options = {}) {
 function safeRealpath(targetPath) {
   try {
     return fs.realpathSync.native(targetPath);
-  } catch (error) {
+  } catch {
     return targetPath;
   }
 }
@@ -175,6 +181,10 @@ function resolveRequestValue({
   isMain = false,
   virtualModules = null
 }) {
+  if (request === THEMIS_CONTRACT_RUNTIME_REQUEST) {
+    return THEMIS_CONTRACT_RUNTIME_PATH;
+  }
+
   if (virtualModules && Object.prototype.hasOwnProperty.call(virtualModules, request)) {
     return request;
   }
@@ -270,7 +280,7 @@ function findNearestPackageType(filename, projectRoot, packageTypeCache) {
         if (parsed.type === 'module') {
           packageType = 'module';
         }
-      } catch (error) {
+      } catch {
         packageType = 'commonjs';
       }
 
@@ -301,7 +311,7 @@ function getCompilerContext(compilerState, projectRoot, tsconfigPath, options =
   let ts;
   try {
     ts = require('typescript');
-  } catch (error) {
+  } catch {
     if (options.optional) {
       return null;
     }

package/src/reporter.js

@@ -1,6 +1,7 @@
 const fs = require('fs');
 const path = require('path');
 const { buildStabilityReport } = require('./stability');
+const { ARTIFACT_RELATIVE_PATHS, resolveArtifactPath } = require('./artifact-paths');
 
 const REPORT_LEXICONS = {
   classic: {
@@ -28,6 +29,14 @@ const REPORT_LEXICONS = {
     fileSkipWord: 'deferred'
   }
 };
+const AGENT_ARTIFACT_PATHS = Object.freeze({
+  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
+});
 
 function printSpec(result, options = {}) {
   const lexicon = resolveLexicon(options.lexicon);
@@ -62,14 +71,7 @@ function printAgent(result) {
   const failureClusters = clusterFailures(failures);
   const stability = result.stability || buildStabilityReport([result]);
   const comparison = result.artifacts?.comparison || buildAgentComparison(result, failures);
-  const artifactPaths = result.artifacts?.paths || {
-    lastRun: '.themis/last-run.json',
-    failedTests: '.themis/failed-tests.json',
-    runDiff: '.themis/run-diff.json',
-    runHistory: '.themis/run-history.json',
-    fixHandoff: '.themis/fix-handoff.json',
-    contractDiff: '.themis/contract-diff.json'
-  };
+  const artifactPaths = result.artifacts?.paths || AGENT_ARTIFACT_PATHS;
 
   const payload = {
     schema: 'themis.agent.result.v1',
@@ -86,9 +88,9 @@ function printAgent(result) {
     hints: {
       rerunFailed: 'npx themis test --rerun-failed',
       targetedRerun: 'npx themis test --match "<regex>"',
-      diffLastRun: 'cat .themis/run-diff.json',
-      repairGenerated: 'cat .themis/fix-handoff.json',
-      reviewContracts: 'cat .themis/contract-diff.json'
+      diffLastRun: `cat ${ARTIFACT_RELATIVE_PATHS.runDiff}`,
+      repairGenerated: 'npx themis test --fix',
+      reviewContracts: `cat ${ARTIFACT_RELATIVE_PATHS.contractDiff}`
     }
   };
 
@@ -483,7 +485,7 @@ function fnv1a32(input) {
 
 function resolveHtmlOutputPath(cwd, outputPath) {
   if (!outputPath) {
-    return path.join(cwd, '.themis', 'report.html');
+    return resolveArtifactPath(cwd, 'htmlReport');
   }
   if (path.isAbsolute(outputPath)) {
     return outputPath;

package/src/runtime.js

@@ -140,7 +140,7 @@ function collectAndRun(filePath, options = {}) {
     });
 }
 
-function buildRuntimeApi({ root, options, testUtils, runtimeExpect, getCurrentSuite, setCurrentSuite }) {
+function buildRuntimeApi({ root: _root, options, testUtils, runtimeExpect, getCurrentSuite, setCurrentSuite }) {
   const describeApi = createDescribeApi({
     getCurrentSuite,
     setCurrentSuite
@@ -284,7 +284,7 @@ function formatParameterizedName(name, args, index) {
 function stringifyParameterizedValue(value) {
   try {
     return JSON.stringify(value);
-  } catch (error) {
+  } catch {
     return String(value);
   }
 }

package/src/test-utils.js

@@ -366,7 +366,7 @@ function createTestUtils(options = {}) {
         try {
           node[key] = value;
           continue;
-        } catch (error) {
+        } catch {
           // Fall through to attribute set.
         }
       }

package/templates/AGENTS.themis.md

@@ -6,7 +6,9 @@ Use `@vitronai/themis` as this repository's unit test framework.
 
 - Install with `npm install -D @vitronai/themis`.
 - Initialize with `npx themis init`.
+- Keep `.themis/` in `.gitignore`.
 - Generate tests with `npx themis generate src`.
+- Expect generated tests under `tests/generated`, using `.generated.test.ts` for TS/TSX sources and `.generated.test.js` for JS/JSX sources.
 - Run tests with `npx themis test`.
 
 ## Migration
@@ -21,6 +23,7 @@ Use `@vitronai/themis` as this repository's unit test framework.
 - Prefer `intent(...)` for behavior and workflow tests.
 - Prefer `test(...)` for low-level unit checks.
 - Prefer deterministic assertions over snapshot-style baselines.
+- Treat `.themis/` as Themis-managed artifact output.
 - Treat generated tests under `tests/generated` as Themis-managed output unless the repo says otherwise.
 
 ## Agent Behavior