spl2dql 0.0.0-stage → 0.1.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.
Files changed (44) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +18 -0
  3. package/README.md +82 -2
  4. package/bin/spl2dql.js +20 -0
  5. package/dist/inputs.d.ts +21 -0
  6. package/dist/inputs.js +130 -0
  7. package/dist/main.d.ts +41 -0
  8. package/dist/main.js +650 -0
  9. package/dist/mapping.d.ts +18 -0
  10. package/dist/mapping.js +60 -0
  11. package/dist/report.d.ts +95 -0
  12. package/dist/report.js +285 -0
  13. package/dist/safe-fs.d.ts +7 -0
  14. package/dist/safe-fs.js +81 -0
  15. package/dist/serve/server.d.ts +47 -0
  16. package/dist/serve/server.js +195 -0
  17. package/package.json +64 -3
  18. package/web/404.html +27 -0
  19. package/web/THIRD-PARTY-NOTICES.txt +774 -0
  20. package/web/_headers +26 -0
  21. package/web/assets/BatchView-CJw9TDhQ.js +1 -0
  22. package/web/assets/DashboardsView-gW0FEoq7.js +1 -0
  23. package/web/assets/DropZone-CIbk77sc.js +492 -0
  24. package/web/assets/MappingView-Co21Vkp_.js +14 -0
  25. package/web/assets/ReferenceView-S1R-kCt6.js +2 -0
  26. package/web/assets/atkinson-hyperlegible-mono-latin-ext-wght-normal-CXgNM06D.woff2 +0 -0
  27. package/web/assets/atkinson-hyperlegible-mono-latin-wght-normal-CoA7y8X5.woff2 +0 -0
  28. package/web/assets/atkinson-hyperlegible-next-latin-ext-wght-normal-C6vrW8VD.woff2 +0 -0
  29. package/web/assets/atkinson-hyperlegible-next-latin-wght-normal-BcXVPD7q.woff2 +0 -0
  30. package/web/assets/dict-9ToLi8Te.js +1 -0
  31. package/web/assets/index-BO3AM1fZ.js +46 -0
  32. package/web/assets/index-DPywAY6M.css +2 -0
  33. package/web/assets/jsx-runtime-Wy9s6hX0.js +1 -0
  34. package/web/assets/mapping-text-B64_Oh2A.js +106 -0
  35. package/web/assets/translate.worker-C2M3Sf23.js +656 -0
  36. package/web/icon-180.png +0 -0
  37. package/web/icon-192.png +0 -0
  38. package/web/icon-512.png +0 -0
  39. package/web/icon.svg +1 -0
  40. package/web/index.html +63 -0
  41. package/web/manifest.webmanifest +15 -0
  42. package/web/robots.txt +2 -0
  43. package/web/social.png +0 -0
  44. package/web/sw.js +24 -0
