@elliots/typical-compiler 0.2.3 → 0.2.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Elliot Shepherd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { ProjectHandle, TransformResult } from './types.js';
+import type { ProjectHandle, TransformResult, AnalyseResult } from "./types.js";
 export interface TypicalCompilerOptions {
     /** Path to the typical binary. If not provided, uses the bundled binary. */
     binaryPath?: string;
@@ -16,8 +16,20 @@ export declare class TypicalCompiler {
     start(): Promise<void>;
     close(): Promise<void>;
     loadProject(configFileName: string): Promise<ProjectHandle>;
-    transformFile(project: ProjectHandle | string, fileName: string, ignoreTypes?: string[], maxGeneratedFunctions?: number, reusableValidators?: 'auto' | 'never' | 'always'): Promise<TransformResult>;
+    transformFile(project: ProjectHandle | string, fileName: string, ignoreTypes?: string[], maxGeneratedFunctions?: number): Promise<TransformResult>;
     release(handle: ProjectHandle | string): Promise<void>;
+    /**
+     * Analyse a file for validation points without transforming it.
+     * Returns information about which parameters, returns, and casts will be validated.
+     * Used by the VSCode extension to show validation indicators.
+     *
+     * @param project - Project handle or ID
+     * @param fileName - Path to the file to analyse
+     * @param content - Optional file content for live updates (uses disk version if not provided)
+     * @param ignoreTypes - Optional glob patterns for types to skip
+     * @returns Analysis result with validation items
+     */
+    analyseFile(project: ProjectHandle | string, fileName: string, content?: string, ignoreTypes?: string[]): Promise<AnalyseResult>;
     /**
      * Transform a standalone TypeScript source string.
      * Creates a temporary project to enable type checking.
@@ -30,7 +42,6 @@ export declare class TypicalCompiler {
     transformSource(fileName: string, source: string, options?: {
         ignoreTypes?: string[];
         maxGeneratedFunctions?: number;
-        reusableValidators?: 'auto' | 'never' | 'always';
     }): Promise<TransformResult>;
     private request;
     private handleData;

package/dist/client.js

@@ -1,28 +1,25 @@
-import { spawn } from 'node:child_process';
-import { join, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { createRequire } from 'node:module';
-import { encodeRequest, decodeResponse } from './protocol.js';
+import { spawn } from "node:child_process";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+import { encodeRequest, decodeResponse } from "./protocol.js";
+import { existsSync } from "node:fs";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
-const debug = process.env.DEBUG === '1';
+const debug = process.env.DEBUG === "1";
 function debugLog(...args) {
     if (debug) {
         console.error(...args);
     }
 }
 function getBinaryPath() {
-    // try local binary first (for development)
-    const localBinPath = join(__dirname, '..', 'bin', 'typical');
-    try {
-        require('fs').accessSync(localBinPath);
-        debugLog(`[CLIENT] Using local binary at ${localBinPath}`);
-        return localBinPath;
+    // use bin/typical in development
+    const devPath = join(__dirname, "../bin/typical");
+    if (existsSync(devPath)) {
+        debugLog(`[CLIENT] Using development binary at ${devPath}`);
+        return devPath;
     }
-    catch {
-        // continue to platform-specific package
-    }
-    // Then use platform-specific package
+    // Find platform-specific package
     const platform = process.platform; // darwin, linux, win32
     const arch = process.arch; // arm64, x64
     const pkgName = `@elliots/typical-compiler-${platform}-${arch}`;
@@ -43,20 +40,20 @@ export class TypicalCompiler {
     }
     async start() {
         if (this.process) {
-            throw new Error('Compiler already started');
+            throw new Error("Compiler already started");
         }
-        this.process = spawn(this.binaryPath, ['--cwd', this.cwd], {
-            stdio: ['pipe', 'pipe', 'inherit'],
+        this.process = spawn(this.binaryPath, ["--cwd", this.cwd], {
+            stdio: ["pipe", "pipe", "inherit"],
         });
         // Don't let the child process keep the Node process alive
         this.process.unref();
-        this.process.stdout.on('data', (data) => {
+        this.process.stdout.on("data", (data) => {
             this.handleData(data);
         });
-        this.process.on('error', err => {
-            console.error('Compiler process error:', err);
+        this.process.on("error", (err) => {
+            console.error("Compiler process error:", err);
         });
-        this.process.on('exit', code => {
+        this.process.on("exit", (code) => {
             this.process = null;
             // Reject any pending requests
             for (const [, { reject }] of this.pendingRequests) {
@@ -65,8 +62,8 @@ export class TypicalCompiler {
             this.pendingRequests.clear();
         });
         // Test the connection with echo
-        const result = await this.request('echo', 'ping');
-        if (result !== 'ping') {
+        const result = await this.request("echo", "ping");
+        if (result !== "ping") {
             throw new Error(`Echo test failed: expected "ping", got "${result}"`);
         }
     }
@@ -81,21 +78,40 @@ export class TypicalCompiler {
         }
     }
     async loadProject(configFileName) {
-        return this.request('loadProject', { configFileName });
+        return this.request("loadProject", { configFileName });
     }
-    async transformFile(project, fileName, ignoreTypes, maxGeneratedFunctions, reusableValidators) {
-        const projectId = typeof project === 'string' ? project : project.id;
-        return this.request('transformFile', {
+    async transformFile(project, fileName, ignoreTypes, maxGeneratedFunctions) {
+        const projectId = typeof project === "string" ? project : project.id;
+        return this.request("transformFile", {
             project: projectId,
             fileName,
             ignoreTypes,
             maxGeneratedFunctions,
-            reusableValidators,
         });
     }
     async release(handle) {
-        const id = typeof handle === 'string' ? handle : handle.id;
-        await this.request('release', id);
+        const id = typeof handle === "string" ? handle : handle.id;
+        await this.request("release", id);
+    }
+    /**
+     * Analyse a file for validation points without transforming it.
+     * Returns information about which parameters, returns, and casts will be validated.
+     * Used by the VSCode extension to show validation indicators.
+     *
+     * @param project - Project handle or ID
+     * @param fileName - Path to the file to analyse
+     * @param content - Optional file content for live updates (uses disk version if not provided)
+     * @param ignoreTypes - Optional glob patterns for types to skip
+     * @returns Analysis result with validation items
+     */
+    async analyseFile(project, fileName, content, ignoreTypes) {
+        const projectId = typeof project === "string" ? project : project.id;
+        return this.request("analyseFile", {
+            project: projectId,
+            fileName,
+            content,
+            ignoreTypes,
+        });
     }
     /**
      * Transform a standalone TypeScript source string.
@@ -107,17 +123,16 @@ export class TypicalCompiler {
      * @returns Transformed code with validation
      */
     async transformSource(fileName, source, options) {
-        return this.request('transformSource', {
+        return this.request("transformSource", {
             fileName,
             source,
             ignoreTypes: options?.ignoreTypes,
             maxGeneratedFunctions: options?.maxGeneratedFunctions,
-            reusableValidators: options?.reusableValidators,
         });
     }
     async request(method, payload) {
         if (!this.process) {
-            throw new Error('Compiler not started');
+            throw new Error("Compiler not started");
         }
         // Use unique request ID to correlate request/response
         const requestId = `${method}:${this.nextRequestId++}`;
@@ -143,17 +158,18 @@ export class TypicalCompiler {
                 // Find the pending request
                 const pending = this.pendingRequests.get(method);
                 if (!pending) {
-                    const pendingKeys = [...this.pendingRequests.keys()].join(', ') || '(none)';
-                    throw new Error(`No pending request for method: ${method}. Pending requests: ${pendingKeys}. ` + `This indicates a protocol bug - received response for a request that wasn't made or was already resolved.`);
+                    const pendingKeys = [...this.pendingRequests.keys()].join(", ") || "(none)";
+                    throw new Error(`No pending request for method: ${method}. Pending requests: ${pendingKeys}. ` +
+                        `This indicates a protocol bug - received response for a request that wasn't made or was already resolved.`);
                 }
                 this.pendingRequests.delete(method);
                 if (messageType === 4 /* MessageType.Response */) {
                     // Parse JSON payload
-                    const result = payload.length > 0 ? JSON.parse(payload.toString('utf8')) : null;
+                    const result = payload.length > 0 ? JSON.parse(payload.toString("utf8")) : null;
                     pending.resolve(result);
                 }
                 else if (messageType === 5 /* MessageType.Error */) {
-                    pending.reject(new Error(payload.toString('utf8')));
+                    pending.reject(new Error(payload.toString("utf8")));
                 }
                 else {
                     pending.reject(new Error(`Unexpected message type: ${messageType}`));

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { TypicalCompiler, type TypicalCompilerOptions } from './client.js';
-export type { ProjectHandle, TransformResult, RawSourceMap } from './types.js';
+export { TypicalCompiler, type TypicalCompilerOptions } from "./client.js";
+export type { ProjectHandle, TransformResult, RawSourceMap } from "./types.js";

package/dist/index.js

@@ -1 +1 @@
-export { TypicalCompiler } from './client.js';
+export { TypicalCompiler } from "./client.js";

package/dist/protocol.js

@@ -8,9 +8,9 @@ const MessagePackTypeBin16 = 0xc5;
 const MessagePackTypeBin32 = 0xc6;
 const MessagePackTypeU8 = 0xcc;
 export function encodeRequest(method, payload) {
-    const methodBuf = Buffer.from(method, 'utf8');
+    const methodBuf = Buffer.from(method, "utf8");
     const payloadStr = JSON.stringify(payload);
-    const payloadBuf = Buffer.from(payloadStr, 'utf8');
+    const payloadBuf = Buffer.from(payloadStr, "utf8");
     // Calculate total size
     // 1 byte for array marker (0x93)
     // 2 bytes for message type (0xCC + type)
@@ -36,7 +36,7 @@ export function decodeResponse(data) {
     let offset = 0;
     // Check array marker
     if (data[offset++] !== MessagePackTypeFixedArray3) {
-        throw new Error(`Expected 0x93, got 0x${data[0].toString(16)}: first 200 of data: ${data.subarray(0, 200).toString('utf8')}`);
+        throw new Error(`Expected 0x93, got 0x${data[0].toString(16)}: first 200 of data: ${data.subarray(0, 200).toString("utf8")}`);
     }
     // Read message type
     if (data[offset++] !== MessagePackTypeU8) {
@@ -46,7 +46,7 @@ export function decodeResponse(data) {
     // Read method
     const { value: methodBuf, newOffset: offset2 } = readBin(data, offset);
     offset = offset2;
-    const method = methodBuf.toString('utf8');
+    const method = methodBuf.toString("utf8");
     // Read payload
     const { value: payload, newOffset: offset3 } = readBin(data, offset);
     return { messageType, method, payload, bytesConsumed: offset3 };
@@ -79,25 +79,25 @@ function writeBin(buf, offset, data) {
 }
 function readBin(buf, offset) {
     if (offset >= buf.length) {
-        throw new Error('Not enough data: need type byte');
+        throw new Error("Not enough data: need type byte");
     }
     const type = buf[offset++];
     let length;
     switch (type) {
         case MessagePackTypeBin8:
             if (offset >= buf.length)
-                throw new Error('Not enough data: need length byte');
+                throw new Error("Not enough data: need length byte");
             length = buf[offset++];
             break;
         case MessagePackTypeBin16:
             if (offset + 2 > buf.length)
-                throw new Error('Not enough data: need 2 length bytes');
+                throw new Error("Not enough data: need 2 length bytes");
             length = buf.readUInt16BE(offset);
             offset += 2;
             break;
         case MessagePackTypeBin32:
             if (offset + 4 > buf.length)
-                throw new Error('Not enough data: need 4 length bytes');
+                throw new Error("Not enough data: need 4 length bytes");
             length = buf.readUInt32BE(offset);
             offset += 4;
             break;

package/dist/types.d.ts

@@ -16,3 +16,27 @@ export interface TransformResult {
     code: string;
     sourceMap?: RawSourceMap;
 }
+/** Represents a single validation point in the source code */
+export interface ValidationItem {
+    /** 1-based line number */
+    startLine: number;
+    /** 0-based column */
+    startColumn: number;
+    /** 1-based line number */
+    endLine: number;
+    /** 0-based column */
+    endColumn: number;
+    /** Type of validation: "parameter", "return", "cast", "json-parse", "json-stringify" */
+    kind: "parameter" | "return" | "cast" | "json-parse" | "json-stringify";
+    /** Name of the item being validated (param name, "return value", or expression text) */
+    name: string;
+    /** Whether the item will be validated or skipped */
+    status: "validated" | "skipped";
+    /** Human-readable type string */
+    typeString: string;
+    /** Reason for skipping (when status is "skipped") */
+    skipReason?: string;
+}
+export interface AnalyseResult {
+    items: ValidationItem[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elliots/typical-compiler",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "TypeScript compiler powered by tsgo for typical validation",
   "keywords": [
     "compiler",
@@ -26,16 +26,16 @@
     "typescript": "^5.7.0"
   },
   "optionalDependencies": {
-    "@elliots/typical-compiler-darwin-arm64": "0.2.3",
-    "@elliots/typical-compiler-darwin-x64": "0.2.3",
-    "@elliots/typical-compiler-linux-arm64": "0.2.3",
-    "@elliots/typical-compiler-linux-x64": "0.2.3",
-    "@elliots/typical-compiler-win32-arm64": "0.2.3",
-    "@elliots/typical-compiler-win32-x64": "0.2.3"
+    "@elliots/typical-compiler-darwin-arm64": "0.2.5",
+    "@elliots/typical-compiler-darwin-x64": "0.2.5",
+    "@elliots/typical-compiler-linux-arm64": "0.2.5",
+    "@elliots/typical-compiler-linux-x64": "0.2.5",
+    "@elliots/typical-compiler-win32-arm64": "0.2.5",
+    "@elliots/typical-compiler-win32-x64": "0.2.5"
   },
   "scripts": {
-    "build": "tsc",
-    "build:go": "./go/scripts/sync-shims.sh && cd go && go build -o ../bin/typical ./cmd/typical",
-    "test": "npx tsx test/e2e.ts"
+    "build": "npm run build:ts && npm run build:go",
+    "build:ts": "tsc",
+    "build:go": "./go/scripts/sync-shims.sh && cd go && go build -o ../bin/typical ./cmd/typical"
   }
 }