@mnaoumov/obsidian-dev-toolkit 0.0.0 → 1.0.0

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

@@ -0,0 +1,533 @@
+/// <reference path="./index.d.cts" />
+/**
+ * @file
+ *
+ * Static coverage/freshness checks that keep a plugin's in-repo `demo-vault/` in sync with its public surface.
+ *
+ * A plugin can ship a curated demo vault at `demo-vault/` in its repo root. These helpers reflect the real
+ * public API/config/docs straight from source and assert — WITHOUT launching Obsidian — that every feature is
+ * demonstrated in the notes and that the notes reference no API member that no longer exists (rename drift).
+ * The runtime behavior of the plugin is covered by its other integration tests, not by the demo vault; the
+ * vault is a learning resource, and these checks only guard that it stays truthful.
+ *
+ * They also guard the vault's own `.obsidian/app.json`: the settings listed in
+ * {@link DEMO_VAULT_APP_JSON_SETTINGS} belong to `obsidian-dev-utils`, which writes them into the archived
+ * vault at release time, so a vault that commits any of them is keeping a second copy nothing reconciles.
+ *
+ * They also enforce the demo-vault AUTHORING convention — every note opens with an `# H1` and a plain
+ * prose paragraph, every note is reachable from the start note, and no note uses a `[[wikilink]]` or a
+ * `[Docs](…)` line. These checks are unconditional: the demo vault is the published documentation, read
+ * in Obsidian AND on GitHub (where a wikilink does not render), so a note that breaks the convention is
+ * broken for real readers. `authoring` only tunes them (which note is the start, which notes sit outside
+ * the learning path); it cannot switch them off.
+ *
+ * Only `rootFolder` is required, so a plugin with no settings and no public API to reflect registers the
+ * suite with that alone and still gets every authoring check — the checks have nothing to do with what the
+ * plugin exposes. Each reflection spec (`configInterfaces`, `interfaces`, `nonTrivialGuard`) adds the checks
+ * it describes when supplied. The vault is guarded against being empty either way: with no notes to read,
+ * every authoring check would pass by having nothing to look at.
+ *
+ * The one exception is a note whose SUBJECT is the wikilink — an embed spelling the reader is being taught
+ * to type, a frontmatter property value that exists to contrast with a Markdown link, a fixture that must
+ * keep the wikilink a command is supposed to leave alone, a link the reader clicks while it still resolves
+ * to nothing. Such a note says so itself, stating why, in one of two forms modelled on ESLint's.
+ *
+ * Per line or per region, written as an HTML comment so it is invisible in Obsidian AND on GitHub — the
+ * spelling these vaults already use for `markdownlint-disable-next-line`:
+ *
+ * ```markdown
+ * <!-- obsidian-dev-utils-disable-next-line demo-vault-validation/no-wikilinks -- Clicking a link to a note that does not exist yet IS the feature. -->
+ * 2. Click this link: [[Projects/Fresh idea]].
+ *
+ * <!-- obsidian-dev-utils-disable demo-vault-validation/no-wikilinks -- The wikilink embed is the syntax this note teaches. -->
+ * ![[basic.html|400]]
+ * <!-- obsidian-dev-utils-enable demo-vault-validation/no-wikilinks -->
+ * ```
+ *
+ * Per note, in the note's own frontmatter — the only form that can reach a wikilink INSIDE frontmatter,
+ * where a comment cannot go:
+ *
+ * ```yaml
+ * ---
+ * obsidian-dev-utils:
+ *   demo-vault-validation:
+ *     allow-wikilinks: The `wikilink` property value is the contrast this note is built around.
+ * ---
+ * ```
+ *
+ * Either way the declaration travels with the note rather than sitting in a list somewhere else, it carries
+ * its justification, and it exempts only the WIKILINK check — the H1, prose, reachability and `[Docs]`
+ * checks still apply. A declaration with no reason, one covering no wikilink, a region never enabled again,
+ * or a misspelled directive all fail: an exemption nobody can justify, that nothing needs any more, or that
+ * silently does nothing is worse than no exemption at all.
+ *
+ * Two layers are exposed:
+ * - {@link DemoVaultCoverageChecker} — a framework-agnostic core that reads the corpus, parses interface /
+ *   class / enum members and exported functions, and returns diagnostic arrays (what is undemonstrated / stale
+ *   / unlinked / off-convention).
+ * - {@link registerDemoVaultCoverageSuite} — a thin wrapper that registers a `vitest` suite over the core, so
+ *   a plugin's `demo-vault.no-app.integration.test.ts` is a single declarative call.
+ */
+/**
+ * Tunes the always-on authoring checks. It cannot disable them — see the file overview.
+ */
+export interface DemoVaultAuthoringSpec {
+    /**
+     * The notes (paths relative to the demo vault) that sit outside the learning path and are therefore
+     * exempt from every authoring check. Defaults to the vault's own `README.md`, which addresses someone
+     * browsing the repo on GitHub rather than a reader working through the vault.
+     */
+    readonly excludedNotes?: string[];
+    /**
+     * The note (path relative to the demo vault) every other note must be reachable from. Defaults to
+     * `00 Start.md`.
+     */
+    readonly startNote?: string;
+}
+/**
+ * Reflects a config interface whose options are demonstrated by their bare name.
+ */
+export interface DemoVaultConfigInterfaceCoverageSpec {
+    /**
+     * The name of the `export interface`, `export class`, or `export enum` whose properties are the config
+     * options.
+     */
+    readonly interfaceName: string;
+    /**
+     * The source file path (relative to the repo root) that declares the interface, class, or enum.
+     */
+    readonly sourcePath: string;
+}
+/**
+ * The parameters for the {@link DemoVaultCoverageChecker} constructor.
+ */
+export interface DemoVaultCoverageCheckerConstructorParams {
+    /**
+     * The notes (paths relative to the demo vault) exempt from the authoring checks. Defaults to the
+     * vault's own `README.md`.
+     */
+    readonly excludedNotes?: string[];
+    /**
+     * The absolute path of the plugin repo root — the folder containing `demo-vault/` and the source being
+     * reflected. Callers typically pass `getRootFolder() ?? process.cwd()`.
+     */
+    readonly rootFolder: string;
+}
+/**
+ * The parameters for {@link DemoVaultCoverageChecker.findStaleReferences}.
+ */
+export interface DemoVaultCoverageCheckerFindStaleReferencesParams {
+    /**
+     * The receiver whose `` `${receiver}.<member>` `` references are scanned for in the demo corpus.
+     */
+    readonly receiver: string;
+    /**
+     * The members that currently exist on the receiver; any referenced member not in this set is stale.
+     */
+    readonly validMembers: string[];
+}
+/**
+ * The parameters for {@link DemoVaultCoverageChecker.findUndemonstratedMembers}.
+ */
+export interface DemoVaultCoverageCheckerFindUndemonstratedMembersParams {
+    /**
+     * The member names that must each appear in the demo corpus.
+     */
+    readonly members: string[];
+    /**
+     * When set, a member is demonstrated only if `` `${receiver}.${member}` `` appears (e.g. a context object's
+     * methods); when absent, the bare member name is looked up (e.g. a config option).
+     */
+    readonly receiver?: string;
+}
+/**
+ * The parameters for {@link DemoVaultCoverageChecker.findUnlinkedFeatureDocs}.
+ */
+export interface DemoVaultCoverageCheckerFindUnlinkedFeatureDocsParams {
+    /**
+     * The docs folder (relative to the repo root) whose top-level `*.md` files are the feature docs.
+     */
+    readonly docsFolder: string;
+    /**
+     * The doc basenames (without `.md`) that are NOT per-feature pages and so need no linking demo note.
+     */
+    readonly nonFeatureDocs: string[];
+}
+/**
+ * The parameters for {@link DemoVaultCoverageChecker.findUnreachableNotes}.
+ */
+export interface DemoVaultCoverageCheckerFindUnreachableNotesParams {
+    /**
+     * The note (path relative to the demo vault) the walk starts from, e.g. `00 Start.md`.
+     */
+    readonly startNote: string;
+}
+/**
+ * The parameters for {@link DemoVaultCoverageChecker.getExportedFunctionNames}.
+ */
+export interface DemoVaultCoverageCheckerGetExportedFunctionNamesParams {
+    /**
+     * The source file path (relative to the repo root) whose `export function`s are parsed.
+     */
+    readonly sourcePath: string;
+}
+/**
+ * The parameters for {@link DemoVaultCoverageChecker.getInterfaceMembers}.
+ */
+export interface DemoVaultCoverageCheckerGetInterfaceMembersParams {
+    /**
+     * The name of the `export interface`, `export class`, or `export enum` to parse.
+     */
+    readonly interfaceName: string;
+    /**
+     * The source file path (relative to the repo root) that declares the interface, class, or enum.
+     */
+    readonly sourcePath: string;
+}
+/**
+ * Configures the feature-doc linking check.
+ */
+export interface DemoVaultDocsCoverageSpec {
+    /**
+     * The docs folder (relative to the repo root) whose top-level `*.md` files are the feature docs.
+     */
+    readonly folder: string;
+    /**
+     * The doc basenames (without `.md`) that are NOT per-feature pages and so need no linking demo note.
+     */
+    readonly nonFeatureDocs: string[];
+}
+/**
+ * Reflects a module's exported functions, each demonstrated by its bare name in the demo corpus.
+ */
+export interface DemoVaultFunctionsCoverageSpec {
+    /**
+     * The source file path (relative to the repo root) whose `export function`s must each be demonstrated.
+     */
+    readonly sourcePath: string;
+}
+/**
+ * Reflects a single interface's members and demonstrates them via `` `${receiver}.<member>` `` references.
+ */
+export interface DemoVaultInterfaceCoverageSpec {
+    /**
+     * The name of the `export interface`, `export class`, or `export enum` to reflect.
+     */
+    readonly interfaceName: string;
+    /**
+     * Whether the demonstrated members are the reflected type's methods or its properties (enum members count as
+     * properties).
+     */
+    readonly kind: DemoVaultInterfaceMemberKind;
+    /**
+     * The identifier the notes call the members on (e.g. `codeButtonContext`).
+     */
+    readonly receiver: string;
+    /**
+     * The source file path (relative to the repo root) that declares the interface, class, or enum.
+     */
+    readonly sourcePath: string;
+}
+/**
+ * Whether an interface's demonstrated members are its methods or its properties.
+ */
+export type DemoVaultInterfaceMemberKind = 'methods' | 'properties';
+/**
+ * Configures the guard that the reflected surface is non-trivial (protects against a parsing regression
+ * silently emptying every other check).
+ */
+export interface DemoVaultNonTrivialGuardSpec {
+    /**
+     * A demo note (path relative to the demo vault) that must be present.
+     */
+    readonly expectDemoNote: string;
+    /**
+     * A member that must be reflected from {@link DemoVaultNonTrivialGuardSpec.interfaceName}.
+     */
+    readonly expectMember: string;
+    /**
+     * The name of the `export interface`, `export class`, or `export enum` whose members are re-parsed for the
+     * guard.
+     */
+    readonly interfaceName: string;
+    /**
+     * The source file path (relative to the repo root) that declares the interface, class, or enum.
+     */
+    readonly sourcePath: string;
+}
+/**
+ * A single demo note, as read from the demo vault.
+ */
+export interface DemoVaultNote {
+    /**
+     * The note's raw Markdown content.
+     */
+    readonly content: string;
+    /**
+     * The note's path relative to the demo vault folder, e.g. `00 Start.md`.
+     */
+    readonly relativePath: string;
+}
+/**
+ * The parsed members of a source interface, class, or enum.
+ */
+export interface InterfaceMembers {
+    /**
+     * Every member — {@link InterfaceMembers.methods} followed by {@link InterfaceMembers.properties}.
+     */
+    readonly all: string[];
+    /**
+     * The method members (declared as `name(...)`).
+     */
+    readonly methods: string[];
+    /**
+     * The property members (declared as `name?: ...`).
+     */
+    readonly properties: string[];
+}
+/**
+ * A note line paired with the line number it came from, so a check that skips fenced blocks can still
+ * report — and an inline directive can still name — the line as the reader sees it.
+ */
+export interface NoteLine {
+    /**
+     * The zero-based line number within the note.
+     */
+    readonly index: number;
+    /**
+     * The line's raw text.
+     */
+    readonly line: string;
+}
+/**
+ * A `disable` region that has been opened and not yet enabled again.
+ */
+export interface OpenWikilinkDirectiveRegion {
+    /**
+     * Whether the region has covered a wikilink, which is what stops it being reported as pointless.
+     */
+    isUsed: boolean;
+    /**
+     * The line the region was opened on.
+     */
+    readonly lineIndex: number;
+}
+/**
+ * The parameters for {@link registerDemoVaultCoverageSuite}.
+ */
+export interface RegisterDemoVaultCoverageSuiteParams {
+    /**
+     * Tunes the always-on authoring checks, or `undefined` to take their defaults. It cannot disable them.
+     */
+    readonly authoring?: DemoVaultAuthoringSpec;
+    /**
+     * The config interfaces whose options must each be demonstrated by their bare name, or `undefined` when the
+     * plugin has no settings.
+     */
+    readonly configInterfaces?: DemoVaultConfigInterfaceCoverageSpec[];
+    /**
+     * The feature-doc linking check, or `undefined` when the plugin ships no `docs/` folder.
+     */
+    readonly docs?: DemoVaultDocsCoverageSpec;
+    /**
+     * The modules whose `export function`s must each be demonstrated by their bare name, or `undefined` when the
+     * plugin exposes no such module to check.
+     */
+    readonly functionModules?: DemoVaultFunctionsCoverageSpec[];
+    /**
+     * The interfaces whose members must each be demonstrated (and referenced without drift), or `undefined` when
+     * the plugin exposes no public API surface to reflect.
+     */
+    readonly interfaces?: DemoVaultInterfaceCoverageSpec[];
+    /**
+     * The guard that keeps the reflected surface non-trivial, or `undefined` when there is no reflected surface
+     * to guard. The vault is checked for being non-empty either way.
+     */
+    readonly nonTrivialGuard?: DemoVaultNonTrivialGuardSpec;
+    /**
+     * The absolute path of the plugin repo root. Callers typically pass `getRootFolder() ?? process.cwd()`.
+     */
+    readonly rootFolder: string;
+}
+/**
+ * What a note's inline `obsidian-dev-utils-disable…` directives allow, and what is wrong with them.
+ */
+export interface WikilinkDirectiveScan {
+    /**
+     * The zero-based line numbers a directive allows a wikilink on.
+     */
+    readonly allowedLineIndexes: ReadonlySet<number>;
+    /**
+     * The directive mistakes found, each phrased for a failing assertion.
+     */
+    readonly problems: string[];
+}
+/**
+ * The running state of a directive scan, threaded through the per-line helpers.
+ */
+export interface WikilinkDirectiveScanState {
+    /**
+     * The lines a directive has allowed a wikilink on so far.
+     */
+    readonly allowedLineIndexes: Set<number>;
+    /**
+     * The region currently open, and whether it has covered a wikilink yet.
+     */
+    openRegion: null | OpenWikilinkDirectiveRegion;
+    /**
+     * The line a `disable-next-line` was read on, while it still waits for the line it covers.
+     */
+    pendingNextLineIndex: null | number;
+    /**
+     * The directive mistakes found so far.
+     */
+    readonly problems: string[];
+    /**
+     * The lines of the note that carry a wikilink.
+     */
+    readonly wikilinkLineIndexes: ReadonlySet<number>;
+}
+/**
+ * Reflects a plugin's public surface from source and checks its in-repo `demo-vault/` stays in sync with it.
+ *
+ * Every method is a pure query over files under the repo root (the demo corpus is read once and cached), so
+ * the checker is trivially unit-testable against a fixture repo and carries no test-framework dependency.
+ */
+export declare class DemoVaultCoverageChecker {
+    private cachedCorpus;
+    private cachedNotes;
+    private readonly demoVaultFolder;
+    private readonly excludedNotes;
+    private readonly rootFolder;
+    /**
+     * Creates a checker rooted at a plugin repo.
+     *
+     * @param params - The parameters for the constructor.
+     */
+    constructor(params: DemoVaultCoverageCheckerConstructorParams);
+    /**
+     * Collects the demo notes as paths relative to the demo vault folder (for a non-trivial-surface guard).
+     *
+     * @returns The relative paths of every `*.md` note in the demo vault.
+     */
+    collectDemoNoteRelativePaths(): string[];
+    /**
+     * Reads and caches every demo note individually — the per-note view the authoring checks work on, as
+     * opposed to the concatenated {@link DemoVaultCoverageChecker.readCorpus}.
+     *
+     * @returns Every `*.md` note in the demo vault, excluded ones included.
+     */
+    collectNotes(): DemoVaultNote[];
+    /**
+     * Finds the `.obsidian/app.json` settings the vault commits that `obsidian-dev-utils` owns and writes
+     * into the archived vault itself. A committed one is a second copy of a setting nothing reconciles, and
+     * it is the copy that goes stale — so the convention is that the vault commits none of them.
+     *
+     * @returns The names of the owned settings the committed `app.json` sets. A vault that commits no
+     * `app.json` at all is fine, and yields none.
+     */
+    findCommittedAppJsonSettings(): string[];
+    /**
+     * Finds notes carrying a `[Docs](…)` link line. The note IS the documentation, so a line pointing
+     * elsewhere for the real explanation is the shape this convention exists to remove.
+     *
+     * @returns The relative paths of the offending notes.
+     */
+    findNotesWithDocsLinks(): string[];
+    /**
+     * Finds notes that do not open with an `# H1` (frontmatter aside).
+     *
+     * @returns The relative paths of the offending notes.
+     */
+    findNotesWithoutH1(): string[];
+    /**
+     * Finds notes with no prose paragraph before their first code fence — the 1-3 sentences saying what the
+     * feature does and why a reader would want it, without which the note is a button with no lesson.
+     *
+     * @returns The relative paths of the offending notes.
+     */
+    findNotesWithoutIntroProse(): string[];
+    /**
+     * Finds notes whose wikilink allowance is not doing any work — declared without a reason, or on a note
+     * that carries no wikilink at all. Both are drift: an exemption nobody can justify, and one nothing needs
+     * any more, which would go on hiding the next wikilink somebody adds by accident.
+     *
+     * @returns The relative paths of the offending notes.
+     */
+    findNotesWithUnjustifiedWikilinkAllowance(): string[];
+    /**
+     * Finds notes using an Obsidian `[[wikilink]]` outside a code fence. The demo vault is also read on
+     * GitHub, where a wikilink renders as literal brackets and leads nowhere. A wikilink shown INSIDE a
+     * fence is sample text, not navigation, so fenced blocks are skipped, as is a note that declares in its
+     * frontmatter why its wikilinks are the point — see the file overview.
+     *
+     * @returns The relative paths of the offending notes.
+     */
+    findNotesWithWikilinks(): string[];
+    /**
+     * Finds members that the demo notes reference on a receiver but that no longer exist on it (rename drift).
+     *
+     * @param params - The parameters for the lookup.
+     * @returns The distinct stale member names referenced in the demo corpus.
+     */
+    findStaleReferences(params: DemoVaultCoverageCheckerFindStaleReferencesParams): string[];
+    /**
+     * Finds members that are not demonstrated anywhere in the demo corpus.
+     *
+     * @param params - The parameters for the lookup.
+     * @returns The member names with no demonstration.
+     */
+    findUndemonstratedMembers(params: DemoVaultCoverageCheckerFindUndemonstratedMembersParams): string[];
+    /**
+     * Finds feature docs that no demo note links to.
+     *
+     * @param params - The parameters for the lookup.
+     * @returns The feature-doc basenames (without `.md`) not linked from any demo note.
+     */
+    findUnlinkedFeatureDocs(params: DemoVaultCoverageCheckerFindUnlinkedFeatureDocsParams): string[];
+    /**
+     * Finds notes that cannot be reached from the start note by following Markdown links between notes.
+     *
+     * The walk starts at {@link DemoVaultCoverageCheckerFindUnreachableNotesParams.startNote} and follows
+     * every `[Text](<./NN Name.md>)` link outside a code fence, transitively. A note nothing links to is
+     * one a reader can only find by browsing the file list — which is exactly what the grouped index in the
+     * start note is meant to replace. When the start note itself is missing, EVERY note is unreachable,
+     * because there is nowhere to start from.
+     *
+     * @param params - The parameters for the walk.
+     * @returns The relative paths of the unreachable notes.
+     */
+    findUnreachableNotes(params: DemoVaultCoverageCheckerFindUnreachableNotesParams): string[];
+    /**
+     * Parses the names of the `export function`s (including `async` and generator declarations) in a source file.
+     *
+     * @param params - The parameters for the lookup.
+     * @returns The exported function names in source order.
+     */
+    getExportedFunctionNames(params: DemoVaultCoverageCheckerGetExportedFunctionNamesParams): string[];
+    /**
+     * Parses the members of an `export interface`, `export class`, or `export enum` declared in a source file.
+     *
+     * @param params - The parameters for the lookup.
+     * @returns The parsed {@link InterfaceMembers}.
+     * @throws When the interface, class, or enum cannot be found in the source file.
+     */
+    getInterfaceMembers(params: DemoVaultCoverageCheckerGetInterfaceMembersParams): InterfaceMembers;
+    /**
+     * Reads and caches the demo corpus — every `*.md` note in the demo vault joined into one string.
+     *
+     * @returns The concatenated demo-note contents.
+     */
+    readCorpus(): string;
+    private collectCheckableNotes;
+    private collectMarkdownFiles;
+}
+/**
+ * Registers a `vitest` suite that keeps a plugin's in-repo `demo-vault/` in sync with its public surface.
+ *
+ * Call it once from a plugin's `demo-vault.no-app.integration.test.ts`; it registers one test per check,
+ * delegating to {@link DemoVaultCoverageChecker}.
+ *
+ * @param params - The declarative coverage specification.
+ */
+export declare function registerDemoVaultCoverageSuite(params: RegisterDemoVaultCoverageSuiteParams): void;