@farming-labs/docs 0.2.120 → 0.2.122

package/dist/retrieval-digest-AOx2-LbC.d.mts

@@ -1,367 +0,0 @@
-import { H as DocsAgentEvaluationAnswerProvider, Rt as DocsCodeBlocksPlannerProvider, Vr as OpenDocsProvider, Vt as DocsCodeBlocksValidateConfig, Wr as OpenDocsTarget, Xn as DocsSearchConfig, Z as DocsAgentFeedbackData, at as DocsAgentGoldenQueryVariant, ct as DocsAgentGoldenTask, et as DocsAgentGoldenCoverageApplicability, lt as DocsAgentGoldenTaskExpectation, nt as DocsAgentGoldenExpectedExample, q as DocsAgentEvaluationSurface, ut as DocsAgentGoldenTaskFilters } from "./types-BJFeMXWZ.mjs";
-import { DocsMcpPage } from "./mcp.mjs";
-
-//#region src/agent-feedback-loop.d.ts
-declare const DOCS_AGENT_FEEDBACK_IMPROVEMENT_FORMAT: "farming-labs-agent-feedback-improvements.v1";
-interface DocsAgentFeedbackImprovementOptions {
-  /** Minimum failed reports required before a cluster becomes recurring. @default 2 */
-  minOccurrences?: number;
-  /** Stable report timestamp override for tests and reproducible automation. */
-  generatedAt?: string;
-}
-interface DocsAgentFeedbackIssueDraft {
-  title: string;
-  body: string;
-  labels: string[];
-}
-interface DocsAgentFeedbackCluster {
-  id: string;
-  page: string;
-  task: string;
-  occurrences: number;
-  outcomes: string[];
-  missingContext: string[];
-  docIssues: string[];
-  suggestedImprovements: string[];
-  goldenTask?: DocsAgentGoldenTask;
-  issue: DocsAgentFeedbackIssueDraft;
-}
-interface DocsAgentFeedbackImprovementReport {
-  format: typeof DOCS_AGENT_FEEDBACK_IMPROVEMENT_FORMAT;
-  generatedAt: string;
-  feedbackCount: number;
-  failureCount: number;
-  recurringClusterCount: number;
-  clusters: DocsAgentFeedbackCluster[];
-  goldenTasks: DocsAgentGoldenTask[];
-  issueDrafts: DocsAgentFeedbackIssueDraft[];
-  pullRequestDraft: {
-    title: string;
-    body: string;
-  };
-}
-declare function analyzeDocsAgentFeedback(feedback: readonly DocsAgentFeedbackData[], options?: DocsAgentFeedbackImprovementOptions): DocsAgentFeedbackImprovementReport;
-declare function readDocsAgentFeedbackFile(filePath: string): DocsAgentFeedbackData[];
-//#endregion
-//#region src/code-blocks.d.ts
-interface DocsCodeBlockTarget {
-  id: string;
-  filePath: string;
-  relativePath: string;
-  lineStart: number;
-  lineEnd: number;
-  language?: string;
-  title?: string;
-  framework?: string;
-  packageManager?: string;
-  runnable: boolean;
-  env: string[];
-  meta: Record<string, string | boolean>;
-  code: string;
-}
-interface DocsCodeBlockCommand {
-  cmd: string;
-  args: string[];
-}
-interface DocsCodeBlockExecutionPlan {
-  id: string;
-  target: DocsCodeBlockTarget;
-  action: "execute" | "validate-syntax" | "skip";
-  template: string;
-  runtime?: string;
-  filePath?: string;
-  command?: DocsCodeBlockCommand;
-  requiredEnv: string[];
-  reason?: string;
-  planner: DocsCodeBlocksPlannerProvider;
-}
-type DocsCodeBlockValidationStatus = "PLAN" | "PASS" | "SKIP" | "FAIL";
-interface DocsCodeBlockValidationResult {
-  id: string;
-  target: DocsCodeBlockTarget;
-  plan: DocsCodeBlockExecutionPlan;
-  status: DocsCodeBlockValidationStatus;
-  stdout?: string;
-  stderr?: string;
-  exitCode?: number | null;
-  reason?: string;
-}
-type OptionalModuleImporter = (specifier: string) => Promise<unknown>;
-declare global {
-  var __DOCS_CODE_BLOCKS_MODULE_IMPORTER__: OptionalModuleImporter | undefined;
-}
-//#endregion
-//#region src/agent-evals.d.ts
-type DocsGoldenEvaluationStatus = "unmeasured" | "passed" | "failed";
-type DocsGoldenEvaluationCoverageStatus = "measured" | "partially-measured" | "unmeasured" | "not-applicable";
-type DocsGoldenTaskFilters = DocsAgentGoldenTaskFilters;
-type DocsGoldenExpectedExample = DocsAgentGoldenExpectedExample;
-type DocsGoldenTaskExpectation = DocsAgentGoldenTaskExpectation;
-type DocsGoldenTask = DocsAgentGoldenTask;
-interface DocsGoldenRetrievedSource {
-  rank: number;
-  url: string;
-  title: string;
-  framework?: string;
-  version?: string;
-  package?: string[];
-  tags?: string[];
-  utf8Bytes: number;
-  relevant: boolean;
-  truncated: boolean;
-}
-interface DocsGoldenRetrievalMetrics {
-  expectedRelevant: number;
-  retrievedRelevant: number;
-  recallAtK: number;
-  firstRelevantRank: number | null;
-  reciprocalRank: number;
-  forbiddenSources: string[];
-  passed: boolean;
-}
-interface DocsGoldenCitationMetrics {
-  /** Where the citation evidence came from. Context/results are not model-answer citations. */
-  evidence: "context" | "results";
-  expected: string[];
-  actual: string[];
-  missing: string[];
-  unexpected: string[];
-  precision: number;
-  recall: number;
-  /** True when every rendered Source line maps one-to-one to a returned source record. */
-  integrity: boolean;
-  passed: boolean;
-}
-interface DocsGoldenSelectionMetrics {
-  requestedFramework?: string;
-  requestedVersion?: string;
-  requestedPackage?: string | readonly string[];
-  requestedTags?: string | readonly string[];
-  requestedLocale?: string;
-  expectedFramework?: string;
-  expectedVersion?: string;
-  expectedPackage?: string | readonly string[];
-  expectedTags?: string | readonly string[];
-  expectedLocale?: string;
-  firstFrameworkMatchRank: number | null;
-  firstVersionMatchRank: number | null;
-  firstPackageMatchRank?: number | null;
-  firstTagsMatchRank?: number | null;
-  firstLocaleMatchRank: number | null;
-  conflictingSources: string[];
-  ambiguousSources: string[];
-  passed: boolean;
-}
-interface DocsGoldenExampleResult {
-  expected: DocsGoldenExpectedExample;
-  matchedId?: string;
-  source?: string;
-  verification: "present" | "syntax" | "execute";
-  status: "passed" | "failed" | "skipped";
-  reason?: string;
-  syntaxValid: boolean;
-  executed: boolean;
-  executionStatus?: DocsCodeBlockValidationResult["status"];
-  /** @deprecated Static/planner executability signal retained for report compatibility. */
-  executable: boolean;
-  passed: boolean;
-}
-interface DocsGoldenExampleMetrics {
-  expected: number;
-  matched: number;
-  syntaxValid: number;
-  executed: number;
-  /** @deprecated Count of statically/planner-executable examples retained for compatibility. */
-  executable: number;
-  results: DocsGoldenExampleResult[];
-  passed: boolean;
-}
-interface DocsGoldenUsageMetrics {
-  budgetUnit: "utf8-bytes";
-  tokenBudget: number;
-  usedUtf8Bytes: number;
-  remainingUtf8Bytes: number;
-  estimatedTokens: number;
-  /** Exact conservative upper bound: one token per UTF-8 byte. */
-  conservativeTokenUpperBound: number;
-  usefulUtf8Bytes: number;
-  usefulByteRatio: number;
-  truncated: boolean;
-  withinBudget: boolean;
-  passed: boolean;
-}
-interface DocsGoldenAnswerMetrics {
-  evidence: "answer";
-  expected: boolean;
-  provided: boolean;
-  textIncludesMissing: string[];
-  textExcludesPresent: string[];
-  citations: string[];
-  requiredCitations: string[];
-  missingCitations: string[];
-  unexpectedCitations: string[];
-  forbiddenCitations: string[];
-  passed: boolean;
-}
-type DocsGoldenSafetyCaseKind = "prompt-injection" | "poisoned-citations" | "authenticated-content" | "freshness" | "framework-version-conflict" | "deleted-section-tombstones";
-interface DocsGoldenSafetyCaseResult {
-  kind: DocsGoldenSafetyCaseKind;
-  passed: boolean;
-  issues: string[];
-}
-interface DocsGoldenQueryVariantResult {
-  kind: DocsAgentGoldenQueryVariant["kind"];
-  query: string;
-  passed: boolean;
-  score: number;
-  firstRelevantRank: number | null;
-  citationIntegrity: boolean;
-  issues: string[];
-}
-interface DocsGoldenSafetyMetrics {
-  expected: boolean;
-  passed: boolean;
-  cases: DocsGoldenSafetyCaseResult[];
-  queryVariants: DocsGoldenQueryVariantResult[];
-}
-interface DocsGoldenTaskReport {
-  id: string;
-  query: string;
-  surface: DocsAgentEvaluationSurface;
-  provider: string;
-  status: "passed" | "failed";
-  passed: boolean;
-  score: number;
-  context: string;
-  sources: DocsGoldenRetrievedSource[];
-  retrieval: DocsGoldenRetrievalMetrics;
-  citations: DocsGoldenCitationMetrics;
-  answer: DocsGoldenAnswerMetrics;
-  safety: DocsGoldenSafetyMetrics;
-  selection: DocsGoldenSelectionMetrics;
-  examples: DocsGoldenExampleMetrics;
-  usage: DocsGoldenUsageMetrics;
-  coverageApplicability: {
-    executableExamples: DocsAgentGoldenCoverageApplicability;
-  };
-  issues: string[];
-}
-interface DocsGoldenTasksReport {
-  status: DocsGoldenEvaluationStatus;
-  passed: boolean | null;
-  /** Compatibility alias for quality.score. */
-  score: number | null;
-  taskCount: number;
-  passedTaskCount: number;
-  failedTaskCount: number;
-  /** Quality across only the expectations configured by each task. */
-  quality: DocsGoldenEvaluationQuality;
-  /** Coverage is intentionally separate so absent evaluation dimensions cannot look perfect. */
-  coverage: DocsGoldenEvaluationCoverage;
-  tasks: DocsGoldenTaskReport[];
-}
-interface DocsGoldenEvaluationQuality {
-  status: DocsGoldenEvaluationStatus;
-  passed: boolean | null;
-  score: number | null;
-  taskCount: number;
-  passedTaskCount: number;
-  failedTaskCount: number;
-}
-interface DocsGoldenEvaluationDimensionCoverage {
-  status: DocsGoldenEvaluationCoverageStatus;
-  measuredTaskCount: number;
-  applicableTaskCount: number;
-  notApplicableTaskCount: number;
-  totalTaskCount: number;
-  coveragePercent: number;
-}
-interface DocsGoldenEvaluationCoverage {
-  status: DocsGoldenEvaluationCoverageStatus;
-  measuredTaskDimensions: number;
-  applicableTaskDimensions: number;
-  notApplicableTaskDimensions: number;
-  totalTaskDimensions: number;
-  coveragePercent: number;
-  dimensions: {
-    safety: DocsGoldenEvaluationDimensionCoverage;
-    answerQuality: DocsGoldenEvaluationDimensionCoverage;
-    executableExamples: DocsGoldenEvaluationDimensionCoverage;
-  };
-}
-interface RunDocsGoldenTasksOptions {
-  /** Default evaluation surface. Tasks may override this with `task.surface`. */
-  surface?: DocsAgentEvaluationSurface;
-  /** Search configuration used by configured-search and ask-ai-context. */
-  search?: boolean | DocsSearchConfig;
-  /** Production-resolved Ask AI retrieval config, including `ai.useMcp`. */
-  askAISearch?: boolean | DocsSearchConfig;
-  siteTitle?: string;
-  baseUrl?: string;
-  rootDir?: string;
-  /** Permit external configured search or HTTP answer calls. @default false */
-  allowNetwork?: boolean;
-  /** Per-attempt configured-search/Ask-AI retrieval timeout in milliseconds. @default 30000 */
-  searchTimeoutMs?: number;
-  /** Project code-block validation config used only by explicit execute expectations. */
-  codeBlocksValidate?: boolean | DocsCodeBlocksValidateConfig;
-  /** Optional actual-answer runner. No model or HTTP request is made when omitted. */
-  answer?: DocsAgentEvaluationAnswerProvider;
-}
-declare function runDocsGoldenTasks(pages: readonly DocsMcpPage[], tasks: readonly DocsGoldenTask[] | undefined, options?: RunDocsGoldenTasksOptions): Promise<DocsGoldenTasksReport>;
-//#endregion
-//#region src/prompt-utils.d.ts
-type PromptAction = "copy" | "open";
-interface SerializedOpenDocsProvider {
-  name: string;
-  iconHtml?: string;
-  urlTemplate: string;
-  promptUrlTemplate?: string;
-  target?: OpenDocsTarget;
-  prompt?: string;
-}
-interface PromptProviderChoice {
-  name: string;
-  iconHtml?: string;
-  urlTemplate: string;
-}
-type PromptProviderInput = Pick<SerializedOpenDocsProvider, "name" | "iconHtml"> & Partial<Pick<SerializedOpenDocsProvider, "promptUrlTemplate" | "urlTemplate">>;
-interface SerializeOpenDocsProviderOptions {
-  target?: OpenDocsTarget;
-  prompt?: string;
-}
-declare const DEFAULT_PROMPT_PROVIDER_TEMPLATES: Record<string, string>;
-declare const DEFAULT_OPEN_DOCS_TARGET: OpenDocsTarget;
-declare const DEFAULT_OPEN_DOCS_PROMPT = "Read this documentation: {url}";
-declare const DEFAULT_OPEN_DOCS_PROVIDER_IDS: readonly ["chatgpt", "claude"];
-declare function normalizePromptProviderName(name: string): string;
-declare function serializeDocsIcon(icon: unknown): string | undefined;
-declare function serializeDocsIconRegistry(icons?: Record<string, unknown>): Record<string, string> | undefined;
-declare function serializeOpenDocsProviders(providers?: OpenDocsProvider[], options?: SerializeOpenDocsProviderOptions): SerializedOpenDocsProvider[] | undefined;
-declare function serializeOpenDocsProvider(provider: OpenDocsProvider, options?: SerializeOpenDocsProviderOptions): SerializedOpenDocsProvider | undefined;
-declare function parsePromptStringArray(value: unknown): string[] | undefined;
-declare function resolvePromptProviderChoices(availableProviders?: PromptProviderInput[], preferredNames?: string[]): PromptProviderChoice[];
-declare function sanitizePromptText(text: string): string;
-//#endregion
-//#region src/pagination.d.ts
-declare class DocsPaginationCursorError extends Error {
-  readonly code = "invalid_cursor";
-  constructor();
-}
-//#endregion
-//#region src/retrieval-digest.d.ts
-/** Validate the bounded HTTP(S) URL or root-relative URI reference used by provenance. */
-declare function isDocsRetrievalCanonicalUrl(value: string): boolean;
-/** Hash exact bytes with portable SHA-256 in Node, edge, and browser runtimes. */
-declare function sha256DocsContent(value: string | Uint8Array): string;
-/** Hash exact message-content bytes with portable SHA-256. */
-declare function digestDocsContent(value: string | Uint8Array): `sha256:${string}`;
-/**
- * Hash the normalized retrieval projection used by search provenance.
- *
- * The projection removes one leading BOM, normalizes line endings to LF, and trims
- * trailing whitespace. This deliberately differs from HTTP digests over exact bytes.
- */
-declare function digestDocsRetrievalContent(value: string): `sha256:${string}`;
-//#endregion
-export { readDocsAgentFeedbackFile as $, DocsGoldenExampleResult as A, DocsGoldenTaskExpectation as B, DocsGoldenCitationMetrics as C, DocsGoldenEvaluationQuality as D, DocsGoldenEvaluationDimensionCoverage as E, DocsGoldenSafetyCaseKind as F, RunDocsGoldenTasksOptions as G, DocsGoldenTaskReport as H, DocsGoldenSafetyCaseResult as I, DocsAgentFeedbackCluster as J, runDocsGoldenTasks as K, DocsGoldenSafetyMetrics as L, DocsGoldenQueryVariantResult as M, DocsGoldenRetrievalMetrics as N, DocsGoldenEvaluationStatus as O, DocsGoldenRetrievedSource as P, analyzeDocsAgentFeedback as Q, DocsGoldenSelectionMetrics as R, DocsGoldenAnswerMetrics as S, DocsGoldenEvaluationCoverageStatus as T, DocsGoldenTasksReport as U, DocsGoldenTaskFilters as V, DocsGoldenUsageMetrics as W, DocsAgentFeedbackImprovementReport as X, DocsAgentFeedbackImprovementOptions as Y, DocsAgentFeedbackIssueDraft as Z, sanitizePromptText as _, DocsPaginationCursorError as a, serializeOpenDocsProvider as b, DEFAULT_OPEN_DOCS_TARGET as c, PromptProviderChoice as d, SerializeOpenDocsProviderOptions as f, resolvePromptProviderChoices as g, parsePromptStringArray as h, sha256DocsContent as i, DocsGoldenExpectedExample as j, DocsGoldenExampleMetrics as k, DEFAULT_PROMPT_PROVIDER_TEMPLATES as l, normalizePromptProviderName as m, digestDocsRetrievalContent as n, DEFAULT_OPEN_DOCS_PROMPT as o, SerializedOpenDocsProvider as p, DOCS_AGENT_FEEDBACK_IMPROVEMENT_FORMAT as q, isDocsRetrievalCanonicalUrl as r, DEFAULT_OPEN_DOCS_PROVIDER_IDS as s, digestDocsContent as t, PromptAction as u, serializeDocsIcon as v, DocsGoldenEvaluationCoverage as w, serializeOpenDocsProviders as x, serializeDocsIconRegistry as y, DocsGoldenTask as z };