Development and Validation

Development and Validation

This project is intentionally small: maintained Node.js built-ins, deterministic files, explicit configuration, and tests that exercise real command-line behavior across temporary repositories.

中文概览：运行时修改必须保持零依赖、跨平台和确定性；文档修改至少要通过审计与本地链接检查。

Prerequisites

• Git;
• Node.js 22 or 24;
• no dependency installation step.

Clone and inspect:

git clone https://github.com/CH-ZHOU-0512/govern-project-docs.git
cd govern-project-docs
git status --short

Local validation

Syntax checks:

node --check scripts/audit-docs.mjs
node --check assets/runtime/docs-toolkit.mjs
node --check assets/runtime/document-index.mjs
node --check assets/runtime/check-doc-governance.mjs
node --check assets/runtime/check-markdown-links.mjs

Tests:

node --test tests/*.test.mjs

Documentation checks:

node scripts/audit-docs.mjs --repo .
node assets/runtime/check-markdown-links.mjs --repo .

Before committing, also run:

git diff --check

Test coverage

The test suite exercises the runtime through its actual CLI entry points. It covers:

• deterministic Markdown and JSON index generation;
• query ranking, stable IDs, encoded paths, and bounded results;
• stale and missing index detection;
• watch refresh behavior;
• active metadata, exclusions, valid dates, and archive boundaries;
• complex local Markdown targets and fenced-code behavior;
• ignored directories and read-only audit reporting;
• help output, missing arguments, and invalid configuration.

When a change affects paths, watching, Markdown parsing, atomic writes, or generated bytes, add a regression test rather than relying on manual observation.

Continuous integration

.github/workflows/validate.yml runs on pushes and pull requests using this matrix:

Operating system	Node.js
Ubuntu	22 and 24
Windows	22 and 24

CI checks syntax, runs the full test suite, audits this Skill repository, and validates local Markdown links.

Design guarantees

Changes should preserve these properties:

• deterministic: identical input produces byte-identical generated output;
• bounded: query results do not expand without limit;
• atomic: generators do not expose partially written files;
• portable: paths and watch behavior work on Windows and Linux;
• read-only where promised: audit and check commands never modify the target;
• explicit: configuration errors fail clearly instead of falling back silently;
• evidence-based: generated relationships and indexes come from detectable files and contracts.

Known boundaries

• Native recursive file watching differs by platform, so watch mode includes polling fallback.
• Watch mode is not a replacement for committed generated output and CI freshness checks.
• The project does not ship a universal code-graph generator; stack-specific graphs require trustworthy parsers and machine contracts.
• Static analysis cannot safely infer reflection, dependency injection, dynamic imports, runtime plugins, or generated behavior without stack-specific evidence.
• Documentation governance cannot decide unresolved product, compliance, provider, or release questions.

Contributing

Issues and pull requests are welcome.

For runtime changes:

1. Describe the failure mode or capability.
2. Keep the shared toolkit cohesive and avoid third-party dependencies unless there is a compelling, reviewed reason.
3. Add or update tests.
4. Run the full local validation set.
5. Explain any platform or watch behavior not directly observed.

For governance changes:

1. State which documentation failure the rule prevents.
2. Decide whether the rule belongs in human policy, configuration, or a machine check.
3. Avoid creating a second authority for an existing fact.
4. Update README, Wiki, templates, references, and runtime only where each is the correct owner.

Use GitHub Issues for bugs and proposals, and submit focused pull requests against main.

Security and privacy

Do not include repository secrets, personal data, private source requirements, or proprietary logs in examples, fixtures, issues, or change records. Use synthetic fixtures in tests and preserve the target repository's existing security policies when integrating hooks or CI.