Skip to content
Hoody Documentation
Hoody.com
Download Page (.md)

The Code Validation API provides endpoints for static analysis of user-supplied scripts before execution. Use these endpoints to check JavaScript syntax, transpile TypeScript, validate declared return types, inspect magic comments, audit required dependencies, or run a full end-to-end validation in a single call.

All endpoints accept a JSON body and are scoped to a specific exec container instance.

Validate Script

Section titled “Validate Script”

POST /api/v1/exec/validate/script

Section titled “POST /api/v1/exec/validate/script”

Run the full validation pipeline on a script source string. The pipeline combines syntax checks, TypeScript transpilation, dependency analysis, magic-comment parsing, and normalization reporting into a single response.

This endpoint takes no parameters.

Request Body

Section titled “Request Body”
FieldTypeRequiredDescription
codestringYesThe full script source to validate.

SDK

Section titled “SDK”
await client.exec.validate.validateScript({
  code: "import axios from 'axios';\n// @timeout 30s\nexport default async function main() {\n  return { ok: true };\n}"
});

Responses

Section titled “Responses”
{
  "valid": true,
  "results": {
    "syntax": {
      "valid": true,
      "message": "JavaScript syntax is valid"
    },
    "typescript": {
      "valid": true,
      "transpiledLength": 412
    },
    "dependencies": {
      "total": 1,
      "installed": 0,
      "missing": 1,
      "missingModules": ["axios"],
      "allInstalled": false
    },
    "magicComments": {
      "timeout": "30s"
    },
    "magicCommentWarnings": [],
    "normalized": false,
    "transformations": []
  },
  "message": "Script validation completed"
}

Validate Syntax

Section titled “Validate Syntax”

POST /api/v1/exec/validate/syntax

Section titled “POST /api/v1/exec/validate/syntax”

Verify that the supplied code is syntactically valid JavaScript. Normalization transformations (if any) are reported back so the caller can understand why the script was rewritten before parsing.

This endpoint takes no parameters.

Request Body

Section titled “Request Body”
FieldTypeRequiredDescription
codestringYesThe JavaScript source to syntax-check.

SDK

Section titled “SDK”
await client.exec.validate.validateSyntax({
  code: "export default function main() { return 42; }"
});

Responses

Section titled “Responses”
{
  "valid": true,
  "message": "JavaScript syntax is valid",
  "codeLength": 41,
  "normalized": false,
  "transformations": []
}

Validate TypeScript

Section titled “Validate TypeScript”

POST /api/v1/exec/validate/typescript

Section titled “POST /api/v1/exec/validate/typescript”

Transpile TypeScript source to JavaScript and confirm the transpilation succeeded. The returned javascript field contains the transpiled output, which can be diffed or fed back into other validators.

This endpoint takes no parameters.

Request Body

Section titled “Request Body”
FieldTypeRequiredDescription
codestringYesThe TypeScript source to transpile and validate.

SDK

Section titled “SDK”
await client.exec.validate.validateTypeScript({
  code: "interface User { id: number; name: string; }\nexport default (u: User): User => u;"
});

Responses

Section titled “Responses”
{
  "valid": true,
  "javascript": "export default (u) => u;",
  "originalLength": 76,
  "transpiledLength": 24,
  "normalized": false,
  "transformations": [],
  "message": "TypeScript validation successful"
}

Validate Dependencies

Section titled “Validate Dependencies”

POST /api/v1/exec/validate/dependencies

Section titled “POST /api/v1/exec/validate/dependencies”

Inspect the script for import and require statements, resolve the set of imported modules, and check which are installed in the container’s runtime. The response includes a ready-to-run install command when modules are missing.

This endpoint takes no parameters.

Request Body

Section titled “Request Body”
FieldTypeRequiredDescription
codestringYesThe source to scan for dependencies.

SDK

Section titled “SDK”
await client.exec.validate.validateDependencies({
  code: "import axios from 'axios';\nimport _ from 'lodash';\nexport default async function main() { return _.size([1, 2, 3]); }"
});

Responses

Section titled “Responses”
{
  "totalModules": 2,
  "allInstalled": false,
  "missingCount": 1,
  "missingModules": ["axios"],
  "dependencies": [
    { "module": "axios", "installed": false, "version": null },
    { "module": "lodash", "installed": true, "version": "4.17.21" }
  ],
  "message": "1 of 2 modules are missing",
  "installCommand": "npm install axios"
}

Validate Magic Comments

Section titled “Validate Magic Comments”

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

Section titled “POST /api/v1/exec/validate/magic-comments”

Parse top-level magic comments (e.g. @timeout, @memory, @cpu) from the script source. The response surfaces parsed directives, warnings for any directive values that were rejected, and the inferred return type when one is declared.

This endpoint takes no parameters.

Request Body

Section titled “Request Body”
FieldTypeRequiredDescription
codestringYesThe script source to inspect for magic comments.

SDK

Section titled “SDK”
await client.exec.validate.validateMagicComments({
  code: "// @timeout 30s\n// @memory 256mb\n/** @returns {{ id: string, ok: boolean }} */\nexport default async function main() { return { id: 'x', ok: true }; }"
});

Responses

Section titled “Responses”
{
  "magicComments": {
    "timeout": "30s",
    "memory": "256mb"
  },
  "warnings": [
    {
      "directive": "@cpu",
      "value": "9bogus",
      "message": "Unknown unit suffix on @cpu value; falling back to default"
    }
  ],
  "returnType": {
    "definition": "{ id: string, ok: boolean }",
    "mode": "object",
    "location": "inline"
  },
  "message": "Magic comments parsed with 1 warning"
}

Validate Return Type

Section titled “Validate Return Type”

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

Section titled “POST /api/v1/exec/validate/return-type”

Validate an arbitrary JSON value against a declared type definition. Useful for confirming that the runtime value a script produced matches the contract declared in its magic comments.

This endpoint takes no parameters.

Request Body

Section titled “Request Body”
FieldTypeRequiredDescription
typeDefinitionstringYesThe TypeScript-style type definition to validate against.
valueJSON valueYesThe runtime value to validate. Sent as raw JSON in the request body.

SDK

Section titled “SDK”
await client.exec.validate.validateReturnType({
  typeDefinition: "{ id: string, ok: boolean, items: number[] }",
  value: { id: "order-42", ok: true, items: [1, 2, 3] }
});

Responses

Section titled “Responses”
{
  "valid": true,
  "errors": [],
  "typeDefinition": "{ id: string, ok: boolean, items: number[] }",
  "parsedType": {
    "kind": "object",
    "fields": {
      "id": "string",
      "ok": "boolean",
      "items": { "kind": "array", "element": "number" }
    }
  },
  "message": "Value matches the declared type"
}