Skip to content

Adds a guide to compiling and evaluating a rule - #209

Merged
johnnyt merged 1 commit into
mainfrom
pts-3rn1-how-to-compile-and-evaluate
Oct 5, 2026
Merged

johnnyt merged 1 commit into
mainfrom
pts-3rn1-how-to-compile-and-evaluate

Conversation

@johnnyt

@johnnyt johnnyt commented Oct 5, 2026

Copy link
Copy Markdown
Member

Why

The package had no task page for the first thing a developer does with it:
compile a rule's text, keep the instruction list, and decide the rule for a
given context. The README's sections on compiling and evaluating are
reference by example; this adds the recipe.

What

  • A how-to page, "How to compile and evaluate a rule", under docs/guides/.
    It states the goal and the starting point, then numbered steps in three
    stages (compile, keep the list, evaluate), each step with the result it
    shows. Its example is a library loan: a copy counts as lost when its loan
    is more than thirty days overdue and the copy is still checked out.
  • One line in the README's Documentation map, under Do, linking the page by
    its absolute GitHub URL (docs/ is not in the published package's
    files, so a relative link would not resolve on npm).

No README text is replaced: the "Compiling a rule" and "Evaluating a rule"
sections stay as the reference the page links to. No file under src/
changes, and no changelog fragment is written (changelog.d/README.md
excludes documentation).

Notes

  • Source material: the docs audit named no span for this subject, so the page
    is written from the package's own type declarations and the README's
    "Compiling a rule", "Evaluating a rule" and "The tagged subpath" sections.
  • Every result the page states was checked against the source on this branch
    by running the page's snippets together (the instruction-list prefix, the
    JSON text, both decisions, the compile refusal's reason and position, and
    the unbound-variable refusal), and the snippets typecheck together under
    strict settings. The page is not executed by test/readme.test.ts, which
    reads the README only.
  • The plain-JSON branch: a date literal and a float lose their type through
    JSON.stringify, and encodeTagged / decodeTagged round-trip the same
    list, which then evaluates; the page says so in one sentence and links the
    tagged subpath.
  • README linter: README.md: 1168 lines, every part present.
  • Gate: the full gate (mise exec -- pnpm run gate) ran green on this head;
    README.md is in gate.also_gated_paths, so the docs-only carve-out does
    not apply.
  • Review: no review agents are declared for this repository; the author's
    own review round checked the page against the how-to rules (goal title,
    starting point, numbered steps each with a visible result, nothing taught
    beyond one sentence a step) and the repository's example-world rule.

Closes pts-3rn1

A how-to page under docs/guides: compile a rule's text, keep the
instruction list as JSON (or the tagged encoding when it carries a
date, a datetime or a float), and evaluate it for one loan, with the
result each step shows. The README's Documentation map links it under
Do.

Refs: pts-3rn1
@johnnyt
johnnyt merged commit f5c688e into main Oct 5, 2026
1 check passed
@johnnyt
johnnyt deleted the pts-3rn1-how-to-compile-and-evaluate branch October 5, 2026 11:29
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.

1 participant