@dbt-tools/core 0.3.2

package/dist/introspection/schema-generator.js

@@ -0,0 +1,275 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCommandSchema = getCommandSchema;
+exports.getAllSchemas = getAllSchemas;
+const ARG_MANIFEST_PATH = "manifest-path";
+const OPT_TARGET_DIR = "--target-dir";
+const OPT_JSON = "--json";
+const OPT_NO_JSON = "--no-json";
+const TYPE_STRING = "string";
+const TYPE_BOOLEAN = "boolean";
+const OUTPUT_JSON_OR_HUMAN = "json or human-readable";
+const DESC_MANIFEST_PATH = "Path to manifest.json file (defaults to ./target/manifest.json)";
+const DESC_TARGET_DIR = "Custom target directory (defaults to ./target)";
+const DESC_FORCE_JSON = "Force JSON output";
+const DESC_FORCE_HUMAN = "Force human-readable output";
+const DESC_FIELDS = "Comma-separated list of fields to include in response (e.g., unique_id,name)";
+const DESC_RUN_RESULTS_PATH = "Path to run_results.json file (defaults to ./target/run_results.json)";
+const DESC_MANIFEST_OPTIONAL = "Path to manifest.json file (optional, for critical path analysis)";
+function getSummarySchema() {
+    return {
+        command: "summary",
+        description: "Provide summary statistics for dbt manifest",
+        arguments: [
+            {
+                name: ARG_MANIFEST_PATH,
+                required: false,
+                description: DESC_MANIFEST_PATH,
+            },
+        ],
+        options: [
+            {
+                name: OPT_TARGET_DIR,
+                type: TYPE_STRING,
+                description: DESC_TARGET_DIR,
+            },
+            {
+                name: "--fields",
+                type: TYPE_STRING,
+                description: DESC_FIELDS,
+            },
+            {
+                name: OPT_JSON,
+                type: TYPE_BOOLEAN,
+                description: DESC_FORCE_JSON,
+            },
+            {
+                name: OPT_NO_JSON,
+                type: TYPE_BOOLEAN,
+                description: DESC_FORCE_HUMAN,
+            },
+        ],
+        output_format: OUTPUT_JSON_OR_HUMAN,
+        example: "dbt-tools summary",
+    };
+}
+function getGraphSchema() {
+    return {
+        command: "graph",
+        description: "Export dependency graph in various formats",
+        arguments: [
+            {
+                name: ARG_MANIFEST_PATH,
+                required: false,
+                description: DESC_MANIFEST_PATH,
+            },
+        ],
+        options: [
+            {
+                name: "--format",
+                type: "enum",
+                values: ["json", "dot", "gexf"],
+                default: "json",
+                description: "Export format",
+            },
+            {
+                name: "--output",
+                type: TYPE_STRING,
+                description: "Output file path (default: stdout)",
+            },
+            {
+                name: OPT_TARGET_DIR,
+                type: TYPE_STRING,
+                description: DESC_TARGET_DIR,
+            },
+            {
+                name: "--fields",
+                type: TYPE_STRING,
+                description: DESC_FIELDS,
+            },
+            {
+                name: "--field-level",
+                type: TYPE_BOOLEAN,
+                description: "Include field-level (column-level) lineage",
+            },
+            {
+                name: "--catalog-path",
+                type: TYPE_STRING,
+                description: "Path to catalog.json file",
+            },
+        ],
+        output_format: "json, dot, or gexf",
+        example: "dbt-tools graph --format dot --output graph.dot",
+    };
+}
+function getRunReportSchema() {
+    return {
+        command: "run-report",
+        description: "Generate execution report from run_results.json",
+        arguments: [
+            {
+                name: "run-results-path",
+                required: false,
+                description: DESC_RUN_RESULTS_PATH,
+            },
+            {
+                name: ARG_MANIFEST_PATH,
+                required: false,
+                description: DESC_MANIFEST_OPTIONAL,
+            },
+        ],
+        options: [
+            {
+                name: OPT_TARGET_DIR,
+                type: TYPE_STRING,
+                description: DESC_TARGET_DIR,
+            },
+            {
+                name: "--fields",
+                type: TYPE_STRING,
+                description: DESC_FIELDS,
+            },
+            {
+                name: "--bottlenecks",
+                type: TYPE_BOOLEAN,
+                description: "Include bottleneck section in report",
+            },
+            {
+                name: "--bottlenecks-top",
+                type: "number",
+                default: "10",
+                description: "Top N slowest nodes (default: 10 when --bottlenecks)",
+            },
+            {
+                name: "--bottlenecks-threshold",
+                type: "number",
+                description: "Nodes exceeding N seconds (alternative to top-N)",
+            },
+            {
+                name: OPT_JSON,
+                type: TYPE_BOOLEAN,
+                description: DESC_FORCE_JSON,
+            },
+            {
+                name: OPT_NO_JSON,
+                type: TYPE_BOOLEAN,
+                description: DESC_FORCE_HUMAN,
+            },
+        ],
+        output_format: OUTPUT_JSON_OR_HUMAN,
+        example: "dbt-tools run-report --bottlenecks",
+    };
+}
+function getDepsSchemaOptions() {
+    return [
+        {
+            name: "--direction",
+            type: "enum",
+            values: ["upstream", "downstream"],
+            default: "downstream",
+            description: "Direction of dependency traversal",
+        },
+        {
+            name: "--manifest-path",
+            type: TYPE_STRING,
+            default: "./target/manifest.json",
+            description: "Path to manifest.json file",
+        },
+        {
+            name: OPT_TARGET_DIR,
+            type: TYPE_STRING,
+            description: DESC_TARGET_DIR,
+        },
+        {
+            name: "--fields",
+            type: TYPE_STRING,
+            description: DESC_FIELDS,
+        },
+        {
+            name: "--field",
+            type: TYPE_STRING,
+            description: "Specific field (column) to trace dependencies for",
+        },
+        {
+            name: "--catalog-path",
+            type: TYPE_STRING,
+            description: "Path to catalog.json file",
+        },
+        {
+            name: "--depth",
+            type: "number",
+            description: "Max traversal depth; 1 = immediate neighbors, omit for all levels",
+        },
+        {
+            name: "--format",
+            type: "enum",
+            values: ["flat", "tree"],
+            default: "tree",
+            description: "Output structure: flat list or nested tree",
+        },
+        {
+            name: "--build-order",
+            type: TYPE_BOOLEAN,
+            description: "Output upstream dependencies in topological build order (only with --direction upstream)",
+        },
+        { name: OPT_JSON, type: TYPE_BOOLEAN, description: DESC_FORCE_JSON },
+        { name: OPT_NO_JSON, type: TYPE_BOOLEAN, description: DESC_FORCE_HUMAN },
+    ];
+}
+function getDepsSchema() {
+    return {
+        command: "deps",
+        description: "Get upstream or downstream dependencies for a dbt resource",
+        arguments: [
+            {
+                name: "resource-id",
+                required: true,
+                description: "Unique ID of the dbt resource (e.g., model.my_project.customers)",
+            },
+        ],
+        options: getDepsSchemaOptions(),
+        output_format: OUTPUT_JSON_OR_HUMAN,
+        example: "dbt-tools deps model.my_project.customers --direction downstream",
+    };
+}
+function getSchemaCommandSchema() {
+    return {
+        command: "schema",
+        description: "Get machine-readable schema for a command",
+        arguments: [
+            {
+                name: "command",
+                required: false,
+                description: "Command name (if omitted, returns all command schemas)",
+            },
+        ],
+        options: [
+            {
+                name: OPT_JSON,
+                type: TYPE_BOOLEAN,
+                description: DESC_FORCE_JSON,
+            },
+        ],
+        output_format: "json",
+        example: "dbt-tools schema deps",
+    };
+}
+/**
+ * Get schema for a specific command
+ */
+function getCommandSchema(command) {
+    const schemas = getAllSchemas();
+    return schemas[command] || null;
+}
+/**
+ * Get all command schemas
+ */
+function getAllSchemas() {
+    return {
+        summary: getSummarySchema(),
+        graph: getGraphSchema(),
+        "run-report": getRunReportSchema(),
+        deps: getDepsSchema(),
+        schema: getSchemaCommandSchema(),
+    };
+}

