@tileflow/dev 0.1.0-alpha.22 → 0.1.0-alpha.24

package/docs/structured-config-inspection-and-diagnostics.md

@@ -0,0 +1,39 @@
+# Structured config inspection and diagnostics
+
+Start with the [@tileflow/dev guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/README.md) for installation and a complete first example.
+
+Custom Node tooling can use the same deterministic documents as `tileflow validate --json` and
+`tileflow inspect --json`:
+
+```ts
+import {inspectTileflowConfig} from '@tileflow/dev/inspect';
+import {
+  createTileflowCommandFailureDocument,
+  serializeTileflowCommandDocument,
+} from '@tileflow/dev/validation';
+
+try {
+  const inspection = await inspectTileflowConfig({config: 'tileflow.config.ts'});
+  process.stdout.write(serializeTileflowCommandDocument(inspection));
+} catch (error) {
+  const failure = createTileflowCommandFailureDocument('inspect', error, process.cwd(), {
+    code: 'INSPECTION_FAILED',
+    phase: 'config-inspection',
+  });
+  process.stderr.write(serializeTileflowCommandDocument(failure));
+}
+```
+
+The inspection resolves one config load into sorted maps, root-to-leaf lineage, declared paths, and
+leaf-level merge provenance. Its `themeContract` exposes the default/system mapping, shared token
+schema, concrete resolved token values, typography and lighting, differences from the default, and
+stable `THEME_IMPLICIT_FIXED` diagnostics across modules, render stacks, and terrain. Each
+diagnostic carries a semantic scope and, for module values, its owner, plus machine-readable
+severity and remediation. Colors, fonts, and images are followed through
+expression outputs; numeric diagnostics intentionally cover only direct visual scalars, excluding
+expression operands, zoom stops, tuples, placement, priority, and other structural numbers.
+Agents can therefore edit semantic roles without
+reverse-engineering compiler layers or parsing prose. It never returns `inputFiles`, absolute filesystem paths, credentials,
+URL queries, data URLs, or recognized secret formats. Structured summaries and diagnostics use the
+same required schema-version-1 fields and bounded safe suggestions so consumers do not need to
+parse human prose.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/dev",
-  "version": "0.1.0-alpha.22",
+  "version": "0.1.0-alpha.24",
   "license": "Apache-2.0",
   "description": "Node development utilities for Tileflow configs and builds.",
   "type": "module",
@@ -28,6 +28,7 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "docs",
     "THIRD_PARTY_NOTICES.md",
     "LICENSE"
   ],
@@ -89,19 +90,19 @@
   "dependencies": {
     "@mapbox/vector-tile": "3.0.0",
     "@maplibre/maplibre-gl-style-spec": "24.8.5",
-    "@tileflow/core": ">=0.1.0-alpha.24 <0.1.0-beta.0",
+    "@tileflow/core": ">=0.1.0-alpha.25 <0.1.0-beta.0",
     "chokidar": "4.0.3",
     "fflate": "0.8.3",
     "fontkit": "2.0.4",
     "jiti": "^2.7.0",
-    "maplibre-gl": "5.24.0",
+    "maplibre-gl": "6.9.0",
     "pbf": "5.1.2",
     "pmtiles": "4.5.0",
     "saxes": "6.0.0",
     "three": "0.185.1"
   },
   "devDependencies": {
-    "@tileflow/maps": "0.1.0-alpha.2"
+    "@tileflow/maps": "0.1.0-alpha.4"
   },
   "optionalDependencies": {
     "sharp": "0.35.4"