hologit/holo-projector-napi/index.d.ts

Hologit automates the projection of layered composite file trees based on flat, declarative plans

/* tslint:disable */
/* eslint-disable */

/* auto-generated by NAPI-RS */

/**
 * Internal self-test hook: deliberately panics inside the binding so the
 * test suite can prove that a panic surfaces as a catchable JS error with
 * code `PANIC` rather than aborting the host process. Never call this
 * outside tests.
 */
export declare function __triggerPanicForTest(): void
/**
 * Compose a holobranch to its **pre-lens tree**: the extends chain and all
 * mappings composed per `specs/behaviors/composition.md`, with
 * `.holo/{branches,sources}` stripped but the final `.holo` strip skipped so
 * the host's lens phase can discover `.holo/lenses` and `.holo/config.toml`.
 * Returns the composed tree hash.
 */
export declare function compositeBranch(gitDir: string, rootTree: string, holobranch: string): string
/**
 * Full composition-only projection of a holobranch, including the final
 * metadata strip — hash-equal to the legacy engine with lensing disabled.
 * Returns the projected tree hash.
 */
export declare function projectBranch(gitDir: string, rootTree: string, holobranch: string): string
/** A source definition for `projectPlan`. Mirrors `ProjectionPlan.addSource`. */
export interface JsPlanSource {
  name: string
  url?: string
  ref?: string
  projectHolobranch?: string
}
/**
 * A mapping definition for `projectPlan`. Mirrors `ProjectionPlan.addMapping`
 * defaults: `files` `["**"]`, `root`/`output` `"."`, `layer` = source name.
 */
export interface JsPlanMapping {
  source: string
  files?: Array<string>
  root?: string
  output?: string
  layer?: string
  after?: Array<string>
  before?: Array<string>
}
/**
 * Compose git trees from structured source/mapping definitions — the
 * `ProjectionPlan` path, no `.holo/` config needed. Returns the composed
 * tree hash (full projection, metadata stripped).
 */
export declare function projectPlan(gitDir: string, sources: Array<JsPlanSource>, mappings: Array<JsPlanMapping>): string
/**
 * A commit identity (author or committer). `timeSeconds`/`offsetMinutes`
 * are optional; when omitted the current wall-clock time at UTC is used.
 * Pass them explicitly to reproduce a specific commit byte-for-byte.
 */
export interface Signature {
  name: string
  email: string
  timeSeconds?: number
  offsetMinutes?: number
}
/**
 * Options for [`ProjectionSession::commit_projection`]
 * (`specs/behaviors/projection-commits.md`). Exactly one of
 * `sourceDescription` (ref mode) / `workTreePath` (working-tree mode) is
 * required — the provenance string is host-computed, never engine-derived.
 */
export interface CommitProjectionOptions {
  /**
   * Target ref to advance (the oracle's `commitTo`); normalized by the
   * engine (`HEAD` and `refs/...` pass through, else `refs/heads/<name>`).
   */
  commitRef: string
  /** The projected holobranch's name. */
  holobranch: string
  /**
   * The composed output tree to commit (tree hash, or a commit/tag hash
   * peeled to its tree).
   */
  tree: string
  /**
   * The source commit the projection was taken from; second parent when
   * present.
   */
  sourceCommit?: string
  /** Ref-mode provenance: the host's `git describe --always --tags` output. */
  sourceDescription?: string
  /** Working-tree-mode provenance: the absolute work-tree path. */
  workTreePath?: string
  /**
   * Message override — replaces the entire default message, trailers
   * included (oracle quirk, ported).
   */
  message?: string
  /**
   * Explicit author; omitted, identity resolves from repo config
   * (including `GIT_AUTHOR_*` env), then holo-tree's fallback.
   */
  author?: Signature
  /** Explicit committer; same fallback chain as `author`. */
  committer?: Signature
}
/** Engine performance counters — process-global, monotonic, metrics only. */
export interface Stats {
  treesRead: number
  treesWritten: number
  treesSkippedClean: number
  cacheHits: number
  cacheMisses: number
  blobsRead: number
}
/** Current engine performance counters. */
export declare function stats(): Stats
/** Reset engine counters and module-level caches. */
export declare function resetStats(): void
/**
 * Warm engine context for repeat projections (`specs/api/projector-napi.md`
 * § ProjectionSession): a persistent repository handle plus one consumer-
 * owned [`TreeCache`] reused across calls.
 *
 * Staleness contract: only content-addressed state is cached (parsed trees
 * keyed by tree id, the gix object cache keyed by object id) — immutable by
 * construction. Refs are re-resolved from the repository on every call, and
 * objects written behind the session (new loose objects/packs) are found
 * without reopening it: gix stats loose refs and revalidates its packed-refs
 * snapshot per access, and refreshes its pack list on an object miss. The
 * session test suite proves both by writing refs/objects behind an open
 * session.
 */
export declare class ProjectionSession {
  /**
   * Open a repository at `gitDir` (a `.git` directory, or any path gix can
   * discover a repo from) and bind a fresh `TreeCache` to it.
   */
  constructor(gitDir: string)
  /** [`composite_branch`] against this session's warm context. */
  compositeBranch(rootTree: string, holobranch: string): string
  /** [`project_branch`] against this session's warm context. */
  projectBranch(rootTree: string, holobranch: string): string
  /** [`project_plan`] against this session's warm context. */
  projectPlan(sources: Array<JsPlanSource>, mappings: Array<JsPlanMapping>): string
  /**
   * Create a projection commit for a composed tree and advance the target
   * ref (`specs/behaviors/projection-commits.md`). Returns the new commit
   * id; a concurrent ref move surfaces as `REF_CONFLICT`.
   */
  commitProjection(options: CommitProjectionOptions): string
  /**
   * Number of trees held in this session's `TreeCache` — observability so
   * warmth is provable in tests; metrics only, never an input to behavior.
   */
  cachedTrees(): number
  /**
   * Drop the session's `TreeCache`. Never required for correctness —
   * content-addressed entries cannot go stale — this is a memory valve for
   * long-lived hosts.
   */
  clearCache(): void
}