meodp 0.0.9 → 0.2.0

package/dist/check/cli.mjs

@@ -0,0 +1,249 @@
+import { readFile, realpath } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import { resolve, join, extname } from 'node:path';
+import process from 'node:process';
+import { parseArgs } from 'node:util';
+import { load } from 'js-yaml';
+import { l as loadProjectConfig } from '../shared/meodp.f96d0510.mjs';
+import { p as planReporters, c as checkSitemap, a as checkLinks, w as writeReporters, n as normalizeTargets, b as waitForReport } from '../shared/meodp.80ff918d.mjs';
+import { r as readReport, s as saveReport } from '../shared/meodp.9c706389.mjs';
+import 'c12';
+import 'node:timers/promises';
+import 'linkinator';
+import 'node:buffer';
+import 'node:zlib';
+import 'fast-xml-parser';
+import 'node:crypto';
+
+const help = `Usage: meodp check <links.json|links.yml> [options]
+
+Check only the listed HTTP(S) URLs, with no browser or recursive resource scan.
+Input: an array of URL strings or objects with url and optional name.
+This makes network requests. To render saved data instead, use meodp report.
+
+  --config <file>      Load a project config (default: meodp.config.ts)
+  --output <directory>  Default report directory (default: reports/meodp)
+  --reporter <names>    json, markdown, html; comma-separated or repeated
+                       Without a selection, write report.json, report.md, report.html
+  --history <file>      Read previous observations and save the completed report
+  --observer <name>     Identify this network/environment (default: hostname)
+  --concurrency <n>     Concurrent sites (default: 5)
+  --timeout <ms>        Timeout per HTTP request (default: 10000)
+  --retries <n>         Retries for transport/5xx failures (default: 1)
+  --max-redirects <n>   Follow at most n redirects (default: 5)
+  --fail-on <policy>    unavailable (default), review, or none
+  -h, --help           Show this help
+
+Exit codes: 0 = policy passed; 1 = findings match --fail-on; 2 = input/execution error.
+Restricted results and redirects require review; they do not prove a dead site.
+`;
+async function runCheckCli(args = process.argv.slice(3)) {
+  return runScanCli("links", args);
+}
+async function runSitemapCli(args = process.argv.slice(3)) {
+  return runScanCli("sitemap", args);
+}
+async function runScanCli(mode, args) {
+  try {
+    const { values, positionals } = parseArgs({
+      args,
+      allowPositionals: true,
+      options: {
+        "config": { type: "string" },
+        "reporter": { type: "string", multiple: true },
+        "output": { type: "string" },
+        "history": { type: "string" },
+        "observer": { type: "string" },
+        "concurrency": { type: "string" },
+        "timeout": { type: "string" },
+        "retries": { type: "string" },
+        "max-redirects": { type: "string" },
+        "fail-on": { type: "string" },
+        "help": { type: "boolean", short: "h" },
+        ...mode === "sitemap" ? {
+          "discover": { type: "boolean" },
+          "max-urls": { type: "string" },
+          "max-sitemaps": { type: "string" },
+          "max-sitemap-bytes": { type: "string" }
+        } : {}
+      }
+    });
+    if (values.help) {
+      console.log(mode === "links" ? help : `Usage: meodp sitemap <sitemap-url> [options]
+
+Read an XML sitemap or nested index, then check each listed page via HTTP.
+  --discover            Treat the URL as a site: read robots.txt or /sitemap.xml
+  --max-urls <n>         Reject discovery above n unique pages (default: 10000)
+  --max-sitemaps <n>     Limit sitemap documents (default: 100)
+  --max-sitemap-bytes <n> Limit each downloaded/decompressed document (default: 10485760)
+
+${help.slice(help.indexOf("  --config"))}`);
+      return 0;
+    }
+    const project = await loadProjectConfig(values.config);
+    const configured = (mode === "links" ? project.config.check : project.config.sitemap) ?? {};
+    const input = positionals[0] ?? (configured.input ? mode === "links" ? project.path(configured.input) : configured.input : void 0);
+    if (!input || positionals.length > 1)
+      throw new Error(`Provide exactly one ${mode === "links" ? "JSON or YAML input file" : "HTTP(S) URL"}. Use --help for examples.`);
+    const selection = selectReporters(values.reporter, configured.reporter ?? project.config.reporter);
+    const outputDir = resolve(values.output ?? (configured.output ? project.path(configured.output) : "reports/meodp"));
+    const reporterOptions = { outputDir, cwd: project.path(".") };
+    const reporter = typeof selection === "string" ? [selection] : [...selection ?? ["json", "markdown", ["html", { outputFile: join(outputDir, "report.html") }]]];
+    if (configured.site)
+      reporter.push(["html", { outputFolder: project.path(configured.site) }]);
+    const plan = planReporters(reporter, reporterOptions);
+    const failOn = values["fail-on"] ?? configured.failOn ?? "unavailable";
+    if (!["none", "unavailable", "review"].includes(failOn))
+      throw new Error("--fail-on must be none, unavailable, or review");
+    const numeric = (value) => typeof value === "string" ? Number(value) : void 0;
+    const history = values.history ?? (configured.history ? project.path(configured.history) : void 0);
+    const seed = configured.historySeed ? project.path(configured.historySeed) : void 0;
+    await protectInputs(plan, [
+      ...mode === "links" ? [{ file: input, jsonOnly: false }] : [],
+      ...[history, seed].filter((file) => !!file).map((file) => ({ file, jsonOnly: true }))
+    ], history);
+    let previousReport = history ? await readReport(history) : void 0;
+    if (!previousReport && seed)
+      previousReport = await readReport(seed);
+    const observer = values.observer ?? configured.observer;
+    if (previousReport && configured.observerMismatch === "reset" && previousReport.observer !== (observer ?? hostname()))
+      previousReport = void 0;
+    const options = {
+      observer,
+      previousReport,
+      concurrency: numeric(values.concurrency) ?? configured.concurrency,
+      timeoutMs: numeric(values.timeout) ?? configured.timeoutMs,
+      retries: numeric(values.retries) ?? configured.retries,
+      maxRedirects: numeric(values["max-redirects"]) ?? configured.maxRedirects,
+      onResult(result) {
+        console.log(`[${result.status}] ${result.httpStatus ?? result.reason} ${result.url}`);
+      }
+    };
+    const report = mode === "sitemap" ? await checkSitemap(input, {
+      ...options,
+      discover: values.discover === void 0 ? configured.discover : values.discover === true,
+      maxUrls: numeric(values["max-urls"]) ?? configured.maxUrls,
+      maxSitemaps: numeric(values["max-sitemaps"]) ?? configured.maxSitemaps,
+      maxSitemapBytes: numeric(values["max-sitemap-bytes"]) ?? configured.maxSitemapBytes
+    }) : await checkLinks(await readTargets(input), options);
+    const outputs = await writeReporters(report, reporter, reporterOptions);
+    for (const output of outputs)
+      console.log(`${output.reporter}: ${output.files.join(", ")}`);
+    if (history)
+      await saveReport(report, history);
+    console.log(`${report.summary.total} URLs: ${report.summary.reachable} reachable, ${report.summary.restricted} restricted, ${report.summary.unavailable} unavailable`);
+    if (failOn === "none")
+      return 0;
+    const findings = report.summary.unavailable > 0 || failOn === "review" && (report.summary.restricted > 0 || report.summary.redirected > 0);
+    return findings ? 1 : 0;
+  } catch (error) {
+    console.error(`meodp ${mode === "links" ? "check" : "sitemap"}: ${error instanceof Error ? error.message : String(error)}`);
+    return 2;
+  }
+}
+async function readTargets(input) {
+  const extension = extname(input).toLowerCase();
+  if (![".json", ".yml", ".yaml"].includes(extension))
+    throw new Error("Input file must use .json, .yml, or .yaml");
+  const source = await readFile(input, "utf8");
+  return normalizeTargets(extension === ".json" ? JSON.parse(source) : load(source));
+}
+async function runReportCli(args = process.argv.slice(3)) {
+  try {
+    const { values, positionals } = parseArgs({
+      args,
+      allowPositionals: true,
+      options: {
+        "config": { type: "string" },
+        "reporter": { type: "string", multiple: true },
+        "verify": { type: "boolean" },
+        "output": { type: "string" },
+        "data-url": { type: "string" },
+        "help": { type: "boolean", short: "h" }
+      }
+    });
+    if (values.help) {
+      console.log(`Usage: meodp report [report.json] [--reporter json,markdown,html] [--output reports/site]
+
+Render saved data through selected reporters without making any site-check requests.
+--reporter accepts json, markdown, html; repeat it or separate names with commas.
+With no configured selection, export the HTML static viewer.
+HTML folders with input write index.html and report.json. The hosted viewer loads
+report.json on each visit; opening index.html as a local file uses its embedded snapshot.
+Without input, only HTML is available: an empty viewer with file upload and URL loading.
+--config loads a project config; CLI arguments override config values.
+--verify waits for report.verify.url to serve this report and the matching viewer.
+--data-url overrides the data source loaded by the hosted viewer (cross-origin needs CORS).
+-h, --help shows this help. To collect fresh observations, use meodp check.
+Exit codes: 0 = exported; 2 = invalid input or execution error.`);
+      return 0;
+    }
+    if (positionals.length > 1)
+      throw new Error("Provide at most one report.json file. Use --help for examples.");
+    const project = await loadProjectConfig(values.config);
+    const configured = project.config.report ?? {};
+    const input = positionals[0] ?? (configured.input ? project.path(configured.input) : void 0);
+    const report = input ? await readReport(input) : void 0;
+    if (input && !report)
+      throw new Error(`Report not found: ${input}`);
+    const reporter = selectReporters(values.reporter, configured.reporter ?? project.config.reporter) ?? "html";
+    if (values.verify) {
+      if (!report || !configured.verify)
+        throw new Error("Verification requires a saved report and report.verify.url in the config.");
+      await waitForReport(report, configured.verify);
+      console.log("The public status page is serving the expected report.");
+      return 0;
+    }
+    const selected = values["data-url"] === void 0 ? reporter : (typeof reporter === "string" ? [reporter] : reporter).map((entry) => {
+      const [name, options] = typeof entry === "string" ? [entry] : entry;
+      return name === "html" ? ["html", { ...options, dataUrl: values["data-url"] }] : entry;
+    });
+    const reporterOptions = {
+      cwd: project.path("."),
+      outputDir: resolve(values.output ?? (configured.output ? project.path(configured.output) : "reports/site")),
+      dataUrl: values["data-url"] ?? configured.dataUrl
+    };
+    await protectInputs(planReporters(selected, reporterOptions), input ? [{ file: input, jsonOnly: true }] : []);
+    const outputs = await writeReporters(report, selected, reporterOptions);
+    for (const output of outputs)
+      console.log(`${output.reporter}: ${output.files.join(", ")}`);
+    return 0;
+  } catch (error) {
+    console.error(`meodp report: ${error instanceof Error ? error.message : String(error)}`);
+    return 2;
+  }
+}
+function selectReporters(cli, configured) {
+  if (cli === void 0)
+    return configured;
+  const names = [...new Set(cli.flatMap((value) => value.split(",").map((name) => name.trim())))];
+  if (names.some((name) => !["json", "markdown", "html"].includes(name)))
+    throw new TypeError("--reporter must select json, markdown, or html.");
+  return names;
+}
+async function protectInputs(plan, inputs, history) {
+  const identity = async (file) => {
+    try {
+      return await realpath(file);
+    } catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code === "ENOENT")
+        return resolve(file);
+      throw error;
+    }
+  };
+  const writes = plan.flatMap((item) => [
+    { file: item.file, reporter: item.reporter },
+    ...item.json ? [{ file: item.json, reporter: "json" }] : []
+  ]);
+  if (history)
+    writes.push({ file: history, reporter: "json" });
+  for (const input of inputs) {
+    const source = await identity(input.file);
+    for (const output of writes) {
+      if (await identity(output.file) === source && (!input.jsonOnly || output.reporter !== "json"))
+        throw new Error(`Reporter/history output would overwrite input ${input.file}; choose another output path.`);
+    }
+  }
+}
+
+export { runCheckCli, runReportCli, runSitemapCli };

