@lightdash/cli 1.84.1 → 1.85.0

package/dist/handlers/apps/validate.d.ts

@@ -0,0 +1,49 @@
+import { type DataAppDataReferences, type DataAppExploreIndex, type DataReferenceLocation } from '@lightdash/common';
+export type AppsValidateFormat = 'human' | 'json';
+export type AppsValidateOptions = {
+    format: AppsValidateFormat;
+    live: boolean;
+    verbose: boolean;
+};
+export type AppsValidationIssueCode = 'bundle' | 'dependencies' | 'external_connection' | 'manifest' | 'semantic_layer' | 'semantic_reference' | 'source_parse';
+export type AppsValidationIssue = {
+    code: AppsValidationIssueCode;
+    message: string;
+    location: DataReferenceLocation | null;
+};
+export type AppsValidationCoverage = DataAppDataReferences['stats'] & {
+    unanalyzed: number;
+};
+export type AppValidationResult = {
+    path: string;
+    name: string | null;
+    projectUuid: string | null;
+    valid: boolean;
+    errors: AppsValidationIssue[];
+    warnings: AppsValidationIssue[];
+    coverage: AppsValidationCoverage;
+};
+export type AppsValidationReport = {
+    valid: boolean;
+    mode: 'live' | 'offline';
+    summary: {
+        apps: number;
+        errors: number;
+        warnings: number;
+        callSites: number;
+        unanalyzedCallSites: number;
+    };
+    apps: AppValidationResult[];
+};
+type ValidateAppOptions = {
+    live: boolean;
+    liveProjectUuid?: string;
+    loadLiveIndex: (projectUuid: string) => Promise<DataAppExploreIndex>;
+};
+export declare const fetchLiveDataAppExploreIndex: (projectUuid: string) => Promise<DataAppExploreIndex>;
+export declare const validateLocalDataApp: (appPath: string, options: ValidateAppOptions) => Promise<AppValidationResult>;
+export declare const buildAppsValidationReport: (apps: AppValidationResult[], live: boolean) => AppsValidationReport;
+export declare const renderAppsValidationHuman: (report: AppsValidationReport) => string;
+export declare const appsValidateHandler: (pathArgs: string[] | undefined, options: AppsValidateOptions) => Promise<void>;
+export {};
+//# sourceMappingURL=validate.d.ts.map

package/dist/handlers/apps/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/handlers/apps/validate.ts"],"names":[],"mappings":"AAAA,OAAO,EAcH,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EAGxB,KAAK,qBAAqB,EAC7B,MAAM,mBAAmB,CAAC;AAgB3B,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,MAAM,CAAC;AAElD,MAAM,MAAM,mBAAmB,GAAG;IAC9B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAC7B,QAAQ,GACR,cAAc,GACd,qBAAqB,GACrB,UAAU,GACV,gBAAgB,GAChB,oBAAoB,GACpB,cAAc,CAAC;AAErB,MAAM,MAAM,mBAAmB,GAAG;IAC9B,IAAI,EAAE,uBAAuB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,qBAAqB,GAAG,IAAI,CAAC;CAC1C,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG,qBAAqB,CAAC,OAAO,CAAC,GAAG;IAClE,UAAU,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAC9B,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,QAAQ,EAAE,sBAAsB,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,OAAO,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,mBAAmB,EAAE,MAAM,CAAC;KAC/B,CAAC;IACF,IAAI,EAAE,mBAAmB,EAAE,CAAC;CAC/B,CAAC;AAEF,KAAK,kBAAkB,GAAG;IACtB,IAAI,EAAE,OAAO,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACxE,CAAC;AA2LF,eAAO,MAAM,4BAA4B,gBACxB,MAAM,KACpB,OAAO,CAAC,mBAAmB,CAqB7B,CAAC;AAEF,eAAO,MAAM,oBAAoB,YACpB,MAAM,WACN,kBAAkB,KAC5B,OAAO,CAAC,mBAAmB,CA4H7B,CAAC;AAEF,eAAO,MAAM,yBAAyB,SAC5B,mBAAmB,EAAE,QACrB,OAAO,KACd,oBAwBF,CAAC;AAmBF,eAAO,MAAM,yBAAyB,WAC1B,oBAAoB,KAC7B,MA4CF,CAAC;AAEF,eAAO,MAAM,mBAAmB,aAClB,MAAM,EAAE,GAAG,SAAS,WACrB,mBAAmB,KAC7B,OAAO,CAAC,IAAI,CA2Cd,CAAC"}

