@featurevisor/catalog 3.0.1 → 3.1.0

package/src/components/tests.spec.ts

@@ -0,0 +1,134 @@
+import type { TestFeature, TestSegment } from "@featurevisor/types";
+
+import { expandTestAssertions, getTestAssertionPermalink } from "../testModel";
+
+describe("catalog test presentation", () => {
+  it("keeps authored assertions without matrices as one numbered assertion", () => {
+    const test: TestFeature = {
+      key: "checkout-primary",
+      feature: "checkout",
+      assertions: [
+        {
+          environment: "staging",
+          context: { country: "nl" },
+          expectedToBeEnabled: true,
+        },
+      ],
+    };
+
+    expect(expandTestAssertions(test)).toEqual([
+      expect.objectContaining({
+        assertionIndex: 0,
+        label: "1",
+        assertion: test.assertions[0],
+      }),
+    ]);
+  });
+
+  it("expands feature matrices in deterministic order with dotted case numbers", () => {
+    const test: TestFeature = {
+      key: "checkout-matrix",
+      feature: "checkout",
+      assertions: [
+        {
+          environment: "staging",
+          context: {},
+          expectedToBeEnabled: true,
+        },
+        {
+          matrix: {
+            environment: ["staging", "production"],
+            at: [10, 90],
+            country: ["nl"],
+          },
+          description: "${{ country }} in ${{ environment }} at ${{ at }}%",
+          environment: "${{ environment }}",
+          target: "${{ environment }}-web",
+          at: "${{ at }}" as never,
+          context: {
+            country: "${{ country }}",
+            label: "${{ country }}-${{ environment }}",
+          },
+          expectedToBeEnabled: true,
+        },
+      ],
+    };
+
+    const expanded = expandTestAssertions(test);
+
+    expect(expanded.map((item) => item.label)).toEqual(["1", "2.1", "2.2", "2.3", "2.4"]);
+    expect(expanded[1]).toMatchObject({
+      assertionIndex: 1,
+      caseIndex: 0,
+      caseCount: 4,
+      matrixValues: { environment: "staging", at: 10, country: "nl" },
+      assertion: {
+        description: "nl in staging at 10%",
+        environment: "staging",
+        target: "staging-web",
+        at: 10,
+        context: { country: "nl", label: "nl-staging" },
+      },
+    });
+    expect(expanded[4]).toMatchObject({
+      matrixValues: { environment: "production", at: 90, country: "nl" },
+      assertion: { environment: "production", at: 90 },
+    });
+    expect("matrix" in expanded[1].assertion).toBe(false);
+  });
+
+  it("expands segment contexts and descriptions without changing expectations", () => {
+    const test: TestSegment = {
+      key: "countries-germany",
+      segment: "countries.germany",
+      assertions: [
+        {
+          matrix: { country: ["de"], city: ["berlin", "hamburg"] },
+          description: "${{ city }}, ${{ country }}",
+          context: { country: "${{ country }}", city: "${{ city }}" },
+          expectedToMatch: false,
+        },
+      ],
+    };
+
+    expect(expandTestAssertions(test)).toEqual([
+      expect.objectContaining({
+        label: "1.1",
+        assertion: expect.objectContaining({
+          description: "berlin, de",
+          context: { country: "de", city: "berlin" },
+          expectedToMatch: false,
+        }),
+      }),
+      expect.objectContaining({
+        label: "1.2",
+        assertion: expect.objectContaining({
+          description: "hamburg, de",
+          context: { country: "de", city: "hamburg" },
+          expectedToMatch: false,
+        }),
+      }),
+    ]);
+  });
+
+  it("uses the test key and dotted case number for stable permalink identities", () => {
+    expect(getTestAssertionPermalink("features/checkout/redesign.spec", "2.3")).toBe(
+      "features/checkout/redesign.spec:2.3",
+    );
+  });
+
+  it("matches the tester by producing no cases for an empty matrix", () => {
+    const test: TestSegment = {
+      segment: "everyone",
+      assertions: [
+        {
+          matrix: {},
+          context: {},
+          expectedToMatch: true,
+        },
+      ],
+    };
+
+    expect(expandTestAssertions(test)).toEqual([]);
+  });
+});

