@goflag/cli 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,589 @@
+type Severity = "error" | "warning" | "info";
+
+/**
+ * Hreflang reciprocity + matrix derivation (Phase 7.4 / 7.5).
+ *
+ * Given a set of crawled `Page`s, builds two derived views:
+ *
+ *   1. A locale → route grid (`I18nMatrix`) the UI renders as a
+ *      green/red heatmap. Routes are derived from the canonical or
+ *      hreflang group, locales from the URL pathname segment when it
+ *      looks like a known BCP 47 tag (`/fr`, `/en-us`, …).
+ *
+ *   2. Per-page reciprocity findings (`reciprocityIssues`) — when
+ *      `/fr/about` declares an `<link rel="alternate" hreflang="en">`
+ *      pointing at `/en/about`, but `/en/about` does not advertise
+ *      `/fr/about` back, that's a Google-flagged broken cluster.
+ *
+ * Both helpers are pure: they accept a `Page[]` and return data, no
+ * I/O. The crawler in `crawl.ts` calls them once after the BFS
+ * finishes to populate the inspect-cache i18n payload.
+ *
+ * Locale code validity: we accept anything that matches BCP 47's
+ * basic shape (`[a-z]{2,3}(-[A-Z]{2})?`) plus `x-default`. Anything
+ * else flags as `locale.invalid`.
+ */
+
+type ReciprocityCode = "missing-back-link" | "self-mismatch" | "x-default-missing" | "locale.invalid";
+interface ReciprocityIssue {
+    code: ReciprocityCode;
+    /** URL of the page where the issue is observed. */
+    url: string;
+    /** Locale tag involved in the issue (or `x-default`). */
+    locale?: string;
+    /** Sister URL involved when the issue is cross-page. */
+    peerUrl?: string;
+    message: string;
+}
+interface I18nCell {
+    /** Absolute URL serving this (route, locale) cell. `null` when
+     *  no page in the crawl filled this cell. */
+    url: string | null;
+    /** True when the page was actually inspected (vs. discovered only). */
+    inspected: boolean;
+}
+interface I18nMatrix {
+    /** Stable locale axis, `x-default` first when present, then BCP 47
+     *  tags sorted alphabetically. */
+    locales: string[];
+    /** Stable route axis. Each route is a "canonical pathname" derived
+     *  by stripping the leading locale segment. Sorted alphabetically. */
+    routes: string[];
+    /** `cells[route][locale]` lookup. Always populated for every
+     *  (route, locale) pair, with `url: null` for missing alternates. */
+    cells: Record<string, Record<string, I18nCell>>;
+}
+
+/** The outcome of probing a single URL. */
+type LinkVerdict = "ok" | "redirect" | "broken" | "blocked" | "warning" | "skipped";
+
+/**
+ * Baseline comparison.
+ *
+ * Every finding already carries a `fingerprint` id derived from the *identity*
+ * of the problem rather than its transient details, and page URLs are
+ * normalised to origin-independent routes — so the same defect fingerprints
+ * identically on localhost, staging and production. That machinery was built
+ * for exactly this and had no consumer.
+ *
+ * What it changes is what the tool *is*. Without a baseline the CI gate is
+ * binary: any finding fails, which is unusable on a site that is not clean
+ * yet, so teams either never turn it on or learn to ignore it. With one, the
+ * gate becomes "no *new* findings" — a promise a real codebase can keep while
+ * the backlog is worked down.
+ *
+ * Pure function of two reports. No I/O; the CLI reads the baseline file.
+ */
+
+/** Which part of the report a finding came from. */
+type FindingKind = "brokenLink" | "unreachablePage" | "translationHole" | "reciprocity" | "seo" | "site";
+/** One finding, flattened out of its report section for comparison. */
+interface DiffEntry {
+    id: string;
+    kind: FindingKind;
+    /**
+     * Severity used for the exit-code decision. Rule findings carry their own;
+     * the rest are mapped to match the verdict logic in `build.ts` — a broken
+     * link or an unreachable page is an error, a translation gap is a warning.
+     */
+    severity: Severity;
+    /** One-line description, for the rendered diff. */
+    summary: string;
+    /** Page the finding sits on, when it has one. */
+    pageUrl?: string;
+}
+interface ReportDiff {
+    /** Where and when the baseline was taken, echoed for the report header. */
+    baseline: {
+        url: string;
+        finishedAt: string;
+    };
+    /** Findings present now and absent from the baseline — what should fail CI. */
+    added: DiffEntry[];
+    /** Findings in the baseline that are gone. Worth showing: progress is data too. */
+    resolved: DiffEntry[];
+    /** Findings present in both. */
+    unchanged: number;
+}
+
+/**
+ * The Goflag report — the single source of truth.
+ *
+ * Everything the CLI prints is a pure function of this object. It is fully
+ * JSON-serializable so `goflag <url> --json` and `--report out.json` emit it
+ * verbatim, and CI can diff / gate on it.
+ */
+
+type Verdict = "green" | "yellow" | "red";
+/** A page that was crawled, with just what the report needs. */
+interface ReportPage {
+    url: string;
+    status: number;
+    /** Locale inferred from the leading path segment, or null when unprefixed. */
+    locale: string | null;
+}
+/** One problematic link, mapped back to the page that references it. */
+interface BrokenLink {
+    /** Stable fingerprint of this finding (see `./fingerprint.ts`). */
+    id: string;
+    /** The page the link was found on. */
+    pageUrl: string;
+    /** The link target (canonical URL that was probed). */
+    href: string;
+    /** Final HTTP status (`0` = network error). */
+    status: number;
+    verdict: LinkVerdict;
+    /** Human-readable reason (network reason, "soft-404", "429 rate-limited", ...). */
+    reason?: string;
+}
+/** A route present in some locales but missing in others. */
+interface TranslationHole {
+    /** Stable fingerprint of this finding (see `./fingerprint.ts`). */
+    id: string;
+    /** Canonical route (locale segment stripped), e.g. `/about`. */
+    route: string;
+    /** Locales that serve this route. */
+    presentLocales: string[];
+    /** Locales that are missing a translation for this route. */
+    missingLocales: string[];
+}
+/** A reciprocity / hreflang finding, carrying a stable fingerprint. */
+type ReportReciprocityIssue = ReciprocityIssue & {
+    /** Stable fingerprint of this finding (see `./fingerprint.ts`). */
+    id: string;
+};
+/** A crawled page that returned a non-2xx status (errored / unreachable). */
+interface UnreachablePage {
+    /** Stable fingerprint of this finding (see `./fingerprint.ts`). */
+    id: string;
+    url: string;
+    /** HTTP status (`0` = network error). */
+    status: number;
+}
+/**
+ * One cross-page finding — a policy that needed the whole site to evaluate
+ * (hreflang coverage, `<head>` vs sitemap agreement). Same shape as `SeoIssue`
+ * so consumers render them identically; `ruleId` says which registry it came
+ * from.
+ */
+interface SiteIssue {
+    /** Stable fingerprint of this finding (see `./fingerprint.ts`). */
+    id: string;
+    /** Page the finding is attributed to. */
+    pageUrl: string;
+    ruleId: string;
+    severity: Severity;
+    message: string;
+    /** Why this rule exists (the rule's one-line summary). */
+    why?: string;
+    /** A copy-pasteable fix snippet, when the rule offers one. */
+    fix?: string;
+}
+/** How the audit established which locales the site serves. */
+interface LocaleAxisReport {
+    locales: string[];
+    /** `none` when nothing declared an axis — goflag does not guess one. */
+    source: "explicit" | "sitemap" | "none";
+    multilingual: boolean;
+    /**
+     * Locale-looking prefixes seen in the crawl, with the evidence for and
+     * against each. Only populated when `source` is `none`; a suggestion for
+     * `--locales`, never promoted automatically.
+     */
+    candidates?: Array<{
+        tag: string;
+        pages: number;
+        isKnownLanguage: boolean;
+        htmlLangAgrees?: boolean;
+        observedLangs: string[];
+    }>;
+}
+/** One SEO metadata finding on a specific page. */
+interface SeoIssue {
+    /** Stable fingerprint of this finding (see `./fingerprint.ts`). */
+    id: string;
+    pageUrl: string;
+    ruleId: string;
+    severity: Severity;
+    message: string;
+    /** Why this rule exists (the rule's one-line summary). */
+    why?: string;
+    /** A copy-pasteable fix snippet, when the rule offers one. */
+    fix?: string;
+}
+interface GoflagReport {
+    /** The base URL the audit started from (normalized). */
+    url: string;
+    /** ISO timestamp when the audit finished. */
+    finishedAt: string;
+    summary: {
+        brokenLinks: number;
+        missingTranslations: number;
+        seoIssues: number;
+        /** Cross-page findings (hreflang coverage, head↔sitemap agreement). */
+        siteIssues: number;
+        unreachablePages: number;
+        verdict: Verdict;
+    };
+    /** Which locales the site serves, and how the audit found out. */
+    localeAxis: LocaleAxisReport;
+    pages: ReportPage[];
+    /** Crawled pages that returned a non-2xx status. */
+    unreachablePages: UnreachablePage[];
+    brokenLinks: BrokenLink[];
+    missingTranslations: {
+        /** Routes present in one locale but absent in another. */
+        holes: TranslationHole[];
+        /** hreflang reciprocity / x-default / invalid-locale findings. */
+        reciprocity: ReportReciprocityIssue[];
+    };
+    seoIssues: SeoIssue[];
+    /** Findings from the cross-page rule registry (`SITE_RULES`). */
+    siteIssues: SiteIssue[];
+    /** Comparison against a stored baseline, when `--baseline` was given. */
+    diff?: ReportDiff;
+    diagnostics: {
+        pagesCrawled: number;
+        pagesScanned: number;
+        pagesFailed: number;
+        truncated: boolean;
+        warnings: string[];
+        /** Translation gaps suppressed by `--ignore-holes`, when any. */
+        ignoredHoles?: number;
+        /**
+         * Pages excluded from the rule layer because they declare a canonical
+         * pointing at another crawled page — the site's own statement that they
+         * are duplicates. Reported so a shrinking finding count is explicable.
+         */
+        duplicatePages?: number;
+        /** Sitemap discovery outcome, when discovery ran. */
+        sitemap?: {
+            found: boolean;
+            sitemapUrl?: string;
+            urlCount: number;
+            /** URLs the sitemap declared that the crawl never reached. */
+            uncrawled: number;
+        };
+    };
+}
+
+/**
+ * Report orchestrator.
+ *
+ * One crawl feeds all three checks:
+ *   - the crawled `Page[]` drives SEO lint + the i18n matrix, and
+ *   - a synthetic `SiteDiscovery` built from the same page set drives the
+ *     link audit.
+ *
+ * Everything funnels into a single `GoflagReport` (see `./types.ts`).
+ */
+
+/**
+ * The phase of the audit a progress event belongs to:
+ *   - "crawl": BFS-visiting + inspecting pages (SEO + i18n input).
+ *   - "scan":  re-reading each page's HTML to extract its links.
+ *   - "links": probing each unique link target.
+ */
+type AuditPhase = "crawl" | "scan" | "links";
+/** A single progress tick, emitted as the audit advances. */
+interface ProgressEvent {
+    phase: AuditPhase;
+    /** Items completed in the current phase. */
+    done: number;
+    /** Best-effort total for the phase (the crawl total grows as links are discovered). */
+    total: number;
+    /** The URL just processed, when the phase tracks one (crawl). */
+    url?: string;
+    /** HTTP status of `url`, when known (crawl). */
+    status?: number;
+}
+interface AuditOptions {
+    /** BFS crawl depth. `0` = entry only. Defaults to 2. */
+    depth?: number;
+    /** Hard cap on pages crawled. Defaults to 200. */
+    maxPages?: number;
+    /** Glob include filter on the URL pathname. */
+    include?: string[];
+    /** Glob exclude filter on the URL pathname. */
+    exclude?: string[];
+    /** Probe external (off-origin) links too. Defaults to true. */
+    checkExternal?: boolean;
+    /** Skip Chromium: static HTML only (no SPA rendering). Defaults to false. */
+    static?: boolean;
+    /** Allow self-signed / invalid TLS (localhost, tunnels). */
+    allowInsecureTls?: boolean;
+    /** Per-request timeout in ms. Defaults to 8_000. */
+    timeoutMs?: number;
+    /** Caller-driven cancellation. */
+    signal?: AbortSignal;
+    /** Progress callback for a live CLI. */
+    onProgress?: (event: ProgressEvent) => void;
+    /**
+     * Locales the site serves, when the operator knows better than we can infer
+     * (`--locales fr,en,pt-br`). Strongest input to the locale axis.
+     */
+    locales?: string[];
+    /**
+     * Routes (locale-free, glob-matched) that are deliberately not translated
+     * everywhere, so their gaps are not reported as missing translations.
+     * Suppression is counted in `diagnostics.ignoredHoles` — a silenced finding
+     * that leaves no trace reads as "nothing was wrong".
+     */
+    ignoreHoles?: string[];
+    /**
+     * Skip sitemap discovery and seed the crawl from `<url>` alone. Defaults to
+     * false — discovery is on by default because crawl-only discovery is exactly
+     * what made hreflang checks silently vacuous.
+     */
+    noSitemap?: boolean;
+}
+/**
+ * Routes present in some locales but absent in others. A "hole" is exactly
+ * the "missing translation page" the tool exists to find. `x-default` is a
+ * fallback pointer, not a real translation, so it never counts as a locale
+ * that must be filled.
+ *
+ * `ignoreRoutes` globs out routes the operator has declared intentionally
+ * partial. A site has no markup for "this page does not exist here on
+ * purpose", so a deliberate gap and a forgotten one are indistinguishable from
+ * outside — only the operator can tell them apart. Without a way to say so, the
+ * report can never reach zero on a site with a jurisdiction-specific legal
+ * page, and a report that can never be clean teaches its reader to ignore it.
+ *
+ * Globs match the locale-free route (`/legal`, `/blog/**`), using the same
+ * matcher as `--include`/`--exclude`.
+ */
+declare function deriveTranslationHoles(matrix: I18nMatrix, ignoreRoutes?: readonly string[]): TranslationHole[];
+/**
+ * The severity at or above which findings should fail the process.
+ *
+ * `warning` is the historical behaviour (any finding fails). `error` lets a
+ * team adopt goflag on a site that is not clean yet: warnings stay visible in
+ * the report while only hard errors block a merge. `never` reports without
+ * ever failing, for exploratory runs.
+ */
+type FailOn = "warning" | "error" | "never";
+/**
+ * Map a report to a process exit code:
+ *   0 = clean (or below the failure threshold), 1 = findings at/above it.
+ * Used by the CLI as a CI gate.
+ *
+ * `red` always fails unless `never`: a red verdict also covers broken links,
+ * unreachable pages and a blind link scan — states where "no findings" would
+ * be a lie rather than a pass.
+ */
+declare function exitCode(report: GoflagReport, failOn?: FailOn): number;
+/** Run the full audit and return the report. Never throws for site-level failures. */
+declare function runAudit(inputUrl: string, options?: AuditOptions): Promise<GoflagReport>;
+
+/**
+ * Render a `GoflagReport` as a human-readable terminal report.
+ *
+ * Pure function of the report — no I/O. Colour is disabled automatically
+ * when stdout is not a TTY or `NO_COLOR` is set.
+ */
+
+interface RenderOptions$1 {
+    color?: boolean;
+}
+declare function renderTerminal(report: GoflagReport, options?: RenderOptions$1): string;
+
+/**
+ * Roll a full `GoflagReport` up into a compact `GoflagSummary`.
+ *
+ * The full report lists every finding on every page — great for a baseline
+ * file or a diff, but noisy for a human skim and expensive for an LLM agent
+ * to read. The summary deduplicates:
+ *
+ *   - broken links by target (one entry per broken URL, with the pages that
+ *     link to it),
+ *   - SEO issues by rule (one entry per rule, carrying its `why`/`fix` once,
+ *     with a sample of affected pages),
+ *   - reciprocity findings by code.
+ *
+ * It is a pure function of the report — `goflag <url> --summary` and
+ * `--summary --json` both derive their output from this, so the rollup logic
+ * lives in exactly one place.
+ */
+
+/** How many example pages/URLs a rolled-up entry keeps before it says "+N more". */
+declare const SAMPLE_LIMIT = 5;
+/** One broken target, with every page that links to it collapsed together. */
+interface RollupLink {
+    href: string;
+    verdict: LinkVerdict;
+    status: number;
+    reason?: string;
+    /** How many (page → link) references share this target + verdict. */
+    count: number;
+    /** Up to {@link SAMPLE_LIMIT} pages that reference it. */
+    pages: string[];
+    /** References beyond the sample. */
+    morePages: number;
+}
+/** One SEO rule, collapsed across every page it fired on. */
+interface RollupSeo {
+    ruleId: string;
+    severity: Severity;
+    why?: string;
+    fix?: string;
+    /** A representative message (from the first occurrence). */
+    sample: string;
+    count: number;
+    pages: string[];
+    morePages: number;
+}
+/** One reciprocity code, collapsed across every page it fired on. */
+interface RollupReciprocity {
+    code: ReciprocityCode;
+    count: number;
+    sample: string;
+    pages: string[];
+    morePages: number;
+}
+interface GoflagSummary {
+    url: string;
+    finishedAt: string;
+    verdict: Verdict;
+    totals: {
+        brokenLinks: number;
+        missingTranslations: number;
+        seoIssues: number;
+        siteIssues: number;
+        unreachablePages: number;
+        pagesCrawled: number;
+        pagesScanned: number;
+        pagesFailed: number;
+    };
+    unreachablePages: UnreachablePage[];
+    brokenLinks: RollupLink[];
+    translations: {
+        holes: TranslationHole[];
+        reciprocity: RollupReciprocity[];
+    };
+    seoIssues: RollupSeo[];
+    /** Cross-page findings, rolled up by rule exactly like `seoIssues`. */
+    siteIssues: RollupSeo[];
+    truncated: boolean;
+    warnings: string[];
+}
+declare function summarize(report: GoflagReport): GoflagSummary;
+
+/**
+ * Render a `GoflagSummary` as a compact, deduplicated terminal report.
+ *
+ * Where `renderTerminal` lists every finding grouped by page, this lists each
+ * distinct problem once with a count and a small sample of affected pages —
+ * the view you want for a large crawl or a quick "is it green?" check. Pure
+ * function of the summary; no I/O.
+ */
+
+interface RenderOptions {
+    color?: boolean;
+}
+declare function renderSummaryTerminal(summary: GoflagSummary, options?: RenderOptions): string;
+
+/**
+ * Stable finding fingerprints.
+ *
+ * Every finding in the report carries an `id` — a short, deterministic key
+ * derived from the *identity* of the problem, not its transient details
+ * (status codes, character counts, wording). This is what lets an agent (or
+ * a CI baseline) say "finding `seo-1a2b3c4d5e` is still open" across runs,
+ * and — because page URLs are normalized to origin-independent routes — even
+ * across environments (localhost vs. staging vs. prod).
+ *
+ * Pure, no I/O. `createHash` is the only dependency.
+ */
+/**
+ * Normalize a same-origin URL to a stable, origin-independent route key so a
+ * finding on `http://localhost:3000/en/about` and `https://site.com/en/about`
+ * fingerprints the same. Drops the origin, collapses a trailing slash, keeps
+ * the query string (it can change what page you get).
+ */
+declare function routeKey(rawUrl: string): string;
+/**
+ * Normalize a link target for fingerprinting. Unlike {@link routeKey} this
+ * keeps the origin, because a broken link's identity includes *where* it
+ * points (two different external hosts are two different findings). Only the
+ * trailing slash is normalized away.
+ */
+declare function targetKey(rawUrl: string): string;
+/**
+ * Build a finding id: `<category>-<10 hex chars>`. The parts are joined with
+ * a NUL separator (which can't appear in a URL or rule id) before hashing, so
+ * distinct tuples never collide by concatenation.
+ */
+declare function fingerprint(category: string, ...parts: string[]): string;
+
+/**
+ * Live progress logger for the CLI.
+ *
+ * Everything here writes to a *side* stream (stderr by default) so the JSON
+ * report on stdout is never polluted. Three modes:
+ *
+ *   - "compact" (default): a single, in-place status line — spinner +
+ *     progress bar + "done/total" + the current page. On a non-TTY (CI,
+ *     pipes) it degrades to throttled plain lines so logs stay readable.
+ *   - "verbose": one line per page as it is analyzed (status + URL), plus
+ *     phase headers. No spinner; lines scroll.
+ *   - "quiet": nothing at all.
+ *
+ * The logger is fed `ProgressEvent`s (see `./build.ts`) via `onProgress`,
+ * and the CLI calls `note()` for banners/warnings and `stop()` at the end.
+ */
+
+type LogMode = "compact" | "verbose" | "quiet";
+interface WriteStreamLike {
+    write(chunk: string): boolean;
+    isTTY?: boolean;
+    columns?: number;
+}
+interface LoggerOptions {
+    /** Destination stream. Defaults to `process.stderr`. */
+    stream?: WriteStreamLike;
+    /** Emit ANSI colour. Defaults to `stream.isTTY`. */
+    color?: boolean;
+    /** Display mode. Defaults to "compact". */
+    mode?: LogMode;
+    /** Spinner tick interval in ms. `0` disables the animating timer (tests). */
+    spinnerIntervalMs?: number;
+    /** Minimum gap between plain progress lines on a non-TTY. Defaults to 250. */
+    throttleMs?: number;
+    /** Injectable clock (tests). */
+    now?: () => number;
+}
+declare class Logger {
+    private readonly stream;
+    private readonly color;
+    private readonly mode;
+    private readonly isTTY;
+    private readonly spinnerIntervalMs;
+    private readonly throttleMs;
+    private readonly now;
+    private timer;
+    private frame;
+    private last;
+    private lineOpen;
+    private lastPlainAt;
+    private headerShown;
+    constructor(options?: LoggerOptions);
+    private paint;
+    /** Print a standalone line (banner, warning). Survives around the spinner. */
+    note(message: string): void;
+    /** Feed one progress tick. */
+    onProgress: (event: ProgressEvent) => void;
+    /** Stop the spinner and clear the status line so the report starts clean. */
+    stop(): void;
+    private ensureTimer;
+    private render;
+    private composeLine;
+    private bar;
+    private verboseLine;
+    private statusTag;
+    private plainThrottled;
+    private clearLine;
+    private truncate;
+}
+
+export { type AuditOptions, type AuditPhase, type BrokenLink, type GoflagReport, type GoflagSummary, type LogMode, Logger, type LoggerOptions, type ProgressEvent, type ReportPage, type ReportReciprocityIssue, type RollupLink, type RollupReciprocity, type RollupSeo, SAMPLE_LIMIT, type SeoIssue, type TranslationHole, type UnreachablePage, type Verdict, deriveTranslationHoles, exitCode, fingerprint, renderSummaryTerminal, renderTerminal, routeKey, runAudit, summarize, targetKey };

package/dist/index.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import {
+  Logger,
+  SAMPLE_LIMIT,
+  deriveTranslationHoles,
+  exitCode,
+  fingerprint,
+  renderSummaryTerminal,
+  renderTerminal,
+  routeKey,
+  runAudit,
+  summarize,
+  targetKey
+} from "./chunk-75OFMTOC.js";
+export {
+  Logger,
+  SAMPLE_LIMIT,
+  deriveTranslationHoles,
+  exitCode,
+  fingerprint,
+  renderSummaryTerminal,
+  renderTerminal,
+  routeKey,
+  runAudit,
+  summarize,
+  targetKey
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}