okf 1.11.0 → 1.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7fae00b0ef2e7029cf0869ec73339321f6a54d58bd566aa6139cf6d5143999b9
-  data.tar.gz: e337a96fadc268338e4f23984bb85b7b6ad54cee9b13f79a8301ae0179d4eec0
+  metadata.gz: 84ee2cefa8e04f2358c9125ca00ccdf9de8a12ab0a78a96315ec846bab8d3e87
+  data.tar.gz: 7a3186c5aa2924b4425a0c0a86c9f0812948427348d4fd3d0cd46852bd6dc575
 SHA512:
-  metadata.gz: ec66b51cd4a4cba56998248a85bf0470ad62db32487f7c5d0c66780057bcdb839b0f6b521fe6649fb438a0010da2c9d3a82b2781fbeb59c90de5d96971b5ab39
-  data.tar.gz: 181388d7be611d1af0fb811a50a326f7d72b159d4ea09b632007d5a355042faf6bca7c27f6d5d67d396fad03f868450ec2ed0234655b3a7861074b43b3356135
+  metadata.gz: b0c9f1002b408702c74f73be001eab10b6691419700d33b41e81bd001d21858f1d79289696edbb2ad6e7c6f4a76ccd4c7458cf211e82fded5224f5fcfa6328b4
+  data.tar.gz: 0ed68e0095ab1aa912c5df3b6fd7b9f82e0e07f2cad0c182437cb70021beed8d5ecb054106185204b18d0f138303372bc62202c286aec75ce6c4a43434f2e546

data/CHANGELOG.md

