Skip to content

✨ feat(analyze): report nodes past their §5.5 stale_after - #15

Open
LGuichet wants to merge 1 commit into
nextfrom
feat/analyze-expired
Open

LGuichet wants to merge 1 commit into
nextfrom
feat/analyze-expired

Conversation

@LGuichet

@LGuichet LGuichet commented Nov 4, 2026 •

Copy link
Copy Markdown
Owner

Summary

okfctl analyze now warns about every node whose §5.5 stale_after date has passed, so a bundle's declared recheck dates surface in the curation report instead of being parsed and ignored.

analyze report

  • New freshness.expired list: one {path, stale_after} entry per node where now >= stale_after (§5.5), printed as "Freshness — past stale_after (§5.5, recheck)". It needs no threshold, because the producer chose the date.
  • Still a report, not a gate: analyze exits 0 as before. No validate or lint rule is added, so a date passing never turns lint --strict red with no change to the bundle (§11: everything beyond the floor is soft guidance).
  • Silent when absent or unparseable: an optional key never fails a bundle (§11), and next quarter carries no instant to compare.

okf (internal/okf/)

  • analyze.go: adds ExpiredNode and FreshnessReport.Expired, fills it from the existing Node.IsStale, and normalises it to [] like stale and time_sensitive.
  • Tests: analyze_expired_test.go covers a past date (listed, with its value, and kept out of the age-based stale list), the exact instant (listed, per >=), negatives (future, one second ahead, absent, unparseable) and the JSON shape ("expired":[]).

cmd (cmd/)

  • analyze.go: prints the new section in the human report.
  • Tests: analyze_test.go adds TestAnalyzeCmd_ExpiredStaleAfter_Section5_5, which checks the past node in both human and JSON output, the future node absent, and exit 0.

docs

  • 2026-11-04-analyze-expired-stale-after.md (docs/specs/): the problem, the decision (report, not gate) and the controls.
  • CHANGELOG.md: Unreleased / Added entry.

Evidence

Spec: upstream GoogleCloudPlatform/open-knowledge-format SPEC.md, header confirmed **Version 0.2**. Sections cited:

  • §5.5: stale_after is optional, and a concept is stale when now >= stale_after.

  • §11: consumers SHOULD derive staleness only from the fields specified, and treat other constraints as soft guidance.

  • Before: Node.IsStale existed, with conformance tests, but no command called it. A node generated yesterday with stale_after last month appeared in no list.
    After: that node is listed under freshness.expired and nowhere else.

Gate layer 1: go test ./internal/okf/ ./cmd/ -run Conformance, both packages ok.

Gate layer 2:

  • gofmt -l . is empty and go vet ./... is clean.
  • go test ./... has 15 failures, all Windows-only and all outside this change: plugin install and discovery, dispatch, node edit with $EDITOR, and git clone/pull. The same 15 fail on fork/next without this change.
  • go test ./... -race in CI's build-test job (Linux): every package ok, including the 15 Windows-only tests that fail locally. It wasn't run locally, because the Windows machine has no C compiler.

Gate layer 3, real corpus: the four market-fr bundles, base binary vs this branch.

bundle validate FAIL lint --strict stale time-sensitive expired
ifpos-interface-cases 0 → 0 0 → 0 0 → 0 0 → 0 n/a → 0
middleware 0 → 0 0 → 0 0 → 0 0 → 0 n/a → 0
nf525-lne 0 → 0 2 → 2 0 → 0 0 → 0 n/a → 0
plateforme-agree 0 → 0 1 → 1 0 → 0 0 → 0 n/a → 0

The only stale_after in the corpus is in the future (2027-03-31), so expired is 0 everywhere. Positive control on a copy of nf525-lne: backdating one concept to an instant (2026-01-01T00:00:00Z) and another in the corpus's date-only form (2026-03-31) lists exactly those two, and validate still prints OK.

v0.1 bundle: legacy timestamp, a body # Citations list, one past and one future stale_after.

  • validate prints OK with both binaries.
  • The age-based stale list is identical (none).
  • Only the past-dated node is listed as expired.

Merge Danger

Door: two-way

Blast Radius: analyze output

  • analyze --json gains a freshness.expired key. A consumer that decodes into a strict schema with unknown keys rejected would need the field. Existing keys are unchanged.
  • The human report gains one section, after the time-sensitive one.

Not in this PR: a lint check for passed stale_after (deliberately left out, see above), and any change to how the age-based stale list is computed.

okfctl parsed stale_after (Node.StaleAfter, Node.IsStale) but no command
reported it, and the age-based freshness signals can't see a declared
expiry on a recently generated node. analyze now lists every node with
now >= stale_after in freshness.expired ({path, stale_after}, always an
array) and a "past stale_after" section of the human report.

It stays a report entry: analyze exits 0, and no validate or lint rule is
added, so a date passing never turns a gate red (§11 soft guidance). An
absent or unparseable stale_after is silent.
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