olympus-group/athena

Rules language for JSON files

Athena

Athena is a validation language for JSON files. With this validator, you can ensure your JSON files meet specific criteria, making data validation straightforward and reliable. All you need to do is to create a schema that describes the rules for validating JSON file, and you'll get the result!

Design document

Link to the design document

Getting started

1. Create a schema: Create a schema file using Athena's syntax that describes all the rules for validating your JSON data.
2. Run Athena: Run the validator program passing your schema and the JSON file you're validating as parameters.
3. Review results: The program will inform you on whether your JSON file is valid or not based on the provided schema.

Installation

1. Ensure you have Node.js >=18.18.0 installed.
2. Clone this repository:

git clone https://github.com/Olympus-Group/athena.git

3. Install dependencies:

npm install

Running the program

Run the program with this command

npx ts-node index.ts ['-s, --schema <file.schema>'] ['-c, --config <file.json>'] | ['-h --help']

['-s, --schema <file.schema>'] – required option: filepath to schema

['-c, --config <file.json>'] – required option: filepath to JSON config

['-h --help'] – optional parameter: information about all options supported by CLI

Running tests

In general mode:

npm test

In developer mode:

npm run test:dev

Examples

Rules supported by Athena's schemas:

Rule	Rule's value type	Description
required	bool	States whether the field is required
optional	bool	States whether the field is optional
isNotEmpty	bool	Checks whether the field is not empty
equals	any	Checks whether the field's value is equal to rule's value
notEquals	any	Checks whether the field's value is not equal to rule's value
isString	bool	Checks whether the field's value is a string
notString	bool	Checks whether the field's value is not a string
isNumber	bool	Checks whether the field's value is a number
notNumber	bool	Checks whether the field's value is not a number
isBool	bool	Checks whether the field's value is boolean
notBool	bool	Checks whether the field's value is not boolean
isUUID	bool	Checks whether the field's value is a UUID
isDatetime	bool	Checks whether the field's value is a Datetime value
isNegative	bool	Checks whether the field's value is negative
isPositive	bool	Checks whether the field's value is positive
min	number	Checks whether the field's value is more than minimal value
max	number	Checks whether the field's value is less than maximal value

Examples of full schemas and JSON configs can be found in .\test\static

Coming soon

• support of arrays as a type of data in fields
• support of nested JSON files validation

athena's Issues

[ENHANCEMENT] Add link to design document

Description

Add link to design document to README.md

To-Do:

• Add link to design document

[ENHANCEMENT] Refactor nodes transformation

Description

In the file /core/utils/nodes.ts we have a getNodeByName function that returns the node basing on the name that is thrown through the arguments. Your task is to replace the huge if-statement with another approach (map or etc.).

Your implementation must be scalable for other nodes.

To-Do:

• Refactor get node function

[ENHANCEMENT] Add help CLI option

Description

Help (or --help) option is usually used to log all the available commands for the user. Your task is to implement such option and describe our syntax requirements there.

To-Do:

• Add --help option
• Add syntax description

[BUG] Change ESLint for TypeScript

Description

Currently, we use JS-based ESLint version that throws an error when we use type declaration in TS. Your task is change .eslint.json file to use TS-based ESLint.

To-Do:

• Change parser option into @typescript-eslint/parser
• Add extends option with content plugin:@typescript-eslint/recommended

[BUG] Remove brackets from schemas

To-Do:

• Remove brackets from 1-simple.schema
• Remove brackets from 2-arrays.schema

[FEATURE] Add command line interface

Description

A command-line interface (CLI) is a means of interacting with a computer program by inputting lines of text called command-lines. Your task is to create a simple example of such an interface to interact with our project logic. You can use any library of CLI framework.

To-Do:

• Add required schema option
• Add required config option

You may add another flags if needed.

[FEATURE] Add lexer unit tests

Description

Unit testing, also known as component or module testing, is a form of software testing by which isolated source code is tested to validate expected behavior.

Unit testing describes tests that are run at the unit level to contrast testing at the integration or system level.

To-Do:

• Add valid syntax cases
• Add invalid syntax cases
• Add different token types cases

[FEATURE] Add CLI unit tests

Description:

Unit testing, also known as component or module testing, is a form of software testing by which isolated source code is tested to validate expected behavior.

Unit testing describes tests that are run at the unit level to contrast testing at the integration or system level.

To-Do:

• Add valid CLI parameters cases
• Add invalid CLI parameters cases

[FEATURE] Add entry point

Description

We have a file index.ts. There you have to implement the usage of our system with CLI-input and files reading, logging and outputting the result.

To-Do:

• Add CLI usage
• Add file system usage
• Add lexer and parser usage

[FEATURE] Add project structure

Description

Add project directories and create mock files to show the future structure.

To-Do:

• Add project directories
• Add mock files

[ENHANCEMENT] Add token types

Description

We have a lexer and some basic tokens with their regular expressions. Your task is to cover all the developed syntax with such tokens and corresponding regexps.

To-Do:

• Add String token type
• Add Bool token type
• Add Number token type

You can add your own custom types according to the project documentation.

[FEATURE] Add file system interface

Description

