@williamthorsen/kb 0.6.2 → 0.8.0

package/dist/esm/note-io/write-note.d.ts

@@ -1,2 +1,11 @@
+/**
+ * Renders a field map and body to note content: the opening fence, the frontmatter, the closing fence, one blank line,
+ * then the body. A single leading newline on the body is dropped so the blank line is not doubled, keeping the output
+ * stable across read/write cycles.
+ */
 export declare function renderNote(fields: Record<string, unknown>, body: string): string;
+/**
+ * Atomically writes a note to `path`, so a concurrent reader never sees a partial write. See {@link writeAtomic} for
+ * the guarantee and its failure behavior.
+ */
 export declare function writeNote(path: string, fields: Record<string, unknown>, body: string): Promise<void>;

package/dist/esm/note-io/yaml-fields.d.ts

@@ -1,5 +1,10 @@
+/**
+ * Parses frontmatter text (the YAML between the fences) into an insertion-ordered field map. A YAML parse error is
+ * returned rather than thrown; a block that is not a map yields an empty field map.
+ */
 export declare function parseFrontmatterFields(text: string): {
     fields: Record<string, unknown>;
     error?: string;
 };
+/** Renders a field map to frontmatter text (no fences), one `key: value` line per entry, in insertion order. */
 export declare function renderFrontmatterFields(fields: Record<string, unknown>): string;

package/dist/esm/records/assertion.d.ts

