simple-graph-query 1.0.0 → 1.1.1

package/README.md

@@ -1,73 +1,118 @@
-# simple-graph-query
+# Forge Expression Evaluator
 
-**simple-graph-query** is a lightweight query engine for navigating and extracting tuples from finite graphs using a relational logic inspired by Alloy. It runs entirely client-side and supports a small, composable query language based on set comprehension and relational navigation.
+A TypeScript library for evaluating Forge language expressions with a browser-compatible UMD bundle.
 
-## What It Does
+## Installation
 
-This tool lets you run queries like:
+```bash
+npm install forge-expr-evaluator
+```
+
+## Usage
 
+### Browser (UMD Bundle)
+```html
+<script src="node_modules/forge-expr-evaluator/dist/forge-expr-evaluator.bundle.js"></script>
+<script>
+  const evaluator = new ForgeExprEvaluator.ForgeExprEvaluatorUtil(datum, sourceCode);
+  const result = evaluator.evaluateExpression("some Board", 0);
+  console.log(result);
+</script>
 ```
-{ x, y : Person | y in x.friend* }
-{ x, y : Person | x.friend = y }
-{ x : Person | x in x.friend* }
+
+### Node.js
+```javascript
+const { ForgeExprEvaluatorUtil } = require('forge-expr-evaluator');
+
+const evaluator = new ForgeExprEvaluatorUtil(datum, sourceCode);
+const result = evaluator.evaluateExpression("some Board", 0);
+console.log(result);
 ```
 
-over JSON-encoded graphs like:
-
-```json
-{
-  "nodes": [
-    { "id": "a", "type": "Person" },
-    { "id": "b", "type": "Person" },
-    { "id": "c", "type": "Person" }
-  ],
-  "edges": [
-    { "from": "a", "to": "b", "label": "friend" },
-    { "from": "b", "to": "c", "label": "friend" }
-  ]
-}
+### TypeScript
+```typescript
+import { ForgeExprEvaluatorUtil, DatumParsed } from 'forge-expr-evaluator';
+
+const datum: DatumParsed = {
+  parsed: {
+    instances: [/* your data */],
+    bitwidth: 4
+  },
+  data: "<alloy>...</alloy>"
+};
+
+const sourceCode = `
+  sig Board { ... }
+  // your Forge signatures and predicates
+`;
+
+const evaluator = new ForgeExprEvaluatorUtil(datum, sourceCode);
+const result = evaluator.evaluateExpression("some Board", 0);
 ```
 
-And returns results like:
+## API
+
+### `ForgeExprEvaluatorUtil`
+
+#### Constructor
+```typescript
+new ForgeExprEvaluatorUtil(datum: DatumParsed, sourceCode: string)
+```
 
-```json
-[
-  ["a", "b"],
-  ["a", "c"],
-  ["b", "c"]
-]
+#### Methods
+```typescript
+evaluateExpression(expression: string, instanceIndex?: number): EvaluationResult
 ```
 
-## What Logic Does It Support
+### Types
+- `DatumParsed`: Data structure containing Forge model instances
+- `EvaluationResult`: Result of expression evaluation (value or error)
+- `EvalResult`: Successful evaluation result (string | number | boolean | Tuple[])
 
-`simple-graph-query` evaluates first-order relational queries over finite graph structures. Specifically:
+## Features
 
