@anokye-labs/kbexplorer-engine 0.1.0

package/dist/sources.js

@@ -0,0 +1,357 @@
+import { globToRegex } from './chunk-MW4BLXVK.js';
+export { buildManifest } from './chunk-MW4BLXVK.js';
+export { GitHubApiSource } from './chunk-NOGBKE7C.js';
+import { collectNodemapData } from './chunk-XVI6CBSX.js';
+export { GITHUB_ENDPOINT_PATTERNS, GitHubApiError, NotModifiedError, RateLimitError, fetchCommits, fetchFile, fetchFiles, fetchIssues, fetchPullRequests, fetchReleases, fetchTree } from './chunk-FJ4GTN4U.js';
+import './chunk-JNQVSNLC.js';
+import { readFile, readdir, stat } from 'fs/promises';
+import { resolve, basename, join, isAbsolute, relative, sep } from 'path';
+import yaml from 'yaml';
+
+// src/sources/manifest-source.ts
+var ManifestSource = class {
+  id = "manifest";
+  name = "Repo Manifest";
+  /** A manifest is a frozen snapshot — read is the only possible affordance. */
+  possibleAffordances = ["read"];
+  manifest;
+  config;
+  constructor(manifest, config) {
+    this.manifest = manifest;
+    this.config = config;
+  }
+  async getRepoData() {
+    const manifest = this.manifest;
+    const listFiles = async (pattern) => {
+      const regex = globToRegex(pattern);
+      return Object.keys(manifest.nodemapFiles ?? {}).filter((p) => regex.test(p));
+    };
+    const data = {
+      repo: this.config.source.repo,
+      tree: manifest.tree,
+      authoredContent: manifest.authoredContent,
+      nodemapRaw: manifest.nodemapRaw ?? null,
+      listFiles,
+      issues: manifest.issues,
+      pullRequests: manifest.pullRequests,
+      commits: manifest.commits,
+      branches: manifest.branches ?? [],
+      repoMetadata: manifest.repoMetadata ?? null,
+      releases: manifest.releases ?? [],
+      structuralFiles: manifest.structuralFiles ?? {},
+      structuredNodeMapRaw: manifest.structuredNodeMapRaw ?? null,
+      contentModel: manifest.contentModel ?? null,
+      readme: manifest.readme,
+      themeFileRaw: manifest.themeFileRaw ?? null
+    };
+    if (manifest.nodemapFiles !== void 0) data.nodemapFiles = manifest.nodemapFiles;
+    if (manifest.nodemapDirs !== void 0) {
+      data.nodemapDirs = manifest.nodemapDirs;
+    }
+    return data;
+  }
+  /**
+   * Read-only resource surface. Files (tree blobs/trees) and issues are
+   * retrievable; every resource is afforded `['read']` and links only to
+   * itself. No write/stage, no staging area.
+   */
+  async retrieve(query) {
+    const kind = query.kind;
+    const out = [];
+    if (!kind || kind === "file" || kind === "tree") {
+      for (const item of this.manifest.tree) {
+        if (kind === "file" && item.type !== "blob") continue;
+        if (kind === "tree" && item.type !== "tree") continue;
+        out.push(this.fileResource(item));
+      }
+    }
+    if (!kind || kind === "issue") {
+      for (const issue of this.manifest.issues) {
+        out.push(this.issueResource(issue.number, issue.title));
+      }
+    }
+    return out;
+  }
+  async get(href) {
+    const all = await this.retrieve({});
+    return all.find((r) => r.href === href);
+  }
+  fileResource(item) {
+    return {
+      href: `git://${this.config.source.repo}/${item.path}`,
+      kind: item.type === "tree" ? "tree" : "file",
+      affordances: ["read"],
+      links: [{ rel: "self", href: `git://${this.config.source.repo}/${item.path}` }],
+      body: { path: item.path }
+    };
+  }
+  issueResource(number, title) {
+    return {
+      href: `github://${this.config.source.repo}/issues/${number}`,
+      kind: "issue",
+      affordances: ["read"],
+      links: [{ rel: "self", href: `github://${this.config.source.repo}/issues/${number}` }],
+      body: { number, title }
+    };
+  }
+};
+var ALWAYS_IGNORE = /* @__PURE__ */ new Set([".git", "node_modules", "dist"]);
+var MAX_STRUCTURAL_FILE_SIZE = 256 * 1024;
+function isStructuralPath(path) {
+  return path.startsWith(".github/") || /(^|\/)CODEOWNERS$/.test(path);
+}
+var FileSystemSource = class {
+  id = "filesystem";
+  name = "File System";
+  /** A local snapshot read — read is the only possible affordance. */
+  possibleAffordances = ["read"];
+  rootDir;
+  repo;
+  contentPath;
+  contentModelPath;
+  ignore;
+  includeFileTree;
+  cache = null;
+  constructor(rootDir, options = {}) {
+    this.rootDir = resolve(rootDir);
+    this.repo = options.repo ?? basename(this.rootDir);
+    this.contentPath = options.contentPath ?? "content";
+    this.contentModelPath = options.contentModelPath ?? "content-model";
+    this.ignore = /* @__PURE__ */ new Set([...ALWAYS_IGNORE, ...options.ignore ?? []]);
+    this.includeFileTree = options.includeFileTree ?? true;
+  }
+  async getRepoData() {
+    if (!this.cache) this.cache = this.readRepoData();
+    return this.cache;
+  }
+  async readRepoData() {
+    const files = await this.walk();
+    const paths = files.map((f) => f.path);
+    const tree = this.includeFileTree ? files.map((f) => ({ path: f.path, type: f.type })) : [];
+    const authoredContent = {};
+    const structuralFiles = {};
+    const rootScan = this.contentPath === "" || this.contentPath === ".";
+    const contentPrefix = rootScan ? "" : `${this.contentPath}/`;
+    const contentModelPrefix = `${this.contentModelPath}/`;
+    const contentModelFiles = {};
+    let readme = null;
+    let structuredNodeMapRaw = null;
+    for (const file of files) {
+      if (file.type !== "blob") continue;
+      const isAuthoredMd = file.path.endsWith(".md") && file.path !== "README.md" && (rootScan ? !file.path.includes("/") : file.path.startsWith(contentPrefix));
+      if (isAuthoredMd) {
+        authoredContent[file.path] = await this.read(file.path);
+        continue;
+      }
+      if (isStructuralPath(file.path) && (file.size ?? 0) <= MAX_STRUCTURAL_FILE_SIZE) {
+        const content = await this.read(file.path);
+        if (content.length <= MAX_STRUCTURAL_FILE_SIZE) structuralFiles[file.path] = content;
+        continue;
+      }
+      if (file.path.startsWith(contentModelPrefix)) {
+        const relativePath = file.path.slice(contentModelPrefix.length);
+        contentModelFiles[relativePath] = await this.read(file.path);
+        continue;
+      }
+      if (file.path === "README.md") {
+        readme = await this.read(file.path);
+        continue;
+      }
+      if (structuredNodeMapRaw === null && (file.path === "structured-node-map.yaml" || file.path === "structured-node-map.yml")) {
+        structuredNodeMapRaw = await this.read(file.path);
+      }
+    }
+    const contentModel = Object.keys(contentModelFiles).length > 0 ? { root: this.contentModelPath, files: contentModelFiles } : null;
+    const listFiles = async (pattern) => {
+      const regex = globToRegex(pattern);
+      return paths.filter((p) => regex.test(p));
+    };
+    const nodemapRaw = await this.readNodemapRaw();
+    let nodemapFiles;
+    let nodemapDirs;
+    if (nodemapRaw !== null) {
+      const collected = await collectNodemapData(
+        nodemapRaw,
+        files,
+        (path) => this.readSafe(path),
+        (dir) => this.listNodemapDir(dir)
+      );
+      nodemapFiles = collected.nodemapFiles;
+      nodemapDirs = collected.nodemapDirs;
+    }
+    const themeFileRaw = await this.resolveThemeFileRaw();
+    return {
+      repo: this.repo,
+      tree,
+      authoredContent,
+      nodemapRaw,
+      ...nodemapFiles !== void 0 ? { nodemapFiles } : {},
+      ...nodemapDirs !== void 0 ? { nodemapDirs } : {},
+      listFiles,
+      issues: [],
+      pullRequests: [],
+      commits: [],
+      // Legitimately empty/null in local mode — there is no live GitHub to
+      // fetch branches/repo metadata from (anokye-labs/kbexplorer-engine#23).
+      branches: [],
+      repoMetadata: null,
+      releases: [],
+      structuralFiles,
+      structuredNodeMapRaw,
+      contentModel,
+      readme,
+      themeFileRaw
+    };
+  }
+  /** Read one repo-relative file as UTF-8. */
+  read(repoRelative) {
+    return readFile(join(this.rootDir, repoRelative), "utf8");
+  }
+  /** Read one repo-relative file as UTF-8, returning `null` when missing/unreadable. */
+  async readSafe(repoRelative) {
+    try {
+      return await readFile(join(this.rootDir, repoRelative), "utf8");
+    } catch {
+      return null;
+    }
+  }
+  /** Read `nodemap.yaml`/`nodemap.yml` from the repo root, or `null` if neither exists. */
+  async readNodemapRaw() {
+    for (const name of ["nodemap.yaml", "nodemap.yml"]) {
+      const content = await this.readSafe(name);
+      if (content !== null) return content;
+    }
+    return null;
+  }
+  /** Read `${contentPath}/config.yaml`(`.yml`), falling back to a root-level `config.yaml`. */
+  async readConfigRaw() {
+    const rootScan = this.contentPath === "" || this.contentPath === ".";
+    const contentPrefix = rootScan ? "" : `${this.contentPath}/`;
+    const candidates = [`${contentPrefix}config.yaml`, `${contentPrefix}config.yml`, "config.yaml"];
+    for (const candidate of candidates) {
+      const content = await this.readSafe(candidate);
+      if (content !== null) return content;
+    }
+    return null;
+  }
+  /**
+   * Read the raw contents of the dedicated theme file referenced by
+   * `config.theme.themesFile`, mirroring the old generator's `readThemeFile`.
+   * `null` when no `themesFile` is configured, the config can't be parsed, the
+   * path escapes the repo root, or the file is missing — a safe no-op.
+   */
+  async resolveThemeFileRaw() {
+    const configRaw = await this.readConfigRaw();
+    if (!configRaw) return null;
+    let parsed;
+    try {
+      parsed = yaml.parse(configRaw);
+    } catch {
+      return null;
+    }
+    const themesFile = parsed?.theme?.themesFile;
+    if (!themesFile || typeof themesFile !== "string") return null;
+    if (isAbsolute(themesFile)) return null;
+    const abs = resolve(this.rootDir, themesFile);
+    const rel = relative(this.rootDir, abs);
+    if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) return null;
+    try {
+      return await readFile(abs, "utf8");
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * One-level directory listing (with file sizes) for a nodemap `directory:`
+   * entry — distinct from `walk()`, which is recursive and does not stat
+   * files. Mirrors the old generator's `listDir`.
+   */
+  async listNodemapDir(dirPath) {
+    const abs = join(this.rootDir, dirPath);
+    let entries;
+    try {
+      entries = await readdir(abs, { withFileTypes: true });
+    } catch {
+      return [];
+    }
+    const out = [];
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) continue;
+      const entryPath = dirPath ? `${dirPath}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        out.push({ path: entryPath, type: "tree" });
+      } else if (entry.isFile()) {
+        try {
+          const st = await stat(join(abs, entry.name));
+          out.push({ path: entryPath, type: "blob", size: st.size });
+        } catch {
+          out.push({ path: entryPath, type: "blob" });
+        }
+      }
+    }
+    return out;
+  }
+  /** Convert an absolute path under the root into a POSIX repo-relative path. */
+  toRepoRelative(absolutePath) {
+    return absolutePath.slice(this.rootDir.length + 1).split(sep).join("/");
+  }
+  /**
+   * Recursively enumerate the root directory into blob/tree entries with
+   * POSIX-separated, repo-relative paths (sorted for determinism). Skips
+   * dotfiles/dot-directories (except `.github`, which the StructuralProvider
+   * reads) in addition to the always-ignored directories — mirrors the old
+   * generator's `walkFileSystem` (anokye-labs/kbexplorer-engine#23).
+   */
+  async walk() {
+    const out = [];
+    const stack = [this.rootDir];
+    while (stack.length > 0) {
+      const dir = stack.pop();
+      const entries = await readdir(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.name.startsWith(".") && entry.name !== ".github") continue;
+        if (entry.isDirectory() && this.ignore.has(entry.name)) continue;
+        const absolutePath = join(dir, entry.name);
+        const repoRelative = this.toRepoRelative(absolutePath);
+        if (entry.isDirectory()) {
+          out.push({ path: repoRelative, type: "tree" });
+          stack.push(absolutePath);
+        } else if (entry.isFile()) {
+          out.push({ path: repoRelative, type: "blob" });
+        }
+      }
+    }
+    out.sort((a, b) => a.path.localeCompare(b.path));
+    return out;
+  }
+  // ── Read-only resource surface (mirrors ManifestSource) ───────────────────
+  async retrieve(query) {
+    const kind = query.kind;
+    const out = [];
+    if (!kind || kind === "file" || kind === "tree") {
+      const { tree } = await this.getRepoData();
+      for (const item of tree) {
+        if (kind === "file" && item.type !== "blob") continue;
+        if (kind === "tree" && item.type !== "tree") continue;
+        out.push(this.fileResource(item));
+      }
+    }
+    return out;
+  }
+  async get(href) {
+    const all = await this.retrieve({});
+    return all.find((r) => r.href === href);
+  }
+  fileResource(item) {
+    const href = `file://${this.repo}/${item.path}`;
+    return {
+      href,
+      kind: item.type === "tree" ? "tree" : "file",
+      affordances: ["read"],
+      links: [{ rel: "self", href }],
+      body: { path: item.path }
+    };
+  }
+};
+
+export { FileSystemSource, ManifestSource };

