@crvouga/atlas 1.18.0 → 1.19.0

package/packages/visualizer/src/evidence/behavior-index.ts

@@ -0,0 +1,162 @@
+/**
+ * @module Project-wide behavior index
+ *
+ * Every behavior of every Gherkin feature in the project as one list, so a reader can search "what does this product
+ * promise?" without knowing which feature file holds the answer. It adds no source of truth: each feature is read
+ * through the same {@link featureBehaviors} the feature page uses, so a behavior has the same coverage state, revisions
+ * and recording here as there. Features whose text has not arrived, or cannot be parsed, are counted and named rather
+ * than silently absent, so an empty answer is never mistaken for "no such behavior".
+ */
+import type { EvidenceView } from '@crvouga/atlas/reports/evidence-view';
+import type { LayerEvidence } from '@crvouga/atlas/reports/evidence-types';
+import type { SpecEntry } from '@crvouga/atlas/reports/explorer-types';
+
+import type { DocFacets } from '../find/query';
+import type { FindDoc, FindField, FindStatus } from '../find/rank';
+import { outlinePath } from '../spec-kind';
+import { assessBehavior, type Assessment, type ReleaseIdentity } from './applicability';
+import { COVERAGE, featureBehaviors, type Behavior, type RevisionSource } from './behavior';
+import { featureModel, scenarioLabel, type FeatureModel } from './gherkin';
+
+/** One behavior of the project, with where it is written. */
+export type IndexedBehavior = {
+  /** Stable for the behavior within the project: the feature file and the behavior's key in it. Safe in an address. */
+  readonly id: string;
+  /** The feature file relative to the specs folder. */
+  readonly file: string;
+  /** The path reports name the feature by (`specs/…`). */
+  readonly specPath: string;
+  /** The feature's title. */
+  readonly feature: string;
+  /** The domain the spec metadata declares; empty when it declares none (nothing is invented). */
+  readonly domain: string;
+  /** The rule the scenario sits under, or null. */
+  readonly rule: string | null;
+  /** The behavior in words: the scenario, and for an outline's example its example label. */
+  readonly title: string;
+  readonly behavior: Behavior;
+  /** Whether the evidence applies to the promise as written now (no release is named in this index). */
+  readonly assessment: Assessment;
+};
+
+/** The behaviors of the project and what could not be read into them. */
+export type BehaviorIndex = {
+  readonly entries: readonly IndexedBehavior[];
+  /** Feature files in the project. */
+  readonly features: number;
+  /** Feature files whose text has not arrived yet; their behaviors are not here yet. */
+  readonly unread: number;
+  /** Feature files that could not be read or parsed; their behaviors are not here. */
+  readonly unreadable: readonly string[];
+};
+
+/** What the index reads: the feature files and their texts, the outline (domains, fingerprints) and the report. */
+export type IndexInput = {
+  /** The feature files, relative to the specs folder. */
+  readonly files: readonly string[];
+  /** The text of each file read so far; an empty text is a file that could not be read. */
+  readonly texts: ReadonlyMap<string, string>;
+  readonly specs: readonly SpecEntry[];
+  readonly view: EvidenceView;
+  /** The layers the report holds, for the spec fingerprint each recorded. */
+  readonly evidence: readonly Pick<LayerEvidence, 'layer' | 'fingerprints'>[];
+  readonly release?: ReleaseIdentity;
+};
+
+function parse(text: string): FeatureModel | null {
+  try {
+    return featureModel(text);
+  } catch {
+    return null;
+  }
+}
+
+/** Reads every feature into behaviors. Pure: the same inputs give the same list, in file then page order. */
+export function indexBehaviors(input: IndexInput): BehaviorIndex {
+  const fingerprints = new Map(input.evidence.map((layer) => [layer.layer.id, layer.fingerprints] as const));
+  const entries: IndexedBehavior[] = [];
+  const unreadable: string[] = [];
+  let unread = 0;
+  for (const file of input.files) {
+    const text = input.texts.get(file);
+    if (text === undefined) {
+      unread += 1;
+      continue;
+    }
+    const feature = text === '' ? null : parse(text);
+    if (!feature) {
+      unreadable.push(file);
+      continue;
+    }
+    const specPath = outlinePath(file);
+    const spec = input.specs.find((candidate) => candidate.path === specPath);
+    const revisions: RevisionSource = { current: spec?.fingerprint ?? null, recorded: (id) => fingerprints.get(id)?.[specPath] };
+    const found = featureBehaviors(feature, input.view.specs.get(specPath)?.slots ?? [], revisions);
+    const ruleOf = new Map(feature.rules.flatMap((rule) => rule.scenarios.map((scenario) => [scenario, rule.name] as const)));
+    for (const behavior of found.all) {
+      const claimed = found.byScenario.has(behavior.scenario);
+      entries.push({
+        id: `${file}#${behavior.key}`,
+        file,
+        specPath,
+        feature: feature.name || file.split('/').at(-1)!,
+        domain: spec?.domain ?? '',
+        rule: ruleOf.get(behavior.scenario) ?? null,
+        title: claimed
+          ? behavior.example
+            ? `${behavior.scenario.name} — ${behavior.example}`
+            : behavior.scenario.name
+          : scenarioLabel(feature.name, behavior.scenario.name),
+        behavior,
+        assessment: assessBehavior(behavior, revisions, input.release ?? {})
+      });
+    }
+  }
+  return { entries, features: input.files.length, unread, unreadable };
+}
+
+/** The check status a behavior's search document filters by, or none when nothing reported on it. */
+function statusOf(behavior: Behavior): FindStatus {
+  return behavior.slot?.status ?? 'none';
+}
+
+/**
+ * A behavior as a searchable document for the shared matcher (`find/`): its wording and steps are what a reader searches
+ * by; the feature, rule, domain, tags and coverage state are metadata. Its facets feed the typed filters (`status:`,
+ * `domain:`, `spec:`, `tag:`, `env:`, `has:video`).
+ */
+export function behaviorDoc(entry: IndexedBehavior): FindDoc {
+  const { behavior } = entry;
+  const outcomes = behavior.slot?.outcomes ?? [];
+  const steps = behavior.scenario.steps.map((step) => `${step.keyword} ${step.text}`).join('\n');
+  const fields: FindField[] = [{ name: 'title', text: entry.title }];
+  if (steps) fields.push({ name: 'steps', text: steps });
+  const description = [entry.feature, entry.rule ?? '', behavior.scenario.description].filter(Boolean).join('\n');
+  if (description) fields.push({ name: 'description', text: description });
+  const metadata = [entry.domain, ...behavior.scenario.tags, COVERAGE[behavior.state].label].filter(Boolean);
+  fields.push({ name: 'metadata', text: metadata.join('\n') });
+  fields.push({ name: 'path', text: entry.specPath });
+  const facets: DocFacets = {
+    status: behavior.slot ? [behavior.slot.status] : [],
+    env: [...new Set(outcomes.map((result) => result.layer.environment ?? '(none)'))],
+    producer: [...new Set(outcomes.map((result) => result.layer.producer))],
+    domain: [entry.domain || '(no domain)'],
+    spec: [entry.specPath],
+    tag: behavior.scenario.tags.map((tag) => tag.replace(/^@/, '')),
+    branch: [...new Set(outcomes.flatMap((result) => (result.layer.branch ? [result.layer.branch] : [])))],
+    video: behavior.demo !== null
+  };
+  return {
+    id: entry.id,
+    group: 'Specs',
+    kind: 'scenario',
+    title: entry.title,
+    subtitle: entry.feature,
+    fields,
+    status: statusOf(behavior),
+    related: [],
+    target: { to: '/specs/$kind', kind: 'gherkin', search: { spec: entry.file, ...(behavior.slot ? { check: behavior.slot.id } : {}) } },
+    recording: null,
+    facets
+  };
+}

