PasWeave v0.4.0

PasWeave v0.4.0

PasWeave v0.4.0 turns generated documentation into authoring feedback that can
be used in CI. It validates structured directives against parsed signatures,
keeps project-local reference links honest, and emits stable coded diagnostics
from the shared documentation model.

Highlights:

• stable warning and error codes, including parameter, return, reference,
  generated-route, and coverage diagnostics;
• parsed-signature validation for missing, duplicate, and unknown @param
  entries plus invalid or conflicting @returns directives;
• conservative model-level @see resolution across the current unit and its
  documented interface dependencies, with unresolved targets left unlinked;
• generated-anchor and unit-route integrity checks before output;
• a deterministic diagnostics.json artifact alongside api-model.json;
• --min-documentation-coverage and --fail-on=warning CI controls while
  retaining error-only failure by default; and
• regression fixtures for ///, { ... }, and (* ... *) comment forms.

See authoring feedback and reference integrity
for the diagnostic contract and CI examples.

Validation includes the complete fixture suite, CLI checks for default and CI
failure policies, and a 45-unit mathlib-fp audit that generated 2,338
symbols with zero errors. Its 2,676 missing-parameter warnings demonstrate
why warning-level failure remains an explicit CI choice.

PasWeave v0.3.0

PasWeave v0.3.0

PasWeave v0.3.0 adds direct Lazarus project and package inputs. Common
multi-package builds can now be documented from their committed .lpi/.lpk
configuration without duplicating source paths, defines, include paths, or
target selection on the command line.

Highlights:

• reads .lpi projects and .lpk packages without starting Lazarus;
• selects named/default Lazarus build modes and imports target settings,
  search paths, defines, and Pascal source units;
• resolves referenced local packages transitively with deterministic ordering;
• gives explicit CLI compiler options precedence over project/package values;
• rejects missing, ambiguous, malformed, macro-unsupported, and cyclic package
  configuration before a partial build can be produced;
• prunes generated, vendor, example, and test trees during automatic package
  discovery, with repeatable --package-path opt-in roots; and
• preserves direct file/directory inputs and the existing renderer/model
  contracts.

See the Lazarus project and package guide for the
supported XML subset, precedence rules, diagnostics, and limitations.

Validation includes the complete FPC 3.2.2 fixture suite, a checked-in
three-unit/two-package Lazarus project fixture, the installed Lazarus
charactermap_demo.lpi project with its local package graph, CLI generation
of JSON/Markdown/HTML, and direct-input compatibility tests.

PasWeave v0.2.0

PasWeave v0.2.0

PasWeave v0.2.0 makes interface parsing compiler-aware. Maintainers can now
describe the unit paths, include paths, conditional defines, target operating
system, and target CPU that select the public API seen by their Free Pascal
build.

Highlights

• Repeat --unit-path, --include-path, and --define as needed.
• Select a normalized target with --target-os and --target-cpu instead of
  inheriting an accidental documentation-host target.
• Resolve project source units transitively in deterministic path order.
• Resolve nested include files and, when include paths are configured, retain
  include-backed source locations and documentation comments.
• Receive early input errors for invalid compiler settings and source-aware
  diagnostics when an include is missing or unreadable.
• Keep existing JSON, Markdown, HTML, and offline assets byte-for-byte
  unchanged when no compiler settings are supplied.

Example:

pasweave build src --recursive \
  --unit-path=packages/core/src \
  --include-path=include \
  --define=USE_FAST_MATH \
  --target-os=linux \
  --target-cpu=aarch64

See compiler-aware parsing for supported
targets, aliases, path rules, precedence, diagnostics, and limitations.

Precedence

• The documentation host supplies OS/CPU defaults only when explicit targets
  are absent.
• Repeated target options use the last value.
• Repeated defines are combined and normalized to uppercase.
• Unit and include paths retain command-line order; the first matching path
  wins.
• Main input units win over matching unit-path sources.

Compatibility

The model schema remains version 1. Direct file input, directory discovery,
and /// documentation remain the defaults. Lazarus .lpi and .lpk files
are not interpreted in this release; their compiler values must be supplied
manually.

Explicit targets are used for conditional interface selection, not code
generation. PasWeave validates OS and CPU values independently and does not
claim every possible pair is a supported FPC backend combination. Unit paths
resolve .pas and .pp source files, not compiled .ppu files.

Validation

• The complete automated suite passes on FPC 3.2.2, including every existing
  checked-in Markdown and HTML golden output.
• A before/after compatibility audit matched all 77 generated documented-api
  files by SHA-256 when no compiler settings were supplied.
• The configured mathlib-fp audit parsed all 45 units into 2,338 symbols with
  zero warnings or errors. All 163 generated files matched the unconfigured
  baseline byte-for-byte.