package/dist/check/index.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+const check_index = require('../shared/meodp.c4c70565.cjs');
+const report = require('../shared/meodp.2b00b0ae.cjs');
+require('node:timers/promises');
+require('linkinator');
+require('node:os');
+require('node:fs/promises');
+require('node:path');
+require('node:process');
+require('node:buffer');
+require('node:util');
+require('node:zlib');
+require('fast-xml-parser');
+require('node:crypto');
+
+
+
+exports.checkLinks = check_index.checkLinks;
+exports.checkSitemap = check_index.checkSitemap;
+exports.readSitemapUrls = check_index.readSitemapUrls;
+exports.waitForReport = check_index.waitForReport;
+exports.writeReporters = check_index.writeReporters;
+exports.formatReport = report.formatReport;
+exports.parseReport = report.parseReport;
+exports.readReport = report.readReport;
+exports.saveReport = report.saveReport;
+exports.writeReportSite = report.writeReportSite;
+exports.writeReports = report.writeReports;

package/dist/check/index.d.cts

@@ -0,0 +1,44 @@
+import { L as LinkTarget, a as CheckOptions, C as CheckReport, S as SitemapOptions, A as Availability, b as LinkObservation } from '../shared/meodp.93e06e00.cjs';
+export { F as FailureReason } from '../shared/meodp.93e06e00.cjs';
+import { b as ReportSiteOptions } from '../shared/meodp.4f1da070.cjs';
+export { H as HtmlReporterOptions, a as ReportVerificationOptions, R as ReporterConfig, c as ReporterDescription, d as ReporterName, e as ReporterOptions, f as ReporterOutput, g as waitForReport, w as writeReporters } from '../shared/meodp.4f1da070.cjs';
+
+/** Check only the supplied URLs. HTTP failures become observations; invalid input rejects. */
+declare function checkLinks(input: readonly (string | LinkTarget)[], options?: CheckOptions): Promise<CheckReport>;
+
+declare function formatReport(report: CheckReport, format?: 'json' | 'markdown' | 'html'): string;
+declare function writeReports(report: CheckReport, directory: string): Promise<{
+    json: string;
+    markdown: string;
+    html: string;
+}>;
+/** Export a portable static site. Hosting refreshes the sidecar; file:// uses the embedded snapshot. */
+declare function writeReportSite(report: CheckReport | undefined, directory: string, options?: ReportSiteOptions): Promise<{
+    index: string;
+    json?: string;
+}>;
+/** A missing file starts history; malformed or incompatible history is an error. */
+declare function readReport(path: string): Promise<CheckReport | undefined>;
+/** Write history only after a completed run; replace it atomically. */
+declare function saveReport(report: CheckReport, path: string): Promise<void>;
+
+/** Shared by the Node reader and the static viewer; report files are untrusted input. */
+declare function parseReport(data: unknown): CheckReport;
+
+/** Read and validate a complete, deduplicated page list without requesting the pages. */
+declare function readSitemapUrls(source: string, options?: SitemapOptions): Promise<string[]>;
+/** Check sitemap-listed pages using the same linkinator adapter, history, and report schema as checkLinks. */
+declare function checkSitemap(source: string, options?: SitemapOptions): Promise<{
+    startedAt: string;
+    schemaVersion: 1;
+    observer: string;
+    completedAt: string;
+    summary: Record<Availability, number> & {
+        total: number;
+        redirected: number;
+        recovered: number;
+    };
+    results: LinkObservation[];
+}>;
+
+export { Availability, CheckOptions, CheckReport, LinkObservation, LinkTarget, ReportSiteOptions, SitemapOptions, checkLinks, checkSitemap, formatReport, parseReport, readReport, readSitemapUrls, saveReport, writeReportSite, writeReports };