-- Typed variables: `{ x, y : Person | ... }`
-- Set comprehension: `{ tuple | condition }`
-- Relational navigation: `x.friend`, `x.friend.friend`
-- Equality: `x.friend = y`
-- Membership: `y in x.friend`
-- Transitive closure: `x.friend*`
+- ✅ Browser-compatible UMD bundle (~688 KiB)
+- ✅ TypeScript support with full type definitions
+- ✅ Evaluates Forge expressions against model data
+- ✅ No external dependencies in the bundle
+- ✅ Works with Sterling/Alloy data formats
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the bundle
+npm run build
+
+# Run tests
+npm test
+
+# Serve demo locally
+npm run serve
+```
 
-This is a subset of Alloy-style relational logic, evaluated over a fixed graph structure, with results returned as sets of tuples.
+## License
 
-## Getting Started
+MIT
 
-1. Clone or unzip the repository.
-2. Open `public/index.html` in your browser.
-3. Paste a query like `{ x, y : Person | y in x.friend* }`.
-4. Click Run and view the results.
+## Contributing
 
-## Project Structure
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if needed
+5. Submit a pull request
 
-- `src/` – parser, evaluator, and AST
-- `examples/graph.json` – sample graph data
-- `public/index.html` – minimal UI to run queries
-- `runQuery(graph, query)` – main API
+## Credits
 
-## TODO
+_Note_: The evaluator makes use of a Forge parser built using ANTLR; this is largely taken from
+the [parser developed by Siddhartha Prasad](https://github.com/sidprasad/forge-antlr/)
+with some minor modifications to the grammar.
 
-- Support for `and`, `!=`, `no`, `some`
-- Regex-style navigation (`friend|coworker`)
-- Type checking and improved error handling
+## Related
 
+- [Forge Language](https://forge.binghamton.edu/)
+- [Alloy](https://alloytools.org/)
+- [Sterling Visualizer](https://sterling-js.github.io/)

package/dist/ForgeExprEvaluator.d.ts

@@ -0,0 +1,58 @@
+import { AbstractParseTreeVisitor } from "antlr4ts/tree/AbstractParseTreeVisitor";
+import { ForgeVisitor } from "./forge-antlr/ForgeVisitor";
+import { ExprContext, Expr1Context, Expr1_5Context, Expr2Context, Expr3Context, Expr4Context, Expr4_5Context, Expr5Context, Expr6Context, Expr7Context, Expr8Context, Expr9Context, Expr10Context, Expr11Context, Expr12Context, Expr13Context, Expr14Context, Expr15Context, Expr16Context, Expr17Context, Expr18Context, ExprListContext, NameContext, PredDeclContext, BlockContext, QualNameContext, QuantDeclListContext, NameListContext, QuantDeclContext } from "./forge-antlr/ForgeParser";
+import { IDataInstance } from "./types";
+export type SingleValue = string | number | boolean;
+export type Tuple = SingleValue[];
+export type EvalResult = SingleValue | Tuple[];
+export declare function areTupleArraysEqual(a: Tuple[], b: Tuple[]): boolean;
+export declare const SUPPORTED_BUILTINS: string[];
+/**
+ * A recursive evaluator for Forge expressions.
+ * This visitor walks the parse tree and prints the type of operation encountered.
+ */
+export declare class ForgeExprEvaluator extends AbstractParseTreeVisitor<EvalResult> implements ForgeVisitor<EvalResult> {
+    private environmentStack;
+    private freeVariableFinder;
+    private freeVariables;
+    private cachedResults;
+    private instanceData;
+    constructor(datum: IDataInstance);
+    private updateFreeVariables;
+    private constructFreeVariableKey;
+    private cacheResult;
+    private getIden;
+    protected aggregateResult(aggregate: EvalResult, nextResult: EvalResult): EvalResult;
+    protected defaultResult(): EvalResult;
+    visitPredDecl(ctx: PredDeclContext): EvalResult;
+    visitBlock(ctx: BlockContext): EvalResult;
+    visitExpr(ctx: ExprContext): EvalResult;
+    visitExpr1(ctx: Expr1Context): EvalResult;
+    visitExpr1_5(ctx: Expr1_5Context): EvalResult;
+    visitExpr2(ctx: Expr2Context): EvalResult;
+    visitExpr3(ctx: Expr3Context): EvalResult;
+    visitExpr4(ctx: Expr4Context): EvalResult;
+    visitExpr4_5(ctx: Expr4_5Context): EvalResult;
+    visitExpr5(ctx: Expr5Context): EvalResult;
+    visitExpr6(ctx: Expr6Context): EvalResult;
+    visitExpr7(ctx: Expr7Context): EvalResult;
+    visitExpr8(ctx: Expr8Context): EvalResult;
+    visitExpr9(ctx: Expr9Context): EvalResult;
+    visitExpr10(ctx: Expr10Context): EvalResult;
+    visitExpr11(ctx: Expr11Context): EvalResult;
+    visitExpr12(ctx: Expr12Context): EvalResult;
+    visitExpr13(ctx: Expr13Context): EvalResult;
+    visitExpr14(ctx: Expr14Context): EvalResult;
+    visitExpr15(ctx: Expr15Context): EvalResult;
+    visitExpr16(ctx: Expr16Context): EvalResult;
+    visitExpr17(ctx: Expr17Context): EvalResult;
+    getNameListValues(ctx: NameListContext): string[];
+    getQuantDeclValues(ctx: QuantDeclContext): Record<string, Tuple[]>;
+    getQuantDeclListValues(ctx: QuantDeclListContext): Record<string, Tuple[]>;
+    visitExpr18(ctx: Expr18Context): EvalResult;
+    visitExprList(ctx: ExprListContext): EvalResult;
+    visitName(ctx: NameContext): EvalResult;
+    visitQualName(ctx: QualNameContext): EvalResult;
+    private evaluateBinaryOperation;
+    private evaluateUnaryOperation;
+}

package/dist/ForgeExprFreeVariableFinder.d.ts

@@ -0,0 +1,45 @@
+import { AbstractParseTreeVisitor } from "antlr4ts/tree/AbstractParseTreeVisitor";
+import { ParseTree } from "antlr4ts/tree/ParseTree";
+import { ForgeVisitor } from "./forge-antlr/ForgeVisitor";
+import { IDataInstance } from "./types";
+import { BlockContext, Expr10Context, Expr11Context, Expr12Context, Expr13Context, Expr14Context, Expr15Context, Expr16Context, Expr17Context, Expr18Context, Expr1Context, Expr1_5Context, Expr2Context, Expr3Context, Expr4Context, Expr4_5Context, Expr5Context, Expr6Context, Expr7Context, Expr8Context, Expr9Context, ExprContext, ExprListContext, NameContext, NameListContext, PredDeclContext, QuantDeclContext, QuantDeclListContext } from "./forge-antlr/ForgeParser";
+export type FreeVariables = Map<ParseTree, Set<string>>;
+/**
+ * A recursive visitor to find all the free variables referenced in a forge
+ * expression.
+ */
+export declare class ForgeExprFreeVariableFinder extends AbstractParseTreeVisitor<FreeVariables> implements ForgeVisitor<FreeVariables> {
+    private instanceData;
+    constructor(instanceData: IDataInstance);
+    protected aggregateResult(aggregate: FreeVariables, nextResult: FreeVariables): FreeVariables;
+    private addCtxToFreeVariableMap;
+    protected defaultResult(): FreeVariables;
+    visitPredDecl(ctx: PredDeclContext): FreeVariables;
+    visitBlock(ctx: BlockContext): FreeVariables;
+    getNameListValues(ctx: NameListContext): Set<string>;
+    getQuantDeclVarNames(ctx: QuantDeclContext): Set<string>;
+    getQuantDeclListVarNames(ctx: QuantDeclListContext): Set<string>;
+    visitExpr(ctx: ExprContext): FreeVariables;
+    visitExpr1(ctx: Expr1Context): FreeVariables;
+    visitExpr1_5(ctx: Expr1_5Context): FreeVariables;
+    visitExpr2(ctx: Expr2Context): FreeVariables;
+    visitExpr3(ctx: Expr3Context): FreeVariables;
+    visitExpr4(ctx: Expr4Context): FreeVariables;
+    visitExpr4_5(ctx: Expr4_5Context): FreeVariables;
+    visitExpr5(ctx: Expr5Context): FreeVariables;
+    visitExpr6(ctx: Expr6Context): FreeVariables;
+    visitExpr7(ctx: Expr7Context): FreeVariables;
+    visitExpr8(ctx: Expr8Context): FreeVariables;
+    visitExpr9(ctx: Expr9Context): FreeVariables;
+    visitExpr10(ctx: Expr10Context): FreeVariables;
+    visitExpr11(ctx: Expr11Context): FreeVariables;
+    visitExpr12(ctx: Expr12Context): FreeVariables;
+    visitExpr13(ctx: Expr13Context): FreeVariables;
+    visitExpr14(ctx: Expr14Context): FreeVariables;
+    visitExpr15(ctx: Expr15Context): FreeVariables;
+    visitExpr16(ctx: Expr16Context): FreeVariables;
+    visitExpr17(ctx: Expr17Context): FreeVariables;
+    visitExpr18(ctx: Expr18Context): FreeVariables;
+    visitExprList(ctx: ExprListContext): FreeVariables;
+    visitName(ctx: NameContext): FreeVariables;
+}

package/dist/errorListener.d.ts

@@ -0,0 +1,4 @@
+import { ANTLRErrorListener, Recognizer, RecognitionException } from "antlr4ts";
+export declare class ParseErrorListener implements ANTLRErrorListener<any> {
+    syntaxError(recognizer: Recognizer<any, any>, offendingSymbol: any, line: number, charPositionInLine: number, msg: string, e: RecognitionException | undefined): void;
+}

package/dist/forge-antlr/ForgeLexer.d.ts

@@ -0,0 +1,134 @@
+import { ATN } from "antlr4ts/atn/ATN";
+import { CharStream } from "antlr4ts/CharStream";
+import { Lexer } from "antlr4ts/Lexer";
+import { Vocabulary } from "antlr4ts/Vocabulary";
+export declare class ForgeLexer extends Lexer {
+    static readonly OPEN_TOK = 1;
+    static readonly LEFT_SQUARE_TOK = 2;
+    static readonly RIGHT_SQUARE_TOK = 3;
+    static readonly AS_TOK = 4;
+    static readonly FILE_PATH_TOK = 5;
+    static readonly VAR_TOK = 6;
+    static readonly ABSTRACT_TOK = 7;
+    static readonly SIG_TOK = 8;
+    static readonly LEFT_CURLY_TOK = 9;
+    static readonly RIGHT_CURLY_TOK = 10;
+    static readonly EXTENDS_TOK = 11;
+    static readonly IN_TOK = 12;
+    static readonly PLUS_TOK = 13;
+    static readonly LONE_TOK = 14;
+    static readonly SOME_TOK = 15;
+    static readonly ONE_TOK = 16;
+    static readonly TWO_TOK = 17;
+    static readonly SET_TOK = 18;
+    static readonly FUNC_TOK = 19;
+    static readonly PFUNC_TOK = 20;
+    static readonly DISJ_TOK = 21;
+    static readonly COLON_TOK = 22;
+    static readonly WHEAT_TOK = 23;
+    static readonly PRED_TOK = 24;
+    static readonly DOT_TOK = 25;
+    static readonly FUN_TOK = 26;
+    static readonly LEFT_PAREN_TOK = 27;
+    static readonly RIGHT_PAREN_TOK = 28;
+    static readonly ASSERT_TOK = 29;
+    static readonly RUN_TOK = 30;
+    static readonly CHECK_TOK = 31;
+    static readonly FOR_TOK = 32;
+    static readonly BUT_TOK = 33;
+    static readonly EXACTLY_TOK = 34;
+    static readonly NONE_TOK = 35;
+    static readonly UNIV_TOK = 36;
+    static readonly IDEN_TOK = 37;
+    static readonly MINUS_TOK = 38;
+    static readonly IS_TOK = 39;
+    static readonly SAT_TOK = 40;
+    static readonly UNSAT_TOK = 41;
+    static readonly THEOREM_TOK = 42;
+    static readonly FORGE_ERROR_TOK = 43;
+    static readonly CHECKED_TOK = 44;
+    static readonly TEST_TOK = 45;
+    static readonly EXPECT_TOK = 46;
+    static readonly SUITE_TOK = 47;
+    static readonly BAR_TOK = 48;
+    static readonly ALL_TOK = 49;
+    static readonly SUFFICIENT_TOK = 50;
+    static readonly NECESSARY_TOK = 51;
+    static readonly CONSISTENT_TOK = 52;
+    static readonly INCONSISTENT_TOK = 53;
+    static readonly WITH_TOK = 54;
+    static readonly LET_TOK = 55;
+    static readonly BIND_TOK = 56;
+    static readonly OR_TOK = 57;
+    static readonly XOR_TOK = 58;
+    static readonly IFF_TOK = 59;
+    static readonly IMP_TOK = 60;
+    static readonly ELSE_TOK = 61;
+    static readonly AND_TOK = 62;
+    static readonly UNTIL_TOK = 63;
+    static readonly RELEASE_TOK = 64;
+    static readonly SINCE_TOK = 65;
+    static readonly TRIGGERED_TOK = 66;
+    static readonly NEG_TOK = 67;
+    static readonly ALWAYS_TOK = 68;
+    static readonly EVENTUALLY_TOK = 69;
+    static readonly AFTER_TOK = 70;
+    static readonly BEFORE_TOK = 71;
+    static readonly ONCE_TOK = 72;
+    static readonly HISTORICALLY_TOK = 73;
+    static readonly CARD_TOK = 74;
+    static readonly PPLUS_TOK = 75;
+    static readonly AMP_TOK = 76;
+    static readonly SUBT_TOK = 77;
+    static readonly SUPT_TOK = 78;
+    static readonly PRIME_TOK = 79;
+    static readonly TILDE_TOK = 80;
+    static readonly EXP_TOK = 81;
+    static readonly STAR_TOK = 82;
+    static readonly AT_TOK = 83;
+    static readonly BACKQUOTE_TOK = 84;
+    static readonly THIS_TOK = 85;
+    static readonly SEXPR_TOK = 86;
+    static readonly INST_TOK = 87;
+    static readonly EVAL_TOK = 88;
+    static readonly EXAMPLE_TOK = 89;
+    static readonly ARROW_TOK = 90;
+    static readonly EQ_TOK = 91;
+    static readonly LT_TOK = 92;
+    static readonly GT_TOK = 93;
+    static readonly LEQ_TOK = 94;
+    static readonly GEQ_TOK = 95;
+    static readonly NI_TOK = 96;
+    static readonly NO_TOK = 97;
+    static readonly SUM_TOK = 98;
+    static readonly INT_TOK = 99;
+    static readonly OPTION_TOK = 100;
+    static readonly COMMA_TOK = 101;
+    static readonly SLASH_TOK = 102;
+    static readonly NUM_CONST_TOK = 103;
+    static readonly IDENTIFIER_TOK = 104;
+    static readonly WS = 105;
+    static readonly CCOMMENT = 106;
+    static readonly COMMENT = 107;
+    static readonly MULTCOMMENT = 108;
+    static readonly LANG_DECL = 109;
+    static readonly channelNames: string[];
+    static readonly modeNames: string[];
+    static readonly ruleNames: string[];
+    private static readonly _LITERAL_NAMES;
+    private static readonly _SYMBOLIC_NAMES;
+    static readonly VOCABULARY: Vocabulary;
+    get vocabulary(): Vocabulary;
+    constructor(input: CharStream);
+    get grammarFileName(): string;
+    get ruleNames(): string[];
+    get serializedATN(): string;
+    get channelNames(): string[];
+    get modeNames(): string[];
+    private static readonly _serializedATNSegments;
+    private static readonly _serializedATNSegment0;
+    private static readonly _serializedATNSegment1;
+    static readonly _serializedATN: string;
+    static __ATN: ATN;
+    static get _ATN(): ATN;
+}