or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md json-processing.md rules-and-configuration.md

tile.json

JSON Processing

This document covers the JSON file processor that handles parsing, error detection, and message formatting for ESLint integration.

JSON Processor Overview

The JSON processor is the core component that integrates VSCode JSON language service with ESLint. It preprocesses JSON files to extract parsing errors and postprocesses ESLint messages to provide properly formatted output.

Processor Interface

interface JsonProcessor {
  preprocess(text: string, fileName: string): string[];
  postprocess(messages: ESLintMessage[][], fileName: string): ESLintMessage[];
}

Available Processors

.json (Legacy)

Processor for legacy ESLint configurations.

const processor = plugin.processors['.json'];

json (Modern)

Processor for flat config ESLint configurations. Functionally identical to the legacy processor.

const processor = plugin.processors['json'];

Processor Methods

preprocess

Parses JSON content and stores validation results for later processing.

function preprocess(text: string, fileName: string): string[];

Parameters:

text (string): The raw JSON file content
fileName (string): The file path being processed

Returns:

string[]: Array containing a single empty string (ESLint requirement)

Behavior:

Creates a TextDocument using VSCode JSON language service
Parses the JSON content to extract syntax errors and comments
Stores parsing results in internal caches for postprocessing
Returns empty array to satisfy ESLint processor interface

postprocess

Processes ESLint messages and formats them with proper source information.

function postprocess(messages: ESLintMessage[][], fileName: string): ESLintMessage[];

Parameters:

messages (ESLintMessage[][]): Nested array of ESLint messages from rules
fileName (string): The file path being processed

Returns:

ESLintMessage[]: Formatted array of validation messages

Behavior:

Flattens message arrays from multiple rules
Groups messages by unique signature to handle duplicates
Prioritizes specific error messages over generic ones
Adds source code snippets to each message
Adjusts line/column numbers for proper ESLint formatting
Cleans up internal caches for the processed file

Internal Processing Details

Error Deduplication

The processor handles cases where multiple rules report the same error:

// Example: Both 'json/*' and 'json/trailing-comma' might report the same issue
// The processor keeps the more specific error message
const errorSignature = (err) => 
  ['message', 'line', 'column', 'endLine', 'endColumn'].map(field => err[field]).join('::');

Deduplication Algorithm:

Messages are grouped by their unique signature (message + position)
If only one message exists for a signature, it's kept as-is
If multiple messages exist, priority rules apply to select which one to keep

Message Priority

When duplicate errors are found:

Generic errors (json/*, json/json) have lower priority
Specific errors (json/trailing-comma, etc.) have higher priority
When comparing errors of different priorities, the higher priority error is kept
When comparing errors of the same priority level, the higher severity error is kept

Source Code Integration

Each processed message includes the actual source code snippet:

interface ProcessedMessage extends ESLintMessage {
  source: string; // The actual JSON text that caused the error
}

Usage in ESLint Configuration

Flat Config

import json from 'eslint-plugin-json';

export default [
  {
    files: ["**/*.json"],
    plugins: { json },
    rules: {
      'json/*': 'error'
    },
    processor: 'json/json' // Specifies which processor to use
  }
];

Legacy Config

{
  "plugins": ["json"],
  "rules": {
    "json/*": "error"
  },
  "overrides": [
    {
      "files": ["*.json"],
      "processor": "json/.json"
    }
  ]
}

Internal State Management

The processor maintains several internal caches during processing:

// Internal state (not exposed in public API)
interface ProcessorState {
  fileLintResults: Record<string, DiagnosticResult[]>;
  fileComments: Record<string, CommentRange[]>;
  fileDocuments: Record<string, TextDocument>;
}

interface DiagnosticResult {
  code: number;
  message: string;
  range: {
    start: { line: number; character: number };
    end: { line: number; character: number };
  };
}

interface CommentRange {
  start: { line: number; character: number };
  end: { line: number; character: number };
}

Error Code Mapping

The processor maps VSCode JSON language service error codes to ESLint rule names:

const ErrorCodes = {
  Undefined: 0,
  EnumValueMismatch: 1,
  UnexpectedEndOfComment: 0x101,
  UnexpectedEndOfString: 0x102,
  UnexpectedEndOfNumber: 0x103,
  InvalidUnicode: 0x104,
  InvalidEscapeCharacter: 0x105,
  InvalidCharacter: 0x106,
  PropertyExpected: 0x201,
  CommaExpected: 0x202,
  ColonExpected: 0x203,
  ValueExpected: 0x204,
  CommaOrCloseBacketExpected: 0x205,
  CommaOrCloseBraceExpected: 0x206,
  TrailingComma: 0x207,
  DuplicateKey: 0x208,
  CommentNotPermitted: 0x209,
  SchemaResolveError: 0x300
};

Processing Flow Example

// 1. ESLint calls preprocess with JSON file content
const result = processor.preprocess('{"key": "value",}', 'example.json');
// Returns: ['']

// 2. ESLint runs rules against the empty string (rules access cached data)
// Rules report errors based on the parsed JSON data

// 3. ESLint calls postprocess with rule messages
const messages = processor.postprocess([[
  {
    ruleId: 'json/trailing-comma',
    message: 'Trailing comma in object',
    line: 1,
    column: 16,
    endLine: 1,
    endColumn: 17
  }
]], 'example.json');

// Returns formatted messages with source code and adjusted positions

Integration with VSCode JSON Language Service

The processor leverages the VSCode JSON language service for parsing:

// Internal usage (not exposed in public API)
const jsonService = require('vscode-json-languageservice');
const jsonServiceHandle = jsonService.getLanguageService({});

const textDocument = jsonService.TextDocument.create(fileName, 'json', 1, text);
const parsed = jsonServiceHandle.parseJSONDocument(textDocument);
const diagnostics = parsed.syntaxErrors; // Array of parsing errors
const comments = parsed.comments;        // Array of comment ranges

This integration provides:

Robust JSON parsing with comprehensive error detection
Comment extraction and validation
Consistent error reporting format
Support for JSON schema validation (when schemas are provided)

Internal Dependencies:

vscode-json-languageservice: For JSON parsing and validation
lodash/fp: For functional data transformations and processing