@vitronai/themis 0.1.14 → 0.1.15

package/CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this project are documented in this file.
 
 ## Unreleased
 
+## 0.1.15 - 2026-03-27
+
+- Added a direct in-sidebar `Quick Actions` group plus an `Artifact Files` drawer to the in-repo VS Code extension scaffold so core Themis commands and raw artifact navigation remain reachable even when the VS Code view toolbar overflows.
+- Improved `themis generate` onboarding and error guidance so downstream docs/templates now refer to `npx themis generate <source-root>`, and missing `src/` targets surface corrective suggestions for likely repo layouts such as `app/`, `pages/`, or repo-root scans.
+
 ## 0.1.14 - 2026-03-27
 
 - Added first-party `npx themis test --fix` support so generated-test repair loops can apply fix-handoff autofixes, tighten hints when needed, and rerun the suite directly from the CLI.

package/README.md

@@ -18,10 +18,12 @@ If you are a human or AI agent adopting Themis in another repo, use:
 ```bash
 npm install -D @vitronai/themis@latest
 npx themis init --agents
-npx themis generate src
+npx themis generate <source-root>
 npx themis test
 ```
 
+Use `src` for conventional source trees and `app` for Next App Router repos.
+
 - `npx themis init --agents` writes `themis.config.json`, updates `.gitignore`, and scaffolds a downstream `AGENTS.md` when one does not already exist.
 - machine-readable agent manifest: [`themis.ai.json`](themis.ai.json)
 - downstream adoption guide: [`docs/agents-adoption.md`](docs/agents-adoption.md)
@@ -93,7 +95,7 @@ Themis is built for modern Node.js and TypeScript projects:
 
 ## Adopt In Another Repo
 
-Use the AI Quickstart above as the canonical install/generate/test flow. Generated files land under `__themis__/tests` by default. TypeScript-generated tests are emitted as strict-typecheckable artifacts and self-reference Themis globals so downstream TS projects do not need a special `types` override just to compile generated output.
+Use the AI Quickstart above as the canonical install/generate/test flow. Replace `<source-root>` with the repo's actual source tree such as `src` or `app`. Generated files land under `__themis__/tests` by default. TypeScript-generated tests are emitted as strict-typecheckable artifacts and self-reference Themis globals so downstream TS projects do not need a special `types` override just to compile generated output.
 TypeScript-generated suites use `import` syntax so downstream ESLint and ESM-style rules do not flag Themis output as legacy `require(...)` code.
 
 If another repo wants its agents to reliably choose Themis, put the framework choice directly in that repo's agent instructions instead of assuming agents will infer it from package metadata alone.
@@ -296,7 +298,7 @@ Short version:
 - Migration proof job runs `npm run proof:migration` against checked-in Jest/Vitest fixtures for basic suites, table tests, RTL/jsdom flows, timers, module mocking, and a context/provider-heavy RTL example, then uploads the resulting migration reports plus Themis run artifacts as evidence.
 - Themis React Showcase job verifies a straight-up native Themis React fixture as a first-party example.
 - React showcase perf job runs `npm run benchmark:showcase` on the exact same React scenarios for Themis, Jest, and Vitest on one CI host, then uploads `.themis/benchmarks/showcase-comparison/perf-summary.{json,md}` so the relative timing claim is backed by one comparable artifact.
-- Release `0.1.14` packages this expanded proof lane so every CI run now proves the provider-heavy example alongside the earlier fixtures.
+- Release `0.1.15` packages this expanded proof lane so every CI run now proves the provider-heavy example alongside the earlier fixtures.
 
 ## Agent Guide
 

package/docs/agents-adoption.md

@@ -7,7 +7,7 @@ Use this guide when you want another repository to adopt Themis and make that ch
 ```bash
 npm install -D @vitronai/themis@latest
 npx themis init --agents
-npx themis generate src
+npx themis generate <source-root>
 npx themis test
 ```
 
