@bevel-software/platform-shared 0.25.2 → 0.27.0

package/dist/workspace/md-links.d.ts

@@ -0,0 +1,138 @@
+/**
+ * The markdown link grammar a move rewrites with: where the links in a page
+ * are, what each one points at, and how to point it somewhere else without
+ * changing anything else about it.
+ *
+ * Pure and dependency-free, so the backend's move and the web app can share
+ * it. The resolver half is the web app's (`resolveKbHref` in the frontend's
+ * `routing/kb-routes.ts`) restated here; a parity test there holds the two to
+ * one answer on a shared fixture set.
+ *
+ * What it deliberately is NOT: a markdown parser. It finds link
+ * DESTINATIONS — inline links, images, reference definitions, and the inline
+ * links in a node's frontmatter (the `nodeType` link) — as character spans, so
+ * a rewrite splices the new destination into the old one's place and every
+ * other byte of the file stays as it was. Code — fenced blocks, indented
+ * blocks and inline code — is skipped: a path written there is an example,
+ * not a link.
+ */
+/**
+ * An id-link destination: a node's frontmatter id (`project-hexis`), optionally
+ * with a heading anchor. The web app's `NODE_ID_LINK_RE`, restated: an id-link
+ * points at a node wherever it lives, so a move never changes one.
+ */
+export declare const MD_ID_LINK_RE: RegExp;
+/** One link destination found in a page. */
+export interface MdLinkSpan {
+    /** `link` and `image` are inline (`[x](d)`, `![x](d)`); `definition` is `[x]: d`. */
+    kind: 'link' | 'image' | 'definition';
+    /** Offsets of the destination as written, angle brackets excluded. */
+    start: number;
+    end: number;
+    /** The destination as written (`text.slice(start, end)`). */
+    destination: string;
+    /** Written as `<dest>`. */
+    angle: boolean;
+    /** Inside the `---` frontmatter block. */
+    inFrontmatter: boolean;
+}
+/**
+ * Every link destination in a markdown page, in document order. Code is
+ * skipped: fenced blocks (``` and ~~~, in lists and quotes too) and inline code
+ * spans. A footnote (`[^1]: …`) is not a reference definition.
+ */
+export declare function scanMarkdownLinks(text: string): MdLinkSpan[];
+/**
+ * The `href`/`src` values of the raw HTML tags a markdown page carries —
+ * what the app renders as a link or a picture that the markdown grammar does
+ * not rewrite. Only an unescaped `<tag …>` outside code counts: a tag in a
+ * fence, a code span or behind a `\<` is an example, and a bare `href=` in
+ * prose is prose.
+ */
+export declare function scanMarkdownHtmlLinks(text: string): HtmlLinkTarget[];
+/**
+ * The `href`/`src` values in an HTML page. A move never rewrites an HTML page
+ * (most of its links are built in scripts nobody can see), so these are only
+ * read, to report the page.
+ */
+export declare function scanHtmlLinks(text: string): string[];
+/** One `href` or `src` value in an HTML tag; `image` says which — a `src` is a picture, and a picture resolves as one. */
+export interface HtmlLinkTarget {
+    destination: string;
+    image: boolean;
+}
+/** {@link scanHtmlLinks}, with each value's attribute kept: `src` is an image, `href` a link. */
+export declare function scanHtmlLinkTargets(text: string): HtmlLinkTarget[];
+/** How a link names its target, which a rewrite keeps. */
+export type MdLinkForm = 'relative' | 'root' | 'workspace';
+/** A link destination that names a file or folder in the workspace. */
+export interface ResolvedMdLink {
+    form: MdLinkForm;
+    /** Workspace-relative (`knowledge-base/…`), decoded. */
+    path: string;
+    /** `#anchor` as written, or ''. */
+    hash: string;
+    /** The branch a `/workspace/<branch>/…` link names; null otherwise. */
+    branch: string | null;
+}
+export interface ResolveMdLinkOptions {
+    /** The workspace-relative file the link sits in. */
+    basePath: string;
+    /** The clone folder (`knowledge-base`), for the mangled-path repair. */
+    kbDirName: string | null;
+    /** An image source gets no mangled-path repair (see the web app's resolver). */
+    image?: boolean;
+}
+/** An href as a browser reads it: outer controls and spaces off, inner tabs and line breaks out. */
+export declare function normalizeMdHref(href: string): string;
+/** `relative` against the file `basePath`, as the web app resolves it. */
+export declare function resolveMdRelativePath(basePath: string, relative: string): string;
+/**
+ * What a destination written in `basePath` points at, or null when it names
+ * no workspace path a move could affect: an external URL, an id-link, a
+ * same-page `#anchor`, or a bare `/workspace/<branch>`.
+ */
+export declare function resolveMdLink(destination: string, opts: ResolveMdLinkOptions): ResolvedMdLink | null;
+/**
+ * The destination `span` must carry once its file sits at `newBase` and its
+ * target at `newTarget`, in the form it was written in: relative stays
+ * relative (`./` and a trailing `/` kept), root-anchored stays root-anchored,
+ * an app URL keeps its branch segment; encoding, anchor — and, because only
+ * the destination is spliced, the title — stay as they were.
+ */
+export declare function retargetMdDestination(span: Pick<MdLinkSpan, 'destination' | 'angle' | 'inFrontmatter'>, resolved: ResolvedMdLink, newBase: string, newTarget: string): string;
+/** One destination a rewrite changed. */
+export interface MdLinkEdit {
+    from: string;
+    to: string;
+}
+export interface RewriteMdLinksOptions {
+    /** Where the file is now (workspace-relative). */
+    oldPath: string;
+    /** Where the file will be after the move (`oldPath` when it does not move). */
+    newPath: string;
+    /** A workspace path's place after the move, or null when it does not move. */
+    mapPath: (path: string) => string | null;
+    kbDirName: string | null;
+    /** The branch the move happens on: a link (not an image) to another branch's app URL is left alone. */
+    branch: string;
+}
+/**
+ * Rewrite the links in one markdown page so that, once it sits at `newPath`
+ * and every moved path is at its new place, each points at the same target it
+ * did before. A link that already does is left alone, as is every byte that is
+ * not a changed destination.
+ */
+export declare function rewriteMdLinks(text: string, opts: RewriteMdLinksOptions): {
+    text: string;
+    edits: MdLinkEdit[];
+};
+/**
+ * The destinations in an HTML page that point at a moved path, or (for a page
+ * that moves itself) whose relative target the move would break. Reported,
+ * never rewritten.
+ */
+export declare function htmlLinksAffectedByMove(text: string, opts: RewriteMdLinksOptions, 
+/** The targets to judge: an HTML page's by default, a markdown page's from {@link scanMarkdownHtmlLinks}. */
+targets?: HtmlLinkTarget[]): string[];
+//# sourceMappingURL=md-links.d.ts.map

package/dist/workspace/md-links.d.ts.map

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