package/src/components/tests.tsx

@@ -0,0 +1,301 @@
+import * as React from "react";
+import { Link, useLocation, useSearchParams } from "react-router-dom";
+import type {
+  FeatureAssertion,
+  SegmentAssertion,
+  Test,
+  TestFeature,
+  TestSegment,
+} from "@featurevisor/types";
+
+import { Badge, EmptyState, EntityKey, LabelValueBadge, MarkdownContent } from "./ui";
+import { expandTestAssertions, getTestAssertionPermalink } from "../testModel";
+
+function getAssertionElementId(permalink: string) {
+  return `assertion-${encodeURIComponent(permalink)}`;
+}
+
+function hasValue(value: unknown) {
+  return value !== undefined && value !== null;
+}
+
+function ValueDisplay(props: { value: unknown }) {
+  if (props.value === undefined || props.value === null) {
+    return <span className="text-faint">not set</span>;
+  }
+
+  if (typeof props.value === "boolean") {
+    return (
+      <Badge tone={props.value ? "success" : "neutral"}>{props.value ? "true" : "false"}</Badge>
+    );
+  }
+
+  if (Array.isArray(props.value)) {
+    if (props.value.length === 0) {
+      return <span className="text-faint">empty</span>;
+    }
+
+    return (
+      <div className="flex flex-wrap gap-1.5">
+        {props.value.map((value, index) => (
+          <span key={index} className="rounded-md border border-border bg-surface px-2 py-1">
+            <ValueDisplay value={value} />
+          </span>
+        ))}
+      </div>
+    );
+  }
+
+  if (typeof props.value === "object") {
+    const entries = Object.entries(props.value as Record<string, unknown>);
+    if (entries.length === 0) {
+      return <span className="text-faint">empty</span>;
+    }
+
+    return (
+      <dl className="divide-y divide-border overflow-hidden rounded-lg border border-border bg-surface">
+        {entries.map(([key, value]) => (
+          <div key={key} className="grid gap-1 px-3 py-2 sm:grid-cols-[minmax(7rem,0.35fr)_1fr]">
+            <dt className="font-mono text-xs font-semibold text-muted [overflow-wrap:anywhere]">
+              {key}
+            </dt>
+            <dd className="min-w-0 text-sm [overflow-wrap:anywhere]">
+              <ValueDisplay value={value} />
+            </dd>
+          </div>
+        ))}
+      </dl>
+    );
+  }
+
+  return <span className="font-mono text-xs [overflow-wrap:anywhere]">{String(props.value)}</span>;
+}
+
+function TestDataPanel(props: { title: string; value: unknown; className?: string }) {
+  if (!hasValue(props.value)) {
+    return null;
+  }
+
+  return (
+    <section
+      className={`min-w-0 rounded-xl border border-border bg-elevated p-4 ${props.className || ""}`}
+    >
+      <h4 className="mb-3 text-[10px] font-semibold uppercase tracking-wider text-faint">
+        {props.title}
+      </h4>
+      <ValueDisplay value={props.value} />
+    </section>
+  );
+}
+
+function AssertionPermalink(props: { permalink: string; label: string }) {
+  const location = useLocation();
+  const search = new URLSearchParams(location.search);
+  search.set("assertion", props.permalink);
+
+  return (
+    <Link
+      to={{ pathname: location.pathname, search: `?${search.toString()}` }}
+      aria-label={`Link to assertion ${props.label}`}
+      title="Link to this assertion"
+      className="inline-flex rounded p-1 text-muted opacity-100 transition-opacity hover:text-primary focus-visible:opacity-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary md:opacity-0 md:group-hover:opacity-100"
+    >
+      <svg
+        aria-hidden="true"
+        viewBox="0 0 24 24"
+        className="h-4 w-4"
+        fill="none"
+        stroke="currentColor"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth="2"
+      >
+        <path d="M10 13a5 5 0 0 0 7.07 0l2.83-2.83a5 5 0 0 0-7.07-7.07L11 4" />
+        <path d="M14 11a5 5 0 0 0-7.07 0L4.1 13.83a5 5 0 1 0 7.07 7.07L13 20" />
+      </svg>
+    </Link>
+  );
+}
+
+function FeatureAssertionContent(props: { assertion: FeatureAssertion }) {
+  const assertion = props.assertion;
+  const defaults = {
+    ...(hasValue(assertion.defaultVariationValue)
+      ? { variation: assertion.defaultVariationValue }
+      : {}),
+    ...(assertion.defaultVariableValues ? { variables: assertion.defaultVariableValues } : {}),
+  };
+  const expectations = {
+    ...(hasValue(assertion.expectedToBeEnabled) ? { enabled: assertion.expectedToBeEnabled } : {}),
+    ...(hasValue(assertion.expectedVariation) ? { variation: assertion.expectedVariation } : {}),
+    ...(assertion.expectedVariables ? { variables: assertion.expectedVariables } : {}),
+    ...(assertion.expectedEvaluations ? { evaluations: assertion.expectedEvaluations } : {}),
+  };
+
+  return (
+    <>
+      <div className="flex flex-wrap gap-2">
+        <LabelValueBadge label="Environment" value={assertion.environment || "none"} compact />
+        {assertion.target && <LabelValueBadge label="Target" value={assertion.target} compact />}
+        {hasValue(assertion.at) && (
+          <LabelValueBadge label="Bucket" value={`${assertion.at}%`} compact />
+        )}
+      </div>
+
+      <div className="space-y-4">
+        <TestDataPanel title="Context" value={assertion.context || {}} />
+        <TestDataPanel title="Expected" value={expectations} />
+        {Object.keys(defaults).length > 0 && <TestDataPanel title="Defaults" value={defaults} />}
+        {assertion.sticky && <TestDataPanel title="Sticky features" value={assertion.sticky} />}
+      </div>
+
+      {assertion.children?.length ? (
+        <section className="space-y-3 rounded-xl border border-border bg-surface p-4">
+          <h4 className="text-[10px] font-semibold uppercase tracking-wider text-faint">
+            Child instances
+          </h4>
+          <div className="space-y-3">
+            {assertion.children.map((child, index) => (
+              <div key={index} className="rounded-lg border border-border bg-elevated p-3">
+                <div className="mb-3 text-xs font-semibold text-muted">Child {index + 1}</div>
+                <ValueDisplay value={child} />
+              </div>
+            ))}
+          </div>
+        </section>
+      ) : null}
+    </>
+  );
+}
+
+function SegmentAssertionContent(props: { assertion: SegmentAssertion }) {
+  return (
+    <div className="space-y-4">
+      <TestDataPanel title="Context" value={props.assertion.context} />
+      <section className="rounded-xl border border-border bg-elevated p-4">
+        <h4 className="mb-3 text-[10px] font-semibold uppercase tracking-wider text-faint">
+          Expected
+        </h4>
+        <Badge tone={props.assertion.expectedToMatch ? "success" : "neutral"}>
+          {props.assertion.expectedToMatch ? "Matches segment" : "Does not match segment"}
+        </Badge>
+      </section>
+    </div>
+  );
+}
+
+function TestSpec(props: { test: Test; index: number; selectedPermalink?: string }) {
+  const testKey = props.test.key || `test-${props.index + 1}`;
+  const assertions = expandTestAssertions(props.test);
+  const authoredCount = props.test.assertions.length;
+  const hasMatrix = props.test.assertions.some((assertion) => Boolean(assertion.matrix));
+
+  return (
+    <section className="space-y-5">
+      <header className="flex flex-col justify-between gap-3 border-b border-border pb-3 sm:flex-row sm:items-end">
+        <div className="min-w-0">
+          <div className="text-[10px] font-semibold uppercase tracking-wider text-faint">
+            Test spec {props.index + 1}
+          </div>
+          <h2 className="mt-1 font-mono text-sm font-semibold [overflow-wrap:anywhere]">
+            <EntityKey value={testKey} />
+          </h2>
+        </div>
+        <div className="flex flex-wrap gap-2">
+          {props.test.promotable === false && <Badge>not promotable</Badge>}
+          <Badge>{authoredCount} authored</Badge>
+          {hasMatrix && <Badge tone="primary">{assertions.length} applied</Badge>}
+        </div>
+      </header>
+
+      {assertions.length === 0 ? (
+        <EmptyState title="No assertions found in this test spec" />
+      ) : (
+        <div className="space-y-5">
+          {assertions.map((expanded) => {
+            const permalink = getTestAssertionPermalink(testKey, expanded.label);
+            const selected = props.selectedPermalink === permalink;
+            const assertion = expanded.assertion;
+
+            return (
+              <article
+                id={getAssertionElementId(permalink)}
+                key={permalink}
+                className={[
+                  "scroll-mt-6 space-y-4 rounded-2xl border bg-surface p-5 transition-shadow",
+                  selected ? "border-primary ring-2 ring-primary/20" : "border-border",
+                ].join(" ")}
+              >
+                <header className="space-y-2">
+                  <div className="group flex min-w-0 items-start justify-between gap-3">
+                    <div className="flex min-w-0 flex-wrap items-center gap-2">
+                      <h3 className="font-semibold">Assertion {expanded.label}</h3>
+                      {hasValue(expanded.caseIndex) && (
+                        <Badge tone="primary">
+                          Matrix case {(expanded.caseIndex as number) + 1} of {expanded.caseCount}
+                        </Badge>
+                      )}
+                    </div>
+                    <div className="shrink-0">
+                      <AssertionPermalink permalink={permalink} label={expanded.label} />
+                    </div>
+                  </div>
+                  {assertion.description && <MarkdownContent value={assertion.description} />}
+                </header>
+
+                {expanded.matrixValues && (
+                  <div className="flex flex-wrap items-center gap-2">
+                    <span className="text-[10px] font-semibold uppercase tracking-wider text-faint">
+                      Matrix values
+                    </span>
+                    {Object.entries(expanded.matrixValues).map(([key, value]) => (
+                      <LabelValueBadge key={key} label={key} value={String(value)} compact />
+                    ))}
+                  </div>
+                )}
+
+                {"feature" in props.test ? (
+                  <FeatureAssertionContent assertion={assertion as FeatureAssertion} />
+                ) : (
+                  <SegmentAssertionContent assertion={assertion as SegmentAssertion} />
+                )}
+              </article>
+            );
+          })}
+        </div>
+      )}
+    </section>
+  );
+}
+
+export function EntityTests(props: { tests: Test[] }) {
+  const [searchParams] = useSearchParams();
+  const selectedPermalink = searchParams.get("assertion") || undefined;
+
+  React.useEffect(() => {
+    if (!selectedPermalink) {
+      return;
+    }
+
+    const frame = window.requestAnimationFrame(() => {
+      document
+        .getElementById(getAssertionElementId(selectedPermalink))
+        ?.scrollIntoView({ block: "start" });
+    });
+
+    return () => window.cancelAnimationFrame(frame);
+  }, [selectedPermalink, props.tests]);
+
+  return (
+    <div className="space-y-10">
+      {props.tests.map((test, index) => (
+        <TestSpec
+          key={test.key || index}
+          test={test as TestFeature | TestSegment}
+          index={index}
+          selectedPermalink={selectedPermalink}
+        />
+      ))}
+    </div>
+  );
+}

