Ddot.it Java Core

Table of Contents

• What is in here
• Warnings
• Dependencies
• Known Consumers
• Where the specification lives
• Building
• Releasing

This repo encodes the main types directly or implicitly defined in the https://ddot.it spec in Java.

What is in here

Package dependencies

Derived from the import statements under src/main/java; javadoc-only imports (the ones in package-info.java that exist so {@link} resolves) are excluded. An arrow points from a package to one it uses. core is the root package it.ddot.core itself, holding DdotSlot, DdotVocabulary and DdotSourceFormats.

Package Dependencies

@startuml
skinparam packageStyle rectangle
skinparam shadowing false
hide empty members
hide circles

class core
class token
class event
class source
class ioHandler as "io.handler"
class io
class hostreader
class html
class lint
class embed
class cds
class store
class annotation

token --u> core
core --u> source
event --u> core
event --u> source
html --u> token
io --u> core
io --u> event
io --u> source
io --u> token
lint --u> token
lint --u> embed
lint --u> cds
lint --u> store
lint --u> event
embed --u> token
embed --u> io
embed --u> event
embed --u> source
cds --u> store
ioHandler --u> core
ioHandler --u> event
ioHandler --u> io
ioHandler --u> source
ioHandler --u> token
hostreader --u> core
hostreader --u> io
hostreader --u> source
hostreader --u> ioHandler

@enduml

Layers

• API Layers

  • source, store, annotation

  • core

  • event, token

• Impl Layers

  • html, io, embed

  • cds

  • lint

  • io.handler

  • hostreader

API Packages

• it.ddot.core.annotation — the @DdotIt marker. Only used when annotating Java source code directly with ddot.it text.

• it.ddot.core.event — evens fired when parsing

• it.ddot.core.source — the snippet and source-location model, the resource-address abstractions a host application implements to feed ddot.it text in

• it.ddot.core.store — the fact and triple-store interfaces (TripleStore, IFact, IDerivation, ILineRange) a reasoner such as cds runs over; no dependencies.

• it.ddot.core.token — the tokenizer and its role model, the grammar itself, and the !!command vocabulary.

• it.ddot.core — Constants

Impl Packages

• it.ddot.core.hostreader — Readers for parsing different source syntax such as AsciiDoc, Markdown, HTML, XML, and YAML. These readers emit the structure within the document as synthetic ddot.it events plus the explicitly user-written ddot.it syntax.

• it.ddot.core.html — helper code for rendering syntax-highlighted ddot.it syntax as HTML.

• it.ddot.core.io — the main Parser and Writer

• it.ddot.core.embed — where a host file’s ddot.it is: the ddot blocks of Markdown and AsciiDoc, the triples in them with their host lines, and where each entity name occurs.

• it.ddot.core.cds — the CDS inference engine: the vocabulary and rules of CDS & Standards Alignment, CdsEngine, the reference engines CdsInferenceEngine and CdsFixpointOracle, and the query layer (CdsQuery, CdsQueryEngine). It runs over the triple-store interfaces in it.ddot.core.store. Design: doc/cds-inf.adoc, history and measurements: doc/cds-inf-perf.adoc.

• it.ddot.core.lint — the linter with its diagnostics, severities and line changes; and DdotAnalysis, the warnings a project gets wherever they are shown (see Warnings).

Warnings

DdotAnalysis owns the warnings about ddot.it: the IntelliJ plugin only marks them in the editor, and ddot lint (in ddot.it-java-ext) only prints them, so both show the same ones on the same lines.

Rule	Scope	What
DL010–DL012	file	The linter’s report-only diagnostics: lines that look like triples but are dropped.
DL017	file	A triple line with no object: s ..p...
DL020	project	A cardinality bound violated, with what the project entails under CDS: values stated through aliases, sub-relations and inverses count, instances of a subtype of the domain are instances of the domain.
DL021	project	A cardinality that is no whole number.
DL022	project	A name also spelled in another letter case.
DL023	project	A relation under both links to and is linked from: it has no direction, so one statement placing it is probably the wrong way round.
DL024	project	A name the project says is replaced by another (a ..is replaced by.. has type), on every place it is used: replacing is an editor instruction, not a second name, so a reasoner does not read a as has type.

The project-wide rules read every file’s triples, as LocatedTriple lists per file — the plugin keeps them in its index, ddot lint extracts them from the files it crawls.

Dependencies

A consumer of it.ddot:ddotit-core gets one more artifact: org.jspecify:jspecify, which is annotations only. The Maven Enforcer rule in pom.xml fails the build if anything else reaches the compile or runtime classpath. Test-scope dependencies (JUnit, Truth, Jackson for the corpus test) never reach a consumer.

The knowledge model — Kbase, Kgraph, Knode, Kedge, and the handlers that turn triple events into a Kgraph — is built on graphinout’s JSON document types, so it lives in its own artifact, it.ddot:ddotit-kbase (ddot.it-java-kbase), which depends on this one. Its packages keep their names (it.ddot.core.kbase.*); the Kgraph handlers moved from it.ddot.core.io.handler to it.ddot.core.kbase.io.

The AsciiDoc reader still finds document and section nodes (see hostreader.asciidoc.Adoc2Kg), but hands them only to a source handler that implements Adoc2Kg.IHandler; ddotit-kbase’s `IKgraphSourceHandler does, and creates them in its Kgraph.

Known Consumers

• graphinout reader-ddot — the reason this artifact stands alone.

• ddot.it-java-ext — the not-yet-released command-line tool. Also uses ddotit-kbase.

• ddot.it-intellij — the official ddot.it IntelliJ plugin. Also uses ddotit-kbase.

• adir — runs the CDS engine over its knowledge graph.

Where the specification lives

This repository is an implementation, not a specification.

The canonical ddot.it syntax reference, the language documentation and the conformance corpus live in the sibling repository ddot.it, checked out next to this one as ../ddot.it. Its test-data/cases directory is the corpus that the ddot.it-javalib DdotCorpusConformanceTest runs against; that test is the harness that decides whether an implementation conforms, and it lives with the graph layer because parsing a case end to end needs it.

Building

Commands

• mvn install — compiles, runs the tests and installs it.ddot:ddotit-core into the local repository, with its tests as ddotit-core:tests (adir runs the CDS contracts on its own graphs with them).

Java 25 or newer is required.

Releasing

Releases go to Maven Central under the namespace it.ddot, so consumers need no extra <repository>. The process is the one in graphinout’s how-to-release.adoc, with the same local profile central-deploy and Central Portal credentials in ~/.m2/settings.xml. Every build already makes the sources and javadoc jars Central requires; the sign-for-sonar profile adds the GPG signatures.

Steps

1. Check that the working tree is clean and mvn test passes.

2. Run mvn release:prepare -DpushChanges=false -P central-deploy,sign-for-sonar. It commits the release version, tags it v<version> (for example v0.3.1) and commits the next snapshot.

3. Run mvn release:perform -DlocalCheckout=true -DdeployAtEnd=true -P central-deploy,sign-for-sonar. It builds the tag, signs it and uploads it to the Central Portal.

4. Push the commits and the tag.

5. Open https://central.sonatype.com/publishing/deployments, check the deployment and press Publish. A release on Central can never be changed or deleted.

ddot.it-java-kbase releases the same way.