@williamthorsen/kb 0.0.0 → 0.3.1

package/dist/esm/frontmatter/parse-note.js

@@ -0,0 +1,98 @@
+import { readFile } from 'node:fs/promises';
+import { isMap, isPair, isScalar, isSeq, parseDocument } from 'yaml';
+import { isRecord } from "../type-guards.js";
+const FENCE = '---';
+export async function parseNote(input) {
+    const content = await readFile(input.path, 'utf8');
+    return parseNoteContent({ content, path: input.path });
+}
+export function parseNoteContent(input) {
+    const { content, path = '<string>' } = input;
+    const lines = content.split('\n');
+    if (lines[0] !== FENCE) {
+        return { path, content, frontmatter: null, frontmatterRaw: null, body: content, bodyStartLine: 1 };
+    }
+    const endIndex = lines.findIndex((line, index) => index > 0 && line === FENCE);
+    if (endIndex === -1) {
+        return { path, content, frontmatter: null, frontmatterRaw: null, body: content, bodyStartLine: 1 };
+    }
+    const text = lines.slice(1, endIndex).join('\n');
+    const doc = parseDocument(text, { schema: 'core' });
+    const parseError = doc.errors[0]?.message;
+    const frontmatterRaw = {
+        text,
+        startLine: 1,
+        endLine: endIndex + 1,
+        ...(parseError !== undefined && { parseError }),
+    };
+    const body = lines.slice(endIndex + 1).join('\n');
+    const bodyStartLine = endIndex + 2;
+    const frontmatter = parseError === undefined ? toFrontmatter(doc) : null;
+    return { path, content, frontmatter, frontmatterRaw, body, bodyStartLine };
+}
+function stringList(value) {
+    if (!isSeq(value)) {
+        return [];
+    }
+    const result = [];
+    for (const item of value.items) {
+        if (isScalar(item) && typeof item.value === 'string') {
+            result.push(item.value);
+        }
+    }
+    return result;
+}
+function stringValue(value) {
+    if (!isScalar(value)) {
+        return '';
+    }
+    const raw = value.value;
+    if (typeof raw === 'string') {
+        return raw;
+    }
+    if (typeof raw === 'number' || typeof raw === 'boolean' || typeof raw === 'bigint') {
+        return String(raw);
+    }
+    return '';
+}
+function toFrontmatter(doc) {
+    const contents = doc.contents;
+    if (!isMap(contents)) {
+        return null;
+    }
+    const plain = doc.toJS();
+    const plainRecord = isRecord(plain) ? plain : {};
+    const extra = {};
+    let title = '';
+    let recordType = '';
+    let created = '';
+    let updated = '';
+    let tags = [];
+    for (const item of contents.items) {
+        if (!isPair(item) || !isScalar(item.key))
+            continue;
+        const key = item.key.value;
+        if (typeof key !== 'string')
+            continue;
+        switch (key) {
+            case 'title':
+                title = stringValue(item.value);
+                break;
+            case 'recordType':
+                recordType = stringValue(item.value);
+                break;
+            case 'created':
+                created = stringValue(item.value);
+                break;
+            case 'updated':
+                updated = stringValue(item.value);
+                break;
+            case 'tags':
+                tags = stringList(item.value);
+                break;
+            default:
+                extra[key] = key in plainRecord ? plainRecord[key] : null;
+        }
+    }
+    return { title, recordType, created, updated, tags, extra };
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,2 @@
+export type { AliasMap, Finding, FindingSeverity, Frontmatter, FrontmatterRaw, KbRegistry, KbRegistryEntry, KbRoot, ParsedNote, } from './types.js';
+export { buildVaultIndex, type VaultIndex } from './vault-integrity/build-vault-index.js';

package/dist/esm/index.js

@@ -0,0 +1 @@
+export { buildVaultIndex } from "./vault-integrity/build-vault-index.js";

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

@@ -0,0 +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';

package/dist/esm/layout/index.js

@@ -0,0 +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";

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

@@ -0,0 +1,15 @@
+export declare const KB_DIR = ".kb";
+export declare const CONTENT_DIR = "content";
+export declare const ASSERTIONS_SEGMENT = "assertions";
+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 function buildEventPath(id: string): string;
+export declare function resolveAssertionsDir(storePath: string): string;
+export declare function resolveEventPath(input: {
+    storePath: string;
+    id: string;
+}): string;
+export declare function resolveEventsDir(storePath: string): string;
+export declare function resolveKbDir(storePath: string): string;

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

@@ -0,0 +1,23 @@
+import { join } from 'node:path';
+export const KB_DIR = '.kb';
+export const CONTENT_DIR = 'content';
+export const ASSERTIONS_SEGMENT = 'assertions';
+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 function buildEventPath(id) {
+    return `${EVENTS_DIR}/${id}.md`;
+}
+export function resolveAssertionsDir(storePath) {
+    return join(storePath, ASSERTIONS_DIR);
+}
+export function resolveEventPath(input) {
+    return join(input.storePath, buildEventPath(input.id));
+}
+export function resolveEventsDir(storePath) {
+    return join(storePath, EVENTS_DIR);
+}
+export function resolveKbDir(storePath) {
+    return join(storePath, KB_DIR);
+}

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

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

package/dist/esm/lints/index.js

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

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

@@ -0,0 +1,6 @@
+import type { Finding } from '../types.js';
+export interface PathsNote {
+    path: string;
+    content: string;
+}
+export declare function pathsFindings(note: PathsNote): Finding[];

package/dist/esm/lints/paths.js

@@ -0,0 +1,12 @@
+import { countNewlines } from "../vault-integrity/wikilink-parse.js";
+export function pathsFindings(note) {
+    const findings = Array.from(note.content.matchAll(USER_HOME), (match) => ({
+        path: note.path,
+        line: countNewlines(note.content, match.index) + 1,
+        rule: 'paths.user-home',
+        severity: 'error',
+        message: `hardcoded "${match[0]}" — replace with ~/`,
+    }));
+    return findings;
+}
+const USER_HOME = /\/Users\/[A-Za-z0-9_.-]+\//g;

package/dist/esm/lints/tag-alias.d.ts

@@ -0,0 +1,6 @@
+import type { AliasMap, Finding } from '../types.js';
+export interface TagAliasNote {
+    path: string;
+    fields: Record<string, unknown>;
+}
+export declare function tagAliasFindings(note: TagAliasNote, aliases: AliasMap): Finding[];

package/dist/esm/lints/tag-alias.js

@@ -0,0 +1,21 @@
+import { asStringList } from "../note-io/field-validators.js";
+import { findAliasFor } from "../tags/canonicalize.js";
+export function tagAliasFindings(note, aliases) {
+    const tags = asStringList(note.fields.tags);
+    if (tags === null) {
+        return [];
+    }
+    const findings = [];
+    for (const tag of tags) {
+        const canonical = findAliasFor(tag, aliases);
+        if (canonical === null)
+            continue;
+        findings.push({
+            path: note.path,
+            rule: 'tag-alias',
+            severity: 'warning',
+            message: `tag "${tag}" is an alias — use canonical form "${canonical}"`,
+        });
+    }
+    return findings;
+}

package/dist/esm/note-io/field-validators.d.ts

@@ -0,0 +1,2 @@
+export declare function asStringList(value: unknown): string[] | null;
+export declare function isValidDate(value: string): boolean;

package/dist/esm/note-io/field-validators.js

@@ -0,0 +1,30 @@
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+const TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
+export function asStringList(value) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        return null;
+    }
+    return value.filter((item) => typeof item === 'string');
+}
+export function isValidDate(value) {
+    const dateOnly = DATE_ONLY.test(value);
+    if (!dateOnly && !TIMESTAMP.test(value)) {
+        return false;
+    }
+    const year = Number(value.slice(0, 4));
+    const month = Number(value.slice(5, 7));
+    const day = Number(value.slice(8, 10));
+    const hour = dateOnly ? 0 : Number(value.slice(11, 13));
+    const minute = dateOnly ? 0 : Number(value.slice(14, 16));
+    const second = dateOnly ? 0 : Number(value.slice(17, 19));
+    const roundTrip = new Date(Date.UTC(year, month - 1, day, hour, minute, second));
+    return (roundTrip.getUTCFullYear() === year &&
+        roundTrip.getUTCMonth() === month - 1 &&
+        roundTrip.getUTCDate() === day &&
+        roundTrip.getUTCHours() === hour &&
+        roundTrip.getUTCMinutes() === minute &&
+        roundTrip.getUTCSeconds() === second);
+}

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