package/dist/check/index.d.mts

@@ -0,0 +1,44 @@
+import { L as LinkTarget, a as CheckOptions, C as CheckReport, S as SitemapOptions, A as Availability, b as LinkObservation } from '../shared/meodp.93e06e00.mjs';
+export { F as FailureReason } from '../shared/meodp.93e06e00.mjs';
+import { b as ReportSiteOptions } from '../shared/meodp.a704f8db.mjs';
+export { H as HtmlReporterOptions, a as ReportVerificationOptions, R as ReporterConfig, c as ReporterDescription, d as ReporterName, e as ReporterOptions, f as ReporterOutput, g as waitForReport, w as writeReporters } from '../shared/meodp.a704f8db.mjs';
+
+/** Check only the supplied URLs. HTTP failures become observations; invalid input rejects. */
+declare function checkLinks(input: readonly (string | LinkTarget)[], options?: CheckOptions): Promise<CheckReport>;
+
+declare function formatReport(report: CheckReport, format?: 'json' | 'markdown' | 'html'): string;
+declare function writeReports(report: CheckReport, directory: string): Promise<{
+    json: string;
+    markdown: string;
+    html: string;
+}>;
+/** Export a portable static site. Hosting refreshes the sidecar; file:// uses the embedded snapshot. */
+declare function writeReportSite(report: CheckReport | undefined, directory: string, options?: ReportSiteOptions): Promise<{
+    index: string;
+    json?: string;
+}>;
+/** A missing file starts history; malformed or incompatible history is an error. */
+declare function readReport(path: string): Promise<CheckReport | undefined>;
+/** Write history only after a completed run; replace it atomically. */
+declare function saveReport(report: CheckReport, path: string): Promise<void>;
+
+/** Shared by the Node reader and the static viewer; report files are untrusted input. */
+declare function parseReport(data: unknown): CheckReport;
+
+/** Read and validate a complete, deduplicated page list without requesting the pages. */
+declare function readSitemapUrls(source: string, options?: SitemapOptions): Promise<string[]>;
+/** Check sitemap-listed pages using the same linkinator adapter, history, and report schema as checkLinks. */
+declare function checkSitemap(source: string, options?: SitemapOptions): Promise<{
+    startedAt: string;
+    schemaVersion: 1;
+    observer: string;
+    completedAt: string;
+    summary: Record<Availability, number> & {
+        total: number;
+        redirected: number;
+        recovered: number;
+    };
+    results: LinkObservation[];
+}>;
+
+export { Availability, CheckOptions, CheckReport, LinkObservation, LinkTarget, ReportSiteOptions, SitemapOptions, checkLinks, checkSitemap, formatReport, parseReport, readReport, readSitemapUrls, saveReport, writeReportSite, writeReports };

