@crvouga/atlas 0.17.0 → 1.1.0

package/packages/visualizer/src/evidence/spec-page.tsx

@@ -1,11 +1,13 @@
-import { Alert, Button, Container, Text, Title } from '@mantine/core';
-import { useQuery } from '@tanstack/react-query';
-import { useNavigate, useParams, useSearch } from '@tanstack/react-router';
+import { Alert, Anchor, Button, Container, Group, List, Stack, Text, Title } from '@mantine/core';
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+import { Link, useNavigate, useParams, useSearch } from '@tanstack/react-router';
 import { lazy, Suspense } from 'react';
 import { keys, specKey, useAdapter } from '../data/queries';
-import { outlinePath, specFile, specKind } from '../spec-kind';
+import { outlinePath, resolveSpec, similarSpecs, specFile, specKind, type SpecKind } from '../spec-kind';
 import type { SelectCheck } from './check-detail';
 import { useEvidence } from './evidence-context';
+import { isMissing, useStalled } from './load-state';
+import { SpecHeader } from './spec-header';
 import { Overview } from './overview';
 // Each kind of spec has a page with a parser of its own (Gherkin, Quint, DMN); a page loads only the one it shows.
 const DocumentPage = lazy(() => import('./document-page').then((m) => ({ default: m.DocumentPage })));
@@ -27,6 +29,63 @@ function Loading({ children }: { children: React.ReactNode }) {
     </Suspense>
   );
 }
