Repository navigation
Conversation
The documentation style rules cover pages under docs/. Plugin-author pages, dev-docs/ARCHITECTURE.md paragraphs and AGENTS.md summaries had no written criteria, though the existing documents already follow consistent conventions. This records those conventions: - Plugin-author pages name the SDK's public API, which rule 5 would otherwise forbid, but never a CLI-internal identifier. - An ARCHITECTURE.md paragraph that carries reasoning below the ADR bar states the rule in the present tense with its reason, with no PR chronology, and links an ADR instead of restating it. - A rule AGENTS.md summarizes changes in its full-rule document in the same pull request. - The docs link check does not cover dev-docs/ or AGENTS.md, so links there are checked by review only. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Warning Review limit reachedYou've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. Next included review available in 28 minutes. View limit details
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
Bomly Diff SummaryCompared Overview
Dependency Changes✅ No dependency changes. Vulnerabilities✅ No vulnerability changes. License Changes✅ No license changes. Project Posture✅ No project posture changes ( Policy Findings✅ No policy differences were identified. |
…losure - ADR-0050 returns as a retired stub: it was live on main, and numbers and filenames are kept. The index lists it under Retired (29 stubs). - ADR-0020 has one Revised line, a Context sentence on plugin trust, and an accurate account of when the access block is shown: at install and in plugins info; plugins enable shows it but asks for no confirmation. - PLUGINS.md lists every case that stops a run with exit 4 (as preflight's available() decides it), links the exit code and the SBOM glossary entry, says an omitted access list equals an empty one, and drops the circular "compare with what the plugin says". - EXIT_CODES.md gains the preflight case under exit 4. - The authoring guide links the prerequisites section inline and shows how a Go descriptor declares Requires. Refs #535 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Folded into #534 at the user's request: commit 18d9263 is cherry-picked there as b46624a, unchanged. Both PRs edit 🤖 Generated with Claude Code |
…ccess (#531) * build(deps): adopt bomly-sdk v0.16.0, giving embedded components a lifetime scope v0.15.0 added HostContext.OnCleanup. Each embedded component now gets a plugin.ComponentScope that RegisterModule records before the constructor runs, and Registry.Close ends them newest first with joined errors. Threading the command context and closing the registry at command end follow in this pull request. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(engine): preflight declared component requirements before a stage runs Each stage now compares the requirements a component's descriptor declares (bomly-sdk v0.16.0 plugin.Requirements) with what the host can vouch for: source-tree-v1 for a filesystem or Git target not planned as an SBOM document, dependency-graph-v1 once detection found a dependency node, and vulnerability-records-v1 at analyze and audit once the registry carries a record. A token this host cannot evaluate is never satisfied. Before any stage, an explicitly selected component the plan can never run fails the command with a PreflightError (exit 4) naming the component, the requirement and the remedy. Inside a stage, a component whose requirement the actual data misses is held back through a registry view before Ready is called, with a warning on the stage's channel. Components that declare nothing are untouched, and Ready/Applicable stay authoritative for the rest. engine.go is not touched: the hook lives in pipeline.go around the existing engine calls. Refs #417 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(plugins): disclose declared access and requirements in plugin views A package manifest may now carry the SDK's access block (bomly-sdk v0.16.0 plugin.Access), validated only through plugin.ValidateAccess. A malformed block fails the install; an absent one keeps installing and reads as unknown, never as "no access". Install, enable (before the plugin is enabled), info, verify and doctor show it as the publisher's unverified claim through one renderer, and the JSON views carry it with accessDisclosure set to declared or unknown. Nothing is enforced. Declared requirements appear in `plugins info` (unknown tokens marked) and in generated matcher, auditor and detector-chain pages when a component declares any; no built-in does yet, so the generated docs are unchanged. The installed-snapshot comparison now includes requirements, so a binary whose declared requirements changed since install fails verify, and the descriptor clone helpers delegate to the SDK's Clone, which copies them. Refs #417 Refs #418 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs: ADR-0051 and plugin docs for component prerequisites and declared access ADR-0051 records the requirement vocabulary the host evaluates, unknown tokens, explicit-versus-default failure, why provider names are not a requirement, and disclosure without enforcement. docs/PLUGINS.md gains "Component prerequisites" and "Declared access"; the authoring guide lists the access keys and the descriptor's requires list. Closes #417 Closes #418 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(engine): preflight ecosystem-scoped auditors in a component audit explain's component audit selects auditors by the queried package's ecosystem, but preflight listed them with no ecosystem, so an npm-only auditor was neither checked at planning nor held back before Ready. The plan now sees every auditor the filter selects, and the component-audit stage evaluates the same selection the engine makes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix: address CodeRabbit round 1 on preflight and access disclosure - explain reports a preflight skip once, not once per matching manifest. - LoadRuntimePlugins sets accessDisclosure like the other installed loaders. - An absent access block reads "has no access declaration", which cannot be mistaken for an empty declaration. - PLUGINS.md and the authoring guide state when Ready and Applicable run, and what a refused install says; ADR index count and ADR-0051 trimmed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(adr): fold ADR-0050 and ADR-0051 into existing records Neither record met the ADR bar: ADR-0050's reason already lives in Engine.Match's doc comment and the SDK Clone docs, and ADR-0051 mostly described the code and restated ADR-0040's ownership split. Both are deleted. ADR-0050 landed with #532 and nothing relied on it, so it has no retired stub. The two points that pass the bar move to existing homes. ADR-0020, the live trust record, is revised in place: a manifest access block is the publisher's unverified claim, shown before enabling and never enforced. dev-docs/ARCHITECTURE.md (Scan Pipeline) now records why only a plan that can never be satisfied fails the command, and why each matcher and analyzer call works on its own snapshot. Code references point there; the ADR index is back to 21 live records. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(plugins): state the outcome for an unknown requirement A component selected by name with a requirement this Bomly does not know stops the command with exit code 4; a default one is skipped with a warning. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs: apply the docs-criteria review to prerequisites and access disclosure - ADR-0050 returns as a retired stub: it was live on main, and numbers and filenames are kept. The index lists it under Retired (29 stubs). - ADR-0020 has one Revised line, a Context sentence on plugin trust, and an accurate account of when the access block is shown: at install and in plugins info; plugins enable shows it but asks for no confirmation. - PLUGINS.md lists every case that stops a run with exit 4 (as preflight's available() decides it), links the exit code and the SBOM glossary entry, says an omitted access list equals an empty one, and drops the circular "compare with what the plugin says". - EXIT_CODES.md gains the preflight case under exit 4. - The authoring guide links the prerequisites section inline and shows how a Go descriptor declares Requires. Refs #535 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(engine): an SBOM beside source manifests leaves a source tree Discovery plans an SBOM found in a directory as its own subproject next to the directory's lockfiles, and any such subproject made preflight treat the whole target as an SBOM document, skipping or rejecting components that need source-tree-v1. A target is now an SBOM document only when every planned subproject is one, as with --sbom. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Related: #531 (its docs were reviewed against these criteria), #534.
Why
AGENTS.md has detailed rules for pages under
docs/(Documentation style, rules 1-10) and for ADRs (dev-docs/adr/README.md). It has none for three other kinds of document that #531 and #534 change:docs/plugins/). Rule 5 forbids Go identifiers in user pages, yet every plugin-author page names SDK API (plugin.BaseMatcher,runtime.ServeModule,Ready), because that is what an author writes. The exception existed only as practice.dev-docs/ARCHITECTURE.mdparagraphs. Since the ADR cleanup (docs(adr): consolidate 48 records into 20 concise decisions #526), reasoning that does not meet the ADR bar goes here. Nothing said how such a paragraph is written.AGENTS.mdsummaries of a rule that lives elsewhere. The ADR bullet ends "The full rule isdev-docs/adr/README.md". Nothing said that a change to the rule must land in that full text too. docs(agents): hold ADR requests to the bar, and record criteria for plugin-author and developer docs #534 adds a rule to the summary only.What
A new subsection, "Plugin-author and developer documentation", under Quality Bar, right after Documentation style. Each line records a convention the existing documents already follow:
docs/plugins/docs/plugins/*.mdpagedev-docs/ARCHITECTURE.mdadr/README.mdandTEMPLATE.md("No implementation history", "identifiers only where the reader must go")AGENTS.mdIt also says which documents CI checks for links. The
Docs link checkjob coversdocs/,README.mdandCONTRIBUTING.md, so links indev-docs/andAGENTS.mdare checked by review only.This change has no bomly-sdk companion. The new subsection applies only to bomly-cli documents and does not touch the shared ADR section or the AI review triage section, which are the ones marked "change both together".
Verification
make testpassed, and the pre-commit hook'sfmt-checkandlintpassed.🤖 Generated with Claude Code