mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-07 07:55:13 +02:00
620d6adbe6
* docs: rewrite Semantic Querying concept with imperative-vs-declarative diagram
Reframe semantic-layer-internals.mdx around the contract the semantic
layer offers an agent: declare what you want (a Semantic Query), KTX
figures out how to compute it. Replaces the old "Context-Aware SQL"
framing with a clear imperative-vs-declarative narrative.
Adds a React Flow component (semantic-layer-flow.tsx) that contrasts a
buggy 4-table agent-authored SQL (chasm trap, LEFT-JOIN-in-WHERE,
hardcoded DATE_TRUNC) against the chasm-safe per-fact CTE SQL the
planner actually emits, including the outer GROUP BY over the requested
dimensions. Both lanes converge into a shared warehouse node and each
SQL card now has parallel bullet notes (failures on the left, KTX
behavior on the right).
Side fixes bundled in:
- include the /ktx basePath in the favicon metadata so the icon resolves
under the production prefix
- migrate docs-site/middleware.ts to docs-site/proxy.ts (Next 16 rename)
- redirect / to /ktx/docs/getting-started/introduction so the apex docs
URL works
- add tests covering the apex redirect, the favicon basePath, and the
middleware-to-proxy rename
- propagate the Semantic Query terminology across the ktx-sl CLI
reference, the context-layer concept page, and the agent-clients /
primary-sources integration pages
* Fix CI dead-code failures
* docs-site: polish semantic-layer-internals code blocks and flow diagram
- Make CodeBlock a server component so children traverse synchronously
under React 19 RSC streaming; previously extractText returned "" in
dev SSR, leaving code blocks empty.
- Add custom JSON/YAML/SQL/code-like tokenizers with theme-aware token
classes; drop the colored file-glyph dot and gradient tab-head.
- Tighten tab-head: subtle grey background, smaller monospace filename
in muted grey, smaller rectangular language pill placed to the left
of the filename.
- Polish the React Flow semantic-layer diagram (controls, fit-view
padding, edge types).
* docs-site: annotate imperative SQL, add section anchor, drop ClickHouse
- Wire numbered red badges to each problematic span in the "Without KTX"
SQL with hover sync between SQL gutter, lines, and the notes list.
- Add #imperative-vs-declarative anchor on the flow section header so
the eyebrow link is shareable; reveals a # glyph on hover/focus.
- Align the compiled-SQL note dots to the first-line midpoint
(mt-[6px] instead of mt-1) so 4px dots sit at y=8 in a 16px line.
- Remove all ClickHouse references from docs-site (primary-sources,
quickstart, ktx-setup, contributing, agents-setup, mechanics test,
warehouse drivers in the flow diagram).
* test: drop ClickHouse contributing-docs assertion
Align the workspace-package mirror test with the ClickHouse removal
from docs-site (75907eb). The connector-clickhouse package still
exists in packages/, but contributing.mdx no longer lists it, so the
test that mirrored docs against the workspace was failing.
70 lines
2.6 KiB
JavaScript
70 lines
2.6 KiB
JavaScript
import assert from "node:assert/strict";
|
|
import { access, readFile } from "node:fs/promises";
|
|
import { dirname, join } from "node:path";
|
|
import { test } from "node:test";
|
|
import { fileURLToPath } from "node:url";
|
|
|
|
const docsSiteDir = join(dirname(fileURLToPath(import.meta.url)), "..");
|
|
|
|
async function readDocsFile(path) {
|
|
return readFile(join(docsSiteDir, path), "utf8");
|
|
}
|
|
|
|
test("root provider uses the base-path-aware search API", async () => {
|
|
const layout = await readDocsFile("app/layout.tsx");
|
|
|
|
assert.match(layout, /search=\{\{/);
|
|
assert.match(layout, /api:\s*"\/ktx\/api\/search"/);
|
|
});
|
|
|
|
test("metadata icons include the docs base path", async () => {
|
|
const layout = await readDocsFile("app/layout.tsx");
|
|
|
|
assert.match(layout, /icon:\s*"\/ktx\/brand\/ktx-mascot\.svg"/);
|
|
assert.match(layout, /shortcut:\s*"\/ktx\/brand\/ktx-mascot\.svg"/);
|
|
assert.doesNotMatch(layout, /:\s*"\/brand\/ktx-mascot\.svg"/);
|
|
});
|
|
|
|
test("markdown negotiation uses the Next proxy convention", async () => {
|
|
await assert.doesNotReject(access(join(docsSiteDir, "proxy.ts")));
|
|
await assert.rejects(access(join(docsSiteDir, "middleware.ts")));
|
|
|
|
const proxy = await readDocsFile("proxy.ts");
|
|
assert.match(proxy, /export function proxy/);
|
|
assert.doesNotMatch(proxy, /export function middleware/);
|
|
});
|
|
|
|
test("site background stacking does not target every body child", async () => {
|
|
const css = await readDocsFile("app/global.css");
|
|
|
|
assert.doesNotMatch(css, /body\s*>\s*\*\s*\{[^}]*z-index/s);
|
|
assert.match(css, /\.ktx-site-shell\s*\{[^}]*z-index:\s*2/s);
|
|
});
|
|
|
|
test("search lock relies on body overflow propagation, not html or sidebar overrides", async () => {
|
|
const css = await readDocsFile("app/global.css");
|
|
|
|
// Body still clips horizontal overflow defensively.
|
|
assert.match(css, /(^|\s)body\s*\{[^}]*overflow-x:\s*clip/s);
|
|
|
|
// html must keep its default `visible` overflow so body's lock
|
|
// (`overflow: hidden` from react-remove-scroll-bar) propagates to the
|
|
// viewport. Locking html directly breaks `position: sticky` on the
|
|
// sidebar placeholder.
|
|
assert.doesNotMatch(css, /(^|\s)html\s*,?\s*\{[^}]*overflow(-y|\s*:)\s*(hidden|clip)/s);
|
|
assert.doesNotMatch(
|
|
css,
|
|
/html:has\(body\[data-scroll-locked\]\)[^{]*\{[^}]*overflow:\s*(hidden|clip)/s,
|
|
);
|
|
|
|
// No site-specific overrides to body's data-scroll-locked overflow or
|
|
// to the sidebar placeholder when locked.
|
|
assert.doesNotMatch(
|
|
css,
|
|
/html\s+body\[data-scroll-locked\][^{]*\{[^}]*overflow:/s,
|
|
);
|
|
assert.doesNotMatch(
|
|
css,
|
|
/body\[data-scroll-locked\]\s+\[data-sidebar-placeholder\][^{]*\{[^}]*position:\s*fixed/s,
|
|
);
|
|
});
|