@dogsbay/commands 0.2.0-beta.101

package/dist/indexes.d.ts

@@ -0,0 +1,175 @@
+import { type TopicMapError } from "@dogsbay/format-topicmap";
+import type { Storage } from "./storage.js";
+export interface DocHeading {
+    level: number;
+    text: string;
+    /** Explicit `{#id}` anchor, when authored. */
+    id?: string;
+    /** The anchor the SITE renders for this heading (renderer-parity slug), when it is a top-level heading. */
+    slug?: string;
+}
+export type RefKind = "link" | "image" | "include" | "topicmap" | "key";
+export interface DocLink {
+    /** The href exactly as authored. */
+    href: string;
+    /** Workspace-relative target path — undefined for external/unresolvable hrefs. */
+    target?: string;
+    /** `#fragment` portion, when present. */
+    fragment?: string;
+    /** The relative target resolves ABOVE the workspace root (`../` remains after joining). */
+    escapes?: boolean;
+    /** Site-absolute (`/guides/x`): resolved by validate against the content roots (no `target`). */
+    siteAbsolute?: boolean;
+    /** For site-absolute links: the path part, query stripped and percent-decoded, no leading/trailing `/`. */
+    sitePath?: string;
+    /** 1-based line of the first un-attributed occurrence of the href in the (code-masked) source. */
+    line?: number;
+    kind: "link" | "image";
+}
+export interface DocInclude {
+    /** Path exactly as written in the `{% include %}` directive. */
+    raw: string;
+    /** Workspace-relative resolved target. */
+    target: string;
+    /** 1-based line of the directive. */
+    line?: number;
+}
+export interface DocIndexEntry {
+    path: string;
+    frontmatter: Record<string, unknown>;
+    title?: string;
+    headings: DocHeading[];
+    /** Every id a `#fragment` link can land on: explicit heading ids, `<a id>` anchors, heading slugs. */
+    anchors: string[];
+    links: DocLink[];
+    includes: DocInclude[];
+    /** Key names referenced via `key:` hrefs. */
+    keyUses: string[];
+    /**
+     * "none" — no `---` opener; "block" — a terminated block, whatever it
+     * parsed to; "unterminated" — an opener with no closer, which makes the
+     * parser swallow the WHOLE page (empty tree, no headings, no links).
+     * `frontmatter` alone cannot tell these apart, and two of the three drop
+     * content silently.
+     */
+    frontmatterBlock: "none" | "block" | "unterminated";
+    /**
+     * 1-based line of each top-level frontmatter key, and whether the block has
+     * any content at all. Derived on the SAME pass that reads the file: validate
+     * used to re-read every page's source for these, which was a second full
+     * read of the corpus (+231% on a 653-doc corpus) and defeated the
+     * incremental index — one changed file, every file re-read.
+     */
+    frontmatterKeyLines: Map<string, number>;
+    /** True when the block holds only blank lines/comments (a stub, not a broken block). */
+    frontmatterEmpty: boolean;
+    /** Set when the file could not be parsed; the entry is otherwise empty. */
+    parseError?: string;
+    /**
+     * Hash of the source bytes this entry was built from — the same hash
+     * `topic-read` returns and the content verbs accept as `expect`, so a fix
+     * derived from this entry can be gated on the file NOT having changed since.
+     */
+    hash: string;
+}
+export interface TopicMapRef {
+    href: string;
+    /**
+     * Workspace-relative target — undefined for external hrefs AND for
+     * "/"-rooted hrefs, which the topicmap loader convention resolves
+     * against the ROOT map's directory (only known when walking from a
+     * root; see `rootRelative`).
+     */
+    target?: string;
+    /** True for "/"-rooted hrefs (root-map-dir-relative, per the loader convention). */
+    rootRelative?: boolean;
+    /** True for `format: topicmap` includes. */
+    isMap: boolean;
+    navtitle?: string;
+}
+export interface TopicMapIndexEntry {
+    path: string;
+    title?: string;
+    refs: TopicMapRef[];
+    errors: TopicMapError[];
+}
+export interface KeyDefinition {
+    name: string;
+    /** keys.yaml file that defines it. */
+    file: string;
+    def: Record<string, unknown>;
+}
+export interface KeyFileError {
+    file: string;
+    message: string;
+}
+export interface InboundRef {
+    /** Referencing file (doc or topic map). */
+    from: string;
+    kind: RefKind;
+    /** The href/path exactly as authored in the referencing file. */
+    raw: string;
+    /** Fragment the reference targets, when present. */
+    fragment?: string;
+}
+export interface WorkspaceIndex {
+    /** Every file in the workspace (posix-relative) — assets included; what a site-absolute link may land on. */
+    files: Set<string>;
+    docs: Map<string, DocIndexEntry>;
+    maps: Map<string, TopicMapIndexEntry>;
+    /** All definitions per key name, in file order — first is the winner. */
+    keys: Map<string, KeyDefinition[]>;
+    keyFileErrors: KeyFileError[];
+    /** Inverted reference graph: target file → inbound references. */
+    inbound: Map<string, InboundRef[]>;
+    /** Key name → files that use it (via key: hrefs). */
+    keyUses: Map<string, string[]>;
+    stats: {
+        files: number;
+        docs: number;
+        maps: number;
+        keyFiles: number;
+        keys: number;
+        links: number;
+        includes: number;
+    };
+}
+/**
+ * Blank out code-region CONTENT so the raw-source include scan never
+ * counts template EXAMPLES as real includes. The fence/span grammar is
+ * @dogsbay/format-dogsbay-md's transformCodeRegions — the same walker
+ * the build preprocessor uses, so "what counts as code" cannot drift
+ * between validate and the build. (The include grammar itself comes
+ * from @dogsbay/minja for the same reason.)
+ *
+ * A `{minja}`-marked fence is NOT blanked, for the same no-drift reason:
+ * the build preprocessor PROCESSES marked fences (its masker skips them),
+ * so a directive inside one is real and must be visible to validation.
+ */
+export declare const blankCodeRegions: (source: string) => string;
+/**
+ * Anchors OTHER renderers would give a heading text — GitHub-slugger
+ * (lowercase, punctuation removed except `-`/space, spaces → `-`, no
+ * collapse) and Python-Markdown/mkdocs (non-word chars removed, runs of
+ * `-`/space → one `-`). Dogsbay's own rule (the site build's) is what
+ * `anchors` holds; these let validate tell "the anchor exists under another
+ * tool's rule" (a migration-era mismatch) from "no such heading" (a dead
+ * link in any tool).
+ */
+/** For each alias (GitHub/mkdocs slug) the DOGSBAY anchor of the same heading — what a mismatched link should be retargeted to. */
+export declare function anchorAliasTargets(headings: DocHeading[], dogsbayAnchors: string[]): Map<string, string>;
+export declare function anchorAliases(headings: DocHeading[]): Set<string>;
+export interface BuildIndexOptions {
+    /**
+     * Incremental: keep every entry of `previous` whose path is NOT in
+     * `changed`, re-read only the changed paths (a gone path is dropped), and
+     * recompute the inverted graphs — the per-file indexing is the cost, the
+     * graphs are milliseconds. Keys files are always re-read (they are few and
+     * their table is global).
+     */
+    previous?: WorkspaceIndex;
+    changed?: string[];
+}
+/** Build every index in one pass over the workspace (or patch a previous one — see BuildIndexOptions). */
+export declare function buildWorkspaceIndex(storage: Storage, options?: BuildIndexOptions): Promise<WorkspaceIndex>;
+//# sourceMappingURL=indexes.d.ts.map

package/dist/indexes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexes.d.ts","sourceRoot":"","sources":["../src/indexes.ts"],"names":[],"mappings":"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"}