@irithell-js/easy-syntax

INITIAL PROJECT Multi-language syntax validator for JavaScript, TypeScript, JSON, YAML, HTML, CSS, Markdown, XML, and SQL with precise diagnostics, security analysis, and best-practice hints.

Features

• 9 Language Parsers - JavaScript, TypeScript, JSON, YAML, HTML, CSS, Markdown, XML, SQL
• Precise Diagnostics - Line/column, code snippets with caret markers, suggestions
• Security-Focused SQL - Dangerous DELETE/UPDATE without WHERE, DROP/TRUNCATE warnings, injection risks
• Performance Hints - SELECT *, LIKE '%text%', correlated subqueries, missing LIMITs
• Best Practices - Naming conventions, modern syntax, data integrity per language
• Strict Mode - Extra formatting, style and consistency rules
• Language Detection - Auto-detect from code content
• Multi-File Support - Single file or directory validation
• TypeScript-First - Full type definitions included
• Dual Format - ESM + CommonJS with automatic type resolution

Installation

npm i @irithell-js/easy-syntax

Quick Start

Basic Usage (ESM - Single File)

import { createValidator } from "@irithell-js/easy-syntax";

const validator = createValidator();

const sqlCode = \`
SELECT * FROM users
WHERE email = NULL
\`;

const result = validator.validate(sqlCode, {
  language: "sql",
  locale: "pt-BR",
  strict: true,
});

console.log("Valid:", result.valid);
console.log("Errors:", result.errors.length);
console.log("Warnings:", result.warnings.length);

Basic Usage (CommonJS - Single File)

const { createValidator } from "@irithell-js/easy-syntax";

const validator = createValidator();

const jsCode = `
const obj = {
  name: 'John',
  age: 30,
}; // trailing comma
`;

const result = validator.validate(jsCode, {
  language: "javascript",
  locale: "en",
  strict: true,
});

if (!result.valid) {
  result.errors.forEach(error => {
    console.log(\`[Line \${error.line}, Col \${error.column}] \${error.message}\`);
  });
}

Runtime Diagnostics

Exclusive feature to analyze errors during execution (ESM & CJS). It automatically detects environment issues like missing files or logical crashes.

import { createValidator, formatError } from "@irithell-js/easy-syntax";

try {
  // Trying to import a file that doesn't exist
  await import("./missing-file.mjs");
} catch (err) {
  const validator = createValidator();
  const analysis = validator.handleRuntimeError(err, { locale: "pt-BR" });

  // Formatted error with suggestions
  console.log(formatError(analysis));
}

Terminal Output

Don't just get a JSON object. Use formatError to get human-readable diagnostics:

import { createValidator, formatError } from "@irithell-js/easy-syntax";

const result = validator.validate("const a = ", { language: "javascript" });

if (!result.valid) {
  result.errors.forEach((err) => console.log(formatError(err)));
}

Auto-Detect Language (ESM)

import { createValidator } from "@irithell-js/easy-syntax";

const validator = createValidator();

const unknownCode = \`
{
  "name": "example",
  "version": "1.0.0"
}
\`;

const result = validator.detectAndValidate(unknownCode, {
  strict: false,
  locale: "en",
});

console.log("Detected language:", result.language);
console.log("Valid:", result.valid);
console.log("Parse time:", result.metadata.parseTime.toFixed(2), "ms");

Validate File (ESM)

import { createValidator } from "@irithell-js/easy-syntax";
import { readFileSync } from "fs";

const validator = createValidator();

const code = readFileSync("./src/index.ts", "utf-8");

const result = validator.validate(code, {
  language: "typescript",
  strict: true,
  locale: "pt-BR",
});

Validate Multiple Files (ESM)

import { createValidator } from "@irithell-js/easy-syntax";
import { readdirSync, readFileSync, statSync } from "fs";
import { extname, join } from "path";

const validator = createValidator();

function validateDirectory(dir: string) {
  const results = [];

  for (const file of readdirSync(dir)) {
    const fullPath = join(dir, file);
    if (statSync(fullPath).isFile() && extname(file) !== ".md") {
      const code = readFileSync(fullPath, "utf-8");
      const result = validator.detectAndValidate(code, {
        strict: true,
        locale: "en",
      });
      results.push({ file, result });
    }
  }

  return results.filter((r) => !r.result.valid);
}

const invalidFiles = validateDirectory("./src");
console.log("Invalid files:", invalidFiles.length);

CommonJS - Multiple Files

const { createValidator } = require("@irithell-js/easy-syntax");
const fs = require("fs");
const path = require("path");

const validator = createValidator();

function validateFile(filePath) {
  const code = fs.readFileSync(filePath, "utf-8");
  const ext = path.extname(filePath);

  const language = ext === ".ts" ? "typescript" :
                   ext === ".sql" ? "sql" :
                   "auto";

  return validator.validate(code, {
    language,
    strict: true,
    locale: "en",
  });
}

// Validate specific files
const results = [
  validateFile("./src/parser.ts"),
  validateFile("./database/schema.sql"),
  validateFile("./styles/main.css"),
];

results.forEach((result, i) => {
  if (!result.valid) {
    console.log(\`File \${i+1} has errors:\`, result.errors);
  }
});

Configuration

Factory Options

const validator = createValidator({
  defaultLocale: "en", // en or pt-BR
  strictByDefault: false, // Strict mode by default
});

Per-Validation Options

interface ValidateOptions {
  language:
    | "javascript"
    | "typescript"
    | "json"
    | "yaml"
    | "html"
    | "css"
    | "markdown"
    | "xml"
    | "sql"
    | "auto";
  locale?: "en" | "pt-BR";
  strict?: boolean;
  dialect?: "mysql" | "postgresql" | "sqlite"; // SQL only
}

Supported Languages & Examples

JavaScript (ESM/CommonJS/JSX)

const js = \`
const sum = (a, b) => {
  return a + b
}
console.log(sum(1, 2)); // console.log in production
\`;

const result = validator.validate(js, {
  language: "javascript",
  strict: true,
});

Strict mode warnings: Missing semicolon, console.log usage

TypeScript (Types/TSX/Generics)

const ts = \`
interface User {
  name: string;
  age?: number
}

const users: User[] = [{
  name: "John"
  // missing age, but optional
}];
\`;

const result = validator.validate(ts, { language: "typescript" });

Validations: Interface syntax, array type checking

JSON (JSON5 support)

const json = \`
{
  "name": "project",
  "version": "1.0.0",
  "scripts": {
    "test": "echo \"test\""
  }
}
\`;

const result = validator.validate(json, { language: "json" });

Validations: Trailing commas, unterminated strings

YAML (Multi-doc)

const yaml = \`
name: project
version: 1.0.0

---
name: another
version: 2.0.0
\`;

const result = validator.validate(yaml, { language: "yaml" });

Validations: Indentation, duplicate keys

HTML

const html = \`
<!DOCTYPE html>
<html>
  <body>
    <div class="container">
      <p>Missing closing
    </div>
  </body>
</html>
\`;

const result = validator.validate(html, { language: "html" });

Validations: Unclosed <p> tag

CSS/PostCSS

const css = \`
.button {
  color: red !important;
  margin: 0;
  margin: 10px; /* duplicate */
}

@media (max-width: 600px) {
  /* unclosed media */
\`;

const result = validator.validate(css, { language: "css", strict: true });

Validations: Duplicate margin, unclosed media query, !important warning

Markdown (GFM)

const md = \`
# Title

[Link](https://example.com)

\`\`\`js
console.log("unclosed fence");
\`\`\`

- [ ] Task list
\`;

const result = validator.validate(md, { language: "markdown", strict: true });

Validations: Unclosed code fence

XML/SVG

const xml = \`
<svg width="100" height="100">
  <circle cx="50" cy="50" r="40" />
</svg>
\`;

const result = validator.validate(xml, { language: "xml" });

Validations: Self-closing tags, namespaces

SQL (Security + Performance)

const sql = \`
-- Dangerous: affects all rows!
DELETE FROM users;

-- Performance issues
SELECT * FROM orders o
INNER JOIN users u ON o.user_id = u.id
INNER JOIN payments p ON p.order_id = o.id
WHERE o.status LIKE '%pending%';

-- Wrong NULL handling
WHERE email = NULL;
\`;

const result = validator.validate(sql, {
  language: "sql",
  dialect: "mysql",
  locale: "pt-BR",
  strict: true,
});

Warnings:

• DELETE without WHERE (CRITICAL)
• SELECT *
• LIKE with leading wildcard
• = NULL instead of IS NULL

Result Structure

{
  valid: boolean,
  language: "sql",
  errors: [
    {
      line: 2,
      column: 1,
      message: "SQL syntax error",
      code: "SQL_PARSE_ERROR",
      severity: "error",
      snippet: { /* code context with ^ marker */ },
      suggestion: "Check syntax around line 2"
    }
  ],
  warnings: [
    {
      line: 8,
      column: 12,
      message: "DELETE without WHERE affects all rows - very dangerous!",
      code: "SQL_NO_WHERE_DANGEROUS",
      severity: "warning",
      suggestion: "Add WHERE clause to limit affected rows"
    }
  ],
  metadata: {
    linesChecked: 12,
    parseTime: 2.34,
    parserName: "node-sql-parser",
    parserVersion: "5.4.0"
  }
}

Strict Mode Examples

SQL Strict Mode

const sql = \`
select * from users where id = 1
\`;

const result = validator.validate(sql, {
  language: "sql",
  strict: true,
  locale: "pt-BR",
});
// Warnings: lowercase keywords, missing semicolon, SELECT *

### JavaScript Strict Mode

```typescript
const js = \`
function test() {
  var x = 1
  console.log(x)
}
\`;

const result = validator.validate(js, {
  language: "javascript",
  strict: true,
});
// Warnings: missing semicolons, console.log, var instead of let/const

Performance

| Language | 100 lines | 500 lines | 1000 lines | | ---------- | --------- | --------- | ---------- | | JavaScript | 2.5ms | 8ms | 15ms | | TypeScript | 4ms | 12ms | 22ms | | JSON | 0.8ms | 2ms | 4ms | | YAML | 1.2ms | 3ms | 6ms | | HTML | 1.5ms | 4ms | 8ms | | CSS | 0.6ms | 1.8ms | 3.5ms | | Markdown | 3ms | 15ms | 35ms | | XML | 1ms | 2.5ms | 5ms | | SQL | 1.8ms | 5ms | 10ms |

Local tests, Node.js 24, strict mode enabled

Status

Early-stage project - APIs and rules may change before stable 1.x release.

Support

If you found a bug or have a suggestion, reach out directly:

• WhatsApp: +55 15 99836-1316

Requirements

• Node.js >= 18.0.0

License

MIT

Changelog

1.0.0 (latest)

• Initial release with 9 language parsers
• Detailed diagnostics with snippets and suggestions
• SQL security/performance analysis
• Multi-language support (EN/PT-BR)
• TypeScript definitions
• ESM + CommonJS support