simple-graph-query 2.8.1 → 3.0.0

package/README.md

@@ -6,6 +6,91 @@ A TypeScript library for evaluating relational + some more expressions with a br
 
 MIT
 
+## Strings
+
+Strings are written as double-quoted literals:
+
+```
+{y : Color | @:y = "Black"}
+```
+
+A literal always denotes a string, whatever the instance happens to contain. It
+may hold any characters — spaces, punctuation, reserved keywords — and supports
+the escapes `\"`, `\\`, `\n`, `\t`, `\r`, and `\0`; any other escaped character
+stands for itself.
+
+```
+"dark blue"     "#FF0000"     "2 of clubs"     "set"     "say \"hi\""
+```
+
+There is no implicit conversion: `"12" = 12` and `"true" = true` are both false.
+Use `@num:` / `@bool:` to convert explicitly.
+
+### Embedding in YAML
+
+`@` is a reserved indicator in YAML, so an expression beginning with `@:` cannot
+be a plain scalar — it has to be quoted whether or not it contains a string
+literal. Single-quoted and block scalars pass `"` through untouched and are the
+recommended styles:
+
+```yaml
+selector: '@:y = "Black"'
+
+selector: |-
+  @:y = "Black"
+```
+
+A double-quoted YAML scalar also works, but requires escaping: `"@:y = \"Black\""`.
+
+### Prior to 3.0
+
+Any identifier that failed to resolve was silently reinterpreted as a string, so
+`@:y = Black` worked only as long as nothing in the instance was named `Black`.
+Adding a sig by that name silently changed what the query meant, labels
+containing spaces or punctuation were inexpressible, and typos evaluated to
+themselves instead of being reported. Bare names are no longer strings; quote
+them.
+
+## Unresolved names
+
+A name that matches nothing in the instance evaluates to the **empty relation**
+and raises a diagnostic. It is not an error:
+
+```ts
+const { value, diagnostics } = evaluator.evaluateExpressionWithDiagnostics("Playr");
+// value       -> []
+// diagnostics -> [{
+//   kind: "unresolved-name",
+//   severity: "warning",
+//   name: "Playr",
+//   suggestion: "Player",
+//   message: "'Playr' does not name a type, relation, or atom in this instance; ..."
+// }]
+```
+
+An instance carries only *populated* types and relations, so a sig with no atoms
+is absent from it entirely — and a sig can empty out between frames of one
+trace. A missing name is therefore indistinguishable from a typo at evaluation
+time, which is why this is a warning for the consumer to surface rather than an
+error. `evaluateExpression` is unchanged and returns the value alone.
+
+Note that empty means predicates pass vacuously: `no Playr` is `true`. This is
+correct for an empty set, and the diagnostic is the only thing distinguishing it
+from a real result — so consumers should show these warnings, not drop them.
+
+### Static analysis
+
+`analyzeForgeExpression(expr, schema)` reports the same names in
+`unresolvedNames`, alongside (not instead of) its status. Given a *schema* it
+is conclusive, because a schema declares every entity whether populated or not:
+
+```ts
+analyzeForgeExpression("none & Playr", schema);
+// { status: "empty", reason: "...", unresolvedNames: ["Playr"] }
+```
+
+Without a schema the field is omitted — there is nothing to check names against.
+
 ## Selector synthesis overview
 
 The selector synthesizer infers a relational expression that returns exactly the atoms supplied in a set of training examples (pairs of `Set<IAtom>` and `IDataInstance`). The current implementation uses a bounded, enumerative search over a compact expression grammar (identifiers, unions/intersections/differences, joins, and transitive closure) that mirrors a lightweight Alloy fragment. The search works breadth-first by depth so that the first solution found is the simplest expression within the bound, and it only explores identifiers shared by every example plus Alloy built-ins like `univ` and `iden`.

package/dist/ForgeExprEvaluator.d.ts

