doc: lint error-diagnostics

Author: mig8447

doc/error-diagnostics.md

@@ -0,0 +1,110 @@
+# Error Diagnostics <!-- omit in toc -->
+
+## Table of Contents <!-- omit in toc -->
+
+- [API](#api)
+- [Error Types](#error-types)
+    - [Misaligned Attributes](#misaligned-attributes)
+    - [Invalid Object references](#invalid-object-references)
+        - [Invalid Table reference in a View](#invalid-table-reference-in-a-view)
+        - [Invalid foreign key](#invalid-foreign-key)
+        - [Duplicate ID](#duplicate-id)
+        - [Missconstructed column type](#missconstructed-column-type)
+
+## API
+
+Error diagnostics procedure is called like this
+
+```js
+let output = ddl.errorMsgs(`dept
+   col1
+ "is this table or misaligned column?"`);
+```
+
+It returns an array of the Error objects
+
+```js
+function SyntaxError( message, from, to, severity ) {
+    this.from = from;
+    this.to = to;
+    if( to == null )
+        this.to = new Offset(from.line, from.depth+1);
+    this.message = message;
+    this.severity = severity;   // warning or error
+    if( severity == null )
+        this.severity = 'error';
+}
+```
+
+where error message offsets are structured as follows
+
+```js
+function Offset( line, depth ) {
+    this.line = line;     // 0-based
+    this.depth = depth;   // 0-based
+}
+```
+
+## Error Types
+
+### Misaligned Attributes
+
+Indentation refers to the spaces at the beginning of a code line. Where in most
+of the other other programming languages the indentation in code is for
+readability only, Quick SQL uses indentation to define Quick SQL tree/forest
+structure. Parent-child relationship in this tree is interpreted as ether table
+containing list of columns, or as 2 tables related with referential integrity
+key constraint.
+
+Inconsistent indentation is detected, with the error message designed to resolve
+any confusion.
+
+### Invalid Object references
+
+#### Invalid Table reference in a View
+
+Example:
+
+```quicksql
+dept
+    name
+
+view customer_view customer
+```
+
+Here the `customer` table (or view) is missing.
+
+#### Invalid foreign key
+
+Example:
+
+```quicksql
+department
+    name
+employee
+    dept /fk dept
+```
+
+Here the `dept` table (or view) is missing.
+
+#### Duplicate ID
+
+Since identity columns are generated by default, specifying them explicitly like
+this
+
+```quicksql
+dept
+    id
+```
+
+would be diagnosed an error.
+
+#### Missconstructed column type
+
+Quick SQL also recognizes syntactically invalid column types like this
+
+```quicksql
+dept
+    name vc-200
+    name vc0
+```