feat(docs): database documentation viewer and DBML export
* feat(docs): add SchemaSnapshot model * feat(docs): infer relationship cardinality from foreign keys * fix(docs): resolve foreign keys within the source schema * feat(docs): convert group hue to sRGB hex for DBML * feat(docs): add DBML lexical primitives * feat(docs): render DBML table blocks * feat(docs): render DBML refs, enums and table groups * feat(docs): assemble complete DBML documents * feat(docs): collect schema snapshots with bounded fan-out * fix(docs): gate FK warning on engine capability and reference synthesized enums * fix(docs): qualify synthesized enum references in multi-schema output * test(docs): anchor the multi-schema enum reference assertion * feat(docs): add snapshot collection route * feat(docs): add collect_docs_snapshot to DbxBackend * feat(docs): add dbx dbml command * test(docs): add live snapshot and DBML verification Runs collect_snapshot + to_dbml against a real PostgreSQL database (organon, 47 tables) and asserts structural DBML validity: Project header, every table present, balanced braces, trailing newline. * refactor(docs): use sort_by_key for snapshot table ordering * docs(docs): add database documentation design and implementation plan Records the Part 1 design (SchemaSnapshot + DBML export) and the plan that produced it. The plan carries an appendix listing the thirteen assumptions that proved wrong during execution, so the corrected facts are not re-derived from the surrounding prose. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TKcC15gEuQBHMidPCFFYwn * fix(docs): use native enum names, canonical engine labels, and surface metadata failures Final review fix wave covering four findings: - PostgreSQL named enums (e.g. `ConversationStatus`) now keep their own type name and synthesized: false, instead of being renamed to `{table}_{column}` and losing identity. A type shared by several columns now dedupes to a single Enum block instead of colliding or duplicating. `synthesize_enum` and `render_type` route through one shared `enum_type_name` helper so the two can't drift apart again. - `database_type` (and the CommentsUnsupported/NoForeignKeyMetadata warnings) now use the same canonical engine label already used throughout table_structure_sql's own warning prose, instead of a raw Rust Debug string (`Postgres`, `SqlServer`, `MongoDb`). - An index-fetch failure during collection now surfaces as a TableSkipped warning instead of silently degrading to an empty index list, which relations.rs uses to infer relationship cardinality. - A schema-enumeration failure now surfaces as a warning instead of silently proceeding against schema "". - Removed the redundant Arc<Semaphore>; buffer_unordered already caps concurrency at MAX_CONCURRENT_TABLES. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TKcC15gEuQBHMidPCFFYwn * feat(docs): add annotation file model * test(docs): assert full round-trip fidelity for the annotation model * feat(docs): add per-engine annotation key folding * fix(docs): do not fold identifiers on case-sensitive engines * feat(docs): load and validate the notes file * fix(docs): report a version mismatch before unknown-field errors * feat(docs): merge annotations into the schema snapshot * feat(docs): detect orphaned annotations without deleting them * feat(docs): add --notes to dbx dbml * feat(docs): remember a notes file path per connection Adds docs_notes_path to ConnectionConfig so the desktop app (Part 3) can persist where a connection's documentation notes file lives. The CLI is unaffected — it takes an explicit --notes path. ConnectionConfig has a hand-written Deserialize impl that delegates to a mirror struct, ConnectionConfigData, and converts via From. Adding the field only to ConnectionConfig would compile but never populate from stored JSON, since ConnectionConfigData's fields are what serde actually reads. The field is threaded through all three places: ConnectionConfig, ConnectionConfigData, and the From impl, mirroring the existing `color` field. * test(docs): verify annotations against a live database * test(docs): assert exactly one orphaned annotation * feat(docs): add snapshot types for the docs viewer * fix(docs): correct snapshot type nullability and add missing column fields * feat(docs): add a real-output fixture and drift conformance test The fixture is generated by dump_docs_fixture.rs from a live collect_snapshot run against the keycloak database in the shared local-infra stack, with annotations applied so a LOCAL note, column note, group and orphanedNotes warning are all present. fixtureConformance.spec.ts asserts against that real JSON rather than a hand-written literal, so a change to the Rust snapshot shape breaks the test instead of silently drifting from the hand-maintained types.ts. Keycloak is used because its schema is public open-source knowledge, so the committed fixture carries no private schema. The kept tables are an explicit allowlist rather than an alphabetical slice, because the conformance test needs a connected foreign-key subgraph: protocol_mapper has two foreign keys to different tables and composite_role has two to the same one. * feat(docs): add index grouping for the docs viewer * feat(docs): describe snapshot warnings for the viewer * feat(docs): add client-side search for the docs viewer * test(docs): make the search fixture able to fail * feat(docs): expose group hue as a CSS custom property * docs(plan): add annotations and viewer plans, correct Task 7 Parts 2 and 3a were planned after the first plan was committed and were never tracked. docs/superpowers/ is gitignored, so both needed -f, matching how the existing specs and plans in that directory were added. The viewer plan's Task 7 is corrected against the installed marked@18.0.4. Its original text carried four defects, found by probing the library rather than by review: an assertion that fails against a correct implementation, a pre-escaping approach that double-escapes entities, a javascript: blocklist with live bypasses (entity-encoded, vbscript:, data:text/html, and <img src>, which was never covered at all), and a link renderer whose text property is raw markdown source rather than parsed HTML — an XSS hole found while verifying the fix for the previous defect. The viewer plan also gains a corrections appendix grouping defects by failure mode. The annotations plan is committed as written; its defects are recorded in a follow-up. * feat(docs): render note markdown with raw HTML escaped * fix(docs): drop protocol-relative URLs in note markdown The URL allowlist permitted anything starting with / so relative paths work, and //evil.com qualifies. Over https that grants nothing a note author could not do with an ordinary https link, but the Part 3b standalone export is opened via file://, where //host/path is a UNC path. On Windows that opens an SMB connection and leaks an NTLM hash, with no click required since images auto-load, and it is plantable from a COMMENT ON value. Found by an adversarial probe of the committed module rather than by review; the backslash form was already dropped, only the slash form slipped through. * docs(plan): add corrections appendix to the annotations plan Groups the defects found executing Part 2 by failure mode, matching the form of the viewer plan's appendix. The notable one is Mode A: docs_notes_path had to be added in three places because ConnectionConfig has a serde mirror struct, and adding it in one place compiles, passes a round-trip test written against the same struct, and then reads None forever after every load. Also records a controller hypothesis that turned out to be wrong, since checking it cost one read. * fix(docs): reject backslash protocol-relative URLs in notes The // guard from the previous commit was itself a blocklist: /\evil.com starts with a single slash, so it passed, and the WHATWG URL spec treats /\ identically to // for special schemes. Browsers normalise the backslash, so it reaches the same file:// UNC path and the same no-click NTLM leak. Rejecting both separator characters in both positions closes it. Found by probing what String(raw).trim() leaves unnormalised before the prefix checks; the third defect on this file found by probing rather than by reading. * feat(docs): add docs viewer components Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TKcC15gEuQBHMidPCFFYwn * test(docs): pin each theme's legacy colour base independently The ordering check indexOf(hsl) < indexOf(@supports) quantified over any occurrence, so deleting the light .docs-group block left the dark block's hsl satisfying it. The test passed while every table group rendered colourless on light-theme WebViews without oklch. Asserting each selector's own base block catches deleting either one. Found by the task implementer, which deleted one block and then both to show the guard pinned 'some base exists' rather than 'each selector has a base'. * fix(docs): escape single quotes in note attribute values escapeHtml covered & < > and double quotes but not single quotes. Not exploitable today because every attribute in this file is double-quoted, but that is a formatting convention enforced nowhere and living in a different part of the file from the escaper. A future edit writing title='...' would turn a formatting choice into an attribute breakout. Raised by review as latent fragility rather than a defect; fixed because the escaper should be correct on its own rather than correct-given-an-invariant. * test(docs): match single-quoted v-html bindings in the contract guard The guard matched /v-html\s*=\s*"([^"]*)"/ — double quotes only. A binding written `v-html='table.note'` produced zero matches and passed, handing a database COMMENT ON value straight to the DOM with the renderNote sanitiser bypassed. Both quote styles are valid Vue and nothing in the repo enforces one, so the guard had a hole exactly where it mattered most. Verified by temporarily rewriting a real WikiIndex binding as `v-html='table.note'`: the test now fails with "WikiIndex.vue: v-html must render renderNote output: expected 'table.note' to contain 'renderNote'". Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TKcC15gEuQBHMidPCFFYwn * fix(docs): cap search results per kind instead of overall DocsSearch sliced searchDocs output to 40 AFTER concatenation, and the concatenation order is tables -> columns -> groups -> enums. Columns always flooded the list, so the cap deleted the tail — every group and enum hit. Against the real fixture, "e" produced 155 hits (9 table, 133 column, 1 group, 12 enum) and rendered 9 tables, 31 columns and nothing else; groups and enums were structurally unreachable through search. Cap each kind against its own limit inside docsSearch.ts, where the logic is tested, and drop the slice from the template so exactly one place limits results. Ranking is unchanged: tables still precede columns. Verified by reverting to a single .slice(0, 40) over the concatenation: the new tests fail with "enums must survive a column flood: expected false to be true" and "expected 30 to be 20". Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TKcC15gEuQBHMidPCFFYwn * fix(docs): move the index card note out of its button The card rendered renderNote output with v-html inside the <button>. A note containing a markdown link — [spec](https://example.com) — put an <a> inside a <button>: invalid nesting, and the anchor was not keyboard reachable because the button swallows it in the tab order. The <li> now carries the card's border, background and hover, the button holds only the table name and kind, and the note is its sibling. Visually identical — same padding, same 0.5 gap, previously mt-0.5 — and the name row still spans the full width as the click target. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TKcC15gEuQBHMidPCFFYwn * test(docs): pin every fixture struct's key set in both directions The guard pinned ColumnInfo and IndexInfo plus three DocTable keys, and only in the "no missing key" direction. Relationship, FieldRef, DocEnum, ProjectMeta, ColumnNote, ForeignKeyInfo, TableGroup and 10 of 13 DocTable keys were unchecked. Renaming Relationship::to to `target` in Rust kept the suite at 67/67 and vue-tsc at exit 0 while RelationshipList read `field.table` on undefined and every table page rendered blank. Every struct in the fixture is now pinned both ways — no missing key, no unexpected key — over every instance rather than element [0]. Each direction catches a different half of a rename. Object.hasOwn throughout, so a key that is present and null stays distinguishable from one skip_serializing_if omitted. ForeignKeyInfo, TableGroup and the SchemaSnapshot root are included beyond the list the review gave: they are equally present in the fixture and equally unpinned. Verified against a modified copy of the fixture outside the repo with Relationship::to renamed: "Relationship[0] must always carry to: expected false to be true". Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TKcC15gEuQBHMidPCFFYwn * fix(cli): error when an explicit --notes path does not exist load_annotations returns Ok(None) for a missing file, which is right for the implicit per-connection notes path — it may legitimately not exist yet. It is wrong for --notes, where the user named a specific file: a mistyped path produced DBML with every note silently absent and no diagnostic at all, indistinguishable from a database that has no documentation. Both final reviewers independently ruled this must-fix-before-merge. * fix(docs): treat an explicit FK ref_schema as authoritative find_target tried the explicit ref_schema, then fell through to the source table's own schema on failure. When the referenced schema was not collected — routine, since users select schemas — an FK from sales.orders to archive.customers resolved to sales.customers instead: a different table, and a diagram that is confidently wrong rather than visibly incomplete. The function's own doc comment already promised that keys pointing outside the collected set are dropped. Now it does that. This is a regression of the defect found in Part 1: the three-tier lookup was added then, but tier one was written to fall through rather than to decide. * fix(docs): corroborate engine capability warnings against what was collected supports_comments and supports_foreign_keys delegate to the structure editor's DDL-generation capabilities, not to introspection support. IRIS is the proven divergence: it reports %DESCRIPTION on introspection but DBX cannot ALTER an existing one, so the flag is false while the collector reads and includes those comments — producing a snapshot that warned comments were unsupported alongside the comments themselves. Each warning now fires only when the flag says the engine cannot AND collection found nothing of the kind to contradict it. ClickHouse and Doris, which genuinely report no foreign keys, still warn. The doc comments now say what the functions actually measure. Found by final review, which traced every other caller to establish the flag's real semantics. * docs(fixture): finish repointing the fixture source to keycloak Follows the rebase that replaced the fixture at its origin commit. Repoints the live annotation test's project identity and both plans, and records the one capability keycloak costs us. Keycloak declares no PostgreSQL enum types, so the fixture cannot exercise DocEnum — a Rust-side rename of a DocEnum field would pass every test here and break the viewer's enum rendering silently. Rather than delete the test, it now asserts the gap, so it fails the day the fixture source gains an enum and prompts restoring the pin. * docs(spec): design for in-app database documentation (Part 3b) Mounts the Part 3a viewer in DBX and makes it editable: table/column notes, table groups, and per-group colour, autosaved to a notes file that can live in the user's repository. Two findings shaped the scope. DBX already ships SchemaDiagramDialog, so the viewer links to it rather than building a second ER diagram — only the Part 3c export needs its own minimal renderer, because that dialog reaches into stores and cannot be inlined. And nothing currently reads docs_notes_path or writes annotations at all, so 'in-app editing' needs new Rust rather than frontend wiring alone. The standalone export, dbx docs verb and hash routing are deferred to 3c. * docs(plan): implementation plan for in-app database documentation Ten tasks: atomic annotation save and path resolution, Tauri commands, web route parity, the frontend facade, pure edit transforms, the i18n namespace with a parity guard, editing components, the enum page, edit plumbing through the viewer, and the dialog with debounced autosave. Self-review caught three defects before dispatch, all the same class that cost Part 3a ten fix rounds: a return type named DescribedWarning that does not exist (it is WarningNotice), a test calling emptySnapshot() which does not exist, and a table() helper invoked with columns when its real signature takes a groupId. Every identifier the plan names is a claim about the codebase. * docs(plan): resolve the data directory without a dbx-mcp dependency Tasks 2 and 3 called dbx_mcp::paths::app_data_dir(), but neither src-tauri nor dbx-web depends on dbx-mcp, so neither would have compiled. Both already have a better source: AppState.storage.data_dir() honours a custom data dir, and WebState already carries data_dir. Found by the pre-flight scan before any implementer saw it. * docs(plan): fix Task 1 against the real crate (no Default, no tempfile) ConnectionConfig has no Default derive and ~60 fields, so resolve_notes_path now takes the connection id and the optional override directly — the two fields it actually reads. The test pain was pointing at the signature. dbx-core has no dev-dependencies, so the tests use the temp_dir + uuid idiom already present in annotations.rs rather than tempfile. * feat(docs): add atomic annotation save and notes path resolution * docs(plan): guard the autosave against concurrent writes flush() cleared the debounce timer but not an in-flight write, so closing the dialog while a debounced save was awaiting the backend started a second one. Two concurrent saves of the same file waste a round trip, race to land stale, and are the exact concurrency that corrupts the notes file when the temp path is not unique per writer. Found while adjudicating the Task 1 review, which demonstrated the Rust half of the same problem. * fix(docs): make temp paths unique to prevent concurrent save corruption * fix(docs): replace vacuous atomicity test with inode-based verification * docs(plan): correct the apply_annotations import path dbx_core::docs re-exports collector, color, dbml, keys, relations and snapshot but NOT annotations, so apply_annotations and friends are only reachable at dbx_core::docs::annotations. Tasks 2 and 3 both used the shorter path and would not have compiled. Verified against crates/dbx-core/src/docs/mod.rs before either was dispatched. * fix(docs): truncate temp filename to stay within 255-byte filesystem limit * feat(docs): add Tauri commands for docs snapshot and annotations * docs(plan): propagate the resolve_notes_path signature to its callers Pre-flight changed resolve_notes_path to take (connection_id, docs_notes_path, data_dir) instead of a ConnectionConfig, but only Task 1 was updated. Tasks 2 and 3 still called it with the old signature and would not have compiled. The Task 2 implementer caught it and used the correct form from its dispatch note. Task 3 had the identical stale call and had not been dispatched yet. The plan's self-review checks signature consistency across tasks; this changed AFTER that review, during pre-flight, and nothing re-ran the check. * docs(plan): pin Task 4's http.ts idiom and the Tauri argument names http.ts uses a post<T>(url, body) helper at line 222; the plan said only 'match the existing idiom', which is delegating verification to someone with less context. Written out concretely now. Also records what Task 2's review flagged as unverifiable from its own diff: Tauri serialises command arguments by name, so the invoke object keys must match the Rust parameter names. That mismatch compiles cleanly on both sides and fails only when a user clicks — and it falls in the gap between two task-scoped reviews, since neither diff contains both halves. * feat(docs): add web routes for annotation load, apply and save Mirrors the Tauri commands (docs_load_annotations, docs_apply_annotations, docs_save_annotations) added in the previous task: collect returns the raw snapshot, apply is separate so the shadowedNote rule stays in one place. * docs(plan): make the i18n parity guard actually observable Every non-English locale is export default withEnglishFallback({...}) — the fallback is applied at module level, inside the locale file. Only en.ts is a bare object. So importing a locale's default export yields the ALREADY-MERGED object, and the parity test would have found every key present in every locale and passed while translations were missing. The test written to catch silent English fallback would have been silently defeated by that fallback. Task 6 now puts the new namespace in per-locale modules under locales/docs/, which the test imports directly and unwrapped. Scoped entirely to the new namespace; the existing 315 KB of keys are untouched. Step 6 also asks the implementer to demonstrate the trap: point the imports back at the merged modules and watch a missing key pass. * feat(docs): expose docs snapshot and annotations to the frontend * docs(plan): locate the duplicated table-key rule correctly in Task 8 The plan said docsIndex.ts builds the qualified table key inline. It does not — it groups by table.schema, a section key. The table key rule lives in a private qualified() in docsSearch.ts and in a hand-rolled tableKey() in DocsApp.vue, DocsSidebar.vue and WikiIndex.vue. Part 3a's final review flagged that duplication as a Minor and it was deferred. Task 8 was about to add a fifth copy, so it now extracts docsKeys.ts first and replaces the existing ones. This is the key annotations are stored under, so two call sites disagreeing attaches a note to the wrong table. * feat(docs): add pure annotation edit transforms * docs(plan): ground the group hue picker in DBX's existing swatch idiom ConnectionDialog.vue already has a swatch row — h-6 w-6 rounded-full buttons, ring-2 selected state, i18n titles. Task 7 now points at it so the new picker looks native. With an explicit warning not to copy the fill mechanism: connection colours are hex painted via Tailwind classes, group colours are hues rendered through docs.css. A naive copy introduces hex literals and fails the contract test — correctly, since a hardcoded hex cannot stay legible on both grounds, which is why groups store a hue at all. * docs(plan): make Task 10's dialog wiring concrete Five exact locations, all verified: the store ref and its export, the useDialogSources watcher, the AppDialogs import and render, and the ObjectBrowser trigger plus its context-menu entry. Records the non-obvious part: the watcher clears the source back to null after firing, and that clearing is what makes the dialog re-openable — without it, setting the same value twice does not re-trigger the watch. ObjectBrowser is the entry point rather than the connection tree, because the tree has no diagram entry either and ObjectBrowser already supplies exactly the prefills the docs dialog needs. * feat(docs): add the docs i18n namespace with a parity guard * fix(docs): ban vue-i18n from standalone-exportable docs components WarningBanner.vue used useI18n() directly, which throws with no Vue app instance -- exactly the standalone HTML export case describeWarning's translator parameter exists to avoid. Thread translate as a prop from DocsApp instead, and add vue-i18n/useI18n( to the component contract's forbidden list so the constraint is enforced, not just documented. * docs(plan): note that DocsApp already has snapshot and translate Task 6's fix added translate to DocsApp when describeWarning started taking a translator. Task 9 said to add it, which would have been a duplicate prop. It now says to add only annotations and readonly to the existing defineProps. * feat(docs): add note editor, group editor and group picker * docs(plan): give Task 10 the dialog shell from SchemaDiagramDialog Exact Dialog primitives, the get/set computed every dialog here uses to bridge the open prop, and the sizing class copied verbatim from SchemaDiagramDialog.vue:827 — the docs viewer is the same kind of full-window workspace, not a form, so it should not invent dimensions. Also states explicitly that this component lives outside src/docs/ and so may and must use useI18n(): it is what supplies the translate prop the viewer components need, since they are banned from importing vue-i18n themselves. * test(docs): guard the light-ground group tokens too * feat(docs): add the enum page and a shared table-key helper EnumPage renders an enum's values and every column declared with that type. It is read-only on purpose: AnnotationFile has no `enums` key, so an edited note would have nowhere to be saved. qualifiedTableKey moves the `schema.name` rule — bare name on schema-less engines like SQLite and MySQL — into docsKeys, where the call sites that had each copied it can share one definition. It is the key annotations are stored under, so two call sites disagreeing would attach a note to the wrong table. columnsUsingEnum matches data_type exactly rather than by substring: an enum named `state` would otherwise claim every `estado` and `statement` column. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VTBWnT4goXLA9iqDrfTPqk * refactor(docs): share one qualified table key across the viewer Six call sites had each copied the `schema.name` rule; they now import qualifiedTableKey from docsKeys instead. Two were not in the plan's list: TablePage.vue and RelationshipList.vue. RelationshipList passes a remapped FieldRef rather than a DocTable, which is why the helper takes Pick<DocTable, "schema" | "name"> — that widening is what let every call site be adapted directly instead of keeping a thin delegating wrapper. Also strengthens the columnsUsingEnum substring guard, which was not guarding anything. Its only column had type `integer`, and "integer".includes("state") is false, so replacing the exact match with includes() left all 8 tests green. Adds a `statement` column — the only type here that really contains `state` — and drops `estado` from the doc comment, since it does not. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VTBWnT4goXLA9iqDrfTPqk * feat(docs): thread editing through the viewer as emitted events DocsApp gains `annotations` and `readonly` and re-emits a DocsEdit for every change its children request. Nothing under src/docs/ persists anything, which is what keeps the directory bundleable into the standalone HTML export; a new contract guard now pins that by rejecting any component that names save/load/applyDocsAnnotations. NoteEditor is fed the MERGED snapshot note, not the local annotation layer. It renders and edits one value, so seeding it locally would show nothing for a note that came from a database comment. Writing over one shadows it, which is what noteSource and shadowedNote already exist to disclose. `annotations` is threaded for what the merge erases: `groups` carries the editable GroupAnnotation records, while snapshot.groups carries resolved TableGroups that GroupPicker and GroupEditor cannot write back to. Also makes enums reachable. EnumPage rendered nowhere and search returned enum hits that DocsSearch deliberately disabled, since enums carry no table key; they now navigate by bare name, which is how columnsUsingEnum resolves them too. Groups remain unclickable — they still have no page. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VTBWnT4goXLA9iqDrfTPqk * feat(docs): mount the documentation viewer in DBX with autosaved editing DatabaseDocsDialog hosts DocsApp outside src/docs/, which is what lets it use useI18n() and supply the `translate` prop the viewer components are banned from importing for themselves. It collects the snapshot, loads the notes file (falling back to emptyAnnotations), and holds the raw snapshot so every edit can re-derive the merged view through applyDocsAnnotations. createAutosave debounces writes and, above all, makes a failure visible: a silently swallowed write is the worst outcome here, because the user keeps typing and believes their notes are saved. It also refuses to run two writes at once — flush() clearing the timer does not stop a write already awaiting save, and two concurrent writes of the same file is the exact race that corrupted the notes file before the Rust side used a unique temp path. Both properties are pinned by tests I confirmed fail when the guard is removed. Loads and re-derivations carry a generation number so a slow response cannot overwrite a newer one, and closing flushes the debounce rather than dropping a note typed a moment earlier. Trigger mirrors the schema diagram's wiring: docsSource on connectionStore, a watch in useDialogSources that clears the source so the dialog is re-openable, an async component in AppDialogs, and openDocs in ObjectBrowser. The context entry is added at BOTH object menus — the plan named only the table one, but views offer diagram.open too and documentation is no less relevant there. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VTBWnT4goXLA9iqDrfTPqk * docs(plan): record Tasks 1-10 as done The plan carried 58 unticked boxes after ten completed tasks, so progress had to be reconstructed from the commit trail instead of read off the document. Tasks 1-7 are ticked from that commit evidence rather than from step-by-step observation — they landed in earlier sessions. Tasks 8-10 were executed and verified directly. Task 8 Step 2 stays open on purpose. `columnsUsingEnum` was already implemented and committed before that step was reached, so its failure was never observed; the exact-match guard was verified by Step 5 instead, which is what exposed that the test could not detect a substring match at all. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VTBWnT4goXLA9iqDrfTPqk * feat(docs): print snapshot warnings as prose from the CLI `dbx dbml` printed `{warning:?}`, so a skipped table surfaced as `TableSkipped { table: "public.orders", reason: "permission denied" }` — the struct shape, reading like a panic rather than like advice. The prose lives in Rust rather than in the `docs.warnings` i18n namespace because the CLI has no i18n runtime. That is the same constraint that made `describeWarning` take a translator instead of importing vue-i18n: the viewer translates, the CLI cannot, so each needs its own source for the same text. A second test asserts the rendering is not the Debug form, because reverting the CLI to `{warning:?}` is a one-character edit that still compiles and still prints something. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ro4mfGEmsbbH32WYsvxsfH * feat(docs): let a connection point its notes file at a repository `docs_notes_path` has existed on `ConnectionConfig` since Part 2 and has been read by `resolve_notes_path` since Part 3b, but nothing ever set it — so every connection silently used the app data directory default and the override was unreachable. The field is what makes schema documentation reviewable: pointing it at a file inside a repository puts notes in the same diff as the migration that changed the schema. Gated on `isSchemaAware`, matching the row above it, since documentation is a relational-only feature. A cleared field is normalised to absent rather than "" — `resolve_notes_path` treats blank as unset, but an empty string would still be persisted as though a path had been chosen. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ro4mfGEmsbbH32WYsvxsfH * docs: document database documentation and DBML export Covers opening the viewer, notes and groups, the LOCAL/database-comment rule, the notes file format and where it lives, every warning the viewer can raise, and the `dbx dbml` verb including the CI drift check. States the boundaries explicitly — relational engines only, no triggers or procedures, and DBML export is one-way — because each of those is a question the feature invites and would otherwise be answered by trying it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ro4mfGEmsbbH32WYsvxsfH --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-authored-by: t8y2 <t8y2@users.noreply.github.com>
This commit is contained in:
117 files changed
+18546
-3
No files matched your search
@@ -0,0 +1,873 @@
|
||||
use std::collections::BTreeMap;
|
||||
use std::io::Write;
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
use serde::{Deserialize, Serialize};
|
||||
|
||||
use crate::docs::keys::{column_key, fold_identifier, table_key};
|
||||
use crate::docs::{ColumnNote, NoteSource, SchemaSnapshot, SnapshotWarning, TableGroup};
|
||||
use crate::models::connection::DatabaseType;
|
||||
|
||||
/// The on-disk notes file. This IS the store — not a cache of anything.
|
||||
/// It is meant to be committed to a repository and reviewed in pull
|
||||
/// requests, so it must stay small, readable, and stable in key order.
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
#[serde(rename_all = "camelCase", deny_unknown_fields)]
|
||||
pub struct AnnotationFile {
|
||||
pub format_version: u32,
|
||||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||||
pub project: Option<ProjectAnnotation>,
|
||||
#[serde(default, skip_serializing_if = "Vec::is_empty")]
|
||||
pub groups: Vec<GroupAnnotation>,
|
||||
/// Keyed by `schema.table` (or bare `table` on schema-less engines).
|
||||
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
|
||||
pub tables: BTreeMap<String, TableAnnotation>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
#[serde(rename_all = "camelCase", deny_unknown_fields)]
|
||||
pub struct ProjectAnnotation {
|
||||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||||
pub name: Option<String>,
|
||||
/// Markdown. Becomes the documentation landing page.
|
||||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||||
pub note: Option<String>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
#[serde(rename_all = "camelCase", deny_unknown_fields)]
|
||||
pub struct GroupAnnotation {
|
||||
/// Stable slug, referenced by `TableAnnotation::group`.
|
||||
pub id: String,
|
||||
pub name: String,
|
||||
/// 0..=359. Lightness and chroma are theme-controlled, so any hue is
|
||||
/// legible on both light and dark grounds by construction.
|
||||
pub hue: u16,
|
||||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||||
pub note: Option<String>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
|
||||
#[serde(rename_all = "camelCase", deny_unknown_fields)]
|
||||
pub struct TableAnnotation {
|
||||
/// References `GroupAnnotation::id`.
|
||||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||||
pub group: Option<String>,
|
||||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||||
pub note: Option<String>,
|
||||
/// Keyed by bare column name.
|
||||
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
|
||||
pub columns: BTreeMap<String, ColumnAnnotation>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
#[serde(rename_all = "camelCase", deny_unknown_fields)]
|
||||
pub struct ColumnAnnotation {
|
||||
pub note: String,
|
||||
}
|
||||
|
||||
/// The only format version this build understands.
|
||||
pub const ANNOTATION_FORMAT_VERSION: u32 = 1;
|
||||
|
||||
/// Load the notes file.
|
||||
///
|
||||
/// An ABSENT file returns `Ok(None)` — that is the normal first-run and
|
||||
/// first-CI-run state. A MALFORMED file is a hard error: someone's prose is
|
||||
/// in there, and rendering apparently-complete documentation while silently
|
||||
/// discarding it is worse than failing.
|
||||
pub fn load_annotations(path: &Path) -> Result<Option<AnnotationFile>, String> {
|
||||
let contents = match std::fs::read_to_string(path) {
|
||||
Ok(contents) => contents,
|
||||
Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
|
||||
Err(error) => return Err(format!("Failed to read notes file {}: {error}", path.display())),
|
||||
};
|
||||
|
||||
// Read the version BEFORE full deserialization. `deny_unknown_fields`
|
||||
// would otherwise reject a future-format file with a confusing
|
||||
// "unknown field" error, never reaching the version check — defeating
|
||||
// the entire purpose of having a version field.
|
||||
let probe: serde_json::Value = serde_json::from_str(&contents)
|
||||
.map_err(|error| format!("Failed to parse notes file {}: {error}", path.display()))?;
|
||||
|
||||
match probe.get("formatVersion").and_then(serde_json::Value::as_u64) {
|
||||
Some(version) if version == u64::from(ANNOTATION_FORMAT_VERSION) => {}
|
||||
Some(version) => {
|
||||
return Err(format!(
|
||||
"Notes file {} has formatVersion {version}, but this build understands {}.",
|
||||
path.display(),
|
||||
ANNOTATION_FORMAT_VERSION
|
||||
))
|
||||
}
|
||||
None => return Err(format!("Notes file {} is missing formatVersion.", path.display())),
|
||||
}
|
||||
|
||||
let parsed: AnnotationFile = serde_json::from_value(probe)
|
||||
.map_err(|error| format!("Failed to parse notes file {}: {error}", path.display()))?;
|
||||
|
||||
Ok(Some(parsed))
|
||||
}
|
||||
|
||||
/// A unique sibling temp path for an atomic save.
|
||||
///
|
||||
/// MUST be unique per call: a temp name derived from the target alone is
|
||||
/// shared by every concurrent writer, so two saves interleave their bytes into
|
||||
/// one file and the last rename publishes the mixture. MUST also be a sibling
|
||||
/// — rename is only atomic within a filesystem.
|
||||
///
|
||||
/// The base name is truncated so the whole component stays within the 255-byte
|
||||
/// limit most filesystems enforce on a single path component. The wrapper
|
||||
/// costs 14 bytes, so a long-but-valid target name would otherwise make every
|
||||
/// save fail with ENAMETOOLONG — a regression against the previous 4-byte
|
||||
/// `.tmp` suffix. Truncating the base is safe because uniqueness comes from
|
||||
/// the uuid, not from the name.
|
||||
fn temp_save_path(path: &Path) -> PathBuf {
|
||||
/// Most filesystems cap one path component at 255 bytes.
|
||||
const MAX_COMPONENT: usize = 255;
|
||||
/// `.` + `.` + 8 hex + `.tmp`
|
||||
const WRAPPER: usize = 14;
|
||||
|
||||
let name = path.file_name().map(|value| value.to_string_lossy().into_owned()).unwrap_or_default();
|
||||
let budget = MAX_COMPONENT - WRAPPER;
|
||||
|
||||
// Truncate on a char boundary — slicing a String by bytes can split a
|
||||
// multi-byte character and panic.
|
||||
let mut used = 0usize;
|
||||
let trimmed: String = name
|
||||
.chars()
|
||||
.take_while(|character| {
|
||||
used += character.len_utf8();
|
||||
used <= budget
|
||||
})
|
||||
.collect();
|
||||
|
||||
let unique = uuid::Uuid::new_v4().simple().to_string();
|
||||
path.with_file_name(format!(".{trimmed}.{}.tmp", &unique[..8]))
|
||||
}
|
||||
|
||||
/// Write the notes file atomically.
|
||||
///
|
||||
/// A partial write destroys prose a human typed, and `load_annotations`
|
||||
/// errors loudly on malformed JSON — so a torn write becomes "your notes file
|
||||
/// is corrupt" the next time the viewer opens. Write a sibling temp file,
|
||||
/// flush it to disk, then rename: rename within a directory is atomic on
|
||||
/// every platform DBX targets.
|
||||
pub fn save_annotations(path: &Path, annotations: &AnnotationFile) -> Result<(), String> {
|
||||
let json =
|
||||
serde_json::to_string_pretty(annotations).map_err(|error| format!("Failed to serialize notes: {error}"))?;
|
||||
|
||||
if let Some(parent) = path.parent() {
|
||||
std::fs::create_dir_all(parent).map_err(|error| format!("Failed to create {}: {error}", parent.display()))?;
|
||||
}
|
||||
|
||||
let temp = temp_save_path(path);
|
||||
{
|
||||
let mut file =
|
||||
std::fs::File::create(&temp).map_err(|error| format!("Failed to create {}: {error}", temp.display()))?;
|
||||
file.write_all(json.as_bytes()).map_err(|error| {
|
||||
let _ = std::fs::remove_file(&temp);
|
||||
format!("Failed to write {}: {error}", temp.display())
|
||||
})?;
|
||||
file.sync_all().map_err(|error| {
|
||||
let _ = std::fs::remove_file(&temp);
|
||||
format!("Failed to flush {}: {error}", temp.display())
|
||||
})?;
|
||||
}
|
||||
|
||||
std::fs::rename(&temp, path).map_err(|error| {
|
||||
let _ = std::fs::remove_file(&temp);
|
||||
format!("Failed to replace {}: {error}", path.display())
|
||||
})
|
||||
}
|
||||
|
||||
/// Where a connection's notes file lives.
|
||||
///
|
||||
/// An explicit `docs_notes_path` wins — that is the entire point of the field.
|
||||
/// Pointing it at a file inside a repository is what lets schema documentation
|
||||
/// be reviewed in pull requests. Otherwise the file lives under the app data
|
||||
/// directory keyed by connection id, so the feature works with no setup.
|
||||
///
|
||||
/// Takes the two fields it needs rather than a whole `ConnectionConfig`:
|
||||
/// that struct has no `Default` and ~60 fields, so passing it would force
|
||||
/// every test to build a literal full of values the function never reads.
|
||||
/// `data_dir` is a parameter because `dbx-core` cannot reach the caller's
|
||||
/// data directory on its own.
|
||||
pub fn resolve_notes_path(connection_id: &str, docs_notes_path: Option<&str>, data_dir: &Path) -> PathBuf {
|
||||
if let Some(path) = docs_notes_path.map(str::trim).filter(|value| !value.is_empty()) {
|
||||
return PathBuf::from(path);
|
||||
}
|
||||
data_dir.join("docs-notes").join(format!("{connection_id}.json"))
|
||||
}
|
||||
|
||||
/// Merge a notes file into a collected snapshot.
|
||||
///
|
||||
/// Precedence is `local ?? database_comment`. When a local note shadows a
|
||||
/// database comment the comment is kept in `shadowed_note`, so a later
|
||||
/// `COMMENT ON` improvement stays visible rather than being silently hidden.
|
||||
pub fn apply_annotations(snapshot: &mut SchemaSnapshot, annotations: &AnnotationFile, db_type: DatabaseType) {
|
||||
if let Some(project) = annotations.project.as_ref() {
|
||||
if let Some(name) = project.name.as_deref().filter(|value| !value.trim().is_empty()) {
|
||||
snapshot.project.name = name.to_string();
|
||||
}
|
||||
if project.note.is_some() {
|
||||
snapshot.project.note = project.note.clone();
|
||||
}
|
||||
}
|
||||
|
||||
let known_groups: std::collections::HashSet<&str> =
|
||||
annotations.groups.iter().map(|group| group.id.as_str()).collect();
|
||||
|
||||
let mut seen_group_ids = std::collections::HashSet::new();
|
||||
snapshot.groups = annotations
|
||||
.groups
|
||||
.iter()
|
||||
// A duplicate id would emit two TableGroup blocks with the same
|
||||
// name, which is invalid DBML. First occurrence wins.
|
||||
.filter(|group| seen_group_ids.insert(group.id.as_str()))
|
||||
.map(|group| TableGroup {
|
||||
id: group.id.clone(),
|
||||
name: group.name.clone(),
|
||||
hue: group.hue,
|
||||
note: group.note.clone(),
|
||||
})
|
||||
.collect();
|
||||
|
||||
for table in &mut snapshot.tables {
|
||||
let key = table_key(db_type, table.schema.as_deref(), &table.name);
|
||||
let Some(annotation) = annotations.tables.get(&key) else { continue };
|
||||
|
||||
if let Some(note) = annotation.note.as_deref().filter(|value| !value.trim().is_empty()) {
|
||||
// Preserve whatever the database said before overwriting it.
|
||||
if matches!(table.note_source, NoteSource::Database) {
|
||||
table.shadowed_note = table.note.clone();
|
||||
}
|
||||
table.note = Some(note.to_string());
|
||||
table.note_source = NoteSource::Local;
|
||||
}
|
||||
|
||||
// A group reference that names no defined group is dropped rather
|
||||
// than assigned — a dangling id would render an empty group header.
|
||||
table.group_id = annotation.group.as_deref().filter(|id| known_groups.contains(id)).map(ToOwned::to_owned);
|
||||
|
||||
for column in &table.columns {
|
||||
let column_fold = fold_identifier(db_type, &column.name);
|
||||
let annotated = annotation.columns.iter().find(|(name, _)| fold_identifier(db_type, name) == column_fold);
|
||||
|
||||
let Some((_, column_annotation)) = annotated else { continue };
|
||||
if column_annotation.note.trim().is_empty() {
|
||||
continue;
|
||||
}
|
||||
|
||||
table.column_notes.insert(
|
||||
column.name.clone(),
|
||||
ColumnNote {
|
||||
note: column_annotation.note.clone(),
|
||||
source: NoteSource::Local,
|
||||
shadowed: column.comment.clone().filter(|value| !value.trim().is_empty()),
|
||||
},
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
let orphans = detect_orphans(snapshot, annotations, db_type);
|
||||
if !orphans.is_empty() {
|
||||
snapshot.warnings.push(SnapshotWarning::OrphanedNotes { count: orphans.len() });
|
||||
}
|
||||
}
|
||||
|
||||
/// Annotation keys whose target no longer exists in the collected schema.
|
||||
///
|
||||
/// Returns fully-qualified keys, sorted, so the caller can list them for a
|
||||
/// human to re-map. This function NEVER mutates the notes file — user prose
|
||||
/// is only ever removed by an explicit human action.
|
||||
///
|
||||
/// Suggestions for where a renamed target went are deliberately absent:
|
||||
/// producing them requires the OLD schema to diff against, and the notes
|
||||
/// file stores prose only. That becomes possible once snapshot history
|
||||
/// exists (see the spec's deferred versioning seam).
|
||||
pub fn detect_orphans(snapshot: &SchemaSnapshot, annotations: &AnnotationFile, db_type: DatabaseType) -> Vec<String> {
|
||||
use std::collections::HashSet;
|
||||
|
||||
let live_tables: HashSet<String> =
|
||||
snapshot.tables.iter().map(|table| table_key(db_type, table.schema.as_deref(), &table.name)).collect();
|
||||
|
||||
let live_columns: HashSet<String> = snapshot
|
||||
.tables
|
||||
.iter()
|
||||
.flat_map(|table| {
|
||||
table
|
||||
.columns
|
||||
.iter()
|
||||
.map(move |column| column_key(db_type, table.schema.as_deref(), &table.name, &column.name))
|
||||
})
|
||||
.collect();
|
||||
|
||||
let mut orphans = Vec::new();
|
||||
|
||||
for (key, annotation) in &annotations.tables {
|
||||
let folded_table = fold_key(db_type, key);
|
||||
if !live_tables.contains(&folded_table) {
|
||||
orphans.push(folded_table);
|
||||
continue;
|
||||
}
|
||||
for column in annotation.columns.keys() {
|
||||
let folded_column = format!("{folded_table}.{}", fold_identifier(db_type, column));
|
||||
if !live_columns.contains(&folded_column) {
|
||||
orphans.push(folded_column);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
orphans.sort();
|
||||
orphans
|
||||
}
|
||||
|
||||
/// Fold an already-dotted key (e.g. `Core.Orders`) segment by segment.
|
||||
fn fold_key(db_type: DatabaseType, key: &str) -> String {
|
||||
key.split('.').map(|segment| fold_identifier(db_type, segment)).collect::<Vec<_>>().join(".")
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
const SAMPLE: &str = r##"{
|
||||
"formatVersion": 1,
|
||||
"project": { "name": "Ecommerce", "note": "# Overview" },
|
||||
"groups": [
|
||||
{ "id": "order-management", "name": "Order Management", "hue": 28, "note": "Checkout to handoff." }
|
||||
],
|
||||
"tables": {
|
||||
"core.orders": {
|
||||
"group": "order-management",
|
||||
"note": "One row per checkout.",
|
||||
"columns": { "status": { "note": "State machine." } }
|
||||
}
|
||||
}
|
||||
}"##;
|
||||
|
||||
#[test]
|
||||
fn parses_a_complete_notes_file() {
|
||||
let parsed: AnnotationFile = serde_json::from_str(SAMPLE).expect("parse");
|
||||
|
||||
assert_eq!(parsed.format_version, 1);
|
||||
assert_eq!(parsed.project.as_ref().unwrap().name.as_deref(), Some("Ecommerce"));
|
||||
assert_eq!(parsed.groups.len(), 1);
|
||||
assert_eq!(parsed.groups[0].hue, 28);
|
||||
assert_eq!(parsed.tables.len(), 1);
|
||||
|
||||
let orders = parsed.tables.get("core.orders").expect("orders");
|
||||
assert_eq!(orders.group.as_deref(), Some("order-management"));
|
||||
assert_eq!(orders.note.as_deref(), Some("One row per checkout."));
|
||||
assert_eq!(orders.columns.get("status").unwrap().note, "State machine.");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_minimal_file_needs_only_the_format_version() {
|
||||
let parsed: AnnotationFile = serde_json::from_str(r#"{"formatVersion": 1}"#).expect("parse");
|
||||
assert!(parsed.tables.is_empty());
|
||||
assert!(parsed.groups.is_empty());
|
||||
assert!(parsed.project.is_none());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn round_trips_through_json() {
|
||||
let parsed: AnnotationFile = serde_json::from_str(SAMPLE).expect("parse");
|
||||
let written = serde_json::to_string(&parsed).expect("serialize");
|
||||
let reparsed: AnnotationFile = serde_json::from_str(&written).expect("reparse");
|
||||
|
||||
// Every field in SAMPLE must survive a write/read cycle. Asserting
|
||||
// only a count here would pass against a model that silently drops
|
||||
// fields on write via a wrong skip_serializing_if predicate.
|
||||
assert_eq!(reparsed.format_version, 1);
|
||||
|
||||
let project = reparsed.project.as_ref().expect("project survived");
|
||||
assert_eq!(project.name.as_deref(), Some("Ecommerce"));
|
||||
assert_eq!(project.note.as_deref(), Some("# Overview"));
|
||||
|
||||
assert_eq!(reparsed.groups.len(), 1);
|
||||
let group = &reparsed.groups[0];
|
||||
assert_eq!(group.id, "order-management");
|
||||
assert_eq!(group.name, "Order Management");
|
||||
assert_eq!(group.hue, 28);
|
||||
assert_eq!(group.note.as_deref(), Some("Checkout to handoff."));
|
||||
|
||||
assert_eq!(reparsed.tables.len(), 1);
|
||||
let orders = reparsed.tables.get("core.orders").expect("orders survived");
|
||||
assert_eq!(orders.group.as_deref(), Some("order-management"));
|
||||
assert_eq!(orders.note.as_deref(), Some("One row per checkout."));
|
||||
assert_eq!(orders.columns.len(), 1);
|
||||
assert_eq!(orders.columns.get("status").expect("column survived").note, "State machine.");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn rejects_a_file_with_an_unknown_top_level_field() {
|
||||
// Typos in a hand-edited file must not be silently ignored — a
|
||||
// misspelled "tabels" key would otherwise discard every note in it.
|
||||
let result: Result<AnnotationFile, _> = serde_json::from_str(r#"{"formatVersion": 1, "tabels": {}}"#);
|
||||
assert!(result.is_err(), "unknown fields must be rejected");
|
||||
}
|
||||
|
||||
fn temp_notes(contents: &str) -> std::path::PathBuf {
|
||||
let path = std::env::temp_dir().join(format!("dbx-notes-test-{}.json", uuid::Uuid::new_v4()));
|
||||
std::fs::write(&path, contents).expect("write temp notes file");
|
||||
path
|
||||
}
|
||||
|
||||
fn temp_case_dir(label: &str) -> std::path::PathBuf {
|
||||
let dir = std::env::temp_dir().join(format!("dbx-notes-{label}-{}", uuid::Uuid::new_v4().simple()));
|
||||
std::fs::create_dir_all(&dir).expect("create temp dir");
|
||||
dir
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn save_then_load_round_trips() {
|
||||
let dir = temp_case_dir("round-trip");
|
||||
let path = dir.join("notes.json");
|
||||
let file = AnnotationFile {
|
||||
format_version: 1,
|
||||
project: Some(ProjectAnnotation { name: Some("P".into()), note: Some("hello".into()) }),
|
||||
groups: vec![GroupAnnotation { id: "g".into(), name: "G".into(), hue: 200, note: None }],
|
||||
tables: BTreeMap::from([(
|
||||
"public.t".to_string(),
|
||||
TableAnnotation { group: Some("g".into()), note: Some("n".into()), columns: BTreeMap::new() },
|
||||
)]),
|
||||
};
|
||||
|
||||
save_annotations(&path, &file).expect("save");
|
||||
let loaded = load_annotations(&path).expect("load").expect("present");
|
||||
|
||||
assert_eq!(loaded.format_version, 1);
|
||||
assert_eq!(loaded.groups[0].hue, 200);
|
||||
assert_eq!(loaded.tables["public.t"].note.as_deref(), Some("n"));
|
||||
assert_eq!(loaded.project.and_then(|p| p.note).as_deref(), Some("hello"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn save_creates_missing_parent_directories() {
|
||||
let dir = temp_case_dir("nested");
|
||||
let path = dir.join("nested").join("deeper").join("notes.json");
|
||||
let file = AnnotationFile { format_version: 1, project: None, groups: Vec::new(), tables: BTreeMap::new() };
|
||||
save_annotations(&path, &file).expect("save into a new directory");
|
||||
assert!(path.exists());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn save_leaves_no_temp_file_behind() {
|
||||
// A stray notes.json.tmp would be picked up by nothing, but it means
|
||||
// the rename did not happen and the write was not atomic.
|
||||
let dir = temp_case_dir("no-temp-left");
|
||||
let path = dir.join("notes.json");
|
||||
let file = AnnotationFile { format_version: 1, project: None, groups: Vec::new(), tables: BTreeMap::new() };
|
||||
save_annotations(&path, &file).expect("save");
|
||||
|
||||
let leftovers: Vec<_> = std::fs::read_dir(&dir)
|
||||
.expect("read_dir")
|
||||
.filter_map(Result::ok)
|
||||
.map(|entry| entry.file_name().to_string_lossy().into_owned())
|
||||
.filter(|name| name.ends_with(".tmp"))
|
||||
.collect();
|
||||
assert!(leftovers.is_empty(), "temp files left behind: {leftovers:?}");
|
||||
}
|
||||
|
||||
#[cfg(unix)]
|
||||
#[test]
|
||||
fn a_save_replaces_the_file_by_rename_rather_than_writing_in_place() {
|
||||
// The whole point of temp-and-rename. A reader either sees the old
|
||||
// file or the new one, never a half-written mix — load_annotations
|
||||
// errors loudly on malformed JSON, so a torn write reads as "your
|
||||
// notes file is corrupt".
|
||||
//
|
||||
// Writing in place keeps the inode; renaming over the target changes
|
||||
// it. That is the difference, and it is observable without having to
|
||||
// make a write fail halfway.
|
||||
use std::os::unix::fs::MetadataExt;
|
||||
|
||||
let dir = temp_case_dir("atomic-replace");
|
||||
let path = dir.join("notes.json");
|
||||
let first = AnnotationFile {
|
||||
format_version: 1,
|
||||
project: None,
|
||||
groups: Vec::new(),
|
||||
tables: BTreeMap::from([(
|
||||
"public.a".to_string(),
|
||||
TableAnnotation { group: None, note: Some("first".into()), columns: BTreeMap::new() },
|
||||
)]),
|
||||
};
|
||||
save_annotations(&path, &first).expect("first save");
|
||||
let before = std::fs::metadata(&path).expect("metadata").ino();
|
||||
|
||||
let second = AnnotationFile {
|
||||
format_version: 1,
|
||||
project: None,
|
||||
groups: Vec::new(),
|
||||
tables: BTreeMap::from([(
|
||||
"public.b".to_string(),
|
||||
TableAnnotation { group: None, note: Some("second".into()), columns: BTreeMap::new() },
|
||||
)]),
|
||||
};
|
||||
save_annotations(&path, &second).expect("second save");
|
||||
let after = std::fs::metadata(&path).expect("metadata").ino();
|
||||
|
||||
assert_ne!(before, after, "an atomic save replaces the file by rename, never writes in place");
|
||||
let loaded = load_annotations(&path).expect("load").expect("present");
|
||||
assert_eq!(loaded.tables["public.b"].note.as_deref(), Some("second"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn an_explicit_notes_path_wins_over_the_default() {
|
||||
let resolved = resolve_notes_path("conn-1", Some("/tmp/team/schema-notes.json"), std::path::Path::new("/data"));
|
||||
assert_eq!(resolved, std::path::PathBuf::from("/tmp/team/schema-notes.json"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn the_default_notes_path_is_keyed_by_connection_id() {
|
||||
let resolved = resolve_notes_path("conn-1", None, std::path::Path::new("/data"));
|
||||
assert_eq!(resolved, std::path::PathBuf::from("/data/docs-notes/conn-1.json"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_blank_notes_path_falls_back_to_the_default() {
|
||||
// An empty string in the config is a cleared field, not a path to a
|
||||
// file named "". Treating it as explicit would resolve to garbage.
|
||||
let resolved = resolve_notes_path("conn-1", Some(" "), std::path::Path::new("/data"));
|
||||
assert_eq!(resolved, std::path::PathBuf::from("/data/docs-notes/conn-1.json"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn each_save_uses_a_distinct_temp_path() {
|
||||
// A temp name derived from the target alone is shared by every
|
||||
// concurrent writer, so two saves interleave into one file and the
|
||||
// last rename publishes the mixture.
|
||||
let target = std::path::Path::new("/data/docs-notes/conn-1.json");
|
||||
let first = temp_save_path(target);
|
||||
let second = temp_save_path(target);
|
||||
assert_ne!(first, second);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn the_temp_path_is_a_sibling_of_the_target() {
|
||||
// rename is only atomic within one filesystem. A temp file in /tmp
|
||||
// could be on a different mount, making the rename a copy.
|
||||
let target = std::path::Path::new("/data/docs-notes/conn-1.json");
|
||||
assert_eq!(temp_save_path(target).parent(), target.parent());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_failed_write_leaves_no_temp_file_in_the_target_directory() {
|
||||
// docs_notes_path is meant to point into a user's repository, so
|
||||
// debris from a failed save shows up in their git status.
|
||||
let dir = temp_case_dir("failed-write-debris");
|
||||
let path = dir.join("notes.json");
|
||||
// A directory at the target makes the rename fail after the temp file
|
||||
// has been written.
|
||||
std::fs::create_dir(&path).expect("block the target path");
|
||||
let file = AnnotationFile { format_version: 1, project: None, groups: Vec::new(), tables: BTreeMap::new() };
|
||||
|
||||
let result = save_annotations(&path, &file);
|
||||
assert!(result.is_err(), "save must fail when the target is a directory");
|
||||
|
||||
let leftovers: Vec<_> = std::fs::read_dir(&dir)
|
||||
.expect("read_dir")
|
||||
.filter_map(Result::ok)
|
||||
.map(|entry| entry.file_name().to_string_lossy().into_owned())
|
||||
.filter(|name| name.ends_with(".tmp"))
|
||||
.collect();
|
||||
assert!(leftovers.is_empty(), "temp files left behind: {leftovers:?}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_long_target_name_still_yields_a_usable_temp_component() {
|
||||
// The wrapper costs 14 bytes. Without a budget, a 245-byte name makes
|
||||
// a 259-byte component and every save fails with ENAMETOOLONG — a
|
||||
// regression against the old 4-byte `.tmp` suffix.
|
||||
let name = format!("{}.json", "a".repeat(240));
|
||||
let target = std::path::Path::new("/data").join(&name);
|
||||
let temp = temp_save_path(&target);
|
||||
let component = temp.file_name().expect("file name").to_string_lossy().len();
|
||||
assert!(component <= 255, "temp component is {component} bytes: {temp:?}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_long_multibyte_target_name_is_truncated_on_a_char_boundary() {
|
||||
// Slicing a String by bytes can split a multi-byte character and
|
||||
// panic. This name is 3 bytes per character.
|
||||
let name = format!("{}.json", "é".repeat(200));
|
||||
let target = std::path::Path::new("/data").join(&name);
|
||||
let temp = temp_save_path(&target); // must not panic
|
||||
let component = temp.file_name().expect("file name").to_string_lossy().len();
|
||||
assert!(component <= 255, "temp component is {component} bytes");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_long_target_name_still_saves_and_loads() {
|
||||
// End to end: the budget is only useful if the save actually works.
|
||||
let dir = temp_case_dir("long-name");
|
||||
let path = dir.join(format!("{}.json", "a".repeat(200)));
|
||||
let file = AnnotationFile { format_version: 1, project: None, groups: Vec::new(), tables: BTreeMap::new() };
|
||||
save_annotations(&path, &file).expect("save with a long name");
|
||||
assert!(load_annotations(&path).expect("load").is_some());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn an_absent_file_is_not_an_error() {
|
||||
let missing = std::path::Path::new("/nonexistent/dbx-notes-does-not-exist.json");
|
||||
assert!(matches!(load_annotations(missing), Ok(None)));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_valid_file_loads() {
|
||||
let path = temp_notes(SAMPLE);
|
||||
let loaded = load_annotations(&path);
|
||||
let _ = std::fs::remove_file(&path);
|
||||
let loaded = loaded.expect("load").expect("some");
|
||||
assert_eq!(loaded.tables.len(), 1);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_malformed_file_is_a_hard_error_naming_the_path() {
|
||||
let path = temp_notes("{ this is not json");
|
||||
let error = load_annotations(&path);
|
||||
let _ = std::fs::remove_file(&path);
|
||||
let error = error.expect_err("must fail");
|
||||
assert!(error.contains(&path.display().to_string()), "error must name the file: {error}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn an_unsupported_format_version_is_rejected() {
|
||||
let path = temp_notes(r#"{"formatVersion": 99}"#);
|
||||
let error = load_annotations(&path);
|
||||
let _ = std::fs::remove_file(&path);
|
||||
let error = error.expect_err("must fail");
|
||||
assert!(error.contains("99"), "error must name the version: {error}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_future_format_version_reports_the_version_not_an_unknown_field() {
|
||||
// deny_unknown_fields must NOT pre-empt the version check — a v1
|
||||
// build reading a v2 file has to say so, or the version field is
|
||||
// useless exactly when it is needed.
|
||||
let path = temp_notes(r#"{"formatVersion": 2, "someNewField": {"a": 1}}"#);
|
||||
let error = load_annotations(&path);
|
||||
let _ = std::fs::remove_file(&path);
|
||||
let error = error.expect_err("must fail");
|
||||
|
||||
assert!(error.contains("formatVersion 2"), "should name the version, got: {error}");
|
||||
assert!(!error.contains("unknown field"), "should not surface a raw serde error, got: {error}");
|
||||
}
|
||||
|
||||
use crate::docs::{DocTable, NoteSource, ProjectMeta, SchemaSnapshot, TableKind};
|
||||
use crate::models::connection::DatabaseType;
|
||||
|
||||
fn snapshot_with(tables: Vec<DocTable>) -> SchemaSnapshot {
|
||||
SchemaSnapshot {
|
||||
format_version: 1,
|
||||
project: ProjectMeta {
|
||||
name: "conn".to_string(),
|
||||
database_type: "postgres".to_string(),
|
||||
database: None,
|
||||
schemas: vec!["core".to_string()],
|
||||
generated_at: String::new(),
|
||||
note: None,
|
||||
},
|
||||
tables,
|
||||
relationships: vec![],
|
||||
groups: vec![],
|
||||
enums: vec![],
|
||||
warnings: vec![],
|
||||
}
|
||||
}
|
||||
|
||||
fn table_named(schema: &str, name: &str, comment: Option<&str>) -> DocTable {
|
||||
DocTable {
|
||||
schema: Some(schema.to_string()),
|
||||
name: name.to_string(),
|
||||
kind: TableKind::Table,
|
||||
columns: vec![],
|
||||
indexes: vec![],
|
||||
foreign_keys: vec![],
|
||||
group_id: None,
|
||||
note: comment.map(ToOwned::to_owned),
|
||||
note_source: if comment.is_some() { NoteSource::Database } else { NoteSource::None },
|
||||
shadowed_note: None,
|
||||
column_notes: BTreeMap::new(),
|
||||
estimated_rows: None,
|
||||
view_definition: None,
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_local_note_shadows_the_database_comment_and_preserves_it() {
|
||||
let mut snapshot = snapshot_with(vec![table_named("core", "orders", Some("Old DB comment."))]);
|
||||
let annotations: AnnotationFile = serde_json::from_str(SAMPLE).expect("parse");
|
||||
|
||||
apply_annotations(&mut snapshot, &annotations, DatabaseType::Postgres);
|
||||
|
||||
let table = &snapshot.tables[0];
|
||||
assert_eq!(table.note.as_deref(), Some("One row per checkout."));
|
||||
assert_eq!(table.note_source, NoteSource::Local);
|
||||
assert_eq!(table.shadowed_note.as_deref(), Some("Old DB comment."));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_database_comment_survives_when_there_is_no_local_note() {
|
||||
let mut snapshot = snapshot_with(vec![table_named("core", "users", Some("From the database."))]);
|
||||
let annotations: AnnotationFile = serde_json::from_str(SAMPLE).expect("parse");
|
||||
|
||||
apply_annotations(&mut snapshot, &annotations, DatabaseType::Postgres);
|
||||
|
||||
let table = &snapshot.tables[0];
|
||||
assert_eq!(table.note.as_deref(), Some("From the database."));
|
||||
assert_eq!(table.note_source, NoteSource::Database);
|
||||
assert_eq!(table.shadowed_note, None);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn keys_match_case_insensitively_on_postgres() {
|
||||
// The notes file says "core.orders"; the live schema reports "Core"/"Orders".
|
||||
let mut snapshot = snapshot_with(vec![table_named("Core", "Orders", None)]);
|
||||
let annotations: AnnotationFile = serde_json::from_str(SAMPLE).expect("parse");
|
||||
|
||||
apply_annotations(&mut snapshot, &annotations, DatabaseType::Postgres);
|
||||
|
||||
assert_eq!(snapshot.tables[0].note.as_deref(), Some("One row per checkout."));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn column_notes_are_applied_and_marked_local() {
|
||||
let mut table = table_named("core", "orders", None);
|
||||
table.columns.push(crate::types::ColumnInfo {
|
||||
name: "status".to_string(),
|
||||
data_type: "text".to_string(),
|
||||
..Default::default()
|
||||
});
|
||||
let mut snapshot = snapshot_with(vec![table]);
|
||||
let annotations: AnnotationFile = serde_json::from_str(SAMPLE).expect("parse");
|
||||
|
||||
apply_annotations(&mut snapshot, &annotations, DatabaseType::Postgres);
|
||||
|
||||
let note = snapshot.tables[0].column_notes.get("status").expect("column note");
|
||||
assert_eq!(note.note, "State machine.");
|
||||
assert_eq!(note.source, NoteSource::Local);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn the_project_note_and_name_are_applied() {
|
||||
let mut snapshot = snapshot_with(vec![]);
|
||||
let annotations: AnnotationFile = serde_json::from_str(SAMPLE).expect("parse");
|
||||
|
||||
apply_annotations(&mut snapshot, &annotations, DatabaseType::Postgres);
|
||||
|
||||
assert_eq!(snapshot.project.name, "Ecommerce");
|
||||
assert_eq!(snapshot.project.note.as_deref(), Some("# Overview"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn groups_are_copied_and_membership_is_assigned() {
|
||||
let mut snapshot = snapshot_with(vec![table_named("core", "orders", None)]);
|
||||
let annotations: AnnotationFile = serde_json::from_str(SAMPLE).expect("parse");
|
||||
|
||||
apply_annotations(&mut snapshot, &annotations, DatabaseType::Postgres);
|
||||
|
||||
assert_eq!(snapshot.groups.len(), 1);
|
||||
assert_eq!(snapshot.groups[0].id, "order-management");
|
||||
assert_eq!(snapshot.groups[0].hue, 28);
|
||||
assert_eq!(snapshot.tables[0].group_id.as_deref(), Some("order-management"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_table_referencing_an_undefined_group_is_left_ungrouped() {
|
||||
let mut snapshot = snapshot_with(vec![table_named("core", "orders", None)]);
|
||||
let mut annotations: AnnotationFile = serde_json::from_str(SAMPLE).expect("parse");
|
||||
annotations.groups.clear();
|
||||
|
||||
apply_annotations(&mut snapshot, &annotations, DatabaseType::Postgres);
|
||||
|
||||
assert_eq!(snapshot.tables[0].group_id, None, "a dangling group reference must not be assigned");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn duplicate_group_ids_collapse_to_one_entry() {
|
||||
// Two TableGroup blocks sharing an id is invalid DBML.
|
||||
let mut snapshot = snapshot_with(vec![table_named("core", "orders", None)]);
|
||||
let mut annotations: AnnotationFile = serde_json::from_str(SAMPLE).expect("parse");
|
||||
let mut dup = annotations.groups[0].clone();
|
||||
dup.name = "Duplicate".to_string();
|
||||
annotations.groups.push(dup);
|
||||
|
||||
apply_annotations(&mut snapshot, &annotations, DatabaseType::Postgres);
|
||||
|
||||
assert_eq!(snapshot.groups.len(), 1, "duplicate ids must collapse");
|
||||
assert_eq!(snapshot.groups[0].name, "Order Management", "first occurrence wins");
|
||||
}
|
||||
|
||||
use crate::docs::SnapshotWarning;
|
||||
|
||||
#[test]
|
||||
fn a_note_for_a_missing_table_is_reported_as_orphaned() {
|
||||
// The notes file describes core.orders; the schema no longer has it.
|
||||
let mut snapshot = snapshot_with(vec![table_named("core", "customers", None)]);
|
||||
let annotations: AnnotationFile = serde_json::from_str(SAMPLE).expect("parse");
|
||||
|
||||
let orphans = detect_orphans(&snapshot, &annotations, DatabaseType::Postgres);
|
||||
assert_eq!(orphans, vec!["core.orders".to_string()]);
|
||||
|
||||
apply_annotations(&mut snapshot, &annotations, DatabaseType::Postgres);
|
||||
let orphan_warnings: Vec<&SnapshotWarning> = snapshot
|
||||
.warnings
|
||||
.iter()
|
||||
.filter(|warning| matches!(warning, SnapshotWarning::OrphanedNotes { .. }))
|
||||
.collect();
|
||||
assert_eq!(orphan_warnings.len(), 1);
|
||||
match orphan_warnings[0] {
|
||||
SnapshotWarning::OrphanedNotes { count } => assert_eq!(*count, 1),
|
||||
other => panic!("unexpected: {other:?}"),
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_note_for_a_missing_column_is_reported_as_orphaned() {
|
||||
// The table exists but no longer has the annotated column.
|
||||
let mut table = table_named("core", "orders", None);
|
||||
table.columns.push(crate::types::ColumnInfo {
|
||||
name: "id".to_string(),
|
||||
data_type: "integer".to_string(),
|
||||
..Default::default()
|
||||
});
|
||||
let snapshot = snapshot_with(vec![table]);
|
||||
let annotations: AnnotationFile = serde_json::from_str(SAMPLE).expect("parse");
|
||||
|
||||
let orphans = detect_orphans(&snapshot, &annotations, DatabaseType::Postgres);
|
||||
assert_eq!(orphans, vec!["core.orders.status".to_string()]);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn nothing_is_orphaned_when_everything_matches() {
|
||||
let mut table = table_named("core", "orders", None);
|
||||
table.columns.push(crate::types::ColumnInfo {
|
||||
name: "status".to_string(),
|
||||
data_type: "text".to_string(),
|
||||
..Default::default()
|
||||
});
|
||||
let mut snapshot = snapshot_with(vec![table]);
|
||||
let annotations: AnnotationFile = serde_json::from_str(SAMPLE).expect("parse");
|
||||
|
||||
assert!(detect_orphans(&snapshot, &annotations, DatabaseType::Postgres).is_empty());
|
||||
|
||||
apply_annotations(&mut snapshot, &annotations, DatabaseType::Postgres);
|
||||
assert!(
|
||||
!snapshot.warnings.iter().any(|w| matches!(w, SnapshotWarning::OrphanedNotes { .. })),
|
||||
"no orphan warning when everything matches"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn orphan_detection_never_removes_anything_from_the_file() {
|
||||
let snapshot = snapshot_with(vec![]);
|
||||
let annotations: AnnotationFile = serde_json::from_str(SAMPLE).expect("parse");
|
||||
let before = annotations.tables.len();
|
||||
|
||||
let _ = detect_orphans(&snapshot, &annotations, DatabaseType::Postgres);
|
||||
|
||||
assert_eq!(annotations.tables.len(), before, "detection must not mutate the file");
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,549 @@
|
||||
use std::collections::{BTreeMap, HashSet};
|
||||
use std::sync::atomic::{AtomicBool, Ordering};
|
||||
|
||||
use futures::stream::{self, StreamExt};
|
||||
|
||||
use crate::connection::AppState;
|
||||
use crate::docs::dbml::{enum_type_name, is_inline_enum_spelling};
|
||||
use crate::docs::{
|
||||
build_relationships, DocEnum, DocTable, NoteSource, ProjectMeta, Relationship, SchemaSnapshot, SnapshotWarning,
|
||||
TableKind,
|
||||
};
|
||||
use crate::models::connection::ConnectionConfig;
|
||||
use crate::schema;
|
||||
use crate::table_structure_sql::{database_type_label, supports_comments, supports_foreign_keys};
|
||||
use crate::types::ColumnInfo;
|
||||
|
||||
/// Concurrent per-table metadata fetches. Bounded so documenting a large
|
||||
/// schema cannot starve the connection pool the UI is also using.
|
||||
const MAX_CONCURRENT_TABLES: usize = 8;
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct CollectOptions {
|
||||
pub database: String,
|
||||
pub schemas: Vec<String>,
|
||||
/// Empty means every table. Entries may be bare (`orders`) or
|
||||
/// qualified (`analytics.daily_sales`).
|
||||
pub tables: Vec<String>,
|
||||
pub project_name: String,
|
||||
}
|
||||
|
||||
impl CollectOptions {
|
||||
pub fn includes_table(&self, schema: &str, table: &str) -> bool {
|
||||
if self.tables.is_empty() {
|
||||
return true;
|
||||
}
|
||||
let qualified = format!("{schema}.{table}");
|
||||
self.tables.iter().any(|wanted| wanted == table || wanted == &qualified)
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct CollectProgress {
|
||||
pub completed: usize,
|
||||
pub total: usize,
|
||||
pub current: String,
|
||||
}
|
||||
|
||||
fn table_kind_from(table_type: &str) -> TableKind {
|
||||
let normalized = table_type.trim().to_ascii_uppercase().replace('_', " ");
|
||||
match normalized.as_str() {
|
||||
"VIEW" => TableKind::View,
|
||||
"MATERIALIZED VIEW" => TableKind::MaterializedView,
|
||||
_ => TableKind::Table,
|
||||
}
|
||||
}
|
||||
|
||||
/// MySQL reports `ENUM('a','b')` inline rather than as a named type, so DBML
|
||||
/// needs a synthesized `{table}_{column}` name for it. PostgreSQL, by
|
||||
/// contrast, reports a named enum type's own identifier in `data_type` — its
|
||||
/// native name is used instead, so the user's real type identity survives
|
||||
/// and a type shared by several columns is recognized as the same enum
|
||||
/// (see `build_enums`, which deduplicates by name).
|
||||
fn synthesize_enum(schema: Option<&str>, table: &str, column: &ColumnInfo) -> Option<DocEnum> {
|
||||
let values = column.enum_values.as_ref().filter(|values| !values.is_empty())?;
|
||||
Some(DocEnum {
|
||||
schema: schema.map(ToOwned::to_owned),
|
||||
name: enum_type_name(column, table),
|
||||
values: values.clone(),
|
||||
note: None,
|
||||
synthesized: is_inline_enum_spelling(&column.data_type),
|
||||
})
|
||||
}
|
||||
|
||||
/// Collect every enum referenced by `tables`, deduplicated by (schema,
|
||||
/// name). A named type (e.g. a PostgreSQL enum) is typically shared by
|
||||
/// several columns — without deduplication each column would emit its own
|
||||
/// copy of the same block, which is invalid DBML.
|
||||
fn build_enums(tables: &[DocTable]) -> Vec<DocEnum> {
|
||||
let mut enums = Vec::new();
|
||||
let mut seen: HashSet<(Option<String>, String)> = HashSet::new();
|
||||
for table in tables {
|
||||
for column in &table.columns {
|
||||
let Some(value) = synthesize_enum(table.schema.as_deref(), &table.name, column) else { continue };
|
||||
if seen.insert((value.schema.clone(), value.name.clone())) {
|
||||
enums.push(value);
|
||||
}
|
||||
}
|
||||
}
|
||||
enums
|
||||
}
|
||||
|
||||
fn cancelled(cancel: &AtomicBool) -> bool {
|
||||
cancel.load(Ordering::Relaxed)
|
||||
}
|
||||
|
||||
/// Whether any table or column in the collected snapshot carries a
|
||||
/// non-empty comment. Used to corroborate `supports_comments` — a DDL-only
|
||||
/// capability flag — against what introspection actually returned.
|
||||
fn any_comment_collected(tables: &[DocTable]) -> bool {
|
||||
tables.iter().any(|table| {
|
||||
table.note.as_deref().is_some_and(|note| !note.trim().is_empty())
|
||||
|| table
|
||||
.columns
|
||||
.iter()
|
||||
.any(|column| column.comment.as_deref().is_some_and(|comment| !comment.trim().is_empty()))
|
||||
})
|
||||
}
|
||||
|
||||
/// True when the `CommentsUnsupported` warning belongs in the snapshot: the
|
||||
/// engine's DDL capability flag says it can't do comments, and collection
|
||||
/// found none to contradict it.
|
||||
fn should_warn_comments_unsupported(supports_comments: bool, tables: &[DocTable]) -> bool {
|
||||
!supports_comments && !any_comment_collected(tables)
|
||||
}
|
||||
|
||||
/// True when the `NoForeignKeyMetadata` warning belongs in the snapshot: the
|
||||
/// engine's DDL capability flag says it can't do foreign keys, and
|
||||
/// collection found no relationships to contradict it.
|
||||
fn should_warn_no_foreign_key_metadata(supports_foreign_keys: bool, relationships: &[Relationship]) -> bool {
|
||||
!supports_foreign_keys && relationships.is_empty()
|
||||
}
|
||||
|
||||
/// Collect a documentation snapshot.
|
||||
///
|
||||
/// A per-table failure is recorded as a `TableSkipped` warning and does not
|
||||
/// abort the run — a permissions gap on one table must not kill a
|
||||
/// 400-table documentation build.
|
||||
pub async fn collect_snapshot(
|
||||
state: &AppState,
|
||||
connection: &ConnectionConfig,
|
||||
options: &CollectOptions,
|
||||
progress: &(dyn Fn(CollectProgress) + Send + Sync),
|
||||
cancel: &AtomicBool,
|
||||
) -> Result<SchemaSnapshot, String> {
|
||||
let mut warnings: Vec<SnapshotWarning> = Vec::new();
|
||||
let engine = database_type_label(connection.db_type);
|
||||
let connection_id = connection.id.as_str();
|
||||
|
||||
let schemas = if options.schemas.is_empty() {
|
||||
match schema::list_schemas_core(state, connection_id, &options.database).await {
|
||||
Ok(schemas) => schemas,
|
||||
Err(error) => {
|
||||
// Distinguish "enumeration failed" from "no schemas exist" —
|
||||
// the latter is a legitimately empty document, the former is
|
||||
// a cryptic one if it silently proceeds against schema "".
|
||||
warnings.push(SnapshotWarning::TableSkipped {
|
||||
table: "*".to_string(),
|
||||
reason: format!("schema enumeration failed: {error}"),
|
||||
});
|
||||
Vec::new()
|
||||
}
|
||||
}
|
||||
} else {
|
||||
options.schemas.clone()
|
||||
};
|
||||
let effective_schemas = if schemas.is_empty() { vec![String::new()] } else { schemas };
|
||||
|
||||
// Enumerate every table first so progress has a real total.
|
||||
let mut targets: Vec<(String, crate::types::TableInfo)> = Vec::new();
|
||||
for schema_name in &effective_schemas {
|
||||
match schema::list_tables_core(
|
||||
state,
|
||||
connection_id,
|
||||
&options.database,
|
||||
schema_name,
|
||||
None,
|
||||
None,
|
||||
None,
|
||||
None,
|
||||
None,
|
||||
)
|
||||
.await
|
||||
{
|
||||
Ok(tables) => {
|
||||
for info in tables {
|
||||
if options.includes_table(schema_name, &info.name) {
|
||||
targets.push((schema_name.clone(), info));
|
||||
}
|
||||
}
|
||||
}
|
||||
Err(error) => {
|
||||
warnings.push(SnapshotWarning::TableSkipped { table: format!("{schema_name}.*"), reason: error })
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
let total = targets.len();
|
||||
|
||||
let collected: Vec<Result<(DocTable, Vec<SnapshotWarning>), SnapshotWarning>> =
|
||||
stream::iter(targets.into_iter().enumerate())
|
||||
.map(|(index, (schema_name, info))| {
|
||||
let database = options.database.clone();
|
||||
async move {
|
||||
if cancelled(cancel) {
|
||||
return Err(SnapshotWarning::TableSkipped {
|
||||
table: info.name.clone(),
|
||||
reason: "cancelled".to_string(),
|
||||
});
|
||||
}
|
||||
|
||||
progress(CollectProgress {
|
||||
completed: index,
|
||||
total,
|
||||
current: format!("{schema_name}.{}", info.name),
|
||||
});
|
||||
|
||||
let columns = schema::get_columns_core(state, connection_id, &database, &schema_name, &info.name)
|
||||
.await
|
||||
.map_err(|error| SnapshotWarning::TableSkipped {
|
||||
table: format!("{schema_name}.{}", info.name),
|
||||
reason: error,
|
||||
})?;
|
||||
|
||||
let mut table_warnings = Vec::new();
|
||||
|
||||
// Indexes feed `relations.rs`'s uniqueness check, so a
|
||||
// failure here must not look identical to "this table
|
||||
// genuinely has no indexes" — that would silently
|
||||
// downgrade a OneToOne relationship to ManyToOne.
|
||||
let indexes = match schema::list_indexes_core(
|
||||
state,
|
||||
connection_id,
|
||||
&database,
|
||||
&schema_name,
|
||||
&info.name,
|
||||
)
|
||||
.await
|
||||
{
|
||||
Ok(indexes) => indexes,
|
||||
Err(error) => {
|
||||
table_warnings.push(SnapshotWarning::TableSkipped {
|
||||
table: format!("{schema_name}.{}", info.name),
|
||||
reason: format!("indexes unavailable: {error}"),
|
||||
});
|
||||
Vec::new()
|
||||
}
|
||||
};
|
||||
|
||||
// Foreign keys also degrade to empty rather than failing the
|
||||
// table, but a real query failure must not look identical to
|
||||
// "this table genuinely has no foreign keys" — it is reported
|
||||
// as its own warning instead of being silently discarded.
|
||||
let foreign_keys =
|
||||
match schema::list_foreign_keys_core(state, connection_id, &database, &schema_name, &info.name)
|
||||
.await
|
||||
{
|
||||
Ok(keys) => keys,
|
||||
Err(error) => {
|
||||
table_warnings.push(SnapshotWarning::TableSkipped {
|
||||
table: format!("{schema_name}.{}", info.name),
|
||||
reason: format!("foreign keys unavailable: {error}"),
|
||||
});
|
||||
Vec::new()
|
||||
}
|
||||
};
|
||||
|
||||
Ok((
|
||||
DocTable {
|
||||
schema: (!schema_name.is_empty()).then(|| schema_name.clone()),
|
||||
name: info.name.clone(),
|
||||
kind: table_kind_from(&info.table_type),
|
||||
columns,
|
||||
indexes,
|
||||
foreign_keys,
|
||||
group_id: None,
|
||||
note: info.comment.clone().filter(|value| !value.trim().is_empty()),
|
||||
note_source: if info.comment.as_deref().is_some_and(|v| !v.trim().is_empty()) {
|
||||
NoteSource::Database
|
||||
} else {
|
||||
NoteSource::None
|
||||
},
|
||||
shadowed_note: None,
|
||||
column_notes: BTreeMap::new(),
|
||||
estimated_rows: None,
|
||||
view_definition: None,
|
||||
},
|
||||
table_warnings,
|
||||
))
|
||||
}
|
||||
})
|
||||
.buffer_unordered(MAX_CONCURRENT_TABLES)
|
||||
.collect()
|
||||
.await;
|
||||
|
||||
let mut tables = Vec::new();
|
||||
for outcome in collected {
|
||||
match outcome {
|
||||
Ok((table, table_warnings)) => {
|
||||
tables.push(table);
|
||||
warnings.extend(table_warnings);
|
||||
}
|
||||
Err(warning) => warnings.push(warning),
|
||||
}
|
||||
}
|
||||
|
||||
tables.sort_by_key(|table| table.qualified_name());
|
||||
|
||||
let enums = build_enums(&tables);
|
||||
|
||||
let relationships = build_relationships(&tables);
|
||||
|
||||
// The capability flags gate DDL generation (COMMENT ON, foreign key
|
||||
// clauses), not introspection — IRIS is the proven divergence: it
|
||||
// reports comments on introspection despite the editor being unable to
|
||||
// ALTER them, so `supports_comments` alone would be a false positive. A
|
||||
// warning fires only when the flag says an engine can't AND collection
|
||||
// corroborates that nothing of the kind actually came back.
|
||||
if should_warn_comments_unsupported(supports_comments(connection.db_type), &tables) {
|
||||
warnings.push(SnapshotWarning::CommentsUnsupported { engine: engine.clone() });
|
||||
}
|
||||
if should_warn_no_foreign_key_metadata(supports_foreign_keys(connection.db_type), &relationships) {
|
||||
warnings.push(SnapshotWarning::NoForeignKeyMetadata { engine: engine.clone() });
|
||||
}
|
||||
|
||||
progress(CollectProgress { completed: total, total, current: String::new() });
|
||||
|
||||
Ok(SchemaSnapshot {
|
||||
format_version: 1,
|
||||
project: ProjectMeta {
|
||||
name: options.project_name.clone(),
|
||||
database_type: engine,
|
||||
database: (!options.database.is_empty()).then(|| options.database.clone()),
|
||||
schemas: effective_schemas.into_iter().filter(|s| !s.is_empty()).collect(),
|
||||
generated_at: chrono::Utc::now().to_rfc3339(),
|
||||
note: None,
|
||||
},
|
||||
tables,
|
||||
relationships,
|
||||
groups: Vec::new(),
|
||||
enums,
|
||||
warnings,
|
||||
})
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn table_kind_maps_from_the_engine_reported_type() {
|
||||
assert_eq!(table_kind_from("TABLE"), TableKind::Table);
|
||||
assert_eq!(table_kind_from("BASE TABLE"), TableKind::Table);
|
||||
assert_eq!(table_kind_from("VIEW"), TableKind::View);
|
||||
assert_eq!(table_kind_from("MATERIALIZED VIEW"), TableKind::MaterializedView);
|
||||
assert_eq!(table_kind_from("materialized_view"), TableKind::MaterializedView);
|
||||
assert_eq!(table_kind_from("something else"), TableKind::Table);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn table_filter_is_empty_means_include_everything() {
|
||||
let options = CollectOptions {
|
||||
database: "shop".to_string(),
|
||||
schemas: vec!["public".to_string()],
|
||||
tables: vec![],
|
||||
project_name: "Ecommerce".to_string(),
|
||||
};
|
||||
assert!(options.includes_table("public", "orders"));
|
||||
assert!(options.includes_table("public", "anything"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn table_filter_matches_bare_and_qualified_names() {
|
||||
let options = CollectOptions {
|
||||
database: "shop".to_string(),
|
||||
schemas: vec!["public".to_string()],
|
||||
tables: vec!["orders".to_string(), "analytics.daily_sales".to_string()],
|
||||
project_name: "Ecommerce".to_string(),
|
||||
};
|
||||
assert!(options.includes_table("public", "orders"));
|
||||
assert!(options.includes_table("analytics", "daily_sales"));
|
||||
assert!(!options.includes_table("public", "users"));
|
||||
assert!(!options.includes_table("public", "daily_sales"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn synthesises_a_named_enum_from_an_inline_mysql_enum_column() {
|
||||
let mut column = crate::types::ColumnInfo {
|
||||
name: "status".to_string(),
|
||||
data_type: "enum('pending','shipped')".to_string(),
|
||||
..Default::default()
|
||||
};
|
||||
column.enum_values = Some(vec!["pending".to_string(), "shipped".to_string()]);
|
||||
|
||||
let synthesized = synthesize_enum(Some("public"), "orders", &column).expect("enum");
|
||||
|
||||
assert_eq!(synthesized.name, "orders_status");
|
||||
assert_eq!(synthesized.values, vec!["pending", "shipped"]);
|
||||
assert!(synthesized.synthesized);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_postgres_named_enum_column_keeps_its_own_type_name() {
|
||||
// PostgreSQL reports the enum's own type name in `data_type`, not an
|
||||
// inline `ENUM(...)` spelling. The user's real type identity must
|
||||
// survive into the document instead of being replaced by a
|
||||
// synthesized `{table}_{column}` name.
|
||||
let mut column = crate::types::ColumnInfo {
|
||||
name: "status".to_string(),
|
||||
data_type: "ConversationStatus".to_string(),
|
||||
..Default::default()
|
||||
};
|
||||
column.enum_values = Some(vec!["open".to_string(), "closed".to_string()]);
|
||||
|
||||
let synthesized = synthesize_enum(Some("public"), "conversations", &column).expect("enum");
|
||||
|
||||
assert_eq!(synthesized.name, "ConversationStatus");
|
||||
assert!(!synthesized.synthesized);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_column_without_enum_values_synthesises_nothing() {
|
||||
let column = crate::types::ColumnInfo {
|
||||
name: "status".to_string(),
|
||||
data_type: "text".to_string(),
|
||||
..Default::default()
|
||||
};
|
||||
assert!(synthesize_enum(Some("public"), "orders", &column).is_none());
|
||||
}
|
||||
|
||||
fn enum_column(name: &str, data_type: &str, values: &[&str]) -> crate::types::ColumnInfo {
|
||||
crate::types::ColumnInfo {
|
||||
name: name.to_string(),
|
||||
data_type: data_type.to_string(),
|
||||
enum_values: Some(values.iter().map(|v| v.to_string()).collect()),
|
||||
..Default::default()
|
||||
}
|
||||
}
|
||||
|
||||
fn table_with_columns(schema: &str, name: &str, columns: Vec<crate::types::ColumnInfo>) -> DocTable {
|
||||
DocTable {
|
||||
schema: Some(schema.to_string()),
|
||||
name: name.to_string(),
|
||||
kind: TableKind::Table,
|
||||
columns,
|
||||
indexes: vec![],
|
||||
foreign_keys: vec![],
|
||||
group_id: None,
|
||||
note: None,
|
||||
note_source: NoteSource::None,
|
||||
shadowed_note: None,
|
||||
column_notes: BTreeMap::new(),
|
||||
estimated_rows: None,
|
||||
view_definition: None,
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_named_enum_type_shared_by_two_columns_is_emitted_once() {
|
||||
let conversations = table_with_columns(
|
||||
"public",
|
||||
"conversations",
|
||||
vec![enum_column("status", "ConversationStatus", &["open", "closed"])],
|
||||
);
|
||||
let archived_conversations = table_with_columns(
|
||||
"public",
|
||||
"archived_conversations",
|
||||
vec![enum_column("status", "ConversationStatus", &["open", "closed"])],
|
||||
);
|
||||
|
||||
let enums = build_enums(&[conversations, archived_conversations]);
|
||||
|
||||
assert_eq!(enums.len(), 1, "two columns of the same named type must dedupe to one block: {enums:?}");
|
||||
assert_eq!(enums[0].name, "ConversationStatus");
|
||||
assert!(!enums[0].synthesized);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn postgres_reports_foreign_key_ddl_capability_true() {
|
||||
assert!(supports_foreign_keys(crate::models::connection::DatabaseType::Postgres));
|
||||
}
|
||||
|
||||
fn column_with_comment(comment: &str) -> crate::types::ColumnInfo {
|
||||
crate::types::ColumnInfo {
|
||||
name: "notes".to_string(),
|
||||
data_type: "text".to_string(),
|
||||
comment: Some(comment.to_string()),
|
||||
..Default::default()
|
||||
}
|
||||
}
|
||||
|
||||
fn sample_relationship() -> Relationship {
|
||||
Relationship {
|
||||
id: "orders.customer_id->customers.id".to_string(),
|
||||
name: None,
|
||||
from: crate::docs::FieldRef {
|
||||
schema: Some("public".to_string()),
|
||||
table: "orders".to_string(),
|
||||
column: "customer_id".to_string(),
|
||||
},
|
||||
to: crate::docs::FieldRef {
|
||||
schema: Some("public".to_string()),
|
||||
table: "customers".to_string(),
|
||||
column: "id".to_string(),
|
||||
},
|
||||
cardinality: crate::docs::Cardinality::ManyToOne,
|
||||
on_update: None,
|
||||
on_delete: None,
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn comments_unsupported_warning_fires_when_flag_is_false_and_nothing_was_collected() {
|
||||
let tables = vec![table_with_columns("public", "orders", vec![])];
|
||||
assert!(should_warn_comments_unsupported(false, &tables));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn comments_unsupported_warning_is_absent_when_a_table_comment_was_collected() {
|
||||
// Regression: IRIS reports `comment: false` on the DDL capability
|
||||
// flag (it supports %DESCRIPTION at CREATE time but DBX cannot ALTER
|
||||
// it), yet IRIS still returns real comments on introspection. The
|
||||
// warning must not contradict data actually present in the snapshot.
|
||||
let mut table = table_with_columns("public", "orders", vec![]);
|
||||
table.note = Some("Checkout rows.".to_string());
|
||||
assert!(!should_warn_comments_unsupported(false, &[table]));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn comments_unsupported_warning_is_absent_when_a_column_comment_was_collected() {
|
||||
let tables = vec![table_with_columns("public", "orders", vec![column_with_comment("Internal notes.")])];
|
||||
assert!(!should_warn_comments_unsupported(false, &tables));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn comments_unsupported_warning_does_not_fire_when_the_capability_flag_is_true() {
|
||||
let tables = vec![table_with_columns("public", "orders", vec![])];
|
||||
assert!(!should_warn_comments_unsupported(true, &tables));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn no_foreign_key_warning_fires_when_flag_is_false_and_no_relationships_were_collected() {
|
||||
assert!(should_warn_no_foreign_key_metadata(false, &[]));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn no_foreign_key_warning_is_absent_when_relationships_were_collected() {
|
||||
// Regression: ClickHouse/Doris genuinely report zero FK metadata, so
|
||||
// this must still fire for them — but an engine that DOES report
|
||||
// relationships must not be flagged just because its DDL capability
|
||||
// flag is false.
|
||||
let relationships = vec![sample_relationship()];
|
||||
assert!(!should_warn_no_foreign_key_metadata(false, &relationships));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn no_foreign_key_warning_does_not_fire_when_the_capability_flag_is_true() {
|
||||
assert!(!should_warn_no_foreign_key_metadata(true, &[]));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,85 @@
|
||||
/// Lightness and chroma of the light-theme `--group-c` token. Only hue
|
||||
/// varies per group, which is what guarantees legible contrast.
|
||||
const GROUP_LIGHTNESS: f64 = 0.55;
|
||||
const GROUP_CHROMA: f64 = 0.15;
|
||||
|
||||
fn linear_to_srgb(channel: f64) -> f64 {
|
||||
if channel <= 0.003_130_8 {
|
||||
12.92 * channel
|
||||
} else {
|
||||
1.055 * channel.powf(1.0 / 2.4) - 0.055
|
||||
}
|
||||
}
|
||||
|
||||
fn to_byte(channel: f64) -> u8 {
|
||||
(linear_to_srgb(channel).clamp(0.0, 1.0) * 255.0).round() as u8
|
||||
}
|
||||
|
||||
/// Convert a group hue to the sRGB hex DBML expects.
|
||||
///
|
||||
/// OKLCH -> OKLab -> LMS -> linear sRGB -> gamma-encoded sRGB.
|
||||
/// Coefficients are Björn Ottosson's published OKLab matrices.
|
||||
pub fn hue_to_hex(hue: u16) -> String {
|
||||
let radians = f64::from(hue % 360) * std::f64::consts::PI / 180.0;
|
||||
let a = GROUP_CHROMA * radians.cos();
|
||||
let b = GROUP_CHROMA * radians.sin();
|
||||
|
||||
let l_ = GROUP_LIGHTNESS + 0.396_337_777_4 * a + 0.215_803_757_3 * b;
|
||||
let m_ = GROUP_LIGHTNESS - 0.105_561_345_8 * a - 0.063_854_172_8 * b;
|
||||
let s_ = GROUP_LIGHTNESS - 0.089_484_177_5 * a - 1.291_485_548_0 * b;
|
||||
|
||||
let l = l_ * l_ * l_;
|
||||
let m = m_ * m_ * m_;
|
||||
let s = s_ * s_ * s_;
|
||||
|
||||
let red = 4.076_741_662_1 * l - 3.307_711_591_3 * m + 0.230_969_929_2 * s;
|
||||
let green = -1.268_438_004_6 * l + 2.609_757_401_1 * m - 0.341_319_396_5 * s;
|
||||
let blue = -0.004_196_086_3 * l - 0.703_418_614_7 * m + 1.707_614_701_0 * s;
|
||||
|
||||
format!("#{:02x}{:02x}{:02x}", to_byte(red), to_byte(green), to_byte(blue))
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn produces_a_six_digit_lowercase_hex_string() {
|
||||
let hex = hue_to_hex(28);
|
||||
assert_eq!(hex.len(), 7, "got {hex}");
|
||||
assert!(hex.starts_with('#'), "got {hex}");
|
||||
assert!(hex[1..].chars().all(|c| c.is_ascii_hexdigit() && !c.is_ascii_uppercase()), "got {hex}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn hue_28_is_a_warm_orange_red() {
|
||||
// Sanity check against the group palette: red channel dominates.
|
||||
let hex = hue_to_hex(28);
|
||||
let r = u8::from_str_radix(&hex[1..3], 16).unwrap();
|
||||
let g = u8::from_str_radix(&hex[3..5], 16).unwrap();
|
||||
let b = u8::from_str_radix(&hex[5..7], 16).unwrap();
|
||||
assert!(r > g && g > b, "expected r > g > b, got {hex}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn hue_148_is_green_dominant() {
|
||||
let hex = hue_to_hex(148);
|
||||
let r = u8::from_str_radix(&hex[1..3], 16).unwrap();
|
||||
let g = u8::from_str_radix(&hex[3..5], 16).unwrap();
|
||||
assert!(g > r, "expected green to dominate, got {hex}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn every_hue_is_in_range_and_never_panics() {
|
||||
for hue in 0..=359u16 {
|
||||
let hex = hue_to_hex(hue);
|
||||
assert_eq!(hex.len(), 7, "hue {hue} produced {hex}");
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn hue_wraps_past_360() {
|
||||
assert_eq!(hue_to_hex(0), hue_to_hex(360));
|
||||
assert_eq!(hue_to_hex(28), hue_to_hex(388));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,893 @@
|
||||
use crate::docs::hue_to_hex;
|
||||
use crate::docs::{
|
||||
Cardinality, DocEnum, DocTable, FieldRef, Relationship, SchemaSnapshot, SnapshotWarning, TableGroup,
|
||||
};
|
||||
use crate::types::{ColumnInfo, IndexInfo};
|
||||
|
||||
/// DBML accepts bare identifiers matching `[A-Za-z_][A-Za-z0-9_]*`;
|
||||
/// everything else needs double quotes.
|
||||
pub(crate) fn quote_identifier(value: &str) -> String {
|
||||
let plain = !value.is_empty()
|
||||
&& value.chars().next().is_some_and(|c| c.is_ascii_alphabetic() || c == '_')
|
||||
&& value.chars().all(|c| c.is_ascii_alphanumeric() || c == '_');
|
||||
|
||||
if plain {
|
||||
value.to_string()
|
||||
} else {
|
||||
format!("\"{}\"", value.replace('"', "\\\""))
|
||||
}
|
||||
}
|
||||
|
||||
/// `schema.name` when qualifying, bare `name` otherwise. Both parts quoted
|
||||
/// independently so an irregular schema or table name is handled correctly.
|
||||
pub(crate) fn qualified(schema: Option<&str>, name: &str, qualify: bool) -> String {
|
||||
match schema.filter(|s| !s.is_empty()) {
|
||||
Some(schema) if qualify => format!("{}.{}", quote_identifier(schema), quote_identifier(name)),
|
||||
_ => quote_identifier(name),
|
||||
}
|
||||
}
|
||||
|
||||
/// Notes always use triple quotes so an apostrophe in prose can never break
|
||||
/// the file.
|
||||
///
|
||||
/// Two things need escaping. A literal `'''` inside the prose, obviously —
|
||||
/// and also a SINGLE trailing quote, which is subtler: the note `he said '`
|
||||
/// would otherwise render as `'''he said ''''`, four quotes in a row, and a
|
||||
/// parser scanning for the closing `'''` would close early and strand the
|
||||
/// fourth. DBML honours `\'` inside triple quotes.
|
||||
pub(crate) fn render_note(value: &str) -> String {
|
||||
let escaped = value.replace("'''", "\\'''");
|
||||
let escaped = match escaped.strip_suffix('\'') {
|
||||
Some(head) => format!("{head}\\'"),
|
||||
None => escaped,
|
||||
};
|
||||
format!("'''{escaped}'''")
|
||||
}
|
||||
|
||||
fn looks_like_expression(value: &str) -> bool {
|
||||
let trimmed = value.trim();
|
||||
if trimmed.starts_with('\'') && trimmed.ends_with('\'') && trimmed.len() >= 2 {
|
||||
return false;
|
||||
}
|
||||
if trimmed.parse::<f64>().is_ok() {
|
||||
return false;
|
||||
}
|
||||
if matches!(trimmed.to_ascii_lowercase().as_str(), "true" | "false" | "null") {
|
||||
return false;
|
||||
}
|
||||
true
|
||||
}
|
||||
|
||||
/// `default: …` for a column, or None when it has no default.
|
||||
/// Expressions go in backticks, literals stay as written.
|
||||
pub(crate) fn render_default(column: &ColumnInfo) -> Option<String> {
|
||||
let value = column.column_default.as_deref()?.trim();
|
||||
if value.is_empty() {
|
||||
return None;
|
||||
}
|
||||
|
||||
if looks_like_expression(value) {
|
||||
Some(format!("default: `{value}`"))
|
||||
} else {
|
||||
Some(format!("default: {value}"))
|
||||
}
|
||||
}
|
||||
|
||||
/// True when `data_type` is MySQL's inline `ENUM(...)` spelling rather than
|
||||
/// a genuine named type. PostgreSQL reports a named enum type's own
|
||||
/// identifier in `data_type` instead (e.g. `"ConversationStatus"`) — only
|
||||
/// the inline MySQL spelling needs a synthesized name.
|
||||
pub(crate) fn is_inline_enum_spelling(data_type: &str) -> bool {
|
||||
let trimmed = data_type.trim();
|
||||
trimmed.get(..5).is_some_and(|prefix| prefix.eq_ignore_ascii_case("enum(")) && trimmed.ends_with(')')
|
||||
}
|
||||
|
||||
/// PostgreSQL's `format_type` double-quotes an identifier that needs it
|
||||
/// (e.g. `"ConversationStatus"`); strip that quoting so the bare name can be
|
||||
/// used as a DBML identifier directly — `quote_identifier` re-quotes it if
|
||||
/// DBML itself requires that.
|
||||
pub(crate) fn unquote_pg_identifier(value: &str) -> String {
|
||||
let trimmed = value.trim();
|
||||
match trimmed.len() >= 2 && trimmed.starts_with('"') && trimmed.ends_with('"') {
|
||||
true => trimmed[1..trimmed.len() - 1].replace("\"\"", "\""),
|
||||
false => trimmed.to_string(),
|
||||
}
|
||||
}
|
||||
|
||||
/// The enum name a column's `enum_values` refers to: the synthesized
|
||||
/// `{table}_{column}` name for MySQL's inline `ENUM(...)` columns, or the
|
||||
/// native type name for a genuine named enum type (e.g. PostgreSQL).
|
||||
///
|
||||
/// This is the single source of truth for that name — `synthesize_enum`
|
||||
/// (collector) and `render_type` (below) both go through it, so a column's
|
||||
/// type reference and its `Enum` block name can never drift apart again.
|
||||
pub(crate) fn enum_type_name(column: &ColumnInfo, table_name: &str) -> String {
|
||||
if is_inline_enum_spelling(&column.data_type) {
|
||||
format!("{table_name}_{}", column.name)
|
||||
} else {
|
||||
unquote_pg_identifier(&column.data_type)
|
||||
}
|
||||
}
|
||||
|
||||
/// DBML does not validate type names, so native types pass through intact.
|
||||
/// Precision is reconstructed only when the engine reported a bare type.
|
||||
pub(crate) fn render_type(column: &ColumnInfo, table_schema: Option<&str>, table_name: &str, qualify: bool) -> String {
|
||||
// A column carrying enum values is emitted as a named enum elsewhere in
|
||||
// the document. This must produce the SAME string `render_enum` produces
|
||||
// for that block — including schema qualification — or the reference
|
||||
// dangles and the Enum block becomes an orphan.
|
||||
if column.enum_values.as_ref().is_some_and(|values| !values.is_empty()) {
|
||||
return qualified(table_schema, &enum_type_name(column, table_name), qualify);
|
||||
}
|
||||
|
||||
let base = column.data_type.trim();
|
||||
if base.contains('(') {
|
||||
return base.to_string();
|
||||
}
|
||||
|
||||
if let Some(length) = column.character_maximum_length.filter(|value| *value > 0) {
|
||||
return format!("{base}({length})");
|
||||
}
|
||||
|
||||
if let Some(precision) = column.numeric_precision.filter(|value| *value > 0) {
|
||||
return match column.numeric_scale {
|
||||
Some(scale) if scale > 0 => format!("{base}({precision},{scale})"),
|
||||
_ => format!("{base}({precision})"),
|
||||
};
|
||||
}
|
||||
|
||||
base.to_string()
|
||||
}
|
||||
|
||||
fn column_settings(column: &ColumnInfo, table: &DocTable) -> Vec<String> {
|
||||
let mut settings = Vec::new();
|
||||
|
||||
if column.is_primary_key {
|
||||
settings.push("pk".to_string());
|
||||
}
|
||||
|
||||
let extra = column.extra.as_deref().unwrap_or("").to_ascii_lowercase();
|
||||
if extra.contains("auto_increment") || extra.contains("identity") {
|
||||
settings.push("increment".to_string());
|
||||
}
|
||||
|
||||
if !column.is_nullable && !column.is_primary_key {
|
||||
settings.push("not null".to_string());
|
||||
}
|
||||
|
||||
if let Some(default) = render_default(column) {
|
||||
settings.push(default);
|
||||
}
|
||||
|
||||
if let Some(note) = table.column_notes.get(&column.name) {
|
||||
settings.push(format!("note: {}", render_note(¬e.note)));
|
||||
} else if let Some(comment) = column.comment.as_deref().filter(|value| !value.trim().is_empty()) {
|
||||
settings.push(format!("note: {}", render_note(comment)));
|
||||
}
|
||||
|
||||
settings
|
||||
}
|
||||
|
||||
fn render_index(index: &IndexInfo) -> String {
|
||||
let columns = index.columns.iter().map(|c| quote_identifier(c)).collect::<Vec<_>>().join(", ");
|
||||
|
||||
let mut settings = vec![format!("name: '{}'", index.name.replace('\'', "\\'"))];
|
||||
if index.is_unique {
|
||||
settings.push("unique".to_string());
|
||||
}
|
||||
|
||||
format!(" ({columns}) [{}]\n", settings.join(", "))
|
||||
}
|
||||
|
||||
/// Render one `Table` block.
|
||||
///
|
||||
/// The primary-key index is skipped because columns already carry `pk`.
|
||||
/// Indexes DBML cannot express are skipped and recorded in `warnings`
|
||||
/// rather than dropped silently.
|
||||
pub(crate) fn render_table(table: &DocTable, qualify: bool, warnings: &mut Vec<SnapshotWarning>) -> String {
|
||||
let name = qualified(table.schema.as_deref(), &table.name, qualify);
|
||||
|
||||
let mut out = format!("Table {name} {{\n");
|
||||
|
||||
for column in &table.columns {
|
||||
let settings = column_settings(column, table);
|
||||
let rendered_settings = if settings.is_empty() { String::new() } else { format!(" [{}]", settings.join(", ")) };
|
||||
out.push_str(&format!(
|
||||
" {} {}{}\n",
|
||||
quote_identifier(&column.name),
|
||||
render_type(column, table.schema.as_deref(), &table.name, qualify),
|
||||
rendered_settings
|
||||
));
|
||||
}
|
||||
|
||||
let emittable: Vec<&IndexInfo> = table
|
||||
.indexes
|
||||
.iter()
|
||||
.filter(|index| {
|
||||
if index.is_primary {
|
||||
return false;
|
||||
}
|
||||
if index.filter.as_deref().is_some_and(|f| !f.trim().is_empty()) {
|
||||
warnings.push(SnapshotWarning::DbmlOmitted {
|
||||
table: table.qualified_name(),
|
||||
item: index.name.clone(),
|
||||
reason: "partial index filter has no DBML equivalent".to_string(),
|
||||
});
|
||||
return false;
|
||||
}
|
||||
if index.included_columns.as_ref().is_some_and(|columns| !columns.is_empty()) {
|
||||
warnings.push(SnapshotWarning::DbmlOmitted {
|
||||
table: table.qualified_name(),
|
||||
item: index.name.clone(),
|
||||
reason: "included columns have no DBML equivalent".to_string(),
|
||||
});
|
||||
return false;
|
||||
}
|
||||
!index.columns.is_empty()
|
||||
})
|
||||
.collect();
|
||||
|
||||
if !emittable.is_empty() {
|
||||
out.push_str("\n Indexes {\n");
|
||||
for index in emittable {
|
||||
out.push_str(&render_index(index));
|
||||
}
|
||||
out.push_str(" }\n");
|
||||
}
|
||||
|
||||
if let Some(note) = table.note.as_deref().filter(|value| !value.trim().is_empty()) {
|
||||
out.push_str(&format!("\n Note: {}\n", render_note(note)));
|
||||
}
|
||||
|
||||
out.push_str("}\n");
|
||||
out
|
||||
}
|
||||
|
||||
fn qualified_field(field: &FieldRef, qualify: bool) -> String {
|
||||
let table = qualified(field.schema.as_deref(), &field.table, qualify);
|
||||
format!("{table}.{}", quote_identifier(&field.column))
|
||||
}
|
||||
|
||||
/// One `Ref` line. `>` is many-to-one, `-` is one-to-one.
|
||||
pub(crate) fn render_ref(relationship: &Relationship, qualify: bool) -> String {
|
||||
let operator = match relationship.cardinality {
|
||||
Cardinality::ManyToOne => ">",
|
||||
Cardinality::OneToOne => "-",
|
||||
};
|
||||
|
||||
let mut actions = Vec::new();
|
||||
if let Some(update) = relationship.on_update.as_deref().filter(|v| !v.trim().is_empty()) {
|
||||
actions.push(format!("update: {}", update.to_lowercase()));
|
||||
}
|
||||
if let Some(delete) = relationship.on_delete.as_deref().filter(|v| !v.trim().is_empty()) {
|
||||
actions.push(format!("delete: {}", delete.to_lowercase()));
|
||||
}
|
||||
let settings = if actions.is_empty() { String::new() } else { format!(" [{}]", actions.join(", ")) };
|
||||
|
||||
let label = match relationship.name.as_deref().filter(|v| !v.trim().is_empty()) {
|
||||
Some(name) => format!("Ref {}", quote_identifier(name)),
|
||||
None => "Ref".to_string(),
|
||||
};
|
||||
|
||||
format!(
|
||||
"{label}: {} {operator} {}{settings}\n",
|
||||
qualified_field(&relationship.from, qualify),
|
||||
qualified_field(&relationship.to, qualify)
|
||||
)
|
||||
}
|
||||
|
||||
pub(crate) fn render_enum(value: &DocEnum, qualify: bool) -> String {
|
||||
let name = qualified(value.schema.as_deref(), &value.name, qualify);
|
||||
|
||||
let mut out = format!("Enum {name} {{\n");
|
||||
for variant in &value.values {
|
||||
out.push_str(&format!(" {}\n", quote_identifier(variant)));
|
||||
}
|
||||
if let Some(note) = value.note.as_deref().filter(|v| !v.trim().is_empty()) {
|
||||
out.push_str(&format!("\n Note: {}\n", render_note(note)));
|
||||
}
|
||||
out.push_str("}\n");
|
||||
out
|
||||
}
|
||||
|
||||
/// A `TableGroup` block. Returns an empty string when the group has no
|
||||
/// members, since DBML rejects an empty group body.
|
||||
pub(crate) fn render_group(group: &TableGroup, members: &[&DocTable], qualify: bool) -> String {
|
||||
if members.is_empty() {
|
||||
return String::new();
|
||||
}
|
||||
|
||||
let mut out = format!("TableGroup {} [color: {}] {{\n", quote_identifier(&group.name), hue_to_hex(group.hue));
|
||||
|
||||
for member in members {
|
||||
let name = qualified(member.schema.as_deref(), &member.name, qualify);
|
||||
out.push_str(&format!(" {name}\n"));
|
||||
}
|
||||
|
||||
if let Some(note) = group.note.as_deref().filter(|v| !v.trim().is_empty()) {
|
||||
out.push_str(&format!("\n Note: {}\n", render_note(note)));
|
||||
}
|
||||
|
||||
out.push_str("}\n");
|
||||
out
|
||||
}
|
||||
|
||||
/// DBML text plus every construct that could not be represented in it.
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct DbmlOutput {
|
||||
pub text: String,
|
||||
pub warnings: Vec<SnapshotWarning>,
|
||||
}
|
||||
|
||||
fn render_project(snapshot: &SchemaSnapshot) -> String {
|
||||
let mut out = format!("Project {} {{\n", quote_identifier(&snapshot.project.name));
|
||||
out.push_str(&format!(" database_type: '{}'\n", snapshot.project.database_type.replace('\'', "\\'")));
|
||||
if let Some(note) = snapshot.project.note.as_deref().filter(|v| !v.trim().is_empty()) {
|
||||
out.push_str(&format!(" Note: {}\n", render_note(note)));
|
||||
}
|
||||
out.push_str("}\n");
|
||||
out
|
||||
}
|
||||
|
||||
/// Serialize a snapshot to DBML.
|
||||
///
|
||||
/// DBML is an interchange format, not a backup: check constraints, partial
|
||||
/// indexes, included columns, collations and generated columns have no
|
||||
/// representation. Each omission is reported in `warnings` so the HTML
|
||||
/// documentation — which *is* the complete record — can mark it.
|
||||
pub fn to_dbml(snapshot: &SchemaSnapshot) -> DbmlOutput {
|
||||
let qualify = snapshot.project.schemas.len() > 1;
|
||||
// Start from the collector's warnings so omissions discovered at collection
|
||||
// time (skipped tables, unsupported comments) survive into the output
|
||||
// alongside those discovered while rendering.
|
||||
let mut warnings = snapshot.warnings.clone();
|
||||
let mut sections: Vec<String> = vec![render_project(snapshot)];
|
||||
|
||||
for value in &snapshot.enums {
|
||||
sections.push(render_enum(value, qualify));
|
||||
}
|
||||
|
||||
for group in &snapshot.groups {
|
||||
let members: Vec<&DocTable> =
|
||||
snapshot.tables.iter().filter(|table| table.group_id.as_deref() == Some(group.id.as_str())).collect();
|
||||
let rendered = render_group(group, &members, qualify);
|
||||
if !rendered.is_empty() {
|
||||
sections.push(rendered);
|
||||
}
|
||||
}
|
||||
|
||||
for table in &snapshot.tables {
|
||||
sections.push(render_table(table, qualify, &mut warnings));
|
||||
}
|
||||
|
||||
if !snapshot.relationships.is_empty() {
|
||||
let refs: String = snapshot.relationships.iter().map(|rel| render_ref(rel, qualify)).collect();
|
||||
sections.push(refs);
|
||||
}
|
||||
|
||||
DbmlOutput { text: sections.join("\n"), warnings }
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::types::ColumnInfo;
|
||||
|
||||
fn col(name: &str, data_type: &str) -> ColumnInfo {
|
||||
ColumnInfo { name: name.to_string(), data_type: data_type.to_string(), ..ColumnInfo::default() }
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn plain_identifiers_are_not_quoted() {
|
||||
assert_eq!(quote_identifier("orders"), "orders");
|
||||
assert_eq!(quote_identifier("order_items"), "order_items");
|
||||
assert_eq!(quote_identifier("_private"), "_private");
|
||||
assert_eq!(quote_identifier("t2"), "t2");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn irregular_identifiers_are_quoted() {
|
||||
assert_eq!(quote_identifier("order items"), "\"order items\"");
|
||||
assert_eq!(quote_identifier("2fast"), "\"2fast\"");
|
||||
assert_eq!(quote_identifier("user-profile"), "\"user-profile\"");
|
||||
assert_eq!(quote_identifier(""), "\"\"");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn embedded_double_quotes_are_escaped() {
|
||||
assert_eq!(quote_identifier("we\"ird"), "\"we\\\"ird\"");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn notes_always_use_triple_quotes_so_apostrophes_are_safe() {
|
||||
assert_eq!(render_note("Bob's orders"), "'''Bob's orders'''");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn notes_escape_a_literal_triple_quote() {
|
||||
assert_eq!(render_note("a ''' b"), "'''a \\''' b'''");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn multiline_notes_are_preserved() {
|
||||
assert_eq!(render_note("line one\nline two"), "'''line one\nline two'''");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_note_ending_in_a_single_quote_does_not_break_the_delimiter() {
|
||||
// Without escaping this yields four quotes in a row and a parser
|
||||
// closes the string early.
|
||||
assert_eq!(render_note("Deprecated in '24'"), "'''Deprecated in '24\\''''");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn expression_defaults_use_backticks_and_literals_use_quotes() {
|
||||
let mut expression = col("created_at", "timestamptz");
|
||||
expression.column_default = Some("now()".to_string());
|
||||
assert_eq!(render_default(&expression).as_deref(), Some("default: `now()`"));
|
||||
|
||||
let mut sequence = col("id", "integer");
|
||||
sequence.column_default = Some("nextval('orders_id_seq'::regclass)".to_string());
|
||||
assert_eq!(render_default(&sequence).as_deref(), Some("default: `nextval('orders_id_seq'::regclass)`"));
|
||||
|
||||
let mut literal = col("status", "text");
|
||||
literal.column_default = Some("'pending'".to_string());
|
||||
assert_eq!(render_default(&literal).as_deref(), Some("default: 'pending'"));
|
||||
|
||||
let mut number = col("qty", "integer");
|
||||
number.column_default = Some("0".to_string());
|
||||
assert_eq!(render_default(&number).as_deref(), Some("default: 0"));
|
||||
|
||||
let mut boolean = col("active", "boolean");
|
||||
boolean.column_default = Some("true".to_string());
|
||||
assert_eq!(render_default(&boolean).as_deref(), Some("default: true"));
|
||||
|
||||
assert_eq!(render_default(&col("plain", "text")), None);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn types_pass_through_verbatim_when_already_parameterised() {
|
||||
assert_eq!(render_type(&col("total", "numeric(10,2)"), None, "orders", false), "numeric(10,2)");
|
||||
assert_eq!(render_type(&col("meta", "jsonb"), None, "orders", false), "jsonb");
|
||||
assert_eq!(
|
||||
render_type(&col("at", "timestamp with time zone"), None, "orders", false),
|
||||
"timestamp with time zone"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn bare_types_are_reconstructed_from_precision_metadata() {
|
||||
let mut varchar = col("email", "character varying");
|
||||
varchar.character_maximum_length = Some(255);
|
||||
assert_eq!(render_type(&varchar, None, "orders", false), "character varying(255)");
|
||||
|
||||
let mut decimal = col("total", "numeric");
|
||||
decimal.numeric_precision = Some(10);
|
||||
decimal.numeric_scale = Some(2);
|
||||
assert_eq!(render_type(&decimal, None, "orders", false), "numeric(10,2)");
|
||||
|
||||
let mut integer = col("count", "numeric");
|
||||
integer.numeric_precision = Some(8);
|
||||
integer.numeric_scale = Some(0);
|
||||
assert_eq!(render_type(&integer, None, "orders", false), "numeric(8)");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn an_inline_enum_column_references_the_synthesized_enum_name() {
|
||||
let mut status = col("status", "enum('pending','shipped')");
|
||||
status.enum_values = Some(vec!["pending".to_string(), "shipped".to_string()]);
|
||||
assert_eq!(render_type(&status, None, "orders", false), "orders_status");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_named_enum_type_column_references_its_own_native_name_not_a_synthesized_one() {
|
||||
// PostgreSQL reports the enum's own type name in `data_type` rather
|
||||
// than an inline `ENUM(...)` spelling — that native name must be
|
||||
// used verbatim, not the `{table}_{column}` scheme MySQL needs.
|
||||
let mut status = col("status", "ConversationStatus");
|
||||
status.enum_values = Some(vec!["open".to_string(), "closed".to_string()]);
|
||||
assert_eq!(render_type(&status, None, "conversations", false), "ConversationStatus");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_quoted_native_enum_type_name_is_unquoted_for_the_reference() {
|
||||
// `format_type` double-quotes an identifier that needs it (mixed
|
||||
// case, here). The DBML reference must be the bare name so
|
||||
// `quote_identifier` can decide on its own quoting.
|
||||
let mut status = col("status", "\"ConversationStatus\"");
|
||||
status.enum_values = Some(vec!["open".to_string()]);
|
||||
assert_eq!(render_type(&status, None, "conversations", false), "ConversationStatus");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_multi_schema_enum_reference_is_qualified_like_its_enum_block() {
|
||||
let mut status = col("status", "enum('pending','shipped')");
|
||||
status.enum_values = Some(vec!["pending".to_string(), "shipped".to_string()]);
|
||||
|
||||
// qualify=true is what to_dbml sets for a multi-schema snapshot. The
|
||||
// column's type must match render_enum's block name exactly, or the
|
||||
// reference dangles.
|
||||
let reference = render_type(&status, Some("public"), "orders", true);
|
||||
|
||||
let block = DocEnum {
|
||||
schema: Some("public".to_string()),
|
||||
name: "orders_status".to_string(),
|
||||
values: vec!["pending".to_string()],
|
||||
note: None,
|
||||
synthesized: true,
|
||||
};
|
||||
let rendered_block = render_enum(&block, true);
|
||||
|
||||
// Anchored, not `contains`: a bare unqualified reference is a substring
|
||||
// of the qualified block name, so `contains` would pass against the very
|
||||
// bug this test exists to catch.
|
||||
assert!(
|
||||
rendered_block.starts_with(&format!("Enum {reference} {{\n")),
|
||||
"column reference `{reference}` must be exactly the Enum block name in:\n{rendered_block}"
|
||||
);
|
||||
}
|
||||
|
||||
use crate::docs::{ColumnNote, DocTable, NoteSource, SnapshotWarning, TableKind};
|
||||
use crate::types::IndexInfo;
|
||||
use std::collections::BTreeMap;
|
||||
|
||||
fn doc_table(name: &str, columns: Vec<ColumnInfo>, indexes: Vec<IndexInfo>) -> DocTable {
|
||||
DocTable {
|
||||
schema: Some("public".to_string()),
|
||||
name: name.to_string(),
|
||||
kind: TableKind::Table,
|
||||
columns,
|
||||
indexes,
|
||||
foreign_keys: vec![],
|
||||
group_id: None,
|
||||
note: None,
|
||||
note_source: NoteSource::None,
|
||||
shadowed_note: None,
|
||||
column_notes: BTreeMap::new(),
|
||||
estimated_rows: None,
|
||||
view_definition: None,
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn renders_a_table_with_columns_and_settings() {
|
||||
let mut id = col("id", "integer");
|
||||
id.is_primary_key = true;
|
||||
id.extra = Some("auto_increment".to_string());
|
||||
|
||||
let mut user_id = col("user_id", "integer");
|
||||
user_id.is_nullable = false;
|
||||
|
||||
// ColumnInfo::default() gives is_nullable=false (i.e. NOT NULL), so a
|
||||
// genuinely nullable column has to say so explicitly.
|
||||
let mut nullable = col("shipped_at", "timestamptz");
|
||||
nullable.is_nullable = true;
|
||||
|
||||
let mut table = doc_table("orders", vec![id, user_id, nullable], vec![]);
|
||||
table.note = Some("Checkout rows.".to_string());
|
||||
table.column_notes.insert(
|
||||
"user_id".to_string(),
|
||||
ColumnNote { note: "Owning customer".to_string(), source: NoteSource::Local, shadowed: None },
|
||||
);
|
||||
|
||||
let mut warnings = Vec::new();
|
||||
let out = render_table(&table, false, &mut warnings);
|
||||
|
||||
assert!(out.starts_with("Table orders {\n"), "got:\n{out}");
|
||||
assert!(out.contains("id integer [pk, increment]"), "got:\n{out}");
|
||||
assert!(out.contains("user_id integer [not null, note: '''Owning customer''']"), "got:\n{out}");
|
||||
assert!(out.contains("shipped_at timestamptz\n"), "got:\n{out}");
|
||||
assert!(out.contains("Note: '''Checkout rows.'''"), "got:\n{out}");
|
||||
assert!(out.ends_with("}\n"), "got:\n{out}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn qualifies_the_table_name_when_requested() {
|
||||
let table = doc_table("orders", vec![col("id", "integer")], vec![]);
|
||||
let mut warnings = Vec::new();
|
||||
assert!(render_table(&table, true, &mut warnings).starts_with("Table public.orders {"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn renders_an_indexes_block() {
|
||||
let index = IndexInfo {
|
||||
name: "idx_orders_user_placed".to_string(),
|
||||
columns: vec!["user_id".to_string(), "placed_at".to_string()],
|
||||
is_unique: false,
|
||||
is_primary: false,
|
||||
filter: None,
|
||||
index_type: None,
|
||||
included_columns: None,
|
||||
comment: None,
|
||||
};
|
||||
let table = doc_table("orders", vec![col("user_id", "integer")], vec![index]);
|
||||
|
||||
let mut warnings = Vec::new();
|
||||
let out = render_table(&table, false, &mut warnings);
|
||||
|
||||
assert!(out.contains("Indexes {"), "got:\n{out}");
|
||||
assert!(out.contains("(user_id, placed_at) [name: 'idx_orders_user_placed']"), "got:\n{out}");
|
||||
assert!(warnings.is_empty());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_unique_index_carries_the_unique_setting() {
|
||||
let index = IndexInfo {
|
||||
name: "uq_orders_ref".to_string(),
|
||||
columns: vec!["reference".to_string()],
|
||||
is_unique: true,
|
||||
is_primary: false,
|
||||
filter: None,
|
||||
index_type: None,
|
||||
included_columns: None,
|
||||
comment: None,
|
||||
};
|
||||
let table = doc_table("orders", vec![col("reference", "text")], vec![index]);
|
||||
let mut warnings = Vec::new();
|
||||
let out = render_table(&table, false, &mut warnings);
|
||||
assert!(out.contains("(reference) [name: 'uq_orders_ref', unique]"), "got:\n{out}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn the_primary_key_index_is_skipped_because_columns_already_carry_pk() {
|
||||
let index = IndexInfo {
|
||||
name: "orders_pkey".to_string(),
|
||||
columns: vec!["id".to_string()],
|
||||
is_unique: true,
|
||||
is_primary: true,
|
||||
filter: None,
|
||||
index_type: None,
|
||||
included_columns: None,
|
||||
comment: None,
|
||||
};
|
||||
let mut id = col("id", "integer");
|
||||
id.is_primary_key = true;
|
||||
let table = doc_table("orders", vec![id], vec![index]);
|
||||
|
||||
let mut warnings = Vec::new();
|
||||
let out = render_table(&table, false, &mut warnings);
|
||||
assert!(!out.contains("orders_pkey"), "got:\n{out}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_filtered_index_is_omitted_and_warned_about() {
|
||||
let index = IndexInfo {
|
||||
name: "idx_orders_open".to_string(),
|
||||
columns: vec!["status".to_string()],
|
||||
is_unique: false,
|
||||
is_primary: false,
|
||||
filter: Some("status <> 'cancelled'".to_string()),
|
||||
index_type: None,
|
||||
included_columns: None,
|
||||
comment: None,
|
||||
};
|
||||
let table = doc_table("orders", vec![col("status", "text")], vec![index]);
|
||||
|
||||
let mut warnings = Vec::new();
|
||||
let out = render_table(&table, false, &mut warnings);
|
||||
|
||||
assert!(!out.contains("idx_orders_open"), "filtered index must not be emitted, got:\n{out}");
|
||||
assert_eq!(warnings.len(), 1);
|
||||
match &warnings[0] {
|
||||
SnapshotWarning::DbmlOmitted { table, item, reason } => {
|
||||
assert_eq!(table, "public.orders");
|
||||
assert_eq!(item, "idx_orders_open");
|
||||
assert!(reason.contains("filter"), "got {reason}");
|
||||
}
|
||||
other => panic!("unexpected warning: {other:?}"),
|
||||
}
|
||||
}
|
||||
|
||||
use crate::docs::{Cardinality, DocEnum, FieldRef, Relationship, TableGroup};
|
||||
|
||||
fn relationship(cardinality: Cardinality) -> Relationship {
|
||||
Relationship {
|
||||
id: "r1".to_string(),
|
||||
name: Some("fk_orders_user".to_string()),
|
||||
from: FieldRef {
|
||||
schema: Some("public".to_string()),
|
||||
table: "orders".to_string(),
|
||||
column: "user_id".to_string(),
|
||||
},
|
||||
to: FieldRef { schema: Some("public".to_string()), table: "users".to_string(), column: "id".to_string() },
|
||||
cardinality,
|
||||
on_update: None,
|
||||
on_delete: Some("CASCADE".to_string()),
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn many_to_one_uses_the_gt_operator() {
|
||||
let out = render_ref(&relationship(Cardinality::ManyToOne), false);
|
||||
assert_eq!(out, "Ref fk_orders_user: orders.user_id > users.id [delete: cascade]\n");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn one_to_one_uses_the_dash_operator() {
|
||||
let out = render_ref(&relationship(Cardinality::OneToOne), false);
|
||||
assert!(out.contains("orders.user_id - users.id"), "got {out}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn refs_qualify_both_sides_together() {
|
||||
let out = render_ref(&relationship(Cardinality::ManyToOne), true);
|
||||
assert!(out.contains("public.orders.user_id > public.users.id"), "got {out}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn referential_actions_are_lowercased_and_both_emitted() {
|
||||
let mut rel = relationship(Cardinality::ManyToOne);
|
||||
rel.on_update = Some("NO ACTION".to_string());
|
||||
rel.on_delete = Some("RESTRICT".to_string());
|
||||
let out = render_ref(&rel, false);
|
||||
assert!(out.contains("[update: no action, delete: restrict]"), "got {out}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn an_unnamed_ref_omits_the_name() {
|
||||
let mut rel = relationship(Cardinality::ManyToOne);
|
||||
rel.name = None;
|
||||
assert!(render_ref(&rel, false).starts_with("Ref: orders.user_id"), "got {}", render_ref(&rel, false));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn renders_an_enum_block() {
|
||||
let value = DocEnum {
|
||||
schema: Some("public".to_string()),
|
||||
name: "order_status".to_string(),
|
||||
values: vec!["pending".to_string(), "shipped".to_string()],
|
||||
note: None,
|
||||
synthesized: false,
|
||||
};
|
||||
let out = render_enum(&value, false);
|
||||
assert_eq!(out, "Enum order_status {\n pending\n shipped\n}\n");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn renders_a_table_group_with_colour_and_note() {
|
||||
let group = TableGroup {
|
||||
id: "order-management".to_string(),
|
||||
name: "Order Management".to_string(),
|
||||
hue: 28,
|
||||
note: Some("Checkout to carrier handoff.".to_string()),
|
||||
};
|
||||
let orders = doc_table("orders", vec![], vec![]);
|
||||
let items = doc_table("order_items", vec![], vec![]);
|
||||
|
||||
let out = render_group(&group, &[&orders, &items], false);
|
||||
|
||||
assert!(out.starts_with("TableGroup \"Order Management\" [color: #"), "got:\n{out}");
|
||||
assert!(out.contains("\n orders\n"), "got:\n{out}");
|
||||
assert!(out.contains("\n order_items\n"), "got:\n{out}");
|
||||
assert!(out.contains("Note: '''Checkout to carrier handoff.'''"), "got:\n{out}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn an_empty_group_renders_nothing() {
|
||||
let group = TableGroup { id: "empty".to_string(), name: "Empty".to_string(), hue: 0, note: None };
|
||||
assert_eq!(render_group(&group, &[], false), "");
|
||||
}
|
||||
|
||||
use crate::docs::{ProjectMeta, SchemaSnapshot};
|
||||
|
||||
fn snapshot(tables: Vec<DocTable>, schemas: Vec<&str>) -> SchemaSnapshot {
|
||||
SchemaSnapshot {
|
||||
format_version: 1,
|
||||
project: ProjectMeta {
|
||||
name: "Ecommerce".to_string(),
|
||||
database_type: "PostgreSQL".to_string(),
|
||||
database: Some("shop".to_string()),
|
||||
schemas: schemas.into_iter().map(str::to_string).collect(),
|
||||
generated_at: "2026-08-02T12:00:00Z".to_string(),
|
||||
note: Some("Storefront database.".to_string()),
|
||||
},
|
||||
tables,
|
||||
relationships: vec![],
|
||||
groups: vec![],
|
||||
enums: vec![],
|
||||
warnings: vec![],
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn emits_a_project_block_first() {
|
||||
let out = to_dbml(&snapshot(vec![], vec!["public"]));
|
||||
assert!(out.text.starts_with("Project Ecommerce {\n"), "got:\n{}", out.text);
|
||||
assert!(out.text.contains("database_type: 'PostgreSQL'"), "got:\n{}", out.text);
|
||||
assert!(out.text.contains("Note: '''Storefront database.'''"), "got:\n{}", out.text);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_single_schema_snapshot_uses_bare_table_names() {
|
||||
let out = to_dbml(&snapshot(vec![doc_table("orders", vec![col("id", "integer")], vec![])], vec!["public"]));
|
||||
assert!(out.text.contains("Table orders {"), "got:\n{}", out.text);
|
||||
assert!(!out.text.contains("Table public.orders"), "got:\n{}", out.text);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_multi_schema_snapshot_qualifies_every_table() {
|
||||
let mut analytics = doc_table("daily_sales", vec![col("id", "integer")], vec![]);
|
||||
analytics.schema = Some("analytics".to_string());
|
||||
|
||||
let out = to_dbml(&snapshot(
|
||||
vec![doc_table("orders", vec![col("id", "integer")], vec![]), analytics],
|
||||
vec!["public", "analytics"],
|
||||
));
|
||||
|
||||
assert!(out.text.contains("Table public.orders {"), "got:\n{}", out.text);
|
||||
assert!(out.text.contains("Table analytics.daily_sales {"), "got:\n{}", out.text);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn sections_appear_in_order_project_enums_groups_tables_refs() {
|
||||
let mut snap = snapshot(vec![doc_table("orders", vec![col("id", "integer")], vec![])], vec!["public"]);
|
||||
snap.enums.push(DocEnum {
|
||||
schema: Some("public".to_string()),
|
||||
name: "order_status".to_string(),
|
||||
values: vec!["pending".to_string()],
|
||||
note: None,
|
||||
synthesized: false,
|
||||
});
|
||||
snap.groups.push(TableGroup {
|
||||
id: "order-management".to_string(),
|
||||
name: "Order Management".to_string(),
|
||||
hue: 28,
|
||||
note: None,
|
||||
});
|
||||
snap.tables[0].group_id = Some("order-management".to_string());
|
||||
snap.relationships.push(relationship(Cardinality::ManyToOne));
|
||||
|
||||
let text = to_dbml(&snap).text;
|
||||
let project = text.find("Project ").expect("project");
|
||||
let enum_at = text.find("Enum ").expect("enum");
|
||||
let group = text.find("TableGroup ").expect("group");
|
||||
let table = text.find("Table orders").expect("table");
|
||||
let reference = text.find("Ref ").expect("ref");
|
||||
|
||||
assert!(project < enum_at, "project before enums:\n{text}");
|
||||
assert!(enum_at < group, "enums before groups:\n{text}");
|
||||
assert!(group < table, "groups before tables:\n{text}");
|
||||
assert!(table < reference, "tables before refs:\n{text}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn warnings_from_table_rendering_reach_the_output() {
|
||||
let index = IndexInfo {
|
||||
name: "idx_partial".to_string(),
|
||||
columns: vec!["status".to_string()],
|
||||
is_unique: false,
|
||||
is_primary: false,
|
||||
filter: Some("status <> 'x'".to_string()),
|
||||
index_type: None,
|
||||
included_columns: None,
|
||||
comment: None,
|
||||
};
|
||||
let out =
|
||||
to_dbml(&snapshot(vec![doc_table("orders", vec![col("status", "text")], vec![index])], vec!["public"]));
|
||||
assert_eq!(out.warnings.len(), 1);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_group_referencing_a_missing_table_is_skipped() {
|
||||
let mut snap = snapshot(vec![doc_table("orders", vec![col("id", "integer")], vec![])], vec!["public"]);
|
||||
snap.groups.push(TableGroup { id: "ghost".to_string(), name: "Ghost".to_string(), hue: 200, note: None });
|
||||
assert!(!to_dbml(&snap).text.contains("Ghost"), "got:\n{}", to_dbml(&snap).text);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn collector_warnings_survive_into_the_output() {
|
||||
let mut snap = snapshot(vec![], vec!["public"]);
|
||||
snap.warnings.push(SnapshotWarning::TableSkipped {
|
||||
table: "public.secret".to_string(),
|
||||
reason: "permission denied".to_string(),
|
||||
});
|
||||
|
||||
let out = to_dbml(&snap);
|
||||
|
||||
assert_eq!(out.warnings.len(), 1, "collector warnings must not be dropped");
|
||||
match &out.warnings[0] {
|
||||
SnapshotWarning::TableSkipped { table, .. } => assert_eq!(table, "public.secret"),
|
||||
other => panic!("unexpected warning: {other:?}"),
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,98 @@
|
||||
use crate::models::connection::DatabaseType;
|
||||
|
||||
/// Fold an identifier to its canonical case for note matching.
|
||||
///
|
||||
/// PostgreSQL folds unquoted identifiers to lower case, Oracle to upper.
|
||||
/// MySQL depends on the server's `lower_case_table_names`; we fold to lower
|
||||
/// unconditionally rather than pay a `SHOW VARIABLES` round-trip per
|
||||
/// collection — on the rare case-sensitive configuration the only risk is
|
||||
/// matching a note to a table differing solely by case, never attaching a
|
||||
/// note to an unrelated table.
|
||||
///
|
||||
/// ClickHouse and MongoDB are genuinely case-sensitive: two identifiers
|
||||
/// differing only by case are DIFFERENT objects there, so folding them
|
||||
/// would let one note attach to the wrong one. They are left untouched.
|
||||
///
|
||||
/// The lower-case default is correct for the remaining SQL engines
|
||||
/// (SQLite, SQL Server, DuckDB, rqlite, Doris, StarRocks), all of which
|
||||
/// compare identifiers case-insensitively.
|
||||
pub fn fold_identifier(db_type: DatabaseType, value: &str) -> String {
|
||||
match db_type {
|
||||
DatabaseType::Oracle => value.to_uppercase(),
|
||||
DatabaseType::ClickHouse | DatabaseType::MongoDb => value.to_string(),
|
||||
_ => value.to_lowercase(),
|
||||
}
|
||||
}
|
||||
|
||||
/// `schema.table`, or bare `table` when there is no schema.
|
||||
pub fn table_key(db_type: DatabaseType, schema: Option<&str>, table: &str) -> String {
|
||||
match schema.filter(|value| !value.is_empty()) {
|
||||
Some(schema) => {
|
||||
format!("{}.{}", fold_identifier(db_type, schema), fold_identifier(db_type, table))
|
||||
}
|
||||
None => fold_identifier(db_type, table),
|
||||
}
|
||||
}
|
||||
|
||||
/// `schema.table.column`, or `table.column` when there is no schema.
|
||||
pub fn column_key(db_type: DatabaseType, schema: Option<&str>, table: &str, column: &str) -> String {
|
||||
format!("{}.{}", table_key(db_type, schema, table), fold_identifier(db_type, column))
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::models::connection::DatabaseType;
|
||||
|
||||
#[test]
|
||||
fn postgres_folds_to_lowercase() {
|
||||
assert_eq!(fold_identifier(DatabaseType::Postgres, "Orders"), "orders");
|
||||
assert_eq!(fold_identifier(DatabaseType::Postgres, "ORDERS"), "orders");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn mysql_folds_to_lowercase() {
|
||||
assert_eq!(fold_identifier(DatabaseType::Mysql, "Orders"), "orders");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn table_keys_are_qualified_when_a_schema_is_present() {
|
||||
assert_eq!(table_key(DatabaseType::Postgres, Some("Core"), "Orders"), "core.orders");
|
||||
assert_eq!(table_key(DatabaseType::Postgres, None, "Orders"), "orders");
|
||||
assert_eq!(table_key(DatabaseType::Postgres, Some(""), "Orders"), "orders");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn column_keys_extend_the_table_key() {
|
||||
assert_eq!(column_key(DatabaseType::Postgres, Some("core"), "orders", "Status"), "core.orders.status");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn folding_is_idempotent() {
|
||||
// Folding an already-folded value must be a no-op, or a key would
|
||||
// depend on how many times it had been normalised.
|
||||
for engine in [DatabaseType::Postgres, DatabaseType::Oracle, DatabaseType::ClickHouse] {
|
||||
let once = fold_identifier(engine, "MixedCase");
|
||||
assert_eq!(fold_identifier(engine, &once), once, "engine {engine:?}");
|
||||
}
|
||||
|
||||
let key_once = table_key(DatabaseType::Postgres, Some("Core"), "Orders");
|
||||
assert_eq!(key_once, "core.orders");
|
||||
// Re-folding each segment of an existing key must not change it.
|
||||
let refolded = key_once
|
||||
.split('.')
|
||||
.map(|segment| fold_identifier(DatabaseType::Postgres, segment))
|
||||
.collect::<Vec<_>>()
|
||||
.join(".");
|
||||
assert_eq!(refolded, key_once);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn case_sensitive_engines_are_not_folded() {
|
||||
// ClickHouse and MongoDB treat `Orders` and `orders` as DIFFERENT
|
||||
// objects. Folding them would let one note attach to the wrong one.
|
||||
assert_eq!(fold_identifier(DatabaseType::ClickHouse, "Orders"), "Orders");
|
||||
assert_eq!(fold_identifier(DatabaseType::MongoDb, "Orders"), "Orders");
|
||||
assert_eq!(table_key(DatabaseType::ClickHouse, Some("Analytics"), "Orders"), "Analytics.Orders");
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
pub mod annotations;
|
||||
pub mod collector;
|
||||
pub mod color;
|
||||
pub mod dbml;
|
||||
pub mod keys;
|
||||
pub mod relations;
|
||||
pub mod snapshot;
|
||||
|
||||
pub use collector::{collect_snapshot, CollectOptions, CollectProgress};
|
||||
pub use color::hue_to_hex;
|
||||
pub use dbml::{to_dbml, DbmlOutput};
|
||||
pub use keys::{column_key, fold_identifier, table_key};
|
||||
pub use relations::build_relationships;
|
||||
pub use snapshot::*;
|
||||
@@ -0,0 +1,392 @@
|
||||
use std::collections::HashSet;
|
||||
|
||||
use crate::docs::{Cardinality, DocTable, FieldRef, Relationship};
|
||||
use crate::types::ForeignKeyInfo;
|
||||
|
||||
/// True when `column` alone is guaranteed unique on `table` — either it is a
|
||||
/// single-column primary key, or a single-column unique index covers it.
|
||||
///
|
||||
/// A composite unique index over (a, b) does NOT make `a` unique, which is
|
||||
/// why the column count is checked.
|
||||
fn column_is_unique(table: &DocTable, column: &str) -> bool {
|
||||
let primary_columns: Vec<&str> =
|
||||
table.columns.iter().filter(|c| c.is_primary_key).map(|c| c.name.as_str()).collect();
|
||||
|
||||
if primary_columns.len() == 1 && primary_columns[0] == column {
|
||||
return true;
|
||||
}
|
||||
|
||||
table
|
||||
.indexes
|
||||
.iter()
|
||||
.any(|index| (index.is_unique || index.is_primary) && index.columns.len() == 1 && index.columns[0] == column)
|
||||
}
|
||||
|
||||
fn cardinality_for(table: &DocTable, foreign_key: &ForeignKeyInfo) -> Cardinality {
|
||||
if column_is_unique(table, &foreign_key.column) {
|
||||
Cardinality::OneToOne
|
||||
} else {
|
||||
Cardinality::ManyToOne
|
||||
}
|
||||
}
|
||||
|
||||
fn relationship_id(source: &DocTable, foreign_key: &ForeignKeyInfo) -> String {
|
||||
[
|
||||
source.qualified_name().as_str(),
|
||||
if foreign_key.name.is_empty() { "foreign_key" } else { foreign_key.name.as_str() },
|
||||
foreign_key.column.as_str(),
|
||||
foreign_key.ref_table.as_str(),
|
||||
foreign_key.ref_column.as_str(),
|
||||
]
|
||||
.join(":")
|
||||
}
|
||||
|
||||
/// Resolve a foreign key's target against the tables actually present.
|
||||
///
|
||||
/// Resolution order mirrors SQL's own: an explicit `ref_schema` wins; an
|
||||
/// unqualified reference resolves inside the source table's own schema;
|
||||
/// only then do we consider a bare-name match elsewhere — and an ambiguous
|
||||
/// one is dropped rather than guessed at, because a wrong edge is worse
|
||||
/// than a missing one.
|
||||
fn find_target<'a>(tables: &'a [DocTable], source: &DocTable, foreign_key: &ForeignKeyInfo) -> Option<&'a DocTable> {
|
||||
// An explicit ref_schema is authoritative: the database told us exactly
|
||||
// which schema the key points at. If that schema was not collected, the
|
||||
// edge must be DROPPED, not resolved elsewhere. Falling through would bind
|
||||
// it to a same-named table in a different schema — `sales.orders` pointing
|
||||
// at `archive.customers` would render as pointing at `sales.customers`,
|
||||
// which is a confidently wrong diagram rather than an incomplete one.
|
||||
if let Some(ref_schema) = foreign_key.ref_schema.as_deref().filter(|s| !s.is_empty()) {
|
||||
return tables.iter().find(|t| t.name == foreign_key.ref_table && t.schema.as_deref() == Some(ref_schema));
|
||||
}
|
||||
|
||||
if let Some(found) = tables.iter().find(|t| t.name == foreign_key.ref_table && t.schema == source.schema) {
|
||||
return Some(found);
|
||||
}
|
||||
|
||||
let mut matches = tables.iter().filter(|t| t.name == foreign_key.ref_table);
|
||||
let first = matches.next()?;
|
||||
if matches.next().is_some() {
|
||||
return None;
|
||||
}
|
||||
Some(first)
|
||||
}
|
||||
|
||||
/// Build the relationship set for a snapshot.
|
||||
///
|
||||
/// Foreign keys pointing at tables outside the collected set are dropped —
|
||||
/// the target may live in a schema the user did not select, and a dangling
|
||||
/// edge renders as a relationship to nothing.
|
||||
pub fn build_relationships(tables: &[DocTable]) -> Vec<Relationship> {
|
||||
let mut seen: HashSet<String> = HashSet::new();
|
||||
let mut relationships = Vec::new();
|
||||
|
||||
for source in tables {
|
||||
for foreign_key in &source.foreign_keys {
|
||||
let Some(target) = find_target(tables, source, foreign_key) else { continue };
|
||||
|
||||
if !source.columns.iter().any(|c| c.name == foreign_key.column) {
|
||||
continue;
|
||||
}
|
||||
|
||||
let id = relationship_id(source, foreign_key);
|
||||
if !seen.insert(id.clone()) {
|
||||
continue;
|
||||
}
|
||||
|
||||
relationships.push(Relationship {
|
||||
id,
|
||||
name: (!foreign_key.name.is_empty()).then(|| foreign_key.name.clone()),
|
||||
from: FieldRef {
|
||||
schema: source.schema.clone(),
|
||||
table: source.name.clone(),
|
||||
column: foreign_key.column.clone(),
|
||||
},
|
||||
to: FieldRef {
|
||||
schema: target.schema.clone(),
|
||||
table: target.name.clone(),
|
||||
column: foreign_key.ref_column.clone(),
|
||||
},
|
||||
cardinality: cardinality_for(source, foreign_key),
|
||||
on_update: foreign_key.on_update.clone(),
|
||||
on_delete: foreign_key.on_delete.clone(),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
relationships
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::docs::{NoteSource, TableKind};
|
||||
use crate::types::{ColumnInfo, ForeignKeyInfo, IndexInfo};
|
||||
use std::collections::BTreeMap;
|
||||
|
||||
fn column(name: &str, primary: bool) -> ColumnInfo {
|
||||
ColumnInfo {
|
||||
name: name.to_string(),
|
||||
data_type: "integer".to_string(),
|
||||
is_nullable: false,
|
||||
is_primary_key: primary,
|
||||
..ColumnInfo::default()
|
||||
}
|
||||
}
|
||||
|
||||
fn fk(name: &str, column: &str, ref_table: &str, ref_column: &str) -> ForeignKeyInfo {
|
||||
ForeignKeyInfo {
|
||||
name: name.to_string(),
|
||||
column: column.to_string(),
|
||||
ref_schema: Some("public".to_string()),
|
||||
ref_table: ref_table.to_string(),
|
||||
ref_column: ref_column.to_string(),
|
||||
on_update: None,
|
||||
on_delete: Some("CASCADE".to_string()),
|
||||
}
|
||||
}
|
||||
|
||||
fn table_in(schema: &str, name: &str, fks: Vec<ForeignKeyInfo>) -> DocTable {
|
||||
DocTable {
|
||||
schema: Some(schema.to_string()),
|
||||
name: name.to_string(),
|
||||
kind: TableKind::Table,
|
||||
columns: vec![column("id", true), column("customer_id", false)],
|
||||
indexes: Vec::new(),
|
||||
foreign_keys: fks,
|
||||
group_id: None,
|
||||
note: None,
|
||||
note_source: NoteSource::None,
|
||||
shadowed_note: None,
|
||||
column_notes: BTreeMap::new(),
|
||||
estimated_rows: None,
|
||||
view_definition: None,
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn an_unresolvable_explicit_ref_schema_does_not_fall_back_to_another_schema() {
|
||||
// sales.orders -> archive.customers, but only the `sales` schema was
|
||||
// collected. `archive.customers` is absent, and `sales.customers`
|
||||
// exists with the same bare name. Falling through to the source-schema
|
||||
// tier would bind the edge to sales.customers — a different table than
|
||||
// the foreign key names — and render a plausible but wrong diagram.
|
||||
let mut fk = fk("orders_customer_fk", "customer_id", "customers", "id");
|
||||
fk.ref_schema = Some("archive".to_string());
|
||||
|
||||
let tables = vec![table_in("sales", "orders", vec![fk]), table_in("sales", "customers", Vec::new())];
|
||||
|
||||
let relationships = build_relationships(&tables);
|
||||
assert!(
|
||||
relationships.is_empty(),
|
||||
"expected the edge to be dropped, got {:?}",
|
||||
relationships.iter().map(|r| (&r.from.table, &r.to.table)).collect::<Vec<_>>()
|
||||
);
|
||||
}
|
||||
|
||||
fn unique_index(name: &str, columns: &[&str]) -> IndexInfo {
|
||||
IndexInfo {
|
||||
name: name.to_string(),
|
||||
columns: columns.iter().map(|c| c.to_string()).collect(),
|
||||
is_unique: true,
|
||||
is_primary: false,
|
||||
filter: None,
|
||||
index_type: None,
|
||||
included_columns: None,
|
||||
comment: None,
|
||||
}
|
||||
}
|
||||
|
||||
fn table(name: &str, columns: Vec<ColumnInfo>, indexes: Vec<IndexInfo>, fks: Vec<ForeignKeyInfo>) -> DocTable {
|
||||
DocTable {
|
||||
schema: Some("public".to_string()),
|
||||
name: name.to_string(),
|
||||
kind: TableKind::Table,
|
||||
columns,
|
||||
indexes,
|
||||
foreign_keys: fks,
|
||||
group_id: None,
|
||||
note: None,
|
||||
note_source: NoteSource::None,
|
||||
shadowed_note: None,
|
||||
column_notes: BTreeMap::new(),
|
||||
estimated_rows: None,
|
||||
view_definition: None,
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn plain_foreign_key_is_many_to_one() {
|
||||
let tables = vec![
|
||||
table(
|
||||
"orders",
|
||||
vec![column("id", true), column("user_id", false)],
|
||||
vec![],
|
||||
vec![fk("fk_orders_user", "user_id", "users", "id")],
|
||||
),
|
||||
table("users", vec![column("id", true)], vec![], vec![]),
|
||||
];
|
||||
|
||||
let rels = build_relationships(&tables);
|
||||
|
||||
assert_eq!(rels.len(), 1);
|
||||
assert_eq!(rels[0].cardinality, Cardinality::ManyToOne);
|
||||
assert_eq!(rels[0].from.table, "orders");
|
||||
assert_eq!(rels[0].from.column, "user_id");
|
||||
assert_eq!(rels[0].to.table, "users");
|
||||
assert_eq!(rels[0].to.column, "id");
|
||||
assert_eq!(rels[0].on_delete.as_deref(), Some("CASCADE"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn foreign_key_on_a_unique_column_is_one_to_one() {
|
||||
let tables = vec![
|
||||
table(
|
||||
"shipments",
|
||||
vec![column("id", true), column("order_id", false)],
|
||||
vec![unique_index("uq_shipments_order", &["order_id"])],
|
||||
vec![fk("fk_shipments_order", "order_id", "orders", "id")],
|
||||
),
|
||||
table("orders", vec![column("id", true)], vec![], vec![]),
|
||||
];
|
||||
|
||||
let rels = build_relationships(&tables);
|
||||
|
||||
assert_eq!(rels.len(), 1);
|
||||
assert_eq!(rels[0].cardinality, Cardinality::OneToOne);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn foreign_key_on_a_primary_key_column_is_one_to_one() {
|
||||
let tables = vec![
|
||||
table(
|
||||
"user_profiles",
|
||||
vec![column("user_id", true)],
|
||||
vec![],
|
||||
vec![fk("fk_profile_user", "user_id", "users", "id")],
|
||||
),
|
||||
table("users", vec![column("id", true)], vec![], vec![]),
|
||||
];
|
||||
|
||||
assert_eq!(build_relationships(&tables)[0].cardinality, Cardinality::OneToOne);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn multi_column_unique_index_does_not_make_a_single_column_unique() {
|
||||
// uq(a, b) does NOT make `a` alone unique, so the FK stays many-to-one.
|
||||
let tables = vec![
|
||||
table(
|
||||
"order_items",
|
||||
vec![column("order_id", false), column("product_id", false)],
|
||||
vec![unique_index("uq_items", &["order_id", "product_id"])],
|
||||
vec![fk("fk_items_order", "order_id", "orders", "id")],
|
||||
),
|
||||
table("orders", vec![column("id", true)], vec![], vec![]),
|
||||
];
|
||||
|
||||
assert_eq!(build_relationships(&tables)[0].cardinality, Cardinality::ManyToOne);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn self_referencing_foreign_key_is_supported() {
|
||||
let tables = vec![table(
|
||||
"categories",
|
||||
vec![column("id", true), column("parent_id", false)],
|
||||
vec![],
|
||||
vec![fk("fk_cat_parent", "parent_id", "categories", "id")],
|
||||
)];
|
||||
|
||||
let rels = build_relationships(&tables);
|
||||
|
||||
assert_eq!(rels.len(), 1);
|
||||
assert_eq!(rels[0].from.table, "categories");
|
||||
assert_eq!(rels[0].to.table, "categories");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn foreign_key_to_an_absent_table_is_dropped() {
|
||||
// The target may live outside the selected schema. A dangling edge
|
||||
// would render as a relationship to nothing.
|
||||
let tables = vec![table(
|
||||
"orders",
|
||||
vec![column("user_id", false)],
|
||||
vec![],
|
||||
vec![fk("fk_orders_user", "user_id", "users", "id")],
|
||||
)];
|
||||
|
||||
assert!(build_relationships(&tables).is_empty());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn relationship_ids_are_stable_and_unique() {
|
||||
let tables = vec![
|
||||
table(
|
||||
"orders",
|
||||
vec![column("user_id", false), column("merchant_id", false)],
|
||||
vec![],
|
||||
vec![fk("fk_a", "user_id", "users", "id"), fk("fk_b", "merchant_id", "users", "id")],
|
||||
),
|
||||
table("users", vec![column("id", true)], vec![], vec![]),
|
||||
];
|
||||
|
||||
let rels = build_relationships(&tables);
|
||||
assert_eq!(rels.len(), 2);
|
||||
assert_ne!(rels[0].id, rels[1].id);
|
||||
assert_eq!(build_relationships(&tables)[0].id, rels[0].id);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn an_unqualified_foreign_key_resolves_within_the_source_schema() {
|
||||
let mut orders = table(
|
||||
"orders",
|
||||
vec![column("id", true), column("user_id", false)],
|
||||
vec![],
|
||||
vec![ForeignKeyInfo {
|
||||
name: "fk_orders_user".to_string(),
|
||||
column: "user_id".to_string(),
|
||||
ref_schema: None,
|
||||
ref_table: "users".to_string(),
|
||||
ref_column: "id".to_string(),
|
||||
on_update: None,
|
||||
on_delete: None,
|
||||
}],
|
||||
);
|
||||
orders.schema = Some("tenant_a".to_string());
|
||||
|
||||
let mut users_a = table("users", vec![column("id", true)], vec![], vec![]);
|
||||
users_a.schema = Some("tenant_a".to_string());
|
||||
let mut users_b = table("users", vec![column("id", true)], vec![], vec![]);
|
||||
users_b.schema = Some("tenant_b".to_string());
|
||||
|
||||
// tenant_b listed FIRST so a naive first-match would pick the wrong one.
|
||||
let rels = build_relationships(&[users_b, orders, users_a]);
|
||||
|
||||
assert_eq!(rels.len(), 1);
|
||||
assert_eq!(rels[0].to.schema.as_deref(), Some("tenant_a"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn an_ambiguous_bare_name_reference_is_dropped_rather_than_guessed() {
|
||||
let mut orders = table(
|
||||
"orders",
|
||||
vec![column("id", true), column("user_id", false)],
|
||||
vec![],
|
||||
vec![ForeignKeyInfo {
|
||||
name: "fk_orders_user".to_string(),
|
||||
column: "user_id".to_string(),
|
||||
ref_schema: None,
|
||||
ref_table: "users".to_string(),
|
||||
ref_column: "id".to_string(),
|
||||
on_update: None,
|
||||
on_delete: None,
|
||||
}],
|
||||
);
|
||||
orders.schema = Some("app".to_string());
|
||||
|
||||
let mut users_a = table("users", vec![column("id", true)], vec![], vec![]);
|
||||
users_a.schema = Some("tenant_a".to_string());
|
||||
let mut users_b = table("users", vec![column("id", true)], vec![], vec![]);
|
||||
users_b.schema = Some("tenant_b".to_string());
|
||||
|
||||
assert!(build_relationships(&[orders, users_a, users_b]).is_empty());
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,315 @@
|
||||
use std::collections::BTreeMap;
|
||||
|
||||
use serde::{Deserialize, Serialize};
|
||||
|
||||
use crate::types::{ColumnInfo, ForeignKeyInfo, IndexInfo};
|
||||
|
||||
/// The normalized description of a relational schema. Every documentation
|
||||
/// output (DBML, HTML, future changelog records) is a serializer over this.
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
#[serde(rename_all = "camelCase")]
|
||||
pub struct SchemaSnapshot {
|
||||
/// Guards viewer/data skew. Always 1 for now; bump only on a breaking
|
||||
/// change to this model.
|
||||
pub format_version: u32,
|
||||
pub project: ProjectMeta,
|
||||
pub tables: Vec<DocTable>,
|
||||
pub relationships: Vec<Relationship>,
|
||||
#[serde(default)]
|
||||
pub groups: Vec<TableGroup>,
|
||||
#[serde(default)]
|
||||
pub enums: Vec<DocEnum>,
|
||||
#[serde(default)]
|
||||
pub warnings: Vec<SnapshotWarning>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
#[serde(rename_all = "camelCase")]
|
||||
pub struct ProjectMeta {
|
||||
pub name: String,
|
||||
pub database_type: String,
|
||||
pub database: Option<String>,
|
||||
pub schemas: Vec<String>,
|
||||
/// RFC3339.
|
||||
pub generated_at: String,
|
||||
/// Markdown. Rendered as the documentation landing page.
|
||||
pub note: Option<String>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
#[serde(rename_all = "camelCase")]
|
||||
pub struct DocTable {
|
||||
pub schema: Option<String>,
|
||||
pub name: String,
|
||||
pub kind: TableKind,
|
||||
pub columns: Vec<ColumnInfo>,
|
||||
pub indexes: Vec<IndexInfo>,
|
||||
pub foreign_keys: Vec<ForeignKeyInfo>,
|
||||
/// References `TableGroup::id`. Populated in Part 2.
|
||||
pub group_id: Option<String>,
|
||||
/// Merged note: local annotation, else database comment.
|
||||
pub note: Option<String>,
|
||||
pub note_source: NoteSource,
|
||||
/// The database comment a local note is overriding, if any. Shown on
|
||||
/// hover so a later `COMMENT ON` improvement is never invisible.
|
||||
pub shadowed_note: Option<String>,
|
||||
#[serde(default)]
|
||||
pub column_notes: BTreeMap<String, ColumnNote>,
|
||||
pub estimated_rows: Option<i64>,
|
||||
pub view_definition: Option<String>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
#[serde(rename_all = "camelCase")]
|
||||
pub struct TableGroup {
|
||||
/// Stable slug. Survives a display-name change.
|
||||
pub id: String,
|
||||
pub name: String,
|
||||
/// 0..=359. Lightness and chroma are theme-controlled in CSS, so any
|
||||
/// hue is legible on both grounds by construction.
|
||||
pub hue: u16,
|
||||
pub note: Option<String>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
#[serde(rename_all = "camelCase")]
|
||||
pub struct ColumnNote {
|
||||
pub note: String,
|
||||
pub source: NoteSource,
|
||||
pub shadowed: Option<String>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
#[serde(rename_all = "camelCase")]
|
||||
pub struct DocEnum {
|
||||
pub schema: Option<String>,
|
||||
pub name: String,
|
||||
pub values: Vec<String>,
|
||||
pub note: Option<String>,
|
||||
/// True when synthesized from a MySQL inline `ENUM(...)` column rather
|
||||
/// than read from a named database type.
|
||||
#[serde(default)]
|
||||
pub synthesized: bool,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
#[serde(rename_all = "camelCase")]
|
||||
pub struct Relationship {
|
||||
pub id: String,
|
||||
pub name: Option<String>,
|
||||
pub from: FieldRef,
|
||||
pub to: FieldRef,
|
||||
pub cardinality: Cardinality,
|
||||
pub on_update: Option<String>,
|
||||
pub on_delete: Option<String>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
|
||||
#[serde(rename_all = "camelCase")]
|
||||
pub struct FieldRef {
|
||||
pub schema: Option<String>,
|
||||
pub table: String,
|
||||
pub column: String,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
|
||||
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
|
||||
pub enum TableKind {
|
||||
Table,
|
||||
View,
|
||||
MaterializedView,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
|
||||
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
|
||||
pub enum NoteSource {
|
||||
/// Read from a database COMMENT.
|
||||
Database,
|
||||
/// Authored in DBX, stored in the notes file.
|
||||
Local,
|
||||
None,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
|
||||
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
|
||||
pub enum Cardinality {
|
||||
OneToOne,
|
||||
ManyToOne,
|
||||
}
|
||||
|
||||
/// Why a snapshot is less complete than it looks. Rendered as a dismissible
|
||||
/// banner rather than left for the reader to discover.
|
||||
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
|
||||
#[serde(rename_all = "camelCase", tag = "kind")]
|
||||
pub enum SnapshotWarning {
|
||||
TableSkipped { table: String, reason: String },
|
||||
NoForeignKeyMetadata { engine: String },
|
||||
CommentsUnsupported { engine: String },
|
||||
OrphanedNotes { count: usize },
|
||||
DbmlOmitted { table: String, item: String, reason: String },
|
||||
}
|
||||
|
||||
/// Human-readable warning text for headless callers.
|
||||
///
|
||||
/// The viewer translates these through its own `docs.warnings` namespace; the
|
||||
/// CLI has no i18n runtime, so the English prose lives here. Without it the
|
||||
/// only thing to print is the derived `Debug` form, which exposes the struct
|
||||
/// shape and reads like a panic rather than like advice.
|
||||
impl std::fmt::Display for SnapshotWarning {
|
||||
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
||||
match self {
|
||||
Self::TableSkipped { table, reason } => {
|
||||
write!(formatter, "{table} was skipped: {reason}. It is missing from this documentation.")
|
||||
}
|
||||
Self::NoForeignKeyMetadata { engine } => {
|
||||
write!(
|
||||
formatter,
|
||||
"{engine} does not report foreign key metadata, so no relationships could be derived."
|
||||
)
|
||||
}
|
||||
Self::CommentsUnsupported { engine } => write!(
|
||||
formatter,
|
||||
"{engine} does not support table or column comments, so every description comes from your own notes."
|
||||
),
|
||||
Self::OrphanedNotes { count } => write!(
|
||||
formatter,
|
||||
"{count} note(s) refer to a table or column that no longer exists. Nothing was deleted."
|
||||
),
|
||||
Self::DbmlOmitted { table, item, reason } => {
|
||||
write!(formatter, "{item} on {table} is documented but omitted from the DBML: {reason}.")
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl DocTable {
|
||||
/// `schema.name` when a schema is present, otherwise bare `name`.
|
||||
pub fn qualified_name(&self) -> String {
|
||||
match &self.schema {
|
||||
Some(schema) if !schema.is_empty() => format!("{schema}.{}", self.name),
|
||||
_ => self.name.clone(),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl FieldRef {
|
||||
pub fn qualified_table(&self) -> String {
|
||||
match &self.schema {
|
||||
Some(schema) if !schema.is_empty() => format!("{schema}.{}", self.table),
|
||||
_ => self.table.clone(),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
fn sample() -> SchemaSnapshot {
|
||||
SchemaSnapshot {
|
||||
format_version: 1,
|
||||
project: ProjectMeta {
|
||||
name: "Ecommerce".to_string(),
|
||||
database_type: "PostgreSQL".to_string(),
|
||||
database: Some("shop".to_string()),
|
||||
schemas: vec!["public".to_string()],
|
||||
generated_at: "2026-08-02T12:00:00Z".to_string(),
|
||||
note: None,
|
||||
},
|
||||
tables: vec![DocTable {
|
||||
schema: Some("public".to_string()),
|
||||
name: "orders".to_string(),
|
||||
kind: TableKind::Table,
|
||||
columns: vec![],
|
||||
indexes: vec![],
|
||||
foreign_keys: vec![],
|
||||
group_id: None,
|
||||
note: Some("Checkout rows.".to_string()),
|
||||
note_source: NoteSource::Database,
|
||||
shadowed_note: None,
|
||||
column_notes: BTreeMap::new(),
|
||||
estimated_rows: Some(2_400_000),
|
||||
view_definition: None,
|
||||
}],
|
||||
relationships: vec![],
|
||||
groups: vec![],
|
||||
enums: vec![],
|
||||
warnings: vec![],
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn snapshot_round_trips_through_json() {
|
||||
let original = sample();
|
||||
let json = serde_json::to_string(&original).expect("serialize");
|
||||
let parsed: SchemaSnapshot = serde_json::from_str(&json).expect("deserialize");
|
||||
|
||||
assert_eq!(parsed.format_version, 1);
|
||||
assert_eq!(parsed.project.name, "Ecommerce");
|
||||
assert_eq!(parsed.tables.len(), 1);
|
||||
assert_eq!(parsed.tables[0].name, "orders");
|
||||
assert_eq!(parsed.tables[0].note.as_deref(), Some("Checkout rows."));
|
||||
assert_eq!(parsed.tables[0].estimated_rows, Some(2_400_000));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn snapshot_json_uses_camel_case_keys() {
|
||||
let json = serde_json::to_string(&sample()).expect("serialize");
|
||||
assert!(json.contains("\"formatVersion\""), "got: {json}");
|
||||
assert!(json.contains("\"generatedAt\""), "got: {json}");
|
||||
assert!(json.contains("\"noteSource\""), "got: {json}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn table_kind_serializes_as_screaming_snake_case() {
|
||||
let json = serde_json::to_string(&TableKind::MaterializedView).expect("serialize");
|
||||
assert_eq!(json, "\"MATERIALIZED_VIEW\"");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn every_warning_renders_as_prose() {
|
||||
// `dbx dbml` prints these to stderr. The derived Debug form leaks the
|
||||
// struct shape (`DbmlOmitted { table: "public.t", .. }`), which reads
|
||||
// as a crash report rather than as advice, so Display is what the CLI
|
||||
// must use. The wording tracks the viewer's own warning strings.
|
||||
let cases = [
|
||||
(
|
||||
SnapshotWarning::TableSkipped { table: "public.orders".into(), reason: "permission denied".into() },
|
||||
"public.orders was skipped: permission denied. It is missing from this documentation.",
|
||||
),
|
||||
(
|
||||
SnapshotWarning::NoForeignKeyMetadata { engine: "ClickHouse".into() },
|
||||
"ClickHouse does not report foreign key metadata, so no relationships could be derived.",
|
||||
),
|
||||
(
|
||||
SnapshotWarning::CommentsUnsupported { engine: "SQLite".into() },
|
||||
"SQLite does not support table or column comments, so every description comes from your own notes.",
|
||||
),
|
||||
(
|
||||
SnapshotWarning::OrphanedNotes { count: 3 },
|
||||
"3 note(s) refer to a table or column that no longer exists. Nothing was deleted.",
|
||||
),
|
||||
(
|
||||
SnapshotWarning::DbmlOmitted {
|
||||
table: "public.orders".into(),
|
||||
item: "idx_partial".into(),
|
||||
reason: "partial index filter has no DBML equivalent".into(),
|
||||
},
|
||||
"idx_partial on public.orders is documented but omitted from the DBML: partial index filter has no DBML equivalent.",
|
||||
),
|
||||
];
|
||||
|
||||
for (warning, expected) in cases {
|
||||
assert_eq!(warning.to_string(), expected);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_warning_never_renders_as_its_debug_form() {
|
||||
// The regression this guards: reverting the CLI to `{warning:?}` is a
|
||||
// one-character edit that still compiles and still prints something.
|
||||
let warning = SnapshotWarning::OrphanedNotes { count: 1 };
|
||||
assert!(!warning.to_string().contains('{'), "got: {warning}");
|
||||
assert_ne!(warning.to_string(), format!("{warning:?}"));
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user