@anokye-labs/kbexplorer-engine 0.1.0

package/dist/repo-data-0JvFdLGv.d.ts

@@ -0,0 +1,461 @@
+import { KBNode, Source } from '@anokye-labs/kbexplorer-core';
+
+/**
+ * Minimal GitHub API shapes needed by `parser.ts`'s `issueToNode` /
+ * `treeToNodes`. These are NOT the full GitHub REST client types — just the
+ * fields those two functions actually read. The full client (`fetchFile`,
+ * `fetchTree`, `fetchFiles`, `fetchIssues`) lives in kbexplorer-template's
+ * `src/api/github.ts`, which has not moved to this package yet (slice 4).
+ */
+/** A GitHub issue or pull request, as returned by the Issues API. */
+interface GHIssue {
+    number: number;
+    title: string;
+    body: string | null;
+    state: string;
+    html_url: string;
+    created_at: string;
+    updated_at: string;
+    labels: Array<{
+        name: string;
+        color?: string;
+    }>;
+    assignees?: Array<{
+        login: string;
+    }> | null;
+    /** The GitHub user who opened the issue/PR (author). Added in slice 2 for PersonProvider/WorkProvider's author-attribution logic — absent from slice 1's parser-only subset. */
+    user?: {
+        login: string;
+    };
+    /** Present (and truthy) only when the issue is actually a pull request. */
+    pull_request?: unknown;
+}
+/** A single entry in a GitHub repo's git tree, as returned by the Git Trees API. */
+interface GHTreeItem {
+    path: string;
+    type: 'blob' | 'tree';
+    size?: number;
+    /** Git file mode (e.g. `'100644'`, `'040000'`). Not read by `treeToNodes` itself. */
+    mode?: string;
+    /** Blob/tree SHA. Not read by `treeToNodes` itself. */
+    sha?: string;
+    /** API URL for this tree entry. Not read by `treeToNodes` itself. */
+    url?: string;
+}
+/**
+ * A GitHub release as returned by the releases API.
+ * Drafts are excluded; prerelease flag is preserved.
+ */
+interface GHRelease {
+    tag_name: string;
+    name: string;
+    body: string;
+    html_url: string;
+    published_at: string;
+    prerelease: boolean;
+}
+/**
+ * A single commit as returned by the Commits API. Added in slice 3 for
+ * `sources/repo-data.ts`'s `RepoData.commits` field (consumed by `WorkProvider`).
+ */
+interface GHCommit {
+    sha: string;
+    commit: {
+        message: string;
+        author: {
+            name: string;
+            date: string;
+        };
+    };
+    html_url: string;
+    files?: Array<{
+        filename: string;
+        status: string;
+    }>;
+}
+
+interface EngineEnv {
+    [key: string]: string | boolean | undefined;
+}
+
+/**
+ * Content-model ingestion types (F2 — issue #149).
+ *
+ * The content model is **schema-driven**: identity/authority comes from
+ * `teamops.yaml`, storage layout from `schema/conventions.yaml`, relationships
+ * from `schema/edges.yaml`, lifecycle bands from `schema/lifecycle.yaml`, and
+ * URN bases from `index/context.jsonld`. The engine reads these files rather
+ * than hardcoding any org's structure, so a second org adopts the platform by
+ * changing config — not engine code.
+ *
+ * Hard rules encoded here:
+ * - A node's **kind comes from its `@type`**, never from the file path.
+ * - **URN bases come from the JSON-LD context only** — never hardcoded.
+ */
+/** Lifecycle band from `schema/lifecycle.yaml` (open — custom bands allowed). */
+type LifecycleBand = 'durable' | 'per-cycle' | 'per-event' | (string & {});
+/** Foreign-key resolution flavor from `schema/edges.yaml`. */
+type FkFlavor = 'scalar' | 'array' | 'composite' | 'alias';
+/** One org declared in `teamops.yaml`. */
+interface OrgDef {
+    id: string;
+    name?: string | undefined;
+    /** Whether this is the home/default org (its entities are stored flat). */
+    default?: boolean;
+}
+/** `teamops.yaml` — maps identity to an authority + a default (home) org. */
+interface TeamOps {
+    /** Authority host, e.g. `xbox.com` — the URN authority segment. */
+    authority: string;
+    /** Default/home org id; entities of org-scoped kinds default to it when flat. */
+    defaultOrg: string;
+    /** All known orgs. */
+    orgs: OrgDef[];
+}
+/** Storage + mapping convention for a single kind (from `schema/conventions.yaml`). */
+interface KindConvention {
+    /** Kind id (matches the entity's `@type`). */
+    kind: string;
+    /** Storage root relative to the content-model root (e.g. `squads`). */
+    path: string;
+    /**
+     * Whether this kind is org-scoped. Org-scoped kinds carry an `/{org}` segment
+     * in their URN and store the **default org flat** / **non-default orgs nested**
+     * in a per-org subdirectory. Authority-scoped kinds omit the org segment.
+     */
+    orgScoped: boolean;
+    /** Field carrying this kind's alias handle (the target of an `alias` FK). */
+    aliasField?: string | undefined;
+    /**
+     * Fields copied verbatim into `data`. When omitted, **all** fields pass
+     * through (the default), which keeps the field→data mapping reversible.
+     */
+    passthrough?: string[] | undefined;
+    /** Sibling-file extension whose content is merged as the node body (e.g. `.md`). */
+    companionExt?: string | undefined;
+}
+/** `schema/conventions.yaml` — per-kind storage + mapping. */
+interface Conventions {
+    /** Field carrying the kind discriminator. Default `@type`; never path-derived. */
+    typeField: string;
+    /** Field carrying the entity id. Default `id`. */
+    idField: string;
+    /** kind → convention. */
+    kinds: Record<string, KindConvention>;
+}
+/** One leg of a composite FK (`<a>:<b>` → two edges). */
+interface CompositeLeg {
+    /** Target kind for this leg. */
+    to: string;
+    /** Relation taxonomy label for this leg. */
+    relation: string;
+}
+/** A foreign-key edge rule from `schema/edges.yaml`. */
+interface EdgeRule {
+    id: string;
+    /** Source kind. */
+    from: string;
+    /** Field on the source entity carrying the foreign key. */
+    field: string;
+    /** Target kind (omitted for `composite`, which uses `composite[]`). */
+    to?: string;
+    fk: FkFlavor;
+    /** Relation taxonomy label applied to resolved edges. */
+    relation: string;
+    /** Legs for a `composite` FK, in the order the `<a>:<b>` parts appear. */
+    composite?: CompositeLeg[];
+    description?: string;
+}
+/**
+ * A derived edge rule — computed from existing edges, not stored on entities.
+ * `shared-target`: sources that point at the **same** target of the referenced
+ * FK rule (`via`) are linked to each other. Deduped so a pair is stored once.
+ */
+interface DerivedRule {
+    id: string;
+    type: 'shared-target';
+    /** Id of the {@link EdgeRule} whose targets define the grouping. */
+    via: string;
+    relation: string;
+    description?: string;
+}
+/** `schema/edges.yaml` — FK edges + derived + deprecated. */
+interface EdgesSpec {
+    edges: EdgeRule[];
+    derived: DerivedRule[];
+    /** Edge rules whose resolved edges are tagged `deprecated`. */
+    deprecated: EdgeRule[];
+}
+/** `schema/lifecycle.yaml` — band → kinds. */
+interface Lifecycle {
+    bands: Record<string, string[]>;
+}
+/** Parsed `index/context.jsonld` — CURIE prefix → URN base. */
+interface JsonLdContext {
+    /** The `@base` keyword, when present. */
+    base?: string | undefined;
+    /** prefix → URN base (full, e.g. `kg://xbox.com/squads/`). */
+    prefixes: Record<string, string>;
+}
+/**
+ * Cross-repo vocabulary / synonym layer (F-cross-repo — issue #153).
+ *
+ * Maps a per-repo **alias term** (a word one repo uses, e.g. `cell` / `crew`)
+ * to a **canonical term** — a kind / CURIE prefix already declared in the
+ * JSON-LD {@link JsonLdContext} (e.g. `squad`). It lets the graph unify concepts
+ * across repos that use different words while each repo keeps its native label.
+ *
+ * The map is **data-driven** (declared in `index/vocabulary.jsonld` and/or
+ * supplied as a shared overlay independent of any single repo's context) and is
+ * a **safe no-op** when empty — output is byte-identical to a build without it.
+ */
+interface Vocabulary {
+    /**
+     * alias term → canonical term. A self-mapping (alias === canonical) is never
+     * stored, so an alias is always a *rename* to some other canonical kind.
+     */
+    aliases: Record<string, string>;
+}
+/**
+ * An overlay vocabulary supplied independently of a repo's own files — the
+ * cross-repo synonym layer. Either raw `vocabulary.jsonld` content (a string),
+ * an already-parsed {@link Vocabulary}, or nothing.
+ */
+type VocabularyOverlay = string | Vocabulary | null | undefined;
+/** The fully-parsed content-model schema. */
+interface ContentModelSchema {
+    teamops: TeamOps;
+    conventions: Conventions;
+    edges: EdgesSpec;
+    lifecycle: Lifecycle;
+    context: JsonLdContext;
+    /** Cross-repo synonym layer; `aliases` is empty when none is declared. */
+    vocabulary: Vocabulary;
+}
+/** Severity of a build/schema diagnostic. */
+type DiagnosticLevel = 'info' | 'warn' | 'error';
+/** A diagnostic raised while reading the schema or building the graph. */
+interface Diagnostic {
+    level: DiagnosticLevel;
+    /** Stable machine code, e.g. `unresolved-ref`, `unknown-prefix`. */
+    code: string;
+    message: string;
+    /** Related id / path / URN for context. */
+    ref?: string;
+}
+/**
+ * A flat content-model source: schema files + entity files keyed by path
+ * relative to {@link ContentModelSource.root}. This abstraction lets the same
+ * builder run against build-time fixtures, the local manifest, and live fetch.
+ */
+interface ContentModelSource {
+    /** Root dir name within the repo (e.g. `content-model`). */
+    root: string;
+    /** path (relative to `root`) → raw file content. */
+    files: Record<string, string>;
+}
+
+/**
+ * Node-type registry — the open, data-driven core of the node-type engine.
+ *
+ * Each node type declares how it participates in the graph: its layer, default
+ * cluster, the relations it tends to emit, and which viewer renders it. The
+ * registry is consulted by {@link getNodeLayer} (via {@link resolveNodeLayer})
+ * and by cluster/legend logic, so adding a brand-new node type requires only a
+ * `registerType` call — no edits to the core discriminated unions or render
+ * switches.
+ *
+ * Implementation note: this module imports `KBNode` from
+ * `@anokye-labs/kbexplorer-core` **type-only**, so there is no runtime import
+ * cycle even though the module augmentation below adds a `layer` field to it.
+ */
+
+/**
+ * Graph layer taxonomy. Not part of `@anokye-labs/kbexplorer-core` (it's an
+ * engine-internal concern, not a core domain type) — defined here since this
+ * is the module that resolves it. content-model/register.ts (slice 2) will
+ * import it from here too once it migrates.
+ */
+type NodeLayer = 'file' | 'content' | 'work';
+/**
+ * Module augmentation: `@anokye-labs/kbexplorer-core`'s `KBNode` does not
+ * declare a `layer` field, but `buildGraph()` (`src/graph.ts`, via
+ * {@link resolveNodeLayer}) stamps one onto every node at build time, and
+ * later-slice consumers (content-model/register.ts) read it back. Augmenting
+ * the core type in place — rather than introducing a parallel `EngineNode`
+ * type that every call site would need to swap to — keeps `KBNode` the single
+ * node shape used throughout this package and its consumers. Flagged upstream
+ * (anokye-labs/kbexplorer-template#472) in case `@anokye-labs/kbexplorer-core`
+ * should grow this field natively in a future version.
+ */
+declare module '@anokye-labs/kbexplorer-core' {
+    interface KBNode {
+        /** Graph layer this node belongs to, stamped by `buildGraph()`. */
+        layer?: NodeLayer;
+    }
+}
+/** A registered node type and how it participates in the graph. */
+interface NodeTypeDefinition {
+    /** Type id — matches a node's `entityType` or, for built-ins, its `source.type`. */
+    id: string;
+    /** Human-readable label (defaults to a humanized id). */
+    label?: string;
+    /** Graph layer this type belongs to. Defaults to `'file'` when unset. */
+    layer?: NodeLayer;
+    /** Default cluster id for nodes of this type (used when a node omits its cluster). */
+    cluster?: string;
+    /** Relation kinds this type commonly emits (informational; surfaced to the legend). */
+    relations?: string[];
+    /**
+     * Viewer key used to resolve a renderer from the viewer registry. Defaults to
+     * the type `id`. The viewer registry falls back to the generic viewer when no
+     * component is registered for the key.
+     */
+    viewer?: string;
+    /** Short description of the type (documentation aid). */
+    description?: string;
+    /**
+     * Optional discovery hook — given raw upstream records, decide which become
+     * nodes of this type. Reserved for content-model ingestion (F2/F3); the
+     * foundation only stores it.
+     */
+    discover?: (records: unknown[]) => unknown[];
+    /**
+     * Optional mapping hook — turn a single upstream record into a partial node.
+     * Reserved for ingestion (F2/F3); the foundation only stores it.
+     */
+    map?: (record: unknown) => Partial<KBNode>;
+}
+/** Register (or replace) a node type. */
+declare function registerType(def: NodeTypeDefinition): void;
+/** Resolve a node type by id. Returns `undefined` for unknown ids. */
+declare function resolveType(id: string | undefined): NodeTypeDefinition | undefined;
+/** Whether a node type id is registered. */
+declare function hasType(id: string): boolean;
+/** All registered node types. */
+declare function getRegisteredTypes(): NodeTypeDefinition[];
+/** (Re)register the built-in source types. Idempotent. */
+declare function registerBuiltInNodeTypes(): void;
+/** Clear the registry back to just the built-ins. Intended for tests. */
+declare function resetNodeTypeRegistry(): void;
+/**
+ * Resolve a node's graph layer via the registry.
+ *
+ * Precedence: the node's `entityType` definition → its `source.type`
+ * definition → `'file'`. This preserves the historical mapping for built-in
+ * source types while letting registered entity types override the layer.
+ */
+declare function resolveNodeLayer(node: KBNode): NodeLayer;
+/**
+ * Resolve the default cluster for a node from its type, when the node does not
+ * already declare one. Returns `undefined` when nothing is registered.
+ */
+declare function resolveTypeCluster(node: Pick<KBNode, 'entityType'> & {
+    source: {
+        type: string;
+    };
+}): string | undefined;
+
+/**
+ * Normalized repo-data bundle (Phase 4 / F4 #318).
+ *
+ * The local and remote loaders historically differed only in *how* they
+ * obtained raw repository data — a pre-built manifest import vs live GitHub API
+ * calls — and then wired the *same* providers from it. {@link RepoData} is the
+ * normalized superset both acquisition paths produce, so a single
+ * `loadKnowledgeBase(source, config)` can wire providers once.
+ *
+ * A {@link RepoSource} is the system-of-record adapter: it both implements the
+ * pure {@link Source} contract from `@anokye-labs/kbexplorer-core` (self-
+ * describing, situationally-afforded {@link Resource}s) and exposes
+ * {@link RepoSource.getRepoData} — the engine-facing accessor the loader
+ * consumes to build the graph.
+ */
+
+/** Pull request shape consumed by the work + person providers (superset). */
+interface RepoPullRequest {
+    number: number;
+    title: string;
+    body: string;
+    state: string;
+    labels: Array<{
+        name: string;
+        color: string;
+    }>;
+    html_url: string;
+    created_at: string;
+    updated_at: string;
+    head_branch?: string;
+    /** GitHub user who opened the PR (present from the API; absent from a manifest). */
+    user?: {
+        login: string;
+    };
+    /** Assignees (present from the API; absent from a manifest). */
+    assignees?: Array<{
+        login: string;
+    }>;
+}
+/** Repository metadata consumed by the work provider. */
+interface RepoMetadata {
+    name: string;
+    description: string;
+    html_url: string;
+    /** Repo homepage URL (blank when unset). Matches the old generator's 12-key `fetchRepoMetadata` shape. */
+    homepage: string;
+    default_branch: string;
+    stargazers_count: number;
+    forks_count: number;
+    private: boolean;
+    topics: string[];
+    primary_language: string;
+    languages: Array<{
+        name: string;
+        size: number;
+    }>;
+    owner: {
+        login: string;
+        avatar_url: string;
+    };
+}
+/**
+ * The normalized raw-data bundle a {@link RepoSource} hands the loader. Optional
+ * fields degrade gracefully: a source that cannot supply them (e.g. the API
+ * source has no `nodemapRaw` yet) leaves them empty/null and the matching
+ * provider becomes a safe no-op — keeping output byte-identical per source.
+ */
+interface RepoData {
+    /** owner/name slug for file-node identity. */
+    repo: string;
+    tree: GHTreeItem[];
+    authoredContent: Record<string, string>;
+    nodemapRaw: string | null;
+    nodemapFiles?: Record<string, string>;
+    nodemapDirs?: Record<string, GHTreeItem[]>;
+    /** Glob lookup over authored/nodemap files (empty for sources without one). */
+    listFiles: (pattern: string) => Promise<string[]>;
+    issues: GHIssue[];
+    pullRequests: RepoPullRequest[];
+    commits: GHCommit[];
+    branches: Array<{
+        name: string;
+        protected: boolean;
+    }>;
+    repoMetadata: RepoMetadata | null;
+    releases: GHRelease[];
+    structuralFiles: Record<string, string>;
+    structuredNodeMapRaw: string | null;
+    contentModel: ContentModelSource | null;
+    readme: string | null;
+    themeFileRaw?: string | null;
+}
+/**
+ * A system-of-record adapter. Implements the pure {@link Source} contract (the
+ * navigable, situationally-afforded resource surface) and exposes the
+ * engine-facing {@link getRepoData} the loader consumes.
+ */
+interface RepoSource extends Source {
+    /** Produce the normalized data bundle the provider pipeline consumes. */
+    getRepoData(): Promise<RepoData>;
+}
+
+export { type ContentModelSchema as C, type Diagnostic as D, type EngineEnv as E, type FkFlavor as F, type GHIssue as G, type JsonLdContext as J, type KindConvention as K, type Lifecycle as L, type NodeLayer as N, type OrgDef as O, type RepoSource as R, type TeamOps as T, type VocabularyOverlay as V, type ContentModelSource as a, type GHTreeItem as b, type GHRelease as c, type RepoData as d, type CompositeLeg as e, type Conventions as f, type DerivedRule as g, type DiagnosticLevel as h, type EdgeRule as i, type EdgesSpec as j, type GHCommit as k, type LifecycleBand as l, type NodeTypeDefinition as m, type Vocabulary as n, getRegisteredTypes as o, hasType as p, registerType as q, registerBuiltInNodeTypes as r, resetNodeTypeRegistry as s, resolveNodeLayer as t, resolveType as u, resolveTypeCluster as v, type RepoMetadata as w, type RepoPullRequest as x };