@mnaoumov/obsidian-dev-toolkit 0.0.0 → 1.0.0

package/dist/lib/cjs/demo-vault-buttons.d.cts

@@ -0,0 +1,259 @@
+/// <reference path="./index.d.cts" />
+/**
+ * @file
+ *
+ * A vitest suite that opens every note of a plugin's in-repo `demo-vault/`, clicks each `code-button`
+ * in it against a real Obsidian, and fails on any button that errors or never reports a result.
+ *
+ * A demo vault's buttons are the one part of it no other gate can check. `lint:md` reads the markdown,
+ * the coverage suite ({@link ./demo-vault-coverage.ts | `registerDemoVaultCoverageSuite`}) checks the
+ * authoring conventions, and neither executes anything — a button whose `require('/demoSetup.ts')` path
+ * is wrong, or that calls an API that has since changed shape, fails at click time and nowhere else.
+ *
+ * The companion half — seeding the temp vault with the demo-vault tree, its `.obsidian` config, and the
+ * CodeScript Toolkit binary that turns ```` ```code-button ```` fences into buttons — is
+ * `buildDemoVaultPopulate` in `obsidian-integration-testing`; hand its result to the project's
+ * `globalSetup` and name CodeScript Toolkit in `enableCommunityPlugins`.
+ */
+/**
+ * CodeScript Toolkit's manifest id. It is still the plugin's original `fix-require-modules` id, which
+ * no longer matches its name — the id is published, so it cannot be changed.
+ */
+export declare const CODE_SCRIPT_TOOLKIT_PLUGIN_ID = "fix-require-modules";
+/**
+ * The waiting budgets a single button click is allowed.
+ *
+ * Both are spent inside ONE transport call, so it is their SUM that
+ * {@link assertClickBudgetsFitTransportCap} bounds.
+ */
+export interface ClickButtonTimeouts {
+    /**
+     * How long to wait for the clicked button to report a result.
+     */
+    readonly buttonResultTimeoutInMilliseconds: number;
+    /**
+     * How long to wait for the button itself to mount.
+     */
+    readonly settleTimeoutInMilliseconds: number;
+}
+/**
+ * The outcome of clicking one button.
+ */
+export interface DemoVaultButtonResult {
+    /**
+     * The button's caption, as rendered.
+     */
+    readonly caption: string;
+    /**
+     * The result line CodeScript Toolkit printed under the button, truncated.
+     */
+    readonly output: string;
+    /**
+     * Whether the button reported success, reported an error, or never reported at all.
+     */
+    readonly status: 'error' | 'ok' | 'timeout' | 'unknown';
+}
+/**
+ * One demo-vault note and how many buttons its source declares.
+ */
+export interface DemoVaultNote {
+    /**
+     * How many buttons the note's source renders, as counted by {@link countRenderedButtons}.
+     */
+    readonly buttonCount: number;
+    /**
+     * The captions of those buttons, in source order, as read by {@link listRenderedButtonCaptions}.
+     */
+    readonly captions: readonly string[];
+    /**
+     * The note's file name, relative to the demo vault root.
+     */
+    readonly name: string;
+}
+/**
+ * A button that is EXPECTED not to report success, so the suite does not fail on it.
+ */
+export interface ExpectedNonOkButton {
+    /**
+     * A substring of the button's rendered caption.
+     */
+    readonly captionIncludes: string;
+    /**
+     * The note holding the button, relative to the demo vault root.
+     */
+    readonly note: string;
+    /**
+     * The status the button is expected to end in. Any other status still fails, so an error demo that
+     * starts timing out instead is reported rather than waved through.
+     */
+    readonly status: Exclude<DemoVaultButtonResult['status'], 'ok'>;
+}
+/**
+ * The options for {@link registerDemoVaultButtonSuite}.
+ */
+export interface RegisterDemoVaultButtonSuiteOptions {
+    /**
+     * How long, in milliseconds, to wait for a clicked button to report a result.
+     *
+     * Bounded by the same sum as {@link RegisterDemoVaultButtonSuiteOptions.settleTimeoutInMilliseconds},
+     * and refused by the same throw at registration.
+     *
+     * @default `10000`
+     */
+    readonly buttonResultTimeoutInMilliseconds?: number;
+    /**
+     * Folders to skip whole, matched against both the folder name and its path relative to the demo vault
+     * root — for a group whose notes cannot run unattended, such as ones that first install a third-party
+     * plugin from the community store.
+     *
+     * @default `[]`
+     */
+    readonly excludedFolders?: readonly string[];
+    /**
+     * Note file names (relative to the demo vault root) to skip.
+     *
+     * @default `['README.md']`
+     */
+    readonly excludedNotes?: readonly string[];
+    /**
+     * Buttons that legitimately do not report success: an error demo, or a button that turns system
+     * messages off and so never prints the result line the suite classifies.
+     *
+     * @default `[]`
+     */
+    readonly expectedNonOkButtons?: readonly ExpectedNonOkButton[];
+    /**
+     * The repository root holding `demo-vault/`.
+     *
+     * @default the resolved repo root, falling back to `process.cwd()`.
+     */
+    readonly rootFolder?: string;
+    /**
+     * How long, in milliseconds, to wait for a note's preview and its buttons to mount.
+     *
+     * Together with `buttonResultTimeoutInMilliseconds` this must stay under the transport's ~30 s script
+     * timeout: one button click spends both inside a SINGLE evaluation, so a sum at or over the cap cannot
+     * be honoured and turns a real timeout into a bare `script timeout` naming only the transport.
+     * {@link registerDemoVaultButtonSuite} throws on such a pair rather than registering it.
+     *
+     * @default `12000`
+     */
+    readonly settleTimeoutInMilliseconds?: number;
+    /**
+     * Whether to dismiss any open modal while waiting for a clicked button's result, and again once it is
+     * classified.
+     *
+     * A button that `await`s an `alert` / `confirm` / `prompt` cannot report a result until somebody closes
+     * the dialog, so without this it ends as `timeout` — and the dialog it left open then sits over every
+     * later button in the run. Off by default, so no suite changes behavior unasked.
+     *
+     * @default `false`
+     */
+    readonly shouldDismissModals?: boolean;
+}
+/**
+ * Refuses a settle/result budget pair that a single transport call could never honour.
+ *
+ * `clickButton` waits for the button to mount and then for its result INSIDE ONE `evalInObsidian`
+ * closure, so the transport's script timeout bounds their sum rather than either one alone — and
+ * `RegisterDemoVaultButtonSuiteOptions` lets a consumer raise each independently, with nothing summing
+ * them. Raising `settleTimeoutInMilliseconds` to 20 000 for one slow note is an ordinary thing to do and
+ * silently puts the pair at the cap.
+ *
+ * Throwing here, at suite registration, is the whole value: the failure it replaces is a
+ * `WebDriverError: script timeout` raised mid-run against whichever button happened to be slowest,
+ * naming the transport and neither budget.
+ *
+ * @param timeouts - The {@link ClickButtonTimeouts} to bound.
+ */
+export declare function assertClickBudgetsFitTransportCap(timeouts: ClickButtonTimeouts): void;
+/**
+ * Counts the buttons a note's source will actually render.
+ *
+ * Three kinds of ` ```code-button ` fence render no clickable button, and a vault that DOCUMENTS code
+ * buttons is full of the first two:
+ *
+ * - A fence nested inside a longer or different fence (a ```` ````markdown ```` or `~~~` block) is a
+ *   markdown SAMPLE shown to the reader; the renderer never sees it as a block.
+ * - An `isRaw: true` fence renders its output directly and no button element at all.
+ * - A fence whose info string carries anything after `code-button` uses the legacy argument syntax, which
+ *   renders an error banner asking to update the config rather than the button.
+ *
+ * Counting any of them makes the suite's shortfall assertion unsatisfiable — it demands more buttons
+ * than the note can ever render — and an assertion that cannot pass gates nothing.
+ *
+ * The scan follows CommonMark's fence rules: a fence closes only on a run of the SAME character at least
+ * as long as the opener, with no info string, and one left open runs to the end of the document, where it
+ * still renders.
+ *
+ * @param source - The note's markdown.
+ * @returns How many buttons it renders.
+ */
+export declare function countRenderedButtons(source: string): number;
+/**
+ * Finds the captions declared by more than one button.
+ *
+ * The suite addresses a button by its caption — it collects the captions that mounted and clicks the
+ * button carrying each one — so two buttons sharing a caption collapse into one: the second is never
+ * clicked, and the note reads as declaring a button that never rendered.
+ *
+ * @param captions - A note's button captions.
+ * @returns Each caption occurring more than once, listed once, in order of first repeat.
+ */
+export declare function findDuplicateCaptions(captions: readonly string[]): string[];
+/**
+ * Builds the assertion message for a note's failing buttons.
+ *
+ * The captured output is included because a button's failure is a runtime one — the stack CodeScript
+ * Toolkit prints under it is the only diagnosis there is.
+ *
+ * @param noteName - The note the buttons belong to.
+ * @param failures - The failing buttons.
+ * @returns The message.
+ */
+export declare function formatFailures(noteName: string, failures: readonly DemoVaultButtonResult[]): string;
+/**
+ * Lists the captions of the buttons a note's source will actually render, in source order.
+ *
+ * Which fences render a button is decided exactly as {@link countRenderedButtons} describes. A caption is
+ * read from the fence's own config block; a fence naming none takes CodeScript Toolkit's default,
+ * `(no caption)`, which is what its button then shows.
+ *
+ * @param source - The note's markdown.
+ * @returns The captions, one per rendered button.
+ */
+export declare function listRenderedButtonCaptions(source: string): string[];
+/**
+ * Picks the buttons that failed and were not expected to.
+ *
+ * @param noteName - The note the results belong to, relative to the demo vault root.
+ * @param results - Every button's result in that note.
+ * @param expectedNonOkButtons - The buttons allowed to end in a given non-`ok` status.
+ * @returns The results that are not `ok` and match no {@link ExpectedNonOkButton}.
+ */
+export declare function selectUnexpectedFailures(noteName: string, results: readonly DemoVaultButtonResult[], expectedNonOkButtons: readonly ExpectedNonOkButton[]): DemoVaultButtonResult[];
+/**
+ * Lists the demo vault's notes that declare at least one `code-button`, walking group folders too.
+ *
+ * A vault big enough to need grouping puts its walkthroughs in numbered folders — and a root-only walk
+ * finds NONE of them, which is worse than it sounds: a vault whose notes are all grouped reports zero
+ * notes, and one that is partly grouped silently gates only the ungrouped part. Fixture and asset
+ * folders are still skipped, so what is walked is walkthroughs and nothing else.
+ *
+ * @param demoVaultPath - The demo vault root.
+ * @param excludedNotes - Note names to skip, matched against both the file name and the path relative
+ * to the vault root.
+ * @param excludedFolders - Folders to skip whole, matched the same way.
+ * @returns The notes, sorted by path.
+ */
+export declare function listNotesWithButtons(demoVaultPath: string, excludedNotes: ReadonlySet<string>, excludedFolders?: ReadonlySet<string>): DemoVaultNote[];
+/**
+ * Registers a vitest suite that clicks every `code-button` in the repo's demo vault.
+ *
+ * One `it` per note, and one `evalInObsidian` per button: a single closure runs as one CDP
+ * `Runtime.evaluate`, which the harness caps at 30 s, so a note with a dozen buttons would otherwise
+ * time out as a whole rather than reporting which button failed.
+ *
+ * @param options - The {@link RegisterDemoVaultButtonSuiteOptions}.
+ */
+export declare function registerDemoVaultButtonSuite(options?: RegisterDemoVaultButtonSuiteOptions): void;