Maintainer workflows

Question answered by this guide: how should maintainers build, validate and publish generated developer-facing assets without confusing source and generated files?

This guide documents repository-level workflows around builds, generated API documentation, examples, AI context and coverage.

Documentation architecture

Path Role Rule
README.md public landing page short, attractive, links to specialized guides
guide/ hand-written developer guides canonical human source of truth
ai/ AI-specific context/rules thin layer; link to guide/ and examples/, do not duplicate them
examples/ product examples executable evidence; safe read-only examples first
architecture/ reference architecture and decisions update only for durable decisions, not routine notes
docs/ generated TypeDoc site regenerated by make docs; do not edit by hand
lib/, dist/ generated build outputs produced by build targets; do not edit by hand
coverage/ generated coverage report local/CI output; do not edit by hand

make docs removes docs/ and regenerates it from TypeScript sources plus the Markdown files in guide/ through TypeDoc projectDocuments.

Documentation entropy rules

Treat documentation as production code with explicit ownership for facts.

Fact class Canonical source Documentation rule Validation
Package version / current release package.json, npm registry, CHANGELOG.md for history Do not repeat the current version in evergreen guides, README, AI files or SECURITY.md. npm run docs:check rejects source-doc literals such as @beblurt/dblurt@<current-version>.
Node/runtime target package.json engines.node Summarize and link to runtime compatibility; do not scatter independent matrices. runtime-compatibility.md must point to package metadata fields.
Browser target package.json browser and browserslist; generated dist/ Do not copy browser version lists; use Browserslist to resolve exact targets. docs:check verifies the runtime guide references browserslist.
TypeScript declaration contract package.json types/typings, generated declarations, package tests Do not document a one-off smoke-test compiler version as a public compatibility minimum. docs:check rejects “TypeScript x.y.z used by project” wording.
API signatures TypeScript source and generated TypeDoc Guides may explain routing; exact signatures belong to TypeDoc/source. TypeDoc generation and tests.
Examples files under examples/ plus their metadata comments Guide pages should link to the canonical catalog instead of duplicating every row. docs:check verifies every example file is listed in examples/README.md.
Security model architecture/SECURITY_ARCHITECTURE.md, SECURITY.md, source/tests for implementation behavior Keep evergreen guidance stable; put release-specific audit output in reports, not guides. docs links + regular tests/audit commands.

When a factual claim cannot be tied to one of these sources, label it as inferred/unverified or remove it.

TypeDoc integration

The project currently uses TypeDoc with:

