openbriefing 0.0.1 → 0.1.0

package/README.md

@@ -1,5 +1,39 @@
 # openbriefing
 
-Tools for the [Open Briefing Standard (OBS)](https://openbriefingstandard.org). OBS is how a publisher states how their content should be summarized and presented when software consumes it.
+This package is the reference parser and checker for the [Open Briefing Standard (OBS)](https://openbriefingstandard.org). OBS is how a publisher says how their content should be summarized and presented when software consumes it.
 
-**This is a draft placeholder.** Version 1.0.0 will include the reference parser and the `openbriefing` command, with `check`, `generate`, `preview`, `backfill`, `review` and a Ghost integration. Follow progress at [github.com/OpenBriefing/openbriefing](https://github.com/OpenBriefing/openbriefing).
+**Version 0.1.** It contains the parser and `openbriefing check`. Later versions add `generate`, `preview`, `backfill`, `review` and a Ghost integration.
+
+## Check a page or a feed
+
+```bash
+npx openbriefing check ./post.html
+npx openbriefing check ./feed.xml
+curl -s https://example.com/post/ | npx openbriefing check - --url https://example.com/post/
+```
+
+`check` exits 1 when the tags are unusable, so a site's CI can gate on it. Add `--json` to get the parsed result as JSON.
+
+## Use the parser
+
+```ts
+import { JSDOM } from "jsdom";
+import { parseObs } from "openbriefing";
+
+const dom = new JSDOM(html, { url });
+const { brief, errors, warnings } = parseObs(dom.window.document, url);
+```
+
+| Export | What it does |
+|--------|--------------|
+| `parseObs(document, pageUrl)` | Reads a page's `obs:` meta tags |
+| `parseFeedObs(itemElement, itemUrl?)` | Reads one RSS `<item>` or Atom `<entry>` |
+| `validateObs(object)` | Checks an object already in the `ObsBrief` shape |
+| `mergeObs(page, feed)` | Applies the feed-against-page rule: the later `obs:modified` stands, and the page wins a tie |
+| `tierFor(words)`, `SIZES`, `normalizeUrl` | Helpers that use the spec's numbers |
+
+The parser has no runtime dependencies. It takes any DOM `Document` (jsdom, linkedom, or a browser's `DOMParser`), makes no network requests, and never throws.
+
+The test fixtures ship with the package in `openbriefing/fixtures/`, with `expected.json`.
+
+MIT licence. The spec is dedicated to the public domain (CC0).

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * openbriefing check <file | -> [--url <page url>] [--json]
+ *
+ * Checks a local HTML page or an RSS/Atom feed for Open Briefing Standard
+ * tags and prints what a reader sees. Exits 1 when the tags are unusable.
+ * Version 0.1 reads local files and standard input only; it makes no
+ * network requests.
+ */
+import { readFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { JSDOM } from "jsdom";
+import { countWords, parseFeedObs, parseObs, SIZES } from "./obs.js";
+const USAGE = `Usage: openbriefing check <file | -> [--url <page url>] [--json]
+
+Checks a page or a feed for Open Briefing Standard tags.
+  --url   the page's address, used when the page has no canonical link
+  --json  print the parsed result as JSON
+Spec: https://openbriefingstandard.org`;
+function parseArgs(argv) {
+    const args = { json: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--json")
+            args.json = true;
+        else if (a === "--url")
+            args.url = argv[++i];
+        else if (a === "-h" || a === "--help")
+            args.command = "help";
+        else if (args.command === undefined)
+            args.command = a;
+        else if (args.file === undefined)
+            args.file = a;
+    }
+    return args;
+}
+function readInput(file) {
+    return file === "-" ? readFileSync(0, "utf8") : readFileSync(file, "utf8");
+}
+function isFeed(text, file) {
+    if (/\.(xml|rss|atom)$/iu.test(file))
+        return true;
+    const head = text.slice(0, 500).trimStart();
+    return head.startsWith("<?xml") ? /<(rss|feed)\b/iu.test(text.slice(0, 2000)) : /^<(rss|feed)\b/iu.test(head);
+}
+/** Page text is untrusted: show control characters (ANSI escapes and the like) instead of sending them to the terminal. */
+const safe = (s) => s.replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/gu, (c) => `\\x${c.charCodeAt(0).toString(16).padStart(2, "0")}`);
+const cut = (s, n = 60) => safe((s.length > n ? `${s.slice(0, n - 1)}…` : s).replace(/\n/gu, " "));
+function describe(label, r) {
+    const lines = [safe(label)];
+    const b = r.brief;
+    if (b) {
+        const row = (k, v) => lines.push(`  ${k.padEnd(12)} ${v}`);
+        if (b.title !== undefined)
+            row("title", `${cut(b.title)}  (${countWords(b.title)}/${SIZES.title} words)`);
+        if (b.headline !== undefined)
+            row("headline", `${cut(b.headline)}  (${countWords(b.headline)}/${SIZES.headline} words)`);
+        for (const s of b.summaries) {
+            const [lo, hi] = SIZES.tiers[s.tier].target;
+            row(`summary`, `${s.tier.padEnd(6)} ${String(s.words).padStart(5)} words  (target ${lo}–${hi})  ${s.from}`);
+        }
+        b.keep.forEach((k, i) => row(i === 0 ? "keep (core)" : `keep ${i + 1}`, cut(k)));
+        row("derive", `${b.derive.mode}; translate ${b.derive.translate ? "yes" : "no"}; combine ${b.derive.combine ? "yes" : "no"}`);
+        if (b.attribution !== undefined)
+            row("attribution", cut(b.attribution));
+        row("preference", b.preference);
+        if (b.lang !== undefined)
+            row("lang", safe(b.lang));
+        row("modified", safe(b.modified));
+        if (b.url !== undefined)
+            row("url", `${safe(b.url)}${b.describesThisPage ? "" : "  (describes another page)"}`);
+    }
+    for (const e of r.errors)
+        lines.push(`  error    ${safe(e)}`);
+    for (const w of r.warnings)
+        lines.push(`  warning  ${safe(w)}`);
+    lines.push(b ? `  ok: usable, ${r.warnings.length} warning${r.warnings.length === 1 ? "" : "s"}` : "  not usable");
+    return lines.join("\n");
+}
+function check(args) {
+    if (!args.file) {
+        console.error(USAGE);
+        return 2;
+    }
+    let text;
+    try {
+        text = readInput(args.file);
+    }
+    catch (err) {
+        console.error(`Cannot read ${args.file}: ${err instanceof Error ? err.message : String(err)}`);
+        return 2;
+    }
+    const pageUrl = args.url ?? (args.file === "-" ? "https://localhost/" : pathToFileURL(resolve(args.file)).href);
+    const label = args.file === "-" ? "(standard input)" : basename(args.file);
+    if (isFeed(text, args.file)) {
+        const doc = new JSDOM(text, { contentType: "text/xml" }).window.document;
+        const items = [...Array.from(doc.getElementsByTagName("item")), ...Array.from(doc.getElementsByTagName("entry"))];
+        const results = items.map((item) => parseFeedObs(item));
+        if (args.json)
+            console.log(JSON.stringify(results, null, 2));
+        else
+            results.forEach((r, i) => console.log(describe(`${label}, item ${i + 1}`, r)));
+        if (items.length === 0) {
+            if (!args.json)
+                console.log(`${label}\n  not usable: no <item> or <entry> elements`);
+            return 1;
+        }
+        return results.every((r) => r.brief) ? 0 : 1;
+    }
+    const doc = new JSDOM(text, { url: pageUrl }).window.document;
+    const r = parseObs(doc, pageUrl);
+    console.log(args.json ? JSON.stringify(r, null, 2) : describe(label, r));
+    return r.brief ? 0 : 1;
+}
+function main(argv) {
+    const args = parseArgs(argv);
+    if (args.command === "check")
+        return check(args);
+    console.error(USAGE);
+    return args.command === "help" ? 0 : 2;
+}
+process.exitCode = main(process.argv.slice(2));

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./obs.js";

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./obs.js";

package/dist/obs.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The Open Briefing Standard, version 1: reference parser.
+ *
+ * Self-contained: no runtime imports. It reads a DOM `Document` or `Element`
+ * (jsdom on a server, DOMParser in a browser) and never touches the network.
+ * Every function here returns a result rather than throwing.
+ *
+ * Section numbers in comments refer to spec/v1.md.
+ */
+export declare const OBS_NS = "https://openbriefingstandard.org/ns#";
+export type ObsTier = "short" | "medium" | "long";
+export type DeriveMode = "verbatim" | "anchor" | "open";
+export type Preference = "summary" | "full";
+export interface ObsSummary {
+    tier: ObsTier;
+    text: string;
+    words: number;
+    /** "tiered" for obs:summary:{tier}; "inferred" for a bare obs:summary (§4). */
+    from: "tiered" | "inferred";
+}
+export interface ObsBrief {
+    version: number;
+    /** obs:modified, as given (ISO 8601). */
+    modified: string;
+    /** obs:url, normalized, when given. */
+    url?: string;
+    /** False when obs:url names content other than this page (§11). */
+    describesThisPage: boolean;
+    title?: string;
+    headline?: string;
+    /** Short to long, at most one per tier, at least one. */
+    summaries: ObsSummary[];
+    /** Priority order, at most 3. keep[0] is the core message (§6). */
+    keep: string[];
+    derive: {
+        mode: DeriveMode;
+        translate: boolean;
+        combine: boolean;
+    };
+    attribution?: string;
+    preference: Preference;
+    lang?: string;
+}
+export interface ParseResult {
+    /** Absent when nothing usable was found. */
+    brief?: ObsBrief;
+    /** Why the tags are unusable. */
+    errors: string[];
+    /** Usable, but something is off. */
+    warnings: string[];
+}
+/** Sizes from §4, exported so tools show the same numbers. */
+export declare const SIZES: {
+    readonly title: 12;
+    readonly headline: 40;
+    readonly keep: 40;
+    readonly attribution: 12;
+    readonly keepMax: 3;
+    readonly tiers: Record<ObsTier, {
+        target: [number, number];
+    }>;
+    readonly bands: {
+        readonly shortMax: 120;
+        readonly mediumMax: 500;
+    };
+};
+/** The tier for a word count, by the bands in §4. */
+export declare function tierFor(words: number): ObsTier;
+/** Words are runs of characters between white space (§4). */
+export declare function countWords(text: string): number;
+/** URL comparison of §11: scheme and host case, trailing slash, tracking parameters. */
+export declare function normalizeUrl(input: string, base?: string): string | undefined;
+/**
+ * Reads a page's obs: meta tags. `pageUrl` is where the page was fetched
+ * from; the page's <link rel="canonical"> takes precedence for §11.
+ */
+export declare function parseObs(doc: Document, pageUrl: string): ParseResult;
+/**
+ * Reads the OBS elements of one RSS <item> or Atom <entry>. `itemUrl`
+ * overrides the item's own link when given.
+ */
+export declare function parseFeedObs(item: Element, itemUrl?: string): ParseResult;
+/** Checks an object in the ObsBrief shape and rebuilds it under the same rules. */
+export declare function validateObs(input: unknown): ParseResult;
+/** The later obs:modified stands; on a tie, the page stands. */
+export declare function mergeObs(page?: ObsBrief, feed?: ObsBrief): ObsBrief | undefined;