Skip to content

fix(cli): split link-escape from link-target for independent control - #25

Open
davidmoshal wants to merge 1 commit into
openknowledge-sh:mainfrom
davidmoshal:fix/validate-escapes-bundle-root
Open

fix(cli): split link-escape from link-target for independent control#25
davidmoshal wants to merge 1 commit into
openknowledge-sh:mainfrom
davidmoshal:fix/validate-escapes-bundle-root

Conversation

@davidmoshal

@davidmoshal davidmoshal commented Aug 4, 2026

Copy link
Copy Markdown
Contributor

Fixes #24

Problem

openknowledge validate <bundle> warns link target escapes bundle root: <href> for every local Markdown link that resolves outside the bundle. In an integrated knowledge base (Wiki/ inside a repository), links from concepts to the source files they document are deliberate, so the warning fires on every run.

The warning shares a single rule ID, link-target, with the "does not exist" warning. So link-target = "off" silences both — there is no way to keep missing-link detection while suppressing the escape noise. (One real 48-file wiki reports ~200 escape warnings and zero missing-target warnings, so the bundled rule loses nothing for it today, but would lose missing-link detection the moment a broken in-bundle link appears.)

The OKF 0.1 spec does not require the escape check: section 5.2 allows standard relative paths with no in-bundle restriction, section 5.3 says an unresolved target is not malformed, and section 9 lists "Broken cross-links" among things consumers MUST NOT reject a bundle over.

Change

Splits the escape warning into its own link-escape rule, keeping link-target for in-bundle missing targets only.

  • Unconfigured default is unchanged: with no .openknowledge.toml and no --rule, the same warnings appear with the same severity (warning) and the same message text. The only unconfigured difference is the JSON rule field for escape issues, which changes from link-target to link-escape.
  • Configured bundles: migration required. An existing link-target = "off" previously silenced escape warnings too; after this change it affects only missing-target, so escape warnings reappear unless link-escape = "off" is also set. Likewise link-target = "error" no longer escalates escape — add link-escape = "error" to keep that. JSON CI consumers keying on rule: "link-target" for escape issues must update to link-escape.
  • Bundles can now silence escape warnings alone: link-escape = "off" in .openknowledge.toml, or --rule link-escape=off. Missing-link detection (link-target) is preserved.
  • link-escape is added to the rule registry, the "Link targets" check row, the command docs, and the changelog.

Testing

  • New TestValidateSeparatesEscapeAndMissingLinkRules: default emits both (link-escape + link-target); link-escape=off leaves only missing; link-target=off leaves only escape.
  • Existing link-target tests (broken in-bundle links, escalation, disable) unchanged and passing.
  • go test ./packages/cli/..., gofmt, go vet clean.
  • openknowledge validate Wiki on this repository's own wiki still passes.
  • End-to-end smoke: default 2 warnings (link-escape + link-target); --rule link-escape=off -> 1 (missing); --rule link-target=off -> 1 (escape).

@davidmoshal davidmoshal changed the title fix(cli): skip link validation for targets outside the bundle root fix(cli): split link-escape from link-target for independent control Aug 4, 2026
@davidmoshal
davidmoshal force-pushed the fix/validate-escapes-bundle-root branch from 3706033 to e99bfd8 Compare August 4, 2026 04:28
The "link target escapes bundle root" warning and the "does not exist"
warning shared a single link-target rule, so link-target = "off" silenced
both and there was no way to keep missing-link detection while suppressing
the escape noise. Move the escape warning to a new link-escape rule, keeping
link-target for in-bundle missing targets only.

The unconfigured default is unchanged (the escape warning still appears by
default); bundles can silence escape warnings alone via link-escape = "off"
without losing missing-link detection. Existing link-target = "off"|"error"
configs now affect only missing-target, so add a matching link-escape entry
to preserve prior behavior.
@davidmoshal
davidmoshal force-pushed the fix/validate-escapes-bundle-root branch from e99bfd8 to f1b54d2 Compare August 4, 2026 04:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

validate: 'link target escapes bundle root' can't be silenced without losing missing-link detection

1 participant