@williamthorsen/kb 0.7.0 → 0.8.1

package/dist/esm/scaffold/render-seeds.d.ts

@@ -1,6 +1,6 @@
 /**
- * The formatting option every store carries that `.editorconfig` cannot express. Held here rather than in the seed
- * prose, so that the file that a store receives cannot diverge from the value that kb documents. See
+ * The formatting option that every store sets and that `.editorconfig` cannot express. Defined here rather than in
+ * the seed prose, so that the file that a store receives cannot diverge from the value that kb documents. See
  * {@link renderPrettierSeed}'s header for what it prevents.
  */
 export declare const canonicalPrettierConfig: {
@@ -10,7 +10,7 @@ export declare const canonicalPrettierConfig: {
 export declare function renderAliasesSeed(): string;
 /** Renders `.kb/config.yaml`: a fully-commented stub whose example values are the live `defaultKbConfig`. */
 export declare function renderConfigSeed(): string;
-/** Renders `.editorconfig`: the editor and formatter settings every store shares. */
+/** Renders `.editorconfig`: the editor and formatter settings that every store shares. */
 export declare function renderEditorconfigSeed(): string;
 /** Renders `.prettierrc.yaml`: the canonical formatting option under a header explaining why it is set. */
 export declare function renderPrettierSeed(): string;

package/dist/esm/scaffold/render-seeds.js

@@ -9,9 +9,11 @@ const ALIASES_HEADER = `# Tag aliases for this knowledge store.
 `;
 const CONFIG_HEADER = `# Check configuration for this knowledge store.
 #
-# Both keys are optional and fall back to the defaults shown below; an absent file uses these defaults too. Uncomment
+# Every key is optional and falls back to the default shown below; an absent file uses these defaults too. Uncomment
 # and edit to override. \`targets\` selects which notes \`kb check\` enumerates and \`exclude\` removes matches;
-# patterns are slash-separated and relative to the store root.
+# patterns are slash-separated and relative to the store root. \`visibility\` declares how widely the store is
+# published, which decides what may link into it: A \`[[store:Note title]]\` link resolves only into a store as
+# shareable as its own or more so.
 #
 `;
 const EDITORCONFIG_SEED = `root = true
@@ -34,7 +36,7 @@ const PRETTIER_HEADER = `# Formatting configuration for this knowledge store.
 #
 # \`embeddedLanguageFormatting: off\` leaves a note's YAML frontmatter unformatted. Formatted, a long \`tags\` or
 # \`addressed-by\` list breaks across several lines, which the note writer puts back onto one the next time it writes
-# the note, so the formatter and the writer would rewrite each other's output without end.
+# the note. The formatter and the writer would rewrite each other's output without end.
 #
 # Width, indentation, and line endings are set in \`.editorconfig\`, which Prettier reads and every editor reads too.
 #

package/dist/esm/scaffold/scaffold.d.ts

@@ -1,21 +1,20 @@
 /**
- * What {@link scaffold} did about one canonical path: `created` where it was absent, `present` where it was left as
- * found, `replaced` where `force` overwrote it.
+ * What {@link scaffold} did about one canonical path: `created` when it was absent, `present` when it was left as
+ * found, `replaced` when `force` overwrote it.
  */
 export type ScaffoldAction = 'created' | 'present' | 'replaced';
 /** One canonical path and what the scaffold did about it. */
 export interface ScaffoldEntry {
-    /** The store-relative path, directories carrying a trailing slash. */
+    /** The store-relative path, directories with a trailing slash. */
     path: string;
     action: ScaffoldAction;
 }
 /**
- * Writes the canonical files and directories every knowledge-base store holds, leaving an existing file as it found it
- * unless `force` is set. Directories are ensured either way, since a directory has no content to replace.
+ * Writes the canonical files and directories that every knowledge-base store contains, leaving an existing file as it
+ * found it unless `force` is set. Directories are ensured either way, since a directory has no content to replace.
  *
- * The function asserts nothing about the store: a caller that requires one to exist, or requires one not to, checks
- * that itself. `create` calls it on a directory it has just confirmed holds no store, and `kb scaffold` on one it has
- * just confirmed does.
+ * The function asserts nothing about the store: A caller that requires one to exist, or requires one not to, checks
+ * that itself.
  */
 export declare function scaffold(input: {
     storePath: string;

package/dist/esm/tags/load-aliases.d.ts

@@ -1,15 +1,14 @@
 import type { AliasMap, KbRoot } from '../types.js';
 /**
  * Loads `.kb/tag-aliases.yaml` from a KB root into a typed `AliasMap`, returning an empty map when the file is absent.
- * The thin I/O wrapper around {@link parseAliases}; structural defects throw with the file path included.
+ * The thin I/O wrapper around {@link parseAliases}; on a structural defect it throws, naming the file path.
  */
 export declare function loadAliases(input: {
     kbRoot: KbRoot;
 }): Promise<AliasMap>;
 /**
  * Parses a tag-aliases registry from a string into an `AliasMap`.
- * Aliases are lowercased on insertion so callers can look up case-insensitively.
- * Throws on any structural defect — non-object top level, missing `aliases` key, non-string entries, self-aliases,
- * or cross-canonical collisions — with `contextLabel` prefixed onto every message.
+ * Aliases are lowercased on insertion so that callers can look up case-insensitively.
+ * Throws on malformed YAML and on any structural defect, with `contextLabel` prefixed onto every message.
  */
 export declare function parseAliases(text: string, contextLabel?: string): AliasMap;

package/dist/esm/taxonomy/domain-paths.d.ts

@@ -1,13 +1,13 @@
 /**
- * Derives every domain a note set implies: the domain each note sits in, plus each of that domain's ancestors, sorted.
- * A grouping domain that holds only subfolders is included, because the rules treat it as in use and would otherwise
- * report a back-filled taxonomy's own entries as unused.
+ * Derives every domain implied by a note set: each note's domain, plus each of that domain's ancestors, sorted.
+ * A grouping domain that contains only subfolders is included, because the rules treat it as in use and would
+ * otherwise report a back-filled taxonomy's own entries as unused.
  */
 export declare function deriveDomains(relativePaths: Iterable<string>): string[];
 /**
- * Derives the domain a note sits in, or `undefined` when the note is not an assertion or sits at the assertions root.
- * Scoping to the assertions root is what keeps event records from registering as domains.
+ * Derives a note's domain, or `undefined` when the note is not an assertion or is at the assertions root.
+ * Scoping to the assertions root keeps event records from registering as domains.
  */
 export declare function resolveDomain(relativePath: string): string | undefined;
-/** Derives a slash-path's parent, or `undefined` when it has no separator and so sits at the top level. */
+/** Derives a slash-path's parent, or `undefined` when it has no separator and so is at the top level. */
 export declare function resolveParent(path: string): string | undefined;

package/dist/esm/taxonomy/load-taxonomy.d.ts

@@ -3,10 +3,10 @@ import { type Taxonomy } from './taxonomy-schema.js';
 /**
  * Loads `.kb/taxonomy.yaml` into a single keyed map, returning an empty taxonomy when the file is absent or declares
  * nothing. The two on-disk blocks are a file-format concern: a consumer looks a domain up once and reads `provisional`
- * off the entry it finds.
+ * off the entry that it finds.
  *
- * Mirrors {@link loadKbConfig}: structural defects (malformed YAML, a wrong type, a malformed key, a path declared in
- * both blocks) throw a {@link KbLoaderError} naming the file. I/O errors other than a missing file propagate.
+ * Structural defects (malformed YAML, a wrong type, a malformed key, a path declared in both blocks) throw a
+ * {@link KbLoaderError} naming the file. I/O errors other than a missing file propagate.
  */
 export declare function loadTaxonomy(input: {
     kbRoot: KbRoot;

package/dist/esm/taxonomy/load-taxonomy.js

@@ -53,8 +53,8 @@ function collectBlock(input) {
 function describeIssueLocation(error) {
     const issue = error.issues[0];
     if (issue === undefined) {
-        return ' — unknown error';
+        return ': unknown error';
     }
     const location = issue.path.length > 0 ? ` at ${issue.path.join('.')}` : '';
-    return `${location} — ${issue.message}`;
+    return `${location}: ${issue.message}`;
 }

package/dist/esm/taxonomy/taxonomy-schema.d.ts

@@ -2,12 +2,11 @@ import { z } from 'zod';
 /**
  * Describes why a domain key cannot be used, or returns `undefined` when the key is well-formed. Keys are relative to
  * the assertions root, so a restated `content/assertions/` prefix would declare the domain a level deeper than the
- * author meant; `kb-add` refuses the same mistake on the note-write path.
+ * author meant.
  */
 export declare function describeKeyDefect(key: string): string | undefined;
 /** A knowledge base's declared assertion structure, keyed by assertions-root-relative slash-path. */
 export type Taxonomy = ReadonlyMap<string, TaxonomyEntry>;
-/** A single declared domain. */
 export interface TaxonomyEntry {
     /** The domain's one-line description; empty when it was declared without one. */
     description: string;
@@ -18,11 +17,11 @@ export interface TaxonomyEntry {
  * The on-disk `.kb/taxonomy.yaml` shape.
  *
  * Both blocks are optional and nullable, so a file may declare only one, and a block header left with nothing under it
- * loads as declaring nothing rather than failing. YAML reads such a header as null, and it is the state promoting the
- * last entry out of a block leaves behind.
+ * loads as declaring nothing rather than failing. YAML reads such a header as null, and it is the state left behind by
+ * promoting the last entry out of a block.
  *
- * A description may likewise be null, so a key written bare (`engineering/tooling:`) loads: that is what a hand editor
- * types and what a domain declared without a description round-trips to.
+ * Because a description may likewise be null, a key written bare (`engineering/tooling:`) loads: That is what a hand
+ * editor types and what a domain declared without a description round-trips to.
  */
 export declare const taxonomyFileShape: z.ZodObject<{
     domains: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodString>>>>;

package/dist/esm/taxonomy/write-taxonomy.d.ts

@@ -1,9 +1,8 @@
 import type { KbRoot } from '../types.js';
-/** A domain to declare. */
 export interface TaxonomyDeclaration {
     /** The domain's assertions-root-relative slash-path. */
     path: string;
-    /** The one-line description; absent or empty writes the key bare, with no description. */
+    /** The one-line description; when absent or empty, `writeTaxonomy` writes the key bare, with no description. */
     description?: string;
     /** Whether to declare under `provisional:` rather than `domains:`. */
     provisional: boolean;
@@ -12,13 +11,13 @@ export interface TaxonomyDeclaration {
  * Declares domains in `.kb/taxonomy.yaml`, creating the file and either block as needed, and returns the paths added.
  *
  * Edits the parsed document rather than re-serializing a plain object, so existing comments, key order, and formatting
- * survive; a plain parse-and-stringify round trip would discard every comment in a hand-curated file. New keys append
- * to the end of their block in path order, and a block header left with nothing under it is filled in place rather
- * than moved.
+ * survive; a plain parse-and-stringify round trip would discard every comment in a hand-curated file. New keys
+ * are appended to the end of their block in path order, and a block header left with nothing under it is filled in
+ * place rather than moved.
  *
- * A path either block already declares is skipped rather than overwritten, so a repeat call adds nothing; when nothing
- * is left to add, the file is not opened for writing at all. The write goes through the shared `writeAtomic` helper,
- * so an interrupted call cannot truncate the taxonomy.
+ * A path already declared by either block is skipped rather than overwritten. A repeat call adds nothing, and when
+ * nothing is left to add, the file is not opened for writing at all. The write goes through the shared `writeAtomic`
+ * helper, so an interrupted call cannot truncate the taxonomy.
  *
  * Throws a {@link KbLoaderError} on a malformed key, or on an existing file that cannot be safely appended to: one
  * that fails to parse, one whose top level is not a mapping, and one whose `domains` or `provisional` block holds

package/dist/esm/type-guards.d.ts

@@ -4,7 +4,7 @@
  */
 export declare function isEnoent(error: unknown): boolean;
 /**
- * Returns true when `error` carries the given Node `code` string (e.g. `'ENOENT'`, `'EACCES'`).
+ * Returns true when `error` has the given Node `code` string (e.g. `'ENOENT'`, `'EACCES'`).
  * @internal
  */
 export declare function isErrorCode(error: unknown, code: string): boolean;

package/dist/esm/types.d.ts

@@ -1,4 +1,4 @@
-/** A knowledge-base root: the directory holding a `.kb/`, and that `.kb/` itself. */
+/** A knowledge-base root: the directory containing a `.kb/`, and that `.kb/` itself. */
 export interface KbRoot {
     /** Absolute path to the directory containing the `.kb/` folder. */
     path: string;
@@ -7,13 +7,11 @@ export interface KbRoot {
 }
 /** A single knowledge base declared in a `kb.yaml` registry, normalized in memory. */
 export interface KbRegistryEntry {
-    /** The KB's name, lifted from the `kbs` map key. */
+    /** The KB's name, taken from the `kbs` map key. */
     name: string;
     /** Absolute path to the KB's root directory (tilde expanded, relative resolved). */
     path: string;
-    /** Optional human-readable description. */
     description?: string;
-    /** Whether the KB is read-only. */
     readonly?: boolean;
     /** Which registry the entry came from. */
     source: 'user' | 'project';
@@ -43,7 +41,7 @@ export interface Frontmatter {
     /** Optional and unknown fields, preserved through round-trip in insertion order. */
     extra: Record<string, unknown>;
 }
-/** The raw frontmatter slice plus parse diagnostics, kept so rules can report at source line numbers. */
+/** The raw frontmatter slice plus parse diagnostics, kept so that rules can report at source line numbers. */
 export interface FrontmatterRaw {
     /** The YAML text between the opening and closing `---` fences. */
     text: string;
@@ -56,7 +54,7 @@ export interface FrontmatterRaw {
 }
 /** A note parsed into frontmatter and body. */
 export interface ParsedNote {
-    /** Path or label the note was parsed from. */
+    /** Path or label from which the note was parsed. */
     path: string;
     /** The full original note content. */
     content: string;
@@ -69,11 +67,10 @@ export interface ParsedNote {
     /** 1-based line where the body begins. */
     bodyStartLine: number;
 }
-/** Severity of a validation finding. */
 export type FindingSeverity = 'error' | 'warning';
 /** A single validation finding produced by a rule. */
 export interface Finding {
-    /** Path or label the finding applies to: a note, or the store file that declares the rule's subject. */
+    /** Path or label to which the finding applies: a note, or the store file that declares the rule's subject. */
     path: string;
     /**
      * What the finding describes, defaulting to `note` when absent. A note-scoped finding is dropped when a run's
@@ -83,7 +80,7 @@ export interface Finding {
     scope?: 'note' | 'vault';
     /** 1-based source line number, when known. */
     line?: number;
-    /** Rule code, e.g. `frontmatter.required`. */
+    /** Rule code, e.g. `wikilinks.basename`. */
     rule: string;
     severity: FindingSeverity;
     message: string;

package/dist/esm/vault-integrity/build-vault-index.d.ts

@@ -1,13 +1,12 @@
 /**
  * A vault-wide lookup from a note basename (without the `.md` extension) to the set of note paths that share it. A
- * single-path entry resolves a wikilink unambiguously; a multi-path entry is a basename collision. Consumed by the
- * vault-integrity checks and by curate's wikilink rewriter.
+ * single-path entry resolves a wikilink unambiguously; a multi-path entry is a basename collision.
  */
 export type VaultIndex = ReadonlyMap<string, ReadonlySet<string>>;
 /**
  * Builds a basename → set-of-paths index from a set of notes, mapping each note's `.md` basename (sans extension) to
- * the note paths that share it. Reads only each note's `path`, so it is type-blind — it needs no frontmatter or record
- * projection. A note's `path` is used verbatim as the index value, so callers control whether entries are
+ * the note paths that share it. Reads only each note's `path`, so it is type-blind: It needs no frontmatter or record
+ * projection. Because a note's `path` is used verbatim as the index value, callers control whether entries are
  * vault-relative or absolute.
  */
 export declare function buildVaultIndex(notes: readonly {

package/dist/esm/vault-integrity/check-vault-integrity.d.ts

@@ -1,20 +1,54 @@
+import type { StoreVisibility } from '../config/config-schema.js';
 import type { Finding } from '../types.js';
-/** A note reduced to what vault integrity inspects: its path, its body, and the file line the body begins on. */
-export interface VaultIntegrityNote {
-    /** Path or label the note was read from; used as the index value and the finding path. */
-    path: string;
-    /** The note body (everything after the frontmatter block). */
-    body: string;
-    /** 1-based file line where the body begins, so link findings report file-absolute lines. */
-    bodyStartLine: number;
-}
+import { type VaultIndex } from './build-vault-index.js';
 /**
  * Checks whole-vault integrity over a type-blind note set: unresolved `[[link]]` targets and basename collisions.
- * Projects no records and reads no frontmatter — a note is just its path and body.
+ * Projects no records and reads no frontmatter: A note is just its path and body.
  *
  * A `[[Target]]` whose basename resolves to zero notes is an error (`wikilinks.unresolved`), reported at its
  * file-absolute line. A basename shared by two or more notes is a single vault-wide warning (`wikilinks.basename`),
  * reported once per basename independent of whether any link references it. An ambiguous link (a basename that several
- * notes share) is not flagged per-link — the vault-wide basename warning subsumes it.
+ * notes share) is not flagged per-link: The vault-wide basename warning subsumes it.
+ *
+ * A `[[store:Target]]` resolves against `options.foreignStores` instead, and is never added to this store's own
+ * basename index, so the basename warning stays store-scoped. Without `options`, a qualified target is treated as a
+ * bare one.
  */
-export declare function checkVaultIntegrity(notes: readonly VaultIntegrityNote[]): Finding[];
+export declare function checkVaultIntegrity(notes: readonly VaultIntegrityNote[], options?: VaultIntegrityOptions): Finding[];
+/** What a check run found when it looked up a store named by one of its links. */
+export type ForeignStore = 
+/** The name matches no entry in the merged registry. */
+{
+    status: 'unknown';
+}
+/** The store is registered but cannot be read on this machine, so its links are unverifiable rather than broken. */
+ | {
+    status: 'unavailable';
+    reason: string;
+}
+/** Because the store is less shareable than the source, a link into it would widen disclosure. */
+ | {
+    status: 'disallowed';
+    visibility: StoreVisibility;
+}
+/** The store was read; `index` contains its basenames. */
+ | {
+    status: 'resolved';
+    index: VaultIndex;
+};
+/** A note reduced to what vault integrity inspects. */
+export interface VaultIntegrityNote {
+    /** Path or label from which the note was read; used as the index value and the finding path. */
+    path: string;
+    /** The note body (everything after the frontmatter block). */
+    body: string;
+    /** 1-based file line where the body begins, so that link findings report file-absolute lines. */
+    bodyStartLine: number;
+}
+/** What a run needs to evaluate a store-qualified link. */
+export interface VaultIntegrityOptions {
+    /** What the run found for each store name that qualifies one of its links, keyed by that name. */
+    foreignStores: ReadonlyMap<string, ForeignStore>;
+    /** The visibility of the store being checked, which decides the direction that a qualified link may take. */
+    sourceVisibility: StoreVisibility;
+}

package/dist/esm/vault-integrity/check-vault-integrity.js

@@ -1,8 +1,8 @@
 import { buildVaultIndex } from "./build-vault-index.js";
-import { countNewlines, extractTarget, hasNonMarkdownExtension, lookupKey, maskFencedCode, maskInlineCode, WIKILINK, } from "./wikilink-parse.js";
-export function checkVaultIntegrity(notes) {
+import { countNewlines, lookupKey, scanWikilinks } from "./wikilink-parse.js";
+export function checkVaultIntegrity(notes, options) {
     const vaultIndex = buildVaultIndex(notes);
-    return [...unresolvedLinkFindings(notes, vaultIndex), ...basenameFindings(vaultIndex)];
+    return [...linkFindings(notes, vaultIndex, options), ...basenameFindings(vaultIndex)];
 }
 function basenameFindings(vaultIndex) {
     const findings = [];
@@ -20,28 +20,67 @@ function basenameFindings(vaultIndex) {
     }
     return findings;
 }
-function unresolvedLinkFindings(notes, vaultIndex) {
+function describeForeignDefect(store, target, options) {
+    const link = `[[${store}:${target}]]`;
+    const foreignStore = options.foreignStores.get(store);
+    if (foreignStore === undefined)
+        return undefined;
+    if (foreignStore.status === 'unknown') {
+        return {
+            rule: 'wikilinks.unknown-store',
+            severity: 'error',
+            message: `${link} names the store "${store}", which no kb.yaml registry entry declares`,
+        };
+    }
+    if (foreignStore.status === 'unavailable') {
+        return {
+            rule: 'wikilinks.store-unavailable',
+            severity: 'warning',
+            message: `${link} targets the store "${store}", which could not be read here: ${foreignStore.reason}`,
+        };
+    }
+    if (foreignStore.status === 'disallowed') {
+        return {
+            rule: 'wikilinks.disallowed-store',
+            severity: 'error',
+            message: `${link} targets "${store}", a ${foreignStore.visibility} store, which a ${options.sourceVisibility} store may not link into: The link discloses the target's title`,
+        };
+    }
+    const resolved = foreignStore.index.get(lookupKey(target));
+    if (resolved !== undefined && resolved.size > 0)
+        return undefined;
+    return {
+        rule: 'wikilinks.unresolved',
+        severity: 'error',
+        message: `${link} does not resolve to any note in the store "${store}"`,
+    };
+}
+function describeLocalDefect(target, vaultIndex) {
+    const resolved = vaultIndex.get(lookupKey(target));
+    if (resolved !== undefined && resolved.size > 0)
+        return undefined;
+    return {
+        rule: 'wikilinks.unresolved',
+        severity: 'error',
+        message: `[[${target}]] does not resolve to any vault note`,
+    };
+}
+function joinTarget(link) {
+    return link.store === undefined ? link.target : `${link.store}:${link.target}`;
+}
+function linkFindings(notes, vaultIndex, options) {
     const findings = [];
     for (const note of notes) {
-        const body = maskInlineCode(maskFencedCode(note.body));
-        for (const match of body.matchAll(WIKILINK)) {
-            const inner = match[1];
-            if (inner === undefined)
-                continue;
-            const target = extractTarget(inner);
-            if (target === null)
-                continue;
-            if (hasNonMarkdownExtension(target))
-                continue;
-            const resolved = vaultIndex.get(lookupKey(target));
-            if (resolved !== undefined && resolved.size > 0)
+        for (const link of scanWikilinks(note.body)) {
+            const defect = link.store === undefined || options === undefined
+                ? describeLocalDefect(joinTarget(link), vaultIndex)
+                : describeForeignDefect(link.store, link.target, options);
+            if (defect === undefined)
                 continue;
             findings.push({
                 path: note.path,
-                line: note.bodyStartLine + countNewlines(body, match.index),
-                rule: 'wikilinks.unresolved',
-                severity: 'error',
-                message: `[[${target}]] does not resolve to any vault note`,
+                line: note.bodyStartLine + countNewlines(note.body, link.offset),
+                ...defect,
             });
         }
     }

package/dist/esm/vault-integrity/index.d.ts

@@ -1,3 +1,3 @@
 export { buildVaultIndex, type VaultIndex } from './build-vault-index.js';
-export { checkVaultIntegrity, type VaultIntegrityNote } from './check-vault-integrity.js';
-export { countNewlines, extractTarget, hasNonMarkdownExtension, lookupKey, maskFencedCode, maskInlineCode, WIKILINK, } from './wikilink-parse.js';
+export { checkVaultIntegrity, type ForeignStore, type VaultIntegrityNote, type VaultIntegrityOptions, } from './check-vault-integrity.js';
+export { lookupKey, type ScannedWikilink, scanWikilinks } from './wikilink-parse.js';

package/dist/esm/vault-integrity/index.js

@@ -1,3 +1,3 @@
 export { buildVaultIndex } from "./build-vault-index.js";
-export { checkVaultIntegrity } from "./check-vault-integrity.js";
-export { countNewlines, extractTarget, hasNonMarkdownExtension, lookupKey, maskFencedCode, maskInlineCode, WIKILINK, } from "./wikilink-parse.js";
+export { checkVaultIntegrity, } from "./check-vault-integrity.js";
+export { lookupKey, scanWikilinks } from "./wikilink-parse.js";

package/dist/esm/vault-integrity/wikilink-parse.d.ts

@@ -1,29 +1,55 @@
-/**
- * Match `[[Target]]` and `![[Target]]` (embeds). A backslash-escaped `\[[…]]` is excluded. Scan the body so that
- * frontmatter wikilink-looking text (e.g. inside a description) is not flagged.
- */
-export declare const WIKILINK: RegExp;
-/** Counts the newlines in `text` before byte offset `upTo`, used to locate a match's source line. */
+/** Counts the newlines in `text` before string index `upTo`, used to locate a match's source line. */
 export declare function countNewlines(text: string, upTo: number): number;
 /**
  * Strips `|alias` and `#anchor` from a wikilink inner string and returns the target. Returns `null` for intra-doc
- * links like `[[#heading]]`, which carry no target.
+ * links like `[[#heading]]`, which have no target.
  */
 export declare function extractTarget(inner: string): string | null;
-/** Whether a target carries a known non-Markdown extension (an embed the vault index cannot resolve). */
-export declare function hasNonMarkdownExtension(target: string): boolean;
-/** Reduces a wikilink target to the basename key the vault index is keyed on (drops any directory prefix and `.md`). */
+/**
+ * Reduces a wikilink target to the basename key on which the vault index is keyed (drops any directory prefix and
+ * `.md`).
+ */
 export declare function lookupKey(target: string): string;
+/** A wikilink target separated into the store that it names, when it names one, and the target within that store. */
+export interface QualifiedTarget {
+    /** The store named by the link, or `undefined` when the target is store-local. */
+    store?: string;
+    /** The target with any store qualifier removed. */
+    target: string;
+}
+/**
+ * One wikilink accepted by a body scan, with its target already split into an optional store qualifier and a target.
+ */
+export interface ScannedWikilink {
+    /** The whole matched link, including any `!` embed prefix. */
+    match: string;
+    /** The text between the brackets, with alias and anchor intact. */
+    inner: string;
+    /** Offset of the match within the body. */
+    offset: number;
+    /** The store named by the link, or `undefined` when the target is store-local. */
+    store?: string;
+    /** The target within that store, with alias, anchor, and any store qualifier stripped. */
+    target: string;
+}
 /**
- * Replaces the content of fenced code blocks with spaces so wikilink-shaped text inside code (e.g., a bash
- * `[[ -n "$x" ]]` conditional) is not flagged. Offsets and line counts are preserved by substituting same-length
- * whitespace.
+ * Scans a note body and yields every wikilink that has a resolvable target: fenced and inline code are masked
+ * first, and backslash-escaped links, intra-doc anchors, and non-Markdown embeds are skipped. This is the single
+ * definition of what counts as a link and what its target is, so a consumer that detects links and one that rewrites
+ * them cannot drift apart on either question.
+ *
+ * `offset` indexes the body as passed in. Because masking substitutes same-length whitespace, which this function
+ * asserts, a consumer may slice the unmasked body at the offsets yielded here. It also leaves every newline where it
+ * was, which lets a consumer count lines in the unmasked body at those offsets. Nothing asserts that at runtime, so a
+ * masker that moved a newline while keeping the length would shift reported line numbers rather than fail.
  */
-export declare function maskFencedCode(body: string): string;
+export declare function scanWikilinks(body: string): Generator<ScannedWikilink>;
 /**
- * Replaces inline backtick spans (e.g., TOML `[[plugins]]` mentioned in prose) with same-length whitespace so
- * wikilink-shaped text inside inline code is not flagged. Matches single or multi-backtick runs whose content
- * contains no backticks or newlines — the common case; complex spans with embedded backticks fall through and are
- * still parsed for wikilinks.
+ * Separates a leading `store:` qualifier from a wikilink target: `fde:Note title` names the note `Note title` in the
+ * store `fde`. A qualifier is recognized only when the text before the first colon is non-empty and contains no
+ * whitespace and no `/`, and something follows the colon. Every other target stays store-local: A title such as
+ * `Release notes: v2` resolves within this store.
+ *
+ * Call it on the output of {@link extractTarget}, which has already stripped any alias and anchor.
  */
-export declare function maskInlineCode(body: string): string;
+export declare function splitStoreQualifier(target: string): QualifiedTarget;

package/dist/esm/vault-integrity/wikilink-parse.js

@@ -1,4 +1,4 @@
-export const WIKILINK = /(?<!\\)!?\[\[([^\]\n]+?)\]\]/g;
+const WIKILINK = /(?<!\\)!?\[\[([^\]\n]+?)\]\]/g;
 const NON_MD_EXTENSIONS = new Set([
     '.png',
     '.jpg',
@@ -26,7 +26,40 @@ export function extractTarget(inner) {
     const trimmed = beforeAnchor.trim();
     return trimmed === '' ? null : trimmed;
 }
-export function hasNonMarkdownExtension(target) {
+export function lookupKey(target) {
+    const withoutExtension = target.endsWith('.md') ? target.slice(0, -3) : target;
+    const segments = withoutExtension.split('/');
+    return segments.at(-1) ?? withoutExtension;
+}
+export function* scanWikilinks(body) {
+    const masked = maskInlineCode(maskFencedCode(body));
+    if (masked.length !== body.length) {
+        throw new Error('code masking changed body length; wikilink offsets would be invalid');
+    }
+    for (const match of masked.matchAll(WIKILINK)) {
+        const inner = match[1];
+        if (inner === undefined)
+            continue;
+        const extracted = extractTarget(inner);
+        if (extracted === null)
+            continue;
+        if (hasNonMarkdownExtension(extracted))
+            continue;
+        const { store, target } = splitStoreQualifier(extracted);
+        yield { match: match[0], inner, offset: match.index, ...(store !== undefined && { store }), target };
+    }
+}
+export function splitStoreQualifier(target) {
+    const colonIndex = target.indexOf(':');
+    if (colonIndex <= 0)
+        return { target };
+    const store = target.slice(0, colonIndex);
+    const remainder = target.slice(colonIndex + 1);
+    if (remainder === '' || /[\s/]/.test(store))
+        return { target };
+    return { store, target: remainder };
+}
+function hasNonMarkdownExtension(target) {
     const dotIndex = target.lastIndexOf('.');
     if (dotIndex === -1)
         return false;
@@ -35,12 +68,7 @@ export function hasNonMarkdownExtension(target) {
         return false;
     return NON_MD_EXTENSIONS.has(ext);
 }
-export function lookupKey(target) {
-    const withoutExtension = target.endsWith('.md') ? target.slice(0, -3) : target;
-    const segments = withoutExtension.split('/');
-    return segments.at(-1) ?? withoutExtension;
-}
-export function maskFencedCode(body) {
+function maskFencedCode(body) {
     const lines = body.split('\n');
     let inFence = false;
     let fenceChar = '';
@@ -69,7 +97,7 @@ export function maskFencedCode(body) {
     }
     return lines.join('\n');
 }
-export function maskInlineCode(body) {
+function maskInlineCode(body) {
     return body.replace(/`+[^`\n]+?`+/g, (match) => ' '.repeat(match.length));
 }
 const FENCE_LINE = /^\s{0,3}(`{3,}|~{3,})/;