@glossic/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rody Huancas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,360 @@
+import { z } from 'zod';
+import { Adapter, GlossicConfig, Manifest, Workspace, GlossicUserConfig, Provider, ExtractResult, Unit, Project, CompletionRequest } from '@glossic/schema';
+export { compareStrings, joinPosix, relativePosix, sortBy, toPosix } from '@glossic/schema';
+
+declare const DEFAULT_CACHE_PATH = ".glossic/cache.json";
+/** Bumped by hand when the entry shape changes; a mismatch discards the whole file. */
+declare const CACHE_VERSION = "1";
+/** What a unit was documented from, so the next run can tell whether anything moved. */
+declare const CacheEntrySchema: z.ZodObject<{
+    unitId: z.ZodString;
+    unitHash: z.ZodString;
+    promptVersion: z.ZodString;
+    model: z.ZodString;
+    lang: z.ZodString;
+    outputPath: z.ZodString;
+    generatedAt: z.ZodString;
+}, z.core.$strip>;
+type CacheEntry = z.infer<typeof CacheEntrySchema>;
+declare const CacheFileSchema: z.ZodObject<{
+    version: z.ZodString;
+    entries: z.ZodArray<z.ZodObject<{
+        unitId: z.ZodString;
+        unitHash: z.ZodString;
+        promptVersion: z.ZodString;
+        model: z.ZodString;
+        lang: z.ZodString;
+        outputPath: z.ZodString;
+        generatedAt: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type CacheFile = z.infer<typeof CacheFileSchema>;
+declare const emptyCache: () => CacheFile;
+/** Reads the cache, returning an empty one for a missing, corrupt or outdated file. */
+declare const readCache: (target: string) => Promise<CacheFile>;
+/** JSON with the entries sorted by unit id, so the file does not churn between runs. */
+declare const serializeCache: (cache: CacheFile) => string;
+/** Writes the cache, creating its directory. Returns the absolute path written. */
+declare const writeCache: (cache: CacheFile, target: string) => Promise<string>;
+/** Entries keyed by unit id, for lookups while deciding what to regenerate. */
+declare const indexCache: (cache: CacheFile) => Map<string, CacheEntry>;
+
+/** What every pipeline stage needs: where to scan, with which adapters and config. */
+interface PipelineContext {
+    root: string;
+    adapters: readonly Adapter[];
+    config?: GlossicConfig;
+    generatedAt?: string;
+}
+interface ScanResult {
+    manifest: Manifest;
+    workspace: Workspace;
+    adapterByProject: Record<string, string>;
+}
+/** Puts the adapters in the order the config asks for, dropping the ones it omits. */
+declare const orderAdapters: (adapters: readonly Adapter[], wanted: readonly string[]) => Adapter[];
+/** Walks the workspace and turns it into a manifest, calling no provider. */
+declare const scan: (ctx: PipelineContext) => Promise<ScanResult>;
+
+interface CheckContext extends PipelineContext {
+    outDir: string;
+}
+/** One unit weighed against its page: the hash expected against the one on disk. */
+interface CheckEntry {
+    unitId: string;
+    docPath: string;
+    expectedHash: string;
+    documentedHash: string | undefined;
+}
+interface CheckResult {
+    outDir: string;
+    upToDate: CheckEntry[];
+    missing: CheckEntry[];
+    stale: CheckEntry[];
+    orphaned: string[];
+    ok: boolean;
+}
+interface DocumentFrontmatter {
+    unit: string | undefined;
+    hash: string | undefined;
+}
+/** The frontmatter of a generated page, empty when the file carries none. */
+declare const readDocFrontmatter: (file: string) => Promise<DocumentFrontmatter>;
+/**
+ * Compares the pages on disk against a fresh scan, calling no provider. This
+ * is what a CI job runs to fail on documentation nobody regenerated.
+ */
+declare const check: (ctx: CheckContext) => Promise<CheckResult>;
+
+/** Config filenames, in the order they are looked for. */
+declare const CONFIG_FILENAMES: string[];
+/** Posix path of the project's config file, when it has one. */
+declare const findConfigFile: (root: string) => Promise<string | undefined>;
+interface LoadedConfig {
+    file: string;
+    values: GlossicUserConfig;
+}
+/** Loads and validates glossic.config.ts, ignoring a file that exports nothing usable. */
+declare const loadProjectConfig: (root: string) => Promise<LoadedConfig | undefined>;
+
+/** Which source decided one option's value; `glossic doctor` prints it. */
+type ConfigOrigin = "flag" | "project" | "preference" | "default";
+type ConfigOrigins = Record<string, ConfigOrigin>;
+interface ConfigSources {
+    flags?: GlossicUserConfig | undefined;
+    project?: GlossicUserConfig | undefined;
+    preference?: GlossicUserConfig | undefined;
+}
+interface ResolvedConfig {
+    config: GlossicConfig;
+    origins: ConfigOrigins;
+}
+/**
+ * Merges the sources under one precedence chain (flags, project config, saved
+ * preference, schema defaults) and records which one won each key.
+ */
+declare const resolveConfig: (sources?: ConfigSources) => ResolvedConfig;
+/** The options that change how files become units, and so invalidate a scan. */
+declare const GROUPING_KEYS: readonly ["include", "exclude", "ignoreUnits", "excludeFromContent", "mergeChildrenInto", "minUnitFiles", "maxUnitFiles"];
+
+/** Placeholder for a code path that is scaffolded but not written yet. */
+declare class NotImplementedError extends Error {
+    constructor(what: string);
+}
+/**
+ * Nothing on this machine can write prose. The message is the install
+ * instructions, because this is the first wall a new user hits.
+ */
+declare class NoProviderAvailableError extends Error {
+    readonly tried: string[];
+    constructor(tried: readonly string[]);
+}
+/** The provider named by a flag or by the config does not exist. */
+declare class UnknownProviderError extends Error {
+    constructor(requested: string, known: readonly string[]);
+}
+
+/** `sleep` and `onRetry` exist so a test can drive the loop without waiting. */
+interface RetryOptions {
+    attempts?: number;
+    baseDelayMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    onRetry?: (attempt: number, error: unknown) => void;
+}
+/** Exponential backoff: the delay doubles with every attempt. */
+declare const backoffDelay: (attempt: number, baseDelayMs: number) => number;
+/** Runs a task again while it fails with a retryable provider error. */
+declare const withRetry: <T>(task: () => Promise<T>, options?: RetryOptions) => Promise<T>;
+
+interface GenerateContext extends PipelineContext {
+    outDir: string;
+    provider?: Provider;
+    dryRun?: boolean;
+    force?: boolean;
+    only?: string;
+    cachePath?: string;
+    retry?: RetryOptions;
+    onEvent?: (event: GenerateEvent) => void;
+}
+type UnitOutcome = "generated" | "cached" | "failed";
+type GenerateEvent = {
+    type: "unit-start";
+    unitId: string;
+    index: number;
+    total: number;
+} | {
+    type: "unit-done";
+    unitId: string;
+    index: number;
+    total: number;
+    outcome: UnitOutcome;
+    durationMs: number;
+};
+type GenerateReason = "cached" | "new" | "content-changed" | "prompt-version-changed" | "model-changed" | "lang-changed" | "output-missing" | "forced";
+interface GeneratePlanEntry {
+    unitId: string;
+    docPath: string;
+    files: number;
+    estimatedTokens: number;
+    reason: GenerateReason;
+    regenerate: boolean;
+}
+interface GenerateWarning {
+    unitId: string;
+    message: string;
+}
+interface GenerateFailure {
+    unitId: string;
+    reason: string;
+    code: string | undefined;
+    detail: string | undefined;
+}
+interface GenerateResult {
+    manifest: Manifest;
+    written: string[];
+    plan: GeneratePlanEntry[];
+    failures: GenerateFailure[];
+    warnings: GenerateWarning[];
+    filteredOut: string[];
+    estimatedTokens: number;
+    savedTokens: number;
+    generated: number;
+    fromCache: number;
+    dryRun: boolean;
+}
+
+/** The model a cache entry was written under, with a name for the unset case. */
+declare const modelCacheKey: (config: GlossicConfig) => string;
+
+/**
+ * Scans, works out what the cache still covers, and writes a page for the
+ * rest. With no provider, or with dryRun, it stops at the plan and spends nothing.
+ */
+declare const generate: (ctx: GenerateContext) => Promise<GenerateResult>;
+
+declare const DEFAULT_MANIFEST_PATH = ".glossic/manifest.json";
+interface BuildManifestOptions {
+    generatedAt?: string;
+}
+/** Assembles the manifest, sorting every list so two runs over the same code match. */
+declare const buildManifest: (workspace: Workspace, results: readonly ExtractResult[], options?: BuildManifestOptions) => Manifest;
+/** The manifest as it lands on disk: JSON, two-space indent, trailing newline. */
+declare const serializeManifest: (manifest: Manifest) => string;
+/** Writes the manifest, creating its directory. Returns the absolute path written. */
+declare const writeManifest: (manifest: Manifest, target: string) => Promise<string>;
+/** Reads and validates a manifest, or undefined when it is missing or invalid. */
+declare const readManifest: (target: string) => Promise<Manifest | undefined>;
+
+/** Where a unit's page goes, relative to the output directory. */
+declare const unitDocPath: (unit: Unit) => string;
+declare const INDEX_DOC_PATH = "index.md";
+interface RenderUnitDocInput {
+    unit: Unit;
+    project: Project;
+    body: string;
+    generatedAt: string;
+}
+/** One unit's page: frontmatter carrying the hash, then the prose the provider wrote. */
+declare const renderUnitDoc: (input: RenderUnitDocInput) => string;
+interface RenderIndexDocInput {
+    manifest: Manifest;
+    generatedAt: string;
+}
+/** The index page listing every unit in the workspace. */
+declare const renderIndexDoc: (input: RenderIndexDocInput) => string;
+
+/** A file longer than this is truncated before it goes into a prompt. */
+declare const MAX_FILE_BYTES = 24000;
+interface UnitSource {
+    path: string;
+    language: string;
+    content: string;
+    truncated: boolean;
+}
+interface BuildPromptInput {
+    unit: Unit;
+    project: Project;
+    workspaceName: string;
+    sources: readonly UnitSource[];
+    lang: string;
+    model?: string | undefined;
+    temperature?: number | undefined;
+}
+/** Bumped by hand when the prompt changes, which invalidates every cached unit. */
+declare const PROMPT_VERSION = "3";
+/** The rules the model is held to; assertDocumentContent checks the answer against them. */
+declare const SYSTEM_PROMPT: string;
+/** Turns a unit and its sources into the one request a provider will answer. */
+declare const buildUnitPrompt: (input: BuildPromptInput) => CompletionRequest;
+/** Reads a unit's documentable files, truncating any that run too long. */
+declare const readUnitSources: (root: string, unit: Unit) => Promise<UnitSource[]>;
+/** Rough token count, for the estimate a dry run prints before anything is spent. */
+declare const estimateTokens: (request: CompletionRequest) => number;
+
+/** Auto-detection order: the local CLI first, the paid API second. */
+declare const PROVIDER_PREFERENCE: string[];
+interface ResolveProviderOptions {
+    providers: readonly Provider[];
+    config?: Pick<GlossicConfig, "provider"> | undefined;
+    requested?: string | undefined;
+}
+interface ProviderStatus {
+    name: string;
+    available: boolean;
+}
+/** Asks every provider whether it can run, in preference order. Never throws. */
+declare const probeProviders: (providers: readonly Provider[]) => Promise<ProviderStatus[]>;
+/**
+ * The provider to use: the one named by a flag or the config, otherwise the
+ * first one available in preference order.
+ */
+declare const resolveProvider: (options: ResolveProviderOptions) => Promise<Provider>;
+
+/** A name-keyed collection of adapters or providers, kept in insertion order. */
+declare class Registry<T extends {
+    name: string;
+}> {
+    #private;
+    register(item: T): this;
+    get(name: string): T | undefined;
+    has(name: string): boolean;
+    list(): T[];
+    get size(): number;
+}
+type AdapterRegistry = Registry<Adapter>;
+type ProviderRegistry = Registry<Provider>;
+declare const createAdapterRegistry: (adapters?: Adapter[]) => AdapterRegistry;
+declare const createProviderRegistry: (providers?: Provider[]) => ProviderRegistry;
+
+/** A provider that records what it was asked, for assertions. */
+interface FakeProvider extends Provider {
+    readonly calls: CompletionRequest[];
+}
+interface FakeProviderOptions {
+    name?: string;
+    available?: boolean;
+    respond?: (request: CompletionRequest, index: number) => string;
+}
+/** A provider that answers from memory, so a test can drive the pipeline end to end. */
+declare const createFakeProvider: (options?: FakeProviderOptions) => FakeProvider;
+
+/** True when the path can be reached; never throws. */
+declare const pathExists: (target: string) => Promise<boolean>;
+/** File contents, or undefined when it cannot be read. */
+declare const readText: (target: string) => Promise<string | undefined>;
+/** Parsed JSON, or undefined when the file is missing or malformed. */
+declare const readJson: <T>(target: string) => Promise<T | undefined>;
+
+/** Under this many characters the answer reads as a refusal, not as a document. */
+declare const MIN_DOCUMENT_LENGTH = 200;
+/** Over this, what precedes the first heading is an answer rather than a preamble. */
+declare const MAX_PREAMBLE_LENGTH = 500;
+interface NormalizedDocument {
+    body: string;
+    preamble: string | undefined;
+}
+/** Shortens text for an error message, onto a single line. */
+declare const excerpt: (text: string, limit: number) => string;
+/** Splits a response into the document and whatever the model said before it. */
+declare const normalizeDocument: (providerName: string, text: string) => NormalizedDocument;
+interface ContentProblem {
+    reason: string;
+    excerpt: string;
+}
+/** The first conversational tell in the text, ignoring fenced code. */
+declare const findContentProblem: (text: string) => ContentProblem | undefined;
+/** Throws a ProviderError when the response reads as conversation, not documentation. */
+declare const assertDocumentContent: (providerName: string, text: string) => void;
+interface PreparedDocument {
+    body: string;
+    droppedPreamble: string | undefined;
+}
+/** Normalises and validates in one pass: what generate writes is what survives this. */
+declare const prepareDocument: (providerName: string, text: string) => PreparedDocument;
+
+/** Identifies the repository and lists its projects, monorepo or not. */
+declare const resolveWorkspace: (root: string) => Promise<Workspace>;
+
+declare const CORE_VERSION: string;
+
+export { type AdapterRegistry, type BuildManifestOptions, type BuildPromptInput, CACHE_VERSION, CONFIG_FILENAMES, CORE_VERSION, type CacheEntry, CacheEntrySchema, type CacheFile, CacheFileSchema, type CheckContext, type CheckEntry, type CheckResult, type ConfigOrigin, type ConfigOrigins, type ConfigSources, type ContentProblem, DEFAULT_CACHE_PATH, DEFAULT_MANIFEST_PATH, type FakeProvider, type FakeProviderOptions, GROUPING_KEYS, type GenerateContext, type GenerateEvent, type GenerateFailure, type GeneratePlanEntry, type GenerateReason, type GenerateResult, type GenerateWarning, INDEX_DOC_PATH, type LoadedConfig, MAX_FILE_BYTES, MAX_PREAMBLE_LENGTH, MIN_DOCUMENT_LENGTH, NoProviderAvailableError, type NormalizedDocument, NotImplementedError, PROMPT_VERSION, PROVIDER_PREFERENCE, type PipelineContext, type PreparedDocument, type ProviderRegistry, type ProviderStatus, Registry, type RenderIndexDocInput, type RenderUnitDocInput, type ResolveProviderOptions, type ResolvedConfig, type RetryOptions, SYSTEM_PROMPT, type ScanResult, type UnitOutcome, type UnitSource, UnknownProviderError, assertDocumentContent, backoffDelay, buildManifest, buildUnitPrompt, check, createAdapterRegistry, createFakeProvider, createProviderRegistry, emptyCache, estimateTokens, excerpt, findConfigFile, findContentProblem, generate, indexCache, loadProjectConfig, modelCacheKey, normalizeDocument, orderAdapters, pathExists, prepareDocument, probeProviders, readCache, readDocFrontmatter, readJson, readManifest, readText, readUnitSources, renderIndexDoc, renderUnitDoc, resolveConfig, resolveProvider, resolveWorkspace, scan, serializeCache, serializeManifest, unitDocPath, withRetry, writeCache, writeManifest };