docs: Plan 1 (frontend + contract + replay) for F4 column curation
Bite-sized TDD tasks: schema-linking types + columns modal, gate widget with staged per-table column selection, registry/summary wiring, and a replay fixture generated from the real physical.yaml catalog. Offline-verifiable in the replay server; harness wiring is Plan 2. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
committed by
Marco Pancotti
Marco Pancotti
co-authored by
Claude Opus 4.8
Claude Opus 4.8
parent
94d171ddf1
commit
106a0de047
@@ -0,0 +1,707 @@
|
||||
# F4 schema-linking column curation — Plan 1 (frontend + contract + replay)
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Render the F4 "tabelle/colonne/esclusioni" gate as a dedicated `schema-linking` widget: table rows with description + rationale, a per-table columns modal (checkbox, suggested pre-selected + bold), staged, emitting a structured response — verifiable offline in replay.
|
||||
|
||||
**Architecture:** New inline gate widget (`SchemaLinkingGateWidget`) owns staged state (`enacted` set + per-table selected-columns map); a controlled modal (`SchemaColumnsDialog`) renders one table's columns. On the gate's Confirm the widget emits a structured `UiResponse.tables[]`. Phase 1 is frontend-only: no backend/harness wiring — the response is exercised through the zero-dep replay server, whose gate 7 is rewritten to the new descriptor from the real catalog.
|
||||
|
||||
**Tech Stack:** React 18 + TypeScript, Vite, vitest + @testing-library/react + userEvent, base-ui Dialog (`components/ui/dialog`), Tailwind v3 (GSD tokens). Replay: zero-dep node (`tools/replay/`).
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- `tsc` is the type gate — run `npx tsc -b` from `frontend/` before every commit (vitest does NOT type-check).
|
||||
- Tests: vitest + MSW, **no network**. Single test run: `npx vitest run <file>`.
|
||||
- UI chrome/labels in **English**; data *content* (table/column names, Italian descriptions) stays as-is.
|
||||
- Reuse look&feel v2 tokens only: cards `border-border/70` + `shadow-sm`, `.thot-label` (mono uppercase micro-label), radii `rounded-xl` cards / `rounded-lg` inputs / `rounded-md` controls / `2xl` dialogs; **no `#000`/`#fff`, no new color tokens**. First action renders as filled primary.
|
||||
- No em dashes in copy you write (use commas/colons/parentheses).
|
||||
- Response contract (verbatim): `{ id, kind: "schema-linking", tables: [{ id, enacted, columns? }] }`. `columns` present only for **enacted promote** tables; column order follows catalog order.
|
||||
- Verify offline in **replay** only (no VPN): `tools/replay/` server on :5333.
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
| File | Responsibility |
|
||||
|---|---|
|
||||
| `frontend/src/api/types.ts` (modify) | Add `SchemaColumn`, `SchemaTable`; extend `WidgetDescriptor.tables?`, `UiResponse.tables?`. |
|
||||
| `frontend/src/widgets/SchemaColumnsDialog.tsx` (create) | Controlled modal listing one table's columns; checkbox first; bold-when-selected; `readOnly` hides checkboxes. |
|
||||
| `frontend/src/widgets/SchemaColumnsDialog.test.tsx` (create) | Unit: bold on selected, toggle callback, readOnly non-selectable. |
|
||||
| `frontend/src/widgets/SchemaLinkingGateWidget.tsx` (create) | Inline gate: staged `enacted`+`selected`, table rows, opens dialog, Confirm → structured response. |
|
||||
| `frontend/src/widgets/SchemaLinkingGateWidget.test.tsx` (create) | Unit: staged suggestion, structured response, column toggle, enact toggle, reserved. |
|
||||
| `frontend/src/widgets/index.ts` (modify) | `register("schema-linking", SchemaLinkingGateWidget)`. |
|
||||
| `frontend/src/shell/WidgetHost.tsx` (modify) | Summarize the `schema-linking` response for `lastUserEntry`. |
|
||||
| `tools/replay/schema-linking-fixture.json` (create, generated) | The 6-table `tables[]` array extracted from `physical.yaml` + session `schema_linking.json`. |
|
||||
| `tools/replay/augment-schema-linking.mjs` (create) | Rewrite replay gate 7 → `schema-linking` descriptor. |
|
||||
|
||||
---
|
||||
|
||||
## Task 1: Type contract + SchemaColumnsDialog
|
||||
|
||||
**Files:**
|
||||
- Modify: `frontend/src/api/types.ts`
|
||||
- Create: `frontend/src/widgets/SchemaColumnsDialog.tsx`
|
||||
- Test: `frontend/src/widgets/SchemaColumnsDialog.test.tsx`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces: `SchemaColumn`, `SchemaTable` (in `api/types.ts`); `SchemaColumnsDialog(props)` where
|
||||
`props = { table: SchemaTable; open: boolean; readOnly: boolean; selected: Set<string>; onToggle: (column: string) => void; onClose: () => void }`.
|
||||
|
||||
- [ ] **Step 1: Add the types**
|
||||
|
||||
In `frontend/src/api/types.ts`, add above `WidgetDescriptor`:
|
||||
|
||||
```ts
|
||||
export interface SchemaColumn {
|
||||
name: string;
|
||||
description?: string;
|
||||
type?: string;
|
||||
pk?: boolean;
|
||||
suggested?: boolean;
|
||||
}
|
||||
|
||||
export interface SchemaTable {
|
||||
id: string;
|
||||
name: string;
|
||||
kind: "promote" | "exclude";
|
||||
recommended?: boolean;
|
||||
description?: string;
|
||||
rationale?: string;
|
||||
columns: SchemaColumn[];
|
||||
}
|
||||
```
|
||||
|
||||
Add `tables?: SchemaTable[];` to the `WidgetDescriptor` interface (before the `[k: string]: unknown` line), and add to `UiResponse`:
|
||||
|
||||
```ts
|
||||
tables?: { id: string; enacted: boolean; columns?: string[] }[];
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Write the failing test**
|
||||
|
||||
Create `frontend/src/widgets/SchemaColumnsDialog.test.tsx`:
|
||||
|
||||
```tsx
|
||||
import { render, screen } from "@testing-library/react";
|
||||
import userEvent from "@testing-library/user-event";
|
||||
import { SchemaColumnsDialog } from "./SchemaColumnsDialog";
|
||||
import type { SchemaTable } from "../api/types";
|
||||
|
||||
const table: SchemaTable = {
|
||||
id: "t-pat",
|
||||
name: "dim_patient",
|
||||
kind: "promote",
|
||||
columns: [
|
||||
{ name: "cod_paz", description: "Codice paziente", suggested: true },
|
||||
{ name: "nome", description: "Nome", suggested: false },
|
||||
],
|
||||
};
|
||||
|
||||
test("selected column renders bold; unselected is normal; toggle fires", async () => {
|
||||
const onToggle = vi.fn();
|
||||
render(
|
||||
<SchemaColumnsDialog
|
||||
table={table}
|
||||
open
|
||||
readOnly={false}
|
||||
selected={new Set(["cod_paz"])}
|
||||
onToggle={onToggle}
|
||||
onClose={() => {}}
|
||||
/>
|
||||
);
|
||||
expect(screen.getByText("cod_paz").className).toContain("font-bold");
|
||||
expect(screen.getByText("nome").className).not.toContain("font-bold");
|
||||
await userEvent.click(screen.getByRole("checkbox", { name: "nome" }));
|
||||
expect(onToggle).toHaveBeenCalledWith("nome");
|
||||
});
|
||||
|
||||
test("readOnly renders no checkboxes and no bold", () => {
|
||||
render(
|
||||
<SchemaColumnsDialog
|
||||
table={table}
|
||||
open
|
||||
readOnly
|
||||
selected={new Set()}
|
||||
onToggle={() => {}}
|
||||
onClose={() => {}}
|
||||
/>
|
||||
);
|
||||
expect(screen.queryByRole("checkbox")).toBeNull();
|
||||
expect(screen.getByText("cod_paz")).toBeInTheDocument();
|
||||
expect(screen.getByText("cod_paz").className).not.toContain("font-bold");
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Run test to verify it fails**
|
||||
|
||||
Run: `cd frontend && npx vitest run src/widgets/SchemaColumnsDialog.test.tsx`
|
||||
Expected: FAIL — cannot resolve `./SchemaColumnsDialog`.
|
||||
|
||||
- [ ] **Step 4: Implement the dialog**
|
||||
|
||||
Create `frontend/src/widgets/SchemaColumnsDialog.tsx`:
|
||||
|
||||
```tsx
|
||||
import type { ReactElement } from "react";
|
||||
import type { SchemaTable } from "../api/types";
|
||||
import { Dialog, DialogContent, DialogTitle } from "../components/ui/dialog";
|
||||
|
||||
export function SchemaColumnsDialog({
|
||||
table,
|
||||
open,
|
||||
readOnly,
|
||||
selected,
|
||||
onToggle,
|
||||
onClose,
|
||||
}: {
|
||||
table: SchemaTable;
|
||||
open: boolean;
|
||||
readOnly: boolean;
|
||||
selected: Set<string>;
|
||||
onToggle: (column: string) => void;
|
||||
onClose: () => void;
|
||||
}): ReactElement {
|
||||
return (
|
||||
<Dialog open={open} onOpenChange={(o) => { if (!o) onClose(); }}>
|
||||
<DialogContent className="grid max-h-[70vh] w-[70vw] max-w-[46rem] grid-rows-[auto_1fr] gap-3 sm:max-w-[46rem]">
|
||||
<DialogTitle className="font-mono text-sm">{table.name}</DialogTitle>
|
||||
<div className="min-h-0 overflow-auto">
|
||||
<ul className="flex flex-col divide-y divide-border/50">
|
||||
{table.columns.map((col) => {
|
||||
const on = selected.has(col.name);
|
||||
const strong = on && !readOnly;
|
||||
return (
|
||||
<li key={col.name} className="flex items-start gap-3 py-2">
|
||||
{!readOnly && (
|
||||
<input
|
||||
type="checkbox"
|
||||
className="mt-0.5 size-4 shrink-0 accent-[oklch(var(--primary))]"
|
||||
checked={on}
|
||||
onChange={() => onToggle(col.name)}
|
||||
aria-label={col.name}
|
||||
/>
|
||||
)}
|
||||
<div className="min-w-0">
|
||||
<div className={`font-mono text-sm ${strong ? "font-bold text-foreground" : "text-foreground/90"}`}>
|
||||
{col.name}
|
||||
</div>
|
||||
{col.description ? (
|
||||
<p className={`text-sm ${strong ? "font-semibold text-foreground" : "text-muted-foreground"}`}>
|
||||
{col.description}
|
||||
</p>
|
||||
) : null}
|
||||
</div>
|
||||
</li>
|
||||
);
|
||||
})}
|
||||
</ul>
|
||||
</div>
|
||||
</DialogContent>
|
||||
</Dialog>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 5: Run tests to verify they pass**
|
||||
|
||||
Run: `cd frontend && npx vitest run src/widgets/SchemaColumnsDialog.test.tsx`
|
||||
Expected: PASS (2 tests).
|
||||
|
||||
- [ ] **Step 6: Typecheck + commit**
|
||||
|
||||
Run: `cd frontend && npx tsc -b`
|
||||
Expected: no errors.
|
||||
|
||||
```bash
|
||||
git add frontend/src/api/types.ts frontend/src/widgets/SchemaColumnsDialog.tsx frontend/src/widgets/SchemaColumnsDialog.test.tsx
|
||||
git commit -m "feat(frontend): schema-linking types + columns modal"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 2: SchemaLinkingGateWidget
|
||||
|
||||
**Files:**
|
||||
- Create: `frontend/src/widgets/SchemaLinkingGateWidget.tsx`
|
||||
- Test: `frontend/src/widgets/SchemaLinkingGateWidget.test.tsx`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: `WidgetProps` (`{ descriptor, onRespond }`), `SchemaTable`/`SchemaColumn` from `api/types.ts`, `SchemaColumnsDialog` from Task 1, `ReservedControls` from `./ReservedControls`.
|
||||
- Produces: `SchemaLinkingGateWidget: React.FC<WidgetProps>` handling `descriptor.widget === "schema-linking"`, emitting `onRespond({ id, kind: "schema-linking", tables: [{ id, enacted, columns? }] })`.
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
Create `frontend/src/widgets/SchemaLinkingGateWidget.test.tsx`:
|
||||
|
||||
```tsx
|
||||
import { render, screen } from "@testing-library/react";
|
||||
import userEvent from "@testing-library/user-event";
|
||||
import { SchemaLinkingGateWidget } from "./SchemaLinkingGateWidget";
|
||||
import type { WidgetDescriptor } from "../api/types";
|
||||
|
||||
const descriptor: WidgetDescriptor = {
|
||||
id: "u7",
|
||||
widget: "schema-linking",
|
||||
title: "F4 — Schema linking",
|
||||
tables: [
|
||||
{
|
||||
id: "t-pat",
|
||||
name: "dim_patient",
|
||||
kind: "promote",
|
||||
recommended: true,
|
||||
description: "Anagrafica",
|
||||
rationale: "Output paziente",
|
||||
columns: [
|
||||
{ name: "cod_paz", description: "Codice", suggested: true },
|
||||
{ name: "nome", description: "Nome", suggested: false },
|
||||
],
|
||||
},
|
||||
{
|
||||
id: "x-sub",
|
||||
name: "fact_sostituzione",
|
||||
kind: "exclude",
|
||||
recommended: true,
|
||||
description: "Sostituzione",
|
||||
rationale: "Non impianto iniziale",
|
||||
columns: [{ name: "cod_paz" }],
|
||||
},
|
||||
],
|
||||
reserved: ["back", "exit", "other"],
|
||||
};
|
||||
|
||||
test("Confirm emits enacted tables with suggested columns (catalog order)", async () => {
|
||||
const onRespond = vi.fn();
|
||||
render(<SchemaLinkingGateWidget descriptor={descriptor} onRespond={onRespond} />);
|
||||
await userEvent.click(screen.getByRole("button", { name: /confirm/i }));
|
||||
expect(onRespond).toHaveBeenCalledWith({
|
||||
id: "u7",
|
||||
kind: "schema-linking",
|
||||
tables: [
|
||||
{ id: "t-pat", enacted: true, columns: ["cod_paz"] },
|
||||
{ id: "x-sub", enacted: true },
|
||||
],
|
||||
});
|
||||
});
|
||||
|
||||
test("selecting a column in the modal adds it to the response", async () => {
|
||||
const onRespond = vi.fn();
|
||||
render(<SchemaLinkingGateWidget descriptor={descriptor} onRespond={onRespond} />);
|
||||
// dim_patient starts with 1 suggested of 2 -> its button reads "Colonne 1/2".
|
||||
await userEvent.click(screen.getByRole("button", { name: /colonne 1\/2/i }));
|
||||
await userEvent.click(screen.getByRole("checkbox", { name: "nome" }));
|
||||
await userEvent.click(screen.getByRole("button", { name: /close/i })); // dialog X button
|
||||
await userEvent.click(screen.getByRole("button", { name: /confirm/i }));
|
||||
expect(onRespond).toHaveBeenCalledWith({
|
||||
id: "u7",
|
||||
kind: "schema-linking",
|
||||
tables: [
|
||||
{ id: "t-pat", enacted: true, columns: ["cod_paz", "nome"] },
|
||||
{ id: "x-sub", enacted: true },
|
||||
],
|
||||
});
|
||||
});
|
||||
|
||||
test("declining a table's enact checkbox drops its columns", async () => {
|
||||
const onRespond = vi.fn();
|
||||
render(<SchemaLinkingGateWidget descriptor={descriptor} onRespond={onRespond} />);
|
||||
await userEvent.click(screen.getByRole("checkbox", { name: /dim_patient/i }));
|
||||
await userEvent.click(screen.getByRole("button", { name: /confirm/i }));
|
||||
expect(onRespond).toHaveBeenCalledWith({
|
||||
id: "u7",
|
||||
kind: "schema-linking",
|
||||
tables: [
|
||||
{ id: "t-pat", enacted: false },
|
||||
{ id: "x-sub", enacted: true },
|
||||
],
|
||||
});
|
||||
});
|
||||
|
||||
test("reserved control emits control", async () => {
|
||||
const onRespond = vi.fn();
|
||||
render(<SchemaLinkingGateWidget descriptor={descriptor} onRespond={onRespond} />);
|
||||
await userEvent.click(screen.getByRole("button", { name: /go back/i }));
|
||||
expect(onRespond).toHaveBeenCalledWith({ id: "u7", control: "back" });
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `cd frontend && npx vitest run src/widgets/SchemaLinkingGateWidget.test.tsx`
|
||||
Expected: FAIL — cannot resolve `./SchemaLinkingGateWidget`.
|
||||
|
||||
- [ ] **Step 3: Implement the widget**
|
||||
|
||||
Create `frontend/src/widgets/SchemaLinkingGateWidget.tsx`:
|
||||
|
||||
```tsx
|
||||
import { useState } from "react";
|
||||
import type { WidgetProps } from "./types";
|
||||
import type { SchemaTable } from "../api/types";
|
||||
import { SchemaColumnsDialog } from "./SchemaColumnsDialog";
|
||||
import { ReservedControls } from "./ReservedControls";
|
||||
|
||||
export function SchemaLinkingGateWidget({ descriptor, onRespond }: WidgetProps) {
|
||||
const tables: SchemaTable[] = descriptor.tables ?? [];
|
||||
const [enacted, setEnacted] = useState<Set<string>>(
|
||||
() => new Set(tables.filter((t) => t.recommended).map((t) => t.id))
|
||||
);
|
||||
const [selected, setSelected] = useState<Map<string, Set<string>>>(() => {
|
||||
const m = new Map<string, Set<string>>();
|
||||
for (const t of tables) {
|
||||
m.set(
|
||||
t.id,
|
||||
new Set(t.kind === "promote" ? t.columns.filter((c) => c.suggested).map((c) => c.name) : [])
|
||||
);
|
||||
}
|
||||
return m;
|
||||
});
|
||||
const [openId, setOpenId] = useState<string | null>(null);
|
||||
|
||||
function toggleEnact(id: string) {
|
||||
setEnacted((prev) => {
|
||||
const next = new Set(prev);
|
||||
if (next.has(id)) next.delete(id);
|
||||
else next.add(id);
|
||||
return next;
|
||||
});
|
||||
}
|
||||
|
||||
function toggleColumn(tableId: string, column: string) {
|
||||
setSelected((prev) => {
|
||||
const next = new Map(prev);
|
||||
const set = new Set(next.get(tableId) ?? []);
|
||||
if (set.has(column)) set.delete(column);
|
||||
else set.add(column);
|
||||
next.set(tableId, set);
|
||||
return next;
|
||||
});
|
||||
}
|
||||
|
||||
function confirm() {
|
||||
const payload = tables.map((t) => {
|
||||
const on = enacted.has(t.id);
|
||||
if (on && t.kind === "promote") {
|
||||
const sel = selected.get(t.id) ?? new Set<string>();
|
||||
return { id: t.id, enacted: true, columns: t.columns.filter((c) => sel.has(c.name)).map((c) => c.name) };
|
||||
}
|
||||
return { id: t.id, enacted: on };
|
||||
});
|
||||
onRespond({ id: descriptor.id, kind: "schema-linking", tables: payload });
|
||||
}
|
||||
|
||||
const openTable = tables.find((t) => t.id === openId) ?? null;
|
||||
|
||||
return (
|
||||
<div className="space-y-4 rounded-xl border border-border/70 bg-card p-4 shadow-sm">
|
||||
{descriptor.title && (
|
||||
<p className="text-[0.95rem] font-semibold leading-snug text-foreground">{descriptor.title}</p>
|
||||
)}
|
||||
|
||||
<div className="flex flex-col gap-2">
|
||||
{tables.map((t) => {
|
||||
const on = enacted.has(t.id);
|
||||
const count = selected.get(t.id)?.size ?? 0;
|
||||
return (
|
||||
<div
|
||||
key={t.id}
|
||||
className={`rounded-lg border px-3 py-2.5 transition-colors ${on ? "border-border/70 bg-accent/40" : "border-transparent bg-muted/30"}`}
|
||||
>
|
||||
<div className="flex items-start gap-3">
|
||||
<input
|
||||
type="checkbox"
|
||||
className="mt-1 size-4 shrink-0 accent-[oklch(var(--primary))]"
|
||||
checked={on}
|
||||
onChange={() => toggleEnact(t.id)}
|
||||
aria-label={t.name}
|
||||
/>
|
||||
<div className="min-w-0 flex-1">
|
||||
<div className="flex items-center gap-2">
|
||||
<span className="font-mono text-sm font-semibold text-foreground">{t.name}</span>
|
||||
<span className="thot-label">{t.kind === "promote" ? "Promuovi" : "Escludi"}</span>
|
||||
</div>
|
||||
{t.description && <p className="mt-0.5 text-sm text-muted-foreground">{t.description}</p>}
|
||||
{t.rationale && <p className="mt-0.5 text-sm text-foreground/80">{t.rationale}</p>}
|
||||
</div>
|
||||
<button
|
||||
className="shrink-0 self-center rounded-md border border-border/60 px-2.5 py-1 text-xs text-muted-foreground shadow-xs transition-colors hover:bg-muted hover:text-foreground"
|
||||
onClick={() => setOpenId(t.id)}
|
||||
>
|
||||
{t.kind === "promote" ? `Colonne ${count}/${t.columns.length}` : `Colonne ${t.columns.length}`}
|
||||
</button>
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
})}
|
||||
</div>
|
||||
|
||||
{openTable && (
|
||||
<SchemaColumnsDialog
|
||||
table={openTable}
|
||||
open
|
||||
readOnly={openTable.kind === "exclude"}
|
||||
selected={selected.get(openTable.id) ?? new Set()}
|
||||
onToggle={(c) => toggleColumn(openTable.id, c)}
|
||||
onClose={() => setOpenId(null)}
|
||||
/>
|
||||
)}
|
||||
|
||||
<div>
|
||||
<button
|
||||
className="rounded-md bg-primary px-4 py-2 text-sm font-semibold text-primary-foreground shadow-xs transition-colors hover:bg-[oklch(var(--primary-hover))]"
|
||||
onClick={confirm}
|
||||
>
|
||||
Confirm
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<ReservedControls
|
||||
reserved={descriptor.reserved}
|
||||
onControl={(c, t) => onRespond({ id: descriptor.id, control: c, ...(t !== undefined ? { text: t } : {}) })}
|
||||
/>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run tests to verify they pass**
|
||||
|
||||
Run: `cd frontend && npx vitest run src/widgets/SchemaLinkingGateWidget.test.tsx`
|
||||
Expected: PASS (4 tests).
|
||||
|
||||
Note: the modal's X button (rendered by `DialogContent`, accessible name "Close") fires `onOpenChange(false)` → `onClose`; the widget's Confirm is only reachable once the modal is closed.
|
||||
|
||||
- [ ] **Step 5: Typecheck + commit**
|
||||
|
||||
Run: `cd frontend && npx tsc -b`
|
||||
Expected: no errors.
|
||||
|
||||
```bash
|
||||
git add frontend/src/widgets/SchemaLinkingGateWidget.tsx frontend/src/widgets/SchemaLinkingGateWidget.test.tsx
|
||||
git commit -m "feat(frontend): schema-linking gate widget with staged column curation"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 3: Register widget + response summary
|
||||
|
||||
**Files:**
|
||||
- Modify: `frontend/src/widgets/index.ts`
|
||||
- Modify: `frontend/src/shell/WidgetHost.tsx`
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: `SchemaLinkingGateWidget` (Task 2), the `UiResponse.tables` field (Task 1).
|
||||
- Produces: registry mapping `"schema-linking" → SchemaLinkingGateWidget`; a `lastUserEntry` summary for the new kind.
|
||||
|
||||
- [ ] **Step 1: Register the widget**
|
||||
|
||||
In `frontend/src/widgets/index.ts`, add the import and registration (alongside the others):
|
||||
|
||||
```ts
|
||||
import { SchemaLinkingGateWidget } from "./SchemaLinkingGateWidget";
|
||||
register("schema-linking", SchemaLinkingGateWidget);
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Write the failing test for the registry**
|
||||
|
||||
Append to `frontend/src/widgets/registry.test.tsx` a case (adapt to that file's existing imports — it already imports `resolve` and the widgets via `./index`):
|
||||
|
||||
```tsx
|
||||
test("resolves the schema-linking widget", async () => {
|
||||
await import("./index");
|
||||
const Comp = resolve("schema-linking");
|
||||
expect(Comp.name).toBe("SchemaLinkingGateWidget");
|
||||
});
|
||||
```
|
||||
|
||||
Run: `cd frontend && npx vitest run src/widgets/registry.test.tsx`
|
||||
Expected: PASS (if `registry.test.tsx` imports `./index` already; if it imports widgets individually, mirror that pattern instead). If the file does not exist or the pattern differs, skip this micro-test and rely on the Task 4 replay check.
|
||||
|
||||
- [ ] **Step 3: Summarize the response in WidgetHost**
|
||||
|
||||
In `frontend/src/shell/WidgetHost.tsx`, replace the `setLastUserEntry({ ... })` call with:
|
||||
|
||||
```tsx
|
||||
setLastUserEntry({
|
||||
kind: "choice",
|
||||
text:
|
||||
r.kind === "schema-linking"
|
||||
? `${r.tables?.filter((t) => t.enacted).length ?? 0} tables curated`
|
||||
: r.text ?? r.choices?.join(", ") ?? r.decision?.type ?? r.control ?? "(choice)",
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Full suite + typecheck**
|
||||
|
||||
Run: `cd frontend && npx vitest run && npx tsc -b`
|
||||
Expected: whole suite green, no type errors.
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add frontend/src/widgets/index.ts frontend/src/shell/WidgetHost.tsx frontend/src/widgets/registry.test.tsx
|
||||
git commit -m "feat(frontend): register schema-linking widget + response summary"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 4: Replay fixture + visual verification
|
||||
|
||||
**Files:**
|
||||
- Create: `tools/replay/schema-linking-fixture.json` (generated, committed)
|
||||
- Create: `tools/replay/augment-schema-linking.mjs`
|
||||
- Modify: `tools/replay/replay.json` (regenerated by the script)
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: the real catalog `physical.yaml` and the session `schema_linking.json` (workspace, local only) to produce the fixture; the `schema-linking` descriptor shape (Task 1).
|
||||
- Produces: replay gate 7 rewritten so the widget renders in the browser.
|
||||
|
||||
- [ ] **Step 1: Generate the fixture from the real catalog**
|
||||
|
||||
Run (uses the harness venv for a YAML parser; paths are the psd workspace):
|
||||
|
||||
```bash
|
||||
cd /Users/mp/projects/ThothII && harness/.venv/bin/python - <<'PY'
|
||||
import yaml, json
|
||||
CAT = "/Users/mp/projects/tht-workspace-psd/artifacts/mschema/physical.yaml"
|
||||
SL = "/Users/mp/projects/tht-workspace-psd/sessions/2026-07-03-170732-fammi-la-lista-dei-pazienti-che-negli-ul/schema_linking.json"
|
||||
tables_meta = yaml.safe_load(open(CAT))["tables"]
|
||||
sl = json.load(open(SL))
|
||||
suggested = {}
|
||||
for c in sl["candidates"]:
|
||||
if c["kind"] == "column" and c.get("decision") == "promoted":
|
||||
tbl, _, col = c["name"].partition(".")
|
||||
suggested.setdefault(tbl, set()).add(col)
|
||||
replay = json.load(open("tools/replay/replay.json"))
|
||||
opts = replay["gates"][7]["descriptor"]["options"]
|
||||
info = {o["decision"]["subject"]: o["decision"] for o in opts
|
||||
if o["decision"]["type"] in ("table_promoted", "table_excluded")}
|
||||
def build(tbl, kind, oid):
|
||||
meta = tables_meta.get(tbl, {"comment": "", "columns": {}})
|
||||
sug = suggested.get(tbl, set())
|
||||
d = info.get(tbl, {})
|
||||
return {
|
||||
"id": oid, "name": tbl, "kind": kind, "recommended": True,
|
||||
"description": meta.get("comment") or d.get("detail", ""),
|
||||
"rationale": d.get("rationale", ""),
|
||||
"columns": [
|
||||
{"name": cn, "description": (cm.get("comment") or ""),
|
||||
"type": cm.get("type"), "pk": bool(cm.get("pk")),
|
||||
"suggested": cn in sug}
|
||||
for cn, cm in meta.get("columns", {}).items()
|
||||
],
|
||||
}
|
||||
tables = [
|
||||
build("fact_studio_elettrofisiologico_endocavitario_ablazione", "promote", "t-ablazione"),
|
||||
build("fact_impianto_defibrillatore_impiantabile", "promote", "t-impianto"),
|
||||
build("dim_patient", "promote", "t-patient"),
|
||||
build("dim_time", "promote", "t-time"),
|
||||
build("fact_sostituzione_impianto_defibrillatore_impiantabile", "exclude", "x-sostituzione"),
|
||||
build("fact_controllo_defibrillatore_impiantabile", "exclude", "x-controllo"),
|
||||
]
|
||||
json.dump(tables, open("tools/replay/schema-linking-fixture.json", "w"), ensure_ascii=False, indent=2)
|
||||
print("wrote", len(tables), "tables;",
|
||||
sum(len(t["columns"]) for t in tables), "columns;",
|
||||
sum(1 for t in tables for c in t["columns"] if c["suggested"]), "suggested")
|
||||
PY
|
||||
```
|
||||
|
||||
Expected: prints e.g. `wrote 6 tables; 21 columns; 15 suggested`.
|
||||
|
||||
- [ ] **Step 2: Write the augment script**
|
||||
|
||||
Create `tools/replay/augment-schema-linking.mjs`:
|
||||
|
||||
```js
|
||||
// Rewrite replay gate F4 "tabelle/colonne/esclusioni" as a `schema-linking`
|
||||
// descriptor carrying the real catalog columns (schema-linking-fixture.json),
|
||||
// so the SchemaLinkingGateWidget renders in replay. Run after editing the
|
||||
// fixture: node tools/replay/augment-schema-linking.mjs
|
||||
import { readFileSync, writeFileSync } from "node:fs";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import { dirname, join } from "node:path";
|
||||
|
||||
const HERE = dirname(fileURLToPath(import.meta.url));
|
||||
const replayPath = join(HERE, "replay.json");
|
||||
const replay = JSON.parse(readFileSync(replayPath, "utf8"));
|
||||
const tables = JSON.parse(readFileSync(join(HERE, "schema-linking-fixture.json"), "utf8"));
|
||||
|
||||
const idx = replay.gates.findIndex(
|
||||
(g) =>
|
||||
/tabelle\/colonne\/esclusioni/.test(g.descriptor?.title ?? "") &&
|
||||
(g.descriptor?.widget === "multiselect" || g.descriptor?.widget === "schema-linking")
|
||||
);
|
||||
if (idx < 0) {
|
||||
console.error("F4 tables gate not found in replay.json");
|
||||
process.exit(1);
|
||||
}
|
||||
const d = replay.gates[idx].descriptor;
|
||||
replay.gates[idx].descriptor = {
|
||||
type: "ui_request",
|
||||
id: d.id,
|
||||
phase: d.phase,
|
||||
schema_version: d.schema_version,
|
||||
widget: "schema-linking",
|
||||
title: d.title,
|
||||
tables,
|
||||
reserved: ["back", "exit", "other"],
|
||||
};
|
||||
writeFileSync(replayPath, JSON.stringify(replay, null, 2) + "\n");
|
||||
console.log(`Rewrote gate ${idx} -> schema-linking (${tables.length} tables)`);
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Run the augment script and assert**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
cd /Users/mp/projects/ThothII && node tools/replay/augment-schema-linking.mjs && \
|
||||
node -e 'const j=require("./tools/replay/replay.json");const g=j.gates.find(x=>/tabelle\/colonne/.test(x.descriptor?.title||""));if(g.descriptor.widget!=="schema-linking"||!Array.isArray(g.descriptor.tables))throw new Error("not rewritten");console.log("OK",g.descriptor.tables.length,"tables")'
|
||||
```
|
||||
|
||||
Expected: `Rewrote gate 7 -> schema-linking (6 tables)` then `OK 6 tables`.
|
||||
|
||||
- [ ] **Step 4: Rebuild the replay bundle and start the server**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
cd /Users/mp/projects/ThothII && rm -rf tools/replay/web && bash scripts/replay.sh build && \
|
||||
( lsof -ti tcp:5333 | xargs kill -9 2>/dev/null; true ) && nohup node tools/replay/server.mjs >/tmp/replay-5333.log 2>&1 &
|
||||
sleep 2 && curl -s -o /dev/null -w "%{http_code}\n" http://localhost:5333/
|
||||
```
|
||||
|
||||
Expected: `200`.
|
||||
|
||||
- [ ] **Step 5: Visually verify in the browser**
|
||||
|
||||
Open http://localhost:5333 → click the "Replay 170732" session → **Resume** → answer the 3 F1 clarifications (recommended option each) → the F4 gate now renders as table rows with description + rationale and "Colonne k/n" buttons. Open a promote table's modal: suggested columns are pre-checked and bold; toggling a column updates bold and the row count. Open an exclude table's modal: fields listed, no checkboxes. Confirm advances the replay.
|
||||
|
||||
Confirm each requirement:
|
||||
- [ ] Promote rows show description + rationale under the name.
|
||||
- [ ] Columns modal: suggested pre-selected + bold; toggle updates bold; no column rows in the list itself.
|
||||
- [ ] Exclude modal: read-only (no checkboxes).
|
||||
|
||||
- [ ] **Step 6: Commit**
|
||||
|
||||
```bash
|
||||
git add tools/replay/schema-linking-fixture.json tools/replay/augment-schema-linking.mjs tools/replay/replay.json
|
||||
git commit -m "feat(replay): render F4 as schema-linking gate from real catalog columns"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Self-Review
|
||||
|
||||
**Spec coverage (Phase 1 slice of `2026-07-06-f4-schema-linking-column-curation-design.md`):**
|
||||
- §1a descriptor `tables[]` → Task 1 types + Task 4 fixture. ✅
|
||||
- §1b structured response → Task 2 `confirm()` + tests. ✅
|
||||
- §2 interaction (inline gate, rows with desc+rationale, columns modal, bold rule, staged, exclude read-only, no column rows) → Task 2 + Task 1 + Task 4 verify. ✅
|
||||
- §3 components (`SchemaLinkingGateWidget`, `SchemaColumnsDialog`, registry, WidgetHost) → Tasks 1-3. ✅
|
||||
- §6 replay fixture from `physical.yaml` → Task 4. ✅
|
||||
- §4/§5 harness + downstream → **Plan 2 (out of scope here)**, by design.
|
||||
|
||||
**Placeholder scan:** none — every step has concrete code/commands. The Task 3 registry micro-test has a documented fallback if `registry.test.tsx` differs.
|
||||
|
||||
**Type consistency:** `SchemaTable`/`SchemaColumn`/`UiResponse.tables` defined in Task 1 and used verbatim in Tasks 2-4. Response shape `{ id, enacted, columns? }` identical across widget, tests, and contract. `descriptor.tables` typed in Task 1, read in Task 2.
|
||||
|
||||
**Note for implementer:** Task 3 Step 2 depends on the exact contents of `frontend/src/widgets/registry.test.tsx`; read it first and mirror its import style, or rely on the Task 4 replay render as the integration check.
|
||||
Reference in New Issue
Block a user