package/dist/io/artifact-loader.d.ts

@@ -0,0 +1,27 @@
+import type { ParsedManifest } from "dbt-artifacts-parser/manifest";
+import type { ParsedRunResults } from "dbt-artifacts-parser/run_results";
+import type { ParsedCatalog } from "dbt-artifacts-parser/catalog";
+/**
+ * Resolved artifact file paths
+ */
+export interface ArtifactPaths {
+    manifest: string;
+    runResults: string;
+    catalog?: string;
+}
+/**
+ * Resolve artifact paths, defaulting to ./target directory
+ */
+export declare function resolveArtifactPaths(manifestPath?: string, runResultsPath?: string, targetDir?: string, catalogPath?: string): ArtifactPaths;
+/**
+ * Load and parse manifest.json file
+ */
+export declare function loadManifest(manifestPath: string): ParsedManifest;
+/**
+ * Load and parse run_results.json file
+ */
+export declare function loadRunResults(runResultsPath: string): ParsedRunResults;
+/**
+ * Load and parse catalog.json file
+ */
+export declare function loadCatalog(catalogPath: string): ParsedCatalog;

package/dist/io/artifact-loader.js

@@ -0,0 +1,142 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveArtifactPaths = resolveArtifactPaths;
+exports.loadManifest = loadManifest;
+exports.loadRunResults = loadRunResults;
+exports.loadCatalog = loadCatalog;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const manifest_1 = require("dbt-artifacts-parser/manifest");
+const input_validator_1 = require("../validation/input-validator");
+const run_results_1 = require("dbt-artifacts-parser/run_results");
+const catalog_1 = require("dbt-artifacts-parser/catalog");
+const DEFAULT_TARGET_DIR = "./target";
+const MANIFEST_FILE = "manifest.json";
+const RUN_RESULTS_FILE = "run_results.json";
+const CATALOG_FILE = "catalog.json";
+function resolveManifestPath(manifestPath, targetDir) {
+    if (manifestPath) {
+        if (manifestPath.endsWith(".json")) {
+            return (0, input_validator_1.resolveSafePath)(manifestPath);
+        }
+        return path.join((0, input_validator_1.resolveSafePath)(manifestPath), MANIFEST_FILE);
+    }
+    const effectiveTargetDir = targetDir || process.env.DBT_TARGET_DIR || DEFAULT_TARGET_DIR;
+    return path.join((0, input_validator_1.resolveSafePath)(effectiveTargetDir), MANIFEST_FILE);
+}
+function resolveRunResultsPath(runResultsPath, targetDir) {
+    if (runResultsPath) {
+        if (runResultsPath.endsWith(".json")) {
+            return (0, input_validator_1.resolveSafePath)(runResultsPath);
+        }
+        return path.join((0, input_validator_1.resolveSafePath)(runResultsPath), RUN_RESULTS_FILE);
+    }
+    const effectiveTargetDir = targetDir || process.env.DBT_TARGET_DIR || DEFAULT_TARGET_DIR;
+    return path.join((0, input_validator_1.resolveSafePath)(effectiveTargetDir), RUN_RESULTS_FILE);
+}
+function resolveCatalogPath(catalogPath, targetDir) {
+    if (catalogPath) {
+        if (catalogPath.endsWith(".json")) {
+            return (0, input_validator_1.resolveSafePath)(catalogPath);
+        }
+        return path.join((0, input_validator_1.resolveSafePath)(catalogPath), CATALOG_FILE);
+    }
+    const effectiveTargetDir = targetDir || process.env.DBT_TARGET_DIR || DEFAULT_TARGET_DIR;
+    return path.join((0, input_validator_1.resolveSafePath)(effectiveTargetDir), CATALOG_FILE);
+}
+/**
+ * Resolve artifact paths, defaulting to ./target directory
+ */
+function resolveArtifactPaths(manifestPath, runResultsPath, targetDir, catalogPath) {
+    const effectiveTargetDir = targetDir || process.env.DBT_TARGET_DIR || DEFAULT_TARGET_DIR;
+    const resolved = {
+        manifest: resolveManifestPath(manifestPath, effectiveTargetDir),
+        runResults: resolveRunResultsPath(runResultsPath, effectiveTargetDir),
+        catalog: resolveCatalogPath(catalogPath, effectiveTargetDir),
+    };
+    return resolved;
+}
+/**
+ * Load and parse manifest.json file
+ */
+function loadManifest(manifestPath) {
+    const fullPath = (0, input_validator_1.resolveSafePath)(manifestPath);
+    if (!fs.existsSync(fullPath)) {
+        throw new Error(`Manifest file not found: ${fullPath}`);
+    }
+    const content = fs.readFileSync(fullPath, "utf-8");
+    try {
+        const manifestJson = JSON.parse(content);
+        return (0, manifest_1.parseManifest)(manifestJson);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse manifest file ${fullPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Load and parse run_results.json file
+ */
+function loadRunResults(runResultsPath) {
+    const fullPath = (0, input_validator_1.resolveSafePath)(runResultsPath);
+    if (!fs.existsSync(fullPath)) {
+        throw new Error(`Run results file not found: ${fullPath}`);
+    }
+    const content = fs.readFileSync(fullPath, "utf-8");
+    try {
+        const runResultsJson = JSON.parse(content);
+        return (0, run_results_1.parseRunResults)(runResultsJson);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse run results file ${fullPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Load and parse catalog.json file
+ */
+function loadCatalog(catalogPath) {
+    const fullPath = (0, input_validator_1.resolveSafePath)(catalogPath);
+    if (!fs.existsSync(fullPath)) {
+        throw new Error(`Catalog file not found: ${fullPath}`);
+    }
+    const content = fs.readFileSync(fullPath, "utf-8");
+    try {
+        const catalogJson = JSON.parse(content);
+        return (0, catalog_1.parseCatalog)(catalogJson);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse catalog file ${fullPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Resource types in dbt manifests
+ */
+export type DbtResourceType = "model" | "source" | "seed" | "snapshot" | "test" | "analysis" | "macro" | "exposure" | "metric" | "semantic_model" | "unit_test" | "field" | "function";
+/**
+ * Node attributes stored in the graph
+ */
+export interface GraphNodeAttributes {
+    unique_id: string;
+    resource_type: DbtResourceType;
+    name: string;
+    package_name: string;
+    path?: string;
+    original_file_path?: string;
+    tags?: string[];
+    description?: string;
+    parent_id?: string;
+    [key: string]: unknown;
+}
+/**
+ * Edge attributes stored in the graph
+ */
+export interface GraphEdgeAttributes {
+    dependency_type: "node" | "macro" | "source" | "field" | "internal";
+    [key: string]: unknown;
+}
+/**
+ * Summary statistics about the graph
+ */
+export interface GraphSummary {
+    total_nodes: number;
+    nodes_by_type: Record<string, number>;
+    total_edges: number;
+    has_cycles: boolean;
+}
+/**
+ * Version information extracted from a manifest
+ */
+export interface VersionInfo {
+    schema_version: number | null;
+    dbt_version: string | null;
+    is_supported: boolean;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/validation/input-validator.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Validate that a path does not contain traversal sequences
+ * Rejects paths like ../../.ssh or ..\\..\\etc
+ */
+export declare function validateSafePath(pathInput: string): void;
+/**
+ * Validate path and resolve to absolute. Use instead of path.resolve for user-controlled paths.
+ * Satisfies path-traversal audit: validation and resolve are coupled.
+ */
+export declare function resolveSafePath(pathInput: string): string;
+/**
+ * Ensure a resolved path is under a base directory (e.g. cwd).
+ * Call this after path.resolve() to prevent escaping the base via absolute paths or traversal.
+ */
+export declare function assertPathUnderBase(resolvedPath: string, baseDir: string): void;
+/**
+ * Validate that input does not contain control characters
+ * Allows \n (0x0A), \r (0x0D), and \t (0x09)
+ */
+export declare function validateNoControlChars(input: string): void;
+/**
+ * Validate that input does not contain pre-encoded URL strings
+ * Rejects strings like %2e%2e (encoded ..)
+ */
+export declare function validateNoPreEncoding(input: string): void;
+/**
+ * Validate a dbt resource ID
+ * Rejects embedded query params, URL fragments, and pre-encoded strings
+ */
+export declare function validateResourceId(id: string): void;
+/**
+ * Validate optional depth for traversal (e.g. deps --depth).
+ * Rejects NaN, non-integers, and values < 1 when depth is provided.
+ */
+export declare function validateDepth(depth: unknown): void;
+/**
+ * Validate a general string input (combines multiple validations)
+ */
+export declare function validateString(input: string, allowEmpty?: boolean): void;

package/dist/validation/input-validator.js

@@ -0,0 +1,167 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateSafePath = validateSafePath;
+exports.resolveSafePath = resolveSafePath;
+exports.assertPathUnderBase = assertPathUnderBase;
+exports.validateNoControlChars = validateNoControlChars;
+exports.validateNoPreEncoding = validateNoPreEncoding;
+exports.validateResourceId = validateResourceId;
+exports.validateDepth = validateDepth;
+exports.validateString = validateString;
+const path = __importStar(require("path"));
+/**
+ * Validate that a path does not contain traversal sequences
+ * Rejects paths like ../../.ssh or ..\\..\\etc
+ */
+function validateSafePath(pathInput) {
+    if (!pathInput || typeof pathInput !== "string") {
+        throw new Error("Path must be a non-empty string");
+    }
+    // Check for path traversal patterns
+    const normalized = pathInput.replace(/\\/g, "/");
+    if (normalized.includes("../") ||
+        normalized.includes("..\\") ||
+        normalized.startsWith("../") ||
+        normalized.includes("/../") ||
+        normalized.includes("\\..\\")) {
+        throw new Error(`Path traversal detected in path: ${pathInput}. Paths must not contain ../ or ..\\`);
+    }
+}
+/**
+ * Validate path and resolve to absolute. Use instead of path.resolve for user-controlled paths.
+ * Satisfies path-traversal audit: validation and resolve are coupled.
+ */
+function resolveSafePath(pathInput) {
+    validateSafePath(pathInput);
+    return path.resolve(pathInput);
+}
+/**
+ * Ensure a resolved path is under a base directory (e.g. cwd).
+ * Call this after path.resolve() to prevent escaping the base via absolute paths or traversal.
+ */
+function assertPathUnderBase(resolvedPath, baseDir) {
+    validateSafePath(resolvedPath);
+    const absPath = path.resolve(resolvedPath);
+    const baseAbs = path.resolve(baseDir);
+    const relative = path.relative(baseAbs, absPath);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error(`Path is outside allowed base: ${resolvedPath}. Paths must be under ${baseDir}`);
+    }
+}
+/**
+ * Validate that input does not contain control characters
+ * Allows \n (0x0A), \r (0x0D), and \t (0x09)
+ */
+function validateNoControlChars(input) {
+    if (!input || typeof input !== "string") {
+        return; // Empty or non-string is fine
+    }
+    for (let i = 0; i < input.length; i++) {
+        const charCode = input.charCodeAt(i);
+        // Reject control characters (< 0x20) except \n, \r, \t
+        if (charCode < 0x20 &&
+            charCode !== 0x09 &&
+            charCode !== 0x0a &&
+            charCode !== 0x0d) {
+            throw new Error(`Control character detected at position ${i}: U+${charCode.toString(16).padStart(4, "0")}`);
+        }
+    }
+}
+/**
+ * Validate that input does not contain pre-encoded URL strings
+ * Rejects strings like %2e%2e (encoded ..)
+ */
+function validateNoPreEncoding(input) {
+    if (!input || typeof input !== "string") {
+        return;
+    }
+    // Check for URL encoding patterns
+    if (input.includes("%")) {
+        // Check for common encoded traversal patterns
+        const lowerInput = input.toLowerCase();
+        if (lowerInput.includes("%2e%2e") ||
+            lowerInput.includes("%2e%2e%2f") ||
+            lowerInput.includes("%2e%2e%5c")) {
+            throw new Error(`Pre-encoded path traversal detected: ${input}. Use the actual path, not an encoded version.`);
+        }
+    }
+}
+/**
+ * Validate a dbt resource ID
+ * Rejects embedded query params, URL fragments, and pre-encoded strings
+ */
+function validateResourceId(id) {
+    if (!id || typeof id !== "string") {
+        throw new Error("Resource ID must be a non-empty string");
+    }
+    // Reject embedded query params
+    if (id.includes("?") || id.includes("#")) {
+        throw new Error(`Resource ID contains invalid characters (?, #): ${id}`);
+    }
+    // Reject pre-encoded URLs (agents sometimes double-encode)
+    if (id.includes("%")) {
+        throw new Error(`Resource ID appears to be URL-encoded: ${id}. Use the actual resource ID, not an encoded version.`);
+    }
+    validateNoControlChars(id);
+}
+/**
+ * Validate optional depth for traversal (e.g. deps --depth).
+ * Rejects NaN, non-integers, and values < 1 when depth is provided.
+ */
+function validateDepth(depth) {
+    if (depth === undefined) {
+        return;
+    }
+    if (typeof depth !== "number" ||
+        Number.isNaN(depth) ||
+        !Number.isInteger(depth) ||
+        depth < 1) {
+        throw new Error(`Invalid depth: ${depth}. Must be a positive integer`);
+    }
+}
+/**
+ * Validate a general string input (combines multiple validations)
+ */
+function validateString(input, allowEmpty = false) {
+    if (!allowEmpty &&
+        (!input || typeof input !== "string" || input.trim().length === 0)) {
+        throw new Error("Input must be a non-empty string");
+    }
+    if (input) {
+        validateNoControlChars(input);
+        validateNoPreEncoding(input);
+    }
+}