package/dist/main.js ADDED
@@ -0,0 +1,650 @@
1
+ import { readFileSync } from 'node:fs';
2
+ import { join, resolve } from 'node:path';
3
+ import { collectMappingNeeds, convertDashboardSource, DashboardError, expandedLength, explainDiagnostic, importSplunkConfig, listCommands, MAX_INPUT, mergeMappingSections, translate, } from '@spl2dql/core';
4
+ import { Command, CommanderError, Option } from 'commander';
5
+ import { stringify as toYaml } from 'yaml';
6
+ import { InputError, readInputs, safeFileName } from './inputs.js';
7
+ import { loadMapping, loadMappingFile, MappingError, validateMapping } from './mapping.js';
8
+ import { boardDetailSize, CONFIDENCE_WORD, detailSize, dropBoardDetail, dropDetail, htmlReport, jsonReport, reportBoard, reportResult, shown, summary, } from './report.js';
9
+ import { prepareOutDir, writeInside } from './safe-fs.js';
10
+ export const EXIT = { ok: 0, confidence: 1, usage: 2 };
11
+ const VERSION = '0.1.0';
12
+ const MAX_STDIN = 10 * 1024 * 1024;
13
+ /** DQL one run may write, dashboards included (ADR-029). */
14
+ export const MAX_RUN_OUTPUT = 200 * 1024 * 1024;
15
+ /** SPL one run may translate, after macro expansion (ADR-029). */
16
+ export const MAX_RUN_WORK = 500 * 1024 * 1024;
17
+ /** Report text with per-search detail; past it, searches are listed without detail (ADR-029). */
18
+ export const MAX_REPORT_DETAIL = 100 * 1024 * 1024;
19
+ /** The mapping file's own limits (docs/spec/mapping-config.md), for the skeleton `mapping init` writes. */
20
+ const MAX_SECTION = 10_000;
21
+ const SPL_NAME = /^[^\s`"|[\]]{1,256}$/;
22
+ const FIELD_KEY = /^[A-Za-z_@][A-Za-z0-9_.:@-]{0,255}$/;
23
+ const DATAMODEL_NAME = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*){0,7}$/;
24
+ const CONF_RANK = { none: 0, low: 1, review: 2, high: 3 };
25
+ class Exit extends Error {
26
+ code;
27
+ constructor(code) {
28
+ super(`exit ${code}`);
29
+ this.code = code;
30
+ }
31
+ }
32
+ /** Runs the CLI. Returns the exit code instead of exiting, so it can be tested in-process. */
33
+ export async function run(argv, io) {
34
+ const color = !!io.stdout.isTTY && io.env.NO_COLOR === undefined;
35
+ const runBudget = io.maxRunOutput ?? MAX_RUN_OUTPUT;
36
+ const workBudget = io.maxRunWork ?? MAX_RUN_WORK;
37
+ const reportBudget = io.maxReportDetail ?? MAX_REPORT_DETAIL;
38
+ // Text from searches can contain terminal escape sequences; strip them from everything printed.
39
+ // Our own colours are the only escapes written: a Painted part is coloured after its text has
40
+ // been made safe, so no colour code can come from the input.
41
+ const render = (parts) => parts.map((p) => (typeof p === 'string' ? safeText(p) : color ? `\u001b[${p.code}m${safeText(p.text)}\u001b[0m` : safeText(p.text))).join('');
42
+ const say = (s) => {
43
+ io.stdout.write(safeText(s));
44
+ };
45
+ const note = (...parts) => {
46
+ io.stderr.write(render(parts));
47
+ };
48
+ const program = new Command()
49
+ .name('spl2dql')
50
+ .description('Move a Splunk app to Dynatrace: SPL searches to DQL queries, dashboards to Dynatrace dashboards. Runs fully offline.')
51
+ .version(VERSION)
52
+ .exitOverride()
53
+ .configureOutput({ writeOut: say, writeErr: note })
54
+ .showHelpAfterError();
55
+ const shared = (c) => c
56
+ .option('-m, --mapping <file>', 'mapping file (YAML or JSON); default spl2dql.mapping.yaml when present')
57
+ .option('--earliest <time>', 'time-picker earliest, e.g. -24h@h')
58
+ .option('--latest <time>', 'time-picker latest, e.g. now')
59
+ .option('--strict', 'treat every missing mapping (SPL4xxx) as an error')
60
+ .addOption(new Option('--fail-on <level>', 'exit 1 when confidence is at or below this level').choices(['review', 'low']))
61
+ .option('-q, --quiet', 'do not print notes');
62
+ /**
63
+ * The mapping to translate with: the mapping file, with definitions from Splunk configuration
64
+ * files (macros.conf, props.conf …) found among the inputs laid underneath. The mapping file wins.
65
+ */
66
+ const resolveMapping = (o, inputs) => {
67
+ const loaded = loadMappingFile(o.mapping, io.cwd);
68
+ const data = loaded?.data ?? { version: 1 };
69
+ if (!inputs || inputs.configs.length === 0)
70
+ return loaded ? { mapping: loaded.mapping, data } : { data };
71
+ const imported = importSplunkConfig(inputs.configs, loaded?.mapping);
72
+ const merged = mergeMappingSections(data, imported.sections);
73
+ return { mapping: validateMapping(merged, 'The mapping built from the Splunk configuration files'), imported, data: merged };
74
+ };
75
+ const describeImport = (imported) => {
76
+ if (!imported)
77
+ return;
78
+ const c = imported.counts;
79
+ const parts = [
80
+ c.macros > 0 ? `${c.macros} macro(s)` : '',
81
+ c.extractions > 0 ? `${c.extractions} field extraction(s)` : '',
82
+ c.eventtypes > 0 ? `${c.eventtypes} eventtype(s)` : '',
83
+ c.tags > 0 ? `${c.tags} tag(s)` : '',
84
+ ].filter(Boolean);
85
+ if (parts.length > 0)
86
+ note(`Using ${parts.join(', ')} from the Splunk configuration files.\n`);
87
+ if (imported.skipped.length > 0)
88
+ note(`${imported.skipped.length} definition(s) could not be carried over; "spl2dql mapping init" lists them.\n`);
89
+ };
90
+ const optionsFrom = (o, inputs) => {
91
+ const { mapping, imported } = resolveMapping(o, inputs);
92
+ const translateOptions = {};
93
+ if (mapping)
94
+ translateOptions.mapping = mapping;
95
+ if (o.earliest || o.latest) {
96
+ translateOptions.timeRange = {};
97
+ if (o.earliest)
98
+ translateOptions.timeRange.earliest = String(o.earliest);
99
+ if (o.latest)
100
+ translateOptions.timeRange.latest = String(o.latest);
101
+ }
102
+ if (o.strict)
103
+ translateOptions.strict = true;
104
+ const out = { translate: translateOptions };
105
+ if (mapping)
106
+ out.mapping = mapping;
107
+ if (imported)
108
+ out.imported = imported;
109
+ return out;
110
+ };
111
+ const failsOn = (o, c) => {
112
+ const level = o.failOn;
113
+ return level !== undefined && CONF_RANK[c] <= CONF_RANK[level];
114
+ };
115
+ const printNotes = (spl, diags, name) => {
116
+ const where = lineCol(spl);
117
+ for (const d of diags) {
118
+ if (d.severity === 'info')
119
+ continue;
120
+ const at = where(d.span.start);
121
+ const tag = d.severity === 'error' ? paint('error', 31) : paint('note', 33);
122
+ note(`${name ? `${name}:` : ''}${at.line}:${at.col} `, tag, ` ${d.code} ${d.message}\n`);
123
+ }
124
+ };
125
+ program
126
+ .command('translate')
127
+ .description('Translate one search. Reads standard input when the file is "-" or omitted.')
128
+ .argument('[file]', 'file with the SPL search')
129
+ .addOption(new Option('-o, --output <format>', 'output format').choices(['dql', 'json', 'pretty']).default('dql'))
130
+ .addHelpText('after', "\nExamples:\n spl2dql translate search.spl -m mapping.yaml\n echo 'index=web | stats count by host' | spl2dql translate -o pretty\n")
131
+ .action(async (file, o) => {
132
+ const spl = file && file !== '-' ? readText(resolve(io.cwd, file)) : await readStdin(io.stdin);
133
+ const { translate: options } = optionsFrom(o);
134
+ const result = translate(spl, options);
135
+ if (o.output === 'json') {
136
+ say(`${JSON.stringify(result, null, 2)}\n`);
137
+ }
138
+ else if (o.output === 'pretty') {
139
+ say(`${result.dql}\n\n${CONFIDENCE_WORD[result.confidence]}\n`);
140
+ for (const d of result.diagnostics)
141
+ say(` ${d.severity === 'error' ? '■' : d.severity === 'warning' ? '▲' : '●'} stage ${d.stageIndex + 1} ${d.code}: ${d.message}\n`);
142
+ }
143
+ else {
144
+ say(`${result.dql}\n`);
145
+ if (!o.quiet)
146
+ printNotes(spl, result.diagnostics);
147
+ }
148
+ if (failsOn(o, result.confidence))
149
+ throw new Exit(EXIT.confidence);
150
+ });
151
+ program
152
+ .command('batch')
153
+ .description('Translate everything in files or a Splunk app folder: saved searches, dashboards, and the macros and extractions they use.')
154
+ .argument('<inputs...>', 'files or directories')
155
+ .requiredOption('--out <dir>', 'output directory')
156
+ .option('--report <formats>', 'report formats: html,json', 'html,json')
157
+ .option('--redact', 'replace quoted values, IP and e-mail addresses in the report')
158
+ .option('--skip-disabled', 'leave out saved searches that are switched off in Splunk (disabled = 1)')
159
+ .addHelpText('after', '\nReads .spl and .txt searches, savedsearches.conf (with each search\'s saved time range), CSV files with a\n"search" column, Splunk dashboards (Simple XML and Dashboard Studio), and macros.conf, props.conf,\ntransforms.conf, eventtypes.conf and tags.conf, whose definitions are used during translation.\n\nExamples:\n spl2dql batch ./my_splunk_app --out ./out\n spl2dql batch savedsearches.conf macros.conf --mapping m.yaml --out ./out --report html --redact\n')
160
+ .action(async (paths, o) => {
161
+ const inputs = readInputs(paths, io.cwd);
162
+ for (const n of inputs.skipped)
163
+ note(paint('note', 33), ` ${n}\n`);
164
+ const searches = o.skipDisabled ? inputs.searches.filter((s) => !s.disabled) : inputs.searches;
165
+ if (searches.length === 0 && inputs.dashboards.length === 0)
166
+ throw new InputError('No searches or dashboards found in the given inputs.');
167
+ const { translate: options, mapping, imported } = optionsFrom(o, inputs);
168
+ describeImport(imported);
169
+ const out = prepareOutDir(resolve(io.cwd, String(o.out)));
170
+ const formats = new Set(String(o.report)
171
+ .split(',')
172
+ .map((f) => f.trim().toLowerCase())
173
+ .filter(Boolean));
174
+ for (const f of formats)
175
+ if (f !== 'html' && f !== 'json')
176
+ throw new InputError(`Unknown report format "${f}". Use html and/or json.`);
177
+ const taken = new Set(['report.html', 'report.json']);
178
+ const entries = [];
179
+ // The run's budget of DQL written (ADR-029). Each file is checked before it is written, so
180
+ // what was written stays complete and the report can still say where the run stopped.
181
+ let written = 0;
182
+ let cutShort;
183
+ let failed = 0;
184
+ const fits = (size) => {
185
+ if (written + size <= runBudget) {
186
+ written += size;
187
+ return true;
188
+ }
189
+ cutShort = `It would write more than ${Math.round(runBudget / 1024 / 1024)} MB of DQL; the rest was not written. Translate the rest in smaller batches.`;
190
+ return false;
191
+ };
192
+ // The run's budget of work: SPL translated, after macro expansion; a search that ends "too
193
+ // large" counts as the full input cap (ADR-029, third round).
194
+ let worked = 0;
195
+ const canWork = (size) => {
196
+ if (worked + size <= workBudget)
197
+ return true;
198
+ cutShort = `It would translate more than ${Math.round(workBudget / 1024 / 1024)} MB of SPL; the rest was not translated. Translate the rest in smaller batches.`;
199
+ return false;
200
+ };
201
+ // The report's budget: past it, searches and dashboards are listed without their detail.
202
+ let detail = 0;
203
+ const withDetail = (size) => {
204
+ if (detail + size > reportBudget)
205
+ return false;
206
+ detail += size;
207
+ return true;
208
+ };
209
+ for (const s of searches) {
210
+ if (cutShort !== undefined)
211
+ break;
212
+ try {
213
+ // The search's own saved time range applies unless --earliest/--latest overrides it.
214
+ const perSearch = { ...options };
215
+ if (!options.timeRange && (s.earliest !== undefined || s.latest !== undefined)) {
216
+ perSearch.timeRange = {};
217
+ if (s.earliest !== undefined)
218
+ perSearch.timeRange.earliest = s.earliest;
219
+ if (s.latest !== undefined)
220
+ perSearch.timeRange.latest = s.latest;
221
+ }
222
+ const expanded = expandedLength(s.spl, perSearch, MAX_INPUT) ?? MAX_INPUT;
223
+ if (!canWork(expanded))
224
+ break;
225
+ const result = translate(s.spl, perSearch);
226
+ worked += result.diagnostics.some((d) => d.code === 'SPL1006') ? MAX_INPUT : expanded;
227
+ if (!fits(result.dql.length + 1))
228
+ break;
229
+ const file = `${safeFileName(s.name, taken)}.dql`;
230
+ writeInside(out, file, `${result.dql}\n`);
231
+ // Only what the report shows is kept for the rest of the run.
232
+ const entry = { name: s.name, origin: s.origin, file, spl: shown(s.spl, s.origin), result: reportResult(result, file) };
233
+ if (!withDetail(detailSize(entry)))
234
+ dropDetail(entry);
235
+ if (s.earliest !== undefined)
236
+ entry.earliest = s.earliest;
237
+ if (s.latest !== undefined)
238
+ entry.latest = s.latest;
239
+ if (s.schedule !== undefined)
240
+ entry.schedule = s.schedule;
241
+ if (s.disabled)
242
+ entry.disabled = true;
243
+ entries.push(entry);
244
+ if (!o.quiet)
245
+ printNotes(s.spl, result.diagnostics, s.name);
246
+ }
247
+ catch (e) {
248
+ failed++;
249
+ note(paint('error', 31), ` The search "${s.name}" (${s.origin}) was skipped: ${messageOf(e)}\n`);
250
+ }
251
+ }
252
+ // Dashboards: one Dynatrace dashboard document each, in out/dashboards/.
253
+ const savedSearches = new Map();
254
+ for (const s of inputs.searches) {
255
+ const ref = { spl: s.spl };
256
+ if (s.earliest !== undefined)
257
+ ref.earliest = s.earliest;
258
+ if (s.latest !== undefined)
259
+ ref.latest = s.latest;
260
+ savedSearches.set(s.name, ref);
261
+ }
262
+ const boards = [];
263
+ const takenBoards = new Set();
264
+ for (const d of inputs.dashboards) {
265
+ // A dashboard starts only while the work budget lasts; it is charged what it really did.
266
+ if (cutShort !== undefined || !canWork(1))
267
+ break;
268
+ try {
269
+ const conversion = convertDashboardSource(d, { ...(mapping ? { mapping } : {}), ...(o.strict ? { strict: true } : {}), savedSearches });
270
+ worked += conversion.work;
271
+ const json = `${JSON.stringify(conversion.dashboard, null, 2)}\n`;
272
+ if (!fits(json.length))
273
+ break;
274
+ const file = `dashboards/${safeFileName(conversion.title, takenBoards)}.json`;
275
+ writeInside(out, file, json);
276
+ const board = reportBoard(conversion, file, d.name);
277
+ if (!withDetail(boardDetailSize(board)))
278
+ dropBoardDetail(board);
279
+ boards.push({ origin: d.name, file, conversion: board });
280
+ }
281
+ catch (e) {
282
+ failed++;
283
+ note(paint('note', 33), ` ${d.name}: ${messageOf(e)} It was skipped.\n`);
284
+ }
285
+ }
286
+ const generated = (io.now?.() ?? new Date()).toISOString();
287
+ const reportOptions = cutShort === undefined ? { redact: !!o.redact } : { redact: !!o.redact, cutShort };
288
+ // A report that cannot be built or written ends the run with a plain message; the files
289
+ // already written stay.
290
+ try {
291
+ if (formats.has('json'))
292
+ writeInside(out, 'report.json', jsonReport(entries, generated, reportOptions, boards));
293
+ if (formats.has('html'))
294
+ writeInside(out, 'report.html', htmlReport(entries, generated, reportOptions, boards));
295
+ }
296
+ catch (e) {
297
+ note(paint('error', 31), ` The report could not be written: ${messageOf(e)} The translated files are in ${out}.\n`);
298
+ throw new Exit(EXIT.usage);
299
+ }
300
+ const s = summary(entries);
301
+ const lines = [];
302
+ if (entries.length > 0)
303
+ lines.push(`${entries.length} searches → ${out}\nExact ${s.high}, needs review ${s.review}, incomplete ${s.low}, not translated ${s.none}`);
304
+ if (boards.length > 0) {
305
+ const t = boards.reduce((a, b) => ({ live: a.live + b.conversion.counts.live, manual: a.manual + b.conversion.counts.manual }), { live: 0, manual: 0 });
306
+ lines.push(`${boards.length} dashboards → ${join(out, 'dashboards')}\n${t.live} panels converted, ${t.manual} need manual work`);
307
+ }
308
+ if (lines.length > 0)
309
+ note(`${lines.join('\n')}\n`);
310
+ if (cutShort !== undefined) {
311
+ note(paint('error', 31), ` The run was cut short: ${cutShort}\n`);
312
+ throw new Exit(EXIT.usage);
313
+ }
314
+ // Skipped items are reported above; the run fails only when nothing could be converted.
315
+ if (entries.length === 0 && boards.length === 0 && failed > 0)
316
+ throw new Exit(EXIT.usage);
317
+ if (entries.some((e) => failsOn(o, e.result.confidence)))
318
+ throw new Exit(EXIT.confidence);
319
+ });
320
+ program
321
+ .command('dashboard')
322
+ .description('Convert Splunk dashboards (Simple XML or Dashboard Studio) into Dynatrace dashboard files.')
323
+ .argument('<inputs...>', 'dashboard files, or directories that contain them')
324
+ .option('-m, --mapping <file>', 'mapping file (YAML or JSON); default spl2dql.mapping.yaml when present')
325
+ .option('--out <dir>', 'write one <name>.json per dashboard here; without it one dashboard is printed')
326
+ .option('--strict', 'treat every missing mapping (SPL4xxx) as an error')
327
+ .option('-q, --quiet', 'do not print the panel summary')
328
+ .addHelpText('after', '\nA panel becomes a live tile only when its search translated completely. Otherwise the tile keeps the\nSplunk search and says what is missing. Inputs become dashboard variables.\n\nExamples:\n spl2dql dashboard web_overview.xml > web_overview.json\n spl2dql dashboard ./my_splunk_app --mapping m.yaml --out ./dashboards\n')
329
+ .action((paths, o) => {
330
+ const inputs = readInputs(paths, io.cwd);
331
+ for (const n of inputs.skipped)
332
+ note(paint('note', 33), ` ${n}\n`);
333
+ if (inputs.dashboards.length === 0)
334
+ throw new InputError('No Splunk dashboards found in the given inputs.');
335
+ if (inputs.dashboards.length > 1 && !o.out)
336
+ throw new InputError(`${inputs.dashboards.length} dashboards found; give --out <dir> to write one file each.`);
337
+ const { mapping, imported } = resolveMapping(o, inputs);
338
+ describeImport(imported);
339
+ const savedSearches = new Map();
340
+ for (const s of inputs.searches) {
341
+ const ref = { spl: s.spl };
342
+ if (s.earliest !== undefined)
343
+ ref.earliest = s.earliest;
344
+ if (s.latest !== undefined)
345
+ ref.latest = s.latest;
346
+ savedSearches.set(s.name, ref);
347
+ }
348
+ const out = o.out ? prepareOutDir(resolve(io.cwd, String(o.out))) : undefined;
349
+ const taken = new Set();
350
+ let converted = 0;
351
+ let written = 0;
352
+ let worked = 0;
353
+ for (const d of inputs.dashboards) {
354
+ if (worked >= workBudget) {
355
+ note(paint('error', 31), ` The run was cut short: it would translate more than ${Math.round(workBudget / 1024 / 1024)} MB of SPL. Convert the rest in smaller batches.\n`);
356
+ throw new Exit(EXIT.usage);
357
+ }
358
+ let conversion;
359
+ try {
360
+ conversion = convertDashboardSource(d, { ...(mapping ? { mapping } : {}), ...(o.strict ? { strict: true } : {}), savedSearches });
361
+ worked += conversion.work;
362
+ const json = `${JSON.stringify(conversion.dashboard, null, 2)}\n`;
363
+ if (written + json.length > runBudget) {
364
+ note(paint('error', 31), ` The run was cut short: it would write more than ${Math.round(runBudget / 1024 / 1024)} MB of DQL. Convert the rest in smaller batches.\n`);
365
+ throw new Exit(EXIT.usage);
366
+ }
367
+ written += json.length;
368
+ if (out)
369
+ writeInside(out, `${safeFileName(conversion.title, taken)}.json`, json);
370
+ else
371
+ say(json);
372
+ converted++;
373
+ }
374
+ catch (e) {
375
+ if (e instanceof Exit)
376
+ throw e;
377
+ // One dashboard that cannot be read or written never ends the run (ADR-029).
378
+ note(paint('note', 33), ` ${d.name}: ${messageOf(e)} It was skipped.\n`);
379
+ continue;
380
+ }
381
+ if (o.quiet)
382
+ continue;
383
+ const c = conversion.counts;
384
+ note(`${conversion.title}: ${c.live} panels converted, ${c.manual} need manual work, ${c.text} text; ${conversion.variables.length} variable(s)\n`);
385
+ for (const t of conversion.tiles) {
386
+ if (t.outcome !== 'manual')
387
+ continue;
388
+ note(' ', paint('▲', 33), ` ${t.title || '(no title)'}: ${t.notes[0] ?? 'needs manual work'}\n`);
389
+ }
390
+ for (const n of conversion.notes)
391
+ note(` ${n}\n`);
392
+ }
393
+ if (converted === 0)
394
+ throw new Exit(EXIT.usage);
395
+ });
396
+ const mapping = program.command('mapping').description('Create or check a mapping file.');
397
+ mapping
398
+ .command('init')
399
+ .description('Write a mapping skeleton: every name the searches and dashboards use, filled in from Splunk configuration files where possible.')
400
+ .argument('<inputs...>', 'files or directories (searches, dashboards, macros.conf, props.conf, eventtypes.conf …)')
401
+ .option('-m, --mapping <file>', 'existing mapping file; only names it does not cover are listed')
402
+ .addHelpText('after', '\nmacros.conf, props.conf (EXTRACT-, REPORT-), transforms.conf, eventtypes.conf and tags.conf among the inputs\nare read and their definitions written into the skeleton, so only what is specific to Dynatrace is left to fill in.\n\nExamples:\n spl2dql mapping init ./my_splunk_app > spl2dql.mapping.yaml\n spl2dql mapping init savedsearches.conf macros.conf -m spl2dql.mapping.yaml\n')
403
+ .action((paths, o) => {
404
+ const inputs = readInputs(paths, io.cwd);
405
+ for (const n of inputs.skipped)
406
+ note(paint('note', 33), ` ${n}\n`);
407
+ const { mapping: existing, imported } = resolveMapping(o, inputs);
408
+ const opts = existing ? { mapping: existing } : {};
409
+ const diags = [];
410
+ // One search or dashboard that cannot be read never ends the run (ADR-029). The run's work
411
+ // budget applies here too.
412
+ let worked = 0;
413
+ const stop = () => {
414
+ note(paint('error', 31), ` The run was cut short: it would translate more than ${Math.round(workBudget / 1024 / 1024)} MB of SPL. Run it on fewer files.\n`);
415
+ throw new Exit(EXIT.usage);
416
+ };
417
+ for (const s of inputs.searches) {
418
+ const expanded = expandedLength(s.spl, opts, MAX_INPUT) ?? MAX_INPUT;
419
+ if (worked + expanded > workBudget)
420
+ stop();
421
+ try {
422
+ const result = translate(s.spl, opts);
423
+ worked += result.diagnostics.some((d) => d.code === 'SPL1006') ? MAX_INPUT : expanded;
424
+ for (const d of result.diagnostics)
425
+ diags.push(d);
426
+ }
427
+ catch (e) {
428
+ note(paint('note', 33), ` The search "${s.name}" (${s.origin}) was skipped: ${messageOf(e)}\n`);
429
+ }
430
+ }
431
+ let panels = 0;
432
+ for (const d of inputs.dashboards) {
433
+ if (worked >= workBudget)
434
+ stop();
435
+ try {
436
+ const conversion = convertDashboardSource(d, existing ? { mapping: existing } : {});
437
+ worked += conversion.work;
438
+ for (const t of conversion.tiles) {
439
+ if (!t.result)
440
+ continue;
441
+ panels++;
442
+ for (const d of t.result.diagnostics)
443
+ diags.push(d);
444
+ }
445
+ for (const v of conversion.variables)
446
+ if (v.result)
447
+ for (const d of v.result.diagnostics)
448
+ diags.push(d);
449
+ }
450
+ catch (e) {
451
+ if (!(e instanceof DashboardError))
452
+ note(paint('note', 33), ` ${d.name}: ${messageOf(e)} It was skipped.\n`);
453
+ }
454
+ }
455
+ const needs = collectMappingNeeds(diags);
456
+ const skeleton = { version: 1 };
457
+ // Held to the mapping file's own limits (names it accepts, 10,000 entries per section), so the
458
+ // skeleton always reads back as a valid mapping file.
459
+ let capped = false;
460
+ const keys = (names, pattern) => {
461
+ const ok = names.filter((n) => pattern.test(n));
462
+ if (ok.length > MAX_SECTION)
463
+ capped = true;
464
+ return ok.slice(0, MAX_SECTION);
465
+ };
466
+ const blank = (names, value) => {
467
+ const list = keys(names, SPL_NAME);
468
+ return list.length > 0 ? Object.fromEntries(list.map((n) => [n, value(n)])) : undefined;
469
+ };
470
+ const sections = [
471
+ ['indexes', blank(needs.indexes, () => ({ dataObject: 'logs', buckets: [] }))],
472
+ ['sourcetypes', blank(needs.sourcetypes, () => ({ filter: 'true' }))],
473
+ [
474
+ 'datamodels',
475
+ needs.datamodels.length > 0
476
+ ? Object.fromEntries(needs.datamodels
477
+ .filter((m) => DATAMODEL_NAME.test(m.name))
478
+ .slice(0, MAX_SECTION)
479
+ .map((m) => [m.name, { dataObject: 'logs', filter: 'true', fields: Object.fromEntries(keys(m.fields, FIELD_KEY).map((f) => [f, f])) }]))
480
+ : undefined,
481
+ ],
482
+ [
483
+ 'fields',
484
+ blank(needs.fields.filter((n) => FIELD_KEY.test(n)), (n) => n),
485
+ ],
486
+ ['macros', blank(needs.macros, () => ({ definition: 'TODO' }))],
487
+ ['lookups', blank(needs.lookups, (n) => ({ path: `/lookups/${n.replace(/[^A-Za-z0-9_.-]/g, '_')}` }))],
488
+ ['eventtypes', blank(needs.eventtypes, () => 'true')],
489
+ ];
490
+ for (const [k, v] of sections)
491
+ if (v)
492
+ skeleton[k] = v;
493
+ // Definitions read from the Splunk configuration files, on top of the blanks above.
494
+ const filled = imported ? mergeMappingSections(skeleton, imported.sections) : skeleton;
495
+ const header = [
496
+ `# Mapping skeleton generated by spl2dql from ${inputs.searches.length} search(es) and ${panels} dashboard panel(s).`,
497
+ '# Fill in every value; see docs/spec/mapping-config.md.',
498
+ ];
499
+ if (capped)
500
+ header.push(`# A section had more than ${MAX_SECTION} names; only the first ${MAX_SECTION} are listed.`);
501
+ if (imported) {
502
+ const c = imported.counts;
503
+ header.push(`# Read from Splunk configuration files: ${c.macros} macro(s), ${c.extractions} extraction(s), ${c.eventtypes} eventtype(s), ${c.tags} tag(s).`);
504
+ if (imported.skipped.length > 0) {
505
+ header.push('#', '# Not carried over (do these by hand):');
506
+ for (const sk of imported.skipped.slice(0, 200))
507
+ header.push(`# ${sk.section} ${oneLine(sk.name)}: ${oneLine(sk.reason)}`);
508
+ if (imported.skipped.length > 200)
509
+ header.push(`# … and ${imported.skipped.length - 200} more`);
510
+ }
511
+ }
512
+ say(`${header.join('\n')}\n${toYaml(filled, { lineWidth: 0 })}`);
513
+ });
514
+ mapping
515
+ .command('check')
516
+ .description('Validate a mapping file.')
517
+ .argument('<file>', 'mapping file')
518
+ .action((file) => {
519
+ loadMapping(file, io.cwd);
520
+ note(`${file}: no problems found.\n`);
521
+ });
522
+ program
523
+ .command('commands')
524
+ .description('Print the support matrix: command, tier, notes.')
525
+ .addOption(new Option('-o, --output <format>', 'output format').choices(['table', 'json']).default('table'))
526
+ .action((o) => {
527
+ const list = listCommands();
528
+ if (o.output === 'json')
529
+ return void say(`${JSON.stringify(list, null, 2)}\n`);
530
+ const tierWord = { T1: 'exact', T2: 'review', T3: 'none' };
531
+ for (const c of list)
532
+ say(`${c.name.padEnd(18)} ${tierWord[c.tier].padEnd(7)} ${c.summary}\n`);
533
+ });
534
+ program
535
+ .command('explain')
536
+ .description('Explain a note code, e.g. SPL3001.')
537
+ .argument('<code>', 'note code')
538
+ .action((code) => {
539
+ const doc = explainDiagnostic(code);
540
+ if (!doc)
541
+ throw new InputError(`Unknown code "${code}". Codes look like SPL3001.`);
542
+ say(`${doc.code} (${doc.severity})\n${doc.title}\nWhat to do: ${doc.hint}\n`);
543
+ });
544
+ program
545
+ .command('serve')
546
+ .description('Open the web app locally: serves it on 127.0.0.1 only. Everything runs in your browser.')
547
+ .option('--port <port>', 'port', '4680')
548
+ .option('--host <host>', 'loopback address to bind', '127.0.0.1')
549
+ .action(async (o) => {
550
+ const { startServer } = await import('./serve/server.js');
551
+ const handle = await startServer({ port: Number(o.port), host: String(o.host) });
552
+ note(`spl2dql web app on ${handle.url}\nPress Ctrl+C to stop.\n`);
553
+ await handle.closed;
554
+ });
555
+ for (const c of program.commands)
556
+ if (['translate', 'batch'].includes(c.name()))
557
+ shared(c);
558
+ try {
559
+ await program.parseAsync(['node', 'spl2dql', ...argv]);
560
+ return EXIT.ok;
561
+ }
562
+ catch (e) {
563
+ if (e instanceof Exit)
564
+ return e.code;
565
+ if (e instanceof CommanderError)
566
+ return e.exitCode === 0 ? EXIT.ok : EXIT.usage;
567
+ if (e instanceof MappingError) {
568
+ note(paint('error', 31), ` ${e.message}\n`);
569
+ for (const i of e.issues)
570
+ note(` ${i.path || '/'}: ${i.message}\n`);
571
+ return EXIT.usage;
572
+ }
573
+ if (e instanceof InputError) {
574
+ note(paint('error', 31), ` ${e.message}\n`);
575
+ return EXIT.usage;
576
+ }
577
+ const message = e instanceof Error ? e.message : String(e);
578
+ note(paint('error', 31), ` ${message}\n`);
579
+ return EXIT.usage;
580
+ }
581
+ }
582
+ function messageOf(e) {
583
+ return e instanceof Error ? e.message : String(e);
584
+ }
585
+ function readText(path) {
586
+ try {
587
+ const text = readFileSync(path, 'utf8');
588
+ if (text.length > MAX_STDIN)
589
+ throw new InputError(`${path} is larger than 10 MB.`);
590
+ return text;
591
+ }
592
+ catch (e) {
593
+ if (e instanceof InputError)
594
+ throw e;
595
+ throw new InputError(`Cannot read ${path}.`);
596
+ }
597
+ }
598
+ async function readStdin(stdin) {
599
+ let out = '';
600
+ for await (const chunk of stdin) {
601
+ out += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
602
+ if (out.length > MAX_STDIN)
603
+ throw new InputError('Standard input is larger than 10 MB.');
604
+ }
605
+ return out;
606
+ }
607
+ /**
608
+ * Line and column of offsets in `text`. The line starts are found once; each lookup is a binary
609
+ * search, so printing many notes for a long search stays fast (ADR-029).
610
+ */
611
+ function lineCol(text) {
612
+ const starts = [0];
613
+ for (let i = text.indexOf('\n'); i !== -1; i = text.indexOf('\n', i + 1))
614
+ starts.push(i + 1);
615
+ return (offset) => {
616
+ let lo = 0;
617
+ let hi = starts.length - 1;
618
+ while (lo < hi) {
619
+ const mid = (lo + hi + 1) >> 1;
620
+ if (starts[mid] <= offset)
621
+ lo = mid;
622
+ else
623
+ hi = mid - 1;
624
+ }
625
+ return { line: lo + 1, col: offset - starts[lo] + 1 };
626
+ };
627
+ }
628
+ /** One line, safe inside a YAML comment. */
629
+ function oneLine(s) {
630
+ return s.replace(/\s+/g, ' ').trim();
631
+ }
632
+ /**
633
+ * Text from the input made safe for a terminal: every escape sequence (CSI such as colours, OSC,
634
+ * DCS and the other string controls, two-character escapes) is removed; a carriage return that
635
+ * is not part of CRLF (it would let a note overwrite its own line) and the Unicode bidirectional
636
+ * controls (which reorder what is shown) are removed; other control characters become "?".
637
+ */
638
+ export function safeText(s) {
639
+ return s
640
+ .replace(/\u001b\[[0-?]*[ -/]*[@-~]?/g, '')
641
+ .replace(/\u001b[\]P^_X][^\u0007\u001b]*(?:\u0007|\u001b\\)?/g, '')
642
+ .replace(/\u001b[ -~]?/g, '')
643
+ .replace(/\r(?!\n)/g, '')
644
+ .replace(/[\u202a-\u202e\u2066-\u2069]/g, '')
645
+ .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g, '?');
646
+ }
647
+ function paint(text, code) {
648
+ return { text, code };
649
+ }
650
+ //# sourceMappingURL=main.js.map
@@ -0,0 +1,18 @@
1
+ import { type MappingConfig, type MappingIssue } from '@spl2dql/core';
2
+ export declare class MappingError extends Error {
3
+ readonly issues: MappingIssue[];
4
+ constructor(message: string, issues?: MappingIssue[]);
5
+ }
6
+ /** Validates already-parsed mapping data. */
7
+ export declare function validateMapping(data: unknown, name: string): MappingConfig;
8
+ /** Parses mapping text (YAML or JSON) and validates it. */
9
+ export declare function parseMappingText(text: string, name: string): MappingConfig;
10
+ export interface LoadedMapping {
11
+ file: string;
12
+ /** The file's content as plain data, for merging with sections imported from Splunk files. */
13
+ data: Record<string, unknown>;
14
+ mapping: MappingConfig;
15
+ }
16
+ /** Loads --mapping, or spl2dql.mapping.yaml from the working directory when present. */
17
+ export declare function loadMappingFile(path: string | undefined, cwd: string): LoadedMapping | undefined;
18
+ export declare function loadMapping(path: string | undefined, cwd: string): MappingConfig | undefined;