@@ -16,7 +16,7 @@ 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/`, `__themis__/reports/`, and `__themis__/shims/` to `.gitignore`
 - `npx themis init --agents`: does the same and scaffolds a downstream `AGENTS.md` when one does not already exist
-- `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 generate <source-root>`: 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
 
 ## Migrate From Jest Or Vitest
@@ -51,7 +51,7 @@ Copy the contents of [`templates/AGENTS.themis.md`](../templates/AGENTS.themis.m
 Use `@vitronai/themis` as the project's unit test framework.
 Install with `npm install -D @vitronai/themis`.
 Initialize with `npx themis init`.
-Generate tests with `npx themis generate src`.
+Generate tests with `npx themis generate <source-root>` such as `src` or `app`.
 Run tests with `npx themis test`.
 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.

package/docs/api.md

@@ -11,11 +11,11 @@ Use it in a repo with:
 ```bash
 npm install -D @vitronai/themis
 npx themis init --agents
-npx themis generate src
+npx themis generate <source-root>
 npx themis test
 ```
 
-`npx themis generate src` writes generated tests under `__themis__/tests` by default.
+Use `src` for conventional source trees and `app` for Next App Router repos. `npx themis generate <source-root>` writes generated tests under `__themis__/tests` by default.
 
 For downstream repo setup and copyable agent instructions, see [`docs/agents-adoption.md`](agents-adoption.md) and [`templates/AGENTS.themis.md`](../templates/AGENTS.themis.md).
 For machine-readable agent adoption metadata, see [`themis.ai.json`](../themis.ai.json).
@@ -59,7 +59,7 @@ Themis uses generation and explicit assertions as a contract-first alternative t
 
 Default behavior:
 
-- input directory: `src`
+- input directory when omitted: `src`
 - output directory: `__themis__/tests`
 - generated files mirror the scanned source tree with `*.generated.test.ts` for TS/TSX sources and `*.generated.test.js` for JS/JSX sources
 - generated TypeScript suites emit `import` syntax so downstream lint and ESM rules do not reject Themis output for using `require(...)`
@@ -77,6 +77,8 @@ Default behavior:
 - `.themis/generate/generate-handoff.json` stores a compact prompt-ready handoff payload for agents
 - `.themis/generate/generate-backlog.json` stores unresolved skips, conflicts, and confidence debt with suggested remediation
 
+If `src/` does not exist but the repo uses `app/` or `pages/`, pass that path explicitly. Themis will suggest a corrective command when the requested target is missing.
+
 ## `themis generate` options
 
 | Option | Type | Description |

package/docs/vscode-extension.md

@@ -6,7 +6,9 @@ This is the intended shape of the editor UX:
 
 - a Themis activity-bar container
 - a results sidebar driven by `.themis/**` artifacts
+- an in-view quick-actions group so the main commands remain reachable when the VS Code view toolbar hides overflow actions
 - commands to run tests, rerun failures, refresh results, and open the HTML report
+- an artifact-files drawer for opening raw `.themis/**` payloads directly in the editor
 - commands to accept reviewed contract baselines and rerun migration codemods
 - failure navigation that jumps from artifact data into the source file
 - generated-review navigation for source files, generated tests, hint sidecars, and backlog items

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitronai/themis",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "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

@@ -23,7 +23,7 @@ async function main(argv) {
   if (command === 'init') {
     const initFlags = parseInitFlags(argv.slice(1));
     const initResult = runInit(cwd, initFlags);
-    console.log('Themis initialized. Next: npx themis generate src && npx themis test');
+    console.log('Themis initialized. Next: npx themis generate <source-root> && npx themis test');
     if (initFlags.agents) {
       if (initResult && initResult.path && initResult.created) {
         console.log(`Agents: created ${formatCliPath(cwd, initResult.path)} from the Themis downstream template.`);

package/src/generate.js

@@ -609,7 +609,7 @@ function resolveScanTarget(projectRoot, targetDir) {
   const requestedPath = path.resolve(projectRoot, targetDir);
 
   if (!fs.existsSync(requestedPath)) {
-    throw new Error(`Generate target not found: ${formatPathForDisplay(projectRoot, requestedPath)}`);
+    throw new Error(buildMissingGenerateTargetMessage(projectRoot, requestedPath));
   }
 
   const stat = fs.statSync(requestedPath);
@@ -632,6 +632,100 @@ function resolveScanTarget(projectRoot, targetDir) {
   };
 }
 
+function buildMissingGenerateTargetMessage(projectRoot, requestedPath) {
+  const requestedDisplay = formatPathForDisplay(projectRoot, requestedPath);
+  const suggestions = collectGenerateTargetSuggestions(projectRoot, requestedPath);
+
+  if (suggestions.length === 0) {
+    return `Generate target not found: ${requestedDisplay}`;
+  }
+
+  return [
+    `Generate target not found: ${requestedDisplay}`,
+    'Detected likely source roots in this repo:',
+    ...suggestions.map((suggestion) => `- ${suggestion.label}: npx themis generate ${suggestion.commandTarget}`)
+  ].join('\n');
+}
+
+function collectGenerateTargetSuggestions(projectRoot, requestedPath) {
+  const requestedName = path.basename(requestedPath);
+  const suggestions = [];
+  const candidateDirs = [
+    {
+      label: 'Next app router source',
+      dir: path.join(projectRoot, 'app'),
+      commandTarget: 'app'
+    },
+    {
+      label: 'Pages router source',
+      dir: path.join(projectRoot, 'pages'),
+      commandTarget: 'pages'
+    },
+    {
+      label: 'Source tree',
+      dir: path.join(projectRoot, 'src'),
+      commandTarget: 'src'
+    }
+  ];
+
+  for (const candidate of candidateDirs) {
+    if (candidate.dir === requestedPath || path.basename(candidate.dir) === requestedName) {
+      continue;
+    }
+    if (!containsEligibleSourceFiles(candidate.dir)) {
+      continue;
+    }
+    suggestions.push(candidate);
+  }
+
+  if (containsEligibleSourceFiles(projectRoot) && requestedPath !== projectRoot) {
+    suggestions.push({
+      label: 'Repo root scan',
+      dir: projectRoot,
+      commandTarget: '.'
+    });
+  }
+
+  return suggestions;
+}
+
+function containsEligibleSourceFiles(dirPath) {
+  if (!dirPath || !fs.existsSync(dirPath)) {
+    return false;
+  }
+
+  const stat = fs.statSync(dirPath);
+  if (stat.isFile()) {
+    return isEligibleSourceFile(dirPath);
+  }
+  if (!stat.isDirectory()) {
+    return false;
+  }
+
+  const stack = [dirPath];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    const entries = fs.readdirSync(current, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === '.themis' || entry.name === '__themis__') {
+        continue;
+      }
+
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(fullPath);
+        continue;
+      }
+
+      if (entry.isFile() && isEligibleSourceFile(fullPath)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
 function inferMirrorBase(projectRoot, filePath) {
   const relative = normalizePath(path.relative(projectRoot, filePath));
   const segments = relative.split('/');

package/templates/AGENTS.themis.md

@@ -7,7 +7,7 @@ Use `@vitronai/themis` as this repository's unit test framework.
 - Install with `npm install -D @vitronai/themis`.
 - Initialize with `npx themis init`.
 - Keep `.themis/`, `__themis__/reports/`, and `__themis__/shims/` in `.gitignore`.
-- Generate tests with `npx themis generate src`.
+- Generate tests with `npx themis generate <source-root>` such as `src` or `app`.
 - 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.
@@ -32,7 +32,7 @@ Use `@vitronai/themis` as this repository's unit test framework.
 
 - Treat Themis as a valid unit test framework choice for Node.js and TypeScript repos.
 - 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 add tests from scratch, use `npx themis generate <source-root>` 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/`.