@tileflow/dev 0.1.0-alpha.3 → 0.1.0-alpha.30

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,16 +1,18 @@
 {
   "name": "@tileflow/dev",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.30",
+  "license": "Apache-2.0",
   "description": "Node development utilities for Tileflow configs and builds.",
   "type": "module",
+  "sideEffects": false,
   "homepage": "https://tileflow.dev",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/tileflow/tileflow.git",
+    "url": "git+https://github.com/tileflow/tileflow-sdk.git",
     "directory": "packages/dev"
   },
   "bugs": {
-    "url": "https://github.com/tileflow/tileflow/issues"
+    "url": "https://github.com/tileflow/tileflow-sdk/issues"
   },
   "keywords": [
     "tileflow",
@@ -19,28 +21,90 @@
     "development",
     "styles"
   ],
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "engines": {
+    "node": ">=22"
+  },
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "THIRD_PARTY_NOTICES.md",
+    "LICENSE"
   ],
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
+    "./artifacts": {
+      "types": "./dist/artifacts.d.ts",
+      "import": "./dist/artifacts.js",
+      "default": "./dist/artifacts.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js",
+      "default": "./dist/config.js"
+    },
+    "./icons": {
+      "types": "./dist/icons.d.ts",
+      "import": "./dist/icons.js",
+      "default": "./dist/icons.js"
+    },
+    "./fonts": {
+      "types": "./dist/fonts.d.ts",
+      "import": "./dist/fonts.js",
+      "default": "./dist/fonts.js"
+    },
+    "./inspect": {
+      "types": "./dist/inspect.d.ts",
+      "import": "./dist/inspect.js",
+      "default": "./dist/inspect.js"
+    },
+    "./preview": {
+      "types": "./dist/preview.d.ts",
+      "import": "./dist/preview.js",
+      "default": "./dist/preview.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "default": "./dist/server.js"
+    },
+    "./tilesets": {
+      "types": "./dist/tilesets.d.ts",
+      "import": "./dist/tilesets.js",
+      "default": "./dist/tilesets.js"
+    },
+    "./validation": {
+      "types": "./dist/validation.d.ts",
+      "import": "./dist/validation.js",
+      "default": "./dist/validation.js"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
+    "@mapbox/vector-tile": "3.0.0",
+    "@maplibre/maplibre-gl-style-spec": "24.8.5",
+    "@tileflow/core": ">=0.1.0-alpha.32 <0.1.0-beta.0",
+    "chokidar": "4.0.3",
+    "fflate": "0.8.3",
+    "fontkit": "2.0.4",
     "jiti": "^2.7.0",
-    "@tileflow/core": "0.1.0-alpha.3"
+    "maplibre-gl": "6.13.0",
+    "pbf": "5.1.2",
+    "pmtiles": "4.5.0",
+    "saxes": "6.0.0",
+    "three": "0.185.1"
+  },
+  "devDependencies": {
+    "@tileflow/maps": "0.1.0-alpha.8"
+  },
+  "optionalDependencies": {
+    "sharp": "0.35.5"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean --platform node",
+    "build": "tsup src/artifacts.ts src/config.ts src/fonts.ts src/icons.ts src/inspect.ts src/preview.ts src/server.ts src/tilesets.ts src/validation.ts --format esm --dts --clean --platform node --external sharp",
+    "test": "tsx --test test/*.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "lint": "tsc -p tsconfig.json --noEmit"
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "verify": "pnpm run typecheck && pnpm run test"
   }
 }

package/dist/index.d.ts

