read-engineering-docs

● STABLE v2.4.1 Updated: 2025-06-12 Author: .git Core Engineering

1. Introduction & Scope

read-engineering-docs is the internal documentation subsystem used by .git to parse, validate, and render engineering specifications, API contracts, and deployment runbooks. It is designed for high-throughput CI/CD pipelines and supports markdown, OpenAPI 3.0, and custom YAML schema definitions.

Target Audience Platform engineers, DevOps practitioners, and integration developers responsible for maintaining deployment manifests and service meshes.

The module operates as a standalone binary or as a library (@git/engine-docs) and enforces strict schema validation before any artifact reaches production staging.

2. Core Architecture

The pipeline follows a four-stage immutable processing model:

Stage	Component	Responsibility	Failure Mode
Ingest	`parser-core`	AST generation & syntax validation	Reject malformed nodes
Normalize	`schema-align`	Type coercion & cross-reference resolution	Schema drift warning
Enrich	`metadata-injector`	Attach version tags, owner mappings, SLOs	Fallback to defaults
Render	`output-engine`	Generate static HTML, JSON, or gRPC payloads	Graceful degradation

All stages are idempotent. Intermediate states are cached in the local ~/.git/cache/docs/ directory with automatic TTL eviction (default: 24h).

3. CLI Reference

The command-line interface exposes three primary subcommands:

`.git docs parse`

Validates and parses documentation sources. Exits with code 0 on success, 1 on fatal errors, 2 on warnings.

usage

.git docs parse [flags] <source-path>

Flags:
  -f, --format string   Output format: json|yaml|html (default "json")
  -s, --strict          Fail on schema warnings
  -o, --output string   Write result to file
  -v, --verbose         Enable trace logging

`.git docs sync`

Pushes validated docs to the central registry or pulls updates from remote.

example

# Push to production registry
$ .git docs sync --target prod --auth-token=$GIT_REGISTRY_TOKEN
→ Authenticating against registry.git.dev...
→ Uploading 14 artifacts...
✓ Sync complete. SHA: 8f3a9c2d

`.git docs serve`

Starts a local development server with live-reload for documentation changes.

example

$ .git docs serve --port 3000 --watch ./spec/
🚀 Server ready at http://localhost:3000
👀 Watching ./spec/ for changes...
[14:22:01] Rebuilding on: specs/api/v2.yaml

4. Configuration Schema

Configuration is managed via .git-docs.yaml at the project root. The schema is strictly validated against JSON Schema Draft 2020-12.

.git-docs.yaml

version: 2
pipeline:
  strict_mode: true
  cache_ttl: "1h"
  parallel_workers: 4

registry:
  endpoint: "https://registry.git.dev/v2"
  region: "us-east-1"
  fallback: false

metadata:
  team: "platform-eng"
  owner_email: "infra@git.dev"
  tags:
    - "internal"
    - "v2-api"
    - "critical-path"

render:
  theme: "dark-minimal"
  include_raw: true
  compress_output: true

⚠ Deprecation Notice The pipeline.parallel_workers field will be removed in v3.0. Use pipeline.concurrency instead. Migration tooling is available via .git docs migrate --to v3.

5. Diagnostics & Debugging

When pipeline stages fail or produce unexpected outputs, use the built-in diagnostic suite:

diagnostics

# Run full health check
$ .git docs doctor
[✓] Parser version matches registry schema
[✗] Cache directory permissions mismatch (~/.git/cache/docs/)
[✓] Network latency to registry: 42ms
[!] Warning: 3 deprecated fields detected in .git-docs.yaml

# Force cache rebuild
$ .git docs cache --clear && .git docs parse ./spec --verbose

Enable TRACE level logging by setting GIT_LOG_LEVEL=trace or passing the --trace flag to any subcommand. Logs are written to ~/.git/logs/engine-docs.log.

6. Known Issues & Workarounds

Cross-platform line endings: Windows CRLF line endings may cause AST parsing failures on strict mode. Workaround: Set core.autocrlf=input in git config or pipe through dos2unix.
Large YAML manifests (>15MB): Memory consumption spikes during normalization. Workaround: Split specs into modular files and use $ref resolution.
Registry timeout on EU endpoints: Intercontinental latency can trigger gRPC deadlines. Workaround: Override region via --registry-region eu-west-1 or configure edge proxy.

Report unreproducible issues via .git docs bug-report --attach-logs. All telemetry is stripped before transmission.

Contributing

Contributions to the parser engine, schema definitions, or CLI tooling are welcome. Please review the CONTRIBUTING.md in the monorepo before submitting PRs. All commits must be signed with GPG and follow conventional commit semantics.

Build locally with: make build && make test && make lint