@cloudcare/guance-front-tools 1.0.19 → 1.0.21

package/skills/grafana-to-guance-dashboard/package.json

@@ -1,16 +0,0 @@
-{
-  "name": "grafana-to-guance-dashboard-skill",
-  "private": true,
-  "type": "module",
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "scripts": {
-    "convert": "node scripts/convert-grafana-dashboard.mjs",
-    "validate:file": "node scripts/validate-file.mjs",
-    "test": "node --test test/*.test.mjs"
-  },
-  "dependencies": {
-    "ajv": "8.11.0"
-  }
-}

package/skills/grafana-to-guance-dashboard/references/conversion-audit-checklist.md

@@ -1,183 +0,0 @@
-# Conversion Audit Checklist
-
-Use this checklist as the default operating sequence when handling Grafana-to-Guance conversion work with this skill.
-
-The goal is not just to produce JSON, but to produce:
-
-- a validated output
-- an explained audit result
-- a clear next action
-
-## 1. Preflight
-
-Before converting, check:
-
-- what panel types are present
-- what datasource types are present
-- whether row panels or nested panels exist
-- whether variables are simple or complex
-- whether transformations or plugin-specific options are present
-- whether units appear explicit or likely need inference
-- whether queries look like PromQL, DQL, SQL-like text, or mixed patterns
-
-Ask:
-
-- is this likely a straightforward conversion
-- is `--guance-promql-compatible` likely useful
-- is `--keep-grafana-meta` likely useful
-- which panels already look risky before conversion starts
-
-## 2. Convert
-
-Run the standalone converter with the chosen flags.
-
-Minimum expectation:
-
-- output file is created
-- schema validation passes or produces actionable errors
-
-If conversion fails immediately:
-
-- do not jump to a large refactor
-- identify whether the failure is path-related, schema-related, query-related, or panel-mapping-related
-
-## 3. Validate
-
-After conversion, confirm:
-
-- the output file validates
-- the output has expected dashboard-level structure
-- chart count is in a plausible range
-- vars and groups exist when expected
-
-If validation fails:
-
-- record the failing paths
-- decide whether the issue is bad output or an overly strict schema
-- prefer fixing converter output before relaxing schemas
-
-## 4. Audit Counts
-
-Compare input and output at a high level:
-
-- Grafana total panels
-- Grafana non-row panels
-- Guance chart count
-- Guance group count
-- input vars
-- output vars
-
-Ask:
-
-- which panels disappeared entirely
-- which panels became groups
-- which panels survived but may have degraded semantics
-
-## 5. Audit Semantics
-
-For suspicious or important panels, inspect:
-
-- panel title
-- Grafana panel type
-- Guance chart type
-- query type
-- explicit unit vs inferred unit
-- links, thresholds, legend, mappings, transformations
-
-Classify each panel as:
-
-- `clean`
-- `partial`
-- `dropped`
-- `suspicious`
-
-## 6. Audit Units
-
-Check whether each important panel has:
-
-- explicit unit
-- inferred unit with `high` confidence
-- inferred unit with `medium` or `low` confidence
-- no credible unit
-
-Use:
-
-- `unit-inference-cheatsheet.md`
-
-Escalate for review when:
-
-- unit materially changes interpretation
-- evidence conflicts
-- multiple weak hints disagree
-
-## 7. Audit PromQL Compatibility
-
-Inspect important or suspicious PromQL queries and classify them:
-
-- `safe`
-- `suspicious`
-- `manual-review`
-
-Use:
-
-- `promql-compatibility-cheatsheet.md`
-
-Ask:
-
-- should the query be kept as-is
-- should `--guance-promql-compatible` be recommended
-- does the query mix naming styles
-- would normalization likely preserve intent
-
-## 8. Decide Next Action
-
-Choose one next step only:
-
-- accept output
-- rerun with different flags
-- produce a debug build with `--keep-grafana-meta`
-- patch one small converter area
-- ask for manual review on specific panels or queries
-
-Do not combine many speculative fixes at once.
-
-## 9. If Repair Is Needed
-
-Before patching:
-
-- isolate one failing panel or query pattern
-- compare source Grafana JSON to generated Guance JSON
-- name the smallest likely fix location
-
-Prefer fix locations in this order:
-
-- panel type map
-- query extraction
-- query classification
-- unit inference
-- PromQL normalization
-- settings conversion
-- variable conversion
-- layout conversion
-
-After patching:
-
-- rerun conversion
-- rerun validation
-- rerun audit
-
-## 10. Report
-
-Provide a short user-facing report with:
-
-- input
-- output
-- flags
-- validation result
-- panel summary
-- dropped or suspicious items
-- unit concerns
-- PromQL concerns
-- recommended next step
-
-Default to concise reporting. Only produce a full panel-by-panel list when the user asks for it or when many panels are failing.

