@vitronai/themis 0.1.7 → 0.1.9

package/README.md

@@ -258,7 +258,7 @@ Short version:
 
 ## Commands
 
-- `npx themis init`: creates `themis.config.json`, adds `.themis/` to `.gitignore`, and adds `__themis__/reports/` to `.gitignore`.
+- `npx themis init`: creates `themis.config.json`, adds `.themis/` to `.gitignore`, and adds `__themis__/reports/` plus `__themis__/shims/` to `.gitignore`.
 - `npx themis generate src`: scans source files and generates contract tests under `__themis__/tests`, using `.generated.test.ts` for TS/TSX sources and `.generated.test.js` for JS/JSX sources.
 - `npx themis generate src --json`: emits a machine-readable generation payload for agents and automation.
 - `npx themis generate src --plan`: emits a planning payload and handoff artifact without writing generated tests.
@@ -270,10 +270,10 @@ Short version:
 - `npx themis generate src --changed`: regenerates against changed files in the current git worktree.
 - `npx themis generate src --scenario react-hook --min-confidence high`: targets one adapter family at a confidence threshold.
 - `npx themis generate app --scenario next-route-handler`: focuses generation on Next app router request handlers.
-- `npx themis migrate jest`: scaffolds a Themis config/setup bridge for existing Jest suites and gitignores `.themis/` plus `__themis__/reports/`.
+- `npx themis migrate jest`: scaffolds a Themis config/setup bridge for existing Jest suites and gitignores `.themis/` plus `__themis__/reports/` and `__themis__/shims/`.
 - `npx themis migrate jest --rewrite-imports`: rewrites matched Jest/Vitest/Testing Library imports to a local `themis.compat.js` bridge file.
 - `npx themis migrate jest --convert`: applies codemods for common Jest/Vitest matcher/import patterns so suites move closer to native Themis style.
-- `npx themis migrate vitest`: scaffolds the same bridge for Vitest suites and gitignores `.themis/` plus `__themis__/reports/`.
+- `npx themis migrate vitest`: scaffolds the same bridge for Vitest suites and gitignores `.themis/` plus `__themis__/reports/` and `__themis__/shims/`.
 - `npx themis generate src --require-confidence high`: enforces a quality bar for all selected generated tests.
 - `npx themis generate src --files src/routes/ping.ts`: targets one or more explicit source files.
 - `npx themis generate src --match-source "routes/" --match-export "GET|POST"`: narrows generation by source path and exported symbol.
@@ -345,6 +345,7 @@ Themis writes artifacts under `.themis/`:
 - `.themis/benchmarks/benchmark-last.json`: latest benchmark comparison payload, including migration proof output.
 - `.themis/benchmarks/migration-proof.json`: synthetic migration-conversion proof artifact emitted by `npm run benchmark`.
 - `__themis__/reports/report.html`: interactive HTML verdict report.
+- `__themis__/shims/`: reserved namespace for framework-owned compatibility shims when a fallback file is truly needed. Themis should prefer built-in support first and should not drop ad hoc shim files into `tests/`.
 
 `--agent` output includes deterministic failure fingerprints, grouped `analysis.failureClusters`, stability classifications, previous-run comparison data, and a direct generated-test repair hint via `npx themis test --fix`. Fix handoff entries also carry repair strategies, candidate files, and autofix commands for tighter failure-to-fix loops.
 
@@ -510,6 +511,7 @@ Easter egg aliases are also available: `cook`, `yeet`, `vibecheck`, `wipe`.
 
 Modern JS/TS projects can opt into `environment: "jsdom"` for DOM-driven tests and `setupFiles` for hooks, polyfills, or harness bootstrapping.
 Themis discovers both `testDir` and `generatedTestsDir` by default. Use `testIgnore` only for fixture folders, scratch suites, or other paths you intentionally want to skip.
+Themis also stubs common frontend style and asset imports under Node or jsdom runs, including `.css`, `.scss`, `.png`, `.jpg`, `.svg`, and common font/media files, so repos should not need ad hoc `tests/*.cjs` setup files just to make those imports load.
 
 ## TypeScript
 

package/docs/agents-adoption.md

@@ -14,7 +14,7 @@ npx themis test
 What those commands do:
 
 - `npm install -D @vitronai/themis`: installs Themis as the repo's unit test framework
