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

package/README.md

@@ -2,9 +2,65 @@
 
 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.
+- Frontmatter parsing uses `vfile-matter`, which is the unified-recommended way to expose YAML metadata on `file.data.matter`.
+- 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.4",
   "description": "Remark plugin that checks docs reviewed dates against repo policy.",
   "license": "MIT",
   "type": "module",
@@ -25,8 +25,8 @@
     "src"
   ],
   "dependencies": {
-    "yaml": "^2.8.3",
-    "@recallnet/docs-governance-policy": "0.2.2"
+    "vfile-matter": "^5.0.1",
+    "@recallnet/docs-governance-policy": "0.2.3"
   },
   "peerDependencies": {
     "remark-frontmatter": "^5.0.0"

package/src/index.js

@@ -9,24 +9,10 @@ import {
   resolveDocsReviewPolicy,
   resolveReviewPolicyConfig,
 } from "@recallnet/docs-governance-policy";
-import { parse } from "yaml";
+import { matter } from "vfile-matter";
 
 const RULE_ID = "docs-freshness";
 
-function findYamlNode(tree) {
-  return tree?.children?.find((node) => node.type === "yaml") ?? null;
-}
-
-function parseFrontmatter(tree) {
-  const yamlNode = findYamlNode(tree);
-  if (!yamlNode?.value) {
-    return null;
-  }
-
-  const data = parse(String(yamlNode.value));
-  return data && typeof data === "object" && !Array.isArray(data) ? data : null;
-}
-
 function dateDiffDays(older, newer) {
   const olderMs = new Date(`${older}T00:00:00Z`).getTime();
   const newerMs = new Date(`${newer}T00:00:00Z`).getTime();
@@ -58,8 +44,13 @@ export default function remarkLintDocsFreshness(options = {}) {
       return;
     }
 
-    const frontmatter = parseFrontmatter(tree);
-    if (!frontmatter) {
+    matter(file);
+    const frontmatter =
+      file.data.matter && typeof file.data.matter === "object" && !Array.isArray(file.data.matter)
+        ? file.data.matter
+        : null;
+
+    if (!frontmatter || Object.keys(frontmatter).length === 0) {
       file.message("Document freshness could not be checked because frontmatter is unreadable.", {
         ruleId: RULE_ID,
         source: "@recallnet/remark-lint-docs-freshness",