Ferralk / Archive
Ferralk documentation
Start with the repository README: it says what Ferralk is for, how it compares with the crates you may already use, and shows the two quick-start examples. This directory holds the durable technical record, grouped by what you are trying to do.
Using Ferralk
Scroll sideways for more columns.
| Document | Use it for |
|---|---|
llms.txt | One screen for coding agents and hurried readers: the defaults, the three matcher entry points, the traps that compile but return wrong results, and links to the tested recipes. |
| Agent skill | The same guidance as a skill an agent can load: which crate for what, recipes, and traps. |
| Usage guide | Every walker default and the switch that changes it, the three matcher entry points, error handling, cancellation, and platform notes. Start here after the README. |
| 1.x stability contract | What 1.x promises: public API, corpus semantics, MSRV policy, Windows tier, and the explicit exclusions. |
| Consumer pattern contract | For a program that passes its users' globs to Ferralk: which pattern language 1.x covers per dialect and entry point, validating a pattern, escaping literal text, stable error information, and porting from globset. |
| Benchmark evidence | What is measured, how to reproduce it, what scoped queries mean, and how Ferralk compares with Rust, Node.js, and zlob libraries. |
| Palamedes adoption | A consumer integration measured over four releases on two real repositories, and which finding produced which change here. |
| Verification depth | How much checkable evidence stands behind the behavior, counted next to comparable crates, and where those counts mislead. |
Coming from another library
Scroll sideways for more columns.
| Document | Use it for |
|---|---|
| Compatibility guide | Migrating zlob 1.6.3 usage to the Ferralk API, a migration table for globset, glob, fast-glob, ignore, and walkdir, the deliberate differences, and the audit of every contract change since 0.9.0. |
| Compatibility matrix | A capability-by-capability status against zlob. |
| fast-glob reference | The pinned fast-glob reference and the divergences the differential fuzzer excludes by shape. |
Contributing
Scroll sideways for more columns.
| Document | Use it for |
|---|---|
| Contributing | The canonical preflight, commit conventions, how a performance claim is evidenced, and the 1.0 release checklist. |
| Corpus format | Maintaining or reviewing JSONL behavioral cases; the corpus is the source of truth for matcher and walker semantics. |
| Fuzzing | The parser, matcher, differential, and native-record fuzz targets and their seeds. |
| ADRs | Accepted architectural decisions and their consequences. They are constraints, not proposals. |
| Deferred follow-up | Platform state and the open work tracked in GitHub after the initial release. |
Historical record
Scroll sideways for more columns.
| Document | Use it for |
|---|---|
| Architecture RFC | The original design: full architecture, goals, and non-goals. Historical context; the ADRs record what was decided. |
| Frozen zlob reference | Upstream API and provenance baseline for the compatibility target. |
| zlob test-suite audit | Which upstream tests Ferralk replays and which are outside the two-crate Rust API. |
| zlob fnmatch test coverage | The line-addressable coverage boundary for the upstream matcher tests. |
The README, usage guide, compatibility matrix, and ADRs are the preferred references for current consumer and contributor decisions.