@viccydev/pi-fpa 0.9.4 → 0.9.6

package/extensions/fpa-dashboard/schema.ts

@@ -1,4 +1,4 @@
-export const DASHBOARD_WIDGET_TYPES = ["stat", "timeseries", "table", "grouped-table"] as const;
+export const DASHBOARD_WIDGET_TYPES = ["stat", "timeseries", "table", "grouped-table", "waterfall", "stacked-bar"] as const;
 export type DashboardWidgetType = (typeof DASHBOARD_WIDGET_TYPES)[number];
 
 const TONES = new Set(["positive", "negative", "warning", "neutral"]);
@@ -106,10 +106,66 @@ function validateGroupedTable(source: Record<string, unknown>): void {
 	}
 }
 
+function validateWaterfall(source: Record<string, unknown>): void {
+	string(source.label, "dataset.label");
+	optionalString(source.description, "dataset.description");
+	optionalString(source.coverage, "dataset.coverage");
+	const steps = source.steps;
+	if (!Array.isArray(steps) || steps.length < 2 || steps.length > 32) {
+		throw new Error("dataset.steps must contain between 2 and 32 entries.");
+	}
+	for (const [index, raw] of steps.entries()) {
+		const step = record(raw, `dataset.steps[${index}]`);
+		string(step.label, `dataset.steps[${index}].label`);
+		if (step.value !== null && (typeof step.value !== "number" || !Number.isFinite(step.value))) {
+			throw new Error(`dataset.steps[${index}].value must be a finite number or null.`);
+		}
+		if (step.display !== null && typeof step.display !== "string") {
+			throw new Error(`dataset.steps[${index}].display must be a string or null.`);
+		}
+		if (step.kind !== undefined && step.kind !== "total" && step.kind !== "delta") {
+			throw new Error(`dataset.steps[${index}].kind must be "total" or "delta".`);
+		}
+		tone(step.tone, `dataset.steps[${index}].tone`);
+	}
+}
+
+function validateStackedBar(source: Record<string, unknown>): void {
+	string(source.label, "dataset.label");
+	optionalString(source.description, "dataset.description");
+	const bars = source.bars;
+	if (!Array.isArray(bars) || bars.length < 1 || bars.length > 8) {
+		throw new Error("dataset.bars must contain between 1 and 8 entries.");
+	}
+	for (const [barIndex, rawBar] of bars.entries()) {
+		const bar = record(rawBar, `dataset.bars[${barIndex}]`);
+		string(bar.label, `dataset.bars[${barIndex}].label`);
+		if (bar.total !== null && typeof bar.total !== "string") {
+			throw new Error(`dataset.bars[${barIndex}].total must be a string or null.`);
+		}
+		const segments = bar.segments;
+		if (!Array.isArray(segments) || segments.length < 1 || segments.length > 24) {
+			throw new Error(`dataset.bars[${barIndex}].segments must contain between 1 and 24 entries.`);
+		}
+		for (const [index, rawSegment] of segments.entries()) {
+			const segment = record(rawSegment, `dataset.bars[${barIndex}].segments[${index}]`);
+			string(segment.name, `dataset.bars[${barIndex}].segments[${index}].name`);
+			if (segment.value !== null && (typeof segment.value !== "number" || !Number.isFinite(segment.value))) {
+				throw new Error(`dataset.bars[${barIndex}].segments[${index}].value must be a finite number or null.`);
+			}
+			if (segment.display !== null && typeof segment.display !== "string") {
+				throw new Error(`dataset.bars[${barIndex}].segments[${index}].display must be a string or null.`);
+			}
+		}
+	}
+}
+
 export function validateDatasetForWidget(type: DashboardWidgetType, value: unknown): void {
 	const source = record(value, "dataset");
 	if (type === "stat") validateStat(source);
 	else if (type === "timeseries") validateTimeseries(source);
 	else if (type === "table") validateTable(source);
+	else if (type === "waterfall") validateWaterfall(source);
+	else if (type === "stacked-bar") validateStackedBar(source);
 	else validateGroupedTable(source);
 }

package/extensions/fpa-dashboard/strategy-decision.ts

