@williamthorsen/kb 0.6.2 → 0.7.0

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,20 @@
 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;
 }
+/**
+ * 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.
+ */
 export declare function checkVaultIntegrity(notes: readonly VaultIntegrityNote[]): Finding[];

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

@@ -1,7 +1,29 @@
+/**
+ * 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. */
 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.
+ */
 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`). */
 export declare function lookupKey(target: string): 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.
+ */
 export declare function maskFencedCode(body: string): string;
+/**
+ * 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.
+ */
 export declare function maskInlineCode(body: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/kb",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Knowledge-base foundation: discovery, config, frontmatter parsing, records, tags, and vault-integrity checks",
   "keywords": [
     "frontmatter",
@@ -72,6 +72,11 @@
       "types": "./dist/esm/records/index.d.ts",
       "import": "./dist/esm/records/index.js"
     },
+    "./scaffold": {
+      "source": "./src/scaffold/index.ts",
+      "types": "./dist/esm/scaffold/index.d.ts",
+      "import": "./dist/esm/scaffold/index.js"
+    },
     "./tags": {
       "source": "./src/tags/index.ts",
       "types": "./dist/esm/tags/index.d.ts",
@@ -97,15 +102,16 @@
     "dist"
   ],
   "dependencies": {
-    "@williamthorsen/toolbelt.errors": "0.6.3",
+    "@williamthorsen/toolbelt.errors": "0.7.0",
     "picomatch": "4.0.7",
     "yaml": "2.9.0",
-    "zod": "4.4.3"
+    "zod": "4.5.4"
   },
   "devDependencies": {
     "@types/node": "24.13.3",
     "@types/picomatch": "4.0.3",
     "eslint": "10.9.1",
+    "prettier": "3.9.6",
     "vitest": "4.1.11"
   },
   "engines": {

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

@@ -1,2 +0,0 @@
-export declare function renderAliasesSeed(): string;
-export declare function renderConfigSeed(): string;

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

@@ -1,29 +0,0 @@
-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.
-#
-# Both keys are optional and fall back to the defaults 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.
-#
-`;
-export function renderAliasesSeed() {
-    return `${ALIASES_HEADER}aliases: {}\n`;
-}
-export function renderConfigSeed() {
-    return `${CONFIG_HEADER}${commentBlock(stringify(defaultKbConfig))}\n`;
-}
-function commentBlock(text) {
-    return text
-        .trimEnd()
-        .split('\n')
-        .map((line) => (line === '' ? '#' : `# ${line}`))
-        .join('\n');
-}