package/dist/handlers/apps/validate.js

@@ -0,0 +1,332 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appsValidateHandler = exports.renderAppsValidationHuman = exports.buildAppsValidationReport = exports.validateLocalDataApp = exports.fetchLiveDataAppExploreIndex = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@lightdash/common");
+const fs_1 = require("fs");
+const p_limit_1 = tslib_1.__importDefault(require("p-limit"));
+const path = tslib_1.__importStar(require("path"));
+const config_1 = require("../../config");
+const env_1 = require("../../env");
+const globalState_1 = tslib_1.__importDefault(require("../../globalState"));
+const styles = tslib_1.__importStar(require("../../styles"));
+const apiClient_1 = require("../dbt/apiClient");
+const appCodeFiles_1 = require("./appCodeFiles");
+const scaffolding_1 = require("./scaffolding");
+const emptyCoverage = () => ({
+    callSites: 0,
+    fullyResolved: 0,
+    partiallyResolved: 0,
+    unresolved: 0,
+    unanalyzed: 0,
+});
+const toCoverage = (stats) => ({
+    ...stats,
+    unanalyzed: stats.partiallyResolved + stats.unresolved,
+});
+const issue = (code, message, location = null) => ({ code, message, location });
+const readSemanticLayerFiles = async (appDir) => {
+    const contextDir = path.join(appDir, '.lightdash', 'context');
+    const candidates = [path.join(contextDir, 'semantic-layer.yml')];
+    const modelsDir = path.join(contextDir, 'models');
+    const modelEntries = await fs_1.promises
+        .readdir(modelsDir, { withFileTypes: true })
+        .catch((error) => {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    });
+    for (const entry of modelEntries) {
+        if (entry.isFile())
+            candidates.push(path.join(modelsDir, entry.name));
+    }
+    const files = await Promise.all(candidates.map(async (filePath) => {
+        try {
+            const content = await fs_1.promises.readFile(filePath, 'utf-8');
+            return {
+                path: path
+                    .relative(appDir, filePath)
+                    .split(path.sep)
+                    .join('/'),
+                content,
+            };
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return null;
+            }
+            throw error;
+        }
+    }));
+    return files.filter((file) => file !== null);
+};
+const validateManifest = (manifest) => {
+    const errors = [];
+    if (manifest.slug !== undefined && !(0, common_1.isValidDataAppSlug)(manifest.slug)) {
+        errors.push(issue('manifest', `Invalid slug "${manifest.slug}" in lightdash-app.yml. Slugs must start with a lowercase letter or digit and contain only lowercase letters, digits, and hyphens, up to 255 characters.`));
+    }
+    if (manifest.vizSchema !== undefined) {
+        const parsed = common_1.dataAppVizSchema.safeParse(manifest.vizSchema);
+        if (!parsed.success) {
+            const details = parsed.error.issues
+                .map((entry) => `${entry.path.join('.')}: ${entry.message}`)
+                .join('; ');
+            errors.push(issue('manifest', `Invalid vizSchema in lightdash-app.yml (${details}).`));
+        }
+    }
+    const aliases = new Set();
+    const links = manifest.externalConnections;
+    if (links === undefined)
+        return { errors, aliases };
+    if (!Array.isArray(links)) {
+        errors.push(issue('manifest', 'Invalid externalConnections in lightdash-app.yml: expected a list.'));
+        return { errors, aliases };
+    }
+    for (const link of links) {
+        if (!link ||
+            typeof link !== 'object' ||
+            typeof link.alias !== 'string' ||
+            typeof link.connectionSlug !== 'string') {
+            errors.push(issue('manifest', 'Invalid externalConnections entry in lightdash-app.yml: expected alias and connectionSlug strings.'));
+        }
+        else {
+            const duplicate = aliases.has(link.alias);
+            aliases.add(link.alias);
+            if (!/^[a-z0-9_-]+$/i.test(link.alias) || link.alias.length > 64) {
+                errors.push(issue('manifest', `Invalid external connection alias "${link.alias}" in lightdash-app.yml: aliases must contain only letters, numbers, hyphens, and underscores (max 64 characters).`));
+            }
+            else if (duplicate) {
+                errors.push(issue('manifest', `Duplicate external connection alias "${link.alias}" in lightdash-app.yml.`));
+            }
+        }
+    }
+    return { errors, aliases };
+};
+const validateDependencies = async (appDir) => {
+    try {
+        const deps = await (0, appCodeFiles_1.readDependenciesFromDir)(appDir);
+        if (deps === null)
+            return [];
+        const templateDependencies = (0, appCodeFiles_1.applySdkMirrorToTemplateDeps)((0, scaffolding_1.loadTemplateDependencies)(env_1.CLI_VERSION), deps.packageJson);
+        if (deps.lockfile === null) {
+            const customDeps = (0, common_1.computeCustomDependencies)(deps.packageJson, templateDependencies);
+            if (Object.keys(customDeps).length > 0) {
+                const hint = deps.hasNpmLockfile
+                    ? 'package-lock.json is not used by the server; run `pnpm install` to generate pnpm-lock.yaml.'
+                    : 'Run `pnpm install` to generate pnpm-lock.yaml.';
+                return [
+                    issue('dependencies', `Custom dependencies require pnpm-lock.yaml. ${hint}`),
+                ];
+            }
+            return [];
+        }
+        (0, common_1.validateDataAppDependencies)({ packageJson: deps.packageJson, lockfile: deps.lockfile }, { templateDependencies });
+        return [];
+    }
+    catch (error) {
+        return [issue('dependencies', (0, common_1.getErrorMessage)(error))];
+    }
+};
+const sourceFilesFromBundle = (files) => files.map((file) => ({
+    path: file.path,
+    content: Buffer.from(file.contentBase64, 'base64').toString('utf-8'),
+}));
+const fetchLiveDataAppExploreIndex = async (projectUuid) => {
+    const summaries = await (0, apiClient_1.lightdashApi)({
+        method: 'GET',
+        url: `/api/v1/projects/${projectUuid}/explores`,
+        body: undefined,
+    });
+    const limit = (0, p_limit_1.default)(8);
+    const explores = await Promise.all(summaries
+        .filter((summary) => !(0, common_1.isSummaryExploreError)(summary))
+        .map((summary) => limit(() => (0, apiClient_1.lightdashApi)({
+        method: 'GET',
+        url: `/api/v1/projects/${projectUuid}/explores/${encodeURIComponent(summary.name)}`,
+        body: undefined,
+    }))));
+    return (0, common_1.buildDataAppExploreIndexFromExplores)(explores);
+};
+exports.fetchLiveDataAppExploreIndex = fetchLiveDataAppExploreIndex;
+const validateLocalDataApp = async (appPath, options) => {
+    const appDir = path.resolve(appPath);
+    const errors = [];
+    const warnings = [];
+    let bundle;
+    try {
+        bundle = await (0, appCodeFiles_1.readBundleFromDir)(appDir);
+    }
+    catch (error) {
+        return {
+            path: appDir,
+            name: null,
+            projectUuid: null,
+            valid: false,
+            errors: [issue('bundle', (0, common_1.getErrorMessage)(error))],
+            warnings,
+            coverage: emptyCoverage(),
+        };
+    }
+    const { manifest } = bundle;
+    const manifestResult = validateManifest(manifest);
+    errors.push(...manifestResult.errors);
+    errors.push(...(await validateDependencies(appDir)));
+    const sourceFiles = sourceFilesFromBundle(bundle.files);
+    if (sourceFiles.length === 0) {
+        errors.push(issue('bundle', 'App bundle has no files under src/ to validate.'));
+    }
+    const extracted = (0, common_1.extractDataAppDataReferences)(sourceFiles);
+    const coverage = toCoverage(extracted.stats);
+    warnings.push(...extracted.parseErrors.map((parseError) => issue('source_parse', `Could not statically analyze ${parseError.path}: ${parseError.message}`)));
+    for (const ref of extracted.references) {
+        if (ref.kind === 'externalFetch' &&
+            ref.alias !== null &&
+            !manifestResult.aliases.has(ref.alias)) {
+            errors.push(issue('external_connection', `externalFetch alias "${ref.alias}" is not declared in lightdash-app.yml externalConnections.`, ref.location));
+        }
+    }
+    const hasSemanticReferences = extracted.references.some((ref) => ref.kind !== 'externalFetch');
+    if (hasSemanticReferences) {
+        try {
+            let exploreIndex;
+            if (options.live) {
+                if (!options.liveProjectUuid) {
+                    throw new Error("No project selected. Run 'lightdash config set-project' before using --live validation.");
+                }
+                exploreIndex = await options.loadLiveIndex(options.liveProjectUuid);
+            }
+            else {
+                const semanticFiles = await readSemanticLayerFiles(appDir);
+                if (semanticFiles.length === 0) {
+                    throw new Error('No local semantic layer snapshot found.');
+                }
+                exploreIndex =
+                    (0, common_1.buildDataAppExploreIndexFromModelFiles)(semanticFiles);
+            }
+            errors.push(...(0, common_1.checkDataAppDataReferences)(extracted.references, exploreIndex).map((referenceError) => issue('semantic_reference', referenceError.error, referenceError.location)));
+        }
+        catch (error) {
+            const message = (0, common_1.getErrorMessage)(error);
+            let semanticLayerMessage;
+            if (options.live) {
+                semanticLayerMessage = `Could not load live semantic layer: ${message}`;
+            }
+            else if (message.toLowerCase().includes('re-download')) {
+                semanticLayerMessage = message;
+            }
+            else {
+                semanticLayerMessage = `${message} Re-download the app to refresh its local semantic layer snapshot.`;
+            }
+            errors.push(issue('semantic_layer', semanticLayerMessage));
+        }
+    }
+    let projectUuid = null;
+    if (options.live) {
+        projectUuid = options.liveProjectUuid ?? null;
+    }
+    else if (typeof manifest.projectUuid === 'string') {
+        projectUuid = manifest.projectUuid;
+    }
+    return {
+        path: appDir,
+        name: typeof manifest.name === 'string' ? manifest.name : null,
+        projectUuid,
+        valid: errors.length === 0,
+        errors,
+        warnings,
+        coverage,
+    };
+};
+exports.validateLocalDataApp = validateLocalDataApp;
+const buildAppsValidationReport = (apps, live) => {
+    const errors = apps.reduce((count, app) => count + app.errors.length, 0);
+    const warnings = apps.reduce((count, app) => count + app.warnings.length, 0);
+    return {
+        valid: errors === 0,
+        mode: live ? 'live' : 'offline',
+        summary: {
+            apps: apps.length,
+            errors,
+            warnings,
+            callSites: apps.reduce((count, app) => count + app.coverage.callSites, 0),
+            unanalyzedCallSites: apps.reduce((count, app) => count + app.coverage.unanalyzed, 0),
+        },
+        apps,
+    };
+};
+exports.buildAppsValidationReport = buildAppsValidationReport;
+const formatCoverage = (coverage) => {
+    if (coverage.callSites === 0) {
+        return 'Coverage: no data-reference call sites found.';
+    }
+    if (coverage.unanalyzed === 0) {
+        return `Coverage: all ${coverage.callSites} data-reference call site(s) were statically analyzed.`;
+    }
+    return `Coverage: ${coverage.unanalyzed} of ${coverage.callSites} data-reference call site(s) couldn't be fully analyzed; unresolved values were skipped and are not errors.`;
+};
+const formatIssue = (entry) => {
+    const prefix = entry.location
+        ? `${entry.location.path}:${entry.location.line}:${entry.location.column} — `
+        : '';
+    return `${prefix}${entry.message}`;
+};
+const renderAppsValidationHuman = (report) => {
+    const lines = [
+        `Validating ${report.summary.apps} data app(s) using ${report.mode === 'live'
+            ? 'the live project semantic layer'
+            : 'local semantic layer snapshots'}.`,
+    ];
+    if (report.mode === 'offline') {
+        lines.push(styles.secondary('Offline snapshots may be stale. Use --live for upload-time semantic validation parity.'));
+    }
+    for (const app of report.apps) {
+        lines.push('');
+        const label = app.name ? `${app.name} (${app.path})` : app.path;
+        lines.push(`${app.valid ? styles.success('✓') : styles.error('✗')} ${label}`);
+        lines.push(`  ${formatCoverage(app.coverage)}`);
+        for (const warning of app.warnings) {
+            lines.push(`  ${styles.warning('warning')} ${formatIssue(warning)}`);
+        }
+        for (const error of app.errors) {
+            lines.push(`  ${styles.error('error')} ${formatIssue(error)}`);
+        }
+    }
+    lines.push('');
+    lines.push(report.valid
+        ? styles.success(`Validation passed for ${report.summary.apps} data app(s) with ${report.summary.warnings} warning(s).`)
+        : styles.error(`Validation failed with ${report.summary.errors} error(s) across ${report.summary.apps} data app(s).`));
+    return `${lines.join('\n')}\n`;
+};
+exports.renderAppsValidationHuman = renderAppsValidationHuman;
+const appsValidateHandler = async (pathArgs, options) => {
+    globalState_1.default.setVerbose(options.verbose);
+    const paths = pathArgs && pathArgs.length > 0 ? pathArgs : ['.'];
+    const resolvedPaths = [
+        ...new Set(paths.map((appPath) => path.resolve(process.cwd(), appPath))),
+    ];
+    const liveProjectUuid = options.live
+        ? (await (0, config_1.getConfig)()).context?.project
+        : undefined;
+    const liveIndexes = new Map();
+    const loadLiveIndex = (projectUuid) => {
+        const cached = liveIndexes.get(projectUuid);
+        if (cached)
+            return cached;
+        const pending = (0, exports.fetchLiveDataAppExploreIndex)(projectUuid);
+        liveIndexes.set(projectUuid, pending);
+        return pending;
+    };
+    const apps = await Promise.all(resolvedPaths.map((appPath) => (0, exports.validateLocalDataApp)(appPath, {
+        live: options.live,
+        liveProjectUuid,
+        loadLiveIndex,
+    })));
+    const report = (0, exports.buildAppsValidationReport)(apps, options.live);
+    process.stdout.write(options.format === 'json'
+        ? `${JSON.stringify(report, null, 2)}\n`
+        : (0, exports.renderAppsValidationHuman)(report));
+    if (!report.valid) {
+        throw new common_1.ParameterError(`Data app validation failed with ${report.summary.errors} error(s).`);
+    }
+};
+exports.appsValidateHandler = appsValidateHandler;

