@asrunjs/asrun 0.2.0 → 0.5.2

package/dist/lib/build-artifacts.d.ts

@@ -0,0 +1,8 @@
+/**
+ * What `pnpm build` produces, which `scripts/build.ts` writes and `scripts/doctor.ts` checks. `tsconfig.build.json`
+ * compiles every `.ts` file into the same relative path under `dist/`; the plain `.mjs` tools are copied as they are.
+ * Keeping the copied files here means the build and the check of a stale build cannot drift apart.
+ */
+export declare const COPIED_SCRIPTS: string[];
+/** The file `dist/` holds for a framework source: `lib/paths.ts` -> `dist/lib/paths.js`, `scripts/go.mjs` -> `dist/scripts/go.mjs`. */
+export declare function builtFile(source: string): string;

package/dist/lib/build-artifacts.js

@@ -0,0 +1,10 @@
+/**
+ * What `pnpm build` produces, which `scripts/build.ts` writes and `scripts/doctor.ts` checks. `tsconfig.build.json`
+ * compiles every `.ts` file into the same relative path under `dist/`; the plain `.mjs` tools are copied as they are.
+ * Keeping the copied files here means the build and the check of a stale build cannot drift apart.
+ */
+export const COPIED_SCRIPTS = ['go.mjs', 'heal-evidence.mjs'];
+/** The file `dist/` holds for a framework source: `lib/paths.ts` -> `dist/lib/paths.js`, `scripts/go.mjs` -> `dist/scripts/go.mjs`. */
+export function builtFile(source) {
+    return `dist/${source.replace(/\.ts$/, '.js')}`;
+}

package/dist/lib/case-doc.d.ts

