@doxbrix/doxloop 0.1.4 → 0.2.0

package/dist/authoring-batches.d.ts

@@ -0,0 +1,190 @@
+import type { DocumentationPlan, DocumentationPlanPage, ValidationIssue } from './types.js';
+export interface AuthoringBatch {
+    /** One-based position in the run. */
+    index: number;
+    total: number;
+    pages: DocumentationPlanPage[];
+    /** Planned screenshot captures across the batch's pages. */
+    captures: number;
+}
+export interface BatchOptions {
+    /** Pages per batch; the last batch may be smaller. */
+    maxPages?: number;
+    /** Planned captures per batch; a page never splits, so one page may exceed it. */
+    maxCaptures?: number;
+}
+export declare const DEFAULT_BATCH_PAGES = 4;
+export declare const DEFAULT_BATCH_CAPTURES = 18;
+/** Pages the run writes: approved, not deferred, created or updated. */
+export declare function writablePlanPages(plan: Pick<DocumentationPlan, 'pages'>): DocumentationPlanPage[];
+export declare function plannedCaptures(page: DocumentationPlanPage): number;
+/** Batch size from the environment, for operators tuning a slow application. */
+export declare function batchOptionsFromEnvironment(env?: NodeJS.ProcessEnv): BatchOptions;
+/**
+ * Split pages into batches in plan order, keeping navigation sections together
+ * where the size allows: pages that share a section read each other's
+ * terminology, so writing them in one session keeps them consistent.
+ */
+export declare function planAuthoringBatches(plan: Pick<DocumentationPlan, 'pages' | 'navigation'>, pages: DocumentationPlanPage[], options?: BatchOptions): AuthoringBatch[];
+/** Claude turn cap for one batch session. */
+export declare function batchTurnBudget(batch: Pick<AuthoringBatch, 'pages' | 'captures'>, env?: NodeJS.ProcessEnv): number;
+/** Turn cap for a targeted fix session over a few pages. */
+export declare function fixTurnBudget(files: number, issues: number): number;
+/** Wall-clock cap for one batch, so a stuck session cannot eat the run's budget. */
+export declare function batchMinutes(batch: Pick<AuthoringBatch, 'pages' | 'captures'>): number;
+export declare function describeBatchPage(page: DocumentationPlanPage): string;
+export declare const BATCH_SLICE_FILE = ".doxloop/cache/authoring-batch.json";
+/**
+ * The part of the plan one batch needs, written to a small file so the agent
+ * reads six pages' worth of plan instead of the whole 90 KB document (which a
+ * real run re-read, truncated, in every session).
+ */
+export declare function batchPlanSlice(plan: DocumentationPlan, batch: AuthoringBatch): Record<string, unknown>;
+/**
+ * The contract appended to the run's prompt for one batch: which pages to
+ * write now, which already exist, which come later, and what Doxloop itself
+ * takes care of so the agent does not spend turns on it.
+ */
+export interface BatchContractInput {
+    batch: AuthoringBatch;
+    completed: DocumentationPlanPage[];
+    upcoming: DocumentationPlanPage[];
+    screenshots: boolean;
+    mode: 'create' | 'update';
+    precaptured?: number;
+    /** Project-relative files Doxloop wrote for this batch. */
+    artifacts?: {
+        slice?: string;
+        manifest?: string;
+        evidence?: string;
+        pack?: string;
+    };
+    /** Other batch sessions run at the same time in this workspace. */
+    concurrent?: boolean;
+    /** This session runs alone and may set up the site (theme, spaces) for the others. */
+    exclusive?: boolean;
+    /** Skill references already included in the prompt, by name, so the writer does not read them again. */
+    references?: string[];
+    /** Frontmatter of the pages earlier batches wrote, for consistent titles and icons. */
+    written?: Array<{
+        path: string;
+        title?: string;
+        icon?: string;
+    }>;
+    /** The extension every new page is saved with (`preferredPageExtension(plan.target)`). */
+    pageExtension?: string;
+}
+export declare function batchContract(input: BatchContractInput): string;
+/**
+ * Concurrent batch sessions, from the environment; 1 runs batches one after
+ * another. A run's wall time is almost entirely model time (a measured run:
+ * 43 min model, 1 min tools), so concurrency is the only lever on it, and it
+ * spends no extra tokens: each batch costs the same whether or not another
+ * is running.
+ */
+export declare function parallelismFromEnvironment(env?: NodeJS.ProcessEnv): number;
+/**
+ * Two, not three: with three Codex sessions in flight a real run saw all
+ * three model streams hang at the same second and lose their whole batch.
+ */
+export declare const DEFAULT_PARALLEL_BATCHES = 2;
+/** How often the inactivity watchdog checks a session's output. */
+export declare const AGENT_IDLE_CHECK_MS = 15000;
+/**
+ * Default quiet time before a session is stopped and retried. Long enough for
+ * a writer to think and then emit four pages in one edit (measured under five
+ * minutes), short enough that a hung model stream costs minutes, not a cap.
+ */
+export declare const DEFAULT_AGENT_IDLE_MINUTES = 6;
+/**
+ * Quiet time after which a session is stopped, in milliseconds; 0 disables
+ * the watchdog. `DOXLOOP_AGENT_IDLE_MINUTES` overrides the default.
+ */
+export declare function agentIdleLimitMs(env?: NodeJS.ProcessEnv): number;
+export declare function formatIdleMinutes(ms: number): string;
+/**
+ * Whether a batch has to run before the others start: the landing page links
+ * to every section, and a new site's theme and spaces must exist before
+ * concurrent sessions try to use them.
+ */
+export declare function batchNeedsExclusiveStart(batch: AuthoringBatch, mode: 'create' | 'update'): boolean;
+/** Split issues into fix-session chunks of at most `maxFiles` files each. */
+export declare function chunkIssuesByFile(issues: ValidationIssue[], maxFiles: number): ValidationIssue[][];
+/**
+ * The follow-up prompt for defects Doxloop found in a batch. Each issue names
+ * its file, so the agent can go straight to the fix.
+ */
+export declare function fixContract(input: {
+    issues: ValidationIssue[];
+    files: string[];
+    round: number;
+    maxRounds: number;
+}): string;
+/** Validation issues that belong to the given page files, errors first. */
+export declare function issuesForFiles(issues: ValidationIssue[], files: Set<string>, options?: {
+    includeWarnings?: boolean;
+}): ValidationIssue[];
+/** Warnings worth a fix session: they are the depth contract the writer owes, not taste. */
+export declare const FIXABLE_WARNINGS: Set<string>;
+/**
+ * How a set of validation issues reads in the run log. Errors block the
+ * proposal; the fixable warnings are suggestions, and calling 204 missing
+ * parameter examples "204 issues" right after every batch "passed" read as
+ * a run that had gone wrong.
+ */
+export declare function describeIssues(issues: ValidationIssue[]): string;
+/** The line that opens the end-of-run pass: "Final polish" when nothing blocks the proposal. */
+export declare function finalCheckAnnouncement(issues: ValidationIssue[], sessions: number, parallel: number): string;
+/**
+ * What a batch's fix round works on. The batch and the end-of-run pass
+ * validate with the same rules: errors always go to a fix session, and the
+ * fixable warnings ride along with them, because the session is already open
+ * on those pages. A batch with warnings alone passes and leaves them for the
+ * one consolidated polish at the end, where they used to arrive unannounced
+ * (204 of them after sixteen batches that had all "passed").
+ */
+export declare function splitBatchIssues(issues: ValidationIssue[]): {
+    fix: ValidationIssue[];
+    deferred: ValidationIssue[];
+};
+/**
+ * A batch's result line. A batch passes on errors alone; its fixable
+ * warnings are counted here so the end-of-run polish is no surprise.
+ */
+export declare function batchPassLine(label: string, pageCount: number, deferred: ValidationIssue[]): string;
+/** Codes Doxloop repairs itself between batches; a fix session never needs them. */
+export declare const REPAIRED_BY_POSTPASS: Set<string>;
+/**
+ * A "broken link" whose target is a planned page another batch has not
+ * written yet is not a defect: the contract tells the writer to link to
+ * those paths, and the end-of-run check sees them once every batch is done.
+ * A per-batch fix session given such an issue removes the cross-link, which
+ * costs a session and loses the link for good.
+ */
+export declare function isForwardLinkIssue(issue: ValidationIssue, pendingPaths: Iterable<string>): boolean;
+/**
+ * Where the writer should look, and where it should not. Search results from
+ * tests, fixtures, generated bundles, migrations and lockfiles are the bulk
+ * of what a broad grep over a product repository returns, and every hit the
+ * agent reads is paid for in context. The batch's own citations name the
+ * directories that matter.
+ */
+export declare const SOURCE_NOISE_DIRECTORIES: string[];
+export declare const SOURCE_NOISE_FILES: string[];
+export declare function sourceSearchGuidance(pages: DocumentationPlanPage[]): string;
+/** Guides per capture session; the browser signs in once per session. */
+export declare const DEFAULT_CAPTURE_GUIDES_PER_SESSION = 3;
+export declare const DEFAULT_CAPTURE_STEPS_PER_SESSION = 8;
+/**
+ * Group guides that still need captures into sessions: a few guides each,
+ * bounded by their planned steps so one session never drives a long tour,
+ * in plan order so a session's guides are neighbours in the product.
+ */
+export declare function captureSessionGroups<T extends {
+    guide: {
+        steps: Array<{
+            status: string;
+        }>;
+    };
+}>(pending: readonly T[], env?: NodeJS.ProcessEnv): T[][];
+//# sourceMappingURL=authoring-batches.d.ts.map