agentic-qe 3.14.5 → 3.14.7

package/dist/domains/test-generation/services/test-generator.js

@@ -6,13 +6,15 @@
  * Uses TypeScript AST parser for code analysis
  * Delegates to specialized services for TDD, property tests, and test data
  */
+import { generateBehaviorExamples } from './behavior-examples.js';
+import { validateBehaviorExamples } from './behavior-example-validation.js';
 import { LoggerFactory } from '../../../logging/index.js';
 import { v4 as uuidv4 } from 'uuid';
 import * as fs from 'fs';
 import * as path from 'path';
 import ts from 'typescript';
 import { ok, err } from '../../../shared/types/index.js';
-import { toErrorMessage } from '../../../shared/error-utils.js';
+import { CallerInputError, toErrorMessage } from '../../../shared/error-utils.js';
 import { TestGeneratorFactory } from '../factories/test-generator-factory.js';
 import { TDDGeneratorService } from './tdd-generator.js';
 import { PropertyTestGeneratorService } from './property-test-generator.js';
@@ -83,6 +85,7 @@ export class TestGeneratorService {
     config;
     memory;
     generatorFactory;
+    usesDefaultGenerator;
     tddGenerator;
     propertyTestGenerator;
     testDataGenerator;
@@ -92,6 +95,7 @@ export class TestGeneratorService {
     constructor(dependencies, config = {}) {
         this.config = { ...DEFAULT_CONFIG, ...config };
         this.memory = dependencies.memory;
+        this.usesDefaultGenerator = !dependencies.generatorFactory;
         this.generatorFactory = dependencies.generatorFactory || new TestGeneratorFactory();
         this.tddGenerator = dependencies.tddGenerator || new TDDGeneratorService();
         this.propertyTestGenerator = dependencies.propertyTestGenerator || new PropertyTestGeneratorService();
@@ -123,11 +127,11 @@ export class TestGeneratorService {
      * Enhance generated test code using LLM
      * Adds edge cases, improves assertions, and adds documentation
      */
-    async enhanceTestWithLLM(testCode, sourceCode, analysis, sourceFilePath, context) {
+    async enhanceTestWithLLM(testCode, sourceCode, analysis, sourceFilePath, context, showSourcePath = true) {
         if (!this.llmRouter)
             return { code: testCode, enhanced: false };
         try {
-            let prompt = this.buildTestEnhancementPrompt(testCode, sourceCode, analysis);
+            let prompt = this.buildTestEnhancementPrompt(testCode, sourceCode, analysis, showSourcePath ? sourceFilePath : undefined, context?.importPath);
             // Prepend historical edge case patterns if injector is available (loki-mode Item 5)
             if (this.edgeCaseInjector) {
                 try {
@@ -223,8 +227,17 @@ Return ONLY the enhanced test code, no explanations.`,
     /**
      * Build prompt for test enhancement
      */
-    buildTestEnhancementPrompt(testCode, sourceCode, analysis) {
-        let prompt = `## Source Code to Test:\n\`\`\`typescript\n${sourceCode}\n\`\`\`\n\n`;
+    buildTestEnhancementPrompt(testCode, sourceCode, analysis, sourceFilePath, importPath) {
+        let prompt = '';
+        if (sourceFilePath || importPath) {
+            prompt += '## Module Under Test:\n';
+            if (sourceFilePath)
+                prompt += `- Source file: ${sourceFilePath}\n`;
+            if (importPath)
+                prompt += `- Import it in the tests from: '${importPath}'\n`;
+            prompt += '\n';
+        }
+        prompt += `## Source Code to Test:\n\`\`\`typescript\n${sourceCode}\n\`\`\`\n\n`;
         prompt += `## Current Test Code:\n\`\`\`typescript\n${testCode}\n\`\`\`\n\n`;
         if (analysis) {
             if (analysis.functions.length > 0) {
@@ -303,6 +316,8 @@ Return a JSON array of test suggestions, each with: { "name": "test name", "desc
      */
     async generateTests(request) {
         try {
+            // Throws CallerInputError (caught below) for malformed examples.
+            validateBehaviorExamples(request.behaviorExamples);
             // Auto-detect language and framework if not provided (ADR-078)
             const resolved = resolveRequest({
                 sourceFiles: request.sourceFiles,
@@ -312,7 +327,10 @@ Return a JSON array of test suggestions, each with: { "name": "test name", "desc
             });
             const effectiveFramework = (request.framework || resolved?.framework || 'vitest');
             const effectiveLanguage = request.language || resolved?.language;
-            const { sourceFiles, testType, coverageTarget = this.config.coverageTargetDefault, patterns = [], } = request;
+            const { sourceFiles, testType, patterns = [], } = request;
+            if (request.behaviorExamples?.length && sourceFiles.length !== 1) {
+                return err(new CallerInputError('behaviorExamples requires exactly one source file'));
+            }
             if (sourceFiles.length === 0) {
                 return err(new Error('No source files provided'));
             }
@@ -335,7 +353,9 @@ Return a JSON array of test suggestions, each with: { "name": "test name", "desc
                     }
                 }
             }
-            const coverageEstimate = this.estimateCoverage(tests, coverageTarget);
+            // Generation does not execute or instrument the source. Assertion counts
+            // are not coverage evidence, including LLM-generated and empty results.
+            const coverageEstimate = null;
             await this.storeGenerationMetadata(tests, patternsUsed);
             return ok({
                 tests,
@@ -458,16 +478,41 @@ Return a JSON array of test suggestions, each with: { "name": "test name", "desc
             dependencies,
             similarCode,
         };
-        let testCode = generator.generateTests(context);
-        // ADR-051: Enhance with LLM if enabled and available.
+        const hasExamples = (originalRequest?.behaviorExamples?.length ?? 0) > 0;
+        const jsSource = /\.(?:[cm]?[jt]s|[jt]sx)$/i.test(sourceFile);
+        const deterministicEligible = (this.usesDefaultGenerator || hasExamples)
+            && testType === 'unit' && jsSource && ['vitest', 'jest', 'node-test'].includes(framework);
+        if (hasExamples && !deterministicEligible) {
+            throw new CallerInputError('Behavior examples require JavaScript/TypeScript and vitest, jest, or node-test');
+        }
+        const buildDeterministic = () => generateBehaviorExamples(sourceContent, sourceFile, originalRequest?.importPathOverrides?.[sourceFile] ?? path.resolve(sourceFile), framework, originalRequest?.behaviorExamples, testType);
+        // ADR-051: Enhance with LLM if enabled and available. Caller-supplied
+        // behavior examples are the oracle, so they are never rewritten by an LLM.
         // #567: `llmEnhanced` reflects whether the LLM actually produced the code,
         // not merely whether a router was configured — a broken provider must not
         // report AI-enhanced output it did not produce.
+        const willEnhance = this.isLLMEnhancementAvailable() && !!sourceContent && !hasExamples;
+        // #795: without fixtures the LLM must start from the framework template,
+        // which carries the real import line for the module under test. The
+        // zero-assertion scaffold is only emitted when no LLM output is used.
+        let deterministic = deterministicEligible && !willEnhance ? buildDeterministic() : undefined;
+        let testCode = deterministic?.code ?? generator.generateTests(context);
         let llmEnhanced = false;
-        if (this.isLLMEnhancementAvailable() && sourceContent) {
-            const result = await this.enhanceTestWithLLM(testCode, sourceContent, codeAnalysis, sourceFile, context);
-            testCode = result.code;
+        if (willEnhance) {
+            // An import override means `sourceFile` is a stand-in (the MCP handler's
+            // /tmp/aqe-temp-* copy of inline source). Do not show the LLM that path:
+            // it could echo it into the test in a form the temp-path rewrite misses.
+            const result = await this.enhanceTestWithLLM(testCode, sourceContent, codeAnalysis, sourceFile, context, originalRequest?.importPathOverrides?.[sourceFile] === undefined);
             llmEnhanced = result.enhanced;
+            if (llmEnhanced) {
+                testCode = result.code;
+            }
+            else if (deterministicEligible) {
+                // The LLM produced nothing usable: fall back to the honest scaffold,
+                // never to template assertions with guessed expected values (#787).
+                deterministic = buildDeterministic();
+                testCode = deterministic.code;
+            }
         }
         const test = {
             id: uuidv4(),
@@ -476,7 +521,8 @@ Return a JSON array of test suggestions, each with: { "name": "test name", "desc
             testFile,
             testCode,
             type: testType,
-            assertions: this.countAssertions(testCode),
+            assertions: deterministic && !llmEnhanced ? deterministic.assertions : this.countAssertions(testCode),
+            ...(!llmEnhanced && deterministic ? { generationMode: deterministic.mode, generationLimits: deterministic.limits } : {}),
             // ADR-078: Include detected language and framework
             language: effectiveLanguage,
             framework: framework,
@@ -976,23 +1022,6 @@ Return a JSON array of test suggestions, each with: { "name": "test name", "desc
         }
         return Math.max(1, count);
     }
-    estimateCoverage(tests, target) {
-        const totalAssertions = tests.reduce((sum, t) => sum + t.assertions, 0);
-        const totalTests = tests.length;
-        const testBasedCoverage = totalTests * 4;
-        const assertionCoverage = totalAssertions * 1.5;
-        const typeMultiplier = tests.reduce((mult, t) => {
-            if (t.type === 'integration')
-                return mult + 0.1;
-            if (t.type === 'e2e')
-                return mult + 0.15;
-            return mult;
-        }, 1);
-        const rawEstimate = (testBasedCoverage + assertionCoverage) * typeMultiplier;
-        const diminishedEstimate = rawEstimate * (1 - rawEstimate / 200);
-        const estimatedCoverage = Math.min(target, Math.max(0, diminishedEstimate));
-        return Math.round(estimatedCoverage * 10) / 10;
-    }
     async storeGenerationMetadata(tests, patterns) {
         const metadata = {
             generatedAt: new Date().toISOString(),

package/dist/domains/visual-accessibility/services/axe-core-audit.d.ts

@@ -1,18 +1,3 @@
-/**
- * Agentic QE v3 - Axe-Core Accessibility Audit
- *
- * Lightweight implementation using vibium + axe-core for accessibility testing.
- * Vibium provides browser automation via WebDriver BiDi (~202KB),
- * axe-core provides accessibility rules (~3MB).
- *
- * Features:
- * - WCAG 2.0/2.1/2.2 compliance testing
- * - Section 508 compliance
- * - Best practices validation
- * - Custom rule configuration
- *
- * @module visual-accessibility/axe-core-audit
- */
 /**
  * WCAG conformance levels
  */

package/dist/domains/visual-accessibility/services/axe-core-audit.js

@@ -1,3 +1,4 @@
+import { loadVibium, isVibiumReady, VIBIUM_SETUP } from '../../../integrations/vibium/runtime.js';
 /**
  * Agentic QE v3 - Axe-Core Accessibility Audit
  *
@@ -83,8 +84,8 @@ export class AccessibilityAuditor {
         }
         // Check for vibium
         try {
-            await import('vibium');
-            this.toolsAvailable.vibium = true;
+            await loadVibium();
+            this.toolsAvailable.vibium = isVibiumReady();
         }
         catch {
             this.toolsAvailable.vibium = false;
@@ -138,11 +139,12 @@ export class AccessibilityAuditor {
      * Run actual axe-core audit using vibium
      */
     async runAxeCoreAudit(startTime) {
-        const { browser } = await import('vibium');
-        let vibe = null;
+        const { browser } = await loadVibium();
+        let instance = null;
         try {
             // Launch browser
-            vibe = await browser.launch();
+            instance = await browser.start({ headless: true });
+            const vibe = await instance.page();
             // Navigate to URL
             await vibe.go(this.config.url);
             // Wait for selector if configured
@@ -153,12 +155,12 @@ export class AccessibilityAuditor {
             }
             // Inject axe-core library
             const axeSource = loadAxeCoreSource();
-            await vibe.evaluate(axeSource);
+            await vibe.addScript(axeSource);
             // Build axe configuration
             const axeConfig = this.buildAxeConfig();
             // Run axe-core audit
             const axeScript = `
-        return axe.run(${this.config.context ? `'${this.config.context}'` : 'document'}, ${JSON.stringify(axeConfig)});
+        axe.run(${this.config.context ? JSON.stringify(this.config.context) : 'document'}, ${JSON.stringify(axeConfig)})
       `;
             const results = await vibe.evaluate(axeScript);
             // Convert results
@@ -188,8 +190,8 @@ export class AccessibilityAuditor {
             };
         }
         finally {
-            if (vibe) {
-                await vibe.quit();
+            if (instance) {
+                await instance.stop();
             }
         }
     }
@@ -218,7 +220,7 @@ export class AccessibilityAuditor {
     createFallbackResult(startTime) {
         const errors = [];
         if (!this.toolsAvailable.vibium) {
-            errors.push('vibium is not installed. Install with: npm install vibium');
+            errors.push(`Vibium runtime or browser payload unavailable; run ${VIBIUM_SETUP}`);
         }
         if (!this.toolsAvailable.axeCore) {
             errors.push('axe-core is not installed. Install with: npm install axe-core');

package/dist/init/agents-installer.d.ts

@@ -74,6 +74,10 @@ export declare class AgentsInstaller {
      * Install a single agent
      */
     private installAgent;
+    /**
+     * Describe an agent from its installed file (type, description, domain).
+     */
+    private describeAgent;
     /**
      * Get the type of an agent based on its name
      */

package/dist/init/agents-installer.js

@@ -11,6 +11,7 @@ import { toErrorMessage } from '../shared/error-utils.js';
 import { loadOverlays, applyOverlayToContent } from '../agents/overlay-loader.js';
 import { validateFleetMcpDeps } from '../validation/steps/agent-mcp-validator.js';
 import { findPackageRoot } from './find-package-root.js';
+import { GENERATED_ON_LINE, writeTextIfChangedIgnoring } from './idempotent-write.js';
 // ============================================================================
 // Helpers
 // ============================================================================
@@ -240,15 +241,21 @@ export class AgentsInstaller {
         result.totalCount = availableAgents.length;
         // Filter agents based on options
         const agentsToInstall = this.filterAgents(availableAgents);
+        // Every selected agent present on disk after this run — newly installed or
+        // already there — so the index describes the install, not just this run's
+        // delta (a repeat init used to rewrite it as "Total Agents: 0", #778).
+        const presentAgents = [];
         // Install each agent
         for (const agentName of agentsToInstall) {
             try {
                 const agentInfo = await this.installAgent(agentName, targetAgentsDir, targetSubagentsDir);
                 if (agentInfo) {
                     result.installed.push(agentInfo);
+                    presentAgents.push(agentInfo);
                 }
                 else {
                     result.skipped.push(agentName);
+                    presentAgents.push(this.describeAgent(agentName, targetAgentsDir, targetSubagentsDir));
                 }
             }
             catch (error) {
@@ -313,7 +320,7 @@ export class AgentsInstaller {
             }
         }
         // Create agents index file
-        await this.createAgentsIndex(targetAgentsDir, result.installed);
+        await this.createAgentsIndex(targetAgentsDir, presentAgents);
         return result;
     }
     /**
@@ -405,17 +412,22 @@ export class AgentsInstaller {
         else {
             throw new Error(`Source file not found: ${sourceFile}`);
         }
-        // Determine agent type
-        const agentType = this.getAgentType(agentName, isSubagent);
-        // Get description from agent file
-        const description = this.getAgentDescription(targetFile);
-        // Get domain from agent name
-        const domain = this.getAgentDomain(agentName);
+        return this.describeAgent(agentPath, targetDir, targetSubagentsDir);
+    }
+    /**
+     * Describe an agent from its installed file (type, description, domain).
+     */
+    describeAgent(agentPath, targetDir, targetSubagentsDir) {
+        const isSubagent = agentPath.startsWith('subagents/');
+        const agentName = isSubagent ? agentPath.split('/')[1] : agentPath;
+        const targetFile = isSubagent
+            ? join(targetSubagentsDir, `${agentName}.md`)
+            : join(targetDir, `${agentName}.md`);
         return {
             name: agentName,
-            type: agentType,
-            description,
-            domain,
+            type: this.getAgentType(agentName, isSubagent),
+            description: this.getAgentDescription(targetFile),
+            domain: this.getAgentDomain(agentName),
         };
     }
     /**
@@ -629,7 +641,8 @@ ${subagents.map(a => `- **${a.name}**${a.description ? `: ${a.description}` : ''
         if (!existsSync(docsDir)) {
             mkdirSync(docsDir, { recursive: true });
         }
-        writeFileSync(join(docsDir, 'v3-agents-index.md'), indexContent, 'utf-8');
+        // #778: ignore the generation-timestamp footer when deciding to rewrite.
+        writeTextIfChangedIgnoring(join(docsDir, 'v3-agents-index.md'), indexContent, GENERATED_ON_LINE);
     }
 }
 /**

package/dist/init/browser-engine-installer.d.ts

@@ -9,13 +9,13 @@
  * Design goals:
  *   - Graceful: never fail init if Vibium install fails; report and continue.
  *   - Idempotent: skip if Vibium is already on PATH.
- *   - Opt-out friendly: respect --minimal and --no-browser-engine flags.
+ *   - Opt-in only: called by init only with --browser-engine.
  *   - No new runtime deps: shells out to `npm install -g vibium` via child_process.
  */
 import { type SpawnSyncReturns } from 'node:child_process';
 /**
- * Default Vibium npm spec. Major-line pin via caret (`^26.3.18`) — npm
- * semver will accept any 26.x.y >= 26.3.18 but reject 27.0.0+. The intent
+ * Default Vibium npm spec. Major-line pin via caret (`^26.8.21`) — npm
+ * semver will accept any 26.x.y >= 26.8.21 but reject 27.0.0+. The intent
  * is to auto-receive security patches and additive minor features while
  * blocking breaking-change major bumps, which is where Vibium's CLI
  * contract (`go`, `--headless`, `viewport`, exit codes) can change.
@@ -27,7 +27,7 @@ import { type SpawnSyncReturns } from 'node:child_process';
  * Bump procedure: update this constant (e.g. to ^27.0.0 at a major), run
  * scripts/smoke-test.sh against the new version, then land the bump.
  */
-export declare const DEFAULT_VIBIUM_SPEC = "vibium@^26.3.18";
+export declare const DEFAULT_VIBIUM_SPEC = "vibium@^26.8.21";
 /**
  * Spawner injected into {@link installBrowserEngine} so tests can mock the
  * shell-out without monkey-patching the child_process module (ESM namespaces
@@ -66,7 +66,7 @@ export interface BrowserEngineInstallResult {
      */
     platformHint?: PlatformHint;
 }
-export type BrowserEngineDetectionStatus = 'ready' | 'cli-missing' | 'payload-missing';
+export type BrowserEngineDetectionStatus = 'ready' | 'cli-missing' | 'payload-missing' | 'unsupported-version';
 export interface BrowserEngineDetectionResult {
     status: BrowserEngineDetectionStatus;
     version?: string;

package/dist/init/browser-engine-installer.js

@@ -9,7 +9,7 @@
  * Design goals:
  *   - Graceful: never fail init if Vibium install fails; report and continue.
  *   - Idempotent: skip if Vibium is already on PATH.
- *   - Opt-out friendly: respect --minimal and --no-browser-engine flags.
+ *   - Opt-in only: called by init only with --browser-engine.
  *   - No new runtime deps: shells out to `npm install -g vibium` via child_process.
  */
 import { spawnSync as realSpawnSync } from 'node:child_process';
@@ -17,8 +17,8 @@ import * as os from 'node:os';
 import * as fs from 'node:fs';
 import { toErrorMessage } from '../shared/error-utils.js';
 /**
- * Default Vibium npm spec. Major-line pin via caret (`^26.3.18`) — npm
- * semver will accept any 26.x.y >= 26.3.18 but reject 27.0.0+. The intent
+ * Default Vibium npm spec. Major-line pin via caret (`^26.8.21`) — npm
+ * semver will accept any 26.x.y >= 26.8.21 but reject 27.0.0+. The intent
  * is to auto-receive security patches and additive minor features while
  * blocking breaking-change major bumps, which is where Vibium's CLI
  * contract (`go`, `--headless`, `viewport`, exit codes) can change.
@@ -30,7 +30,7 @@ import { toErrorMessage } from '../shared/error-utils.js';
  * Bump procedure: update this constant (e.g. to ^27.0.0 at a major), run
  * scripts/smoke-test.sh against the new version, then land the bump.
  */
-export const DEFAULT_VIBIUM_SPEC = 'vibium@^26.3.18';
+export const DEFAULT_VIBIUM_SPEC = 'vibium@^26.8.21';
 const defaultPlatformProbe = {
     platform: () => os.platform(),
     arch: () => os.arch(),
@@ -109,7 +109,7 @@ export function detectVibium(spawner = defaultSpawner, timeoutMs = 5_000) {
     const raw = stdout || stderr;
     if (!raw)
         return 'unknown';
-    // Extract first semver-looking token if present (e.g. "vibium version 26.3.18" → "26.3.18")
+    // Extract first semver-looking token if present (e.g. "vibium version 26.8.21" → "26.8.21")
     const match = raw.match(/v?(\d+\.\d+\.\d+(?:[-+][\w.]+)?)/);
     return match ? match[1] : raw.split(/\s+/)[0] || 'unknown';
 }
@@ -121,6 +121,15 @@ export function detectBrowserEngine(spawner = defaultSpawner, timeoutMs = 5_000)
     const version = detectVibium(spawner, timeoutMs);
     if (!version)
         return { status: 'cli-missing' };
+    // The modern JS adapter is supported only by stable 26.x releases >= 26.8.21.
+    const semver = /^(\d+)\.(\d+)\.(\d+)(?:\+[\w.]+)?$/.exec(version);
+    if (!semver || Number(semver[1]) !== 26 ||
+        Number(semver[2]) < 8 || (Number(semver[2]) === 8 && Number(semver[3]) < 21)) {
+        return {
+            status: 'unsupported-version', version,
+            message: `Vibium ${version} is unsupported; install ${DEFAULT_VIBIUM_SPEC} for the browser.start() API`,
+        };
+    }
     const payload = tryRun(spawner, 'vibium', ['is-installed'], timeoutMs);
     if (payload.status === 0)
         return { status: 'ready', version };
@@ -176,7 +185,20 @@ export function installBrowserEngine(options = {}) {
                 'unknown npm install failure',
         };
     }
-    const verified = detectBrowserEngine(spawner);
+    let verified = detectBrowserEngine(spawner);
+    if (verified.status === 'payload-missing') {
+        // Reinstalling an already-current npm package may not rerun postinstall.
+        // This installer is explicitly requested, so provision the payload directly.
+        const payloadInstall = tryRun(spawner, 'vibium', ['install'], timeoutMs);
+        if (payloadInstall.status !== 0) {
+            return {
+                status: 'install-failed', packageSpec, platformHint,
+                message: `Browser payload installation failed: ${payloadInstall.stderr?.trim() ||
+                    payloadInstall.stdout?.trim() || 'vibium install failed'}. Run \`vibium install\` and verify with \`vibium is-installed\`.`,
+            };
+        }
+        verified = detectBrowserEngine(spawner);
+    }
     if (verified.status !== 'ready') {
         const reason = verified.message ? `: ${verified.message}` : '';
         return {

package/dist/init/codex-installer.js

@@ -10,6 +10,7 @@ import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { toErrorMessage } from '../shared/error-utils.js';
 import { findPackageRoot } from './find-package-root.js';
+import { writeFileIfChanged } from './idempotent-write.js';
 import { selectCodexSkills } from './codex-skill-manifest.js';
 import { createPlatformConfigGenerator, } from './platform-config-generator.js';
 export const CODEX_COMPACT_GUIDANCE_MAX_BYTES = 512;
@@ -236,9 +237,10 @@ export class CodexInstaller {
             const userGroups = (existing.hooks?.[event] || []).filter((group) => !owned(group));
             mergedHooks[event] = [...userGroups, ...(generated.hooks?.[event] || [])];
         }
-        writeFileSync(targetConfig, JSON.stringify({ ...existing, description: generated.description, hooks: mergedHooks }, null, 2) + '\n');
+        // #778: a converged hooks.json is left untouched (no mtime churn).
+        const changed = writeFileIfChanged(targetConfig, JSON.stringify({ ...existing, description: generated.description, hooks: mergedHooks }, null, 2) + '\n');
         result.hooksConfigured = true;
-        return 'updated';
+        return changed ? 'updated' : 'preserved';
     }
     /** Install the curated repo-scoped AQE skills Codex discovers automatically. */
     installCodexSkills() {

package/dist/init/idempotent-write.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Idempotent file writers for `aqe init` (#778).
+ *
+ * A repeat `aqe init` on an unchanged project must be a byte-stable
+ * convergence step: files whose content would not change are left alone (no
+ * rewrite, so the mtime is preserved too), and volatile fields such as
+ * generation timestamps are carried over from the existing file unless
+ * something else in that file actually changed.
+ */
+/**
+ * Write `content` to `path` only when the bytes on disk differ.
+ * @returns true when the file was written.
+ */
+export declare function writeFileIfChanged(path: string, content: string | Buffer): boolean;
+/**
+ * Copy `src` to `dest` only when `dest` is missing or its bytes differ.
+ * Uses copyFileSync for the actual copy so file-mode semantics are unchanged.
+ * @returns true when the file was copied.
+ */
+export declare function copyFileIfChanged(src: string, dest: string): boolean;
+/**
+ * Write a text file whose content embeds a volatile line (e.g. a generation
+ * timestamp). When the existing file matches `content` on every line except
+ * the lines matching `volatileLine`, the file is left untouched.
+ * @returns true when the file was written.
+ */
+export declare function writeTextIfChangedIgnoring(path: string, content: string, volatileLine: RegExp): boolean;
+/** The `*Generated by AQE v3 init on <ISO>*` footer of generated index docs. */
+export declare const GENERATED_ON_LINE: RegExp;
+/** JSON serialization with object keys sorted, for order-insensitive comparison. */
+export declare function canonicalJson(value: unknown): string;
+/** Deep structural equality of two JSON values, ignoring object key order. */
+export declare function jsonEquivalent(a: unknown, b: unknown): boolean;
+/**
+ * Carry volatile fields (timestamps) over from `previous` into `next` when
+ * `next` is otherwise identical to `previous`.
+ *
+ * - Unchanged (apart from the volatile fields): `next` is mutated to hold the
+ *   previous values and `false` is returned — the caller should not write.
+ * - Changed, or no previous document: `next` keeps its fresh values and
+ *   `true` is returned — the caller should write.
+ */
+export declare function stabilizeVolatileFields(previous: unknown, next: Record<string, unknown>, volatilePaths: ReadonlyArray<readonly string[]>): boolean;
+/** Read and parse a JSON file, or return undefined when missing/unparseable. */
+export declare function readJsonIfPresent(path: string): unknown;
+/**
+ * Write a generated JSON document (2-space indent) unless it is equivalent to
+ * the one already on disk, preserving the existing values of `volatilePaths`
+ * (e.g. `[['createdAt']]`) when nothing else changed.
+ * @returns true when the file was written.
+ */
+export declare function writeJsonIfChanged(path: string, doc: Record<string, unknown>, volatilePaths?: ReadonlyArray<readonly string[]>): boolean;
+//# sourceMappingURL=idempotent-write.d.ts.map