Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(ok): resolve and re-encode percent-encoded internal links (PRD-8141) (#3673)

serafin-garciadf2a25dec4d4
diff --git a/.changeset/percent-encoded-link-resolution.md b/.changeset/percent-encoded-link-resolution.md
new file mode 100644
index 000000000..3d82edeee
--- /dev/null
+++ b/.changeset/percent-encoded-link-resolution.md
@@ -0,0 +1,7 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Percent-encoded links now resolve to the document they name. A link like `./Agent%20Memory.md` (the form the generated `index.md` emits, and the standard GitHub/Obsidian spelling for names with spaces, parentheses, `#`, `&`, or non-ASCII characters) used to resolve to a phantom document containing the raw escapes, so the Problems panel flagged it `dead-link`, the graph lost the backlink, and clicking it offered to create a new page. The canonical resolvers now decode each path segment per RFC 3986 before path resolution, so lint, graph, navigation, rename rewriting, and asset links all agree with the file on disk. Escapes stay data: `%2F` and `%5C` never become a path separator or a `..` traversal, malformed escapes are kept as literal bytes, and `[[wiki]]` targets remain verbatim.
+
+Renaming or moving a document also re-encodes the links it rewrites. Because the resolvers now decode, a rename matches percent-encoded links for the first time, so the rewriters emit the encoded form rather than a raw name. A document or asset whose name carries a space, `#`, `?`, or a parenthesis keeps a link that still parses after the rename.
diff --git a/knip.config.ts b/knip.config.ts
index 78162ec09..f9179f2d4 100644
--- a/knip.config.ts
+++ b/knip.config.ts
@@ -123,7 +123,9 @@ export default {
'packages/server': {
entry: ['src/**/*.test.ts', 'src/parse-worker.ts'],
project: 'src/**',
- ignoreDependencies: ['@types/shell-quote'],
+ ignoreDependencies: [
+ '@types/shell-quote',
+ ],
},
'packages/cli': {
entry: ['src/**/*.test.ts', 'scripts/*.ts', 'tests/**/*.ts', 'src/parse-worker.ts'],
diff --git a/packages/app/src/editor/asset-dispatch/types.ts b/packages/app/src/editor/asset-dispatch/types.ts
index 4b42ba228..f9f28a19c 100644
--- a/packages/app/src/editor/asset-dispatch/types.ts
+++ b/packages/app/src/editor/asset-dispatch/types.ts
@@ -31,7 +31,10 @@ export interface AssetClickContext {
readonly url: string;
/**
* Project-root-relative, canonical path. Computed by the caller using
- * `resolveAssetProjectPath(url, sourceDocName)` from `link-targets.ts`.
+ * `resolveAssetProjectPath(url, sourceDocName, { literal })` from
+ * `link-targets.ts` — the caller supplies the plane `url` was authored on,
+ * since a wiki target is a literal filename and a markdown destination is a
+ * URI whose escapes decode.
* This is what the Electron main-process handler expects — `openAssetSafely`
* resolves it against `ProjectContext.projectPath + realpath +
* isPathWithinProject` for containment.
diff --git a/packages/app/src/editor/components/image-target-existence.ts b/packages/app/src/editor/components/image-target-existence.ts
index e5ae53b27..b97851385 100644
--- a/packages/app/src/editor/components/image-target-existence.ts
+++ b/packages/app/src/editor/components/image-target-existence.ts
@@ -37,9 +37,16 @@ export function classifyImageTargetExistence(
assetPaths: ReadonlySet<string> | undefined,
filePaths: ReadonlySet<string> | undefined,
): ImageTargetExistence {
- const projectRelPath = resolveAssetProjectPath(src, sourceDocName);
+ // URI plane, for every producer of an `<img src>` — markdown images, the
+ // `WikiEmbed*` compats, and bare HTML alike. The src is what the browser
+ // fetches, and the asset serve path percent-decodes that request URL before
+ // touching disk, so an existence check that skipped decoding would answer a
+ // different question than the fetch it is explaining.
+ const projectRelPath = resolveAssetProjectPath(src, sourceDocName, { literal: false });
if (projectRelPath === null) return 'unknown';
- return isResolvedAssetHref(src, sourceDocName, assetPaths, filePaths) ? 'exists' : 'missing';
+ return isResolvedAssetHref(src, sourceDocName, assetPaths, filePaths, { literal: false })
+ ? 'exists'
+ : 'missing';
}
/**
diff --git a/packages/app/src/editor/extensions/InternalLinkPropPanel.tsx b/packages/app/src/editor/extensions/InternalLinkPropPanel.tsx
index 939b9fa77..4a1b5cb92 100644
--- a/packages/app/src/editor/extensions/InternalLinkPropPanel.tsx
+++ b/packages/app/src/editor/extensions/InternalLinkPropPanel.tsx
@@ -392,8 +392,11 @@ export function InternalLinkPropPanel({
// inventory membership. Without the same check the card offers Create page
// over a file that is right there on disk — and the chip beside it, which
// does consult the tracked-file sets, renders resolved at the same moment.
+ // `href` is the link mark's markdown destination — a URI whose escapes
+ // decode, the same reading `classifyMarkdownHref` just applied to it.
const namesTrackedFile =
- target?.kind === 'doc' && isResolvedAssetHref(href, sourceDocName, assetPaths, filePaths);
+ target?.kind === 'doc' &&
+ isResolvedAssetHref(href, sourceDocName, assetPaths, filePaths, { literal: false });
const docIntent =
target?.kind === 'doc' && !namesTrackedFile
? resolveLinkTargetIntent(target.docName, {
diff --git a/packages/app/src/editor/extensions/bare-html-image-decoration.tsx b/packages/app/src/editor/extensions/bare-html-image-decoration.tsx
index 9e02f85e1..9d4f063d4 100644
--- a/packages/app/src/editor/extensions/bare-html-image-decoration.tsx
+++ b/packages/app/src/editor/extensions/bare-html-image-decoration.tsx
@@ -62,7 +62,11 @@ export function findBareHtmlImageTags(text: string): BareTagMatch[] {
function imagePropsFromElement(image: HTMLImageElement, sourceDocName: string): ImageProps | null {
const src = image.getAttribute('src');
- if (src === null || resolveAssetProjectPath(src, sourceDocName) === null) return null;
+ // An HTML `src` is a URL, so its escapes decode — the same reading the asset
+ // serve path applies when the browser actually fetches it.
+ if (src === null || resolveAssetProjectPath(src, sourceDocName, { literal: false }) === null) {
+ return null;
+ }
const loading = image.getAttribute('loading');
const decoding = image.getAttribute('decoding');
diff --git a/packages/app/src/editor/extensions/internal-link.asset-activation.test.ts b/packages/app/src/editor/extensions/internal-link.asset-activation.test.ts
new file mode 100644
index 000000000..69a89cba8
--- /dev/null
+++ b/packages/app/src/editor/extensions/internal-link.asset-activation.test.ts
@@ -0,0 +1,74 @@
+/**
+ * Plane discipline for the link-mark asset-activation branch.
+ *
+ * The same branch serves two authored forms whose hrefs live on different
+ * planes: a markdown destination is a URI whose percent escapes decode, while
+ * a `sourceForm: 'wikiembed'` mark carries literal filesystem bytes. The
+ * resolved `projectRelPath` is what `shell.openPath` / `showItemInFolder`
+ * receive, so a decode on the wrong plane opens a neighbouring file.
+ */
+
+import { classifyMarkdownHref } from '@inkeep/open-knowledge-core';
+import { describe, expect, test } from 'vitest';
+import { resolveLinkMarkAssetActivation } from './internal-link';
+
+const DOC = 'notes/readme';
+
+function activate(href: string, sourceForm: unknown) {
+ return resolveLinkMarkAssetActivation({
+ href,
+ sourceForm,
+ docName: DOC,
+ classified: classifyMarkdownHref(href, DOC),
+ });
+}
+
+describe('resolveLinkMarkAssetActivation', () => {
+ test('a wikiembed mark keeps its percent sequences literal', () => {
+ expect(activate('/media/100%20done.png', 'wikiembed')).toEqual({
+ kind: 'asset',
+ url: '/media/100%20done.png',
+ ext: 'png',
+ literal: true,
+ projectRelPath: 'media/100%20done.png',
+ });
+ });
+
+ test('a wikiembed mark does not resolve to its decoded neighbour', () => {
+ const activation = activate('/media/100%20done.png', 'wikiembed');
+ expect(activation.kind).toBe('asset');
+ if (activation.kind !== 'asset') return;
+ expect(activation.projectRelPath).not.toBe('media/100 done.png');
+ expect(activation.literal).toBe(true);
+ });
+
+ test('the same bytes on a markdown mark DO decode', () => {
+ // The classified target is asset-shaped either way, so only `sourceForm`
+ // separates the two readings — this is the assertion that would go green
+ // with the plane hard-coded to the wrong value.
+ expect(activate('./media/100%20done.png', undefined)).toEqual({
+ kind: 'asset',
+ url: './media/100%20done.png',
+ ext: 'png',
+ literal: false,
+ projectRelPath: 'notes/media/100 done.png',
+ });
+ });
+
+ test('a bare wiki target with no leading slash stays literal', () => {
+ const activation = activate('100%20done.png', 'wikiembed');
+ expect(activation.kind).toBe('asset');
+ if (activation.kind !== 'asset') return;
+ expect(activation.projectRelPath).toBe('notes/100%20done.png');
+ expect(activation.projectRelPath).not.toBe('notes/100 done.png');
+ });
+
+ test('a doc link is not an asset activation', () => {
+ expect(activate('./other.md', undefined)).toEqual({ kind: 'not-asset' });
+ expect(activate('https://example.com', undefined)).toEqual({ kind: 'not-asset' });
+ });
+
+ test('a path-escaping asset href is refused rather than dispatched', () => {
+ expect(activate('../../../etc/passwd.png', undefined)).toEqual({ kind: 'refused' });
+ });
+});
diff --git a/packages/app/src/editor/extensions/internal-link.ts b/packages/app/src/editor/extensions/internal-link.ts
index 3bda5a545..4a7a746b0 100644
--- a/packages/app/src/editor/extensions/internal-link.ts
+++ b/packages/app/src/editor/extensions/internal-link.ts
@@ -63,6 +63,51 @@ export interface InternalLinkOptions {
docName: string;
}
+/**
+ * Whether a link mark's activation is an asset dispatch, and on which plane.
+ *
+ * `refused` is asset-shaped but path-escaping: the caller surfaces the
+ * suspicious href in the PropPanel instead of dispatching to the OS
+ * (`openAssetSafely` in the main process is the defense-in-depth backstop).
+ */
+export type LinkMarkAssetActivation =
+ | { kind: 'not-asset' }
+ | { kind: 'refused' }
+ | { kind: 'asset'; url: string; ext: string; literal: boolean; projectRelPath: string };
+
+/**
+ * Two paths enter the asset branch:
+ * 1. `classifyMarkdownHref` returned `kind: 'asset'`.
+ * 2. `sourceForm === 'wikiembed'` + the href shape looks asset-like —
+ * post-roundtrip `![[file.ext]]` emits as content-root-relative paths
+ * (`/file.ext`); `sourceForm` disambiguates those embedded references.
+ *
+ * `sourceForm` also decides the PLANE, and it outranks the classified target: a
+ * `wikiembed` mark carries the resolved file path (or the bare wiki target) as
+ * literal bytes, but `/file.png` is asset-shaped to the markdown classifier
+ * too, so the classifier tags it as a URI it never was. Decoding a literal
+ * target dispatches at a neighbouring file that may not exist.
+ */
+export function resolveLinkMarkAssetActivation(params: {
+ href: string;
+ sourceForm: unknown;
+ docName: string;
+ classified: ReturnType<typeof classifyMarkdownHref>;
+}): LinkMarkAssetActivation {
+ const { href, sourceForm, docName, classified } = params;
+ const hrefExt = extractAssetExtension(href);
+ const isWikiEmbed = sourceForm === 'wikiembed';
+ if (classified?.kind !== 'asset' && !(isWikiEmbed && hrefExt !== null)) {
+ return { kind: 'not-asset' };
+ }
+ const url = classified?.kind === 'asset' ? classified.url : href;
+ const ext = classified?.kind === 'asset' ? classified.ext : (hrefExt ?? '');
+ const literal = isWikiEmbed;
+ const projectRelPath = resolveAssetProjectPath(url, docName, { literal });
+ if (!projectRelPath) return { kind: 'refused' };
+ return { kind: 'asset', url, ext, literal, projectRelPath };
+}
+
export const InternalLink = LinkFidelity.extend<InternalLinkOptions>({
addOptions() {
return {
@@ -137,28 +182,16 @@ export const InternalLink = LinkFidelity.extend<InternalLinkOptions>({
// Cmd/Ctrl+click — asset hrefs never open the PropPanel. Bare click
// navigates to the in-app asset preview (sidebar parity); Cmd+click
// forces OS delegation as an escape hatch (see `activateAssetLink`).
- //
- // Two paths enter this branch:
- // 1. `classifyMarkdownHref` returned `kind: 'asset'`.
- // 2. `sourceForm === 'wikiembed'` + the href shape looks
- // asset-like — post-roundtrip `![[file.ext]]` emits as
- // content-root-relative paths (`/file.ext`); `sourceForm`
- // disambiguates those embedded asset references.
- const sourceForm = info?.attrs?.sourceForm;
const target = classifyMarkdownHref(href, docName);
- const hrefExt = extractAssetExtension(href);
- const isAssetShape =
- target?.kind === 'asset' || (sourceForm === 'wikiembed' && hrefExt !== null);
- if (isAssetShape) {
- const url = target?.kind === 'asset' ? target.url : href;
- const ext = target?.kind === 'asset' ? target.ext : (hrefExt ?? '');
- const projectRelPath = resolveAssetProjectPath(url, docName);
- if (!projectRelPath) {
- // Path-escape — surface the suspicious href in the PropPanel
- // instead of dispatching to OS. `openAssetSafely` in the main
- // process is the defense-in-depth backstop.
- return false;
- }
+ const activation = resolveLinkMarkAssetActivation({
+ href,
+ sourceForm: info?.attrs?.sourceForm,
+ docName,
+ classified: target,
+ });
+ if (activation.kind === 'refused') return false;
+ if (activation.kind === 'asset') {
+ const { url, ext, literal, projectRelPath } = activation;
const cache = getPageListCache();
if (cache === null) return false;
// BOTH partitions participate in the existence
@@ -168,7 +201,7 @@ export const InternalLink = LinkFidelity.extend<InternalLinkOptions>({
// unchanged so we don't refuse to navigate before the first
// /api/documents lands.
if (cache.assetPaths !== undefined || cache.filePaths !== undefined) {
- if (!isResolvedAssetHref(url, docName, cache.assetPaths, cache.filePaths)) {
+ if (!isResolvedAssetHref(url, docName, cache.assetPaths, cache.filePaths, { literal })) {
return false;
}
}
@@ -184,10 +217,12 @@ export const InternalLink = LinkFidelity.extend<InternalLinkOptions>({
if (!target) return false;
- // `target.kind === 'asset'` is excluded by the isAssetShape
- // early-return above, so TypeScript narrows `target` to doc /
- // anchor / external here.
switch (target.kind) {
+ case 'asset':
+ // Unreachable: an asset-classified target always produces an
+ // `asset` or `refused` activation above, both of which return. The
+ // case stays so the DU exhaustiveness guard below keeps compiling.
+ return false;
case 'doc': {
// Missing docs fall through so the popover surfaces "Create page" —
// the only useful action when there's no destination to navigate
diff --git a/packages/app/src/editor/extensions/link-resolution-uniformity.test.ts b/packages/app/src/editor/extensions/link-resolution-uniformity.test.ts
index 0fb610081..cde0f7ea5 100644
--- a/packages/app/src/editor/extensions/link-resolution-uniformity.test.ts
+++ b/packages/app/src/editor/extensions/link-resolution-uniformity.test.ts
@@ -164,7 +164,9 @@ describe('editor resolution state agrees with the canonical server classificatio
// the doc-intent resolver ever runs.
const cache = fixtureCache();
expect(
- isResolvedAssetHref('assets/NOTICE', SOURCE_DOC, cache.assetPaths, cache.filePaths),
+ isResolvedAssetHref('assets/NOTICE', SOURCE_DOC, cache.assetPaths, cache.filePaths, {
+ literal: false,
+ }),
).toBe(true);
setLinkValidationVisible(true);
expect(RESOLVED_STATES).toContain(
@@ -177,7 +179,9 @@ describe('editor resolution state agrees with the canonical server classificatio
// missing document — that is the row the matrix expects Create page on.
const cache = fixtureCache();
expect(
- isResolvedAssetHref('targets/missing-wiki', SOURCE_DOC, cache.assetPaths, cache.filePaths),
+ isResolvedAssetHref('targets/missing-wiki', SOURCE_DOC, cache.assetPaths, cache.filePaths, {
+ literal: false,
+ }),
).toBe(false);
});
diff --git a/packages/app/src/editor/extensions/link-resolution.ts b/packages/app/src/editor/extensions/link-resolution.ts
index b27c917ab..aa510f0ef 100644
--- a/packages/app/src/editor/extensions/link-resolution.ts
+++ b/packages/app/src/editor/extensions/link-resolution.ts
@@ -62,11 +62,21 @@ export function isResolvedAssetHref(
* `/api/documents`). When provided, a markdown-link to an existing
* non-markdown file that's NOT a renderable asset
* (e.g. `[csv](./data/example.csv)`) resolves rather than rendering dead.
- * Absent for legacy callers; the asset-path-only check still applies.
+ * `undefined` keeps the asset-path-only check.
*/
- filePaths?: ReadonlySet<string> | undefined,
+ filePaths: ReadonlySet<string> | undefined,
+ /**
+ * Which plane `href` lives on. Required, and threaded from the caller for
+ * the same reason `resolveAssetProjectPath` requires it: this predicate is
+ * consulted from both the markdown chip surfaces and the wiki-embed
+ * activation path, and picking a default silently reports one plane's
+ * working links as dead.
+ */
+ options: { literal: boolean },
): boolean {
- const projectRelPath = resolveAssetProjectPath(href, sourceDocName);
+ const projectRelPath = resolveAssetProjectPath(href, sourceDocName, {
+ literal: options.literal,
+ });
if (projectRelPath === null) return false;
if (assetPaths && setHasPathCaseInsensitive(assetPaths, projectRelPath)) return true;
if (filePaths && setHasPathCaseInsensitive(filePaths, projectRelPath)) return true;
@@ -106,7 +116,9 @@ export function computeLinkResolutionState(
// are missing from the cache (very old snapshot) we stay optimistic — the
// original invariant.
if (cache.assetPaths === undefined && cache.filePaths === undefined) return 'asset';
- return isResolvedAssetHref(target.url, sourceDocName, cache.assetPaths, cache.filePaths)
+ return isResolvedAssetHref(target.url, sourceDocName, cache.assetPaths, cache.filePaths, {
+ literal: target.literal,
+ })
? 'asset'
: 'unresolved';
}
@@ -123,7 +135,13 @@ export function computeLinkResolutionState(
// identity first, then an exact file hit. Resolving only against `pages` +
// `folderPaths` here means the editor paints a redlink, and offers Create
// page, over a file the server has already proven exists.
- if (isResolvedAssetHref(href, sourceDocName, cache.assetPaths, cache.filePaths)) return 'asset';
+ // `href` reached this branch through `classifyMarkdownHref`, so it is a
+ // markdown destination — a URI whose escapes decode.
+ if (
+ isResolvedAssetHref(href, sourceDocName, cache.assetPaths, cache.filePaths, { literal: false })
+ ) {
+ return 'asset';
+ }
return 'unresolved';
}
diff --git a/packages/app/src/editor/extensions/wiki-link-embed.test.ts b/packages/app/src/editor/extensions/wiki-link-embed.test.ts
index b5d4c05be..52eb67d40 100644
--- a/packages/app/src/editor/extensions/wiki-link-embed.test.ts
+++ b/packages/app/src/editor/extensions/wiki-link-embed.test.ts
@@ -1,5 +1,8 @@
import { describe, expect, test } from 'vitest';
-import { applyWikiLinkEmbedImageDomAttributes } from './wiki-link-embed.ts';
+import {
+ applyWikiLinkEmbedImageDomAttributes,
+ resolveWikiEmbedActivation,
+} from './wiki-link-embed.ts';
interface RecordingElement {
attrs: Map<string, string>;
@@ -51,3 +54,37 @@ describe('applyWikiLinkEmbedImageDomAttributes', () => {
expect(dom.attrs.get('data-alias')).toBe('');
});
});
+
+describe('resolveWikiEmbedActivation', () => {
+ test('keeps percent sequences in a bare wiki target literal', () => {
+ // `![[100%20done.png]]` names a file whose name really contains `%20`, and
+ // `projectRelPath` is what `shell.openPath` / `showItemInFolder` receive.
+ expect(resolveWikiEmbedActivation({ target: '100%20done.png', resolvedSrc: null })).toEqual({
+ url: '100%20done.png',
+ projectRelPath: '100%20done.png',
+ ext: 'png',
+ title: '100%20done.png',
+ });
+ });
+
+ test('a wiki target never resolves to its decoded neighbour', () => {
+ const activation = resolveWikiEmbedActivation({ target: '100%20done.png', resolvedSrc: null });
+ expect(activation?.projectRelPath).not.toBe('100 done.png');
+ expect(activation?.title).not.toBe('100 done.png');
+ });
+
+ test('keeps percent sequences in a drop-time resolvedSrc literal', () => {
+ // `resolvedSrc` is a filesystem path the drop pipeline produced, not a URI.
+ const activation = resolveWikiEmbedActivation({
+ target: '100%20done.png',
+ resolvedSrc: '/media/100%20done.png',
+ });
+ expect(activation?.projectRelPath).toBe('media/100%20done.png');
+ expect(activation?.projectRelPath).not.toBe('media/100 done.png');
+ });
+
+ test('declines a target with no extension and an empty target', () => {
+ expect(resolveWikiEmbedActivation({ target: 'no-extension', resolvedSrc: null })).toBeNull();
+ expect(resolveWikiEmbedActivation({ target: '', resolvedSrc: null })).toBeNull();
+ });
+});
diff --git a/packages/app/src/editor/extensions/wiki-link-embed.ts b/packages/app/src/editor/extensions/wiki-link-embed.ts
index 0c4d5ca63..9625b0f73 100644
--- a/packages/app/src/editor/extensions/wiki-link-embed.ts
+++ b/packages/app/src/editor/extensions/wiki-link-embed.ts
@@ -121,6 +121,44 @@ function isImageExtension(target: string): boolean {
return ext !== null && IMAGE_EXTENSIONS.has(ext);
}
+/**
+ * Resolve a `wikiLinkEmbed` node's attrs into the asset-dispatch payload, or
+ * `null` when the node names nothing openable.
+ *
+ * Drop-time `wikiLinkEmbed` always carries a server-absolute `resolvedSrc`, so
+ * the resolver ignores the source-doc argument. For the `resolvedSrc === null`
+ * edge case (bare target) the empty `sourceDocName` resolves against the
+ * project root — acceptable because drop-time bare targets are root-level
+ * co-located assets. Post-roundtrip asset clicks go through `internal-link.ts`
+ * (link-mark with `sourceForm: 'wikiembed'`), which has the full doc context.
+ *
+ * Wiki plane by construction: both `resolvedSrc` (a drop-time filesystem path)
+ * and the bare `target` are literal filenames, so percent-decoding them would
+ * send `shell.openPath` at a neighbouring file that may not exist.
+ */
+export function resolveWikiEmbedActivation(attrs: {
+ target: string;
+ resolvedSrc: string | null;
+}): { url: string; projectRelPath: string; ext: string; title: string } | null {
+ const target = attrs.target;
+ if (!target) return null;
+ const url = attrs.resolvedSrc && attrs.resolvedSrc.length > 0 ? attrs.resolvedSrc : target;
+ const ext = extractAssetExtension(target);
+ if (ext === null) return null;
+ // A null resolve is the refusal signal — the path escapes the project root, or
+ // the input is malformed. Falling back to the raw target would proceed past a
+ // refusal the sibling link-mark resolver honours, and two activation paths with
+ // opposite failure policies is how an eager-refusal layer goes inert.
+ const projectRelPath = resolveAssetProjectPath(url, '', { literal: true });
+ if (projectRelPath === null) return null;
+ return {
+ url,
+ projectRelPath,
+ ext,
+ title: projectRelPath.split('/').pop() ?? url,
+ };
+}
+
export const WikiLinkEmbed = BaseWikiLinkEmbed.extend({
addNodeView() {
return ({ editor, node, getPos }) => {
@@ -211,32 +249,12 @@ export const WikiLinkEmbed = BaseWikiLinkEmbed.extend({
controls: {},
handlePrimary: ({ newTab }) => {
const live = currentNode.attrs;
- const liveTarget = typeof live.target === 'string' ? live.target : '';
- if (!liveTarget) return false;
- const liveResolvedSrc =
- typeof live.resolvedSrc === 'string' && live.resolvedSrc.length > 0
- ? live.resolvedSrc
- : null;
- const liveUrl = liveResolvedSrc ?? liveTarget;
- const ext = extractAssetExtension(liveTarget);
- if (ext === null) return false;
- // Drop-time wikiLinkEmbed always carries a server-absolute
- // `resolvedSrc`, so the resolver
- // ignores the source-doc argument. For the `resolvedSrc === null`
- // edge case (bare target), we pass empty `sourceDocName` to
- // resolve against project root — acceptable because drop-time
- // bare targets are root-level co-located assets. Post-roundtrip
- // asset clicks go through `internal-link.ts` (link-mark with
- // `sourceForm: 'wikiembed'`) which has the full doc context.
- const projectRelPath = resolveAssetProjectPath(liveUrl, '');
- const rel = projectRelPath ?? liveTarget;
- activateAssetLink({
- url: liveUrl,
- projectRelPath: rel,
- ext,
- title: rel.split('/').pop() ?? liveUrl,
- newTab,
+ const activation = resolveWikiEmbedActivation({
+ target: typeof live.target === 'string' ? live.target : '',
+ resolvedSrc: typeof live.resolvedSrc === 'string' ? live.resolvedSrc : null,
});
+ if (activation === null) return false;
+ activateAssetLink({ ...activation, newTab });
return true;
},
});
diff --git a/packages/app/src/editor/internal-link-helpers.test.ts b/packages/app/src/editor/internal-link-helpers.test.ts
index 48b02094d..10a3630d9 100644
--- a/packages/app/src/editor/internal-link-helpers.test.ts
+++ b/packages/app/src/editor/internal-link-helpers.test.ts
@@ -1,6 +1,8 @@
+import { classifyMarkdownHref } from '@inkeep/open-knowledge-core';
import { afterEach, describe, expect, it, vi } from 'vitest';
import {
activateAssetLink,
+ buildCurrentRelativeMarkdownHref,
handleChipLinkClick,
navigateToMarkdownTarget,
toInternalHashHref,
@@ -217,3 +219,36 @@ describe('toInternalHashHref', () => {
expect(toInternalHashHref({ docName: 'docs/guide', anchor: null })).toBe('#/docs/guide');
});
});
+
+/**
+ * The link-edit popover's URL field writes whatever it holds verbatim as the
+ * href (`setLink({ href: url.trim() })`), and its suggestion picker seeds that
+ * field from `buildCurrentRelativeMarkdownHref`. The field is a URL field —
+ * seeded from the raw href when editing an existing link, and accepting
+ * external URLs unchanged — so the builder's escaped output is the correct
+ * thing to show there. Decoding for display would need a re-encode on apply,
+ * which cannot tell an author's literal `%20` from a display-decoded space.
+ * The user-facing FRIENDLY path is a separate surface: the prop panel shows
+ * `classifyMarkdownHref(...).docName`, which is already decoded.
+ */
+describe('buildCurrentRelativeMarkdownHref — popover field round-trip', () => {
+ it('emits an href that classifies straight back to the picked doc', () => {
+ const href = buildCurrentRelativeMarkdownHref('notes/Agent Memory', null, '#/notes/index');
+ expect(href).toBe('./Agent%20Memory.md');
+ // Applied verbatim by the popover, and read back by every resolution
+ // surface as the doc the user picked — not as a doc literally named
+ // `Agent%20Memory`.
+ expect(classifyMarkdownHref(href, 'notes/index')).toEqual({
+ kind: 'doc',
+ docName: 'notes/Agent Memory',
+ anchor: null,
+ });
+ });
+
+ it('shows the decoded name on the friendly display surface', () => {
+ // The prop panel's `displayHref` is built from the classified docName, so
+ // the escaped bytes never reach the reader there.
+ const classified = classifyMarkdownHref('./Agent%20Memory.md', 'notes/index');
+ expect(classified?.kind === 'doc' && classified.docName).toBe('notes/Agent Memory');
+ });
+});
diff --git a/packages/app/src/editor/plugins/asset-context-menu.test.ts b/packages/app/src/editor/plugins/asset-context-menu.test.ts
index eef02aa88..a1ac0a826 100644
--- a/packages/app/src/editor/plugins/asset-context-menu.test.ts
+++ b/packages/app/src/editor/plugins/asset-context-menu.test.ts
@@ -48,6 +48,27 @@ describe('classifyContextMenuTarget', () => {
});
});
+ test('wiki-embed target keeps its percent sequences literal', () => {
+ // `data-target` is the authored wiki target, so `%20` is three characters
+ // of the filename. Decoding it points Reveal / Open at `100 done.png`.
+ const a = makeEl('a', { 'data-wiki-embed': '', 'data-target': '100%20done.png' });
+ expect(classifyContextMenuTarget(a, 'notes/readme')).toEqual({
+ kind: 'asset',
+ relPath: 'notes/100%20done.png',
+ title: '100%20done.png',
+ });
+ });
+
+ test('wiki-embed target does not resolve to its decoded neighbour', () => {
+ const a = makeEl('a', { 'data-wiki-embed': '', 'data-target': '100%20done.png' });
+ const target = classifyContextMenuTarget(a, 'notes/readme');
+ expect(target?.relPath).not.toBe('notes/100 done.png');
+ // The markdown-href branch of the same walker, given the same bytes, DOES
+ // decode — the two branches are meant to disagree.
+ const anchor = makeEl('a', { href: './100%20done.png' });
+ expect(classifyContextMenuTarget(anchor, 'notes/readme')?.relPath).toBe('notes/100 done.png');
+ });
+
test('wiki-link chip → wiki-link', () => {
const span = makeEl('span', { 'data-wiki-link': '', 'data-target': 'guides/install' });
expect(classifyContextMenuTarget(span, 'docs/readme')).toEqual({
diff --git a/packages/app/src/editor/plugins/asset-context-menu.ts b/packages/app/src/editor/plugins/asset-context-menu.ts
index cc0427141..6b1d114a2 100644
--- a/packages/app/src/editor/plugins/asset-context-menu.ts
+++ b/packages/app/src/editor/plugins/asset-context-menu.ts
@@ -57,7 +57,10 @@ export function classifyContextMenuTarget(
if (cur.hasAttribute('data-wiki-embed')) {
const target = cur.getAttribute('data-target') ?? '';
if (!target) return null;
- const relPath = resolveAssetProjectPath(target, sourceDocName);
+ // `data-target` is the authored wiki target — a literal filename, not a
+ // URI. Decoding it sends Reveal/Open at a neighbouring file that may not
+ // exist (`100%20done.png` is not `100 done.png`).
+ const relPath = resolveAssetProjectPath(target, sourceDocName, { literal: true });
if (!relPath) return null;
const isImg = cur.tagName === 'IMG';
return {
@@ -87,7 +90,9 @@ export function classifyContextMenuTarget(
const href = cur.getAttribute('href') ?? '';
const classified = classifyMarkdownHref(href, sourceDocName);
if (classified?.kind === 'asset') {
- const relPath = resolveAssetProjectPath(classified.url, sourceDocName);
+ const relPath = resolveAssetProjectPath(classified.url, sourceDocName, {
+ literal: classified.literal,
+ });
if (!relPath) return null;
return {
kind: 'asset',
@@ -106,7 +111,9 @@ export function classifyContextMenuTarget(
if (src) {
const classified = classifyMarkdownHref(src, sourceDocName);
if (classified?.kind === 'asset') {
- const relPath = resolveAssetProjectPath(classified.url, sourceDocName);
+ const relPath = resolveAssetProjectPath(classified.url, sourceDocName, {
+ literal: classified.literal,
+ });
if (!relPath) return null;
return {
kind: 'image',
diff --git a/packages/core/src/bridge/bind-frontmatter-doc.ts b/packages/core/src/bridge/bind-frontmatter-doc.ts
index d7a845280..dfd95ef49 100644
--- a/packages/core/src/bridge/bind-frontmatter-doc.ts
+++ b/packages/core/src/bridge/bind-frontmatter-doc.ts
@@ -1,3 +1,4 @@
+
import type * as Y from 'yjs';
import type { Err, Ok, Result } from '../config/result.ts';
import { type FrontmatterValidationError, toFrontmatterIssue } from '../frontmatter/errors.ts';
diff --git a/packages/core/src/bridge/bridge-invariant.ts b/packages/core/src/bridge/bridge-invariant.ts
index 005627195..8bfdb40cd 100644
--- a/packages/core/src/bridge/bridge-invariant.ts
+++ b/packages/core/src/bridge/bridge-invariant.ts
@@ -1,3 +1,4 @@
+
import { fnv1aDigest } from './hash-util.ts';
export type BridgeInvariantSite = 'observer-b' | 'persistence' | 'test-harness';
diff --git a/packages/core/src/bridge/compose.ts b/packages/core/src/bridge/compose.ts
index f4cc8a286..2a597ec3d 100644
--- a/packages/core/src/bridge/compose.ts
+++ b/packages/core/src/bridge/compose.ts
@@ -1,3 +1,4 @@
+
import { prependFrontmatter, stripFrontmatter } from '../extensions/frontmatter.ts';
export type ComposeAdjustment = 'none' | 'body' | 'frontmatter' | 'unresolved';
diff --git a/packages/core/src/bridge/divergence-locate.ts b/packages/core/src/bridge/divergence-locate.ts
index 6b505314d..d979f4b39 100644
--- a/packages/core/src/bridge/divergence-locate.ts
+++ b/packages/core/src/bridge/divergence-locate.ts
@@ -1,3 +1,4 @@
+
import { findFirstDivergenceIndex } from './tolerance-telemetry.ts';
export const BRIDGE_LINE_KINDS = [
diff --git a/packages/core/src/bridge/doc-boundary-space.ts b/packages/core/src/bridge/doc-boundary-space.ts
index 8fb428b90..01ef76a9f 100644
--- a/packages/core/src/bridge/doc-boundary-space.ts
+++ b/packages/core/src/bridge/doc-boundary-space.ts
@@ -1,3 +1,4 @@
+
import { FRONTMATTER_RE, stripFrontmatter } from '../extensions/frontmatter.ts';
import { carriedEdgeEmpties, type DocEdgeEmpties } from '../markdown/doc-edge-blank-runs.ts';
diff --git a/packages/core/src/bridge/growth-detect.ts b/packages/core/src/bridge/growth-detect.ts
index 9d9c244b0..463e89595 100644
--- a/packages/core/src/bridge/growth-detect.ts
+++ b/packages/core/src/bridge/growth-detect.ts
@@ -1,3 +1,4 @@
+
const DEFAULT_MIN_SUBSTANTIVE_LINE_LENGTH = 16;
export const DUPLICATION_GATE_MIN_LINE_LENGTH = 8;
diff --git a/packages/core/src/bridge/intraline-predicate.ts b/packages/core/src/bridge/intraline-predicate.ts
index c43fdd7e7..0939885bb 100644
--- a/packages/core/src/bridge/intraline-predicate.ts
+++ b/packages/core/src/bridge/intraline-predicate.ts
@@ -1,3 +1,4 @@
+
export function rawLineCounts(doc: string): Map<string, number> {
const counts = new Map<string, number>();
for (const line of doc.split('\n')) {
diff --git a/packages/core/src/bridge/merge-three-way.ts b/packages/core/src/bridge/merge-three-way.ts
index 251560a35..c0dc65705 100644
--- a/packages/core/src/bridge/merge-three-way.ts
+++ b/packages/core/src/bridge/merge-three-way.ts
@@ -65,6 +65,7 @@ export function tryLineLevelCombine(
return { clean: true, merged };
}
+
export type BridgeMergeContentLossSide = 'user' | 'agent';
export type BridgeMergeContentLossWhich = 'substring' | 'order' | 'growth';
diff --git a/packages/core/src/bridge/normalize.ts b/packages/core/src/bridge/normalize.ts
index 01ac80099..dcc5b0690 100644
--- a/packages/core/src/bridge/normalize.ts
+++ b/packages/core/src/bridge/normalize.ts
@@ -1,3 +1,4 @@
+
import { stripFrontmatter } from '../extensions/frontmatter.ts';
import { bodyEdgeEmpties } from './doc-boundary-space.ts';
diff --git a/packages/core/src/bridge/pm-structural-equivalence.ts b/packages/core/src/bridge/pm-structural-equivalence.ts
index 754dc5cc2..0be5203e4 100644
--- a/packages/core/src/bridge/pm-structural-equivalence.ts
+++ b/packages/core/src/bridge/pm-structural-equivalence.ts
@@ -32,6 +32,7 @@ const BR_SENTINEL: PmStructuralNode = { type: '__br__' };
const BR_LITERAL_RE = /^<br\s*\/?>$/i;
+
interface DegradeEntry {
readonly label: string;
readonly severity: ToleranceClassSeverity;
@@ -127,6 +128,7 @@ export interface ComparePmStructuralOptions {
ignoreAttrs?: (attrKey: string) => boolean;
}
+
/** Rebuild a node with `fn` applied to each child; identity when childless.
* Shared by the degrade canonicalizers so none re-implements the walk. */
function mapChildren(
@@ -248,6 +250,7 @@ function applyDegrades(tree: PmStructuralNode): {
return { normalized: current, fired };
}
+
export function comparePmStructural(
expected: PmStructuralNode,
actual: PmStructuralNode,
diff --git a/packages/core/src/bridge/subsequence.ts b/packages/core/src/bridge/subsequence.ts
index af20de1e2..dca644141 100644
--- a/packages/core/src/bridge/subsequence.ts
+++ b/packages/core/src/bridge/subsequence.ts
@@ -1,3 +1,4 @@
+
/** True when `needle` is a subsequence of `haystack` (two-pointer, O(n+m)):
* insertions in `haystack` are free; any dropped or substituted `needle` byte
* fails. */
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 8d7590d1c..f609121f8 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -1963,11 +1963,18 @@ export {
type ExternalLinkTarget,
extractAssetExtension,
isExternalHref,
+ type ResolveAssetProjectPathOptions,
resolveAssetProjectPath,
} from './utils/link-targets.ts';
export { type BasenameIndex, createBasenameIndex } from './utils/path-resolve.ts';
export { randomUUID } from './utils/random-uuid.ts';
-export { type ResolvedInternalHref, resolveInternalHref } from './utils/resolve-internal-href.ts';
+export {
+ decodeHrefPath,
+ encodeHrefPath,
+ encodeHrefPathSegment,
+ type ResolvedInternalHref,
+ resolveInternalHref,
+} from './utils/resolve-internal-href.ts';
export { sanitizeFolderName } from './utils/sanitize-folder-name.ts';
export { sleep } from './utils/sleep.ts';
export {
diff --git a/packages/core/src/markdown/callout-transformer.ts b/packages/core/src/markdown/callout-transformer.ts
index 83d47404a..a363dfd54 100644
--- a/packages/core/src/markdown/callout-transformer.ts
+++ b/packages/core/src/markdown/callout-transformer.ts
@@ -1,3 +1,4 @@
+
import type { Blockquote, Paragraph, Root } from 'mdast';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/code-fence.ts b/packages/core/src/markdown/code-fence.ts
index 9807a7e82..4499dbc92 100644
--- a/packages/core/src/markdown/code-fence.ts
+++ b/packages/core/src/markdown/code-fence.ts
@@ -1,3 +1,4 @@
+
export function selectFenceChar(info: string): '`' | '~' {
return info.includes('`') ? '~' : '`';
}
diff --git a/packages/core/src/markdown/comment-promoter.ts b/packages/core/src/markdown/comment-promoter.ts
index 7415c474a..34704165b 100644
--- a/packages/core/src/markdown/comment-promoter.ts
+++ b/packages/core/src/markdown/comment-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Paragraph, PhrasingContent, Root, RootContent, Text } from 'mdast';
import { SKIP, visit } from 'unist-util-visit';
import type { VFile } from 'vfile';
diff --git a/packages/core/src/markdown/dedent-block-jsx-close.ts b/packages/core/src/markdown/dedent-block-jsx-close.ts
index ece5c02a1..b6299a948 100644
--- a/packages/core/src/markdown/dedent-block-jsx-close.ts
+++ b/packages/core/src/markdown/dedent-block-jsx-close.ts
@@ -1,3 +1,4 @@
+
import { findFencedRegions, isInsideFence } from './fence-regions.ts';
const INDENTED_BLOCK_JSX_CLOSE_RE = /^([ ]{1,3})(<\/[A-Z][A-Za-z0-9_]*\s*>)([ \t]*)$/gm;
diff --git a/packages/core/src/markdown/details-accordion-promoter.ts b/packages/core/src/markdown/details-accordion-promoter.ts
index 54774764a..acd398aa6 100644
--- a/packages/core/src/markdown/details-accordion-promoter.ts
+++ b/packages/core/src/markdown/details-accordion-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Paragraph, Parent, Root, Text } from 'mdast';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/div-align-promoter.ts b/packages/core/src/markdown/div-align-promoter.ts
index 43ecdc709..ba9b56384 100644
--- a/packages/core/src/markdown/div-align-promoter.ts
+++ b/packages/core/src/markdown/div-align-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Paragraph, Parent, Root, Text } from 'mdast';
import type { MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/fence-regions.ts b/packages/core/src/markdown/fence-regions.ts
index 6d3f3643e..4513da9bb 100644
--- a/packages/core/src/markdown/fence-regions.ts
+++ b/packages/core/src/markdown/fence-regions.ts
@@ -1,3 +1,4 @@
+
const FENCE_RE = /^(`{3,}|~{3,})/gm;
export function findFencedRegions(src: string): Array<[number, number]> {
diff --git a/packages/core/src/markdown/fixtures/index.ts b/packages/core/src/markdown/fixtures/index.ts
index 00f5771ee..6931623c7 100644
--- a/packages/core/src/markdown/fixtures/index.ts
+++ b/packages/core/src/markdown/fixtures/index.ts
@@ -1,3 +1,4 @@
+
import { readFileSync } from 'node:fs';
import { dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
@@ -8,6 +9,7 @@ function fixturePath(...segments: string[]): string {
return resolve(FIXTURES_DIR, ...segments);
}
+
interface GfmExample {
section: string;
markdown: string;
@@ -17,6 +19,7 @@ export function loadGfmExamples(): GfmExample[] {
return JSON.parse(readFileSync(fixturePath('gfm', 'examples.json'), 'utf8')) as GfmExample[];
}
+
interface MdxCrashEntry {
id: string;
input: string;
@@ -68,6 +71,7 @@ export function loadLargeEmbedFixtures(): LargeEmbedFixture[] {
) as LargeEmbedFixture[];
}
+
export function loadPrd6955Before(): string {
return readFileSync(fixturePath('regression', 'prd-6955-before.md'), 'utf8');
}
@@ -76,6 +80,7 @@ export function loadPrd6955CorruptedTriplicated(): string {
return readFileSync(fixturePath('regression', 'prd-6955-corrupted-triplicated.md'), 'utf8');
}
+
export interface NgPinnedCase {
id: string;
name: string;
@@ -92,6 +97,7 @@ export function loadNgPinnedCases(): NgPinnedCase[] {
) as NgPinnedCase[];
}
+
export function loadLargeRealistic(): string {
return readFileSync(fixturePath('perf', 'large-realistic.md'), 'utf8');
}
diff --git a/packages/core/src/markdown/fixtures/perf/generate.ts b/packages/core/src/markdown/fixtures/perf/generate.ts
index 8b1eb8519..daa3ef82b 100644
--- a/packages/core/src/markdown/fixtures/perf/generate.ts
+++ b/packages/core/src/markdown/fixtures/perf/generate.ts
@@ -1,3 +1,4 @@
+
import { writeFileSync } from 'node:fs';
import { dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
@@ -10,6 +11,7 @@ const BASELINE_ONLY_COUNTS = [500, 2500] as const;
const SEED = 0xf1de1117;
+
function mulberry32(seed: number): () => number {
let a = seed >>> 0;
return () => {
@@ -36,6 +38,7 @@ function pickWeighted<T>(rand: () => number, items: readonly [T, number][]): T {
return items[items.length - 1][0];
}
+
const WORDS = [
'lorem',
'ipsum',
@@ -153,6 +156,7 @@ function mdxBlock(rand: () => number): string {
return `<${name}>\n\n${sentence(rand)}\n\n</${name}>`;
}
+
type BlockKind = 'paragraph' | 'heading' | 'list' | 'code' | 'table' | 'mdx';
const MIX: readonly [BlockKind, number][] = [
@@ -191,6 +195,7 @@ function generateDocument(blockCount: number, seed: number): string {
return `${blocks.join('\n\n')}\n`;
}
+
function main(): void {
for (const count of [...BLOCK_COUNTS, ...BASELINE_ONLY_COUNTS]) {
const doc = generateDocument(count, SEED);
diff --git a/packages/core/src/markdown/guard-flanking-matrix.ts b/packages/core/src/markdown/guard-flanking-matrix.ts
index 420dc0fe5..32c055c5b 100644
--- a/packages/core/src/markdown/guard-flanking-matrix.ts
+++ b/packages/core/src/markdown/guard-flanking-matrix.ts
@@ -7,6 +7,7 @@ import {
import { BACKSLASH_GUARD_SUBSTITUTIONS, encodeBackslashEscapes } from './backslash-escape-guard.ts';
import { ENTITY_REF_GUARD_SUBSTITUTIONS, encodeEntityRefs } from './entity-ref-guard.ts';
+
export const ATTENTION_DELIMITERS = ['*', '_', '**', '~~', '=='] as const;
export type FlankClass = 'whitespace' | 'punctuation' | 'other';
diff --git a/packages/core/src/markdown/handler-shadow-audit.ts b/packages/core/src/markdown/handler-shadow-audit.ts
index 2653473da..283913255 100644
--- a/packages/core/src/markdown/handler-shadow-audit.ts
+++ b/packages/core/src/markdown/handler-shadow-audit.ts
@@ -1,3 +1,4 @@
+
export interface HandlerShadowWitness {
input: string;
expect: 'byte' | 'byte-and-reparse-type';
diff --git a/packages/core/src/markdown/highlight-promoter.ts b/packages/core/src/markdown/highlight-promoter.ts
index da0a81d23..5d1000cc4 100644
--- a/packages/core/src/markdown/highlight-promoter.ts
+++ b/packages/core/src/markdown/highlight-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Parent, PhrasingContent, Root, Text } from 'mdast';
import type { MdxJsxTextElement } from 'mdast-util-mdx';
import { SKIP, visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/html-to-mdast.ts b/packages/core/src/markdown/html-to-mdast.ts
index 787315157..9681c0056 100644
--- a/packages/core/src/markdown/html-to-mdast.ts
+++ b/packages/core/src/markdown/html-to-mdast.ts
@@ -1,3 +1,4 @@
+
import type { Element as HastElement, Root as HastRoot } from 'hast';
import type { List, Nodes as MdastNodes, Root as MdastRoot } from 'mdast';
import rehypeParse from 'rehype-parse';
@@ -128,7 +129,8 @@ export function htmlToMdast(html: string, options?: HtmlToMdastOptions): MdastRo
throw new HtmlPayloadTooLargeError(html.length, maxBytes);
}
- const processor = unified().use(rehypeParse, { fragment: true });
+ const processor = unified()
+ .use(rehypeParse, { fragment: true });
for (const plugin of cleanupPlugins) {
processor.use(plugin);
diff --git a/packages/core/src/markdown/image-promoter.ts b/packages/core/src/markdown/image-promoter.ts
index 706fa9afb..994eb6917 100644
--- a/packages/core/src/markdown/image-promoter.ts
+++ b/packages/core/src/markdown/image-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Image, Paragraph, Root } from 'mdast';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/index.ts b/packages/core/src/markdown/index.ts
index 779e27500..ec1ac1b7e 100644
--- a/packages/core/src/markdown/index.ts
+++ b/packages/core/src/markdown/index.ts
@@ -1,3 +1,4 @@
+
import {
type FromProseMirrorOptions,
fromPmMark,
@@ -206,6 +207,7 @@ export class MarkdownManager {
}
}
+
const registry = createRegistry();
function destructureAttrs(
@@ -254,6 +256,7 @@ function destructureAttrs(
return result;
}
+
function hasDirtyDescendant(node: PmNode): boolean {
let found = false;
node.descendants((child) => {
@@ -276,6 +279,7 @@ function effectiveDirty(node: PmNode, freshnessChecker?: StructuralFreshnessChec
return freshnessChecker ? freshnessChecker.isDiverged(node.toJSON()) : false;
}
+
function isEmptyMdastParagraph(node: MdastNodes): boolean {
if (node.type !== 'paragraph') return false;
const children = node.children ?? [];
@@ -344,6 +348,7 @@ function extractTextFromMdastNodes(nodes: MdastNodes[]): string {
return out;
}
+
import {
AUDIO_EXTENSIONS,
FILE_ATTACHMENT_EXTENSIONS,
@@ -596,6 +601,7 @@ function buildMdastToPmHandlers(
}));
}
+
if (m.emphasis) {
handlers.emphasis = toPmMark(m.emphasis, (node: Emphasis) => ({
sourceDelimiter: node.data?.sourceDelimiter ?? '*',
@@ -676,6 +682,7 @@ function buildMdastToPmHandlers(
}));
}
+
if (m.link) {
const sourceLiteralMark = m.sourceLiteral;
handlers.link = (node: Link, _parent: MdastParent, state: MdastToPmState) => {
@@ -973,6 +980,7 @@ function buildMdastToPmHandlers(
};
}
+
const blockUnknownHandler = (node: {
type: string;
position?: { start: { offset: number }; end: { offset: number } };
@@ -1098,6 +1106,7 @@ function buildMdastToPmHandlers(
return handlers as RemarkProseMirrorOptions['handlers'];
}
+
function buildPmToMdastHandlers(
schema: Schema,
freshness: FreshnessCheckerHolder,
diff --git a/packages/core/src/markdown/lint/applies-to.ts b/packages/core/src/markdown/lint/applies-to.ts
index fa0be9e86..b79e9aef7 100644
--- a/packages/core/src/markdown/lint/applies-to.ts
+++ b/packages/core/src/markdown/lint/applies-to.ts
@@ -1,3 +1,4 @@
+
import picomatch from 'picomatch';
import { SUPPORTED_DOC_EXTENSIONS } from '../../constants/doc-extensions.ts';
diff --git a/packages/core/src/markdown/lint/config-files.ts b/packages/core/src/markdown/lint/config-files.ts
index 312c9c74b..94b34dee1 100644
--- a/packages/core/src/markdown/lint/config-files.ts
+++ b/packages/core/src/markdown/lint/config-files.ts
@@ -1,3 +1,4 @@
+
const MARKDOWNLINT_JSON_CONFIG_FILES: ReadonlySet<string> = new Set([
'.markdownlint.json',
'.markdownlint.jsonc',
diff --git a/packages/core/src/markdown/lint/config-schemas.ts b/packages/core/src/markdown/lint/config-schemas.ts
index 1a81aa524..fbbd309df 100644
--- a/packages/core/src/markdown/lint/config-schemas.ts
+++ b/packages/core/src/markdown/lint/config-schemas.ts
@@ -52,6 +52,7 @@ const fullPluginShape = Object.fromEntries(
LINT_PLUGINS.map((plugin) => [plugin.id, plugin.sliceSchema]),
) as z.ZodRawShape;
+
export const LinterConfigSchema = z.object({
enabled: z.boolean(),
plugins: z.object(fullPluginShape),
diff --git a/packages/core/src/markdown/lint/default-config.ts b/packages/core/src/markdown/lint/default-config.ts
index d48eea5e4..a51f2ffb0 100644
--- a/packages/core/src/markdown/lint/default-config.ts
+++ b/packages/core/src/markdown/lint/default-config.ts
@@ -6,6 +6,7 @@ export const DEFAULT_MARKDOWNLINT_CONFIG: Record<string, MarkdownlintRuleSetting
MD013: false,
};
+
export function resolveMarkdownlintConfig(
rules: Record<string, MarkdownlintRuleSetting> | undefined,
): Configuration {
diff --git a/packages/core/src/markdown/lint/frontmatter-schema-edit.ts b/packages/core/src/markdown/lint/frontmatter-schema-edit.ts
index ef478e268..9c9542661 100644
--- a/packages/core/src/markdown/lint/frontmatter-schema-edit.ts
+++ b/packages/core/src/markdown/lint/frontmatter-schema-edit.ts
@@ -1,3 +1,4 @@
+
import { CANONICAL_SCHEMA_DIALECT_URIS, DEFAULT_SCHEMA_DIALECT } from './frontmatter-validate.ts';
export interface FrontmatterFieldConstraint {
diff --git a/packages/core/src/markdown/lint/frontmatter-validate.ts b/packages/core/src/markdown/lint/frontmatter-validate.ts
index 5f953d667..b0e7833fd 100644
--- a/packages/core/src/markdown/lint/frontmatter-validate.ts
+++ b/packages/core/src/markdown/lint/frontmatter-validate.ts
@@ -1,3 +1,4 @@
+
import Ajv, { type ValidateFunction } from 'ajv';
import Ajv2019 from 'ajv/dist/2019.js';
import Ajv2020 from 'ajv/dist/2020.js';
diff --git a/packages/core/src/markdown/lint/index.ts b/packages/core/src/markdown/lint/index.ts
index 11b5abdfd..ffd277a90 100644
--- a/packages/core/src/markdown/lint/index.ts
+++ b/packages/core/src/markdown/lint/index.ts
@@ -1,3 +1,4 @@
+
import { LINT_PLUGINS, type LinterConfig } from './plugins.ts';
import type { LintDiagnostic } from './types.ts';
diff --git a/packages/core/src/markdown/lint/okf-frontmatter/materialize.ts b/packages/core/src/markdown/lint/okf-frontmatter/materialize.ts
index 7a5af097e..f438f1b16 100644
--- a/packages/core/src/markdown/lint/okf-frontmatter/materialize.ts
+++ b/packages/core/src/markdown/lint/okf-frontmatter/materialize.ts
@@ -1,3 +1,4 @@
+
import type { OkfRuleId } from '../okf-rule-meta.ts';
import { fileNameFor, OKF_SCHEMA_DIR, okfSchemaPathFor } from './paths.ts';
import { OKF_FRONTMATTER_REGISTRY } from './registry.ts';
diff --git a/packages/core/src/markdown/lint/okf-frontmatter/paths.ts b/packages/core/src/markdown/lint/okf-frontmatter/paths.ts
index 1ee913527..c290b6878 100644
--- a/packages/core/src/markdown/lint/okf-frontmatter/paths.ts
+++ b/packages/core/src/markdown/lint/okf-frontmatter/paths.ts
@@ -1,3 +1,4 @@
+
import type { OkfRuleId } from '../okf-rule-meta.ts';
export const OKF_SCHEMA_DIR = '.ok/okf';
diff --git a/packages/core/src/markdown/lint/okf-frontmatter/registry.ts b/packages/core/src/markdown/lint/okf-frontmatter/registry.ts
index f325fbbb4..53ecb619d 100644
--- a/packages/core/src/markdown/lint/okf-frontmatter/registry.ts
+++ b/packages/core/src/markdown/lint/okf-frontmatter/registry.ts
@@ -1,3 +1,4 @@
+
import { compileAppliesTo } from '../applies-to.ts';
import { validateFrontmatterSource } from '../frontmatter-validate.ts';
import {
diff --git a/packages/core/src/markdown/lint/okf-frontmatter/schemas.ts b/packages/core/src/markdown/lint/okf-frontmatter/schemas.ts
index f1c37671b..89845d3d5 100644
--- a/packages/core/src/markdown/lint/okf-frontmatter/schemas.ts
+++ b/packages/core/src/markdown/lint/okf-frontmatter/schemas.ts
@@ -1,3 +1,4 @@
+
// file-level form is deliberate: the sibling `biome-ignore` must sit on the line
// oxlint-disable unicorn/no-thenable
diff --git a/packages/core/src/markdown/lint/okf-project/rules.ts b/packages/core/src/markdown/lint/okf-project/rules.ts
index 6d691ae2b..8b476332e 100644
--- a/packages/core/src/markdown/lint/okf-project/rules.ts
+++ b/packages/core/src/markdown/lint/okf-project/rules.ts
@@ -1,3 +1,4 @@
+
import { SUPPORTED_DOC_EXTENSIONS } from '../../../constants/doc-extensions.ts';
import { isOkfRuleEnabled, type OkfRuleId, type OkfRuleToggles } from '../okf-rule-meta.ts';
diff --git a/packages/core/src/markdown/lint/okf-rule-meta.ts b/packages/core/src/markdown/lint/okf-rule-meta.ts
index 4de50d79f..44913a9dc 100644
--- a/packages/core/src/markdown/lint/okf-rule-meta.ts
+++ b/packages/core/src/markdown/lint/okf-rule-meta.ts
@@ -1,3 +1,4 @@
+
export const OKF_RULE_IDS = [
'no-wiki-links',
'log-shape',
diff --git a/packages/core/src/markdown/lint/okf-rules.ts b/packages/core/src/markdown/lint/okf-rules.ts
index 1d5538421..d0999b62e 100644
--- a/packages/core/src/markdown/lint/okf-rules.ts
+++ b/packages/core/src/markdown/lint/okf-rules.ts
@@ -1,3 +1,4 @@
+
import { isOkfRuleEnabled, type OkfRuleId, type OkfRuleToggles } from './okf-rule-meta.ts';
import type { OkfRule } from './okf-runner.ts';
import { indexShape } from './rules/index-shape.ts';
diff --git a/packages/core/src/markdown/lint/okf-runner.ts b/packages/core/src/markdown/lint/okf-runner.ts
index de130e3f4..fabb08d6e 100644
--- a/packages/core/src/markdown/lint/okf-runner.ts
+++ b/packages/core/src/markdown/lint/okf-runner.ts
@@ -1,3 +1,4 @@
+
import type { Root } from 'mdast';
import remarkFrontmatter from 'remark-frontmatter';
import remarkGfm from 'remark-gfm';
diff --git a/packages/core/src/markdown/lint/plugins.ts b/packages/core/src/markdown/lint/plugins.ts
index 09c8450ee..0a089990e 100644
--- a/packages/core/src/markdown/lint/plugins.ts
+++ b/packages/core/src/markdown/lint/plugins.ts
@@ -1,3 +1,4 @@
+
import { z } from 'zod';
import { DEFAULT_MARKDOWNLINT_CONFIG, resolveMarkdownlintConfig } from './default-config.ts';
import {
@@ -23,6 +24,7 @@ import {
type OkfSlice,
} from './types.ts';
+
const MarkdownlintRuleSettingSchema = z.union([
z.boolean(),
z.enum(MARKDOWNLINT_RULE_SEVERITIES),
diff --git a/packages/core/src/markdown/lint/rules/index-shape.ts b/packages/core/src/markdown/lint/rules/index-shape.ts
index 59fe9b87d..fcbb1b56c 100644
--- a/packages/core/src/markdown/lint/rules/index-shape.ts
+++ b/packages/core/src/markdown/lint/rules/index-shape.ts
@@ -1,3 +1,4 @@
+
import type { List, ListItem } from 'mdast';
import { EXIT, visit } from 'unist-util-visit';
import { defineScopedOkfRule } from '../okf-runner.ts';
diff --git a/packages/core/src/markdown/lint/rules/log-shape.ts b/packages/core/src/markdown/lint/rules/log-shape.ts
index e0159519f..431e4e9c8 100644
--- a/packages/core/src/markdown/lint/rules/log-shape.ts
+++ b/packages/core/src/markdown/lint/rules/log-shape.ts
@@ -1,3 +1,4 @@
+
import type { Heading } from 'mdast';
import { toString as headingText } from 'mdast-util-to-string';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/lint/rules/no-wiki-links.ts b/packages/core/src/markdown/lint/rules/no-wiki-links.ts
index 2123e977f..f75a04d15 100644
--- a/packages/core/src/markdown/lint/rules/no-wiki-links.ts
+++ b/packages/core/src/markdown/lint/rules/no-wiki-links.ts
@@ -1,3 +1,4 @@
+
import type { Point } from 'unist';
import { visit } from 'unist-util-visit';
import { defineOkfRule } from '../okf-runner.ts';
diff --git a/packages/core/src/markdown/lint/rules/reserved-casing.ts b/packages/core/src/markdown/lint/rules/reserved-casing.ts
index 89ef3e4a9..c8b4d8f28 100644
--- a/packages/core/src/markdown/lint/rules/reserved-casing.ts
+++ b/packages/core/src/markdown/lint/rules/reserved-casing.ts
@@ -1,3 +1,4 @@
+
import { SUPPORTED_DOC_EXTENSIONS } from '../../../constants/doc-extensions.ts';
import { defineOkfRule } from '../okf-runner.ts';
diff --git a/packages/core/src/markdown/lint/types.ts b/packages/core/src/markdown/lint/types.ts
index 6836b962d..c04fa4de0 100644
--- a/packages/core/src/markdown/lint/types.ts
+++ b/packages/core/src/markdown/lint/types.ts
@@ -1,3 +1,4 @@
+
import type { BrokenLinkReason } from '../../schemas/api/agent-write.ts';
import type { OkfRuleId } from './okf-rule-meta.ts';
@@ -112,6 +113,7 @@ export interface OkfSlice {
generate?: { index?: boolean };
}
+
interface RuleOptionSpecBase {
key: string;
description: string;
diff --git a/packages/core/src/markdown/lint/validation-counts.ts b/packages/core/src/markdown/lint/validation-counts.ts
index 98238656e..437cc539a 100644
--- a/packages/core/src/markdown/lint/validation-counts.ts
+++ b/packages/core/src/markdown/lint/validation-counts.ts
@@ -1,3 +1,4 @@
+
export interface ValidationSourceCounts {
errorCount: number;
warningCount: number;
diff --git a/packages/core/src/markdown/math-promoter.ts b/packages/core/src/markdown/math-promoter.ts
index a5b511f25..bd79424c7 100644
--- a/packages/core/src/markdown/math-promoter.ts
+++ b/packages/core/src/markdown/math-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Code, Root } from 'mdast';
import type { Math as MdastMath } from 'mdast-util-math';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
diff --git a/packages/core/src/markdown/mdast-to-hast-handlers.ts b/packages/core/src/markdown/mdast-to-hast-handlers.ts
index ed89371d0..00fbc0035 100644
--- a/packages/core/src/markdown/mdast-to-hast-handlers.ts
+++ b/packages/core/src/markdown/mdast-to-hast-handlers.ts
@@ -1,3 +1,4 @@
+
import type { Comment, Element, ElementContent, Properties } from 'hast';
import type { FootnoteDefinition, FootnoteReference } from 'mdast';
import type { MdxJsxFlowElement, MdxJsxTextElement } from 'mdast-util-mdx';
diff --git a/packages/core/src/markdown/mdast-to-html.ts b/packages/core/src/markdown/mdast-to-html.ts
index 8ce2b2492..df788a80d 100644
--- a/packages/core/src/markdown/mdast-to-html.ts
+++ b/packages/core/src/markdown/mdast-to-html.ts
@@ -1,3 +1,4 @@
+
import type { Element, Root as HastRoot, Text as HastText } from 'hast';
import type { Root as MdastRoot, Text as MdastText } from 'mdast';
import type { Handler } from 'mdast-util-to-hast';
diff --git a/packages/core/src/markdown/merged-walker.ts b/packages/core/src/markdown/merged-walker.ts
index bfd7e3109..fa3cfcd86 100644
--- a/packages/core/src/markdown/merged-walker.ts
+++ b/packages/core/src/markdown/merged-walker.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Parent, Root } from 'mdast';
import { SKIP, visit } from 'unist-util-visit';
import type { VFile } from 'vfile';
diff --git a/packages/core/src/markdown/mermaid-promoter.ts b/packages/core/src/markdown/mermaid-promoter.ts
index 1a897fca8..17ed2b829 100644
--- a/packages/core/src/markdown/mermaid-promoter.ts
+++ b/packages/core/src/markdown/mermaid-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Code, Root } from 'mdast';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/parse-with-fallback.ts b/packages/core/src/markdown/parse-with-fallback.ts
index d988f4b8b..4aa0490c4 100644
--- a/packages/core/src/markdown/parse-with-fallback.ts
+++ b/packages/core/src/markdown/parse-with-fallback.ts
@@ -168,6 +168,7 @@ export function parseRecursive(
}
}
+
interface VFilePlace {
offset?: number;
start?: { offset?: number };
@@ -186,6 +187,7 @@ function extractErrorOffset(err: unknown): number | undefined {
return undefined;
}
+
interface Region {
start: number;
end: number;
@@ -209,6 +211,7 @@ function nearestBlankLineAfter(src: string, offset: number): number | null {
return null;
}
+
export interface TagEvent {
kind: 'open' | 'close' | 'self-close';
name: string;
@@ -355,6 +358,7 @@ function findFallbackRegion(src: string, errorOffset: number): Region {
return { start: blockStart, end: blockEnd };
}
+
interface SourceBlock {
src: string;
start: number;
@@ -452,6 +456,7 @@ function tryPerBlockFallback(
};
}
+
function wholeDocRawText(source: string): JSONContent {
return {
type: 'doc',
diff --git a/packages/core/src/markdown/parser-drop-closure.ts b/packages/core/src/markdown/parser-drop-closure.ts
index e6ab4fd57..43d420187 100644
--- a/packages/core/src/markdown/parser-drop-closure.ts
+++ b/packages/core/src/markdown/parser-drop-closure.ts
@@ -1,3 +1,4 @@
+
export type DroppedTokenAdjudication =
| {
kind: 'format-dof-axis';
diff --git a/packages/core/src/markdown/pipeline.ts b/packages/core/src/markdown/pipeline.ts
index 0e3224206..55736041c 100644
--- a/packages/core/src/markdown/pipeline.ts
+++ b/packages/core/src/markdown/pipeline.ts
@@ -1,3 +1,4 @@
+
import {
type FromProseMirrorOptions,
fromProseMirror,
diff --git a/packages/core/src/markdown/position-aware-join.ts b/packages/core/src/markdown/position-aware-join.ts
index 91cdf658f..ccf06e94d 100644
--- a/packages/core/src/markdown/position-aware-join.ts
+++ b/packages/core/src/markdown/position-aware-join.ts
@@ -1,3 +1,4 @@
+
import type { Join } from 'mdast-util-to-markdown';
import type { Position } from 'unist';
import { isBlankLineParagraph } from './zero-emission-blocks.ts';
diff --git a/packages/core/src/markdown/position-slice.ts b/packages/core/src/markdown/position-slice.ts
index 0f399d34c..e5b4c9eba 100644
--- a/packages/core/src/markdown/position-slice.ts
+++ b/packages/core/src/markdown/position-slice.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Root } from 'mdast';
import { visit } from 'unist-util-visit';
import type { VFile } from 'vfile';
@@ -476,7 +477,8 @@ export function applyPositionSliceToNode(
const first = source[startOff];
if (first !== '[' && first !== '<' && !node.title) {
node.data.sourceStyle = 'gfm-autolink';
- } else if (first === '[') {
+ }
+ else if (first === '[') {
const slice = source.slice(startOff, endOff);
const closeBracketIdx = slice.lastIndexOf('](');
if (closeBracketIdx !== -1) {
diff --git a/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts b/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts
index db10fa54b..ca225ce9b 100644
--- a/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts
+++ b/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts
@@ -1,3 +1,4 @@
+
import type { Comment, Element, Root, Text } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts b/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts
index 34068d103..3a2524a9a 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts
@@ -1,3 +1,4 @@
+
import type { Element, ElementContent, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts b/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts
index 93151d43b..2279a0189 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts
@@ -1,3 +1,4 @@
+
import type { Element, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts b/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts
index 188f02d83..a0f467c42 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts
@@ -1,3 +1,4 @@
+
import type { Element, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts b/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts
index 4ba2c3418..4e8542a21 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts
@@ -1,3 +1,4 @@
+
import type { Element, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts b/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts
index 1a74b1272..a3c96b24a 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts
@@ -1,3 +1,4 @@
+
import type { Element, ElementContent, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts b/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts
index de35e7b79..e95cf43d6 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts
@@ -1,3 +1,4 @@
+
import type { Comment, Element, ElementContent, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts b/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts
index b4be1b2ea..ffdb4d5b5 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts
@@ -1,3 +1,4 @@
+
import type { Element, ElementContent, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts b/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts
index 3c8d88b7c..e2a96d1a7 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts
@@ -1,3 +1,4 @@
+
import type { Element, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/resolve-image-url.ts b/packages/core/src/markdown/resolve-image-url.ts
index cf2c9da8e..0389575ac 100644
--- a/packages/core/src/markdown/resolve-image-url.ts
+++ b/packages/core/src/markdown/resolve-image-url.ts
@@ -1,3 +1,4 @@
+
import { isRelativeUrl } from './safe-url.ts';
function isDevDiagnosticContext(): boolean {
diff --git a/packages/core/src/markdown/safe-url.ts b/packages/core/src/markdown/safe-url.ts
index 4d3250d3a..8be632ba4 100644
--- a/packages/core/src/markdown/safe-url.ts
+++ b/packages/core/src/markdown/safe-url.ts
@@ -1,3 +1,4 @@
+
export const SAFE_URL_SCHEMES = ['https', 'http', 'mailto', 'tel', 'ftp', 'sms'] as const;
const SCHEME_ALT = SAFE_URL_SCHEMES.map((s) => `${s}:`).join('|');
diff --git a/packages/core/src/markdown/serialize-fidelity.test-helper.ts b/packages/core/src/markdown/serialize-fidelity.test-helper.ts
index 0dd54070e..96304e7a5 100644
--- a/packages/core/src/markdown/serialize-fidelity.test-helper.ts
+++ b/packages/core/src/markdown/serialize-fidelity.test-helper.ts
@@ -1,3 +1,4 @@
+
import type { JSONContent } from '@tiptap/core';
import type { Nodes } from 'mdast';
import { expect } from 'vitest';
diff --git a/packages/core/src/markdown/serialize-helpers.ts b/packages/core/src/markdown/serialize-helpers.ts
index 7cac5b042..93798cf83 100644
--- a/packages/core/src/markdown/serialize-helpers.ts
+++ b/packages/core/src/markdown/serialize-helpers.ts
@@ -1,3 +1,4 @@
+
import type { Node as PmNode } from '@tiptap/pm/model';
import type {
MdxJsxAttribute,
diff --git a/packages/core/src/markdown/single-dollar-math-promoter.ts b/packages/core/src/markdown/single-dollar-math-promoter.ts
index b012a5aff..8c08b7a04 100644
--- a/packages/core/src/markdown/single-dollar-math-promoter.ts
+++ b/packages/core/src/markdown/single-dollar-math-promoter.ts
@@ -1,3 +1,4 @@
+
import type { PhrasingContent, Root, Text } from 'mdast';
import type { InlineMath } from 'mdast-util-math';
import { SKIP, visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/to-markdown-handlers.ts b/packages/core/src/markdown/to-markdown-handlers.ts
index 3e79f8cb6..959cc0bd2 100644
--- a/packages/core/src/markdown/to-markdown-handlers.ts
+++ b/packages/core/src/markdown/to-markdown-handlers.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Parents } from 'mdast';
import type { MdxJsxAttribute, MdxJsxExpressionAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import type { Handle, Info, State } from 'mdast-util-to-markdown';
diff --git a/packages/core/src/markdown/underline-promoter.ts b/packages/core/src/markdown/underline-promoter.ts
index 0f1b0f27d..6e6d73400 100644
--- a/packages/core/src/markdown/underline-promoter.ts
+++ b/packages/core/src/markdown/underline-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Parent, Root } from 'mdast';
import type { MdxJsxTextElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/unknown-mdast-guard.ts b/packages/core/src/markdown/unknown-mdast-guard.ts
index 1a082bda7..932d7d2a8 100644
--- a/packages/core/src/markdown/unknown-mdast-guard.ts
+++ b/packages/core/src/markdown/unknown-mdast-guard.ts
@@ -1,3 +1,4 @@
+
import type { Root as MdastRoot } from 'mdast';
import type { VFile } from 'vfile';
diff --git a/packages/core/src/markdown/whitespace-char-ref.ts b/packages/core/src/markdown/whitespace-char-ref.ts
index d578476a7..ac9f5239b 100644
--- a/packages/core/src/markdown/whitespace-char-ref.ts
+++ b/packages/core/src/markdown/whitespace-char-ref.ts
@@ -1,3 +1,4 @@
+
const INLINE_WHITESPACE_BY_CODE: ReadonlyMap<number, string> = new Map([
[0x20, ' '],
[0x09, '\t'],
diff --git a/packages/core/src/markdown/wiki-link-micromark.ts b/packages/core/src/markdown/wiki-link-micromark.ts
index 6dad26200..afd9936fe 100644
--- a/packages/core/src/markdown/wiki-link-micromark.ts
+++ b/packages/core/src/markdown/wiki-link-micromark.ts
@@ -17,6 +17,7 @@ declare module 'micromark-util-types' {
}
}
+
const CODE_BANG = 33; // !
const CODE_LBRACKET = 91; // [
const CODE_RBRACKET = 93; // ]
@@ -260,6 +261,7 @@ export function wikiLinkSyntax(): Extension {
};
}
+
function enterWikiLink(this: CompileContext, token: Token) {
this.enter(
{
@@ -385,6 +387,7 @@ export const wikiLinkToMarkdown: {
unsafe: [{ character: '[', inConstruct: ['phrasing'] }],
};
+
const MICROMARK_EXT = wikiLinkSyntax();
export function remarkWikiLink(this: Processor) {
diff --git a/packages/core/src/utils/link-targets.test.ts b/packages/core/src/utils/link-targets.test.ts
index e735668c3..d578894cf 100644
--- a/packages/core/src/utils/link-targets.test.ts
+++ b/packages/core/src/utils/link-targets.test.ts
@@ -1,4 +1,5 @@
import { describe, expect, test } from 'vitest';
+import { skillFileLiveDocName } from '../constants/cc1.ts';
import {
buildAbsoluteMarkdownHref,
buildRelativeMarkdownHref,
@@ -6,6 +7,7 @@ import {
classifyWikiLinkTarget,
resolveAssetProjectPath,
} from './link-targets.ts';
+import { resolveInternalHref } from './resolve-internal-href.ts';
describe('classifyMarkdownHref', () => {
test('returns null for empty hrefs', () => {
@@ -58,9 +60,27 @@ describe('classifyMarkdownHref', () => {
kind: 'asset',
url: './meeting.pdf',
ext: 'pdf',
+ literal: false,
});
});
+ test('an escaped extension dot still classifies as an asset', () => {
+ // The extension is read off the decoded path. Reading it raw sees no
+ // extension at all, and the href falls out of the classifier entirely —
+ // neither doc nor asset — so nothing downstream can route the click.
+ expect(classifyMarkdownHref('./meeting%2Epdf', 'docs/notes')).toEqual({
+ kind: 'asset',
+ url: './meeting%2Epdf',
+ ext: 'pdf',
+ literal: false,
+ });
+ // `url` stays the authored bytes: the asset resolver decodes it under
+ // `literal: false`, so pre-decoding here would double-decode.
+ expect(resolveAssetProjectPath('./meeting%2Epdf', 'docs/notes', { literal: false })).toBe(
+ 'docs/meeting.pdf',
+ );
+ });
+
test('strips .mdx extension when resolving doc-link', () => {
expect(classifyMarkdownHref('./guide.mdx', 'docs/index')).toEqual({
kind: 'doc',
@@ -81,6 +101,7 @@ describe('classifyMarkdownHref', () => {
kind: 'asset',
url: '/docs/file.pdf',
ext: 'pdf',
+ literal: false,
});
});
@@ -104,6 +125,24 @@ describe('classifyMarkdownHref', () => {
});
});
+ test('decodes percent-escapes in doc hrefs', () => {
+ // Inherits the canonical resolver's RFC 3986 decoding — the doc kind must
+ // carry the decoded docName, not the escaped bytes.
+ expect(classifyMarkdownHref('./Agent%20Memory.md', 'blogs/drafts/index')).toEqual({
+ kind: 'doc',
+ docName: 'blogs/drafts/Agent Memory',
+ anchor: null,
+ });
+ });
+
+ test('malformed escapes classify as a doc with the raw bytes, without throwing', () => {
+ expect(classifyMarkdownHref('./100%ZZ.md', 'docs/index')).toEqual({
+ kind: 'doc',
+ docName: 'docs/100%ZZ',
+ anchor: null,
+ });
+ });
+
test('bundle overlay is narrow: non-skill source is unaffected', () => {
// `references/x` from a normal doc still resolves generically, not into a skill dir.
expect(classifyMarkdownHref('references/setup.md', 'docs/index')?.docName).not.toBe(
@@ -137,33 +176,73 @@ describe('classifyWikiLinkTarget', () => {
kind: 'asset',
url: '/docs/public/Wide.png',
ext: 'png',
+ literal: true,
+ });
+ });
+
+ test('wiki asset targets carry literal: true so consumers inherit the plane', () => {
+ // A consumer holding this target must not have to re-derive the plane from
+ // context it may not have — the tag IS the answer it feeds to
+ // `resolveAssetProjectPath`.
+ const wiki = classifyWikiLinkTarget('100%20done.png', null);
+ expect(wiki).toEqual({ kind: 'asset', url: '100%20done.png', ext: 'png', literal: true });
+ const markdown = classifyMarkdownHref('./100%20done.png', 'notes/readme');
+ expect(markdown).toEqual({
+ kind: 'asset',
+ url: './100%20done.png',
+ ext: 'png',
+ literal: false,
+ });
+ // The tags round-trip through the resolver to two different files.
+ if (wiki?.kind !== 'asset' || markdown?.kind !== 'asset') throw new Error('expected assets');
+ expect(resolveAssetProjectPath(wiki.url, 'notes/readme', { literal: wiki.literal })).toBe(
+ 'notes/100%20done.png',
+ );
+ expect(
+ resolveAssetProjectPath(markdown.url, 'notes/readme', { literal: markdown.literal }),
+ ).toBe('notes/100 done.png');
+ });
+
+ test('wiki targets are literal doc names — percent-escapes are never decoded', () => {
+ // `[[Agent%20Memory]]` names a doc whose filename literally contains
+ // `%20`; wiki targets are not URIs, so href decoding must not reach here.
+ expect(classifyWikiLinkTarget('Agent%20Memory', null)).toEqual({
+ kind: 'doc',
+ docName: 'Agent%20Memory',
+ anchor: null,
});
});
});
describe('resolveAssetProjectPath', () => {
test('same-dir asset resolves to sourceDoc-dir/basename', () => {
- expect(resolveAssetProjectPath('./meeting.pdf', 'notes/readme')).toBe('notes/meeting.pdf');
+ expect(resolveAssetProjectPath('./meeting.pdf', 'notes/readme', { literal: false })).toBe(
+ 'notes/meeting.pdf',
+ );
});
test('parent-relative asset walks up one dir', () => {
- expect(resolveAssetProjectPath('../shared.pdf', 'notes/sub/readme')).toBe('notes/shared.pdf');
+ expect(resolveAssetProjectPath('../shared.pdf', 'notes/sub/readme', { literal: false })).toBe(
+ 'notes/shared.pdf',
+ );
});
test('subdir-relative asset descends into sub', () => {
- expect(resolveAssetProjectPath('./assets/photo.png', 'docs/guide')).toBe(
+ expect(resolveAssetProjectPath('./assets/photo.png', 'docs/guide', { literal: false })).toBe(
'docs/assets/photo.png',
);
});
test('path escape above project root returns null', () => {
- expect(resolveAssetProjectPath('../../etc/passwd', 'notes/readme')).toBeNull();
+ expect(
+ resolveAssetProjectPath('../../etc/passwd', 'notes/readme', { literal: false }),
+ ).toBeNull();
});
test('strips anchor from returned path', () => {
- expect(resolveAssetProjectPath('./meeting.pdf#page=3', 'notes/readme')).toBe(
- 'notes/meeting.pdf',
- );
+ expect(
+ resolveAssetProjectPath('./meeting.pdf#page=3', 'notes/readme', { literal: false }),
+ ).toBe('notes/meeting.pdf');
});
test('server-absolute path is treated as project-root-relative (2026-04-24b)', () => {
@@ -174,9 +253,15 @@ describe('resolveAssetProjectPath', () => {
// dispatcher for any asset that round-tripped through the server —
// the click would fall through to external-URL handling rather than
// reaching `shell.openAsset` in Electron.
- expect(resolveAssetProjectPath('/docs/file.pdf', 'notes/readme')).toBe('docs/file.pdf');
- expect(resolveAssetProjectPath('/vale_15.m4v', 'notes/readme')).toBe('vale_15.m4v');
- expect(resolveAssetProjectPath('/sub/dir/photo.png', 'docs/guide')).toBe('sub/dir/photo.png');
+ expect(resolveAssetProjectPath('/docs/file.pdf', 'notes/readme', { literal: false })).toBe(
+ 'docs/file.pdf',
+ );
+ expect(resolveAssetProjectPath('/vale_15.m4v', 'notes/readme', { literal: false })).toBe(
+ 'vale_15.m4v',
+ );
+ expect(resolveAssetProjectPath('/sub/dir/photo.png', 'docs/guide', { literal: false })).toBe(
+ 'sub/dir/photo.png',
+ );
});
test('server-absolute path still refuses escape attempts', () => {
@@ -185,20 +270,74 @@ describe('resolveAssetProjectPath', () => {
// URL parser. Containment is defense-in-depth — the main-process
// `openAssetSafely` is the authoritative gate, but the renderer
// shouldn't feed it escape attempts.
- expect(resolveAssetProjectPath('/../etc/passwd', 'notes/readme')).toBeNull();
- expect(resolveAssetProjectPath('/docs/../../../etc/passwd', 'notes/readme')).toBeNull();
+ expect(
+ resolveAssetProjectPath('/../etc/passwd', 'notes/readme', { literal: false }),
+ ).toBeNull();
+ expect(
+ resolveAssetProjectPath('/docs/../../../etc/passwd', 'notes/readme', { literal: false }),
+ ).toBeNull();
});
test('HTTPS URL returns null', () => {
- expect(resolveAssetProjectPath('https://example.com/doc.pdf', 'notes/readme')).toBeNull();
+ expect(
+ resolveAssetProjectPath('https://example.com/doc.pdf', 'notes/readme', { literal: false }),
+ ).toBeNull();
});
test('source doc at root — `..` pop fails', () => {
- expect(resolveAssetProjectPath('../escape.pdf', 'readme')).toBeNull();
+ expect(resolveAssetProjectPath('../escape.pdf', 'readme', { literal: false })).toBeNull();
});
test('empty href returns null', () => {
- expect(resolveAssetProjectPath('', 'notes/readme')).toBeNull();
+ expect(resolveAssetProjectPath('', 'notes/readme', { literal: false })).toBeNull();
+ });
+
+ test('decodes percent-escapes in asset hrefs', () => {
+ // Same RFC 3986 contract as the doc resolver: the returned value is a
+ // filesystem location, so escaped bytes must decode to the real filename.
+ expect(
+ resolveAssetProjectPath('./design%20spec.pdf', 'blogs/drafts/index', { literal: false }),
+ ).toBe('blogs/drafts/design spec.pdf');
+ });
+
+ // Asserted positively: a null return would satisfy any "not traversal" check
+ // while quietly breaking every filename that legitimately carries the bytes.
+ test('%2F in an asset href stays literal data under the source dir', () => {
+ expect(
+ resolveAssetProjectPath('..%2F..%2Fetc%2Fpasswd.pdf', 'notes/readme', { literal: false }),
+ ).toBe('notes/..%2F..%2Fetc%2Fpasswd.pdf');
+ });
+
+ test('%5C in an asset href stays literal data under the source dir', () => {
+ expect(
+ resolveAssetProjectPath('..%5C..%5Cwindows.pdf', 'notes/readme', { literal: false }),
+ ).toBe('notes/..%5C..%5Cwindows.pdf');
+ });
+
+ test('a literal asset target keeps its percent sequences undecoded', () => {
+ expect(resolveAssetProjectPath('100%20done.png', 'notes/readme', { literal: true })).toBe(
+ 'notes/100%20done.png',
+ );
+ });
+
+ test('a literal asset target never resolves to its decoded neighbour', () => {
+ // The companion to the assertion above: `notes/100 done.png` is a
+ // DIFFERENT file that may also exist. Decoding a literal target reports a
+ // working link as dead and, worse, points Reveal/Open at the wrong file.
+ expect(resolveAssetProjectPath('100%20done.png', 'notes/readme', { literal: true })).not.toBe(
+ 'notes/100 done.png',
+ );
+ // …and the markdown plane, given the same bytes, MUST reach that neighbour —
+ // the two planes disagree by construction, which is why the option exists.
+ expect(resolveAssetProjectPath('100%20done.png', 'notes/readme', { literal: false })).toBe(
+ 'notes/100 done.png',
+ );
+ });
+
+ test('malformed escapes fall back to the raw asset path without throwing', () => {
+ expect(resolveAssetProjectPath('./100%ZZ.pdf', 'notes/readme', { literal: false })).toBe(
+ 'notes/100%ZZ.pdf',
+ );
});
});
@@ -218,6 +357,42 @@ describe('buildRelativeMarkdownHref', () => {
test('honors a non-default extension for the target', () => {
expect(buildRelativeMarkdownHref('docs/index', 'docs/guide', null, '.mdx')).toBe('./guide.mdx');
});
+
+ // An emitted destination must survive the resolver that reads it back. A bare
+ // CommonMark destination cannot contain a literal space, so a doc name that
+ // needs escaping has to be encoded here or the link does not parse at all.
+ test('encodes a target name that cannot appear literally in a destination', () => {
+ expect(buildRelativeMarkdownHref('blogs/drafts/index', 'blogs/drafts/Agent Memory')).toBe(
+ './Agent%20Memory.md',
+ );
+ });
+
+ test('keeps traversal markers structural while encoding the name', () => {
+ expect(buildRelativeMarkdownHref('guides/nested/page', 'guides/Install Guide')).toBe(
+ '../Install%20Guide.md',
+ );
+ });
+
+ test('leaves the anchor byte-for-byte, matching the resolver', () => {
+ expect(buildRelativeMarkdownHref('notes/index', 'notes/My Doc', 'a b')).toBe(
+ './My%20Doc.md#a b',
+ );
+ });
+
+ test.each([
+ 'Agent Memory',
+ 'team plan (draft) #1',
+ 'Q&A',
+ 'café',
+ "it's here",
+ '100% done',
+ ])('round-trips %j back through the resolver', (name) => {
+ const href = buildRelativeMarkdownHref('blogs/drafts/index', `blogs/drafts/${name}`);
+ expect(resolveInternalHref(href, 'blogs/drafts/index')).toEqual({
+ docName: `blogs/drafts/${name}`,
+ anchor: null,
+ });
+ });
});
describe('buildAbsoluteMarkdownHref', () => {
@@ -234,6 +409,20 @@ describe('buildAbsoluteMarkdownHref', () => {
test('honors a non-default extension', () => {
expect(buildAbsoluteMarkdownHref('guides/widget', '.mdx')).toBe('/guides/widget.mdx');
});
+
+ test('encodes each segment while keeping `/` as hierarchy', () => {
+ expect(buildAbsoluteMarkdownHref('blogs/my drafts/Agent Memory')).toBe(
+ '/blogs/my%20drafts/Agent%20Memory.md',
+ );
+ });
+
+ test('round-trips a space-bearing name back through the resolver', () => {
+ const href = buildAbsoluteMarkdownHref('blogs/drafts/Agent Memory');
+ expect(resolveInternalHref(href, 'anywhere/else')).toEqual({
+ docName: 'blogs/drafts/Agent Memory',
+ anchor: null,
+ });
+ });
});
describe('/<skill-name> targets', () => {
@@ -258,6 +447,14 @@ describe('/<skill-name> targets', () => {
expect(target?.kind === 'doc' ? target.docName : null).not.toBe('.agents/skills/a/SKILL');
});
+ test('a percent-encoded skill name still names the sibling skill', () => {
+ expect(classifyMarkdownHref('/my%20skill', '.agents/skills/brand/SKILL')).toEqual({
+ kind: 'doc',
+ docName: '.agents/skills/my skill/SKILL',
+ anchor: null,
+ });
+ });
+
test('outside a skill it stays an ordinary path', () => {
const target = classifyMarkdownHref('/graphics', 'notes/index');
expect(target?.kind === 'doc' ? target.docName : null).not.toBe(
@@ -265,3 +462,27 @@ describe('/<skill-name> targets', () => {
);
});
});
+
+describe('percent-encoded hrefs decode on every classify branch', () => {
+ // `classifyMarkdownHref` dispatches to the skill-bundle resolver before the
+ // generic one. An href is a URI on every branch, so a branch that skipped the
+ // decode would keep resolving to a phantom doc.
+ for (const scope of ['global', 'project'] as const) {
+ test(`an encoded skill-bundle ref from a ${scope} SKILL.md decodes`, () => {
+ const base = skillFileLiveDocName(scope, 'demo', 'SKILL');
+ expect(classifyMarkdownHref('references/my%20ref.md', base)).toEqual({
+ kind: 'doc',
+ docName: skillFileLiveDocName(scope, 'demo', 'references/my ref'),
+ anchor: null,
+ });
+ });
+ }
+
+ test('the anchor is returned verbatim, not decoded', () => {
+ // Anchors feed heading-slug matching, whose byte contract is separate from
+ // the path's. Pinned so a change to it is a deliberate decision, not drift.
+ expect(classifyMarkdownHref('./Agent%20Memory.md#section%20two', 'blogs/drafts/index')).toEqual(
+ { kind: 'doc', docName: 'blogs/drafts/Agent Memory', anchor: 'section%20two' },
+ );
+ });
+});
diff --git a/packages/core/src/utils/link-targets.ts b/packages/core/src/utils/link-targets.ts
index 37c02c3bd..557fb322a 100644
--- a/packages/core/src/utils/link-targets.ts
+++ b/packages/core/src/utils/link-targets.ts
@@ -1,6 +1,12 @@
import { resolveSkillBundleWikiTarget, resolveSkillSlashTarget } from '../constants/cc1.ts';
import { DEFAULT_DOC_EXTENSION } from '../constants/doc-extensions.ts';
-import { type ResolvedInternalHref, resolveInternalHref } from './resolve-internal-href.ts';
+import {
+ decodeHrefPath,
+ decodeHrefPathSegment,
+ encodeHrefPath,
+ type ResolvedInternalHref,
+ resolveInternalHref,
+} from './resolve-internal-href.ts';
export interface DocLinkTarget extends ResolvedInternalHref {
kind: 'doc';
@@ -28,6 +34,15 @@ export interface AssetLinkTarget {
kind: 'asset';
url: string;
ext: string;
+ /**
+ * Whether `url` is literal bytes (a wiki target names a file directly) or a
+ * URI whose percent escapes decode (a markdown destination, per RFC 3986
+ * §2.1). Both classifiers emit this same shape, so without the tag a
+ * consumer holding one cannot tell which plane produced it and has to
+ * re-derive the answer from context it may not have. Feed it straight to
+ * `resolveAssetProjectPath`'s `literal` option.
+ */
+ literal: boolean;
}
export type ClassifiedLinkTarget =
@@ -95,7 +110,11 @@ export function classifyMarkdownHref(
// real ref doc. Narrow by design: non-skill sources / non-bundle targets return
// null and fall through unchanged.
const hashAt = trimmed.indexOf('#');
- const bundlePath = hashAt < 0 ? trimmed : trimmed.slice(0, hashAt);
+ // Decode here, not inside the skill resolvers: those are shared with the
+ // `[[wiki]]` path, whose targets are literal doc names and must stay
+ // verbatim. An href is a URI on every branch, so it decodes on every branch —
+ // otherwise a percent-encoded skill ref keeps resolving to a phantom doc.
+ const bundlePath = decodeHrefPath(hashAt < 0 ? trimmed : trimmed.slice(0, hashAt));
const bundleDoc = resolveSkillBundleWikiTarget(bundlePath, sourceDocName);
if (bundleDoc) {
return {
@@ -133,9 +152,14 @@ export function classifyMarkdownHref(
// viewer or OS delegation. Without this branch, post-reload clicks on
// `![[meeting.pdf]]` fall back to `null` (unresolved) and end up
// rendering as a broken doc-link.
- const ext = extractAssetExtension(trimmed);
+ // Extension off the DECODED path, not the raw href: an escaped extension dot
+ // (`./photo%2Ejpg`) only looks like an extension once the escape is resolved,
+ // and reading it raw classifies the asset as a doc link. Same ordering
+ // `resolveInternalHref`'s non-markdown guard uses, so the two agree on which
+ // hrefs are assets.
+ const ext = extractAssetExtension(bundlePath);
if (ext && ext !== 'md' && ext !== 'mdx') {
- return { kind: 'asset', url: trimmed, ext };
+ return { kind: 'asset', url: trimmed, ext, literal: false };
}
return null;
@@ -157,7 +181,10 @@ export function classifyWikiLinkTarget(
const ext = extractAssetExtension(trimmed);
if (ext && ext !== 'md' && ext !== 'mdx') {
- return { kind: 'asset', url: trimmed, ext };
+ // A wiki target names a file literally: `[[100%20done.png]]` means a file
+ // whose name really contains those three characters, so the target must
+ // never be percent-decoded on its way to a filesystem path.
+ return { kind: 'asset', url: trimmed, ext, literal: true };
}
return {
@@ -205,7 +232,29 @@ export function classifyWikiLinkTarget(
* - Server-absolute `/..` pops into negative territory → returns
* `null`.
*/
-export function resolveAssetProjectPath(href: string, sourceDocName: string): string | null {
+export interface ResolveAssetProjectPathOptions {
+ /**
+ * Treat the href as literal bytes rather than a URI: skip percent-decoding.
+ * Wiki targets name a file directly, so `[[100%20done.png]]` means a file
+ * whose name really contains `%20`; a markdown destination is a URI whose
+ * escapes decode (RFC 3986 §2.1).
+ *
+ * REQUIRED, with no default, on purpose. Both classifiers emit the same
+ * `{kind: 'asset', url}` shape, so the plane cannot be recovered here — the
+ * caller that knows it must say so, and a caller that serves both planes has
+ * to thread it from ITS caller rather than silently pick one. A default
+ * would let a new call site inherit the wrong plane and report a working
+ * link as dead. A caller holding a `ClassifiedLinkTarget` passes the
+ * target's own `literal` rather than re-deriving it.
+ */
+ literal: boolean;
+}
+
+export function resolveAssetProjectPath(
+ href: string,
+ sourceDocName: string,
+ options: ResolveAssetProjectPathOptions,
+): string | null {
const trimmed = href.trim();
if (!trimmed) return null;
@@ -241,7 +290,7 @@ export function resolveAssetProjectPath(href: string, sourceDocName: string): st
if (dirParts.length === 0) return null;
dirParts.pop();
} else if (seg !== '.' && seg !== '') {
- dirParts.push(seg);
+ dirParts.push(options.literal ? seg : decodeHrefPathSegment(seg));
}
}
@@ -286,7 +335,10 @@ export function buildRelativeMarkdownHref(
relativePath = `./${relativePath}`;
}
- return `${relativePath}${ext}${anchor ? `#${anchor}` : ''}`;
+ // The path is escaped but the anchor is not: `resolveInternalHref` decodes the
+ // path portion and returns the fragment verbatim, so encoding the fragment here
+ // would break that symmetry.
+ return `${encodeHrefPath(relativePath)}${ext}${anchor ? `#${anchor}` : ''}`;
}
/**
@@ -300,5 +352,5 @@ export function buildAbsoluteMarkdownHref(
ext: string = DEFAULT_DOC_EXTENSION,
anchor: string | null = null,
): string {
- return `/${docName}${ext}${anchor ? `#${anchor}` : ''}`;
+ return `/${encodeHrefPath(docName)}${ext}${anchor ? `#${anchor}` : ''}`;
}
diff --git a/packages/core/src/utils/resolve-internal-href.test.ts b/packages/core/src/utils/resolve-internal-href.test.ts
index 8621e30c2..cbd8731c1 100644
--- a/packages/core/src/utils/resolve-internal-href.test.ts
+++ b/packages/core/src/utils/resolve-internal-href.test.ts
@@ -1,6 +1,11 @@
import { describe, expect, test } from 'vitest';
import { skillFileLiveDocName } from '../constants/cc1.ts';
-import { resolveInternalHref } from './resolve-internal-href.ts';
+import {
+ decodeHrefPathSegment,
+ encodeHrefPath,
+ encodeHrefPathSegment,
+ resolveInternalHref,
+} from './resolve-internal-href.ts';
describe('resolveInternalHref', () => {
test('resolves same-directory relative links', () => {
@@ -72,6 +77,213 @@ describe('resolveInternalHref', () => {
expect(resolveInternalHref('../../../way-out.md', 'deep/a/b')).toBeNull();
});
+ // A CommonMark link destination is URI-shaped: a literal space cannot appear
+ // in an unbracketed destination, so percent-escapes are the only valid way to
+ // link a doc whose name needs them (RFC 3986). Resolving the encoded href of
+ // a path must therefore yield the same docName as resolving the path itself.
+ describe('percent-encoded hrefs', () => {
+ test('decodes %20 in a relative href to reach the real doc', () => {
+ expect(resolveInternalHref('./Agent%20Memory.md', 'blogs/drafts/index')).toEqual({
+ docName: 'blogs/drafts/Agent Memory',
+ anchor: null,
+ });
+ });
+
+ test('decodes root-absolute encoded hrefs from the content root', () => {
+ expect(resolveInternalHref('/blogs/drafts/Agent%20Memory.md', 'notes')).toEqual({
+ docName: 'blogs/drafts/Agent Memory',
+ anchor: null,
+ });
+ });
+
+ test('preserves the anchor while decoding the path portion', () => {
+ expect(resolveInternalHref('./Agent%20Memory.md#usage', 'blogs/drafts/index')).toEqual({
+ docName: 'blogs/drafts/Agent Memory',
+ anchor: 'usage',
+ });
+ });
+
+ test('decodes parens, hash, and ampersand escapes in filenames', () => {
+ expect(resolveInternalHref('./team%20plan%20%28draft%29%20%231.md', 'notes/index')).toEqual({
+ docName: 'notes/team plan (draft) #1',
+ anchor: null,
+ });
+ expect(resolveInternalHref('./R%26D%20notes.md', 'notes/index')).toEqual({
+ docName: 'notes/R&D notes',
+ anchor: null,
+ });
+ });
+
+ test('decodes non-ASCII escapes', () => {
+ expect(resolveInternalHref('./caf%C3%A9.md', 'notes/index')).toEqual({
+ docName: 'notes/café',
+ anchor: null,
+ });
+ });
+
+ test('an escaped extension dot still refuses the href as an asset', () => {
+ // The non-markdown-extension guard has to read the same bytes the
+ // resolved docName is built from. `%2E` carries no literal dot, so a
+ // guard that runs before decoding sees an extension-less path, admits
+ // the asset as a doc, and the click dispatcher navigates the router to a
+ // doc named `notes/file.pdf` that cannot exist.
+ expect(resolveInternalHref('./file%2Epdf', 'notes/index')).toBeNull();
+ expect(resolveInternalHref('/assets/photo%2Ejpg', 'notes/index')).toBeNull();
+ // The escaped-dot form and the plain form must agree.
+ expect(resolveInternalHref('./file.pdf', 'notes/index')).toBeNull();
+ });
+
+ test('an escaped dot in a markdown filename still resolves as a doc', () => {
+ // Precision guard for the reorder above: the decoded extension decides,
+ // so an escaped dot in front of `md` stays a doc rather than being
+ // refused wholesale as an asset.
+ expect(resolveInternalHref('./v1%2E2%20notes.md', 'notes/index')).toEqual({
+ docName: 'notes/v1.2 notes',
+ anchor: null,
+ });
+ });
+
+ test('%2F never becomes a path separator', () => {
+ // RFC 3986: an escaped slash inside a segment is data, not hierarchy.
+ // Decoding it into a separator would let one segment become two.
+ // Pinned by exact value: a variant that refuses the href outright
+ // (returning null) is also wrong, and a negative assertion would miss it.
+ expect(resolveInternalHref('./a%2Fb.md', 'blogs/drafts/index')).toEqual({
+ docName: 'blogs/drafts/a%2Fb',
+ anchor: null,
+ });
+ });
+
+ test('%2F-bearing escapes cannot pop above the content root', () => {
+ expect(resolveInternalHref('./..%2F..%2Fescape.md', 'blogs/drafts/index')).toEqual({
+ docName: 'blogs/drafts/..%2F..%2Fescape',
+ anchor: null,
+ });
+ });
+
+ test('%5C never becomes a path separator', () => {
+ // A backslash is a separator on Windows, so a decode that mints one is
+ // the same hierarchy-minting the `%2F` refusal exists to prevent.
+ expect(resolveInternalHref('./a%5Cb.md', 'blogs/drafts/index')).toEqual({
+ docName: 'blogs/drafts/a%5Cb',
+ anchor: null,
+ });
+ expect(resolveInternalHref('./..%5C..%5Cwin.md', 'docs/a/b')).toEqual({
+ docName: 'docs/a/..%5C..%5Cwin',
+ anchor: null,
+ });
+ });
+
+ test('encoded dot-segments stay data — they never become traversal', () => {
+ // The traversal check reads the DECODED segment, so the escape surviving
+ // as data is `decodeHrefPathSegment`'s doing, not the walk's: it refuses
+ // any decode whose result is `.` or `..`, so `%2E%2E` never becomes a
+ // segment the pop could see. That refusal is the load-bearing dependency
+ // here — if it ever softened, these hrefs would start traversing.
+ expect(resolveInternalHref('./%2E%2E/secret.md', 'blogs/drafts/index')).toEqual({
+ docName: 'blogs/drafts/%2E%2E/secret',
+ anchor: null,
+ });
+ expect(resolveInternalHref('./%2E/secret.md', 'blogs/drafts/index')).toEqual({
+ docName: 'blogs/drafts/%2E/secret',
+ anchor: null,
+ });
+ });
+
+ test('an encoded NUL stays literal', () => {
+ expect(resolveInternalHref('./bad%00name.md', 'notes/index')).toEqual({
+ docName: 'notes/bad%00name',
+ anchor: null,
+ });
+ });
+
+ // The guard reads the extension off decoded bytes, so the strip has to as
+ // well — otherwise an escaped `.md` is admitted as a doc and then carried
+ // into the docName, which is extension-less by contract.
+ test('an escaped doc extension is stripped, not carried into the docName', () => {
+ expect(resolveInternalHref('./meeting%2Emd', 'notes/index')).toEqual({
+ docName: 'notes/meeting',
+ anchor: null,
+ });
+ expect(resolveInternalHref('./meeting%2Emdx', 'notes/index')).toEqual({
+ docName: 'notes/meeting',
+ anchor: null,
+ });
+ });
+
+ // What the extension strip leaves behind is still a path segment: `...md`
+ // reduces to `..` and must pop, never land in the docName. A docName
+ // carrying `.`/`..` is indexed, graphed, and offered for creation as a
+ // wrong-doc resolution well before downstream containment sees it.
+ test('a stripped extension that exposes a traversal segment traverses', () => {
+ expect(resolveInternalHref('./...md', 'notes/index')).toBeNull();
+ expect(resolveInternalHref('./...md', 'index')).toBeNull();
+ expect(resolveInternalHref('./..md', 'notes/index')).toEqual({
+ docName: 'notes',
+ anchor: null,
+ });
+ });
+
+ // The escaped spelling reduces to the same segment as the plain one, so it
+ // has to reach the same verdict — `decodeHrefPathSegment` refuses a segment
+ // that IS `.`/`..`, but `...md` is neither until the extension comes off.
+ test('an escaped traversal-after-strip matches its plain spelling', () => {
+ expect(resolveInternalHref('./%2E%2E%2Emd', 'notes/index')).toBeNull();
+ expect(resolveInternalHref('./..%2Emd', 'notes/index')).toBeNull();
+ });
+
+ // A segment that is nothing BUT an extension contributes nothing, rather
+ // than emptying the accumulated path.
+ test('a bare extension segment resolves to its containing directory', () => {
+ expect(resolveInternalHref('./.md', 'notes/index')).toEqual({
+ docName: 'notes',
+ anchor: null,
+ });
+ expect(resolveInternalHref('./sub/.md', 'notes/index')).toEqual({
+ docName: 'notes/sub',
+ anchor: null,
+ });
+ });
+
+ // A colon decodes, drive-letter-shaped or not. Refusing the escaped spelling
+ // would leave the plain one (`/D:foo.md`, which never reaches the decoder)
+ // untouched, so it would not actually contain anything — while making
+ // `D:plan`, a legal POSIX filename, permanently unresolvable through an
+ // encoded link. Containment lives downstream, where it covers both spellings.
+ test('a colon decodes rather than being refused', () => {
+ expect(resolveInternalHref('./notes%3A2026.md', 'notes/index')).toEqual({
+ docName: 'notes/notes:2026',
+ anchor: null,
+ });
+ expect(resolveInternalHref('./D%3Aplan.md', 'notes/index')).toEqual({
+ docName: 'notes/D:plan',
+ anchor: null,
+ });
+ });
+
+ test('escaped octets decode exactly once', () => {
+ // RFC 3986 §2.4: `%2520` denotes the literal bytes `%20` in the filename.
+ // A second decode pass would collapse it to a space and miss the doc.
+ expect(resolveInternalHref('./100%2520done.md', 'notes/index')).toEqual({
+ docName: 'notes/100%20done',
+ anchor: null,
+ });
+ });
+
+ test('malformed escapes fall back to the raw bytes without throwing', () => {
+ // Hrefs are user-authored strings parsed out of markdown bytes; a stray
+ // `%` must degrade to a literal lookup, never a URIError.
+ expect(resolveInternalHref('./100%ZZ.md', 'notes/index')).toEqual({
+ docName: 'notes/100%ZZ',
+ anchor: null,
+ });
+ expect(resolveInternalHref('./50%.md', 'notes/index')).toEqual({
+ docName: 'notes/50%',
+ anchor: null,
+ });
+ });
+ });
+
// A skill's SKILL.md links to its references with skill-relative paths
// (`references/setup.md`). With the file's own bundle doc as the base, those
// resolve to the sibling reference doc instead of a nonexistent content path —
@@ -95,3 +307,47 @@ describe('resolveInternalHref', () => {
}
});
});
+
+describe('encodeHrefPathSegment', () => {
+ // The encode/decode pair is the contract this whole module exists to hold:
+ // every href OK emits must resolve back to the name it was built from.
+ // Splitting the halves is what let an encoded link and a decoding resolver
+ // disagree in the first place.
+ const names = [
+ 'Agent Memory',
+ 'team plan (draft) #1',
+ 'R&D notes',
+ "don't panic!",
+ 'café résumé',
+ '100%20done',
+ '..',
+ '.',
+ 'plain',
+ ];
+
+ for (const name of names) {
+ test(`round-trips ${JSON.stringify(name)}`, () => {
+ expect(decodeHrefPathSegment(encodeHrefPathSegment(name))).toBe(name);
+ });
+ }
+
+ test('does not round-trip a separator-bearing name — by design', () => {
+ // The decoder refuses any decode that would mint hierarchy, so a name
+ // containing `/` or `\` survives as its escaped form rather than decoding
+ // back. Such a name cannot address a real file through an href; wiki links
+ // are the escape hatch. This is the deliberate limit of the pair above.
+ expect(decodeHrefPathSegment(encodeHrefPathSegment('a/b'))).toBe('a%2Fb');
+ expect(decodeHrefPathSegment(encodeHrefPathSegment('a\\b'))).toBe('a%5Cb');
+ });
+
+ test('never emits a character that terminates a bare link destination', () => {
+ for (const name of names) {
+ if (name === '.' || name === '..') continue;
+ expect(encodeHrefPathSegment(name)).not.toMatch(/[ ()#?]/);
+ }
+ });
+
+ test('keeps `/` as hierarchy and leaves traversal markers structural', () => {
+ expect(encodeHrefPath('../a b/c#d')).toBe('../a%20b/c%23d');
+ });
+});
diff --git a/packages/core/src/utils/resolve-internal-href.ts b/packages/core/src/utils/resolve-internal-href.ts
index 228eeff5e..455064f7e 100644
--- a/packages/core/src/utils/resolve-internal-href.ts
+++ b/packages/core/src/utils/resolve-internal-href.ts
@@ -1,8 +1,88 @@
+import { stripMdExt } from '../constants/cc1.ts';
+import { SUPPORTED_DOC_EXTENSIONS } from '../constants/doc-extensions.ts';
+
export interface ResolvedInternalHref {
docName: string;
anchor: string | null;
}
+/**
+ * Decode one percent-encoded path segment of an internal href. Applied per
+ * raw `/`-delimited segment (never to the whole path) so an escaped `%2F`
+ * stays segment data instead of becoming a separator — RFC 3986 §3.3: an
+ * escaped octet is data, not hierarchy.
+ */
+export function decodeHrefPathSegment(segment: string): string {
+ if (!segment.includes('%')) return segment;
+ let decoded: string;
+ try {
+ decoded = decodeURIComponent(segment);
+ } catch {
+ // RFC 3986 §2.1: an invalid escape (`%ZZ`, lone `%`) is not an escape —
+ // treat the bytes literally rather than throwing.
+ return segment;
+ }
+ // Refuse any decode that would mint hierarchy (`/`, and `\` — a separator on
+ // Windows), traversal (`.`/`..`), or a NUL: the encoded form must never gain
+ // path semantics it didn't have.
+ //
+ // This refusal is what keeps `resolveInternalHref`'s walk safe: that walk
+ // applies its `.`/`..` semantics to the DECODED segment, so an escaped
+ // traversal stays data only because it never decodes here in the first place.
+ // Softening this would silently make `./%2E%2E/secret.md` traverse.
+ //
+ // A leading drive qualifier (`D:`) is deliberately NOT refused. Refusing it
+ // here would only cover the escaped spelling — a plainly-written `/D:foo.png`
+ // never reaches this function, since a segment without `%` returns above — so
+ // the guard would read as complete while covering half the cases. It would
+ // also break this module's round-trip invariant for `D:plan`, a legal POSIX
+ // filename, stranding it permanently unresolvable through an encoded link:
+ // the same "valid name reads as dead link" failure this decoding exists to
+ // remove. Containment against both spellings is enforced downstream, where it
+ // can be complete — realpath plus a content-dir check on the server, and
+ // `openAssetSafely` in desktop.
+ if (
+ decoded === '.' ||
+ decoded === '..' ||
+ decoded.includes('/') ||
+ decoded.includes('\\') ||
+ decoded.includes('\0')
+ ) {
+ return segment;
+ }
+ return decoded;
+}
+
+/**
+ * Inverse of `decodeHrefPathSegment`: encode one path segment for emission into
+ * a markdown link destination. Applied per `/`-delimited segment so `/` stays
+ * hierarchy, and beyond `encodeURIComponent` it also neutralizes `!'()*` so an
+ * unbalanced paren can never terminate a bare CommonMark destination.
+ *
+ * Every href OK emits must round-trip: `decodeHrefPathSegment(encodeHrefPathSegment(s)) === s`.
+ * Emitting a raw segment instead leaks spaces and `#`/`?` into the destination,
+ * where a parser reads them as the end of the link.
+ */
+export function encodeHrefPathSegment(segment: string): string {
+ // Traversal markers are structure, not data — encoding them would break the
+ // relative path they belong to.
+ if (segment === '.' || segment === '..') return segment;
+ return encodeURIComponent(segment).replace(
+ /[!'()*]/g,
+ (char) => `%${char.codePointAt(0)?.toString(16).toUpperCase()}`,
+ );
+}
+
+/** Per-segment `encodeHrefPathSegment` across a `/`-delimited path. */
+export function encodeHrefPath(path: string): string {
+ return path.split('/').map(encodeHrefPathSegment).join('/');
+}
+
+/** Per-segment `decodeHrefPathSegment` across a `/`-delimited path. */
+export function decodeHrefPath(path: string): string {
+ return path.split('/').map(decodeHrefPathSegment).join('/');
+}
+
/**
* Canonical resolution for markdown hrefs that target docs inside the content
* tree. Server and app surfaces share this so "is this internal?" stays
@@ -32,32 +112,50 @@ export function resolveInternalHref(
// links. Without this guard, `docs/meeting.pdf` resolves as a doc named
// `docs/meeting.pdf` and the click dispatcher tries to navigate OK's
// router to that nonexistent doc.
- const lastSegment = cleanPath.split('/').pop() ?? '';
+ //
+ // The extension is read AFTER decoding, matching the decode the resolution
+ // loop below applies: `./meeting%2Epdf` carries no literal dot, so a raw
+ // read sees no extension and admits the asset as a doc — the guard has to
+ // see the same bytes the resolved docName would be built from.
+ const lastSegment = decodeHrefPathSegment(cleanPath.split('/').pop() ?? '');
+ //
+ // The admitted set comes from `SUPPORTED_DOC_EXTENSIONS` rather than being
+ // spelled out here, because admission and stripping have to stay in step: an
+ // extension admitted here but not stripped below lands in the docName, which
+ // is extension-less by contract. The strip is `stripMdExt`, core's single
+ // spelling of that grammar — it carries its own `.mdx?` regex, so a third
+ // supported extension needs updating there too.
const extMatch = lastSegment.match(/\.([a-z0-9]+)$/i);
if (extMatch) {
- const ext = (extMatch[1] ?? '').toLowerCase();
- if (ext !== 'md' && ext !== 'mdx') return null;
+ const ext = `.${(extMatch[1] ?? '').toLowerCase()}`;
+ if (!(SUPPORTED_DOC_EXTENSIONS as readonly string[]).includes(ext)) return null;
}
- // Strip the canonical doc extensions case-insensitively (see
- // packages/server/src/doc-extensions.ts for the server-side source of
- // truth — core can't import from server, so the list is inlined here and
- // kept narrow: .md + .mdx).
- const lower = cleanPath.toLowerCase();
- const withoutExt = lower.endsWith('.mdx')
- ? cleanPath.slice(0, -4)
- : lower.endsWith('.md')
- ? cleanPath.slice(0, -3)
- : cleanPath;
- const isRootRelative = withoutExt.startsWith('/');
- const effectivePath = isRootRelative ? withoutExt.slice(1) : withoutExt;
+ const isRootRelative = cleanPath.startsWith('/');
+ const effectivePath = isRootRelative ? cleanPath.slice(1) : cleanPath;
const dirParts = isRootRelative
? []
: sourceDocName.includes('/')
? sourceDocName.split('/').slice(0, -1)
: [];
- for (const seg of effectivePath.split('/')) {
+ // Each segment is decoded, and the final one additionally has its doc
+ // extension stripped, BEFORE the traversal semantics below run. Order is
+ // load-bearing in both directions:
+ //
+ // - decode before traversal, so `./meeting%2Emd` — which carries no literal
+ // `.md` — still strips to an extension-less docName. OK docNames never
+ // carry an extension.
+ // - strip before traversal, so what the strip leaves behind is still read as
+ // a path segment: `./...md` must reduce to `..` and pop, not land in the
+ // docName as a literal `notes/..`. A docName bearing `.`/`..` gets
+ // indexed, graphed, and offered for creation as a wrong-doc resolution
+ // long before any downstream containment check sees it.
+ const segments = effectivePath.split('/');
+ const lastSegmentIndex = segments.length - 1;
+ for (let i = 0; i < segments.length; i++) {
+ let seg = decodeHrefPathSegment(segments[i] ?? '');
+ if (i === lastSegmentIndex) seg = stripMdExt(seg);
if (seg === '..') {
if (dirParts.length === 0) return null;
dirParts.pop();
diff --git a/packages/core/src/utils/wiki-link-resolve.test.ts b/packages/core/src/utils/wiki-link-resolve.test.ts
index 5adb0be7e..52c953226 100644
--- a/packages/core/src/utils/wiki-link-resolve.test.ts
+++ b/packages/core/src/utils/wiki-link-resolve.test.ts
@@ -315,6 +315,7 @@ describe('composed wiki-link resolution', () => {
kind: 'asset',
url: 'acp.daemon',
ext: 'daemon',
+ literal: true,
});
});
@@ -347,6 +348,7 @@ describe('composed wiki-link resolution', () => {
kind: 'asset',
url: 'Wide.png',
ext: 'png',
+ literal: true,
});
});
@@ -355,6 +357,7 @@ describe('composed wiki-link resolution', () => {
kind: 'asset',
url: 'data/example.csv',
ext: 'csv',
+ literal: true,
});
});
@@ -363,6 +366,7 @@ describe('composed wiki-link resolution', () => {
kind: 'asset',
url: 'missing.pdf',
ext: 'pdf',
+ literal: true,
});
});
@@ -382,6 +386,7 @@ describe('composed wiki-link resolution', () => {
kind: 'asset',
url: 'meeting.pdf',
ext: 'pdf',
+ literal: true,
});
});
@@ -400,6 +405,7 @@ describe('composed wiki-link resolution', () => {
kind: 'asset',
url: 'data.csv',
ext: 'csv',
+ literal: true,
});
});
diff --git a/packages/server/src/asset-references.test.ts b/packages/server/src/asset-references.test.ts
index ff9bc8827..6773e69ca 100644
--- a/packages/server/src/asset-references.test.ts
+++ b/packages/server/src/asset-references.test.ts
@@ -7,7 +7,6 @@ import {
assetReferencesChanged,
collectReferencedAssets,
extractLocalAssetHrefs,
- isLocalAssetReferenceHref,
isRemoteOrOpaqueHref,
resolveReferencedAssetPath,
stripHrefDecorations,
@@ -85,20 +84,25 @@ describe('asset reference extraction', () => {
).toEqual(['./real.png', './real-html.jpeg']);
});
+ // Exercised through the signature rather than a bare predicate: admission is
+ // plane-aware now, and a raw-bytes predicate sitting beside the plane-aware
+ // one is what invites a caller to reintroduce the collapse.
+ const admits = (markdown: string): boolean => assetReferenceSignature(markdown) !== '';
+
test('classifies only local supported asset hrefs as sidebar asset references', () => {
- expect(isLocalAssetReferenceHref('#section')).toBe(false);
- expect(isLocalAssetReferenceHref('//cdn.example.com/photo.png')).toBe(false);
- expect(isLocalAssetReferenceHref('https://example.com/photo.png')).toBe(false);
- expect(isLocalAssetReferenceHref('data:image/png;base64,abc')).toBe(false);
- expect(isLocalAssetReferenceHref('./local/photo.png')).toBe(true);
- expect(isLocalAssetReferenceHref('<./local/photo.png?size=1#hero>')).toBe(true);
- expect(isLocalAssetReferenceHref('./doc.md')).toBe(false);
+ expect(admits('[x](#section)')).toBe(false);
+ expect(admits('[x](//cdn.example.com/photo.png)')).toBe(false);
+ expect(admits('[x](https://example.com/photo.png)')).toBe(false);
+ expect(admits('[x](data:image/png;base64,abc)')).toBe(false);
+ expect(admits('[x](./local/photo.png)')).toBe(true);
+ expect(admits('[x](<./local/photo.png?size=1#hero>)')).toBe(true);
+ expect(admits('[x](./doc.md)')).toBe(false);
});
test('classifies .base and .canvas hrefs as local asset references', () => {
- expect(isLocalAssetReferenceHref('./Characters.base')).toBe(true);
- expect(isLocalAssetReferenceHref('Characters.base')).toBe(true);
- expect(isLocalAssetReferenceHref('./vault/Board.canvas')).toBe(true);
+ expect(admits('[x](./Characters.base)')).toBe(true);
+ expect(admits('[x](Characters.base)')).toBe(true);
+ expect(admits('[x](./vault/Board.canvas)')).toBe(true);
});
test('resolves .base and .canvas hrefs to disk paths', () =>
@@ -112,6 +116,7 @@ describe('asset reference extraction', () => {
contentDir: dir,
fromDocName: 'vault/note',
href: './Characters.base',
+ literal: false,
}),
).toBe(realpathSync(resolve(dir, 'vault/Characters.base')));
@@ -120,6 +125,7 @@ describe('asset reference extraction', () => {
contentDir: dir,
fromDocName: 'vault/note',
href: './Board.canvas',
+ literal: false,
}),
).toBe(realpathSync(resolve(dir, 'vault/Board.canvas')));
@@ -129,6 +135,7 @@ describe('asset reference extraction', () => {
contentDir: dir,
fromDocName: 'vault/note',
href: 'Board.canvas',
+ literal: false,
}),
).toBe(realpathSync(resolve(dir, 'vault/Board.canvas')));
}));
@@ -192,6 +199,19 @@ describe('asset reference extraction', () => {
).toBe(true);
});
+ // The signature gates whether the collector re-runs, so it has to agree with
+ // the collector. Both of these edits change which file is referenced while
+ // leaving the href bytes recognizable only to a plane-aware, decoded reading —
+ // a signature that collapsed either would report "unchanged" and serve a stale
+ // cache.
+ test('signature notices a plane switch on identical href bytes', () => {
+ expect(assetReferencesChanged('![[100%20done.png]]', '[x](100%20done.png)')).toBe(true);
+ });
+
+ test('signature notices an asset whose extension is escaped', () => {
+ expect(assetReferencesChanged('no refs here', '[x](./photo%2Ejpg)')).toBe(true);
+ });
+
test('resolves only existing local assets inside contentDir', () =>
withFixture((dir) => {
mkdirSync(join(dir, 'docs'));
@@ -204,6 +224,7 @@ describe('asset reference extraction', () => {
contentDir: dir,
fromDocName: 'docs/guide',
href: './photo.png',
+ literal: false,
}),
).toBe(realpathSync(resolve(dir, 'docs/photo.png')));
expect(
@@ -211,6 +232,7 @@ describe('asset reference extraction', () => {
contentDir: dir,
fromDocName: 'docs/guide',
href: '/docs/photo.png',
+ literal: false,
}),
).toBe(realpathSync(resolve(dir, 'docs/photo.png')));
expect(
@@ -218,6 +240,7 @@ describe('asset reference extraction', () => {
contentDir: dir,
fromDocName: 'docs/guide',
href: '<./My%20Photo.png>',
+ literal: false,
}),
).toBe(realpathSync(resolve(dir, 'docs/My Photo.png')));
expect(
@@ -225,6 +248,7 @@ describe('asset reference extraction', () => {
contentDir: dir,
fromDocName: 'docs/guide',
href: './paper.pdf',
+ literal: false,
}),
).toBe(realpathSync(resolve(dir, 'docs/paper.pdf')));
@@ -233,6 +257,7 @@ describe('asset reference extraction', () => {
contentDir: dir,
fromDocName: 'docs/guide',
href: 'https://example.com/photo.png',
+ literal: false,
}),
).toBeNull();
expect(
@@ -240,6 +265,7 @@ describe('asset reference extraction', () => {
contentDir: dir,
fromDocName: 'docs/guide',
href: '../outside.png',
+ literal: false,
}),
).toBeNull();
expect(
@@ -247,10 +273,124 @@ describe('asset reference extraction', () => {
contentDir: dir,
fromDocName: 'docs/guide',
href: './missing.png',
+ literal: false,
}),
).toBeNull();
}));
+ test('resolves a %2520 href to a filename containing literal %20 without double decoding', () =>
+ withFixture((dir) => {
+ mkdirSync(join(dir, 'docs'));
+ writeFileSync(join(dir, 'docs', 'My%20Photo.png'), 'png');
+ // RFC 3986 §2.4: escaped octets decode exactly once, so `%2520`
+ // addresses the literal-`%20` filename above. The space-named
+ // sibling exists to catch a double decode, which would land here.
+ writeFileSync(join(dir, 'docs', 'My Photo.png'), 'png');
+
+ expect(
+ resolveReferencedAssetPath({
+ contentDir: dir,
+ fromDocName: 'docs/guide',
+ href: '<./My%2520Photo.png>',
+ literal: false,
+ }),
+ ).toBe(realpathSync(resolve(dir, 'docs', 'My%20Photo.png')));
+ }));
+
+ test('a wiki target names the literal filename, not its decoded neighbour', () =>
+ withFixture((dir) => {
+ mkdirSync(join(dir, 'docs'));
+ // Both files exist, so a wrong plane resolves to a real path rather than
+ // to null — a test that only asserted "not null" would pass either way.
+ writeFileSync(join(dir, 'docs', '100%20done.png'), 'png');
+ writeFileSync(join(dir, 'docs', '100 done.png'), 'png');
+
+ expect(
+ resolveReferencedAssetPath({
+ contentDir: dir,
+ fromDocName: 'docs/guide',
+ href: '100%20done.png',
+ literal: true,
+ }),
+ ).toBe(realpathSync(resolve(dir, 'docs', '100%20done.png')));
+ expect(
+ resolveReferencedAssetPath({
+ contentDir: dir,
+ fromDocName: 'docs/guide',
+ href: '100%20done.png',
+ literal: true,
+ }),
+ ).not.toBe(realpathSync(resolve(dir, 'docs', '100 done.png')));
+ // The markdown plane, given the identical bytes, reaches the other file.
+ expect(
+ resolveReferencedAssetPath({
+ contentDir: dir,
+ fromDocName: 'docs/guide',
+ href: './100%20done.png',
+ literal: false,
+ }),
+ ).toBe(realpathSync(resolve(dir, 'docs', '100 done.png')));
+ }));
+
+ test('the collector carries each reference plane from its authored syntax', () =>
+ withFixture((dir) => {
+ mkdirSync(join(dir, 'docs'));
+ writeFileSync(join(dir, 'docs', '100%20done.png'), 'png');
+ writeFileSync(join(dir, 'docs', '100 done.png'), 'png');
+ writeFileSync(
+ join(dir, 'docs', 'guide.md'),
+ // Same bytes, two syntaxes: the wiki embed must land on the literal
+ // name and the markdown link on the decoded one.
+ '![[100%20done.png]]\n\n![md](./100%20done.png)\n',
+ );
+
+ const assets = collectReferencedAssets({
+ contentDir: dir,
+ fileIndex: new Map<string, FileIndexEntry>([
+ [
+ 'docs/guide',
+ { canonicalPath: join(dir, 'docs', 'guide.md') } as unknown as FileIndexEntry,
+ ],
+ ]),
+ readMarkdown: (path) =>
+ path.endsWith('guide.md') ? '![[100%20done.png]]\n\n![md](./100%20done.png)\n' : null,
+ });
+
+ expect(assets.map((a) => a.path).sort()).toEqual([
+ 'docs/100 done.png',
+ 'docs/100%20done.png',
+ ]);
+ }));
+
+ // The case above authors the two planes with different bytes (`./` prefix), so
+ // it never reaches the collector's dedup. Byte-identical hrefs do, and they
+ // still name two different files — keying dedup on the bytes alone would drop
+ // one of them.
+ test('byte-identical hrefs on both planes are both collected', () =>
+ withFixture((dir) => {
+ mkdirSync(join(dir, 'docs'));
+ writeFileSync(join(dir, 'docs', '100%20done.png'), 'png');
+ writeFileSync(join(dir, 'docs', '100 done.png'), 'png');
+ const md = '![[100%20done.png]]\n\n[md](100%20done.png)\n';
+ writeFileSync(join(dir, 'docs', 'guide.md'), md);
+
+ const assets = collectReferencedAssets({
+ contentDir: dir,
+ fileIndex: new Map<string, FileIndexEntry>([
+ [
+ 'docs/guide',
+ { canonicalPath: join(dir, 'docs', 'guide.md') } as unknown as FileIndexEntry,
+ ],
+ ]),
+ readMarkdown: (path) => (path.endsWith('guide.md') ? md : null),
+ });
+
+ expect(assets.map((a) => a.path).sort()).toEqual([
+ 'docs/100 done.png',
+ 'docs/100%20done.png',
+ ]);
+ }));
+
test('collects referenced assets with referencing docs and ignores unreferenced files', () =>
withFixture((dir) => {
mkdirSync(join(dir, 'docs'), { recursive: true });
@@ -415,6 +555,7 @@ describe('asset reference extraction', () => {
contentDir: join(tmpdir(), 'ok-missing-content-dir'),
fromDocName: 'docs/guide',
href: './photo.png',
+ literal: false,
}),
).toBeNull();
expect(warnSpy).toHaveBeenCalled();
diff --git a/packages/server/src/asset-references.ts b/packages/server/src/asset-references.ts
index a9a1fae03..f5d161dc3 100644
--- a/packages/server/src/asset-references.ts
+++ b/packages/server/src/asset-references.ts
@@ -2,6 +2,7 @@ import { realpathSync, type Stats, statSync } from 'node:fs';
import { extname, normalize, resolve, sep } from 'node:path';
import {
createCodeFenceTracker,
+ decodeHrefPath,
type InlineAssetMediaKind,
LINKABLE_ASSET_EXTENSIONS,
mediaKindForSidebarAssetExtension,
@@ -47,17 +48,37 @@ export function stripHrefDecorations(rawHref: string): string {
return queryIndex >= 0 ? withoutHash.slice(0, queryIndex) : withoutHash;
}
-export function isLocalAssetReferenceHref(rawHref: string): boolean {
- const href = stripHrefDecorations(rawHref);
+/**
+ * Whether a collected reference names a linkable asset, judged on the bytes the
+ * resolver will actually use: a markdown destination is a URI, so its extension
+ * only appears once escapes are resolved (`photo%2Ejpg` reads as extension-less
+ * raw), while a wiki target is already literal.
+ */
+function isLocalAssetReference(ref: LocalAssetReference): boolean {
+ const href = stripHrefDecorations(ref.href);
if (!href || isRemoteOrOpaqueHref(href)) return false;
- return LINKABLE_ASSET_EXTENSIONS.has(extname(href).slice(1).toLowerCase());
+ const resolvedBytes = ref.literal ? href : decodeHrefPath(href);
+ return LINKABLE_ASSET_EXTENSIONS.has(extname(resolvedBytes).slice(1).toLowerCase());
}
+/**
+ * Change-detection key for the referenced-asset cache. It must agree with the
+ * collector it gates, so it carries the plane and reads extensions off resolved
+ * bytes exactly as `extractLocalAssetReferences` does — a signature that
+ * collapsed either distinction would report "unchanged" for an edit that moves
+ * the reference to a different file, and the cache would serve a stale answer.
+ */
export function assetReferenceSignature(markdown: string | null): string {
if (!markdown) return '';
- return [...new Set(extractLocalAssetHrefs(markdown).filter(isLocalAssetReferenceHref))]
+ // No second dedup here: `extractLocalAssetReferences` already keys its map on
+ // the same (plane, href) pair, so a `Set` over these could only ever be a
+ // no-op — and one spelled with a different separator than the map it shadows,
+ // which reads as though the two enforce different conditions.
+ return extractLocalAssetReferences(markdown)
+ .filter(isLocalAssetReference)
+ .map((ref) => `${ref.literal ? 'w' : 'm'}\0${ref.href}`)
.sort()
- .join('\0');
+ .join('\u0001');
}
export function assetReferencesChanged(
@@ -67,15 +88,6 @@ export function assetReferencesChanged(
return assetReferenceSignature(previousMarkdown) !== assetReferenceSignature(persistedMarkdown);
}
-function decodeHrefPath(rawHref: string): string {
- const stripped = stripHrefDecorations(rawHref);
- try {
- return decodeURI(stripped);
- } catch {
- return stripped;
- }
-}
-
function mediaKindForAssetPath(path: string): InlineAssetMediaKind | null {
const ext = extname(path).slice(1).toLowerCase();
return mediaKindForSidebarAssetExtension(ext);
@@ -85,19 +97,35 @@ function errnoCode(err: unknown): string | null {
return err instanceof Error && 'code' in err && typeof err.code === 'string' ? err.code : null;
}
-function collectHrefsFromLine(line: string, hrefs: Set<string>): void {
+function collectHrefsFromLine(line: string, refs: Map<string, LocalAssetReference>): void {
+ const add = (href: string, literal: boolean): void => {
+ // Key on the plane too, not the bytes alone. The same byte string authored
+ // both ways names two DIFFERENT files — `![[100%20done.png]]` is a literal
+ // filename while `[x](100%20done.png)` decodes to `100 done.png` — so
+ // deduping on `href` would silently drop one real reference, re-collapsing
+ // at dedup time the very distinction this collector carries. Emitting both
+ // adds no duplicate downstream: `collectReferencedAssets` keys its output by
+ // RESOLVED path, and the two resolve apart. First writer still wins within a
+ // plane, so the map stays insertion-ordered like the Set it replaced.
+ const key = `${literal ? 'w' : 'm'} ${href}`;
+ if (!refs.has(key)) refs.set(key, { href, literal });
+ };
// nestedBracketLabels keeps the pre-consolidation preference for the
// OUTER destination of badge-style `[![alt](img)](file.pdf)` links —
// the linked file counts as the referenced asset, not the inner image.
for (const match of matchMarkdownLinks(line, { nestedBracketLabels: true })) {
- if (match.href) hrefs.add(match.href);
+ if (match.href) add(match.href, false);
}
+ // A wiki target is a literal filename, not a URI — `![[100%20done.png]]`
+ // names a file whose name really contains those three characters. Collapsing
+ // both forms into one untagged list is what let the plane get lost between
+ // recognition and resolution.
for (const match of matchWikiLinks(line)) {
- hrefs.add(match.target);
+ add(match.target, true);
}
for (const match of line.matchAll(HTML_LINK_ATTR_RE)) {
const href = match[1] ?? match[2] ?? match[3] ?? match[4];
- if (href) hrefs.add(href);
+ if (href) add(href, false);
}
}
@@ -121,16 +149,31 @@ function stripHtmlComments(line: string, state: { inComment: boolean }): string
return visible;
}
-export function extractLocalAssetHrefs(markdown: string): string[] {
- const hrefs = new Set<string>();
+/**
+ * One authored asset reference plus the plane its bytes live on. The plane is
+ * decided at recognition time (by the syntax that produced the reference) and
+ * carried to resolution, because `resolveAssetProjectPath` cannot recover it.
+ */
+interface LocalAssetReference {
+ href: string;
+ /** `true` for wiki targets (literal filename), `false` for markdown/HTML URIs. */
+ literal: boolean;
+}
+
+function extractLocalAssetReferences(markdown: string): LocalAssetReference[] {
+ const refs = new Map<string, LocalAssetReference>();
const isInCodeFence = createCodeFenceTracker();
const htmlCommentState = { inComment: false };
for (const rawLine of markdown.replaceAll('\r\n', '\n').replaceAll('\r', '\n').split('\n')) {
if (isInCodeFence(rawLine)) continue;
const line = stripHtmlComments(rawLine, htmlCommentState).replace(/`[^`]*`/g, '');
- collectHrefsFromLine(line, hrefs);
+ collectHrefsFromLine(line, refs);
}
- return [...hrefs];
+ return [...refs.values()];
+}
+
+export function extractLocalAssetHrefs(markdown: string): string[] {
+ return extractLocalAssetReferences(markdown).map((ref) => ref.href);
}
interface ResolvedReferencedAsset {
@@ -143,14 +186,20 @@ function resolveReferencedAssetWithinContentDir(args: {
contentDir: string;
fromDocName: string;
href: string;
+ literal: boolean;
}): ResolvedReferencedAsset | null {
- const href = decodeHrefPath(args.href);
+ const href = stripHrefDecorations(args.href);
if (!href || isRemoteOrOpaqueHref(href)) return null;
- const ext = extname(href).slice(1).toLowerCase();
- if (!LINKABLE_ASSET_EXTENSIONS.has(ext)) return null;
- const relativeAssetPath = resolveAssetProjectPath(href, args.fromDocName);
+ // Read the extension off the RESOLVED path, not the raw href: on the markdown
+ // plane the resolver decodes, so an escaped extension dot (`photo%2Ejpg`)
+ // only looks like an extension after resolution.
+ const relativeAssetPath = resolveAssetProjectPath(href, args.fromDocName, {
+ literal: args.literal,
+ });
if (!relativeAssetPath) return null;
+ const ext = extname(relativeAssetPath).slice(1).toLowerCase();
+ if (!LINKABLE_ASSET_EXTENSIONS.has(ext)) return null;
const requestedPath = resolve(args.contentDir, relativeAssetPath);
let canonicalPath: string;
let stat: Stats;
@@ -177,6 +226,8 @@ export function resolveReferencedAssetPath(args: {
contentDir: string;
fromDocName: string;
href: string;
+ /** Wiki plane (literal filename) vs markdown/HTML plane (URI that decodes). */
+ literal: boolean;
}): string | null {
let contentDir: string;
try {
@@ -219,11 +270,12 @@ export function collectReferencedAssets(args: {
for (const [docName, entry] of args.fileIndex) {
const markdown = args.readMarkdown(entry.canonicalPath);
if (markdown === null) continue;
- for (const href of extractLocalAssetHrefs(markdown)) {
+ for (const ref of extractLocalAssetReferences(markdown)) {
const asset = resolveReferencedAssetWithinContentDir({
contentDir,
fromDocName: docName,
- href,
+ href: ref.href,
+ literal: ref.literal,
});
if (!asset) continue;
if (args.isExcluded?.(asset.relativePath)) continue;
diff --git a/packages/server/src/backlink-index.ts b/packages/server/src/backlink-index.ts
index 882535b19..9c2983174 100644
--- a/packages/server/src/backlink-index.ts
+++ b/packages/server/src/backlink-index.ts
@@ -81,7 +81,11 @@ function namesExistingFile(
): boolean {
if (!oracle) return false;
if (isSupportedDocFile(href)) return false;
- const filePath = resolveAssetProjectPath(href, sourceDocName);
+ // Markdown plane only: both callers hand this a markdown destination (an
+ // inline `[text](href)` and a reference definition's destination), which is a
+ // URI whose escapes decode. Wiki targets never reach here — they resolve by
+ // vault-wide basename, not by a source-relative path.
+ const filePath = resolveAssetProjectPath(href, sourceDocName, { literal: false });
return filePath !== null && oracle.hasFile(filePath);
}
@@ -1091,7 +1095,9 @@ export function computeBrokenOutboundLinks(
// `../src/foo.py`). It has no CRDT presence, so validate the resolved
// path against disk. Skip when no oracle is injected.
if (!fileExists) return;
- const filePath = resolveAssetProjectPath(classified.url, sourceDocName);
+ const filePath = resolveAssetProjectPath(classified.url, sourceDocName, {
+ literal: classified.literal,
+ });
if (filePath === null) {
// `../`-overshoot past the content root — the off-by-one depth bug.
record(trimmed, null, 'unresolvable');
diff --git a/packages/server/src/content/generate-index.test.ts b/packages/server/src/content/generate-index.test.ts
index 0dfbfbe10..b5a682df1 100644
--- a/packages/server/src/content/generate-index.test.ts
+++ b/packages/server/src/content/generate-index.test.ts
@@ -1,3 +1,4 @@
+import { resolveInternalHref } from '@inkeep/open-knowledge-core';
import { describe, expect, test } from 'vitest';
import { buildIndexMarkdown, type IndexEntry } from './generate-index.ts';
@@ -319,4 +320,32 @@ describe('buildIndexMarkdown', () => {
expect(reversed).toBe(forward);
});
+
+ test('emitted hrefs round-trip through the canonical resolver to the entry they came from', () => {
+ // The generator's percent-encoding is the only CommonMark-valid way to link
+ // these names (a literal space does not parse as an unbracketed link
+ // destination), so the encoded href must resolve back to the original
+ // docName through the same resolver every link surface consumes
+ // (precedent #56). A generated index whose own validator flags its links
+ // as dead is the failure this pins against.
+ const names = [
+ 'Agent Memory',
+ 'team plan (draft) #1',
+ 'R&D notes',
+ "don't panic!",
+ 'café résumé',
+ ];
+ const out = buildIndexMarkdown(
+ names.map((name) => entry({ path: `blogs/drafts/${name}.md`, title: name, type: 'note' })),
+ { isRoot: false, directory: 'blogs/drafts' },
+ );
+
+ const hrefs = [...out.matchAll(/\]\(([^)]+)\)/g)].map((match) => match[1] ?? '');
+ expect(hrefs).toHaveLength(names.length);
+
+ const resolved = hrefs.map(
+ (href) => resolveInternalHref(href, 'blogs/drafts/index')?.docName ?? `<unresolved ${href}>`,
+ );
+ expect(resolved.toSorted()).toEqual(names.map((name) => `blogs/drafts/${name}`).toSorted());
+ });
});
diff --git a/packages/server/src/content/generate-index.ts b/packages/server/src/content/generate-index.ts
index 6e9e69300..21620aec7 100644
--- a/packages/server/src/content/generate-index.ts
+++ b/packages/server/src/content/generate-index.ts
@@ -23,6 +23,8 @@
* without a server, a disk, or a Y.Doc.
*/
+import { encodeHrefPath } from '@inkeep/open-knowledge-core';
+
/** One document as the index renders it. `path` is content-root-relative. */
export interface IndexEntry {
path: string;
@@ -151,14 +153,6 @@ function escapeLinkLabel(value: string): string {
return toSingleLine(value).replace(/[\\[\]]/g, '\\$&');
}
-/** RFC 3986 segment encoding keeps `/` as hierarchy and neutralizes `()`/spaces. */
-function encodePathSegment(segment: string): string {
- return encodeURIComponent(segment).replace(
- /[!'()*]/g,
- (char) => `%${char.codePointAt(0)?.toString(16).toUpperCase()}`,
- );
-}
-
/**
* Strip the index's own directory prefix so a content-root-relative path renders
* relative to where the index lives. Entries are always at or below `directory`
@@ -184,7 +178,7 @@ function relativeTo(directory: string, path: string): string {
*/
function toHref(relativePath: string): string {
const normalized = relativePath.replaceAll('\\', '/');
- return `./${normalized.split('/').map(encodePathSegment).join('/')}`;
+ return `./${encodeHrefPath(normalized)}`;
}
function renderLink(link: RenderableLink, directory: string): string {
diff --git a/packages/server/src/local-target-assessment.test.ts b/packages/server/src/local-target-assessment.test.ts
index 164029f5c..89d1ed007 100644
--- a/packages/server/src/local-target-assessment.test.ts
+++ b/packages/server/src/local-target-assessment.test.ts
@@ -418,3 +418,48 @@ describe('toForwardLinkLocalTargets — Links panel Local files projection', ()
expect(rows).toEqual([]);
});
});
+
+// The reported symptom was a false `dead-link` on a link the generated index
+// emitted itself. Pinning it here, at the tier that produces the verdict the
+// user sees, keeps the contract honest if the resolver is ever refactored.
+describe('percent-encoded targets are assessed against the decoded document', () => {
+ test('an encoded link to an existing document is exact, not missing', () => {
+ const a = assessOne(
+ '[Agent Memory](./Agent%20Memory.md)',
+ inventory({ docs: ['notes/Agent Memory'] }),
+ );
+ expect(a).toMatchObject({
+ targetKind: 'document',
+ resolvedTarget: 'notes/Agent Memory',
+ status: 'exact',
+ reason: null,
+ });
+ });
+
+ test('an encoded link to a genuinely absent document still reports missing', () => {
+ const a = assessOne('[Gone](./Not%20Here.md)', inventory({ docs: ['notes/Agent Memory'] }));
+ expect(a).toMatchObject({ targetKind: 'document', status: 'missing' });
+ });
+
+ test('an encoded asset link resolves to the decoded file', () => {
+ const a = assessOne(
+ '[Spec](./design%20spec.pdf)',
+ inventory({ files: ['notes/design spec.pdf'] }),
+ );
+ expect(a).toMatchObject({ status: 'exact' });
+ });
+
+ // The two planes reach the same asset resolver with the same shape, so the
+ // decode has to be gated on the authored form. A wiki target names the file
+ // literally; decoding it would hunt for a different file and report the same
+ // false dead-link this work exists to remove.
+ test('a wiki asset embed keeps percent sequences literal', () => {
+ const a = assessOne('![[100%20done.png]]', inventory({ files: ['notes/100%20done.png'] }));
+ expect(a).toMatchObject({ status: 'exact' });
+ });
+
+ test('a wiki asset embed does not resolve to the decoded neighbour', () => {
+ const a = assessOne('![[100%20done.png]]', inventory({ files: ['notes/100 done.png'] }));
+ expect(a).toMatchObject({ status: 'missing' });
+ });
+});
diff --git a/packages/server/src/local-target-assessment.ts b/packages/server/src/local-target-assessment.ts
index 327cb5350..ae4e837c5 100644
--- a/packages/server/src/local-target-assessment.ts
+++ b/packages/server/src/local-target-assessment.ts
@@ -240,8 +240,9 @@ function assessFile(
href: string,
sourceDocName: string,
inventory: LocalTargetInventory,
+ literal: boolean,
): SharedAssessment {
- const filePath = resolveAssetProjectPath(assetUrl, sourceDocName);
+ const filePath = resolveAssetProjectPath(assetUrl, sourceDocName, { literal });
if (filePath === null) {
// `../` overshoot past the content root — no project-local path.
return { ...UNRESOLVABLE, targetKind: 'file' };
@@ -330,7 +331,7 @@ function assessHref(
// extension-bearing embed still classifies as a file through the `asset`
// branch below, because `classifyMarkdownHref` never routes it here.
if (role === 'image' && !isWikiForm(sourceForm)) {
- return assessFile(href, href, sourceDocName, inventory);
+ return assessFile(href, href, sourceDocName, inventory, false);
}
const documentExists = inventory.hasDocument(classified.docName);
// The file fallback is markdown-only, and deliberately so. It resolves
@@ -340,13 +341,20 @@ function assessHref(
// document by contract anyway: `[[Note]]` names a note, and an
// extension-bearing one never reaches this branch.
if (!documentExists && !isWikiForm(sourceForm)) {
- const file = assessFile(href, href, sourceDocName, inventory);
+ const file = assessFile(href, href, sourceDocName, inventory, false);
if (file.status === 'exact') return file;
}
return assessDocument(classified.docName, href, sourceDocName, inventory, documentExists);
}
case 'asset':
- return assessFile(classified.url, href, sourceDocName, inventory);
+ // Both classifiers emit the same `{kind: 'asset', url}` shape, so the
+ // plane rides on the target's own `literal` tag rather than being
+ // re-derived from `sourceForm` here. A wiki target names a file
+ // literally: `![[100%20done.png]]` means a file whose name contains
+ // `%20`, and decoding it would look for a different file and report a
+ // false dead-link — the very symptom this resolver's decoding half fixes
+ // on the markdown plane.
+ return assessFile(classified.url, href, sourceDocName, inventory, classified.literal);
case 'external':
case 'anchor':
return null;
diff --git a/packages/server/src/local-target-index.test.ts b/packages/server/src/local-target-index.test.ts
index 35974e3ac..681fbf4a1 100644
--- a/packages/server/src/local-target-index.test.ts
+++ b/packages/server/src/local-target-index.test.ts
@@ -156,6 +156,27 @@ describe('LocalTargetIndex reverse-dependent freshness', () => {
});
});
+ test('wiki forms are not projected here, which is what fixes this index on the URI plane', () => {
+ // The extension-less disambiguation candidate resolves every href as a URI
+ // (percent escapes decode). That is only sound because no wiki form reaches
+ // this index — a wiki target is a literal filename, and decoding one would
+ // key its dependent under a path nothing else looks up. Admitting wiki
+ // forms without revisiting the plane turns this red rather than silently
+ // registering candidates under decoded names.
+ const index = createIndex();
+ index.setSource('src', 'See [[100%20done]] and ![[100%20done.png]].\n');
+ expect(index.getAssessments('src')).toEqual([]);
+ expect(index.getFileDependents('100 done')).toEqual([]);
+ expect(index.getDocumentDependents('100 done')).toEqual([]);
+
+ // Control: identical bytes authored as a markdown link ARE a URI, so the
+ // decoded candidate is exactly right there.
+ const markdownIndex = createIndex();
+ markdownIndex.setSource('src', 'See [progress](100%20done).\n');
+ expect(markdownIndex.getFileDependents('100 done')).toEqual(['src']);
+ expect(markdownIndex.getFileDependents('100%20done')).toEqual([]);
+ });
+
test('a content-only file-update event does not flip existence or bump the generation', () => {
const index = createIndex();
index.setSource('src', 'Download [pdf](assets/report.pdf).\n');
diff --git a/packages/server/src/local-target-index.ts b/packages/server/src/local-target-index.ts
index 22e9668f8..8178c7cb7 100644
--- a/packages/server/src/local-target-index.ts
+++ b/packages/server/src/local-target-index.ts
@@ -136,11 +136,22 @@ function assessmentTargetDeps(
// Extension-less links are inventory-disambiguated. Retain both candidate
// edges even while one wins so a file delete/recreate or document
// create/delete can move the verdict back in either direction.
+ //
+ // Markdown plane throughout: only `markdown-inline` / `markdown-reference` /
+ // `html-img` occurrences are projected onto this index at all
+ // (`isProjectableToLocalTargetSurfaces` drops the wiki forms), so every href
+ // reaching here is a URI whose escapes decode — the same reading
+ // `classifyMarkdownHref` just applied to it two lines up. Re-check that
+ // projection filter before admitting a wiki form here; a literal target
+ // resolved with this decode would key the candidate under a path nothing
+ // else looks up.
if (assessment.occurrence.role === 'link') {
const classified = classifyMarkdownHref(assessment.occurrence.href, sourceDocName);
if (classified?.kind === 'doc') {
docs.push(classified.docName);
- const filePath = resolveAssetProjectPath(assessment.occurrence.href, sourceDocName);
+ const filePath = resolveAssetProjectPath(assessment.occurrence.href, sourceDocName, {
+ literal: false,
+ });
if (filePath === classified.docName) files.push(filePath);
}
}
diff --git a/packages/server/src/managed-rename-rewrite.test.ts b/packages/server/src/managed-rename-rewrite.test.ts
index bbaf89bef..9a70d135d 100644
--- a/packages/server/src/managed-rename-rewrite.test.ts
+++ b/packages/server/src/managed-rename-rewrite.test.ts
@@ -1,8 +1,10 @@
+import { resolveAssetProjectPath, resolveInternalHref } from '@inkeep/open-knowledge-core';
import { describe, expect, test } from 'vitest';
import {
rewriteAssetReferencesForRename,
rewriteMarkdownLinksForDocumentRename,
rewriteMirrorSrcForDocumentRename,
+ rewriteOutboundMarkdownLinksForSourceMove,
rewriteWikiLinksForDocumentRename,
} from './managed-rename-rewrite.ts';
@@ -521,8 +523,28 @@ describe('rewriteAssetReferencesForRename', () => {
'docs/final/asset with spaces (2).png',
);
+ // Parens are escaped, not passed through: the canonical segment encoder
+ // neutralizes `!'()*` so an unbalanced paren can never terminate a bare
+ // CommonMark destination. Both spellings resolve back to the same asset.
expect(result).toEqual({
- markdown: '![Spaced](./final/asset%20with%20spaces%20(2).png?dl=1#hero)\n',
+ markdown: '![Spaced](./final/asset%20with%20spaces%20%282%29.png?dl=1#hero)\n',
+ rewrites: 1,
+ });
+ });
+
+ test('matches a %2520 href to a literal %20-bearing asset filename without double decoding', () => {
+ // RFC 3986 §2.4: an escaped octet is decoded exactly once — `%2520`
+ // denotes the literal bytes `%20` in the target filename. A second
+ // decode would turn it into a space and silently miss the asset.
+ const result = rewriteAssetReferencesForRename(
+ '![Literal](./media/name%2520with%2520percents.png)\n',
+ 'docs/guide',
+ 'docs/media/name%20with%20percents.png',
+ 'docs/final/name%20with%20percents.png',
+ );
+
+ expect(result).toEqual({
+ markdown: '![Literal](./final/name%2520with%2520percents.png)\n',
rewrites: 1,
});
});
@@ -541,6 +563,57 @@ describe('rewriteAssetReferencesForRename', () => {
});
});
+ test('a wiki asset target matches on its literal percent sequences', () => {
+ // `![[100%20done.png]]` names a file whose name really contains those three
+ // characters. Reading the target as a URI resolves it to `100 done.png`,
+ // which is not the asset being renamed, so the embed is left behind
+ // pointing at a path that no longer exists.
+ const result = rewriteAssetReferencesForRename(
+ '![[media/100%20done.png|Progress]]\n',
+ 'docs/guide',
+ 'docs/media/100%20done.png',
+ 'docs/final/100%20done.png',
+ );
+
+ expect(result).toEqual({
+ markdown: '![[final/100%20done.png|Progress]]\n',
+ rewrites: 1,
+ });
+ });
+
+ test('a wiki asset target does not match the decoded neighbour asset', () => {
+ // Companion to the assertion above. Renaming `docs/media/100 done.png` —
+ // the file the decoded reading names — must leave the literal-named embed
+ // untouched, or the rewrite repoints a working link at someone else's move.
+ const result = rewriteAssetReferencesForRename(
+ '![[media/100%20done.png|Progress]]\n',
+ 'docs/guide',
+ 'docs/media/100 done.png',
+ 'docs/final/100 done.png',
+ );
+
+ expect(result).toEqual({
+ markdown: '![[media/100%20done.png|Progress]]\n',
+ rewrites: 0,
+ });
+ });
+
+ test('a markdown asset href still matches the decoded asset path', () => {
+ // The other half of the plane split: identical authored bytes, markdown
+ // syntax, must resolve to the space-named file and rewrite.
+ const result = rewriteAssetReferencesForRename(
+ '![Progress](./media/100%20done.png)\n',
+ 'docs/guide',
+ 'docs/media/100 done.png',
+ 'docs/final/100 done.png',
+ );
+
+ expect(result).toEqual({
+ markdown: '![Progress](./final/100%20done.png)\n',
+ rewrites: 1,
+ });
+ });
+
test('rewrites HTML src and href attributes that point at the moved asset', () => {
const result = rewriteAssetReferencesForRename(
[
@@ -585,3 +658,77 @@ describe('rewriteAssetReferencesForRename', () => {
).toEqual({ markdown, rewrites: 0 });
});
});
+
+// Resolvers decode, so a rewriter that rebuilds an href from a decoded docName
+// must re-encode it. Without that the rewrite emits a literal space, `#`, or
+// `?` into the destination and the link stops parsing — corrupting the user's
+// markdown on disk on an ordinary rename.
+describe('rewritten hrefs round-trip back through the canonical resolvers', () => {
+ const awkward = [
+ 'Agent Memory',
+ 'team plan (draft) #1',
+ 'R&D notes',
+ "don't panic!",
+ 'café résumé',
+ ];
+
+ for (const name of awkward) {
+ test(`document rename to ${JSON.stringify(name)} emits a resolvable href`, () => {
+ const { markdown, rewrites } = rewriteMarkdownLinksForDocumentRename(
+ '[Link](./Old%20Name.md)\n',
+ 'blogs/drafts/index',
+ 'blogs/drafts/Old Name',
+ `blogs/drafts/${name}`,
+ );
+
+ expect(rewrites).toBe(1);
+ const href = markdown.match(/\]\((.*)\)/)?.[1] ?? '';
+ expect(href).not.toMatch(/[ ()#?]/);
+ expect(resolveInternalHref(href, 'blogs/drafts/index')?.docName).toBe(`blogs/drafts/${name}`);
+ });
+
+ test(`asset rename to ${JSON.stringify(name)} emits a resolvable href`, () => {
+ const { markdown, rewrites } = rewriteAssetReferencesForRename(
+ '![Img](./media/old%20name.png)\n',
+ 'docs/guide',
+ 'docs/media/old name.png',
+ `docs/final/${name}.png`,
+ );
+
+ expect(rewrites).toBe(1);
+ const href = markdown.match(/\]\((.*)\)/)?.[1] ?? '';
+ expect(href).not.toMatch(/[ ()#?]/);
+ expect(resolveAssetProjectPath(href, 'docs/guide', { literal: false })).toBe(
+ `docs/final/${name}.png`,
+ );
+ });
+ }
+
+ test('a source move re-encodes outbound links to space-bearing targets', () => {
+ const { markdown, rewrites } = rewriteOutboundMarkdownLinksForSourceMove(
+ '[Agent Memory](./Agent%20Memory.md)\n',
+ 'blogs/drafts/index',
+ 'blogs/index',
+ );
+
+ expect(rewrites).toBe(1);
+ expect(markdown).toBe('[Agent Memory](./drafts/Agent%20Memory.md)\n');
+ expect(resolveInternalHref('./drafts/Agent%20Memory.md', 'blogs/index')?.docName).toBe(
+ 'blogs/drafts/Agent Memory',
+ );
+ });
+
+ test('an asset name containing # is escaped, not left to truncate the href', () => {
+ const { markdown } = rewriteAssetReferencesForRename(
+ '![Hash](./media/my%23file.png)\n',
+ 'docs/guide',
+ 'docs/media/my#file.png',
+ 'docs/final/my#file.png',
+ );
+
+ expect(markdown).toBe('![Hash](./final/my%23file.png)\n');
+ expect(resolveAssetProjectPath('./final/my%23file.png', 'docs/guide', { literal: false })).toBe(
+ 'docs/final/my#file.png',
+ );
+ });
+});
diff --git a/packages/server/src/managed-rename-rewrite.ts b/packages/server/src/managed-rename-rewrite.ts
index ba48ade5e..9ef46c5c3 100644
--- a/packages/server/src/managed-rename-rewrite.ts
+++ b/packages/server/src/managed-rename-rewrite.ts
@@ -1,5 +1,10 @@
import { posix } from 'node:path';
-import { resolveAssetProjectPath, resolveInternalHref } from '@inkeep/open-knowledge-core';
+import {
+ encodeHrefPath,
+ encodeHrefPathSegment,
+ resolveAssetProjectPath,
+ resolveInternalHref,
+} from '@inkeep/open-knowledge-core';
import { readMarkdownLinkAt, readWikiLinkAt } from './link-syntax.ts';
interface FenceState {
@@ -247,14 +252,6 @@ function recomputeRelativeImageHref(
return `${newRef}${querySuffix}${hashSuffix}`;
}
-function decodeHrefForAssetResolution(href: string): string {
- try {
- return decodeURI(href);
- } catch {
- return href;
- }
-}
-
function splitHrefPathAndSuffix(href: string): {
pathPart: string;
suffix: string;
@@ -275,7 +272,10 @@ function buildAssetHrefFromSource(
options: { encodePath?: boolean } = {},
): string {
const encodePath = options.encodePath ?? true;
- const formatPath = (path: string) => (encodePath ? encodeURI(path) : path);
+ // Per-segment, not `encodeURI`: the latter leaves `#` and `?` raw, so an
+ // asset whose filename contains one is re-read as path + fragment/query and
+ // the rewritten link silently points somewhere else.
+ const formatPath = (path: string) => (encodePath ? encodeHrefPath(path) : path);
const { pathPart, suffix } = splitHrefPathAndSuffix(originalHref);
if (pathPart.startsWith('/')) return `/${formatPath(newAssetPath)}${suffix}`;
@@ -290,15 +290,22 @@ function buildAssetHrefFromSource(
return `${formatPath(nextHref)}${suffix}`;
}
+/**
+ * `options.literal` is the authored form's plane, threaded from the caller: a
+ * wiki target is a literal filename, a markdown/HTML destination is a URI whose
+ * escapes decode. It has to match `encodePath` on the way back out, or the
+ * rewrite reads one plane and writes the other.
+ */
function rewriteAssetHrefForRename(
originalHref: string,
sourceDocName: string,
oldAssetPath: string,
newAssetPath: string,
- options: { encodePath?: boolean } = {},
+ options: { literal: boolean; encodePath?: boolean },
): string | null {
- const decodedHref = decodeHrefForAssetResolution(originalHref);
- const resolved = resolveAssetProjectPath(decodedHref, sourceDocName);
+ const resolved = resolveAssetProjectPath(originalHref, sourceDocName, {
+ literal: options.literal,
+ });
if (resolved !== oldAssetPath) return null;
return buildAssetHrefFromSource(originalHref, sourceDocName, newAssetPath, options);
}
@@ -317,10 +324,13 @@ function recomputeRelativeMarkdownHref(
const keepsRootPrefix = pathPart.startsWith('/');
const sourceDir = posix.dirname(sourceDocName);
+ // docNames are decoded, hrefs are not: a name carrying a space, `#`, `?`, or
+ // a paren must be re-encoded on the way back out or the emitted destination
+ // stops parsing as a link.
let relativePath = keepsRootPrefix
- ? `/${newDocName}`
- : posix.relative(sourceDir === '.' ? '' : sourceDir, newDocName);
- relativePath ||= posix.basename(newDocName);
+ ? `/${encodeHrefPath(newDocName)}`
+ : encodeHrefPath(posix.relative(sourceDir === '.' ? '' : sourceDir, newDocName));
+ relativePath ||= encodeHrefPathSegment(posix.basename(newDocName));
// Preserve whatever supported doc extension the authored link carried.
// The canonical list lives at `packages/server/src/doc-extensions.ts`; this
@@ -459,7 +469,9 @@ function rewriteHtmlAssetAttrsInTag(
const markdown = tag.replace(HTML_ASSET_ATTR_RE, (whole, prefix, double, single, curly, bare) => {
const value = double ?? single ?? curly ?? bare;
if (typeof value !== 'string') return whole;
- const nextHref = rewriteAssetHrefForRename(value, sourceDocName, oldAssetPath, newAssetPath);
+ const nextHref = rewriteAssetHrefForRename(value, sourceDocName, oldAssetPath, newAssetPath, {
+ literal: false,
+ });
if (nextHref === null) return whole;
rewrites++;
if (double !== undefined) return `${prefix}"${nextHref}"`;
@@ -509,7 +521,7 @@ function rewriteAssetReferencesInLine(
sourceDocName,
oldAssetPath,
newAssetPath,
- { encodePath: false },
+ { literal: true, encodePath: false },
);
if (nextTarget !== null) {
rewritten += renderWikiLinkOrEmbed(wikiLink, nextTarget);
@@ -559,6 +571,7 @@ function rewriteAssetReferencesInLine(
sourceDocName,
oldAssetPath,
newAssetPath,
+ { literal: false },
);
if (nextHref !== null) {
const hrefRaw =
@@ -583,6 +596,7 @@ function rewriteAssetReferencesInLine(
sourceDocName,
oldAssetPath,
newAssetPath,
+ { literal: false },
);
if (nextHref !== null) {
const hrefRaw =