Skip to content
Hoody Documentation
Download Page (.md)

Code Validation

Section titled “Code Validation”

Validate script source code across multiple dimensions: syntax, TypeScript transpilation, runtime dependencies, magic comments, and return type conformance. Use these endpoints to lint user-submitted scripts before execution, surface dependency gaps, or extract structured metadata from inline annotations.

All endpoints accept a JSON body containing the source code (and optionally a type definition and value), and return structured validation results.

Validate Script

Section titled “Validate Script”

POST /api/v1/exec/validate/script

Run a full validation pass against a script: syntax check, TypeScript transpilation, dependency inspection, and magic comment parsing — all in one call.

This endpoint takes no parameters.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
codestringYesCode

Response

Section titled “Response”
{
  "valid": true,
  "results": {
    "syntax": {
      "valid": true,
      "message": "JavaScript syntax is valid"
    },
    "typescript": {
      "valid": true,
      "transpiledLength": 1248
    },
    "dependencies": {
      "total": 3,
      "installed": 2,
      "missing": 1,
      "missingModules": ["lodash"],
      "allInstalled": false
    },
    "magicComments": {
      "endpoint": "GET /users"
    },
    "normalized": true,
    "transformations": ["trim", "stripBom"]
  },
  "message": "Script validation completed"
}

SDK

Section titled “SDK”
const result = await client.exec.validate.validateScript({
  data: {
    code: "import _ from 'lodash';\nexport default function() { return _.range(1, 10); }"
  }
});

Validate Syntax

Section titled “Validate Syntax”

POST /api/v1/exec/validate/syntax

Check that a script is syntactically valid JavaScript. Returns the normalized form and any transformations applied during normalization.

This endpoint takes no parameters.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
codestringYesCode

Response

Section titled “Response”
{
  "valid": true,
  "message": "JavaScript syntax is valid",
  "codeLength": 1024,
  "normalized": true,
  "transformations": ["trim", "stripBom", "stripShebang"]
}

SDK

Section titled “SDK”
const result = await client.exec.validate.validateSyntax({
  data: {
    code: "function add(a, b) { return a + b; }"
  }
});

Validate TypeScript

Section titled “Validate TypeScript”

POST /api/v1/exec/validate/typescript

Transpile TypeScript source to JavaScript and verify the transpilation succeeds. Returns the generated JavaScript output and a list of normalization transformations.

This endpoint takes no parameters.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
codestringYesCode

Response

Section titled “Response”
{
  "valid": true,
  "javascript": "function add(a, b) { return a + b; }",
  "originalLength": 1280,
  "transpiledLength": 960,
  "normalized": true,
  "transformations": ["trim", "stripBom", "stripTypeAnnotations"],
  "message": "TypeScript validation successful"
}

SDK

Section titled “SDK”
const result = await client.exec.validate.validateTypeScript({
  data: {
    code: "interface User { id: number; name: string; }\nfunction greet(u: User) { return u.name; }"
  }
});

Validate Dependencies

Section titled “Validate Dependencies”

POST /api/v1/exec/validate/dependencies

Inspect a script for import statements and require() calls, then report which modules are missing from the runtime environment. Useful for surfacing installation requirements before execution.

This endpoint takes no parameters.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
codestringYesCode

Response

Section titled “Response”
{
  "totalModules": 4,
  "allInstalled": false,
  "missingCount": 1,
  "missingModules": ["axios"],
  "dependencies": [
    { "module": "lodash", "installed": true },
    { "module": "axios", "installed": false },
    { "module": "fs", "installed": true },
    { "module": "path", "installed": true }
  ],
  "message": "1 module is missing",
  "installCommand": "npm install axios"
}

SDK

Section titled “SDK”
const result = await client.exec.validate.validateDependencies({
  data: {
    code: "import axios from 'axios';\nimport _ from 'lodash';\nexport default async function() { return _.head(await axios.get('https://api.example.com')); }"
  }
});

Validate Magic Comments

Section titled “Validate Magic Comments”

POST /api/v1/exec/validate/magic-comments

Parse inline magic comments (e.g. /* endpoint: ... */, /* timeout: ... */) and the declared return type from a script. Returns the structured metadata extracted from annotations.

This endpoint takes no parameters.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
codestringYesCode

Response

Section titled “Response”
{
  "magicComments": {
    "endpoint": "POST /orders",
    "timeout": 5000,
    "schedule": "0 */6 * * *"
  },
  "returnType": {
    "definition": "{ orderId: string, status: 'pending' | 'confirmed' }",
    "mode": "strict",
    "location": "line 3, column 18"
  },
  "message": "Magic comments parsed successfully"
}

SDK

Section titled “SDK”
const result = await client.exec.validate.validateMagicComments({
  data: {
    code: "/* endpoint: POST /orders */\n/* timeout: 5000 */\n/** @returns {{ orderId: string, status: 'pending' | 'confirmed' }} */\nexport default function() { return { orderId: 'abc', status: 'pending' }; }"
  }
});

Validate Return Type

Section titled “Validate Return Type”

POST /api/v1/exec/validate/return-type

Verify that a JSON value conforms to a declared TypeScript-style type definition. Returns whether the value matches, a list of validation errors (if any), and a parsed representation of the type.

This endpoint takes no parameters.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
typeDefinitionstringYesType Definition
valueobjectYesArbitrary JSON value to validate against the declared return type

Response

Section titled “Response”
{
  "valid": true,
  "errors": [],
  "typeDefinition": "{ id: number, name: string, tags: string[] }",
  "parsedType": {
    "kind": "object",
    "properties": {
      "id": { "kind": "primitive", "type": "number" },
      "name": { "kind": "primitive", "type": "string" },
      "tags": { "kind": "array", "element": { "kind": "primitive", "type": "string" } }
    }
  },
  "message": "Value conforms to declared return type"
}

SDK

Section titled “SDK”
const result = await client.exec.validate.validateReturnType({
  data: {
    typeDefinition: "{ id: number, name: string, tags: string[] }",
    value: { id: 42, name: "ada", tags: ["admin", "user"] }
  }
});