package/skills/grafana-to-guance-dashboard/references/converter-notes.md

@@ -1,244 +0,0 @@
-# Converter Notes
-
-## Skill Files
-
-- `skills/grafana-to-guance-dashboard/package.json`: standalone dependencies and convenience scripts
-- `skills/grafana-to-guance-dashboard/scripts/convert-grafana-dashboard.mjs`: standalone converter shipped by this skill
-- `skills/grafana-to-guance-dashboard/scripts/convert-grafana-dashboard-core.js`: standalone conversion core used by this skill
-- `skills/grafana-to-guance-dashboard/scripts/validate-file.mjs`: standalone validator for generated output
-- `skills/grafana-to-guance-dashboard/schemas/dashboard-schema.json`: standalone Guance dashboard schema entrypoint
-- `skills/grafana-to-guance-dashboard/fixtures/grafana-dashboard.json`: bundled standalone fixture dashboard
-- `skills/grafana-to-guance-dashboard/test/convert.test.mjs`: bundled end-to-end regression test
-
-## Current Mapping Notes
-
-Use these notes together with LLM analysis, not as a replacement for it. The script handles deterministic conversion. The LLM should handle risk analysis, output auditing, root-cause explanation, and patch planning when conversion gaps remain.
-
-For the default step-by-step operating flow, also read [conversion-audit-checklist.md](conversion-audit-checklist.md).
-
-Two especially useful LLM-only review areas are:
-
-- unit inference when Grafana leaves units implicit
-- PromQL dialect compatibility when Grafana query habits differ from Guance expectations
-
-For unit inference heuristics and confidence patterns, also read [unit-inference-cheatsheet.md](unit-inference-cheatsheet.md).
-For PromQL review heuristics and rewrite-risk patterns, also read [promql-compatibility-cheatsheet.md](promql-compatibility-cheatsheet.md).
-
-### Variables
-
-- Supported Grafana variable types:
-  - `query`
-  - `custom`
-- Variable mapping:
-  - `query` -> `PROMQL_QUERY`
-  - `custom` -> `CUSTOM_LIST`
-
-Additional Grafana variable types such as `textbox`, `constant`, `interval`, and `datasource` are converted into Guance custom-list style variables by the standalone script.
-
-The standalone script also preserves extra variable metadata such as `refresh`, `skipUrlSync`, `sort`, `description`, and raw option lists under `var.extend`.
-
-### Panels
-
-Panel type mapping should live in the standalone skill converter implementation, typically `convert-grafana-dashboard-core.js`.
-
-If a Grafana panel type is missing, the panel is filtered out before conversion. Add the panel type to the standalone script map before debugging deeper.
-
-By default, the converter does not emit raw `extend.grafana` metadata in the generated Guance dashboard. Use `--keep-grafana-meta` only when you need source-level debugging context.
-
-### Queries
-
-The converter pulls query text from the first defined field among:
-
-1. `target.expr`
-2. `target.query`
-3. `target.queryText`
-4. `target.expression`
-5. `target.rawSql`
-
-Generated Guance queries default to PromQL-style output unless the query looks like DQL:
-
-```json
-{
-  "datasource": "dataflux",
-  "qtype": "promql",
-  "type": "sequence",
-  "query": {
-    "q": "...",
-    "type": "promql",
-    "code": "a",
-    "promqlCode": 1
-  }
-}
-```
-
-Variable replacement is intentionally conservative:
-
-- only known Grafana dashboard variables are rewritten from `$var` / `${var}` to `#{var}`
-- Grafana built-ins such as `${__from}` and `${__to}` are preserved
-- unknown template expressions such as JavaScript local variables in text panels stay unchanged, for example `${hotcall}`
-
-Query classification is datasource-aware:
-
-- Prometheus-like datasources stay `promql`
-- SQL-like datasources such as MySQL/Postgres/MSSQL are emitted as `dql`
-- `guance-guance-datasource` defaults to `dql`
-- if a `guance-guance-datasource` target explicitly sets `qtype: "promql"`, that explicit PromQL mode wins
-- the generated `query.type` now follows the same classification instead of falling back to `simple`
-
-Guance PromQL compatibility mode:
-
-- pass `--guance-promql-compatible` to rewrite PromQL metric selectors from `metric_name` to `measurement:field`
-- the rewrite is conservative and only applies to metric selector tokens outside label braces
-- label keys such as `app_name` and grouping keys such as `by (app_name)` are preserved
-- keep this mode opt-in, because some dashboards may already target Guance-native metric names
-
-PromQL compatibility review should also inspect:
-
-- whether metric names should remain untouched rather than rewritten
-- whether recording-rule style metric names already look Guance-native
-- whether label selectors, grouping keys, or function nesting may behave differently after rewrite
-- whether a query should be marked suspicious instead of rewritten automatically
-
-### Layout
-
-Grafana `gridPos` is not copied directly.
-
-- `x` and `w` are kept close to Grafana values
-- `y` and `h` are scaled into a Guance-friendly layout ratio
-
-If the final dashboard looks vertically misaligned, inspect the layout conversion helpers first.
-
-## Debug Checklist
-
-When output is wrong:
-
-1. Start with a preflight or audit mindset instead of editing immediately:
-   - what panel type is this
-   - what datasource shape does it use
-   - what settings or transformations look important
-   - is the panel dropped, partially converted, or converted with wrong semantics
-1. Confirm the panel type is in the standalone script panel map.
-2. Confirm the panel has `gridPos`.
-3. Confirm the panel has usable `targets`.
-4. Check whether the query lives in `expr`, `query`, or `queryText`.
-5. Check whether row panels are collapsed, because collapsed and expanded rows are handled differently.
-6. Validate the generated JSON with:
-
-```bash
-npm run validate:file -- ./output/guance-dashboard.json
-```
-
-7. Run `npm test` to verify the bundled standalone fixture still converts and validates cleanly.
-8. If the behavior itself is wrong, patch the standalone files under `skills/grafana-to-guance-dashboard/scripts/` directly instead of relying on repository sync/build flows.
-
-## Audit Prompts
-
-When comparing input and output, explicitly answer:
-
-- Which Grafana panels converted cleanly
-- Which Grafana panels were dropped
-- Which Grafana panels are only partially represented
-- Which variables converted incorrectly or not at all
-- Which queries appear to be misclassified as `promql` or `dql`
-- Which panels are missing units and what units are most likely
-- Which inferred units are high-confidence versus low-confidence
-- Which PromQL queries are safe to normalize and which should be flagged for review
-- Which settings are missing versus only preserved in `extend.grafana`
-- Whether the next fix belongs in mapping, extraction, classification, or validation
-
-When inferring units, use evidence such as:
-
-- metric suffixes like `_bytes`, `_seconds`, `_ms`, `_percent`, `_ratio`
-- rate-like functions such as `rate`, `irate`, `increase`, `delta`
-- panel titles like `latency`, `duration`, `memory`, `cpu`, `qps`, `error rate`
-- legend aliases and threshold semantics
-
-Always state whether the unit inference is:
-
-- high confidence
-- medium confidence
-- low confidence
-
-For PromQL compatibility review, classify each query as:
-
-- safe
-  - normalization is straightforward and low-risk
-- suspicious
-  - a rewrite may be needed, but the intent is not obvious
-- manual-review
-  - automatic advice is too risky or the datasource assumptions are unclear
-
-When a query is marked `suspicious` or `manual-review`, explain why in one sentence rather than only flagging it.
-
-## Reporting Defaults
-
-Unless the user asks for raw detail, prefer:
-
-- one dashboard-level summary
-- one risk summary
-- one short list of dropped, partial, or suspicious panels
-- one short list of unit or PromQL concerns
-- one recommended next action
-
-Do not overwhelm the user with a full panel-by-panel dump when only a few panels are problematic.
-
-## Settings Conversion
-
-The standalone script attempts to convert:
-
-- thresholds -> Guance `levels`
-- Grafana value maps and range maps -> Guance `mappings`
-- table override mappings -> Guance `valMappings`
-- legend placement and legend values, including older Grafana `legend.current/avg/min/max/total`
-- units, decimals, min, max from both newer and older Grafana panel formats
-- stacking and connect-nulls behavior from both newer and older Grafana panel formats
-- table column organize / rename / exclude / order transformations
-- panel links and field links into `extend.links`
-- appearance metadata into `settings.extend.appearance`, including:
-  - `lineWidth`
-  - `fillOpacity`
-  - `pointMode`
-  - `graphMode`
-  - `colorMode`
-  - `textMode`
-  - `reduceCalcs`
-  - `gaugeMode`
-
-This is heuristic conversion. For plugin-specific panels, validate the generated JSON and then refine the script with a real sample.
-
-## Repair Strategy
-
-When the user asks to fix a conversion problem:
-
-1. Isolate one concrete failing panel, variable, or query pattern.
-2. Compare original Grafana JSON to generated Guance JSON.
-3. State the smallest likely fix location:
-   - panel type map
-   - query extraction
-   - query classification
-   - unit inference
-   - PromQL normalization
-   - settings conversion
-   - variable conversion
-   - layout conversion
-4. Patch only that part of the standalone converter first.
-5. Re-run conversion, validation, and audit.
-
-Prefer this order of operations:
-
-1. explanation
-2. smallest patch
-3. validation
-4. audit
-5. user-facing summary
-
-## Safe Extension Pattern
-
-When adding support for a new panel type:
-
-1. Add the Grafana panel type to the standalone script panel map.
-2. Decide the Guance chart type target.
-3. Add any special-case settings generation in the standalone script.
-4. Convert a real dashboard containing that panel.
-5. Validate the generated output file.
-6. Run `npm test` to keep the standalone fixture and validator working.