+/** What a spec that cannot be shown still says: where it was looked for, what is recorded for it, and the ways on. */
+function SpecUnavailable({
+  kind,
+  file,
+  missing,
+  detail,
+  retry,
+  run
+}: {
+  kind: SpecKind;
+  file: string;
+  missing: boolean;
+  detail: string;
+  retry: () => void;
+  run: string | undefined;
+}) {
+  const evidence = useEvidence();
+  const listed = evidence.files.filter(kind.accepts);
+  const similar = similarSpecs(file, listed);
+  const entry = evidence.view.specs.get(outlinePath(file));
+  return (
+    <Container component="article" size="xl" w="100%" py="xl">
+      <SpecHeader title={file.split('/').at(-1)!} file={file} kind={kind} entry={entry}>
+        <Alert role={missing ? 'status' : 'alert'} color={missing ? 'orange' : 'red'} my="sm" title={missing ? `This ${kind.one} is not available` : `The ${kind.one} could not be read`}>
+          <Stack gap="sm">
+            <Text component="div">
+              {missing ? `specs/${file} is not in this spec set. ` : ''}
+              {detail}
+              {evidence.filesPending || evidence.filesError ? '' : ` ${listed.length} ${listed.length === 1 ? kind.one : kind.many} are listed.`}
+              {entry && entry.slots.length > 0 ? ' Results recorded against it are shown above.' : ''}
+            </Text>
+            {similar.length > 0 && (
+              <>
+                <Text component="div">Did you mean:</Text>
+                <List listStyleType="none">
+                  {similar.map((candidate) => (
+                    <List.Item key={candidate}>
+                      <Anchor renderRoot={(props) => <Link {...props} to="/specs/$kind" params={{ kind: kind.id }} search={{ run, spec: candidate }} />}>{candidate}</Anchor>
+                    </List.Item>
+                  ))}
+                </List>
+              </>
+            )}
+            <Group gap="sm">
+              <Button type="button" onClick={retry} variant="light">
+                Try again
+              </Button>
+              <Button variant="subtle" renderRoot={(props) => <Link {...props} to="/specs/$kind" params={{ kind: kind.id }} search={{ run }} />}>
+                Back to {kind.label}
+              </Button>
+            </Group>
+          </Stack>
+        </Alert>
+      </SpecHeader>
+    </Container>
+  );
+}
 /** One spec tab: its overview, one of its documents, or a recording opened from that document. */
 export function SpecPage() {
   const params = useParams({ from: '/specs/$kind' });
@@ -35,7 +94,8 @@ export function SpecPage() {
   const adapter = useAdapter();
   const evidence = useEvidence();
   const kind = specKind(params.kind);
-  const file = search.spec ? specFile(search.spec) : '';
+  // A link may name a spec by another form of its path (with the folder, in other letter case): the listed one is shown.
+  const file = search.spec ? resolveSpec(specFile(search.spec), evidence.files) : '';
   const readable = kind !== null && file.length > 0 && kind.accepts(file);
   const text = useQuery({
     queryKey: keys.specFile(specKey(adapter), file),
@@ -43,6 +103,12 @@ export function SpecPage() {
     enabled: readable,
     retry: false
   });
+  const stalled = useStalled(text.isLoading, file);
+  const client = useQueryClient();
+  // A read that has not answered is dropped before asking again; asking again beside it would only wait for the same answer.
+  const retryText = () => {
+    void client.cancelQueries({ queryKey: keys.specFile(specKey(adapter), file) }).then(() => text.refetch());
+  };
   if (!kind) {
     return (
       <Container component="article" size="xl" w="100%" py="xl">
@@ -101,24 +167,41 @@ export function SpecPage() {
       </Loading>
     );
   }
-  if (text.isPending)
+  if (text.isPending || (text.isError && evidence.filesPending))
     return (
       <Container component="article" size="xl" w="100%" py="xl">
         <Text role="status" component="div" c="dimmed">
-          Loading the {kind.one}…
+          Loading specs/{file}…
         </Text>
+        {stalled && (
+          <Alert role="status" color="orange" my="sm" title={`Reading the ${kind.one} is taking longer than expected`}>
+            <Group gap="sm">
+              <Text span inherit>
+                specs/{file} has not arrived yet. Recorded results for other specs are not affected.
+              </Text>
+              <Button type="button" onClick={retryText} variant="light">
+                Try again
+              </Button>
+              <Button variant="subtle" renderRoot={(props) => <Link {...props} to="/specs/$kind" params={{ kind: kind.id }} search={{ run: search.run }} />}>
+                Back to {kind.label}
+              </Button>
+            </Group>
+          </Alert>
+        )}
       </Container>
     );
   if (text.isError) {
+    const listedElsewhere = !evidence.filesPending && !evidence.filesError && !evidence.files.includes(file);
+    const missing = isMissing(text.error) || listedElsewhere;
     return (
-      <Container component="article" size="xl" w="100%" py="xl">
-        <Alert role="alert" color={'red'} my="sm">
-          The {kind.one} could not be read.{' '}
-          <Button type="button" onClick={() => void text.refetch()} variant="subtle">
-            Try again
-          </Button>
-        </Alert>
-      </Container>
+      <SpecUnavailable
+        kind={kind}
+        file={file}
+        missing={missing}
+        detail={text.error instanceof Error ? text.error.message : ''}
+        retry={retryText}
+        run={search.run}
+      />
     );
   }
   const page = { file, text: text.data, kind, entry, selection: { check: search.check, layer: search.layer }, select };

package/packages/visualizer/src/find/Finder.tsx

@@ -6,6 +6,7 @@ import { useEffect, useMemo, useRef, useState, type KeyboardEvent as ReactKeyboa
 import { useAtlas } from '../app/atlas-context';
 import { keys, specKey, useAdapter } from '../data/queries';
 import { useEvidence } from '../evidence/evidence-context';
+import { plural } from '../evidence/format';
 import { StatusMark } from '../evidence/marks';
 import { kindOfFile } from '../spec-kind';
 import { corpusFrom } from './corpus';
@@ -41,15 +42,29 @@ function isTypingTarget(target: EventTarget | null) {
   const tag = target.tagName;
   return target.isContentEditable || tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || tag === 'BUTTON' || tag === 'A';
 }
-function useSpecTexts(files: readonly string[]) {
+/**
+ * Reads the text of every spec for search, a few at a time, once `enabled`. Each file lands as it arrives, so a search
+ * can use what is read so far; `read` of `total` say how far it is, and `failed` how many could not be read at all.
+ */
+function useSpecTexts(files: readonly string[], enabled: boolean, open: boolean) {
   const adapter = useAdapter();
   const client = useQueryClient();
   const source = specKey(adapter);
   const cache = useRef(new Map<string, string>());
+  const unreadable = useRef(new Set<string>());
   const [texts, setTexts] = useState<ReadonlyMap<string, string>>(() => new Map());
   const [pending, setPending] = useState(false);
+  const [failedFiles, setFailedFiles] = useState<ReadonlySet<string>>(() => new Set());
   const key = files.join('\n');
+  // Opening the finder is another chance for the files that could not be read.
   useEffect(() => {
+    if (!open || unreadable.current.size === 0) return;
+    for (const file of unreadable.current) cache.current.delete(file);
+    unreadable.current.clear();
+    setFailedFiles(new Set());
+  }, [open]);
+  useEffect(() => {
+    if (!enabled) return;
     const wanted = key.length === 0 ? [] : key.split('\n');
     let cancelled = false;
     const missing = wanted.filter((file) => !cache.current.has(file));
@@ -65,13 +80,15 @@ function useSpecTexts(files: readonly string[]) {
         if (file === undefined || cancelled) return;
         let text = '';
         try {
-          text = await client.fetchQuery({ queryKey: keys.specFile(source, file), queryFn: () => adapter.specFile(file) });
+          text = await client.fetchQuery({ queryKey: keys.specFile(source, file), queryFn: () => adapter.specFile(file), retry: false });
         } catch {
           text = '';
+          unreadable.current.add(file);
         }
         if (cancelled) return;
         cache.current.set(file, text);
         setTexts(new Map(cache.current));
+        if (unreadable.current.has(file)) setFailedFiles(new Set(unreadable.current));
       }
     };
     void Promise.all([pull(), pull(), pull(), pull()]).then(() => {
@@ -80,8 +97,10 @@ function useSpecTexts(files: readonly string[]) {
     return () => {
       cancelled = true;
     };
-  }, [adapter, client, key, source]);
-  return { texts, pending };
+  }, [adapter, client, enabled, key, source]);
+  const read = useMemo(() => files.filter((file) => texts.has(file)).length, [files, texts]);
+  const failed = useMemo(() => files.filter((file) => failedFiles.has(file)).length, [files, failedFiles]);
+  return { texts, pending, total: files.length, read, failed };
 }
 /** The vector cache outlives a keystroke, so a live run does not embed the suite again. */
 const vectorCache = new Map<string, Float32Array>();
@@ -101,12 +120,25 @@ export function Finder() {
   const navigate = useNavigate();
   const routeSearch = useSearch({ strict: false });
   const readable = useMemo(() => evidence.files.filter((file) => kindOfFile(file)), [evidence.files]);
-  const { texts, pending } = useSpecTexts(readable);
+  // Reading every spec's text is for search, and a focused page needs its own spec first: start only once search is wanted.
+  const [wanted, setWanted] = useState(false);
+  useEffect(() => {
+    if (open) setWanted(true);
+  }, [open]);
+  const { texts, pending, total, read, failed } = useSpecTexts(readable, wanted, open);
   const docs = useMemo(
     () => corpusFrom(view, evidence.files, evidence.titleOf, evidence.view, texts),
     [view, evidence.files, evidence.titleOf, evidence.view, texts]
   );
   const index = useMemo(() => indexCorpus(docs), [docs]);
+  // What search has not covered yet, so an empty answer is not read as "no such behavior".
+  const unindexed = evidence.filesPending
+    ? 'The spec list is still loading'
+    : pending
+      ? `${total - read} of ${total} specs are still being read`
+      : !evidence.ready && !evidence.unavailable
+        ? 'Recorded results are still loading'
+        : '';
   const [query, setQuery] = useState('');
   const store = finderStore;
   const spotlightState = useSpotlight(store);
@@ -254,7 +286,13 @@ export function Finder() {
         <Spotlight.ActionsList id="atlas-finder-actions" role="listbox" aria-label="Flows, specs and runs">
           {shown.length === 0 && (
             <Spotlight.Empty>
-              {query.trim() ? 'Nothing close to that.' : 'Type what someone does. For example, add a todo.'}
+              {!query.trim()
+                ? 'Type what someone does. For example, add a todo.'
+                : unindexed
+                  ? `No match yet. ${unindexed}, so this is not the final answer.`
+                  : failed > 0
+                    ? `Nothing close to that. ${plural(failed, 'spec', 'specs')} could not be read, so search may miss ${failed === 1 ? 'it' : 'them'}.`
+                    : 'Nothing close to that.'}
             </Spotlight.Empty>
           )}
           {FIND_GROUPS.map((group) => {
@@ -285,7 +323,7 @@ export function Finder() {
         <Spotlight.Footer>
           <Group gap="md" justify="space-between">
             <Text size="xs" c="dimmed">
-              {pending ? 'Reading specs…' : '↑↓ move'}
+              {unindexed ? `Searching what is read so far: ${unindexed}` : failed > 0 ? `${plural(failed, 'spec', 'specs')} could not be read and ${failed === 1 ? 'is' : 'are'} not searched` : '↑↓ move'}
             </Text>
             <Text size="xs" c="dimmed">
               ↵ open · esc close

package/packages/visualizer/src/spec-kind.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'bun:test';
 
-import { fileName, folderOf, kindOfFile, outlinePath, specFile, specKind } from './spec-kind';
+import { fileName, folderOf, kindOfFile, outlinePath, resolveSpec, similarSpecs, specFile, specKind } from './spec-kind';
 
 describe('spec kinds', () => {
   it('gives each notation its own tab and leaves statecharts and notes to the map', () => {
@@ -24,4 +24,17 @@ describe('spec kinds', () => {
     expect(folderOf('auth/sign-in.feature')).toBe('auth');
     expect(folderOf('atlas.yaml')).toBe('');
   });
+
+  it('reads a link to a spec by any form of its path and finds the listed spec it means', () => {
+    expect(specFile('./auth/sign-in.feature')).toBe('auth/sign-in.feature');
+    expect(specFile('/specs/auth\\sign-in.feature')).toBe('auth/sign-in.feature');
+    const listed = ['auth/sign-in.feature', 'billing/Pay.feature', 'billing/pay-later.feature', 'a/x.feature', 'b/x.feature'];
+    expect(resolveSpec('auth/sign-in.feature', listed)).toBe('auth/sign-in.feature');
+    expect(resolveSpec('Auth/Sign-In.feature', listed)).toBe('auth/sign-in.feature');
+    expect(resolveSpec('sign-in.feature', listed)).toBe('auth/sign-in.feature');
+    // Two candidates, or none, leave the link as written.
+    expect(resolveSpec('x.feature', listed)).toBe('x.feature');
+    expect(resolveSpec('nothing.feature', listed)).toBe('nothing.feature');
+    expect(similarSpecs('other/pay.feature', listed)).toEqual(['billing/Pay.feature']);
+  });
 });

package/packages/visualizer/src/spec-kind.ts

@@ -42,9 +42,35 @@ export function outlinePath(file: string) {
   return normal.startsWith('specs/') ? normal : `specs/${normal}`;
 }
 
-/** A file path relative to the specs folder, from either form. */
+/**
+ * A file path relative to the specs folder, from any form a link may name it by: with or without the `specs/` folder,
+ * with a leading `./` or `/`, with backslashes. Nothing here can leave the folder; `..` parts are kept for the reader to refuse.
+ */
 export function specFile(path: string) {
-  return path.replaceAll('\\', '/').replace(/^specs\//, '');
+  return path
+    .replaceAll('\\', '/')
+    .replace(/^(\.?\/)+/, '')
+    .replace(/^specs\//, '')
+    .replace(/\/{2,}/g, '/');
+}
+
+/**
+ * The listed spec a link means. An exact entry wins; otherwise the one listed spec that differs only in letter case, or that
+ * the link names by a trailing part of its path. More than one candidate, or none, leaves the link as written.
+ */
+export function resolveSpec(file: string, listed: readonly string[]): string {
+  if (listed.includes(file)) return file;
+  const lower = file.toLowerCase();
+  const sameCase = listed.filter((candidate) => candidate.toLowerCase() === lower);
+  if (sameCase.length === 1) return sameCase[0]!;
+  const tail = listed.filter((candidate) => candidate.toLowerCase().endsWith(`/${lower}`));
+  return tail.length === 1 ? tail[0]! : file;
+}
+
+/** The listed specs with the same file name as `file`, to offer when a link names one that is not there. */
+export function similarSpecs(file: string, listed: readonly string[], limit = 5): string[] {
+  const name = fileName(file).toLowerCase();
+  return listed.filter((candidate) => fileName(candidate).toLowerCase() === name).slice(0, limit);
 }
 
 export function fileName(path: string) {