@crvouga/atlas 0.4.0 → 0.5.0

package/dist/schema/src/common.js

@@ -1,5 +1,20 @@
+/**
+ * @module Shared statechart vocabulary
+ *
+ * Small schemas and types used by both the run manifest (`manifest.ts`) and the spec formats (`spec.ts`): the status
+ * of a run result, who sends an event, how sure a spec is, screenshot references, status tallies, the shape of a
+ * reading problem, and the transition id convention. The statuses and kinds are written by `atlas run` and read by
+ * the visualizer.
+ *
+ * @see docs/statecharts.md
+ */
 import { z } from 'zod/v4';
+/**
+ * Outcome of a state, transition, path or journey in a statechart run: `passed`, `failed`, `flaky` (failed on the
+ * first attempt and passed on the retry) or `not-reached` (no path got there, or the path was blocked before it).
+ */
 export const RUN_STATUSES = ['passed', 'failed', 'flaky', 'not-reached'];
+/** Zod enum over `RUN_STATUSES`. */
 export const RunStatusSchema = z.enum(RUN_STATUSES);
 /**
  * Who or what sends an event: a person using the product (`user`), another system (`system`), the
@@ -7,17 +22,35 @@ export const RunStatusSchema = z.enum(RUN_STATUSES);
  * `member` is read as `user`, for specs written before the kinds were renamed.
  */
 export const EVENT_KINDS = ['user', 'system', 'time', 'hand-off'];
+/**
+ * Zod schema for an `EVENT_KINDS` value that first rewrites the legacy value `member` to `user`, so specs written
+ * before the kinds were renamed still parse.
+ */
 export const EventKindSchema = z.preprocess((value) => (value === 'member' ? 'user' : value), z.enum(EVENT_KINDS));
+/**
+ * How sure a spec is about a state's description (`meta.confidence`): `confirmed` or `assumed`. A run records
+ * `assumed` for a state whose spec does not say.
+ */
 export const CONFIDENCES = ['confirmed', 'assumed'];
+/** Zod enum over `CONFIDENCES`. */
 export const ConfidenceSchema = z.enum(CONFIDENCES);
 const ScreenSchema = z.object({
     png: z.string().min(1),
     webp: z.string().min(1).optional().describe('About 400 px wide, for the map; the original image is used while a thumbnail is unavailable'),
     client: z.string().optional().describe('Which client\'s screen it is, in a multi-client run')
 });
+/**
+ * A screenshot of a state in a run manifest: `png` and an optional `webp` thumbnail, as paths relative to the run
+ * directory (the folder holding `manifest.json`), plus the other clients' screens at the same moment in a
+ * multi-client run.
+ */
 export const ImageSchema = ScreenSchema.extend({
     also: z.array(ScreenSchema.partial({ webp: true })).optional().describe("The other clients' screens at the same moment")
 });
+/**
+ * Tally of states or transitions by status: `total` and one count per `RUN_STATUSES` value (`notReached` for
+ * `not-reached`). Used by manifest coverage and run summaries.
+ */
 export const CountSchema = z.object({
     total: z.number().int().nonnegative(),
     passed: z.number().int().nonnegative(),
@@ -25,8 +58,17 @@ export const CountSchema = z.object({
     flaky: z.number().int().nonnegative(),
     notReached: z.number().int().nonnegative()
 });
+/** Severities of a `DataIssue`, most serious first: `error`, `warning`, `info`. */
 export const ISSUE_SEVERITIES = ['error', 'warning', 'info'];
+/**
+ * Separator inside a transition id (`<source state> :: <event>`). Ids are not escaped, so a state name containing it
+ * makes an id ambiguous. The same value as core's `TRANSITION_SEPARATOR`.
+ */
 export const TRANSITION_ID_SEPARATOR = ' :: ';
+/**
+ * Builds the id of a transition, the key of `transitions` in a manifest: the source state's name,
+ * `TRANSITION_ID_SEPARATOR`, then the event name.
+ */
 export function transitionId(source, event) {
     return `${source}${TRANSITION_ID_SEPARATOR}${event}`;
 }

package/dist/schema/src/index.d.ts

@@ -1,5 +1,19 @@
+/**
+ * @module Schema package entry point (`@crvouga/atlas/schema`)
+ *
+ * Re-exports every Zod schema, constant and inferred type of the Atlas contract: the layer format and report status
+ * (`layer`), the statechart run manifest (`manifest`, `common`), the spec file formats (`spec`), the run index and
+ * report sources the viewer reads (`runs-index`, `report-sources`) and the server configuration (`server-config`).
+ * The JSON Schemas shipped in `schemas/` are generated from these by `bun run schemas`.
+ *
+ * @see docs/report-contract.md
+ */
 export * from './common.js';
 export * from './manifest.js';
 export * from './runs-index.js';
 export * from './spec.js';
 export * from './report-sources.js';
+export * from './layer.js';
+export * from './server-config.js';
+export * from './api.js';
+export * from './cli-results.js';

package/dist/schema/src/index.js

@@ -1,5 +1,19 @@
+/**
+ * @module Schema package entry point (`@crvouga/atlas/schema`)
+ *
+ * Re-exports every Zod schema, constant and inferred type of the Atlas contract: the layer format and report status
+ * (`layer`), the statechart run manifest (`manifest`, `common`), the spec file formats (`spec`), the run index and
+ * report sources the viewer reads (`runs-index`, `report-sources`) and the server configuration (`server-config`).
+ * The JSON Schemas shipped in `schemas/` are generated from these by `bun run schemas`.
+ *
+ * @see docs/report-contract.md
+ */
 export * from './common.js';
 export * from './manifest.js';
 export * from './runs-index.js';
 export * from './spec.js';
 export * from './report-sources.js';
+export * from './layer.js';
+export * from './server-config.js';
+export * from './api.js';
+export * from './cli-results.js';