docs: add P1.1 workspace directory plan

2026-08-11 14:22:28 +02:00
parent 66f44b054f
commit 7356d6794b
4 changed files with 1662 additions and 0 deletions
@@ -0,0 +1,82 @@
+import { expect, test } from "vitest";
+import { parseWorkspaceYaml } from "../src/workspaces/schema.js";
+import {
+  CATALOG_PATH,
+  assertCatalogMatchesDescriptor,
+  parseWorkspaceCatalogYaml,
+} from "../src/workspaces/catalog.js";
+
+const descriptor = parseWorkspaceYaml(`workspace:
+  schema_version: 3
+  id: psd
+  name: Policlinico San Donato
+  description: Clinical warehouse
+  language: it
+dwh:
+  engine: postgres
+  database: postgres
+  schema: datawarehouse
+  supported_transports: [rest_api]
+semantic_index:
+  vector_store: { engine: qdrant, collection: psd, dimensions: 1024, distance: cosine }
+  embedding: { provider: ollama_internal, model: qwen3-embedding:0.6b, dimensions: 1024 }
+llm_policy: { allowed: [zai/glm-5.2] }
+`);
+
+test("parses the strict ordered root catalog", () => {
+  expect(CATALOG_PATH).toBe("thoth-workspaces.yaml");
+  expect(parseWorkspaceCatalogYaml(`schema_version: 1
+workspaces:
+  - id: psd
+    name: Policlinico San Donato
+    description: Clinical warehouse
+  - id: research
+    name: Research
+`)).toEqual({
+    schema_version: 1,
+    workspaces: [
+      { id: "psd", name: "Policlinico San Donato", description: "Clinical warehouse" },
+      { id: "research", name: "Research" },
+    ],
+  });
+});
+
+test("preserves optional description absence and trims metadata", () => {
+  expect(parseWorkspaceCatalogYaml(`schema_version: 1
+workspaces:
+  - id: psd
+    name: "  PSD  "
+`)).toEqual({ schema_version: 1, workspaces: [{ id: "psd", name: "PSD" }] });
+});
+
+test.each([
+  ["duplicate IDs", `schema_version: 1\nworkspaces: [{id: psd, name: One}, {id: psd, name: Two}]`],
+  ["invalid ID", `schema_version: 1\nworkspaces: [{id: PSD, name: One}]`],
+  ["reserved ID", `schema_version: 1\nworkspaces: [{id: workspace-docs, name: One}]`],
+  ["unknown key", `schema_version: 1\nworkspaces: [{id: psd, name: One, secret: CANARY}]`],
+  ["duplicate YAML key", `schema_version: 1\nworkspaces:\n  - id: psd\n    id: research\n    name: One`],
+  ["multiple documents", `schema_version: 1\nworkspaces: []\n---\nschema_version: 1\nworkspaces: []`],
+])("rejects %s without exposing unsafe input", (_name, source) => {
+  expect(() => parseWorkspaceCatalogYaml(source)).toThrow(/catalog|workspace|id|YAML/i);
+  try { parseWorkspaceCatalogYaml(source); } catch (error) {
+    expect(String(error)).not.toContain("CANARY");
+  }
+});
+
+test("rejects catalog metadata that differs from its descriptor", () => {
+  expect(() => assertCatalogMatchesDescriptor(
+    { id: "psd", name: "Other", description: "Clinical warehouse" }, descriptor,
+  )).toThrow(/catalog|metadata/i);
+  expect(() => assertCatalogMatchesDescriptor(
+    { id: "psd", name: "Policlinico San Donato" }, descriptor,
+  )).toThrow(/catalog|metadata/i);
+  expect(() => assertCatalogMatchesDescriptor(
+    { id: "other", name: "Policlinico San Donato", description: "Clinical warehouse" }, descriptor,
+  )).toThrow(/catalog|metadata/i);
+});
+
+test("accepts exact catalog metadata", () => {
+  expect(() => assertCatalogMatchesDescriptor(
+    { id: "psd", name: "Policlinico San Donato", description: "Clinical warehouse" }, descriptor,
+  )).not.toThrow();
+});