@williamthorsen/kb 0.3.1 → 0.5.0

package/dist/esm/cli/resolve-store.d.ts

@@ -0,0 +1,14 @@
+import type { StoreRef } from './format.js';
+export type ResolveStoreOutcome = {
+    ok: true;
+    store: StoreRef;
+    readonly: boolean;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function resolveStore(input: {
+    explicitKb: string | null;
+    cwd: string;
+    home?: string;
+}): Promise<ResolveStoreOutcome>;

package/dist/esm/cli/resolve-store.js

@@ -0,0 +1,25 @@
+import { findKbRoot } from "../discovery/find-kb-root.js";
+import { tryLoadKbRegistry } from "../discovery/load-registry.js";
+export async function resolveStore(input) {
+    const { config } = await tryLoadKbRegistry({
+        projectDir: input.cwd,
+        ...(input.home !== undefined && { home: input.home }),
+    });
+    if (input.explicitKb !== null) {
+        const match = config.entries.find((entry) => entry.name === input.explicitKb);
+        if (match === undefined) {
+            return { ok: false, message: `--kb "${input.explicitKb}" does not match any registered knowledge base` };
+        }
+        return { ok: true, store: { name: match.name, path: match.path }, readonly: match.readonly ?? false };
+    }
+    const discovered = await findKbRoot({ startDir: input.cwd });
+    if (discovered === null) {
+        return { ok: false, message: 'no .kb/ directory found in the current directory or any ancestor' };
+    }
+    const registered = config.entries.find((entry) => entry.path === discovered.path);
+    return {
+        ok: true,
+        store: { name: registered?.name ?? null, path: discovered.path },
+        readonly: registered?.readonly ?? false,
+    };
+}

package/dist/esm/cli/run.d.ts

@@ -1,6 +1,6 @@
 import { type CommandOutput } from './commands/check.js';
 import type { SelectKbPrompt } from './select-kb-prompt.js';
-export declare const HELP = "Usage: kb <command> [options]\n\nCommands:\n  check        Validate a knowledge base, optionally scoped to selected notes.\n  create       Scaffold a new knowledge base and register it in the kb.yaml registry.\n  set-default  Set, clear, or choose the default knowledge base.\n\nRun \"kb <command> --help\" for command options.\n";
+export declare const HELP = "Usage: kb <command> [options]\n\nCommands:\n  check        Validate a knowledge base, optionally scoped to selected notes.\n  create       Scaffold a new knowledge base and register it in the kb.yaml registry.\n  set-default  Set, clear, or choose the default knowledge base.\n  taxonomy     Derive a knowledge base's taxonomy from the notes it already holds.\n\nRun \"kb <command> --help\" for command options.\n";
 export declare function run(input: {
     argv: readonly string[];
     cwd: string;

package/dist/esm/cli/run.js

@@ -1,12 +1,14 @@
 import { runCheck } from "./commands/check.js";
 import { runCreate } from "./commands/create.js";
 import { runSetDefault } from "./commands/set-default.js";
+import { runTaxonomy } from "./commands/taxonomy.js";
 export const HELP = `Usage: kb <command> [options]
 
 Commands:
   check        Validate a knowledge base, optionally scoped to selected notes.
   create       Scaffold a new knowledge base and register it in the kb.yaml registry.
   set-default  Set, clear, or choose the default knowledge base.
+  taxonomy     Derive a knowledge base's taxonomy from the notes it already holds.
 
 Run "kb <command> --help" for command options.
 `;
@@ -26,6 +28,9 @@ export async function run(input) {
             ...(input.selectKb !== undefined && { selectKb: input.selectKb }),
         });
     }
+    if (command === 'taxonomy') {
+        return runTaxonomy({ argv: rest, cwd: input.cwd, ...(input.home !== undefined && { home: input.home }) });
+    }
     if (command === 'set-default') {
         return runSetDefault({
             argv: rest,

package/dist/esm/create/create.d.ts

@@ -2,6 +2,7 @@ export type DefaultKbOutcome = 'set' | 'unchanged' | 'needs-selection';
 export interface CreatedStore {
     name: string;
     storePath: string;
+    description?: string;
     registered: boolean;
     created: readonly string[];
     defaultKb?: DefaultKbOutcome;
@@ -14,6 +15,7 @@ export type CreateInput = {
 } | {
     register: true;
     registryPath: string;
+    description?: string;
 });
 export type CreateOutcome = {
     ok: true;

package/dist/esm/create/create.js

@@ -22,12 +22,13 @@ export async function create(input) {
         return { ok: false, reason: 'name-registered', message: nameRegisteredMessage(name, registryPath) };
     }
     const created = await scaffold(storePath);
-    const result = await registerStore({ registryPath, name, storePath });
+    const described = input.description !== undefined && { description: input.description };
+    const result = await registerStore({ registryPath, name, storePath, ...described });
     if (result.status === 'already-present') {
         return { ok: false, reason: 'name-registered', message: nameRegisteredMessage(name, registryPath) };
     }
     const defaultKb = await ensureDefaultKb({ registryPath, name, before });
-    return { ok: true, created: { name, storePath, registered: true, created, defaultKb } };
+    return { ok: true, created: { name, storePath, ...described, registered: true, created, defaultKb } };
 }
 async function ensureDefaultKb(input) {
     if (input.before.defaultKb !== undefined) {

package/dist/esm/discovery/register-store.js

@@ -1,5 +1,6 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
+import { isMap, isScalar } from 'yaml';
 import { kbRegistryFileSchema } from "./kb-registry-schema.js";
 import { loadRegistryDocument } from "./registry-document.js";
 export async function registerStore(input) {
@@ -11,11 +12,12 @@ export async function registerStore(input) {
     if (doc.hasIn(['kbs', input.name])) {
         return { status: 'already-present' };
     }
-    const entry = { path: input.storePath };
-    if (input.description !== undefined) {
-        entry.description = input.description;
-    }
+    const entry = {
+        ...(input.description !== undefined && { description: input.description }),
+        path: input.storePath,
+    };
     doc.setIn(['kbs', input.name], entry);
+    sortRegistryEntries(doc);
     const result = kbRegistryFileSchema.safeParse(doc.toJS());
     if (!result.success) {
         throw new Error(`${input.registryPath}: cannot register "${input.name}" — ${result.error.issues[0]?.message ?? 'invalid entry'}`);
@@ -24,3 +26,20 @@ export async function registerStore(input) {
     await writeFile(input.registryPath, doc.toString(), 'utf8');
     return { status: 'added' };
 }
+function compareRegistryNames(left, right) {
+    const caseInsensitive = left.localeCompare(right, 'en', { sensitivity: 'base' });
+    return caseInsensitive === 0 ? left.localeCompare(right) : caseInsensitive;
+}
+function sortRegistryEntries(doc) {
+    const kbs = doc.getIn(['kbs'], true);
+    if (!isMap(kbs)) {
+        return;
+    }
+    kbs.items.sort((left, right) => compareRegistryNames(readName(left.key), readName(right.key)));
+}
+function readName(key) {
+    if (isScalar(key)) {
+        return String(key.value);
+    }
+    return typeof key === 'string' ? key : '';
+}

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

@@ -1 +1 @@
-export { ALIASES_FILE, ASSERTIONS_DIR, ASSERTIONS_SEGMENT, buildEventPath, CONFIG_FILE, CONTENT_DIR, EVENTS_DIR, KB_DIR, resolveAssertionsDir, resolveEventPath, resolveEventsDir, resolveKbDir, } from './store-layout.js';
+export { ALIASES_FILE, ASSERTIONS_DIR, ASSERTIONS_SEGMENT, buildEventPath, CONFIG_FILE, CONTENT_DIR, EVENTS_DIR, KB_DIR, resolveAssertionsDir, resolveEventPath, resolveEventsDir, resolveKbDir, TAXONOMY_FILE, } from './store-layout.js';

package/dist/esm/layout/index.js

@@ -1 +1 @@
-export { ALIASES_FILE, ASSERTIONS_DIR, ASSERTIONS_SEGMENT, buildEventPath, CONFIG_FILE, CONTENT_DIR, EVENTS_DIR, KB_DIR, resolveAssertionsDir, resolveEventPath, resolveEventsDir, resolveKbDir, } from "./store-layout.js";
+export { ALIASES_FILE, ASSERTIONS_DIR, ASSERTIONS_SEGMENT, buildEventPath, CONFIG_FILE, CONTENT_DIR, EVENTS_DIR, KB_DIR, resolveAssertionsDir, resolveEventPath, resolveEventsDir, resolveKbDir, TAXONOMY_FILE, } from "./store-layout.js";

package/dist/esm/layout/store-layout.d.ts

@@ -5,6 +5,7 @@ export declare const ALIASES_FILE = ".kb/tag-aliases.yaml";
 export declare const ASSERTIONS_DIR = "content/assertions";
 export declare const CONFIG_FILE = ".kb/config.yaml";
 export declare const EVENTS_DIR = "content/events";
+export declare const TAXONOMY_FILE = ".kb/taxonomy.yaml";
 export declare function buildEventPath(id: string): string;
 export declare function resolveAssertionsDir(storePath: string): string;
 export declare function resolveEventPath(input: {

package/dist/esm/layout/store-layout.js

@@ -6,6 +6,7 @@ export const ALIASES_FILE = `${KB_DIR}/tag-aliases.yaml`;
 export const ASSERTIONS_DIR = `${CONTENT_DIR}/${ASSERTIONS_SEGMENT}`;
 export const CONFIG_FILE = `${KB_DIR}/config.yaml`;
 export const EVENTS_DIR = `${CONTENT_DIR}/events`;
+export const TAXONOMY_FILE = `${KB_DIR}/taxonomy.yaml`;
 export function buildEventPath(id) {
     return `${EVENTS_DIR}/${id}.md`;
 }

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

@@ -1,2 +1,3 @@
 export { pathsFindings, type PathsNote } from './paths.js';
 export { tagAliasFindings, type TagAliasNote } from './tag-alias.js';
+export { taxonomyFindings, type TaxonomyNote } from './taxonomy.js';

package/dist/esm/lints/index.js

@@ -1,2 +1,3 @@
 export { pathsFindings } from "./paths.js";
 export { tagAliasFindings } from "./tag-alias.js";
+export { taxonomyFindings } from "./taxonomy.js";

package/dist/esm/lints/taxonomy.d.ts

@@ -0,0 +1,12 @@
+import type { KbConfig } from '../config/config-schema.js';
+import type { Taxonomy } from '../taxonomy/taxonomy-schema.js';
+import type { Finding } from '../types.js';
+export interface TaxonomyNote {
+    relativePath: string;
+}
+export declare function taxonomyFindings(input: {
+    notes: readonly TaxonomyNote[];
+    taxonomy: Taxonomy;
+    config: KbConfig;
+    taxonomyPath: string;
+}): Finding[];

package/dist/esm/lints/taxonomy.js

@@ -0,0 +1,52 @@
+import { createNoteScopeMatcher } from "../config/note-scope.js";
+import { ASSERTIONS_DIR } from "../layout/index.js";
+import { resolveDomain, resolveParent } from "../taxonomy/domain-paths.js";
+export function taxonomyFindings(input) {
+    const { notes, taxonomy, config, taxonomyPath } = input;
+    const declared = taxonomy.keys().toArray().toSorted();
+    if (declared.length === 0) {
+        return [];
+    }
+    const observed = new Set();
+    for (const note of notes) {
+        const domain = resolveDomain(note.relativePath);
+        if (domain !== undefined) {
+            observed.add(domain);
+        }
+    }
+    const matcher = createNoteScopeMatcher(config);
+    const findings = [];
+    for (const domain of [...observed].toSorted()) {
+        if (!taxonomy.has(domain)) {
+            findings.push(buildFinding(taxonomyPath, 'undeclared', `folder "${domain}" holds notes but no domain declares it`));
+        }
+    }
+    for (const domain of declared) {
+        if (holdsNote(domain, observed) || matcher.isExcluded(`${ASSERTIONS_DIR}/${domain}`)) {
+            continue;
+        }
+        findings.push(buildFinding(taxonomyPath, 'unused', `domain "${domain}" is declared but holds no notes`));
+    }
+    for (const domain of declared) {
+        const parent = resolveParent(domain);
+        if (parent !== undefined && !taxonomy.has(parent)) {
+            findings.push(buildFinding(taxonomyPath, 'orphan', `domain "${domain}" is declared but its parent "${parent}" is not`));
+        }
+    }
+    return findings;
+}
+function buildFinding(taxonomyPath, rule, message) {
+    return { path: taxonomyPath, scope: 'vault', rule: `taxonomy.${rule}`, severity: 'warning', message };
+}
+function holdsNote(domain, observed) {
+    if (observed.has(domain)) {
+        return true;
+    }
+    const prefix = `${domain}/`;
+    for (const candidate of observed) {
+        if (candidate.startsWith(prefix)) {
+            return true;
+        }
+    }
+    return false;
+}

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

@@ -0,0 +1,3 @@
+export declare function deriveDomains(relativePaths: Iterable<string>): string[];
+export declare function resolveDomain(relativePath: string): string | undefined;
+export declare function resolveParent(path: string): string | undefined;

package/dist/esm/taxonomy/domain-paths.js

@@ -0,0 +1,23 @@
+import { ASSERTIONS_DIR } from "../layout/index.js";
+export function deriveDomains(relativePaths) {
+    const domains = new Set();
+    for (const relativePath of relativePaths) {
+        let domain = resolveDomain(relativePath);
+        while (domain !== undefined) {
+            domains.add(domain);
+            domain = resolveParent(domain);
+        }
+    }
+    return domains.values().toArray().toSorted();
+}
+export function resolveDomain(relativePath) {
+    const prefix = `${ASSERTIONS_DIR}/`;
+    if (!relativePath.startsWith(prefix)) {
+        return undefined;
+    }
+    return resolveParent(relativePath.slice(prefix.length));
+}
+export function resolveParent(path) {
+    const lastSlash = path.lastIndexOf('/');
+    return lastSlash === -1 ? undefined : path.slice(0, lastSlash);
+}

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

@@ -0,0 +1,4 @@
+export { resolveDomain, resolveParent } from './domain-paths.js';
+export { loadTaxonomy } from './load-taxonomy.js';
+export { describeKeyDefect, type Taxonomy, type TaxonomyEntry, taxonomyFileShape } from './taxonomy-schema.js';
+export { type TaxonomyDeclaration, writeTaxonomy } from './write-taxonomy.js';

package/dist/esm/taxonomy/index.js

@@ -0,0 +1,4 @@
+export { resolveDomain, resolveParent } from "./domain-paths.js";
+export { loadTaxonomy } from "./load-taxonomy.js";
+export { describeKeyDefect, taxonomyFileShape } from "./taxonomy-schema.js";
+export { writeTaxonomy } from "./write-taxonomy.js";

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

@@ -0,0 +1,5 @@
+import type { KbRoot } from '../types.js';
+import { type Taxonomy } from './taxonomy-schema.js';
+export declare function loadTaxonomy(input: {
+    kbRoot: KbRoot;
+}): Promise<Taxonomy>;

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

@@ -0,0 +1,60 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parse } from 'yaml';
+import { KbLoaderError } from "../config/kb-loader-error.js";
+import { TAXONOMY_FILE } from "../layout/index.js";
+import { isEnoent } from "../type-guards.js";
+import { describeKeyDefect, taxonomyFileShape } from "./taxonomy-schema.js";
+export async function loadTaxonomy(input) {
+    const path = join(input.kbRoot.path, TAXONOMY_FILE);
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (isEnoent(error)) {
+            return new Map();
+        }
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = parse(text);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new KbLoaderError(`${path}: malformed YAML — ${message}`);
+    }
+    const result = taxonomyFileShape.safeParse(parsed ?? {});
+    if (!result.success) {
+        throw new KbLoaderError(`${path}: invalid taxonomy.yaml${describeIssueLocation(result.error)}`);
+    }
+    const entries = new Map();
+    collectBlock({ entries, block: result.data.domains ?? undefined, provisional: false, path });
+    collectBlock({ entries, block: result.data.provisional ?? undefined, provisional: true, path });
+    return entries;
+}
+function collectBlock(input) {
+    const { entries, block, provisional, path } = input;
+    if (block === undefined) {
+        return;
+    }
+    for (const [key, description] of Object.entries(block)) {
+        const defect = describeKeyDefect(key);
+        if (defect !== undefined) {
+            throw new KbLoaderError(`${path}: domain "${key}" ${defect}`);
+        }
+        if (entries.has(key)) {
+            throw new KbLoaderError(`${path}: domain "${key}" is declared in both domains and provisional`);
+        }
+        entries.set(key, { description: description ?? '', provisional });
+    }
+}
+function describeIssueLocation(error) {
+    const issue = error.issues[0];
+    if (issue === undefined) {
+        return ' — unknown error';
+    }
+    const location = issue.path.length > 0 ? ` at ${issue.path.join('.')}` : '';
+    return `${location} — ${issue.message}`;
+}

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

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+export declare function describeKeyDefect(key: string): string | undefined;
+export type Taxonomy = ReadonlyMap<string, TaxonomyEntry>;
+export interface TaxonomyEntry {
+    description: string;
+    provisional: boolean;
+}
+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>>>>;
+}, z.core.$strip>;

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

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import { ASSERTIONS_DIR, ASSERTIONS_SEGMENT, CONTENT_DIR } from "../layout/index.js";
+export function describeKeyDefect(key) {
+    if (key === '') {
+        return 'is empty';
+    }
+    if (key.includes('\\')) {
+        return 'contains a backslash; domain paths are slash-separated';
+    }
+    if (key.startsWith('/') || key.endsWith('/')) {
+        return 'has a leading or trailing slash';
+    }
+    const segments = key.split('/');
+    if (segments.some((segment) => segment.trim() === '')) {
+        return 'has an empty segment';
+    }
+    if (segments.some((segment) => segment === '.' || segment === '..')) {
+        return 'has a "." or ".." segment';
+    }
+    if (segments[0] === ASSERTIONS_SEGMENT || (segments[0] === CONTENT_DIR && segments[1] === ASSERTIONS_SEGMENT)) {
+        return `restates the ${ASSERTIONS_DIR}/ prefix, which every key implies`;
+    }
+    return undefined;
+}
+export const taxonomyFileShape = z.object({
+    domains: z.record(z.string(), z.string().nullable()).nullable().optional(),
+    provisional: z.record(z.string(), z.string().nullable()).nullable().optional(),
+});

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

@@ -0,0 +1,12 @@
+import type { KbRoot } from '../types.js';
+export interface TaxonomyDeclaration {
+    path: string;
+    description?: string;
+    provisional: boolean;
+}
+export declare function writeTaxonomy(input: {
+    kbRoot: KbRoot;
+    declarations: readonly TaxonomyDeclaration[];
+}): Promise<{
+    added: string[];
+}>;

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

@@ -0,0 +1,142 @@
+import { randomBytes } from 'node:crypto';
+import { readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isMap, isPair, isScalar, parseDocument } from 'yaml';
+import { KbLoaderError } from "../config/kb-loader-error.js";
+import { TAXONOMY_FILE } from "../layout/index.js";
+import { isEnoent, isRecord } from "../type-guards.js";
+import { describeKeyDefect } from "./taxonomy-schema.js";
+const BLOCKS = new Set(['domains', 'provisional']);
+export async function writeTaxonomy(input) {
+    const path = join(input.kbRoot.path, TAXONOMY_FILE);
+    for (const declaration of input.declarations) {
+        const defect = describeKeyDefect(declaration.path);
+        if (defect !== undefined) {
+            throw new KbLoaderError(`${path}: domain "${declaration.path}" ${defect}`);
+        }
+    }
+    const document = await readDocument(path);
+    const declared = readDeclaredPaths(document);
+    const added = [];
+    const byBlock = new Map();
+    for (const declaration of sortByPath(input.declarations)) {
+        if (declared.has(declaration.path)) {
+            continue;
+        }
+        declared.add(declaration.path);
+        added.push(declaration.path);
+        const block = declaration.provisional ? 'provisional' : 'domains';
+        const description = declaration.description ?? '';
+        const entries = byBlock.get(block) ?? [];
+        entries.push([declaration.path, description === '' ? null : description]);
+        byBlock.set(block, entries);
+    }
+    if (added.length === 0) {
+        return { added };
+    }
+    for (const [block, entries] of byBlock) {
+        declareInBlock({ document, block, entries });
+    }
+    await writeAtomic(path, document.toString({ nullStr: '' }));
+    return { added };
+}
+function assertBlocksAppendable(document, path) {
+    const contents = document.contents;
+    if (!isMap(contents)) {
+        return;
+    }
+    for (const pair of contents.items) {
+        if (!isPair(pair) || !isScalar(pair.key) || typeof pair.key.value !== 'string') {
+            continue;
+        }
+        if (!BLOCKS.has(pair.key.value) || isMap(pair.value) || isEmptyBlockValue(pair.value)) {
+            continue;
+        }
+        throw new KbLoaderError(`${path}: "${pair.key.value}" must be a mapping of domain paths to descriptions`);
+    }
+}
+function declareInBlock(input) {
+    const { document, block, entries } = input;
+    const emptied = findEmptyBlock(document, block);
+    if (emptied === undefined) {
+        for (const [path, description] of entries) {
+            document.setIn([block, path], description);
+        }
+        return;
+    }
+    const comment = isScalar(emptied.value) ? emptied.value.comment : undefined;
+    if (typeof comment === 'string' && isScalar(emptied.key)) {
+        emptied.key.comment = comment;
+    }
+    emptied.value = document.createNode(Object.fromEntries(entries));
+}
+function findEmptyBlock(document, block) {
+    const contents = document.contents;
+    if (!isMap(contents)) {
+        return undefined;
+    }
+    for (const pair of contents.items) {
+        if (isPair(pair) && isScalar(pair.key) && pair.key.value === block && isEmptyBlockValue(pair.value)) {
+            return pair;
+        }
+    }
+    return undefined;
+}
+function isEmptyBlockValue(value) {
+    return value === null || (isScalar(value) && value.value === null);
+}
+async function readDocument(path) {
+    let text = '';
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (!isEnoent(error)) {
+            throw error;
+        }
+    }
+    const document = parseDocument(text);
+    const firstError = document.errors[0];
+    if (firstError !== undefined) {
+        throw new KbLoaderError(`${path}: malformed YAML — ${firstError.message}`);
+    }
+    if (document.contents !== null && !isMap(document.contents)) {
+        throw new KbLoaderError(`${path}: top-level must be a mapping`);
+    }
+    assertBlocksAppendable(document, path);
+    return document;
+}
+function readDeclaredPaths(document) {
+    const paths = new Set();
+    const contents = document.toJS();
+    if (!isRecord(contents)) {
+        return paths;
+    }
+    for (const block of BLOCKS) {
+        const declarations = contents[block];
+        if (isRecord(declarations)) {
+            for (const path of Object.keys(declarations)) {
+                paths.add(path);
+            }
+        }
+    }
+    return paths;
+}
+function sortByPath(declarations) {
+    return declarations.toSorted((a, b) => {
+        if (a.path === b.path)
+            return 0;
+        return a.path < b.path ? -1 : 1;
+    });
+}
+async function writeAtomic(path, content) {
+    const tempPath = `${path}.${randomBytes(8).toString('hex')}.tmp`;
+    await writeFile(tempPath, content, 'utf8');
+    try {
+        await rename(tempPath, path);
+    }
+    catch (error) {
+        await unlink(tempPath).catch(() => { });
+        throw error;
+    }
+}

package/dist/esm/types.d.ts

@@ -42,6 +42,7 @@ export interface ParsedNote {
 export type FindingSeverity = 'error' | 'warning';
 export interface Finding {
     path: string;
+    scope?: 'note' | 'vault';
     line?: number;
     rule: string;
     severity: FindingSeverity;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/kb",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Knowledge-base foundation: discovery, config, frontmatter parsing, records, tags, and vault-integrity checks",
   "keywords": [
     "frontmatter",
@@ -76,6 +76,11 @@
       "types": "./dist/esm/tags/index.d.ts",
       "import": "./dist/esm/tags/index.js"
     },
+    "./taxonomy": {
+      "source": "./src/taxonomy/index.ts",
+      "types": "./dist/esm/taxonomy/index.d.ts",
+      "import": "./dist/esm/taxonomy/index.js"
+    },
     "./vault-integrity": {
       "source": "./src/vault-integrity/index.ts",
       "types": "./dist/esm/vault-integrity/index.d.ts",