docbridge 0.12.0 → 0.13.1

package/docs/README.md

@@ -63,7 +63,7 @@ with the specification for the interface whose exact contract you need:
 - [Commit messages](contributing/commits.md)
 - [Pull requests](contributing/pull-requests.md)
 - [Releasing](contributing/releasing.md)
-- [Self-audit baseline](contributing/self-audit.md)
+- [Self-audit](contributing/self-audit.md)
 
 ## Historical records
 

package/docs/user/configuration.md

@@ -57,22 +57,23 @@ source file may match only one language.
 
 ## Languages
 
-| Key          | Files                                                | `visibility` values              | Default               | Scanner                   |
-| ------------ | ---------------------------------------------------- | -------------------------------- | --------------------- | ------------------------- |
-| `typescript` | `.ts`, `.tsx`, `.mts`, `.cts`, not declaration files | `public`, `protected`, `private` | `public`, `protected` | built in                  |
-| `javascript` | `.js`, `.jsx`, `.mjs`, `.cjs`                        | `public`, `protected`, `private` | `public`, `protected` | built in                  |
-| `swift`      | `.swift`                                             | `public`, `open`, `internal`     | `public`, `open`      | `docbridge-swift-scanner` |
-| `dart`       | `.dart`                                              | `public`                         | `public`              | `docbridge_dart_scanner`  |
-| `rust`       | `.rs`                                                | `pub`, `private`                 | `pub`                 | `docbridge-rust-scanner`  |
-| `go`         | `.go`                                                | `exported`, `unexported`         | `exported`            | `docbridge-go-scanner`    |
-| `python`     | `.py`                                                | `public`, `private`              | `public`              | CPython 3.10 or later     |
-| `ruby`       | `.rb`                                                | `public`, `protected`, `private` | `public`              | CRuby 3.3 or later        |
+| Key          | Files                                                | `visibility` values                         | Default               | Scanner                   |
+| ------------ | ---------------------------------------------------- | ------------------------------------------- | --------------------- | ------------------------- |
+| `typescript` | `.ts`, `.tsx`, `.mts`, `.cts`, not declaration files | `public`, `protected`, `private`            | `public`, `protected` | built in                  |
+| `javascript` | `.js`, `.jsx`, `.mjs`, `.cjs`                        | `public`, `protected`, `private`            | `public`, `protected` | built in                  |
+| `swift`      | `.swift`                                             | `public`, `open`, `internal`                | `public`, `open`      | `docbridge-swift-scanner` |
+| `dart`       | `.dart`                                              | `public`                                    | `public`              | `docbridge_dart_scanner`  |
+| `rust`       | `.rs`                                                | `pub`, `private`                            | `pub`                 | `docbridge-rust-scanner`  |
+| `go`         | `.go`                                                | `exported`, `unexported`                    | `exported`            | `docbridge-go-scanner`    |
+| `python`     | `.py`                                                | `public`, `private`                         | `public`              | CPython 3.10 or later     |
+| `ruby`       | `.rb`                                                | `public`, `protected`, `private`            | `public`              | CRuby 3.3 or later        |
+| `java`       | `.java`                                              | `public`, `protected`, `package`, `private` | `public`              | JDK 17 or later           |
 
 Patterns must end with one of the language's extensions. The npm package
 bundles the Swift, Dart, Rust, and Go scanners for `darwin-arm64` and
 `linux-x64`; TypeScript, JavaScript, and Markdown need no scanner binary.