@@ -3,6 +3,7 @@ import { link, lstat, mkdir, open, readFile, realpath, unlink } from "node:fs/pr
 import { join } from "node:path";
 
 import { stableJson } from "../fpa-artifacts/store.ts";
+import { createDecisionPackage } from "./decision-package.ts";
 import { resolveDashboardDir } from "./publisher.ts";
 
 const SHA256_RE = /^[a-f0-9]{64}$/;
@@ -30,6 +31,21 @@ export interface CommitStrategyDecisionInput {
 	decision: "confirm" | "request_changes";
 	feedback?: string;
 	decidedAt?: string;
+	/**
+	 * Context for the decision package materialised on `confirm`. Optional so a
+	 * caller with no budget context still records the decision — the package
+	 * then carries a null budget and says so rather than inventing one.
+	 */
+	packageContext?: {
+		title?: string;
+		scopeId?: string;
+		cycleId?: string;
+		approverRole?: string;
+		owner?: string | null;
+		approvedBudgetUsd?: number | null;
+		budgetThresholdPct?: number;
+		parameters?: Record<string, unknown>;
+	};
 }
 
 export interface CommitStrategyDecisionResult {
@@ -38,6 +54,8 @@ export interface CommitStrategyDecisionResult {
 	decision: "confirm" | "request_changes";
 	strategyVersion: string;
 	handoffFingerprint: string;
+	/** Set only on `confirm` — a rejected strategy has nothing to track. */
+	decisionId?: string;
 }
 
 export interface CommittedStrategyDecision {
@@ -173,9 +191,62 @@ export async function commitStrategyDecision(cwd: string, input: CommitStrategyD
 			decision: existing.decision,
 			strategyVersion: request.strategy_version,
 			handoffFingerprint: request.handoff_fingerprint,
+			// The already-committed decision owns the timestamp. Re-deriving it
+			// here would change the package's content — and its id, across a UTC
+			// midnight — so a second submission would look like a different
+			// decision instead of the same one.
+			...(existing.decision === "confirm"
+				? { decisionId: await materialiseDecisionPackage(cwd, request, existing.decided_at, input.packageContext) }
+				: {}),
 		};
 	}
-	return { decisionFingerprint, path, decision: input.decision, strategyVersion: request.strategy_version, handoffFingerprint: request.handoff_fingerprint };
+	return {
+		decisionFingerprint,
+		path,
+		decision: input.decision,
+		strategyVersion: request.strategy_version,
+		handoffFingerprint: request.handoff_fingerprint,
+		...(input.decision === "confirm"
+			? { decisionId: await materialiseDecisionPackage(cwd, request, decision.decided_at, input.packageContext) }
+			: {}),
+	};
+}
+
+/**
+ * Turn a confirmed strategy into a trackable object.
+ *
+ * Runs after the decision record is durable, so a package can never exist for
+ * a decision that was not committed. `createDecisionPackage` is idempotent on
+ * the same inputs, which is what makes the re-commit path above safe to call.
+ */
+async function materialiseDecisionPackage(
+	cwd: string,
+	request: StrategyDecisionRequest,
+	decidedAt: string,
+	context: CommitStrategyDecisionInput["packageContext"],
+): Promise<string> {
+	const pkg = await createDecisionPackage(cwd, {
+		actionId: request.action_id,
+		strategyVersion: request.strategy_version,
+		handoffFingerprint: request.handoff_fingerprint,
+		title: context?.title ?? `执行策略 ${request.strategy_version}`,
+		scopeId: context?.scopeId ?? "unscoped",
+		cycleId: context?.cycleId ?? "uncycled",
+		approverRole: context?.approverRole ?? "CEO",
+		owner: context?.owner ?? null,
+		approvedBudgetUsd: context?.approvedBudgetUsd ?? null,
+		...(context?.budgetThresholdPct !== undefined ? { budgetThresholdPct: context.budgetThresholdPct } : {}),
+		parameters: context?.parameters ?? {},
+		approvals: [{
+			step_order: 1,
+			role: context?.approverRole ?? "CEO",
+			approver: context?.approverRole ?? "CEO",
+			action: "approved",
+			decided_at: decidedAt,
+		}],
+		approvedAt: decidedAt,
+	});
+	return pkg.decision_id;
 }
 
 export async function readCommittedStrategyDecision(cwd: string, actionId: string, decisionFingerprint: string): Promise<CommittedStrategyDecision> {

package/extensions/fpa-data/csvsource.ts

@@ -0,0 +1,296 @@
+import { readFile } from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
+
+import { getDataset, type DatasetDef } from "./registry.ts";
+import type { QuerySpec } from "./sql.ts";
+
+// ============================================================================
+// A CSV-backed executor for the same QuerySpec the SQL builder compiles.
+//
+// The registry, the query spec, the derived-metric engine, and the query
+// receipt are all shared with the Supabase path — only the execution differs.
+// That is the point: when the real finance import lands, this file is the only
+// thing that gets replaced, and every metric definition and every projector
+// keeps working untouched.
+//
+// The aggregation deliberately matches SQL, including the part people get
+// wrong: SUM over a set where every contributing value is NULL is NULL, not 0.
+// An FP&A dashboard that reports 0 for "we have no data" is worse than one
+// that reports nothing.
+// ============================================================================
+
+const MAX_FILE_BYTES = 32 * 1024 * 1024;
+const MAX_ROWS = 500_000;
+
+export const CSV_ROOT_ENV = "FPA_FINANCE_CSV_ROOT";
+
+/** Where a project's finance CSVs live, beside the projects like `.fpa-dashboard`. */
+export const FINANCE_DIR_NAME = ".fpa-finance";
+
+/**
+ * Resolve the finance CSV directory for one project.
+ *
+ * Defaults to the workspace-level `.fpa-finance/`, so a tenant reads only its
+ * own financials. The env override exists for a genuinely shared company
+ * source, and is explicit precisely because pointing every tenant at one
+ * directory is a data-leak shaped decision that should never be the default.
+ */
+export function resolveCsvRoot(env: NodeJS.ProcessEnv = process.env, workspaceRoot?: string): string {
+	const configured = env[CSV_ROOT_ENV]?.trim();
+	if (configured) {
+		if (!isAbsolute(configured)) throw new Error(`${CSV_ROOT_ENV} must be an absolute path.`);
+		return resolve(configured);
+	}
+	if (workspaceRoot) return join(resolve(workspaceRoot), FINANCE_DIR_NAME);
+	throw new Error(
+		`Finance CSV datasets need either a project directory or ${CSV_ROOT_ENV} pointing at the directory holding them. ` +
+			"No query was run.",
+	);
+}
+
+/** Parse one CSV line, honouring quoted fields and doubled quotes. */
+function parseLine(line: string): string[] {
+	const cells: string[] = [];
+	let current = "";
+	let quoted = false;
+	for (let index = 0; index < line.length; index += 1) {
+		const char = line[index];
+		if (quoted) {
+			if (char === '"' && line[index + 1] === '"') {
+				current += '"';
+				index += 1;
+			} else if (char === '"') {
+				quoted = false;
+			} else {
+				current += char;
+			}
+		} else if (char === '"') {
+			quoted = true;
+		} else if (char === ",") {
+			cells.push(current);
+			current = "";
+		} else {
+			current += char;
+		}
+	}
+	cells.push(current);
+	return cells;
+}
+
+export interface CsvTable {
+	headers: string[];
+	rows: Array<Record<string, string>>;
+}
+
+export async function readCsvTable(path: string): Promise<CsvTable> {
+	let raw: string;
+	try {
+		raw = await readFile(path, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			throw new Error(`Finance CSV file does not exist: ${path}`);
+		}
+		throw error;
+	}
+	if (Buffer.byteLength(raw, "utf8") > MAX_FILE_BYTES) {
+		throw new Error(`Finance CSV file exceeds the ${MAX_FILE_BYTES / (1024 * 1024)}MB limit: ${path}`);
+	}
+	const lines = raw.split("\n").filter((line, index) => index === 0 || line.trim() !== "");
+	if (lines.length === 0) throw new Error(`Finance CSV file is empty: ${path}`);
+	const headers = parseLine(lines[0]).map((header) => header.trim());
+	const rows: Array<Record<string, string>> = [];
+	for (const line of lines.slice(1)) {
+		if (rows.length >= MAX_ROWS) throw new Error(`Finance CSV file exceeds the ${MAX_ROWS}-row limit: ${path}`);
+		const cells = parseLine(line);
+		const row: Record<string, string> = {};
+		headers.forEach((header, index) => { row[header] = cells[index] ?? ""; });
+		rows.push(row);
+	}
+	return { headers, rows };
+}
+
+/** An empty cell is missing, not zero. */
+function cellValue(raw: string | undefined): number | null {
+	if (raw === undefined || raw.trim() === "") return null;
+	const parsed = Number(raw);
+	return Number.isFinite(parsed) ? parsed : null;
+}
+
+/**
+ * The row's date, normalised so a YYYY-MM column compares against the
+ * YYYY-MM-DD bounds the query spec carries.
+ */
+function rowDate(value: string | undefined, format: "month" | "date"): string | null {
+	if (!value || value.trim() === "") return null;
+	const text = value.trim();
+	return format === "month" ? `${text}-01` : text;
+}
+
+interface Accumulator {
+	sum: number;
+	count: number;
+	/** Null until a non-null value arrives, which is what keeps all-NULL null. */
+	seen: boolean;
+	min: number;
+	max: number;
+	last: number | null;
+}
+
+function aggregate(accumulator: Accumulator, fn: "sum" | "avg" | "min" | "max" | "last"): number | null {
+	if (!accumulator.seen) return null;
+	switch (fn) {
+		case "sum": return accumulator.sum;
+		case "avg": return accumulator.count === 0 ? null : accumulator.sum / accumulator.count;
+		case "min": return accumulator.min;
+		case "max": return accumulator.max;
+		case "last": return accumulator.last;
+	}
+}
+
+export interface CsvQueryResult {
+	rows: Array<Record<string, unknown>>;
+	dataset: DatasetDef;
+	measures: string[];
+	dimensions: string[];
+	notes: string[];
+}
+
+export async function runCsvQuery(
+	spec: QuerySpec,
+	env: NodeJS.ProcessEnv = process.env,
+	workspaceRoot?: string,
+): Promise<CsvQueryResult> {
+	const dataset = getDataset(spec.dataset);
+	if (dataset.source !== "csv" || !dataset.csv) throw new Error(`Dataset "${dataset.id}" is not CSV-backed.`);
+	for (const unsupported of ["exactUaScope", "exactUaPortfolioScope", "exactUaChannelScope"] as const) {
+		if (spec[unsupported] !== undefined) throw new Error(`${unsupported} is supported only for ua_spend.`);
+	}
+
+	const notes: string[] = [];
+	const dimensionNames = spec.dimensions ?? [];
+	const dimensionDefs = dimensionNames.map((name) => {
+		const def = dataset.dimensions.find((dimension) => dimension.name === name);
+		if (!def) {
+			throw new Error(
+				`Unknown dimension "${name}" for dataset "${dataset.id}". ` +
+					`Available: ${dataset.dimensions.map((dimension) => dimension.name).join(", ")}.`,
+			);
+		}
+		return def;
+	});
+
+	// Resolve metrics against the same registry rules the SQL path uses:
+	// a derived metric pulls in its numerator and denominator.
+	const baseNames = new Set(dataset.measures.map((measure) => measure.name));
+	const derivedByName = new Map(dataset.derived.map((derived) => [derived.name, derived]));
+	const selected = new Set<string>();
+	const derived: DatasetDef["derived"] = [];
+	for (const metric of spec.metrics) {
+		if (baseNames.has(metric)) {
+			selected.add(metric);
+		} else if (derivedByName.has(metric)) {
+			const def = derivedByName.get(metric)!;
+			derived.push(def);
+			selected.add(def.numerator);
+			selected.add(def.denominator);
+		} else {
+			throw new Error(
+				`Unknown metric "${metric}" for dataset "${dataset.id}". ` +
+					`Available metrics: ${[...baseNames, ...derivedByName.keys()].join(", ")}.`,
+			);
+		}
+	}
+	if (selected.size === 0) throw new Error("At least one metric is required.");
+
+	const table = await readCsvTable(join(resolveCsvRoot(env, workspaceRoot), dataset.csv.file));
+	const dateFormat = dataset.csv.dateFormat ?? "date";
+
+	const filters: Array<{ column: string; values: Set<string> }> = [];
+	for (const [key, raw] of Object.entries(spec.filters ?? {})) {
+		const def = dataset.dimensions.find((dimension) => dimension.name === key);
+		if (!def) {
+			throw new Error(
+				`Unknown filter field "${key}" for dataset "${dataset.id}". ` +
+					`Filterable fields: ${dataset.dimensions.map((dimension) => dimension.name).join(", ")}. ` +
+					"Use dateFrom/dateTo for the date range.",
+			);
+		}
+		const values = Array.isArray(raw) ? raw : [raw];
+		if (values.length === 0) throw new Error("Filter arrays must contain at least one value.");
+		filters.push({ column: def.sql, values: new Set(values.map(String)) });
+	}
+
+	const groups = new Map<string, { key: Record<string, string>; accumulators: Map<string, Accumulator>; sourceRows: number }>();
+	for (const row of table.rows) {
+		const date = rowDate(row[dataset.dateColumn], dateFormat);
+		if (spec.dateFrom && (date === null || date < spec.dateFrom)) continue;
+		if (spec.dateTo && (date === null || date > spec.dateTo)) continue;
+		if (filters.some((filter) => !filter.values.has(row[filter.column] ?? ""))) continue;
+
+		const key = Object.fromEntries(dimensionDefs.map((def) => [def.name, row[def.sql] ?? ""]));
+		const groupKey = dimensionDefs.map((def) => row[def.sql] ?? "").join("");
+		let group = groups.get(groupKey);
+		if (!group) {
+			group = { key, accumulators: new Map(), sourceRows: 0 };
+			groups.set(groupKey, group);
+		}
+		group.sourceRows += 1;
+		for (const measure of selected) {
+			const column = dataset.measures.find((entry) => entry.name === measure)!.sql;
+			const value = cellValue(row[column]);
+			let accumulator = group.accumulators.get(measure);
+			if (!accumulator) {
+				accumulator = { sum: 0, count: 0, seen: false, min: Infinity, max: -Infinity, last: null };
+				group.accumulators.set(measure, accumulator);
+			}
+			// A NULL contributes nothing and does not make the group non-null.
+			if (value === null) continue;
+			accumulator.seen = true;
+			accumulator.sum += value;
+			accumulator.count += 1;
+			accumulator.min = Math.min(accumulator.min, value);
+			accumulator.max = Math.max(accumulator.max, value);
+			accumulator.last = value;
+		}
+	}
+
+	let rows = [...groups.values()].map((group) => {
+		const out: Record<string, unknown> = { ...group.key, source_rows: group.sourceRows };
+		for (const measure of selected) {
+			const fn = dataset.csv!.aggregates[measure] ?? "sum";
+			const accumulator = group.accumulators.get(measure);
+			out[measure] = accumulator ? aggregate(accumulator, fn) : null;
+		}
+		return out;
+	});
+
+	if (spec.sort) {
+		const { by, direction = "desc" } = spec.sort;
+		if (!selected.has(by) && !dimensionNames.includes(by) && !derived.some((def) => def.name === by)) {
+			throw new Error(`Cannot sort by "${by}": it is not a selected metric or dimension.`);
+		}
+		rows.sort((left, right) => {
+			const a = left[by];
+			const b = right[by];
+			// Nulls sort last in both directions: a missing value is not the
+			// smallest value, it is an absent one.
+			if (a === null && b === null) return 0;
+			if (a === null) return 1;
+			if (b === null) return -1;
+			const comparison = typeof a === "number" && typeof b === "number" ? a - b : String(a).localeCompare(String(b));
+			return direction === "asc" ? comparison : -comparison;
+		});
+	} else if (dimensionNames.length > 0) {
+		rows.sort((left, right) => dimensionNames
+			.map((name) => String(left[name] ?? "").localeCompare(String(right[name] ?? "")))
+			.find((value) => value !== 0) ?? 0);
+	}
+
+	const limit = spec.limit ?? 200;
+	if (rows.length > limit) {
+		notes.push(`Returned the first ${limit} of ${rows.length} groups.`);
+		rows = rows.slice(0, limit);
+	}
+
+	return { rows, dataset, measures: [...selected], dimensions: dimensionNames, notes };
+}