package/dist/sqlite-graph-store-NH2NHL2B.js

@@ -0,0 +1,2 @@
+export { SQLiteGraphStore } from './chunk-IWEURXYH.js';
+import './chunk-HXAS3BSD.js';

package/dist/sqlite-runtime-CysPjjzX.d.cts

@@ -0,0 +1,96 @@
+import { KBNode, KBConfig, KBEdge } from '@anokye-labs/kbexplorer-core';
+import { SqlJsStatic, Database } from 'sql.js';
+
+/**
+ * Source-agnostic input the transform stage needs beyond the provider nodes.
+ * The README arrives as raw markdown (or null when the source has none); every
+ * other input is derived from the node list itself.
+ */
+interface TransformContext {
+    /** Raw README markdown for the source, or null when absent. */
+    readme: string | null;
+}
+/**
+ * A single ordered post-provider transform. `apply` receives the current node
+ * list and returns the next one — it may mutate nodes in place (e.g. add
+ * connections), append nodes, or replace nodes (e.g. split). Transforms must be
+ * pure with respect to ordering: they recompute any subsets they need.
+ */
+interface GraphTransform {
+    readonly name: string;
+    apply(nodes: KBNode[], ctx: TransformContext): KBNode[];
+}
+/**
+ * Synthesize the README node and cross-reference it to issues + directories it
+ * mentions (by issue ref, fuzzy title match, directory name, and inline links).
+ * No-op when the source has no README.
+ */
+declare const readmeTransform: GraphTransform;
+/**
+ * Auto-link each issue to directories whose name it references in its body.
+ * Runs before {@link issueSplitTransform} so links stay on the original nodes.
+ */
+declare const issueDirectoryLinkTransform: GraphTransform;
+/**
+ * Split issues with 2+ headings into a parent + section nodes, replacing the
+ * original issue node with its expansion.
+ */
+declare const issueSplitTransform: GraphTransform;
+/**
+ * Default ordered post-provider transform stage. Order is significant: README
+ * synthesis, then issue→directory linking (before splitting), then issue
+ * splitting. Matches the original inline loader sequence exactly.
+ */
+declare const DEFAULT_TRANSFORMS: readonly GraphTransform[];
+/** Run an ordered list of transforms over the node list. */
+declare function applyTransforms(nodes: KBNode[], ctx: TransformContext, transforms?: readonly GraphTransform[]): KBNode[];
+
+/** Result produced by a single provider run */
+interface ProviderResult {
+    nodes: KBNode[];
+    edges: KBEdge[];
+}
+/** A graph provider produces nodes and edges from a data source */
+interface GraphProvider {
+    /** Unique provider identifier */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Provider IDs this provider depends on (for ordering) */
+    dependencies?: string[];
+    /**
+     * Resolve content from this provider.
+     * @param config - the KB config
+     * @param existingNodes - nodes from previously-run providers (for cross-referencing)
+     */
+    resolve(config: KBConfig, existingNodes: KBNode[]): Promise<ProviderResult>;
+}
+/** Provider registry — ordered collection of providers */
+declare class ProviderRegistry {
+    private providers;
+    register(provider: GraphProvider): void;
+    /** Get providers in dependency-safe execution order */
+    getExecutionOrder(): GraphProvider[];
+    get(id: string): GraphProvider | undefined;
+}
+
+interface SqliteByteStore {
+    load(): Promise<Uint8Array | undefined>;
+    save(bytes: Uint8Array): Promise<void>;
+}
+declare function loadSqlJs(locateFile?: (file: string) => string): Promise<SqlJsStatic>;
+declare function openPersistedDatabase(byteStore?: SqliteByteStore, locateFile?: (file: string) => string): Promise<{
+    db: Database;
+    persist: () => Promise<void>;
+}>;
+declare class MemorySqliteByteStore implements SqliteByteStore {
+    private bytes?;
+    load(): Promise<Uint8Array | undefined>;
+    save(bytes: Uint8Array): Promise<void>;
+}
+declare class IndexedDbSqliteByteStore implements SqliteByteStore {
+    load(): Promise<Uint8Array | undefined>;
+    save(bytes: Uint8Array): Promise<void>;
+}
+
+export { DEFAULT_TRANSFORMS as D, type GraphProvider as G, IndexedDbSqliteByteStore as I, MemorySqliteByteStore as M, type ProviderResult as P, type SqliteByteStore as S, type TransformContext as T, ProviderRegistry as a, type GraphTransform as b, applyTransforms as c, issueSplitTransform as d, issueDirectoryLinkTransform as i, loadSqlJs as l, openPersistedDatabase as o, readmeTransform as r };

