@buenos_andres/compact-builder 0.5.3

package/dist/Compiler.js

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import chalk from 'chalk';
+import ora from 'ora';
+import { CompilerService } from "./services/CompilerService.js";
+import { EnvironmentValidator } from "./services/EnvironmentValidator.js";
+import { FileDiscovery } from "./services/FileDiscovery.js";
+import { UIService } from "./services/UIService.js";
+import { CompilationError, DirectoryNotFoundError, isPromisifiedChildProcessError, } from "./types/errors.js";
+import { DEFAULT_OUT_DIR, DEFAULT_SRC_DIR, } from "./types/options.js";
+// Re-export public types and services so consumers keep importing them
+// from './Compiler.js' regardless of the internal file layout.
+// biome-ignore lint/performance/noBarrelFile: package entrypoint
+export { CompilerService } from "./services/CompilerService.js";
+export { EnvironmentValidator } from "./services/EnvironmentValidator.js";
+export { FileDiscovery } from "./services/FileDiscovery.js";
+export { UIService } from "./services/UIService.js";
+/**
+ * Main compiler class that orchestrates the compilation process.
+ * Coordinates environment validation, file discovery, and compilation services
+ * to provide a complete .compact file compilation solution.
+ *
+ * Features:
+ * - Dependency injection for testability
+ * - Structured error propagation with custom error types
+ * - Progress reporting and user feedback
+ * - Support for compiler flags and toolchain versions
+ * - Environment variable integration
+ * - Configurable artifact output structure (flattened or hierarchical)
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with options object (flattened artifacts by default)
+ * const compiler = new CompactCompiler({
+ *   flags: '--skip-zk',
+ *   targetDir: 'security',
+ *   version: '0.26.0',
+ * });
+ * await compiler.compile();
+ *
+ * // Factory method usage
+ * const compiler = CompactCompiler.fromArgs(['--dir', 'security', '--skip-zk']);
+ * await compiler.compile();
+ *
+ * // With hierarchical artifacts structure
+ * const compiler = CompactCompiler.fromArgs(['--hierarchical', '--skip-zk']);
+ * await compiler.compile();
+ *
+ * // With environment variables
+ * process.env.SKIP_ZK = 'true';
+ * const compiler = CompactCompiler.fromArgs(['--dir', 'token']);
+ * await compiler.compile();
+ * ```
+ */
+export class CompactCompiler {
+    /** Environment validation service */
+    environmentValidator;
+    /** File discovery service */
+    fileDiscovery;
+    /** Compilation execution service */
+    compilerService;
+    /** Compiler options */
+    options;
+    /**
+     * Creates a new CompactCompiler instance with specified configuration.
+     *
+     * @param options - Compiler configuration options
+     * @param execFn  - Optional custom exec function for dependency injection
+     */
+    constructor(options = {}, execFn) {
+        this.options = {
+            flags: (options.flags ?? '').trim(),
+            targetDir: options.targetDir,
+            version: options.version,
+            hierarchical: options.hierarchical ?? false,
+            srcDir: options.srcDir ?? DEFAULT_SRC_DIR,
+            outDir: options.outDir ?? DEFAULT_OUT_DIR,
+            exclude: options.exclude ?? [],
+        };
+        this.environmentValidator = new EnvironmentValidator(execFn);
+        this.fileDiscovery = new FileDiscovery(this.options.srcDir, this.options.exclude);
+        this.compilerService = new CompilerService(execFn, {
+            hierarchical: this.options.hierarchical,
+            srcDir: this.options.srcDir,
+            outDir: this.options.outDir,
+        });
+    }
+    /**
+     * Parses command-line arguments into a CompilerOptions object.
+     *
+     * Supported argument patterns:
+     * - `--dir <directory>` - Target specific subdirectory within srcDir
+     * - `--src <directory>` - Source directory containing .compact files (default: 'src')
+     * - `--out <directory>` - Output directory for artifacts (default: 'artifacts')
+     * - `--hierarchical` - Preserve source directory structure in artifacts output
+     * - `--exclude <pattern>` - Skip `.compact` files matching the glob pattern (repeatable)
+     * - `+<version>` - Use specific toolchain version
+     * - Other arguments - Treated as compiler flags
+     * - `SKIP_ZK=true` environment variable - Adds --skip-zk flag
+     *
+     * @param args - Array of command-line arguments
+     * @param env  - Environment variables (defaults to process.env)
+     * @returns Parsed CompilerOptions object
+     * @throws {Error} If --dir, --src, --out, or --exclude is provided without a value
+     */
+    static parseArgs(args, env = process.env) {
+        const options = {
+            hierarchical: false,
+        };
+        const flags = [];
+        if (env.SKIP_ZK === 'true') {
+            flags.push('--skip-zk');
+        }
+        for (let i = 0; i < args.length; i++) {
+            if (args[i] === '--dir') {
+                const valueExists = i + 1 < args.length && !args[i + 1].startsWith('--');
+                if (valueExists) {
+                    options.targetDir = args[i + 1];
+                    i++;
+                }
+                else {
+                    throw new Error('--dir flag requires a directory name');
+                }
+            }
+            else if (args[i] === '--src') {
+                const valueExists = i + 1 < args.length && !args[i + 1].startsWith('--');
+                if (valueExists) {
+                    options.srcDir = args[i + 1];
+                    i++;
+                }
+                else {
+                    throw new Error('--src flag requires a directory path');
+                }
+            }
+            else if (args[i] === '--out') {
+                const valueExists = i + 1 < args.length && !args[i + 1].startsWith('--');
+                if (valueExists) {
+                    options.outDir = args[i + 1];
+                    i++;
+                }
+                else {
+                    throw new Error('--out flag requires a directory path');
+                }
+            }
+            else if (args[i] === '--hierarchical') {
+                options.hierarchical = true;
+            }
+            else if (args[i] === '--exclude') {
+                const valueExists = i + 1 < args.length && !args[i + 1].startsWith('--');
+                if (valueExists) {
+                    options.exclude ??= [];
+                    options.exclude.push(args[i + 1]);
+                    i++;
+                }
+                else {
+                    throw new Error('--exclude flag requires a pattern');
+                }
+            }
+            else if (args[i].startsWith('+')) {
+                options.version = args[i].slice(1);
+            }
+            else {
+                // Forward flags in original order, no dedup — repeatable flags
+                // (e.g. `--define x=1 --define y=2`) must be preserved as given.
+                flags.push(args[i]);
+            }
+        }
+        options.flags = flags.join(' ');
+        return options;
+    }
+    /**
+     * Factory method to create a CompactCompiler from command-line arguments.
+     * See {@link CompactCompiler.parseArgs} for the supported argument shapes.
+     *
+     * @param args - Array of command-line arguments
+     * @param env  - Environment variables (defaults to process.env)
+     * @returns New CompactCompiler instance configured from arguments
+     * @throws {Error} If --dir, --src, --out, or --exclude is provided without a value
+     */
+    static fromArgs(args, env = process.env) {
+        const options = CompactCompiler.parseArgs(args, env);
+        return new CompactCompiler(options);
+    }
+    /**
+     * Validates the compilation environment and displays version information.
+     *
+     * @throws {CompactCliNotFoundError} If Compact CLI is not available in PATH
+     * @throws {Error} If version retrieval or other validation steps fail
+     */
+    async validateEnvironment() {
+        const { devToolsVersion, toolchainVersion } = await this.environmentValidator.validate(this.options.version);
+        UIService.displayEnvInfo(devToolsVersion, toolchainVersion, this.options.targetDir, this.options.version);
+    }
+    /**
+     * Main compilation method that orchestrates the entire compilation process.
+     *
+     * @throws {CompactCliNotFoundError} If Compact CLI is not available
+     * @throws {DirectoryNotFoundError} If target directory doesn't exist
+     * @throws {CompilationError} If any file compilation fails
+     */
+    async compile() {
+        await this.validateEnvironment();
+        const searchDir = this.options.targetDir
+            ? join(this.options.srcDir, this.options.targetDir)
+            : this.options.srcDir;
+        // Validate target directory exists
+        if (this.options.targetDir && !existsSync(searchDir)) {
+            throw new DirectoryNotFoundError(`Target directory ${searchDir} does not exist`, searchDir);
+        }
+        const compactFiles = await this.fileDiscovery.getCompactFiles(searchDir);
+        if (compactFiles.length === 0) {
+            UIService.showNoFiles(this.options.targetDir);
+            return;
+        }
+        UIService.showCompilationStart(compactFiles.length, this.options.targetDir);
+        for (const [index, file] of compactFiles.entries()) {
+            await this.compileFile(file, index, compactFiles.length);
+        }
+    }
+    /**
+     * Compiles a single file with progress reporting and error handling.
+     *
+     * @param file  - Relative path to the .compact file
+     * @param index - Current file index (0-based) for progress tracking
+     * @param total - Total number of files being compiled
+     * @throws {CompilationError} If compilation fails
+     */
+    async compileFile(file, index, total) {
+        const step = `[${index + 1}/${total}]`;
+        const spinner = ora(chalk.blue(`[COMPILE] ${step} Compiling ${file}`)).start();
+        try {
+            const result = await this.compilerService.compileFile(file, this.options.flags, this.options.version);
+            spinner.succeed(chalk.green(`[COMPILE] ${step} Compiled ${file}`));
+            // Filter out compactc version output from compact compile
+            const filteredOutput = result.stdout.split('\n').slice(1).join('\n');
+            if (filteredOutput) {
+                UIService.printOutput(filteredOutput, chalk.cyan);
+            }
+            UIService.printOutput(result.stderr, chalk.yellow);
+        }
+        catch (error) {
+            spinner.fail(chalk.red(`[COMPILE] ${step} Failed ${file}`));
+            // CompilationError wraps the underlying child-process error in `.cause`.
+            // The previous guard `isPromisifiedChildProcessError(error)` on a
+            // CompilationError instance was unreachable — unwrap via `.cause` to
+            // surface compactc's stdout/stderr to the user.
+            const execError = error instanceof CompilationError ? error.cause : error;
+            if (isPromisifiedChildProcessError(execError)) {
+                // Filter out compactc version output from compact compile
+                const filteredOutput = execError.stdout.split('\n').slice(1).join('\n');
+                if (filteredOutput) {
+                    UIService.printOutput(filteredOutput, chalk.cyan);
+                }
+                UIService.printOutput(execError.stderr, chalk.red);
+            }
+            throw error;
+        }
+    }
+    /**
+     * For testing - returns the resolved options object
+     */
+    get testOptions() {
+        return this.options;
+    }
+}
+//# sourceMappingURL=Compiler.js.map

