From 100225480560799f0aeae7d710bae3e330765c0a Mon Sep 17 00:00:00 2001 From: Boris Tyshkevich Date: Mon, 29 Jun 2026 11:28:12 +0200 Subject: [PATCH 1/3] chore: release-readiness hygiene (attribution, CHANGELOG, CONTRIBUTING, dependabot) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes the easy 1.0 should-haves from the roadmap (#68): - License compliance: add NOTICE + THIRD-PARTY-NOTICES.md, and embed the bundled Chart.js + @dagrejs/dagre (MIT) notices into the built dist/sql.html. esbuild strips legal comments (legalComments:'none'), so build/build.mjs now injects the notices as a leading, sanitized HTML comment via a template token. - Add CHANGELOG.md (Keep a Changelog; seeded from v0.1.0–v0.1.4). - Add CONTRIBUTING.md (human-facing distillation of the CLAUDE.md hard rules + build/test quickstart). - Add .github/dependabot.yml (npm + github-actions, weekly) — the two runtime deps ship inside the artifact, so keep them watched. The two larger should-haves are tracked as issues instead: accessibility pass (#73) and in-app version/build stamp (#74). npm test green (1023); build verified to embed both notices. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_019kE9qbgBNBrfNgwg9fRsMJ --- .github/dependabot.yml | 17 +++++++++++ CHANGELOG.md | 64 ++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 64 ++++++++++++++++++++++++++++++++++++++++++ NOTICE | 11 ++++++++ THIRD-PARTY-NOTICES.md | 34 ++++++++++++++++++++++ build/build.mjs | 8 ++++++ build/template.html | 1 + 7 files changed, 199 insertions(+) create mode 100644 .github/dependabot.yml create mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md create mode 100644 NOTICE create mode 100644 THIRD-PARTY-NOTICES.md diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..f330087 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,17 @@ +# Dependency update alerts/PRs. The two runtime deps (Chart.js, @dagrejs/dagre) +# are inlined into the shipped dist/sql.html, so a vuln in them ships to every +# browser that loads the page — keep them watched, alongside devDeps and Actions. +version: 2 +updates: + - package-ecosystem: npm + directory: "/" + schedule: + interval: weekly + open-pull-requests-limit: 5 + groups: + dev-dependencies: + dependency-type: development + - package-ecosystem: github-actions + directory: "/" + schedule: + interval: weekly diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..721a80f --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,64 @@ +# Changelog + +All notable changes to this project are documented here. The format follows +[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims to +adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +GitHub Releases (cut from `v*` tags by `.github/workflows/release.yml`) carry the +auto-generated per-PR notes; this file is the curated, human-readable history. + +## [Unreleased] + +### Added +- `NOTICE` + `THIRD-PARTY-NOTICES.md`, and the bundled Chart.js / dagre (MIT) + notices are now embedded in the built `dist/sql.html`. +- `CONTRIBUTING.md` and this `CHANGELOG.md`. +- Dependabot configuration for npm + GitHub Actions updates. + +## [0.1.4] - 2026-06-28 + +### Changed +- Schema detail pane: removed the "Insert SHOW CREATE" action button; opening a + node now rings its card (a double border) and the ring clears on every + pane-close path including Esc (#65). +- Code-review follow-ups for the schema/zoom work: extracted `schemaLayout()` and + a `fixedAnchor()` helper, and the transitive-lineage node cap now counts only + linked nodes so a large single database isn't truncated early (#64). + +## [0.1.3] - 2026-06-28 + +### Changed +- Whole-database schema graph now draws **every** table (linked or not), packs the + unlinked tables into a grid below the lineage, and drops the redundant `.` + prefix from node labels for objects in the focused database (#63). + +## [0.1.2] - 2026-06-28 + +### Fixed +- Bridged the shipped `html { zoom }` across the full-view schema panel and the + splitter / detail-pane-resize / popover coordinate math, so the full view fits + one screen (the detail-pane DDL was previously pushed off-screen) and drags and + popovers track the cursor (#62). + +## [0.1.1] - 2026-06-28 + +### Added +- `antalya-oauth` demo connection (Google SSO). + +### Changed +- Documentation updates; dropped the inaccurate "zero-dependency" framing (the + app bundles two deliberate runtime dependencies). + +## [0.1.0] - 2026-06-28 + +### Added +- Initial release: OAuth-gated (PKCE) single-file SQL browser served from + ClickHouse — SQL editor, sortable results table + chart view, EXPLAIN pipeline + graph, and the schema data-flow graph. Built by esbuild into one `dist/sql.html`. + +[Unreleased]: https://github.com/Altinity/altinity-sql-browser/compare/v0.1.4...HEAD +[0.1.4]: https://github.com/Altinity/altinity-sql-browser/compare/v0.1.3...v0.1.4 +[0.1.3]: https://github.com/Altinity/altinity-sql-browser/compare/v0.1.2...v0.1.3 +[0.1.2]: https://github.com/Altinity/altinity-sql-browser/compare/v0.1.1...v0.1.2 +[0.1.1]: https://github.com/Altinity/altinity-sql-browser/compare/v0.1.0...v0.1.1 +[0.1.0]: https://github.com/Altinity/altinity-sql-browser/releases/tag/v0.1.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..7f9cf28 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,64 @@ +# Contributing to the Altinity SQL Browser + +Thanks for your interest! This is a modular, no-framework ES-module SPA that +builds to **one self-contained HTML file** (`dist/sql.html`) served from a +ClickHouse cluster. Quality is held by tests and a strict layering discipline — +please read the hard rules below before opening a PR. + +## Quickstart + +```bash +npm install +npm test # vitest + coverage gate (must pass) +npm run build # esbuild → dist/sql.html +npm run local # build, then serve locally with a connection picker +npm run test:e2e # Playwright (chromium + firefox); needs: npx playwright install chromium firefox +``` + +Requirements: Node 22, a POSIX shell. No other toolchain. + +## Hard rules (non-negotiable) + +These mirror `CLAUDE.md` (the in-repo agent guide) — the same rules apply to human +contributors. + +1. **The coverage gate must pass.** `npm test` enforces **100% per-file** for the + pure / network / state / DOM / render layers. `src/ui/app.js` + `src/main.js` + are the browser glue, gated lower and integration-tested. **Add tests in the + same change as the code.** +2. **Keep the layers honest.** + - Pure logic → `src/core/` (no DOM, no globals). + - Network → `src/net/` with the `fetch` seam **injected**, never imported. + - DOM rendering → `src/ui/` as functions that take the `app` controller. + - Side-effectful environment access (location, crypto, storage, fetch) is + injected through `createApp(env)` so everything is testable under happy-dom. +3. **No secrets in git.** `config.json` (rendered) is gitignored; only + `deploy/config.json.example` is committed. `config.json` is served to browsers + — prefer a PKCE public client (see the README "Configuring OAuth" and + `SECURITY.md`). +4. **The build is esbuild only; runtime deps are rare and deliberate.** There are + exactly **two** bundled runtime dependencies — **Chart.js** and + **@dagrejs/dagre** — both inlined so the page makes zero third-party requests. + Adding another is a deliberate decision that grows the single served file. When + a feature needs a library, keep the testable logic pure in `src/core/` and make + the library call an **injected seam** (like `app.Chart` / `app.Dagre`). + +## How to add a result view / panel / feature + +Touch these in one change: +- the module under `src/core/` (pure logic) or `src/ui/` (render); +- its `tests/unit/.test.js` to 100%; +- if it changes the deployed surface, `deploy/http_handlers.xml` + the README. + +## Pull requests + +- Branch off `main`; keep PRs focused. +- `npm test` green (coverage gate) and `npm run build` succeeds. +- Update the README / `CHANGELOG.md` (`[Unreleased]`) when behavior or the + deployed surface changes. +- Releases are cut by pushing a `vX.Y.Z` tag (see `.github/workflows/release.yml`). + +## Reporting bugs / security + +Open a GitHub issue for bugs and feature requests. For security-sensitive +reports, follow `SECURITY.md` instead of filing a public issue. diff --git a/NOTICE b/NOTICE new file mode 100644 index 0000000..98016f3 --- /dev/null +++ b/NOTICE @@ -0,0 +1,11 @@ +Altinity SQL Browser +Copyright 2026 Altinity, Inc. + +This product is licensed under the Apache License, Version 2.0 (see LICENSE). + +It bundles the following third-party components into the built single-file +artifact (dist/sql.html). Their licenses and copyright notices are reproduced in +THIRD-PARTY-NOTICES.md and are embedded in the artifact: + + - Chart.js (MIT) — https://www.chartjs.org + - @dagrejs/dagre (MIT) — https://github.com/dagrejs/dagre diff --git a/THIRD-PARTY-NOTICES.md b/THIRD-PARTY-NOTICES.md new file mode 100644 index 0000000..37cdacf --- /dev/null +++ b/THIRD-PARTY-NOTICES.md @@ -0,0 +1,34 @@ +# Third-party notices + +The Altinity SQL Browser is licensed under Apache-2.0 (see `LICENSE`). The built +single-file artifact (`dist/sql.html`) inlines the two runtime dependencies +below; this file reproduces their MIT license texts as required, and the same +notices are embedded as a comment at the top of the built artifact. + +--- + +## Chart.js — v4.5.1 + +The MIT License (MIT) + +Copyright (c) 2014-2024 Chart.js Contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--- + +## @dagrejs/dagre — v3.0.0 + +The MIT License (MIT) + +Copyright (c) 2012-2014 Chris Pettitt + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/build/build.mjs b/build/build.mjs index a0acc37..fb3916f 100644 --- a/build/build.mjs +++ b/build/build.mjs @@ -28,7 +28,15 @@ async function main() { const styles = await readFile(resolve(root, 'src/styles.css'), 'utf8'); const template = await readFile(resolve(here, 'template.html'), 'utf8'); + // The two runtime deps (Chart.js, dagre) are MIT and inlined into the bundle, + // so the artifact must carry their notices. esbuild strips legal comments + // (legalComments: 'none'), so embed THIRD-PARTY-NOTICES.md as a leading HTML + // comment — sanitized so its text can't close the comment early. + const notices = (await readFile(resolve(root, 'THIRD-PARTY-NOTICES.md'), 'utf8')).replace(/--+>?/g, '-'); + const thirdParty = ''; + const html = template + .replace('', () => thirdParty) .replace('/*__STYLES__*/', () => styles) .replace('/*__SCRIPT__*/', () => script); diff --git a/build/template.html b/build/template.html index 324255d..e513a78 100644 --- a/build/template.html +++ b/build/template.html @@ -1,6 +1,7 @@ + Altinity SQL Browser From a1f467b2291c25fc70644d02a9bdad4a4ca6c952 Mon Sep 17 00:00:00 2001 From: Boris Tyshkevich Date: Mon, 29 Jun 2026 12:11:07 +0200 Subject: [PATCH 2/3] chore: add issue/PR templates, CODEOWNERS, and a