@doxbrix/doxloop 0.1.5 → 0.2.0

package/dist/source-discovery.d.ts

@@ -0,0 +1,132 @@
+import { type LoadedOpenApi } from './openapi.js';
+import type { SourceBinding, SourceKind } from './types.js';
+declare const DISCOVERY_SCHEMA_VERSION: 1;
+export type DiscoveryEvidenceKind = 'package' | 'command' | 'export' | 'route' | 'operation' | 'configuration' | 'authentication' | 'authorization' | 'error' | 'event' | 'integration' | 'example' | 'test' | 'documentation' | 'asset';
+export interface DiscoveryEvidence {
+    source: string;
+    path: string;
+    kind: DiscoveryEvidenceKind;
+    label: string;
+    line?: number;
+    /**
+     * Set on rows read from an API contract (an OpenAPI or Swagger file). They
+     * all share the spec's path, so only the operation, schema, or scheme
+     * named in the label documents them; citing the spec file as a whole must
+     * not mark the entire API as covered.
+     */
+    contract?: true;
+}
+export interface SourceDiscoveryResult {
+    name: string;
+    kind: SourceKind;
+    location: string;
+    revision: string | null;
+    filesScanned: number;
+    filesAvailable: number;
+    truncated: boolean;
+    languages: string[];
+    packageNames: string[];
+    evidence: DiscoveryEvidence[];
+    /**
+     * English UI message catalogs (for example `src/lang/en.json` or
+     * `public/intl/messages/en-US.json`). Authors quote displayed strings from
+     * these files instead of translation keys or guessed labels.
+     */
+    uiLabelCatalogs: string[];
+    warnings: string[];
+    scope?: SourceBinding['scope'];
+}
+export interface DocumentationDiscoveryInventory {
+    schemaVersion: typeof DISCOVERY_SCHEMA_VERSION;
+    cacheKey: string;
+    generatedAt: string;
+    sources: SourceDiscoveryResult[];
+    existingPages: string[];
+    navigationFiles: string[];
+    totals: {
+        sources: number;
+        filesScanned: number;
+        publicSignals: number;
+        existingPages: number;
+    };
+    suggestedPages: {
+        starter: number;
+        standard: number;
+        comprehensive: number;
+    };
+}
+export interface DiscoveryResult {
+    inventory: DocumentationDiscoveryInventory;
+    cacheHit: boolean;
+}
+/**
+ * Build a bounded, deterministic public-surface inventory. The cache key is
+ * derived from configured sources, safe source fingerprints, and discovery
+ * rules so unchanged sources do not consume another planning pass.
+ */
+export declare function discoverDocumentationSources(root: string): Promise<DiscoveryResult>;
+/**
+ * The inventory as the planner reads it: grouped text instead of one JSON
+ * line. The same JSON for a mid-sized product ran to 120k characters and was
+ * re-sent on every planning turn; grouping rows by kind and file keeps every
+ * citation (source, path, kind, label, line) at a fraction of the size.
+ */
+export declare function formatDiscoveryInventory(inventory: DocumentationDiscoveryInventory): string;
+/**
+ * Signals for one API contract: the product, every operation, schema,
+ * security scheme, documented 4xx/5xx response, and webhook. Shared by
+ * OpenAPI sources and by specs found inside a repository.
+ */
+export declare function openApiEvidence(source: string, path: string, loaded: Pick<LoadedOpenApi, 'document' | 'summary' | 'snapshot'>): DiscoveryEvidence[];
+/**
+ * Which part of the product a file belongs to. Only product code contributes
+ * keyword-derived public-surface signals: prose, fixtures, tests, and examples
+ * mention authentication, roles, and integrations constantly without being
+ * reader-facing behavior, and counting every such line turned a 16-page site
+ * into a "30% covered" one with a hundred junk gaps to resolve by hand.
+ */
+export type SourceFileRole = 'code' | 'infrastructure' | 'documentation' | 'test' | 'example' | 'fixture' | 'asset' | 'other';
+export declare function classifySourceFile(path: string): SourceFileRole;
+/** Keyword-derived signal kinds, counted once per folder rather than per file. */
+export declare const KEYWORD_SIGNAL_KINDS: ReadonlySet<DiscoveryEvidenceKind>;
+/** Build and shell variables every toolchain reads; not product configuration. */
+export declare const TOOLCHAIN_ENV: RegExp;
+/**
+ * The module a file belongs to, for counting keyword signals once per module:
+ * a folder at most three levels deep, or four inside a monorepo's
+ * `packages/<name>/src/<module>`. A page citing any file in the module covers
+ * it. Shared by discovery and coverage so both group the same way.
+ */
+export declare function signalModule(path: string): string;
+/**
+ * Framework-owned HTTP routes that no `app.get(...)` line declares. A Next.js
+ * App Router handler lives at `app/api/users/[id]/route.ts` and exports one
+ * function per method, so the route is derived from the file path.
+ */
+export declare function frameworkRoutes(path: string, content: string): string[];
+/**
+ * Evidence-derived page estimates. Comprehensive scales with the public
+ * surface instead of stopping at a fixed ceiling: a product with sixty
+ * commands, routes, and configuration groups needs more than thirty pages, and
+ * the reviewer can raise or lower the target page count on the plan anyway.
+ */
+export declare const MAXIMUM_SUGGESTED_PAGES = 120;
+export declare function suggestedPageCounts(signals: number, existingPages: number): {
+    starter: number;
+    standard: number;
+    comprehensive: number;
+};
+/**
+ * Keyword signals ("this file mentions OAuth") count once per folder and
+ * family: a module that authenticates is one surface to document, not one
+ * per file. The signal's path is the folder, and its label names the
+ * keywords found there, so the gap reads as "Authentication in apis".
+ */
+export declare function groupKeywordSignals(items: DiscoveryEvidence[]): DiscoveryEvidence[];
+/**
+ * What the planner must know about the inventory beyond its rows: which
+ * files hold the strings readers see, and whether the inventory is partial.
+ */
+export declare function discoveryGuidance(discovery: DocumentationDiscoveryInventory): string;
+export {};
+//# sourceMappingURL=source-discovery.d.ts.map