package/dist/Compiler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Compiler.js","sourceRoot":"","sources":["../src/Compiler.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { BuilderOnlyOptions, BuilderOptions } from './Builder.js';
+export { CompactBuilder } from './Builder.js';
+export type { CompilerOptions, CompilerServiceOptions, ExecFunction, } from './Compiler.js';
+export { CompactCompiler, CompilerService, EnvironmentValidator, FileDiscovery, UIService, } from './Compiler.js';
+export type { PromisifiedChildProcessError } from './types/errors.js';
+export { CompactCliNotFoundError, CompilationError, DirectoryNotFoundError, isPromisifiedChildProcessError, } from './types/errors.js';
+export type { BuildStep } from './types/options.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+// biome-ignore lint/performance/noBarrelFile: package entrypoint
+export { CompactBuilder } from './Builder.js';
+export { CompactCompiler, CompilerService, EnvironmentValidator, FileDiscovery, UIService, } from './Compiler.js';
+export { CompactCliNotFoundError, CompilationError, DirectoryNotFoundError, isPromisifiedChildProcessError, } from './types/errors.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,iEAAiE;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAM9C,OAAO,EACL,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,aAAa,EACb,SAAS,GACV,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,uBAAuB,EACvB,gBAAgB,EAChB,sBAAsB,EACtB,8BAA8B,GAC/B,MAAM,mBAAmB,CAAC"}

