@sdt-tools/cli 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,393 @@
+import { Command } from 'commander';
+
+declare function initCommand(): Command;
+
+declare function buildCommand(): Command;
+
+declare function extractCommand(): Command;
+
+declare function compareCommand(): Command;
+
+declare function publishCommand(): Command;
+
+declare function driftCommand(): Command;
+
+/**
+ * `sdt validate` — schema-shape sanity check on a `.sdtproj`. Default
+ * mode confirms the project file parses, scope resolves, and object
+ * files discover successfully. The `--references` flag adds the
+ * Microsoft-SSDT-style build-time semantic resolution: every object reference in every
+ * project body is classified as resolved / dangling / external /
+ * temporary / dynamic, with warnings for unresolved references.
+ *
+ * Column-level resolution is Phase 2 (BACKLOG-tracked).
+ */
+declare function validateCommand(): Command;
+
+declare function connectionCommand(): Command;
+
+/**
+ * Placeholder factory for commands whose backing engine is a later
+ * deliverable. Prints a clear "not yet implemented" message and exits
+ * non-zero so CI notices.
+ *
+ * Mirrors `ddt scaffold` — exported for embedders, not wired into the
+ * SDT CLI itself.
+ */
+declare function scaffoldCommand(name: string): Command;
+
+/**
+ * `sdt graph` — emit an object-dependency DAG (Mermaid or DOT) from a
+ * `.sdtproj` or `.sdtpac`. Lets reviewers see blast radius before a
+ * drop. Inspired by DBeaver's "Object References" panel — but at the
+ * cross-object level rather than column level.
+ *
+ * With `--compare-to <other-source>`, diffs the two graphs and (when
+ * `--explain` is on) narrates the DAG changes in plain English — the
+ * AI Phase 6 "lineage explanation" surface.
+ *
+ * Mirrors `ddt graph`.
+ */
+declare function graphCommand(): Command;
+
+declare function historyCommand(): Command;
+
+/**
+ * `sdt verify <pac>` — recompute checksums and confirm the .sdtpac is
+ * intact. Catches tampering / corruption / partial-extraction
+ * accidents. Sets up the Enterprise-tier signing chain — a signed pac
+ * is `verify` + `signature-check` together.
+ */
+declare function verifyCommand(): Command;
+
+declare function installHooksCommand(): Command;
+
+/**
+ * `sdt script` — generate a deploy SQL script for source → target. Mirrors
+ * SqlPackage `/Action:Script` / SSDT's "Generate Script" affordance. Always
+ * offline — does not touch a live Snowflake account.
+ *
+ * Output formats:
+ *   - sql  (default): human-readable migration script with banner comments
+ *   - json:           raw CompareResult + safety assessment + per-statement
+ *                     metadata, suitable for CI gates or UI rendering
+ *
+ * Mirrors `ddt script`. To compare against a live account, use
+ * `sdt compare` or `sdt publish`.
+ */
+declare function scriptCommand(): Command;
+
+/**
+ * `sdt revert --manifest <path>` — undo a previous deploy by executing
+ * each step's `reverseSql` in reverse order. Manifests come from
+ * `sdt publish --apply --manifest <path>` (the JSON deploy manifest
+ * captured after `--apply`).
+ *
+ * Steps without `reverseSql` are inherently irreversible (DROP, etc.)
+ * and skipped with a clear warning. The command exits non-zero if any
+ * reverse fails or if any step was irreversible (the user must inspect
+ * by hand).
+ *
+ * Mirrors `Databricks/packages/cli/src/commands/revert.ts`. Use case: a
+ * deploy succeeded but something downstream broke; revert it. Use case:
+ * drift is detected and you need to roll back to the last-known-good
+ * state.
+ */
+declare function revertCommand(): Command;
+
+/**
+ * `sdt seed` — declare static reference rows next to DDL; engine
+ * generates MERGE statements to keep them in sync.
+ *
+ * Mirrors `Databricks/packages/cli/src/commands/seed.ts`. Subcommands:
+ *   list                       enumerate seed files + row counts
+ *   render -p <project>        emit MERGEs to stdout (offline)
+ *   apply  -p <project> -c <conn>  execute the MERGEs against an account
+ */
+declare function seedCommand(): Command;
+
+/**
+ * `sdt lineage` — extract data-flow lineage from a `.sdtproj` or
+ * `.sdtpac` and emit it as Mermaid, DOT, JSON, or Markdown.
+ *
+ * Distinct from `sdt graph`: graph is FQN-level dependency edges
+ * (A references B). Lineage adds direction-of-data-flow classification
+ * (READS_FROM vs WRITES_TO), upstream/downstream traversal, and
+ * column-level best-effort tagging for view SELECT lists.
+ *
+ * Use cases:
+ *   - "What does ANALYTICS.GOLD.CUSTOMER_360 depend on?" (upstream slice)
+ *   - "If I drop RAW.STAGING.ORDERS_RAW, what breaks?" (downstream slice)
+ *   - "Embed this graph in our PR template / docs / dashboard."
+ *
+ * Mirrors `ddt lineage`.
+ */
+declare function lineageCommand(): Command;
+
+/**
+ * `sdt diagnose` — project-level health report. Bundles lint, lineage
+ * smells (orphan / no-downstream / hot-table / cycle), object smells
+ * (`SELECT *` in views, large tables without clustering, missing PK)
+ * and cost smells (warehouse without AUTO_SUSPEND, long Time Travel)
+ * into one ranked report. Every finding ships with a **reasoning**
+ * line explaining *why* it matters — readers learn the engineering
+ * motivation, not just the patch.
+ *
+ * Use cases:
+ *   - Pre-PR check: `sdt diagnose --source <proj> --min-severity warning`
+ *   - Periodic project audit: weekly cron emitting JSON to a dashboard
+ *   - Onboarding: a new engineer reads the report to learn what good
+ *     looks like in this codebase
+ *
+ * Mirrors `ddt diagnose`.
+ */
+declare function diagnoseCommand(): Command;
+
+/**
+ * `sdt review` — produce a senior-DBA Markdown report combining lint,
+ * lineage findings, smell findings, cost findings, and safety
+ * reasoning. The deliverable a reviewer can paste straight into a PR
+ * or an architecture-review meeting.
+ *
+ * Default mode (project health): pure composition of existing modules —
+ * every finding's reasoning + suggestion is generated by
+ * `@sdt-tools/core/diagnostics`; the format is the value-add.
+ *
+ * `--senior-dba` mode (AI Phase 4): takes a compare-result JSON
+ * (typically the output of `sdt compare --json`) + a safety-summary
+ * JSON + optional target-metadata snapshot + truncated DDL preview,
+ * asks the configured AI provider for a senior-DBA verdict, and emits
+ * the parsed result as Markdown (or JSON via `--format json`).
+ */
+declare function reviewCommand(): Command;
+
+/**
+ * `sdt impact <fqn>` — single-FQN blast-radius answer. "If I change
+ * this, what breaks? What feeds it? What pending diagnostics
+ * touch it?" Composition of `@sdt-tools/core/lineage` (upstream/downstream)
+ * and `@sdt-tools/core/diagnostics` (findings filtered to the FQN).
+ *
+ * Output is Markdown by default; `--format json` returns a structured
+ * payload for CI integration.
+ */
+declare function impactCommand(): Command;
+
+/**
+ * `sdt cost-estimate` — static heuristic estimator for the Snowflake
+ * credits a migration script will consume when applied.
+ *
+ * Approach: classify each statement by its observable cost-class
+ * (TABLE rebuild, CREATE OR REPLACE VIEW, ADD COLUMN, ALTER TYPE,
+ * dynamic-table refresh, etc.) and assign a credit-band estimate per
+ * class. Estimates are intentionally **ranges** rather than point
+ * values because actual cost depends on row count, warehouse size,
+ * and data layout — we don't pretend otherwise.
+ *
+ * The framing alone is uniquely valuable: no other Snowflake schema
+ * tool surfaces "this migration will roughly cost X credits at S
+ * warehouse" before you apply it.
+ *
+ * The classifier is regex-based and conservative — when a statement
+ * doesn't match a known cost-class it's reported as
+ * "unknown / negligible" so the user knows the estimate didn't see it.
+ */
+declare function costEstimateCommand(): Command;
+
+/**
+ * `sdt pr-comment` — produce a Markdown PR sticky-comment from a
+ * source↔target compare. Bundles the diff summary, reversibility-
+ * grouped safety findings, project health diagnostics, and a
+ * collapsible per-object changelog into a single deliverable a CI
+ * step can POST as a pull-request comment.
+ *
+ * Distinct from `sdt review`: `review` is project-only, `pr-comment`
+ * is change-driven (here's what's *in this PR*).
+ */
+declare function prCommentCommand(): Command;
+
+/**
+ * `sdt template <kind> <name>` — schema cookbook generator. Produces
+ * a complete set of `.sql` files implementing a common pattern, ready
+ * to drop into a `.sdtproj`'s object tree. Saves a junior engineer
+ * from re-inventing the SCD2 pattern from scratch.
+ *
+ * Supported kinds:
+ *   - `scd1`         — Slowly-changing-dimension type-1 (overwrite, no history).
+ *   - `scd2`         — Slowly-changing-dimension type-2 (history-preserving).
+ *   - `scd3`         — Slowly-changing-dimension type-3 (one previous value).
+ *   - `scd4`         — Slowly-changing-dimension type-4 (current + history table).
+ *   - `scd6`         — Hybrid 1+2+3 (current + valid_from/to + previous value).
+ *   - `star`         — Star schema fact + N dimensions.
+ *   - `fact`         — Fact table only, with surrogate-key FKs to named dims.
+ *   - `scd2-merge`   — Canonical MERGE statement to load an SCD2 dimension.
+ *   - `current-view` — `CREATE VIEW` over an SCD2 table where IS_CURRENT = TRUE.
+ *   - `time-series`  — Hash-partitioned time-series with retention.
+ *   - `audit`        — Generic audit-log table with append-only constraints.
+ *
+ * Mirrors `ddt template`. Patterns are conservative: every template
+ * sets a PK, populates COMMENT fields, and prefers `CREATE OR ALTER`
+ * over `CREATE OR REPLACE` to play well with the safety classifier.
+ */
+declare function templateCommand(): Command;
+
+/**
+ * `sdt anonymize` — generate masking-policy DDL for PII columns
+ * discovered in a project model. Pairs with the L012 `pii-without-mask`
+ * lint rule: the lint surfaces *which* columns need masking; this
+ * command writes the policy DDL ready to copy into the project.
+ *
+ * Use case: refresh prod → dev pipeline. Most teams need to
+ * pseudonymize PII before any non-prod role sees the data. This
+ * command auto-generates a starter set of MASKING POLICY statements
+ * + the ALTER TABLE ... ALTER COLUMN ... SET MASKING POLICY calls
+ * to apply them.
+ *
+ * Output is intentionally **conservative**: every emitted policy has
+ * `RETURN VAL` (no-op) when the current role is in `('PROD_ETL')` so
+ * production keeps working as-is; every other role sees a hashed /
+ * redacted value. Adjust the role allow-list before applying.
+ */
+declare function anonymizeCommand(): Command;
+
+/**
+ * `sdt safety` — inspect safety-finding codes.
+ *
+ * Subcommands:
+ *   sdt safety list                       — list every known finding code with a one-line summary
+ *   sdt safety explain <code>             — deep explainer for a single code: why it is dangerous,
+ *                                           what cannot be reversed, safer alternatives, required gates
+ *
+ * The finding codes are stable identifiers attached to every `SafetyFinding`
+ * the classifier emits during `sdt compare` / `sdt publish`. When the user
+ * sees a finding they don't understand, they can copy the code and ask:
+ *
+ *     sdt safety explain DROP_UNRECOVERABLE
+ *
+ * See `docs/UX_PLAYBOOK.md` §3 (dangerous-op UX) and
+ * `docs/AI_FEATURES.md` use case C2.
+ */
+
+declare function safetyCommand(): Command;
+
+declare function saferAlternativeCommand(): Command;
+
+declare function sketchCommand(): Command;
+
+declare function compareProfilesCommand(): Command;
+
+/**
+ * `sdt explorer` — ASCII tree dump of the live db/schema/object hierarchy
+ * for a connected target, read from the EE1 catalog cache.
+ *
+ * The eventual VS Code TreeDataProvider walks the same `treeForSnapshot`
+ * shape; this CLI gives non-VS-Code users the same browsable view of the
+ * cached catalog. No live queries are issued — the cache is read-only.
+ * Run `sdt catalog refresh --connection <name>` first to populate it.
+ *
+ * Inputs:
+ *   --connection <name>   Required. Connection profile name to load the cache for.
+ *   --root <path>         Project root (where .sdt/cache/ lives). Default cwd.
+ *   --filter <query>      Typeahead filter; case-insensitive substring match.
+ *                         Keeps every ancestor of a leaf match.
+ *   --json                Emit the tree as JSON instead of an ASCII tree.
+ */
+
+declare function explorerCommand(): Command;
+
+/**
+ * `sdt catalog` — manage the per-connection catalog cache (EE1 substrate).
+ *
+ *   sdt catalog refresh --connection <name> [--databases <csv>] [--concurrency <n>]
+ *   sdt catalog show    --connection <name> [--json]
+ *   sdt catalog clear   --connection <name>
+ *
+ * `refresh` opens a live Snowflake connection, discovers databases via
+ * `SHOW DATABASES`, runs the bulk-scan SQL per database via the bounded
+ * promise pool, and writes the assembled snapshot to
+ * `<root>/.sdt/cache/<conn>/catalog.msgpack` (RES.1 — was `catalog.json`
+ * before 2026-05-16; the cache reader still accepts the legacy form for
+ * one major version). Schema fingerprints (`MAX(LAST_ALTERED)`) are
+ * checked first; databases that haven't changed since the last refresh
+ * are skipped.
+ *
+ * `show` reads the cache file and pretty-prints (or emits JSON).
+ * `clear` deletes the cache file (and its parent dir if empty).
+ *
+ * Object Explorer (`sdt explorer`) and the eventual EE2 intellisense
+ * provider both consume this cache.
+ */
+
+declare function catalogCommand(): Command;
+
+/**
+ * `sdt exec <file.sql> --profiles <list>` — AUTH.3.
+ *
+ * Runs a SQL script on one or more connection profiles in parallel and
+ * prints a merged report. Guarded against any profile whose name matches
+ * the word "prod" or "production" (case-insensitive) unless `--yes` is
+ * passed.
+ *
+ * Mirrors `Databricks/packages/cli/src/commands/exec.ts`.
+ */
+
+interface ExecResult {
+    profile: string;
+    status: 'success' | 'error';
+    rowsAffected?: number;
+    durationMs: number;
+    error?: string;
+}
+type ExecFn = (profile: string, sql: string, timeoutMs: number) => Promise<Omit<ExecResult, 'profile' | 'durationMs'>>;
+declare function execCommand(execFn?: ExecFn): Command;
+
+/**
+ * `sdt search <pattern> --profiles <list|all>` — AUTH.4.
+ *
+ * Finds objects whose name matches a pattern across one or more connection
+ * profiles. Surfaces presence/absence drift: if an object exists in some
+ * profiles but not others, those profiles are flagged.
+ *
+ * The search is case-insensitive substring match by default; --exact
+ * switches to exact name match; --type filters by objectType.
+ *
+ * Mirrors `Databricks/packages/cli/src/commands/search.ts`.
+ */
+
+interface SearchMatch {
+    profile: string;
+    fqn: string;
+    objectType: string;
+}
+interface SearchResult {
+    profile: string;
+    matches: SearchMatch[];
+    error?: string;
+}
+interface SearchFnOptions {
+    exact: boolean;
+    objectType?: string;
+    /** Project / cache root. Defaults to `process.cwd()`. */
+    root?: string;
+}
+type SearchFn = (profile: string, pattern: string, opts: SearchFnOptions) => Promise<SearchMatch[]>;
+declare function searchCommand(searchFn?: SearchFn): Command;
+
+/**
+ * `sdt query-log` — AUTH.5 local query log CLI.
+ *
+ * Subcommands:
+ *   sdt query-log list [--profile <p>] [--limit N] [--format text|json]
+ *   sdt query-log show <id> [--format text|json|sql]
+ *   sdt query-log add <sql> --profile <p> [--status success|error] [--store <path>]
+ *   sdt query-log clear [--profile <p>] [--yes]
+ *
+ * The log is stored at `~/.sdt/query-log.json` (override with --store).
+ * EE3 will call `appendEntry()` on the substrate directly when a query
+ * is executed. This CLI surfaces it for ad-hoc review + rerun.
+ *
+ * Mirrors `Databricks/packages/cli/src/commands/query-log.ts`.
+ */
+
+declare function queryLogCommand(): Command;
+
+export { type ExecFn, type ExecResult, type SearchFn, type SearchMatch, type SearchResult, anonymizeCommand, buildCommand, catalogCommand, compareCommand, compareProfilesCommand, connectionCommand, costEstimateCommand, diagnoseCommand, driftCommand, execCommand, explorerCommand, extractCommand, graphCommand, historyCommand, impactCommand, initCommand, installHooksCommand, lineageCommand, prCommentCommand, publishCommand, queryLogCommand, revertCommand, reviewCommand, saferAlternativeCommand, safetyCommand, scaffoldCommand, scriptCommand, searchCommand, seedCommand, sketchCommand, templateCommand, validateCommand, verifyCommand };