@@ -1,3 +1,4 @@
+/** A parsed `assertion` record: its typed fields, the body, and any other frontmatter preserved in `extra`. */
 export interface KbAssertion {
     recordType: 'assertion';
     title: string;
@@ -11,6 +12,7 @@ export interface KbAssertion {
     extra: Record<string, unknown>;
     body: string;
 }
+/** The outcome of parsing frontmatter as an assertion: the typed record, or the validation errors that blocked it. */
 export type ParseAssertionResult = {
     ok: true;
     record: KbAssertion;
@@ -18,7 +20,9 @@ export type ParseAssertionResult = {
     ok: false;
     errors: string[];
 };
+/** Validates a frontmatter field map as an assertion and projects it onto a {@link KbAssertion}, accumulating every error. */
 export declare function parseAssertion(fields: Record<string, unknown>, body: string): ParseAssertionResult;
+/** Projects an assertion back to a frontmatter field map (typed fields first, then preserved `extra`) plus its body. */
 export declare function renderAssertion(record: KbAssertion): {
     fields: Record<string, unknown>;
     body: string;

package/dist/esm/records/event.d.ts

@@ -1,10 +1,15 @@
+/** The impact levels an event may carry, ordered lowest to highest. */
 export declare const EVENT_IMPACT_LEVELS: readonly ["low", "medium", "high", "critical"];
+/** An event's impact: the author's subjective, revisable rating of how much addressing the event matters. */
 export type EventImpact = (typeof EVENT_IMPACT_LEVELS)[number];
+/** Reports whether a value is one of the declared {@link EVENT_IMPACT_LEVELS}. */
 export declare function isEventImpact(value: unknown): value is EventImpact;
+/** A parsed `event` record: its declared fields, the body, and any other frontmatter preserved in `extra`. */
 export interface KbEvent {
     recordType: 'event';
     id: string;
     capturedAt: string;
+    /** Harness-dependent provenance: absent when the harness that captured the event exposes no session id. */
     session?: string;
     cwd: string;
     summary: string;
@@ -14,6 +19,7 @@ export interface KbEvent {
     extra: Record<string, unknown>;
     body: string;
 }
+/** The outcome of parsing frontmatter as an event: the typed record, or the validation errors that blocked it. */
 export type ParseEventResult = {
     ok: true;
     record: KbEvent;
@@ -21,7 +27,13 @@ export type ParseEventResult = {
     ok: false;
     errors: string[];
 };
+/** Validates a frontmatter field map as an event and projects it onto a {@link KbEvent}, accumulating every error. */
 export declare function parseEvent(fields: Record<string, unknown>, body: string): ParseEventResult;
+/**
+ * Projects an event back to a frontmatter field map (declared fields first, then preserved `extra`) plus its body. An
+ * empty `session` is omitted like an absent one, mirroring {@link parseEvent}: the two spellings of "no session" have a
+ * single representation on both edges of the module, so no record can reacquire the empty field on a write.
+ */
 export declare function renderEvent(record: KbEvent): {
     fields: Record<string, unknown>;
     body: string;

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

@@ -0,0 +1,2 @@
+export { renderAliasesSeed, renderConfigSeed } from './render-seeds.js';
+export { scaffold, type ScaffoldAction, type ScaffoldEntry } from './scaffold.js';

package/dist/esm/scaffold/index.js

@@ -0,0 +1,2 @@
+export { renderAliasesSeed, renderConfigSeed } from "./render-seeds.js";
+export { scaffold } from "./scaffold.js";

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

@@ -0,0 +1,16 @@
+/**
+ * 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
+ * {@link renderPrettierSeed}'s header for what it prevents.
+ */
+export declare const canonicalPrettierConfig: {
+    embeddedLanguageFormatting: string;
+};
+/** Renders `.kb/tag-aliases.yaml`: an empty `aliases: {}` map under an explanatory header. */
+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. */
+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

@@ -0,0 +1,65 @@
+import { stringify } from 'yaml';
+import { defaultKbConfig } from "../config/config-schema.js";
+const ALIASES_HEADER = `# Tag aliases for this knowledge store.
+#
+# Map each canonical tag to the aliases that should resolve to it, for example:
+#   aliases:
+#     typescript: [ts, type-script]
+# The \`aliases:\` key is required even when empty.
+`;
+const CONFIG_HEADER = `# Check configuration for this knowledge store.
+#
+# 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. \`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
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 2
+indent_style = space
+insert_final_newline = true
+max_line_length = 120
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+`;
+const PRETTIER_HEADER = `# Formatting configuration for this knowledge store.
+#
+# The single option here is not stylistic. It prevents a specific failure, so read this before removing it.
+#
+# \`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.
+#
+# Width, indentation, and line endings are set in \`.editorconfig\`, which Prettier reads and every editor reads too.
+#
+`;
+export const canonicalPrettierConfig = {
+    embeddedLanguageFormatting: 'off',
+};
+export function renderAliasesSeed() {
+    return `${ALIASES_HEADER}aliases: {}\n`;
+}
+export function renderConfigSeed() {
+    return `${CONFIG_HEADER}${commentBlock(stringify(defaultKbConfig))}\n`;
+}
+export function renderEditorconfigSeed() {
+    return EDITORCONFIG_SEED;
+}
+export function renderPrettierSeed() {
+    return `${PRETTIER_HEADER}${stringify(canonicalPrettierConfig)}`;
+}
+function commentBlock(text) {
+    return text
+        .trimEnd()
+        .split('\n')
+        .map((line) => (line === '' ? '#' : `# ${line}`))
+        .join('\n');
+}

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

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ */
+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. */
+    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.
+ *
+ * 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.
+ */
+export declare function scaffold(input: {
+    storePath: string;
+    force?: boolean;
+}): Promise<readonly ScaffoldEntry[]>;

package/dist/esm/scaffold/scaffold.js

@@ -0,0 +1,35 @@
+import { mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { pathExists } from "../filesystem/exists.js";
+import { writeAtomic } from "../filesystem/write-atomic.js";
+import { ALIASES_FILE, CONFIG_FILE, CONTENT_DIR, EDITORCONFIG_FILE, EVENTS_DIR, PRETTIER_CONFIG_FILE, } from "../layout/index.js";
+import { renderAliasesSeed, renderConfigSeed, renderEditorconfigSeed, renderPrettierSeed } from "./render-seeds.js";
+export async function scaffold(input) {
+    const { storePath, force = false } = input;
+    const entries = [];
+    for (const file of CANONICAL_FILES) {
+        const absolutePath = join(storePath, file.path);
+        const exists = await pathExists(absolutePath);
+        if (exists && !force) {
+            entries.push({ path: file.path, action: 'present' });
+            continue;
+        }
+        await mkdir(dirname(absolutePath), { recursive: true });
+        await writeAtomic(absolutePath, file.render());
+        entries.push({ path: file.path, action: exists ? 'replaced' : 'created' });
+    }
+    for (const directory of CANONICAL_DIRECTORIES) {
+        const absolutePath = join(storePath, directory);
+        const exists = await pathExists(absolutePath);
+        await mkdir(absolutePath, { recursive: true });
+        entries.push({ path: `${directory}/`, action: exists ? 'present' : 'created' });
+    }
+    return entries;
+}
+const CANONICAL_DIRECTORIES = [CONTENT_DIR, EVENTS_DIR];
+const CANONICAL_FILES = [
+    { path: EDITORCONFIG_FILE, render: renderEditorconfigSeed },
+    { path: CONFIG_FILE, render: renderConfigSeed },
+    { path: ALIASES_FILE, render: renderAliasesSeed },
+    { path: PRETTIER_CONFIG_FILE, render: renderPrettierSeed },
+];

package/dist/esm/tags/canonicalize.d.ts

@@ -1,3 +1,11 @@
 import type { AliasMap } from '../types.js';
+/**
+ * Returns the canonical form of a tag. Lookups are case-insensitive.
+ * Unknown tags and tags that are already canonical pass through unchanged.
+ */
 export declare function canonicalize(tag: string, aliases: AliasMap): string;
+/**
+ * Returns the canonical form of a tag only when the input is a known alias; otherwise `null`.
+ * Distinguishes drift (an alias is present) from canonical or new-vocabulary tags.
+ */
 export declare function findAliasFor(tag: string, aliases: AliasMap): string | null;

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

@@ -1,5 +1,15 @@
 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.
+ */
 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.
+ */
 export declare function parseAliases(text: string, contextLabel?: string): AliasMap;

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

@@ -1,3 +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.
+ */
 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.
+ */
 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. */
 export declare function resolveParent(path: string): string | undefined;

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

@@ -1,5 +1,13 @@
 import type { KbRoot } from '../types.js';
 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.
+ *
+ * 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.
+ */
 export declare function loadTaxonomy(input: {
     kbRoot: KbRoot;
 }): Promise<Taxonomy>;

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

@@ -1,10 +1,29 @@
 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.
+ */
 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;
+    /** Whether the domain was declared under `provisional:` rather than `domains:`. */
     provisional: boolean;
 }
+/**
+ * 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.
+ *
+ * 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.
+ */
 export declare const taxonomyFileShape: z.ZodObject<{
     domains: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodString>>>>;
     provisional: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodString>>>>;

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

@@ -1,9 +1,29 @@
 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. */
     description?: string;
+    /** Whether to declare under `provisional:` rather than `domains:`. */
     provisional: boolean;
 }
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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
+ * something other than a mapping. Other I/O errors propagate.
+ */
 export declare function writeTaxonomy(input: {
     kbRoot: KbRoot;
     declarations: readonly TaxonomyDeclaration[];

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

@@ -1,3 +1,16 @@
+/**
+ * Checks whether an error is an ENOENT (no such file or directory) filesystem error.
+ * @internal
+ */
 export declare function isEnoent(error: unknown): boolean;
+/**
+ * Returns true when `error` carries the given Node `code` string (e.g. `'ENOENT'`, `'EACCES'`).
+ * @internal
+ */
 export declare function isErrorCode(error: unknown, code: string): boolean;
+/**
+ * Type guard for a non-null, non-array object.
+ *
+ * @internal
+ */
 export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/esm/types.d.ts

@@ -1,51 +1,92 @@
+/** A knowledge-base root: the directory holding a `.kb/`, and that `.kb/` itself. */
 export interface KbRoot {
+    /** Absolute path to the directory containing the `.kb/` folder. */
     path: string;
+    /** Absolute path to the `.kb/` directory itself. */
     kbDir: string;
 }
+/** 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. */
     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';
 }
+/** The merged, normalized KB registry. */
 export interface KbRegistry {
+    /** All KB entries, user entries merged with project overrides. */
     entries: KbRegistryEntry[];
+    /** The entry named by `default_kb`, resolved against `entries`; absent when `default_kb` is unset. */
     defaultKb?: KbRegistryEntry;
+    /** Absolute paths of the registry files that contributed entries. */
     sources: {
         user?: string;
         project?: string;
     };
 }
+/** Strongly-typed frontmatter for a note. */
 export interface Frontmatter {
     title: string;
+    /** The stored record-type discriminant (e.g. `assertion`, `event`). */
     recordType: string;
+    /** Second-precision UTC timestamp (`YYYY-MM-DDTHH:MM:SSZ`); bare legacy `YYYY-MM-DD` dates remain valid. */
     created: string;
+    /** Second-precision UTC timestamp (`YYYY-MM-DDTHH:MM:SSZ`); bare legacy `YYYY-MM-DD` dates remain valid. */
     updated: string;
     tags: string[];
+    /** 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. */
 export interface FrontmatterRaw {
+    /** The YAML text between the opening and closing `---` fences. */
     text: string;
+    /** 1-based line of the opening `---` fence. */
     startLine: number;
+    /** 1-based line of the closing `---` fence. */
     endLine: number;
+    /** YAML parse error message, if the block could not be parsed. */
     parseError?: string;
 }
+/** A note parsed into frontmatter and body. */
 export interface ParsedNote {
+    /** Path or label the note was parsed from. */
     path: string;
+    /** The full original note content. */
     content: string;
+    /** Typed frontmatter, or `null` when no frontmatter block is present or it failed to parse. */
     frontmatter: Frontmatter | null;
+    /** Raw frontmatter slice and diagnostics, or `null` when no `---` block is present. */
     frontmatterRaw: FrontmatterRaw | null;
+    /** The note body (everything after the closing `---`). */
     body: string;
+    /** 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: string;
+    /**
+     * What the finding describes, defaulting to `note` when absent. A note-scoped finding is dropped when a run's
+     * selection excludes its note; a vault-scoped one describes the store itself, so it survives every selection,
+     * including one matching no notes at all.
+     */
     scope?: 'note' | 'vault';
+    /** 1-based source line number, when known. */
     line?: number;
+    /** Rule code, e.g. `frontmatter.required`. */
     rule: string;
     severity: FindingSeverity;
     message: string;
 }
+/** A lowercase-keyed map from tag alias to its canonical form. */
 export type AliasMap = ReadonlyMap<string, string>;

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

@@ -1,4 +1,15 @@
+/**
+ * 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.
+ */
 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
+ * vault-relative or absolute.
+ */
 export declare function buildVaultIndex(notes: readonly {
     path: string;
 }[]): VaultIndex;

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

@@ -1,7 +1,54 @@
+import type { StoreVisibility } from '../config/config-schema.js';
 import type { Finding } from '../types.js';
+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.
+ *
+ * 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.
+ *
+ * A `[[store:Target]]` resolves against `options.foreignStores` instead, and never joins this store's own basename
+ * index, so the basename warning stays store-scoped. Without `options`, a qualified target is treated as a bare one,
+ * which is the behavior every caller had before cross-store resolution existed.
+ */
+export declare function checkVaultIntegrity(notes: readonly VaultIntegrityNote[], options?: VaultIntegrityOptions): Finding[];
+/** What a check run found when it looked up a store one of its links names. */
+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;
+}
+/** The store is less shareable than the source, so a link into it would widen disclosure. */
+ | {
+    status: 'disallowed';
+    visibility: StoreVisibility;
+}
+/** The store was read; `index` holds its basenames. */
+ | {
+    status: 'resolved';
+    index: VaultIndex;
+};
+/** 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;
 }
-export declare function checkVaultIntegrity(notes: readonly VaultIntegrityNote[]): Finding[];
+/** What a run needs to evaluate a store-qualified link. */
+export interface VaultIntegrityOptions {
+    /** What the run found for each store name its links qualify, keyed by that name. */
+    foreignStores: ReadonlyMap<string, ForeignStore>;
+    /** The visibility of the store being checked, which decides the direction 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';