feat(ADR-0046): add optional description to package docs#1811
Merged
Conversation
feat(ADR-0046): package documentation portal + nav entry (#1686) objectui@893e5302174c7cbf75a7bed9e8e6dcb935273363
…local resolution Phase 1 — install-time namespace gate. `SchemaRegistry.installPackage` refuses a package whose `manifest.namespace` is already owned by a DIFFERENT installed package (new `NamespaceConflictError`), making explicit and early the constraint the object/table layer already enforces implicitly (a duplicate `CREATE TABLE <ns>_<obj>` fails at the DB). Same-package reinstall and shareable platform namespaces (base/system/sys) are exempt; OS_METADATA_COLLISION=warn downgrades to a warning. Phase 2 — prefer-local (container-scoped) resolution. `getItem(type, name, ns?)` resolves a bare name to the item owned by `ns`'s package before any cross-package fallback, preserving ADR-0005 overlay precedence and remaining backward compatible (param optional). `getApp` resolves prefer-local against its own name (app.name ≡ namespace in v1). The per-item collision guard now narrows to the cases prefer-local CANNOT disambiguate (shared/missing namespace), so two DIFFERENT-namespace packages legitimately coexist on the same bare name — the marketplace coexistence the revised ADR-0048 targets. Every existing collision test still passes (namespace-less fixtures remain a hard error). Tests: registry-namespace-install-gate.test.ts (7), registry-prefer-local- resolution.test.ts (7). Full objectql suite green (600). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A doc can now carry a one-line `description` (frontmatter `description:`) — title / summary / body, the natural minimal model. - spec: DocSchema gains optional `description`. - cli: collect-docs reads `description:` from frontmatter (generalized the scalar extractor; title + description share it). Regression test added. - It travels in GET /meta/doc list (content is omitted there), so the docs portal shows summaries without fetching each body — verified live: showcase /meta/doc returns description, hasContent:false. - Example docs (app-showcase, app-todo) carry descriptions. - ADR-0046: schema + a P3 design note for doc TAGS (deferred) — tags are i18n-resolved keys, core protocol vocabulary + namespace-prefixed package tags; not a field to bolt on early. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
A doc can now carry a one-line
description(frontmatterdescription:) — the natural minimal model: title / summary / body.DocSchemagains optionaldescription.collect-docsreadsdescription:from frontmatter (generalized the scalar extractor;title+descriptionshare it). Regression test added.GET /meta/doclist response (which omitscontent), so a docs portal shows summaries without fetching each body. Verified live: showcase/meta/docreturnsdescription,hasContent:false.app-showcase,app-todo) carry descriptions.Tags — decided + recorded, not built
Per the discussion, ADR-0046 now has a P3 design note for doc tags (deferred): tags are keys resolved through the platform's label-key → i18n mechanism (never display strings), with a small protocol core vocabulary plus namespace-prefixed package tags. Pure closed enum is too rigid, pure free-form fragments + has no i18n owner; the layered key model resolves both. Not a field to bolt on before there's doc volume to justify a discovery surface.
descriptiondeliberately stops short of taxonomy (no i18n-keying burden).Companion
The portal-side display (render the summary, drop the machine id from the reader-facing list) ships as a separate objectui PR.
🤖 Generated with Claude Code