@williamthorsen/kb 0.0.0 → 0.3.0

package/dist/esm/records/event.js

@@ -0,0 +1,128 @@
+import { asStringList, isValidDate } from "../note-io/field-validators.js";
+export const EVENT_IMPACT_LEVELS = ['low', 'medium', 'high', 'critical'];
+const IMPACT_LEVEL_SET = new Set(EVENT_IMPACT_LEVELS);
+export function isEventImpact(value) {
+    return typeof value === 'string' && IMPACT_LEVEL_SET.has(value);
+}
+const TYPED_FIELDS = new Set([
+    'recordType',
+    'id',
+    'captured-at',
+    'session',
+    'cwd',
+    'summary',
+    'tags',
+    'addressed-by',
+    'impact',
+]);
+export function parseEvent(fields, body) {
+    const errors = [];
+    if (fields.recordType !== 'event') {
+        errors.push('recordType: expected "event"');
+    }
+    const id = requireString(fields.id, 'id', errors);
+    const session = readOptionalNonEmptyString(fields.session, 'session', errors);
+    const cwd = requireString(fields.cwd, 'cwd', errors);
+    const summary = requireString(fields.summary, 'summary', errors);
+    let capturedAt;
+    const rawCapturedAt = fields['captured-at'];
+    if (typeof rawCapturedAt !== 'string') {
+        errors.push('missing required field: captured-at');
+    }
+    else if (!isValidDate(rawCapturedAt)) {
+        errors.push('captured-at: expected a YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ date');
+    }
+    else {
+        capturedAt = rawCapturedAt;
+    }
+    const tags = readListField(fields.tags, 'tags', errors);
+    const addressedBy = readListField(fields['addressed-by'], 'addressed-by', errors);
+    const impact = readImpactField(fields.impact, errors);
+    if (errors.length > 0 ||
+        id === undefined ||
+        capturedAt === undefined ||
+        cwd === undefined ||
+        summary === 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: 'event',
+            id,
+            capturedAt,
+            ...(session !== undefined && { session }),
+            cwd,
+            summary,
+            tags,
+            addressedBy,
+            ...(impact !== undefined && { impact }),
+            extra,
+            body,
+        },
+    };
+}
+export function renderEvent(record) {
+    const fields = {
+        recordType: record.recordType,
+        id: record.id,
+        'captured-at': record.capturedAt,
+        ...(record.session !== undefined && record.session.length > 0 && { session: record.session }),
+        cwd: record.cwd,
+        summary: record.summary,
+    };
+    if (record.tags.length > 0) {
+        fields.tags = record.tags;
+    }
+    if (record.addressedBy.length > 0) {
+        fields['addressed-by'] = record.addressedBy;
+    }
+    if (record.impact !== undefined) {
+        fields.impact = record.impact;
+    }
+    Object.assign(fields, record.extra);
+    return { fields, body: record.body };
+}
+function readImpactField(value, errors) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (isEventImpact(value)) {
+        return value;
+    }
+    errors.push(`impact: expected one of ${EVENT_IMPACT_LEVELS.join(', ')}`);
+    return undefined;
+}
+function readListField(value, field, errors) {
+    const list = asStringList(value);
+    if (list === null) {
+        errors.push(`${field}: must be a list`);
+        return undefined;
+    }
+    return list;
+}
+function readOptionalNonEmptyString(value, field, errors) {
+    if (value === undefined || value === null || value === '') {
+        return undefined;
+    }
+    if (typeof value === 'string') {
+        return value;
+    }
+    errors.push(`${field}: expected a string`);
+    return undefined;
+}
+function requireString(value, field, errors) {
+    if (typeof value === 'string' && value.length > 0) {
+        return value;
+    }
+    errors.push(`missing required field: ${field}`);
+    return undefined;
+}

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

@@ -0,0 +1,2 @@
+export { type KbAssertion, parseAssertion, type ParseAssertionResult, renderAssertion } from './assertion.js';
+export { EVENT_IMPACT_LEVELS, type EventImpact, isEventImpact, type KbEvent, parseEvent, type ParseEventResult, renderEvent, } from './event.js';

package/dist/esm/records/index.js

@@ -0,0 +1,2 @@
+export { parseAssertion, renderAssertion } from "./assertion.js";
+export { EVENT_IMPACT_LEVELS, isEventImpact, parseEvent, renderEvent, } from "./event.js";

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

@@ -0,0 +1,3 @@
+import type { AliasMap } from '../types.js';
+export declare function canonicalize(tag: string, aliases: AliasMap): string;
+export declare function findAliasFor(tag: string, aliases: AliasMap): string | null;

package/dist/esm/tags/canonicalize.js

