ast-guard

npm install @enclave-vm/ast

new JSAstValidator(preset: ValidationPreset)

async validate(code: string): Promise<ValidationResult>

interface ValidationResult {
  valid: boolean;
  issues: ValidationIssue[];
  ast?: ESTree.Program;
}

interface ValidationIssue {
  rule: string;
  message: string;
  severity: 'error' | 'warning' | 'info';
  location?: {
    line: number;
    column: number;
    endLine?: number;
    endColumn?: number;
  };
  fix?: {
    range: [number, number];
    text: string;
  };
}

import { JSAstValidator, createAgentScriptPreset } from '@enclave-vm/ast';

const validator = new JSAstValidator(createAgentScriptPreset());
const result = await validator.validate(`
  const x = eval('code');
`);

if (!result.valid) {
  for (const issue of result.issues) {
    console.log(`${issue.rule}: ${issue.message}`);
  }
}

new PreScanner(config: PreScannerConfig)

scan(code: string): PreScanResult

interface PreScanResult {
  valid: boolean;
  issues: PreScanIssue[];
}

interface PreScanIssue {
  message: string;
  severity: 'error' | 'warning';
}

import { PreScanner, createPreScannerConfig } from '@enclave-vm/ast';

const scanner = new PreScanner(createPreScannerConfig('agentscript'));
const result = scanner.scan(code);

if (!result.valid) {
  console.log('Pre-scan failed:', result.issues);
}

function createAgentScriptPreset(options?: AgentScriptOptions): ValidationPreset

interface AgentScriptOptions {
  // Globals
  allowedGlobals?: string[];
  additionalDisallowedIdentifiers?: string[];

  // Features
  requireCallTool?: boolean;

  // Loops
  allowedLoops?: {
    allowFor?: boolean;
    allowForOf?: boolean;
    allowWhile?: boolean;
    allowDoWhile?: boolean;
    allowForIn?: boolean;
  };

  // Functions
  allowArrowFunctions?: boolean;
  allowFunctionDeclarations?: boolean;
}

const preset = createAgentScriptPreset({
  allowedGlobals: ['callTool', 'Math', 'JSON', 'console', 'context'],
  allowedLoops: {
    allowFor: true,
    allowForOf: true,
    allowWhile: false,
  },
});

function createPreScannerConfig(preset: 'agentscript' | 'standard'): PreScannerConfig

interface PreScannerConfig {
  maxInputSize: number;
  maxNestingDepth: number;
  maxStringLength: number;
  maxArrayLiteralLength: number;
  checkReDoS: boolean;
  blockedPatterns: RegExp[];
}

function createSecurityRules(): ValidationRule[]

interface ValidationPreset {
  rules: ValidationRule[];
  globals: GlobalConfig;
  transforms?: TransformConfig[];
}

interface GlobalConfig {
  allowed: string[];
  disallowed: string[];
}

interface ValidationRule {
  id: string;
  name: string;
  description: string;
  severity: 'error' | 'warning' | 'info';
  check: (node: ESTree.Node, context: RuleContext) => void;
}

interface RuleContext {
  report: (issue: Omit<ValidationIssue, 'rule'>) => void;
  getSource: () => string;
  getAncestors: () => ESTree.Node[];
}

function transformAgentScript(
  code: string,
  options?: TransformOptions
): string

interface TransformOptions {
  wrapInMain?: boolean;
  transformCallTool?: boolean;
  transformLoops?: boolean;
  transformConsole?: boolean;
}

import { transformAgentScript } from '@enclave-vm/ast';

const transformed = transformAgentScript(`
  const users = await callTool('users:list', {});
  for (const user of users) {
    console.log(user.name);
  }
  return users.length;
`, {
  wrapInMain: true,
  transformCallTool: true,
  transformLoops: true,
});

// Output:
// async function __ag_main() {
//   const users = await __safe_callTool('users:list', {});
//   for (const user of __safe_forOf(users)) {
//     __safe_console.log(user.name);
//   }
//   return users.length;
// }

import { ValidationRule, RuleContext } from '@enclave-vm/ast';

const noConsoleRule: ValidationRule = {
  id: 'no-console',
  name: 'No Console',
  description: 'Disallow console statements',
  severity: 'warning',

  check(node, context) {
    if (
      node.type === 'CallExpression' &&
      node.callee.type === 'MemberExpression' &&
      node.callee.object.type === 'Identifier' &&
      node.callee.object.name === 'console'
    ) {
      context.report({
        message: 'Console statements are not allowed',
        severity: 'warning',
        location: {
          line: node.loc?.start.line || 0,
          column: node.loc?.start.column || 0,
        },
      });
    }
  },
};

import { JSAstValidator, createAgentScriptPreset } from '@enclave-vm/ast';

const preset = createAgentScriptPreset();
preset.rules.push(noConsoleRule);

const validator = new JSAstValidator(preset);

import {
  JSAstValidator,
  PreScanner,
  createAgentScriptPreset,
  createPreScannerConfig,
  transformAgentScript,
} from '@enclave-vm/ast';

async function validateAndTransform(code: string) {
  // Step 1: Pre-scan
  const scanner = new PreScanner(createPreScannerConfig('agentscript'));
  const scanResult = scanner.scan(code);

  if (!scanResult.valid) {
    return { valid: false, error: 'Pre-scan failed', issues: scanResult.issues };
  }

  // Step 2: AST validation
  const preset = createAgentScriptPreset({
    allowedGlobals: ['callTool', 'Math', 'JSON', 'console'],
  });
  const validator = new JSAstValidator(preset);
  const validation = await validator.validate(code);

  if (!validation.valid) {
    return { valid: false, error: 'Validation failed', issues: validation.issues };
  }

  // Step 3: Transform
  const transformed = transformAgentScript(code, {
    wrapInMain: true,
    transformCallTool: true,
    transformLoops: true,
  });

  return { valid: true, code: transformed };
}

// Usage
const result = await validateAndTransform(`
  const users = await callTool('users:list', { limit: 10 });
  return users.length;
`);

if (result.valid) {
  console.log('Transformed code:', result.code);
} else {
  console.log('Validation errors:', result.issues);
}