@duckcodeailabs/dql-agent 1.6.21 → 1.6.23

package/dist/propose/propose.d.ts

@@ -0,0 +1,226 @@
+/**
+ * `dql propose` engine — turn dbt evidence into a ranked queue of DRAFT blocks.
+ *
+ * Product principle: **AI drafts, humans certify.** A new user should not author
+ * DQL from a blank file. This engine scans dbt artifacts and proposes a draft
+ * governance layer: one `block` per high-value model, born `status: draft`, run
+ * through the Certifier (results stored so a reviewer sees "what's missing to
+ * certify"), and demand-ranked by downstream value.
+ *
+ * Hard rules enforced here:
+ *   - Nothing is ever emitted with `status: certified`. Promotion is a separate
+ *     human action (`dql certify --from-draft`).
+ *   - Re-running is idempotent: an existing draft / certified / review block for
+ *     the same model is never overwritten or duplicated.
+ *   - Inference is conservative — grain/pattern/outputs are only set when the
+ *     evidence is obvious, and invariants are limited to provably-safe checks.
+ */
+import { type Classification } from './classify.js';
+import { type ProposeConfig, type ProposeConfigInput } from './config.js';
+import type { EnrichedContent } from './enrich.js';
+export interface ProposeOptions {
+    projectRoot: string;
+    dbtManifestPath: string;
+    /** Default owner stamped on drafts (reviewer fills in if blank). */
+    owner?: string;
+    /**
+     * Cap on the number of drafts written in one run. Keeps the queue reviewable
+     * on large dbt projects. undefined = no cap.
+     */
+    limit?: number;
+    /**
+     * When true, score and rank but do not write any files. Useful for previews.
+     */
+    dryRun?: boolean;
+    /**
+     * Set of model/block slugs that already exist in the project (drafts or
+     * certified). When omitted, the engine derives it by checking the filesystem.
+     * Injectable for tests.
+     */
+    existingBlockSlugs?: Set<string>;
+    /**
+     * Optional `propose` config block (from `dql.config.json`). Refines the
+     * classifier conventions, bounded selection, and AI-enrichment toggle.
+     * Defaults apply for every field when omitted.
+     */
+    config?: ProposeConfigInput | null;
+    /**
+     * When provided, restrict generation to exactly these block slugs (the human
+     * "approved scope"). Pass 1 classification still scans all models; only the
+     * selected, approved slugs are inferred + certified + written. Reuses the
+     * same bounded-selection path otherwise.
+     */
+    onlySlugs?: string[];
+    /**
+     * Optional pre-computed AI enrichment (keyed by slug), produced asynchronously
+     * by the generate path. When present for a slug, its `description`/`llmContext`/
+     * `examples` override the deterministic dbt-derived content. The engine never
+     * calls a provider itself — enrichment is consumed here as plain data, so
+     * `propose()` stays sync, deterministic, and offline-safe.
+     */
+    enrichedBySlug?: Map<string, EnrichedContent>;
+}
+export type ProposedPattern = 'entity_profile' | 'metric_wrapper' | 'entity_rollup' | 'trend' | 'custom';
+export interface ProposalInference {
+    pattern: ProposedPattern;
+    grain?: string;
+    declaredOutputs: string[];
+    entities: string[];
+    llmContext?: string;
+    invariants: string[];
+    examples: Array<{
+        question: string;
+        sql?: string;
+    }>;
+    tags: string[];
+}
+export interface ProposalRanking {
+    /** Number of dbt models that depend on this model (downstream fan-out). */
+    fanOut: number;
+    /** Whether a dbt exposure references this model. */
+    exposureLinked: boolean;
+    /** Recorded runs from run_results.json (0 when unavailable). */
+    runCount: number;
+    /** Composite score used to order the queue (higher = more valuable). */
+    score: number;
+}
+export interface ProposalResult {
+    model: string;
+    slug: string;
+    domain: string;
+    /** Deterministic business-layer classification (business | plumbing | niche). */
+    classification: Classification;
+    /** Human-readable signals that drove the classification + selection. */
+    evidence: string[];
+    /** Owner derived from dbt meta, if present. */
+    owner?: string;
+    inference: ProposalInference;
+    ranking: ProposalRanking;
+    /** Path written (relative to projectRoot), or undefined when skipped/dry-run. */
+    path?: string;
+    /** Why a draft was skipped (already exists), if applicable. */
+    skipped?: string;
+    /** Stored Certifier verdict so a reviewer sees what's missing to certify. */
+    certification: {
+        certified: false;
+        errors: Array<{
+            rule: string;
+            message: string;
+        }>;
+        warnings: Array<{
+            rule: string;
+            message: string;
+        }>;
+    };
+}
+export interface ProposeSummary {
+    projectName?: string;
+    modelsScanned: number;
+    /** Models classified `business` by the cascade. */
+    businessModels: number;
+    /** Models classified `plumbing` and excluded from generation. */
+    plumbingExcluded: number;
+    /** Semantic metrics discovered in the manifest. */
+    metricsFound: number;
+    proposalsRanked: number;
+    draftsWritten: number;
+    draftsSkipped: number;
+    /** Resolved propose config used for this run. */
+    config: ProposeConfig;
+    proposals: ProposalResult[];
+}
+/**
+ * Run the proposal engine end to end: load artifacts, classify (cheap pass),
+ * select a bounded business-only seed, then — for the selection ONLY — infer
+ * grain/pattern/outputs/invariants and run the Certifier, write drafts, and
+ * store verdicts. Returns a deterministic, ranked summary.
+ *
+ * Plumbing/niche models are EXCLUDED from generation (never written), and the
+ * expensive Pass-2 work (inference + Certifier) runs only on the bounded
+ * selection — at 10k models this is hundreds of inferences, not thousands.
+ */
+export declare function propose(options: ProposeOptions): ProposeSummary;
+export interface ProposePlanCandidate {
+    model: string;
+    slug: string;
+    score: number;
+    classification: Classification;
+    owner?: string;
+    /** Human-readable signals (e.g. "feeds 2 exposures", "marts/ folder"). */
+    evidence: string[];
+    /** Optional cheap-pass grain/pattern hints (may be omitted in the plan). */
+    grain?: string;
+    pattern?: ProposedPattern;
+    /**
+     * OPTIONAL "transparent preview" fields (spec 14, part A). Left undefined by
+     * the cheap `proposePlan()` so the plan stays O(N) and Certifier-free for all
+     * candidates. The `/api/propose/preview?slug=` endpoint fills them for ONE
+     * candidate by running real SQL generation + the Certifier + (best-effort) AI
+     * enrichment, so the UI can show the actual SQL/logic before a human commits.
+     */
+    sqlPreview?: string;
+    description?: string;
+    llmContext?: string;
+    examples?: string[];
+    outputs?: string[];
+    certifierVerdict?: {
+        blocking: string[];
+        warnings: string[];
+        ready: boolean;
+    };
+}
+export interface ProposePlanDomain {
+    name: string;
+    owner?: string;
+    modelCount: number;
+    candidates: ProposePlanCandidate[];
+}
+export interface ProposePlan {
+    totals: {
+        modelsScanned: number;
+        businessModels: number;
+        plumbingExcluded: number;
+        metricsFound: number;
+    };
+    willGenerate: number;
+    willSkip: number;
+    domains: ProposePlanDomain[];
+    /** Resolved propose config used to build the plan. */
+    config: ProposeConfig;
+}
+export interface ProposePlanOptions {
+    config?: ProposeConfigInput | null;
+    /** When true, omit cheap grain/pattern hints (pure classify-only plan). */
+    skipHints?: boolean;
+}
+/**
+ * Build a deterministic PLAN of what `propose` WOULD generate — and writes
+ * NOTHING. Reuses the cheap Pass-1 scan + bounded selection so the plan is an
+ * exact preview of the generated scope. Grain/pattern hints are cheap and
+ * optional (folder/column heuristics, no Certifier). Same input → same plan.
+ */
+export declare function proposePlan(projectRoot: string, dbtManifestPath: string, options?: ProposePlanOptions): ProposePlan;
+export interface ProposePreviewOptions {
+    config?: ProposeConfigInput | null;
+    /** Default owner for the Certifier verdict (so "Missing owner" is suppressed). */
+    owner?: string;
+    /**
+     * Optional pre-computed AI enrichment for this slug. When present, its
+     * description/llmContext/examples override the deterministic dbt-derived
+     * content. The engine never calls a provider itself.
+     */
+    enriched?: EnrichedContent;
+}
+/**
+ * Build the FILLED preview for a single candidate slug: real aggregation/
+ * projection SQL (via `buildBusinessQuery`, NOT select-*), declared outputs,
+ * description, llmContext, examples, and the Certifier verdict
+ * ({ blocking, warnings, ready }). Writes NOTHING.
+ *
+ * This is the lazy/expensive path: `proposePlan()` stays cheap for all
+ * candidates; this runs inference + SQL generation + the Certifier for ONE slug
+ * only. Returns `undefined` when the slug is not part of the bounded,
+ * business-only selection (so the caller can 404).
+ */
+export declare function buildProposePreview(projectRoot: string, dbtManifestPath: string, slug: string, options?: ProposePreviewOptions): ProposePlanCandidate | undefined;
+//# sourceMappingURL=propose.d.ts.map

package/dist/propose/propose.d.ts.map

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