-Python and Ruby are scanned by scripts in the package that run on the
-interpreter installed on the machine, on any platform; see
+Python, Ruby, and Java are scanned by workers in the package that run on the
+interpreter or JDK installed on the machine, on any platform; see
 [Scanner runtimes](#scanner-runtimes).
 
 Each language accepts an optional `visibility` array; omitting it uses the
@@ -81,11 +82,12 @@ type members; top-level declarations must be exported, and every JavaScript
 member is `public`. Rust `pub` means unrestricted `pub`, and `private` covers
 every narrower visibility. A declaration excluded by visibility is not an
 endpoint. An `@doc` on an excluded TypeScript or JavaScript member, or on an
-excluded Python or Ruby declaration, is `unsupported_declaration`; the Swift,
+excluded Python, Ruby, or Java declaration, is `unsupported_declaration`; the Swift,
 Dart, Rust, and Go scanners ignore an `@doc` on an excluded declaration
 without a diagnostic. See `docbridge docs show linking` for the per-language
 declaration rules, including Dart's and Python's leading-underscore privacy,
-Go's exported-name rule for methods, and Ruby's `private` calls. The
+Go's exported-name rule for methods, Ruby's `private` calls, and Java's
+implicitly public interface members. The
 [Scanning specification](https://github.com/salan70/docbridge/blob/main/docs/specs/scanning.md)
 owns the exact scanner behavior and platform keys.
 
@@ -93,13 +95,15 @@ owns the exact scanner behavior and platform keys.
 
 ## Scanner runtimes
 
-Python and Ruby files are scanned by scripts that run on an interpreter
-installed on the machine: CPython 3.10 or later, and CRuby 3.3 or later, whose
-bundled Prism parses the source. DocBridge looks for `python3`, then `python`
-(`py -3`, then `python` on Windows), and for `ruby` on `PATH`, and checks each
-candidate before using it. The scripts never import or run project code.
+Python, Ruby, and Java files are scanned by workers that run on a runtime
+installed on the machine: CPython 3.10 or later; CRuby 3.3 or later, whose
+bundled Prism parses the source; and a JDK 17 or later, whose `jdk.compiler`
+module parses the source. A JRE lacks that module and cannot scan Java.
+DocBridge looks for `python3`, then `python` (`py -3`, then `python` on
+Windows), for `ruby`, and for `java` on `PATH`, and checks each candidate
+before using it. The workers never import, compile, or run project code.
 
-To use another interpreter, name it under `scanners`:
+To use another runtime, name it under `scanners`:
 
 ```json
 {
@@ -113,13 +117,15 @@ To use another interpreter, name it under `scanners`:
 }
 ```
 
-`command` is the interpreter followed by its own arguments, as an array rather
-than a shell string; a relative path resolves against the project root.
-Without a configured command, the environment variable
-`DOCBRIDGE_PYTHON_RUNTIME` or `DOCBRIDGE_RUBY_RUNTIME` can name one
-interpreter executable instead. A configured command or variable is the only
-interpreter tried: when it is missing or unusable, the files report
-`code_scanner_unavailable` instead of falling back to `PATH`.
+`command` is the runtime executable followed by its own arguments, as an
+array rather than a shell string; a relative path resolves against the project
+root. A Java entry names the JDK's `java`, such as
+`["/opt/jdk-21/bin/java"]`. Without a configured command, the environment
+variable `DOCBRIDGE_PYTHON_RUNTIME`, `DOCBRIDGE_RUBY_RUNTIME`, or
+`DOCBRIDGE_JAVA_RUNTIME` can name one runtime executable instead. A configured
+command or variable is the only runtime tried: when it is missing or unusable,
+the files report `code_scanner_unavailable` instead of falling back to
+`PATH`.
 
 A configured command runs with your permissions in the CLI and in the editor
 extension. Review `scanners` in a repository you do not trust before running
@@ -148,9 +154,10 @@ documentation should stay outside the graph:
 ```
 
 For Go, `cmd/**/*.go` and `internal/**/*.go` scan fewer files than
-`**/*.go`, but `_test.go` files under them are still scanned. For Python and
-Ruby, keep test directories such as `tests/` and `spec/` outside the patterns
-in the same way.
+`**/*.go`, but `_test.go` files under them are still scanned. For Python,
+Ruby, and Java, keep test directories such as `tests/`, `spec/`, and
+`src/test/` outside the patterns in the same way; in a Maven or Gradle layout,
+`src/main/java/**/*.java` does.
 
 DocBridge always ignores dependency directories, Git metadata, dot-prefixed
 path segments, symbolic links, and TypeScript declaration files (`.d.ts`,

package/docs/user/getting-started.md

@@ -1,5 +1,5 @@
 ---
-description: Set up DocBridge in an existing TypeScript, JavaScript, Swift, Dart, Rust, Go, Python, or Ruby project.
+description: Set up DocBridge in an existing TypeScript, JavaScript, Swift, Dart, Rust, Go, Python, Ruby, or Java project.
 ---
 
 # Getting Started

package/docs/user/linking.md

@@ -106,8 +106,13 @@ def login(email: str, password: str) -> None:
 def login(email, password); end
 ```
 
+```java
+/** @doc docs/auth.md#login-flow */
+public void login(String email, char[] password) {}
+```
+
 Paths are relative to the configured root. An annotation on an unsupported
-declaration, or on a TypeScript, JavaScript, Python, or Ruby declaration
+declaration, or on a TypeScript, JavaScript, Python, Ruby, or Java declaration
 excluded by visibility, produces `unsupported_declaration`; the same
 declaration without an annotation is ignored. Swift, Dart, Rust, and Go ignore
 an annotation on a declaration excluded by visibility without a diagnostic. To link such a declaration, add
@@ -209,6 +214,28 @@ file is one endpoint. Bare `private`, `protected`, and `public` calls,
 modules, and constants are always `public`. `attr_reader` and its siblings,
 `alias`, and `define_method` are not endpoints.
 
+### Java declarations
+
+Supported forms are top-level and nested classes, interfaces, enums, records,
+and annotation types; methods and constructors; and fields and enum
+constants. Put `@doc` in the declaration's Javadoc comment (`/** */`); `//`
+and `/* */` comments are ignored. IDs are dot-qualified without the package,
+and methods and constructors add their parameter types: `AuthService`,
+`AuthService.MAX_ATTEMPTS`, `AuthService.login(String,char[])`, and
+`AuthService.AuthService(Authenticator)` for a constructor. Parameter types
+are written as in the source, without type arguments or annotations, and
+varargs become arrays (`String...` is `String[]`). Visibility defaults to
+`public`. Interface members without a modifier and enum constants are
+`public`, and a member is never more visible than its enclosing types. Local
+and anonymous classes, lambdas, and initializer blocks are not endpoints. An
+`@doc` above a field statement that declares several names (`int a, b;`) is
+`unsupported_declaration` because it cannot name one endpoint; link those
+fields from `docbridge.links.json` instead.
+
+`javadoc` reports `@doc` as an unknown tag when doclint runs with
+`-Xdoclint`. Register the tag with `-tag doc:a:"DocBridge:"` so the check
+accepts it.
+
 <!-- @code src/scan/markdown/markdown.ts#scanMarkdown -->
 
 ## Documentation to code

package/docs/user/troubleshooting.md

@@ -36,15 +36,18 @@ lacks a binary for the current platform or the binary cannot execute.
 Reinstall the package first. If the platform is not supported, run DocBridge
 in a supported environment or build the scanner from the repository.
 
-Python and Ruby run on the interpreter installed on the machine. For them,
-`code_scanner_unavailable` names the interpreter DocBridge needs, the minimum
-version, and what it found for each candidate: no interpreter on `PATH`, a
-version below CPython 3.10 or CRuby 3.3, or a Ruby whose bundled Prism does not
-load. Install a supported version on `PATH`, or point `scanners.python.command`
-or `scanners.ruby.command` in the configuration, or `DOCBRIDGE_PYTHON_RUNTIME`
-or `DOCBRIDGE_RUBY_RUNTIME` in the environment, at one; see
-[Configuration](configuration.md#scanner-runtimes). When the message names
-one of those overrides, DocBridge tried only that interpreter, so fix or remove
+Python, Ruby, and Java run on the runtime installed on the machine. For them,
+`code_scanner_unavailable` names the runtime DocBridge needs, the minimum
+version, and what it found for each candidate: no runtime on `PATH`, a
+version below CPython 3.10, CRuby 3.3, or JDK 17, a Ruby whose bundled Prism
+does not load, or a Java runtime without the `jdk.compiler` module, which is
+what a JRE or a trimmed `jlink` image reports. Install a supported version on
+`PATH`, or point `scanners.<language>.command` in the configuration, or
+`DOCBRIDGE_PYTHON_RUNTIME`, `DOCBRIDGE_RUBY_RUNTIME`, or
+`DOCBRIDGE_JAVA_RUNTIME` in the environment, at one; see
+[Configuration](configuration.md#scanner-runtimes). For Java, that is the
+`java` executable of a full JDK 17 or later, not a JRE. When the message names
+one of those overrides, DocBridge tried only that runtime, so fix or remove
 the override instead of installing another one.
 
 `code_scanner_failed` diagnostics contain the worker failure rather than
@@ -54,9 +57,10 @@ Check that the source parses with the project's own toolchain, then reproduce
 with the smallest configured file set.
 
 `code_parse_error` means a TypeScript, JavaScript, Swift, Dart, Rust, Go,
-Python, or Ruby source file has a syntax error. The diagnostic points at the
-first error the language's parser found and includes the parser's message; for
-Python and Ruby, the wording comes from the installed interpreter. DocBridge extracts no links or symbols
+Python, Ruby, or Java source file has a syntax error. The diagnostic points at
+the first error the language's parser found and includes the parser's message;
+for Python, Ruby, and Java, the wording comes from the installed runtime, and
+Java syntax newer than the installed JDK does not parse. DocBridge extracts no links or symbols
 from that file, so fix the syntax before judging link diagnostics that involve
 it. Unlike
 `code_scanner_failed`, the worker ran correctly; the source itself did not

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docbridge",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "A CLI that links Markdown specifications and code declarations. Runs on Node.js and Bun.",
   "keywords": [
     "bun",

package/schemas/context-output.schema.json

@@ -35,7 +35,17 @@
           },
           "language": {
             "type": "string",
-            "enum": ["typescript", "swift", "dart", "rust", "go", "javascript", "python", "ruby"],
+            "enum": [
+              "typescript",
+              "swift",
+              "dart",
+              "rust",
+              "go",
+              "javascript",
+              "python",
+              "ruby",
+              "java"
+            ],
             "description": "Code language for code context blocks."
           },
           "startLine": {

package/schemas/docbridge.schema.json

@@ -25,7 +25,8 @@
             "go": { "$ref": "#/$defs/goEntry" },
             "javascript": { "$ref": "#/$defs/javascriptEntry" },
             "python": { "$ref": "#/$defs/pythonEntry" },
-            "ruby": { "$ref": "#/$defs/rubyEntry" }
+            "ruby": { "$ref": "#/$defs/rubyEntry" },
+            "java": { "$ref": "#/$defs/javaEntry" }
           }
         },
         "docs": {
@@ -239,6 +240,28 @@
           }
         }
       }
+    },
+    "javaEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["patterns"],
+      "properties": {
+        "patterns": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "pattern": "\\.java$"
+          }
+        },
+        "visibility": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["public", "protected", "package", "private"]
+          }
+        }
+      }
     }
   }
 }

package/schemas/graph-output.schema.json

@@ -31,7 +31,17 @@
           },
           "language": {
             "type": "string",
-            "enum": ["typescript", "swift", "dart", "rust", "go", "javascript", "python", "ruby"],
+            "enum": [
+              "typescript",
+              "swift",
+              "dart",
+              "rust",
+              "go",
+              "javascript",
+              "python",
+              "ruby",
+              "java"
+            ],
             "description": "Code language for code nodes."
           },
           "location": { "$ref": "common-output.schema.json#/$defs/location" },