@@ -0,0 +1,4 @@
+export { asStringList, isValidDate } from './field-validators.js';
+export { type ReadNote, readNote, readNoteContent } from './read-note.js';
+export { renderNote, writeNote } from './write-note.js';
+export { parseFrontmatterFields, renderFrontmatterFields } from './yaml-fields.js';

package/dist/esm/note-io/index.js

@@ -0,0 +1,4 @@
+export { asStringList, isValidDate } from "./field-validators.js";
+export { readNote, readNoteContent } from "./read-note.js";
+export { renderNote, writeNote } from "./write-note.js";
+export { parseFrontmatterFields, renderFrontmatterFields } from "./yaml-fields.js";

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

@@ -0,0 +1,8 @@
+export interface ReadNote {
+    fields: Record<string, unknown>;
+    body: string;
+    bodyStartLine: number;
+    error?: string;
+}
+export declare function readNote(path: string): Promise<ReadNote>;
+export declare function readNoteContent(content: string): ReadNote;

package/dist/esm/note-io/read-note.js

@@ -0,0 +1,22 @@
+import { readFile } from 'node:fs/promises';
+import { parseFrontmatterFields } from "./yaml-fields.js";
+const FENCE = '---';
+export async function readNote(path) {
+    const content = await readFile(path, 'utf8');
+    return readNoteContent(content);
+}
+export function readNoteContent(content) {
+    const lines = content.split('\n');
+    if (lines[0] !== FENCE) {
+        return { fields: {}, body: content, bodyStartLine: 1, error: 'no frontmatter block found' };
+    }
+    const endIndex = lines.findIndex((line, index) => index > 0 && line === FENCE);
+    if (endIndex === -1) {
+        return { fields: {}, body: content, bodyStartLine: 1, error: 'no frontmatter block found' };
+    }
+    const text = lines.slice(1, endIndex).join('\n');
+    const body = lines.slice(endIndex + 1).join('\n');
+    const bodyStartLine = endIndex + 2;
+    const { fields, error } = parseFrontmatterFields(text);
+    return { fields, body, bodyStartLine, ...(error !== undefined && { error }) };
+}

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