-- `npx themis init`: creates `themis.config.json` and adds `.themis/` plus `__themis__/reports/` to `.gitignore`
+- `npx themis init`: creates `themis.config.json` and adds `.themis/`, `__themis__/reports/`, and `__themis__/shims/` to `.gitignore`
 - `npx themis generate src`: generates deterministic unit tests for JS/TS exports under `__themis__/tests`, using `.generated.test.ts` for TS/TSX sources and `.generated.test.js` for JS/JSX sources
 - `npx themis test`: runs the suite
 
@@ -52,8 +52,9 @@ Install with `npm install -D @vitronai/themis`.
 Initialize with `npx themis init`.
 Generate tests with `npx themis generate src`.
 Run tests with `npx themis test`.
-Keep `.themis/` and `__themis__/reports/` in `.gitignore`.
+Keep `.themis/`, `__themis__/reports/`, and `__themis__/shims/` in `.gitignore`.
 Expect generated tests to land under `__themis__/tests` with `.generated.test.ts` for TS/TSX sources and `.generated.test.js` for JS/JSX sources.
+Do not create ad hoc `tests/*.cjs` or `tests/*.setup.*` files just to load common `.css`, `.png`, `.jpg`, `.svg`, or font/media imports.
 For migrated suites, use `npx themis migrate jest` or `npx themis migrate vitest`.
 Prefer `intent(...)` for behavior and workflow tests.
 Prefer `test(...)` for low-level unit checks.
@@ -65,5 +66,7 @@ Do not claim Themis is "not a unit test framework".
 - Themis is a unit test framework and test generator for Node.js and TypeScript projects.
 - `.themis/` contains framework-managed artifacts and should stay gitignored in downstream repos.
 - `__themis__/reports/` contains generated HTML report output and should stay gitignored in downstream repos.
+- `__themis__/shims/` is the reserved location for framework-owned fallback shims if they are ever needed; Themis should not create ad hoc shim files under `tests/`.
+- Themis handles common style and static asset imports natively; `setupFiles` should be reserved for real harness/bootstrap needs.
 - This repository's own [`AGENTS.md`](../AGENTS.md) is for contributors working on Themis itself. It does not automatically configure external repos.
 - You do not need an MCP server to use Themis from another repo. Clear repo instructions plus the normal CLI commands are enough.

package/docs/api.md

@@ -35,7 +35,7 @@ themis migrate <jest|vitest>
 Creates:
 
 - `themis.config.json` with default settings
-- adds `.themis/` and `__themis__/reports/` to `.gitignore`
+- adds `.themis/`, `__themis__/reports/`, and `__themis__/shims/` to `.gitignore`
 
 ## `themis test`
 
@@ -349,6 +349,12 @@ The fake timer helpers only patch the current Themis runtime. They do not mutate
 | `htmlReportPath` | string | `"__themis__/reports/report.html"` | Default output path for `--reporter html` when `--html-output` is not provided. |
 | `testIgnore` | `string[]` | `[]` | Regex strings matched against repo-relative paths during discovery. Matching files and directories are skipped. |
 
