okf-kit 0.8.0 → 0.10.0

package/dist/util.js

@@ -47,4 +47,76 @@ export function getTimestampEpoch(parsed) {
         return undefined;
     return Math.floor(ms / 1000);
 }
+/**
+ * The frontmatter `timestamp`'s raw string form, or undefined when it is
+ * absent, blank, or not a string -- notably, a native `Date` instance (see
+ * `getTimestampEpoch`'s doc comment) returns undefined here too, since a
+ * `Date`'s `getTime()` is always UTC-unambiguous and carries none of the
+ * local-timezone risk `hasUtcDesignator` exists to catch. Used only by
+ * `sources-fresh-future`'s UTC-designator gate; `sources-fresh` itself has
+ * no need for the raw string, only the resolved epoch.
+ */
+export function getRawTimestampString(parsed) {
+    if (!isRecord(parsed))
+        return undefined;
+    const timestamp = parsed.timestamp;
+    if (typeof timestamp !== "string" || timestamp.trim() === "")
+        return undefined;
+    return timestamp;
+}
+/**
+ * Whether an ISO-ish timestamp string carries an explicit UTC designator
+ * (`Z`) or a numeric UTC offset (`+02:00`, `-0500`) at its end. A timestamp
+ * with neither ("2026-01-01T00:00:00", "2026-01-01 00:00:00") parses in
+ * the machine's LOCAL timezone under `Date.parse`, which would make
+ * `sources-fresh-future`'s clock-skew comparison swing by hours depending
+ * on which machine runs the check -- not usable for a check whose default
+ * allowance is only 10 minutes. A numeric offset, unlike a bare local
+ * time, is unambiguous: `Date.parse`/`Date#getTime()` already normalizes
+ * it to a real UTC instant, so no extra conversion is needed here beyond
+ * recognizing it as present. `sources-fresh`'s own thresholds are in
+ * days, wide enough that this ambiguity doesn't practically matter there,
+ * so this helper is deliberately NOT applied to that rule's comparison.
+ */
+export function hasUtcDesignator(raw) {
+    return /(?:Z|[+-]\d{2}:?\d{2})$/i.test(raw.trim());
+}
+/**
+ * A canonical identity string for the frontmatter `timestamp` VALUE, or
+ * undefined when the key is absent, blank, or not a scalar this tool
+ * understands. Two docs (or two revisions of one doc) are "stamped the same"
+ * iff this returns the same value for both.
+ *
+ * Used by `sources-fresh` to decide whether a commit actually re-stamped a
+ * doc, by comparing the doc's frontmatter at that commit against its
+ * frontmatter in the commit's first parent. Comparing VALUES, not diff text,
+ * is what makes the test immune to the three shapes a diff-text scan gets
+ * wrong: a `timestamp:` line inside a fenced YAML example in the doc BODY (it
+ * is not the frontmatter key, so it never reaches this function at all), a
+ * rename (the two revisions are read by path, not from a diff header), and a
+ * merge commit (whose combined-diff output is empty while its trees are
+ * perfectly readable).
+ *
+ * The `date:`/`string:` prefixes keep the two YAML shapes distinguishable: a
+ * `!!timestamp`-tagged scalar resolving to a native `Date` and a plain string
+ * are different frontmatter, so rewriting one into the other counts as a
+ * re-stamp rather than silently comparing equal. Deliberately NOT normalized
+ * to an epoch: this is an identity test ("did the value change"), not a
+ * chronological one, so re-writing `2026-01-01T00:00:00Z` as
+ * `2026-01-01T00:00:00+00:00` counts as a re-stamp -- the author touched the
+ * stamp. Whether the new value is CORRECT is a separate question this
+ * function deliberately does not answer (see the README's known limitations).
+ */
+export function getTimestampIdentity(parsed) {
+    if (!isRecord(parsed))
+        return undefined;
+    const timestamp = parsed.timestamp;
+    if (timestamp instanceof Date) {
+        const ms = timestamp.getTime();
+        return Number.isNaN(ms) ? undefined : `date:${ms}`;
+    }
+    if (typeof timestamp !== "string" || timestamp.trim() === "")
+        return undefined;
+    return `string:${timestamp.trim()}`;
+}
 //# sourceMappingURL=util.js.map

package/dist/util.js.map

@@ -1 +1 @@
-{"version":3,"file":"util.js","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,aAAa,CAAC,MAAe;IAC3C,OAAO,QAAQ,CAAC,MAAM,CAAC,IAAI,SAAS,IAAI,MAAM,CAAC;AACjD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,MAAe;IAC7C,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IAC7C,MAAM,OAAO,GAAI,MAAkC,CAAC,OAAO,CAAC;IAC5D,MAAM,YAAY,GAChB,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QACtB,OAAO,CAAC,MAAM,GAAG,CAAC;QAClB,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACjE,OAAO,YAAY,CAAC,CAAC,CAAE,OAAoB,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAe;IAC/C,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;IACnC,IAAI,SAAS,YAAY,IAAI,EAAE,CAAC;QAC9B,MAAM,EAAE,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC;QAC/B,OAAO,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;IAC9D,CAAC;IACD,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE;QAC1D,OAAO,SAAS,CAAC;IACnB,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACjC,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAAE,OAAO,SAAS,CAAC;IACvC,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;AAC/B,CAAC"}
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okf-kit",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "CLI that validates OKF v0.1 knowledge bundles for structural correctness",
   "type": "module",
   "bin": {
@@ -38,7 +38,7 @@
   },
   "dependencies": {
     "commander": "^12.0.0",
-    "yaml": "^2.5.0"
+    "yaml": "^2.8.3"
   },
   "devDependencies": {
     "@types/node": "^20.11.0",