PasWeave v0.1.0-alpha.1

PasWeave v0.1.0-alpha.1

PasWeave's first public alpha turns Free Pascal interface declarations and
their documentation comments into a searchable, equation-capable static API
site. It also emits deterministic Markdown and a reusable JSON model.

This is an early release intended for evaluation and feedback. The output is
already useful, but project configuration and parts of the semantic model will
continue to evolve before a stable release.

Download

Download these two files from the release assets:

• pasweave.exe
• pasweave.exe.sha256

The executable is a portable Windows x86-64 application: there is no installer
or ZIP package, and Free Pascal is not required at runtime. Place it anywhere
and run:

.\pasweave.exe --version
.\pasweave.exe build path\to\project --output docs

The HTML site is self-contained for offline use. PasWeave extracts its embedded
KaTeX and Mermaid resources into the generated site's asset directory.

Verify the download before running it:

Get-FileHash .\pasweave.exe -Algorithm SHA256
Get-Content .\pasweave.exe.sha256

The values must match. This alpha is not code-signed, so Windows may display a
SmartScreen warning.

Highlights

• Builds its source model with Free Pascal's reusable fcl-passrc parser
  libraries rather than guessing from declaration text.
• Generates deterministic JSON schema version 1, Markdown, and responsive
  static HTML.
• Provides offline symbol search, documentation coverage counts, stable links,
  structured directives, source positions, and light and dark colour schemes.
• Renders marked inline and display mathematics with offline KaTeX.
• Produces linked Mermaid diagrams from resolved unit dependencies,
  inheritance, and interface implementation relationships.
• Gives every diagram accessible zoom, pan, and reset controls plus a readable
  non-interactive text fallback.
• Supports single files, top-level directories, and opt-in recursive discovery
  with repeatable include and exclude globs.
• Isolates parse failures by file and returns meaningful process exit codes.

Documentation comments

The safe default recognizes consecutive /// lines. This is an explicit
PasWeave convention: Free Pascal sees them as ordinary line comments, and
ordinary // comments are not documentation.

Pascal block comments can be enabled per project:

.\pasweave.exe build src --output docs --doc-comments=brace
.\pasweave.exe build src --output docs --doc-comments=paren
.\pasweave.exe build src --output docs --doc-comments=all

Enabled adjacent forms can be mixed in source order. Documentation must
immediately precede an interface declaration; a blank line ends the
association. Compiler directives such as {$mode objfpc} and (*$...*) are
never documentation.

Structured @param, @returns, @raises, @deprecated, @see, and @since
directives are extracted from documentation groups.

Compatibility

Area	This release
Portable binary	Windows x86-64; self-contained and unsigned
Source builds	Free Pascal 3.2.2+ with fcl-passrc and fcl-json
Primary Pascal mode	{$mode objfpc}
Delphi syntax	Accepted only where FPC's parser handles it naturally
JSON model	Schema version 1
Generated site	Static and offline; JavaScript enhances search, mathematics, and diagrams

Validation

The full test suite and an isolated portable-executable smoke test run before
the release workflow publishes any binary.

Against the recorded mathlib-fp revision, PasWeave parsed all 45 units into
2,338 model symbols with no parse errors, missing source positions, or
duplicate stable IDs. It rendered 2,227 API symbols and resolved 97
project-local dependency edges. Because that project contains no PasWeave
/// comments, default documentation coverage is correctly 0 of 2,227;
enabling brace comments finds 570 documented API symbols, with the documented
section-label false-positive caveat described in the validation report.

The equation-rich scientific showcase documents all 30 public API symbols and
contains 16 display equations and 65 inline mathematical expressions. The
portable smoke test also verifies all 67 extracted third-party assets
byte-for-byte.

See the complete mathlib-fp validation report
and the checked-in scientific API showcase.

Known alpha limitations

• The Windows executable is not code-signed.
• Compiler-aware project and package configuration is not implemented yet.
• Source-backed comment association currently operates on the main unit file;
  declarations originating from include files do not yet receive it.
• Type relationship resolution is intentionally scoped and may leave standard
  library or otherwise out-of-scope ancestors unresolved.
• Opting ordinary block comments into documentation can capture section labels;
  review coverage findings when enabling brace or paren on an existing
  codebase.
• Markdown and mathematical rendering deliberately support a focused,
  documented subset.

See the README limitations and
roadmap for the current boundaries and next milestones.

License and attribution

PasWeave is released under the MIT License. Embedded KaTeX and
Mermaid components retain their own license notices in
THIRD_PARTY_NOTICES.md.

Questions, bugs, and real-world compatibility reports are welcome in
GitHub Issues.