Raven-1/commitlint.config.cjs
Dizhan Xue 7ab685f600
docs(*): send the README's reference sections to the documentation site (#519)
## Summary

Five sections leave both READMEs: self-hosting, the command reference,
the
documentation index, the repo layout and the architecture. Each is
already a
page on the documentation site, and a second copy in the README is the
one
that drifts. Quick Start now ends by naming the site, so a reader who
has just
installed Raven is told where the rest lives. English drops 258 lines
and
Chinese 228, and the two stay in step: every section removed and the
pointer
added exist in both.

The repo-layout table went with them, and it was never only prose. It is
the
canonical set of commit scopes: a test held it equal to the packages on
disk
while commitlint computes its enum from that same tree, so the table is
what
keeps the list a reader is sent to and the list the tooling enforces
from
splitting. Removing the section broke both of that test's assertions,
and the
test reads the documentation page now, which carries the same table and
the
same key directories block. It is renamed with the move, because it no
longer
reads a README. AGENTS.md, raven/README.md and two comments in
commitlint.config.cjs name the page as well. The enum commitlint
computes is
unchanged at 71 scopes, because it was always read from the tree rather
than
from the table.

Two things are deliberately left alone. The dated records under
docs/plans and
docs/specs still describe the old location: they record the tree as of
their
date. And the English README keeps a Showcase section the Chinese one
does not
have, which is how they already were.

## Type

- [ ] Fix
- [ ] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

The coupling was demonstrated rather than assumed: removing the sections
first
was run against the existing test, which failed with "README.md lost its
'Repo
layout' section" and "Key directories lost its agents/ line". After
repointing,
dropping one table row from the documentation page fails it again with
"package
on disk without a table row: ['acp']", so the guard still bites from its
new
source.

- `uv run pytest tests/test_scope_canon.py tests/test_docs_site.py
tests/test_docker_runtime.py tests/test_living_docs.py
tests/test_external_consumer_surface.py` -> 22 passed
- `uv run pytest` over the eleven other tests that read a README -> 859
passed
- `make lint-python`, `make lint-imports`, `make lint-deps`, `make
lint-types`
  -> exit 0, against an environment synced the way CI installs
- `make check-commits`, `make check-source-language`, `make
check-large-files`,
  and `pre-commit run --from-ref origin/main --to-ref HEAD` -> exit 0
- `make docs-build` -> built
- `node -e` on commitlint.config.cjs -> 71 scopes, the same set as
before
- the only internal anchors left in either README are `#readme-top`,
whose
target is still there, and no remaining link points into a removed
section

## Risk

User-visible: the README no longer answers self-hosting, the commands,
the
layout or the architecture; it points at the site instead. Anyone who
had
bookmarked a README anchor for one of those sections loses it. The scope
list
AGENTS.md sends a contributor to is now a page rather than a README
section.

Rollback: revert the commit. Nothing outside the repository depends on
the
removed sections, and the site pages they moved to were already
published.

## Related Issues

N/A

Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
2026-09-19 23:41:14 +08:00

101 lines
2.6 KiB
JavaScript

const fs = require("fs");
const path = require("path");
const TYPES = [
"build",
"chore",
"ci",
"docs",
"feat",
"fix",
"perf",
"refactor",
"revert",
"test",
];
// The canonical scope set mirrors the documentation site's repo-layout
// table (docs-site/docs/repo-layout.md): every
// top-level package under raven/ (plus the home.py module), computed from
// the tree at config-load time so the enum cannot rot behind a refactor.
function ravenPackages() {
const root = path.join(__dirname, "raven");
return fs
.readdirSync(root, { withFileTypes: true })
.filter(
(entry) =>
entry.isDirectory() &&
fs.existsSync(path.join(root, entry.name, "__init__.py")),
)
.map((entry) => entry.name);
}
// A change living wholly in a top-level tree outside raven/ uses that tree
// as its scope (see that page's preamble).
const TOP_LEVEL_TREES = [
"agents",
"benchmarks",
"bridge",
"docs",
"evolver",
"plugins-dist",
"schemas",
"scripts",
"tests",
"ui-tui",
"ui-web",
];
// Two files at the repository root rather than a tree, so no directory scan
// reaches them -- but a change confined to install.sh and install.ps1 is as
// scoped as one confined to ui-web/, and `*` says less than the truth about it.
const ROOT_SURFACES = ["installer"];
const PRODUCTS = ["raven-code", "raven-design", "raven-oncall", "raven-ppt", "raven-research"];
// The plugin distributions beside the host wheel: each is its own package
// with its own version, so a change confined to one scopes by its wheel name.
const WHEEL_DISTRIBUTIONS = ["design-engine", "everos-memory", "ppt-engine"];
// Scopes already used on refactor/raven_v0_2_0 before the enum existed; a PR
// from that branch lints its whole history, so they stay legal until the
// branch merges. Retire this list afterwards.
const LEGACY_SCOPES = [
"changelog",
"context",
"integration",
"plans",
"subagent",
"subagents",
"ui",
"web_rpc",
];
const SCOPES = [
...new Set([
...ravenPackages(),
"home",
...TOP_LEVEL_TREES,
...ROOT_SURFACES,
...PRODUCTS,
...WHEEL_DISTRIBUTIONS,
...LEGACY_SCOPES,
"*",
"deps",
"deps-dev",
]),
].sort();
module.exports = {
rules: {
"header-max-length": [2, "always", 100],
"scope-enum": [2, "always", SCOPES],
"subject-case": [2, "never", ["sentence-case", "start-case", "pascal-case", "upper-case"]],
"subject-empty": [2, "never"],
"subject-full-stop": [2, "never", "."],
"type-case": [2, "always", "lower-case"],
"type-empty": [2, "never"],
"type-enum": [2, "always", TYPES],
},
};