Merge pull request #1 from distributed-lab/dev

MVP

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,28 @@
+name: Bug Report
+description: File a bug report
+labels: ['bug']
+body:
+  - type: markdown
+    attributes:
+      value: Thanks for taking the time to fill out this bug report!
+  - type: input
+    id: version
+    attributes:
+      label: "Project version"
+      placeholder: "1.2.3"
+    validations:
+      required: true
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A brief description of what happened and what you expected to happen
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction-steps
+    attributes:
+      label: "Minimal reproduction steps"
+      description: "The minimal steps needed to reproduce the bug"
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -0,0 +1,11 @@
+name: Feature request
+description: Suggest a new feature
+labels: ['feature']
+body:
+  - type: textarea
+    id: feature-description
+    attributes:
+      label: "Describe the feature"
+      description: "A description of what you would like to see in the project"
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/other-issue.md

@@ -0,0 +1,4 @@
+---
+name: Other issue
+about: Other kind of issue
+---

.github/actions/setup/action.yml

@@ -0,0 +1,16 @@
+name: setup
+
+description: setup
+
+runs:
+  using: composite
+  steps:
+    - name: Setup node
+      uses: actions/setup-node@v3
+      with:
+        node-version: "18.x"
+        cache: npm
+
+    - name: Install packages
+      run: npm install
+      shell: bash

.github/workflows/checks.yml

@@ -0,0 +1,23 @@
+name: "checks"
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+      - dev
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@v3
+
+      - name: Setup
+        uses: ./.github/actions/setup
+
+      - name: Run tests
+        run: npm run test

.gitignore

@@ -0,0 +1,6 @@
+dist
+node_modules
+.idea
+!parser/antlr-4.13.1-complete.jar
+!parser/generate.sh
+parser/*

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "circom-g4-grammar"]
+	path = circom-g4-grammar
+	branch = main
+	url = https://github.com/distributed-lab/circom-g4-grammar.git

.husky/pre-commit

@@ -0,0 +1 @@
+npm run lint-fix && git add -u

.mocharc.json

@@ -0,0 +1,7 @@
+{
+  "require": [ "ts-node/register" ],
+  "extensions": ["ts"],
+  "spec": [
+    "test/**/*.ts"
+  ]
+}

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Distributed Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1 +1,60 @@
-# Circom Parser
+# Circom Parser
+
+A TypeScript package for parsing [Circom](https://docs.circom.io) code using [ANTLR (ANother Tool for Language Recognition)](https://github.com/distributed-lab/circom-g4-grammar) grammar.
+
+It includes built-in visitors and utilities that allow you to parse, traverse, and manipulate Circom circuits.
+
+## Installation
+
+```bash
+npm install @distributed-lab/circom-parser
+```
+
+## Usage
+
+### Custom Visitor Creation
+
+To create your own visitor, simply extend the CircomVisitor class and override the visit methods you need.
+
+```typescript
+import { CircomVisitor, AnyRuleContext } from '@distributed-lab/circom-parser';
+
+export default class MyCircomVisitor extends CircomVisitor {
+    visitAnyRule = (ctx: AnyRuleContext) => {
+        // override the visit logic here
+    }
+}
+```
+
+### Custom Visitor Usage
+
+After creating your custom visitor, you can use it with the CircomParser to traverse and manipulate the parse tree.
+
+```typescript
+import { getCircomParser, ParserError } from '@distributed-lab/circom-parser';
+
+import { MyCircomVisitor } from './MyCircomVisitor';
+
+const { parser, errorListener } = getCircomParser(source);
+
+const templateVisitor = new MyCircomVisitor();
+
+templateVisitor.visit(parser.circuit());
+
+if (errorListener.hasErrors()) {
+    throw new ParserError(errorListener.getErrors());
+}
+```
+
+## Reference: Built-in Visitors
+
+You can use the built-in visitors provided in this package as a reference or starting point for your own implementations:
+- [CircomTemplateVisitor](./src/builtin/CircomTemplateVisitor.ts)
+- [CircomIncludeVisitor](./src/builtin/CircomIncludeVisitor.ts)
+- [CircomMainComponentVisitor](./src/builtin/CircomMainComponentVisitor.ts)
+- [CircomExpressionVisitor](./src/builtin/CircomExpressionVisitor.ts)
+
+## Known limitations
+
+1. Function calls inside the main component declaration or expressions are not supported.
+2. Currently, all 'simple' expressions are evaluated as-is, without accounting for the module.