feat: endpoint describe panel (#97)

[MathiasVDA]

Closes #97

Summary

Adds an Endpoint overview panel for getting to know an unfamiliar SPARQL endpoint while writing queries. Open it with the new Describe endpoint button in the tab control bar (also in the mobile menu) or with F8.

Panel behaviour

• Docked to the right of the editor.
• Can be pinned (stays open, restored after a reload), collapsed to a thin bar, or resized by dragging its left edge.
• An unpinned panel collapses when the user clicks into the editor.
• On small screens it opens as a bottom sheet.
• Follows the endpoint of the active tab.

Service Description and VoID

• Fetched automatically when the panel opens:
  • the SD by requesting the endpoint without ?query;
  • VoID from /.well-known/void, or embedded in the SD.
• Shows features, extension functions, named graphs, dataset statistics, vocabularies and class/property partitions.
• When an endpoint publishes neither (e.g. GraphDB), the panel says so instead of showing an error.
• Descriptions are read up to 5 MB and parsed up to the last complete statement; the panel says when a description was cut off. Wikidata's SD is about 19 MB.

Overview queries

• 20 queries across all six categories from the issue comment:
  • overview (named graphs, triples per graph, triple count, namespaces)
  • schema (classes, properties, SKOS schemes, SHACL/ShEx shapes)
  • instances (samples per class, hubs)
  • labels and languages
  • links (referenced hosts, linking properties, linked entities)
  • time and geo (temporal and geo properties, CRS, lat/long bounding box, and a bounding box computed from a sample of WKT literals)
• Queries run only when clicked ("Run" or "Run all").
• Every query has a LIMIT.
• Lists such as named graphs are paginated with "Load more", so an endpoint with millions of graphs is not listed in one request.
• Full-scan queries are labelled "may be slow".
• At most two describe queries run at once, each with a timeout (60 s by default).
• Queries run through the tab's request config and authentication, but without the tab's default/named graphs.
• Incomplete results are marked Partial result. Virtuoso "anytime queries" (DBpedia) answer 206 / X-SQL-State: S1TAT, often with an empty result.
• Error messages are made readable:
  • HTML error pages are reduced to their title;
  • rate limiting (429) is explained, including Retry-After;
  • Java stack traces (Blazegraph/Wikidata) are reduced to their root cause.

Remembered results

• Results are cached per endpoint and survive other queries, tab switches and reloads. Each shows when it was fetched.
• The cache has its own storage key, capped at 20 endpoints and 200 rows per result. MatGUI's quota handler would otherwise wipe the whole configuration if the cache filled the storage.

Working with results

• Clicking an IRI inserts it into the query as a prefixed name and adds the missing PREFIX line.
• Any describe query can be opened in a new tab.

Configuration

• New endpointDescribe option: enabled, queries, categories, timeoutMs, maxConcurrentQueries, fetchMetadata.
• Queries and categories can be extended, e.g. with endpoint-specific queries.

API additions

• Tab.runBackgroundQuery() and Tab.getRequestInit().
• yasgui.endpointDescribe.
• A skipGraphArgs option on yasqe's executeQuery.

Other

• n3 added to the yasgui dependencies (already used by yasr).
• Changeset: minor.

Documentation

• User guide: new "Endpoint Overview" section (including partial results, rate limits and large descriptions), and an F8 entry under keyboard shortcuts.
• Developer guide: "Endpoint Describe Configuration" section with an example, plus API reference entries for yasgui.endpointDescribe, tab.runBackgroundQuery() and tab.getRequestInit().
• README and website intro: feature bullet and config option.

Testing

Live endpoints. Every query was run against DBpedia (Virtuoso), Wikidata (Blazegraph) and data.europa.eu (Virtuoso). SD/VoID discovery was run against all three, and the panel itself was run in headless Chromium against Wikidata and data.europa.eu.

• All queries are accepted by all three endpoints, except named-graphs / graph-sizes on Wikidata, which runs in triples mode.
• Full-scan queries are refused or time out on the large endpoints, as their "may be slow" label says.
• Fixed based on these runs:
  • the namespaces regex matched the empty string, which Virtuoso rejects;
  • partial 206 results looked like complete results;
  • the 19 MB Wikidata SD was downloaded in full;
  • blank-node datasets were shown as IRIs;
  • HTML and stack-trace error bodies were shown raw;
  • SKOS schemes was not flagged as slow;
  • runQuery() did nothing on a closed panel.
• The ERA endpoint (data-interop.era.europa.eu) could not be reached from the development environment.

Unit tests:

• query catalogue: bounded queries, balanced syntax, declared prefixes, no REPLACE patterns that match the empty string, LIMIT/OFFSET pagination, per-class sample generation, WKT bounding box;
• SD/VoID extraction: unavailable/HTML/404 cases, de-duplication, blank nodes, size cap and truncation;
• response handling: partial results, HTML/429/504/Blazegraph errors;
• cache: persistence, truncation, eviction, storage failures;
• skipGraphArgs.

Browser tests (Puppeteer, against a mocked endpoint):

• SD/VoID display;
• results kept after a regular query;
• IRI insertion with its prefix;
• following the active tab's endpoint;
• pinned panel restored after a reload;
• partial result and 429 messages;
• auto-collapse when the editor gets focus.

Other checks:

• Every generated query parses with sparqljs (checked ad hoc, not added as a dependency).
• Local run on the branch with main merged in: npm run build, npm run unit-test (180 passing) and npm run puppeteer-test (47 passing).

🤖 Generated with Claude Code

https://claude.ai/code/session_01DEbQuDzCkbQKKsARAXTpKu

[Copilot]

Copilot review overview

🔵 Needs a closer look

It introduces a large new subsystem (~2,500 lines) spanning UI, concurrency/scheduling, RDF parsing, persistent cache eviction, and new public APIs, which warrants final human review.

Review effort: Balanced
Findings: 1

Open (1)

• Avoid comma-formatting 4-digit year literals · New

What changed in this PR

This PR implements the Endpoint overview ("Describe endpoint") panel (closing #97), a new docked side panel in @matdata/yasgui that helps users explore an unfamiliar SPARQL endpoint while writing queries. It discovers the endpoint's SPARQL Service Description and VoID description, offers ~20 bounded overview queries across six categories, caches results per endpoint in its own storage key, and can be pinned/collapsed/resized. It also adds supporting primitives to @matdata/yasqe (skipGraphArgs) and Tab (runBackgroundQuery, getRequestInit).

Changes:

• New endpointDescribe/ subsystem (panel UI, query catalogue, SD/VoID metadata discovery, response/error normalization, per-endpoint cache with LRU eviction).
• New public APIs: yasgui.endpointDescribe, Tab.runBackgroundQuery(), Tab.getRequestInit(), and executeQuery's skipGraphArgs option; F8 shortcut and control-bar/hamburger buttons.
• Extensive unit + Puppeteer tests, docs (user/developer guides, README, intro), changeset, and the n3 dependency.

File	Description
packages/​yasgui/​src/​endpointDescribe/​EndpointDescribePanel.ts	Core panel UI, query scheduling/concurrency, rendering, IRI insertion
packages/​yasgui/​src/​endpointDescribe/​describeQueries.ts	Catalogue of bounded overview queries + WKT bounding-box post-processing
packages/​yasgui/​src/​endpointDescribe/​metadataSources.ts	SD/VoID fetching and RDF extraction with size limiting/truncation
packages/​yasgui/​src/​endpointDescribe/​responseUtils.ts	Partial-result detection and readable error messages
packages/​yasgui/​src/​endpointDescribe/​DescribeStore.ts	Per-endpoint cache, row truncation, LRU/size eviction, UI state
packages/​yasgui/​src/​endpointDescribe/​EndpointDescribePanel.scss	Docked/collapsed/bottom-sheet styling
packages/​yasgui/​src/​index.ts	Wires panel into layout (mainEl/tabPanelsEl), config, lifecycle
packages/​yasgui/​src/​Tab.ts	runBackgroundQuery, getRequestInit, F8 handler
packages/​yasgui/​src/​TabSettingsModal.ts	Control-bar and hamburger "Describe endpoint" buttons
packages/​yasgui/​src/​defaults.ts	Default endpointDescribe config
packages/​yasqe/​src/​sparql.ts	skipGraphArgs option omitting tab graph arguments
packages/​yasgui/​package.json, package-lock.json	Adds n3 dependency
test/​endpoint-describe-browser.ts, test/​unit/​endpoint-describe-test.ts, test/​unit/​yasqe-background-query-test.ts, test/​run.ts	New unit + browser test coverage
docs/​user-guide.md, docs/​developer-guide.md, README.md, website/​docs/​intro.md, .changeset/​endpoint-describe-panel.md	Documentation and changeset

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.