@recallnet/remark-lint-docs-freshness 0.2.2 → 0.2.3

package/README.md

@@ -2,9 +2,64 @@
 
 Checks Markdown frontmatter `reviewed` dates against policy-defined `max_age_days`.
 
-Use with `remark-frontmatter`:
+## Install
+
+```bash
+npm install -D remark remark-frontmatter @recallnet/remark-lint-docs-freshness
+```
+
+## Use
+
+Use with `remark-frontmatter` so YAML frontmatter is available to the rule:
 
 ```js
+import { remark } from "remark";
 import remarkFrontmatter from "remark-frontmatter";
 import remarkLintDocsFreshness from "@recallnet/remark-lint-docs-freshness";
+
+await remark()
+  .use(remarkFrontmatter)
+  .use(remarkLintDocsFreshness, {
+    cwd: process.cwd(),
+    policyPath: "./docs/docs-policy.json",
+  })
+  .process({
+    path: "docs/architecture/cache.md",
+    value: `---
+review_policy: periodic-7
+reviewed: 2026-03-01
+---
+
+# Cache`,
+  });
 ```
+
+## What It Checks
+
+- only files that match `in_scope_paths` in `docs/docs-policy.json`
+- only docs using periodic review policies
+- frontmatter `reviewed` values in `YYYY-MM-DD` format
+- whether `reviewed` is older than the policy's `max_age_days`
+
+The rule reports messages such as:
+
+```text
+Document is stale: reviewed=2026-03-01 age_days=18 max_age_days=7.
+```
+
+## Options
+
+- `cwd`
+  Repository root used to resolve the docs policy and the current file path.
+- `policyPath`
+  Path to the docs policy file relative to `cwd`.
+  Defaults to `docs/docs-policy.json`.
+- `today`
+  Override the current date as `YYYY-MM-DD`.
+  Useful for deterministic tests.
+
+## Notes
+
+- Docs with non-periodic policies such as `historical` are ignored.
+- If frontmatter is missing or unreadable for an in-scope file, the rule reports that freshness could not be checked.
+- This package is intended for docs-governance setups that keep freshness policy in repo config rather than hardcoding date thresholds in lint config.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recallnet/remark-lint-docs-freshness",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Remark plugin that checks docs reviewed dates against repo policy.",
   "license": "MIT",
   "type": "module",
@@ -26,7 +26,7 @@
   ],
   "dependencies": {
     "yaml": "^2.8.3",
-    "@recallnet/docs-governance-policy": "0.2.2"
+    "@recallnet/docs-governance-policy": "0.2.3"
   },
   "peerDependencies": {
     "remark-frontmatter": "^5.0.0"