npm package: @irithell-js/easy-syntax
Description: Multi-language syntax validator with TypeScript, JavaScript, JSON, YAML, HTML, CSS, SQL and more in future.
Author: Irithell
Latest version: 1.0.0

# @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

```bash
npm i @irithell-js/easy-syntax
```

## Quick Start

### Basic Usage (ESM - Single File)

```typescript
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)

```javascript
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.

```typescript
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:

```typescript
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)

```typescript
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)

```typescript
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)

```typescript
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

```javascript
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

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

### Per-Validation Options

```typescript
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)

```typescript
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)

```typescript
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)

```typescript
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)

```typescript
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

```typescript
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

```typescript
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)

```typescript
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

```typescript
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)

```typescript
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

```typescript
{
  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

````typescript
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](https://wa.me/5515998361316)

## 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