@@ -0,0 +1,6 @@
+export function canonicalize(tag, aliases) {
+    return aliases.get(tag.toLowerCase()) ?? tag;
+}
+export function findAliasFor(tag, aliases) {
+    return aliases.get(tag.toLowerCase()) ?? null;
+}

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

@@ -0,0 +1,3 @@
+export type { AliasMap } from '../types.js';
+export { canonicalize, findAliasFor } from './canonicalize.js';
+export { loadAliases, parseAliases } from './load-aliases.js';

package/dist/esm/tags/index.js

@@ -0,0 +1,2 @@
+export { canonicalize, findAliasFor } from "./canonicalize.js";
+export { loadAliases, parseAliases } from "./load-aliases.js";

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

@@ -0,0 +1,5 @@
+import type { AliasMap, KbRoot } from '../types.js';
+export declare function loadAliases(input: {
+    kbRoot: KbRoot;
+}): Promise<AliasMap>;
+export declare function parseAliases(text: string, contextLabel?: string): AliasMap;

package/dist/esm/tags/load-aliases.js

@@ -0,0 +1,72 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parse } from 'yaml';
+import { KbLoaderError } from "../config/kb-loader-error.js";
+import { ALIASES_FILE } from "../layout/index.js";
+import { isEnoent, isRecord } from "../type-guards.js";
+export async function loadAliases(input) {
+    const path = join(input.kbRoot.path, ALIASES_FILE);
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (isEnoent(error)) {
+            return new Map();
+        }
+        throw error;
+    }
+    try {
+        return parseAliases(text, path);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new KbLoaderError(message);
+    }
+}
+export function parseAliases(text, contextLabel = 'tag-aliases') {
+    let parsed;
+    try {
+        parsed = parse(text);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`${contextLabel}: malformed YAML — ${message}`);
+    }
+    if (!isRecord(parsed)) {
+        throw new Error(`${contextLabel}: top-level must be a mapping`);
+    }
+    if (!('aliases' in parsed)) {
+        throw new Error(`${contextLabel}: missing required "aliases" key`);
+    }
+    const aliasesBlock = parsed.aliases;
+    if (!isRecord(aliasesBlock)) {
+        throw new Error(`${contextLabel}: "aliases" must be a mapping of canonical to alias list`);
+    }
+    const map = new Map();
+    for (const [canonical, value] of Object.entries(aliasesBlock)) {
+        if (!Array.isArray(value)) {
+            throw new TypeError(`${contextLabel}: "${canonical}" must be a list of alias strings`);
+        }
+        const seenInCanonical = new Set();
+        for (const entry of value) {
+            if (typeof entry !== 'string') {
+                throw new TypeError(`${contextLabel}: alias entries under "${canonical}" must be string values`);
+            }
+            const alias = entry.toLowerCase();
+            if (alias === canonical.toLowerCase()) {
+                throw new Error(`${contextLabel}: alias "${entry}" equals its canonical "${canonical}"`);
+            }
+            if (seenInCanonical.has(alias)) {
+                throw new Error(`${contextLabel}: alias "${entry}" is listed twice under canonical "${canonical}"`);
+            }
+            seenInCanonical.add(alias);
+            const existing = map.get(alias);
+            if (existing !== undefined && existing !== canonical) {
+                throw new Error(`${contextLabel}: alias "${entry}" appears under multiple canonicals ("${existing}" and "${canonical}")`);
+            }
+            map.set(alias, canonical);
+        }
+    }
+    return map;
+}

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

@@ -0,0 +1,3 @@
+export declare function isEnoent(error: unknown): boolean;
+export declare function isErrorCode(error: unknown, code: string): boolean;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/esm/type-guards.js

@@ -0,0 +1,12 @@
+export function isEnoent(error) {
+    return isErrorCode(error, 'ENOENT');
+}
+export function isErrorCode(error, code) {
+    return isObject(error) && error.code === code;
+}
+export function isRecord(value) {
+    return isObject(value) && !Array.isArray(value);
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}

package/dist/esm/types.d.ts

@@ -0,0 +1,50 @@
+export interface KbRoot {
+    path: string;
+    kbDir: string;
+}
+export interface KbRegistryEntry {
+    name: string;
+    path: string;
+    description?: string;
+    readonly?: boolean;
+    source: 'user' | 'project';
+}
+export interface KbRegistry {
+    entries: KbRegistryEntry[];
+    defaultKb?: KbRegistryEntry;
+    sources: {
+        user?: string;
+        project?: string;
+    };
+}
+export interface Frontmatter {
+    title: string;
+    recordType: string;
+    created: string;
+    updated: string;
+    tags: string[];
+    extra: Record<string, unknown>;
+}
+export interface FrontmatterRaw {
+    text: string;
+    startLine: number;
+    endLine: number;
+    parseError?: string;
+}
+export interface ParsedNote {
+    path: string;
+    content: string;
+    frontmatter: Frontmatter | null;
+    frontmatterRaw: FrontmatterRaw | null;
+    body: string;
+    bodyStartLine: number;
+}
+export type FindingSeverity = 'error' | 'warning';
+export interface Finding {
+    path: string;
+    line?: number;
+    rule: string;
+    severity: FindingSeverity;
+    message: string;
+}
+export type AliasMap = ReadonlyMap<string, string>;