package/dist/sqlite-runtime-CysPjjzX.d.ts

@@ -0,0 +1,96 @@
+import { KBNode, KBConfig, KBEdge } from '@anokye-labs/kbexplorer-core';
+import { SqlJsStatic, Database } from 'sql.js';
+
+/**
+ * Source-agnostic input the transform stage needs beyond the provider nodes.
+ * The README arrives as raw markdown (or null when the source has none); every
+ * other input is derived from the node list itself.
+ */
+interface TransformContext {
+    /** Raw README markdown for the source, or null when absent. */
+    readme: string | null;
+}
+/**
+ * A single ordered post-provider transform. `apply` receives the current node
+ * list and returns the next one — it may mutate nodes in place (e.g. add
+ * connections), append nodes, or replace nodes (e.g. split). Transforms must be
+ * pure with respect to ordering: they recompute any subsets they need.
+ */
+interface GraphTransform {
+    readonly name: string;
+    apply(nodes: KBNode[], ctx: TransformContext): KBNode[];
+}
+/**
+ * Synthesize the README node and cross-reference it to issues + directories it
+ * mentions (by issue ref, fuzzy title match, directory name, and inline links).
+ * No-op when the source has no README.
+ */
+declare const readmeTransform: GraphTransform;
+/**
+ * Auto-link each issue to directories whose name it references in its body.
+ * Runs before {@link issueSplitTransform} so links stay on the original nodes.
+ */
+declare const issueDirectoryLinkTransform: GraphTransform;
+/**
+ * Split issues with 2+ headings into a parent + section nodes, replacing the
+ * original issue node with its expansion.
+ */
+declare const issueSplitTransform: GraphTransform;
+/**
+ * Default ordered post-provider transform stage. Order is significant: README
+ * synthesis, then issue→directory linking (before splitting), then issue
+ * splitting. Matches the original inline loader sequence exactly.
+ */
+declare const DEFAULT_TRANSFORMS: readonly GraphTransform[];
+/** Run an ordered list of transforms over the node list. */
+declare function applyTransforms(nodes: KBNode[], ctx: TransformContext, transforms?: readonly GraphTransform[]): KBNode[];
+
+/** Result produced by a single provider run */
+interface ProviderResult {
+    nodes: KBNode[];
+    edges: KBEdge[];
+}
+/** A graph provider produces nodes and edges from a data source */
+interface GraphProvider {
+    /** Unique provider identifier */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Provider IDs this provider depends on (for ordering) */
+    dependencies?: string[];
+    /**
+     * Resolve content from this provider.
+     * @param config - the KB config
+     * @param existingNodes - nodes from previously-run providers (for cross-referencing)
+     */
+    resolve(config: KBConfig, existingNodes: KBNode[]): Promise<ProviderResult>;
+}
+/** Provider registry — ordered collection of providers */
+declare class ProviderRegistry {
+    private providers;
+    register(provider: GraphProvider): void;
+    /** Get providers in dependency-safe execution order */
+    getExecutionOrder(): GraphProvider[];
+    get(id: string): GraphProvider | undefined;
+}
+
+interface SqliteByteStore {
+    load(): Promise<Uint8Array | undefined>;
+    save(bytes: Uint8Array): Promise<void>;
+}
+declare function loadSqlJs(locateFile?: (file: string) => string): Promise<SqlJsStatic>;
+declare function openPersistedDatabase(byteStore?: SqliteByteStore, locateFile?: (file: string) => string): Promise<{
+    db: Database;
+    persist: () => Promise<void>;
+}>;
+declare class MemorySqliteByteStore implements SqliteByteStore {
+    private bytes?;
+    load(): Promise<Uint8Array | undefined>;
+    save(bytes: Uint8Array): Promise<void>;
+}
+declare class IndexedDbSqliteByteStore implements SqliteByteStore {
+    load(): Promise<Uint8Array | undefined>;
+    save(bytes: Uint8Array): Promise<void>;
+}
+
+export { DEFAULT_TRANSFORMS as D, type GraphProvider as G, IndexedDbSqliteByteStore as I, MemorySqliteByteStore as M, type ProviderResult as P, type SqliteByteStore as S, type TransformContext as T, ProviderRegistry as a, type GraphTransform as b, applyTransforms as c, issueSplitTransform as d, issueDirectoryLinkTransform as i, loadSqlJs as l, openPersistedDatabase as o, readmeTransform as r };

package/dist/store-orchestrator-337XWIXO.js

@@ -0,0 +1,5 @@
+export { orchestrateWithProviderResultStore } from './chunk-YTMIERYM.js';
+import './chunk-DJ2DBEEK.js';
+import './chunk-FJ4GTN4U.js';
+import './chunk-JNQVSNLC.js';
+import './chunk-HXAS3BSD.js';