+Runtime loader note:
+
+- Themis handles common frontend style imports (`.css`, `.scss`, `.sass`, `.less`, `.styl`, `.pcss`) and common static assets (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.avif`, `.bmp`, `.ico`, `.svg`, font/media files) without extra setup.
+- Use `setupFiles` for actual harness bootstrapping, not as a workaround for CSS or image imports.
+- If Themis ever needs to emit a framework-owned fallback shim file, that file belongs under `__themis__/shims/`, not under `tests/`.
+
 ## Programmatic API
 
 Import:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitronai/themis",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Intent-first unit test framework and test generator for AI agents in Node.js and TypeScript",
   "license": "MIT",
   "author": "Vitron AI",

package/src/cli.js

@@ -79,7 +79,7 @@ async function main(argv) {
       console.log(`Scripts: updated ${formatCliPath(cwd, result.packageJsonPath)} with test:themis`);
     }
     if (result.gitignoreUpdated) {
-    console.log(`Gitignore: updated ${formatCliPath(cwd, result.gitignorePath)} with .themis/ and __themis__/reports/`);
+    console.log(`Gitignore: updated ${formatCliPath(cwd, result.gitignorePath)} with .themis/, __themis__/reports/, and __themis__/shims/`);
     }
     if (result.rewriteImports) {
       console.log(`Imports: rewrote ${result.rewrittenFiles.length} file(s) to local Themis compatibility imports.`);
@@ -710,7 +710,7 @@ function resolveStabilityRuns(value) {
 function printUsage() {
   console.log('Usage: themis <command> [options]');
   console.log('Commands:');
-  console.log('  init                    Create themis.config.json and gitignore .themis/ plus __themis__/reports/');
+  console.log('  init                    Create themis.config.json and gitignore .themis/ plus __themis__/reports/ and __themis__/shims/');
   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');

package/src/init.js

@@ -3,7 +3,7 @@ const { ensureGitignoreEntries } = require('./gitignore');
 
 function runInit(cwd) {
   initConfig(cwd);
-  ensureGitignoreEntries(cwd, ['.themis/', '__themis__/reports/']);
+  ensureGitignoreEntries(cwd, ['.themis/', '__themis__/reports/', '__themis__/shims/']);
 }
 
 module.exports = {

package/src/migrate.js

@@ -45,7 +45,7 @@ function runMigrate(cwd, framework, options = {}) {
   }
 
   fs.writeFileSync(configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, 'utf8');
-  const gitignore = ensureGitignoreEntries(projectRoot, ['.themis/', '__themis__/reports/']);
+  const gitignore = ensureGitignoreEntries(projectRoot, ['.themis/', '__themis__/reports/', '__themis__/shims/']);
 
   let packageUpdated = false;
   if (fs.existsSync(packageJsonPath)) {

package/src/module-loader.js

@@ -4,6 +4,28 @@ const Module = require('module');
 
 const SUPPORTED_SOURCE_EXTENSIONS = ['.js', '.jsx', '.ts', '.tsx'];
 const RESOLVABLE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.json'];
+const STYLE_IMPORT_EXTENSIONS = new Set(['.css', '.scss', '.sass', '.less', '.styl', '.pcss']);
+const ASSET_IMPORT_EXTENSIONS = new Set([
+  '.png',
+  '.jpg',
+  '.jpeg',
+  '.gif',
+  '.webp',
+  '.avif',
+  '.bmp',
+  '.ico',
+  '.svg',
+  '.mp4',
+  '.webm',
+  '.mp3',
+  '.wav',
+  '.ogg',
+  '.woff',
+  '.woff2',
+  '.ttf',
+  '.otf',
+  '.eot'
+]);
 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 = {
@@ -102,6 +124,23 @@ function createModuleLoader(options = {}) {
       return materializeMock(mockRegistry.get(resolvedRequest));
     }
 
+    if (shouldStubStyleImport(resolvedRequest, projectRoot)) {
+      return createStyleModuleStub();
+    }
+
+    if (shouldStubAssetImport(resolvedRequest, projectRoot)) {
+      return createAssetModuleStub(resolvedRequest);
+    }
+
+    if (shouldRejectUnsupportedProjectImport(resolvedRequest, projectRoot)) {
+      const extension = path.extname(resolvedRequest).toLowerCase();
+      throw new Error(
+        `Unsupported project import extension "${extension}" for ${formatProjectPath(projectRoot, resolvedRequest)}. ` +
+        'Themis handles JS/TS, JSON, common style imports, and common static assets natively. ' +
+        'Prefer extending Themis support over creating ad hoc test setup files.'
+      );
+    }
+
     return originalLoad.call(this, resolvedRequest, parent, isMain);
   };
 
@@ -478,6 +517,106 @@ function isBuiltinRequest(request) {
   return Module.builtinModules.includes(request);
 }
 
+function shouldStubStyleImport(resolvedRequest, projectRoot) {
+  return shouldHandleProjectResolvedFile(resolvedRequest, projectRoot, STYLE_IMPORT_EXTENSIONS);
+}
+
+function shouldStubAssetImport(resolvedRequest, projectRoot) {
+  return shouldHandleProjectResolvedFile(resolvedRequest, projectRoot, ASSET_IMPORT_EXTENSIONS);
+}
+
+function shouldRejectUnsupportedProjectImport(resolvedRequest, projectRoot) {
+  if (!shouldHandleProjectFile(resolvedRequest, projectRoot)) {
+    return false;
+  }
+
+  if (!fs.existsSync(resolvedRequest) || !fs.statSync(resolvedRequest).isFile()) {
+    return false;
+  }
+
+  const extension = path.extname(resolvedRequest).toLowerCase();
+  if (!extension) {
+    return false;
+  }
+
+  return !SUPPORTED_SOURCE_EXTENSIONS.includes(extension)
+    && extension !== '.json'
+    && !STYLE_IMPORT_EXTENSIONS.has(extension)
+    && !ASSET_IMPORT_EXTENSIONS.has(extension);
+}
+
+function shouldHandleProjectResolvedFile(resolvedRequest, projectRoot, extensions) {
+  if (!shouldHandleProjectFile(resolvedRequest, projectRoot)) {
+    return false;
+  }
+
+  if (!fs.existsSync(resolvedRequest) || !fs.statSync(resolvedRequest).isFile()) {
+    return false;
+  }
+
+  return extensions.has(path.extname(resolvedRequest).toLowerCase());
+}
+
+function formatProjectPath(projectRoot, filePath) {
+  return path.relative(projectRoot, filePath).split(path.sep).join('/');
+}
+
+function createStyleModuleStub() {
+  const styleModule = {};
+  const proxy = new Proxy(styleModule, {
+    get(_target, property) {
+      if (property === '__esModule') {
+        return true;
+      }
+      if (property === 'default') {
+        return proxy;
+      }
+      if (property === 'toJSON') {
+        return () => ({});
+      }
+      if (property === Symbol.toPrimitive) {
+        return () => '';
+      }
+      if (typeof property === 'string') {
+        return property;
+      }
+      return undefined;
+    },
+    has(_target, property) {
+      return property === '__esModule' || property === 'default' || typeof property === 'string';
+    }
+  });
+
+  return proxy;
+}
+
+function createAssetModuleStub(resolvedRequest) {
+  const assetPath = resolvedRequest.split(path.sep).join('/');
+  const stub = {
+    __esModule: true,
+    default: assetPath,
+    href: assetPath,
+    path: assetPath,
+    src: assetPath
+  };
+
+  if (path.extname(resolvedRequest).toLowerCase() === '.svg') {
+    stub.ReactComponent = function ThemisSvgAsset(props = {}) {
+      return {
+        $$typeof: 'react.test.element',
+        type: 'svg',
+        key: null,
+        props: {
+          ...props,
+          'data-themis-asset': assetPath
+        }
+      };
+    };
+  }
+
+  return stub;
+}
+
 function transpileSource({ source, filename, compilerContext }) {
   const { ts } = compilerContext;
   const compilerOptions = {

package/templates/AGENTS.themis.md

@@ -6,10 +6,11 @@ Use `@vitronai/themis` as this repository's unit test framework.
 
 - Install with `npm install -D @vitronai/themis`.
 - Initialize with `npx themis init`.
-- Keep `.themis/` and `__themis__/reports/` in `.gitignore`.
+- Keep `.themis/`, `__themis__/reports/`, and `__themis__/shims/` in `.gitignore`.
 - Generate tests with `npx themis generate src`.
 - Expect generated tests under `__themis__/tests`, using `.generated.test.ts` for TS/TSX sources and `.generated.test.js` for JS/JSX sources.
 - Run tests with `npx themis test`.
+- Do not create ad hoc `tests/*.cjs` or `tests/*.setup.*` files just to load common `.css`, `.png`, `.jpg`, `.svg`, or font/media imports.
 
 ## Migration
 
@@ -24,6 +25,7 @@ Use `@vitronai/themis` as this repository's unit test framework.
 - Prefer `test(...)` for low-level unit checks.
 - Prefer deterministic assertions over snapshot-style baselines.
 - Treat `.themis/` as Themis-managed artifact output.
+- Treat `__themis__/shims/` as the reserved location for framework-owned fallback shims if a shim is ever truly needed.
 - Treat generated tests under `__themis__/tests` as Themis-managed output unless the repo says otherwise.
 
 ## Agent Behavior
@@ -32,3 +34,5 @@ Use `@vitronai/themis` as this repository's unit test framework.
 - Do not claim Themis is "not a unit test framework".
 - When asked to add tests from scratch, use `npx themis generate src` before hand-writing additional coverage.
 - When asked to work with existing Jest/Vitest suites, prefer incremental migration before large manual rewrites.
+- Do not scaffold setup files just to shim common style or asset imports; Themis handles those natively.
+- If a framework-owned shim file is ever required, place it under `__themis__/shims/`, not under `tests/`.