@@ -7,6 +7,30 @@ 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 non-fatal condition noticed while evaluating an expression.
+ *
+ * Diagnostics never change the value of an expression — they are advisory, and
+ * consumers are expected to surface them to whoever wrote the query. Severity
+ * is always `"warning"`: the evaluator sees a single instance, not a schema, so
+ * it is not in a position to declare an unresolved name an error.
+ */
+export interface Diagnostic {
+    kind: "unresolved-name";
+    severity: "warning";
+    /** The name that could not be resolved. */
+    name: string;
+    /** Human-readable message suitable for showing to a query author. */
+    message: string;
+    /** Closest name in the instance, when one is close enough to be worth offering. */
+    suggestion?: string;
+}
+/**
+ * Strip the surrounding double quotes from a STRING_TOK and resolve its escape
+ * sequences. The lexer rule is `'"' (~["\\] | '\\' .)* '"'`, so a backslash
+ * always consumes exactly one following character.
+ */
+export declare function unquoteStringLiteral(text: string): string;
 /**
  * A recursive evaluator for Forge expressions.
  * This visitor walks the parse tree and prints the type of operation encountered.
@@ -19,7 +43,24 @@ export declare class ForgeExprEvaluator extends AbstractParseTreeVisitor<EvalRes
     private instanceData;
     private relationCache;
     private relationIndexCache;
+    private diagnostics;
     constructor(datum: IDataInstance);
+    /** Diagnostics recorded since the last `resetDiagnostics()`. */
+    getDiagnostics(): Diagnostic[];
+    /** Clear diagnostics. Callers that reuse an evaluator must call this per evaluation. */
+    resetDiagnostics(): void;
+    /**
+     * Record a name that could not be resolved against this instance.
+     *
+     * This is deliberately a warning rather than an error. The instance format
+     * carries only populated types and relations, so a sig with no atoms in this
+     * instance is indistinguishable from a typo — and a sig can empty out between
+     * frames of the same trace. Failing hard would break working selectors at
+     * exactly the frames where a set happens to be empty.
+     */
+    private reportUnresolvedName;
+    /** Closest name in this instance within a small edit distance, if any. */
+    private suggestName;
     private buildRelationCache;
     private updateFreeVariables;
     private constructFreeVariableKey;

package/dist/ForgeExprStaticAnalyzer.d.ts

@@ -21,7 +21,19 @@ type Abstract = {
 } | {
     kind: "unknown";
 };