@@ -5,6 +5,196 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.13.0] - 2026-08-07
+
+### Added
+
+- **`Bundle#directories`** — the bundle's own answer to "does this bundle have
+  directory X?", public because every surface now asks it (the CLI's concept
+  views, `okf-mcp`'s `dir` refusal) and the API this version's minor bump
+  exists for. Introduced by, and argued in, the `root` fix under Fixed below.
+
+### Changed
+
+- **The repository became a monorepo, and the gem moved into `okf/`.** Nothing
+  about the published gem changes in kind — same name, same library, same `v*` tag
+  series, same image, byte-identical in size to a pre-move build — but a checkout is laid out differently: one
+  directory per gem, named for the gem it ships, so `okf-mcp/` and the rest can
+  land beside the baseline without reshaping anything. `plugin/`,
+  `.claude-plugin/`, `.okf/` and the `Dockerfile` stay at the root; the last of
+  those because its build context must be the repo root, where the `.git` the
+  gemspec's `git ls-files` needs lives. From a checkout it is `cd okf` for
+  everything about the gem, and plain `rake` at the root to run every gem's suite
+  or to validate this repo's own bundle.
+- **`CODE_OF_CONDUCT.md` no longer ships in the gem** (70 files, from 71). It is
+  a repository document and was packaged only because nothing rejected it. The
+  gem now carries **its own README** instead of the project's — which also fixes
+  a long-standing wart, since the project README opens with images under
+  `.github/` that the gemspec has never packaged, so the page on rubygems.org has
+  been rendering a broken hero.
+- `changelog_uri` points at `okf/CHANGELOG.md`, where this file now lives.
+
+### Fixed
+
+- **A directory really named `root` is nameable again.** `--dir` and `--area`
+  accept `root` as a spelling of the bundle root, which is worth a shell quote
+  right up until a bundle actually has a `root/` directory — and then the alias
+  made it unaddressable, answering for the bundle root instead: the wrong
+  concepts, exit 0, nothing said. The alias now yields to a real directory,
+  since a convenience is worth less than a directory being reachable at all;
+  where no such directory exists nothing changes, which is every bundle that
+  has ever relied on the spelling. `okf dirs` carried the same fold into its
+  `subtree` column, where it computed the `root` row's subtree against the
+  bundle root — so the number on the row disagreed with what `--dir` on that
+  row returns, the one thing it promises never to do.
+
+  "Does this bundle have a `root` directory?" is now asked of the bundle
+  (`Bundle#directories`, under Added above) rather than of whichever list a view
+  had to hand. The concept views were reading it off the *catalog*, which knows
+  only directories holding concepts, so a `root/` carrying nothing but an
+  `index.md` stayed folded in `catalog`/`files`/`tags`/`types`/`search` while
+  `dirs` and `index` named it correctly — two answers to one question about one
+  bundle. And a multi-bundle `okf search @a @b --dir root` resolved per bundle
+  inside the loop, so one flag meant the `root/` subtree in the bundle that has
+  one and the bundle root in the bundle that does not, merged into a single
+  ranking with nothing in the output saying so; the served set resolves it once.
+
+  `Bundle#directories` counts every file kind that makes a directory real —
+  concepts, an `index.md`, and now a scoped `log.md`, which the first cut left
+  out: a `root/` holding only its history was invisible to the set, so the
+  alias won again for exactly the shape the fix was named after, one file kind
+  over. The same seed feeds `directory_index`, so `dirs`, `index` and `stats`
+  count a log-only directory too, and every surface answers "does this bundle
+  have directory X?" from one list.
+- **`filter_entries` regained its 1.12.0 arity.** The dirs-source fix above
+  added a required third parameter to a helper on `CLI::Command` — the base
+  every verb inherits, plugin gems' verbs included — so an out-of-tree verb
+  calling the released two-argument shape raised `ArgumentError` at runtime.
+  The parameter defaults now, and the default is 1.12.0's resolution — the
+  helper is handed rows, not the folder, so it has nothing to resolve a real
+  `root/` against, and the `root` alias folds exactly as it did; the plugin
+  suite drives a 1.12.0-era verb through the two-argument shape to pin it.
+  Its sibling `filter_ids` makes the opposite choice on purpose: it *is*
+  handed the folder, and its two-argument shape resolves through `dir_scope`,
+  because the unconditional fold there was the bug this entry fixes, not a
+  contract — an old caller gets the corrected answer rather than the familiar
+  wrong one. In-tree callers pass
+  the set through `dir_scope`, which also derives it only when a `--dir` or
+  `--area` flag will actually consult it — a plain listing no longer pays a
+  per-path ancestor walk for a set nothing reads (and `Bundle#directories` is
+  memoized, so the verbs that ask twice pay once).
+- **Coverage stopped measuring the plugin's curation hook** for one commit, and
+  said so by going *up*: SimpleCov's root defaults to the working directory, so
+  moving the gem down a level dropped ~100 tested lines out of the report and
+  line coverage read 98.63% against 98.47%. Its root is the repository now, with
+  the report still written inside the gem.
+
+### Security
+
+- **A symlinked file in a bundle can no longer read past the bundle root.** The
+  traversal guard `Path.join_under!` was lexical — it expands the path string,
+  and `File.expand_path` does not resolve a symlink — so a link whose name sat
+  inside the root but whose target did not passed the check, and the read
+  followed it. Every read now realpath-resolves and re-checks against the real
+  root: `Path.under?` is the shared pure predicate, `Bundle::Reader` quarantines
+  an escaping file into the unparseable bucket (a planted symlink is one bad
+  file, not grounds to fail the whole bundle read, which would hand any writer of
+  a served directory a denial of service), and `Concept::File` guards its own
+  read. A symlink that stays inside the bundle still resolves as before. The gap
+  reached every reader; serving a bundle's contents to an agent — as `okf-mcp`
+  does — is what surfaced it.
+
+## [1.12.0] - 2026-07-24
+
+### Added
+
+- **`okf graph --traffic`** — the link graph read one grain coarser. `--hubs`
+  measures concepts, but the refine playbook's directory judgements ("does this
+  directory prune? a concern, or a container?") had nothing measured at their
+  grain. `--traffic` collapses each concept into its directory and the links
+  between two directories into one weighted arc, so every row carries its
+  internal / out / in traffic and a **cohesion** — its internal share of that
+  total. That is cohesion versus coupling on a knowledge tree: near-zero cohesion
+  under heavy inbound is a shared vocabulary doing its job, heavy outbound with
+  nothing back is a projection wearing a directory. The rows sort by cohesion
+  ascending, so the directories with a case to answer come first, and a directory
+  with no traffic at all prints `—` rather than a `0%` it did not earn. The arc
+  **cut** is fitted to the bundle, not fixed — at weight 3, ten bundles ranged
+  from 2 arcs to 136 — and `--cut N` overrides it; cohesion is computed over
+  *every* arc regardless, so narrowing the drawn picture never moves the
+  evidence. JSON: `{ bundle, cut, fitted, dirs, arcs, total_arcs }`. The pure
+  model underneath is `Bundle::Skeleton` — concepts folded to directories, links
+  to weighted arcs, every edge tagged with the cut it survives (a local-degree
+  sparsifier, union rule, so no linked concept is ever stranded) — and it does no
+  I/O and draws nothing: it names a cut rather than taking one, so both the graph
+  page and the CLI narrow the same emission their own way.
+- **The graph page draws links in three amounts, and opens dense on its spine.**
+  227 links over 47 concepts at degree 9.7 is unreadable because of its arrows,
+  not its dots — so links become a layer: **every** link, the **spine** (each
+  concept's strongest edge — the Skeleton's `keep_at===0` set, chosen so it
+  touches every linked concept), or **none**, with a selected concept's own links
+  always shown in full. A dense bundle now opens on its spine rather than greeting
+  the reader with the thicket; the trigger is undirected degree above a floor set
+  between a tree's ~2 and the 9.7 that drove it, and `--map` overrides to none
+  with the directories boxed. Above 800 edges the first layout runs on the spine
+  alone and the rest arrive a frame later with no re-layout — **6.25 s → 3.29 s**
+  on 414 concepts, nothing on screen moving. Proven in both render modes on a
+  committed 110-concept / 880-link fixture, the only one over both floors.
+- **Registry groups — a named, recursive set of bundles.** A group is a registry
+  slug that names a list of members (bundle *or* group slugs, so they nest) and
+  resolves recursively, path-deduped, to its bundle leaves. `okf registry group
+  <slug> <@member…>` creates one or adds to it, `ungroup` removes members (and
+  emptying a group deletes it), and `del`/`rename` now span a group slug too —
+  one name cascades across every member list, one `del` cascade-drops the slug and
+  deletes any group it empties. Groups live in their own list in the registry
+  JSON, so the first-is-default rule and the `File.directory?` guards never meet a
+  pathless entry. `okf search @backend` merges the members into one ranking and
+  `okf server @backend` mounts each (the first at `/`), both skipping a vanished
+  member with a note, exactly as `@all` does. Every single-bundle verb **refuses**
+  a `@group` (exit 2) — the same rule that refuses a second bundle, through the
+  same `resolve_registered` seam.
+- **`okf registry init`** — create a project-local `.okf-registry.json` in the
+  current directory. Once it exists, okf discovers it by walking up from the
+  working directory, and every registry operation — and every `@slug` — resolves
+  through it in place of the global `$OKF_HOME` registry, so a bare `okf server`
+  inside a repo serves that repo's bundles with no global setup. The nearest one
+  on the path wins (nested registries resolve nearest-first), `okf registry list`
+  names the local file it found, and `OKF_NO_DISCOVERY=1` forces the global one —
+  the escape hatch for a fixed-cwd caller (CI, a tool).
+- **A local registry stores portable, relative paths.** A bundle inside the
+  registry's own tree is written relative to the `.okf-registry.json`, so the file
+  can be committed and travels with the repo — a checkout on another machine, or a
+  container that mounts it, resolves the same bundles unchanged. A bundle outside
+  the tree keeps an absolute path (it cannot travel). Paths still read back
+  absolute everywhere the CLI reports them; the relative form lives only on disk,
+  and an existing absolute local entry migrates to relative on its next write. The
+  global `$OKF_HOME` registry is unchanged — it stores absolute paths as before.
+
+### Changed
+
+- **The derived `area` field is renamed `top_dir`** — the first-path-segment
+  rollup the catalog, search, `stats`, and `graph --hubs` carry. `area` was never
+  the OKF spec's word (the spec speaks only of `dir`), so the rollup now names
+  itself in the spec's vocabulary: it is the `dir` at the top level. The `--json`
+  keys move with it — catalog/search rows carry `top_dir` in place of `area`,
+  `stats` emits `top_dirs`/`by_top_dir`, and `graph --hubs` emits
+  `top_dir`/`by_top_dir`. The **deprecated `--area`/`--by area` input flags are
+  unchanged** — they still warn and map to `--dir`/`--by dir`, and now source the
+  renamed field internally. No behavior changes; the well-homed-hub numbers are
+  identical.
+
+### Fixed
+
+- **A local-registry server preserves its relative-path anchor across a
+  re-open.** The hub re-read its boot registry with `OKF::Registry.new(path)`,
+  which drops the `relative_base` a discovered `.okf-registry.json` carries — so
+  on a project-local server the Bundles panel matched each mounted bundle's
+  absolute root against the re-read entry's *relative* path, missed, and drew
+  every in-tree bundle as "folder is gone", while a browser add flattened the new
+  bundle to an absolute path, undoing the portability relative storage exists for.
+  `Registry#reopen` re-reads the same file anchored the same way, and both hub
+  re-open sites use it.
+
 ## [1.11.0] - 2026-07-22
 
 ### Added
@@ -205,7 +395,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   rendered `(root)` for humans — and "cluster" stays prose for what a dir
   groups. Both deprecated spellings keep their **old behavior exactly** and warn
   once per run on stderr (`--json` on stdout is unaffected); they go in a later
-  release, along with `by_area` and the `area` row field.
+  release.
 
 ## [1.10.0] - 2026-07-21
 
@@ -1132,6 +1322,8 @@ Initial release.
 
 - Runs on Ruby >= 2.4 with two runtime dependencies: rack and webrick.
 
+[1.13.0]: https://github.com/serradura/okf-gem/compare/v1.12.0...v1.13.0
+[1.12.0]: https://github.com/serradura/okf-gem/compare/v1.11.0...v1.12.0
 [1.11.0]: https://github.com/serradura/okf-gem/compare/v1.10.0...v1.11.0
 [1.10.0]: https://github.com/serradura/okf-gem/compare/v1.9.0...v1.10.0
 [1.9.0]: https://github.com/serradura/okf-gem/compare/v1.8.0...v1.9.0