gasp-standard-mcp 1.10.0 → 1.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +30 -22
- package/build/compile.d.ts +50 -0
- package/build/compile.js +268 -0
- package/build/derive.d.ts +30 -0
- package/build/derive.js +300 -0
- package/build/export-data.js +3 -0
- package/build/formula.d.ts +185 -0
- package/build/formula.js +674 -0
- package/build/index.js +133 -299
- package/build/loader.d.ts +18 -0
- package/build/loader.js +161 -32
- package/build/ossie/check.d.ts +12 -0
- package/build/ossie/check.js +274 -0
- package/build/ossie/index.d.ts +10 -0
- package/build/ossie/index.js +26 -0
- package/build/ossie/mapping.d.ts +21 -0
- package/build/ossie/mapping.js +55 -0
- package/build/ossie/metrics.d.ts +29 -0
- package/build/ossie/metrics.js +266 -0
- package/build/ossie/model.d.ts +25 -0
- package/build/ossie/model.js +198 -0
- package/build/ossie/names.d.ts +28 -0
- package/build/ossie/names.js +12 -0
- package/build/ossie/ontology.d.ts +85 -0
- package/build/ossie/ontology.js +257 -0
- package/build/ossie/types.d.ts +168 -0
- package/build/ossie/types.js +10 -0
- package/build/ossie/validate.d.ts +7 -0
- package/build/ossie/validate.js +40 -0
- package/build/standard-data.json +1 -1
- package/build/standard-version.json +1 -1
- package/build/tools.d.ts +62 -0
- package/build/tools.js +277 -0
- package/build/traversal.js +4 -3
- package/build/types.d.ts +90 -1
- package/package.json +13 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# gasp-standard-mcp
|
|
2
2
|
|
|
3
|
-
MCP server for the [GASP Standard](https://gaspwiki.com)
|
|
3
|
+
MCP server for the [GASP Standard](https://gaspwiki.com), the Generally Accepted SaaS Principles standard for metric definitions, formulas, benchmarks and relationships.
|
|
4
4
|
|
|
5
5
|
Works with Claude Code, Claude Desktop, or any [MCP](https://modelcontextprotocol.io/)-compatible client.
|
|
6
6
|
|
|
@@ -33,38 +33,44 @@ Restart your MCP client after adding the config.
|
|
|
33
33
|
|
|
34
34
|
| Tool | Description |
|
|
35
35
|
|------|-------------|
|
|
36
|
-
| `lookup_metric` | Full metric details: definition, formula, benchmarks, entity, common mistakes, sources and page URL. Falls back to glossary terms when no metric matches |
|
|
37
|
-
| `lookup_definition` | Glossary term lookup (e.g. Signal Type, Sensitivity Tier, Access Scope, Metric Owner, CEL): full definition, section, canonical or reference link and page URL |
|
|
36
|
+
| `lookup_metric` | Full metric details: definition, formula, benchmarks, entity, common mistakes, sources and page URL. Matches exactly (name with or without its abbreviation, abbreviation, alias, slug or graph label) and suggests close names instead of guessing. Falls back to glossary terms when no metric matches |
|
|
37
|
+
| `lookup_definition` | Glossary term lookup (e.g. Signal Type, Sensitivity Tier, Access Scope, Metric Owner, CEL): full definition, section, canonical or reference link and page URL. Matches exactly and suggests close terms instead of guessing |
|
|
38
38
|
| `list_metrics` | List all metrics, optionally filtered by department and/or signal type |
|
|
39
|
-
| `get_formula` |
|
|
40
|
-
| `get_relationships` | Upstream/downstream relationships for metrics, entities
|
|
41
|
-
| `get_data_requirements` | Data requirements for implementing a metric: fields, types, grain, source
|
|
42
|
-
| `search` | Full-text search across metrics, definitions
|
|
43
|
-
| `generate_query` |
|
|
44
|
-
| `validate_adapter` | Validate a GASP adapter mapping file
|
|
45
|
-
| `infer_drivers` | Diagnose what could explain an observed metric movement
|
|
39
|
+
| `get_formula` | Canonical formula in the GASP formula grammar, with unit, O/M forms, variants, inputs with polarity, raw fields and the datasets they live in. Metrics that cannot be computed carry the reason |
|
|
40
|
+
| `get_relationships` | Upstream/downstream relationships for metrics, entities or concepts. 21 relationship types across signal, lifecycle, ownership, interaction and financial flow categories |
|
|
41
|
+
| `get_data_requirements` | Data requirements for implementing a metric: fields, types, grain, source and example SQL |
|
|
42
|
+
| `search` | Full-text search across metrics, definitions and data requirements. Metric and definition hits include their gaspwiki.com URL |
|
|
43
|
+
| `generate_query` | Compile warehouse-specific SQL from the metric's canonical formula and an adapter mapping. One scalar subquery per aggregate, each reading the table mapped for its dataset, with `:period_start` and `:period_end` parameters. Unmapped fields stay as `{{field@dataset}}` placeholders. Matches the metric exactly and suggests close names instead of guessing |
|
|
44
|
+
| `validate_adapter` | Validate a GASP adapter mapping file (schema 1.1). Reports schema-level problems, unknown fields and datasets, dataset table conflicts, enum fields mapped without a transform and covered metrics without an owner. Computes coverage per metric against the exact field and dataset pairs its compiled SQL reads (full, partial or none) and ranks the highest-value next pairs to map |
|
|
45
|
+
| `infer_drivers` | Diagnose what could explain an observed metric movement: ranked upstream candidates with paths and per-step edge classifications |
|
|
46
46
|
| `explain_path` | Enumerate edge chains between two metrics, with classification (metric_signal / structural / lifecycle / behavioral / assignment / generative) per step |
|
|
47
47
|
| `coverage_gap` | Audit a metric set: identify one-hop upstream/downstream metrics not in the set, plus any disconnected metrics |
|
|
48
48
|
|
|
49
|
-
The traversal tools (`infer_drivers`, `explain_path`, `coverage_gap`) return *structure*
|
|
49
|
+
The traversal tools (`infer_drivers`, `explain_path`, `coverage_gap`) return *structure* (paths, classifications, attenuation scores), not numeric forecasts. They serve diagnosis, exploration and coverage-audit workflows respectively and compose: use `infer_drivers` to pick candidates, `explain_path` to scrutinise a chain, then `coverage_gap` to check whether the candidate is being measured. For counterfactual "what if" simulation, use the [TWIN Modifier](https://gaspwiki.com/v1/twin-modifier).
|
|
50
50
|
|
|
51
51
|
## Data
|
|
52
52
|
|
|
53
|
+
Version 1.12.0.
|
|
54
|
+
|
|
53
55
|
- 300 metrics across 13 departments
|
|
54
56
|
- 92 glossary definitions (80 SaaS domain + 12 GASP framework)
|
|
55
|
-
- 82 relationship nodes (60 metrics + 15 entities + 7 concepts),
|
|
57
|
+
- 82 relationship nodes (60 metrics + 15 entities + 7 concepts), 172 edges
|
|
56
58
|
- 21 relationship types: metric signal (drives, reduces, predicts, component, measures), entity lifecycle (converts_to, parent_of, belongs_to), entity ownership (owns, grants, priced_by), entity interactions (manages, serves, engages_via, submits, represented_by, sources), entity financial flows (generates, produces, contributes_to, incurs)
|
|
57
|
-
-
|
|
58
|
-
-
|
|
59
|
-
-
|
|
60
|
-
-
|
|
61
|
-
-
|
|
62
|
-
-
|
|
59
|
+
- 270 data requirements, one per metric with a formula, compiled from the formula at load time: fields with types, datasets, grain and a compiled example query
|
|
60
|
+
- 270 query templates, one per metric with a formula, compiled from the formulas by the same step (no hand-written SQL). Every field placeholder names the dataset it is read from (`{{customer_status@customer}}`), so `generate_query` resolves per-dataset adapter mappings by tag, including inside cohort subqueries. The grammar's `window(expr, n unit)` gives DAU, WAU and MAU their 1, 7 and 30 day windows and `all_time(expr)` lets retention numerators read past the period end; intervals are emitted in units Postgres accepts
|
|
61
|
+
- The test suite executes every compiled template against a seeded fixture in an in-process Postgres (PGlite) and checks ten metrics against independently computed values
|
|
62
|
+
- Apache Ossie (incubating) export, written by `npm run derive` to https://gaspwiki.com/downloads/ossie/: `gasp.ontology.yaml` (every dataset and GASP concept as an entity type, every field as a value type or relationship, enum values as constraints), `gasp.semantic_model.yaml` (the 47 datasets with `OSSIE_SQL_2026` field expressions, 40 foreign-key relationships and every canonical formula as a metric: 164 direct expressions, 138 staged through per-period datasets that carry the compiled SQL, O/M forms and variants as separate metrics with the form in `custom_extensions`), `gasp.mapping.yaml` (the ontology mapped onto the model) and `coverage.json` (how each formula was exported and why). All three documents pass the upstream validator, vendored at `ossie-validator/`, plus GASP's own cross-reference checks (`src/ossie/check.ts`), which catch what the upstream validator does not
|
|
63
|
+
- 15 business entities (Customer, Subscription, License, Lead, Opportunity, User, Ticket, Employee, Invoice, Partner, Project, Plan, Product, Campaign and Contact)
|
|
64
|
+
- 7 business concepts (Revenue, Bookings, COGS, Cohort, Pipeline, Segment and TCV)
|
|
65
|
+
- 251 canonical fields across 47 datasets (event, snapshot and fact tables with date and key fields, entities, CEL class and activation rules). Enum fields declare their allowed values
|
|
66
|
+
- 59 structured formulas with decomposed inputs (metric refs + field refs)
|
|
67
|
+
- Canonical formulas for every metric in the GASP formula grammar (`standard/formulas.json`): 289 entries covering all 300 metrics (270 with formulas, 19 marked not computable with a reason, 2 department-qualified ids for shared headings), with units, O/M forms for ARR, NRR, CAC, LTV and Gross Margin (a form can reference another metric's form, `metric.gross_margin.O`) and variants such as Adjusted NRR (served by `get_formula` and compiled by `generate_query` and `get_data_requirements`)
|
|
63
68
|
- Access control classifications for every graph metric (sensitivity tier + access scope)
|
|
64
69
|
- CEL `change_nature` field for revenue quality analysis (Adjusted NRR/GRR)
|
|
65
70
|
- Per-department cross-references (e.g. NRR under Customer Success, Gross Margin under Finance) now resolve to the full canonical content via slug lookup
|
|
66
71
|
- Every metric and definition result carries its gaspwiki.com page URL; definitions keep their full body and reference links
|
|
67
72
|
- Access classifications, structured formulas and entity mappings resolve for every graph metric, including cross-reference records (e.g. NRR under Customer Success, CAC under Marketing)
|
|
73
|
+
- Adapter schema 1.1 (`standard/gasp-adapter-schema.json`): a `datasets` map, per-dataset mappings (a mapping names its `dataset`), informational fields and `$schema`. A ready template ships at `gasp-wiki-frontend/public/downloads/gasp-adapter-template.json` and is tested against the public copy of the schema at https://gaspwiki.com/schemas/gasp-adapter-v1.json, which `npm run derive` writes from the canonical file
|
|
68
74
|
- Sources: the canonical [GASP Standard](https://gaspwiki.com) files
|
|
69
75
|
|
|
70
76
|
## Examples
|
|
@@ -85,11 +91,13 @@ Once installed, ask your AI assistant:
|
|
|
85
91
|
- "Search for churn"
|
|
86
92
|
|
|
87
93
|
**Diagnosis, exploration and coverage** (new in 1.9.0)
|
|
88
|
-
- "ARR is down this month. What could explain it?"
|
|
89
|
-
- "How does
|
|
90
|
-
- "We track ARR, NRR, GRR, CAC and CAC Payback. What important metrics are we missing?"
|
|
91
|
-
- "Why might NRR be slipping? Trace the path back through Health Score."
|
|
94
|
+
- "ARR is down this month. What could explain it?" (`infer_drivers`)
|
|
95
|
+
- "How does Health Score eventually affect NRR?" (`explain_path`)
|
|
96
|
+
- "We track ARR, NRR, GRR, CAC and CAC Payback. What important metrics are we missing?" (`coverage_gap`)
|
|
97
|
+
- "Why might NRR be slipping? Trace the path back through Health Score." (composes `infer_drivers` and `explain_path`)
|
|
92
98
|
|
|
93
99
|
## License
|
|
94
100
|
|
|
101
|
+
<!-- TODO: add a "Source" link and package.json "repository" field to https://github.com/GASP-Standard/gasp once the repository is public. -->
|
|
102
|
+
|
|
95
103
|
Apache-2.0
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Compiles GASP formulas (src/formula.ts) to parameterised ANSI SQL.
|
|
3
|
+
*
|
|
4
|
+
* Every aggregate becomes a scalar subquery over one dataset, so metrics that
|
|
5
|
+
* combine several datasets need no joins: each aggregate is a number per
|
|
6
|
+
* period. Placeholders:
|
|
7
|
+
* {{<field>@<dataset>}} a canonical field on the logical table it is read
|
|
8
|
+
* from; the adapter maps the pair to a column. The tag
|
|
9
|
+
* is what lets a filler resolve a field that lives on
|
|
10
|
+
* several datasets (snapshot_date, customer_id) without
|
|
11
|
+
* parsing the SQL; exampleSql() strips it for display
|
|
12
|
+
* {{_table:<dataset>}} the warehouse table behind a dataset
|
|
13
|
+
* {{_period_start}}, {{_period_end}} reporting period bounds (dates)
|
|
14
|
+
*
|
|
15
|
+
* Period semantics by dataset kind: event and fact rows are filtered to the
|
|
16
|
+
* period by the dataset's date field; snapshot rows are taken as of the period
|
|
17
|
+
* end, or the point named by `at`. `to_date` widens an event or fact filter to
|
|
18
|
+
* everything up to the period end. `window` replaces it with the n units ending
|
|
19
|
+
* at the period end. `all_time` drops it. `lag` shifts both bounds. `over cohort`
|
|
20
|
+
* restricts every aggregate to keys present in the key's dataset at the point.
|
|
21
|
+
* Intervals are emitted in units Postgres accepts (a quarter is 3 months).
|
|
22
|
+
*/
|
|
23
|
+
import { type LagUnit } from "./formula.js";
|
|
24
|
+
import type { MetricFormula, OntologyDataset, OntologyField } from "./types.js";
|
|
25
|
+
export interface CompileContext {
|
|
26
|
+
fields: Record<string, OntologyField>;
|
|
27
|
+
datasets: Record<string, OntologyDataset>;
|
|
28
|
+
formulas: Record<string, MetricFormula>;
|
|
29
|
+
}
|
|
30
|
+
export interface Compiled {
|
|
31
|
+
/** Scalar SELECT with placeholders */
|
|
32
|
+
sql: string;
|
|
33
|
+
/** Every field the SQL reads, including through metric refs */
|
|
34
|
+
fields: string[];
|
|
35
|
+
/** Every (field, dataset) pair the SQL reads, as "field@dataset" */
|
|
36
|
+
placeholders: string[];
|
|
37
|
+
datasets: string[];
|
|
38
|
+
metricRefs: string[];
|
|
39
|
+
/** Uses cohort or lag, so it cannot run as one Ossie aggregate */
|
|
40
|
+
staged: boolean;
|
|
41
|
+
}
|
|
42
|
+
export declare class CompileError extends Error {
|
|
43
|
+
}
|
|
44
|
+
/** An interval literal in units Postgres, Redshift and Snowflake accept. */
|
|
45
|
+
export declare function interval(n: number, unit: LagUnit): string;
|
|
46
|
+
export declare function compileMetric(id: string, ctx: CompileContext, variant?: string): Compiled;
|
|
47
|
+
/** Replace placeholders with plain names, for documentation examples. */
|
|
48
|
+
export declare function exampleSql(sql: string): string;
|
|
49
|
+
/** Strip the dataset tag from a field placeholder: "{{mrr@subscription}}" -> "{{mrr}}". */
|
|
50
|
+
export declare function untagged(sql: string): string;
|
package/build/compile.js
ADDED
|
@@ -0,0 +1,268 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Compiles GASP formulas (src/formula.ts) to parameterised ANSI SQL.
|
|
3
|
+
*
|
|
4
|
+
* Every aggregate becomes a scalar subquery over one dataset, so metrics that
|
|
5
|
+
* combine several datasets need no joins: each aggregate is a number per
|
|
6
|
+
* period. Placeholders:
|
|
7
|
+
* {{<field>@<dataset>}} a canonical field on the logical table it is read
|
|
8
|
+
* from; the adapter maps the pair to a column. The tag
|
|
9
|
+
* is what lets a filler resolve a field that lives on
|
|
10
|
+
* several datasets (snapshot_date, customer_id) without
|
|
11
|
+
* parsing the SQL; exampleSql() strips it for display
|
|
12
|
+
* {{_table:<dataset>}} the warehouse table behind a dataset
|
|
13
|
+
* {{_period_start}}, {{_period_end}} reporting period bounds (dates)
|
|
14
|
+
*
|
|
15
|
+
* Period semantics by dataset kind: event and fact rows are filtered to the
|
|
16
|
+
* period by the dataset's date field; snapshot rows are taken as of the period
|
|
17
|
+
* end, or the point named by `at`. `to_date` widens an event or fact filter to
|
|
18
|
+
* everything up to the period end. `window` replaces it with the n units ending
|
|
19
|
+
* at the period end. `all_time` drops it. `lag` shifts both bounds. `over cohort`
|
|
20
|
+
* restricts every aggregate to keys present in the key's dataset at the point.
|
|
21
|
+
* Intervals are emitted in units Postgres accepts (a quarter is 3 months).
|
|
22
|
+
*/
|
|
23
|
+
import { parseFormula } from "./formula.js";
|
|
24
|
+
export class CompileError extends Error {
|
|
25
|
+
}
|
|
26
|
+
const TEMPORAL = new Set(["date", "timestamp"]);
|
|
27
|
+
/** An interval literal in units Postgres, Redshift and Snowflake accept. */
|
|
28
|
+
export function interval(n, unit) {
|
|
29
|
+
return unit === "quarter" ? `INTERVAL '${n * 3} month'` : `INTERVAL '${n} ${unit}'`;
|
|
30
|
+
}
|
|
31
|
+
export function compileMetric(id, ctx, variant) {
|
|
32
|
+
const f = ctx.formulas[id];
|
|
33
|
+
if (!f)
|
|
34
|
+
throw new CompileError(`No formula for '${id}'`);
|
|
35
|
+
const src = variant ? f.forms?.[variant] ?? f.variants?.[variant] : f.formula;
|
|
36
|
+
if (!src)
|
|
37
|
+
throw new CompileError(f.notComputable ? `'${id}' is not computable: ${f.notComputable}` : `'${id}' has no ${variant ?? "formula"}`);
|
|
38
|
+
const c = new Compiler(ctx);
|
|
39
|
+
const body = c.formula(parseFormula(src), { toDate: false, shift: [], path: [id] });
|
|
40
|
+
return {
|
|
41
|
+
sql: `SELECT ${body} AS ${id.replace(/[^a-z0-9_]/gi, "_")}`,
|
|
42
|
+
fields: [...c.fields].sort(),
|
|
43
|
+
placeholders: [...c.placeholders].sort(),
|
|
44
|
+
datasets: [...c.datasets].sort(),
|
|
45
|
+
metricRefs: [...c.metricRefs].sort(),
|
|
46
|
+
staged: c.staged,
|
|
47
|
+
};
|
|
48
|
+
}
|
|
49
|
+
/** Replace placeholders with plain names, for documentation examples. */
|
|
50
|
+
export function exampleSql(sql) {
|
|
51
|
+
return sql
|
|
52
|
+
.replace(/\{\{_table:(\w+)\}\}/g, "$1")
|
|
53
|
+
.replace(/\{\{_period_start\}\}/g, ":period_start")
|
|
54
|
+
.replace(/\{\{_period_end\}\}/g, ":period_end")
|
|
55
|
+
.replace(/\{\{(\w+)@\w+\}\}/g, "$1");
|
|
56
|
+
}
|
|
57
|
+
/** Strip the dataset tag from a field placeholder: "{{mrr@subscription}}" -> "{{mrr}}". */
|
|
58
|
+
export function untagged(sql) {
|
|
59
|
+
return sql.replace(/\{\{(\w+)@\w+\}\}/g, "{{$1}}");
|
|
60
|
+
}
|
|
61
|
+
class Compiler {
|
|
62
|
+
ctx;
|
|
63
|
+
fields = new Set();
|
|
64
|
+
placeholders = new Set();
|
|
65
|
+
datasets = new Set();
|
|
66
|
+
metricRefs = new Set();
|
|
67
|
+
staged = false;
|
|
68
|
+
constructor(ctx) {
|
|
69
|
+
this.ctx = ctx;
|
|
70
|
+
}
|
|
71
|
+
formula(f, scope) {
|
|
72
|
+
const s = f.cohort ? { ...scope, cohort: scope.cohort ?? f.cohort } : scope;
|
|
73
|
+
if (f.cohort) {
|
|
74
|
+
this.staged = true;
|
|
75
|
+
this.fields.add(f.cohort.key);
|
|
76
|
+
}
|
|
77
|
+
return this.expr(f.expr, s);
|
|
78
|
+
}
|
|
79
|
+
bound(point, scope) {
|
|
80
|
+
let b = `{{_period_${point === "period_start" ? "start" : "end"}}}`;
|
|
81
|
+
for (const sh of scope.shift)
|
|
82
|
+
b = `(${b} - ${interval(sh.n, sh.unit)})`;
|
|
83
|
+
return b;
|
|
84
|
+
}
|
|
85
|
+
/** A tagged field placeholder on the given dataset. */
|
|
86
|
+
ph(field, ds) {
|
|
87
|
+
this.fields.add(field);
|
|
88
|
+
this.placeholders.add(`${field}@${ds}`);
|
|
89
|
+
return `{{${field}@${ds}}}`;
|
|
90
|
+
}
|
|
91
|
+
type(id) {
|
|
92
|
+
return this.ctx.fields[id]?.type;
|
|
93
|
+
}
|
|
94
|
+
isTemporal(n) {
|
|
95
|
+
if (n.kind === "field")
|
|
96
|
+
return TEMPORAL.has(this.type(n.id) ?? "");
|
|
97
|
+
if (n.kind === "period_bound")
|
|
98
|
+
return true;
|
|
99
|
+
return false;
|
|
100
|
+
}
|
|
101
|
+
expr(n, scope) {
|
|
102
|
+
switch (n.kind) {
|
|
103
|
+
case "number": return String(n.value);
|
|
104
|
+
case "string": return `'${n.value.replace(/'/g, "''")}'`;
|
|
105
|
+
case "boolean": return n.value ? "TRUE" : "FALSE";
|
|
106
|
+
case "field":
|
|
107
|
+
if (!scope.dataset)
|
|
108
|
+
throw new CompileError(`field.${n.id} outside an aggregate`);
|
|
109
|
+
return this.ph(n.id, scope.dataset);
|
|
110
|
+
case "period_bound": return this.bound(n.point, scope);
|
|
111
|
+
case "period_days": return `(${this.bound("period_end", scope)} - ${this.bound("period_start", scope)} + 1)`;
|
|
112
|
+
case "metric": return this.metric(n.id, scope, n.form);
|
|
113
|
+
case "neg": return `(-${this.expr(n.arg, scope)})`;
|
|
114
|
+
case "binary": {
|
|
115
|
+
const l = this.expr(n.left, scope);
|
|
116
|
+
const r = this.expr(n.right, scope);
|
|
117
|
+
if (n.op === "-" && this.isTemporal(n.left) && this.isTemporal(n.right)) {
|
|
118
|
+
const ts = [n.left, n.right].some((x) => x.kind === "field" && this.type(x.id) === "timestamp");
|
|
119
|
+
return ts ? `(EXTRACT(EPOCH FROM (${l} - ${r})) / 86400.0)` : `(${l} - ${r})`;
|
|
120
|
+
}
|
|
121
|
+
// Cast the numerator so COUNT / COUNT is not integer division (Postgres, Redshift, SQL Server).
|
|
122
|
+
if (n.op === "/")
|
|
123
|
+
return n.right.kind === "number" ? `(CAST(${l} AS DOUBLE PRECISION) / ${r})` : `(CAST(${l} AS DOUBLE PRECISION) / NULLIF(${r}, 0))`;
|
|
124
|
+
return `(${l} ${n.op} ${r})`;
|
|
125
|
+
}
|
|
126
|
+
case "scalar": {
|
|
127
|
+
const fn = { min: "LEAST", max: "GREATEST", abs: "ABS", coalesce: "COALESCE" }[n.fn];
|
|
128
|
+
return `${fn}(${n.args.map((a) => this.expr(a, scope)).join(", ")})`;
|
|
129
|
+
}
|
|
130
|
+
case "compare": return `${this.expr(n.left, scope)} ${n.op === "!=" ? "<>" : n.op} ${this.expr(n.right, scope)}`;
|
|
131
|
+
case "in": return `${this.expr(n.arg, scope)} ${n.negated ? "NOT IN" : "IN"} (${n.values.map((v) => this.expr(v, scope)).join(", ")})`;
|
|
132
|
+
case "isnull": return `${this.expr(n.arg, scope)} IS ${n.negated ? "NOT " : ""}NULL`;
|
|
133
|
+
case "logic": return `(${this.expr(n.left, scope)} ${n.op.toUpperCase()} ${this.expr(n.right, scope)})`;
|
|
134
|
+
case "not": return `NOT (${this.expr(n.arg, scope)})`;
|
|
135
|
+
case "at": return this.expr(n.arg, { ...scope, point: scope.point ?? n.point }); // outer at wins
|
|
136
|
+
case "to_date": return this.expr(n.arg, { ...scope, toDate: true });
|
|
137
|
+
case "lag":
|
|
138
|
+
this.staged = true;
|
|
139
|
+
return this.expr(n.arg, { ...scope, shift: [...scope.shift, { n: n.n, unit: n.unit }] });
|
|
140
|
+
case "window": return this.expr(n.arg, { ...scope, window: scope.window ?? { n: n.n, unit: n.unit } }); // outer window wins
|
|
141
|
+
case "all_time": return this.expr(n.arg, { ...scope, allTime: true });
|
|
142
|
+
case "agg":
|
|
143
|
+
case "percentile": return this.aggregate(n, scope);
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
/** A metric ref compiles its main formula, or the named form (metric.<id>.O). Cycles key on the id. */
|
|
147
|
+
metric(id, scope, form) {
|
|
148
|
+
if (scope.path.includes(id))
|
|
149
|
+
throw new CompileError(`Cycle: ${[...scope.path, id].join(" -> ")}`);
|
|
150
|
+
const f = this.ctx.formulas[id];
|
|
151
|
+
if (!f?.formula)
|
|
152
|
+
throw new CompileError(`metric.${id} has no formula`);
|
|
153
|
+
const src = form ? f.forms?.[form] : f.formula;
|
|
154
|
+
if (!src)
|
|
155
|
+
throw new CompileError(`metric.${id} declares no ${form} form`);
|
|
156
|
+
this.metricRefs.add(id);
|
|
157
|
+
const inner = new Compiler(this.ctx);
|
|
158
|
+
const body = inner.formula(parseFormula(src), { ...scope, path: [...scope.path, id] });
|
|
159
|
+
inner.fields.forEach((x) => this.fields.add(x));
|
|
160
|
+
inner.placeholders.forEach((x) => this.placeholders.add(x));
|
|
161
|
+
inner.datasets.forEach((x) => this.datasets.add(x));
|
|
162
|
+
inner.metricRefs.forEach((x) => this.metricRefs.add(x));
|
|
163
|
+
this.staged ||= inner.staged;
|
|
164
|
+
return `(${body})`;
|
|
165
|
+
}
|
|
166
|
+
fieldsIn(n, out = new Set()) {
|
|
167
|
+
switch (n.kind) {
|
|
168
|
+
case "field":
|
|
169
|
+
out.add(n.id);
|
|
170
|
+
break;
|
|
171
|
+
case "binary":
|
|
172
|
+
case "logic":
|
|
173
|
+
case "compare":
|
|
174
|
+
this.fieldsIn(n.left, out);
|
|
175
|
+
this.fieldsIn(n.right, out);
|
|
176
|
+
break;
|
|
177
|
+
case "in":
|
|
178
|
+
this.fieldsIn(n.arg, out);
|
|
179
|
+
n.values.forEach((v) => this.fieldsIn(v, out));
|
|
180
|
+
break;
|
|
181
|
+
case "scalar":
|
|
182
|
+
n.args.forEach((a) => this.fieldsIn(a, out));
|
|
183
|
+
break;
|
|
184
|
+
case "neg":
|
|
185
|
+
case "lag":
|
|
186
|
+
case "window":
|
|
187
|
+
case "all_time":
|
|
188
|
+
case "at":
|
|
189
|
+
case "to_date":
|
|
190
|
+
case "not":
|
|
191
|
+
case "isnull":
|
|
192
|
+
this.fieldsIn(n.arg, out);
|
|
193
|
+
break;
|
|
194
|
+
case "agg":
|
|
195
|
+
case "percentile":
|
|
196
|
+
this.fieldsIn(n.arg, out);
|
|
197
|
+
if (n.where)
|
|
198
|
+
this.fieldsIn(n.where, out);
|
|
199
|
+
break;
|
|
200
|
+
}
|
|
201
|
+
return out;
|
|
202
|
+
}
|
|
203
|
+
datasetFor(fieldIds) {
|
|
204
|
+
const sets = fieldIds.map((id) => {
|
|
205
|
+
const f = this.ctx.fields[id];
|
|
206
|
+
if (!f)
|
|
207
|
+
throw new CompileError(`Unknown field '${id}'`);
|
|
208
|
+
return f.datasets ?? [];
|
|
209
|
+
});
|
|
210
|
+
const shared = sets.reduce((a, b) => a.filter((x) => b.includes(x)));
|
|
211
|
+
if (shared.length === 0)
|
|
212
|
+
throw new CompileError(`Fields share no dataset: ${fieldIds.join(", ")}`);
|
|
213
|
+
// Prefer the dataset keyed by one of the fields, then the first declared.
|
|
214
|
+
return shared.find((d) => fieldIds.includes(this.ctx.datasets[d]?.key)) ?? shared[0];
|
|
215
|
+
}
|
|
216
|
+
aggregate(n, scope) {
|
|
217
|
+
const ids = [...this.fieldsIn(n)];
|
|
218
|
+
const ds = this.datasetFor(ids);
|
|
219
|
+
const meta = this.ctx.datasets[ds];
|
|
220
|
+
if (!meta)
|
|
221
|
+
throw new CompileError(`Unknown dataset '${ds}'`);
|
|
222
|
+
this.datasets.add(ds);
|
|
223
|
+
const s = { ...scope, dataset: ds };
|
|
224
|
+
const inner = this.expr(n.arg, s);
|
|
225
|
+
const agg = n.kind === "percentile" ? `PERCENTILE_CONT(${n.p}) WITHIN GROUP (ORDER BY ${inner})`
|
|
226
|
+
: n.fn === "count_distinct" ? `COUNT(DISTINCT ${inner})`
|
|
227
|
+
: n.fn === "median" ? `PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY ${inner})`
|
|
228
|
+
: `${n.fn.toUpperCase()}(${inner})`;
|
|
229
|
+
const where = [];
|
|
230
|
+
const date = this.ph(meta.date, ds);
|
|
231
|
+
if (meta.kind === "snapshot") {
|
|
232
|
+
if (scope.window || scope.allTime)
|
|
233
|
+
throw new CompileError(`${scope.window ? "window" : "all_time"}() does not apply to the snapshot dataset '${ds}'`);
|
|
234
|
+
where.push(`${date} = ${this.bound(scope.point ?? "period_end", scope)}`);
|
|
235
|
+
}
|
|
236
|
+
else if (scope.allTime) {
|
|
237
|
+
// The where clause bounds the rows itself (for example relative to another date field).
|
|
238
|
+
}
|
|
239
|
+
else if (scope.window) {
|
|
240
|
+
const end = this.bound(scope.point ?? "period_end", scope);
|
|
241
|
+
where.push(`${date} > (${end} - ${interval(scope.window.n, scope.window.unit)})`, `${date} <= ${end}`);
|
|
242
|
+
}
|
|
243
|
+
else if (scope.toDate) {
|
|
244
|
+
where.push(`${date} <= ${this.bound(scope.point ?? "period_end", scope)}`);
|
|
245
|
+
}
|
|
246
|
+
else if (scope.point) {
|
|
247
|
+
// A point on an event or fact dataset reads as everything up to that point.
|
|
248
|
+
where.push(`${date} <= ${this.bound(scope.point, scope)}`);
|
|
249
|
+
}
|
|
250
|
+
else {
|
|
251
|
+
where.push(`${date} >= ${this.bound("period_start", scope)}`, `${date} <= ${this.bound("period_end", scope)}`);
|
|
252
|
+
}
|
|
253
|
+
if (n.where)
|
|
254
|
+
where.push(this.expr(n.where, s));
|
|
255
|
+
if (scope.cohort && (this.ctx.fields[scope.cohort.key]?.datasets ?? []).includes(ds)) {
|
|
256
|
+
const key = scope.cohort.key;
|
|
257
|
+
const keyDs = Object.entries(this.ctx.datasets).find(([, d]) => d.key === key)?.[0];
|
|
258
|
+
if (!keyDs)
|
|
259
|
+
throw new CompileError(`Cohort key '${key}' is not the key of any dataset`);
|
|
260
|
+
this.datasets.add(keyDs);
|
|
261
|
+
const kmeta = this.ctx.datasets[keyDs];
|
|
262
|
+
const ks = { ...scope, dataset: keyDs };
|
|
263
|
+
const active = kmeta.activeWhen ? ` AND ${this.expr(parseFormula(kmeta.activeWhen).expr, ks)}` : "";
|
|
264
|
+
where.push(`${this.ph(key, ds)} IN (SELECT ${this.ph(key, keyDs)} FROM {{_table:${keyDs}}} WHERE ${this.ph(kmeta.date, keyDs)} = ${this.bound(scope.cohort.point, { ...scope, shift: [] })}${active})`);
|
|
265
|
+
}
|
|
266
|
+
return `(SELECT ${agg} FROM {{_table:${ds}}}${where.length ? ` WHERE ${where.join(" AND ")}` : ""})`;
|
|
267
|
+
}
|
|
268
|
+
}
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import type { StandardData } from "./types.js";
|
|
3
|
+
export declare const DERIVED_FILES: {
|
|
4
|
+
ontology: string;
|
|
5
|
+
relationships: string;
|
|
6
|
+
cypher: string;
|
|
7
|
+
template: string;
|
|
8
|
+
schema: string;
|
|
9
|
+
ossieOntology: string;
|
|
10
|
+
ossieModel: string;
|
|
11
|
+
ossieMapping: string;
|
|
12
|
+
ossieCoverage: string;
|
|
13
|
+
};
|
|
14
|
+
/** The canonical adapter schema; the public copy at /schemas/gasp-adapter-v1.json is written from it. */
|
|
15
|
+
export declare const SCHEMA_SOURCE: string;
|
|
16
|
+
/** Replace one top-level key's value in a JSON document without reformatting the rest. */
|
|
17
|
+
export declare function replaceJsonSection(raw: string, key: string, value: unknown): string;
|
|
18
|
+
export declare function computeDerived(data: StandardData, current: Record<keyof typeof DERIVED_FILES, string>): {
|
|
19
|
+
ontology: string;
|
|
20
|
+
relationships: string;
|
|
21
|
+
cypher: string;
|
|
22
|
+
template: string;
|
|
23
|
+
schema: string;
|
|
24
|
+
ossieOntology: string;
|
|
25
|
+
ossieModel: string;
|
|
26
|
+
ossieMapping: string;
|
|
27
|
+
ossieCoverage: string;
|
|
28
|
+
};
|
|
29
|
+
/** Current contents of every derived file; a file that does not exist yet reads as empty so the first derive writes it. */
|
|
30
|
+
export declare function readCurrent(): Record<keyof typeof DERIVED_FILES, string>;
|