@vmz/diagnostic 0.0.0 → 0.1.18

package/README.md

@@ -1,3 +1,13 @@
-# @vmz/diagnostic
+# `@vmz/diagnostic`
 
-Placeholder package (0.0.0). Reserved for the VMZ project.
+Diagnostic layout for structured `code + args + span` rows.
+
+- Caller injects `t` / catalog (official tables live in `@vmz/vmz`)
+- No built-in language packs; no separate i18n package
+- Deepen snippet / caret when the product CLI needs them
+
+```ts
+import { formatDiagnostic } from '@vmz/diagnostic';
+
+formatDiagnostic(row, { locale: 'en-US', catalog: productCatalog });
+```

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `@vmz/diagnostic` — catalog render + pretty printer (skeleton).
+ *
+ * Product path: N-API diagnostic wire → `t(code, args)` → layout.
+ */
+/** Message id → template (`{name}` placeholders). */
+export type LocaleCatalog = Record<string, string>;
+/** Severity labels on the wire (kebab-case). */
+export type Severity = 'error' | 'warning' | 'advice';
+/** UTF-8 byte offset span (line/col only at render time). */
+export type SourceSpan = {
+    start: number;
+    end: number;
+};
+/** Language-neutral diagnostic row (product wire shape). */
+export type DiagnosticInput = {
+    path: string;
+    severity: Severity;
+    code: string;
+    args?: Record<string, string>;
+    /**
+     * Transitional wire prose when the product catalog has no entry for `code`.
+     * Prefer catalog templates; do not treat this as a second i18n source of truth.
+     */
+    message?: string;
+    span?: SourceSpan;
+};
+/** Optional offset → line/col context (aligned with compiler OffsetIndex later). */
+export type PositionContext = {
+    lineCol(offset: number): {
+        line: number;
+        column: number;
+    };
+};
+export type FormatOptions = {
+    locale: string;
+    catalog: LocaleCatalog | ((locale: string) => LocaleCatalog);
+    sourceText?: string;
+    position?: PositionContext;
+};
+/**
+ * Resolve a catalog template with `{arg}` substitution.
+ * Missing keys fall back to `{{code}}` so wire identity stays visible.
+ */
+export declare function t(code: string, args: Record<string, string> | undefined, catalog: LocaleCatalog): string;
+/**
+ * Format one diagnostic for terminal / logs.
+ * Skeleton: single-line `path: severity[code]: message` — no snippet yet.
+ */
+export declare function formatDiagnostic(d: DiagnosticInput, opts: FormatOptions): string;
+/**
+ * Format many diagnostics, one per line.
+ */
+export declare function formatDiagnostics(list: DiagnosticInput[], opts: FormatOptions): string;

package/dist/index.js

@@ -0,0 +1,56 @@
+/**
+ * `@vmz/diagnostic` — catalog render + pretty printer (skeleton).
+ *
+ * Product path: N-API diagnostic wire → `t(code, args)` → layout.
+ */
+/**
+ * Resolve a catalog template with `{arg}` substitution.
+ * Missing keys fall back to `{{code}}` so wire identity stays visible.
+ */
+export function t(code, args, catalog) {
+    const template = catalog[code];
+    if (template == null) {
+        return `{{${code}}}`;
+    }
+    return template.replace(/\{([a-zA-Z0-9_.-]+)\}/g, (_m, name) => {
+        if (args && Object.prototype.hasOwnProperty.call(args, name)) {
+            return args[name] ?? '';
+        }
+        return `{${name}}`;
+    });
+}
+function resolveCatalog(locale, catalog) {
+    return typeof catalog === 'function' ? catalog(locale) : catalog;
+}
+/**
+ * Format one diagnostic for terminal / logs.
+ * Skeleton: single-line `path: severity[code]: message` — no snippet yet.
+ */
+export function formatDiagnostic(d, opts) {
+    if (!d.code || typeof d.code !== 'string') {
+        throw new Error('@vmz/diagnostic: DiagnosticInput.code is required');
+    }
+    const catalog = resolveCatalog(opts.locale, opts.catalog);
+    const message = Object.prototype.hasOwnProperty.call(catalog, d.code)
+        ? t(d.code, d.args, catalog)
+        : d.message != null && String(d.message).length
+            ? String(d.message)
+            : t(d.code, d.args, catalog);
+    const where = formatWhere(d, opts);
+    const head = where ? `${where}: ` : '';
+    return `${head}${d.severity}[${d.code}]: ${message}`;
+}
+/**
+ * Format many diagnostics, one per line.
+ */
+export function formatDiagnostics(list, opts) {
+    return list.map((d) => formatDiagnostic(d, opts)).join('\n');
+}
+function formatWhere(d, opts) {
+    const path = d.path || '';
+    if (!d.span || !opts.position) {
+        return path;
+    }
+    const { line, column } = opts.position.lineCol(d.span.start);
+    return path ? `${path}:${line}:${column}` : `${line}:${column}`;
+}

package/package.json

@@ -1,10 +1,38 @@
 {
   "name": "@vmz/diagnostic",
-  "version": "0.0.0",
-  "description": "VMZ placeholder ?not for production use.",
+  "version": "0.1.18",
+  "type": "module",
+  "description": "Language-neutral diagnostic catalog render and pretty printer",
   "license": "MIT",
-  "private": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
   "files": [
+    "dist",
     "README.md"
-  ]
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "keywords": [
+    "vmz",
+    "diagnostic",
+    "i18n",
+    "pretty-print"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/doki-land/vmz-framework.git"
+  }
 }