entryPoints: src/index.ts
projectDocuments: guide/*.md
out: docs

Current TypeDoc role:

  • generate the API reference site;
  • include human guide pages inside the generated site;
  • keep editorial Markdown outside the generated output.

Current rule:

TypeDoc output is generated. `docs/` is not a source documentation directory.

TypeDoc evolution notes

Do not migrate away from TypeDoc in routine documentation work.

Future TypeDoc outputs worth evaluating, in order:

  1. JSON reflection output for API metadata and documentation validation.
  2. API symbol index generated from TypeDoc JSON.
  3. Markdown API output for future site/AI ingestion.
  4. Generated llms.txt / SKILL.md only after TypeDoc/plugin compatibility is proven.

Potential future generated inputs for AI:

Output Future use
TypeDoc JSON API metadata, symbol lookup, API coverage, generated summaries
TypeDoc Markdown llms-full.txt, docs site pages, AI retrieval
API symbol index hallucination prevention and quick lookup
Documentation coverage report missing public API docs/examples

Current caution:

Some modern TypeDoc AI plugins require newer TypeDoc versions than the project currently uses. Evaluate plugin peer dependencies before adding them.

TypeDoc warning remediation plan

Current warning classes observed during the documentation quality pass:

Class Status Remediation
Legacy tags (@file, @description, @brief, @ingroup, @note) mostly remediated where reported by TypeDoc Replace with normal prose when files are touched. Do not add TypeDoc suppressions.
Incorrect @param names mostly remediated where reported by TypeDoc Keep parameter names exactly aligned with function signatures. For object parameters, document the object parameter and its exported interface fields.
Broken {@link ...} targets mostly remediated where reported by TypeDoc Prefer plain text or a valid exported symbol. Do not link to private implementation details.
Referenced public property type not included open Client.broadcast references BroadcastAPI, and experimental/core options reference internal core adapter shapes. Fix only after deciding whether exporting those symbols is a public API change.

Current policy:

  • report TypeDoc warnings in every documentation quality pass;
  • fix factual JSDoc issues when safe;
  • do not silence warnings;
  • do not expand public API just to satisfy TypeDoc without maintainer approval.

Publication strategy

Do not publish documentation manually from a local checkout.

Recommended future publication flow:

source docs + examples + TypeDoc config
        |
        v
validation jobs
        |
        v
generated API docs / AI indexes / site output
        |
        v
GitLab Pages public artifact

Near-term publication should keep raw TypeDoc output viable. A later GitLab Pages job can publish docs/ or a public/ artifact without changing the source documentation model.

Future GitLab Pages candidates:

Output Publish when
TypeDoc HTML after docs validation exists
llms.txt after canonical URLs are stable
llms-core.txt / llms-full.txt after generated assembly exists
TypeDoc Markdown/site output after site framework decision, if any
coverage reports only if maintainers want public coverage visibility

Documentation validation workflow

The validation workflow is intentionally staged. It does not need to be fully implemented before every documentation change, but future CI should move toward it.

For local development, the consolidated entry point is:

npm run docs:check

It validates Markdown links, fenced-code balance, AI-layer hygiene, example metadata, read-only Node examples, TypeScript example compilation, and TypeDoc generation to /tmp without modifying docs/.

If public RPC endpoints are unavailable, skip live examples while keeping static checks active:

DBLURT_DOCS_CHECK_SKIP_LIVE_EXAMPLES=1 npm run docs:check

Stage 1: Markdown structure

Validate:

  • files exist for relative Markdown links;
  • code fences are balanced;
  • generated directories are not hand-edited in documentation PRs;
  • forbidden project claims do not appear.

Examples of forbidden or risky claims:

  • calling dblurt the official Blurt SDK without proof;
  • claiming unsupported runtimes;
  • presenting Nexus Layer 2 data as Layer 1 consensus truth.

Stage 2: Executable examples

Validate safe examples first:

node examples/node/read-head-block.cjs
node examples/node/read-block-operations.cjs
node examples/node/read-account.cjs
node examples/node/read-post.cjs
node examples/node/read-active-votes.cjs
node examples/node/read-witness.cjs
node examples/node/read-account-history.cjs
node examples/node/stream-block-numbers.cjs
node examples/node/read-nexus-ranked-posts.cjs
node examples/node/read-nexus-community.cjs
node examples/node/generic-call.cjs

Rules:

  • read-only examples may run against public RPC endpoints;
  • examples requiring keys must not run by default;
  • broadcast examples must remain opt-in and safety-reviewed.

Stage 3: TypeScript examples

Compile TypeScript examples without emitting output:

npx tsc --noEmit --target ES2020 --module commonjs --moduleResolution node examples/typescript/read-account.ts

A future validation script should centralize this command and avoid relying on ad-hoc shell invocations.

Stage 4: TypeDoc and generated docs

Validate:

npm run docs

Expected behavior:

  • docs/ is regenerated;
  • no hand edits are made inside docs/;
  • TypeDoc warnings are reported, not ignored.

Future improvement:

  • establish a TypeDoc warning baseline;
  • fail CI only on new warnings after the baseline is known.

Stage 5: AI documentation consistency

Validate:

  • ai/ links to guide/ and examples/ instead of duplicating them;
  • AI files do not contain stale copied guide sections;
  • AI rules match package metadata and runtime compatibility docs;
  • future llms.txt links point to canonical public URLs.

Stage 6: Documentation freshness

Future freshness checks should detect:

  • guide examples that no longer match examples/ files;
  • API guide entries for methods that no longer exist;
  • examples that use removed exports;
  • TypeDoc output not regenerated after public API changes;
  • AI context not updated after runtime/package changes.

Make targets

Target Status Purpose
make all active build library, browser bundle and generated docs
make lib active compile TypeScript into lib/ and generate lib/version.js
make bundle active generate dist/dblurt.js, dist/dblurt.js.gz and dist/dblurt.d.ts
make docs active regenerate the TypeDoc site under docs/
make docs-check active validate source docs, AI context, examples and TypeDoc warning baseline without writing generated docs
make test active local Mocha test runner, supports grep=...
make ci-test active lint plus c8 LCOV test run used by npm test
make lint active ESLint over src/**/*.ts
make typecheck active tsc --noEmit validation
make coverage active HTML/text/LCOV coverage report for local inspection
make clean active remove generated lib/, dist/*, docs/ and coverage/
make distclean active clean plus node_modules/ removal

Historical browser test targets existed in the initial Makefile but depended on Karma/Sauce tooling that is no longer present in current package.json. They should not be restored without adding and validating a modern browser test stack.

Coverage

make coverage uses c8 rather than the historical nyc stack.

It generates:

  • terminal text coverage;
  • HTML coverage under coverage/;
  • LCOV coverage under coverage/lcov.info.

The target excludes test/** and scripts/** so the report focuses on library code. The CI-oriented make ci-test still generates LCOV output with TAP test reporting.

Release command

npm run release currently delegates to commit-and-tag-version. It can create local release commits and tags.

Do not run it during documentation, DX, validation or audit work unless release side effects are explicitly authorized.

Settings

Member Visibility

On This Page

Maintainer workflows