laranex-schema-viewer-ui 0.2.0 → 0.4.0

package/NOTICE

@@ -9,6 +9,17 @@ and orthogonal edge routing are adapted from Laranex Laravel Schema Viewer,
 ui/src/elk.ts, ui/src/layout.ts and ui/src/routing.ts, inspected at commit
 62b056a (https://github.com/laranex/laravel-schema-viewer).
 
+The icons (src/viewer/icons.tsx) and the brand mark (src/viewer/brand.ts),
+which is also the favicon and the documentation site's logo, are adapted from
+Laranex Laravel Schema Viewer, ui/src/App.tsx and ui/src/components/*.tsx,
+inspected at commit 62b056a: the same shapes, proportions and viewBoxes, drawn
+in the viewer's own theme colors. The icons Laravel has no counterpart for
+(select, details, changes, compare, migrations, behind, branch, circle) are
+drawn for this package in the same style. No third-party icon set is used.
+The line ends (crow's foot, bar, double bar and through arrow) are adapted from
+ui/src/components/LinkEdge.tsx at the same commit and drawn the same way in
+images (src/viewer/graph.ts END_SHAPES).
+
 The laranex-schema contract takes its structure and camelCase naming from
 Laravel Schema Viewer's serialized document (src/Schema/*.php) and its
 provenance-preserving rules from Python Schema Viewer's snapshot contract

package/README.md

@@ -16,10 +16,28 @@ import 'laranex-schema-viewer-ui/styles.css';
 
 ```js
 import { validateDocument, buildGraph, canonicalJson } from 'laranex-schema-viewer-ui/contract';
+import { dbml, mermaid, markdown, json } from 'laranex-schema-viewer-ui/export';
 ```
 
-Hosts without Node.js serve `node_modules/laranex-schema-viewer-ui/dist/viewer/` as static files with a
-`snapshot.json` beside `index.html`, or use `<laranex-schema-viewer src="snapshot.json">`.
+The viewer's Download dialog exports a connection as Mermaid, DBML, Markdown or a scoped JSON document, the diagram as
+SVG or PNG, and the whole viewer as one offline HTML file, all in the browser; see [docs/exports.md](docs/exports.md).
+
+The viewer displays the comparisons, migration tracks and inferred associations a document stores (Compare and
+Migrations tabs, difference marks on the diagram, inferred marks on foreign-key edges) and never computes them; see
+[docs/views.md](docs/views.md).
+
+The viewer is a development-only tool: never expose it or its snapshots in production, and require authentication
+even in local development. [docs/embedding.md](docs/embedding.md) shows how to add it to an existing React, Next.js,
+Vue, Angular, FastAPI or Node.js application as a protected development page; [docs/security.md](docs/security.md) is
+the policy.
+
+Hosts without Node.js serve `node_modules/laranex-schema-viewer-ui/dist/viewer/` as static files (including its
+`favicon.svg` and `favicon.ico`) with a `snapshot.json` beside `index.html`, or use
+`<laranex-schema-viewer src="snapshot.json">`. Using the viewer (layout, connections, line ends, column details,
+shortcuts and deep links) is described in [docs/viewer.md](docs/viewer.md).
+
+Its icons, brand mark, favicon and line ends come from Laranex Laravel Schema Viewer, drawn in this package's own
+theme colors (see NOTICE); [docs/parity.md](docs/parity.md) compares the two viewers feature by feature.
 
 ## License
 

package/contract/allowlist.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://laranex.github.io/schema-viewer-ui/laranex-schema-allowlist/1.0.json",
+  "title": "laranex-schema-allowlist 1.0",
+  "type": "object",
+  "properties": {
+    "format": {
+      "const": "laranex-schema-allowlist"
+    },
+    "version": {
+      "const": "1.0"
+    },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string",
+            "pattern": "^(?!/)(?!.*//)(?!.*/$)(?!(.*/)?\\.\\.?(/|$))[^\\\\\\u0000]+$"
+          },
+          "sha256": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$"
+          }
+        },
+        "required": [
+          "path",
+          "sha256"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "include": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string",
+            "pattern": "^(?!/)(?!.*//)(?!.*/$)(?!(.*/)?\\.\\.?(/|$))[^\\\\\\u0000]+$"
+          },
+          "root": {
+            "type": "string",
+            "pattern": "^\\.$|^(?!/)(?!.*//)(?!.*/$)(?!(.*/)?\\.\\.?(/|$))[^\\\\\\u0000]+$"
+          }
+        },
+        "required": [
+          "path",
+          "root"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": [
+    "format",
+    "version",
+    "entries"
+  ],
+  "additionalProperties": false
+}

package/contract/check.mjs

@@ -3,10 +3,11 @@
 //
 //   node node_modules/laranex-schema-viewer-ui/contract/check.mjs [--lenient] [--no-graph] [--no-canonical] FILE...
 //
