Synolib2

.devcontainer/Dockerfile

@@ -1,3 +1,3 @@
-FROM denoland/deno:bin-1.41.3 AS deno
+FROM denoland/deno:bin-1.45.5 AS deno
 FROM mcr.microsoft.com/devcontainers/typescript-node:20
 COPY --from=deno /deno /usr/local/bin/deno

.devcontainer/devcontainer.json

@@ -1,27 +1,26 @@
 {
-	"name": "Deno",
-	"build": {
-		"dockerfile": "Dockerfile"
-	},
+  "name": "Deno",
+  "build": {
+    "dockerfile": "Dockerfile"
+  },
 
-	// Features to add to the dev container. More info: https://containers.dev/features.
-	// "features": {},
+  // Features to add to the dev container. More info: https://containers.dev/features.
+  // "features": {},
 
-	// Use 'forwardPorts' to make a list of ports inside the container available locally.
-	// "forwardPorts": [],
+  // Use 'forwardPorts' to make a list of ports inside the container available locally.
+  // "forwardPorts": [],
 
-	// Use 'postCreateCommand' to run commands after the container is created.
-	// "postCreateCommand": "yarn install",
+  // Use 'postCreateCommand' to run commands after the container is created.
+  // "postCreateCommand": "yarn install",
 
-	// Configure tool-specific properties.
-	"customizations": {
-		"vscode": {
-			"extensions": [
-				"justjavac.vscode-deno-extensionpack"
-			]
-		}
-	}
-
-	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
-	// "remoteUser": "root"
-}
+  // Configure tool-specific properties.
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "justjavac.vscode-deno-extensionpack"
+      ]
+    }
+  }
+  // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
+  // "remoteUser": "root"
+}

.github/workflows/pages.yml

@@ -3,8 +3,8 @@ name: GitHub Pages
 on:
   push:
     branches:
-      - main      # Set a branch to deploy
-      - synolib2  # publish on change in either branch
+      - main # Set a branch to deploy
+      - synolib2 # publish on change in either branch
 permissions:
   contents: write
 
@@ -14,41 +14,19 @@ jobs:
     runs-on: ubuntu-22.04
 
     steps:
-
-      # main / old:
-      - name: 'Checkout main branch'
-        uses: actions/checkout@v3
-        with:
-          ref: main
-      - name: Setup Deno
-        uses: denoland/setup-deno@v1
-        with:
-          deno-version: v1.x
-      - name: prepare
-        run: |
-          mkdir build
-          cp index.html build/
-      - run: deno bundle SynonymGroup.ts build/synonym-group.js
-      - run: cp SynonymGroup.ts build/
-
-      # synolib2 / new:
-      - name: 'Checkout synolib2 branch'
+      - name: "Checkout synolib2 branch"
         uses: actions/checkout@v3
         with:
           ref: synolib2
-          path: 'synolib2'
-      - name: Use Node.js
-        uses: actions/setup-node@v4
+      - name: Setup Deno
+        uses: denoland/setup-deno@v2
         with:
-          node-version: '20.x'
+          deno-version: v2.x
       - name: Draw the rest of the owl
         run: |
-          cd synolib2
-          npm ci
-          npm run example build
-          mkdir ../build/next
-          cp ./example/index.* ../build/next/
-          cd ..
+          deno task example_build
+          mkdir ./build
+          cp ./example/index.* ./build/
 
       - name: Deploy to GitHub Pages
         uses: JamesIves/[email protected]

.github/workflows/publish.yml

@@ -0,0 +1,18 @@
+name: Publish
+
+on:
+  push:
+    branches:
+      - synolib2
+
+# runs on every push, does not publish unless deno.jsonc version number was updated
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write # The OIDC ID token is used for authentication with JSR.
+    steps:
+      - uses: actions/checkout@v4
+      - run: npx jsr publish

.gitignore

@@ -1,5 +1,5 @@
-synonym-group.js
-
-npm-package/node_modules
-npm-package/index.js
-npm-package/index.d.ts
+docs/
+build/
+example/index.js
+example/index.js.map
+node_modules/

.vscode/launch.json

@@ -46,6 +46,5 @@
       ],
       "attachSimplePort": 9229
     }
-
   ]
 }

DESIGN.md

@@ -0,0 +1,57 @@
+# Design
+
+<!-- deno-fmt-ignore -->
+> [!NOTE]
+> This currently (2024-07-27) describes a potential future design, not
+> the current one.
+
+## Overview
+
+The central taxonomic entity is one object `N` per latin name.\
+Synolib returns as results a list of `N`s.
+
+Each `N` exists because of a taxon-name, taxon-concept or col-taxon in the
+data.\
+Each `N` is uniquely determined by its human-readable latin name (for taxa
+ranking below genus, this is a multi-part name — binomial or trinomial) and
+kingdom.\
+Each `N` contains `N+A` objects which represent latin names with an authority.\
+Each `N` contains, if present, `treatment`s directly associated with the
+respective taxon-name.\
+Other metadata (if present) of a `N` are the list of its parent names (family,
+order, ...); vernacular names; and taxon-name URI.
+
+Each `N+A` exists because of a taxon-concept or col-taxon in the data. It always
+has a parent `N`.\
+Each `N+A` is uniquely determined by its human-readable latin name (as above),
+kingdom and (normalized [^1]) authority.\
+Each `N+A` contains, if present, `treatment`s directly associated with the
+respective taxon-concept.\
+Other metadata (if present) of a `N` are CoL IDs; and taxon-concept URI.
+
+A `treatment` exists because it is in the data, and is identifed by its RDF
+URI.\
+A `treatment` may _define_, _augment_, _deprecate_ or _cite_ a `N+A`, and
+_treat_ or _cite_ a `N`.\
+If a `treatment` does _define_, _augment_, _deprecate_ or _treat_ different `N`
+and/or `N+A`s, they are considered synonyms.\
+Note that _cite_ does not create synonmic links.\
+Other metadata of a `treatment` are its authors, material citations, and images.
+
+Starting point of the algorithm is a latin name or the URI of either a
+taxon-name, tacon-conecpt or col-taxon.\
+It will first try to find the respective `N` and all associated metadata, `N+A`s
+and `treatment`s.\
+This `N` is the first result.\
+Then it will recursively use all synonyms indicated by the found `treatment`s to
+find new `N`s.\
+For each new `N`, it will find all associated metadata, `N+A`s and `treatment`s;
+and return it as the next result.\
+Then it will continue to expand recursively until no more new `N`s are found.
+
+The algorithm keeps track of which treatment links it followed and other reasons
+it added a `N` to the results.\
+This "justification" is also proved as metadata of a `N`.
+
+[^1]: I.e. ignoring differences in punctuation, diacritics, capitalization and
+    such.