fix: escape labels, scope the layer annotation, guard foreign catalogs, announce the root (#2, #4, #5) - #10
Merged
Merged
Conversation
…s, announce the root (#2, #4, #5) #2 -- escape brackets in catalog link labels. A title like "Fact [Sales]" rendered as [Fact [Sales]](/tables/a.md), which the OKF graph reader's link regex cannot match. The result is a MISSING edge, not a broken one -- validate reports broken links only for edges that exist, and its orphan check needs a concept to have NEITHER inbound NOR outbound links. So any concept carrying one outbound link lost its catalog backlink silently. Note the limit, because it surprised me: backslash-escaping does NOT rescue a reader whose label class is [^]]+, since that class has no notion of an escape and still stops at the literal ]. Escaping is the correct CommonMark output and what a bracket-aware reader needs, but it only takes effect once the matching reader change ships. The test asserts that negative explicitly. #4 -- scope the layer annotation to catalogs only this plugin owns. This is the actual shared-bundle fix. The " · <layer>" suffix fired for any concept carrying a `layer` key, in any of the 32 catalogs -- including the 8 that system-architecture-capture also declares. Its renderer emits a bare - [label](path), so the file flipped on every alternation between plugins. Measured after the change: rendering a `glossary` concept through all three plugins now produces byte-identical output (md5 eecb841a from each). The annotation is retained on catalogs only this plugin owns, e.g. `layers`. Also added the `catalog not in CATALOGS` guard. On its own that does NOT fix the churn -- for a catalog two plugins both declare it passes in both -- which is exactly why the annotation scoping is the load-bearing half. #5 -- announce a fallback root. resolve_knowledge_root probes sample-knowledge/ and .okf/ when the configured root is not an initialized bundle. There are 16 call sites and only dekc_doctor announced the bundle it used, so with any other command you could not tell which root you got. This repo ships a sample-knowledge/, so a capture run inside a clone before initializing a bundle wrote there silently. 3 failures before, 22/22 after. py_compile, validate, doctor, index build and the search assertion all pass. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011XXDjM9WnCtsdRTU441WUu
Union-merge the test file (both branches purely added imports/classes) and collapse the dekc_common import block to a single statement.
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
1 participant
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.
Three fixes in the bundle/catalog layer. The middle one is the interesting one.
#4 — scope the
· <layer>annotation to catalogs only this plugin ownsThis is the actual shared-bundle fix. The suffix fired for any concept
carrying a
layerkey, in any of the 32 catalogs — including the 8 thatsystem-architecture-capturealso declares (agents,diagrams,domains,glossary,packs,products,storage,workflows). Its renderer emits abare
- [label](path), so a shared catalog flipped back and forth on everyalternation between the two plugins.
Measured after the change — rendering the same
glossaryconcept through allthree plugins:
Byte-identical. The annotation is kept on catalogs only this plugin owns, such
as
layers, and the test pins both halves.I also added the
catalog not in CATALOGSguard, but I want to be clear it isnot what fixes this: for a catalog two plugins both declare, that guard
passes in both. It is defensive hardening against an outside caller iterating
directories. The annotation scoping is the load-bearing change.
#2 — escape brackets in catalog link labels
Fact [Sales]rendered as[Fact [Sales]](/tables/a.md), which the graphreader's link regex cannot match — producing a missing edge rather than a
broken one, which
validatedoes not report.Limit worth stating: backslash-escaping does not rescue a reader whose
label class is
[^\]]+; that class has no notion of an escape and still stops atthe literal
]. Escaping is correct CommonMark and is what a bracket-awarereader needs, but this half is inert until the reader change ships
(
okf-plugin#48/#50). The test asserts that negative explicitly.#5 — announce a fallback root
resolve_knowledge_rootprobessample-knowledge/and.okf/when theconfigured root is not an initialized bundle. There are 16 call sites and only
dekc_doctorannounced the bundle it used, so with any other command you couldnot tell which root you got — and this repo ships a
sample-knowledge/, so acapture run inside a clone before initializing a bundle wrote there silently.
The configured root still wins whenever it is usable; that is unchanged and now
pinned by a test.
Verification
Closes #2
Closes #4
Closes #5