-export type StaticAnalysis = {
+/**
+ * Names the expression references that the schema does not declare.
+ *
+ * This is reported alongside — not instead of — the status, because an
+ * expression can both name something undeclared and be provably empty. It is
+ * populated only when a schema is supplied: without one there is nothing to
+ * check a name against.
+ *
+ * Unlike the evaluator's `unresolved-name` diagnostic, this IS conclusive. A
+ * schema declares every entity whether or not it is populated, so a name absent
+ * from the schema cannot be explained away as a sig that happens to be empty.
+ */
+export type StaticAnalysis = ({
     status: "unsat";
     reason: string;
 } | {
@@ -35,10 +47,17 @@ export type StaticAnalysis = {
     reason: string;
 } | {
     status: "unknown";
+}) & {
+    unresolvedNames?: string[];
 };
 export declare class ForgeExprStaticAnalyzer extends AbstractParseTreeVisitor<Abstract> implements ForgeVisitor<Abstract> {
     private readonly schema?;
+    private readonly boundScopes;
+    private readonly unresolved;
     constructor(schema?: IForgeSchema);
+    private isBound;
+    /** Run `body` with `names` treated as bound. */
+    private withBoundScope;
     private collectNamesFromList;
     private collectBoundNames;
     private illTypedIfBindsReservedName;
@@ -67,5 +86,10 @@ export declare class ForgeExprStaticAnalyzer extends AbstractParseTreeVisitor<Ab
     visitExpr17(ctx: Expr17Context): Abstract;
     visitExpr18(ctx: Expr18Context): Abstract;
     visitName(ctx: NameContext): Abstract;
+    /** Walk the whole tree, recording every name the schema does not declare. */
+    private collectUnresolvedNames;
+    /** The binder parts of a quantifier or set comprehension, if this node is one. */
+    private asBinder;
+    private recordIfUnresolved;
 }
 export {};

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

@@ -7,7 +7,7 @@ export declare class ForgeLexer extends Lexer {
     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 STRING_TOK = 5;
     static readonly VAR_TOK = 6;
     static readonly ABSTRACT_TOK = 7;
     static readonly SIG_TOK = 8;

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

@@ -13,7 +13,7 @@ export declare class ForgeParser extends Parser {
     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 STRING_TOK = 5;
     static readonly VAR_TOK = 6;
     static readonly ABSTRACT_TOK = 7;
     static readonly SIG_TOK = 8;
@@ -385,7 +385,7 @@ export declare class ImportDeclContext extends ParserRuleContext {
     RIGHT_SQUARE_TOK(): TerminalNode | undefined;
     AS_TOK(): TerminalNode | undefined;
     name(): NameContext | undefined;
-    FILE_PATH_TOK(): TerminalNode | undefined;
+    STRING_TOK(): TerminalNode | undefined;
     constructor(parent: ParserRuleContext | undefined, invokingState: number);
     get ruleIndex(): number;
     enterRule(listener: ForgeListener): void;
@@ -651,6 +651,7 @@ export declare class ConstContext extends ParserRuleContext {
     IDEN_TOK(): TerminalNode | undefined;
     number(): NumberContext | undefined;
     MINUS_TOK(): TerminalNode | undefined;
+    STRING_TOK(): TerminalNode | undefined;
     constructor(parent: ParserRuleContext | undefined, invokingState: number);
     get ruleIndex(): number;
     enterRule(listener: ForgeListener): void;
@@ -846,7 +847,7 @@ export declare class OptionDeclContext extends ParserRuleContext {
     OPTION_TOK(): TerminalNode;
     qualName(): QualNameContext[];
     qualName(i: number): QualNameContext;
-    FILE_PATH_TOK(): TerminalNode | undefined;
+    STRING_TOK(): TerminalNode | undefined;
     number(): NumberContext | undefined;
     MINUS_TOK(): TerminalNode | undefined;
     constructor(parent: ParserRuleContext | undefined, invokingState: number);

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { ForgeListenerImpl } from './forge-antlr/ForgeListenerImpl';
 import { ParseTreeWalker } from 'antlr4ts/tree/ParseTreeWalker';
-import { EvalResult } from './ForgeExprEvaluator';
+import { Diagnostic, EvalResult } from './ForgeExprEvaluator';
 import { ForgeExprStaticAnalyzer, StaticAnalysis } from './ForgeExprStaticAnalyzer';
 import { IDataInstance, IForgeSchema } from './types';
 export type ErrorResult = {
@@ -44,6 +44,7 @@ export declare class SimpleGraphQueryEvaluator {
     private parseTreeCache;
     private cachedEvaluator;
     private cachedEvaluatorDatum;
+    private lastDiagnostics;
     constructor(datum: IDataInstance);
     /**
      * Discard the cached inner evaluator (and its relation index /
@@ -56,6 +57,24 @@ export declare class SimpleGraphQueryEvaluator {
      */
     invalidate(): void;
     getExpressionParseTree(forgeExpr: string): import("./forge-antlr/ForgeParser").ParseExprContext;
+    /**
+     * Evaluate `forgeExpr` and return both its value and any diagnostics raised
+     * along the way.
+     *
+     * Diagnostics are advisory and never change the value — today the only kind
+     * is an unresolved name, which evaluates to the empty set. Consumers should
+     * surface them to whoever authored the query; see {@link Diagnostic}.
+     *
+     * Note that an unresolved name is a warning rather than an error on purpose.
+     * An instance carries only populated types and relations, so a sig that is
+     * empty here looks exactly like a typo, and a sig can empty out between
+     * frames of one trace. Deciding which it is needs context this library does
+     * not have.
+     */
+    evaluateExpressionWithDiagnostics(forgeExpr: string): {
+        value: EvaluationResult;
+        diagnostics: Diagnostic[];
+    };
     evaluateExpression(forgeExpr: string): EvaluationResult;
 }
 /**
@@ -75,5 +94,6 @@ export declare class SimpleGraphQueryEvaluator {
 export declare function analyzeForgeExpression(forgeExpr: string, schema?: IForgeSchema): StaticAnalysis;
 export { ForgeExprStaticAnalyzer, StaticAnalysis };
 export type { IForgeSchema };
+export type { Diagnostic };
 export { synthesizeSelector, synthesizeBinaryRelation, synthesizeBinaryRelationWithWhy, synthesizeSelectorWithWhy, AtomSelectionExample, BinaryRelationExample, SelectorSynthesisError, SynthesisWhy, SynthesisWhyExample, WhyNode, } from './SelectorSynthesizer';
 export { getIdentifierName, quoteIfReserved, FORGE_RESERVED_KEYWORDS, } from './forge-antlr/utils';