{
  "markdown": "# okftool\n\n[![CI](https://github.com/ryansann/okftool/actions/workflows/ci.yml/badge.svg)](https://github.com/ryansann/okftool/actions/workflows/ci.yml)\n[![crates.io](https://img.shields.io/crates/v/okftool-cli.svg)](https://crates.io/crates/okftool-cli)\n[![npm](https://img.shields.io/npm/v/@ryansann/okftool.svg)](https://www.npmjs.com/package/@ryansann/okftool)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)\n\nA fast, embeddable **validator and linter** for [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)\n(Open Knowledge Format) bundles, written in Rust.\n\nOne core, three surfaces:\n\n| Surface | Crate | Use |\n|---|---|---|\n| **Native CLI** | `okftool-cli` → `okftool` | CI, local `okftool validate` / `okftool lint` |\n| **wasm / npm** | `okftool-wasm` → `@ryansann/okftool` npm package | embed in JS hosts (a desktop app, a Node/edge API, the browser) |\n| **Rust crate** | `okftool-core` | embed directly in a Rust host |\n\nThe brain — parsing, spec validation, and the lint engine — lives in `okftool-core`\nand is filesystem-agnostic (callers pass `(path, content)`), so it compiles\nunchanged to native and `wasm32`. There is exactly one implementation.\n\n## Two layers\n\nokftool mirrors the OKF spec's MUST/SHOULD split:\n\n- **`validate`** enforces what the spec says MUST be true (§9 conformance:\n  parseable frontmatter, a non-empty `type`). These are non-disableable errors.\n- **`lint`** enforces what SHOULD be true plus everything the spec leaves to\n  judgment. Every lint rule is configurable and disableable. A lint rule may\n  never flag something the spec mandates tolerating (broken links, unknown\n  `type` values, missing optional fields) as a non-disableable error.\n\n## Install\n\n```sh\n# from source (requires a Rust toolchain)\ncargo install --path crates/okftool-cli\n# or, once published\ncargo install okftool-cli\n```\n\nPrebuilt binaries for macOS/Linux/Windows are attached to each\n[GitHub release](https://github.com/ryansann/okftool/releases).\n\n## Usage\n\n```sh\nokftool validate <bundle>      # §9 conformance only (exit 1 if non-conformant)\nokftool lint <bundle>          # spec + lint rules; --config, --format pretty|json|sarif\nokftool rules                  # list all rules by category\nokftool explain <rule>         # a rule's rationale, category, default severity\nokftool init [dir]             # scaffold a .okftool.yaml\nokftool build <bundle>         # package the bundle as <name>.tar.gz (-o, --prefix)\n```\n\n`lint` reads `<bundle>/.okftool.yaml` (or `--config`), else the `okf-recommended`\nprofile. Exit is non-zero on non-conformance or any diagnostic at/above\n`ci.fail-on` (default `error`). `--format sarif` emits SARIF 2.1.0 for inline\nGitHub PR annotations.\n\n## Package bundles\n\n`okftool build` creates a distributable `.tar.gz` from a bundle directory. By\ndefault it validates spec conformance first, then writes `<bundle>.tar.gz` with a\nsingle top-level directory inside the archive.\n\n```sh\nokftool build docs/okf\nokftool build docs/okf -o okftool-0.2.5.tar.gz --prefix okftool-0.2.5\n```\n\n## Rules & configuration\n\nokftool ships **28 lint rules** across seven categories (frontmatter,\ntype-vocabulary, linking, topology, graph-structure, body, index/log). `.okftool.yaml` selects a\nprofile with `extends`, sets per-rule severity/options, scopes rules with glob\n`overrides`, and gates CI with `ci.fail-on`. Concepts can opt out inline via an\n`okf-lint-disable` frontmatter list.\n\n```yaml\n# .okftool.yaml\nextends: okf-recommended           # or okf-strict / okf-minimal\nrules:\n  linking/no-dangling-links: warn          # off | info | warn | error\n  topology/max-out-degree: { severity: warn, options: { max: 20 } }\ngraph:\n  neighborhoods:\n    graph-authoring:\n      paths: [principles/local-neighborhoods.md, rules/graph-coherence.md]\nci:\n  fail-on: error\n```\n\nThe full format, every rule, and the **okf-recommended / okf-strict / okf-minimal**\nprofiles are documented in okftool's own OKF bundle (it dogfoods itself) — see\n[`docs/okf`](docs/okf), in particular\n[reference/configuration](docs/okf/reference/configuration.md),\n[reference/profiles](docs/okf/reference/profiles.md), and\n[reference/rules](docs/okf/reference/rules/index.md).\n\n## Develop\n\n```sh\nmake ci          # fmt + clippy + test + wasm build + dogfood lint\nmake lint-self   # lint okftool's own OKF docs bundle under the strict profile\nmake help        # list all targets\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for how to add a rule.\n\n## License\n\nLicensed under the [Apache License, Version 2.0](LICENSE).\n",
  "bytes": 4593,
  "sha": "90a4dbbd9a126f9bf4cdd51bcf630c0f93f0a2210900e6936cec87fef664ed20",
  "repo_slug": "ryansann/okftool",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_ryansann_okftool_docs_okf_index_md_a0f7efe0/readme"
}