package/dist/services/CompilerService.d.ts

@@ -0,0 +1,47 @@
+import { type CompilerServiceOptions, type ExecFunction } from '../types/options.ts';
+/**
+ * Service responsible for compiling individual .compact files.
+ * Builds argv arrays and invokes the Compact CLI via `child_process.execFile`
+ * (no shell), so user-supplied values cannot inject extra commands.
+ *
+ * @example
+ * ```typescript
+ * const compiler = new CompilerService();
+ * const result = await compiler.compileFile(
+ *   'contracts/Token.compact',
+ *   '--skip-zk --verbose',
+ *   '0.26.0'
+ * );
+ * ```
+ */
+export declare class CompilerService {
+    private execFn;
+    private options;
+    /**
+     * Creates a new CompilerService instance.
+     *
+     * @param execFn  - Function to invoke the Compact CLI binary (defaults to
+     *                  a promisified `child_process.execFile` — argv array, no shell).
+     * @param options - Compiler service options
+     */
+    constructor(execFn?: ExecFunction, options?: CompilerServiceOptions);
+    /**
+     * Compiles a single .compact file using the Compact CLI.
+     * Builds the argv array (no shell interpolation) and invokes the binary.
+     *
+     * By default, uses flattened output structure where all artifacts go to `<outDir>/<ContractName>/`.
+     * When `hierarchical` is true, preserves source directory structure: `<outDir>/<subdir>/<ContractName>/`.
+     *
+     * @param file    - Relative path to the .compact file from srcDir
+     * @param flags   - Space-separated compiler flags (e.g., '--skip-zk --verbose').
+     *                  Tokenized via `shell-quote` so quoted whitespace is preserved
+     *                  and shell operators (`;`, `&&`, …) cannot inject commands.
+     * @param version - Optional specific toolchain version to use
+     * @returns Promise resolving to compilation output (stdout/stderr)
+     * @throws {CompilationError} If compilation fails for any reason
+     */
+    compileFile(file: string, flags: string, version?: string): Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+}