package/packages/visualizer/src/evidence/behavior-panel.tsx

@@ -26,6 +26,7 @@ import { exampleIndexFor, exampleRows, fillExample, type FeatureStep } from './g
 import { Origin, StatusMark } from './marks';
 import { MomentPlayback, stepsOfRecording, useMomentVideo, useRequestedMoment } from './moments';
 import { outcomeHeadline, videosIn } from './outcome';
+import { ScopedSummary } from './scoped-summary-view';
 
 /** The short, readable form of a spec fingerprint (`<length>:<hash>:<hash>`): its length and the start of its hash. */
 export function shortRevision(fingerprint: string): string {
@@ -83,6 +84,18 @@ function expectedSteps(steps: readonly FeatureStep[]): FeatureStep[] {
   return at < 0 ? [] : steps.slice(at);
 }
 
+/**
+ * The steps a behavior reads as: an outline's example with its values filled in, else the scenario's own. `expected` is
+ * what should be true afterwards; `named` is true when the recorded example name matches no row, so nothing was filled in.
+ */
+export function behaviorSteps(behavior: Behavior) {
+  const { scenario, example } = behavior;
+  const at = example === null ? -1 : exampleIndexFor(scenario, example);
+  const entry = at < 0 ? null : exampleRows(scenario)[at]!;
+  const steps = entry ? fillExample(scenario.steps, entry) : scenario.steps;
+  return { steps, entry, expected: expectedSteps(steps), named: example !== null && entry === null };
+}
+
 /** The recording itself: the one player the steps beside it seek, which marks the step playing. */
 function WatchVideo({ attachment, url }: { attachment: Attachment; url: string }) {
   const moments = useMomentVideo(attachment);
@@ -101,8 +114,8 @@ function WatchVideo({ attachment, url }: { attachment: Attachment; url: string }
   );
 }
 
-/** The recording of one result, read only when this is on screen. */
-function Player({ result }: { result: EvidenceResult }) {
+/** The recording of one result, read only when this is on screen, with the steps beside it that seek it. */
+export function Player({ result }: { result: EvidenceResult }) {
   const detail = useCheckDetail(result.layer, result.row);
   const videos = useMemo(() => videosIn(detail.data?.check), [detail.data]);
   const requested = useRequestedMoment();
@@ -158,6 +171,24 @@ function Player({ result }: { result: EvidenceResult }) {
   );
 }
 
+/** What the result shown recorded and where it came from: its status, environment, run, commit and time. */
+export function Provenance({ subject }: { subject: EvidenceResult }) {
+  const { backends } = useEvidence();
+  const now = useNow();
+  return (
+    <Group gap="xs" wrap="wrap" align="center">
+      <StatusMark status={subject.row.status} size={14} />
+      <Text span inherit fw={600}>
+        {statusWord(subject.row.status)}
+      </Text>
+      <Text span inherit c="dimmed">
+        in {environmentLabel(subject.layer.environment)}
+      </Text>
+      <Origin layer={subject.layer} backends={backends} now={now} />
+    </Group>
+  );
+}
+
 /** Read, Watch and Inspect for one behavior. `inspect` is the technical record, shown only under Inspect. */
 export function BehaviorPanel({
   behavior,
@@ -175,14 +206,8 @@ export function BehaviorPanel({
   /** The tab to open on; by default Watch when there is something to watch, Inspect while a run is in progress (its progress lives there), else Read. */ start?:
     'read' | 'watch' | 'inspect';
 }) {
-  const { backends } = useEvidence();
-  const now = useNow();
   const { scenario, example, demo, subject, revision, state } = behavior;
-  const at = example === null ? -1 : exampleIndexFor(scenario, example);
-  const entry = at < 0 ? null : exampleRows(scenario)[at]!;
-  const steps = useMemo(() => (entry ? fillExample(scenario.steps, entry) : scenario.steps), [scenario, entry]);
-  const expected = expectedSteps(steps);
-  const named = example !== null && entry === null;
+  const { steps, entry, expected, named } = useMemo(() => behaviorSteps(behavior), [behavior]);
   // The coverage state is the check's combined status; this says what the recording or result shown here recorded, apart from it.
   const outcome =
     subject && behavior.slot ? (
@@ -229,7 +254,6 @@ export function BehaviorPanel({
             <CoverageBadge state={state} />
             {behavior.representative && <Badge variant="outline">Representative demo</Badge>}
           </Group>
-          {outcome}
           {expected.length > 0 && (
             <Box component="section" aria-label="Expected outcome">
               <Title order={4} mb="xs">
@@ -250,19 +274,9 @@ export function BehaviorPanel({
               Nothing to watch. {COVERAGE[state].meaning}
             </Text>
           )}
-          {subject && (
-            <Group gap="xs" wrap="wrap" align="center">
-              <StatusMark status={subject.row.status} size={14} />
-              <Text span inherit fw={600}>
-                {statusWord(subject.row.status)}
-              </Text>
-              <Text span inherit c="dimmed">
-                in {environmentLabel(subject.layer.environment)}
-              </Text>
-              <Origin layer={subject.layer} backends={backends} now={now} />
-            </Group>
-          )}
+          {subject && <Provenance subject={subject} />}
           <RevisionLine revision={revision} />
+          <ScopedSummary behavior={behavior} />
           {applicability && <ApplicabilitySummary assessment={applicability} release={release} />}
         </Stack>
       </Tabs.Panel>

package/packages/visualizer/src/evidence/behavior-return.test.ts

@@ -0,0 +1,41 @@
+import { beforeEach, expect, test } from 'bun:test';
+
+import { forgetReturn, recallReturn, rememberReturn, scopeKey } from './behavior-return';
+
+const store = new Map<string, string>();
+beforeEach(() => {
+  store.clear();
+  (globalThis as { sessionStorage?: unknown }).sessionStorage = {
+    getItem: (key: string) => store.get(key) ?? null,
+    setItem: (key: string, value: string) => void store.set(key, value),
+    removeItem: (key: string) => void store.delete(key)
+  };
+});
+
+test('a remembered point comes back only to the scope it was taken in', () => {
+  const scope = scopeKey({ q: 'refund', coverage: 'failed' });
+  rememberReturn({ scope, scrollY: 480, shown: 80, focus: 'a.feature#Refund' });
+  expect(recallReturn(scope)).toEqual({ scope, scrollY: 480, shown: 80, focus: 'a.feature#Refund' });
+  // Another search, or none, never gets the scroll of this one.
+  expect(recallReturn(scopeKey({ q: 'pay' }))).toBeNull();
+  expect(recallReturn(scopeKey({}))).toBeNull();
+});
+
+test('reading a point does not forget it until it is given back', () => {
+  const scope = scopeKey({});
+  rememberReturn({ scope, scrollY: 10, shown: 40, focus: null });
+  expect(recallReturn(scope)).not.toBeNull();
+  expect(recallReturn(scope)).not.toBeNull();
+  forgetReturn();
+  expect(recallReturn(scope)).toBeNull();
+});
+
+test('unreadable or unavailable storage only means nothing is restored', () => {
+  store.set('atlas-behaviors-return', '{not json');
+  expect(recallReturn(scopeKey({}))).toBeNull();
+  store.set('atlas-behaviors-return', JSON.stringify({ scope: scopeKey({}), scrollY: 'far' }));
+  expect(recallReturn(scopeKey({}))).toBeNull();
+  (globalThis as { sessionStorage?: unknown }).sessionStorage = undefined;
+  expect(() => rememberReturn({ scope: 's', scrollY: 1, shown: 1, focus: null })).not.toThrow();
+  expect(recallReturn('s')).toBeNull();
+});

package/packages/visualizer/src/evidence/behavior-return.ts

@@ -0,0 +1,59 @@
+/**
+ * @module Returning from the read-and-watch workspace
+ *
+ * Opening a behavior in the dedicated workspace replaces the index, so the index would come back at the top with
+ * nothing selected. The scope (the search words and the coverage filter) and the selection are in the address and come
+ * back by themselves. What an address cannot hold is where the reader had scrolled to, how much of a long list had been
+ * shown, and which row had focus: they are remembered here for the session, against the scope they were taken in, and
+ * given back once, only to the same scope.
+ */
+
+const KEY = 'atlas-behaviors-return';
+
+/** What the index remembers when it is left for the workspace. */
+export type ReturnPoint = {
+  /** The scope the point was taken in ({@link scopeKey}); it is only used for that scope. */
+  readonly scope: string;
+  /** How far the page was scrolled, in pixels. */
+  readonly scrollY: number;
+  /** How many rows of the list had been shown. */
+  readonly shown: number;
+  /** The behavior whose row had focus, or null. */
+  readonly focus: string | null;
+};
+
+/** The scope of an index: its search words and its coverage filter. */
+export function scopeKey(search: { readonly q?: string | undefined; readonly coverage?: string | undefined }): string {
+  return JSON.stringify([search.q ?? '', search.coverage ?? '']);
+}
+
+/** Remembers where the reader was. Storage that is unavailable or full only means nothing is restored. */
+export function rememberReturn(point: ReturnPoint): void {
+  try {
+    sessionStorage.setItem(KEY, JSON.stringify(point));
+  } catch {
+    // Not being able to remember means the list opens at its top.
+  }
+}
+
+/** The remembered point, if it was taken in `scope`; a point of another scope is never used. Reading does not forget it. */
+export function recallReturn(scope: string): ReturnPoint | null {
+  try {
+    const raw = sessionStorage.getItem(KEY);
+    if (!raw) return null;
+    const point = JSON.parse(raw) as Partial<ReturnPoint>;
+    if (point.scope !== scope || typeof point.scrollY !== 'number' || typeof point.shown !== 'number') return null;
+    return { scope, scrollY: point.scrollY, shown: point.shown, focus: typeof point.focus === 'string' ? point.focus : null };
+  } catch {
+    return null;
+  }
+}
+
+/** Forgets the remembered point, once it has been given back. */
+export function forgetReturn(): void {
+  try {
+    sessionStorage.removeItem(KEY);
+  } catch {
+    // Nothing was remembered.
+  }
+}

package/packages/visualizer/src/evidence/behavior.ts

@@ -11,7 +11,7 @@
 import type { CheckSlot } from '@crvouga/atlas/reports/evidence-view';
 import type { EvidenceResult } from '@crvouga/atlas/reports/layer-merge';
 
-import { exampleIndexFor, exampleRows, scenarioLabel, type FeatureScenario } from './gherkin';
+import { exampleIndexFor, exampleRows, scenarioLabel, slotsByScenario, type FeatureModel, type FeatureScenario } from './gherkin';
 
 /** Where a behavior stands, from the most reassuring to the least. */
 export type CoverageState =
@@ -266,3 +266,34 @@ export function coverageCounts(behaviors: readonly Behavior[]): CoverageCounts {
   for (const behavior of behaviors) counts[behavior.state] += 1;
   return counts;
 }
+
+/** Every behavior of a feature, by scenario, with the ones no scenario claims. */
+export type FeatureBehaviors = {
+  /** The behaviors of each scenario (a background is not one), in the order the file has them. */
+  readonly byScenario: ReadonlyMap<FeatureScenario, readonly Behavior[]>;
+  /** The recorded checks no scenario of the file claims: recorded against the file under a name it does not have now. */
+  readonly leftOver: readonly CheckSlot[];
+  /** Every behavior, claimed or not, in page order; a result no scenario claims is still a behavior that was checked. */
+  readonly all: readonly Behavior[];
+};
+
+/** A scenario that stands for a recorded check no scenario of the file names. */
+function strayScenario(name: string): FeatureScenario {
+  return { keyword: 'Scenario', name, description: '', background: false, tags: [], steps: [], examples: [] };
+}
+
+/**
+ * Reads a whole feature as behaviors: its scenarios (an outline as one per example), each with the recorded checks filed
+ * under it, and the checks no scenario claims. The feature page and the project-wide behavior index both read a feature
+ * through this, so a behavior is the same behavior wherever it is listed. `feature` is null when the file could not be parsed.
+ */
+export function featureBehaviors(feature: FeatureModel | null, slots: readonly CheckSlot[], revisions: RevisionSource): FeatureBehaviors {
+  // A file that cannot be read has no scenarios: every check recorded against it is one nothing claims.
+  const filed = feature ? slotsByScenario(feature, slots) : { byScenario: new Map<string, CheckSlot[]>(), leftOver: [...slots] };
+  const byScenario = new Map<FeatureScenario, Behavior[]>();
+  for (const scenario of feature?.rules.flatMap((rule) => rule.scenarios.filter((each) => !each.background)) ?? []) {
+    byScenario.set(scenario, scenarioBehaviors(scenario, filed.byScenario.get(scenario.name) ?? [], feature!.name, revisions));
+  }
+  const other = filed.leftOver.map((slot) => behaviorOf(strayScenario(slot.title), slot, null, revisions, slot.key));
+  return { byScenario, leftOver: filed.leftOver, all: [...[...byScenario.values()].flat(), ...other] };
+}