Graph Structure Lint Rules

[ryansann]

Summary

This adds a new graph-structure lint category for checking whether an OKF bundle is shaped coherently, not just whether links resolve.

The new rules look at local neighborhoods, cross-neighborhood bridges, hub concepts, and dense local linking patterns. The goal is to help authors keep bundles navigable and useful as they grow.

What changed

• Added neighborhood inference for graph checks:
  • configured exact paths/globs
  • frontmatter neighborhood
  • directory-based fallback
  • isolated root concepts by default
• Added precomputed graph facts for cohesive vs bridging edges
• Added 8 new lint rules:
  • graph-structure/no-excessive-bridging
  • graph-structure/bridging-ratio
  • graph-structure/no-leaf-bridge-fanout
  • graph-structure/require-bridge-prose
  • graph-structure/prefer-neighborhood-index-link
  • graph-structure/no-complete-neighborhood-clique
  • graph-structure/min-local-cohesion
  • graph-structure/declare-hubs
• Added graph.neighborhoods config support, including glob paths
• Updated strict/minimal presets for the new rules
• Added docs for each new rule and for neighborhood configuration
• Updated okftool’s own OKF docs to dogfood the new checks cleanly
• Added tests covering the new graph rules and neighborhood behavior

Why

Basic topology checks can tell us whether a graph is connected, but not whether it is understandable.

These rules are intended to catch patterns like ordinary concepts linking all over the bundle, concepts that only point outside their local area, overloaded bridge concepts that should be declared as hubs, and
neighborhoods where every concept links to everything else.

Testing

• cargo fmt --all --check
• make ci
• scripts/build-npm-package.sh
• Node smoke check that the wasm package exports all new graph-structure/* rule descriptors