Trust ClojureScript :file analysis metadata

Updated ClojureScript's reader to use the :file metadata returned by analysis.
It formerly set :file to the actual path of the :file it was analysing. This
change matches the Clojure reader behaviour and allows for potemkin import-vars
type manipulation of metadata to, for example, point at an alternate var's docs
in a different source file.

To verify readers are still returning data that we expect, I added some tests
based on the existing playgound under test-sources. The tests are a good start
but not comprehensive and should be extended as needed. Circleci config
is included to automatically run tests on commit.

While adding tests, I noticed small bugs and made corrections:
1. The ClojureScript reader now sorts protocol methods by name. This
   matches the behaviour of the Clojure reader.
2. The Clojure reader will now add a single var for each defrecord
   with the name of the defrecord. This matches the ClojureScript
   behaviour and is apparently the desired behaviour for cljdoc.

For consistency and testability:
  - we are now removing keys with empty/nil values from reader analysis maps.
  - to be conistent with the ClojureScript reader, the Clojure reader no longer
    returns :file :line :column :end-column and :end-line on the namespace
    element.

For maintainability and to reduce confusion I removed unused: html writer,
resources and project.clj.

Notes:

As part of this change, the ClojureScript reader will stop supressing protocol
functions when the actual source does not match the :file metadata. This allows
for a tool such as import-vars to point to, and have documented, an imported
protocol function. No action was needed for the Clojure reader to make this
work.

This change was made a bit challenging due to cljdoc's usage of codox's
root-dir and :file metadata:

  The original intent of codox is that the config :root-dir point to the
  project (aka git) root of a project and that the :file metadata
  was simply what was returned by analysis. Codox added the :path to analysis
  metadata to resolve :file to the :root-dir.

  Cljdoc does not set the :root-dir to the project root, ignores the :path and
  assumes that the :file is always relative to configured :source-path. Although
  this usage works for cljdoc, it did sprain my brain while making this change.

  To compensate, I have been careful to ensure that :file continues to always
  be relative to the the configured :source-path.

Another oddity was that altered :file metadata is being resolved to paths
within the jar file when codox is called from cljdoc. This might be due to the
way the classpath is setup when doing an analysis run. My change is coded to
handle this situation when it arises.

Author: lread

.circleci/config.yml

@@ -0,0 +1,49 @@
+# Clojure CircleCI 2.0 configuration file
+#
+# Check https://circleci.com/docs/2.0/language-clojure/ for more details
+#
+version: 2
+jobs:
+  build:
+    branches:
+      only:
+        - /cljs-proper.*/
+
+    docker:
+      - image: circleci/clojure:tools-deps-1.10.0.442
+
+    working_directory: ~/repo
+
+    steps:
+      - checkout
+
+      - restore_cache:
+          keys:
+            - v1-dependencies-{{ checksum "codox/deps.edn" }}
+            - v1-dependencies- # fallback if cache not found
+
+      - run:
+          name: Dump tool versions
+          command: clojure -e '(println (System/getProperty "java.runtime.name") (System/getProperty "java.runtime.version") "\nClojure" (clojure-version))'
+          working_directory: ~/repo/codox
+
+      - run:
+          name: Dump classpath
+          command: clojure -Spath
+          working_directory: ~/repo/codox
+
+      - run:
+          name: Run tests
+          command: clojure -Atest --reporter documentation --plugin kaocha.plugin/junit-xml --junit-xml-file target/test-results/unit/results.xml
+          working_directory: ~/repo/codox
+
+      - save_cache:
+          paths:
+            - ~/.m2
+          key: v1-dependencies-{{ checksum "codox/deps.edn" }}
+
+      - store_test_results:
+          path: codox/target/test-results
+
+      - store_artifacts:
+          path: codox/target/test-results

.gitignore

@@ -1,9 +1,11 @@
 pom.xml
 pom.xml.asc
 *jar
+.cpcache/
 lib/
 classes/
 target/
+out/
 checkouts/
 .lein-*
 .nrepl-port

README.md

@@ -1,9 +1,12 @@
 ### Notes about this fork
 
-- Focused on extracting structured data (EDN) from jars.
-- Any writing-related (HTML etc.) dependencies have been removed, code is kept to keep diff to mainline manageable.
-- Various tweaks have been done to align the results of Clojure and ClojureScript analysis.
+[![CircleCI](https://circleci.com/gh/cljdoc/codox/tree/cljs-proper.svg?style=svg)](https://circleci.com/gh/cljdoc/codox/tree/cljs-proper)
 
+- Focused on extracting structured data (EDN) from jars for cljdoc which makes use of work under codox subdir only.
+- Any writing-related (HTML etc.) dependencies have been removed.
+- Any remaining unused files are kept only to keep diff to mainline manageable.
+- Various tweaks have been done to align the results of Clojure and ClojureScript analysis.
+- During dev, tests can be run via `clojure -A:test --watch`
 
 ---
 

codox/deps.edn

@@ -1,4 +1,9 @@
-{:paths ["src" "resources" "test-sources"]
+{:paths ["src"]
  :deps {org.clojure/clojure {:mvn/version "1.9.0"}
         org.clojure/tools.namespace {:mvn/version "0.2.11"}
-        org.clojure/clojurescript {:mvn/version "1.10.339"}}}
+        org.clojure/clojurescript {:mvn/version "1.10.520"}}
+ :aliases {:test
+            {:extra-paths ["test" "test-sources"]
+             :extra-deps {lambdaisland/kaocha {:mvn/version "0.0-413"}
+                          lambdaisland/kaocha-junit-xml {:mvn/version "0.0-70"}}
+             :main-opts ["-m" "kaocha.runner"]}}}