@@ -0,0 +1,311 @@
+export type StepTag = 'writes' | 'input' | 'email';
+export declare const STEP_TAGS: readonly StepTag[];
+export interface TextRange {
+    start: number;
+    end: number;
+}
+export interface TextEdit extends TextRange {
+    text: string;
+}
+/** One line of the file: `text` without its line break, `start`/`end` are offsets into the whole document. */
+export interface CaseLine {
+    number: number;
+    start: number;
+    end: number;
+    text: string;
+}
+export interface CaseSection {
+    name: string;
+    /** Offset of the `## ` heading. */
+    headingStart: number;
+    /** The body: after the heading line up to the next `## ` heading (or the end of the file). */
+    body: TextRange;
+}
+/** One entry of the front matter, with the ranges the panel edits. */
+export interface FrontMatterEntry {
+    key: string;
+    /** The parsed value (a string, a list, ...). */
+    value: unknown;
+    /** The key line through the last line of its value (trailing blank lines excluded). */
+    range: TextRange;
+    /** The value itself: on the key line after the colon, or the block below the key. */
+    valueRange: TextRange;
+    line: number;
+    /** True when the value continues below the key (a block list, a `|`/`>` block). */
+    block: boolean;
+}
+export interface CaseFrontMatter {
+    data: Record<string, unknown>;
+    entries: FrontMatterEntry[];
+    /** The opening `---` through the closing `---` (without the line break after it). */
+    range: TextRange;
+    /** Offset just after the opening `---` line, where a new key is inserted first. */
+    insertAt: number;
+    /** Why the yaml cannot be read; null when it parses. */
+    problem: string | null;
+}
+/** The front matter of a case document that the tools care about. The case document is the single source of truth. */
+export interface CaseMeta {
+    id: string;
+    /** Suites the case belongs to, e.g. `['smoke', 'regression']`. A case runs in every suite it lists. */
+    suites: string[];
+    /**
+     * Environments in which the case may create or change data of the test accounts (and cleans it up), e.g.
+     * `['staging']`. Empty = the case never writes. In any other environment the case is skipped, not failed.
+     */
+    writes: string[];
+    /** What the case writes; required when `writes` is not empty. Shown to the person who confirms a production run. */
+    writesNote: string | null;
+    /** Environments the case may run in; `null` = all. */
+    envs: string[] | null;
+}
+/** A prose section (`## Goal`, `## Notes`, ...), read-only in the panel: clicking it reveals its line. */
+export interface CaseProse {
+    name: string;
+    body: string;
+    range: TextRange;
+    /** 1-based line of the first character of the body, for the editor offset of the rendered Markdown. */
+    line: number;
+}
+/** One top-level bullet of a list section (`## Expected`, `## Visual checks`), with the question blocks below it. */
+export interface CaseBullet {
+    /** The bullet's text without its marker, wrapped lines joined. */
+    text: string;
+    /** The whole block: the bullet through its nested lines, without trailing blank lines. */
+    range: TextRange;
+    /** The text only: after the marker through the last line of the bullet's own text (nested bullets excluded). */
+    textRange: TextRange;
+    line: number;
+    /** Lines of the `TODO` blocks that hang under this bullet. */
+    questionLines: number[];
+}
+/** One `### T<n>` card of `## Targets`, with the ranges the panel shows next to a visual check. */
+export interface CaseTargetCard {
+    id: string;
+    name: string;
+    /** The `- <Field>: ...` bullets, keyed by lower-case field name (`what`, `where`, `identified by`, `not`, ...). */
+    fields: Record<string, string>;
+    /** The `- Reference <profile>: <path>` bullets, keyed by profile id. */
+    references: Record<string, string>;
+    /** The card holds a `🚫 TODO [blocking]` block: the check that uses it is not generated yet. */
+    blocking: boolean;
+    /** 1-based line of the `### T<n>` heading in the whole file. */
+    line: number;
+    /** The heading line through the last line of the card (without trailing blank lines). */
+    range: TextRange;
+}
+/** The fields every card must have; `pnpm case:check` fails without them. Kept here (pure) for the web panel. */
+export declare const TARGET_REQUIRED_FIELDS: readonly ['what', 'where', 'identified by'];
+export interface CaseStep {
+    /** The number as written in the file (a case written by hand may skip or repeat one). */
+    number: number;
+    /** The sentence without its trailing tags. */
+    text: string;
+    tags: StepTag[];
+    /** The whole block: the step line through its wrapped lines, without its trailing tags. */
+    range: TextRange;
+    /** The sentence only (after `N. ` through the last wrapped line, tags excluded). */
+    textRange: TextRange;
+    /** Where ` [tag]` is inserted when a tag is added (end of the sentence, before trailing blanks). */
+    insertAt: number;
+    /** 1-based line number in the file. */
+    line: number;
+    /** The `- Recipe (...):` lines under the step, in the order written; `/gen-spec` replays them. */
+    recipes: CaseRecipe[];
+    /** The `- Ready when:` lines under the step, in the order written; `/gen-spec` waits for them. */
+    readiness: CaseReadySignal[];
+}
+/**
+ * One `- Ready when: ...` bullet under a step: what proves that the content the step loads is really there. It is a
+ * wait, not a check: the expected behaviour lives in `## Expected`.
+ */
+export interface CaseReadySignal {
+    /** The text after the colon, wrapped lines joined. */
+    text: string;
+    /** 1-based line number in the file. */
+    line: number;
+    /** The bullet through its last continuation line. */
+    range: TextRange;
+    /** The text the panel edits, from the colon to the end of the last continuation line. */
+    textRange: TextRange;
+}
+/**
+ * One `- Recipe (phase): ...` bullet under a step: what a person did for that step during `/explore-case --attended`,
+ * as a general recipe (positions, `[asrun]` names, control labels). It is not test data: the asserted values live in
+ * `## Values`.
+ */
+export interface CaseRecipe {
+    /** The phase label in parentheses, e.g. `start`; null when not written. */
+    what: string | null;
+    /** The text after the colon, wrapped lines joined. */
+    text: string;
+    /** 1-based line number in the file. */
+    line: number;
+    /** The bullet through its last continuation line. */
+    range: TextRange;
+    /** The text the panel edits, from the colon to the end of the last continuation line. */
+    textRange: TextRange;
+}
+export type QuestionKind = 'blocking' | 'non-blocking';
+export interface CaseQuestion {
+    kind: QuestionKind;
+    /** The question itself, without the marker and without the trailing evidence in parentheses. Wrapped lines are joined. */
+    question: string;
+    /** What the page showed, in parentheses at the end of the question; null when there is none. */
+    evidence: string | null;
+    /**
+     * The block the question hangs under: one list item or one paragraph, wrapped lines joined. It stays in the case when
+     * the block is accepted. Null when there is no such text (a heading, a code fence or the start of the file above it).
+     */
+    parent: {
+        text: string;
+        line: number;
+        from: number;
+    } | null;
+    section: string;
+    line: number;
+    indent: number;
+    /** Text written after `Answer:` ('' when empty or when there is no answer line). */
+    answer: string;
+    /** The text after `Answer:` (an empty range at the end of that line when nothing was typed). */
+    answerRange: TextRange;
+    hasAnswerLine: boolean;
+    /** Line number of the `Answer:` line; null when the block has none. */
+    answerLine: number | null;
+    /** Line number of the last line of the block, to check that the answer is the last one. */
+    lastLine: number;
+    /** The TODO line through the last line of its block (the answer and any continuation), without the final line break. */
+    blockRange: TextRange;
+    /**
+     * The question with the text it hangs under: from the first line of `parent` (the TODO line when there is none)
+     * through the last line of its block. The case panel highlights it when its row is clicked.
+     */
+    region: TextRange;
+}
+export type MarkerKind = 'confirm' | 'unseen';
+/** `🔍 to be confirmed by QA` and `👁️ not observed`: markers of what was seen but not checked by a person. */
+export interface CaseMarker {
+    kind: MarkerKind;
+    /** The marker as written, including its emoji. */
+    text: string;
+    range: TextRange;
+    /** The whole line, for display. */
+    sentence: string;
+    section: string;
+    line: number;
+}
+export type CaseValues = Record<string, Record<string, unknown>>;
+export interface CaseValuesBlock {
+    /** False when "## Values" exists but has no complete fenced yaml block (nothing can be edited then). */
+    hasBlock: boolean;
+    /** The yaml text between the fences. */
+    range: TextRange;
+    values: CaseValues;
+    /** Why the block cannot be read or edited; null when it is fine. */
+    problem: string | null;
+    /** Values that are empty or start with TODO, as `profile.key`: `requireValues` refuses them at run time. */
+    placeholders: string[];
+}
+/** One line of the old `## Inputs` section; new cases put the same text in a `- Recipe (...)` line under the step. */
+export interface CaseInput {
+    /** The step number the line belongs to; null for a free note (a bullet with no `Step <n>`). */
+    step: number | null;
+    /** The label in parentheses after the step number, e.g. `start` or `items`; null when not written. */
+    what: string | null;
+    /** The text after the colon (a recipe), or the whole bullet of a note. Wrapped lines are joined. */
+    recipe: string;
+    line: number;
+    /** The bullet through its last continuation line. */
+    range: TextRange;
+    /** The text the panel edits, from the colon (or the bullet marker) to the end of the last continuation line. */
+    recipeRange: TextRange;
+}
+export interface CaseDocument {
+    text: string;
+    frontMatter: CaseFrontMatter | null;
+    sections: CaseSection[];
+    steps: CaseStep[];
+    questions: CaseQuestion[];
+    markers: CaseMarker[];
+    values: CaseValuesBlock | null;
+    targets: CaseTargetCard[];
+    inputs: CaseInput[];
+}
+/**
+ * The body of `## <name>`: exactly the regex every reader used before this module existed
+ * (`lib/values.ts`, `lib/targets.ts`, `scripts/check-cases.ts`), so behaviour does not change.
+ */
+export declare function caseSectionText(text: string, name: string): string;
+export declare function splitLines(text: string): CaseLine[];
+/** Offset just after the line break that starts at `end` (or `end` itself at the end of the file). */
+export declare function endWithBreak(text: string, end: number): number;
+/** Offset just after the line break of `line` (also when the line is the last one, without a break). */
+export declare const afterLine: (text: string, line: CaseLine) => number;
+/** The front matter block: its parsed data plus the range of every key, so the panel can edit one key at a time. */
+export declare function parseCaseFrontMatter(text: string): CaseFrontMatter | null;
+/** A prose section (`## Goal`, `## Notes`): the panel renders it read-only and reveals a line on click. */
+export declare function parseProse(text: string, name: string): CaseProse | null;
+/** The top-level bullets of a list section, with the blocks (a wrapped text, a TODO block) that belong to each. */
+export declare function parseBullets(text: string, name: string): CaseBullet[];
+/** The `### T<n>` cards of `## Targets`. Pure, so the web panel can show a card name next to a visual check. */
+export declare function parseTargetCards(text: string): CaseTargetCard[];
+/** Parses and validates the front matter. Throws an Error that starts with `label` and says what to fix. */
+export declare function validateCaseMeta(id: string, data: Record<string, unknown>, knownEnvs: string[], label?: string): CaseMeta;
+/** The front matter problems a form can show without throwing; empty when it is valid. */
+export declare function caseMetaProblems(id: string, data: Record<string, unknown>, knownEnvs: string[], label?: string): string[];
+export declare function parseCaseDocument(text: string): CaseDocument;
+/** Applies replacements that do not overlap. Positions refer to `text`, the text they were parsed from. */
+export declare function patchText(text: string, edits: TextEdit[]): string;
+/** Adds or removes one `[writes]` / `[input]` / `[email]` tag at the end of a step. */
+export declare function setStepTag(text: string, stepNumber: number, tag: StepTag, on: boolean): string;
+/** Writes an answer after `Answer:`; an empty answer clears the slot and keeps the line. */
+export declare function setQuestionAnswer(text: string, question: CaseQuestion, answer: string): string;
+/** Accepts the suggestion: deletes the whole question block, the answer line included. */
+export declare function acceptQuestion(text: string, question: CaseQuestion): string;
+/**
+ * Removes a `🔍 to be confirmed by QA` / `👁️ not observed` marker. When the marker is the only content of its
+ * parentheses, the parentheses go too (`(👁️ not observed)`); otherwise the marker and one separator leave
+ * `(observed, 🔍 to be confirmed by QA)` as `(observed)`.
+ */
+export declare function removeMarker(text: string, marker: CaseMarker): string;
+/** Sets one value of one profile; `null` removes it (an empty cell in the panel means "not set here"). */
+export declare function setCaseValue(text: string, profile: string, key: string, value: string | null): string;
+/** Adds a key to the `default` values of the case. */
+export declare function addCaseValueKey(text: string, key: string, value: string): string;
+/** Writes the text of one `## Inputs` line (a recipe or a note); an empty text deletes the line. */
+export declare function setInputText(text: string, input: CaseInput, value: string): string;
+/** Deletes one `## Inputs` bullet (a recipe line or a note), its wrapped lines included. */
+export declare function removeInputLine(text: string, input: CaseInput): string;
+/** Writes the text of one recipe line under a step; an empty text deletes the line. */
+export declare function setRecipeText(text: string, recipe: CaseRecipe, value: string): string;
+/** Deletes one recipe line under a step, its wrapped lines included. */
+export declare function removeRecipe(text: string, recipe: CaseRecipe): string;
+/** Writes the text of one `- Ready when:` line under a step; an empty text deletes the line. */
+export declare function setStepReady(text: string, signal: CaseReadySignal, value: string): string;
+/** Deletes one `- Ready when:` line under a step, its wrapped lines included. */
+export declare function removeStepReady(text: string, signal: CaseReadySignal): string;
+/**
+ * Adds a `- Ready when: ...` line under a step, right under the step sentence and above its recipes: readiness is read
+ * first, then what a person did. A second line goes under the first.
+ */
+export declare function addStepReady(text: string, stepNumber: number, value: string): string;
+/**
+ * Adds a `- Recipe (phase): ...` line under a step. It goes after the step's last recipe, or after its last readiness
+ * line, or directly under the step sentence, so a step keeps its readiness and recipes together and no separate input
+ * section is needed.
+ */
+export declare function addStepRecipe(text: string, stepNumber: number, what: string | null, value: string): string;
+/** Sets one front matter key (a scalar or a list); `null` or an empty list removes it. */
+export declare function setFrontMatterValue(text: string, key: string, value: string | string[] | null): string;
+/** Removes one front matter key and its lines. */
+export declare function removeFrontMatterKey(text: string, key: string): string;
+/** Sets the sentence of a step (a multi-line value keeps its wrapping, indented under the number). */
+export declare function setStepText(text: string, step: CaseStep, value: string): string;
+/** Sets the text of one bullet (`## Expected`, `## Visual checks`); a nested TODO block is not touched. */
+export declare function setBulletText(text: string, bullet: CaseBullet, value: string): string;
+/** Appends a bullet to a list section. Returns the text unchanged when the section does not exist. */
+export declare function addBullet(text: string, name: string, value: string): string;
+/** Deletes one bullet and everything under it (a nested question block included). */
+export declare function removeBullet(text: string, bullet: CaseBullet): string;
+/** Moves one bullet block (and everything under it) to another position, with `arrayMove` semantics. */
+export declare function moveBullet(text: string, name: string, from: number, to: number): string;