simple-graph-query 2.5.2 → 2.7.0

package/dist/ForgeExprEvaluator.d.ts

@@ -66,6 +66,7 @@ export declare class ForgeExprEvaluator extends AbstractParseTreeVisitor<EvalRes
     visitQualName(ctx: QualNameContext): EvalResult;
     private evaluateBinaryOperation;
     private evaluateUnaryOperation;
+    private evaluateSetOperation;
 }
 export declare class NameNotFoundError extends Error {
     constructor(message: string);

package/dist/ForgeExprStaticAnalyzer.d.ts

@@ -0,0 +1,71 @@
+import { AbstractParseTreeVisitor } from "antlr4ts/tree/AbstractParseTreeVisitor";
+import { ParseTree } from "antlr4ts/tree/ParseTree";
+import { ForgeVisitor } from "./forge-antlr/ForgeVisitor";
+import { Expr1Context, Expr1_5Context, Expr2Context, Expr3Context, Expr4Context, Expr5Context, Expr6Context, Expr7Context, Expr8Context, Expr9Context, Expr11Context, Expr12Context, Expr14Context, Expr15Context, Expr17Context, Expr18Context, ExprContext, NameContext, BlockContext } from "./forge-antlr/ForgeParser";
+import { IForgeSchema } from "./types";
+type Abstract = {
+    kind: "bool";
+    value: boolean;
+} | {
+    kind: "num";
+    value: number;
+} | {
+    kind: "empty";
+} | {
+    kind: "typed";
+    arity: number;
+    columnTypes?: readonly string[];
+} | {
+    kind: "ill-typed";
+    reason: string;
+} | {
+    kind: "unknown";
+};
+export type StaticAnalysis = {
+    status: "unsat";
+    reason: string;
+} | {
+    status: "tautology";
+    reason: string;
+} | {
+    status: "empty";
+    reason: string;
+} | {
+    status: "ill-typed";
+    reason: string;
+} | {
+    status: "unknown";
+};
+export declare class ForgeExprStaticAnalyzer extends AbstractParseTreeVisitor<Abstract> implements ForgeVisitor<Abstract> {
+    private readonly schema?;
+    constructor(schema?: IForgeSchema);
+    private collectNamesFromList;
+    private collectBoundNames;
+    private illTypedIfBindsReservedName;
+    analyze(ctx: ParseTree): StaticAnalysis;
+    private static arityOf;
+    protected defaultResult(): Abstract;
+    private static bailIfIllTyped;
+    protected aggregateResult(aggregate: Abstract, nextResult: Abstract): Abstract;
+    visitExpr(ctx: ExprContext): Abstract;
+    private foldQuantifier;
+    visitBlock(ctx: BlockContext): Abstract;
+    visitExpr1(ctx: Expr1Context): Abstract;
+    visitExpr1_5(ctx: Expr1_5Context): Abstract;
+    visitExpr2(ctx: Expr2Context): Abstract;
+    visitExpr3(ctx: Expr3Context): Abstract;
+    visitExpr4(ctx: Expr4Context): Abstract;
+    visitExpr5(ctx: Expr5Context): Abstract;
+    visitExpr6(ctx: Expr6Context): Abstract;
+    visitExpr7(ctx: Expr7Context): Abstract;
+    visitExpr8(ctx: Expr8Context): Abstract;
+    visitExpr9(ctx: Expr9Context): Abstract;
+    visitExpr12(ctx: Expr12Context): Abstract;
+    visitExpr11(ctx: Expr11Context): Abstract;
+    visitExpr14(ctx: Expr14Context): Abstract;
+    visitExpr15(ctx: Expr15Context): Abstract;
+    visitExpr17(ctx: Expr17Context): Abstract;
+    visitExpr18(ctx: Expr18Context): Abstract;
+    visitName(ctx: NameContext): Abstract;
+}
+export {};

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

@@ -110,12 +110,13 @@ export declare class ForgeLexer extends Lexer {
     static readonly COMMA_TOK = 105;
     static readonly SLASH_TOK = 106;
     static readonly NUM_CONST_TOK = 107;
-    static readonly IDENTIFIER_TOK = 108;
-    static readonly WS = 109;
-    static readonly CCOMMENT = 110;
-    static readonly COMMENT = 111;
-    static readonly MULTCOMMENT = 112;
-    static readonly LANG_DECL = 113;
+    static readonly QUOTED_IDENTIFIER_TOK = 108;
+    static readonly IDENTIFIER_TOK = 109;
+    static readonly WS = 110;
+    static readonly CCOMMENT = 111;
+    static readonly COMMENT = 112;
+    static readonly MULTCOMMENT = 113;
+    static readonly LANG_DECL = 114;
     static readonly channelNames: string[];
     static readonly modeNames: string[];
     static readonly ruleNames: string[];

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

@@ -116,12 +116,13 @@ export declare class ForgeParser extends Parser {
     static readonly COMMA_TOK = 105;
     static readonly SLASH_TOK = 106;
     static readonly NUM_CONST_TOK = 107;
-    static readonly IDENTIFIER_TOK = 108;
-    static readonly WS = 109;
-    static readonly CCOMMENT = 110;
-    static readonly COMMENT = 111;
-    static readonly MULTCOMMENT = 112;
-    static readonly LANG_DECL = 113;
+    static readonly QUOTED_IDENTIFIER_TOK = 108;
+    static readonly IDENTIFIER_TOK = 109;
+    static readonly WS = 110;
+    static readonly CCOMMENT = 111;
+    static readonly COMMENT = 112;
+    static readonly MULTCOMMENT = 113;
+    static readonly LANG_DECL = 114;
     static readonly RULE_predDecl = 0;
     static readonly RULE_parseExpr = 1;
     static readonly RULE_alloyModule = 2;
@@ -855,7 +856,8 @@ export declare class OptionDeclContext extends ParserRuleContext {
     accept<Result>(visitor: ForgeVisitor<Result>): Result;
 }
 export declare class NameContext extends ParserRuleContext {
-    IDENTIFIER_TOK(): TerminalNode;
+    IDENTIFIER_TOK(): TerminalNode | undefined;
+    QUOTED_IDENTIFIER_TOK(): TerminalNode | undefined;
     constructor(parent: ParserRuleContext | undefined, invokingState: number);
     get ruleIndex(): number;
     enterRule(listener: ForgeListener): void;

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

@@ -0,0 +1,28 @@
+import { NameContext } from './ForgeParser';
+/**
+ * Extracts the identifier string from a NameContext.
+ * Handles both regular identifiers and backtick-quoted identifiers (for reserved keywords).
+ *
+ * Examples:
+ *   - Regular: `myVar` -> "myVar"
+ *   - Quoted: `` `set` `` -> "set"
+ *   - Quoted with escape: `` `my\`name` `` -> "my`name"
+ *
+ * @param ctx The NameContext to extract the identifier from
+ * @returns The identifier string with backticks and escapes processed
+ */
+export declare function getIdentifierName(ctx: NameContext): string;
+/**
+ * Quotes an identifier if it conflicts with a reserved keyword.
+ * Use this when generating Forge expressions that might contain reserved words.
+ *
+ * @param identifier The identifier to potentially quote
+ * @param reservedKeywords Set of reserved keywords to check against
+ * @returns The identifier, quoted with backticks if necessary
+ */
+export declare function quoteIfReserved(identifier: string, reservedKeywords: Set<string>): string;
+/**
+ * Set of all reserved keywords in Forge.
+ * Use with quoteIfReserved() when generating Forge expressions.
+ */
+export declare const FORGE_RESERVED_KEYWORDS: Set<string>;

package/dist/index.d.ts

@@ -1,19 +1,79 @@
 import { ForgeListenerImpl } from './forge-antlr/ForgeListenerImpl';
 import { ParseTreeWalker } from 'antlr4ts/tree/ParseTreeWalker';
 import { EvalResult } from './ForgeExprEvaluator';
-import { IDataInstance } from './types';
+import { ForgeExprStaticAnalyzer, StaticAnalysis } from './ForgeExprStaticAnalyzer';
+import { IDataInstance, IForgeSchema } from './types';
 export type ErrorResult = {
     error: Error;
     stackTrace?: string;
 };
 export type EvaluationResult = EvalResult | ErrorResult;
+/**
+ * Evaluates Forge expressions against an `IDataInstance`.
+ *
+ * ## Caching contract (important for correctness)
+ *
+ * For performance, this class caches an inner evaluator (with its relation
+ * index and subexpression cache) across `evaluateExpression` calls. The
+ * cache is invalidated when the `datum` field is reassigned to a different
+ * reference, but **not** when the underlying `IDataInstance` is mutated in
+ * place (e.g. adding/removing atoms or tuples on the same object).
+ *
+ * If you mutate the underlying data in place, you **must** call
+ * {@link invalidate} (or reassign `datum` to a new object) before the next
+ * `evaluateExpression` call. Otherwise queries may return stale results.
+ *
+ * Recommended patterns:
+ *  - Treat `IDataInstance` as immutable; create a new instance on data
+ *    changes and construct a new `SimpleGraphQueryEvaluator` (or assign to
+ *    `.datum`).
+ *  - Or, if you mutate in place, call `invalidate()` after each mutation
+ *    batch.
+ */
 export declare class SimpleGraphQueryEvaluator {
+    /**
+     * The data instance evaluated against. Reassigning this field is a
+     * supported invalidation signal — the inner evaluator cache is rebuilt
+     * on the next `evaluateExpression` call. **In-place mutation of the
+     * existing object is NOT detected**; call {@link invalidate} in that
+     * case.
+     */
     datum: IDataInstance;
     forgeListener: ForgeListenerImpl;
     walker: ParseTreeWalker;
     private parseTreeCache;
+    private cachedEvaluator;
+    private cachedEvaluatorDatum;
     constructor(datum: IDataInstance);
+    /**
+     * Discard the cached inner evaluator (and its relation index /
+     * subexpression cache). Call this after mutating the underlying
+     * `IDataInstance` in place, so the next `evaluateExpression` sees the
+     * updated data.
+     *
+     * Cheap: just nulls a couple of references. The caches rebuild lazily
+     * on the next query.
+     */
+    invalidate(): void;
     getExpressionParseTree(forgeExpr: string): import("./forge-antlr/ForgeParser").ParseExprContext;
     evaluateExpression(forgeExpr: string): EvaluationResult;
 }
+/**
+ * Run a static analysis on a Forge expression.
+ *
+ * Returns `unsat` when the expression provably reduces to `false`, `empty`
+ * when it provably reduces to the empty set, `tautology` when it provably
+ * reduces to `true`, `ill-typed` for static type errors (e.g. arity
+ * mismatch), and `unknown` otherwise (including parse errors).
+ *
+ * When `schema` is provided, the analyzer also uses the type lattice and
+ * relation declarations to detect type-disjoint intersections, subtype
+ * tautologies in `in`, join column-type mismatches, and arity errors.
+ * Disjointness uses a closed-world rule (A ∩ B = ∅ iff no type in the
+ * lattice has both A and B in its lineage).
+ */
+export declare function analyzeForgeExpression(forgeExpr: string, schema?: IForgeSchema): StaticAnalysis;
+export { ForgeExprStaticAnalyzer, StaticAnalysis };
+export type { IForgeSchema };
 export { synthesizeSelector, synthesizeBinaryRelation, synthesizeBinaryRelationWithWhy, synthesizeSelectorWithWhy, AtomSelectionExample, BinaryRelationExample, SelectorSynthesisError, SynthesisWhy, SynthesisWhyExample, WhyNode, } from './SelectorSynthesizer';
+export { getIdentifierName, quoteIfReserved, FORGE_RESERVED_KEYWORDS, } from './forge-antlr/utils';