@osdlc/markdown-link 0.0.0-stage → 0.5.0

package/dist/display.js

@@ -0,0 +1,88 @@
+/**
+ * What a reader sees for a link, and typed references. A port of the
+ * `markdown-link` crate's `display_text` and `parse_typed_ref`.
+ */
+import { isWhitespace, parseInner, splitAlias, trim } from "./parse.js";
+/**
+ * Replace each wikilink and embed with what a reader sees for it, for
+ * snippets and search: its alias, or else its target. An embed's trailing
+ * `|300` or `|300x200` is a size, not an alias, so
+ * `![[img.png|300]]` shows `img.png`. An empty alias shows the target. Code
+ * is not skipped.
+ *
+ * Every delimiter is ASCII, so the scan can step UTF-16 units: a surrogate
+ * never matches one.
+ */
+export function displayText(text) {
+    let out = '';
+    let i = 0;
+    while (i < text.length) {
+        const embed = text[i] === '!' && text.startsWith('[[', i + 1);
+        const open = embed ? i + 1 : i;
+        if (text.startsWith('[[', open)) {
+            const close = linkClose(text, open);
+            if (close !== null) {
+                const link = parseInner(text.slice(open + 2, close), embed);
+                if (link !== null)
+                    out += shown(link);
+                i = close + 2;
+                continue;
+            }
+        }
+        out += text[i];
+        i++;
+    }
+    return out;
+}
+/** Where the `]]` closing the `[[` at `open` starts, or `null`. */
+function linkClose(text, open) {
+    for (let j = open + 2; j + 1 < text.length; j++) {
+        if (text[j] === ']' && text[j + 1] === ']')
+            return j;
+        if (text[j] === '[' || text[j] === ']')
+            return null;
+    }
+    return null;
+}
+/** What a reader sees for one link. See `displayText`. */
+function shown(link) {
+    let alias = link.alias;
+    if (alias !== null && link.embed) {
+        const pipe = alias.lastIndexOf('|');
+        const last = pipe === -1 ? alias : alias.slice(pipe + 1);
+        if (isSize(trim(last)))
+            alias = pipe === -1 ? '' : trim(alias.slice(0, pipe));
+    }
+    return alias || link.target;
+}
+/** `300` or `300x200`: an embed's width, or width and height. */
+function isSize(s) {
+    return /^[0-9]+(?:x[0-9]+)?$/.test(s);
+}
+/**
+ * Parse a whole value as a typed reference, or `null`.
+ *
+ * Shape only: the target is not resolved. The value is exactly `[[...]]`
+ * with no `[`, `]` or line break inside. The target ends at the first `|`,
+ * minus a `\` that escapes it, as in `parseInner`. Its type and each
+ * `/`-separated slug segment are non-empty and hold no whitespace.
+ */
+export function parseTypedRef(value) {
+    if (!value.startsWith('[[') || !value.endsWith(']]'))
+        return null;
+    const inner = value.slice(2, -2);
+    if (/[[\]\n\r]/.test(inner))
+        return null;
+    const [target, alias] = splitAlias(inner);
+    const slash = target.indexOf('/');
+    if (slash === -1)
+        return null;
+    const kind = target.slice(0, slash);
+    const slug = target.slice(slash + 1);
+    if (!isWord(kind) || !slug.split('/').every(isWord))
+        return null;
+    return { kind, slug, alias };
+}
+function isWord(s) {
+    return s !== '' && !Array.from(s).some(isWhitespace);
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Wikilink parsing that follows documented link-resolution conventions: the TypeScript twin of the `markdown-link`
+ * crate's parsing half. Each function gives the same answer as its Rust
+ * namesake. Both suites read the crate's case file,
+ * `packages/rust/markdown-link/tests/fixtures/conformance.json`.
+ *
+ * Spans and ranges are UTF-16 offsets, so they index a JavaScript string.
+ * The Rust crate reports byte offsets.
+ */
+export { type CodeRules, stripCode, stripCodeWith } from './code.ts';
+export { ATTACHMENT_EXTENSIONS, type TextRange, type WikiLink, isVaultLinkUrl, mdLinkTarget, parseInner, targetRange, } from './parse.ts';
+export { type TypedRef, displayText, parseTypedRef } from './display.ts';
+export { type BodyLink, type BodyLinkKind, type LinkKind, type RawLink, bodyLinks, bodyLinksSpanned, } from './body-links.ts';

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * Wikilink parsing that follows documented link-resolution conventions: the TypeScript twin of the `markdown-link`
+ * crate's parsing half. Each function gives the same answer as its Rust
+ * namesake. Both suites read the crate's case file,
+ * `packages/rust/markdown-link/tests/fixtures/conformance.json`.
+ *
+ * Spans and ranges are UTF-16 offsets, so they index a JavaScript string.
+ * The Rust crate reports byte offsets.
+ */
+export { stripCode, stripCodeWith } from "./code.js";
+export { ATTACHMENT_EXTENSIONS, isVaultLinkUrl, mdLinkTarget, parseInner, targetRange, } from "./parse.js";
+export { displayText, parseTypedRef } from "./display.js";
+export { bodyLinks, bodyLinksSpanned, } from "./body-links.js";

package/dist/parse.d.ts

@@ -0,0 +1,68 @@
+/**
+ * One wikilink body, and one markdown link URL. A port of the `wikilink`
+ * crate's `parse_inner`, `target_range`, `is_vault_link_url` and
+ * `md_link_target`.
+ */
+/** A parsed `[[target#heading|alias]]`. */
+export interface WikiLink {
+    target: string;
+    heading: string | null;
+    alias: string | null;
+    embed: boolean;
+}
+/** A half-open range of UTF-16 offsets, `[start, end)`. */
+export interface TextRange {
+    start: number;
+    end: number;
+}
+/**
+ * Parse a single wikilink body (the text between the brackets).
+ *
+ * A `\` right before the first `|` is the escape a GFM table cell needs
+ * (`[[Note\|alias]]`) and is dropped from the target or heading.
+ *
+ * @returns `null` when the target is empty: a blank body, or one holding only
+ * a `#heading` or an `|alias`.
+ */
+export declare function parseInner(inner: string, embed: boolean): WikiLink | null;
+/**
+ * The range of `parseInner`'s target within `inner`, for a caller that
+ * rewrites the target in place and must leave the rest of the link as written.
+ * UTF-16 offsets, where the Rust crate returns byte offsets.
+ */
+export declare function targetRange(inner: string): TextRange | null;
+/** `inner` split at the first `|`, minus the `\` that escapes it. */
+export declare function splitAlias(inner: string): [string, string | null];
+export declare function trim(s: string): string;
+/** Whether a single code point is Unicode White_Space. */
+export declare function isWhitespace(c: string): boolean;
+/**
+ * Every non-markdown extension that counts as a vault attachment (lowercase,
+ * no dot). Matched case-insensitively, unlike the `.md` rule.
+ *
+ * This answers "is this file an attachment", not "can it be displayed".
+ * `tiff` and `heic` are real attachments a photo library produces that no
+ * browser reliably paints: they belong in a graph and a search index, not in
+ * an `<img>`.
+ *
+ * The Rust `markdown-link` crate's `ATTACHMENT_EXTENSIONS` is the same list;
+ * `tests/attachment-extensions.test.ts` fails if they disagree.
+ */
+export declare const ATTACHMENT_EXTENSIONS: readonly string[];
+/**
+ * Whether a markdown link's URL is one this dialect harvests: a note, or a
+ * vault attachment.
+ *
+ * The `.md` test is case-sensitive (`x.MD` is not a link) and needs at least
+ * one character before the extension (`.md` is not either).
+ */
+export declare function isVaultLinkUrl(url: string): boolean;
+/**
+ * The resolution target of a markdown link's URL: percent-decoded, minus its
+ * trailing `.md`.
+ *
+ * `.md` and then `.MD` are stripped **repeatedly**, so `a.md.md` targets `a`.
+ * Only when neither strips anything does a single case-insensitive `.md` come
+ * off.
+ */
+export declare function mdLinkTarget(url: string): string;

package/dist/parse.js

@@ -0,0 +1,217 @@
+/**
+ * One wikilink body, and one markdown link URL. A port of the `wikilink`
+ * crate's `parse_inner`, `target_range`, `is_vault_link_url` and
+ * `md_link_target`.
+ */
+/**
+ * Parse a single wikilink body (the text between the brackets).
+ *
+ * A `\` right before the first `|` is the escape a GFM table cell needs
+ * (`[[Note\|alias]]`) and is dropped from the target or heading.
+ *
+ * @returns `null` when the target is empty: a blank body, or one holding only
+ * a `#heading` or an `|alias`.
+ */
+export function parseInner(inner, embed) {
+    const target = targetRange(inner);
+    if (target === null)
+        return null;
+    const [beforeAlias, alias] = splitAlias(inner);
+    const hash = beforeAlias.indexOf('#');
+    return {
+        target: inner.slice(target.start, target.end),
+        heading: hash === -1 ? null : trim(beforeAlias.slice(hash + 1)),
+        alias: alias === null ? null : trim(alias),
+        embed,
+    };
+}
+/**
+ * The range of `parseInner`'s target within `inner`, for a caller that
+ * rewrites the target in place and must leave the rest of the link as written.
+ * UTF-16 offsets, where the Rust crate returns byte offsets.
+ */
+export function targetRange(inner) {
+    const [beforeAlias] = splitAlias(inner);
+    const hash = beforeAlias.indexOf('#');
+    const raw = hash === -1 ? beforeAlias : beforeAlias.slice(0, hash);
+    const target = trim(raw);
+    if (target === '')
+        return null;
+    const lead = raw.length - trimStart(raw).length;
+    return { start: lead, end: lead + target.length };
+}
+/** `inner` split at the first `|`, minus the `\` that escapes it. */
+export function splitAlias(inner) {
+    const pipe = inner.indexOf('|');
+    if (pipe === -1)
+        return [inner, null];
+    const before = inner.slice(0, pipe);
+    return [before.endsWith('\\') ? before.slice(0, -1) : before, inner.slice(pipe + 1)];
+}
+/**
+ * Whether a UTF-16 unit is Unicode White_Space, as Rust's `char::is_whitespace`
+ * reads it. Every White_Space character is in the BMP. JavaScript's `trim` and
+ * `\s` differ: they treat U+FEFF as space and U+0085 as not.
+ */
+function isSpaceUnit(unit) {
+    return ((unit >= 0x09 && unit <= 0x0d) ||
+        unit === 0x20 ||
+        unit === 0x85 ||
+        unit === 0xa0 ||
+        unit === 0x1680 ||
+        (unit >= 0x2000 && unit <= 0x200a) ||
+        unit === 0x2028 ||
+        unit === 0x2029 ||
+        unit === 0x202f ||
+        unit === 0x205f ||
+        unit === 0x3000);
+}
+function trimStart(s) {
+    let start = 0;
+    while (start < s.length && isSpaceUnit(s.charCodeAt(start)))
+        start++;
+    return s.slice(start);
+}
+export function trim(s) {
+    const rest = trimStart(s);
+    let end = rest.length;
+    while (end > 0 && isSpaceUnit(rest.charCodeAt(end - 1)))
+        end--;
+    return rest.slice(0, end);
+}
+/** Whether a single code point is Unicode White_Space. */
+export function isWhitespace(c) {
+    return c.length === 1 && isSpaceUnit(c.charCodeAt(0));
+}
+/**
+ * Every non-markdown extension that counts as a vault attachment (lowercase,
+ * no dot). Matched case-insensitively, unlike the `.md` rule.
+ *
+ * This answers "is this file an attachment", not "can it be displayed".
+ * `tiff` and `heic` are real attachments a photo library produces that no
+ * browser reliably paints: they belong in a graph and a search index, not in
+ * an `<img>`.
+ *
+ * The Rust `markdown-link` crate's `ATTACHMENT_EXTENSIONS` is the same list;
+ * `tests/attachment-extensions.test.ts` fails if they disagree.
+ */
+export const ATTACHMENT_EXTENSIONS = [
+    'png',
+    'jpg',
+    'jpeg',
+    'gif',
+    'svg',
+    'webp',
+    'avif',
+    'bmp',
+    'ico',
+    'tiff',
+    'heic',
+    'mp4',
+    'webm',
+    'ogv',
+    'mov',
+    'mkv',
+    'mp3',
+    'wav',
+    'm4a',
+    '3gp',
+    'flac',
+    'ogg',
+    'oga',
+    'opus',
+    'pdf',
+    'base',
+    'canvas',
+];
+/**
+ * Whether a markdown link's URL is one this dialect harvests: a note, or a
+ * vault attachment.
+ *
+ * The `.md` test is case-sensitive (`x.MD` is not a link) and needs at least
+ * one character before the extension (`.md` is not either).
+ */
+export function isVaultLinkUrl(url) {
+    if (url.length > 3 && url.endsWith('.md'))
+        return true;
+    const last = url.slice(url.lastIndexOf('/') + 1);
+    const dot = last.lastIndexOf('.');
+    // A leading dot is a hidden file, not an extension, and a trailing dot is no
+    // extension at all.
+    if (dot <= 0)
+        return false;
+    return ATTACHMENT_EXTENSIONS.includes(last.slice(dot + 1).toLowerCase());
+}
+/**
+ * The resolution target of a markdown link's URL: percent-decoded, minus its
+ * trailing `.md`.
+ *
+ * `.md` and then `.MD` are stripped **repeatedly**, so `a.md.md` targets `a`.
+ * Only when neither strips anything does a single case-insensitive `.md` come
+ * off.
+ */
+export function mdLinkTarget(url) {
+    const decoded = percentDecode(url);
+    let trimmed = decoded;
+    while (trimmed.endsWith('.md'))
+        trimmed = trimmed.slice(0, -3);
+    while (trimmed.endsWith('.MD'))
+        trimmed = trimmed.slice(0, -3);
+    return trimmed.length === decoded.length ? stripMdExt(decoded) : trimmed;
+}
+/** Drop a trailing `.md`, ignoring ASCII case. */
+function stripMdExt(s) {
+    return /\.[mM][dD]$/.test(s) ? s.slice(0, -3) : s;
+}
+const utf8Decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+/**
+ * Percent-decode a URL over its UTF-8 bytes. Bytes that do not decode to UTF-8
+ * leave the URL as written, rather than becoming U+FFFD.
+ */
+function percentDecode(s) {
+    if (!s.includes('%'))
+        return s;
+    const bytes = new TextEncoder().encode(s);
+    const out = [];
+    let i = 0;
+    while (i < bytes.length) {
+        if (bytes[i] === 0x25 && i + 2 < bytes.length) {
+            const value = hexByte(bytes[i + 1], bytes[i + 2]);
+            if (value !== null) {
+                out.push(value);
+                i += 3;
+                continue;
+            }
+        }
+        out.push(bytes[i]);
+        i++;
+    }
+    try {
+        return utf8Decoder.decode(Uint8Array.from(out));
+    }
+    catch {
+        return s;
+    }
+}
+/**
+ * Two bytes read as Rust's `u8::from_str_radix(_, 16)` reads them: two hex
+ * digits, or a `+` sign and one hex digit.
+ */
+function hexByte(a, b) {
+    const low = hexDigit(b);
+    if (low === null)
+        return null;
+    if (a === 0x2b)
+        return low;
+    const high = hexDigit(a);
+    return high === null ? null : high * 16 + low;
+}
+function hexDigit(byte) {
+    if (byte >= 0x30 && byte <= 0x39)
+        return byte - 0x30;
+    if (byte >= 0x41 && byte <= 0x46)
+        return byte - 0x37;
+    if (byte >= 0x61 && byte <= 0x66)
+        return byte - 0x57;
+    return null;
+}

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@osdlc/markdown-link",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.5.0",
+  "description": "Wikilink parsing that follows documented link-resolution conventions: every [[link]], ![[embed]] and relative markdown link in a note body, with spans, and the code lexer that keeps links in code out. The TypeScript twin of the parsing half of the Rust markdown-link crate, held to it by a shared case file. No dependencies.",
+  "license": "MIT OR Apache-2.0",
+  "author": "sksizer",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/osdlc/osdlc.git",
+    "directory": "packages/ts/markdown-link"
+  },
+  "homepage": "https://github.com/osdlc/osdlc/tree/main/packages/ts/markdown-link#readme",
+  "bugs": "https://github.com/osdlc/osdlc/issues",
+  "keywords": [
+    "markdown",
+    "wikilink",
+    "obsidian",
+    "links",
+    "embed",
+    "parser",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE-MIT",
+    "LICENSE-APACHE",
+    "SECURITY.md",
+    "CONTRIBUTING.md"
+  ],
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "@vitest/coverage-v8": "^5.0.5",
+    "oxlint": "^1.65.0",
+    "prettier": "3.9.6",
+    "typescript": "~6.0.3",
+    "vitest": "^5.0.5",
+    "@osdlc/prettier-config": "^0.3.1",
+    "@osdlc/tsconfig": "^0.4.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "test": "vitest run",
+    "coverage": "vitest run --coverage",
+    "smoke": "node tests/smoke.mjs",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "oxlint .",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.build.json --noEmit"
+  }
 }