Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

feat(ci): group storage schema doc by owner namespace

Steven Enamakel8981ca93abaf
diff --git a/scripts/ci/check-storage-schema.mjs b/scripts/ci/check-storage-schema.mjs
index 86055187bc..dfbde6e286 100644
--- a/scripts/ci/check-storage-schema.mjs
+++ b/scripts/ci/check-storage-schema.mjs
@@ -2,17 +2,18 @@
// Storage-schema gate (tinyhumansai/openhuman#7992, part of #7973).
//
// Owners expose v2 `CollectionSpec` values; the host composes them
-// (`crates/openhuman-core/src/storage/schema.rs`). This check dumps the
-// composed declarations as JSON (the `storage_schema_dump` example of
-// `openhuman-cli`), lints them, and keeps `docs/storage-schema.md` in step.
+// (`crates/openhuman-core/src/storage/schema.rs`). This check dumps those
+// declarations as JSON (the `storage_schema_dump` example of `openhuman-cli`),
+// lints them, and keeps `docs/storage-schema.md` in step. The doc groups each
+// spec by the owner namespace in its collection name.
//
// Lint rules (the spec is docs/specs/schema-v2.md in tinystoragedrivers):
// 1. collection names are `<owner>.<entity>` with a snake_case entity
// (lowercase letters, digits and `_`);
-// 2. each composed collection name and index name is unique;
+// 2. each collection name and index name is unique;
// 3. indexed fields that hold a time are `*_ms` (no `_at`, `_ns`, `_us`,
// `_secs`, `_ts` or `_time` suffix);
-// 4. expiry and search declarations are carried through the composed dump.
+// 4. expiry and search declarations are carried through the dump.
//
// Usage:
// check-storage-schema.mjs lint and fail on doc drift
@@ -116,27 +117,40 @@ export function lint(dump) {
return problems;
}
-/** Renders docs/storage-schema.md. */
+const compare = (left, right) => (left < right ? -1 : left > right ? 1 : 0);
+
+/** Renders docs/storage-schema.md from stable owner-grouped CollectionSpecs. */
export function render(dump) {
+ const owners = new Map();
+ for (const collection of dump.collections ?? []) {
+ const owner = collection.name.split('.', 1)[0];
+ if (!owners.has(owner)) owners.set(owner, []);
+ owners.get(owner).push(collection);
+ }
+
const out = [
'# Storage schema',
'',
'<!-- Generated by `pnpm docs:generate` (scripts/ci/check-storage-schema.mjs) from the',
- 'composed owner `CollectionSpec` values (`crates/openhuman-core/src/storage/schema.rs`). Do not edit by hand. -->',
+ 'host-composed owner `CollectionSpec` values (`crates/openhuman-core/src/storage/schema.rs`). Do not edit by hand. -->',
'',
'Record owners declare collections with `CollectionSpec`; the host composes and prepares',
- 'those declarations at boot. The table lists collection names, indexes, expiry fields, and',
- 'full-text search fields. Record shapes and migrations stay with their owners.',
+ 'those declarations at boot. Each section lists the specs by the owner namespace in the',
+ 'collection name, including indexes, expiry fields, and full-text search fields.',
+ 'Record shapes and migrations stay with their owners.',
'',
];
- out.push('| Collection | Indexes | Expiry field | Search fields |', '| --- | --- | --- | --- |');
- for (const collection of [...(dump.collections ?? [])].sort((a, b) => a.name.localeCompare(b.name))) {
- const indexes = (collection.indexes ?? []).map(index =>
- `\`${index.name}\` (${index.fields.map(field => `\`${field}\``).join(', ')})${index.unique ? ' unique' : ''}`
- ).join('<br>');
- out.push(
- `| \`${collection.name}\` | ${indexes} | ${collection.ttl_field ? `\`${collection.ttl_field}\`` : ''} | ${(collection.search?.fields ?? []).map(field => `\`${field}\``).join(', ')} |`
- );
+ for (const owner of [...owners.keys()].sort(compare)) {
+ out.push(`## ${owner}`, '', '| Collection | Indexes | Expiry field | Search fields |', '| --- | --- | --- | --- |');
+ for (const collection of owners.get(owner).sort((a, b) => compare(a.name, b.name))) {
+ const indexes = (collection.indexes ?? []).map(index =>
+ `\`${index.name}\` (${index.fields.map(field => `\`${field}\``).join(', ')})${index.unique ? ' unique' : ''}`
+ ).sort(compare).join('<br>');
+ out.push(
+ `| \`${collection.name}\` | ${indexes} | ${collection.ttl_field ? `\`${collection.ttl_field}\`` : ''} | ${(collection.search?.fields ?? []).map(field => `\`${field}\``).join(', ')} |`
+ );
+ }
+ out.push('');
}
return `${out.join('\n').trimEnd()}\n`;
}
@@ -179,7 +193,8 @@ function main(argv) {
console.error(`${docPath} is out of date. Run \`pnpm docs:generate\` and commit the result.`);
return 1;
}
- console.log(`storage schema ok: ${dump.owners.length} owners`);
+ const owners = new Set((dump.collections ?? []).map(collection => collection.name.split('.', 1)[0]));
+ console.log(`storage schema ok: ${owners.size} owners, ${(dump.collections ?? []).length} collections`);
return 0;
}