@williamthorsen/kb 0.6.2 → 0.8.0

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

@@ -1,3 +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";
+export { checkVaultIntegrity, } from "./check-vault-integrity.js";
+export { lookupKey, scanWikilinks } from "./wikilink-parse.js";

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

@@ -1,7 +1,50 @@
-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;
-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;
-export declare function maskFencedCode(body: string): string;
-export declare function maskInlineCode(body: string): string;
+/** A wikilink target separated into the store it names, where 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. */
+    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. */
+export interface ScannedWikilink {
+    /** The whole matched link, including any `!` embed prefix. */
+    match: string;
+    /** The text between the brackets, with alias and anchor intact. */
+    inner: string;
+    /** Offset of the match within the body. */
+    offset: number;
+    /** The store the link names, 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
+ * 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.
+ */
+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.
+ *
+ * Call it on the output of {@link extractTarget}, which has already stripped any alias and anchor.
+ */
+export declare function splitStoreQualifier(target: string): QualifiedTarget;

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

@@ -1,4 +1,4 @@
-export const WIKILINK = /(?<!\\)!?\[\[([^\]\n]+?)\]\]/g;
+const WIKILINK = /(?<!\\)!?\[\[([^\]\n]+?)\]\]/g;
 const NON_MD_EXTENSIONS = new Set([
     '.png',
     '.jpg',
@@ -26,7 +26,40 @@ export function extractTarget(inner) {
     const trimmed = beforeAnchor.trim();
     return trimmed === '' ? null : trimmed;
 }
-export function hasNonMarkdownExtension(target) {
+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* scanWikilinks(body) {
+    const masked = maskInlineCode(maskFencedCode(body));
+    if (masked.length !== body.length) {
+        throw new Error('code masking changed body length; wikilink offsets would be invalid');
+    }
+    for (const match of masked.matchAll(WIKILINK)) {
+        const inner = match[1];
+        if (inner === undefined)
+            continue;
+        const extracted = extractTarget(inner);
+        if (extracted === null)
+            continue;
+        if (hasNonMarkdownExtension(extracted))
+            continue;
+        const { store, target } = splitStoreQualifier(extracted);
+        yield { match: match[0], inner, offset: match.index, ...(store !== undefined && { store }), target };
+    }
+}
+export function splitStoreQualifier(target) {
+    const colonIndex = target.indexOf(':');
+    if (colonIndex <= 0)
+        return { target };
+    const store = target.slice(0, colonIndex);
+    const remainder = target.slice(colonIndex + 1);
+    if (remainder === '' || /[\s/]/.test(store))
+        return { target };
+    return { store, target: remainder };
+}
+function hasNonMarkdownExtension(target) {
     const dotIndex = target.lastIndexOf('.');
     if (dotIndex === -1)
         return false;
@@ -35,12 +68,7 @@ export function hasNonMarkdownExtension(target) {
         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) {
+function maskFencedCode(body) {
     const lines = body.split('\n');
     let inFence = false;
     let fenceChar = '';
@@ -69,7 +97,7 @@ export function maskFencedCode(body) {
     }
     return lines.join('\n');
 }
-export function maskInlineCode(body) {
+function maskInlineCode(body) {
     return body.replace(/`+[^`\n]+?`+/g, (match) => ' '.repeat(match.length));
 }
 const FENCE_LINE = /^\s{0,3}(`{3,}|~{3,})/;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/kb",
-  "version": "0.6.2",
+  "version": "0.8.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",
+    "eslint": "10.10.0",
+    "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');
-}