package/dist/services/CompilerService.js

@@ -0,0 +1,100 @@
+import { execFile as execFileCallback } from 'node:child_process';
+import { basename, dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+import { parse as parseShellArgs } from 'shell-quote';
+import { CompilationError } from "../types/errors.js";
+import { DEFAULT_OUT_DIR, DEFAULT_SRC_DIR, } from "../types/options.js";
+const defaultExecFn = (file, args) => promisify(execFileCallback)(file, [...args]);
+/**
+ * Tokenizes a user-supplied `flags` string into discrete argv entries using
+ * `shell-quote` (the same rules a shell would apply for splitting). Any
+ * non-string tokens (e.g. operators like `;`, `&&`) are filtered out so they
+ * cannot leak into argv as data — defense in depth against command injection
+ * via the `flags` option.
+ */
+function tokenizeFlags(flags) {
+    if (!flags) {
+        return [];
+    }
+    return parseShellArgs(flags).filter((token) => typeof token === 'string');
+}
+/**
+ * Service responsible for compiling individual .compact files.
+ * Builds argv arrays and invokes the Compact CLI via `child_process.execFile`
+ * (no shell), so user-supplied values cannot inject extra commands.
+ *
+ * @example
+ * ```typescript
+ * const compiler = new CompilerService();
+ * const result = await compiler.compileFile(
+ *   'contracts/Token.compact',
+ *   '--skip-zk --verbose',
+ *   '0.26.0'
+ * );
+ * ```
+ */
+export class CompilerService {
+    execFn;
+    options;
+    /**
+     * Creates a new CompilerService instance.
+     *
+     * @param execFn  - Function to invoke the Compact CLI binary (defaults to
+     *                  a promisified `child_process.execFile` — argv array, no shell).
+     * @param options - Compiler service options
+     */
+    constructor(execFn = defaultExecFn, options = {}) {
+        this.execFn = execFn;
+        this.options = {
+            hierarchical: options.hierarchical ?? false,
+            srcDir: options.srcDir ?? DEFAULT_SRC_DIR,
+            outDir: options.outDir ?? DEFAULT_OUT_DIR,
+        };
+    }
+    /**
+     * Compiles a single .compact file using the Compact CLI.
+     * Builds the argv array (no shell interpolation) and invokes the binary.
+     *
+     * By default, uses flattened output structure where all artifacts go to `<outDir>/<ContractName>/`.
+     * When `hierarchical` is true, preserves source directory structure: `<outDir>/<subdir>/<ContractName>/`.
+     *
+     * @param file    - Relative path to the .compact file from srcDir
+     * @param flags   - Space-separated compiler flags (e.g., '--skip-zk --verbose').
+     *                  Tokenized via `shell-quote` so quoted whitespace is preserved
+     *                  and shell operators (`;`, `&&`, …) cannot inject commands.
+     * @param version - Optional specific toolchain version to use
+     * @returns Promise resolving to compilation output (stdout/stderr)
+     * @throws {CompilationError} If compilation fails for any reason
+     */
+    async compileFile(file, flags, version) {
+        const inputPath = join(this.options.srcDir, file);
+        const fileDir = dirname(file);
+        const fileName = basename(file, '.compact');
+        // Flattened (default): <outDir>/<ContractName>/
+        // Hierarchical: <outDir>/<subdir>/<ContractName>/
+        const outputDir = this.options.hierarchical && fileDir !== '.'
+            ? join(this.options.outDir, fileDir, fileName)
+            : join(this.options.outDir, fileName);
+        const args = [
+            'compile',
+            ...(version ? [`+${version}`] : []),
+            ...tokenizeFlags(flags),
+            inputPath,
+            outputDir,
+        ];
+        try {
+            return await this.execFn('compact', args);
+        }
+        catch (error) {
+            let message;
+            if (error instanceof Error) {
+                message = error.message;
+            }
+            else {
+                message = String(error); // fallback for strings, objects, numbers, etc.
+            }
+            throw new CompilationError(`Failed to compile ${file}: ${message}`, file, error);
+        }
+    }
+}
+//# sourceMappingURL=CompilerService.js.map

package/dist/services/CompilerService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CompilerService.js","sourceRoot":"","sources":["../../src/services/CompilerService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,KAAK,IAAI,cAAc,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAEL,eAAe,EACf,eAAe,GAEhB,MAAM,qBAAqB,CAAC;AAK7B,MAAM,aAAa,GAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CACjD,SAAS,CAAC,gBAAgB,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;AAE/C;;;;;;GAMG;AACH,SAAS,aAAa,CAAC,KAAa;IAClC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,cAAc,CAAC,KAAK,CAAC,CAAC,MAAM,CACjC,CAAC,KAAK,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CACtD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,eAAe;IAClB,MAAM,CAAe;IACrB,OAAO,CAAiC;IAEhD;;;;;;OAMG;IACH,YACE,SAAuB,aAAa,EACpC,UAAkC,EAAE;QAEpC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG;YACb,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,KAAK;YAC3C,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,eAAe;YACzC,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,eAAe;SAC1C,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,WAAW,CACf,IAAY,EACZ,KAAa,EACb,OAAgB;QAEhB,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAClD,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC9B,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QAE5C,gDAAgD;QAChD,kDAAkD;QAClD,MAAM,SAAS,GACb,IAAI,CAAC,OAAO,CAAC,YAAY,IAAI,OAAO,KAAK,GAAG;YAC1C,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC;YAC9C,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QAE1C,MAAM,IAAI,GAAa;YACrB,SAAS;YACT,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACnC,GAAG,aAAa,CAAC,KAAK,CAAC;YACvB,SAAS;YACT,SAAS;SACV,CAAC;QAEF,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAC5C,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAI,OAAe,CAAC;YAEpB,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;gBAC3B,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;YAC1B,CAAC;iBAAM,CAAC;gBACN,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,+CAA+C;YAC1E,CAAC;YAED,MAAM,IAAI,gBAAgB,CACxB,qBAAqB,IAAI,KAAK,OAAO,EAAE,EACvC,IAAI,EACJ,KAAK,CACN,CAAC;QACJ,CAAC;IACH,CAAC;CACF"}

package/dist/services/EnvironmentValidator.d.ts

@@ -0,0 +1,56 @@
+import type { ExecFunction } from '../types/options.ts';
+/**
+ * Service responsible for validating the Compact CLI environment.
+ * Checks CLI availability, retrieves version information, and ensures
+ * the toolchain is properly configured before compilation.
+ *
+ * @example
+ * ```typescript
+ * const validator = new EnvironmentValidator();
+ * await validator.validate('0.26.0');
+ * const version = await validator.getDevToolsVersion();
+ * ```
+ */
+export declare class EnvironmentValidator {
+    private execFn;
+    /**
+     * Creates a new EnvironmentValidator instance.
+     *
+     * @param execFn - Function to execute the Compact CLI binary (defaults to
+     *                 a promisified `child_process.execFile` — argv array, no shell).
+     */
+    constructor(execFn?: ExecFunction);
+    /**
+     * Checks if the Compact CLI is available in the system PATH.
+     *
+     * @returns Promise resolving to true if CLI is available, false otherwise
+     */
+    checkCompactAvailable(): Promise<boolean>;
+    /**
+     * Retrieves the version of the Compact developer tools.
+     *
+     * @returns Promise resolving to the version string
+     * @throws {Error} If the CLI is not available or command fails
+     */
+    getDevToolsVersion(): Promise<string>;
+    /**
+     * Retrieves the version of the Compact toolchain/compiler.
+     *
+     * @param version - Optional specific toolchain version to query
+     * @returns Promise resolving to the toolchain version string
+     * @throws {Error} If the CLI is not available or command fails
+     */
+    getToolchainVersion(version?: string): Promise<string>;
+    /**
+     * Validates the entire Compact environment and ensures it's ready for compilation.
+     * Checks CLI availability and retrieves version information.
+     *
+     * @param version - Optional specific toolchain version to validate
+     * @throws {CompactCliNotFoundError} If the Compact CLI is not available
+     * @throws {Error} If version commands fail
+     */
+    validate(version?: string): Promise<{
+        devToolsVersion: string;
+        toolchainVersion: string;
+    }>;
+}

package/dist/services/EnvironmentValidator.js

@@ -0,0 +1,82 @@
+import { execFile as execFileCallback } from 'node:child_process';
+import { promisify } from 'node:util';
+import { CompactCliNotFoundError } from "../types/errors.js";
+const defaultExecFn = (file, args) => promisify(execFileCallback)(file, [...args]);
+/**
+ * Service responsible for validating the Compact CLI environment.
+ * Checks CLI availability, retrieves version information, and ensures
+ * the toolchain is properly configured before compilation.
+ *
+ * @example
+ * ```typescript
+ * const validator = new EnvironmentValidator();
+ * await validator.validate('0.26.0');
+ * const version = await validator.getDevToolsVersion();
+ * ```
+ */
+export class EnvironmentValidator {
+    execFn;
+    /**
+     * Creates a new EnvironmentValidator instance.
+     *
+     * @param execFn - Function to execute the Compact CLI binary (defaults to
+     *                 a promisified `child_process.execFile` — argv array, no shell).
+     */
+    constructor(execFn = defaultExecFn) {
+        this.execFn = execFn;
+    }
+    /**
+     * Checks if the Compact CLI is available in the system PATH.
+     *
+     * @returns Promise resolving to true if CLI is available, false otherwise
+     */
+    async checkCompactAvailable() {
+        try {
+            await this.execFn('compact', ['--version']);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Retrieves the version of the Compact developer tools.
+     *
+     * @returns Promise resolving to the version string
+     * @throws {Error} If the CLI is not available or command fails
+     */
+    async getDevToolsVersion() {
+        const { stdout } = await this.execFn('compact', ['--version']);
+        return stdout.trim();
+    }
+    /**
+     * Retrieves the version of the Compact toolchain/compiler.
+     *
+     * @param version - Optional specific toolchain version to query
+     * @returns Promise resolving to the toolchain version string
+     * @throws {Error} If the CLI is not available or command fails
+     */
+    async getToolchainVersion(version) {
+        const args = ['compile', ...(version ? [`+${version}`] : []), '--version'];
+        const { stdout } = await this.execFn('compact', args);
+        return stdout.trim();
+    }
+    /**
+     * Validates the entire Compact environment and ensures it's ready for compilation.
+     * Checks CLI availability and retrieves version information.
+     *
+     * @param version - Optional specific toolchain version to validate
+     * @throws {CompactCliNotFoundError} If the Compact CLI is not available
+     * @throws {Error} If version commands fail
+     */
+    async validate(version) {
+        const isAvailable = await this.checkCompactAvailable();
+        if (!isAvailable) {
+            throw new CompactCliNotFoundError("'compact' CLI not found in PATH. Please install the Compact developer tools.");
+        }
+        const devToolsVersion = await this.getDevToolsVersion();
+        const toolchainVersion = await this.getToolchainVersion(version);
+        return { devToolsVersion, toolchainVersion };
+    }
+}
+//# sourceMappingURL=EnvironmentValidator.js.map

package/dist/services/EnvironmentValidator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EnvironmentValidator.js","sourceRoot":"","sources":["../../src/services/EnvironmentValidator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAG7D,MAAM,aAAa,GAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CACjD,SAAS,CAAC,gBAAgB,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;AAE/C;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,oBAAoB;IACvB,MAAM,CAAe;IAE7B;;;;;OAKG;IACH,YAAY,SAAuB,aAAa;QAC9C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,qBAAqB;QACzB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC;YAC5C,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,kBAAkB;QACtB,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC;QAC/D,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;IACvB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,mBAAmB,CAAC,OAAgB;QACxC,MAAM,IAAI,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,WAAW,CAAC,CAAC;QAC3E,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QACtD,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;IACvB,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,QAAQ,CACZ,OAAgB;QAEhB,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,qBAAqB,EAAE,CAAC;QACvD,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,MAAM,IAAI,uBAAuB,CAC/B,8EAA8E,CAC/E,CAAC;QACJ,CAAC;QAED,MAAM,eAAe,GAAG,MAAM,IAAI,CAAC,kBAAkB,EAAE,CAAC;QACxD,MAAM,gBAAgB,GAAG,MAAM,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC;QAEjE,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,CAAC;IAC/C,CAAC;CACF"}

package/dist/services/FileDiscovery.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Service responsible for discovering .compact files in the source directory.
+ * Recursively scans directories and filters for .compact file extensions,
+ * applying user-supplied exclude patterns.
+ *
+ * @example
+ * ```typescript
+ * const discovery = new FileDiscovery('src', ['Mock*']);
+ * const files = await discovery.getCompactFiles('src/security');
+ * ```
+ */
+export declare class FileDiscovery {
+    private srcDir;
+    private excludes;
+    /**
+     * Creates a new FileDiscovery instance.
+     *
+     * @param srcDir   - Base source directory for relative path calculation (default: 'src')
+     * @param excludes - Glob-style patterns of `.compact` files to skip.
+     *                   Patterns containing `/` match against the full path
+     *                   (as `find <srcDir>` would emit it); others match against
+     *                   the filename only. Default: `[]`.
+     */
+    constructor(srcDir?: string, excludes?: readonly string[]);
+    /**
+     * Recursively discovers all .compact files in a directory.
+     * Returns relative paths from the srcDir for consistent processing.
+     *
+     * @param dir - Directory path to search (relative or absolute)
+     * @returns Promise resolving to array of relative file paths
+     */
+    getCompactFiles(dir: string): Promise<string[]>;
+}