Use built-in file system manager and develop unified interfaces for reading files with .schema and .json formats.

To-Do:

• Add and export function for reading custom .schema files
• Add and export function for reading .json files and converting them into object

Additional Notes

Your functions must check file existence and permission to open it. If not, throw an error.

[FEATURE] Add reader unit tests

Description

Unit testing, also known as component or module testing, is a form of software testing by which isolated source code is tested to validate expected behavior.

Unit testing describes tests that are run at the unit level to contrast testing at the integration or system level.

To-Do:

• Add valid files cases
• Add invalid files cases
• Add inaccessible file case

[FEATURE] Add GitHub templates

Description

We will use a lot of issues in our project, and the best way to unify them is to set up the default template for all the labels.

To-Do:

• Add issues templates: feature, enhancement, bug
• Add pull request template

Additional Notes

Configuration files:

• /.github/ISSUE_TEMPLATE/
• /.github/PULL-REQUEST-TEMPLATE.md

[FEATURE] Add basic parser logic

Description

Parsing, syntax analysis, or syntactic analysis is the process of analyzing a string of symbols, either in natural language, computer languages or data structures, conforming to the rules of a formal grammar.

Within computational linguistics, the term is used to refer to the formal analysis by a computer of a sentence or other string of words into its constituents, resulting in a parse tree showing their syntactic relation to each other, which may also contain semantic information. Some parsing algorithms generate a parse forest or list of parse trees from a string that is syntactically ambiguous.

To-Do:

Your task is to create a parser structure with a method that validates and converts a list of tokens into a parse list with next structure:

{
    "name": "FIELD_NAME",
    "operations": [
         IsNumberNode,
         IsRequiredNode
    ]
}

Node is the basic cover over the rule operation with method Run(value) that checks if field value satisfies the conditions.

• Add basic parser class
• Add simple nodes

[FEATURE] Add basic lexer logic

Description

In computer science, lexical analysis is the process of analytically parsing an input sequence of characters (such as source code in a programming language) to produce an output sequence of characters called "tokens" (similar to the grouping of letters in words).

A group of characters in an input sequence that is identified as a token at the output of a process is called a token. In the process of lexical analysis, lexemes are recognized and extracted from the input sequence of characters.

To-Do:

Your task is to implement basic lexer and create an opportunity to extend the syntax with another tokens. You have to implement some basic token's regexp (like Field and Option), but not implement all the syntax.

• Add lexer logic
• Add token class
• Add basic token types

Additional Notes

See the syntax example on our development board.

[ENHANCEMENT] Add complex logging

Description

In the parser, we used a special logger directory with messages for different exceptions. Your task is to replace all system error messages (both in Lexer and Parser) with such approach. You can change error messages as you want.

To-Do:

• Replace error messages in Lexer
• Replace error messages in nodes

[ENHANCEMENT] Add rule nodes

Description

Node is the basic cover over the rule operation with method Run(value) that checks if field value satisfies the conditions.

To-Do:

• Add [name] node
• Add [name] node
• Add [name] node
• Add new nodes to token-node map

Additional Notes

See the available operations on the development board.

[FEATURE] Add parser and nodes unit tests

Description

Your task is to fully tests parser with unit tests.

Unit testing, also known as component or module testing, is a form of software testing by which isolated source code is tested to validate expected behavior.

Unit testing describes tests that are run at the unit level to contrast testing at the integration or system level.

To-Do:

• Add tests for valid schemas
• Add tests for invalid schemas
• Test all Nodes on different input types

[FEATURE] Add continuous integration

Description

Continuous integration (CI) is the practice of frequently building and testing a software system during its development. It is intended to ensure that code written by programmers is always buildable, runnable and passes automated testing. Developers merge to an integration branch and an automated system builds and tests.

To-Do:

• Add deploy.yml file to .github directory
• Add dependency installation step
• Add test running step

[BUG] Fix jest configuration

Description

We use Jest framework for testing our components. Unfortunately, we made a mistake during its' configuration for TypeScript. Your task is research the topic and refactor config and existing tests.

To-Do:

• Fix Jest configuration
• Refactor CLI unit tests

[FEATURE] Add npm project

Description

Initialize a npm project with basic development configuration (typescript and eslint).

To-Do:

• Add npm project
• Add development tools
• Add code style tools

[FEATURE] Add project description

Description

Your task is to add README.md file to the root directory of the repository, where you have to describe what our project is and give the instruction of its usage.

To-Do:

• Add README.md file
• Describe project
• Describe usage of the project

[FEATURE] Add examples for testing

Description

We have a test directory in our project where we will store unit testing files of our system. Your task is to add some examples of schemas and services in separate directory inside the test. Include invalid examples as well.

To-Do:

• Add valid examples
• Add invalid examples

Additional Notes

See the syntax example on our development board.

[ENHANCEMENT] Update project description

Description

Update Readme and files for testing.

To-Do:

• Update link to design document
• Update static files for testing

[BUG] Fix command line interface

To-Do:

• Add jest.config file
• Fix CLI tests
• Fix code style

[ENHANCEMENT] Add expected value logging

To-Do:

• Rework node interface
• Add expected value output