-// By default a document must pass strict validation, store exactly the links the shared graph builder produces, and
-// be written in canonical form. Exits 1 when any file fails.
+// By default a document must pass strict validation (which also checks comparison ids, order and summaries, and
+// migration statuses), store exactly the links the shared graph builder produces and the inferred associations the
+// shared inference produces, and be written in canonical form. Exits 1 when any file fails.
 import { readFileSync } from 'node:fs';
-import { buildGraph, canonicalJson, validateDocument } from '../dist/lib/contract.js';
+import { buildGraph, canonicalJson, inferAssociations, validateDocument } from '../dist/lib/contract.js';
 
 const args = process.argv.slice(2);
 const flags = new Set(args.filter((a) => a.startsWith('--')));
@@ -37,6 +38,9 @@ for (const file of files) {
             if (canonicalJson(expected.derivedLinks) !== canonicalJson(doc.derivedLinks)) {
                 problems.push('derivedLinks differ from the shared graph builder');
             }
+            if (canonicalJson(inferAssociations(doc)) !== canonicalJson(doc.inferredAssociations)) {
+                problems.push('inferredAssociations differ from the shared inference');
+            }
         }
         if (!flags.has('--no-canonical') && canonicalJson(doc) !== text) {
             problems.push('not in canonical form (sorted keys, two-space indentation, trailing newline)');

package/contract/conformance/comparison/column-fields-same-driver.json

@@ -0,0 +1,387 @@
+{
+  "description": "Columns match by name; on one driver types compare as written (certain), defaults as normalized SQL (likely), and fields are sorted",
+  "expected": {
+    "baseline": {
+      "connection": "connection:a",
+      "schema": null
+    },
+    "complete": true,
+    "differences": [
+      {
+        "baseline": {
+          "id": null,
+          "label": "users.email",
+          "table": "a:users"
+        },
+        "certainty": "certain",
+        "change": "changed",
+        "fields": [
+          {
+            "baseline": true,
+            "field": "nullable",
+            "target": false
+          },
+          {
+            "baseline": "varchar(255)",
+            "field": "type",
+            "target": "VARCHAR(320)"
+          }
+        ],
+        "id": "x411857b333eecaa2",
+        "key": [
+          "users",
+          "email"
+        ],
+        "objectType": "column",
+        "severity": "warning",
+        "target": {
+          "id": null,
+          "label": "users.email",
+          "table": "b:users"
+        }
+      },
+      {
+        "baseline": {
+          "id": null,
+          "label": "users.note",
+          "table": "a:users"
+        },
+        "certainty": "certain",
+        "change": "changed",
+        "fields": [
+          {
+            "baseline": "old",
+            "field": "comment",
+            "target": "new"
+          }
+        ],
+        "id": "x46fb774d0d31dcf8",
+        "key": [
+          "users",
+          "note"
+        ],
+        "objectType": "column",
+        "severity": "info",
+        "target": {
+          "id": null,
+          "label": "users.note",
+          "table": "b:users"
+        }
+      },
+      {
+        "baseline": null,
+        "certainty": "certain",
+        "change": "extra",
+        "fields": [],
+        "id": "xb29093c0bc285345",
+        "key": [
+          "users",
+          "phone"
+        ],
+        "objectType": "column",
+        "severity": "error",
+        "target": {
+          "id": null,
+          "label": "users.phone",
+          "table": "b:users"
+        }
+      },
+      {
+        "baseline": {
+          "id": null,
+          "label": "users.status",
+          "table": "a:users"
+        },
+        "certainty": "likely",
+        "change": "changed",
+        "fields": [
+          {
+            "baseline": {
+              "kind": "literal",
+              "value": "'a'::text"
+            },
+            "field": "default",
+            "target": {
+              "kind": "literal",
+              "value": "'b'::text"
+            }
+          }
+        ],
+        "id": "x2f91ca963ed4eca9",
+        "key": [
+          "users",
+          "status"
+        ],
+        "objectType": "column",
+        "severity": "warning",
+        "target": {
+          "id": null,
+          "label": "users.status",
+          "table": "b:users"
+        }
+      }
+    ],
+    "id": "ccd30999b0df19108",
+    "omitted": 0,
+    "summary": {
+      "changed": 3,
+      "extra": 1,
+      "missing": 0
+    },
+    "target": {
+      "connection": "connection:b",
+      "schema": null
+    }
+  },
+  "input": {
+    "baseline": {
+      "connection": "connection:a",
+      "schema": null
+    },
+    "document": {
+      "connections": [
+        {
+          "coverage": {
+            "database": {
+              "complete": true,
+              "features": {
+                "checkConstraints": "complete",
+                "columnTypes": "complete",
+                "columns": "complete",
+                "comments": "complete",
+                "defaults": "complete",
+                "foreignKeys": "complete",
+                "includedColumns": "complete",
+                "indexExpressions": "complete",
+                "indexPredicates": "complete",
+                "indexes": "complete",
+                "primaryKeys": "complete",
+                "referentialActions": "complete",
+                "tables": "complete",
+                "uniqueConstraints": "complete"
+              },
+              "schemas": null
+            },
+            "declared": null
+          },
+          "defaultSchema": null,
+          "driver": "postgresql",
+          "id": "connection:a",
+          "name": "a",
+          "tables": [
+            {
+              "columns": [
+                {
+                  "autoIncrement": false,
+                  "collation": null,
+                  "comment": null,
+                  "default": null,
+                  "enum": null,
+                  "generated": null,
+                  "name": "email",
+                  "note": null,
+                  "nullable": true,
+                  "ormDefault": null,
+                  "provenance": [
+                    "database"
+                  ],
+                  "timezone": null,
+                  "type": "varchar(255)",
+                  "typeName": "varchar"
+                },
+                {
+                  "autoIncrement": false,
+                  "collation": null,
+                  "comment": "old",
+                  "default": null,
+                  "enum": null,
+                  "generated": null,
+                  "name": "note",
+                  "note": null,
+                  "nullable": false,
+                  "ormDefault": null,
+                  "provenance": [
+                    "database"
+                  ],
+                  "timezone": null,
+                  "type": "text",
+                  "typeName": "text"
+                },
+                {
+                  "autoIncrement": false,
+                  "collation": null,
+                  "comment": null,
+                  "default": {
+                    "kind": "literal",
+                    "value": "'a'::text"
+                  },
+                  "enum": null,
+                  "generated": null,
+                  "name": "status",
+                  "note": null,
+                  "nullable": false,
+                  "ormDefault": null,
+                  "provenance": [
+                    "database"
+                  ],
+                  "timezone": null,
+                  "type": "text",
+                  "typeName": "text"
+                }
+              ],
+              "comment": "People",
+              "constraints": [],
+              "foreignKeys": [],
+              "id": "a:users",
+              "indexes": [],
+              "name": "users",
+              "note": null,
+              "owner": {
+                "kind": "application",
+                "package": null
+              },
+              "primaryKey": [],
+              "provenance": [
+                "database"
+              ],
+              "schema": null
+            }
+          ]
+        },
+        {
+          "coverage": {
+            "database": {
+              "complete": true,
+              "features": {
+                "checkConstraints": "complete",
+                "columnTypes": "complete",
+                "columns": "complete",
+                "comments": "complete",
+                "defaults": "complete",
+                "foreignKeys": "complete",
+                "includedColumns": "complete",
+                "indexExpressions": "complete",
+                "indexPredicates": "complete",
+                "indexes": "complete",
+                "primaryKeys": "complete",
+                "referentialActions": "complete",
+                "tables": "complete",
+                "uniqueConstraints": "complete"
+              },
+              "schemas": null
+            },
+            "declared": null
+          },
+          "defaultSchema": null,
+          "driver": "postgresql",
+          "id": "connection:b",
+          "name": "b",
+          "tables": [
+            {
+              "columns": [
+                {
+                  "autoIncrement": false,
+                  "collation": null,
+                  "comment": null,
+                  "default": null,
+                  "enum": null,
+                  "generated": null,
+                  "name": "email",
+                  "note": null,
+                  "nullable": false,
+                  "ormDefault": null,
+                  "provenance": [
+                    "database"
+                  ],
+                  "timezone": null,
+                  "type": "VARCHAR(320)",
+                  "typeName": "varchar"
+                },
+                {
+                  "autoIncrement": false,
+                  "collation": null,
+                  "comment": "new",
+                  "default": null,
+                  "enum": null,
+                  "generated": null,
+                  "name": "note",
+                  "note": null,
+                  "nullable": false,
+                  "ormDefault": null,
+                  "provenance": [
+                    "database"
+                  ],
+                  "timezone": null,
+                  "type": "text",
+                  "typeName": "text"
+                },
+                {
+                  "autoIncrement": false,
+                  "collation": null,
+                  "comment": null,
+                  "default": null,
+                  "enum": null,
+                  "generated": null,
+                  "name": "phone",
+                  "note": null,
+                  "nullable": false,
+                  "ormDefault": null,
+                  "provenance": [
+                    "database"
+                  ],
+                  "timezone": null,
+                  "type": "text",
+                  "typeName": "text"
+                },
+                {
+                  "autoIncrement": false,
+                  "collation": null,
+                  "comment": null,
+                  "default": {
+                    "kind": "literal",
+                    "value": "'b'::text"
+                  },
+                  "enum": null,
+                  "generated": null,
+                  "name": "status",
+                  "note": null,
+                  "nullable": false,
+                  "ormDefault": null,
+                  "provenance": [
+                    "database"
+                  ],
+                  "timezone": null,
+                  "type": "text",
+                  "typeName": "text"
+                }
+              ],
+              "comment": "People",
+              "constraints": [],
+              "foreignKeys": [],
+              "id": "b:users",
+              "indexes": [],
+              "name": "users",
+              "note": null,
+              "owner": {
+                "kind": "application",
+                "package": null
+              },
+              "primaryKey": [],
+              "provenance": [
+                "database"
+              ],
+              "schema": null
+            }
+          ]
+        }
+      ],
+      "source": "database"
+    },
+    "limit": null,
+    "overrides": [],
+    "target": {
+      "connection": "connection:b",
+      "schema": null
+    }
+  }
+}