SilentSpec

Before / After

Three exported functions, no tests:

// src/math.ts
export function add(a: number, b: number): number {
  return a + b;
}
export function multiply(a: number, b: number): number {
  return a * b;
}
export function clamp(n: number, min: number, max: number): number {
  return Math.min(Math.max(n, min), max);
}

After first save — spec file created automatically:

// src/math.spec.ts  (created beside source)
// @auto-generated by SilentSpec | 2026-04-05
// Functions covered: add, multiply, clamp
// <SS-IMPORTS-START>
import { add, multiply, clamp } from "./math";
// <SS-IMPORTS-END>
// <SS-HELPERS-START>
// <SS-HELPERS-END>
// <SS-USER-TESTS>
// Add your own tests here — SilentSpec will never modify this section
// </SS-USER-TESTS>
// <SS-GENERATED-START v="1" covered="add,multiply,clamp" pending="">
describe("add", () => {
  it("should add two positive numbers", () => {
    expect(add(2, 3)).toBe(5);
  });
  it("should handle negative numbers", () => {
    expect(add(-1, 1)).toBe(0);
  });
});
describe("multiply", () => {
  it("should multiply two numbers", () => {
    expect(multiply(3, 4)).toBe(12);
  });
  it("should return 0 when either operand is 0", () => {
    expect(multiply(5, 0)).toBe(0);
  });
});
describe("clamp", () => {
  it("should clamp value above max", () => {
    expect(clamp(10, 0, 5)).toBe(5);
  });
  it("should clamp value below min", () => {
    expect(clamp(-5, 0, 10)).toBe(0);
  });
  it("should return value when within range", () => {
    expect(clamp(3, 0, 10)).toBe(3);
  });
});
// <SS-GENERATED-END>

You add a 4th function and save again. Only divide gets a new test — everything else is untouched.

// SS-GENERATED-START marker after second save:
// <SS-GENERATED-START v="1" covered="add,multiply,clamp,divide" pending="">
//
// ↑ divide added to covered list
// ↑ new describe("divide", ...) appended below existing tests
// ↑ existing describe blocks for add, multiply, clamp — unchanged

Why SilentSpec

Most AI test tools regenerate entire files on every run. They overwrite the tests you wrote by hand, and the output often doesn't compile on the first try. You end up maintaining generated tests instead of writing features.

SilentSpec is different:

• Only generates what's missing. It tracks which exported functions already have tests and only calls the AI for uncovered ones.
• Your tests are protected. Hand-written tests live in the SS-USER-TESTS zone — a section that is never modified after creation. This is enforced at write time, not in the prompt.
• Tests are compiler-checked before writing. After generation, SilentSpec runs a TypeScript compiler pass. When compile errors are detected, broken tests are removed before writing. On first generation of a new spec file, the healer verifies against the existing project — full diagnostic repair activates on subsequent saves. Semantic correctness still requires human review.

How It Works

Save file
   │
   ▼
Pre-debounce checks (untitled / non-file / no workspace / disabled / paused /
                      test file / unsupported ext / too large)
   │
   ▼
2-second debounce
   │
   ▼
Post-debounce checks (formatter re-save / unmanaged spec)
   │
   ▼
AST analysis — extract exported functions only
   │
   ▼
Compare covered list against current exports → compute gaps
   │
   ▼
AI call → validate response → fix imports
   │
   ▼
Healer — TypeScript compiler analysis → remove broken tests
   │
   ▼
Write spec file — 4-zone structure, SS-USER-TESTS never touched

Generation is batched: up to 5 functions per AI call. GitHub Models is additionally capped at 2–3 functions to stay within the free tier's output token limit. The SSMarker comment in the spec file tracks which functions are covered across saves, so each run only calls the AI for what's actually missing.

Zone Architecture

Four zones keep system-managed content separate from your tests:

// @auto-generated by SilentSpec | 2026-04-05
// Source: src/utils/formatting.ts
// Functions covered: formatCurrency, formatDate, truncate

// <SS-IMPORTS-START>                         ← SYSTEM: replaced every run
import { formatCurrency, formatDate, truncate } from "../utils/formatting";
jest.mock("date-fns", () => ({ format: jest.fn(() => "2026-01-01") }));
// <SS-IMPORTS-END>

// <SS-HELPERS-START>                         ← SYSTEM: replaced every run
const fakeCurrency = (amount: number, code: string) =>
  ({ amount, code }) as unknown as CurrencyInput;
// <SS-HELPERS-END>

// <SS-USER-TESTS>                            ← YOUR TESTS: never modified
// Write integration tests, complex mocks, edge cases the AI misses.
// SilentSpec will never modify this section — it's yours.
describe("formatCurrency — edge cases I care about", () => {
  it("should use parentheses for negative values in accounting mode", () => {
    expect(formatCurrency(-100, "USD", { style: "accounting" })).toBe(
      "(100.00)",
    );
  });
});
// </SS-USER-TESTS>

