@williamthorsen/kb 0.8.0 → 0.8.1

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

@@ -3,19 +3,19 @@ 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.
+ * 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 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.
+ * 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[], options?: VaultIntegrityOptions): Finding[];
-/** What a check run found when it looked up a store one of its links names. */
+/** 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. */
 {
@@ -26,29 +26,29 @@ export type ForeignStore =
     status: 'unavailable';
     reason: string;
 }
-/** The store is less shareable than the source, so a link into it would widen disclosure. */
+/** 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` holds its basenames. */
+/** The store was read; `index` contains 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. */
+/** A note reduced to what vault integrity inspects. */
 export interface VaultIntegrityNote {
-    /** Path or label the note was read from; used as the index value and the finding path. */
+    /** 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 link findings report file-absolute lines. */
+    /** 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 its links qualify, keyed by that name. */
+    /** 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 a qualified link may take. */
+    /** 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

@@ -43,7 +43,7 @@ function describeForeignDefect(store, target, options) {
         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`,
+            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));

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

@@ -1,20 +1,25 @@
-/** 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;
-/** 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 it names, where it names one, and the target within that store. */
+/** 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 the link names, or `undefined` when the target is store-local. */
+    /** 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 a body scan accepted, with its target already split into an optional store qualifier and a target. */
+/**
+ * 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;
@@ -22,28 +27,28 @@ export interface ScannedWikilink {
     inner: string;
     /** Offset of the match within the body. */
     offset: number;
-    /** The store the link names, or `undefined` when the target is store-local. */
+    /** 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;
 }
 /**
- * Walks a note body and yields every wikilink that carries a resolvable target: fenced and inline code are masked
+ * 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. Masking substitutes same-length whitespace, which this function asserts, so
- * a consumer may slice the unmasked body at the offsets yielded here. It also leaves every newline where it was, so a
- * consumer may 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.
+ * `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 scanWikilinks(body: string): Generator<ScannedWikilink>;
 /**
- * Separates a leading `store:` qualifier from a wikilink target, so `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 carries no
- * whitespace and no `/`, and something follows the colon; every other target passes through store-local, which leaves
- * a title that happens to contain a colon resolving as it always has.
+ * 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.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/kb",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Knowledge-base foundation: discovery, config, frontmatter parsing, records, tags, and vault-integrity checks",
   "keywords": [
     "frontmatter",
@@ -102,13 +102,13 @@
     "dist"
   ],
   "dependencies": {
-    "@williamthorsen/toolbelt.errors": "0.7.0",
+    "@williamthorsen/toolbelt.errors": "0.8.1",
     "picomatch": "4.0.7",
-    "yaml": "2.9.0",
-    "zod": "4.5.4"
+    "yaml": "2.9.1",
+    "zod": "4.6.5"
   },
   "devDependencies": {
-    "@types/node": "24.13.3",
+    "@types/node": "24.13.4",
     "@types/picomatch": "4.0.3",
     "eslint": "10.10.0",
     "prettier": "3.9.6",