datahike-browser-tests 1.0.0

package/src/datahike/codegen/report.clj

@@ -0,0 +1,55 @@
+(ns datahike.codegen.report
+  "Generate coverage reports for all code generation bindings."
+  (:require [datahike.api.specification :refer [api-specification]]
+            [datahike.codegen.validation :as validation]
+            [datahike.codegen.native :refer [native-operations native-excluded-operations]]
+            [datahike.codegen.python :refer [python-operations python-excluded-operations]]
+            [datahike.codegen.naming :refer [js-skip-list]]
+            [datahike.codegen.cli :refer [cli-excluded-operations]]))
+
+(defn generate-report
+  "Generate and print coverage report for all bindings."
+  []
+  (let [;; Validate each binding
+        java-result {:binding "Java"
+                     :total (count api-specification)
+                     :implemented (count api-specification)
+                     :excluded 0
+                     :missing 0
+                     :missing-ops []
+                     :coverage-pct 100}
+
+        ;; TypeScript - all ops except js-skip-list
+        typescript-ops (into {} (remove #(contains? js-skip-list (first %)) api-specification))
+        typescript-excluded (zipmap js-skip-list (repeat "ClojureScript incompatible"))
+        typescript-result (validation/validate-coverage
+                           "TypeScript"
+                           typescript-ops
+                           typescript-excluded)
+
+        ;; CLI - all ops except cli-excluded-operations
+        cli-ops (into {} (remove #(contains? cli-excluded-operations (first %)) api-specification))
+        cli-result (validation/validate-coverage
+                    "CLI"
+                    cli-ops
+                    cli-excluded-operations)
+
+        native-result (validation/validate-coverage
+                       "Native"
+                       native-operations
+                       native-excluded-operations)
+
+        python-result (validation/validate-coverage
+                       "Python"
+                       python-operations
+                       python-excluded-operations)
+
+        all-results [java-result typescript-result cli-result native-result python-result]]
+
+    ;; Print report
+    (validation/print-coverage-report all-results)))
+
+(defn -main
+  "Generate and print coverage report."
+  [& _args]
+  (generate-report))

package/src/datahike/codegen/typescript.clj

@@ -0,0 +1,262 @@
+(ns datahike.codegen.typescript
+  "Generate TypeScript type definitions from api.specification.
+
+  This namespace provides tooling to generate .d.ts files that:
+  - Map malli schemas to TypeScript types
+  - Provide proper Promise<T> types for async operations
+  - Include JSDoc comments with full documentation
+  - Support IDE autocompletion and type checking"
+  (:require [datahike.api.specification :refer [api-specification malli-schema->argslist]]
+            [datahike.api.types :as types]
+            [datahike.codegen.naming :refer [js-skip-list clj-name->js-name]]
+            [clojure.string :as str]))
+
+;; =============================================================================
+;; Malli -> TypeScript Type Mapping
+;; =============================================================================
+
+(defn malli->ts-type
+  "Convert a malli schema to a TypeScript type string."
+  [schema]
+  (cond
+    ;; Keyword schemas (primitives)
+    (keyword? schema)
+    (case schema
+      :boolean "boolean"
+      :string "string"
+      :int "number"
+      :long "number"
+      :double "number"
+      :number "number"
+      :keyword "string"
+      :symbol "string"
+      :any "any"
+      :nil "null"
+      :map "object"
+      :vector "Array<any>"
+      :sequential "Array<any>"
+      :set "Set<any>"
+      "any")
+
+    ;; Symbols (type references)
+    (symbol? schema)
+    (let [schema-name (name schema)]
+      (cond
+        ;; types/SConfig → DatabaseConfig
+        (str/starts-with? schema-name "types/")
+        (get types/malli->typescript-type
+             (keyword (subs schema-name 6))
+             "any")
+
+        ;; Direct type names
+        :else
+        (get types/malli->typescript-type
+             (keyword schema-name)
+             "any")))
+
+    ;; Vector schemas
+    (vector? schema)
+    (let [[op & args] schema]
+      (case op
+        ;; [:or Type1 Type2] → Type1 | Type2
+        :or
+        (str/join " | " (map malli->ts-type args))
+
+        ;; [:maybe Type] → Type | null
+        :maybe
+        (str (malli->ts-type (first args)) " | null")
+
+        ;; [:sequential Type] → Array<Type>
+        :sequential
+        (str "Array<" (malli->ts-type (first args)) ">")
+
+        ;; [:vector Type] → Array<Type>
+        :vector
+        (str "Array<" (malli->ts-type (first args)) ">")
+
+        ;; [:map ...] → object
+        :map
+        "object"
+
+        ;; [:function ...] or [:=> ...] - extract return type
+        (:function :=>)
+        "any"
+
+        ;; [:cat ...] - tuple, represent as array for now
+        :cat
+        "Array<any>"
+
+        ;; [:alt ...] - union
+        :alt
+        "any"
+
+        ;; [:* Type] - rest params
+        :*
+        (str "..." (malli->ts-type (first args)) "[]")
+
+        ;; [:enum ...] - union of literals
+        :enum
+        (str/join " | " (map #(str "'" % "'") args))
+
+        ;; [:fn ...] - function type
+        :fn
+        "Function"
+
+        ;; Default
+        "any"))
+
+    ;; Default
+    :else "any"))
+
+(defn extract-params-from-malli
+  "Extract parameter information from malli function schema.
+   Returns vector of maps with :name, :type, and :optional keys."
+  [args-schema]
+  (cond
+    ;; [:=> [:cat Type1 Type2] Return]
+    (and (vector? args-schema) (= :=> (first args-schema)))
+    (let [[_ input-schema _] args-schema]
+      (when (and (vector? input-schema) (= :cat (first input-schema)))
+        (vec
+         (map-indexed
+          (fn [idx type-schema]
+            {:name (str "arg" idx)
+             :type (malli->ts-type type-schema)
+             :optional false})
+          (rest input-schema)))))
+
+    ;; [:function [:=> ...] [:=> ...]] - multi-arity, use first
+    (and (vector? args-schema) (= :function (first args-schema)))
+    (let [first-arity (second args-schema)]
+      (extract-params-from-malli first-arity))
+
+    ;; Default
+    :else []))
+
+(defn generate-function-signature
+  "Generate TypeScript function signature from specification entry."
+  [[fn-name {:keys [args ret doc]}]]
+  (let [ts-name (clj-name->js-name fn-name)
+        params (extract-params-from-malli args)
+        params-str (str/join ", "
+                             (map (fn [{:keys [name type optional]}]
+                                    (str name (if optional "?" "") ": " type))
+                                  params))
+        return-type (malli->ts-type ret)
+        ;; Wrap in Promise for async operations
+        final-return (str "Promise<" return-type ">")]
+    {:name ts-name
+     :signature (str "export function " ts-name "(" params-str "): " final-return ";")
+     :doc doc}))
+
+(defn generate-jsdoc
+  "Generate JSDoc comment from docstring and examples."
+  [doc examples]
+  (when doc
+    (let [;; Extract first sentence for summary
+          summary (first (str/split doc #"\.\s"))
+          ;; Add examples if available
+          example-text (when (seq examples)
+                         (str "\n *\n * Examples:\n"
+                              (str/join "\n"
+                                        (map (fn [{:keys [desc code]}]
+                                               (str " * - " desc "\n"
+                                                    " *   " code))
+                                             (take 2 examples)))))]
+      (str "/**\n * " summary "."
+           example-text
+           "\n */"))))
+
+(defn generate-type-definitions
+  "Generate complete TypeScript type definitions from api-specification."
+  []
+  (let [header "// Auto-generated TypeScript definitions for Datahike JavaScript API
+// DO NOT EDIT - Generated from datahike.api.specification
+
+"
+        ;; Core type definitions
+        types "
+// Core Datahike Types
+
+export interface DatabaseConfig {
+  store: {
+    backend: string;
+    id?: string;
+    path?: string;
+    [key: string]: any;
+  };
+  'keep-history'?: boolean;
+  'schema-flexibility'?: 'read' | 'write';
+  'initial-tx'?: Transaction[];
+  name?: string;
+  [key: string]: any;
+}
+
+export interface Connection {
+  [key: string]: any;
+}
+
+export interface Database {
+  [key: string]: any;
+}
+
+export type Transaction =
+  | [':db/add', number | string, string, any]
+  | [':db/retract', number | string, string, any]
+  | { [key: string]: any };
+
+export interface TransactionReport {
+  'db-before': Database;
+  'db-after': Database;
+  'tx-data': Datom[];
+  tempids: { [key: string]: number };
+  'tx-meta'?: any;
+}
+
+export interface Datom {
+  e: number;
+  a: string;
+  v: any;
+  tx: number;
+  added: boolean;
+}
+
+export interface Schema {
+  [key: string]: {
+    'db/valueType': string;
+    'db/cardinality': string;
+    'db/unique'?: string;
+    'db/index'?: boolean;
+    [key: string]: any;
+  };
+}
+
+export interface Metrics {
+  [key: string]: any;
+}
+
+"
+        ;; Generate function signatures
+        functions (str/join "\n\n"
+                            (for [entry (sort-by first api-specification)
+                                  :when (not (contains? js-skip-list (first entry)))
+                                  :let [[fn-name spec-data] entry
+                                        {:keys [name signature doc]} (generate-function-signature entry)
+                                        jsdoc (generate-jsdoc doc (:examples spec-data))]]
+                              (str jsdoc "\n" signature)))]
+    (str header types "\n// API Functions\n\n" functions "\n")))
+
+(defn write-type-definitions!
+  "Write TypeScript definitions to a file."
+  ([]
+   (write-type-definitions! "npm-package/index.d.ts"))
+  ([output-path]
+   (spit output-path (generate-type-definitions))
+   (println "TypeScript definitions written to:" output-path)))
+
+(comment
+  ;; Generate types
+  (println (generate-type-definitions))
+
+  ;; Write to file
+  (write-type-definitions!))

package/src/datahike/codegen/validation.clj

@@ -0,0 +1,145 @@
+(ns datahike.codegen.validation
+  "Validation utilities for code generation coverage.
+
+  Ensures all API operations are either implemented or explicitly excluded
+  across all language bindings."
+  (:require [datahike.api.specification :refer [api-specification]]
+            [clojure.string :as str]
+            [clojure.set :as set]))
+
+;; =============================================================================
+;; Coverage Validation
+;; =============================================================================
+
+(defn validate-coverage
+  "Validate that all operations are either implemented or excluded.
+
+  Args:
+    binding-name - String name for display (e.g., 'Native', 'Python')
+    operations - Map of implemented operations
+    excluded - Map or set of excluded operations
+
+  Returns:
+    Map with :missing, :implemented, :excluded, :total"
+  [binding-name operations excluded]
+  (let [all-ops (set (keys api-specification))
+        implemented (set (keys operations))
+        ;; Handle both maps (with reasons) and sets (just symbols)
+        excluded-ops (if (map? excluded)
+                       (set (keys excluded))
+                       (set excluded))
+        missing (set/difference all-ops implemented excluded-ops)
+        total (count all-ops)
+        impl-count (count implemented)
+        excl-count (count excluded-ops)
+        miss-count (count missing)]
+
+    ;; Print warnings for missing operations
+    (when (seq missing)
+      (println (str "\n⚠️  WARNING: " binding-name " bindings missing operations:"))
+      (doseq [op (sort missing)]
+        (println (str "  - " op)))
+      (println (str "\n  Either add to " (str/lower-case binding-name) "-operations"
+                    " or " (str/lower-case binding-name) "-excluded-operations\n")))
+
+    {:binding binding-name
+     :total total
+     :implemented impl-count
+     :excluded excl-count
+     :missing miss-count
+     :missing-ops (sort missing)
+     :coverage-pct (int (* 100 (/ (+ impl-count excl-count) total)))}))
+
+;; =============================================================================
+;; Coverage Reporting
+;; =============================================================================
+
+(defn print-coverage-line
+  "Print a single line of the coverage table."
+  [{:keys [binding total implemented excluded missing coverage-pct]}]
+  (let [status (if (zero? missing) "✅" "⚠️ ")
+        impl-excl (if (zero? excluded)
+                    (format "%2d" implemented)
+                    (format "%2d+%d" implemented excluded))
+        coverage-str (format "%3d%%" coverage-pct)]
+    (printf "%-12s %s/%2d (%s) %s%s\n"
+            (str binding ":")
+            impl-excl
+            total
+            coverage-str
+            status
+            (if (zero? excluded)
+              ""
+              (format " (%d excluded)" excluded)))))
+
+(defn print-coverage-report
+  "Print coverage report for all bindings.
+
+  Args:
+    results - Sequence of validation results from validate-coverage"
+  [results]
+  (println "\nCode Generation Coverage Report")
+  (println "================================\n")
+  (printf "Total operations in api-specification: %d\n\n"
+          (:total (first results)))
+
+  (doseq [result (sort-by :binding results)]
+    (print-coverage-line result))
+
+  ;; Print missing operations detail
+  (let [missing-any (filter #(pos? (:missing %)) results)]
+    (when (seq missing-any)
+      (println "\nMissing Operations:")
+      (doseq [{:keys [binding missing-ops]} missing-any]
+        (println (str "\n" binding ":"))
+        (doseq [op missing-ops]
+          (println (str "  - " op))))))
+
+  (println))
+
+(defn validate-exclusion-reasons
+  "Validate that all exclusions have documented reasons.
+
+  Args:
+    binding-name - String name for display
+    excluded - Map of excluded operations to reason strings, or set (skips validation)
+
+  Returns true if all have reasons (or is a set), prints warnings otherwise"
+  [binding-name excluded]
+  ;; Skip validation for sets (they don't have reasons)
+  (if-not (map? excluded)
+    true
+    (let [missing-reasons (filter (fn [[_ reason]]
+                                    (or (nil? reason)
+                                        (str/blank? reason)))
+                                  excluded)]
+      (when (seq missing-reasons)
+        (println (str "\n⚠️  WARNING: " binding-name " exclusions missing reasons:"))
+        (doseq [[op _] missing-reasons]
+          (println (str "  - " op)))
+        (println))
+      (empty? missing-reasons))))
+
+;; =============================================================================
+;; Overlay Validation
+;; =============================================================================
+
+(defn validate-overlay-completeness
+  "Validate that overlay provides required config for each operation.
+
+  Args:
+    binding-name - String name for display
+    operations - Map of operation overlays
+    required-keys - Vector of required keys in overlay (e.g., [:pattern :java-call])
+
+  Prints warnings for incomplete overlays"
+  [binding-name operations required-keys]
+  (let [incomplete (filter (fn [[op-name config]]
+                             (not-every? #(contains? config %) required-keys))
+                           operations)]
+    (when (seq incomplete)
+      (println (str "\n⚠️  WARNING: " binding-name " incomplete overlay configs:"))
+      (doseq [[op-name config] incomplete]
+        (let [missing (filter #(not (contains? config %)) required-keys)]
+          (println (str "  - " op-name ": missing " (str/join ", " missing)))))
+      (println))))