package/skills/grafana-to-guance-dashboard/references/promql-compatibility-cheatsheet.md

@@ -1,172 +0,0 @@
-# PromQL Compatibility Cheatsheet
-
-Use this reference when reviewing whether Grafana-style PromQL should be kept as-is, normalized for Guance, or flagged for manual review.
-
-This file is a review guide. It is not a guarantee that a rewrite is safe.
-
-## Review Outcome Labels
-
-- `safe`
-  - a rewrite or keep-as-is decision is low-risk and well-supported
-- `suspicious`
-  - the query may need adjustment, but the intent is not fully obvious
-- `manual-review`
-  - the query is too ambiguous or too environment-specific for confident automated advice
-
-## Common Cases
-
-### Plain Prometheus Metric Names
-
-Example shape:
-
-```promql
-sum(rate(http_requests_total[5m])) by (service)
-```
-
-Typical review:
-
-- compatible with Prometheus-style Grafana dashboards
-- likely candidate for `--guance-promql-compatible` if the target environment expects `measurement:field`
-
-Typical outcome:
-
-- `safe` if the whole dashboard consistently uses underscore-style metric names
-
-### Metrics Already Containing `:`
-
-Example shape:
-
-```promql
-sum(rate(http:requests_total[5m])) by (service)
-```
-
-Typical review:
-
-- this may already be a recording rule or a Guance-style metric name
-- avoid blindly rewriting it again
-
-Typical outcome:
-
-- `suspicious` or `manual-review`
-
-### Mixed Naming Styles
-
-Example shape:
-
-```promql
-sum(rate(http_requests_total[5m])) + sum(rate(http:errors_total[5m]))
-```
-
-Typical review:
-
-- mixed naming styles usually mean the dashboard is not uniformly Prometheus-native
-- broad normalization may break part of the query
-
-Typical outcome:
-
-- `manual-review`
-
-### Recording Rules
-
-Example shape:
-
-```promql
-job:http_requests:rate5m
-```
-
-Typical review:
-
-- recording rules often compress semantics into names
-- avoid assuming underscore-based normalization is still appropriate
-
-Typical outcome:
-
-- `suspicious`
-
-### Histogram Quantile Queries
-
-Example shape:
-
-```promql
-histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket[5m])) by (le, service))
-```
-
-Typical review:
-
-- often safe structurally
-- the main question is whether metric naming should be normalized, not whether the function shape is valid
-
-Typical outcome:
-
-- `safe` if naming is consistently Prometheus-style
-- `suspicious` if histogram metric names already mix styles
-
-## Label and Grouping Review
-
-Inspect carefully when queries use:
-
-- `by (...)`
-- `without (...)`
-- `on (...)`
-- `ignoring (...)`
-- `group_left`
-- `group_right`
-
-These constructs do not automatically mean incompatibility, but they increase rewrite risk when naming conventions are also being changed.
-
-Typical outcome:
-
-- `safe` if only metric names are normalized and label keys remain untouched
-- `suspicious` if a proposed rewrite would also alter grouping or selector meaning
-
-## When To Recommend `--guance-promql-compatible`
-
-Good signals:
-
-- most queries are standard Prometheus metric selectors
-- metric names consistently use underscore-heavy names
-- no widespread use of recording-rule names already containing `:`
-- the user explicitly targets Guance metric naming compatibility
-
-Typical outcome:
-
-- `safe`
-
-## When Not To Recommend It Blindly
-
-Warning signals:
-
-- the dashboard mixes Prometheus-native and Guance-native naming
-- many metrics already contain `:`
-- datasource assumptions are unclear
-- the queries appear heavily hand-tuned for a specific Prometheus backend
-
-Typical outcome:
-
-- `suspicious` or `manual-review`
-
-## Review Questions
-
-When auditing a query, answer:
-
-- Is the query structurally valid PromQL?
-- Is the main issue naming compatibility or something deeper?
-- Are metric names consistently Prometheus-style, already Guance-style, or mixed?
-- Would normalization likely preserve intent?
-- Should this query be kept, rewritten, or escalated to manual review?
-
-## Reporting Pattern
-
-Use compact notes like:
-
-```md
-- query: sum(rate(http_requests_total[5m])) by (service)
-  review: safe
-  reason: metric names are consistently Prometheus-style and no Guance-native naming is mixed in
-```
-
-```md
-- query: sum(rate(http_requests_total[5m])) + sum(rate(http:errors_total[5m]))
-  review: manual-review
-  reason: query mixes underscore-style metrics with colon-style recording rules, so blanket normalization is risky
-```