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.
| 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 blockchain query 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.
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.
The project currently uses TypeDoc with:
entryPoints: src/index.ts
projectDocuments: guide/*.md
out: docs
Current TypeDoc role:
Current rule:
TypeDoc output is generated. `docs/` is not a source documentation directory.
Do not migrate away from TypeDoc in routine documentation work.
Future TypeDoc outputs worth evaluating, in order:
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.
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:
The build has one TypeScript compilation path. make lib runs tsc and emits CommonJS-compatible JavaScript under lib/ plus lib/version.js. The TypeScript configuration uses Node-style module semantics so native dynamic import() is preserved where runtime lazy loading is required.
The browser bundle is generated from the compiled browser entrypoint:
src/ -> tsc -> lib/index-browser.js -> browserify -> dist/dblurt.js
Do not reintroduce a second TypeScript compiler path for the browser bundle unless there is a concrete compatibility reason. The browser bundle should stay reproducible from lib/, and npm run csp:check should continue to prove that generated runtime artifacts do not contain unsafe-eval constructs such as eval() or new Function().
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
npm run docs:site:build and npm run docs:public:build both regenerate AI retrieval surfaces before building the VitePress site. VitePress copies static files from site/public/ to the output root, and the VitePress build hook copies generated root publication assets such as llms.txt and llms-full.txt into the same output directory. Deployment should not require a manual post-build copy step for root publication assets.
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 |
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 documentation-only work, the consolidated entry point is:
npm run docs:check
It validates Markdown links, fenced-code balance, AI-layer hygiene, example metadata, blockchain query Node examples, TypeScript example compilation, and TypeDoc generation to /tmp without modifying docs/.
For release-oriented maintenance work, use:
npm run release:check
That command runs typecheck, lint, tests, build, CI-safe documentation checks, AI documentation freshness, CSP runtime scanning and npm package tarball validation.
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
Validate:
Examples of forbidden or risky claims:
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:
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.
Validate:
npm run docs
Expected behavior:
docs/ is regenerated;docs/;Future improvement:
Validate:
ai/ links to guide/ and examples/ instead of duplicating them;llms.txt links point to canonical public URLs.Validate generated runtime and package surfaces after build or packaging changes:
npm run csp:check
npm run package:check
csp:check scans generated runtime JavaScript under lib/ and dist/dblurt.js for constructs that require unsafe-eval. package:check packs the npm payload, verifies required files and installs the tarball into a temporary CommonJS consumer smoke test.
Future freshness checks should detect:
examples/ files;| 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.
make coverage uses c8 rather than the historical nyc stack.
It generates:
coverage/;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.
npm run release:check is the side-effect-free release preflight. Run it before proposing a package release or merging release-sensitive build/package changes.
npm run release 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.