package/dist/handlers/apps/validate.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=validate.test.d.ts.map

package/dist/handlers/apps/validate.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.test.d.ts","sourceRoot":"","sources":["../../../src/handlers/apps/validate.test.ts"],"names":[],"mappings":""}

package/dist/handlers/apps/validate.test.js

@@ -0,0 +1,270 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const common_1 = require("@lightdash/common");
+const fs_1 = require("fs");
+const os = tslib_1.__importStar(require("os"));
+const path = tslib_1.__importStar(require("path"));
+const appCodeFiles_1 = require("./appCodeFiles");
+const validate_1 = require("./validate");
+const semanticLayer = [
+    'models:',
+    '  - name: orders',
+    '    meta:',
+    '      metrics:',
+    '        total_revenue:',
+    '          type: sum',
+    '    columns:',
+    '      - name: status',
+].join('\n');
+const defaultManifest = {
+    codeVersion: 1,
+    projectUuid: 'project-uuid',
+    slug: 'orders-app',
+    version: 1,
+    name: 'Orders app',
+    description: '',
+    template: null,
+    downloadedAt: '2026-08-01T00:00:00.000Z',
+    externalConnections: [{ alias: 'stripe', connectionSlug: 'stripe-api' }],
+};
+const validSource = `
+    import { query } from '@lightdash/query-sdk';
+    query('orders').dimensions(['status']).metrics(['total_revenue']);
+    lightdash.externalFetch('stripe', { path: '/charges' });
+`;
+const makeApp = async (args) => {
+    const dir = await fs_1.promises.mkdtemp(path.join(os.tmpdir(), 'ld-app-validate-'));
+    const code = {
+        manifest: args?.manifest ?? defaultManifest,
+        files: [
+            {
+                path: 'src/App.tsx',
+                contentBase64: Buffer.from(args?.source ?? validSource).toString('base64'),
+            },
+        ],
+    };
+    await (0, appCodeFiles_1.writeBundleToDir)(dir, code);
+    const layout = args?.semanticLayout ?? 'sharded';
+    if (layout === 'legacy') {
+        const contextDir = path.join(dir, '.lightdash', 'context');
+        await fs_1.promises.mkdir(contextDir, { recursive: true });
+        await fs_1.promises.writeFile(path.join(contextDir, 'semantic-layer.yml'), semanticLayer);
+    }
+    else if (layout === 'sharded') {
+        const modelsDir = path.join(dir, '.lightdash', 'context', 'models');
+        await fs_1.promises.mkdir(modelsDir, { recursive: true });
+        await Promise.all([
+            fs_1.promises.writeFile(path.join(dir, '.lightdash', 'context', 'semantic-layer.yml'), '# See models/'),
+            fs_1.promises.writeFile(path.join(modelsDir, 'orders.yml'), semanticLayer),
+        ]);
+    }
+    if (args?.packageJson !== undefined) {
+        await fs_1.promises.writeFile(path.join(dir, 'package.json'), args.packageJson);
+    }
+    if (args?.lockfile !== undefined) {
+        await fs_1.promises.writeFile(path.join(dir, 'pnpm-lock.yaml'), args.lockfile);
+    }
+    return dir;
+};
+const unusedLiveLoader = () => {
+    throw new Error('live semantic layer should not be loaded');
+};
+const liveIndex = (0, common_1.buildDataAppExploreIndexFromModelFiles)([
+    { path: 'orders.yml', content: semanticLayer },
+]);
+describe('validateLocalDataApp', () => {
+    it.each(['sharded', 'legacy'])('validates a correct app against a %s offline semantic layer', async (semanticLayout) => {
+        const dir = await makeApp({ semanticLayout });
+        const result = await (0, validate_1.validateLocalDataApp)(dir, {
+            live: false,
+            loadLiveIndex: unusedLiveLoader,
+        });
+        expect(result.valid).toBe(true);
+        expect(result.errors).toEqual([]);
+        expect(result.coverage).toMatchObject({
+            callSites: 2,
+            fullyResolved: 2,
+            unanalyzed: 0,
+        });
+    });
+    it('reports semantic errors and undeclared externalFetch aliases with source locations', async () => {
+        const dir = await makeApp({
+            source: `
+                import { query } from '@lightdash/query-sdk';
+                query('ordrs').dimensions(['missing_field']);
+                client.externalFetch('salesforce', { path: '/accounts' });
+            `,
+        });
+        const result = await (0, validate_1.validateLocalDataApp)(dir, {
+            live: false,
+            loadLiveIndex: unusedLiveLoader,
+        });
+        expect(result.valid).toBe(false);
+        expect(result.errors).toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                code: 'semantic_reference',
+                message: "Explore 'ordrs' does not exist — did you mean 'orders'?",
+                location: expect.objectContaining({ path: 'src/App.tsx' }),
+            }),
+            expect.objectContaining({
+                code: 'external_connection',
+                message: expect.stringContaining('salesforce'),
+                location: expect.objectContaining({ path: 'src/App.tsx' }),
+            }),
+        ]));
+    });
+    it('counts dynamic query call sites as unanalyzed without failing', async () => {
+        const dir = await makeApp({
+            source: `
+                import { query } from '@lightdash/query-sdk';
+                function build(explore) {
+                    return query(explore).dimensions(['status']);
+                }
+            `,
+        });
+        const result = await (0, validate_1.validateLocalDataApp)(dir, {
+            live: false,
+            loadLiveIndex: unusedLiveLoader,
+        });
+        expect(result.valid).toBe(true);
+        expect(result.coverage).toMatchObject({
+            callSites: 1,
+            unresolved: 1,
+            unanalyzed: 1,
+        });
+    });
+    it('does not treat a dynamic externalFetch alias as an error', async () => {
+        const dir = await makeApp({
+            source: `
+                function load(client, alias) {
+                    return client.externalFetch(alias, { path: '/resource' });
+                }
+            `,
+            semanticLayout: 'none',
+        });
+        const result = await (0, validate_1.validateLocalDataApp)(dir, {
+            live: false,
+            loadLiveIndex: unusedLiveLoader,
+        });
+        expect(result.valid).toBe(true);
+        expect(result.errors).toEqual([]);
+        expect(result.coverage).toMatchObject({
+            callSites: 1,
+            unresolved: 1,
+            unanalyzed: 1,
+        });
+    });
+    it('uses the live semantic layer and does not require a local snapshot', async () => {
+        const dir = await makeApp({ semanticLayout: 'none' });
+        const loadLiveIndex = vi.fn().mockResolvedValue(liveIndex);
+        const result = await (0, validate_1.validateLocalDataApp)(dir, {
+            live: true,
+            liveProjectUuid: 'configured-project-uuid',
+            loadLiveIndex,
+        });
+        expect(result.valid).toBe(true);
+        expect(result.projectUuid).toBe('configured-project-uuid');
+        expect(loadLiveIndex).toHaveBeenCalledWith('configured-project-uuid');
+    });
+    it('explains how to configure a project for live validation', async () => {
+        const dir = await makeApp({ semanticLayout: 'none' });
+        const result = await (0, validate_1.validateLocalDataApp)(dir, {
+            live: true,
+            loadLiveIndex: unusedLiveLoader,
+        });
+        expect(result.valid).toBe(false);
+        expect(result.projectUuid).toBeNull();
+        expect(result.errors).toContainEqual(expect.objectContaining({
+            code: 'semantic_layer',
+            message: expect.stringContaining('lightdash config set-project'),
+        }));
+    });
+    it('gives an upgrade path instead of crashing on a missing offline snapshot', async () => {
+        const dir = await makeApp({ semanticLayout: 'none' });
+        const result = await (0, validate_1.validateLocalDataApp)(dir, {
+            live: false,
+            loadLiveIndex: unusedLiveLoader,
+        });
+        expect(result.valid).toBe(false);
+        expect(result.errors).toContainEqual(expect.objectContaining({
+            code: 'semantic_layer',
+            message: expect.stringContaining('Re-download the app'),
+        }));
+    });
+    it('validates slug and vizSchema from the manifest', async () => {
+        const manifest = {
+            ...defaultManifest,
+            slug: '../invalid',
+            vizSchema: { fields: 'not-an-array' },
+        };
+        const dir = await makeApp({ manifest });
+        const result = await (0, validate_1.validateLocalDataApp)(dir, {
+            live: false,
+            loadLiveIndex: unusedLiveLoader,
+        });
+        expect(result.errors).toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                code: 'manifest',
+                message: expect.stringContaining('Invalid slug'),
+            }),
+            expect.objectContaining({
+                code: 'manifest',
+                message: expect.stringContaining('Invalid vizSchema'),
+            }),
+        ]));
+    });
+    it('requires a pnpm lockfile for custom dependencies', async () => {
+        const dir = await makeApp({
+            packageJson: JSON.stringify({
+                dependencies: { 'left-pad': '1.3.0' },
+            }),
+        });
+        const result = await (0, validate_1.validateLocalDataApp)(dir, {
+            live: false,
+            loadLiveIndex: unusedLiveLoader,
+        });
+        expect(result.errors).toContainEqual(expect.objectContaining({
+            code: 'dependencies',
+            message: expect.stringContaining('pnpm-lock.yaml'),
+        }));
+    });
+    it('surfaces parser failures as warnings rather than errors', async () => {
+        const dir = await makeApp({
+            source: 'const broken = ;',
+            semanticLayout: 'none',
+        });
+        const result = await (0, validate_1.validateLocalDataApp)(dir, {
+            live: false,
+            loadLiveIndex: unusedLiveLoader,
+        });
+        expect(result.valid).toBe(true);
+        expect(result.warnings).toContainEqual(expect.objectContaining({ code: 'source_parse' }));
+    });
+});
+describe('renderAppsValidationHuman', () => {
+    it('makes partial green coverage explicit', () => {
+        const report = (0, validate_1.buildAppsValidationReport)([
+            {
+                path: '/tmp/orders-app',
+                name: 'Orders app',
+                projectUuid: 'project-uuid',
+                valid: true,
+                errors: [],
+                warnings: [],
+                coverage: {
+                    callSites: 14,
+                    fullyResolved: 11,
+                    partiallyResolved: 2,
+                    unresolved: 1,
+                    unanalyzed: 3,
+                },
+            },
+        ], false);
+        const output = (0, validate_1.renderAppsValidationHuman)(report);
+        expect(output).toContain("3 of 14 data-reference call site(s) couldn't be fully analyzed");
+        expect(output).toContain('unresolved values were skipped');
+        expect(output).toContain('Validation passed');
+        expect(output).toContain('Offline snapshots may be stale');
+    });
+});