package/dist/check/index.d.ts

@@ -0,0 +1,44 @@
+import { L as LinkTarget, a as CheckOptions, C as CheckReport, S as SitemapOptions, A as Availability, b as LinkObservation } from '../shared/meodp.93e06e00.js';
+export { F as FailureReason } from '../shared/meodp.93e06e00.js';
+import { b as ReportSiteOptions } from '../shared/meodp.8369c4c1.js';
+export { H as HtmlReporterOptions, a as ReportVerificationOptions, R as ReporterConfig, c as ReporterDescription, d as ReporterName, e as ReporterOptions, f as ReporterOutput, g as waitForReport, w as writeReporters } from '../shared/meodp.8369c4c1.js';
+
+/** Check only the supplied URLs. HTTP failures become observations; invalid input rejects. */
+declare function checkLinks(input: readonly (string | LinkTarget)[], options?: CheckOptions): Promise<CheckReport>;
+
+declare function formatReport(report: CheckReport, format?: 'json' | 'markdown' | 'html'): string;
+declare function writeReports(report: CheckReport, directory: string): Promise<{
+    json: string;
+    markdown: string;
+    html: string;
+}>;
+/** Export a portable static site. Hosting refreshes the sidecar; file:// uses the embedded snapshot. */
+declare function writeReportSite(report: CheckReport | undefined, directory: string, options?: ReportSiteOptions): Promise<{
+    index: string;
+    json?: string;
+}>;
+/** A missing file starts history; malformed or incompatible history is an error. */
+declare function readReport(path: string): Promise<CheckReport | undefined>;
+/** Write history only after a completed run; replace it atomically. */
+declare function saveReport(report: CheckReport, path: string): Promise<void>;
+
+/** Shared by the Node reader and the static viewer; report files are untrusted input. */
+declare function parseReport(data: unknown): CheckReport;
+
+/** Read and validate a complete, deduplicated page list without requesting the pages. */
+declare function readSitemapUrls(source: string, options?: SitemapOptions): Promise<string[]>;
+/** Check sitemap-listed pages using the same linkinator adapter, history, and report schema as checkLinks. */
+declare function checkSitemap(source: string, options?: SitemapOptions): Promise<{
+    startedAt: string;
+    schemaVersion: 1;
+    observer: string;
+    completedAt: string;
+    summary: Record<Availability, number> & {
+        total: number;
+        redirected: number;
+        recovered: number;
+    };
+    results: LinkObservation[];
+}>;
+
+export { Availability, CheckOptions, CheckReport, LinkObservation, LinkTarget, ReportSiteOptions, SitemapOptions, checkLinks, checkSitemap, formatReport, parseReport, readReport, readSitemapUrls, saveReport, writeReportSite, writeReports };