package/dist/esm/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,4 @@
+export type VaultIndex = ReadonlyMap<string, ReadonlySet<string>>;
+export declare function buildVaultIndex(notes: readonly {
+    path: string;
+}[]): VaultIndex;

package/dist/esm/vault-integrity/build-vault-index.js

@@ -0,0 +1,14 @@
+import { basename } from 'node:path';
+export function buildVaultIndex(notes) {
+    const index = new Map();
+    for (const note of notes) {
+        const key = basename(note.path).replace(/\.md$/, '');
+        let set = index.get(key);
+        if (set === undefined) {
+            set = new Set();
+            index.set(key, set);
+        }
+        set.add(note.path);
+    }
+    return index;
+}

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

@@ -0,0 +1,7 @@
+import type { Finding } from '../types.js';
+export interface VaultIntegrityNote {
+    path: string;
+    body: string;
+    bodyStartLine: number;
+}
+export declare function checkVaultIntegrity(notes: readonly VaultIntegrityNote[]): Finding[];

package/dist/esm/vault-integrity/check-vault-integrity.js

@@ -0,0 +1,49 @@
+import { buildVaultIndex } from "./build-vault-index.js";
+import { countNewlines, extractTarget, hasNonMarkdownExtension, lookupKey, maskFencedCode, maskInlineCode, WIKILINK, } from "./wikilink-parse.js";
+export function checkVaultIntegrity(notes) {
+    const vaultIndex = buildVaultIndex(notes);
+    return [...unresolvedLinkFindings(notes, vaultIndex), ...basenameFindings(vaultIndex)];
+}
+function basenameFindings(vaultIndex) {
+    const findings = [];
+    for (const key of [...vaultIndex.keys()].toSorted()) {
+        const paths = vaultIndex.get(key);
+        if (paths === undefined || paths.size < 2)
+            continue;
+        const sortedPaths = [...paths].toSorted();
+        findings.push({
+            path: sortedPaths[0] ?? key,
+            rule: 'wikilinks.basename',
+            severity: 'warning',
+            message: `basename "${key}" is shared by ${sortedPaths.length} notes: ${sortedPaths.join(', ')}`,
+        });
+    }
+    return findings;
+}
+function unresolvedLinkFindings(notes, vaultIndex) {
+    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)
+                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`,
+            });
+        }
+    }
+    return findings;
+}

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

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

package/dist/esm/vault-integrity/index.js

@@ -0,0 +1,3 @@
+export { buildVaultIndex } from "./build-vault-index.js";
+export { checkVaultIntegrity } from "./check-vault-integrity.js";
+export { countNewlines, extractTarget, hasNonMarkdownExtension, lookupKey, maskFencedCode, maskInlineCode, WIKILINK, } from "./wikilink-parse.js";

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

@@ -0,0 +1,7 @@
+export declare const WIKILINK: RegExp;
+export declare function countNewlines(text: string, upTo: number): number;
+export declare function extractTarget(inner: string): string | null;
+export declare function hasNonMarkdownExtension(target: string): boolean;
+export declare function lookupKey(target: string): string;
+export declare function maskFencedCode(body: string): string;
+export declare function maskInlineCode(body: string): string;

package/dist/esm/vault-integrity/wikilink-parse.js

@@ -0,0 +1,75 @@
+export const WIKILINK = /(?<!\\)!?\[\[([^\]\n]+?)\]\]/g;
+const NON_MD_EXTENSIONS = new Set([
+    '.png',
+    '.jpg',
+    '.jpeg',
+    '.gif',
+    '.svg',
+    '.webp',
+    '.pdf',
+    '.mp3',
+    '.mp4',
+    '.mov',
+    '.wav',
+]);
+export function countNewlines(text, upTo) {
+    let count = 0;
+    for (let index = 0; index < upTo && index < text.length; index += 1) {
+        if (text[index] === '\n')
+            count += 1;
+    }
+    return count;
+}
+export function extractTarget(inner) {
+    const beforeAlias = inner.split('|', 1)[0] ?? '';
+    const beforeAnchor = beforeAlias.split('#', 1)[0] ?? '';
+    const trimmed = beforeAnchor.trim();
+    return trimmed === '' ? null : trimmed;
+}
+export function hasNonMarkdownExtension(target) {
+    const dotIndex = target.lastIndexOf('.');
+    if (dotIndex === -1)
+        return false;
+    const ext = target.slice(dotIndex).toLowerCase();
+    if (ext === '.md')
+        return false;
+    return NON_MD_EXTENSIONS.has(ext);
+}
+export function lookupKey(target) {
+    const withoutExtension = target.endsWith('.md') ? target.slice(0, -3) : target;
+    const segments = withoutExtension.split('/');
+    return segments.at(-1) ?? withoutExtension;
+}
+export function maskFencedCode(body) {
+    const lines = body.split('\n');
+    let inFence = false;
+    let fenceChar = '';
+    let fenceLength = 0;
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? '';
+        const fenceMatch = line.match(FENCE_LINE);
+        if (fenceMatch) {
+            const marker = fenceMatch[1] ?? '';
+            const char = marker[0] ?? '';
+            if (!inFence) {
+                inFence = true;
+                fenceChar = char;
+                fenceLength = marker.length;
+                continue;
+            }
+            if (char === fenceChar && marker.length >= fenceLength) {
+                inFence = false;
+                fenceChar = '';
+                fenceLength = 0;
+                continue;
+            }
+        }
+        if (inFence)
+            lines[index] = ' '.repeat(line.length);
+    }
+    return lines.join('\n');
+}
+export function maskInlineCode(body) {
+    return body.replace(/`+[^`\n]+?`+/g, (match) => ' '.repeat(match.length));
+}
+const FENCE_LINE = /^\s{0,3}(`{3,}|~{3,})/;

package/package.json

@@ -1,4 +1,110 @@
 {
   "name": "@williamthorsen/kb",
-  "version": "0.0.0"
-}
+  "version": "0.3.0",
+  "description": "Knowledge-base foundation: discovery, config, frontmatter parsing, records, tags, and vault-integrity checks",
+  "keywords": [
+    "frontmatter",
+    "knowledge-base",
+    "markdown",
+    "notes"
+  ],
+  "homepage": "https://github.com/williamthorsen/codeassembly/tree/main/packages/kb#readme",
+  "bugs": {
+    "url": "https://github.com/williamthorsen/codeassembly/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/williamthorsen/codeassembly.git",
+    "directory": "packages/kb"
+  },
+  "license": "ISC",
+  "author": "William Thorsen <william@thorsen.dev> (https://github.com/williamthorsen)",
+  "type": "module",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    },
+    "./check": {
+      "source": "./src/check/index.ts",
+      "types": "./dist/esm/check/index.d.ts",
+      "import": "./dist/esm/check/index.js"
+    },
+    "./config": {
+      "source": "./src/config/index.ts",
+      "types": "./dist/esm/config/index.d.ts",
+      "import": "./dist/esm/config/index.js"
+    },
+    "./create": {
+      "source": "./src/create/index.ts",
+      "types": "./dist/esm/create/index.d.ts",
+      "import": "./dist/esm/create/index.js"
+    },
+    "./discovery": {
+      "source": "./src/discovery/index.ts",
+      "types": "./dist/esm/discovery/index.d.ts",
+      "import": "./dist/esm/discovery/index.js"
+    },
+    "./filesystem": {
+      "source": "./src/filesystem/index.ts",
+      "types": "./dist/esm/filesystem/index.d.ts",
+      "import": "./dist/esm/filesystem/index.js"
+    },
+    "./frontmatter": {
+      "source": "./src/frontmatter/index.ts",
+      "types": "./dist/esm/frontmatter/index.d.ts",
+      "import": "./dist/esm/frontmatter/index.js"
+    },
+    "./layout": {
+      "source": "./src/layout/index.ts",
+      "types": "./dist/esm/layout/index.d.ts",
+      "import": "./dist/esm/layout/index.js"
+    },
+    "./note-io": {
+      "source": "./src/note-io/index.ts",
+      "types": "./dist/esm/note-io/index.d.ts",
+      "import": "./dist/esm/note-io/index.js"
+    },
+    "./records": {
+      "source": "./src/records/index.ts",
+      "types": "./dist/esm/records/index.d.ts",
+      "import": "./dist/esm/records/index.js"
+    },
+    "./tags": {
+      "source": "./src/tags/index.ts",
+      "types": "./dist/esm/tags/index.d.ts",
+      "import": "./dist/esm/tags/index.js"
+    },
+    "./vault-integrity": {
+      "source": "./src/vault-integrity/index.ts",
+      "types": "./dist/esm/vault-integrity/index.d.ts",
+      "import": "./dist/esm/vault-integrity/index.js"
+    }
+  },
+  "main": "./dist/esm/index.js",
+  "bin": {
+    "kb": "bin/kb.js"
+  },
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "dependencies": {
+    "picomatch": "4.0.5",
+    "yaml": "2.9.0",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@types/picomatch": "4.0.3"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "nmr compile"
+  }
+}