@cavelang/cli 0.34.0 → 0.36.0

package/dist/internal/connect/declared.d.ts

@@ -0,0 +1,204 @@
+import type { Store } from '@cavelang/store';
+import * as Source from './source.ts';
+import * as Template from './template.ts';
+import type { Report } from './run.ts';
+/** Entity prefix of source declarations and policy (spec §26.3). */
+export declare const prefix = "source/";
+/** The declaration attributes, one per `cave connect` option. */
+export declare const attributes: readonly ["path", "map", "key", "format", "delimiter", "table", "sql", "records"];
+export type Attribute = typeof attributes[number];
+export type Declared = {
+    /** The entity name after `source/`. */
+    readonly name: string;
+    /** File path (relative to the store's directory) or URL. */
+    readonly path: string;
+    /** Mapping template path, or an inline template (`?name IS person, …`); a `.cave` source needs none. */
+    readonly map?: string;
+    readonly key?: string;
+    /** `csv | tsv | json | jsonl | sqlite`, or `cave`; by extension when omitted. */
+    readonly format?: string;
+    readonly delimiter?: string;
+    readonly table?: string;
+    readonly sql?: string;
+    readonly records?: string;
+};
+export type t = Declared;
+/** A source's declaration attributes as one text carries them — possibly partial, a delta over what the store knows. */
+export type Delta = {
+    readonly name: string;
+    readonly fields: Partial<Record<Attribute, string>>;
+};
+/**
+ * A stored attribute value as declared: the store keeps a literal's
+ * delimiters (`"SELECT …"`, `` `?name IS person, …` ``), and a path, a
+ * query, or an inline mapping is the text inside them.
+ */
+export declare const unwrap: (value: string) => string;
+/** Every `source/<name>` attribute claim current in the store, grouped by source — complete or not. */
+export declare const deltasOf: (store: Store) => Delta[];
+/** A delta applied over a known declaration; a source without a `path` is not declared. */
+export declare const merge: (known: undefined | Declared, delta: Delta) => undefined | Declared;
+/**
+ * The store's declared sources: every `source/<name>` whose current belief
+ * carries a positive `path`, with the other declaration attributes that
+ * are current alongside it. Retracting a `path` (`… @ 0%`) removes that
+ * series; the source disappears only when no positive path series remains.
+ * Superseding the newest positive path moves it.
+ */
+export declare const declaredSources: (store: Store) => Declared[];
+/**
+ * The sources a CAVE text declares, read without touching any store: the
+ * text is replayed into a scratch in-memory store. This is how an overlay
+ * or a dry run discovers what a followed `.cave` source declares in turn,
+ * before anything is appended.
+ */
+export declare const declaredIn: (text: string) => Declared[];
+/**
+ * Every source declaration attribute a CAVE text carries, complete or
+ * partial: a followed `.cave` source may change just the map or key of a
+ * source the store already declares, and that delta must reach whatever
+ * reads declarations without appending (`discover`, `--name`).
+ */
+export declare const declarationsIn: (text: string) => Delta[];
+/** Where a declared path points: URLs as they are, files against the store's directory. */
+export declare const resolvePath: (path: string, dir: string) => string;
+/** A mapping-free CAVE text source: the file is its own template (all prelude). */
+export declare const isCave: (declared: Declared) => boolean;
+/** The declaration as the equivalent `cave connect` invocation, for listings. */
+export declare const describe: (declared: Declared) => string;
+/** The store directory a root path implies: the file's directory, or the working directory for `:memory:`. */
+export declare const directoryOf: (root: string) => string;
+/** The declaration's content, for change detection between passes of one run. */
+export declare const signature: (declared: Declared) => string;
+/** Bookkeeping attribute recording which declaration a source was last run under. */
+export declare const declarationAttribute = "connect-declaration";
+/** Digest of a declaration — what a run records, and what `followed` compares. */
+export declare const declarationDigest: (declared: Declared) => string;
+/**
+ * @returns `true` when the store followed the source under exactly this
+ * declaration: every run records the declaration's digest on the source
+ * entity (`source/<name> HAS connect-declaration: …`), so a source
+ * re-declared since — a local file that became a URL, say — is not
+ * followed, whatever digests its earlier version left behind.
+ */
+export declare const followed: (store: Store, declared: Declared) => boolean;
+/** A selection and everything it owns, transitively — what a named watch must watch. */
+export declare const closure: (store: Store, names: readonly string[]) => Declared[];
+/** A declared source loaded and ready for a pass. */
+export type Prepared = {
+    readonly declared: Declared;
+    readonly mapping: Template.Mapping;
+    readonly records: readonly Record<string, unknown>[];
+    readonly spans?: NonNullable<Source.Loaded['spans']>;
+    /** The path or URL the records came from, as declared — portable in `@src:` spans. */
+    readonly source?: string;
+    readonly cave: boolean;
+};
+/** Loads a declared source synchronously — local files only (`assemble`); a URL is refused. */
+export declare const prepareSync: (declared: Declared, dir: string) => Prepared;
+/** Loads a declared source, URLs included — a `.cave` URL is fetched and parsed as the template (`cave connect`). */
+export declare const prepare: (declared: Declared, dir: string, fetchImpl?: Source.FetchLike, signal?: AbortSignal) => Promise<Prepared>;
+export type DiscoverOptions = {
+    readonly signal?: AbortSignal;
+    readonly fetchImpl?: Source.FetchLike;
+    /** Only this declared source (and what it declares in turn). */
+    readonly only?: string;
+    /** Simulate a `--force` pass: every followed text is applied, digest or not. */
+    readonly force?: boolean;
+    /** Simulate a `--prune` pass: records that left a source retract, declarations they made included. */
+    readonly prune?: boolean;
+    /**
+     * Skip sources the store has already followed (they carry a digest claim)
+     * — what a text store's overlay needs: assembly followed every local
+     * source on open, so only the URL ones, and what they declare, are left.
+     */
+    readonly skipFollowed?: boolean;
+};
+/** Counts a source's declaration versions within one pass and refuses a cycle. */
+export declare const versionCounter: () => (name: string) => void;
+/**
+ * Loads every declared source of the store without leaving anything in
+ * it, URLs included, and returns the exact sequence a pass would run —
+ * a source re-declared along the way appears again, later. Nothing is
+ * simulated: the sources run through the real pass against a private
+ * snapshot of the store, each exactly once as it is discovered, and the
+ * declarations are read from that copy as they stand after each run; so
+ * precedence, deltas, retractions, and what an unchanged source skips
+ * come out exactly as in the pass, and the real database holds no lock
+ * while sources load. `force` replays every text (the overlay applies
+ * everything it loads); `prune` retracts what vanished records declared.
+ */
+export declare const discover: (origin: Store, root: string, options?: DiscoverOptions) => Promise<Prepared[]>;
+/** A discovery's run sequence with the declaration state it started from — what an overlay must still see before replaying. */
+export type Discovery = {
+    readonly sequence: Prepared[];
+    readonly baseline: ReadonlyMap<string, string>;
+};
+/**
+ * The declaration state an overlay depends on: the current row of every
+ * `source/…` claim key — effective declarations, shadowed series, partial
+ * deltas, bookkeeping, and the provenance ownership follows — keyed by
+ * claim key. Any change a writer makes to those inputs, even one that
+ * leaves every effective declaration and owner the same, changes it.
+ */
+export declare const declarationState: (store: Store) => Map<string, string>;
+/** Compare keyed declaration signatures or claim-row identities without ignoring ownership changes. */
+export declare const sameDeclarations: (a: ReadonlyMap<string, string>, b: ReadonlyMap<string, string>) => boolean;
+/** How many times an overlay rediscovers when the declarations changed underneath it. */
+export declare const overlayAttempts = 3;
+export declare const staleOverlay: () => Error;
+/** `discover`, also returning the declarations the snapshot started from. */
+export declare const discovery: (origin: Store, root: string, options?: DiscoverOptions) => Promise<Discovery>;
+/**
+ * Names of the sources whose current declaration claims a followed source
+ * owns — appended under its run — so a selection keeps a source's
+ * descendants even when its run changed nothing.
+ */
+export declare const ownedDeclarations: (store: Store, owner: string) => string[];
+/**
+ * Who owns which declarations, in one pass over the current declaration
+ * rows: the prelude runs as `<owner>`, a record as `<owner>/<key>`, so a
+ * mapping that emits declarations per record owns them through its
+ * records.
+ */
+export declare const ownership: (store: Store) => Map<string, Set<string>>;
+/** Declaration signatures by name. */
+export declare const signatures: (declared: readonly Declared[]) => Map<string, string>;
+/** Names whose declaration was added, changed, or removed between two snapshots. */
+export declare const changedNames: (before: ReadonlyMap<string, string>, after: ReadonlyMap<string, string>) => string[];
+export type RunOptions = {
+    readonly force?: boolean;
+    readonly prune?: boolean;
+};
+/** The digest of the declaration a source was last run under, if any. */
+export declare const recordedDeclaration: (store: Store, name: string) => undefined | string;
+/**
+ * One pass of a prepared declared source under `declaredNaming` (spec
+ * §23.4), recording the declaration it ran under. A source whose
+ * declaration changed since its last run — another path, key, query, or
+ * record selector — prunes as it runs: records the new version does not
+ * produce are retired, since the per-record diff never visits them. A
+ * source that was followed without a recorded declaration (digests, no
+ * marker) is treated as changed, conservatively.
+ */
+export declare const run: (store: Store, ready: Prepared, options?: RunOptions) => Report;
+export type Assembled = {
+    readonly declared: Declared;
+    readonly report: Report;
+};
+/**
+ * Follows every declared source of the store, the ones the followed
+ * sources declare in turn included, until none is left. `root` is the
+ * store's own file (or `:memory:`): paths resolve against its directory
+ * and the root file itself is never re-read as a source, so a file that
+ * declares itself, directly or through a cycle, is loaded exactly once —
+ * one file under several names, with different mappings say, is followed
+ * under each. URL sources are skipped, not errors: fetching cannot be
+ * synchronous, and `cave connect` follows them. Other failures are
+ * `LocateError`s — the store is incomplete without its sources, exactly
+ * as with a text file that does not parse.
+ */
+export declare const assemble: (store: Store, root: string, options?: {
+    readonly force?: boolean;
+}) => Assembled[];
+//# sourceMappingURL=declared.d.ts.map

package/dist/internal/connect/declared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"declared.d.ts","sourceRoot":"","sources":["../../src/declared.ts"],"names":[],"mappings":"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"}