mviz 1.6.4 → 1.6.7

package/dist/core/formatting.js

@@ -40,8 +40,11 @@ export function localeFixed(value, decimals, locale) {
  * Format a number according to the specified format type
  * @param showSign - If true, prefix positive numbers with +
  * @param currency - Optional currency config for currency formats (defaults to USD)
+ * @param pctMultiply - For pct formats: multiply the value by 100 before formatting.
+ *   Default true. Set false when the caller has already determined that the series
+ *   values are in percentage units (via detectPctMultiply).
  */
-export function formatNumber(value, format, showSign = false, currency) {
+export function formatNumber(value, format, showSign = false, currency, pctMultiply = true) {
     if (value === null || value === undefined || isNaN(value)) {
         return '';
     }
@@ -69,10 +72,10 @@ export function formatNumber(value, format, showSign = false, currency) {
             break;
         case 'pct':
         case 'pct1':
-            result = formatPct1(value);
+            result = formatPct1(value, pctMultiply);
             break;
         case 'pct0':
-            result = formatPct0(value);
+            result = formatPct0(value, pctMultiply);
             break;
         case 'num0':
             result = formatNum0(value);
@@ -89,6 +92,12 @@ export function formatNumber(value, format, showSign = false, currency) {
         case 'num0b':
             result = formatNum0b(value);
             break;
+        case 'duration':
+            result = formatDuration(value);
+            break;
+        case 'date':
+            result = formatDateValue(value);
+            break;
         default:
             result = smartFormatNumber(value, false, cur);
     }
@@ -195,17 +204,199 @@ function formatCurrency0b(value, cur) {
     const formatted = cur.symbol + localeFixed(absValue / 1_000_000_000, 1, cur.locale) + 'b';
     return isNegative ? `(${formatted})` : formatted;
 }
+/**
+ * Render a number of seconds as a compact duration string: `"1m7s"`,
+ * `"25m39s"`, `"1h2m3s"`. Sub-second values render as `"0.5s"`. Negatives
+ * are wrapped in parens like the rest of the formatters.
+ */
+function formatDuration(seconds) {
+    if (seconds === 0)
+        return '0s';
+    const neg = seconds < 0;
+    let s = Math.abs(seconds);
+    const h = Math.floor(s / 3600);
+    s -= h * 3600;
+    const m = Math.floor(s / 60);
+    s -= m * 60;
+    let body = '';
+    if (h)
+        body += `${h}h`;
+    if (m)
+        body += `${m}m`;
+    if (s || (!h && !m)) {
+        const secStr = Number.isInteger(s) ? `${s}` : s.toFixed(2).replace(/\.?0+$/, '');
+        body += `${secStr}s`;
+    }
+    return neg ? `(${body})` : body;
+}
+/**
+ * Render an epoch-ms number as an ISO `YYYY-MM-DD` date string.
+ * String inputs are handled separately by the renderer (passed through),
+ * so this only fires when the value is numeric.
+ */
+function formatDateValue(value) {
+    const d = new Date(value);
+    if (isNaN(d.getTime()))
+        return String(value);
+    const yyyy = d.getUTCFullYear();
+    const mm = String(d.getUTCMonth() + 1).padStart(2, '0');
+    const dd = String(d.getUTCDate()).padStart(2, '0');
+    return `${yyyy}-${mm}-${dd}`;
+}
+/**
+ * Convert a cell value to a numeric (or string) sort key based on the
+ * declared column format. The result is what the table emits as
+ * `data-sort` so the client-side compare always sees comparable values.
+ *
+ * - `date` → epoch ms (accepts Date, ISO string, or numeric ms)
+ * - `duration` → total seconds (accepts number-of-seconds or `1m7s` style)
+ * - currency / pct / num / auto → underlying numeric value
+ *
+ * Returns null when the value can't be coerced for the declared format —
+ * the caller falls back to its untyped heuristic chain.
+ */
+export function formatSortKey(value, format) {
+    if (value === null || value === undefined)
+        return null;
+    if (!format)
+        return null;
+    if (format === 'date') {
+        if (value instanceof Date) {
+            const t = value.getTime();
+            return isNaN(t) ? null : t;
+        }
+        if (typeof value === 'number' && !isNaN(value))
+            return value;
+        if (typeof value === 'string') {
+            const t = Date.parse(value);
+            return isNaN(t) ? null : t;
+        }
+        return null;
+    }
+    if (format === 'duration') {
+        if (typeof value === 'number' && !isNaN(value))
+            return value;
+        if (typeof value === 'string') {
+            return parseDurationString(value);
+        }
+        return null;
+    }
+    // Numeric-typed formats (currency*, pct*, num*, auto): pass numeric values
+    // through, parse simple numeric strings. Pre-formatted strings are *not*
+    // parsed — pass numeric values for typed columns.
+    if (typeof value === 'number' && !isNaN(value))
+        return value;
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        const n = parseFloat(trimmed);
+        if (!isNaN(n) && String(n) === trimmed)
+            return n;
+    }
+    return null;
+}
+/**
+ * Parse a duration string like `"10s"`, `"1m7s"`, `"25m39s"`, `"1h2m3s"`
+ * into total seconds. Returns null when the input doesn't match.
+ * Exported for the untyped fallback path in `cellSortAttr`.
+ *
+ * When `requireSeconds` is true, only strings that contain an `s` segment
+ * match — bare `5m` or `1h` are rejected. The untyped fallback uses this
+ * stricter form because a bare magnitude like `5m` is ambiguous (5 minutes
+ * or 5 million?); the lenient form is for columns that explicitly declare
+ * `fmt: "duration"`.
+ */
+export function parseDurationString(s, options = {}) {
+    const trimmed = s.trim();
+    const m = trimmed.match(/^(?:(\d+)h)?(?:(\d+)m)?(?:(\d+(?:\.\d+)?)s)?$/);
+    if (!m)
+        return null;
+    const [, h, mm, ss] = m;
+    if (h === undefined && mm === undefined && ss === undefined)
+        return null;
+    if (options.requireSeconds && ss === undefined)
+        return null;
+    const hours = h ? parseInt(h, 10) : 0;
+    const mins = mm ? parseInt(mm, 10) : 0;
+    const secs = ss ? parseFloat(ss) : 0;
+    return hours * 3600 + mins * 60 + secs;
+}
+/**
+ * Parse an ISO-8601 date string (`YYYY-MM-DD` with optional time/timezone)
+ * into epoch ms. Returns null for non-ISO strings so they fall back to
+ * locale sort instead of mis-parsing through `Date.parse`.
+ */
+export function parseIsoDateString(s) {
+    const trimmed = s.trim();
+    const iso = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/;
+    if (!iso.test(trimmed))
+        return null;
+    const t = Date.parse(trimmed);
+    return isNaN(t) ? null : t;
+}
+/**
+ * Detect whether a series of values needs to be multiplied by 100 for percent formatting.
+ * Returns true when the series looks fractional (max |v| <= 1). Returns false when any
+ * value exceeds 1, indicating the series is already in percentage units (e.g., [15, 22, 38]).
+ *
+ * Empty / all-null series default to true (fractional), matching the legacy behavior.
+ */
+export function detectPctMultiply(values) {
+    let max = 0;
+    let sawAny = false;
+    for (const v of values) {
+        if (v === null || v === undefined || isNaN(v))
+            continue;
+        sawAny = true;
+        const abs = Math.abs(v);
+        if (abs > max)
+            max = abs;
+    }
+    if (!sawAny)
+        return true;
+    return max <= 1;
+}
+/**
+ * Series-aware pctMultiply for a chart/table column.
+ *
+ * For non-pct formats, always returns true (no effect — the flag is unused for those).
+ * For pct formats, returns false when the series contains a value > 1, so callers can
+ * format already-percent data like [15, 22, 38] as 15%, 22%, 38% instead of 1500% etc.
+ */
+export function shouldPctMultiply(format, values) {
+    if (format !== 'pct' && format !== 'pct0' && format !== 'pct1')
+        return true;
+    return detectPctMultiply(values);
+}
+/**
+ * Pull numeric values out of a data array for one or more field names.
+ * Used by charts to sample a y-series for pct auto-detection.
+ */
+export function collectNumericFieldValues(data, fields) {
+    const out = [];
+    if (!data)
+        return out;
+    for (const row of data) {
+        for (const f of fields) {
+            const v = row[f];
+            if (typeof v === 'number' && !isNaN(v))
+                out.push(v);
+        }
+    }
+    return out;
+}
 /**
  * Format as percentage with 1 decimal: 15.0%
  */
-function formatPct1(value) {
-    return (value * 100).toFixed(1) + '%';
+function formatPct1(value, pctMultiply = true) {
+    const scaled = pctMultiply ? value * 100 : value;
+    return scaled.toFixed(1) + '%';
 }
 /**
  * Format as percentage with 0 decimals: 15%
  */
-function formatPct0(value) {
-    return Math.round(value * 100) + '%';
+function formatPct0(value, pctMultiply = true) {
+    const scaled = pctMultiply ? value * 100 : value;
+    return Math.round(scaled) + '%';
 }
 /**
  * Format as number with 0 decimals: 1,250
@@ -394,8 +585,9 @@ export function parseNumericString(value) {
  * @param currencySymbol - Symbol to use for currency formats (defaults to '$')
  * @param locale - Locale for number formatting (defaults to 'en-US')
  */
-export function formatValue(fmt, currencySymbol = '$', locale = 'en-US') {
+export function formatValue(fmt, currencySymbol = '$', locale = 'en-US', pctMultiply = true) {
     const locStr = JSON.stringify(locale);
+    const pctExpr = pctMultiply ? '(value * 100)' : 'value';
     switch (fmt) {
         case 'currency':
             return `'${currencySymbol}' + value.toLocaleString(${locStr})`;
@@ -407,9 +599,9 @@ export function formatValue(fmt, currencySymbol = '$', locale = 'en-US') {
             return `'${currencySymbol}' + (value/1000000000).toLocaleString(${locStr}, {minimumFractionDigits:1, maximumFractionDigits:1}) + 'b'`;
         case 'pct':
         case 'pct1':
-            return "(value * 100).toFixed(1) + '%'";
+            return `${pctExpr}.toFixed(1) + '%'`;
         case 'pct0':
-            return "(value * 100).toFixed(0) + '%'";
+            return `${pctExpr}.toFixed(0) + '%'`;
         case 'num0':
             return "value.toLocaleString()";
         case 'num1':
@@ -430,7 +622,7 @@ export function formatValue(fmt, currencySymbol = '$', locale = 'en-US') {
  * @param currencySymbol - Symbol to use for currency formats (defaults to '$')
  * @param locale - Locale for number formatting (defaults to 'en-US')
  */
-export function getLabelFormatterJs(fmt, currencySymbol = '$', locale = 'en-US') {
+export function getLabelFormatterJs(fmt, currencySymbol = '$', locale = 'en-US', pctMultiply = true) {
     if (fmt === null || fmt === undefined) {
         return null;
     }
@@ -473,7 +665,7 @@ export function getLabelFormatterJs(fmt, currencySymbol = '$', locale = 'en-US')
         };
     }
     // Get the formatting expression for specific formats
-    const expr = formatValue(fmt, currencySymbol, locale);
+    const expr = formatValue(fmt, currencySymbol, locale, pctMultiply);
     if (expr === 'value') {
         return null;
     }
@@ -488,7 +680,7 @@ export function getLabelFormatterJs(fmt, currencySymbol = '$', locale = 'en-US')
  * @param currencySymbol - Symbol to use for currency formats (defaults to '$')
  * @param locale - Locale for number formatting (defaults to 'en-US')
  */
-export function getAxisFormatterJs(fmt, currencySymbol = '$', locale = 'en-US') {
+export function getAxisFormatterJs(fmt, currencySymbol = '$', locale = 'en-US', pctMultiply = true) {
     if (fmt === null || fmt === undefined) {
         return null;
     }
@@ -526,19 +718,26 @@ export function getAxisFormatterJs(fmt, currencySymbol = '$', locale = 'en-US')
 }`,
         };
     }
-    // For percentage, multiply by 100
+    // For percentage, multiply by 100 unless the caller signals the series is already in
+    // percent units (pctMultiply === false).
     if (fmt === 'pct' || fmt === 'pct1') {
+        const body = pctMultiply
+            ? `return (value * 100).toFixed(1) + '%';`
+            : `return value.toFixed(1) + '%';`;
         return {
-            _js_: `function(value) { return (value * 100).toFixed(1) + '%'; }`,
+            _js_: `function(value) { ${body} }`,
         };
     }
     if (fmt === 'pct0') {
+        const body = pctMultiply
+            ? `return (value * 100).toFixed(0) + '%';`
+            : `return value.toFixed(0) + '%';`;
         return {
-            _js_: `function(value) { return (value * 100).toFixed(0) + '%'; }`,
+            _js_: `function(value) { ${body} }`,
         };
     }
     // Get the formatting expression for specific formats
-    const expr = formatValue(fmt, currencySymbol, locale);
+    const expr = formatValue(fmt, currencySymbol, locale, pctMultiply);
     if (expr === 'value') {
         return null;
     }

package/dist/core/lint-rules/registry.d.ts

@@ -4,7 +4,7 @@
  * Rules register themselves at module load time. The linter
  * calls executeLintRules() to run all applicable rules.
  */
-import type { LintContext, LintExecutionResult, LintRuleDefinition } from './types.js';
+import type { LintContext, LintExecutionMode, LintExecutionResult, LintRuleDefinition } from './types.js';
 /**
  * Register a lint rule in the global registry.
  * Called at module load time by rule files.
@@ -14,9 +14,11 @@ export declare function registerLintRule(definition: LintRuleDefinition): void;
  * Execute all applicable lint rules for a given context.
  *
  * @param context - The lint context with spec, type, data, etc.
+ * @param mode - 'generate' (default) skips rules flagged `lintOnly: true`;
+ *   'lint' runs every applicable rule.
  * @returns Execution result with errors, warnings, and validity
  */
-export declare function executeLintRules(context: LintContext): LintExecutionResult;
+export declare function executeLintRules(context: LintContext, mode?: LintExecutionMode): LintExecutionResult;
 /**
  * Get all registered rules (for testing/debugging)
  */

package/dist/core/lint-rules/registry.js

@@ -31,15 +31,20 @@ function ruleApplies(rule, type) {
  * Execute all applicable lint rules for a given context.
  *
  * @param context - The lint context with spec, type, data, etc.
+ * @param mode - 'generate' (default) skips rules flagged `lintOnly: true`;
+ *   'lint' runs every applicable rule.
  * @returns Execution result with errors, warnings, and validity
  */
-export function executeLintRules(context) {
+export function executeLintRules(context, mode = 'lint') {
     const errors = [];
     const warnings = [];
     for (const ruleDef of ruleRegistry) {
         if (!ruleApplies(ruleDef, context.type)) {
             continue;
         }
+        if (ruleDef.lintOnly && mode !== 'lint') {
+            continue;
+        }
         try {
             const results = ruleDef.rule(context);
             for (const result of results) {

package/dist/core/lint-rules/rules/index.d.ts

@@ -13,4 +13,5 @@ import './required-fields.js';
 import './waterfall-type-values.js';
 import './data-field-exists.js';
 import './mermaid-syntax.js';
+import './pct-scalar-gt-one.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/lint-rules/rules/index.js

@@ -13,4 +13,5 @@ import './required-fields.js';
 import './waterfall-type-values.js';
 import './data-field-exists.js';
 import './mermaid-syntax.js';
+import './pct-scalar-gt-one.js';
 //# sourceMappingURL=index.js.map

package/dist/core/lint-rules/rules/pct-scalar-gt-one.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Lint rule: pct-scalar-gt-one
+ *
+ * Warns when a scalar component (big_value / delta) uses a pct* format on a value
+ * whose absolute value is > 1. These formats always multiply by 100, so `value: 15.5`
+ * with `format: "pct"` renders as 1550.0%, which is almost never what was intended.
+ * The likely fix is to pass `value / 100` or to pass an already-fractional input.
+ *
+ * Scoped to scalars only. Charts and tables are series-aware and handle the
+ * already-percent case automatically (see shouldPctMultiply).
+ */
+export {};
+//# sourceMappingURL=pct-scalar-gt-one.d.ts.map

package/dist/core/lint-rules/rules/pct-scalar-gt-one.js

@@ -0,0 +1,46 @@
+/**
+ * Lint rule: pct-scalar-gt-one
+ *
+ * Warns when a scalar component (big_value / delta) uses a pct* format on a value
+ * whose absolute value is > 1. These formats always multiply by 100, so `value: 15.5`
+ * with `format: "pct"` renders as 1550.0%, which is almost never what was intended.
+ * The likely fix is to pass `value / 100` or to pass an already-fractional input.
+ *
+ * Scoped to scalars only. Charts and tables are series-aware and handle the
+ * already-percent case automatically (see shouldPctMultiply).
+ */
+import { registerLintRule } from '../registry.js';
+const PCT_FORMATS = new Set(['pct', 'pct0', 'pct1']);
+registerLintRule({
+    id: 'pct-scalar-gt-one',
+    description: 'Warns when big_value/delta uses pct format with |value| > 1 (will render as value × 100)',
+    appliesTo: ['big_value', 'delta'],
+    defaultSeverity: 'warning',
+    // Advisory rule: only fire when the CLI is explicitly linting. Normal HTML
+    // rendering stays quiet so the dashboard output isn't noisy for end users.
+    lintOnly: true,
+    rule: checkPctScalar,
+});
+function checkPctScalar(context) {
+    const { spec } = context;
+    const format = spec.format;
+    if (typeof format !== 'string' || !PCT_FORMATS.has(format))
+        return [];
+    const value = spec.value;
+    if (typeof value !== 'number' || isNaN(value))
+        return [];
+    if (Math.abs(value) <= 1)
+        return [];
+    const scaled = (value * 100).toFixed(1).replace(/\.0$/, '');
+    const fractional = value / 100;
+    return [
+        {
+            ruleId: 'pct-scalar-gt-one',
+            message: `"value": ${value} with "format": "${format}" will render as ${scaled}% (value × 100).`,
+            severity: 'warning',
+            path: '/value',
+            suggestion: `If ${value} is already a percentage, change it to ${fractional} (or pass the raw fraction). The pct* formats always multiply scalar values by 100.`,
+        },
+    ];
+}
+//# sourceMappingURL=pct-scalar-gt-one.js.map

package/dist/core/lint-rules/types.d.ts

@@ -56,9 +56,21 @@ export interface LintRuleDefinition {
     appliesTo: string[];
     /** Default severity when rule triggers */
     defaultSeverity: LintSeverity;
+    /**
+     * If true, this rule only fires when the CLI is explicitly linting
+     * (`mviz --lint …`). Normal HTML generation silently skips it.
+     * Use for checks that are advisory for authors but should not noise up
+     * the output when the user is just rendering a dashboard.
+     */
+    lintOnly?: boolean;
     /** The rule function */
     rule: LintRule;
 }
+/**
+ * Execution mode passed to the registry. `lint` runs every registered rule.
+ * `generate` skips rules flagged `lintOnly: true`.
+ */
+export type LintExecutionMode = 'lint' | 'generate';
 /**
  * Result of running all applicable lint rules
  */

package/dist/core/linter.d.ts

@@ -4,6 +4,7 @@
  * Validates specs against JSON Schema and performs data validation
  * using modular lint rules. Throws errors on validation failure.
  */
+import type { LintExecutionMode } from './lint-rules/types.js';
 /**
  * Error thrown when spec validation fails
  */
@@ -14,11 +15,18 @@ export declare class SpecValidationError extends Error {
 /**
  * Lint a single spec - validates against schema and performs data validation.
  * Throws SpecValidationError on failure. Logs warnings to stderr.
+ *
+ * Columnar specs (`{columns, rows}`) are normalized to the standard
+ * `{data}` shape before validation, so callers do not need to convert first.
+ *
+ * @param mode - 'generate' (default) skips lint-only rules so HTML rendering
+ *   stays quiet. 'lint' (used by `mviz --lint`) runs every rule, including
+ *   advisory ones scoped to the lint command.
  */
-export declare function lintSpec(spec: unknown): void;
+export declare function lintSpec(spec: unknown, mode?: LintExecutionMode): void;
 /**
  * Lint multiple specs (e.g., from a dashboard)
  * Throws SpecValidationError on first failure.
  */
-export declare function lintSpecs(specs: unknown[]): void;
+export declare function lintSpecs(specs: unknown[], mode?: LintExecutionMode): void;
 //# sourceMappingURL=linter.d.ts.map

package/dist/core/linter.js

@@ -10,7 +10,8 @@ import { readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { executeLintRules, buildLintContext, findSchemaDir } from './lint-rules/index.js';
-import { TYPE_TO_SCHEMA_DEF, VALID_TYPES } from './lint-rules/schema-fields.js';
+import { TYPE_TO_SCHEMA_DEF, VALID_TYPES, VALID_FIELDS } from './lint-rules/schema-fields.js';
+import { convertColumnarFormat } from '../layout/converter.js';
 // Handle default exports for CommonJS/ESM interop
 const Ajv2020 = Ajv2020Module;
 const addFormats = addFormatsModule;
@@ -93,12 +94,37 @@ function filterErrorsNoType(errors) {
 /**
  * Filter errors to only those relevant to a specific schema definition
  */
-function filterErrorsForDef(errors, defName) {
+function filterErrorsForDef(errors, defName, specType) {
     const relevantErrors = errors.filter((e) => e.schemaPath.includes(`/$defs/${defName}/`));
+    // Also keep enum errors from shared $defs (like FormatOption) when the
+    // failing property belongs to this spec's root — otherwise invalid enum
+    // values silently pass because the error lives under `/$defs/FormatOption/enum`
+    // rather than the type's own def.
+    const sharedEnumErrors = findSharedEnumErrors(errors, specType);
     if (relevantErrors.length === 0) {
-        return errors.filter((e) => e.keyword === 'additionalProperties' && e.schemaPath.includes(`/$defs/${defName}`));
+        const additionalPropErrors = errors.filter((e) => e.keyword === 'additionalProperties' && e.schemaPath.includes(`/$defs/${defName}`));
+        return [...additionalPropErrors, ...sharedEnumErrors];
     }
-    return relevantErrors;
+    return [...relevantErrors, ...sharedEnumErrors];
+}
+/**
+ * Find enum errors whose instancePath points to a top-level field of the
+ * spec. These come from shared $defs (e.g. FormatOption) and would otherwise
+ * be dropped by the schemaPath-based filter.
+ */
+function findSharedEnumErrors(errors, specType) {
+    const validFields = VALID_FIELDS[specType];
+    if (!validFields)
+        return [];
+    return errors.filter((e) => {
+        if (e.keyword !== 'enum')
+            return false;
+        // instancePath like "/format" — first segment is the field name.
+        const m = e.instancePath.match(/^\/([^/]+)(?:\/|$)/);
+        if (!m || !m[1])
+            return false;
+        return validFields.has(m[1]);
+    });
 }
 /**
  * Filter schema errors to only show relevant errors for the detected type.
@@ -113,7 +139,7 @@ function filterSchemaErrors(errors, specType) {
     if (!defName) {
         return [createUnknownTypeError(specType)];
     }
-    return filterErrorsForDef(errors, defName);
+    return filterErrorsForDef(errors, defName, specType);
 }
 /**
  * Format a schema error into a readable message
@@ -185,17 +211,39 @@ function logWarnings(warnings) {
     }
     console.error('');
 }
+/**
+ * Normalize a spec for validation.
+ *
+ * Currently this just folds the columnar `{columns, rows}` shape into the
+ * standard `{data}` shape. Linting always runs against the normalized spec so
+ * every entry point (CLI, markdown parser, programmatic) sees the same
+ * contract.
+ */
+function normalizeForLint(spec) {
+    if (spec && typeof spec === 'object' && 'type' in spec) {
+        return convertColumnarFormat(spec);
+    }
+    return spec;
+}
 /**
  * Lint a single spec - validates against schema and performs data validation.
  * Throws SpecValidationError on failure. Logs warnings to stderr.
+ *
+ * Columnar specs (`{columns, rows}`) are normalized to the standard
+ * `{data}` shape before validation, so callers do not need to convert first.
+ *
+ * @param mode - 'generate' (default) skips lint-only rules so HTML rendering
+ *   stays quiet. 'lint' (used by `mviz --lint`) runs every rule, including
+ *   advisory ones scoped to the lint command.
  */
-export function lintSpec(spec) {
+export function lintSpec(spec, mode = 'generate') {
+    const normalized = normalizeForLint(spec);
     // Schema validation
-    validateAgainstSchema(spec);
+    validateAgainstSchema(normalized);
     // Modular lint rules validation
-    if (spec && typeof spec === 'object' && 'type' in spec) {
-        const context = buildLintContext(spec);
-        const result = executeLintRules(context);
+    if (normalized && typeof normalized === 'object' && 'type' in normalized) {
+        const context = buildLintContext(normalized);
+        const result = executeLintRules(context, mode);
         // Log warnings to stderr
         if (result.warnings.length > 0) {
             logWarnings(result.warnings);
@@ -217,9 +265,9 @@ export function lintSpec(spec) {
  * Lint multiple specs (e.g., from a dashboard)
  * Throws SpecValidationError on first failure.
  */
-export function lintSpecs(specs) {
+export function lintSpecs(specs, mode = 'generate') {
     for (const spec of specs) {
-        lintSpec(spec);
+        lintSpec(spec, mode);
     }
 }
 //# sourceMappingURL=linter.js.map

package/dist/layout/block-loader.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Phase 2: Load + convert + validate.
+ *
+ * Walks a raw IR (from markdown-parser) and resolves every `RawCodeBlockItem`
+ * into a `ParsedItem` by:
+ *   - reading any `file=` reference (CSV or JSON)
+ *   - parsing inline JSON
+ *   - merging file data with inline options
+ *   - applying columnar -> standard format conversion
+ *   - injecting frontmatter currency / theme defaults
+ *   - linting the resulting spec
+ *
+ * Errors collected during this phase are returned as a string list so the
+ * caller can report them in non-strict mode or short-circuit in strict mode.
+ */
+import type { ParsedFrontmatter, RawSection, Section } from './parser-types.js';
+export interface LoadOptions {
+    baseDir: string | undefined;
+    strict: boolean;
+    lintMode: 'generate' | 'lint';
+    frontmatter: ParsedFrontmatter;
+}
+export interface LoadResult {
+    sections: Section[];
+    errors: string[];
+}
+/**
+ * Resolve all raw items into parsed items. Walks every section/row/item.
+ */
+export declare function loadSections(rawSections: RawSection[], options: LoadOptions): LoadResult;
+//# sourceMappingURL=block-loader.d.ts.map