package/src/components/ui.tsx

@@ -123,18 +123,14 @@ export function LabelValueBadge(props: {
       {props.value}
     </Link>
   ) : (
-    <span className={props.compact ? undefined : "font-medium text-text"}>{props.value}</span>
+    <span className="font-medium text-text">{props.value}</span>
   );
 
   if (props.compact) {
     return (
-      <span className="inline-flex h-6 shrink-0 overflow-hidden rounded-full border border-border text-[11px] leading-none text-faint transition-colors group-hover:text-muted">
-        <span className="flex items-center bg-slate-100 pl-1.5 pr-1.5 font-medium transition-colors group-hover:bg-slate-200">
-          {props.label}
-        </span>
-        <span className="flex items-center bg-surface pl-1.5 pr-1.5 transition-colors group-hover:bg-slate-100">
-          {valueContent}
-        </span>
+      <span className="inline-flex h-5 shrink-0 overflow-hidden rounded-md border border-border/70 text-[10px] leading-none">
+        <span className="flex items-center bg-elevated px-1.5 text-muted">{props.label}</span>
+        <span className="flex items-center bg-surface px-1.5 text-text">{valueContent}</span>
       </span>
     );
   }
@@ -241,15 +237,19 @@ export function EmptyState(props: { title: string; description?: string }) {
 
 export function PageHeader(props: {
   title: React.ReactNode;
+  titleAction?: React.ReactNode;
   description?: React.ReactNode;
   actions?: React.ReactNode;
 }) {
   return (
     <div className="mb-6 flex flex-col justify-between gap-4 border-b border-border px-6 pb-4 pt-8 md:flex-row md:items-start">
       <div className="min-w-0 flex-1">
-        <h1 className="min-w-0 text-3xl font-black text-text [overflow-wrap:anywhere]">
-          {props.title}
-        </h1>
+        <div className="group flex min-w-0 items-center gap-2">
+          <h1 className="min-w-0 text-3xl font-black text-text [overflow-wrap:anywhere]">
+            {props.title}
+          </h1>
+          {props.titleAction ? <div className="shrink-0">{props.titleAction}</div> : null}
+        </div>
         {props.description && (
           <div className="mt-2 min-w-0 text-sm text-muted [overflow-wrap:anywhere]">
             {props.description}

package/src/entityTypes.spec.ts

@@ -0,0 +1,13 @@
+import { decodeRouteSegment, encodeDataPath, encodeRouteSegment } from "./entityTypes";
+
+describe("catalog entity path encoding", () => {
+  it("keeps slash-namespaced keys in one browser route segment", () => {
+    expect(encodeRouteSegment("checkout/redesign")).toBe("checkout%252Fredesign");
+    expect(decodeRouteSegment("checkout%2Fredesign")).toBe("checkout/redesign");
+  });
+
+  it("maps slash-namespaced keys to nested data paths", () => {
+    expect(encodeDataPath("checkout/redesign")).toBe("checkout/redesign");
+    expect(encodeDataPath("checkout/new design")).toBe("checkout/new%20design");
+  });
+});

package/src/entityTypes.ts

@@ -55,6 +55,13 @@ export function encodeDataSegment(value: string) {
   return encodeURIComponent(value);
 }
 
+export function encodeDataPath(value: string) {
+  return value
+    .split("/")
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+}
+
 export function getBasePath(setKey?: string) {
   return setKey ? `/sets/${encodeRouteSegment(setKey)}` : "";
 }

package/src/node/index.spec.ts

@@ -85,8 +85,51 @@ function createDatasource(set = "") {
     readGroup: async () => undefined,
     listSchemas: async () => [],
     readSchema: async () => undefined,
-    listTests: async () => ["checkout"],
-    readTest: async () => ({ key: "checkout", feature: featureKey, assertions: [] }),
+    listTests: async () => ["checkout-primary", "checkout-matrix", "premium-users"],
+    readTest: async (key: string) => {
+      if (key === "premium-users") {
+        return {
+          key,
+          segment: segmentKey,
+          assertions: [
+            {
+              context: { plan: "premium" },
+              expectedToMatch: true,
+            },
+          ],
+        };
+      }
+
+      if (key === "checkout-matrix") {
+        return {
+          key,
+          feature: featureKey,
+          assertions: [
+            {
+              matrix: { country: ["nl", "de"], at: [10, 90] },
+              description: "${{ country }} at ${{ at }}%",
+              environment: "production",
+              at: "${{ at }}",
+              context: { country: "${{ country }}" },
+              expectedToBeEnabled: true,
+            },
+          ],
+        };
+      }
+
+      return {
+        key,
+        feature: featureKey,
+        assertions: [
+          {
+            description: "Enabled in staging",
+            environment: "staging",
+            context: { country: "nl" },
+            expectedToBeEnabled: true,
+          },
+        ],
+      };
+    },
   };
 }
 
@@ -161,8 +204,27 @@ describe("catalog export", () => {
       segments: ["premiumUsers"],
       attributes: ["country"],
       targets: ["premiumWeb"],
-      tests: ["checkout"],
+      tests: ["checkout-matrix", "checkout-primary"],
     });
+    expect(detail.tests).toHaveLength(2);
+    expect(detail.tests.map((test: any) => test.key)).toEqual([
+      "checkout-matrix",
+      "checkout-primary",
+    ]);
+    expect(detail.tests[0].assertions[0].matrix).toEqual({
+      country: ["nl", "de"],
+      at: [10, 90],
+    });
+
+    const segmentDetail = JSON.parse(
+      fs.readFileSync(
+        path.join(root, "catalog", "data", "root", "entities", "segment", "premiumUsers.json"),
+        "utf8",
+      ),
+    );
+    expect(segmentDetail.tests).toEqual([
+      expect.objectContaining({ key: "premium-users", segment: "premiumUsers" }),
+    ]);
   });
 
   it("writes per-set catalog files for sets-enabled projects", async () => {
@@ -200,6 +262,88 @@ describe("catalog export", () => {
     ).toBe(true);
   });
 
+  it("writes slash-namespaced entity details as nested data paths", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "featurevisor-catalog-"));
+    const projectConfig = {
+      ...createProjectConfig(root),
+      namespaceCharacter: "/",
+    };
+    const baseDatasource = createDatasource();
+    const featureKey = "checkout/redesign";
+    const datasource = {
+      ...baseDatasource,
+      listHistoryEntries: async () => [
+        {
+          commit: "root123456789",
+          author: "Test",
+          timestamp: "2026-01-01T00:00:00.000Z",
+          entities: [{ type: "feature", key: featureKey }],
+        },
+      ],
+      listFeatures: async () => [featureKey],
+      readFeature: async () => ({
+        ...(await baseDatasource.readFeature()),
+        key: featureKey,
+      }),
+      listTests: async () => ["features/checkout/redesign.spec"],
+      readTest: async () => ({
+        key: "features/checkout/redesign.spec",
+        feature: featureKey,
+        assertions: [],
+      }),
+    };
+
+    await exportCatalog(createRuntime(), root, projectConfig, datasource, {
+      copyAssets: false,
+    });
+
+    const nestedDetailPath = path.join(
+      root,
+      "catalog",
+      "data",
+      "root",
+      "entities",
+      "feature",
+      "checkout",
+      "redesign.json",
+    );
+    const legacyFlatDetailPath = path.join(
+      root,
+      "catalog",
+      "data",
+      "root",
+      "entities",
+      "feature",
+      "checkout%2Fredesign.json",
+    );
+    const detail = JSON.parse(fs.readFileSync(nestedDetailPath, "utf8"));
+    const index = JSON.parse(
+      fs.readFileSync(path.join(root, "catalog", "data", "root", "index.json"), "utf8"),
+    );
+
+    expect(fs.existsSync(legacyFlatDetailPath)).toBe(false);
+    expect(
+      fs.existsSync(
+        path.join(
+          root,
+          "catalog",
+          "data",
+          "root",
+          "entities",
+          "feature",
+          "checkout",
+          "redesign",
+          "history",
+          "page-1.json",
+        ),
+      ),
+    ).toBe(true);
+    expect(index.entities.feature[0].key).toBe(featureKey);
+    expect(index.entities.feature[0].href).toBe("entities/feature/checkout/redesign.json");
+    expect(detail.sourcePath).toBe("features/checkout/redesign.yml");
+    expect(detail.historyPath).toBe("data/root/entities/feature/checkout/redesign/history");
+  });
+
   it("exports repository source links and dev editor links", async () => {
     const root = fs.mkdtempSync(path.join(os.tmpdir(), "featurevisor-catalog-"));