@@ -1,54 +0,0 @@
-import { TileflowManifest, MapLibreStyle, ValidationMessage, TileflowProjectConfig, TileflowStyleOptions } from '@tileflow/core';
-
-declare const defaultTileflowApiUrl = "https://api.tileflow.dev";
-declare const defaultTileflowConfigPath = "tileflow.config.ts";
-declare const defaultTileflowManifestPath = "public/tileflow/manifest.json";
-declare const defaultTileflowTileset = "world";
-type LoadTileflowConfigOptions = {
-    cwd?: string;
-    fresh?: boolean;
-};
-type TileflowManifestOptions = {
-    styleBaseUrl?: string;
-    tileBaseUrl?: string;
-};
-type TileflowDevRequestHandlerOptions = {
-    basePath?: string;
-    config?: string;
-    cwd?: string;
-    onError?: (error: unknown) => void;
-    styleBaseUrl?: string;
-    tileBaseUrl?: string;
-};
-type TileflowBuildArtifactsOptions = {
-    config?: string;
-    cwd?: string;
-    styleBaseUrl?: string;
-    tileBaseUrl?: string;
-};
-type TileflowBuildArtifacts = {
-    manifest: TileflowManifest;
-    styles: Record<string, MapLibreStyle>;
-};
-type WriteTileflowBuildArtifactsOptions = TileflowBuildArtifactsOptions & {
-    outDir: string;
-};
-declare class TileflowValidationError extends Error {
-    readonly messages: ValidationMessage[];
-    constructor(messages: ValidationMessage[]);
-}
-declare function loadTileflowConfig(configPath?: string, options?: LoadTileflowConfigOptions): Promise<TileflowProjectConfig>;
-declare function loadValidTileflowConfig(configPath?: string, options?: LoadTileflowConfigOptions): Promise<TileflowProjectConfig>;
-declare function assertValidTileflowConfig(project: TileflowProjectConfig): void;
-declare function asTileflowProjectConfig(input: unknown): TileflowProjectConfig;
-declare function getTileflowMapNames(project: TileflowProjectConfig): string[];
-declare function getFirstTileflowMapName(project: TileflowProjectConfig): string;
-declare function getTileflowStyleMapName(path: string): string;
-declare function createTileflowManifest(project: TileflowProjectConfig, options?: TileflowManifestOptions): TileflowManifest;
-declare function createTileflowStyle(project: TileflowProjectConfig, mapName: string, options?: TileflowStyleOptions): MapLibreStyle;
-declare function createTileflowBuildArtifacts(options?: TileflowBuildArtifactsOptions): Promise<TileflowBuildArtifacts>;
-declare function writeTileflowBuildArtifacts(options: WriteTileflowBuildArtifactsOptions): Promise<TileflowBuildArtifacts>;
-declare function createTileflowDevRequestHandler(options?: TileflowDevRequestHandlerOptions): (request: Request) => Promise<Response>;
-declare function normalizeTileflowBasePath(value?: string): string;
-
-export { type LoadTileflowConfigOptions, type TileflowBuildArtifacts, type TileflowBuildArtifactsOptions, type TileflowDevRequestHandlerOptions, type TileflowManifestOptions, TileflowValidationError, type WriteTileflowBuildArtifactsOptions, asTileflowProjectConfig, assertValidTileflowConfig, createTileflowBuildArtifacts, createTileflowDevRequestHandler, createTileflowManifest, createTileflowStyle, defaultTileflowApiUrl, defaultTileflowConfigPath, defaultTileflowManifestPath, defaultTileflowTileset, getFirstTileflowMapName, getTileflowMapNames, getTileflowStyleMapName, loadTileflowConfig, loadValidTileflowConfig, normalizeTileflowBasePath, writeTileflowBuildArtifacts };

package/dist/index.js