package/dist/check/index.mjs

@@ -0,0 +1,13 @@
+export { a as checkLinks, c as checkSitemap, r as readSitemapUrls, b as waitForReport, w as writeReporters } from '../shared/meodp.80ff918d.mjs';
+export { f as formatReport, p as parseReport, r as readReport, s as saveReport, a as writeReportSite, w as writeReports } from '../shared/meodp.9c706389.mjs';
+import 'node:timers/promises';
+import 'linkinator';
+import 'node:os';
+import 'node:fs/promises';
+import 'node:path';
+import 'node:process';
+import 'node:buffer';
+import 'node:util';
+import 'node:zlib';
+import 'fast-xml-parser';
+import 'node:crypto';

package/dist/cli/index.cjs

@@ -235,8 +235,8 @@ const cli = yargs__default(helpers.hideBin(process__default$1.argv)).scriptName(
     await output(argv.type);
   }
 ).alias("h", "help").alias("v", "version").showHelpOnFail(false).help();
-function run() {
-  cli.parse();
+async function run(args = helpers.hideBin(process__default$1.argv), scriptName = "meodp") {
+  await cli.scriptName(scriptName).parseAsync(args);
 }
 
 exports.__DEV__ = __DEV__;

package/dist/cli/index.d.cts

@@ -6,6 +6,6 @@ declare const __DEV__ = false;
  */
 declare function debug(name: string, ...args: any[]): void;
 declare const cli: yargs.Argv<{}>;
-declare function run(): void;
+declare function run(args?: string[], scriptName?: string): Promise<void>;
 
 export { __DEV__, cli, debug, run };

package/dist/cli/index.d.mts

@@ -6,6 +6,6 @@ declare const __DEV__ = false;
  */
 declare function debug(name: string, ...args: any[]): void;
 declare const cli: yargs.Argv<{}>;
-declare function run(): void;
+declare function run(args?: string[], scriptName?: string): Promise<void>;
 
 export { __DEV__, cli, debug, run };

package/dist/cli/index.d.ts

@@ -6,6 +6,6 @@ declare const __DEV__ = false;
  */
 declare function debug(name: string, ...args: any[]): void;
 declare const cli: yargs.Argv<{}>;
-declare function run(): void;
+declare function run(args?: string[], scriptName?: string): Promise<void>;
 
 export { __DEV__, cli, debug, run };

package/dist/cli/index.mjs

@@ -224,8 +224,8 @@ const cli = yargs(hideBin(process$1.argv)).scriptName("meodp").usage("$0 \u68C0\
     await output(argv.type);
   }
 ).alias("h", "help").alias("v", "version").showHelpOnFail(false).help();
-function run() {
-  cli.parse();
+async function run(args = hideBin(process$1.argv), scriptName = "meodp") {
+  await cli.scriptName(scriptName).parseAsync(args);
 }
 
 export { __DEV__, cli, debug, run };