// <SS-GENERATED-START v="1" covered="formatCurrency,formatDate,truncate" pending="">
// ← SYSTEM: AI-generated tests, replaced when coverage changes
describe("formatCurrency", () => {
  /* ... */
});
describe("formatDate", () => {
  /* ... */
});
describe("truncate", () => {
  /* ... */
});
// <SS-GENERATED-END>

System zones (SS-IMPORTS, SS-HELPERS, SS-GENERATED) are fully replaced on each run. The SS-USER-TESTS zone is written once and never touched again.

Quick Start

1. Install

Search for SilentSpec in the VS Code Extensions panel, or install from the Marketplace.

2. Open a project

Open any TypeScript or JavaScript project folder. SilentSpec activates automatically.

3. Save a file

Save any .ts, .tsx, .js, or .jsx file that exports functions. A spec file appears in your existing __tests__ directory if one is present, or beside the source file otherwise.

Provider Setup

Set your provider: VS Code Settings → search silentspec.provider.

Set your API key: Command Palette (Cmd/Ctrl+Shift+P) → SilentSpec: Set API Key.

Ollama users: install Ollama from ollama.com, run ollama pull deepseek-coder:6.7b, then start Ollama before launching VS Code. SilentSpec detects it on activation and uses it automatically when no provider is explicitly set.

Supported Languages & Frameworks

Languages

Frameworks (auto-detected from package.json)

Framework is detected by walking up from the saved file to the nearest package.json that declares a known test framework. Monorepo sub-packages are detected independently.

Provider Comparison

Ollama model selection: SilentSpec prefers deepseek-coder:6.7b → deepseek-coder → codellama → llama3.2 in order of preference, picking the first installed model. Override with silentspec.model.

File System Impact

Files Created

• Spec files — .spec.ts (or .tsx / .js / .jsx) placed using a 5-pass algorithm: existing spec in adjacent __tests__ or test subfolder → existing spec in same directory as source → existing spec in root test directory (lookup only — never creates here) → new file in established adjacent test directory → new file beside the source as fallback. Collision detection uses the // Source: header to verify ownership before claiming an existing spec file.
• globalStorageUri/stats.json — local telemetry, in a VS Code-managed directory.

Files Modified

• Existing SilentSpec-managed spec files — system zones (SS-IMPORTS, SS-HELPERS, SS-GENERATED) are updated on each run; SS-USER-TESTS is never modified.
• tsconfig.json — only if you explicitly click "Fix tsconfig automatically" in the preflight warning notification. This adds the detected framework to compilerOptions.types.

SilentSpec never modifies source files, node_modules, package.json, or any file that does not have SilentSpec zone markers. It never modifies unmanaged test files.

Preflight auto-install: when @types/jest (or equivalent) is missing, SilentSpec attempts a silent install before the first generation. This modifies node_modules and the lock file, but not your source code. If the install fails, SilentSpec continues in safe mode and shows a notification with the manual install command.

On Uninstall

Generated spec files remain on disk — they are yours. VS Code cleans up globalStorageUri automatically. No orphaned processes, no background tasks.

Offline & Air-Gapped Use

The Ollama provider works fully offline. Framework detection, AST analysis, zone parsing, and the healer all run locally using the TypeScript compiler API — no network required for these steps. Only the AI generation step requires a provider connection.

Cloud providers (GitHub Models, Claude, OpenAI) require internet access for every generation call.

Known Limitations

• Ollama must be running before VS Code starts. The health check runs once on activation. If Ollama starts later in the session, set silentspec.provider: "ollama" explicitly or restart VS Code.
• Files over 1,500 lines or 200,000 characters are skipped. This is a deliberate gate to avoid excessive token usage and slow healer runs on very large files.
• Only exported functions and classes are detected. Non-exported functions, export default object literals, and TypeScript namespace exports are not currently analyzed by the AST gate.
• Remote SSH, Dev Containers, and WSL have limited support. SilentSpec uses Node fs and child_process directly. A warning is shown on activation in remote environments.
• silentspec.findGaps runs in full healer mode regardless of preflight result. If @types are missing, some healer diagnostics may be incomplete.
• Generated tests require review for semantic correctness. The healer removes tests that don't compile, but cannot verify that a test correctly describes your function's intended behavior.
• First-generation healer limitation. On the very first save for a new spec file, the healer's pre-check runs against the existing (clean) project and may short-circuit. Full diagnostic repair activates on subsequent saves once the spec file exists on disk.
• testsHealedSuccessfully is always 0 in the impact report. The healer tracks test removal but not repair — this counter is reserved for a future healer repair feature.
• GitHub Models free tier is limited to approximately 50 requests per day. Each save that triggers generation uses one request per batch call.

Privacy, Data & Security

Contributing

npm install
npm run compile   # type-check + lint + build
npm test          # run the test suite

Report bugs and feature requests at github.com/BHARADWAJ-MADDURI/silent-spec/issues.

License

Apache License 2.0 — Copyright 2026 Bharadwaj Madduri.