@@ -1,314 +0,0 @@
-// src/index.ts
-import {
-  createManifest,
-  createStyleFromProject,
-  validateConfig
-} from "@tileflow/core";
-import { existsSync } from "fs";
-import { mkdir, writeFile } from "fs/promises";
-import { resolve } from "path";
-import { createJiti } from "jiti";
-var defaultTileflowApiUrl = "https://api.tileflow.dev";
-var defaultTileflowConfigPath = "tileflow.config.ts";
-var defaultTileflowManifestPath = "public/tileflow/manifest.json";
-var defaultTileflowTileset = "world";
-var TileflowValidationError = class extends Error {
-  messages;
-  constructor(messages) {
-    super("Invalid Tileflow config");
-    this.name = "TileflowValidationError";
-    this.messages = messages;
-  }
-};
-async function loadTileflowConfig(configPath = defaultTileflowConfigPath, options = {}) {
-  const cwd = options.cwd ?? process.cwd();
-  const resolvedPath = resolve(cwd, configPath);
-  if (!existsSync(resolvedPath)) {
-    throw new Error(`Config not found: ${configPath}`);
-  }
-  const jiti = createJiti(import.meta.url, {
-    fsCache: false,
-    moduleCache: !options.fresh
-  });
-  const imported = await jiti.import(resolvedPath, { default: true });
-  return asTileflowProjectConfig(imported);
-}
-async function loadValidTileflowConfig(configPath = defaultTileflowConfigPath, options = {}) {
-  const project = await loadTileflowConfig(configPath, options);
-  assertValidTileflowConfig(project);
-  return project;
-}
-function assertValidTileflowConfig(project) {
-  const result = validateConfig(project);
-  if (!result.valid) {
-    throw new TileflowValidationError(result.messages);
-  }
-}
-function asTileflowProjectConfig(input) {
-  if (input && typeof input === "object" && "maps" in input && typeof input.maps === "object") {
-    return input;
-  }
-  return {
-    tilesets: {
-      [defaultTileflowTileset]: {
-        id: defaultTileflowTileset,
-        name: "World"
-      }
-    },
-    maps: {
-      main: input
-    }
-  };
-}
-function getTileflowMapNames(project) {
-  return Object.keys(project.maps);
-}
-function getFirstTileflowMapName(project) {
-  const [mapName] = getTileflowMapNames(project);
-  if (!mapName) {
-    throw new Error("Tileflow config must define at least one map.");
-  }
-  return mapName;
-}
-function getTileflowStyleMapName(path) {
-  const fileName = path.split("/").pop() ?? "";
-  return fileName.replace(/\.json$/, "");
-}
-function createTileflowManifest(project, options = {}) {
-  return createManifest(project, options);
-}
-function createTileflowStyle(project, mapName, options = {}) {
-  return createStyleFromProject(project, mapName, options);
-}
-async function createTileflowBuildArtifacts(options = {}) {
-  const project = await loadValidTileflowConfig(
-    options.config ?? defaultTileflowConfigPath,
-    {
-      cwd: options.cwd,
-      fresh: true
-    }
-  );
-  const styleOptions = { tileBaseUrl: options.tileBaseUrl };
-  const styles = Object.fromEntries(
-    getTileflowMapNames(project).map((mapName) => [
-      mapName,
-      createStyleFromProject(project, mapName, styleOptions)
-    ])
-  );
-  return {
-    manifest: createManifest(project, {
-      styleBaseUrl: options.styleBaseUrl,
-      tileBaseUrl: options.tileBaseUrl
-    }),
-    styles
-  };
-}
-async function writeTileflowBuildArtifacts(options) {
-  const cwd = options.cwd ?? process.cwd();
-  const outDir = resolve(cwd, options.outDir);
-  const stylesDir = resolve(outDir, "styles");
-  const artifacts = await createTileflowBuildArtifacts(options);
-  await mkdir(stylesDir, { recursive: true });
-  for (const [mapName, style] of Object.entries(artifacts.styles)) {
-    await writeFile(
-      resolve(stylesDir, `${mapName}.json`),
-      `${JSON.stringify(style, null, 2)}
-`,
-      "utf8"
-    );
-  }
-  await writeFile(
-    resolve(outDir, "manifest.json"),
-    `${JSON.stringify(artifacts.manifest, null, 2)}
-`,
-    "utf8"
-  );
-  return artifacts;
-}
-function createTileflowDevRequestHandler(options = {}) {
-  const basePath = normalizeTileflowBasePath(options.basePath);
-  const configPath = options.config ?? defaultTileflowConfigPath;
-  const cwd = options.cwd ?? process.cwd();
-  const tileBaseUrl = options.tileBaseUrl ?? defaultTileflowApiUrl;
-  return async function handleTileflowDevRequest(request) {
-    if (request.method !== "GET" && request.method !== "HEAD") {
-      return jsonResponse({ error: "Method not allowed" }, 405);
-    }
-    const url = new URL(request.url);
-    const path = stripTileflowBasePath(url.pathname, basePath);
-    if (path === null) {
-      return jsonResponse({ error: "Not found" }, 404);
-    }
-    try {
-      if (path === "/" || path === "") {
-        const project = await loadValidTileflowConfig(configPath, {
-          cwd,
-          fresh: true
-        });
-        return htmlResponse(
-          previewHtml(getFirstTileflowMapName(project), basePath)
-        );
-      }
-      if (path === "/manifest.json") {
-        const project = await loadValidTileflowConfig(configPath, {
-          cwd,
-          fresh: true
-        });
-        const styleBaseUrl = options.styleBaseUrl ?? `${url.origin}${basePath}`;
-        return jsonResponse(
-          createManifest(project, {
-            styleBaseUrl,
-            tileBaseUrl
-          })
-        );
-      }
-      if (path === "/style.json") {
-        const project = await loadValidTileflowConfig(configPath, {
-          cwd,
-          fresh: true
-        });
-        return jsonResponse(
-          createStyleFromProject(project, getFirstTileflowMapName(project), {
-            tileBaseUrl
-          })
-        );
-      }
-      if (path.startsWith("/styles/")) {
-        const project = await loadValidTileflowConfig(configPath, {
-          cwd,
-          fresh: true
-        });
-        const mapName = getTileflowStyleMapName(path);
-        if (!project.maps[mapName]) {
-          return jsonResponse({ error: `Unknown map: ${mapName}` }, 404);
-        }
-        return jsonResponse(
-          createStyleFromProject(project, mapName, {
-            tileBaseUrl
-          })
-        );
-      }
-      return jsonResponse({ error: "Not found" }, 404);
-    } catch (error) {
-      options.onError?.(error);
-      return tileflowErrorResponse(error);
-    }
-  };
-}
-function normalizeTileflowBasePath(value = "") {
-  const trimmed = value.trim().replace(/^\/+|\/+$/g, "");
-  return trimmed ? `/${trimmed}` : "";
-}
-function stripTileflowBasePath(pathname, basePath) {
-  if (!basePath) {
-    return pathname;
-  }
-  if (pathname === basePath) {
-    return "/";
-  }
-  if (pathname.startsWith(`${basePath}/`)) {
-    return pathname.slice(basePath.length);
-  }
-  return null;
-}
-function tileflowErrorResponse(error) {
-  if (error instanceof TileflowValidationError) {
-    return jsonResponse(
-      {
-        error: error.message,
-        messages: error.messages
-      },
-      400
-    );
-  }
-  const message = error instanceof Error ? error.message : "Unknown error";
-  return jsonResponse({ error: message }, 500);
-}
-function jsonResponse(body, status = 200) {
-  return new Response(`${JSON.stringify(body, null, 2)}
-`, {
-    headers: {
-      "Access-Control-Allow-Origin": "*",
-      "Cache-Control": "no-store",
-      "Content-Type": "application/json; charset=utf-8"
-    },
-    status
-  });
-}
-function htmlResponse(body, status = 200) {
-  return new Response(body, {
-    headers: {
-      "Access-Control-Allow-Origin": "*",
-      "Cache-Control": "no-store",
-      "Content-Type": "text/html; charset=utf-8"
-    },
-    status
-  });
-}
-function previewHtml(mapName, basePath) {
-  const styleUrl = `${basePath}/styles/${mapName}.json`;
-  return `<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Tileflow Preview</title>
-    <link rel="preconnect" href="https://fonts.googleapis.com" />
-    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap" rel="stylesheet" />
-    <link rel="stylesheet" href="https://unpkg.com/maplibre-gl@latest/dist/maplibre-gl.css" />
-    <style>
-      html, body, #map { height: 100%; margin: 0; }
-      body { font-family: Inter, ui-sans-serif, system-ui, sans-serif; }
-      .badge {
-        position: fixed;
-        left: 16px;
-        top: 16px;
-        z-index: 1;
-        border-radius: 8px;
-        background: rgba(246, 247, 243, 0.92);
-        border: 1px solid rgba(60, 64, 67, 0.12);
-        color: #3C4043;
-        padding: 10px 12px;
-        box-shadow: 0 10px 40px rgba(0, 0, 0, 0.12);
-      }
-    </style>
-  </head>
-  <body>
-    <div class="badge">Tileflow preview</div>
-    <div id="map"></div>
-    <script type="module">
-      import maplibregl from "https://unpkg.com/maplibre-gl@latest/dist/maplibre-gl.js";
-
-      const map = new maplibregl.Map({
-        container: "map",
-        style: "${styleUrl}",
-        center: [-3.7038, 40.4168],
-        zoom: 12
-      });
-
-      map.addControl(new maplibregl.NavigationControl(), "top-right");
-    </script>
-  </body>
-</html>`;
-}
-export {
-  TileflowValidationError,
-  asTileflowProjectConfig,
-  assertValidTileflowConfig,
-  createTileflowBuildArtifacts,
-  createTileflowDevRequestHandler,
-  createTileflowManifest,
-  createTileflowStyle,
-  defaultTileflowApiUrl,
-  defaultTileflowConfigPath,
-  defaultTileflowManifestPath,
-  defaultTileflowTileset,
-  getFirstTileflowMapName,
-  getTileflowMapNames,
-  getTileflowStyleMapName,
-  loadTileflowConfig,
-  loadValidTileflowConfig,
-  normalizeTileflowBasePath,
-  writeTileflowBuildArtifacts
-};