@@ -0,0 +1,2 @@
+export declare function renderNote(fields: Record<string, unknown>, body: string): string;
+export declare function writeNote(path: string, fields: Record<string, unknown>, body: string): Promise<void>;

package/dist/esm/note-io/write-note.js

@@ -0,0 +1,21 @@
+import { randomBytes } from 'node:crypto';
+import { rename, unlink, writeFile } from 'node:fs/promises';
+import { renderFrontmatterFields } from "./yaml-fields.js";
+const FENCE = '---';
+export function renderNote(fields, body) {
+    const frontmatter = renderFrontmatterFields(fields);
+    const normalizedBody = body.startsWith('\n') ? body.slice(1) : body;
+    return `${FENCE}\n${frontmatter}\n${FENCE}\n\n${normalizedBody}`;
+}
+export async function writeNote(path, fields, body) {
+    const content = renderNote(fields, body);
+    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/note-io/yaml-fields.d.ts

@@ -0,0 +1,5 @@
+export declare function parseFrontmatterFields(text: string): {
+    fields: Record<string, unknown>;
+    error?: string;
+};
+export declare function renderFrontmatterFields(fields: Record<string, unknown>): string;

package/dist/esm/note-io/yaml-fields.js

@@ -0,0 +1,49 @@
+import { Document, parseDocument, stringify } from 'yaml';
+import { isRecord } from "../type-guards.js";
+const SCALAR_STRINGIFY_OPTIONS = {
+    schema: 'core',
+    defaultStringType: 'PLAIN',
+    defaultKeyType: 'PLAIN',
+    singleQuote: true,
+    lineWidth: 0,
+};
+export function parseFrontmatterFields(text) {
+    const doc = parseDocument(text, { schema: 'core' });
+    const error = doc.errors[0]?.message;
+    if (error !== undefined) {
+        return { fields: {}, error };
+    }
+    const plain = doc.toJS();
+    return { fields: isRecord(plain) ? plain : {} };
+}
+export function renderFrontmatterFields(fields) {
+    return Object.entries(fields)
+        .flatMap(([key, value]) => renderEntry(key, value))
+        .join('\n');
+}
+function renderEntry(key, value) {
+    if (typeof value === 'string') {
+        return [`${key}: ${renderScalar(value)}`];
+    }
+    if (value === null || value === undefined) {
+        return [`${key}:`];
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return [`${key}: ${stringify(value, SCALAR_STRINGIFY_OPTIONS).replace(/\n$/, '')}`];
+    }
+    if (Array.isArray(value) && value.every((item) => typeof item === 'string')) {
+        return [`${key}: ${renderFlowList(value)}`];
+    }
+    const doc = new Document({ [key]: value });
+    return doc.toString({ lineWidth: 0 }).trimEnd().split('\n');
+}
+function renderFlowList(values) {
+    return `[${values.map((value) => renderScalar(value)).join(', ')}]`;
+}
+function renderScalar(value) {
+    const rendered = stringify(value, SCALAR_STRINGIFY_OPTIONS).replace(/\n$/, '');
+    if (rendered.includes('\n')) {
+        return stringify(value, { ...SCALAR_STRINGIFY_OPTIONS, defaultStringType: 'QUOTE_DOUBLE' }).replace(/\n$/, '');
+    }
+    return rendered;
+}

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

@@ -0,0 +1,25 @@
+export interface KbAssertion {
+    recordType: 'assertion';
+    title: string;
+    created: string;
+    updated: string;
+    tags: string[];
+    addressedBy: string[];
+    lastVerified?: string;
+    supersedes?: string;
+    supersededBy?: string;
+    extra: Record<string, unknown>;
+    body: string;
+}
+export type ParseAssertionResult = {
+    ok: true;
+    record: KbAssertion;
+} | {
+    ok: false;
+    errors: string[];
+};
+export declare function parseAssertion(fields: Record<string, unknown>, body: string): ParseAssertionResult;
+export declare function renderAssertion(record: KbAssertion): {
+    fields: Record<string, unknown>;
+    body: string;
+};

package/dist/esm/records/assertion.js

@@ -0,0 +1,136 @@
+import { asStringList, isValidDate } from "../note-io/field-validators.js";
+const TYPED_FIELDS = new Set([
+    'recordType',
+    'title',
+    'created',
+    'updated',
+    'tags',
+    'addressed-by',
+    'last-verified',
+    'supersedes',
+    'superseded-by',
+]);
+export function parseAssertion(fields, body) {
+    const errors = [];
+    if (fields.recordType !== 'assertion') {
+        errors.push('recordType: expected "assertion"');
+    }
+    let title;
+    if (typeof fields.title === 'string' && fields.title.length > 0) {
+        title = fields.title;
+    }
+    else {
+        errors.push('missing required field: title');
+    }
+    const created = requireDate(fields.created, 'created', errors);
+    const updated = requireDate(fields.updated, 'updated', errors);
+    let tags;
+    if (fields.tags === undefined) {
+        errors.push('missing required field: tags');
+    }
+    else {
+        const list = asStringList(fields.tags);
+        if (list === null) {
+            errors.push('tags: must be a list');
+        }
+        else {
+            tags = list;
+        }
+    }
+    const addressedBy = readListField(fields['addressed-by'], 'addressed-by', errors);
+    const lastVerified = readOptionalDate(fields['last-verified'], 'last-verified', errors);
+    const supersedes = readOptionalString(fields.supersedes, 'supersedes', errors);
+    const supersededBy = readOptionalString(fields['superseded-by'], 'superseded-by', errors);
+    if (errors.length > 0 ||
+        title === undefined ||
+        created === undefined ||
+        updated === undefined ||
+        tags === undefined ||
+        addressedBy === undefined) {
+        return { ok: false, errors };
+    }
+    const extra = {};
+    for (const [key, value] of Object.entries(fields)) {
+        if (!TYPED_FIELDS.has(key)) {
+            extra[key] = value;
+        }
+    }
+    return {
+        ok: true,
+        record: {
+            recordType: 'assertion',
+            title,
+            created,
+            updated,
+            tags,
+            addressedBy,
+            ...(lastVerified !== undefined && { lastVerified }),
+            ...(supersedes !== undefined && { supersedes }),
+            ...(supersededBy !== undefined && { supersededBy }),
+            extra,
+            body,
+        },
+    };
+}
+export function renderAssertion(record) {
+    const fields = {
+        recordType: record.recordType,
+        title: record.title,
+        created: record.created,
+        updated: record.updated,
+        tags: record.tags,
+    };
+    if (record.addressedBy.length > 0) {
+        fields['addressed-by'] = record.addressedBy;
+    }
+    if (record.lastVerified !== undefined) {
+        fields['last-verified'] = record.lastVerified;
+    }
+    if (record.supersedes !== undefined) {
+        fields.supersedes = record.supersedes;
+    }
+    if (record.supersededBy !== undefined) {
+        fields['superseded-by'] = record.supersededBy;
+    }
+    Object.assign(fields, record.extra);
+    return { fields, body: record.body };
+}
+function requireDate(value, field, errors) {
+    if (typeof value !== 'string') {
+        errors.push(`missing required field: ${field}`);
+        return undefined;
+    }
+    if (!isValidDate(value)) {
+        errors.push(`${field}: expected a YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ date`);
+        return undefined;
+    }
+    return value;
+}
+function readListField(value, field, errors) {
+    const list = asStringList(value);
+    if (list === null) {
+        errors.push(`${field}: must be a list`);
+        return undefined;
+    }
+    return list;
+}
+function readOptionalDate(value, field, errors) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value === 'string' && isValidDate(value)) {
+        return value;
+    }
+    errors.push(`${field}: expected a YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ date`);
+    return undefined;
+}
+function readOptionalString(value, field, errors) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value === 'string') {
+        return value;
+    }
+    errors.push(`${field}: expected a string`);
+    return undefined;
+}

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

@@ -0,0 +1,28 @@
+export declare const EVENT_IMPACT_LEVELS: readonly ["low", "medium", "high", "critical"];
+export type EventImpact = (typeof EVENT_IMPACT_LEVELS)[number];
+export declare function isEventImpact(value: unknown): value is EventImpact;
+export interface KbEvent {
+    recordType: 'event';
+    id: string;
+    capturedAt: string;
+    session?: string;
+    cwd: string;
+    summary: string;
+    tags: string[];
+    addressedBy: string[];
+    impact?: EventImpact;
+    extra: Record<string, unknown>;
+    body: string;
+}
+export type ParseEventResult = {
+    ok: true;
+    record: KbEvent;
+} | {
+    ok: false;
+    errors: string[];
+};
+export declare function parseEvent(fields: Record<string, unknown>, body: string): ParseEventResult;
+export declare function renderEvent(record: KbEvent): {
+    fields: Record<string, unknown>;
+    body: string;
+};