opencode-wiki-historian 0.4.0 → 0.5.1

package/dist/lint.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Body lint: one fence-aware pass over a page body producing the structural
+ * facts every hard gate and surface detector reuses (plan v0.5.0 #6).
+ * Pure functions, zero wiki I/O — the deep scanner injects bodies, the write
+ * tools lint drafts before they hit the API. This is the module the
+ * architecture-page audit (HANDOFF Issue #6) forced into existence: nothing
+ * here was optional before, which is exactly how a page with five empty
+ * sections shipped for three days claiming `状态: Active`.
+ */
+import type { Locale } from './wiki/pages.read.js';
+/** Machine rule keys; the human report renders zh labels from these. */
+export type GateViolation = 'redirect-stub-no-exit' | 'active-with-unfinished-skeleton';
+export interface LintFinding {
+    readonly key: 'todo-markers' | 'empty-sections' | 'intro-empty' | 'no-related-pages' | 'no-state-block' | 'h1-mismatch' | 'zh-english-dominant' | 'claims-without-stamp';
+    readonly detail: string;
+}
+export interface PageLink {
+    /** Normalized wiki path (locale prefix stripped, leading `/` removed, no anchor/query). */
+    readonly path: string;
+    readonly locale: Locale;
+    /** True when the raw target was a same-page anchor (`#…`) — never resolved. */
+    readonly anchor: boolean;
+}
+export interface ClaimCounts {
+    readonly ports: number;
+    readonly paths: number;
+    readonly commands: number;
+}
+export interface BodyLint {
+    readonly isRedirectStub: boolean;
+    readonly redirectTarget: string | null;
+    readonly stubHasLink: boolean;
+    readonly hasStateBlock: boolean;
+    readonly state: 'active' | 'draft' | 'superseded' | 'deprecated' | null;
+    readonly todoMarkers: number;
+    /** Heading text of sections whose body (before the next heading ≤ level) is empty. */
+    readonly emptySections: readonly string[];
+    readonly introEmpty: boolean;
+    readonly hasRelatedPages: boolean;
+    readonly h1: string | null;
+    /** All heading spans in document order (twin-parity + structure checks). */
+    readonly headings: readonly HeadingSpan[];
+    readonly links: readonly PageLink[];
+    readonly hasStamp: boolean;
+    readonly claims: ClaimCounts;
+    readonly claimTotal: number;
+    /** CJK chars / non-whitespace chars, zh body only meaningful; 0..1. */
+    readonly cjkRatio: number;
+}
+export interface HeadingSpan {
+    readonly level: number;
+    readonly heading: string;
+    /** Subtree body: weighted length until the next heading ≤ level, INCLUDING
+     *  descendant sections' content (masked+comment-free). */
+    readonly bodyChars: number;
+    /** Direct body only: weighted length until the next heading at ANY level.
+     *  Used for the intro ratio so an H1 span never swallows the whole page. */
+    readonly directChars: number;
+}
+/** Section headings (##+) whose SUBTREE holds no content. A parent that groups
+ *  non-empty subsections is an outline container, not an unfinished product;
+ *  only wholly-empty subtrees indicate an unfilled skeleton section. */
+export declare function emptySectionsOf(headings: readonly HeadingSpan[]): readonly string[];
+export interface LinkScanOpts {
+    readonly baseUrl: string;
+}
+/** Extract internal page links (relative wiki paths + same-host absolute URLs). */
+export declare function extractLinks(masked: string, opts: LinkScanOpts): readonly PageLink[];
+export interface LintOpts {
+    readonly locale: Locale;
+    readonly baseUrl: string;
+    /** Page title for the h1-mismatch check. */
+    readonly title?: string;
+}
+export declare function lintBody(body: string, opts: LintOpts): BodyLint;
+/** Structural h1≠title flag (kept out of BodyLint's hot fields on purpose). */
+export declare function h1TitleMismatch(lint: BodyLint, title: string | undefined): boolean;
+/** The two hard publish-gate rules (shared.ts refuses the write on a hit). */
+export declare function publishGateViolations(lint: BodyLint): readonly GateViolation[];

package/dist/lint.js

@@ -0,0 +1,254 @@
+/**
+ * Body lint: one fence-aware pass over a page body producing the structural
+ * facts every hard gate and surface detector reuses (plan v0.5.0 #6).
+ * Pure functions, zero wiki I/O — the deep scanner injects bodies, the write
+ * tools lint drafts before they hit the API. This is the module the
+ * architecture-page audit (HANDOFF Issue #6) forced into existence: nothing
+ * here was optional before, which is exactly how a page with five empty
+ * sections shipped for three days claiming `状态: Active`.
+ */
+// --- fence + comment masking ----------------------------------------------------
+/** Blank out fenced code-block interiors (keep line structure) so markers,
+ *  headings and links inside code fences never count (SYN fence rule). */
+function maskFences(body) {
+    const lines = body.split('\n');
+    let fence = null;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const m = /^(`{3,}|~{3,})/.exec(line.trimStart());
+        if (fence === null && m !== null) {
+            fence = m[1][0];
+            continue;
+        }
+        if (fence !== null) {
+            if (line.trimStart().startsWith(fence.repeat(3))) {
+                fence = null;
+            }
+            else {
+                lines[i] = '';
+            }
+        }
+    }
+    return lines.join('\n');
+}
+const COMMENT_RE = /<!--[\s\S]*?-->/g;
+// --- redirect stub --------------------------------------------------------------
+const REDIRECT_LINE_RE = /^>\s*Redirect:\s*(\S.*?)\s*$/im;
+function redirectTarget(masked) {
+    const m = REDIRECT_LINE_RE.exec(masked);
+    return m !== null ? m[1] : null;
+}
+/** Clickable exit (Issue #5.1): a stub only lives if it carries at least one
+ *  real internal link — a bare `<code>` path or an in-page anchor is a dead
+ *  end for the reader who lands here. Wrong-target links belong to the
+ *  dead-link scanner, not this gate. */
+function hasClickableExit(visibleNoAnchors) {
+    return visibleNoAnchors > 0;
+}
+// --- status block -----------------------------------------------------------------
+const STATE_LINE_RE = /(?:^|\n)\s*\*{0,2}\s*(?:状态\s*\/\s*Status|状态|Status)\s*\*{0,2}\s*[:：]\s*([A-Za-z\u4e00-\u9fff][^\n·|<]*)/i;
+function parseState(maskedNoComments) {
+    const m = STATE_LINE_RE.exec(maskedNoComments);
+    if (m === null)
+        return { has: false, state: null };
+    const v = m[1].trim().toLowerCase();
+    if (v.startsWith('active'))
+        return { has: true, state: 'active' };
+    if (v.startsWith('draft'))
+        return { has: true, state: 'draft' };
+    if (v.startsWith('superseded'))
+        return { has: true, state: 'superseded' };
+    if (v.startsWith('deprecated'))
+        return { has: true, state: 'deprecated' };
+    return { has: true, state: null };
+}
+// --- markers, headings, intro -------------------------------------------------------
+const TODO_COMMENT_RE = /(TODO|TBD|PLACEHOLDER|占位)/i;
+const LITERAL_TODO_RE = /\bTODO:/g;
+function countTodoMarkers(masked) {
+    let n = 0;
+    for (const m of masked.matchAll(COMMENT_RE)) {
+        if (TODO_COMMENT_RE.test(m[0]))
+            n++;
+    }
+    // literal TODO: outside comments (comments already masked to '' for this pass)
+    const noComments = masked.replace(COMMENT_RE, '');
+    n += (noComments.match(LITERAL_TODO_RE) ?? []).length;
+    return n;
+}
+const HEADING_RE = /^(#{1,6})\s+(.+?)\s*#*$/;
+const STATUS_BOILERPLATE_RE = /状态\s*\/\s*Status|日期\s*\/\s*Date|本页回答|This page answers/i;
+/** Parse headings + emptiness over masked, comment-stripped text. Also returns
+ *  the intro span (before the first heading) for the 导言占比 detector. */
+function parseStructure(masked) {
+    const noComments = masked.replace(COMMENT_RE, '');
+    const lines = noComments.split('\n');
+    const headings = [];
+    let h1 = null;
+    let intro = 0;
+    const stack = [];
+    // CJK glyphs carry ~3x the visual weight of a latin char per cell — count
+    // weight, not raw chars, so a terse Chinese intro is not flagged empty.
+    const weight = (s) => {
+        const stripped = s.replace(/\s/g, '');
+        const cjk = (stripped.match(CJK_WEIGHT_RE) ?? []).length;
+        return cjk * 3 + (stripped.length - cjk);
+    };
+    const closeTo = (level) => {
+        const closing = [];
+        for (;;) {
+            const s = stack[stack.length - 1];
+            if (s === undefined || s.level < level)
+                break;
+            stack.pop();
+            closing.push({ level: s.level, heading: s.heading, bodyChars: s.subtree, directChars: s.direct });
+        }
+        // inner-first pop order must be flipped back to document order
+        headings.push(...closing.reverse());
+    };
+    for (const line of lines) {
+        const m = HEADING_RE.exec(line);
+        if (m !== null) {
+            const level = m[1].length;
+            closeTo(level);
+            if (level === 1 && h1 === null)
+                h1 = m[2].trim();
+            stack.push({ level, heading: m[2].trim(), direct: 0, subtree: 0 });
+            continue;
+        }
+        if (STATUS_BOILERPLATE_RE.test(line))
+            continue;
+        const w = weight(line);
+        if (stack.length === 0) {
+            intro += w;
+            continue;
+        }
+        for (const s of stack)
+            s.subtree += w;
+        stack[stack.length - 1].direct += w;
+    }
+    closeTo(1);
+    // The intro is the H1 section's DIRECT span (real pages all open with
+    // `# 标题`); the pre-heading accumulator only carries weight on heading-less bodies.
+    const firstH1 = headings.find((h) => h.level === 1);
+    const introWeight = firstH1 !== undefined ? firstH1.directChars : intro;
+    return { headings, introEmpty: introWeight < 40, h1 };
+}
+/** Section headings (##+) whose SUBTREE holds no content. A parent that groups
+ *  non-empty subsections is an outline container, not an unfinished product;
+ *  only wholly-empty subtrees indicate an unfilled skeleton section. */
+export function emptySectionsOf(headings) {
+    return headings.filter((h) => h.level >= 2 && h.bodyChars === 0).map((h) => h.heading);
+}
+// --- links -----------------------------------------------------------------------
+const LINK_MD_RE = /\]\(([^)\s]+)[^)]*\)/g;
+const LINK_HREF_RE = /href="([^"]+)"/gi;
+/** Extract internal page links (relative wiki paths + same-host absolute URLs). */
+export function extractLinks(masked, opts) {
+    const out = [];
+    const host = opts.baseUrl.replace(/\/+$/, '');
+    const seen = new Set();
+    const push = (raw) => {
+        let target = raw.trim();
+        if (target === '' || target.startsWith('#')) {
+            if (target.startsWith('#'))
+                out.push({ path: target.slice(1), locale: 'en', anchor: true });
+            return;
+        }
+        if (/^(mailto:|javascript:)/i.test(target))
+            return;
+        let locale = 'en';
+        if (/^https?:\/\//i.test(target)) {
+            if (!target.toLowerCase().startsWith(host.toLowerCase()))
+                return; // external
+            target = target.slice(host.length);
+        }
+        if (/\.(png|jpe?g|gif|svg|webp|pdf|zip|css|js)\b/i.test(target))
+            return;
+        target = target.split('#')[0];
+        target = target.split('?')[0];
+        target = target.replace(/^\/+/, '');
+        if (target === '')
+            return;
+        if (target.startsWith('zh/')) {
+            locale = 'zh';
+            target = target.slice(3);
+        }
+        else if (target.startsWith('en/')) {
+            target = target.slice(3);
+        }
+        const key = `${locale}\u0000${target}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        out.push({ path: target, locale, anchor: false });
+    };
+    for (const re of [LINK_MD_RE, LINK_HREF_RE]) {
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(masked)) !== null)
+            push(m[1] ?? '');
+    }
+    return out;
+}
+// --- claims + stamps + language -----------------------------------------------------
+const STAMP_RE = /上次核实|上次验证|last verified/i;
+const PORT_RE = /:\d{4,5}\b/g;
+const FS_PATH_RE = /\/(?:opt|var|etc|usr|srv)\/[\w./-]+/g;
+const CMD_RE = /\b(?:systemctl|journalctl|docker|curl|nc|wget|iptables|nginx|caddy)\b/gi;
+const CJK_RE = /[\u3400-\u4dbf\u4e00-\u9fff\u3040-\u30ff]/g;
+const CJK_WEIGHT_RE = /[\u3400-\u4dbf\u4e00-\u9fff\u3040-\u30ff]/g;
+function distinct(text, re) {
+    return new Set(text.match(re) ?? []).size;
+}
+// --- main entry ---------------------------------------------------------------------
+export function lintBody(body, opts) {
+    const masked = maskFences(body);
+    const visible = masked.replace(COMMENT_RE, '');
+    const target = redirectTarget(masked);
+    const isRedirectStub = /^\s*>\s*Redirect:/im.test(masked);
+    const { headings, introEmpty, h1 } = parseStructure(masked);
+    const links = extractLinks(visible, { baseUrl: opts.baseUrl }).filter((l) => !l.anchor);
+    const nonSpace = (visible.match(/\S/g) ?? []).length;
+    const cjk = (visible.match(CJK_RE) ?? []).length;
+    const claims = {
+        ports: distinct(visible, PORT_RE),
+        paths: distinct(visible, FS_PATH_RE),
+        commands: distinct(visible, CMD_RE),
+    };
+    const stateInfo = parseState(visible);
+    return {
+        isRedirectStub,
+        redirectTarget: target,
+        stubHasLink: !isRedirectStub || hasClickableExit(links.length),
+        hasStateBlock: stateInfo.has,
+        state: stateInfo.state,
+        todoMarkers: countTodoMarkers(masked),
+        emptySections: emptySectionsOf(headings),
+        introEmpty,
+        hasRelatedPages: /^#{1,6}\s+.*(相关页面|Related Pages)/im.test(masked),
+        h1,
+        headings,
+        links,
+        hasStamp: STAMP_RE.test(visible),
+        claims,
+        claimTotal: claims.ports + claims.paths + claims.commands,
+        cjkRatio: nonSpace === 0 ? 0 : cjk / nonSpace,
+    };
+}
+/** Structural h1≠title flag (kept out of BodyLint's hot fields on purpose). */
+export function h1TitleMismatch(lint, title) {
+    if (title === undefined || lint.h1 === null)
+        return false;
+    return lint.h1.trim().toLowerCase() !== title.trim().toLowerCase();
+}
+/** The two hard publish-gate rules (shared.ts refuses the write on a hit). */
+export function publishGateViolations(lint) {
+    const out = [];
+    if (lint.isRedirectStub && !lint.stubHasLink)
+        out.push('redirect-stub-no-exit');
+    if (lint.state === 'active' && (lint.todoMarkers > 0 || lint.emptySections.length > 0)) {
+        out.push('active-with-unfinished-skeleton');
+    }
+    return out;
+}

package/dist/maintain.d.ts

@@ -91,7 +91,7 @@ export interface MaintainReport {
             childPath: string;
         }[];
     };
-    readonly rootOrphans: readonly {
+    readonly flatRootPages: readonly {
         section: string;
         paths: readonly string[];
     }[];
@@ -114,7 +114,7 @@ export interface MaintainReport {
     }[];
     readonly freshness: FreshnessScan | null;
 }
-export declare const MAINTAIN_SCHEMA = "historian.maintain.v1";
+export declare const MAINTAIN_SCHEMA = "historian.maintain.v2";
 /** Trigram-Jaccard bar for calling two (different-path) titles near-duplicates. */
 export declare const DUP_TITLE_THRESHOLD = 0.75;
 export declare function buildMaintainReport(input: MaintainInput, opts?: MaintainOptions): Promise<MaintainReport>;

package/dist/maintain.js

@@ -17,7 +17,7 @@ import { classifyGenre } from './templates/genres.js';
 import { isInternalPath } from './tools/shared.js';
 import { normalize } from './migrate-score.js';
 // --- Constants --------------------------------------------------------------
-export const MAINTAIN_SCHEMA = 'historian.maintain.v1';
+export const MAINTAIN_SCHEMA = 'historian.maintain.v2';
 /** Trigram-Jaccard bar for calling two (different-path) titles near-duplicates. */
 export const DUP_TITLE_THRESHOLD = 0.75;
 const DAY_MS = 86_400_000;
@@ -58,8 +58,11 @@ function jaccard(a, b) {
 function cmpStr(a, b) {
     return a < b ? -1 : a > b ? 1 : 0;
 }
+// bold-merge deliberately leaves (重定向)/(redirect)-suffixed stubs beside their
+// live twins; clustering those pairs reports non-defects and buries true near-dupes.
+const STUB_TITLE_RE = /[（(]\s*(?:重定向|redirect)\s*[）)]\s*$/i;
 function findDuplicates(rows) {
-    const units = rows.map((r) => ({
+    const units = rows.filter((r) => !STUB_TITLE_RE.test(r.title)).map((r) => ({
         path: r.path,
         title: r.title,
         grams: titleGrams(normalize(r.title).toLowerCase()),
@@ -147,7 +150,7 @@ function singleChildDirs(paths) {
     }
     return out;
 }
-function rootOrphans(paths) {
+function flatRootPages(paths) {
     const bySection = new Map();
     for (const path of paths) {
         if (path.split('/').length !== 2)
@@ -270,7 +273,7 @@ export async function buildMaintainReport(input, opts = {}) {
         duplicates: { threshold: DUP_TITLE_THRESHOLD, clusters: findDuplicates(kept) },
         staleness: { topN, oldest: staleness(kept, now, topN) },
         diffusion: { singleChildDirs: singleChildDirs(paths) },
-        rootOrphans: rootOrphans(paths),
+        flatRootPages: flatRootPages(paths),
         tags: tagVocab(kept),
         redirects,
         sections: sectionDist(kept),
@@ -313,10 +316,10 @@ export function renderMaintainMarkdown(r) {
         L.push('  - none');
     for (const d of r.diffusion.singleChildDirs)
         L.push(`  - \`${d.dir}/\` holds only \`${d.childPath}\``);
-    L.push('- root-level orphans (depth-2 pages, no sub-shelf):');
-    if (r.rootOrphans.length === 0)
+    L.push('- flat root pages per section (depth-2 listing, shelving hint — NOT inbound analysis; true orphans = surface deep links.orphanPages):');
+    if (r.flatRootPages.length === 0)
         L.push('  - none');
-    for (const o of r.rootOrphans)
+    for (const o of r.flatRootPages)
         L.push(`  - \`${o.section}/\` (${fmt(o.paths.length)}): ${o.paths.map((p) => `\`${p}\``).join(', ')}`);
     L.push('', '## Tag vocabulary', '');
     if (!r.tags.available)

package/dist/surface.d.ts

@@ -0,0 +1,146 @@
+/**
+ * src/surface.ts — human-interface & content-hygiene detectors (V6.1).
+ *
+ * maintain.ts owns per-page G5/G6 freshness; this module owns the WIKI-WIDE
+ * structural health of the human surface (HANDOFF issues #1-#6): navigation
+ * hygiene, map-vs-live coverage, redirect-stub reachability, broken / stacked /
+ * index-less links, orphans, twin divergence, zh-first language, unfinished
+ * skeletons and claim ledgers that beg re-verification.
+ *
+ * Pure functions over rows + live inventory + an injected readBody; the light
+ * tier costs nothing beyond the map baseline, the deep tier reads every body
+ * once (caller pools the reads).
+ */
+import type { MaintainRow } from './maintain.js';
+import type { Locale } from './wiki/pages.read.js';
+import type { NavSnapshot } from './wiki/nav.js';
+export declare const SURFACE_SCHEMA: "historian.surface.v1";
+/** Minimal shape of a live `pages.list` row the surface diff needs. */
+export interface LiveRow {
+    readonly path: string;
+    readonly locale: Locale;
+    readonly isPublished?: boolean;
+    readonly isPrivate?: boolean;
+}
+export interface SurfaceInput {
+    readonly rows: readonly MaintainRow[];
+    readonly generatedAt: string;
+    readonly baseUrl: string;
+    readonly liveInventory?: readonly LiveRow[];
+    /**
+     * Live primary nav. Issue #1's disease is sidebar exposure, so the check
+     * must read the real tree — omit/null reports `available: false` rather
+     * than falsely claiming a clean nav.
+     */
+    readonly nav?: NavSnapshot | null;
+    readonly deep?: boolean;
+    readonly readBody?: (path: string, locale: Locale) => Promise<string | null>;
+}
+export interface SurfaceCoverage {
+    readonly liveRows: number;
+    readonly mapRows: number;
+    readonly missingFromMap: {
+        readonly path: string;
+        readonly locale: Locale;
+    }[];
+    readonly removedFromLive: number;
+}
+export interface SurfaceNav {
+    readonly available: boolean;
+    readonly mode: string | null;
+    /** DYNAMIC/MIXED re-mirror the filesystem page tree into the sidebar — the exact Issue #1 relapse. */
+    readonly filesystemExposed: boolean;
+    /** Underscore-prefixed (machine-namespace) links explicitly mounted in the curated tree. */
+    readonly machineLinks: {
+        readonly locale: string;
+        readonly label: string;
+        readonly target: string;
+    }[];
+    /** Informational: underscore segments in the PAGE tree — by design (_meta/_evidence/_sandbox/_data). */
+    readonly machinePaths: readonly string[];
+    readonly sectionLandingMissing: {
+        readonly dir: string;
+        readonly pagePaths: number;
+    }[];
+}
+export interface SurfaceUnfinished {
+    readonly path: string;
+    readonly locale: Locale;
+    readonly title: string;
+    readonly todo: number;
+    readonly emptySections: readonly string[];
+    readonly introEmpty: boolean;
+    readonly active: boolean;
+    readonly h1Mismatch: boolean;
+}
+export interface SurfaceStub {
+    readonly path: string;
+    readonly locale: Locale;
+    readonly target: string | null;
+    readonly clickable: boolean;
+    readonly targetLive: boolean;
+}
+export interface SurfaceLinks {
+    readonly broken: {
+        readonly from: string;
+        readonly locale: Locale;
+        readonly target: string;
+    }[];
+    readonly toStubs: {
+        readonly from: string;
+        readonly locale: Locale;
+        readonly target: string;
+    }[];
+    readonly sameTargetStacks: {
+        readonly from: string;
+        readonly locale: Locale;
+        readonly target: string;
+        readonly texts: number;
+    }[];
+    readonly orphanPages: readonly string[];
+    readonly indexMissing: readonly string[];
+}
+export interface SurfaceTwin {
+    readonly path: string;
+    readonly lenRatio: number;
+    readonly sectionCountRatio: number;
+    readonly relatedMismatch: boolean;
+    readonly divergent: boolean;
+}
+export interface SurfaceDeep {
+    readonly unfinished: SurfaceUnfinished[];
+    readonly stubs: SurfaceStub[];
+    readonly links: SurfaceLinks;
+    readonly roleDivergence: {
+        readonly path: string;
+        readonly stubIn: Locale;
+        readonly liveIn: Locale;
+    }[];
+    readonly twinParity: SurfaceTwin[];
+    readonly zhEnglishDominant: {
+        readonly path: string;
+        readonly cjkRatio: number;
+    }[];
+    readonly ledgerClaims: {
+        readonly path: string;
+        readonly locale: Locale;
+        readonly genre: string;
+        readonly ports: number;
+        readonly paths: number;
+        readonly commands: number;
+    }[];
+}
+export interface SurfaceReport {
+    readonly schema: typeof SURFACE_SCHEMA;
+    readonly generatedAt: string;
+    readonly deep: boolean;
+    readonly coverage: SurfaceCoverage | null;
+    readonly nav: SurfaceNav;
+    readonly tagsEmpty: {
+        readonly path: string;
+        readonly locale: Locale;
+    }[];
+    readonly deepReport: SurfaceDeep | null;
+}
+export declare function buildSurfaceReport(input: SurfaceInput): Promise<SurfaceReport>;
+export declare function renderSurfaceMarkdown(r: SurfaceReport): string;